@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/plugins/sso-saml.md

@@ -55,6 +55,14 @@ SLO works in **both directions**. A `LogoutRequest` must reference the IdP `Name
 - **SP-initiated** (`GET /saml/logout`) — loads the stored NameID/SessionIndex, builds the (signed) `LogoutRequest`, clears the session cookie, and redirects to the IdP SLO endpoint.
 - **IdP-initiated** (`GET|POST /saml/slo`) — the IdP's signed `LogoutRequest` clears the SP session and is answered with a `LogoutResponse`; a bad signature is rejected (`401`) and the session is left intact.
 
+  An SLO message with **no signature at all** is rejected `401` before the SAML
+  library is consulted. This is not a formality: the underlying verifier treats
+  an absent redirect-binding signature as "nothing to verify" and returns
+  valid, and `/saml/slo` is a `GET` that is deliberately CSRF-exempt — so an
+  unsigned message would let any page log a visitor out with an `<img>` tag.
+  **If your IdP does not sign SLO, it now gets a 401**; enable message signing
+  on the IdP side.
+
 The SLO state store mirrors the replay cache — in-process by default (single replica), shared via the DataStore with `sloStore: { store: true }` (a `_voltro_saml_logout` table) so a login on one replica can log out on another.
 
 ```ts
@@ -104,22 +112,53 @@ samlSsoPlugin({
 
 All three secrets come from env / a secrets backend — never a literal, never logged.
 
-## Replay / `InResponseTo` protection
+## Which signatures are required
+
+Two separate requirements, and only one of them is a choice:
+
+| | Required? | Option |
+|---|---|---|
+| **Assertion** signature | Always. Not configurable. | — |
+| **Response** envelope signature | No, by default | `wantAuthnResponseSigned` |
+
+The assertion is the part that matters: only signature-covered XML is ever read, and the assertion is what carries the NameID, the attributes, the audience restriction, the validity window and the `SubjectConfirmationData`. An envelope signature additionally covers the response-level `Status`, `Destination` and `InResponseTo`.
 
-By default node-saml runs with `validateInResponseTo: 'never'`, so a captured `SAMLResponse` can be replayed to the ACS within its validity window (and unsolicited IdP-initiated posts are accepted). Turn on the one-time request-id cache with `replayProtection`:
+**The default accepts an assertion-signed, envelope-unsigned response** — Okta's default application profile ("Sign assertion", response unsigned), and Azure AD's. Set `wantAuthnResponseSigned: true` if your IdP signs the response; it is one checkbox on both, and it is the stronger posture:
 
 ```ts
 samlSsoPlugin({
   // …idp / sp / sessionSecret / onLogin…
-  replayProtection: { store: true },   // shared across replicas — the production choice
+  wantAuthnResponseSigned: true,   // require the envelope signature too
 })
 ```
 
-- `false` (default) — off. Single-replica dev / PoC only.
-- `true` — on with an **in-process** cache. Correct for one replica only; a login and its ACS POST that land on different processes fail the check (boot warns).
-- `{ store: true, ttlMs? }` — on, backed by the framework DataStore (a contributed `_voltro_saml_replay` table). Shared across replicas. Declares `store:write`. `ttlMs` bounds an outstanding request's validity (default 10 min).
+One edge worth knowing at the default: an envelope signature that does **not** verify is treated the same as no envelope signature — it is discarded and the assertion signature decides. That is not a bypass (an attacker holding a validly signed assertion would simply send no envelope signature, and an attacker-signed *assertion* is refused at every setting), but it does mean an IdP misconfigured to sign responses with the wrong key goes unnoticed. `wantAuthnResponseSigned: true` surfaces it.
+
+## Replay / `InResponseTo` protection
+
+**On by default, backed by the DataStore.** The `AuthnRequest` id is stored at `/saml/login` and **consumed** at `/saml/acs`, so the same assertion can't be replayed and a response referencing no request this SP issued is rejected.
+
+- `{ store: true, ttlMs? }` (**default**) — backed by the framework DataStore (a contributed `_voltro_saml_replay` table). Shared across replicas. Declares `store:write`. `ttlMs` bounds an outstanding request's validity (default 10 min).
+- `true` — an **in-process** cache. Correct for one replica only; a login and its ACS POST that land on different processes fail the check (boot warns). The default is store-backed rather than this precisely because the in-process mode is not a milder version of the same protection — under more than one replica it is a total login outage.
+- `false` — off, and a captured `SAMLResponse` is replayable within its validity window.
+
+### It refuses IdP-initiated SSO — and `false` is the only way back
+
+Replay protection sets `validateInResponseTo: 'always'`, which means a `SAMLResponse` carrying no `InResponseTo` is rejected. That is exactly an **IdP-initiated** login: the Okta / Azure dashboard app tile, rather than a user arriving at `/saml/login`.
+
+You cannot keep both, and the reason is structural rather than a missing feature: the protection *is* the requirement that the response answer a request this SP issued, and an unsolicited response answers none. (`'ifPresent'` looks like the compromise and is not one — an attacker replaying a captured response just deletes the attribute and the check declines to run.)
+
+If you need the app tile, opt out deliberately:
+
+```ts
+samlSsoPlugin({
+  // …idp / sp / sessionSecret / onLogin…
+  replayProtection: false,          // accepts unsolicited responses — and replays
+  wantAuthnResponseSigned: true,    // recommended if you must run unsolicited
+})
+```
 
-The `AuthnRequest` id is stored at `/saml/login` and **consumed** at `/saml/acs`, so the same assertion can't be replayed and a response referencing no request this SP issued is rejected.
+Boot warns when replay protection is off, because nothing about it is visible at runtime.
 
 ## Notes
 
@@ -129,4 +168,4 @@ The `AuthnRequest` id is stored at `/saml/login` and **consumed** at `/saml/acs`
 
 ## Permissions
 
-None by default (it serves the SAML routes + mints a session). `replayProtection: { store: true }` and `sloStore: { store: true }` each declare `store:write` for their shared table (`_voltro_saml_replay` / `_voltro_saml_logout`).
+`store:write` by default — replay protection is on and store-backed, so the plugin contributes `_voltro_saml_replay`. `sloStore: { store: true }` adds `_voltro_saml_logout` under the same permission. Setting `replayProtection: false` (and leaving `sloStore` at its in-process default) drops the permission entirely: the plugin then only serves the SAML routes + mints a session.

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

@@ -417,6 +417,17 @@ procedure's wire-error union so they decode typed on the client:
 `storage.revoke`, `storage.listGrants`, `storage.listRefs`. (The upload hook picks
 the right ones per `prefer`; you rarely call them directly.)
 
+Every route declares its access decision. The self-service upload/read flow is
+`openAccess` — what bounds it is structural (mints bind the caller's subject +
+tenant into a signed ticket, finalize/complete refuse another subject's token,
+reads go through the per-object access policy + grants, the grant RPCs enforce
+owner-or-admin in-handler). Three routes require a scope instead: **`storage.mintUploadUrl`**
+(the raw bring-your-own-key PUT, which bypasses limits + scan) and
+**`storage.ingestUrl`** (the server fetches a caller-supplied URL — an SSRF
+surface) need `storage:manage`; **`storage.listRefs`** (the tenant-WIDE media
+library index) needs `storage:browse`. Grant them via an rbac role or
+`resolveScopes`; `admin:full` passes.
+
 ### The grant RPCs are owner-only
 
 `storage.share`, `storage.revoke` and `storage.listGrants` require that the

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

@@ -328,6 +328,8 @@ import { Schema } from 'effect'
 
 export const subscribeWebhook = defineMutation({
   name:   'webhooks.subscribe',
+  // Registers a URL this server will POST your events to — never openAccess.
+  guards: [{ scope: 'webhooks:manage' }],
   input:  Schema.Struct({ url: Schema.String }),
   output: Schema.Struct({ targetId: Schema.String }),
   error:  WebhookSubscribeInvalid,
@@ -374,6 +376,37 @@ The endpoint mounts at `/webhooks/<id>` by default; override with
 `VOLTRO_WEBHOOK_SECRET_STRIPE` (non-alphanumeric characters in the id become
 `_`).
 
+### Verification is not optional
+
+An incoming webhook is a **public POST that runs your application code**, so the
+framework refuses to mount one that has made no decision about who may call it.
+A descriptor with no `signature` and no `provider` fails the boot, naming the
+endpoint. Four ways to satisfy it:
+
+| Declaration | Means |
+|---|---|
+| `provider: stripeProvider()` | a preset brings the scheme, replay window and idempotency key |
+| `signature: { _tag: 'hmac', … }` | a hand-declared scheme for a sender with its own convention |
+| `verification: 'provider'` | your handler verifies with the provider's own SDK |
+| `verification: 'none'` | deliberately public — a gateway or IP allow-list owns the boundary |
+
+```ts
+export default defineIncomingWebhook({
+  id:           'internal.reindex',
+  verification: 'none',        // behind the cluster gateway; nothing else may reach it
+  payload:      Schema.Struct({ index: Schema.String }),
+  handler:      async (ctx) => { /* … */ },
+})
+```
+
+`verification: 'none'` logs a warning at every boot, on purpose — an open
+endpoint should stay visible.
+
+**A declared signature with no configured secret answers 503**, on every
+delivery, naming the variable to set. It does not skip the check: that fallback
+meant one missing env var silently turned a verified webhook into an open one.
+The framework never generates the secret — the sender holds the other half of it.
+
 ### Provider presets
 
 Built-in presets configure the signature scheme, idempotency extraction, and
@@ -425,6 +458,78 @@ export default defineIncomingWebhook({
 })
 ```
 
+## Signing — Standard Webhooks v1.0.0
+
+Outbound deliveries are signed to the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) spec by default. That is the point of a spec: every conformant consumer library verifies your deliveries with no code specific to you.
+
+```http
+POST /your/hook
+webhook-id: 3f6a…                    ← the delivery id — USE THIS AS THE IDEMPOTENCY KEY
+webhook-timestamp: 1786503000        ← unix seconds
+webhook-signature: v1,K5oZfzN95Z…=   ← base64 HMAC-SHA256, space-delimited during a rotation
+x-voltro-event: orders.paid
+x-voltro-attempt: 1
+content-type: application/json
+```
+
+The signed content is `<webhook-id>.<webhook-timestamp>.<raw body>`. The key is `whsec_` + base64 of 24–64 random bytes, and the HMAC runs over the **decoded** bytes — `subscribe()` mints the right shape automatically. Passing your own hex secret for a spec-signed target is REFUSED at subscribe rather than producing signatures no consumer accepts: a hex string is also valid base64, so a lenient decoder would key the HMAC on bytes that round-trip against itself and fail against everyone else.
+
+Implemented: the symmetric `v1` scheme, multi-signature rotation, the `.`-delimiter constraint on the id (asserted, not assumed), a constant-time compare, a 300s replay tolerance (the spec requires a tolerance and names no number — this one is ours, and tunable). NOT implemented: the asymmetric half (ed25519 / `v1a` / `whsk_`). A `v1a`-only signature is rejected by name rather than reported as a generic mismatch.
+
+Other schemes stay available as explicit choices — `genericHmacSignature()` (the previous house format, `X-Webhook-Signature: t=…,v1=<hex>`), `stripeSignature()`, `githubSignature()`, `slackSignature()`:
+
+```ts
+subscribe({ event: 'orders.paid', url, signing: genericHmacSignature() })
+```
+
+### Delivery semantics the spec dictates
+
+| response | what happens |
+|---|---|
+| `2xx` | success |
+| `3xx` | **failure. The redirect is not followed** — the target URL is the one we validated, and following one walks past that check |
+| `410 Gone` | the target is disabled **immediately**, whatever `autoDisableAfter` says. The receiver answered the question |
+| `429` / `5xx` | retried with backoff; `Retry-After` is honoured |
+
+Each attempt has a **30s wire timeout** (`VOLTRO_WEBHOOK_TIMEOUT_MS`, or `timeoutMs` on the delivery workflow) — the top of the spec's recommended 15–30s band.
+
+## `voltro webhooks consumer` — the package your subscribers install
+
+Your app already knows every event a subscriber can register for, every payload's shape, and the exact scheme it signs with. So generate the verification package rather than making the receiving team write it:
+
+```
+voltro webhooks consumer --out ../partner-sdk
+voltro webhooks events --json          # what a subscriber can register for
+```
+
+It emits `index.js` + `index.d.ts` + `package.json` + a README, with **no runtime dependencies at all** — it imports `node:crypto` and nothing else. That constraint is the design, not an optimisation: the package runs in your subscriber's service, which is usually a different codebase and often not a Voltro app, and a dependency list is where "npm i and paste this in" stops being true.
+
+```js
+import { createVerifier, WebhookVerificationError } from 'acme-webhooks'
+
+const verifier = createVerifier({ secret: process.env.WEBHOOK_SECRET })
+
+app.post('/webhooks/acme', (req, res) => {
+  let delivery
+  try {
+    delivery = verifier.verify(req.rawBody, req.headers)   // ← RAW bytes
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) return res.status(401).send(err.reason)
+    throw err
+  }
+  if (alreadyProcessed(delivery.id)) return res.sendStatus(200)   // webhook-id
+  switch (delivery.event) { /* … */ }
+  res.sendStatus(200)
+})
+```
+
+Notes worth knowing before you hand it over:
+
+- **The raw body is the whole trap.** The signature covers the exact bytes that arrived; a JSON body-parser re-serialises and the signature then never matches. The generated README carries the per-framework recipe (Express / Fastify / Next / Hono).
+- **Node 18+**, deliberately. Web Crypto's HMAC is async, which would make `verify()` return a Promise and force every handler using it to be async too.
+- **Payload types only.** They are generated from each event's Schema; no decoder ships. The types describe what you send — the signature is what proves you sent it.
+- Pass an array as `secret` during a rotation; each is tried.
+
 ## Managing targets
 
 ```ts

package/templates/agent-docs/plugins.md

@@ -19,7 +19,7 @@ The framework ships some plugins; you write your own; the contract is small enou
 
 - [The plugin contract](/docs/plugins/contract) — `definePlugin`, lifecycle hooks, rpc interceptors, framework-version compatibility
 - [plugin-audit](/docs/plugins/audit) — mutation audit log + `audit()` mixin
-- [plugin-auth](/docs/plugins/auth) — full auth suite: password (rehash-on-verify) + sessions (multi-key rotation + sliding-window) + magic-link/reset + passkeys (atomic clone detection, BYO multi-replica challenge store) + CSRF + session revocation + memberships/switch-tenant + TOTP/MFA (sign-in enforcement + recovery codes), mounted by `authRoutesPlugin()` (see also the [Authentication section](/docs/authentication/overview))
+- [plugin-auth](/docs/plugins/auth) — full auth suite: password (rehash-on-verify) + sessions (multi-key rotation + sliding-window) + magic-link/reset + email verification + tenant invitations + user impersonation + passkeys (atomic clone detection, BYO multi-replica challenge store) + CSRF + session revocation + memberships/switch-tenant + TOTP/MFA (sign-in enforcement + recovery codes), mounted by `authRoutesPlugin()` (see also the [Authentication section](/docs/authentication/overview))
 - [plugin-multitenancy](/docs/plugins/multitenancy) — `tenant()` schema mixin + `assertOwnTenant` write-guard + `TenantMismatch`
 - [plugin-soft-delete](/docs/plugins/soft-delete) — `softDelete()` schema mixin (hide on delete, `hardDelete()` bypass)
 - [plugin-rbac](/docs/plugins/rbac) — roles + permissions + the `permission()` guard
@@ -46,7 +46,8 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-governance](/docs/plugins/governance) — data governance: retention TTL sweep, GDPR export + erasure, consent ledger, field encryption
 - [plugin-openapi](/docs/plugins/openapi) — OpenAPI 3.1 spec + Swagger-UI docs generated from your `defineRestRoute` descriptors and (opt-in) rpc procedures
 - [plugin-versioning](/docs/plugins/versioning) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
-- [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, cross-instance
+- [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, held in memory; cross-instance with [plugin-broadcast](/docs/plugins/broadcast)
+- [plugin-auth-social](/docs/plugins/auth-social) — first-party Sign in with Google / GitHub / Apple: mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, sessions issued through plugin-auth
 - [plugin-scim](/docs/plugins/scim) — SCIM 2.0 provisioning (Users + Groups at `/scim/v2`) so an enterprise IdP can create/deactivate users
 - [plugin-sso-saml](/docs/plugins/sso-saml) — enterprise SAML 2.0 SSO: SP-initiated login + Single Logout, ACS, metadata (+ IdP-metadata-URL auto cert rotation, encrypted assertions, SP request signing); mints a framework session
 - [API keys](/docs/configuration/api-keys) — **first-class** (not a plugin): `apiKeys: true` enables Bearer-key auth + admin-gated issue/list/revoke
@@ -60,7 +61,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | Plugin | Status | What it does |
 |---|---|---|
 | `@voltro/plugin-audit` | ✓ | Mutation audit log + `audit()` mixin |
-| `@voltro/plugin-auth` | ✓ | Full auth suite via `authRoutesPlugin()`: password (rehash-on-verify), sessions (multi-key rotation + sliding-window), magic-link + password-reset, passkeys/WebAuthn (atomic clone detection, BYO multi-replica challenge store), CSRF, session enumeration + revocation, memberships + switch-tenant, TOTP/MFA (sign-in enforcement + recovery codes); `authTables` schemas |
+| `@voltro/plugin-auth` | ✓ | Full auth suite via `authRoutesPlugin()`: password (rehash-on-verify), sessions (multi-key rotation + sliding-window), magic-link + password-reset, email verification (off/soft/strict policy), tenant invitations (addressed, single-use, role chosen by the inviter), user impersonation (marked, time-bounded, escalation-proof), passkeys/WebAuthn (atomic clone detection, BYO multi-replica challenge store), CSRF, session enumeration + revocation, memberships + switch-tenant, TOTP/MFA (sign-in enforcement + recovery codes); `authTables` schemas |
 | `@voltro/plugin-multitenancy` | ✓ | `tenant()` schema mixin (read-scope + write-fill) + `assertOwnTenant` guard + typed `TenantMismatch` |
 | `@voltro/plugin-soft-delete` | ✓ | `softDelete()` schema mixin — `deletedAt` / `deletedBy`; `delete` → UPDATE, `hardDelete()` bypass |
 | `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `ScopeError` |
@@ -71,6 +72,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
 | `@voltro/plugin-broadcast` | ✓ | Cross-replica reactivity — fans out app-mutation change events to every replica over a pub/sub bus (Redis / NATS). Closes the single-instance gap for every non-postgres dialect. [→ details](/docs/plugins/broadcast) |
 | `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
+| `@voltro/plugin-auth-social` | ✓ | First-party social login — Sign in with Google / GitHub / Apple with no identity vendor: authorize URL + code exchange + JWKS-verified ID tokens, mandatory PKCE (S256) and `state`, an explicit account-linking policy (`never` by default), Apple's signed-JWT client secret / one-time name / private-relay email all handled; sessions via `issueUserSession`. [→ details](/docs/plugins/auth-social) |
 | `@voltro/plugin-auth-{workos,kinde,clerk,auth0,supabase,oidc}` | ✓ | Six IdP adapters over the shared `jwtBearerStrategy` — JWKS verify + claims→tenant mapping; WorkOS additionally ships hosted-login OAuth primitives (`workosAuthorizationUrl` / `workosAuthenticateWithCode`) for a redirect-based SSO login flow. [→ details](/docs/authentication/external-idp) |
 | `@voltro/plugin-analytics-postgres` | ✓ | First-party lite — events on the main DataStore, cross-dialect (postgres / mysql / mariadb / mssql / sqlite / turso). [→ details](/docs/plugins/analytics#voltroplugin-analytics-postgres) |
 | `@voltro/plugin-duckdb` | ✓ | Embedded DuckDB sidecar — real OLAP performance, no external service. [→ details](/docs/plugins/analytics#voltroplugin-duckdb) |
@@ -91,7 +93,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-governance` | ✓ | Data governance — retention TTL sweep (delete / anonymise), GDPR subject export + erasure (admin-gated routes + `GovernanceService`), consent ledger, field encryption. [→ details](/docs/plugins/governance) |
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
 | `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
-| `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator, swept `_voltro_presence` table, cross-instance. [→ details](/docs/plugins/presence) |
+| `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator. Held **in memory**, owner-partitioned — no table is written; cross-instance requires [`@voltro/plugin-broadcast`](/docs/plugins/broadcast), and without a broker each replica sees only its own clients. [→ details](/docs/plugins/presence) |
 | `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
 
@@ -126,7 +128,7 @@ Order matters: the framework composes outer→inner, so the rate-limit intercept
 | `extendSchema` | Contribute tables + custom SQL migrations (tracked in `_voltro_plugin_migrations`). |
 | `services` | Provide an Effect `Layer` whose Tags every handler can `yield*` (e.g. `MailService`, `StorageService`). |
 | `routes` | Register plugin-owned rpc queries / mutations / actions (alias-prefixed tags). |
-| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). The request carries `store` — the app's DataStore — for a route that must read or write (a login endpoint minting a session row cannot be an rpc mutation). Not tenant-scoped: raw HTTP has no resolved Subject, so scope it yourself. |
+| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). The request carries `store` — the app's DataStore — for a route that must read or write (a login endpoint minting a session row cannot be an rpc mutation), and `remoteAddr`, the client address already resolved through `security.trustedProxies` (use it instead of `x-forwarded-for`). Not tenant-scoped: raw HTTP has no resolved Subject, so scope it yourself. A state-changing route is [origin-checked](/docs/security/overview#cross-site-requests-are-refused) unless it declares `originGuard: 'exempt'`. |
 | `inspectEndpoints` | Mount tooling under `/_voltro/inspect/plugins/<alias>/…`. |
 | `onScheduleFire` / `onWorkflowStep` / `onHttpRequest` | Wrap every cron firing, every workflow `step()`, every pre-auth HTTP request. |
 | `onInstall` / `onActivate` / `onDeactivate` / `onUninstall` | Lifecycle hooks at first-install, boot, shutdown, and removal. |
@@ -207,10 +209,15 @@ To REPLACE one deliberately, declare it:
 
 ```ts
 // Adopt the plugin's namespace, add your own leaves beside it…
-defineQuery({ name: 'notifications.archive', … })
-
-// …and REPLACE just the one you need to behave differently.
-defineMutation({ name: 'notifications.markRead', overridesPlugin: true, … })
+defineQuery({ name: 'notifications.archive', guards: [{ scope: 'notifications:read' }], … })
+
+// …and REPLACE just the one you need to behave differently. Your replacement is
+// YOUR procedure, so it needs its own access decision — the plugin's does not
+// carry over with the tag.
+defineMutation({
+  name: 'notifications.markRead', overridesPlugin: true,
+  guards: [{ scope: 'notifications:write' }], …
+})
 ```
 
 The plugin's route is dropped, not merely permitted alongside yours — permitting
@@ -345,6 +352,8 @@ onChangeEvent: (event: PluginChangeEvent) => Effect.Effect<void, unknown>
 // PluginChangeEvent = {
 //   table, op: 'insert'|'update'|'delete', new: Row | null, old: Row | null,
 //   origin?: 'inline' | 'injected', changeScope: 'local' | 'fleet',
+//   traceId?, subjectId?, procedure?,
+//   oversized?: 'rehydrated' | 'tombstone' | 'unrecovered',
 // }
 ```
 
@@ -359,6 +368,8 @@ onChangeEvent: (event) =>
       )
 ```
 
+**Check `event.oversized` before you treat an image as a snapshot.** It is absent on an ordinary event, and set when the transport could not carry the row and the images were reconstructed — a row over postgres' 8000-byte NOTIFY cap. `'rehydrated'` means `new` is the row re-read from the database (correct to index or forward, but the row as it is NOW rather than the image at commit); `'tombstone'` means a delete whose `old` is the primary key and nothing else (enough to REMOVE the row, never a record of what it held); `'unrecovered'` means both images are null and the content is gone. A tap that stores history must not write a tombstone as a snapshot. Full guarantee: [postgres — oversized rows](/docs/database/dialects/postgres).
+
 Runs under BOTH `voltro dev` and `voltro serve` (the prod serve path fans out the same way). Requires the `'store:changes:read'` permission. It is NOT durable at the framework layer — a crash between commit and the fork loses the event; build durability INSIDE the Effect (insert into an outbox and retry against the typed error channel, the way `@voltro/plugin-cdc-out` does). Exactly-once / change-scope semantics are unchanged: read `event.origin` + `event.changeScope` inside the Effect to act once per change fleet-wide (skip `origin: 'injected'` on `'local'` scope; elect one worker on `'fleet'`). Used by `@voltro/plugin-search` to mirror rows into an external index. For in-transaction reactions use a mutation; for best-effort per-table reactions in app code prefer a `*.subscribe.ts` — `onChangeEvent` is the plugin-level equivalent.
 
 ### `onInstall` / `onUninstall` / `onActivate` / `onDeactivate` lifecycle
@@ -523,9 +534,8 @@ export const auditPlugin = (): VoltroPlugin =>
   })
 ```
 
-Tag derivation: `<plugin-alias>.<query.name>` unless `query.name` contains
-a dot (escape hatch). Plugin alias strips `@scope/` + the `plugin-` prefix
-and kebab→camelCase:
+Tag derivation: `<plugin-alias>.<query.name>`. The plugin alias strips
+`@scope/` + the `plugin-` prefix and kebab→camelCase:
 
 | Plugin name | Alias |
 |---|---|
@@ -535,6 +545,71 @@ and kebab→camelCase:
 | `plain-name` | `plainName` |
 | `@voltro/audit` | `audit` (no `plugin-` to strip) |
 
+A `query.name` that already contains a dot is handled by whether it names the
+plugin's OWN namespace:
+
+- `'notifications.inbox'` on a plugin whose canonical name is
+  `@voltro/plugin-notifications` is re-namespaced — under
+  `alias: 'inbox'` it becomes `inbox.inbox`, not `notifications.inbox`.
+  A deeper path keeps its depth: `'audit.admin.events'` under `alias: 'trail'`
+  becomes `trail.admin.events`.
+- `'acme.legacyBridge'` — a namespace that is not the plugin's own — passes
+  through untouched. That is the escape hatch, and it is the only case that
+  still bypasses the alias.
+
+The re-namespacing needs the plugin to declare `baseName` (its canonical name,
+before any app-supplied `alias`); a plugin that omits it keeps the older
+behaviour where any dotted name passes through.
+
+### Naming a plugin: `alias` vs `name`
+
+Two different app-side problems land on a plugin's name, so first-party plugins
+that carry tables or routes accept two separate options:
+
+| Option | Question it answers | Effect |
+|---|---|---|
+| `alias` | "your namespace collides with mine" | replaces the namespace — tags become `<alias>.<route>`, the inspect mount becomes `/_voltro/inspect/plugins/<alias>/…` |
+| `name` | "I want two of these" | appends a `#suffix` discriminator so two installs never register the same tag |
+
+```ts
+notificationsPlugin({ alias: 'alerts' })                    // alerts.inbox
+notificationsPlugin({ name: 'ops' })                        // notifications#ops.inbox
+notificationsPlugin({ alias: 'alerts', name: 'ops' })       // alerts#ops.inbox
+```
+
+`alias` exists to escape a tag collision, which is fatal at codegen. Two costs
+are worth knowing before you reach for it:
+
+- the local and cloud dashboards fetch a plugin's inspect panel at its DEFAULT
+  slug, so an aliased plugin keeps serving its inspect endpoints while its
+  dashboard panel stops resolving;
+- the plugin-migration ledger key is `<plugin-alias>__<migration.id>`, so
+  aliasing a plugin that ships `extendSchema.migrations` makes its already-applied
+  migrations look unapplied. Choose the alias before first boot, not after.
+
+### `tables: false` — keeping your own tables
+
+Plugins whose tables carry no authorization or safety decision accept
+`tables: false`, which stops them contributing DDL through `extendSchema` so an
+app can keep equivalent tables it already has. Everything else — routes,
+inspect, interceptors — is unchanged.
+
+```ts
+notificationsPlugin({ tables: false })   // you declare the six notification tables
+```
+
+It is offered on `@voltro/plugin-rbac`, `@voltro/plugin-audit`,
+`@voltro/plugin-notifications` and `@voltro/plugin-ai-flows`. The plugin still
+writes to those tables BY NAME, so you take over declaring each one with the
+shape the package exports, and a missing or mis-shaped table fails at the first
+write rather than at boot.
+
+It is deliberately NOT offered on plugins whose tables carry a guarantee — the
+SAML assertion replay cache, SCIM provisioning state, billing's usage counters,
+cdc-out's delivery outbox, the governance consent ledger, search's tenant-scoped
+index rows. A `tables: false` there would disable a security or correctness
+decision with no signal to the app that it now owns it.
+
 Boot fails with a clear error on tag collisions (between two plugins, or
 with a user-authored tag).
 
@@ -770,7 +845,7 @@ markers. The plugin sees the api name + the list of discovered user-query
 rpc tags so it can emit per-rpc bindings. Returning `null` contributes
 nothing.
 
-### `templates: PluginTemplate[]` — ship `voltro init` templates
+### `templates: PluginTemplate[]` — ship scaffolding templates
 
 ```ts
 definePlugin({
@@ -819,8 +894,14 @@ export const rateLimitPlugin = (opts: { perMinute: number }) =>
     name: '@vendor/plugin-rate-limit',
     permissions: ['http:intercept'],
     onHttpRequest: async (next, ctx) => {
-      const remoteAddr = ctx.headers['x-forwarded-for'] ?? ctx.remoteAddr ?? 'unknown'
-      if (buckets.consume(remoteAddr, opts.perMinute) === 'exhausted') {
+      // `ctx.remoteAddr` is ALREADY resolved through the app's
+      // `security.trustedProxies` policy — the same value the framework's own
+      // rate limiter, geo-block and audit rows use. Never read
+      // `ctx.headers['x-forwarded-for']`: it is a request header, so any
+      // caller can write it, and a limiter keyed on it is bypassed by one
+      // extra header. `undefined` only when the socket address is unavailable.
+      const clientAddr = ctx.remoteAddr ?? 'unknown'
+      if (buckets.consume(clientAddr, opts.perMinute) === 'exhausted') {
         return {
           status: 429,
           headers: { 'retry-after': '60', 'content-type': 'application/json' },
@@ -832,10 +913,28 @@ export const rateLimitPlugin = (opts: { perMinute: number }) =>
   })
 ```
 
+**`ctx.remoteAddr` is the client address — `x-forwarded-for` is not.**
+The framework resolves `remoteAddr` through the app's
+`security.trustedProxies` policy (`VOLTRO_TRUSTED_PROXIES`) before it hands you
+the context: with no trusted proxy declared the header is ignored entirely and
+the socket address wins, and with one declared only the hops that are actually
+a configured proxy are believed. Reading `ctx.headers['x-forwarded-for']`
+yourself throws that away and keys your limiter on a string the caller typed —
+one extra header and every request looks like a new client. The same rule
+applies to a plugin's raw HTTP routes, where the resolved value arrives as
+`req.remoteAddr`; see [Trusted proxies](/docs/security/overview#the-same-address-reaches-your-plugin-routes).
+
 A per-plugin `plugin.<name>.http-intercept` metric is auto-emitted so
 the dashboard's Plugins panel surfaces HTTP-intercept latency next to
 RPC-intercept latency.
 
+**Runs on both boot paths.** The chain is composed and installed identically by
+`voltro dev` and `voltro serve` — this is a production capability, and for a
+pre-auth shield production is the point. There is exactly ONE exemption, and it
+is deliberate: `GET /internal/liveness` and `GET /internal/readiness` are
+answered before the interceptor, so a rate-limit or geo-block plugin cannot 503
+a Kubernetes probe and take the replica out of rotation.
+
 ### `extendSchema: { tables, migrations }` — contribute schema + migrations
 
 A plugin contributes BOTH declarative table descriptors AND custom SQL
@@ -848,6 +947,14 @@ The ledger key is `<plugin-alias>__<migration.id>` so two plugins can
 each ship `'001-init'` without collision. Failure aborts boot;
 re-runs are no-ops.
 
+**Which commands run them:** `voltro dev`'s boot auto-migrate, `voltro db apply`
+(bare and `--plan`) and `voltro migrate --create-only`. NOT `voltro serve` —
+serve never applies a schema, so a plugin's steps land in the pre-deploy job
+alongside the schema, which is where they belong. Until 0.34.0 only the `voltro
+dev` boot ran them, so a plugin's SQL steps executed on every developer machine
+and on no deployed database; if you ship migrations, verify against a deployed
+database rather than a dev boot.
+
 ```ts
 import { Effect, Schema } from 'effect'
 import { definePlugin } from '@voltro/protocol'
@@ -1387,17 +1494,44 @@ analytics: duckdbAnalytics({
 }),
 ```
 
-The postgres-lite (`postgresAnalytics({ mirrorTables: [...] })`) and ClickHouse (`clickhouseAnalytics({ url, mirrorTables: [...] })`) sinks take the same options. Each mirrored table lands as `_voltro_mirror_<table>` (`voltro_mirror_<table>` on DuckDB / ClickHouse) holding `{ id, data }` — `id` is the source row's primary key, `data` is the full row as JSON. Analytical queries JOIN events against the mirror:
+The postgres-lite (`postgresAnalytics({ mirrorTables: [...] })`) and ClickHouse (`clickhouseAnalytics({ url, mirrorTables: [...] })`) sinks take the same options. Each mirrored table lands as `_voltro_mirror_<table>` (`voltro_mirror_<table>` on DuckDB / ClickHouse) holding `{ id, data, version, is_deleted }` — `id` is the source row's primary key, `data` is the full row as JSON, `version` orders the writes (see below) and `is_deleted` marks a tombstone. Analytical queries JOIN events against the mirror and filter tombstones out:
 
 ```sql
 -- DuckDB: events per user tier
 SELECT json_extract_string(m.data, '$.tier'), COUNT(*)
 FROM voltro_events e
-JOIN voltro_mirror_users m ON m.id = e.subject_id
+JOIN voltro_mirror_users m ON m.id = e.subject_id AND m.is_deleted = false
 GROUP BY 1
 ```
 
-The mirror is **opt-in** (omit `mirrorTables` → events-only) and **idempotent** — inserts/updates upsert by primary key, deletes remove by key, so a re-delivered change (e.g. after a reconnect) is a no-op-equivalent overwrite. Per-change failures are isolated into the log channel: the OLTP write that produced the change already committed, so a warehouse hiccup never surfaces to the request. On DuckDB the mirror table is a plain `(id, data)` table; on ClickHouse it's a `ReplacingMergeTree(version)` so re-inserts collapse to the latest version on merge (deletes write a `is_deleted = 1` tombstone — filter `is_deleted = 0` or use `FINAL`).
+The mirror is **opt-in** (omit `mirrorTables` → events-only) and **idempotent** — inserts/updates upsert by primary key, deletes write a tombstone by key, so a re-delivered change (e.g. after a reconnect) is a no-op-equivalent overwrite.
+
+### Delivery guarantee
+
+**At-least-once for the lifetime of the process, ordered per row.** Read that sentence literally — every clause is a promise the framework keeps, and the sentence stops where the implementation does:
+
+- **Retried, not dropped.** A failing mirror write is retried with exponential backoff (`retryAttempts`, default 5). A write that outlives its retries is queued for **repair**: a timer re-reads the row's *current* state from your database and re-applies it, so the mirror converges on the truth rather than on a stale change that happened to be in flight.
+- **Ordered per row.** Writes for the same primary key are applied one at a time, in commit order, and every write carries a **version** stamped when the change left the store — never a clock read inside the warehouse client. A change that arrives late therefore *loses*: ClickHouse's `ReplacingMergeTree(version)` keeps the highest version, and the DuckDB / postgres mirrors apply the update only when the incoming version is newer. Different rows are still mirrored concurrently.
+- **A delete is a tombstone, not a row removal.** Filter `is_deleted = false` (`is_deleted = 0` / `FINAL` on ClickHouse). A physical delete would leave nothing for a late, stale insert of the same key to lose against — the row would silently come back. The tombstone also keeps its version, which is what lets a replacement replica seed a key's numbering after a delete.
+- **N replicas converge to ONE row per change.** Under postgres CDC / mysql binlog every replica observes every change and mirrors it, so a change is written N times — but the version is derived from the CHANGE (the warehouse's own high-water mark for the key, plus the change's position in the fleet stream), never from a replica's clock. The N duplicates are byte-identical, and the sink's version guard collapses them for free: no leader election, and no clock-skew window in which an older image could out-version a newer one. A replica that boots mid-stream reads each key's high-water mark from the warehouse before its first write, so it continues the fleet's numbering instead of restarting it.
+- **Never surfaces to the request.** The OLTP write that produced the change has already committed; a warehouse outage is isolated into the log channel and the metrics below.
+- **A graceful shutdown is not a crash.** On SIGINT / SIGTERM the mirror stops taking new changes and then **settles** what is already queued and in flight, before the sink itself is disposed. That drain is bounded (3 s of the teardown budget you set with `VOLTRO_SHUTDOWN_GRACE_MS`, default 10 s): a warehouse that has stopped answering cannot hold the process open until the orchestrator's SIGKILL, which would lose strictly more. The two outcomes log differently — `analytics mirror drained` at info, or a `warn` naming what was still pending when the deadline cut it, because that is the moment those counters can still be read.
+- **Not durable across a crash.** The repair queue lives in memory. A change still awaiting repair when the process dies — SIGKILL, an OOM, a host failure — is lost, as is one evicted after `repairQueueLimit`. Both are logged at error level and counted by `voltro_analytics_mirror_dropped_total` — if that counter is non-zero, the affected tables need a re-seed.
+
+Metrics: `voltro_analytics_mirror_forwarded_total`, `..._retries_total`, `..._repair_queued_total`, `..._dropped_total`.
+
+### Tuning
+
+Every number the mirror picks on your behalf has a default and an environment override:
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_ATTEMPTS` | `5` | Total attempts per mirror write (`1` = no retry). |
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_BASE_MS` | `100` | First backoff delay; doubles per attempt. |
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_MAX_MS` | `30000` | Ceiling for the doubling backoff. |
+| `VOLTRO_ANALYTICS_MIRROR_REPAIR_INTERVAL_MS` | `60000` | How often the repair loop re-drives exhausted changes (`0` disables it). |
+| `VOLTRO_ANALYTICS_MIRROR_REPAIR_QUEUE_LIMIT` | `10000` | Maximum keys held for repair before the oldest is dropped and counted. |
+| `VOLTRO_ANALYTICS_MIRROR_VERSION_STATE_LIMIT` | `100000` | Maximum keys whose fleet-scope version state stays in memory; an evicted key re-seeds from the warehouse on its next change. |
 
 ## Default — no sink configured