Skip to content

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.md requires 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 Background gains 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 Influences links the design's package placement.
  • The new ADRs take the next free numbers at the time of writing. Each follows docs/adr/_structure.md: status accepted with 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 iss check, the UserInfo sub check), 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 unknown kid). 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_oidc and fetch_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.toml is 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 ## Acceptance block, their predecessors, and Iteration set 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 Order and Breaking changes list 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.