# Generated auth runtime summary

> This file is generated from the live auth app. Do not edit it by hand; regenerate it from `apps/docs-site/` with `bun run generate`.

Generated from: `apps/core/auth/package.json`, `apps/core/auth/src/platform/better-auth/auth.ts`, `apps/core/auth/src/index.ts`

## Better Auth packages detected

| Package | Version | Type | Why it matters here |
| --- | --- | --- | --- |
| `@better-auth/mcp` | `1.7.0-rc.6` | Official addon | Auth dependency discovered in the auth app manifest. |
| `@better-auth/oauth-provider` | `1.7.0-rc.6` | Official addon | Auth dependency discovered in the auth app manifest. |
| `@better-auth/passkey` | `1.7.0-rc.6` | Official addon | Official Better Auth passkey addon enabling WebAuthn / passkey ceremonies. |
| `@better-auth/sso` | `1.7.0-rc.6` | Official addon | Auth dependency discovered in the auth app manifest. |
| `@better-auth/stripe` | `1.7.0-rc.6` | Official addon | Auth dependency discovered in the auth app manifest. |
| `@crown/better-auth-admin-access` | `workspace:*` | Crown extension | Crown extension for platform-wide admin, GDPR, auditor, and support access flows. |
| `@crown/better-auth-external-structure` | `workspace:*` | Crown extension | Crown extension for partner/external organization trees, invitations, and delegated access. |
| `@crown/better-auth-organization-archive` | `workspace:*` | Crown extension | Crown extension for organization archive, soft-delete, restore, and cascade handling. |
| `@crown/better-auth-permissions` | `workspace:*` | Crown extension | Crown extension for scoped roles, role templates, team grants, and permission checks. |
| `@crown/better-auth-workspace` | `workspace:*` | Crown extension | Crown extension for workspaces, workspace teams, invitations, and active workspace context. |
| `better-auth` | `1.7.0-rc.6` | Core | Core Better Auth runtime mounted by the auth service under `/api/auth/**`. |

## Plugin stack in configured order

| # | Module | Source | Type | What it adds |
| --- | --- | --- | --- | --- |
| 1 | Bearer Reads | `../../features/session/bearer-reads` | Official addon | Bearer Reads is configured in the auth app. |
| 2 | Email OTP | `better-auth/plugins` | Official addon | Sends verification, reset-password, and security-code OTP emails through Better Auth. |
| 3 | Two Factor | `better-auth/plugins` | Official addon | Adds TOTP / OTP-based second-factor challenges, backup codes, and trusted-device cookies. |
| 4 | Two Factor Context | `../../features/two-factor/two-factor-context` | Official addon | Two Factor Context is configured in the auth app. |
| 5 | Expired Session Cookies | `../../features/session/expired-session-cookies` | Official addon | Expired Session Cookies is configured in the auth app. |
| 6 | Admin | `better-auth/plugins` | Official addon | Enables Better Auth admin capabilities for platform owner/admin roles. |
| 7 | Organization | `better-auth/plugins` | Official addon | Adds organizations, teams, invitations, and membership roles to Better Auth. |
| 8 | Workspace | `@crown/better-auth-workspace` | Crown extension | Adds Crown workspaces, workspace teams, invitations, and active workspace tracking. |
| 9 | Passkey | `@better-auth/passkey` | Official addon | Enables WebAuthn passkey registration and sign-in via `@better-auth/passkey`. |
| 10 | Organization Archive | `@crown/better-auth-organization-archive` | Crown extension | Adds archive, soft-delete, and restore lifecycle operations for organizations. |
| 11 | JWT | `better-auth/plugins` | Official addon | Signs short-lived JWTs, manages JWKS keys, and defines the outbound token payload. |
| 12 | External Structure | `@crown/better-auth-external-structure` | Crown extension | Adds hierarchical partner/external organization nodes, invitations, and delegated workspace access. |
| 13 | Permissions | `@crown/better-auth-permissions` | Crown extension | Adds scoped roles, role templates, effective-permission checks, and team-wide grants. |
| 14 | Admin Access | `@crown/better-auth-admin-access` | Crown extension | Adds platform-level admin access APIs for organizations, users, teams, workspaces, and GDPR actions. |
| 15 | Sso | `@better-auth/sso` | Official addon | Sso is configured in the auth app. |
| 16 | Sso Policy | `../../features/sso/sso-policy` | Official addon | Sso Policy is configured in the auth app. |
| 17 | Billing Plugins | `../../features/billing/billing-plugins` | Official addon | Billing Plugins is configured in the auth app. |

## How Better Auth works in Crown

- Better Auth is mounted inside the Hono auth service at `/api/auth/**`, so the browser talks to the service wrapper rather than to Better Auth directly.
- The auth store uses `surrealAdapter(...)`, so Better Auth state lives in SurrealDB alongside the Crown auth schema.
- Primary sign-in modes detected: `email + password`, `email OTP`, `passkey`.
- Email/password sign-in requires verified email before the normal session flow is considered complete.
- OTP-related flows default to a 10-minute validity window unless overridden by environment variables.
- A user creation hook bootstraps the first user as an owner, so initial platform setup happens inside the auth app rather than in separate seed logic.
- A session creation hook normalizes Surreal record IDs and auto-activates organization, workspace, and team context whenever the user membership graph is unambiguous.
- Trusted origins are configured explicitly, which keeps Better Auth, email links, passkeys, and cross-origin UI callbacks aligned with the deployed frontend origins.
- Cookie defaults are centralized, so session, two-factor, and trusted-device cookies share the same secure / httpOnly / sameSite policy envelope.
- The JWT plugin signs 15m tokens using EdDSA / Ed25519 and publishes JWKS for downstream verification.
- The auth service layers a token-exchange route on top of Better Auth so an existing token can be reissued for an alternate SurrealDB access scope.
- A passkey admin helper route lets privileged users inspect passkey records already persisted by Better Auth.
- Crown-specific role template, custom role, and assignment APIs are hosted beside Better Auth so permission authoring stays anchored to the same authenticated session context.
- Reference-numbering routes also live in the auth service, reusing the Better Auth session and resolved organization / workspace / team scope.

## Session behavior detected

- Session inactivity expiry: `60 * 30`
- Session refresh cadence: `60`
- Fresh-session window: `60 * 5`
- Cookie cache max age: `60`

## JWT claims detected

The Better Auth JWT payload currently includes: `ac`, `activeOrganizationId`, `activeTeamId`, `activeWorkspaceId`, `db`, `email`, `emailVerified`, `false`, `id`, `ns`, `null`, `orgRole`, `role`, `sub`, `teamRole`, `twoFactorEnabled`, `twoFactorMethod`, `twoFactorMethods`.

## Auth-service endpoint groups detected

| Route / prefix | Methods | Why it exists | Matched paths |
| --- | --- | --- | --- |
| `/api/auth/**` | GET, POST | Mounted Better Auth handler for sign-in, sign-up, sessions, password reset, passkeys, and plugin endpoints. | `/api/auth/**` |
| `/.well-known/jwks.json` | GET | Stable JWKS alias used by downstream APIs and SurrealDB to verify Better Auth JWTs. | `/.well-known/jwks.json` |
| `/api/token/exchange-db` | POST | Verifies an existing Better Auth JWT and mints a database-scoped replacement token. | `/api/token/exchange-db` |
| `/api/admin/user-passkeys` | GET | Admin helper route for inspecting passkey credentials already stored for a user. | `/api/admin/user-passkeys` |
| `/api/reference-numbering/*` | GET, POST | Crown auth-service extensions that use the authenticated org/workspace/team context for reference numbering. | `/api/reference-numbering/context`<br/>`/api/reference-numbering/organization`<br/>`/api/reference-numbering/team`<br/>`/api/reference-numbering/workspace` |
| `/api/role-templates*` | DELETE, GET, PATCH, POST | Crown role-template APIs layered next to Better Auth authorization metadata. | `/api/role-templates`<br/>`/api/role-templates/:id`<br/>`/api/role-templates/:id/roles` |
| `/api/roles*` | DELETE, GET, PATCH, POST | Custom role CRUD, template-diff, and migration APIs layered on top of the Better Auth session. | `/api/roles`<br/>`/api/roles/:id`<br/>`/api/roles/:id/migrate`<br/>`/api/roles/:id/template-diff` |
| `/api/role-assignments*` | DELETE, GET, POST | Crown role-assignment APIs that attach custom roles to members in org/workspace/team scopes. | `/api/role-assignments`<br/>`/api/role-assignments/:id` |
| `/session` | GET | Minimal authenticated echo of the Better Auth session and current user. | `/session` |
| `/api/bootstrap/status` | GET | Checks whether the auth datastore already contains a privileged bootstrap user. | `/api/bootstrap/status` |

## Generation note

- The auth flow diagram and this runtime summary are both derived from the auth app’s current Better Auth config and Hono routes.
- If the plugin list, JWT payload, or auth-service routes change, the next docs generation run updates these artifacts automatically.