Understand / Architecture
Architecture and ownership.
ComplicatedAuth separates Tenant administration from Project User authentication, then separates browser-safe state from authoritative backend secrets.
Management consoleTenant Member · HttpOnly session cookie
Customer browser@complicatedauth/browser · opaque browser tokens
ComplicatedAuth APIGo control plane + Project runtime · 116 operations
Customer BFF@complicatedauth/server · scoped service credential stays server-side
PostgreSQLTenants, projects, users, credentials, sessions
Biometric providerOptional external template service
Responsibility map
Every boundary has one owner.
The current architecture is strongest when credentials stay inside the layer designed to hold them.
Management consoleTenant Member login, WebAuthn setup, Project configuration, users, service accounts, activity.Holds a one-time login secret transiently in memory; authenticated state uses an HttpOnly bootstrap or strong cookie.
Browser SDKLogin orchestration, WebAuthn ceremonies, optional camera capture.Holds browser-safe opaque login and session tokens.
Customer BFFMaps opaque tokens, adds one scoped Project service credential, and proxies the stable
/auth protocol.Holds the service credential and authoritative login/session references.Go APIAuthorization, assurance policy, ceremonies, sessions, control plane, audit.Hashes secrets before PostgreSQL persistence.
Biometric providerCreates and compares external templates.Receives selfie bytes; ComplicatedAuth stores only its template ID.
Workspace components
| Repository | Role | Current signal |
|---|---|---|
complicatedauth-openapi | Canonical contract and generated-type source. | 116 operations; lint and bundle pass. |
complicatedauth-backend | Authoritative Go HTTP service and migrations. | Unit and PostgreSQL acceptance tests pass. |
complicatedauth-console | First-party Next.js control plane. | Typecheck, lint, build, audit, and browser flows pass. |
complicatedauth-web-sdk | Framework-neutral browser client. | Typecheck, tests, build, and CI pass. |
complicatedauth-backend-sdk | Secret-holding BFF companion. | Includes shared Redis TTL storage and multi-instance tests. |
complicatedauth-biometric-web-sdk | Optional camera and biometric client. | Tests and build pass; no liveness contract. |
complicatedauth-nextjs-example | Minimal all-SDK integration. | Builds without secrets; loads them only on a route request. |
Isolation invariants
- Every Project User query includes
project_uid. - A service credential is accepted only while its credential, parent service account, and Project are active, and only for the Project encoded in the request path.
- Service-account scopes are exact and re-evaluated on every request; scope removal and credential revocation take effect immediately.
- Origin validation uses exact configured origins for WebAuthn ceremonies.
- The management console and customer applications use distinct WebAuthn RP IDs; ports are not an isolation boundary.
- The RP ID becomes permanently locked after the first credential registration.
- Identical emails may exist independently in different Projects.
- OAuth client types are immutable, redirect URIs match exactly, and client IDs are never reused after deletion.
- OpenID subjects are pairwise per Tenant Member and OAuth Application; email is not the account key.
- OAuth access tokens are audience-bound to UserInfo and cannot authorize management APIs.
- Delegated tokens name one exact Resource Server; Tenant, principal, audience, and capabilities come only from the active token.
- Administrative client grants bound user consent, while scope-v1 policy semantics remain stable and versioned.
- Support Cases belong to a Tenant and optional Project. Tenant operators receive the full inbox; Project service credentials receive only their exact Project and public correspondence.