@voltro/cli 0.50.1 → 0.52.0

package/templates/agent-docs/schema-driven-ui.md

@@ -199,8 +199,8 @@ A combined create-or-edit screen is a three-line wrapper:
 - **Rung 3 — own the layout.** Pass children + arrange `<Field>`s (columns,
   sections, tabs); each still auto-renders.
 - **Eject (headless).** `useFormBinding('app', 'todos.create')` returns
-  `{ fields, values, errors, isValid, pending, setValue, submit, reset }` for
-  100% custom JSX — the binding stays.
+  `{ fields, values, errors, formError, isValid, pending, setValue, submit, reset }`
+  for 100% custom JSX — the binding stays.
 
 ### Accessible by default
 
@@ -214,6 +214,82 @@ Schema.Struct({
 })
 ```
 
+### Forms without JavaScript
+
+On a server-rendered page, `<AutoForm>` works with JavaScript disabled — or not
+yet loaded. It always renders `action="/form/<mutationTag>"` + `method="post"`,
+so the browser has a native form-POST fallback; with JavaScript, `onSubmit`
+intercepts as before (the RPC path, optimistic — unchanged).
+
+The `/form/<mutationTag>` endpoint is mounted by the WEB listener on both boot
+paths (`voltro dev` AND `voltro start`). It maps the posted `FormData` against
+the SAME input schema the RPC path decodes:
+
+- a checkbox present → `true`, absent → `false`
+- `''` on a number/date field → the field is omitted (an optional field stays
+  absent; a required one reports "missing" — never a silent `0`)
+- arrays arrive as repeated keys (`getAll` semantics)
+- a non-numeric string passes through RAW, so the decode fails honestly (never
+  `NaN`)
+- unknown keys are dropped
+
+Validation runs through the same `validateFields` as the client-side
+validation, so the error texts are identical. Then:
+
+- **Success → `303 See Other`** (POST-redirect-GET): back to the submitting
+  page, or to `redirectTo` (same-origin relative paths only; anything else is
+  discarded). Reloading the target page never produces a second write.
+- **Validation error → `422`**: the referer page is re-rendered in the same
+  response, with the field errors and the entered values server-side in the
+  same error UI (`role="alert"`, aria unchanged) — sent with
+  `cache-control: no-store`, past the ISR cache. An RPC error AFTER valid
+  input (a guard, the server) renders as a form-level error (`role="alert"`,
+  `data-voltro-form-error`).
+- **Multipart → `415`** ("file uploads need JavaScript").
+
+Three props exist for this path:
+
+- **`formKey?: string`** — distinguishes several forms on one page in the
+  no-JS round-trip (default: the mutation tag); the 422 re-render fills only
+  the submitted form.
+- **`redirectTo?: string`** — where the success `303` goes (no-JS path only;
+  with JavaScript, `onSuccess` applies). A same-origin relative path.
+- **`action?: false`** — renders no `action` attribute, for pure
+  static-hosting deploys (dist on a CDN without `voltro start`), where
+  `/form/*` does not exist.
+
+**On SSR pages, pass `schema` explicitly.** Descriptor resolution
+(`descriptors[tag].input`) is a client-runtime feature; the SSR render sees an
+empty descriptor map and would render zero fields without the `schema` prop.
+Recommended source: import the schema from a shared browser-safe file — the
+same one the mutation uses. One schema, no drift.
+
+```tsx
+export const renderMode = 'ssr' as const
+
+<AutoForm api="app" mutation="notes.create" schema={noteInput} redirectTo="/thanks" />
+```
+
+Three limits, and this list is complete:
+
+1. **The no-JS ERROR display** (the 422 re-render) works only on `ssr`/`isr`
+   pages — the server cannot re-render a static page with request state
+   (fallback: a minimal error page).
+2. **Pure static-hosting deploys** (dist on a CDN, no `voltro start`) have no
+   `/form/` endpoint — set `action={false}` there.
+3. **File uploads stay JS-only** (multipart → `415`).
+
+Security-wise, the endpoint forwards server-side to the api as `POST /rpc` —
+auth middleware, guards and RPC interceptors run identically to the normal RPC
+path; details, including the one boundary, in the
+[security overview](/docs/security/overview).
+
+Headless: `useFormBinding` now takes a `flash` option and returns a
+`formError` field; `useFormFlash(formKey)` (`@voltro/web`) returns the flash —
+on SSR from the request context, on the client from the
+`#__voltro_form_flash__` JSON script. Both are identical, so hydration is
+deterministic.
+
 ## `<DataTable>` — bind to a QUERY
 
 Columns come from the query's output `Schema`; rows are a LIVE subscription

package/templates/agent-docs/security.md

@@ -172,7 +172,8 @@ one machine is invisible to code review.
 ## Cross-site requests are refused
 
 **Every request that can change state is checked** — anything but `GET`, `HEAD`
-and `OPTIONS` — plus the `/ws` upgrade, which is a GET. That is deliberately a
+and `OPTIONS` — plus **every WebSocket upgrade**, which is a GET: the rpc
+socket's `/ws` AND every raw gateway path a `*.ws.ts` file mounts. That is deliberately a
 rule about the METHOD rather than a list of paths, because a mutation reaches
 your api by more than one road: `POST /rpc`, every REST route projected from a
 `publicApi:` mutation, everything in `apiConfig.restRoutes`, and
@@ -192,6 +193,43 @@ bearer/JWT flow.
 Reads are not checked: a `GET` cannot be a cross-site write, and checking it
 would break every link into your api.
 
+### Raw WebSocket gateways are guarded before the upgrade
+
+A [`defineWebSocket` gateway](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket)
+mounts its own upgrade path beside the rpc socket, and the listener treats it
+exactly like the rpc upgrade:
+
+- **Origin-checked BEFORE the upgrade.** An upgrade is a GET, so the
+  state-changing rule above never covers it — every gateway path therefore
+  joins the upgrade origin guard's set, and a cross-origin upgrade is `403`.
+  That closes cross-site WebSocket hijacking for every gateway, not only the
+  framework's own socket.
+- **Authenticated BEFORE the upgrade.** `auth` is required with no default:
+  `'subject'` resolves the caller through the SAME auth chain as rpc/SSR and
+  answers `401` while the request is still plain http — no socket ever exists
+  for an unauthenticated caller — and the connection is bound to the
+  credential's expiry (application close code `4001`, so a foreign client can
+  re-auth and reconnect). `'public'` is a decision somebody wrote down, not a
+  default anyone fell into.
+
+### The web listener's `/form/*` endpoint is checked the same way
+
+`<AutoForm>`'s no-JavaScript fallback POSTs to `/form/<mutationTag>` on the
+**web** listener — mounted on both boot paths, `voltro dev` and `voltro start`.
+That is a state-changing surface too, and it is classified by the same
+`classifyRequestOrigin` as the api rpc listener: a cross-origin form POST gets
+the same `403`.
+
+Behind the check, the endpoint forwards the request server-side to the api as
+`POST /rpc` — auth middleware, guards and rpc interceptors run identically to
+the normal rpc path, with the session resolved from the cookie exactly as an
+SSR render resolves it.
+
+One boundary, stated explicitly: `@voltro/plugin-ratelimit`'s **pre-auth IP
+shield** runs only on the api listener and never sees `/form/*`. The
+ratelimit **rpc interceptor** does see every write, because the endpoint
+reaches the api as `POST /rpc` like any other mutation.
+
 ### A split web/api deployment must declare its origins
 
 If your web app is served from a different origin than your api, say so — or
@@ -307,6 +345,18 @@ signed ticket the attacker does not have", the route is exempt. Otherwise it is
 not. The exemption covers the route's whole path prefix, not the sub-paths its
 handler branches on.
 
+## Shared (isr) renders never see credentials
+
+An `isr` page's HTML is cached and served to every visitor inside its
+revalidate window — a shared artefact. The framework therefore strips
+credential material before the render runs: the cookie jar (except
+`voltro:locale`), `authorization`, and every `x-voltro-*` header never reach an
+isr page's loaders, `ctx.query`, or `useServerRequest()`. A subject-reading
+loader gets the anonymous answer instead of caching one user's data for
+everyone, and the strip applies identically under `voltro dev` and
+`voltro start`. Details: [Render modes → isr renders are
+anonymous](/docs/routing/render-modes).
+
 ## The client IP comes from the socket, not from a header
 
 `x-forwarded-for` is a request header, so **any client can write it**. Voltro
@@ -420,6 +470,17 @@ Environment overrides: `VOLTRO_SECURITY_HEADERS` (`off|default|strict`),
 just that one. Embedders pass the same object as
 `RpcServerOptions.security.headers`.
 
+### A nonce-based CSP for the web app's HTML
+
+The headers above are the **api** listener's. For the web app's rendered HTML,
+`middleware.ts` can mint a per-request `cspNonce`: the framework stamps
+`nonce="…"` onto every script tag of that render — the state script, the
+deferred registry, the shell's bundle tags, and React's own bootstrap/settle
+scripts — while the policy header itself stays the middleware's to set via
+`responseHeaders`, carrying the same nonce. An `isr` page combined with
+`cspNonce` refuses the render: a cached nonce is a lie the browser enforces.
+Mechanics + examples: [Middleware → cspNonce](/docs/routing/middleware#a-per-request-csp-nonce--cspnonce).
+
 ## Incoming webhooks must verify their caller
 
 An incoming webhook is a **public POST that runs your application code**. A
@@ -474,13 +535,23 @@ row never fails; it is there so a deliberately public URL is visible in a review
 instead of only in a boot log. Both rows are in `voltro doctor --json` under
 `webhookVerification`.
 
-## The rpc body cap counts bytes as they arrive — and answers 413 either way
+## The body cap applies EVERYWHERE — and answers 413 either way
+
+The 8-MiB body cap covers every surface that reads a request body: `POST /rpc`
+(as it always did, `VOLTRO_MAX_RPC_BODY_BYTES`), plugin HTTP routes, REST
+routes and incoming webhooks — whose read is also **binary-clean** now (it used
+to round-trip through UTF-8, corrupting binary payloads). The non-rpc cap is
+`http.maxBodyBytes` in `app.config.ts` (env `VOLTRO_MAX_BODY_BYTES`), with
+per-route overrides on `defineRestRoute({ maxBodyBytes })` and on a webhook
+handler's `maxBodyBytes` — fat provider payloads are the normal case there.
+Routes **sharing a path share one body read**, so the widest override in the
+group applies to the group.
 
-`POST /rpc` is capped at 8 MiB (`VOLTRO_MAX_RPC_BODY_BYTES`). The limit is
-enforced **while the body streams**, so a `Transfer-Encoding: chunked` request
-with no `Content-Length` is cut off at the cap rather than buffered without
-bound. A declared oversize length is still rejected up front, so an honest client
-gets its `413` without uploading anything.
+The limit is enforced **while the body streams**, so a
+`Transfer-Encoding: chunked` request with no `Content-Length` is cut off at the
+cap rather than buffered without bound. A declared oversize length is still
+rejected up front, so an honest client gets its `413` without uploading
+anything.
 
 **Both shapes end in the same response:**
 
@@ -497,6 +568,52 @@ size — it is not read).
 Uploads ride separate plugin routes with their own `limits.maxBytes`, and are
 unaffected.
 
+## The global HTTP interceptor is fail-closed
+
+The pre-auth plugin hook (`onHttpRequest`) wraps every request, which makes it
+a place people put security gates — rate limits, geo-blocks, bot detection. A
+gate that crashes must not become an open door, so **a throwing interceptor is
+a `500` plus a log line; the request does not continue**. It used to: the
+failure was swallowed and the request flowed on, silently, which is the worst
+possible failure mode for exactly the code this hook attracts.
+
+An interceptor that wants to tolerate its OWN outage — protection with a
+dependency, like a rate-limit counter in Redis — catches internally and
+degrades **loudly**. `@voltro/plugin-ratelimit`'s `httpShield` does exactly
+that: a Redis outage means unlimited-with-a-warning, never a self-inflicted API
+outage. The full authoring guidance is in the
+[plugin contract](/docs/plugins/contract#onhttprequest-httprequestinterceptor--pre-auth-http-pipeline-hook).
+
+## Response compression — and where BREACH sits
+
+Buffered responses are compression-negotiated on both boot paths: brotli
+preferred, gzip as the fallback, a client's `q=0` respected. Only an allowlist
+of compressible types is touched (`text/*`, `application/json`,
+`application/javascript`, `application/xml`, `image/svg+xml`), nothing under
+1 KiB is compressed, and `Vary: Accept-Encoding` is set on every compressible
+type — including responses that go out uncompressed, so caches never mix
+encodings. It covers the api's plugin/REST/webhook responses AND the HTML
+`voltro start` serves. Streams and SSE are never compressed. Config:
+
+```ts
+// app.config.ts
+export default {
+  http: { compression: { enabled: true, minBytes: 1024 } },
+}
+```
+
+**The BREACH position is structural, not a tuning knob:** `POST /rpc`
+responses are NEVER compressed — that is where session-authenticated reads
+flow, the exact combination (secret + attacker-reflected input + compression
++ observable length) the attack needs. The residual risk is an
+**authenticated REST route** that carries a secret next to reflected caller
+input in one response; an app with such a route sets
+`http.compression.enabled: false`.
+
+One cache note: an `isr` page's cache holds ONE uncompressed entry and
+compresses per hit (brotli q4, single-digit milliseconds) — caching a variant
+per encoding would have multiplied the memory for no measurable win.
+
 ## Logs are redacted by default
 
 Every logger surface — `createLogger`, `makeLogger`, `LoggerLayer` — installs a redactor with no configuration, and it runs **before** formatting and **before** the sink fan-out, so a masked value reaches neither stdout nor any downstream sink (the CLI buffer, logship, Datadog).
@@ -570,7 +687,7 @@ Every hit line names the needles that matched, with the number of rows each appe
 
 The predicate is a substring match over the whole serialized column, so a match is a match on a *name*, wherever it sits. The third line above is a bounded second pass that reads the matched rows back and says what actually matched — a JSON **key**, or only a **redaction marker**. Values are never printed and never logged.
 
-A redaction marker is the framework's own record that a credential was deliberately *not* stored: `_omitted` (`@voltro/plugin-versioning`, the column names left out of a row snapshot) and `__redacted` (`@voltro/plugin-audit`). A target whose every matched row is one of those is reported as explained, and does **not** fail CI:
+A redaction marker is the framework's own record that a credential was deliberately *not* stored: `_omitted` (`@voltro/plugin-row-history`, the column names left out of a row snapshot) and `__redacted` (`@voltro/plugin-audit`). A target whose every matched row is one of those is reported as explained, and does **not** fail CI:
 
 ```
 ~  _voltro_row_history.data — 69 of 149 row(s) contain a credential-shaped NAME (anywhere in the value)

package/templates/agent-docs/templates/apibackends.md

@@ -2881,40 +2881,40 @@ Replace `keywordProvider([...])` with `aiProvider()` — the rules don't change.
 
 ---
 
-<!-- source: en/templates/api-versioning.md -->
-## API · Versioning
+<!-- source: en/templates/api-row-history.md -->
+## API · Row history
 
-_Full row history + time-travel with @voltro/plugin-versioning — snapshots every insert/update/delete on the listed tables via the post-commit change tap; read every version with rowHistory() and the value at a past instant with rowAsOf(). audit() is who/when; this is what-changed-to-what. Memory store, zero infra._
+_Full row history + time-travel with @voltro/plugin-row-history — snapshots every insert/update/delete on your tables (every table by default — narrow with include/exclude) via the post-commit change tap; read every version with rowHistory() and the value at a past instant with rowAsOf(). audit() is who/when; this is what-changed-to-what. Memory store, zero infra._
 
-Every version of a row, queryable. `@voltro/plugin-versioning` rides the post-commit ChangeEvent tap and records a FULL snapshot of every insert/update/delete on the listed tables. Read it back with `rowHistory(store, table, id)` (every version) and `rowAsOf(store, table, id, when)` (the value at a past instant — time-travel). `audit()` records WHO/WHEN; this records WHAT it changed to, so you can diff or restore. Memory store, zero infra. Template id: **`api-versioning`**.
+Every version of a row, queryable. `@voltro/plugin-row-history` rides the post-commit ChangeEvent tap and records a FULL snapshot of every insert/update/delete on your tables — every table by default, narrowed with `include:`/`exclude:`. Read it back with `rowHistory(store, table, id)` (every version) and `rowAsOf(store, table, id, when)` (the value at a past instant — time-travel). `audit()` records WHO/WHEN; this records WHAT it changed to, so you can diff or restore. Memory store, zero infra. Template id: **`api-row-history`**.
 
 ## Scaffold
 
 ```bash
-voltro create-project acme --api=api-versioning
+voltro create-project acme --api=api-row-history
 ```
 
 ## Wire it + read it back
 
 ```ts
 // app.config.ts
-import { versioningPlugin } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin } from '@voltro/plugin-row-history'
 export default { type: 'api', name: 'AcmeVer', store: 'memory',
-  plugins: [versioningPlugin({})] }
+  plugins: [rowHistoryPlugin({})] }
 ```
 
 The snapshotting is automatic. The point is to **read history through handlers** — the template ships two actions:
 
 ```ts
 // documents.history.action.server.ts
-import { rowHistory } from '@voltro/plugin-versioning'
+import { rowHistory } from '@voltro/plugin-row-history'
 export default async ({ id }, ctx) => {
   const rows = await rowHistory(ctx.store, 'documents', id, ctx.request.subject.tenantId ?? null)
   return rows.map((r) => ({ version: r.version, op: r.op, content: r.data?.content ?? null, changedAt: r.changedAt }))
 }
 
 // documents.asOf.action.server.ts
-import { rowAsOf } from '@voltro/plugin-versioning'
+import { rowAsOf } from '@voltro/plugin-row-history'
 export default async ({ id, at }, ctx) =>
   rowAsOf(ctx.store, 'documents', id, ctx.request.subject.tenantId ?? null, at)  // the row as it was at `at` (epoch ms), or null
 ```
@@ -2933,14 +2933,14 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
 # documents.asOf with v1's changedAt → { content:"draft v1" }  (time-travel)
 ```
 
-## audit vs versioning
+## audit vs row-history
 
 | You want… | Use |
 |---|---|
 | WHO changed a row + WHEN | `audit()` mixin |
-| WHAT it changed to (every prior value) | `@voltro/plugin-versioning` (this) |
+| WHAT it changed to (every prior value) | `@voltro/plugin-row-history` (this) |
 
-They compose — `audit()` for accountability, versioning for diff/restore.
+They compose — `audit()` for accountability, row-history for diff/restore.
 
 ## Production
 
@@ -2948,8 +2948,8 @@ The memory history store is single-process. With a SQL store, history persists i
 
 ## Anti-patterns
 
-- **Listing `versioningPlugin()` and stopping there.** That records history but never shows it. The value is in the READS — wire `rowHistory` / `rowAsOf` into a handler (or the dashboard) like this template does.
-- **Versioning every table.** Snapshots cost storage proportional to write volume. Pick the tables whose past values you actually need.
+- **Listing `rowHistoryPlugin()` and stopping there.** That records history but never shows it. The value is in the READS — wire `rowHistory` / `rowAsOf` into a handler (or the dashboard) like this template does.
+- **Keeping history for every table.** Snapshots cost storage proportional to write volume. Pick the tables whose past values you actually need.
 
 
 

package/templates/agent-docs/templates/overview.md

@@ -54,7 +54,7 @@ The `api-backend*` shapes share the same minimal `notes` domain and differ only
 | [`api-ratelimit`](/docs/templates/api-ratelimit) | **Per-endpoint rate limiting** — `@voltro/plugin-ratelimit` intercepts rpc: a default + rules (sliding-window / token-bucket, by subject/tenant/…), typed `RateLimited` auto-merged into the error union. Memory store. |
 | [`api-rbac`](/docs/templates/api-rbac) | **Role → scope access control** — `@voltro/plugin-rbac`: a role map, an interceptor resolving roles to scopes, and an in-handler `permission(ctx, 'notes:write')` guard (typed `ScopeError`). `admin:full` bypasses. Config-only. |
 | [`api-moderation`](/docs/templates/api-moderation) | **Pre-commit content moderation** — `@voltro/plugin-moderation` checks fields before the handler: a `block` rule rejects with typed `ContentRejected`, a `flag` rule queues for review. keywordProvider / aiProvider. |
-| [`api-versioning`](/docs/templates/api-versioning) | **Row history + time-travel** — `@voltro/plugin-versioning` snapshots every write via the change tap; `rowHistory()` (every version) + `rowAsOf()` (value at a past instant), read through handlers. Memory store. |
+| [`api-row-history`](/docs/templates/api-row-history) | **Row history + time-travel** — `@voltro/plugin-row-history` snapshots every write via the change tap; `rowHistory()` (every version) + `rowAsOf()` (value at a past instant), read through handlers. Memory store. |
 | [`api-backend-deactivation`](/docs/templates/api-backend-deactivation) | **The `deactivation()` mixin** — lock a user out (`deactivatedAt`) while the row stays VISIBLE/queryable — the deliberate opposite of `softDelete()`'s hide+anonymise. Pure schema. |
 | [`api-governance`](/docs/templates/api-governance) | **Field encryption + GDPR + consent + retention** — `@voltro/plugin-governance`: AES-256-GCM `.encrypted()` columns (plaintext to handlers, ciphertext at rest), admin-gated `governance.export`/`erase`, a consent ledger, retention sweeps. |
 | [`api-collab`](/docs/templates/api-collab) | **Local-first / CRDT collaborative editing** — a `documents` table with a `crdtText()` `body`; concurrent edits from many clients CONVERGE via an authoritative server-side merge on the write path (no last-write-wins loser), then broadcast over the reactive engine. Zero-infra; pairs with `frontend-collab`. |