F13.3 — Core contracts and token profiles
| State | Closed |
| Parent | E13 |
| Iteration | Release 7 |
| Start Date | 2026-10-27 |
| Closed Date | 2026-10-27 |
| Predecessors | F13.2 |
| Source | Owner decision, 2026-10-26 |
Stories: 9 Closed
| Story | State | Depends on |
|---|---|---|
| S13.3.1 — Identity and authorization contracts | Closed (2026-10-27) | — |
| S13.3.2 — Principal, Requirement and the scope limit | Closed (2026-10-27) | — |
| S13.3.3 — Authorization context cache | Closed (2026-10-27) | — |
| S13.3.4 — Token validation profiles | Closed (2026-10-27) | — |
S13.3.5 — return_to and the session body |
Closed (2026-10-27) | — |
| S13.3.6 — Session, transaction and replay stores | Closed (2026-10-27) | — |
| S13.3.7 — Wire contract additions | Closed (2026-10-27) | — |
| S13.3.8 — Offline fake IdP | Closed (2026-10-27) | — |
| S13.3.9 — Document the core | Closed (2026-10-27) | — |
The framework-neutral core of rn-forge-auth: the contracts every login method,
binding and application builds on, the three token validation profiles, the
stores, and the offline fakes every later feature tests against.
Context
The design's Contracts,
Authorization model,
Token validation,
Revocation and Testing sections are
the specification, and ADR-0013 sets the account
resolution and per-request authorization these contracts carry. The contracts
live in the core, the token profiles in the oidc adapter and the Redis stores
in a redis adapter, each behind its extra
(ADR-0011); the auth guides document the result.
S13.3.1 — Identity and authorization contracts
State: Closed (2026-10-27)
Acceptance:
ExternalIdentity,IdentityProvider,LoginStart,LoginTransaction,AccountResolver,AccountRejected,AuthorizationContext,AuthorizationContextProviderandResourcePolicyare importable fromrn_forge.auth, with the fields and methods of Contracts, and type-check under strict pyright.ProviderKindis closed tooidc,oauth2,passwordanddevelopment.- The core imports no third-party library, and
uv run lint-importspasses.
S13.3.2 — Principal, Requirement and the scope limit
State: Closed (2026-10-27)
Acceptance:
Principalcarries the fields of the design'sPrincipaltable, each with its one provenance;mechanismis one ofsession,bearerandbasic.Requirementhasany_permissionandall_permissionsand no role clauses; its scope clauses only narrow access. A test shows an administrator account's read-only token failing a write route's requirement.- A neutral helper builds a
Requirementfrom a base permission key and an action (orders+partial_update→orders.update). - A bearer principal's effective permissions are its account's permissions limited by the application's scope-to-permission map, and a scope the map does not name allows nothing. A session principal has no scopes and its account's permissions. Tests cover each case.
S13.3.3 — Authorization context cache
State: Closed (2026-10-27)
Acceptance:
- A cache wraps any
AuthorizationContextProviderand keys entries by account and authorization version. An invalidation API bumps one account's version or the global version, and the next lookup recomputes. - A configurable TTL bounds every entry. A test shows a change made without the invalidation API applied after the TTL.
- Changing an account's
activeflag or session version through the API bumps its authorization version, so no cached context outlives it.
S13.3.4 — Token validation profiles
State: Closed (2026-10-27)
Acceptance:
rn_forge.auth.oidcholds the access-token, ID-token and logout-token profiles of Token validation. The access-token profile isJwtVerifierover PyJWT'sjwt.decodeandPyJWKClient, in RFC 9068 and RFC 7519 modes; the ID-token profile runs Authlib'sCodeIDToken; the logout-token profile runs PyJWT and recordsjtiin the replay store.- Each deployment restriction in the table has a test that fails without it: the
algorithm allow-list, the
issandaudchecks,nonceandeventsrejection, thetyprule of each mode,auth_timewithinmax_age, the logout token'siatwindow and replayedjti. - A cross-profile test signs one token of each kind with the same key and shows each is accepted only by its own profile.
- Configuration refuses an API audience equal to the OIDC login client ID unless
the provider is in RFC 9068 mode, and refuses a non-HTTPS
jwks_uriexcept to a local host. PyJWKClient'scooldown_durationbounds refetches: a test with 200 unknownkidvalues sees one fetch, and a rotated key is accepted after the cooldown.- The
oidcextra requires PyJWT 2.15 or later and Authlib, and the development group gainstypes-authlib.
S13.3.5 — return_to and the session body
State: Closed (2026-10-27)
Acceptance:
return_tovalidation accepts only a relative path under a configured prefix. Tests reject absolute and scheme-relative URLs, backslashes, encoded slashes, control characters and paths outside the prefixes.- The session-body schema serializes the
/auth/sessionbody in camelCase, withsubjectthe internal account ID and the optional fields omitted when absent. - The callback error codes are a closed type:
access_denied,account_not_provisionedandlogin_failed.
S13.3.6 — Session, transaction and replay stores
State: Closed (2026-10-27)
Acceptance:
SessionStore, the transaction store and the replay store (which also holds revoked(issuer, sid)pairs) are protocols in the core, with in-memory implementations for tests that say they are not safe across processes.ReplayStoreandInMemoryReplayStorelanded with S13.3.4, which the logout-token profile needed.- The
redisadapter implements all three over redis-py: transactions are consumed withGETDEL, replay records and revokedsidvalues are set withSET NXand an expiry. - The
redisadapter also implementsAuthorizationVersions(S13.3.3) withINCR, so a version bump reaches every process. - A test runs 50 concurrent consumes of one transaction and sees exactly one succeed, against both the in-memory and the Redis store. A CI job with a Redis service runs the Redis tests.
S13.3.7 — Wire contract additions
State: Closed (2026-10-27)
Acceptance:
rn-forge-webgains thecsrf-failedproblem type, returned with403, and a session-only401that carries noWWW-Authenticate, as HTTP surface describes.- The conformance table gains cases for both, which F13.5 and F13.6 pass.
- The API conventions record the
401deviation from RFC 9110 §15.5.2.
S13.3.8 — Offline fake IdP
State: Closed (2026-10-27)
Acceptance:
rn_forge.auth.testingprovides an in-process fake OIDC IdP: discovery, JWKS with key rotation, authorization, token and UserInfo endpoints, and logout tokens for back-channel logout. It needs no network.- It has a switch for each failure the OIDC rows of
Security controls cover: wrong or missing
issin the response, a discovery document naming another issuer, a UserInfosubthat differs, a wrongnonce,aud,azporat_hash, an expired token,alg: noneand an unknownkid. - Each switch is exercised by at least one test in this feature or F13.4.
S13.3.9 — Document the core
State: Closed (2026-10-27)
Acceptance:
rn-forge-auth's guides cover the contracts, the token profiles, the stores and the fakes, and its API reference builds.- The changelog records the
PrincipalandRequirementchanges as breaking. - Both strict MkDocs builds pass.
Acceptance
- The contracts,
Principal,Requirementand the scope limit exist in the core and type-check under strict pyright (S13.3.1, S13.3.2). - The context cache invalidates by version and TTL (S13.3.3).
- The three token profiles run on PyJWT and Authlib and reject each other's tokens (S13.3.4).
return_to, the session body and the error codes are validated (S13.3.5).- The stores consume and record atomically, in memory and on Redis (S13.3.6).
rn-forge-webcarries thecsrf-failedproblem and the session401(S13.3.7).- The fake OIDC IdP covers every OIDC failure switch (S13.3.8).
- The core is documented (S13.3.9).