102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
<!-- 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 -->
|