Scoped Per-User API Keys for Programmatic Access

[devsimze]

Problem Statement

The only way to call the API as a user is with a session Bearer JWT — obtained by signing a wallet challenge (src/controllers/auth-controller.ts), short-lived, refresh-rotated, and tied to a Session row. That is right for an interactive app and wrong for everything else: a user who wants to run a script, a bot, or a backtest harness against their own account has to either automate wallet signing or babysit refresh tokens. There is an AdminApiKey model with role + scopes[] for operators, but nothing equivalent for end users. This issue adds scoped per-user API keys: long-lived, hashed-at-rest credentials with a permission scope narrower than a full session, per-key rate limits, IP allowlisting, and revocation — so programmatic access is first-class and safely bounded.

Current State

• src/middleware/authenticate.ts — canonical auth: Bearer → JWT verify (JwtAdapter) → live Session row → not expired → user active. Sets req.user.
• src/controllers/auth-controller.ts — challenge/verify/refresh/logout; refresh-token rotation (Add refresh token rotation for JWT sessions #214); closeUserSockets on logout.
• src/middleware/adminAuth.ts + AdminApiKey (name, role, scopes[], hash (bcrypt), tokenPrefix (sha256: lookup key), expiresAt, revokedAt, lastUsedAt) + AdminAuditLog — the exact pattern to mirror for users.
• src/middleware/rateLimiter.ts — HTTP rate limiting; src/middleware/subAccount.ts — sub-account permission checks.
• prisma/schema.prisma — User, Session, AdminApiKey.
• docs/API_REFERENCE.md, docs/api-versioning.md.

Proposed Solution

1. Model

model UserApiKey {
  id           String   @id @default(uuid())
  userId       String
  name         String
  scopes       String[] // e.g. "portfolio:read", "transactions:read", "deposit:write", "alerts:manage"
  hash         String   // bcrypt of the raw secret
  tokenPrefix  String   // "sha256:<hex>" deterministic lookup, narrows before bcrypt (same as AdminApiKey)
  ipAllowlist  String[] // optional CID--/IP list; empty = any
  rateLimitPerMin Int?  // optional per-key override
  lastUsedAt   DateTime?
  lastUsedIp   String?
  expiresAt    DateTime?
  revokedAt    DateTime?
  createdAt    DateTime @default(now())
  @@index([userId])
  @@index([tokenPrefix])
}

• Raw key format: nwk_<keyId>_<secret> (prefix makes it greppable in leaked-secret scanners and lets us do the tokenPrefix lookup). Shown once on creation.

2. Auth middleware

• Extend the auth layer: if the Authorization header is Bearer nwk_…, route to authenticateApiKey instead of the JWT path:
  • tokenPrefix lookup → bcrypt compare → not revoked/expired → user active → IP in ipAllowlist (if set) → set req.user plus req.authScopes and req.authKind = 'api_key'.
• A requireScope('deposit:write') middleware gates routes. Session JWTs implicitly have all user scopes (req.authScopes = ['*']); API keys have only their granted set. Existing routes get a scope annotation (a central map, so it's reviewable in one place).
• Money-movement scopes (deposit:write, withdraw:write) are opt-in per key and off by default; a key with no write scopes is read-only.

3. Guardrails

• withdraw:write on an API key additionally requires the key to have been created with an explicit allowWithdrawals: true confirmation and (config) may be disabled platform-wide — a leaked read key must never be able to drain an account, and even a write key is subject to approval workflows (Approval Workflows & Multi-Signature Governance for High-Value Transactions #314) and compliance freeze (AML Transaction Monitoring & Sanctions Screening Pipeline #321) exactly like a session.
• Per-key rate limit (default stricter than a session); 429 with the key id in the log.
• lastUsedAt/lastUsedIp updated async (not on the hot path) for anomaly review.

4. Management + docs

• POST/GET/DELETE /api/v1/keys — create (returns secret once), list (metadata only, never the secret), revoke. POST /api/v1/keys/:id/rotate.
• Every create/revoke/rotate emits a security.api_key_changed real-time + email event (ties into the email-channel + session-management issues) — the user always knows when a key appears.
• GET /api/v1/keys/:id/usage — recent request counts, last IP, scope-denied attempts.
• docs/API_KEYS.md — scope catalog, key format, rotation, the withdrawal opt-in; docs/API_REFERENCE.md auth section updated.

Edge Cases & Failure Modes

• Leaked key: revocation is immediate (checked every request, no caching beyond a short TTL that's documented); secret scanners can match the nwk_ prefix; usage endpoint shows unfamiliar IPs.
• Scope escalation attempt: a key calling a route outside its scopes gets 403 insufficient_scope with the required scope named; the attempt is logged and counted (feeds anomaly review).
• IP allowlist + legitimate IP change: documented; the user edits the allowlist (a session-auth action, not an API-key action — a key cannot widen its own allowlist).
• Key with withdraw:write + a AML Transaction Monitoring & Sanctions Screening Pipeline #321 freeze: freeze wins; the withdrawal is halted at the outbox exactly as a session withdrawal would be.
• Expired key: 401 key_expired (distinct from revoked/invalid) so tooling can tell the difference.
• Clock skew on expiresAt: evaluated server-side; small grace, documented.
• Sub-account: an API key belongs to one User; to act on a child it needs both the relevant scope and the parent's SubAccount permission for that child — the API-key path reuses src/middleware/subAccount.ts, no separate logic.
• Bulk key creation abuse: cap active keys per user (config); creating past the cap is 409.

Security & Privacy Considerations

• Secrets hashed with bcrypt at rest; tokenPrefix is a SHA-256 lookup accelerator, not the secret; the raw secret is returned exactly once and never logged.
• Read-only by default; write and especially withdrawal scopes are explicit opt-ins with a confirmation and a platform kill-switch.
• API-key requests are subject to every downstream control a session is (rate limits, sub-account perms, approval workflows, compliance freeze) — the key is an authentication method, not a bypass.
• Key lifecycle events notify the user out-of-band so an attacker-created key is visible.
• keys management endpoints require session auth (an API key cannot create or escalate another API key).

Out of Scope

• OAuth2 / third-party app authorization (this is the account owner's own key).
• Fine-grained resource-level scopes (per-position, per-goal) — v1 is action+resource-type scopes.
• HMAC request signing (Bearer secret over TLS for v1).
• Machine-to-machine key exchange / JWKS.

Suggested Implementation Plan

1. UserApiKey model + migration/rollback; raw key format + tokenPrefix derivation (mirror AdminApiKey).
2. authenticateApiKey middleware + requireScope + a central route→scope map; wire into the auth entry point alongside the JWT path.
3. Withdrawal opt-in + platform kill-switch + per-key rate limit; reuse subAccount.ts for delegated access.
4. POST/GET/DELETE /api/v1/keys + rotate + :id/usage; session-auth-only; active-key cap.
5. security.api_key_changed events (real-time + email); async lastUsedAt/IP updates.
6. docs/API_KEYS.md + docs/API_REFERENCE.md + docs/openapi.yaml; metrics (auth by kind, scope-denied count).

Acceptance Criteria

• UserApiKey with named scopes, bcrypt hash + tokenPrefix lookup, optional IP allowlist and per-key rate limit, expiry, and revocation — secret shown once
• Authorization: Bearer nwk_… authenticates via a dedicated path setting req.authScopes; requireScope(...) gates routes from a central route→scope map; sessions keep ['*']
• Keys are read-only by default; withdraw:write requires an explicit per-key opt-in and honors a platform kill-switch; API-key requests are still subject to rate limits, sub-account perms, Approval Workflows & Multi-Signature Governance for High-Value Transactions #314 approvals, and AML Transaction Monitoring & Sanctions Screening Pipeline #321 freeze
• Revocation takes effect within a documented short TTL; expired vs. revoked vs. invalid return distinct errors; scope violations return 403 insufficient_scope and are logged
• keys management endpoints require session auth (a key cannot mint or escalate a key); active-key count is capped per user
• Every key create/revoke/rotate notifies the user via real-time + email; :id/usage shows recent IPs and scope-denied attempts
• docs/API_KEYS.md + docs/API_REFERENCE.md + docs/openapi.yaml updated; unit + integration tests green

[dot-enny]

@dot-enny has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi there, I think i can handle this. Thank you. 😊

ℹ️ Repo Maintainers: To accept this application, review their application or assign @dot-enny to this issue.

[Bosskandy1]

@Bosskandy1 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi, I’d like to work on this issue. I can implement the scoped user API key system with secure authentication, scope-based access control, key management, and the required tests while following the existing security patterns.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Bosskandy1 to this issue.

[od-hunter]

@od-hunter has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Can I be assigned this issue please?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @od-hunter to this issue.

[drips-wave]

Congratulations, @od-hunter! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @od-hunter: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@od-hunter's PR #378 was approved and merged by @Abidoyesimze.

🏆 @od-hunter: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,228 total points). Track your full progress on GrantFox.

👏 Great work, @od-hunter! Keep contributing to Neurowealth.

[drips-wave]

This issue has been completed by @od-hunter as part of the Stellar Wave Program's 8th Wave 🥳

😎 @od-hunter: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.