Skip to content

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's SessionInfo stays identity only. An anonymous session before sign-in is that record alone, short-lived, behind the same __Host-session cookie; 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 in rn-forge-auth with one case ID per row of Security controls, after rn_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.auth package that replaces the auth module, keeping its public names; the rn-forge-auth stores are synchronous and run in the thread pool; privilege-change rotation is an explicit rotate_session call; rate limiting is the binding's own fixed-window counter over Redis INCR, with an in-memory counter for tests; ResourcePolicy is 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-session cookie, 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. A Bearer request and back-channel logout are exempt; a Basic one is not.
  • Implementation defaults, 2026-10-28 (S13.6.5): the audit helper (audit, AUDIT_LOGGER) lives in rn-forge-auth, so both bindings emit the same events. rn_forge.auth.conformance is imported by name, not re-exported. The FastAPI binding cannot tell provisioning from linking, so an application's provisioning AccountResolver emits account.provisioned itself, and account.disabled is 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 APIRouter serves 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-fastapi gains a redis extra on rn-forge-auth[redis], and its oidc extra names rn-forge-auth[oidc].
  • No Location header, 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 SessionStore sets the __Host-session cookie 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/session not extending it, and rotation at login and on privilege change leaving the old ID unreadable.
  • Version and revoked-sid checks run on read and delete an invalid session. /auth/logout, /auth/logout/all and 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 403 csrf-failed.
  • Before sign-in a short-lived anonymous session holds the token, so /auth/login/password is protected; sign-in replaces both.
  • The origin check, the exemptions and the conformance case for csrf-failed match S13.5.3, with session-routes and csrf in the driver's PROVIDES set.
  • Mounting the router without a problem type_base fails at startup (E13).

S13.6.4 — Principal dependencies

State: Closed (2026-10-28)

Acceptance:

  • current_principal yields a session or bearer Principal, and requires checks a Requirement built by the action-to-key helper. ResourcePolicy hooks scope SQLAlchemy selects.
  • bearer_auth() resolves the token's (issuer, subject) through AccountResolver.lookup, never provisions, and answers 401 for an unlinked subject. A request with an Authorization header 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 redis extra. 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).
uv run --package rn-forge-fastapi pytest packages/rn-forge-fastapi
uv run pyright
sh docs/_update_board.sh --check