@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/auth-oidc.md

@@ -0,0 +1,95 @@
+# OIDC (generic)
+
+> Generic OIDC AuthStrategy — verifies any OpenID-Connect IdP's JWTs via JWKS (Okta, Keycloak, Cognito, Azure AD, Google Workspace). Discovery or explicit JWKS URL; maps a claim → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-oidc.md -->
+## OIDC (generic)
+
+_Generic OIDC AuthStrategy — verifies any OpenID-Connect IdP's JWTs via JWKS (Okta, Keycloak, Cognito, Azure AD, Google Workspace). Discovery or explicit JWKS URL; maps a claim → tenantId._
+
+`@voltro/plugin-auth-oidc` is the **generic** OIDC adapter: an `AuthStrategy` (conforming to `@voltro/protocol`) for any IdP that publishes a standards-compliant OpenID Connect discovery document — **Okta, Keycloak, Cognito, Azure AD, Google Workspace**, and anything else OIDC-compliant that doesn't ship a first-party plugin. It verifies the IdP's JWTs against its **JWKS** (public-key verify — no client secret), maps a configured claim to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It performs no verification of its own — it adds the JWKS-discovery indirection and delegates the verify pipeline to the shared `jwtBearerStrategy`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-oidc
+```
+
+## Wiring
+
+Add `oidcStrategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { oidcStrategy } from '@voltro/plugin-auth-oidc'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      oidcStrategy({
+        id:          'okta',                       // stable id for logs + metadata.provider
+        issuer:      'https://acme.okta.com',      // also the discovery base
+        audience:    'api://acme',                 // expected `aud`
+        tenantClaim: 'acme/tenant_id',             // which claim carries the Voltro tenantId
+        // jwksUrl:   'https://acme.okta.com/oauth2/v1/keys',  // skip discovery roundtrip
+        // discoveryUrl: '…',                       // non-standard discovery path
+        // defaultTenantId: 'public',               // fallback when the claim is absent
+        // scopesFromClaims: (c) => String(c['scope'] ?? '').split(' ').filter(Boolean),
+      }),
+    ],
+  },
+}
+```
+
+Two modes: pass `jwksUrl` for zero boot-time IO, or omit it and the strategy fetches `jwks_uri` from `${issuer}/.well-known/openid-configuration` on the first request (cached per-URL for the process lifetime). Pass `discoveryUrl` if your provider hosts the document at a non-standard path.
+
+Tenant resolution: the value at `tenantClaim` (default `'tenant'`) becomes `tenantId`; or supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict — the strategy owns the request but can't satisfy the tenant invariant). `scopesFromClaims` maps verified claims onto `Subject.scopes` so `requireScope` / `hasScope` gate handlers off the token with no second lookup.
+
+To accept your own password sessions AND OIDC during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { oidcStrategy } from '@voltro/plugin-auth-oidc'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  oidcStrategy({ id: 'keycloak', issuer: 'https://id.acme.com/realms/acme', tenantClaim: 'realm_access.tenant' }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `id` | — (**required**) | Stable id for logs + `metadata.provider`. |
+| `issuer` | — (**required**) | Expected `iss`; discovery base. |
+| `audience` | (off) | Expected `aud`. String or array. |
+| `jwksUrl` | (discovery) | Explicit JWKS URL — skips discovery. |
+| `discoveryUrl` | `${issuer}/.well-known/openid-configuration` | Override for non-standard paths. |
+| `algorithms` | `['RS256']` | Allowlist; extend with `ES256` / `PS256` / `EdDSA`. |
+| `cookieName` | (off) | Cookie carrying the JWT; `null` disables cookie fallback. |
+| `tenantClaim` | `'tenant'` | Claim carrying the Voltro `tenantId`. |
+| `tenantIdFromClaims` | (uses `tenantClaim`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback when the claim is absent. |
+| `scopesFromClaims` | (none) | Map claims → `Subject.scopes`. |
+
+## Environment variables
+
+None read directly — pass `issuer` / `audience` / `jwksUrl` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token (or a discovery failure) yields `failed`, never `matched`. Asymmetric algorithms only (`HS256` is rejected — a shared-secret HMAC over a public JWKS flow is a downgrade vector).
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)

package/templates/agent-docs/plugins/auth-supabase.md

@@ -0,0 +1,103 @@
+# Supabase Auth
+
+> Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-supabase.md -->
+## Supabase Auth
+
+_Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId._
+
+`@voltro/plugin-auth-supabase` integrates [Supabase Auth (GoTrue)](https://supabase.com/auth): an `AuthStrategy` (conforming to `@voltro/protocol`) that verifies Supabase-issued JWTs — by default against the project's **JWKS endpoint** (asymmetric public-key verify, no secret), or via an opt-in **HS256 shared secret** (`jwtSecret`) for legacy / self-hosted deployments that sign symmetrically and expose no JWKS — maps a server-controlled metadata claim to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It's a thin specialization of the shared `jwtBearerStrategy` — it adds Supabase's defaults and performs no verification of its own. Verified claims (both the server-controlled `app_metadata` and the user-controlled `user_metadata` blobs) arrive on the Subject under `metadata.claims`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-supabase
+```
+
+## Wiring
+
+Add `supabaseStrategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { supabaseStrategy } from '@voltro/plugin-auth-supabase'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      supabaseStrategy({
+        projectRef: 'abcdef',                       // builds the hosted JWKS URL
+        // OR self-hosted GoTrue — pass an explicit URL + issuer:
+        // jwksUrl: 'https://my-supabase.example.com/auth/v1/.well-known/jwks.json',
+        // issuer:  'https://my-supabase.example.com/auth/v1',
+        // OR legacy / self-hosted Supabase signing with the shared secret
+        // (HS256, no JWKS) — verify with the secret instead:
+        // jwtSecret: process.env.SUPABASE_JWT_SECRET!,  // server-only credential
+        // tenantClaim: 'app_metadata.tenant_id',    // default (dotted path)
+        // defaultTenantId: 'public',                // fallback for single-tenant deployments
+      }),
+    ],
+  },
+}
+```
+
+Pass `projectRef` (hosted), `jwksUrl` (self-hosted GoTrue), or `jwtSecret` (legacy / self-hosted HS256 shared secret — see below). For a hosted project, the JWKS URL defaults to `https://<projectRef>.supabase.co/auth/v1/.well-known/jwks.json` and the issuer to `https://<projectRef>.supabase.co/auth/v1`. `audience` defaults to `'authenticated'` (Supabase's role for signed-in users).
+
+Tenant resolution maps from `tenantClaim` — default the dotted path `app_metadata.tenant_id` (a server-controlled blob users can't forge), then `defaultTenantId`. Apps that route tenants via `user_metadata` set `tenantClaim: 'user_metadata.org'` (same dotted-path resolution). Supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict).
+
+`cookieName` defaults to `null` (header-only) — most Voltro apps send the token as an `Authorization: Bearer` header. For **server-rendered / `@supabase/ssr` apps** that keep the session in a cookie, set `cookieName: 'sb-<projectRef>-auth-token'`. `@supabase/ssr` does NOT store a raw JWT there — it stores the whole GoTrue session as a JSON envelope, by default prefixed with `base64-` and base64url-encoded, and (for large sessions) split across `sb-<projectRef>-auth-token.0`, `.1`, … chunk cookies. The strategy unwraps all of that — URL-decode, strip the `base64-` prefix + base64url-decode, concatenate chunks in order — down to the inner `access_token` before verifying it. The `Authorization: Bearer` header is always a raw JWT and is unaffected.
+
+Strategies live on your **`type:'api'` app** — a `type:'web'` app has no auth middleware, so putting `auth.strategies` in a web `app.config.ts` does nothing. The web app forwards the request cookie to the api (including from [`ctx.query` in a loader](/docs/routing/loaders-and-meta#authentication-in-loaders)); the api's strategies verify it.
+
+> Client side — this strategy only *verifies*; your browser must *send* the token. For HTTP that's the normal `Authorization: Bearer` header; for **live subscriptions over the WebSocket** (the usual cross-origin api), pass it to `mount({ apis: { api: { headers: async () => ({ authorization: 'Bearer ' + token }) } } })` — a browser can't set WS upgrade headers, so without this every subscription connects anonymous. See [Client: getting the token to the api](/docs/authentication/external-idp#client-getting-the-token-to-the-api-http-and-websocket).
+
+To accept your own password sessions AND Supabase during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { supabaseStrategy } from '@voltro/plugin-auth-supabase'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  supabaseStrategy({ projectRef: process.env.SUPABASE_PROJECT_REF! }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `projectRef` | — | The `<ref>` in `<ref>.supabase.co`. Required unless `jwksUrl` is set. |
+| `jwksUrl` | `https://<projectRef>.supabase.co/auth/v1/.well-known/jwks.json` | For self-hosted GoTrue; takes precedence over `projectRef`. |
+| `jwtSecret` | — | **Opt-in HS256 mode** for legacy / self-hosted Supabase that signs with the shared `JWT_SECRET` and exposes no JWKS. Tokens are verified symmetrically (`HS256`); the JWKS path is not used. Server-only credential — never ship it to the browser. |
+| `issuer` | `https://<projectRef>.supabase.co/auth/v1` | Set explicitly for self-hosted. |
+| `audience` | `'authenticated'` | String or array. |
+| `cookieName` | `null` (header-only) | Set to `sb-<ref>-auth-token` for `@supabase/ssr` cookie-mode apps — the JSON / `base64-` / chunked session envelope is unwrapped to the inner `access_token`. |
+| `tenantClaim` | `'app_metadata.tenant_id'` | Dotted-path. |
+| `tenantIdFromClaims` | (uses `tenantClaim`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback for single-tenant deployments. |
+| `scopesFromClaims` | (none) | Map claims (Supabase `role`, or an `app_metadata` permissions array) → `Subject.scopes`. |
+
+Algorithms follow the mode — JWKS pins `['RS256', 'ES256']`, `jwtSecret` pins `['HS256']`; the two are mutually exclusive, so there is no alg-confusion downgrade surface (an RS256 setup can't be tricked into accepting an HS256-forged token). `none` is never accepted.
+
+## Environment variables
+
+None read directly — pass `projectRef` / `jwksUrl` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token, or one with no resolvable tenant, yields `failed`, never `matched`. JWKS mode does public-key verify only and handles no secret. The opt-in `jwtSecret` mode (legacy / self-hosted) verifies HS256 with the project's shared secret — a server-side credential; keep it out of the browser bundle and source control (load it from your env). Prefer JWKS whenever the deployment offers it.
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)

package/templates/agent-docs/plugins/auth-workos.md

@@ -0,0 +1,105 @@
+# WorkOS
+
+> WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId.
+
+
+
+---
+
+<!-- source: en/plugins/auth-workos.md -->
+## WorkOS
+
+_WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId._
+
+`@voltro/plugin-auth-workos` integrates [WorkOS](https://workos.com) AuthKit / SSO: an `AuthStrategy` (conforming to `@voltro/protocol`) that verifies WorkOS-issued JWTs against the **JWKS endpoint** (public-key verify — no API key), maps `org_id` to the framework's `tenantId`, and composes with other strategies (your password cookie, an API key, another IdP). It's a thin specialization of the shared `jwtBearerStrategy` — it adds WorkOS's defaults and performs no verification of its own. Verified claims arrive on the Subject as `metadata.provider === 'workos'` + `metadata.claims`.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-workos
+```
+
+## Wiring
+
+Add `workosStrategy(...)` to `auth.strategies` in your api's `app.config.ts`. The built-in signed-cookie password strategy always runs first; your strategies run after it, in order, until one `matched`s (or one `failed`s).
+
+```ts
+// app.config.ts
+import { workosStrategy } from '@voltro/plugin-auth-workos'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  auth: {
+    strategies: [
+      workosStrategy({
+        clientId: process.env.WORKOS_CLIENT_ID!,   // client_01H… — builds JWKS URL + audience
+        // defaultTenantId: 'public',               // fallback when claims expose no org_id
+      }),
+    ],
+  },
+}
+```
+
+`clientId` is the only required option. From it: the JWKS URL defaults to `https://api.workos.com/sso/jwks/<clientId>`, the issuer to `https://api.workos.com`, and the **audience to the `clientId`**. The cookie defaults to `wos-session` (set by AuthKit's cookie-mode SDK; pass `null` for header-only).
+
+Tenant resolution maps from `claims.org_id`, then `defaultTenantId`. Supply `tenantIdFromClaims(claims)` to derive it (returning `null` is a `failed` verdict). Verified claims arrive as `WorkosClaims` (`sub`, `email`, `org_id`, `role`, `permissions`, …).
+
+To accept your own password sessions AND WorkOS during a migration, build the chain explicitly with `composeAuthStrategies` (see [auth strategies](/docs/authentication/strategies)):
+
+```ts
+import { composeAuthStrategies } from '@voltro/protocol'
+import { voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { workosStrategy } from '@voltro/plugin-auth-workos'
+
+const resolve = composeAuthStrategies([
+  voltroPasswordStrategy(),
+  workosStrategy({ clientId: process.env.WORKOS_CLIENT_ID! }),
+])
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `clientId` | — (**required**) | `client_01H…`. Builds JWKS URL + audience. |
+| `jwksUrl` | `https://api.workos.com/sso/jwks/<clientId>` | Override. |
+| `issuer` | `https://api.workos.com` | Override. |
+| `cookieName` | `'wos-session'` | AuthKit cookie mode; `null` for header-only. |
+| `tenantIdFromClaims` | (uses `org_id`) | Derive `tenantId`; `null` → `failed`. |
+| `defaultTenantId` | (none) | Fallback when claims expose no `org_id`. |
+| `scopesFromClaims` | (none) | Map claims (AuthKit's `permissions[]` / `role`) → `Subject.scopes`. |
+
+The audience is the `clientId`; algorithms are pinned to `['RS256', 'ES256']` (no alg-confusion).
+
+## Environment variables
+
+None read directly — pass `clientId` explicitly (typically from your own `defineEnv`-declared vars).
+
+## Security
+
+Server-only; fails closed — a forged, expired, or wrong-audience token, or one with no resolvable tenant, yields `failed`, never `matched`. JWKS public-key verify only; no WorkOS API key is ever handled.
+
+## Hosted-login primitives (SSO login)
+
+Beyond the verify-only `workosStrategy`, the package exports two primitives for the **hosted-login** flow — WorkOS logs the user in and your app mints its *own* session (an alternate front door alongside password login, not a replacement session authority):
+
+- **`workosAuthorizationUrl({ clientId, redirectUri, state? })`** → the AuthKit login URL to redirect the browser to.
+- **`workosAuthenticateWithCode({ clientId, apiKey, code })`** → exchanges the callback `code` for a `WorkosProfile` (`workosUserId`, `email`, `firstName`, `lastName`, `organizationId`). Server-only (carries the API key).
+
+Both are transport-thin (raw `fetch`, no `@workos-inc/node` dependency). Wire them into a `GET /auth/workos/login` + `GET /auth/workos/callback` route pair, find-or-provision your user in the callback, then `issueSession(...)`. Full worked example: [WorkOS SSO login](/docs/authentication/external-idp#workos-sso-login).
+
+## Passwordless (Magic Auth)
+
+For **passwordless** login — an email one-time code, no password and no browser redirect — the package exports the WorkOS Magic Auth pair:
+
+- **`workosSendMagicAuthCode({ apiKey, email })`** → creates + emails a one-time code to `email`. Server-only (the API key is sent as a Bearer token).
+- **`workosAuthenticateWithMagicAuth({ clientId, apiKey, email, code })`** → verifies the submitted `code` and returns the same `WorkosProfile` as the code exchange.
+
+Wire them into a `POST /auth/passwordless/start` (send the code) + `POST /auth/passwordless/verify` (verify → find-or-provision → `issueSession(...)`) route pair — the same mint-your-own-session model as the hosted-login flow, without the redirect. Both are transport-thin (raw `fetch`).
+
+## See also
+
+- [External identity providers](/docs/authentication/external-idp)
+- [Auth plugin](/docs/plugins/auth)

package/templates/agent-docs/plugins/auth.md

@@ -0,0 +1,227 @@
+# Auth
+
+> Password + session-cookie auth — overview. Full docs in the Authentication section.
+
+
+
+---
+
+<!-- source: en/plugins/auth.md -->
+## Auth
+
+_Password + session-cookie auth — overview. Full docs in the Authentication section._
+
+`@voltro/plugin-auth` ships the full server-side auth suite — password hashing (with rehash-on-verify), HMAC session cookies (multi-key rotation + sliding-window auto-renewal), magic-link + password-reset flows, passkeys/WebAuthn (with atomic clone detection), CSRF, session enumeration + revocation, multi-tenant memberships + switch-tenant, TOTP/MFA with sign-in enforcement + recovery codes — plus React glue (`SubjectProvider`, `useSubject`, `RequireAuth`) and a browser passkey ceremony helper. Identity is a pluggable [strategy](/docs/authentication/strategies) protocol — the password flow is the default, and external IdPs stack on top.
+
+The single `authRoutesPlugin()` mounts **every** auth HTTP route under `/auth` — you don't hand-wire endpoints.
+
+**Status:** ✓ shipped.
+
+This page is a 60-second overview. The dedicated [Authentication section](/docs/authentication/overview) has the depth:
+
+- [Passwords](/docs/authentication/passwords) — scrypt hashing, timing-oracle defence
+- [Sessions](/docs/authentication/sessions) — HMAC-SHA256 signed sessions
+- [The Subject](/docs/authentication/subject) — the typed `ctx.subject` model
+- [Auth strategies](/docs/authentication/strategies) — the `AuthStrategy` protocol + chain
+- [External identity providers](/docs/authentication/external-idp) — WorkOS, Kinde, Clerk, Auth0, Supabase, OIDC
+- [HTTP handlers](/docs/authentication/handlers) — `handleSignIn`, `handleSignUp`, `handleSignOut`
+- [User stores](/docs/authentication/user-stores) — `memoryUserStore`, `postgresUserStore`, custom
+- [React on the web side](/docs/authentication/react) — `SubjectProvider` + hooks
+- [Cookie security](/docs/authentication/cookies) — production checklist
+
+## Quick wire-up
+
+Add `authRoutesPlugin()` to your api's `plugins` array. It mounts the entire auth surface under `/auth` on the same listener the rpc server uses — no hand-wired endpoints. The documented email path forwards magic-link + password-reset mail to `@voltro/plugin-mail` via `mailSender(...)`:
+
+```ts
+// app.config.ts
+import { authRoutesPlugin, postgresUserStore, mailSender } from '@voltro/plugin-auth'
+import { mailPlugin, MailService } from '@voltro/plugin-mail'
+import { bindConnectionSubject } from '@voltro/runtime'
+import { Effect } from 'effect'
+
+// `mail` is the yielded MailService from the mail plugin's services layer.
+const auth = (mail: MailService) =>
+  authRoutesPlugin({
+    store:           postgresUserStore(sql),     // sql: a provided @effect/sql SqlClient
+    secret:          process.env.VOLTRO_SESSION_SECRET!,
+    defaultTenantId: 'public',
+    cookieSecure:    process.env.NODE_ENV === 'production',
+    appBaseUrl:      'https://app.example.com',
+    sendEmail:       mailSender(mail),           // ← plugin-mail synergy (the default wiring)
+    rebind:          bindConnectionSubject,       // ← switch-tenant rebinds the live connection
+    passkey: {
+      rpId:   'example.com',
+      rpName: 'Acme',
+      origin: 'https://app.example.com',
+    },
+  })
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  plugins: [ mailPlugin({ provider: 'resend', from: 'Acme <hi@acme.com>' }) /*, auth(...) */ ],
+}
+```
+
+`sendEmail` is a plain injected hook (`{ to, subject, html, text, kind, actionUrl } => Promise<void>`); `mailSender(mail)` is the first-class adapter that forwards it to `MailService.send`. Omit `sendEmail` and the magic-link / reset routes still mint + persist the token but can't deliver it (they return `202` so account existence never leaks).
+
+```ts
+// app.config.ts — add identity strategies (the built-in password cookie always runs first)
+import { jwtBearerStrategy } from '@voltro/protocol/jwt'
+import { apiKeyStrategy } from '@voltro/protocol/apikey'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  auth: { strategies: [ jwtBearerStrategy({ /* … */ }), apiKeyStrategy({ /* … */ }) ] },
+}
+```
+
+The plugin:
+
+- Mounts every auth route under `/auth` via `authRoutesPlugin()` (also re-exports the underlying Effect-typed handlers — `handleSignIn`, `handleSignUp`, `handleMagicLinkRequest`, `handleSwitchTenant`, … — if you'd rather mount a subset yourself).
+- Resolves `ctx.subject` via `AuthMiddleware` running the strategy chain — the built-in `voltroPasswordStrategy` reads the session cookie.
+- Exposes the typed user store via `postgresUserStore(sql)` (synchronous; the caller owns the `SqlClient`) or `memoryUserStore()` for dev/tests.
+- Contributes the auth tables (`usersTable`, `sessionsTable`, `membershipsTable`, `authTokensTable`, `passkeysTable`) via `authTables`.
+
+## Routes mounted under `/auth`
+
+| Route | Auth | Purpose |
+|---|---|---|
+| `POST /auth/sign-in` · `/sign-up` · `/sign-out` | — | password flow (sign-out also revokes the session row). For an MFA-enrolled user, `sign-in` returns an **mfa-required challenge**, not a session — see below |
+| `POST /auth/mfa/verify` | — | complete the second factor (TOTP or recovery code) with the pending token → issues the real session |
+| `GET  /auth/session` | cookie | session probe: current subject + `renewed` flag; re-issues the cookie when the sliding window (or a key rotation) asks for it |
+| `GET  /auth/csrf` | — | issue a double-submit CSRF token |
+| `POST /auth/magic-link` · `/magic-link/callback` | — | passwordless sign-in |
+| `POST /auth/password-reset` · `/password-reset/confirm` | — | reset flow (confirm revokes all sessions) |
+| `GET  /auth/sessions` · `POST /auth/sessions/revoke` · `/sessions/revoke-others` | cookie | device list + revocation |
+| `GET  /auth/memberships` · `POST /auth/switch-tenant` | cookie | multi-tenant membership + active-tenant switch |
+| `POST /auth/mfa/enroll/start` · `/enroll/verify` · `/unenroll` · `/recovery-codes/regenerate` | cookie | TOTP enrolment (needs `mfa: { issuer }` config); `enroll/verify` returns one-time recovery codes |
+| `POST /auth/passkey/register/options` · `/register/verify` | cookie | passkey enrolment |
+| `POST /auth/passkey/assert/options` · `/assert/verify` | — | passkey sign-in |
+
+State-changing authenticated routes require a valid `x-csrf-token` header matching the `voltro:csrf` cookie.
+
+## Schema
+
+```ts
+import { authTables } from '@voltro/plugin-auth/schema'
+// authTables = [usersTable, sessionsTable, membershipsTable, authTokensTable,
+//               passkeysTable, recoveryCodesTable, passkeyChallengesTable]
+```
+
+Spread `authTables` into your `database/index.ts` handle + `voltro migrate` creates the tables.
+
+## Multi-tenant memberships + switch-tenant
+
+A user belongs to MANY tenants. The Subject carries an active `tenantId` plus its memberships (in `metadata.memberships`, read via `subjectMemberships(subject)`). `POST /auth/switch-tenant` validates the user is a member of the target tenant, re-issues the session cookie with the new active tenant, and — when invoked over the live WebSocket with a `clientId` — rebinds the connection's Subject via `bindConnectionSubject` (the dispatcher re-scopes active subscriptions on rebind).
+
+## MFA / TOTP sign-in enforcement
+
+MFA is a real sign-in gate, not just enrolment. **Enrolment** (`POST /auth/mfa/enroll/*`, needs `mfa: { issuer }` in the plugin config) stores a TOTP secret on the user (`generateTotpSecret` → `otpauthUrl` for the QR); `enroll/verify` confirms the first code, marks the user enrolled, and returns a one-time batch of **recovery codes** (shown once, stored hashed).
+
+**Sign-in enforcement** is automatic for any enrolled user — no config flag:
+
+1. **Challenge, not session.** When an enrolled user posts valid credentials to `POST /auth/sign-in`, the response is `{ ok: true, mfaRequired: true, pendingToken }` — a short-lived (5 min), single-use token whose hash is stored in `authTokens`. **No session cookie is issued.** The pending token is NOT a session; it can only redeem the second factor.
+2. **Verify → session.** The client posts the pending token plus a `code` (6-digit TOTP) — or a `recoveryCode` as the lost-authenticator fallback — to `POST /auth/mfa/verify`. The token is redeemed atomically (single-use, so a guessed code can't be retried against the same challenge), the code is checked against the stored secret (±1 step drift, constant-time compare), and only then is the real session issued — through the same `issueSession` path as password sign-in, so **rotation, sliding-window renewal, and revocation all apply**.
+
+A non-enrolled user still gets a session directly from `sign-in` (unchanged). Recovery codes are single-use; regenerate them with `POST /auth/mfa/recovery-codes/regenerate` (wipes the prior set) and they are wiped on `unenroll`. The TOTP secret is stored plaintext on the user row — put it behind your database's at-rest encryption.
+
+## Passkeys / WebAuthn
+
+Server verification (`verifyRegistration` / `verifyAssertion`, `node:crypto`-only) checks the challenge, origin, rpId hash, and signature, and enforces a strictly-increasing signature counter (clone detection). Attestation is intentionally skipped (the 90% path). The browser ceremony helper lives in the `/web` subpath:
+
+```tsx
+import { registerPasskey, signInWithPasskey, isPasskeySupported } from '@voltro/plugin-auth/web'
+
+if (isPasskeySupported()) {
+  await registerPasskey({ userId, userName }, { csrfToken })   // navigator.credentials.create
+  await signInWithPasskey({ userId })                          // navigator.credentials.get
+}
+```
+
+### Clone detection is atomic
+
+Per the WebAuthn spec, an authenticator's signature counter must strictly increase across assertions; a counter that regresses (or fails to advance) means a cloned credential. The counter bump is a **store-level compare-and-swap** — `advancePasskeyCounter` issues one `UPDATE … WHERE counter < :new RETURNING` statement, so the check and the write are a single atomic operation. Two replicas racing the *same* assertion can't both succeed: exactly one `UPDATE` matches, and the loser (zero rows advanced, counter unchanged) is rejected with `counter_regressed`. The guarantee holds across replicas, not just within one process.
+
+### Multi-replica: bring your own ChallengeStore
+
+A passkey ceremony is two round-trips (`.../options` mints a challenge, `.../verify` redeems it). The default `memoryChallengeStore()` holds challenges in process memory — fine for a **single node**, but on ≥2 replicas the `options` and `verify` requests can land on different nodes and the challenge is missing. For any multi-replica deployment, pass a shared store:
+
+```ts
+import { authRoutesPlugin, dataStoreChallengeStore } from '@voltro/plugin-auth'
+
+authRoutesPlugin({
+  // …store, secret, passkey…
+  challengeStore: dataStoreChallengeStore(sql),  // shared table, survives across replicas
+})
+```
+
+`dataStoreChallengeStore(sql)` persists challenges in the `passkeyChallenges` table (shipped in `authTables`) — single-use (`take` is one `DELETE … RETURNING`, so concurrent verifies can't both redeem) and short-lived (`put` stamps `expiresAt`; an expired row reads as absent). The caller owns the `SqlClient` lifecycle, same contract as `postgresUserStore`.
+
+**BYO contract.** Any `ChallengeStore` you supply implements two Effect-returning methods, keyed by `<userId>:<ceremony>`:
+
+```ts
+interface ChallengeStore {
+  put: (key: string, challenge: string, ttlSeconds: number) => Effect.Effect<void>
+  take: (key: string) => Effect.Effect<string | null>   // read AND delete (single-use); null if absent/expired
+}
+```
+
+`take` **must** delete on read (single-use) and return `null` for an absent, already-taken, or expired key. Back it with any shared, low-latency store (Postgres via `dataStoreChallengeStore`, or a Redis/KV of your own) so all replicas see the same challenges.
+
+## Multi-key session-secret rotation
+
+To rotate without logging everyone out: set the new secret as `VOLTRO_SESSION_SECRET`, move the old one to `VOLTRO_SESSION_SECRET_PREVIOUS` for one max-session-lifetime window, then drop the `_PREVIOUS` var. Every verify path is keyed — the framework's rpc auth chain, the plugin's `/auth/*` routes, and `readSession` — trying `current` first, then `previous`. A cookie that verified under the previous key is re-issued under the current key on the next authenticated `/auth/*` response (`GET /auth/session` triggers this proactively), so live sessions migrate onto the new key during the window. The optional `VOLTRO_SESSION_KID` / `VOLTRO_SESSION_KID_PREVIOUS` vars label the keys (non-secret; default `k0` / `k-previous`). Prefer explicit config over env? `authRoutesPlugin` / `AuthConfig` accept `secrets: { current, previous? }` directly; `resolveSessionSecrets()` (in `@voltro/protocol/session`) is the env reader underneath.
+
+## Sliding-window auto-renewal
+
+Sessions carry an `iat`. `verifySessionKeyed` returns a `renew` flag once the session crosses the renewal threshold (default 70% of its lifetime); authenticated `/auth/*` responses act on it by re-issuing the cookie with its original lifetime (and sliding the `sessions` row's `expiresAt` forward), so an active user never gets logged out mid-session. `GET /auth/session` is the probe a client pings to keep a session sliding — rpc frames over the WebSocket can't set cookies, so renewal is an HTTP-response mechanism.
+
+## Request-time session revocation
+
+Revoking a session (device-list revoke, "sign out other devices", sign-out, or password-reset's revoke-all) actually terminates the live cookie: on every verify, the cookie's `metadata.sessionId` is checked against the `sessions` table through an in-process TTL cache (default **30s**, tune via `authRoutesPlugin({ sessionRevocation: { ttlMs } })`). A kill is instant on the process that performed it (inline cache invalidation) and takes effect within the cache window on other replicas. The plugin carries a pre-wired `auth.sessionStrategy` (same store, same cache) that `voltro dev` / `voltro serve` slot into the rpc auth chain automatically — so WebSocket calls reject a revoked session exactly like the HTTP routes. A cookie minted by hand via `issueSession` (no `sessions` row, no `sessionId`) stays purely stateless and can't be revoked this way.
+
+## Post-authentication subject guards
+
+Every login path (password, MFA, magic-link, passkey) resolves WHO you are, then — right before minting the session cookie — runs the configured **subject guards** against the authenticated `UserRecord`. A guard returns `{ ok: true }` to allow or `{ ok: false, code, message }` to VETO; the first rejection wins, the login returns a **403** carrying the guard's `code` as the body `error`, and **no session is issued**. Sign-up is exempt — it creates a brand-new user no guard could yet reject.
+
+This is a general seam, not tied to any single concern — "account deactivated", "email not verified", "tenant suspended", "must accept new terms" all fit. Pass guards on `subjectGuards`:
+
+```ts
+import { authRoutesPlugin, type SubjectGuard } from '@voltro/plugin-auth'
+import { Effect } from 'effect'
+
+const suspendedTenants = new Set(['tenant-under-review'])
+
+const tenantSuspendedGuard: SubjectGuard = (user) =>
+  Effect.succeed(
+    suspendedTenants.has(user.tenantId)
+      ? { ok: false, code: 'tenant_suspended', message: 'tenant is suspended' }
+      : { ok: true },
+  )
+
+authRoutesPlugin({
+  store,
+  secret: process.env.VOLTRO_SESSION_SECRET!,
+  defaultTenantId: 'acme',
+  subjectGuards: [tenantSuspendedGuard],
+})
+```
+
+The canonical guard ships in `@voltro/plugin-deactivation`: `deactivationGuard()` refuses login when the user's `deactivatedAt` is set — making the `deactivation()` mixin's "a deactivated user can't log in" promise self-enforcing without a hand-rolled resolver check. See [deactivation](/docs/plugins/deactivation#enforcing-a-deactivated-user-cant-log-in). With no guards configured, every authenticated user proceeds exactly as before.
+
+## Rehash-on-verify
+
+`verifyPasswordWithRehash` parses the scrypt cost out of the stored hash; when it's below the current cost, a successful sign-in returns a freshly-minted replacement that `handleSignIn` persists via `UserStore.updatePassword` — passwords strengthen silently on the next login, no forced reset.
+
+## When to use a different auth strategy
+
+`plugin-auth`'s password flow is the default. For specific needs:
+
+- **Existing user base in an IdP** (Okta, Auth0, Clerk, WorkOS, Kinde, Supabase) — add the matching [external IdP strategy](/docs/authentication/external-idp) to the chain. The framework keeps its own `Subject` + `tenantId`.
+- **Any OIDC provider** — `@voltro/plugin-auth-oidc`'s `oidcStrategy`, or `jwtBearerStrategy` from `@voltro/protocol/jwt` directly.
+- **Headless / programmatic callers** — `apiKeyStrategy` from `@voltro/protocol/apikey`.
+
+For 95% of apps, the password flow is the right starting point. The depth lives in the Authentication section.