@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/authentication.md

@@ -95,7 +95,7 @@ import { hashPassword } from '@voltro/plugin-auth'
 import { Effect } from 'effect'
 
 const hash = await Effect.runPromise(hashPassword('correct horse battery staple'))
-// → 'scrypt$16384$8$1$<saltB64>$<derivedB64>'
+// → 'scrypt$32768$8$1$<saltB64>$<derivedB64>'
 ```
 
 Store `hash` in the `passwordHash` column of your users table. **Never** store the plaintext.
@@ -133,11 +133,29 @@ The framework uses scrypt with these defaults:
 
 | Param | Value | Effect |
 |---|---|---|
-| `N` | `2^14` = 16384 | CPU + memory cost |
+| `N` | `2^15` = 32768 | CPU + memory cost |
 | `r` | 8 | block size |
 | `p` | 1 | parallelism |
 
-At those parameters a single hash takes roughly ~50ms on a modern laptop — slow enough to make offline brute force expensive, fast enough that sign-in feels instant. The cost is roughly equivalent to bcrypt's `$2y$10$`. The parameters are encoded inline in the hash string (`scrypt$16384$8$1$…`), so a future cost bump can decode older hashes and re-encode on the next sign-in.
+Measured — node v26.3.0, Apple M2 Pro, median of 5 runs at `r=8 p=1 keyLen=32`. Memory is `128 · N · r`, held for the whole derivation:
+
+| `N` | time | memory |
+|---|---|---|
+| `2^14` | 39 ms | 16 MiB |
+| **`2^15`** (this) | **73 ms** | **32 MiB** |
+| `2^16` | 156 ms | 64 MiB |
+| `2^17` (OWASP's floor) | 271 ms | 128 MiB |
+
+### Why not OWASP's `2^17`
+
+Every row of that table is a cost **your server** pays, per attempt, on an endpoint an anonymous caller controls. Two facts decide it:
+
+- The brute-force lockout that is on by default is keyed by **email** — deliberately, so an unknown address locks exactly like a real one and the lock is not an existence oracle. An attacker who rotates the email field is therefore not rate-limited, and every attempt buys a full derivation. General per-IP rate limiting is opt-in ([`@voltro/plugin-ratelimit`](/docs/plugins/ratelimit)).
+- The common deployment target is a small container. At 0.25 vCPU, `2^17` is over a second of CPU and 128 MiB **per anonymous attempt** — one laptop can hold that box down, and ten concurrent logins is an OOM.
+
+Availability is part of security, so the ceiling here is set by what an anonymous caller can make the server spend, not by the offline-cracking table alone. Put a per-IP limiter in front of `/auth` and raising `N` becomes cheap.
+
+The parameters are encoded inline in the hash string (`scrypt$32768$8$1$…`), so a cost bump decodes older hashes and re-encodes them on the next sign-in — see [Rehash-on-verify](/docs/plugins/auth). Hashes minted at `2^14` keep verifying; nothing to migrate.
 
 For high-throughput service-to-service flows that need many auths per second, use API keys instead — `apiKeyStrategy` from `@voltro/protocol/apikey`. Passwords are for humans.
 
@@ -227,13 +245,40 @@ voltro:session=<base64url(payload)>.<base64url(signature)>
 
 Where:
 
-- `payload` is JSON `{ subject, exp, iat, kid? }` — the **whole** typed `Subject` round-trips inside the cookie, e.g. `{ "subject": { "type": "user", "id": "user-id", "tenantId": "tenant-id" }, "exp": 1736294400, "iat": 1735689600 }`. The subject's own `id` is the identity; `iat` drives the sliding-window renewal below; `kid` is the (non-secret) label of the signing key, stamped when signing with a keyed secret set.
+- `payload` is JSON `{ v, subject, exp, iat, kid? }`, e.g. `{ "v": 2, "subject": { "type": "user", "id": "user-id", "tenantId": "tenant-id" }, "exp": 1736294400, "iat": 1735689600 }`. `v` is the payload format version; `iat` drives the sliding-window renewal below; `kid` is the (non-secret) label of the signing key, stamped when signing with a keyed secret set.
 - `signature` is HMAC-SHA256(payload, AUTH_SECRET)
 
 **Why HMAC, not JWT?**
 
 JWTs come with the `alg: 'none'` attack and a long history of header confusion. The framework's format is intentionally simpler: HMAC-SHA256, fixed algorithm, no header.
 
+## The cookie carries identity, never authority
+
+`subject` in the payload is a **`SubjectIdentity`** — the `Subject` union with `scopes` omitted at the schema level. A session cookie says *who* the caller is. What they may *do* is resolved on every request by [`auth.resolveScopes`](/docs/authentication/strategies).
+
+This is not a style choice, it is the whole lifetime argument. Identity is settled once at sign-in and never changes. Authority changes the moment an admin removes a role — and a value signed into a 7-day cookie is frozen for 7 days, longer if the sliding renewal keeps re-signing it. Embedding scopes meant that narrowing someone's role had no effect on the session they already held: you could sign them out entirely, but you could not take one permission away.
+
+Two consequences to know:
+
+- **`issueSession` / `signSession` throw** when handed a subject that carries `scopes`. They do not strip them. A silently dropped scope is an authorization change with no error, no log line and no diff — you find it later, as "permissions randomly stopped working".
+- **`readSession` / `verifySession` return a `SubjectIdentity`.** The absent field is the guarantee: nothing downstream can read authority out of a cookie, because the value it gets back has nowhere to keep it.
+
+If you build a Subject yourself at login — a custom sign-in route, an SSO `onLogin` — mint the session from the identity and move the permissions into the resolver:
+
+```ts
+// before: authority frozen into the cookie for a week
+issueSession({ ...identity, scopes: permissionsFor(user) }, secret)
+
+// after: identity in the cookie, authority resolved per request
+issueSession(identity, secret)
+```
+
+### Payload versioning — what happens to live sessions
+
+`v` is required and pinned to the version this build mints. A payload without it, or with an older one, **fails to decode** — it does not fall back to a lenient read. A cookie from the previous format asserts authority, and honouring that assertion is exactly the defect being removed; authenticating someone under a contract the server no longer holds is worse than asking them to sign in.
+
+So a framework upgrade that bumps the payload version ends every live session. Plan it like a secret rotation: users see the sign-in screen once. Their `sessions` rows are untouched.
+
 ## Issuing
 
 ```ts
@@ -241,7 +286,7 @@ import { issueSession } from '@voltro/plugin-auth'
 
 // Positional args: (subject, secret, options?). Returns { value, setCookie }.
 const { value, setCookie } = issueSession(
-  subject,                            // a full Subject, e.g. subjectFromUser(user)
+  subject,                            // an identity, e.g. subjectFromUser(user) — no scopes
   AUTH_CONFIG.secret,
   {
     ttlSeconds: 60 * 60 * 24 * 7,     // 7 days (default if omitted)
@@ -262,7 +307,7 @@ res.setHeader('set-cookie', setCookie)
 import { readSession } from '@voltro/plugin-auth'
 
 const subject = readSession(req.headers.cookie, AUTH_CONFIG.secret)
-// → { type: 'user', id, tenantId } | null
+// → { type: 'user', id, tenantId } | null   — a SubjectIdentity: no `scopes`
 ```
 
 Returns `null` for:
@@ -270,6 +315,7 @@ Returns `null` for:
 - Missing cookie
 - Tampered payload (signature mismatch)
 - Expired session (`exp < now`)
+- A payload from a superseded format version (see above)
 
 ## Clearing
 
@@ -304,6 +350,8 @@ For centralised revocation, the plugin writes a `sessions` row on every sign-in
 
 Revocation is enforced **at request time**: on every verify, the cookie's server-side session id (`metadata.sessionId`) is checked against the `sessions` table through a small in-process TTL cache (default **30 seconds**, tune via the plugin's `sessionRevocation.ttlMs`). Be honest about the window: a revocation is instant on the process that performed it (its cache entry is invalidated inline — sign-out kills the cookie immediately there) and takes effect within the cache window on every other replica. `POST /auth/sign-out` deletes the caller's session row, and a password-reset confirm revokes **all** of the user's sessions — in both cases a retained copy of the cookie stops authenticating within that window, days before its `exp`. The framework's rpc auth chain enforces the same check: `authRoutesPlugin` carries a pre-wired session strategy (sharing the same cache) that `voltro dev` / `voltro serve` slot into the chain automatically. One deliberate gap: a cookie minted by hand via `issueSession` without a `sessions` row carries no `sessionId` and stays purely stateless.
 
+**Revoking a session and revoking a permission are two different operations, and both now take effect on a live session.** This section is the first: kill the row and the holder is signed out. The second is [`auth.resolveScopes`](/docs/authentication/strategies) — narrow the role and the caller keeps their session but loses the permission. The two windows are deliberately the same 30 seconds and both invalidate to zero the same way, so there is one number to reason about rather than a second one you discover later.
+
 ## When to use a longer / shorter lifetime
 
 | Use case | Lifetime |
@@ -322,9 +370,9 @@ Sliding-window auto-renewal ships: the session payload carries an `iat`, and `ve
 // 1. Parse cookie → { payloadB64, sigB64 }
 // 2. Compute expected = hmacSha256(payloadB64, secret)
 // 3. Constant-time compare expected vs. sigB64
-// 4. Decode payload
+// 4. Decode payload (rejects a superseded payload version)
 // 5. Check exp (reject if exp < now)
-// 6. Return the decoded Subject
+// 6. Return the decoded SubjectIdentity
 ```
 
 All steps use constant-time comparisons to defeat timing attacks. Implementation lives in `@voltro/plugin-auth/session.ts` — read it for the full story.
@@ -674,21 +722,26 @@ Order matters: put the cheapest / most-common strategy first. When no strategy m
 
 If your authorization is a database ROLE rather than a scope on the token, the framework cannot see it. `voltro check`'s `rbac/unguarded-mutation` reports every such write as unguarded — correctly, because nothing about the decision is declared — and the declarative alternative is unusable for you: subjects that come from an external IdP carry no scopes, so `requireScope('employee:admin')` would lock out every real user. One app measured 1566 findings it had no way to act on.
 
-`resolveScopes` closes that. It runs after a strategy matches and adds scopes to the resolved Subject from whatever source you like:
+`resolveScopes` closes that. It runs after a strategy matches, on every request, and resolves the caller's authority from whatever source you like:
 
 ```ts
 // app.config.ts
 export default defineApiConfig({
   auth: {
     resolveScopes: async (subject, { store }) => {
-      if (store === undefined) return []            // still booting — claim nothing
-      const role = await roleCache.get(subject.id, store)   // cache it — see below
-      return role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read']
+      if (store === undefined) return { kind: 'unavailable', reason: 'store not ready' }
+      const role = await readRole(store, subject.id)
+      return {
+        kind: 'authoritative',
+        scopes: role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read'],
+      }
     },
   },
 })
 ```
 
+**For a cookie-authenticated caller this is not a supplement — it is the only place authority comes from.** The session cookie carries a [`SubjectIdentity`](/docs/authentication/sessions) with no `scopes` field, so the strategy establishes nothing to add to. An app that gates on scopes and wires no resolver has callers with no scopes, which is the fail-closed direction.
+
 The same authorization is now declarable on the descriptor:
 
 ```ts
@@ -699,16 +752,86 @@ export const payrollList = defineQuery({
 })
 ```
 
-**You get the app's DataStore.** A role lives in the database, and without it the only way to reach one was a second connection path beside the framework's — to the same database the request store opens a moment later. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists, so it is `undefined` while the store is still being built. Return `[]` then rather than guessing.
+### Three answers, and picking the right one is the point
+
+| Return | Meaning | Effect |
+|---|---|---|
+| `['a', 'b']` — a bare array | **grant** (the shorthand; identical to `{ kind: 'grant', scopes }`) | unioned onto whatever the strategy established |
+| `{ kind: 'authoritative', scopes }` | this resolver is the **complete** answer | replaces — anything not listed is removed |
+| `{ kind: 'unavailable', reason }` | the authority source could not be reached | the request fails closed with `Unauthenticated`, and `reason` reaches `onStrategyFailed` |
+
+An already-written resolver returning an array keeps its exact meaning, with no compiler error suggesting otherwise.
 
-**Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface. The returned scopes are UNIONED with whatever the strategy already set, so a resolver can grant authority but never revoke it.
+**Why this is three tags and not a boolean.** The hook used to be union-only, on the reasoning that a resolver which can silently subtract is a resolver whose bad day is indistinguishable from a policy decision — a DB blip that returns no rows would read as "this user has no permissions" and be applied as such. That hazard is real. But union-only also made narrowing impossible: removing a permission from a role had no effect on anyone already signed in, because the only hook that could have observed it was structurally forbidden from removing anything.
+
+The empty array is what forced the split. Under a grant shape `[]` has to mean "no extra scopes"; under a replace shape it has to mean "no scopes at all"; and a failed lookup produces it under both. Three meanings, one value — so each got its own tag, and none of them is what you get by accident. **Return `unavailable`, not `[]`, when a lookup fails.**
+
+**You get the app's DataStore.** A role lives in the database, and without it the only way to reach one was a second connection path beside the framework's — to the same database the request store opens a moment later. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists, so it is `undefined` while the store is still being built. Return `{ kind: 'unavailable', … }` then rather than guessing — under the old contract `[]` was the safe answer there, and it no longer is.
+
+**Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface.
 
 **It does not run for anonymous callers** — there is no identity to look a role up for.
 
-**Cache it yourself.** It is on the request path. A `Map` keyed by subject id with a short TTL is usually enough. The framework deliberately does not cache for you, because only you know how quickly a role change has to take effect.
+### It also answers for durable workflows — read `ctx.origin` first
+
+A workflow's start context persists the caller's **identity**, never their scopes: a `json()` column read back by another cluster runner days later is authority frozen and made durable, which is the session cookie's old defect one layer down. So a resumed run asks this resolver what its caller may do, on every execution attempt:
+
+```ts
+resolveScopes: async (subject, ctx) => {
+  if (ctx.origin === 'workflow') return rolesFromDb(subject, ctx.store)
+  return rolesFromHeader(ctx.headers)   // the request path, unchanged
+}
+```
+
+`ctx.origin` is `'request' | 'workflow'`. For `'workflow'` there **is** no request: `ctx.headers` is `{}` and `ctx.clientId` is `undefined` (its type is `number | undefined`, which is where a resolver reading it sees the compile error). Empty rather than fabricated — a resolver that needs headers has to be able to branch instead of silently receiving a bag that is always empty.
+
+Three consequences worth stating plainly:
+
+- **An app that wires no resolver gets workflow runs with no scopes.** Fail-closed, and the same default a cookie-authenticated request already has.
+- **`{ kind: 'unavailable' }` fails the execution attempt**, rather than downgrading it. A run that quietly skips the branch it was not allowed to take is indistinguishable from one whose business logic said no. Fix the source and `voltro workflows redrive`.
+- **A run with no recorded caller at all** — a bootstrap, or one whose start-context row aged out — runs as the framework's `SYSTEM_SUBJECT` and is *not* put through your resolver. It already states its own authority, and it carries `tenantId: null`, which the tenant scope reads as "every tenant". That is why the framework does not promote a *caller-owned* workflow to it: that would trade frozen authority for cross-tenant visibility.
+
+`scopeCache` applies to the request path only. One resolution per run attempt is not a hot path, and a run that lasts days must not inherit a window sized for a burst of requests.
+
+**Narrowing is audited.** `auth.onScopesNarrowed` is called whenever an authoritative resolution removed scopes the strategy had established, with `{ strategyId, subjectType, subjectId, removed, granted }`. It fires on a fresh resolution rather than on a cache replay, so a narrowed caller logs once per window instead of once per request.
 
 Wired identically under `voltro dev` and `voltro serve`.
 
+## The staleness window, and how to make it zero
+
+The framework caches the resolution for you. The window is `auth.scopeCache`, and its default is **30 seconds** — deliberately the same window the [session-revocation check](/docs/authentication/sessions) already used, so the two per-request store reads miss together and there is *one* number to reason about rather than a second one you discover later.
+
+That number is the lag between "an admin removes a role" and "every replica enforces it". Three ways to shorten it:
+
+```ts
+// app.config.ts
+import { makeScopeCache, scopeCacheKey } from '@voltro/protocol'
+
+// 1. Keep the default: a role change lands within 30s, everywhere. Nothing to write.
+
+// 2. Resolve on every request. Staleness zero, one store read per request.
+export default defineApiConfig({
+  auth: { resolveScopes, scopeCache: { ttlMs: 0 } },
+})
+
+// 3. Keep the cache AND get zero where it matters: hold the handle and drop the
+//    entry from whatever changes a role.
+export const scopeCache = makeScopeCache({ ttlMs: 30_000 })
+export default defineApiConfig({
+  auth: { resolveScopes, scopeCache },
+})
+
+// …in the mutation that grants or removes a role:
+scopeCache.invalidate(scopeCacheKey(subject))   // instant on this process, ttlMs elsewhere
+scopeCache.invalidateAll()                      // when a ROLE's definition changed, not one membership
+```
+
+`VOLTRO_AUTH_SCOPE_CACHE_TTL_MS` overrides the default per deployment; an explicit `ttlMs` in code wins over the variable. Set `scopeCache: false` when your resolver reads anything beyond the subject's identity (a header, a request path) — the cache key is `type + tenantId + id` and nothing else, so a resolver that varies on something outside that key must not be cached.
+
+`tenantId` is in the key on purpose: a user keeps their `id` across a tenant switch and their authority does not.
+
+**The honest cost.** This is one extra store read per subject per window, on a path that was already doing one of exactly this shape for session revocation. An `unavailable` verdict is never cached — caching it would stretch one blip into a window of denials and hide the recovery.
+
 ## Wiring it into the app
 
 The composed resolver becomes the runtime's `AuthMiddleware` — the per-request middleware that populates `SubjectService` so every handler can `yield* SubjectService` (or read `ctx.subject`). On a single-strategy password app you never touch this; the plugin wires `voltroPasswordStrategy` for you. You only assemble the chain explicitly when you add a second strategy:
@@ -723,7 +846,11 @@ export const AuthLayer = Layer.succeed(
 )
 ```
 
-The runtime injects a connection-override fast-path *ahead* of the chain so a soft re-auth (`auth.signin` rebinding the WebSocket's subject after a credential check) is honoured without re-running strategies. That's why `AuthStrategyInput` carries `clientId`.
+Nothing runs *ahead* of the chain. A soft re-auth — `auth.signin` over the live WebSocket, a tenant switch — calls `bindConnectionCredential(clientId, { cookies })` from `@voltro/runtime`, which patches the connection's headers; the chain then runs on those headers exactly as it would for a fresh request. That's why `AuthStrategyInput` carries `clientId`.
+
+This used to be a fast path that returned a stored `Subject` and skipped the chain, and the cost was everything downstream of the strategy: session revocation (it lives inside the strategy), `resolveScopes`, the scope cache, and the credential-expiry bound — for the whole life of the connection, with a 24-hour idle sweep as the only backstop. Patching the credential means a rebound connection has no property a reconnecting one lacks, because it is the same code path.
+
+If you have no credential to present, that is the finding rather than a limitation: a caller that cannot authenticate a fresh request was holding authority no request could obtain.
 
 ## The built-in: `voltroPasswordStrategy`
 
@@ -826,6 +953,8 @@ Voltro ships first-party [strategy](/docs/authentication/strategies) plugins for
 | `@voltro/plugin-auth-supabase` | Supabase Auth (GoTrue) | `supabase` |
 | `@voltro/plugin-auth-oidc` | Generic OIDC (Okta, Keycloak, Cognito, Azure AD, Google Workspace, …) | configurable via `id:` |
 
+> **Looking for "Sign in with Google"?** That is a different plugin. Everything on this page is a *verifier* — it checks a JWT an enterprise IdP already issued. For consumer social login (Google / GitHub / Apple) where Voltro runs the whole redirect flow and mints your own session, use [`@voltro/plugin-auth-social`](/docs/plugins/auth-social). No identity vendor required.
+
 Every plugin is a thin wrapper — ~70–110 lines each — over one shared engine: **`jwtBearerStrategy`**. They add nothing but provider-specific defaults (JWKS URL, cookie name, tenant-claim mapping). If your IdP isn't in the list AND doesn't expose a standard OIDC discovery document, point `jwtBearerStrategy` at its JWKS endpoint directly.
 
 ## The model: verify, don't redirect
@@ -911,21 +1040,25 @@ Tenant maps from `claims.org_id`. Verified claims arrive as `subject.metadata.cl
 
 The strategy above is the *verify* model — WorkOS' JWT is the session. `@voltro/plugin-auth-workos` also exports two primitives for the **other** model, where WorkOS runs the login and your app mints its **own** session — an alternate front door *alongside* password sign-in, not a replacement session authority. This is how **Voltro Cloud** offers a "Sign in with WorkOS SSO" button next to email/password.
 
-- **`workosAuthorizationUrl({ clientId, redirectUri, state? })`** — builds the WorkOS hosted-login (AuthKit) URL to redirect the browser to. Pass a random `state` for CSRF defence (and to carry a post-login return path).
-- **`workosAuthenticateWithCode({ clientId, apiKey, code })`** — exchanges the `?code=` from the callback for the authenticated `WorkosProfile` (`workosUserId`, `email`, `firstName`, `lastName`, `organizationId`). **Server-only** — it carries the WorkOS **API key** (the OAuth client secret).
+- **`workosBeginLogin({ clientId, redirectUri })`** — returns `{ url, state, codeVerifier }`. `url` is the WorkOS hosted-login (AuthKit) URL to redirect the browser to; it always carries a freshly-minted CSRF `state` and a PKCE `code_challenge` (S256). Stash `state` and `codeVerifier` — the callback needs both.
+- **`workosAuthenticateWithCode({ clientId, apiKey, code, state, expectedState, codeVerifier })`** — verifies the state in constant time, then exchanges the `?code=` from the callback for the authenticated `WorkosProfile` (`workosUserId`, `email`, `firstName`, `lastName`, `organizationId`). **Server-only** — it carries the WorkOS **API key** (the OAuth client secret).
 
 Both are transport-thin (raw `fetch`, no `@workos-inc/node` dependency), so they drop into any app's own routing + provisioning.
 
+> **`state` and PKCE are not optional, and the check is not yours to remember.** `state` used to be a parameter you could pass — which meant the default flow had no CSRF token at all. Without it, an attacker who gets a victim's browser to hit your callback with an authorization code *they* obtained logs the victim into the **attacker's** account. It is now minted for you on every call, and the state comparison lives *inside* `workosAuthenticateWithCode`: a generated `state` that nothing verifies is worse than none, because a code review and a screenshot of the authorize URL then both read as "CSRF is handled". PKCE (S256) rides along for the same reason — the authorization code travels through the address bar and the referrer chain, and without a verifier whoever captures it can redeem it first.
+
 ### The flow
 
 ```text
 GET /auth/workos/login
-   ─► set a random `state` cookie (CSRF defence)
-   ─► 302 → workosAuthorizationUrl({ clientId, redirectUri, state })
+   ─► const { url, state, codeVerifier } = workosBeginLogin({ clientId, redirectUri })
+   ─► stash BOTH in short-lived HttpOnly cookies (CSRF nonce + PKCE verifier)
+   ─► 302 → url
 
 GET /auth/workos/callback?code=…&state=…
-   ─► verify `state` matches the cookie   (else 400 — possible CSRF)
-   ─► workosAuthenticateWithCode({ clientId, apiKey, code }) → WorkosProfile
+   ─► workosAuthenticateWithCode({ clientId, apiKey, code,
+        state, expectedState: <cookie>, codeVerifier: <cookie> })
+        → WorkosProfile   (throws WorkosStateMismatchError → 400 on a mismatch)
    ─► find-or-provision the local user + org   (SHARED with password signup)
    ─► issueSession(subject) → Set-Cookie: voltro:session=…
    ─► 302 → dashboard
@@ -938,9 +1071,8 @@ The callback mints the **same** `voltro:session` as password sign-in, so everyth
 Wrap the two routes in a small **server-only** plugin and add it to `plugins` in your api's `app.config`:
 
 ```ts
-import { randomUUID } from 'node:crypto'
 import { definePlugin } from '@voltro/protocol'
-import { workosAuthorizationUrl, workosAuthenticateWithCode } from '@voltro/plugin-auth-workos'
+import { workosBeginLogin, workosAuthenticateWithCode, WorkosStateMismatchError } from '@voltro/plugin-auth-workos'
 import { issueSession, resolveSessionSecret } from '@voltro/plugin-auth/session'
 
 export const workosAuthPlugin = () =>
@@ -956,11 +1088,20 @@ export const workosAuthPlugin = () =>
           if (!clientId || !redirectUri) {
             return { status: 503, contentType: 'text/plain', body: 'WorkOS SSO is not configured.' }
           }
-          const state = randomUUID()
-          const url = workosAuthorizationUrl({ clientId, redirectUri, state })
+          const { url, state, codeVerifier } = workosBeginLogin({ clientId, redirectUri })
+          // SameSite=Lax, not Strict: the return from WorkOS is a top-level GET,
+          // which Lax allows and Strict would drop — and a dropped cookie now
+          // FAILS the login instead of silently skipping the check.
+          const attrs = 'Path=/; Max-Age=600; HttpOnly; SameSite=Lax'
           return {
             status: 302,
-            headers: { location: url, 'set-cookie': `workos-oauth-state=${state}; Path=/; Max-Age=600; SameSite=Lax` },
+            headers: {
+              location: url,
+              'set-cookie': [
+                `workos-oauth-state=${state}; ${attrs}`,
+                `workos-oauth-verifier=${codeVerifier}; ${attrs}`,
+              ].join('\n'),
+            },
             body: '',
           }
         },
@@ -974,10 +1115,24 @@ export const workosAuthPlugin = () =>
           if (!clientId || !apiKey) {
             return { status: 503, contentType: 'text/plain', body: 'WorkOS SSO is not configured.' }
           }
-          const code = new URLSearchParams(req.query).get('code')
+          const params = new URLSearchParams(req.query)
+          const code = params.get('code')
           if (!code) return { status: 400, contentType: 'text/plain', body: 'Missing authorization code.' }
-          // …also validate `state` against the state cookie (CSRF) before exchanging.
-          const profile = await workosAuthenticateWithCode({ clientId, apiKey, code })
+          let profile
+          try {
+            profile = await workosAuthenticateWithCode({
+              clientId, apiKey, code,
+              state:         params.get('state') ?? '',
+              expectedState: readCookie(req.headers['cookie'], 'workos-oauth-state') ?? '',
+              codeVerifier:  readCookie(req.headers['cookie'], 'workos-oauth-verifier') ?? '',
+            })
+          } catch (err) {
+            // Distinct from "WorkOS said no" — worth alerting on separately.
+            if (err instanceof WorkosStateMismatchError) {
+              return { status: 400, contentType: 'text/plain', body: 'Invalid or missing OAuth state (possible CSRF).' }
+            }
+            return { status: 502, contentType: 'text/plain', body: 'WorkOS code exchange failed.' }
+          }
           // find-or-provision runs the SAME path as password signup:
           const { userId, orgId } = await findOrProvisionUser(profile)
           const issued = issueSession({ type: 'user', id: userId, tenantId: orgId }, resolveSessionSecret())
@@ -995,6 +1150,8 @@ export const workosAuthPlugin = () =>
   })
 ```
 
+Do **not** keep a hand-rolled `state !== cookieState` check beside this — two expressions of one rule, and the copy is the one that goes stale.
+
 The **first** SSO login provisions the local user + org (the same routine password signup uses); later logins find the existing user by email. That's why the routes live in *your app*, not in the plugin — the provisioning and session model are yours; the plugin only supplies the reusable OAuth primitives. Match the `voltro:session` cookie's attributes (e.g. `Secure`, `HttpOnly`) to your app's existing session cookie.
 
 ### Configuration
@@ -1738,7 +1895,9 @@ const TenantSwitcher = () => {
 }
 ```
 
-`POST /auth/switch-tenant` validates membership server-side, re-issues the session cookie with the new active tenant, and — over the live WebSocket — rebinds the connection's Subject so active subscriptions re-scope to the new tenant without a reconnect. No re-auth.
+`POST /auth/switch-tenant` validates membership server-side, re-issues the session cookie with the new active tenant, and — over the live WebSocket — presents that cookie on the connection, so calls made afterwards resolve against the new tenant without a reconnect. No re-auth.
+
+Calls, not subscriptions: a subscription already open on that connection was authorized under the previous cookie and keeps running until the client re-subscribes. Re-mount the subscribing components (or reload) if the switch has to change what they show.
 
 ## Anti-patterns
 
@@ -2001,6 +2160,99 @@ A subscription is a long-lived grant. Its guards — scope and relationship alik
 — are re-evaluated before each delivery, so revoking a relation mid-session ends
 the stream with the typed error instead of continuing to push rows.
 
+## Every procedure decides — `guards:` or `openAccess:`
+
+A procedure that declares neither is **refused at boot**. `guards:` used to
+default to "allowed", so a discovered `*.query.ts` / `*.mutation.ts` /
+`*.action.ts` / `*.stream.ts` with no guard was callable by **any authenticated
+session** — the door defaulted open, and nothing said so.
+
+The same rule covers **events**: a `*.event.ts` declaration is a wire surface
+too, and one that declares neither `guards:` nor `openAccess:` was silently
+subscribable by anyone who could open the socket. `defineEvent` takes the same
+two answers — see [Events](/docs/data/events).
+
+There are exactly two answers, and they are not the same claim:
+
+```ts
+export const invoiceList = defineQuery({
+  name: 'invoices.list',
+  guards: [{ scope: 'invoices:read' }],      // the caller must hold a scope
+  …
+})
+
+export const pricing = defineQuery({
+  name: 'pricing.current',
+  openAccess: 'public pricing page — reads no caller data',   // anyone may call it, and why
+  …
+})
+```
+
+`openAccess` takes a **reason, not a boolean**. That is the point of it: the
+reason is what a reviewer reads later, and it is what makes *"we decided this is
+open"* distinguishable from *"nobody looked"*. Without such a marker, the only
+way to satisfy a default-deny gate is to add a guard — so every genuinely open
+endpoint grows a scope every caller already holds. That rubber stamp reads as
+protection and enforces nothing, which is a worse state than the hole it
+replaces.
+
+A procedure that only other **server** code calls wants neither: mark it
+`internal: true` and it leaves the wire entirely (no client-group entry, no
+route). `openAccess` on an internal procedure is refused — there is no wire
+surface to make a decision about.
+
+### The gate
+
+`voltro dev` and `voltro serve` run the same check at boot, and `voltro doctor`
+runs it as a preflight (non-zero exit; `accessDecisions` in `--json`). The
+refusal names **every** offending procedure with its file, because the fix is one
+pass over the whole list:
+
+```
+[access] 3 wire-exposed procedures or events declare no access decision, and
+this app runs with `security.defaultDeny`:
+
+    invoices.list  (query)
+      src/api/invoices.query.ts
+    …
+```
+
+`voltro doctor` is the fastest way to get the list without a failed boot.
+
+### Turning it off
+
+One field, in `app.config.ts`, for the whole app:
+
+```ts
+export default defineApiConfig({
+  security: { defaultDeny: false },
+})
+```
+
+There is deliberately **no environment variable** for this. The only direction
+anyone reaches for is off, and an env var is how a security default becomes
+permanently off in one CI job with no diff to review. `voltro doctor` keeps
+listing the undecided procedures while it is off, marked advisory.
+
+### What it does NOT cover — and what covers the rest
+
+The **boot** gate reads **your app's own** discovered procedures and events. The
+procedures a plugin declares are the plugin author's decision and are not judged
+at boot — adopting this does not turn into a bug report against a plugin you
+installed.
+
+They are not unpoliced, though: the same `security.defaultDeny` is also enforced
+**per request in the dispatch spine**, as defense in depth. A descriptor that
+reaches the wire with no access decision — a plugin route, a hand-bound
+descriptor — is refused with the same typed `ScopeError` before the transaction
+opens or any external I/O runs. Every first-party plugin route declares its own
+decision (a scope where a real authority exists — e.g. `billing:manage`,
+`storage:browse` — or `openAccess` with the reason on the routes that are
+self-scoped or anonymous-capable by design; each plugin's page lists them). A
+third-party plugin that declares neither on a route will see that route refused
+per-request under default-deny — the fix is one field on the route, exactly as
+for your own procedures.
+
 ## Decide — `can` / `assertCan`
 
 `can(subject, action, resource, { policy, tuples })` is the decision; `assertCan`
@@ -2252,6 +2504,36 @@ error frame, rather than delivering an empty snapshot — an empty snapshot on a
 live subscription reads to a client as "every row you could see was just
 deleted". Make sure your subscription error handling surfaces it.
 
+## A path that cannot apply the filter refuses, rather than serving rows
+
+If a filter is registered and a scoped store is built without a resolved scope,
+the store **throws**. It does not fall back to unfiltered reads.
+
+That fallback used to exist, and it is the reason this section does. A team
+measured four read paths returning every row of the tenant to every employee,
+on both transports, with `row filter registered` in the boot log and a green
+test suite. The registration lived in a module-local variable, so an app's
+`*.startup.tsx` and the framework's request pipeline could hold two different
+copies of it — the serve bundle inlines the framework while app modules stay
+external, and a strict pnpm tree can resolve one version into two directories.
+The pipeline read "no filter registered", which was indistinguishable from an
+app that has none, and served everything.
+
+The registration is process-global for real now (`globalThis`, so every copy
+shares one cell), and the ambiguity that made the failure silent is gone: those
+two readings are different claims and only one of them is a decision.
+
+If a code path is deliberately unfiltered — a system sweep, a migration, a
+seeding helper in a test — say so:
+
+```ts
+wrapStoreWithMixinBehaviour(store, { subject, schemaRegistry, rowFilter: NO_ROW_FILTER })
+```
+
+`runAsSystem`, change-stream subscribers and the webhook trigger context already
+do this; a system subject bypasses row filters by design, and it is now written
+down rather than inferred from an absence.
+
 ## What does *not* bypass it
 
 | | Bypasses the row filter? |

package/templates/agent-docs/caching.md

@@ -276,6 +276,7 @@ Add a `cache` field to a `defineQuery` and the framework caches the query's **se
 export const listTodos = defineQuery({
   name:   'todos.listByTenant',
   source: 'todos',
+  guards: [{ scope: 'todos:read' }],                     // who may call it
   input:  Schema.Struct({ done: Schema.optional(Schema.Boolean) }),
   output: Todo,
   cache:  { ttl: '30s', swr: '5m', scope: 'subject' },   // tenant-filtered → subject
@@ -299,6 +300,8 @@ The matching `.<primitive>.server.ts` is **unchanged** — caching is a descript
 export const listCountries = defineQuery({
   name:   'reference.countries',
   source: 'countries',
+  openAccess: 'a static country reference list — the same rows for every caller, '
+    + 'no tenant rows and nothing caller-derived',
   input:  Schema.Void,
   output: Country,
   cache:  { ttl: '1h', scope: 'global' },
@@ -308,12 +311,15 @@ export const listCountries = defineQuery({
 export const last12Months = defineQuery({
   name:   'globalStatistics.last12Months',
   source: ['invoices', 'employees'],
+  guards: [{ scope: 'analytics:read' }],
   input:  Schema.Struct({}),
   output: Stats,
   cache:  { ttl: '5m', scope: 'tenant' },
 })
 ```
 
+**`cache.scope` and the access decision are two questions, and they line up here by coincidence rather than by rule.** Every wire-exposed query must also declare `guards:`, `openAccess: '<reason>'` or `internal: true` or the boot refuses it — and the reasoning that made `scope: 'global'` correct for `reference.countries` (the same rows for everyone, nothing caller-derived) is the same reasoning that makes `openAccess` honest there. It does not generalise: a query can be perfectly cacheable per subject *and* need a scope to call, which is `todos.listByTenant` above. Decide them separately; see [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 `'tenant'` exists because the other two were the only options and neither fit an org-wide figure: `'subject'` recomputes it per person — eighteen identical computations of the same nine-table statistic for an eighteen-person org — and `'global'` shares one entry across tenant boundaries, which for data derived from `subject.tenantId` is not a cache but a leak.
 
 A caller with no `tenantId` (an anonymous or system subject) **bypasses** a `'tenant'` cache rather than sharing a null-keyed entry.