feat(agent-bff): BFF API key resolver wiring

[nbouliol]

Context

Mode 2 (developer path) for the BFF: a request presents an fbff_<keyId>_<secret> key in the X-Forest-Bff-Key header. The BFF resolves it server-to-server against the SaaS (POST /liana/v1/bff-api-keys/resolve, already shipped in forestadmin-server), caches the result briefly, and mints a fresh 5m agent JWT per request from the resolved identity. The minted JWT is never cached.

Slice 2 of the auth foundation. The actual agent call is Slice 3 — here the JWT is asserted as correctly minted and attached (ctx.state.agentToken / ctx.state.apiKeyIdentity), with the agent client out of scope.

fixes PRD-663

What's in it

New packages/agent-bff/src/api-key/:

• api-key.ts — parse fbff_<16hex>_<64hex>, hashApiKey (cache key = sha256 of keyId+secret), fingerprintApiKey (logs)
• api-key-client.ts / api-key-resolve-error.ts — S2S resolve call, typed errors
• agent-token.ts — mint 5m JWT (camelCase + snake_case aliases, tags→Record, null→'')
• resolve-cache.ts — per-instance TTL cache (positive 60s / negative 10s), now() injected, bounded (10k)
• api-key-error.ts — nested { error: { type, status, message } } contract
• api-key-authenticator.ts — orchestrates parse → cache → resolve → mint
• api-key-middleware.ts — reads the header, attaches to ctx.state, Retry-After on 503

Wired in cli-core.ts (mounted independently of OAuth) and exported from index.ts.

Error mapping (SaaS → BFF)

• 401 → invalid_api_key (negative-cached ≤10s)
• 403 → forest_identity_not_allowed (negative-cached ≤10s)
• 400 → invalid_request (not cached)
• 429 / unreachable / 5xx → 503 key_resolution_unavailable + Retry-After (not cached; SaaS Retry-After propagated on 429)
• malformed key shape → 401 invalid_api_key locally, no SaaS call

Notes / follow-ups

• The resolved identity has no role; the minted JWT omits it. To be revisited in Slice 3 when the agent call is wired.
• Mode 1/Mode 2 precedence, CORS, per-key allowedOrigins enforcement and cross-cutting contract tests are owned by T6 (PRD-666). This PR only exposes allowedOrigins on the attached identity for T6 to consume.

Tests

49 focused tests (test/api-key/): parse, cache TTLs + bound, mint claims/expiry, resolve error mapping, authenticator cache behavior, middleware attach/error/passthrough, no raw secret in logs. Lint + tsc clean.

Includes a second commit addressing local review findings (downstream-error masking, Retry-After NaN, unguarded success JSON, size() staleness, test fetch restore).

🤖 Generated with Claude Code

Note

Add Mode 2 BFF API key authentication middleware to agent-bff

• Adds a full API key authentication pipeline: key parsing/hashing, a Forest server resolver client, a TTL-aware resolve cache (60s positive / 10s negative), an authenticator, and a Koa middleware gated on the X-Forest-Bff-Key header.
• On successful authentication, mints a short-lived (5min) HS256 JWT with user identity claims and attaches it to Koa state alongside the resolved identity; sets Cache-Control: no-store.
• On failure, returns structured ApiKeyError responses (400/401/403/503) with optional Retry-After; unexpected errors return a generic 500.
• Middleware is conditionally registered in cli-core.ts when forestServerUrl, forestEnvSecret, and forestAuthSecret are all present in config; logs a warning and skips otherwise.
• Risk: Requests authenticated via API key bypass existing OAuth middleware; cache-full behavior silently drops new entries rather than evicting old ones.

Changes since #1730 opened

• Enforced strict validation in ApiKeyClient.isResolvedIdentity and added ApiKeyClient.isIdentityUser method to require complete identity structure [86caf50]
• Implemented LRU eviction in createResolveCache store utility to remove oldest entry when cache reaches capacity [86caf50]
• Restricted ApiKeyClient.parseRetryAfter to only accept positive integer values for Retry-After headers [86caf50]
• Added agentUrl requirement to resolveApiKeyConfig configuration validation [86caf50]
• Refactored createApiKeyAuthenticator.authenticate handler to mint AuthenticatedApiKey once before caching [86caf50]
• Removed agentUrl requirement from resolveApiKeyConfig function in agent-bff package [8c99477]

^{Macroscope summarized bb63ce1.}

[linear-code]

PRD-663

[qltysh]

7 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 6): mapResolveError	2
qlty	Structure	Function with high complexity (count = 15): createApiKeyAuthenticator	2
qlty	Structure	Function with many parameters (count = 4): constructor	2
qlty	Structure	Complex binary expression	1

[macroscopeapp]

🟡 Medium src/cli-core.ts:128

When API-key-only configuration is provided (e.g. FOREST_APP_URL or BFF_TOKEN_ENCRYPTION_KEY missing), runCli still builds and registers the API-key middleware so requests authenticate successfully. But /health is driven by config.hasAllRequired, which requires all OAuth fields, so it returns 503 degraded. Readiness/liveness probes then keep the service out of rotation or restart it indefinitely despite valid authenticated traffic. Consider making the health check reflect the auth modes actually enabled, or document that OAuth config is required for a healthy status.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/agent-bff/src/cli-core.ts around line 128:

When API-key-only configuration is provided (e.g. `FOREST_APP_URL` or `BFF_TOKEN_ENCRYPTION_KEY` missing), `runCli` still builds and registers the API-key middleware so requests authenticate successfully. But `/health` is driven by `config.hasAllRequired`, which requires all OAuth fields, so it returns `503 degraded`. Readiness/liveness probes then keep the service out of rotation or restart it indefinitely despite valid authenticated traffic. Consider making the health check reflect the auth modes actually enabled, or document that OAuth config is required for a healthy status.

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.04%.

Modified Files with Diff Coverage (10)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/cli-core.ts	100.0%
	packages/agent-bff/src/index.ts	100.0%
	packages/agent-bff/src/api-key/api-key-middleware.ts	100.0%
	packages/agent-bff/src/api-key/resolve-cache.ts	100.0%
	packages/agent-bff/src/api-key/api-key-authenticator.ts	100.0%
	packages/agent-bff/src/api-key/api-key-resolve-error.ts	100.0%
	packages/agent-bff/src/api-key/api-key.ts	100.0%
	packages/agent-bff/src/api-key/agent-token.ts	100.0%
	packages/agent-bff/src/api-key/api-key-error.ts	100.0%
	packages/agent-bff/src/api-key/api-key-client.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.