Phase 2a: embedded OIDC provider (authorize/token/userinfo/jwks/discovery)

[ClaydeCode]

Phase 2a of the multi-user identity rollout: the embedded OIDC provider, productionized from the passed PoC (spike spike/oidc-provider-poc, verdict 2026-06-12). Stacked on the phase-1 substrate PR.

Five endpoints under /public/oidc: /.well-known/openid-configuration, /authorize, /token, /userinfo, /jwks. Authorization-code + PKCE + refresh rotation, RS256 id_tokens. Deliberately not built: dynamic client registration, consent UI, third-party clients, logout channels — first-party app clients only.

How it works

• Built on Authlib's framework-agnostic server classes (>=1.7.2,<1.8 — 1.8 makes the grant param mandatory; pinned rather than chased tonight).
• Session = the existing terminal cookie. /authorize resolves the authorization JWT → terminal → users row (phase 1). The sub claim is the stringified numeric user id. A paired browser signs into an app with zero clicks; an anonymous browser is 302'd to the terminal UI with an oidc_rd return URL (login page lands in phase 3).
• Authlib's core is sync: request handling runs in asyncio.to_thread, storage hooks bridge back to the main loop's psycopg pool via run_coroutine_threadsafe — one pool, no sidestep (unlike the spike's sync-psycopg shortcut).
• Multi-user-ready: the provider only knows users rows; when members arrive (phase 4) nothing here changes except the grant check in /authorize.

Hardening vs. the spike (full list from the PoC verdict)

• Access/refresh tokens and authorization codes stored as SHA-256 digests — a DB read can no longer replay sessions. Client secrets stay plaintext deliberately: compose templates re-render them at every startup, and they sit in the app's compose env on the same disk anyway.
• Scope stored from request.scope (client-allowed), not raw request — scope-escalation regression covered by test.
• Null claims stripped from id_tokens (strict clients like Immich's openid-client v6 reject nonce: null).
• Both client_secret_basic and client_secret_post accepted (Immich sends _post).
• Token endpoint rate-limited (in-process, 30/min) → 429.
• RS256 key generated once, persisted in kv_store.
• ENV FORWARDED_ALLOW_IPS=* in the Dockerfile: fastapi run already enables uvicorn's proxy headers, but forwarded headers from the in-network Traefik must be trusted or Authlib sees http:// and refuses flows (InsecureTransportError, hit in the PoC).

Tests

17 integration tests against the real app + Postgres: discovery, JWKS stability, confidential + public (PKCE-only) flows, id_token claim correctness incl. nonce-absence, userinfo, refresh rotation (old access revoked, rotated refresh unusable), open-redirect rejection, wrong secret / unknown / expired / reused codes, anonymous redirect, scope narrowing, hashed-at-rest assertion, rate limit.

Not in this PR

• Client registration at app install + {{ oidc.* }} template vars (phase 2b, next PR)
• Login page / credentials (phase 3), members + grants (phase 4)
• Cleanup job for expired codes/tokens (tables stay tiny at household scale; can ride along with phase 3)

Recommended reading order

1. migrations/shard-core-0003-oidc.sql — schema
2. shard_core/database/oidc.py — storage (conn-first, hashed lookups)
3. shard_core/service/oidc_provider.py — Authlib models, grants, key mgmt, sync→async bridge
4. shard_core/web/public/oidc.py — FastAPI adapter, lazy init, session resolution, rate limit
5. shard_core/web/public/__init__.py, Dockerfile, pyproject.toml — wiring
6. tests/test_oidc.py

🤖 Generated with Claude Code

Test status

Full suite: 190 passed, 1 failed — test_app_lifecycle.py::test_app_starts_and_stops, which fails identically on clean main on this machine (pre-existing, container-start timing), not a regression from this branch.

---

Rebased on the reworked phase-1 branch: user_sub columns are BIGINT FKs, ShardUser carries the numeric id.

[ClaydeCode]

Security-hardening round from the OIDC review (RFC 9700), commit be5293b:

• PKCE: S256 only. Authlib's default also accepted plain (challenge = cleartext verifier — no interception protection). Dropped from validation and discovery.
• Authorization codes: atomic single-use. Redemption is now one UPDATE … RETURNING on a redeemed flag — the SELECT-then-DELETE TOCTOU where two concurrent /token calls could both redeem a code is gone. Any redemption attempt burns the code (even one that fails PKCE), and reuse of a redeemed code revokes every token of that (client, user) grant. Redeemed rows persist until expiry, which also makes the nonce-replay window real.
• Refresh-token reuse detection. Replaying a rotated-out refresh token now revokes the whole token family — previously the thief who rotated first kept a live token while the legit client got a silent invalid_grant.

Deferred (low, noted for later): per-client/IP rate-limit buckets — the coarse global 30/min guard stays.

Tests: 20/20 in tests/test_oidc.py, incl. new coverage for plain-PKCE rejection, burn-on-failed-redemption, code-reuse revocation, and family revocation on refresh replay.

🤖 Generated with Claude Code