Skip to content

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, AuthorizationContextProvider and ResourcePolicy are importable from rn_forge.auth, with the fields and methods of Contracts, and type-check under strict pyright.
  • ProviderKind is closed to oidc, oauth2, password and development.
  • The core imports no third-party library, and uv run lint-imports passes.

S13.3.2 — Principal, Requirement and the scope limit

State: Closed (2026-10-27)

Acceptance:

  • Principal carries the fields of the design's Principal table, each with its one provenance; mechanism is one of session, bearer and basic.
  • Requirement has any_permission and all_permissions and 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 Requirement from 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 AuthorizationContextProvider and 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 active flag 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.oidc holds the access-token, ID-token and logout-token profiles of Token validation. The access-token profile is JwtVerifier over PyJWT's jwt.decode and PyJWKClient, in RFC 9068 and RFC 7519 modes; the ID-token profile runs Authlib's CodeIDToken; the logout-token profile runs PyJWT and records jti in the replay store.
  • Each deployment restriction in the table has a test that fails without it: the algorithm allow-list, the iss and aud checks, nonce and events rejection, the typ rule of each mode, auth_time within max_age, the logout token's iat window and replayed jti.
  • 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_uri except to a local host.
  • PyJWKClient's cooldown_duration bounds refetches: a test with 200 unknown kid values sees one fetch, and a rotated key is accepted after the cooldown.
  • The oidc extra requires PyJWT 2.15 or later and Authlib, and the development group gains types-authlib.

S13.3.5 — return_to and the session body

State: Closed (2026-10-27)

Acceptance:

  • return_to validation 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/session body in camelCase, with subject the internal account ID and the optional fields omitted when absent.
  • The callback error codes are a closed type: access_denied, account_not_provisioned and login_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. ReplayStore and InMemoryReplayStore landed with S13.3.4, which the logout-token profile needed.
  • The redis adapter implements all three over redis-py: transactions are consumed with GETDEL, replay records and revoked sid values are set with SET NX and an expiry.
  • The redis adapter also implements AuthorizationVersions (S13.3.3) with INCR, 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-web gains the csrf-failed problem type, returned with 403, and a session-only 401 that carries no WWW-Authenticate, as HTTP surface describes.
  • The conformance table gains cases for both, which F13.5 and F13.6 pass.
  • The API conventions record the 401 deviation from RFC 9110 §15.5.2.

S13.3.8 — Offline fake IdP

State: Closed (2026-10-27)

Acceptance:

  • rn_forge.auth.testing provides 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 iss in the response, a discovery document naming another issuer, a UserInfo sub that differs, a wrong nonce, aud, azp or at_hash, an expired token, alg: none and an unknown kid.
  • 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 Principal and Requirement changes as breaking.
  • Both strict MkDocs builds pass.

Acceptance

  • The contracts, Principal, Requirement and 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-web carries the csrf-failed problem and the session 401 (S13.3.7).
  • The fake OIDC IdP covers every OIDC failure switch (S13.3.8).
  • The core is documented (S13.3.9).
uv run --package rn-forge-auth pytest packages/rn-forge-auth
uv run lint-imports
uv run pyright
sh docs/_update_board.sh --check