Enforce API-key authentication on all state-changing endpoints

[mikewheeleer]

Implement enforced API-key authentication on all state-changing endpoints

Description

The middleware in src/index.ts recognises an X-API-Key header and tags req.apiKey, but the comment is explicit: it "without yet rejecting unkeyed requests (so the API stays open until the admin opts in)." Every write endpoint — POST /api/v1/usage, POST /api/v1/settle, POST /api/v1/services, POST /api/v1/api-keys, admin pause — is fully open. This issue adds opt-in enforcement so the backend can run authenticated.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add an env flag REQUIRE_API_KEY=true that turns the recognition middleware into an enforcing one for non-GET methods.
• Return a structured 401 unauthorized (with requestId) when enforcement is on and no valid key is supplied; keep GET/HEAD/OPTIONS open for dashboards.
• Hash stored API keys (the store currently holds the raw key as the map key in apiKeyStore) so a store dump does not leak live credentials; compare with a constant-time function.
• Keep the /api/v1/api-keys list endpoint returning only the 8-char prefix, never the secret.
• Treat POST /api/v1/admin/* as privileged: require a separate ADMIN_API_KEY rather than any tenant key.

Suggested execution

• Fork the repo and create a branch
• git checkout -b feature/auth-03-enforce-api-keys
• Implement changes
  • Write code in: the auth middleware and admin handlers in src/index.ts; extract an src/auth/apiKeys.ts helper for hashing/compare.
  • Write comprehensive tests in: new src/auth/apiKeys.test.ts — enforced vs open mode, admin-only routes, prefix-only listing.
  • Add documentation: update README.md with an "Authentication" section.
  • Add TSDoc on the enforcement middleware and hashing helper.
  • Validate security assumptions: constant-time compare, no raw key persisted, admin separation.
• Test and commit

Test and commit

• Run npm run build, npm test, and npm run lint.
• Cover edge cases: missing header, unknown key, valid tenant key on admin route, enforcement disabled.
• Include the full npm test output and a threat-model note in the PR description.

Example commit message

feat: enforce hashed API-key auth on write and admin endpoints

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[BojayL]

/claim

[BojayL]

/attempt #87

[pq198363-ops]

/claim

[pq198363-ops]

/attempt #234