@voltro/cli 0.33.0 → 0.34.0

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

@@ -45,7 +45,16 @@ const Room = ({ channel }: { channel: string }) => {
 }
 ```
 
-`usePresence(channel, opts)` heartbeats on an interval (`heartbeatMs`, default 15s) and publishes per-member `meta` (status, cursor position, …). The roster is **push-driven** — `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework pushes a fresh roster over the subscription transport on every roster change (heartbeat / leave / sweep / a peer departing) with NO client polling. `key` defaults to the subject id; pass an explicit `key` for anonymous members.
+`usePresence(channel, opts)` heartbeats on an interval (`heartbeatMs`, default 15s) and publishes per-member `meta` (status, cursor position, …). The roster is **push-driven** — `presence.list` is a reactive plugin query whose `source:` is a [reactivity channel](/docs/data/subscriptions#reactivity-channels), so the framework pushes a fresh roster over the subscription transport with NO client polling. `key` defaults to the subject id; pass an explicit `key` for anonymous members.
+
+A member is `{ key, meta }`. **It pushes only when the roster actually moves** — a join, a leave, a change to someone's `meta`, a sweep, a peer's delta, a peer's death. A heartbeat that repeats what the server already knows pushes nothing, which is what keeps a large steady room free.
+
+> **There is a second `usePresence`, and it is a different hook.**
+> [`@voltro/local-first/react`](/docs/local-first/overview#presence--awareness)
+> exports one for peer-to-peer *awareness* — `usePresence(roomId, self, { channel })`
+> → `{ presence, others, setPresence }` — carrying high-frequency cursor and
+> selection state over a pub/sub channel. This one is the server-backed roster.
+> Different packages, different signatures; pick by the question you are asking.
 
 ## Typing indicator
 
@@ -85,7 +94,9 @@ an event declared `delivery: 'latest'` rather than in presence metadata.
 
 ## Notes
 
-- The roster is push-driven: `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework re-runs it and pushes deltas over the subscription transport on every roster change — no client polling. There is no such TABLE any more; the name survives purely as the reactivity key the framework routes on, which is why the roster push needed no second mechanism when presence moved into memory. Any plugin query route that names a `source` table becomes push-driven the same way.
+- The roster is push-driven: `presence.list` declares a [reactivity channel](/docs/data/subscriptions#reactivity-channels) as its `source:`, so the framework re-runs it and pushes deltas over the subscription transport — no client polling. There is **no table**, and there is no longer a table NAME either: presence used to declare `_voltro_presence` and never write to it, purely to own a name the reactivity layer would route on. If you have an existing `_voltro_presence`, it is empty and the upgrade does not drop it (the differ never plans a drop for a framework table no app declares) — remove it by hand when convenient.
+- **A repeat heartbeat does not push.** Measured on this machine at 2.7 µs per subscriber per publish, an unconditional push cost a steady room of N clients N² × that per heartbeat interval — ~107 ms of CPU per 15s at N=200, and a per-node ceiling around 750 subscribers that nothing in the app controlled. Publishing only on a real change removes that term entirely; what remains is linear in actual roster churn. Reproduce with `node --import tsx packages/plugin-presence/scripts/rosterFanoutBody.ts`.
+- **A member has no `lastSeen`.** It used to, and it was the owning replica's clock — "active 3 minutes ago" rendered from it is wrong by whatever the skew between two pods is. Use `meta` for anything you need to show.
 - A member counts as online for `timeoutMs` after its last heartbeat. The sweep runs every `timeoutMs / 3`, so a vanished member is gone within roughly 1.3× the window.
 - The sweep needs **no cluster coordination**, and that follows from the design rather than being a shortcut: every member is owned by exactly one replica and nobody else may touch it, so each replica sweeps its own and there is nothing to contend over. (The table version *did* need coordination — its rows were shared.)
 

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

@@ -22,6 +22,15 @@ upgrade — never the individual calls. The Effect-native rpc interceptors are
 the only surface that sees each call **and** the resolved subject (needed for
 per-tenant limits).
 
+> **This plugin is opt-in, and nothing rate-limits your RPC surface until you add it.**
+> There is no built-in per-IP, per-API-key or per-tenant request cap — an app that
+> does not install and configure `@voltro/plugin-ratelimit` accepts calls as fast as
+> they arrive. The one throttle that *is* on by default is `plugin-auth`'s
+> [brute-force lockout](/docs/authentication/passwords#brute-force-lockout) on sign-in,
+> and it only covers credential attempts. Put a per-IP cap at your ingress as well —
+> see [production hardening](/docs/deployment/production-hardening); that layer holds
+> per-IP state across replicas, which an in-process limiter cannot.
+
 Live — `demo.limited` is capped at 5/min per visitor; the 6th call within a
 minute fails with the typed `RateLimited` error (carrying `retryAfterMs`):
 

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

@@ -24,15 +24,19 @@ export default {
   name: 'api',
   plugins: [
     searchPlugin({
-      // backend: defaults to memory (dev). Swap for production:
-      // backend: typesenseBackend({ url, apiKey }) | meilisearchBackend({ ... }) | algoliaBackend({ ... })
+      // backend: defaults to memory — dev + tests only. Under NODE_ENV=production
+      // the memory backend REFUSES TO BOOT (see "The memory backend refuses to
+      // boot in production" below). Name a durable engine for a deployment:
+      // backend: { engine: 'typesense', url, apiKey } | { engine: 'meilisearch', … } | { engine: 'algolia', appId, apiKey }
       indexes: {
         posts: {
           index: 'posts',
           tenantField: 'tenantId',                       // index documents carry the tenant → query scopes by it
+          queryableFields: ['title', 'body', 'status'],  // optional: fields a caller may filter/facet/highlight on
           map: (row) => ({ id: String(row.id), title: String(row.title), body: String(row.body) }),
         },
       },
+      // allowedEngineParams: ['query_by'],               // optional: widen the engineParams allowlist (see below)
     }),
   ],
 }
@@ -44,6 +48,50 @@ The plugin declares `onChangeEvent`. On every committed write to a configured ta
 
 For pre-existing rows, `backfillIndex(backend, spec, rows)` indexes the rows you supply (call it from a `*.startup.tsx` or a one-off script) — or use the **Reindex** button / `POST /reindex` inspect endpoint, which reads the table's current rows for you.
 
+## When the engine is down
+
+The database commit has already happened by the time the tap runs, so a failed index write is **drift**: the row is in your database and missing from — or stale in — your index. That is not left to a log line.
+
+1. **Retry.** A failure the backend marks *transient* (network, engine unavailable, 5xx, rate limited) is retried inside the tap's own Effect with capped exponential backoff. A *permanent* failure — an unsupported query shape, a `map(row)` that throws on one row's shape — is **not** retried: repeating it cannot succeed, and it lands in step 2 immediately.
+2. **Record.** A change that outlives the retry is written to the framework-owned `_voltro_search_drift` table, one row per `(index, source row)`. Nothing is lost at that point: the entry lives in your own database — the thing that just committed successfully — while the search engine is what is down.
+3. **Repair.** A cluster-coordinated sweep re-reads each recorded row **from the database** and re-derives its document. It never replays the failed event, and that is what makes repair order-free and idempotent: a row updated three times during an outage converges in one pass, and a row deleted since the failure converges to a removal.
+
+The one case that is still a loss is the engine failing **and** the ledger write failing — and that one fails the tap loudly rather than reporting success.
+
+Every number here is yours to set (defaults shown):
+
+```ts
+searchPlugin({
+  indexes: { /* … */ },
+  sync: {
+    retries: 5,               // retries after the first attempt; transient failures only. 0 disables retry
+    retryBaseDelayMs: 200,    // first backoff — doubles per attempt
+    retryMaxDelayMs: 10_000,  // ceiling for any single wait
+    resyncIntervalMs: 60_000, // repair-sweep interval. 0 turns the sweep off (POST /resync still repairs on demand)
+    resyncBatchSize: 200,     // max ledger entries repaired per sweep
+  },
+})
+```
+
+Drift is visible **without reading logs**:
+
+| Endpoint | Shows |
+|---|---|
+| `GET /_voltro/inspect/plugins/search/indexes` | per index: `dropped`, `pendingDrift`, `lastDriftAt`, `drifted` — plus the retry policy actually in force |
+| `GET …/search/drift` | the failing rows themselves, oldest first, with their last error and attempt count |
+| `POST …/search/resync` | runs a repair pass now (`{ scanned, repaired, failed }`) |
+
+An entry whose `attempts` keeps climbing is telling you something a retry cannot fix — a `map(row)` that throws on that row, a document the engine rejects. That is the case to look at by hand; everything else drains on its own.
+
+`_voltro_search_drift` is applied by the declarative differ on `voltro db apply` and on a `voltro dev` boot, on every dialect — there is nothing to migrate.
+
+### Under multiple replicas
+
+Index **writes** and index **counters** are deliberately treated differently when your store's change scope is `fleet` (every replica receives every change — postgres `LISTEN/NOTIFY` CDC, for instance):
+
+- **The write runs on every replica.** An `upsert`/`remove` of the same document is idempotent, so a duplicate costs write amplification — while electing a single writer would cost a *lost* update whenever that replica dies mid-change, and would import the leadership-gap window with it.
+- **The count runs everywhere too, but is aggregated as a maximum.** Each replica's stats row is already a fleet-wide count of the same changes, so `/indexes` takes the highest rather than the sum — the panel reports one sync per change, not one per replica. Under `local` scope only the replica that actually made the write counts (peers see an echo), and the rows are summed. Neither path needs a leader, so neither has a window in which counting stops.
+
 ## Querying
 
 `search.query` is a typed **action** (not a streaming query — search results aren't reactive):
@@ -90,27 +138,130 @@ const res = await backend.query('posts', {
 - **facets** — per-value counts for the named fields (over the full matched set, before paging).
 - **highlight** — matched-term snippets per field, returned as `hit.highlights[field]`.
 - **fuzziness** — a max edit distance (`0` = exact) or `'auto'`.
-- **engineParams** — an escape-hatch bag forwarded verbatim into the underlying engine's search call. Ignored by the memory backend.
+- **engineParams** — the engine's **presentation-only** params (see the next section). Ignored by the memory backend.
 
 Native support degrades honestly: memory, Typesense, Meilisearch and Algolia all do filters/facets/highlighting; Typesense honors a numeric typo count (`num_typos` 0–2) while Meilisearch and Algolia only toggle typo tolerance on/off (`fuzziness: 0` disables it, other values keep their built-in tolerance). A backend op fails with a typed `SearchBackendError`.
 
+## What the server validates
+
+`search.query` is a public wire surface, and three of its inputs — the index name, the field names, and `engineParams` — become the search engine's **control plane**. The plugin validates all three server-side, before the engine sees them, and refuses with a typed error rather than answering a query it cannot scope:
+
+| Input | Rule | On violation |
+|---|---|---|
+| `index` | must be one of the indexes you declared in `searchPlugin({ indexes })` | `SearchIndexNotFound` |
+| `filters[].field`, `facets[]`, `highlight.fields[]` | a plain field path (`^[A-Za-z_][A-Za-z0-9_.]*$`), and — if the index declares `queryableFields` — one of those | `SearchFieldRejected` |
+| `engineParams` | only the engine's presentation-only keys (paging, ordering, typo tolerance, highlight shaping) | the key is dropped and logged |
+
+```ts
+import { SearchFieldRejected, SearchIndexNotFound } from '@voltro/plugin-search'
+```
+
+Why each one, because the reasoning is what tells you whether your own declaration is tight enough:
+
+- **An unknown index has no spec, therefore no `tenantField`, therefore no tenant clause.** Answering it would run the caller's query unscoped against whatever collection of that name exists on your engine — and a Typesense / Meilisearch / Algolia instance is usually shared with indexes this app never declared. It is refused, not answered empty.
+- **A field name is spliced into the engine's filter DSL.** Typesense's `filter_by` is one flat string that supports `||`, so a crafted name can re-group the boolean tree around the tenant clause appended after it. The identifier pattern is the floor every index gets; `queryableFields` narrows it further to what your UI actually needs. Your `tenantField` does **not** belong in that list — the tenant clause is injected after this check, by the server, and is never a caller's to name.
+- **`engineParams` is not a filter hatch.** It used to be merged last into the engine's params, so a caller could set `filter_by` (Typesense), `filter` (Meilisearch) or `facetFilters` (Algolia) and overwrite the tenant clause. Keys that could select a different document set — those, plus `query_by`, `restrictSearchableAttributes`, `preset`, `pinned_hits`, `enableRules`, … — are dropped. Express a filter as a `filters[]` clause instead: those are validated *and* ANDed with the tenant scope rather than replacing it.
+
+If your app genuinely needs one more engine key, widen the allowlist **server-side**, where it is a deliberate decision instead of a caller's:
+
+```ts
+searchPlugin({
+  indexes: { /* … */ },
+  allowedEngineParams: ['query_by'],   // this app trusts callers with this key
+})
+```
+
+Document-selecting keys stay refused even when listed there — that is the authority the tenant clause holds.
+
 ## Backends
 
 | Backend | Notes |
 |---|---|
-| `memoryBackend` (default) | Fully in-process; dev + tests. Not for production scale. |
+| `memoryBackend` (default) | Fully in-process; dev + tests. **Refuses to boot under `NODE_ENV=production`** — see below. |
 | `typesenseBackend` | Optional dep `typesense`. Lazy-loaded. |
 | `meilisearchBackend` | Optional dep `meilisearch`. Lazy-loaded. |
 | `algoliaBackend` | Optional dep `algoliasearch`. Lazy-loaded. |
 
 A backend is the `SearchBackend` interface (`upsert` / `remove` / `query`) — bring your own (OpenSearch, Elastic, …).
 
+### The memory backend refuses to boot in production
+
+This is a **refusal, not a warning, and not a scale caveat**. Under
+`NODE_ENV=production` on the in-memory backend, `onActivate` throws
+`SearchBackendNotDurable` and the process does not start:
+
+```text
+plugin-search refuses to boot in production on the in-memory backend.
+
+The memory index lives in THIS process's heap. Two consequences, both silent:
+  • every replica holds a different index, so a result depends on which replica served you;
+  • the index starts EMPTY after every restart/deploy, and nothing re-seeds it automatically.
+
+Configure a durable engine in app.config.ts:
+  searchPlugin({ backend: { engine: 'typesense',    url: …, apiKey: … }, indexes })
+  searchPlugin({ backend: { engine: 'meilisearch',  url: …, apiKey: … }, indexes })
+  searchPlugin({ backend: { engine: 'algolia',      appId: …, apiKey: … }, indexes })
+or pass your own `SearchBackend` implementation.
+```
+
+**Running one replica does not make it correct**, which is why the refusal is
+not conditional on detecting a cluster. Two independent things are wrong with an
+in-process index in a deployment and only one of them is the multi-replica
+story:
+
+1. **Per-process.** N replicas hold N divergent indexes. Which results you get
+   depends on which replica served the request — including *zero hits* for a
+   document that demonstrably exists.
+2. **Non-durable.** The index lives in the heap, so every restart and every
+   deploy starts EMPTY and nothing re-seeds it: `backfillIndex` is a function
+   your app calls, not something the plugin does at boot.
+
+(2) is what a single replica does not fix. It only removes one of the two ways
+the backend is wrong.
+
+Dev is **silent** — the memory backend is exactly right there, and a warning
+that fires on every `voltro dev` boot is a warning nobody reads.
+
+#### The escape hatch — `singleProcessMemoryIndex`
+
+If this deployment genuinely is ONE process that re-seeds its index at startup,
+say so and the boot proceeds:
+
+```ts
+searchPlugin({
+  singleProcessMemoryIndex: true,   // exactly one process, and it calls backfillIndex at startup
+  indexes: { /* … */ },
+})
+```
+
+Two things to be clear about before you reach for it:
+
+- **It is a claim about your topology, not a mute switch.** The plugin holds you
+  to both halves: exactly one process serves search, and a `*.startup.tsx`
+  calls `backfillIndex` for every index — because the index *is* empty after
+  each restart until something fills it. The boot logs a `note` at info
+  restating what you signed up for.
+- **The plugin checks the claim against reality.** When the instance-membership
+  registry reports that a peer replica joined, the plugin logs that the
+  declaration is now false — in *any* environment, because a peer announcing
+  itself is an observation rather than a guess about `NODE_ENV`:
+
+  ```text
+  search: replica "<id>" joined, but this app declared `singleProcessMemoryIndex: true`.
+  That declaration is now false: each replica has its own in-memory index, so search
+  results depend on which one serves the request. Configure a durable backend
+  (typesense / meilisearch / algolia) or run one process.
+  ```
+
+  Without the declaration, a peer joining while search is served from a heap
+  index warns too — same observation, different wording.
+
 ## Dashboard panel
 
 Both dashboards ship a **Search** panel (api apps): the configured indexes with per-index sync stats (docs synced/removed, last reindex) + the resolved backend, and a **Reindex** button per index that re-seeds it from the table's current rows (`backfillIndex`). Reindex gates on the `canReindexSearch` capability. Backed by `/_voltro/inspect/plugins/search/{indexes,reindex}`.
 
-The sync stats behind this panel are **durable and aggregated across replicas**. They live in a framework-owned `_voltro_search_stats` table (contributed via `extendSchema.tables`; the plugin declares `store:write`), one row per `(index, replica)`, each bumped with an atomic compare-and-set. `/indexes` sums every replica's row and takes the most-recent reindex — so the counts are truthful under multiple instances and survive a restart (they no longer reset with the process, and no replica under-reports the fleet total). Zero-infra dev/tests use an in-process stats store; `bindDataStore` swaps in the durable one at boot.
+The sync stats behind this panel are **durable and aggregated across replicas**. They live in a framework-owned `_voltro_search_stats` table (contributed via `extendSchema.tables`; the plugin declares `store:write`), one row per `(index, replica)`, each bumped with an atomic compare-and-set. `/indexes` aggregates every replica's row — summed under `local` change scope, maxed under `fleet` (see [Under multiple replicas](#under-multiple-replicas)) — and takes the most-recent reindex, so the counts are truthful under multiple instances and survive a restart. Zero-infra dev/tests use an in-process stats store; `bindDataStore` swaps in the durable one at boot, along with the drift ledger.
 
 ## Permissions
 
-`store:changes:read` (the ChangeEvent tap) + `store:write` (the durable `_voltro_search_stats` counters) + `inspect:read` (dashboard panel) + `network:outbound:<host>` (for a remote backend).
+`store:changes:read` (the ChangeEvent tap) + `store:write` (the durable `_voltro_search_stats` counters and the `_voltro_search_drift` ledger) + `inspect:read` / `inspect:write` (dashboard panel, incl. reindex + resync) + `network:outbound:<host>` (for a remote backend).

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/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