Skip to content

F22.8 — Auth policy and bounded caches

State Closed
Parent E22
Iteration Release 9
Closed Date 2026-11-16
Predecessors F22.3

Stories: 5 Closed

Story State Depends on
S22.8.1 — Bound authorization-context retention Closed (2026-11-16) S22.8.4
S22.8.2 — Own shared identity and record policy Closed (2026-11-15) —
S22.8.3 — Separate OIDC responsibilities conservatively Closed (2026-11-16) —
S22.8.4 — Decide the retention bound Closed (2026-11-16) S22.3.2
S22.8.5 — Share login admission between the adapters Closed (2026-11-16) S22.8.2

Give shared identity and persisted-record policy one owner and bound cache retention without weakening invalidation.

Context

context_cache.py:128-146 never removes entries for accounts no longer requested: TTL only limits reuse. In-memory stores rebuild dictionaries during common operations. OIDC verification/provider/logout code shares a 1,538-line module. The two framework adapters repeat bearer account projection and record mapping.

S22.8.1 — Bound authorization-context retention

State: Closed (2026-11-16) · Depends on: S22.8.4

Implement the bound S22.8.4 chose. Keep version invalidation independent of entry eviction; do not reset versions in a way that can make stale contexts current.

Acceptance:

  • Settled by the owner in S22.8.4 (2026-11-16): option B. Entries live in an insertion-ordered dict; each insert pops then re-inserts its key and expires entries from the front whose TTL has passed. Retention is bounded by the accounts resolved within one TTL; no hard cap and no new public parameter. Version counters are never pruned (parked as the auth-version-counter-retention idea). S22.8.4's characterization test is replaced by an assertion of this bound.
  • Injected-clock churn over many distinct accounts has a documented finite retention bound.
  • Account/global invalidation, inactive-account rejection and a version bump racing provider resolution retain security behavior.
  • Lock hold time and peak memory are compared to baseline; single-flight is added only if measured and separately justified.

Outcome: a miss pops the account, drops expired entries from the front under the existing lock and appends the new one. At 16,000 accounts with a 60 s TTL the cache holds 60 entries (25 KB) instead of 16,000 (6.8 MB); version counters stay unpruned.

S22.8.2 — Own shared identity and record policy

State: Closed (2026-11-15)

Extract only pure account-to-principal projection and common SessionInfo/LoginTransaction mapping. Consider the repeated login rate-window arithmetic in the same ownership pass. Keep cookies, CSRF, backend atomic counters, JSON and network scheduling in adapters.

Acceptance:

  • Django and FastAPI share tested inactive/unlinked account, scope-limit, tenant and external-identity rules.
  • Old persisted session/transaction shapes decode identically; new encoding round-trips optional AMR/auth-time/token fields without exposing secrets.
  • Backend adapters retain expiry/atomicity behavior; no universal session backend abstraction is added.

Outcome: rn_forge.auth owns link_bearer_principal, session_principal and PrincipalLinkError (linking), the session and transaction record mappings with unchanged keys (records), and fixed-window arithmetic (rate_window). Django and FastAPI translate PrincipalLinkError into their own AuthenticationFailed, and keep RateLimit, counters, JSON and cookies. SessionInfo.id_token and LoginTransaction.state, nonce and code_verifier are left out of repr.

S22.8.3 — Separate OIDC responsibilities conservatively

State: Closed (2026-11-16)

Group discovery/JWKS, token profiles, provider exchange and back-channel logout behind the supported rn_forge.auth.oidc surface. Prefer focused internal modules and explicit composition over a generic token-verifier hierarchy.

Acceptance:

  • The oidc extra stays optional; base imports do not load its dependencies.
  • Issuer/audience/algorithm/type/nonce/replay/expiry and key-rotation cases remain covered for each token profile; test helpers stay off the production import path.
  • JWKS refresh request counts and latency are measured; cache changes preserve rotation and unknown-key denial.
  • The key-set lifespan test advances a clock the verifier accepts, rather than patching PyJWT's internal jwk_set_cache module.
  • Large in-memory store sweeps are optimized only after measured growth shows a benefit.

Settled contract: oidc.py stays one module (every public name is in __all__, the private helpers depend on the public TokenVerificationError, and the oidc extra is one dependency set); key-set lifespan runs on a private injectable clock (_KeySetClient, built by _new_jwks_client) while the cooldown stays on time.monotonic; no public clock argument; ID tokens keep no typ check; in-memory stores keep a lower bound on the earliest expiry and sweep only once it has passed.

Outcome: filling an in-memory store with 16,000 records fell from 4.6–6.1 s to 0.04–0.16 s; a 15-case profile matrix covers rotation, unknown and missing kid and alg=none per token profile.

S22.8.4 — Decide the retention bound

State: Closed (2026-11-16) · Depends on: S22.3.2

Measure account churn with an injected clock, then choose a small bounded retention or expiry mechanism that keeps version invalidation independent of eviction.

Acceptance:

  • The decision records the bound, the mechanism and the rejected options.
  • A baseline records churn, lock hold time and peak memory before the change.

Decision (owner, 2026-11-16): option B, front expiry in an insertion-ordered dict, bounded by the accounts resolved within one TTL. Rejected: A (full sweep, O(n) under the lock), C (LRU cap that keeps expired entries) and D (a new public max_entries and two orderings to keep in sync). Version counters stay unbounded; parked as an idea.

Outcome: baseline at 16,000 distinct accounts with a 60 s TTL: 16,000 entries retained (60 live), 6.8 MB traced; the B prototype kept 60 entries and 31 KB.

S22.8.5 — Share login admission between the adapters

State: Closed (2026-11-16) · Depends on: S22.8.2

Both adapters' _complete repeat the same policy after a verified login: resolve the account, refuse a rejected or inactive one with the same codes and audit events, build SessionInfo from the identity, and fall back to the default return_to. Both also parse the transaction cookie from the raw header to reject duplicates, and read string fields from a JSON login body. Move that policy into rn_forge.auth, which already owns the flow, accounts, contexts and SessionInfo; rn_forge.web sits below rn_forge.auth and knows none of them. Keep starting the session, CSRF token rotation, response building, form parsing and header access in the adapters.

Acceptance:

  • One rn_forge.auth function turns a CompletedLogin into the account ID, the SessionInfo and the validated return_to, raising LoginFailed with account_not_provisioned or access_denied and the existing audit events; both adapters call it, and neither builds SessionInfo itself.
  • TRANSACTION_COOKIE, the duplicate-cookie check and the JSON credential fields are defined once in rn_forge.auth; each adapter only supplies its raw cookie headers or body bytes.
  • Login, callback and local-password responses, audit events and log messages are unchanged in both adapters; the existing route suites pass unedited.

Outcome: rn_forge.auth owns admit_login and AdmittedLogin (admission), TRANSACTION_COOKIE and transaction_cookie_value (flow) and json_string_fields (local). Both adapters call them, keep their own "Login with … refused" warning on their route logger, and no longer export TRANSACTION_COOKIE.

Acceptance

  • S22.8.1: Injected-clock churn over many distinct accounts has a documented finite retention bound.
  • S22.8.2: Django and FastAPI share tested inactive/unlinked account, scope-limit, tenant and external-identity rules.
  • S22.8.3: The oidc extra stays optional; base imports do not load its dependencies.
  • S22.8.4: The decision records the retention bound, mechanism and baseline.