feat(apikey): scoped, rotatable API keys (Tier-A #3)

[devin-ai-integration]

Summary

Adds service-to-service API-key authentication that composes with the existing JWT + RBAC stack. The bearer can be either a JWT (unchanged behaviour) or a goforge-format API key gf_<env>_<id>_<secret>; routes downstream of the auth group are oblivious to which one was presented.

Why

Tier-A #3 of the Tier A + Tier B framework expansion. Almost every SaaS / B2B integration needs scoped, rotatable, prefixed-id API keys (Stripe-style). Hand-rolling them per project wastes a day every time and is easy to get wrong (timing leaks, missing rotation, denormalised vs role-derived scopes).

How

Token format

gf_<env>_<id>_<secret>
 |   |     |    |
 |   |     |    +-- 64 hex chars (256-bit secret entropy)
 |   |     +------- 12 hex chars (48-bit unique id, indexed)
 |   +------------- env tag ("live" / "staging" / "dev" — visible)
 +----------------- framework tag ("gf" — never changes)

The visible env tag exists so a leaked key is immediately identifiable (it's why GitHub keys say ghp_… and Stripe says sk_live_…).

Storage / hashing

Only sha256(plaintext) is stored. Plaintext is returned by POST /api/v1/api-keys exactly once and never persisted.

SHA-256 is the right choice here — not Argon2id (used elsewhere for password hashing). The secret already carries 256 bits of cryptographic entropy; the cost of a memory-hard hash buys nothing without a low-entropy input. Constant-time hex compare prevents timing leaks against the prefix lookup.

Layers

• pkg/apikey/ — Generate / Parse / VerifyHash / LooksLikeAPIKey (zero infra deps)
• internal/domain/apikey/ — Key entity, Repo interface, ErrNotFound
• internal/adapter/repository/postgres/ — pgxpool implementation
• internal/usecase/apikey.go — Create / List / Revoke / Authenticate
• internal/adapter/http/middleware/apikey.go — APIKeyOrJWTAuth
• internal/adapter/http/handler/apikey.go — /api/v1/api-keys CRUD
• migrations/0008_api_keys.{up,down}.sql

Routes (behind the existing authenticated group)

• GET /api/v1/api-keys — list caller's own keys
• POST /api/v1/api-keys — mint key, plaintext returned exactly once
• DELETE /api/v1/api-keys/:id — revoke

RBAC interaction (the interesting bit)

RequirePermission("x.y", ...) short-circuits when the request arrived with a goforge API key: it consults the key's scopes, not the owning user's role surface. So a user with role admin can mint a key with scope ["reports.read"] for a CI job and that key cannot perform admin actions. The wildcard "*" is honoured for break-glass keys; the deployment is responsible for gating who may issue them.

Test plan

• make lint clean (golangci-lint run ./...)
• make test clean (go test -race ./...)
• Migrations applied + rolled back successfully
• Tests cover:
  • pkg/apikey: format, round-trip, tampered-secret rejection
  • internal/usecase: happy path, tampered, revoked, expired, malformed-bearer-is-401, NotFound mapping, scope sanitisation
  • internal/adapter/http/middleware: scope-grants-without-RBAC-lookup, narrow-scope-denies-even-if-role-would-grant, wildcard, JWT fallback path leaves API-key auth untouched, 401 on bad bearer

Risk

• Low — additive feature. The new middleware short-circuit only activates when the composition root passes APIKeyAuth in AccessControl; existing apps wired without it keep behaving exactly as before.
• The new middleware sits before Auth in the chain. Re-using c.Locals(CtxKeyUserID) keeps every downstream handler unaware of the auth mechanism.
• Rollback: revert PR + run migrations/0008_api_keys.down.sql. No public API changes outside the new package.

Checklist

• Doc comments updated for any public API change (full doc comments on every exported symbol; docs/api-keys.md covers token format, RBAC interaction, schema)
• OpenAPI 3.1 doc auto-registers the three new operations under the api-keys tag
• No secrets / debug logs / fmt.Println left behind

Link to Devin session: https://app.devin.ai/sessions/8fdfc20358514c97a766adca630a2527
Requested by: @dedeez14

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 10 additional findings in Devin Review.

[devin-ai-integration]

🔴 API-key-authenticated requests can mint new keys with arbitrary scopes, enabling privilege escalation

The /api-keys self-service routes (internal/infrastructure/server/router.go:65-68) are registered under the authed group with no RequirePermission middleware. This means an API key with narrow scopes (e.g., ["reports.read"]) can call POST /api/v1/api-keys and create a new key with ["*"] scopes, completely bypassing the scope restriction. The Create handler (internal/adapter/http/handler/apikey.go:64-69) passes req.Scopes directly from the request body to the use case with no check that the caller's own scopes are a superset of the requested scopes.

This defeats the core security invariant stated in the PR's own docs and middleware comments: "a service key with a narrow scope can never piggyback on the owning user's broader role assignments." While RequirePermission correctly short-circuits on API-key scopes for gated routes, the ungated key-management endpoints let a narrow key escalate to wildcard access in one API call.

Prompt for agents

The API key management endpoints (GET/POST/DELETE /api-keys) are registered under the authed group with no scope or permission check. This allows any API-key-authenticated request to create new keys with arbitrary scopes, escalating privileges.

Relevant files:
- internal/infrastructure/server/router.go:64-68 (route registration)
- internal/adapter/http/handler/apikey.go:51-78 (Create handler passes req.Scopes unchecked)
- internal/adapter/http/middleware/apikey.go:41-65 (sets scopes in context)
- internal/adapter/http/middleware/permission.go:71-78 (scope check only runs when RequirePermission is used)

Possible approaches:
1. Gate the api-keys routes behind a RequirePermission("apikeys.manage", ...) middleware so that API keys need an explicit scope to manage keys.
2. In the Create handler, when the request is API-key-authenticated (APIKeyScopesFromCtx returns non-nil), reject the request or validate that the requested scopes are a subset of the caller's scopes.
3. Reject API-key-authenticated requests from the key management endpoints entirely (only allow JWT).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Real and critical — confirmed and fixed in f0e4d1f.

Took approach 3 (forbid API-key auth on the whole /api-keys subtree) rather than a subset-scope check because the strict rule is the only one that's safe by default:

• Subset-check still lets a leaked key call DELETE /api-keys/:id and revoke the owner's other keys (denial of service).
• Subset-check still lets a leaked key rotate itself, escaping the owner's revoke.
• Strict rule is structural and auditable — "credential management is only from JWT sessions", no carve-outs.

Implementation:

// middleware/apikey.go - new guard
func RequireUserSession() fiber.Handler {
    return func(c *fiber.Ctx) error {
        if v := c.Locals(CtxKeyAPIKeyScopes); v != nil {
            return httpx.RespondError(c,
                errs.Forbidden(
                    "apikey.user_session_required",
                    "this endpoint cannot be called with an API key; sign in to manage credentials",
                ))
        }
        return c.Next()
    }
}

// server/router.go
if h.APIKeys != nil {
    keys := authed.Group("/api-keys", middleware.RequireUserSession())
    keys.Get("",     h.APIKeys.List)
    keys.Post("",    h.APIKeys.Create)
    keys.Delete("/:id", h.APIKeys.Revoke)
}

Regression test TestRequireUserSession_RejectsAPIKeyAuth covers both legs — API-key bearer gets 403, JWT bearer passes through.

Future admin tooling that legitimately needs programmatic key management can use a JWT-exchange flow instead of a scope — that keeps the attack surface of a leaked API key from ever including self-replication.