@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/plugins/ai-flows.md

@@ -41,6 +41,32 @@ import { aiFlowsPlugin } from '@voltro/plugin-ai-flows'
 export default { plugins: [aiFlowsPlugin()] }   // contributes _voltro_ai_flows + _voltro_ai_flow_runs
 ```
 
+Three tunables, all with defaults — set them when the defaults don't match your
+process:
+
+```ts
+// app.config.ts
+import { aiFlowsPlugin } from '@voltro/plugin-ai-flows'
+
+export default {
+  plugins: [
+    aiFlowsPlugin({
+      // How long a `human` step parks before the run fails. Default 7 days;
+      // `0` = wait forever. A flow's `humanTimeoutMs` and a step's own
+      // `timeoutMs` both outrank this.
+      humanReviewTimeoutMs: 14 * 24 * 60 * 60 * 1000,
+      // How long a FINISHED run is kept. Default 90 days.
+      runsTtlMs: 180 * 24 * 60 * 60 * 1000,
+      // Ceiling on rows one `/flows` or `/runs` inspect call returns.
+      inspectPageMax: 200,
+    }),
+  ],
+}
+```
+
+Each also has a deploy-time env override, for an operator who can't edit source:
+`VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` and `VOLTRO_AI_FLOW_RUNS_TTL_HOURS`.
+
 ## Author a flow (code-first)
 
 ```ts
@@ -65,10 +91,39 @@ Each step writes `context[outputKey]`; later steps reference it as `{{outputKey}
 
 - **`agent`** — delegate to a sub-agent (its system prompt + model), text-only.
 - **`generate`** — `text` / `image` / `video` / `audio` via `@voltro/ai`.
-- **`structured`** — a JSON object.
+- **`structured`** — a JSON object, validated against the step's JSON Schema.
 - **`note`** — the interpolated prompt itself is the output (no model call).
 - **`human`** — pause for review (`approve` / `choice` / `text`).
 
+### `structured` — the schema is real
+
+A `structured` step's `schema` is a JSON Schema, and it is **both** what the model
+is told to emit and what the result is validated against:
+
+```ts
+import { flowStep } from '@voltro/plugin-ai-flows'
+
+flowStep.structured({
+  prompt: 'Extract the invoice fields from: {{document}}',
+  outputKey: 'invoice',
+  schema: {
+    type: 'object',
+    required: ['total', 'currency'],
+    properties: {
+      total:    { type: 'number', description: 'Gross total' },
+      currency: { type: 'string', enum: ['EUR', 'USD'] },
+      lines:    { type: 'array', items: { type: 'string' } },
+    },
+  },
+})
+```
+
+Objects (with `required`), arrays, the four scalars, `enum`, `const`, both
+nullability spellings and `anyOf` / `oneOf` unions are modelled;
+`description` / `title` ride along as annotations. A construct the adapter does
+not model (`$ref`, `allOf`, …) degrades to "unknown" for **that node** rather
+than failing the step, and a step with no `schema` behaves as it always did.
+
 ## Human-in-the-loop
 
 A `human` step sets the run to `waiting` and **parks the workflow without holding
@@ -76,6 +131,40 @@ a worker** (the durable suspend). The user answers via `respondToFlow`; a reject
 ends the run cancelled, otherwise the answer lands in `context` and the run
 resumes. Thousands of runs can wait on review for days at no runtime cost.
 
+**Several reviews in one flow are independent.** Each human step parks on its own
+durable signal, derived from that step's position in the plan the run's journal
+pinned at step 0 — so the identity is the same on every replay, and answering the
+first review cannot resolve the second. `respondToFlow` reads the parked step off
+the run row's live timeline and addresses that step, which is why the UI never
+has to track a step index; it returns the `stepIndex` it answered.
+
+### The park is bounded, and the bound is yours
+
+An approval left over a weekend used to fail the whole flow: the park inherited
+`@voltro/workflow`'s 24-hour default, which no flow author chose or could change.
+It resolves most-specific-first now — **step → flow → plugin option → env →
+7 days** — and `0` at any level means *wait forever* (the park is slot-free, so
+an unbounded wait costs no worker):
+
+```ts
+import { defineFlow, flowStep } from '@voltro/plugin-ai-flows'
+
+defineFlow({
+  name: 'contract-review',
+  // Flow-wide default for every human step that sets none.
+  humanTimeoutMs: 30 * 24 * 60 * 60 * 1000,
+  steps: [
+    flowStep.human({ reviewMode: 'approve', prompt: 'Legal sign-off?' }),
+    // This one is the CFO's, and it waits as long as it takes.
+    flowStep.human({ reviewMode: 'approve', prompt: 'Budget sign-off?', timeoutMs: 0 }),
+  ],
+})
+```
+
+A flow authored as DATA carries the same setting in `_voltro_ai_flows.humanTimeoutMs`.
+When the bound does expire, the run row is written `status: 'failed'` naming the
+bound that elapsed — it no longer dies with the row still reading `waiting`.
+
 ## Chaining & cadence
 
 - **`chainTo`** launches a follow-up flow on success (result ⊕ input → the child's
@@ -90,6 +179,58 @@ resumes. Thousands of runs can wait on review for days at no runtime cost.
 `costMicroUsd`, …) as it runs, and the client's subscription streams the timeline
 over CDC — no polling, no sockets.
 
+## Driving a flow from the UI
+
+`@voltro/plugin-ai-flows/web` is the browser-safe half: launch → observe →
+respond, without hand-rolling a subscription.
+
+```tsx
+import { useFlowReview, useLaunchFlow } from '@voltro/plugin-ai-flows/web'
+
+export function ArticleFlow({ runId }: { runId?: string }) {
+  const { launch, pending } = useLaunchFlow()
+  const { steps, status, awaitingReview, prompt, approve, reject, done } = useFlowReview(runId)
+
+  if (runId === undefined) {
+    return (
+      <button disabled={pending} onClick={() => launch({ flowRef: 'blog-article', input: { topic: 'Effect' } })}>
+        Start
+      </button>
+    )
+  }
+  return (
+    <div>
+      <ol>{steps.map((s) => <li key={s.id}>{s.title ?? s.type} — {s.status}</li>)}</ol>
+      {awaitingReview && (
+        <div>
+          <p>{prompt}</p>
+          <button onClick={() => approve(runId)}>Approve</button>
+          <button onClick={() => reject(runId)}>Reject</button>
+        </div>
+      )}
+      {done && <p>Finished: {status}</p>}
+    </div>
+  )
+}
+```
+
+The full set: `useLaunchFlow`, `useFlowRun` (the reactive run row projected into
+a timeline — steps, status, the pending review, `done`), `useFlowRuns`,
+`useFlows`, `useRetryFlow`, `useCancelFlow`, `useRespondToFlow`
+(`approve` / `reject` / `choose` / `submitText`) and `useFlowReview`, which is
+the whole review widget in one call.
+
+**Every hook takes the tag set.** This plugin ships no fixed RPC routes — its
+procedures are helpers you wire into your own thin rpc files (below) — so the
+hooks default to `aiFlows.launch` / `.run` / `.respond` / … and accept an
+override plus an `apiName`:
+
+```tsx
+import { useFlowRun } from '@voltro/plugin-ai-flows/web'
+
+const run = useFlowRun(runId, { apiName: 'admin', tags: { run: 'flows.oneRun' } })
+```
+
 ## Wiring (once per app)
 
 The engine runs as one durable workflow; the operations are server helpers (a
@@ -138,8 +279,26 @@ Adopt `@voltro/plugin-versioning` on `_voltro_ai_flows` for automatic edit histo
   planner), so a mid-run crash re-plans (`retry` = fresh run).
 - **Cadence + scale-to-zero**: `dormancy: 'sleep'` won't fire an in-process tick —
   use an external waker or `trigger: 'external'`.
+- **Run retention**: `_voltro_ai_flow_runs` is bounded by the framework sweep at
+  **90 days** (`runsTtlMs` / `VOLTRO_AI_FLOW_RUNS_TTL_HOURS`). Only **terminal**
+  runs are swept (`succeeded | failed | cancelled`) — a run parked on a human
+  review is live state, not history, and a plain time-TTL would delete pending
+  approvals. `_voltro_ai_flows` (the DEFINITIONS) is deliberately unbounded: its
+  size tracks how many flows a team writes, not traffic.
+
+  **Upgrading a live app:** the first sweep runs ~30 s after boot and deletes
+  every terminal run older than the TTL, in batches, until the backlog drains. An
+  app that has been running flows for more than 90 days loses that history at
+  once — set the env var (or `runsTtlMs`) BEFORE deploying if you need it. An
+  app's own `registerRetention` for the table also outranks the plugin's.
 - **Media retention**: not automatic — add a `*.cron.tsx` deleting old artifacts
-  via `storage.delete(id)` (a plain retention sweep would orphan the blobs).
+  via `storage.delete(id)` (a plain retention sweep would orphan the blobs). Note
+  this interacts with the run TTL: a run's steps carry hosted URLs whose blobs
+  belong to the storage plugin, so deleting the row orphans them. Keep the run
+  TTL at or above your media-purge window, or purge by run id first.
+- **Inspect page size**: `/flows` and `/runs` take a `?take=`, clamped by
+  `inspectPageMax` (default 200). It matters here more than usual — a run row
+  carries every step's full text output.
 - **Media tenant on resume**: `generateMedia` receives `run.tenantId`, read from
   the durable run row. Pin persistence to it (as above) rather than the caller
   subject — a resumed run executes under a tenant-less system subject, so reading

package/templates/agent-docs/plugins/analytics-postgres.md

@@ -53,7 +53,7 @@ plugin's `_voltro_events` table is auto-merged into your schema, so
 | Option | Type | Default | Notes |
 |---|---|---|---|
 | `sqlClient` | `SqlClient.SqlClient` | the main DataStore's client | Override to land events in a SEPARATE database (e.g. a dedicated analytics Postgres while the app runs MySQL). You must create the events table there yourself. |
-| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `_voltro_mirror_<table>` (`{ id, data }`) so analytical queries can JOIN events against live user data. |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `_voltro_mirror_<table>` (`{ id, data, version, is_deleted }`) so analytical queries can JOIN events against live user data. Deletes write a tombstone — filter `is_deleted = false`. |
 | `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
 
 ```ts

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

@@ -73,7 +73,7 @@ auditPlugin({
 // custom function: (event: AuditEvent) => void | Promise<void> | Effect.Effect<void>
 ```
 
-`'datastore'` is the production sink: it survives restarts, is shared across replicas, and is queryable via `ctx.store.select('_voltro_audit_log')`. Each row carries the flattened `tag` / `at` / `subjectId` / `tenantId` / `traceId` / `status` / `durationMs` (indexed by `tag` + `traceId`) plus the full `subject` / `input` / `outcome` as portable `json()` columns.
+`'datastore'` is the production sink: it survives restarts, is shared across replicas, and is queryable via `ctx.store.select('_voltro_audit_log')`. Each row carries the flattened `tag` / `at` / `subjectId` / `tenantId` / `traceId` / `status` / `durationMs` (indexed by `tag` + `traceId`) plus the full `subject` / `input` / `outcome` as portable `json()` columns, plus the `chainId` / `seq` / `prevHash` / `hash` tamper-evidence columns (see [the hash chain](#tamper-evidence--the-hash-chain)).
 
 The custom function is the escape hatch for persisting events anywhere the built-in table's schema doesn't fit — e.g. an `Effect.Effect<void>` sink that writes rows into your own audit table on top of `@effect/sql`. All return shapes are normalised by the interceptor. A sink that throws / rejects / dies is caught and swallowed, so a broken sink can never mask the mutation's real outcome.
 
@@ -176,6 +176,42 @@ const denied = await auditBySubject(ctx.store, actorId, { status: 'error', limit
 
 `auditBySubject` takes `status` as a real argument rather than leaving you to filter in JS: the index is `(subjectId, status, at)`, so a filter applied after fetching would not use it.
 
+### Tamper-evidence — the hash chain
+
+Append-only is a convention, not a guarantee. An actor with `UPDATE` on the database could rewrite what a call did, or `DELETE` the row that recorded a refusal, and no read of the table would notice — an audit trail whose integrity rests on "nobody has database access" is exactly as trustworthy as the thing it exists to check.
+
+Every row written by `sink: 'datastore'` therefore carries its position in a hash chain: `chainId`, `seq`, `prevHash` and `hash`, where `hash` covers the row's own content **and** the previous row's hash. Altering any row invalidates every row after it; removing one leaves a hole.
+
+```ts
+import { verifyAuditChain } from '@voltro/plugin-audit'
+
+const verdict = await verifyAuditChain(ctx.store)
+// { ok, rowsChecked, unchainedRows, keyed, chains: [{ chainId, from, to, tip, prunedPrefix }], issues: [...] }
+```
+
+`issues` names what does not add up, and the kinds are not interchangeable:
+
+| Kind | Meaning |
+|---|---|
+| `tampered` | The row's content does not hash to its stored `hash`. A column was altered. |
+| `broken-link` | The row's `prevHash` is not the previous row's `hash`. Reordering, or a row substituted for another. |
+| `gap` | `seq` jumped. A row was deleted, or its write failed. |
+
+A gap at the **start** of a chain is not an issue — the retention sweep prunes oldest-first, so a pruned prefix is reported as `prunedPrefix: true`. Rows written before chaining shipped carry no `hash` at all and are counted as `unchainedRows` rather than passed over silently.
+
+#### The chain is per WRITER, and that is the concurrency answer
+
+One global chain would need every insert to know the current tip — a serialization point across every process writing audit rows. Two replicas racing on one chain **fork**, and a fork is indistinguishable from tampering. A chain that breaks under normal operation is worse than no chain at all, because the first false positive is what teaches everyone to ignore the verifier. A per-tenant chain has the identical problem one level down.
+
+So each process mints its own `chainId` at boot and allocates `seq`/`prevHash`/`hash` in a synchronous, `await`-free step — atomic against any number of concurrent events. What you get in exchange is stated plainly: N replicas produce N chains, so verification attests *"every chain is intact"*, not *"the log is complete"*.
+
+#### Read the guarantee before you quote it
+
+Unkeyed (the default), the chain detects any change that does **not** recompute it: a hand-run `UPDATE`, a botched migration, storage corruption, a script that scrubs one row. It does **not** stop an adversary who knows the scheme and rewrites the chain forward — SHA-256 is public, so with write access they can. Two things close that, both available:
+
+- **`VOLTRO_AUDIT_CHAIN_SECRET`** — set it and the chain is HMAC-SHA256. An actor with the database but not the key cannot forge a link. There is no default value and nothing is minted for you; keep the key where the database is not.
+- **Anchor the tips.** `verifyAuditChain` returns each chain's `tip`. Publish it on a schedule to somewhere append-only you do not control (an object-lock bucket, a log shipper, a compliance mailbox). This is also the *only* defence against tail truncation — deleting the newest N rows of a chain is undetectable from the table alone, for any hash chain.
+
 ### Retention, and the GDPR interaction
 
 `sink: 'datastore'` registers its own retention: **365 days by default**, tunable with `VOLTRO_AUDIT_LOG_TTL_HOURS`, drained by the boot sweep. An append-only trail with no ceiling is the one that eventually takes the database down.

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

@@ -0,0 +1,143 @@
+# Social login (Google / GitHub / Apple)
+
+> First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor.
+
+
+
+---
+
+<!-- source: en/plugins/auth-social.md -->
+## Social login (Google / GitHub / Apple)
+
+_First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor._
+
+`@voltro/plugin-auth-social` is "Sign in with Google" without adopting an identity vendor. The six sibling `@voltro/plugin-auth-*` adapters are enterprise-IdP **token verifiers** — they check a JWT an IdP already issued. This one runs the whole login: it builds the authorize URL, redeems the authorization code, verifies what came back, decides what the identity means for your `users` table, and issues the **same** session cookie password sign-in issues.
+
+Three providers ship: **Google**, **GitHub** and **Apple**.
+
+## Install
+
+```
+pnpm add @voltro/plugin-auth-social
+```
+
+## Wiring
+
+```ts
+// app.config.ts
+import { authRoutesPlugin, postgresUserStore } from '@voltro/plugin-auth'
+import { socialAuthPlugin } from '@voltro/plugin-auth-social'
+
+const auth = {
+  defaultTenantId: 'public',
+  appBaseUrl: 'https://app.example.com',
+}
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  plugins: [
+    authRoutesPlugin({ store: users, ...auth }),
+    socialAuthPlugin({
+      providers: { google: {}, github: {} },
+      users,
+      auth,
+    }),
+  ],
+}
+```
+
+An empty `{}` for a provider means "take the credentials from the environment". Then link to the start route:
+
+```tsx
+<a href="/auth/social/google">Sign in with Google</a>
+<a href="/auth/social/github">Sign in with GitHub</a>
+```
+
+Two routes are mounted per provider, under `/auth/social` by default:
+
+| Route | What it does |
+|---|---|
+| `GET /auth/social/<provider>` | Mints `state` + a PKCE verifier + an OIDC nonce, stores them in a short-lived `HttpOnly` cookie, redirects to the provider |
+| `GET` or `POST /auth/social/<provider>/callback` | Verifies `state`, redeems the code, verifies the ID token, applies the link policy, issues the session cookie |
+
+The session is issued by `issueUserSession` from `@voltro/plugin-auth` — the same function password sign-in, magic-link, MFA and passkeys use. So a social login gets the `sessions` row (device list + server-side revocation), keyed-secret rotation, sliding-window renewal and the membership-carrying Subject automatically.
+
+## Credentials
+
+Nothing is ever defaulted. A missing credential fails the boot; it never falls back.
+
+| Provider | Environment |
+|---|---|
+| Google | `VOLTRO_GOOGLE_CLIENT_ID`, `VOLTRO_GOOGLE_CLIENT_SECRET` |
+| GitHub | `VOLTRO_GITHUB_CLIENT_ID`, `VOLTRO_GITHUB_CLIENT_SECRET` |
+| Apple | `VOLTRO_APPLE_CLIENT_ID`, `VOLTRO_APPLE_TEAM_ID`, `VOLTRO_APPLE_KEY_ID`, `VOLTRO_APPLE_PRIVATE_KEY` |
+
+Register `<appBaseUrl>/auth/social/<provider>/callback` as the redirect URI with each provider, byte for byte.
+
+## Account linking — read this before shipping
+
+The security decision at the heart of social login is one sentence: *Google says the person in front of you owns `ada@example.com`, and your `users` table already has a row for `ada@example.com`. Do you log them into it?*
+
+Answering "yes, the emails match" is the classic pre-authentication account-takeover vector. A provider that does not verify an address lets an attacker register the victim's email, never confirm it, click "Sign in with X" and land inside the victim's account. So there are two policies, and the default is the strict one:
+
+| `linkPolicy` | Behaviour |
+|---|---|
+| `'never'` (default) | A social identity never attaches to a pre-existing account. Unknown email ⇒ a new user. Known email ⇒ refused, with a message telling the user to sign in the way they already can and connect the provider from account settings |
+| `'verified-email'` | Links when the provider **asserted** the address is verified and it is not an Apple private relay. A real, bounded risk, taken deliberately |
+
+There is deliberately no policy that links on an *unverified* email.
+
+The linking that is always sound is not a policy at all: attaching a provider to an account whose **session you already hold**. Call `linkSocialIdentity` from an authenticated route — the proof of ownership is the session, which is the only proof that is actually sound. That is the escape hatch every app on `'never'` needs.
+
+```ts
+import { linkSocialIdentity, socialCompleteLogin } from '@voltro/plugin-auth-social'
+
+// inside an authenticated route, after socialCompleteLogin returned a profile
+yield* linkSocialIdentity(identities, subject.id, {
+  provider: profile.provider,
+  providerAccountId: profile.providerAccountId,
+  email: profile.email,
+  emailVerified: profile.emailVerified,
+})
+```
+
+## What is verified, and what is not
+
+- **`state` is mandatory and is never caller-supplied.** It is compared in constant time *before anything leaves the process* — a forged callback never reaches a token endpoint.
+- **PKCE (S256) rides on every provider**, including GitHub, whose OAuth app flow ignores it. The parameter is unconditional so a future provider cannot silently land on the no-PKCE path.
+- **ID tokens are verified against the provider's JWKS** — signature (ES256/RS256 only; HMAC algorithms are rejected), `iss`, `aud`, `exp`/`iat` — through the same verifier every IdP adapter here uses, plus a `nonce` check that makes an ID token from another login fail.
+- **GitHub has nothing signed to verify.** Identity comes from `GET /user` plus `GET /user/emails`, and only the entry that is both `primary` and `verified` is trusted. The self-declared profile email is never used.
+
+## Apple: three things that break naive implementations
+
+1. **The name arrives exactly once.** Apple returns it in no token — it posts a `user` form field on the *first* authorization and never again. The profile flags this as `nameIsFirstAuthorizationOnly`; persist it then or lose it.
+2. **The client secret is a JWT you sign yourself** (ES256, from a `.p8` key, capped at six months). This plugin does not store one at all: it mints a 15-minute secret per exchange, so there is nothing to rotate and nothing to expire in production half a year later. A TTL above Apple's cap is rejected at call time.
+3. **The email may be a per-app private relay** (`…@privaterelay.appleid.com`, flagged by `is_private_email`). It is verified but it is not the user's address, so linking on it is refused even under `'verified-email'`.
+
+One more Apple-specific trap: requesting the `name`/`email` scopes makes Apple **POST the callback cross-site**, and a `SameSite=Lax` cookie is not sent on a cross-site POST. The plugin writes the login-state cookie `SameSite=None; Secure` for Apple, which means **Apple needs HTTPS even in development**.
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `providers` | — | Which providers to offer; `{}` takes credentials from the environment |
+| `users` | — | The same `UserStore` `authRoutesPlugin` runs on |
+| `auth` | — | The same `AuthConfig`: session secret, cookie flags, default tenant, subject guards |
+| `identities` | DataStore-backed | Where identities are recorded |
+| `linkPolicy` | `'never'` | See above |
+| `prefix` | `/auth/social` | Route prefix |
+| `appBaseUrl` | `auth.appBaseUrl` | Origin the default redirect URIs are built from |
+| `successRedirect` | `auth.successRedirect` ?? `/` | Where to send the browser after a login |
+| `failureRedirect` | — | When set, a refusal redirects with `?social_error=<code>` instead of answering JSON |
+| `stateTtlSeconds` | `600` | How long a started login may take to come back |
+| `stateCookieName` | `voltro:oauth` | Name of the login-state cookie |
+
+## Schema
+
+The plugin contributes `_voltro_oauth_identities` (one row per user per provider account, unique on `[provider, providerAccountId]`) via `extendSchema`. It rides the declarative differ — `voltro db apply` and a `voltro dev` boot both reconcile it, on every dialect. It is deliberately **not** swept by retention: these rows *are* the credential, and a TTL that deleted them would silently un-enrol users.
+
+## Post-authentication guards
+
+`auth.subjectGuards` run here exactly as on every other login path, so an account blocked by `@voltro/plugin-deactivation` cannot get in through the newest door. Sign-*up* is exempt — a brand-new user no guard could yet have an opinion about.

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

@@ -85,8 +85,10 @@ Server-only; fails closed — a forged, expired, or wrong-audience token, or one
 
 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).
+- **`workosBeginLogin({ clientId, redirectUri })`** → `{ url, state, codeVerifier }`. The AuthKit login URL always carries a minted CSRF `state` **and** a PKCE `code_challenge` (S256); stash the other two for the callback.
+- **`workosAuthenticateWithCode({ clientId, apiKey, code, state, expectedState, codeVerifier })`** → verifies the state in constant time (throwing `WorkosStateMismatchError` on a mismatch, before any network call), then exchanges the callback `code` for a `WorkosProfile` (`workosUserId`, `email`, `firstName`, `lastName`, `organizationId`). Server-only (carries the API key).
+
+Neither `state` nor PKCE is optional: `state` used to be a parameter you could pass, so the default flow had no CSRF token, and the exchange verified nothing. The check now lives inside the only function that can redeem a code — a generated `state` that nothing verifies is worse than none.
 
 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).
 

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

@@ -11,7 +11,7 @@
 
 _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.
+`@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, email verification, tenant invitations, user impersonation, 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.
 
@@ -37,7 +37,7 @@ Add `authRoutesPlugin()` to your api's `plugins` array. It mounts the entire aut
 // app.config.ts
 import { authRoutesPlugin, postgresUserStore, mailSender } from '@voltro/plugin-auth'
 import { mailPlugin, MailService } from '@voltro/plugin-mail'
-import { bindConnectionSubject } from '@voltro/runtime'
+import { bindConnectionCredential } from '@voltro/runtime'
 import { Effect } from 'effect'
 
 // `mail` is the yielded MailService from the mail plugin's services layer.
@@ -49,7 +49,7 @@ const auth = (mail: MailService) =>
     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
+    rebind:          bindConnectionCredential,    // ← switch-tenant presents the new cookie on the live connection
     passkey: {
       rpId:   'example.com',
       rpName: 'Acme',
@@ -83,7 +83,7 @@ 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`.
+- Contributes the auth tables (`usersTable`, `sessionsTable`, `membershipsTable`, `authTokensTable`, `passkeysTable`, `invitationsTable`, `impersonationGrantsTable`, …) via `authTables`.
 
 ## Routes mounted under `/auth`
 
@@ -97,25 +97,150 @@ The plugin:
 | `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/verify-email` · `/verify-email/callback` | — | request/resend a confirmation link (uniform `202`); redeem one (issues **no** session) |
+| `POST /auth/invitations` · `GET /auth/invitations` · `POST /auth/invitations/revoke` | cookie | create / list / withdraw tenant invitations (needs `invitations` config) |
+| `POST /auth/invitations/preview` · `/invitations/accept` · `/invitations/sign-up` | — / cookie | inspect a token, redeem it as the signed-in user, or redeem it by creating the invited account |
+| `POST /auth/impersonate/start` · `/impersonate/stop` | cookie | act as another user and end it (needs `impersonation` config) |
 | `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.
 
+While a session is **impersonated**, the account-security routes are refused with `403 forbidden_while_impersonating` — see [User impersonation](#user-impersonation-log-in-as).
+
 ## Schema
 
 ```ts
 import { authTables } from '@voltro/plugin-auth/schema'
 // authTables = [usersTable, sessionsTable, membershipsTable, authTokensTable,
-//               passkeysTable, recoveryCodesTable, passkeyChallengesTable]
+//               passkeysTable, recoveryCodesTable, passkeyChallengesTable,
+//               loginAttemptsTable, invitationsTable, impersonationGrantsTable]
 ```
 
 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).
+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` — **presents that same cookie on the connection** via `bindConnectionCredential`.
+
+It presents a CREDENTIAL, not a Subject, and that is the whole design. The rebound connection is resolved by the full auth chain on its next call — session revocation, `auth.resolveScopes`, the scope cache, the credential-expiry bound — exactly as a reconnecting browser would be. It used to hand the middleware a resolved Subject, which the middleware returned verbatim: the connection then kept that authority for its whole life, immune to a revocation performed anywhere else. (And it only worked under `voltro dev`; `voltro serve` had no such path at all, so the rebind silently did nothing in production.)
+
+What a rebind does NOT do: re-scope subscriptions already open on that connection. They were authorized under the previous cookie and run until the client re-subscribes. Calls made after the rebind see the new tenant.
+
+## Email verification
+
+`users` carries a nullable `emailVerifiedAt`, and `POST /auth/verify-email` + `/verify-email/callback` mint, send and redeem a confirmation link over the same single-use hashed-token table the magic-link and reset flows use.
+
+**What an unverified account may do is a product decision, so it is a config field with three values** rather than a behaviour the framework picks for every app:
+
+```ts
+authRoutesPlugin({
+  // …store, secret, defaultTenantId, sendEmail…
+  emailVerification: {
+    policy: 'strict',                                    // 'off' (default) · 'soft' · 'strict'
+    exemptAccountsCreatedBefore: new Date('2026-08-11'),  // your deploy instant
+  },
+})
+```
+
+| policy | login | the session |
+|---|---|---|
+| `'off'` (default) | proceeds | carries **no** mark |
+| `'soft'` | proceeds | marked — `isEmailVerified(subject)` is `false` |
+| `'strict'` | refused, `403 email_not_verified` | never issued |
+
+**Why `'off'` is the default.** The column arrives `NULL` on every existing row. Under `'strict'` as a default, the first boot after upgrading would refuse the next login of every user you already have — a total authentication outage caused by missing data rather than by anything a user did. `exemptAccountsCreatedBefore` is the adoption seam: accounts created before that instant count as verified, so you can turn `'strict'` on without a backfill.
+
+**`isEmailVerified(subject)` is tri-state, and `null` is not `false`.** A session minted while the policy was `'off'` says nothing about verification. Reading "no mark" as "unverified" would refuse every live session at the moment you switch the policy on — the same outage one layer up. Gate on `=== false`.
+
+**Three links prove an address, not one.** A magic link and a completed password reset are inbox round-trips exactly as a verification link is, so both stamp `emailVerifiedAt` (keeping the first timestamp — the column answers "since when", not "last clicked"). Without that, `'strict'` deadlocks a magic-link-only user: they can prove their address by signing in, and are refused the sign-in for not having proved it.
+
+**A verification link is not a credential.** Redeeming one marks the address and issues **no** session. Treating it as a sign-in would turn a link that sits 24 hours in a mailbox — and in every relay along the way — into a day-long credential.
+
+`'strict'` is enforced through the [subject-guard seam](#post-authentication-subject-guards), so it covers password, MFA verify, magic-link and passkey sign-in from one wiring. `authRoutesPlugin` installs the guard when you set the policy; if you mount the handlers yourself, add `emailVerificationGuard(config)` to `subjectGuards` — setting the policy alone changes only what the session is *marked* with.
+
+The request endpoint answers a uniform `202` (unknown address, already-verified address and cooled-down resend are indistinguishable) and sends at most one mail per `resendCooldownSeconds` (default 60). Without that bound, "resend" is a mail-bomb primitive aimed at any address known to have an account.
+
+## Tenant invitations
+
+`invitations` joins `authTables`, and six routes mount when you pass an `invitations` config:
+
+```ts
+authRoutesPlugin({
+  // …store, secret, defaultTenantId, sendEmail, appBaseUrl…
+  invitations: {
+    ttlSeconds: 7 * 24 * 60 * 60,          // default
+    inviterRoles: ['owner', 'admin'],      // default
+    roleRank: ['owner', 'admin', 'member', 'viewer'],  // default, most privileged first
+    maxPending: 500,                       // default
+  },
+})
+```
+
+**An invitation is a credential that grants access to someone else's data**, so it gets the token discipline of one — 32 CSPRNG bytes, only the SHA-256 stored, single-use via one conditional `UPDATE … RETURNING`, an expiry — plus three properties a login token has no need for:
+
+- **It is addressed.** The invited address is compared against the accepting user's; a mismatch is `403 invitation_email_mismatch`. A link forwarded, leaked into a channel or intercepted is refused rather than silently granting whoever opens it first.
+- **It carries its own authority, chosen by the inviter.** The accept request is `{ token }` and nothing else — there is no field an invitee could use to name their own role.
+- **It is revocable**, tenant-scoped in the SQL predicate, so an admin of one tenant cannot withdraw another's by id.
+
+**An inviter can never grant a role above their own.** That direction is not configurable: an `admin` who can mint an `owner` invitation and accept it from a second address has promoted themselves, which makes every role boundary in the product advisory. `canGrantRole` replaces the whole rule for a model that is not a line (a matrix, a per-tenant plan) — keep it a refusal by default. A role the ranking does not know is grantable only by the top role; treating an unfamiliar `superadmin` as probably-harmless is how it gets handed out by an `admin`.
+
+Both "the invitee already has an account" cases are covered. Signed in as the invited address, `POST /auth/invitations/accept` writes the membership. Signed out with no account, `POST /auth/invitations/sign-up` creates one — with the address taken from the **invitation**, never from the request, and marked already verified, since the invitation arrived in that mailbox and came back. An existing address is answered `409 account_exists` and the invitation is not burned.
+
+Re-inviting **supersedes**: every pending invitation for the same (tenant, address) is revoked before the new one is issued, so a resend cannot leave live tokens behind. `maxPending` bounds a tenant so a compromised admin account is not a mail cannon. The admin list never returns `tokenHash` — a hash verifies a guessed plaintext offline, and an admin list is not a place to publish a verifier.
+
+`invitations` is registered with the retention sweep at 90 days (`VOLTRO_INVITATIONS_TTL_HOURS`), armed only when the feature is configured.
+
+## User impersonation ("log in as")
+
+An impersonated session that is indistinguishable from a real one does not merely lack a feature — it retroactively destroys the audit trail of the whole product. Every row an agent touches is attributed to the user, so afterwards nobody can answer *"did the customer delete this, or did we?"* — including for the incident where it matters. Everything below follows from that.
+
+```ts
+import { authRoutesPlugin, impersonationAuditRedactor } from '@voltro/plugin-auth'
+import { auditPlugin } from '@voltro/plugin-audit'
+import { Effect } from 'effect'
+
+authRoutesPlugin({
+  // …store, secret, defaultTenantId…
+  impersonation: {
+    // REQUIRED. A function, never a role — see below.
+    authority: ({ actorUser }) => Effect.succeed(supportAgentIds.has(actorUser.id)),
+    // REQUIRED. Fires for 'started', 'stopped' AND 'refused'.
+    audit: (event) => { void recordSupportEvent(event) },
+    maxDurationSeconds: 900,   // default — 15 minutes
+    requireReason: true,       // default
+  },
+})
+
+// So the mark reaches the durable audit trail too — read the note below.
+auditPlugin({ sink: 'datastore', redactSubject: impersonationAuditRedactor() })
+```
+
+**`authority` is a function, never a role, and has no default.** Two separate reasons. "A role that happens to be admin-ish" is how this becomes a privilege-escalation path in a product where `admin` means "can edit the pricing page". And mechanically: the subject these routes resolve comes from the session cookie, which [carries identity only](/docs/authentication/sessions#the-cookie-carries-identity-never-authority) — it has no `scopes` at all, so a scope-based default would be unsatisfiable by every caller, i.e. a feature that refuses everyone.
+
+**`audit` is required** because impersonation's whole risk is an unrecorded action. A config that let you enable it while leaving the destination unset would make the dangerous half optional and the safe half opt-in.
+
+**The mark lives in two places with different failure modes.** `subject.metadata.impersonation` travels with the cookie and reaches the client, so a banner needs no extra endpoint (`impersonationOf(subject)` reads it). An `impersonationGrants` **row** is written *before* the session exists — so a session can never be reachable without the record naming who is behind it — and no redaction policy can drop it.
+
+> **Wire `impersonationAuditRedactor()` or your audit rows will not say who was behind an impersonated action.** `auditPlugin`'s default is `redactSubject: 'metadata'`, which replaces the whole metadata bag — correct in general (that bag is where a per-user provider credential lands) and it takes this mark with it. The redactor keeps the mark and redacts everything else: strictly safer than `'none'`, strictly more informative than the default.
+
+**Time-bounded means the cookie expires**, not that a row says it should. The grant duration is the cookie's `Max-Age`, the session row's `expiresAt` and the grant's `expiresAt`, minted from one number. A caller may request *less*; a request for more is clamped, never obeyed.
+
+**Stopping** closes the grant, deletes the impersonated session row and drops it from the revocation cache — so a copy of that cookie taken during the grant dies immediately, not at its own expiry — then re-issues the impersonator's own, never-revoked session for its **remaining** lifetime. Restoring does not extend their login. An actor whose own session died meanwhile is signed out rather than left as somebody else.
+
+**Four escalation refusals:**
+
+| refusal | what it stops |
+|---|---|
+| `self_impersonation` | acting as yourself — every action marked impersonated with no second identity behind it, i.e. noise in the field an investigator reads |
+| `nested_impersonation` | A→B, then as B→C. The mark carries one actor, so a chain attributes C's session to B — reaching any account with a **forged** attribution |
+| `target_may_impersonate` | acting as someone who can themselves impersonate. The probe is `authority` evaluated with the identities **swapped** ("could the target impersonate me?"), so there is no second policy to keep in step |
+| `forbidden_while_impersonating` | MFA enrolment/removal, recovery-code regeneration, passkey registration, switch-tenant, revoke-other-sessions, and starting another impersonation. Without this a 15-minute grant converts to permanent access in one request: enrol a passkey as the user and the time bound is decoration |
+
+The impersonator also gains no authority the target lacks, by construction: the cookie **is** the target's identity, carries no scopes, and authority is re-resolved per request from that identity. Being impersonated does not clear the target's brute-force lockout either — a support action must not undo the protection on the account someone is hammering.
+
+`impersonationGrants` is registered with the retention sweep at 365 days (`VOLTRO_IMPERSONATION_GRANTS_TTL_HOURS`) — matching the audit log, because it answers the same class of question — armed only when the feature is configured.
 
 ## MFA / TOTP sign-in enforcement