@claude Expose a federated AuthN contract for sibling apps (FuzeKeys): shared Authentik issuer/JWKS + published token-validator

[izzywdev]

Originator: FuzeKeys auth integration (FuzeKeys must delegate authN to the shared Authentik, not roll its own).

Context / why: FuzeFront's auth is a BFF — backend/src/services/oidc.ts exchanges the Authentik code server-side and backend/src/routes/auth.ts mints a private HS256 JWT (jwt.sign({userId}, JWT_SECRET)), verified in backend/src/middleware/auth.ts. There is no JWKS, no aud/iss, no introspection, and no shared validator a sibling service can use without sharing JWT_SECRET.

Asks:

1. Document the canonical federation model: are sibling apps (FuzeKeys) independent OIDC clients of the same Authentik (validate Authentik RS256 via JWKS), or meant to consume FuzeFront's minted token? State it authoritatively.
2. If independent-client: publish a versioned token-validation contract (issuer, expected aud per app, JWKS URL, sub→user mapping) + a reference validator (a @fuzefront/authn TS helper and a documented FastAPI/Python equivalent).
3. If consume-FuzeFront-token: expose POST /api/auth/introspect (or RS256 + JWKS) so siblings never need JWT_SECRET.

Acceptance criteria:

• A documented, versioned AuthN integration contract a FastAPI service can implement.
• Either a published validator package or a JWKS/introspection endpoint (no JWT_SECRET sharing).
• Worked example: FuzeKeys validates a family token end-to-end.

Notifications requested: please @-mention me when the contract is frozen and again when it is deployed to the cluster.

STATE: blocks FuzeKeys flipping AUTH_MODE=authentik. Asserted against live izzywdev/FuzeFront master (the FuzeKeys-vendored submodule is pinned older and lacks this surface).

[claude]

Claude finished @izzywdev's task in 8m 44s —— View job • claude/issue-112-20260630-0708 • Create PR ➔

---

Federated AuthN contract for sibling apps (FuzeKeys)

• Read current auth surface (oidc.ts, auth.ts, middleware/auth.ts)
• Map repo structure (packages, docs, lerna/workspaces, SDK publishing)
• Decide & document the canonical federation model (authoritative)
• Write the versioned token-validation contract doc
• Implement @fuzefront/authn reference validator (TS)
• FastAPI/Python reference validator + worked example
• Wire package into lerna/workspaces, add READMEs
• Open PR (no bot-merge — master is deploy-on-push); request maintainer freeze

---

Decision (authoritative)

Sibling apps (FuzeKeys) are independent OIDC resource servers of the shared Authentik issuer. They validate Authentik-issued RS256 JWTs via the shared JWKS, scoped to their own aud. They do not consume FuzeFront's minted token, and JWT_SECRET is never shared.

Why — FuzeFront's jwt.sign({ userId, sessionId }, JWT_SECRET) (HS256, in backend/src/routes/auth.ts) is a private BFF session artifact: no iss/aud, symmetric (verifying it elsewhere = sharing the secret), bound to the sessions table. It must not cross a service boundary. Authentik is already the family IdP, so the clean, standards-based model is per-app OIDC resource servers validating RS256 via JWKS — zero shared secrets, JWKS key rotation, first-class library support. The introspection / consume-FuzeFront-token path is explicitly rejected for v1 (rationale + future migration in the doc).

What's in the PR

Deliverable	Path
Versioned contract (v1.0.0, normative: issuer/JWKS/aud/sub-mapping, verification rules, per-app registry, freeze status)	docs/auth/federation-authn-contract.md
TS reference validator @fuzefront/authn — createAuthnValidator() + requireFamilyAuth() Express middleware, RS256-only + alg-confusion guard, vitest suite	packages/authn/ (wired into lerna.json + workspaces)
Python/FastAPI reference FamilyAuthValidator + FastAPI dependency	examples/fuzekeys-fastapi/fuze_authn.py, app.py
Worked example — mints RS256 tokens with an ephemeral keypair and validates end-to-end (valid passes; wrong-aud/iss, expired, missing-sub, HS256 rejected) — in both TS and Python	packages/authn/src/validator.test.ts, examples/fuzekeys-fastapi/test_validator.py

Acceptance criteria — ✅ documented versioned contract a FastAPI service can implement · ✅ published validator package (@fuzefront/authn) rather than a JWT_SECRET-sharing endpoint · ✅ end-to-end worked example.

⚠️ Notes / what I did NOT do

• No backend auth changes. Model A does not require FuzeFront to change its BFF flow, and master is deploy-on-push — so I left runtime auth untouched.
• Not merged, not frozen. Per the repo convention (master deploy-on-push → never bot-merge; freeze needs your sign-off) the contract is marked 🟡 DRAFT — pending freeze.
• Could not run the test suites here — the action sandbox blocked npm/pytest/script execution (and @fuzefront/authn's jose dep isn't installed). The TS (vitest) and Python (pytest) suites are written to run network-free; please let CI / a local run validate them.
• @izzywdev — this is the contract for you to review and freeze. On your approval/merge, the doc's freeze milestone flips to frozen and FuzeKeys can pin v1.0.0. Deploy also needs a fuzekeys OAuth2 provider (client_id=fuzekeys-client) registered in the shared Authentik — a FuzeInfra change to be delegated via @claude. I'll @-mention you again at freeze and at deploy as requested.

· branch claude/issue-112-20260630-0708