F13.1 — Auth design
| State | Closed |
| Parent | E13 |
| Iteration | Release 7 |
| Start Date | 2026-10-26 |
| Closed Date | 2026-10-27 |
| Predecessors | ADR-0006 |
Stories: 5 Closed
| Story | State | Depends on |
|---|---|---|
| S13.1.1 — Settle the design | Closed (2026-10-26) | — |
| S13.1.2 — Record the decisions | Closed (2026-10-27) | — |
| S13.1.3 — Evaluate the libraries | Closed (2026-10-27) | — |
| S13.1.4 — Write the implementation features | Closed (2026-10-27) | S13.1.2, S13.1.3 |
| S13.1.5 — Federate SAML through a broker | Closed (2026-10-27) | — |
Discuss, settle and record the E13 design: an industry-standard auth pattern that any new rn-forge web application can adopt. This feature holds the work; the design itself lives on its own page so every later E13 feature can build on it.
Context
Owner decisions, 2026-10-26:
- The six proposed decisions are recorded as one
revised ADR and two new ADRs, plus a link from ADR-0011, not as one ADR per
decision and not as one umbrella ADR that defers to the design page.
docs/adr/_structure.mdrequires one question per ADR and keeps fields and names out of ADRs, and the design page is a working spec that later features edit. - The library evaluation is a desk review backed by throwaway spikes.
- The implementation features are F13.3 to F13.7, and all of them ship in Release 7.
S13.1.2 and S13.1.3 are independent. S13.1.4 needs both.
S13.1.1 — Settle the design
State: Closed (2026-10-26)
Acceptance: The owner has answered every open question or deferred it with a trigger, the design has no open questions left, and the design and the patterns page agree with the answers.
S13.1.2 — Record the decisions
State: Closed (2026-10-27)
Acceptance:
- ADR-0006 is rewritten in place to state the
current choice (proposed decisions 1 and 4): pykit verifies tokens an
authorization server issued and never issues its own; browsers authenticate
with a server-side session behind an HttpOnly cookie, never with a token;
and the locally issued JWT flows are removed
(F13.7). Its title says so, and its
Backgroundgains one dated sentence on the revision. - A new ADR, titled as its decision, records proposed decisions 2 and 3: every
caller, session or bearer, resolves to an internal account through
(issuer, subject); authorization is computed on the server per request from application data; a token's scopes only limit it; and the UI receives a copy of the permissions. - A new ADR records proposed decision 5: Django and FastAPI expose the same auth HTTP surface and the same security defaults, over whichever evaluated library fits each framework. It links ADR-0005 rather than restating it.
- Proposed decision 6 takes no new ADR. ADR-0011's
Influenceslinks the design's package placement. - The new ADRs take the next free numbers at the time of writing. Each follows
docs/adr/_structure.md: statusacceptedwith its date, the three leading sections within 300 words, and links to the design's sections instead of restating routes, fields or settings. - The decision log lists both new ADRs and ADR-0006's new title. The design's proposed decisions section links each decision to its ADR, and every page that cites ADR-0006 for what it says still agrees with it.
S13.1.3 — Evaluate the libraries
State: Closed (2026-10-27)
Acceptance:
- Each candidate in the library evaluation is assessed against its "Fits when" criteria, with its version, latest release date, Python 3.14 support, typing (strict pyright) and open security advisories.
- Each fit claim that only running code can settle is backed by a throwaway
spike: at least Authlib's Django and Starlette integrations (transaction
storage, the RFC 9207
isscheck, the UserInfosubcheck), django-allauth headless (the session body and HTTP surface, linking on(issuer, subject), bearer lookup alongside it), starsessions (a Redis store, per-session expiry, a hook on read), a Starlette CSRF library (a token bound to the server session, pre-session tokens) and the access-token validator (RFC 9068 mode, a bound on refetches for an unknownkid). Spikes run in a scratch worktree or directory and are never committed; the design records what each one showed. - Libraries names, for each concern, the library pykit binds, or the requirement no candidate met for each component pykit writes. The "Candidate" entries are gone.
- Each login flow on each framework has exactly one named owner, a library's integration or pykit's adapter over the library's core (see Contracts).
- The design states, for each of
JwtVerifier,JwksCache,discover_oidcandfetch_json, whether F13.2 moves it or deletes it, and which library replaces a deleted one. - Package responsibilities,
What this replaces,
Supported storage and the
package placement extras agree with the
result. Adding a library to a
pyproject.tomlis left to the feature that uses it.
S13.1.4 — Write the implementation features
State: Closed (2026-10-27) · Depends on: S13.1.2, S13.1.3
Acceptance:
- F13.3 to F13.7 each have
stories with observable acceptance, a
## Acceptanceblock, their predecessors, andIterationset to Release 7. Each story names the library S13.1.3 chose wherever it binds one. - Together they cover every row of Package responsibilities for pykit's packages, every row of What this replaces except ngkit's, every security control with the test that proves it, and the Testing section.
- Release 7's
OrderandBreaking changeslist the features and the removals they make. - No code change precedes its feature.
S13.1.5 — Federate SAML through a broker
State: Closed (2026-10-27)
Acceptance:
- Owner decision, 2026-10-27: pykit speaks no SAML. A SAML IdP federates through a broker that speaks OIDC to the app. An application with its own direct SAML integration, such as ew-loop, keeps it until its IdP connection moves to OIDC.
- ADR-0006 records it, and the design, the patterns page, F13.3 to F13.7 and Release 7 carry no SAML adapter, route, extra or library.
Acceptance
- Every open question is answered or deferred with a trigger, and the design and the patterns page agree (S13.1.1).
- ADR-0006 is revised, the two new ADRs are accepted and listed in the decision log, ADR-0011 links the package placement, and the design links each proposed decision to its ADR (S13.1.2).
- Every library candidate is assessed, spiked where code must settle it, and the result recorded in the design, including the fate of each commons token symbol (S13.1.3).
- F13.3 to F13.7 have stories and acceptance and are on Release 7 (S13.1.4).
- SAML IdPs federate through a broker, and pykit carries no SAML (S13.1.5).
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
absent -F 'Candidate' docs/specs/epics/E13-auth/design.md
for f in 3 4 5 6 7; do
grep -q '^### S13\.'"$f"'\.1 ' docs/specs/epics/E13-auth/F13.$f-*.md
grep -q 'release-7' docs/specs/epics/E13-auth/F13.$f-*.md
done
sh docs/_update_board.sh --check
uv run --group docs mkdocs build --strict
The owner's acceptance of the ADR wording cannot be scripted.