diff --git a/docs/components/backend/authenticator/DESIGN.md b/docs/components/backend/authenticator/DESIGN.md index ab4ea9115..47b6a273c 100644 --- a/docs/components/backend/authenticator/DESIGN.md +++ b/docs/components/backend/authenticator/DESIGN.md @@ -966,7 +966,7 @@ The authenticator is an idiomatic gears-rust gear -- the same shape the analytic - **Type system**: DTOs derive the OpenAPI schema and register through the types registry; any future plugin-shaped extension point (a `SessionStore` backend, IdP-quirk adapters) declares a GTS schema with well-known instances collected at link time. - **The two-listener wrinkle**: the REST host binds one address; the token listener (`POST /internal/token` only) is a small secondary HTTP server owned by the gear's runnable capability -- cluster-internal, one endpoint, deliberately off the public OpenAPI surface. - **Wiring**: compose service entry (`authenticator`, own port), multi-stage Dockerfile, Helm chart (deployment + configmap + envFrom secret), CI build-path filter, workspace member -- copy the analytics pattern. -- **Reuse map** (verified in the workspace): OIDC issuer discovery + JWKS fetch/cache + circuit breaker + single-flight exist in oidc-authn-plugin infrastructure (reuse/extract); the S2S token client exists as that plugin's token client (also the model for the *client* side of `/internal/token`); the authorization-code + PKCE client and JWT minting + JWKS *serving* are new builds; Redis comes from the workspace's pinned `redis` crate. +- **Reuse map** (verified in the workspace): OIDC issuer discovery + JWKS fetch/cache + circuit breaker + single-flight exist in oidc-authn-plugin infrastructure (reuse/extract); the S2S token client exists as that plugin's token client (also the model for the *client* side of `/internal/token`); the authorization-code + PKCE client and JWT minting + JWKS *serving* are new builds; Redis comes from the workspace's pinned `redis` crate. The broker adoption (ADR-0003) added no bespoke broker code to the gear: Keycloak runs as the in-stack `insight-keycloak` subchart with realm content applied by keycloak-config-cli (both adopted externals, configuration-as-code only); the roster realm is generated by the seed package's `insight-seed-realm` entry point and reused unchanged by compose, the local sandbox, CI, and the e2e rigs -- one token contract everywhere, which is what let the fakeidp test double be deleted rather than maintained in parallel; the only authenticator code the broker required is the host-keyed issuer map (`issuers.rs`, realm selection by request host). - **Known collision**: gears-rust contains a docs-only twin (`gears/system/bff` -- PRD/DESIGN/ADRs, zero code) whose design the authenticator substantially implements. Those docs are marked superseded-for-insight (or the authenticator is later upstreamed as their implementation) -- tracked in the gears-rust repo, outside this document. ## 4. Cross-Cutting Concerns