F13.6 — FastAPI binding
| State | Closed |
| Parent | E13 |
| Iteration | Release 7 |
| Start Date | 2026-10-28 |
| Closed Date | 2026-10-28 |
| Predecessors | F13.4 |
| Source | Owner decision, 2026-10-26 |
Stories: 6 Closed
| Story | State | Depends on |
|---|---|---|
| S13.6.1 — Router | Closed (2026-10-28) | — |
| S13.6.2 — Session middleware | Closed (2026-10-28) | — |
| S13.6.3 — CSRF | Closed (2026-10-28) | — |
| S13.6.4 — Principal dependencies | Closed (2026-10-28) | — |
| S13.6.5 — Rate limiting, audit events and parity | Closed (2026-10-28) | — |
| S13.6.6 — Document the binding | Closed (2026-10-28) | — |
rn-forge-fastapi binds the same HTTP surface and security defaults as an
APIRouter, as Package responsibilities
lists for it.
Context
Libraries binds no session or CSRF library on FastAPI:
starsessions cannot hold idle and absolute timeouts together, extends the
session on every read and leaves the old record readable after rotation, and no
evaluated CSRF library binds its token to the session. pykit writes both over
rn-forge-auth's SessionStore. ADR-0014 requires
the behaviour of F13.5, case for case. The link table
and default AccountResolver in rn-forge-sqlalchemy wait for an application
that needs them, so FastAPI applications implement AccountResolver and
AuthorizationContextProvider themselves.
Decisions
- Owner decision, 2026-10-28: the synchronizer CSRF token lives in a record the
binding owns, keyed by session ID, with in-memory and Redis implementations.
rn-forge-auth'sSessionInfostays identity only. An anonymous session before sign-in is that record alone, short-lived, behind the same__Host-sessioncookie; sign-in deletes it and mints a token for the new session. - Owner decision, 2026-10-28: the security-control case list shared by both
bindings' suites is
rn_forge.auth.conformance, an ungated module inrn-forge-authwith one case ID per row of Security controls, afterrn_forge.web.conformance. Each suite maps every ID to its tests, and a test fails on an uncovered ID. - Implementation defaults, 2026-10-28, following F13.5: the binding lives in an
rn_forge.fastapi.authpackage that replaces theauthmodule, keeping its public names; thern-forge-authstores are synchronous and run in the thread pool; privilege-change rotation is an explicitrotate_sessioncall; rate limiting is the binding's own fixed-window counter over RedisINCR, with an in-memory counter for tests;ResourcePolicyis generic over the query type, so SQLAlchemy is a test dependency only. - Implementation default, 2026-10-28 (S13.6.3): the session middleware runs the
CSRF check on an unsafe request that carries a
__Host-sessioncookie, live, anonymous or stale, and always on the password-login path, so a cookie-less API call is unchecked, as Django's DRF views are. ABearerrequest and back-channel logout are exempt; aBasicone is not. - Implementation defaults, 2026-10-28 (S13.6.5): the audit helper (
audit,AUDIT_LOGGER) lives inrn-forge-auth, so both bindings emit the same events.rn_forge.auth.conformanceis imported by name, not re-exported. The FastAPI binding cannot tell provisioning from linking, so an application's provisioningAccountResolveremitsaccount.provisioneditself, andaccount.disabledis emitted at login. Each suite finds its tagged tests by scanning its source, so coverage does not depend on test selection.
S13.6.1 — Router
State: Closed (2026-10-28)
Acceptance:
- An
APIRouterserves every route of HTTP surface under a configurable prefix, with the same responses, cookies, error codes and transaction handling as S13.5.1. rn-forge-fastapigains aredisextra onrn-forge-auth[redis], and itsoidcextra namesrn-forge-auth[oidc].- No
Locationheader, URL or log record in the route tests contains a token, code or assertion.
S13.6.2 — Session middleware
State: Closed (2026-10-28)
Acceptance:
- A session middleware over a
SessionStoresets the__Host-sessioncookie with the design's flags and holds only the design's session content. - Tests show the 30-minute sliding idle timeout and the 12-hour absolute timeout
applying to the same session,
GET /auth/sessionnot extending it, and rotation at login and on privilege change leaving the old ID unreadable. - Version and revoked-
sidchecks run on read and delete an invalid session./auth/logout,/auth/logout/alland back-channel logout behave as on Django. - Race tests run concurrent requests against a logout, a back-channel logout and an account disablement, and no request after the revocation succeeds.
- Outside debug mode the binding refuses the in-memory stores.
S13.6.3 — CSRF
State: Closed (2026-10-28)
Acceptance:
- A synchronizer token kept in the server session is exposed through a readable cookie and compared in constant time with the header on every unsafe request to a session-authenticated route, with names matching Angular's XSRF support.
- A test replays a token pair minted in another browser with the victim's
session cookie and gets
403csrf-failed. - Before sign-in a short-lived anonymous session holds the token, so
/auth/login/passwordis protected; sign-in replaces both. - The origin check, the exemptions and the conformance case for
csrf-failedmatch S13.5.3, withsession-routesandcsrfin the driver'sPROVIDESset. - Mounting the router without a problem
type_basefails at startup (E13).
S13.6.4 — Principal dependencies
State: Closed (2026-10-28)
Acceptance:
current_principalyields a session or bearerPrincipal, andrequireschecks aRequirementbuilt by the action-to-key helper.ResourcePolicyhooks scope SQLAlchemy selects.bearer_auth()resolves the token's(issuer, subject)throughAccountResolver.lookup, never provisions, and answers401for an unlinked subject. A request with anAuthorizationheader is authenticated by the bearer path alone.- The password provider uses an application-supplied verifier.
S13.6.5 — Rate limiting, audit events and parity
State: Closed (2026-10-28)
Acceptance:
- Rate limits and audit events match S13.5.6, in tests.
- One case list, shared by the Django and FastAPI test suites, covers every row of Security controls, and both suites pass every case.
S13.6.6 — Document the binding
State: Closed (2026-10-28)
Acceptance:
- The FastAPI auth guide describes the new surface, configuration, the Redis requirement and the protocols an application implements.
- The changelog records the binding and the
redisextra. Both strict MkDocs builds pass.
Acceptance
- The HTTP surface is served by an
APIRouter(S13.6.1). - pykit's session middleware times out, rotates and revokes as on Django (S13.6.2).
- The synchronizer CSRF token is bound to the session (S13.6.3).
- Session and bearer callers resolve to accounts and are authorized through the dependencies (S13.6.4).
- Both bindings pass the shared security-control cases (S13.6.5).
- The binding is documented (S13.6.6).