Initial Commit

openspec/archive/2026-05-26-api-auth-jwt/specs/api-auth-jwt/spec.md

@@ -0,0 +1,101 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-auth-jwt (api-auth-jwt)
+
+**Package**: `@suaveplan/api-auth-jwt`
+**Status**: PROPOSED
+
+## ADDED Requirements
+
+### Requirement: Session-resolver-only surface
+
+The package SHALL implement the `AuthAdapter` session-resolver contract from `@suaveplan/api-auth`. It MUST NOT register any HTTP routes — login/logout/refresh are provider responsibilities and live in separate adapters.
+
+#### Scenario: factory exposes resolveSession but no route contributions
+
+- **WHEN** `createJwtSessionResolver({ jwksUrl: "..." })` is called
+- **THEN** the returned adapter has `resolveSession` AND no `contributeRoutes` method AND `securitySchemeContribution()` returns a Bearer JWT entry
+
+**Verified by:** `src/factory/create-jwt-session-resolver.test.ts::"exposes resolveSession and no route contributions"`
+
+---
+
+### Requirement: JWT verification against JWKS or static key
+
+The package SHALL verify tokens using `@suaveplan/jws` against either a JWKS URL (with TTL + ETag caching) or a single static `JsonWebKey`. Algorithms MUST be restricted to the allowlist in `options.algorithms`; any token signed with a non-allowlisted algorithm MUST be rejected with `AUTH_JWT_ALGORITHM_NOT_ALLOWED`.
+
+#### Scenario: token signed with disallowed alg is rejected
+
+- **WHEN** a token signed with `HS256` is presented to a resolver whose `algorithms: ["RS256"]`
+- **THEN** `resolveSession()` returns `null` AND emits `AUTH_JWT_ALGORITHM_NOT_ALLOWED` on the failure counter
+
+#### Scenario: JWKS `kid` miss triggers refresh
+
+- **WHEN** a token's `kid` is not in the cached JWKS AND the cache is older than 0ms
+- **THEN** the resolver refetches the JWKS exactly once (in-flight dedup) AND retries verification
+
+**Verified by:** `src/factory/create-jwt-session-resolver.test.ts::"rejects tokens signed with non-allowlisted algorithms"` AND `src/jwks/jwks-cache.test.ts::"kid miss triggers a single in-flight JWKS refresh"`
+
+---
+
+### Requirement: Direct and worker-proxy surfaces both pass conformance
+
+The adapter SHALL pass `runAuthSessionConformance` from `@suaveplan/api-auth/testing` under BOTH `createJwtSessionResolver` (direct) AND `createJwtSessionResolverWorkerProxy` (proxy). Neither surface may skip an invariant.
+
+#### Scenario: direct surface conforms
+
+- **WHEN** `runAuthSessionConformance("jwt-direct", () => createJwtSessionResolver(...))` runs
+- **THEN** every invariant passes
+
+#### Scenario: worker-proxy surface conforms
+
+- **WHEN** `runAuthSessionConformance("jwt-worker-proxy", () => createJwtSessionResolverWorkerProxy(channel.port2, ...))` runs over a real `MessageChannel`
+- **THEN** every invariant passes
+
+**Verified by:** `src/factory/create-jwt-session-resolver.spec-conformance.test.ts::"jwt-direct conforms to AuthSession contract"` AND `src/proxy/create-jwt-session-resolver-worker-proxy.spec-conformance.test.ts::"jwt-worker-proxy conforms to AuthSession contract"`
+
+---
+
+### Requirement: Claim → Principal projection is overridable
+
+The package SHALL provide `defaultClaimToPrincipal` mapping `sub → id`, `scope`/`scopes` → `scopes[]`, `tenant_id`/`tid` → `tenantId`, remaining claims into `claims`. Callers MAY override via `options.claimToPrincipal`.
+
+#### Scenario: custom mapper supplies tenantId from a non-standard claim
+
+- **WHEN** `options.claimToPrincipal` reads `org_id` instead of `tenant_id`
+- **THEN** the produced `Principal.tenantId` reflects `org_id`
+
+**Verified by:** `src/claim-mapping/default-claim-to-principal.test.ts::"custom claimToPrincipal overrides default tenantId extraction"`
+
+---
+
+### Requirement: Token extraction honours header and cookie sources
+
+The package SHALL extract the token from the configured header (default `Authorization: Bearer <jwt>`) or cookie (when `cookieName` is set). If both are present, header wins.
+
+#### Scenario: cookie source produces a Principal
+
+- **WHEN** `cookieName: "session"` is configured AND a request carries `Cookie: session=<jwt>`
+- **THEN** the resolver returns the projected `Principal`
+
+#### Scenario: header takes precedence over cookie
+
+- **WHEN** a request carries BOTH a valid Bearer header AND a valid cookie
+- **THEN** the Principal reflects the header token's claims
+
+**Verified by:** `src/factory/create-jwt-session-resolver.test.ts::"extracts token from cookie when configured"` AND `src/factory/create-jwt-session-resolver.test.ts::"header source wins over cookie when both present"`
+
+---
+
+### Requirement: Options Zod-validated
+
+`JwtSessionResolverOptions` MUST be Zod-validated. Constructing the resolver with no `jwksUrl` AND no `staticKey` MUST throw `AUTH_JWT_INVALID_OPTIONS` synchronously.
+
+#### Scenario: missing key material throws
+
+- **WHEN** `createJwtSessionResolver({} as never)`
+- **THEN** a `SuaveplanError` with code `AUTH_JWT_INVALID_OPTIONS` is thrown synchronously
+
+**Verified by:** `src/options/jwt-session-resolver-options.test.ts::"throws when neither jwksUrl nor staticKey is supplied"`
+
+<!-- markdownlint-enable MD024 -->