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-retentionidea). 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_cachemodule. - 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.authfunction turns aCompletedLogininto the account ID, theSessionInfoand the validatedreturn_to, raisingLoginFailedwithaccount_not_provisionedoraccess_deniedand the existing audit events; both adapters call it, and neither buildsSessionInfoitself. TRANSACTION_COOKIE, the duplicate-cookie check and the JSON credential fields are defined once inrn_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.