@voltro/database 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -39,6 +39,80 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.41.0] — 2026-08-17
+
+### ⚠ BREAKING
+
+- **@voltro/web, @voltro/cli** — `middleware.ts` exports `defineMiddleware(...)` (from `@voltro/web/middleware`) instead of a bare function, and each export carries its own `match`. Several middlewares per file are allowed; **at most one may match a given route**.
+
+  Migration: the codemod wraps the existing default export. That is behaviour-preserving — no `match` means every server-rendered route, which is what an unwrapped middleware did — and its note explains how to replace a hand-written path gate with a `match`.
+
+  **Why it was worth a break.** A hand-written `if (!req.pathname.startsWith('/app')) return` is invisible: nothing can tell you a middleware runs nowhere, or that two of them claim one route. `match` puts it where both the boot and `voltro doctor` can read it.
+
+  **The matcher speaks ROUTES, not URL patterns** — `under` / `routes` / `except`, validated against the app's own route patterns. A path matching no route refuses the boot instead of silently never firing. This is the deliberate difference from the `'/((?!api|_next/static|…).*)'` shape: our hook runs after route matching, so an app has never needed to know its own asset layout, and non-page requests are reachable only by asking (`assets: true`) — where, note, there is no render, so only `setCookies` takes effect.
+
+  An overlap refuses the boot and names both middlewares plus the route. Declaration order is not a semantic, "most specific wins" silently drops the broader hook, and merging needs a per-field rule nobody remembers — so two hooks writing one `authorization` header is a refusal, not a resolution.
+
+  **The web bundle budget moved UP, and the split is worth stating** because only one half is a cost the framework imposes:
+
+  | measured | before | after | | --- | --- | --- | | first load | 184 955 B | 185 309 B (**+354**) | | lazy route chunks | 3 502 B | 4 415 B (+913) |
+
+  The **+354 B of first load is the real price** — one `serverContext` chunk, 0.2 KB gz, which every app now carries whether or not it declares a middleware. That is the number to argue with, and it leaves 6.7 KB of headroom under the ceiling.
+
+  The +913 B is NOT a per-route regression: the fixture gained four routes (`exact`, `exact/[id]`, `mw`, `mw/skip`) to exercise the feature end to end, at 0.1–0.2 KB gz each, which accounts for the growth without remainder. Re-pinned with `--update` rather than by hand, so the `slackFloor` keeps ratcheting — a ceiling nobody lowers again silently permits re-inflating to the old number.
+
+### Fixed
+
+- **@voltro/data-transfer, @voltro/cli** — `voltro data export` could not export a table whose primary key is not named `id`, and one of its two failure modes reported success.
+
+  The keyset column was `columns.find(c => c.type === 'id')?.name ?? 'id'`, and `type: 'id'` is tagged only on a column that is BOTH the single-column primary key AND literally named `id` — identically in all four dialect introspectors. So any introspected table with another PK name was ordered by a column that does not exist. It now comes from the real primary key (the synthesised `<table>_pkey` index), with the declared `id()` column still winning where there is one.
+
+  **A composite or absent primary key is now REFUSED**, not silently ordered by the first column: keyset pagination on a non-unique order splits equal values across page boundaries, so rows are dropped or duplicated into a bundle that reports success. Bounded exports are recoverable; a quietly short backup is discovered at the restore.
+
+  **A requested table missing from the schema is refused too.** `scope: { kind: 'tables' }` used to drop unknown names, so a run that explicitly named a table wrote `"tables": []` and printed `export complete` with exit 0. `kind: 'all'` over an empty database is still a legal empty export — the asymmetry is deliberate: a named table is an expectation.
+
+  **Failure reasons survive.** `String(e?.message ?? e)` produced `"write table failed: "` with nothing after the colon — `??` falls back on null/undefined, and an Effect `TaggedError` carries an empty-string `message`. Every catch site in the exporter now reports tag, message or cause.
+
+  **New: `voltro data export --exclude a,b`** — everything except these, resolved against the live table list. It is the escape hatch the refusals above require; without it a single unkeyable table would block a whole-database export. An unknown name is refused for the same reason. Direct target only (the expansion needs the live table list), and it expands to an explicit `tables` scope, so the manifest records what was actually exported.
+
+  Reported with a reduced repro, a four-way variation over PK TYPES that ruled type out, and two disproved hypotheses. The affected tables include `@effect/cluster`'s own (`cluster_locks`, `cluster_migrations`), so no app running workflows could take a whole-database export.
+- **@voltro/database, @voltro/runtime, @voltro/cli** — `.encrypted()` had three writers and two encodings. The store wrote `encrypt(JSON.stringify(v))`; `encryptField` — the documented raw-SQL escape hatch — and `voltro db encrypt-column` wrote `encrypt(v)`. All three produce the same `enc:v1:` envelope and nothing distinguished them, so a value written by one and read by another either threw with the wrong diagnosis or came back subtly wrong (`decryptField` handed back the JSON encoding verbatim, quotes and all, raising nothing).
+
+  There is one encoding for every WRITE now, and every READ resolves BOTH forms — so **no data has to be rewritten and nothing is blocked**. That second half is the point: the old form is already on staging and production disks, and a fix that needs the rows rewritten before the app works is an outage with a migration attached.
+
+  Reading two forms is deterministic, not a heuristic. After decrypting, a parse failure is the raw form; a parse to a STRING is the JSON form; a parse to a non-string depends on the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). The one case nothing can separate — a raw secret whose literal text is `"abc"`, quotes included — is stated in the code rather than hidden.
+
+  **`voltro db encrypt-column` verified itself against the wrong decoder.** It wrote the raw form and checked it with `cipher.decrypt` — a decoder nothing reads these columns with — so it reported success over columns the app could not read. It round-trips through `decodeFieldValue` now, the same function the store calls. A self-check against a decoder the runtime does not use is not a weaker check; it is a second opinion from the same mistake.
+
+  The command also NORMALISES rows in the old encoding as it goes (reported separately from the ones it encrypts), so an operator does not write a script per column. It skips anything ambiguous and anything it cannot decrypt.
+
+  **The width pre-flight measured the wrong thing after the encoding changed.** It sized the ciphertext from the PLAINTEXT's byte length while the cipher is handed the JSON encoding — two characters more at minimum, and more for every escape. Measured on a real MariaDB: a 63-byte value in a `varchar(135)` passed the check and the UPDATE answered `ER_DATA_TOO_LONG`, which is the failure that check exists to prevent, mid-column with the rest already converted. It measures the encoded length now, and the refusal says "encodes to" rather than "is" so an operator measuring their own column finds the number it names.
+
+  **Two dialect defects, both found by running the command against real servers.** SQL Server reports `-1` for `NVARCHAR(MAX)` — its spelling of unbounded — and the pre-flight read it as a one-character column, so it refused the widest column the dialect has and printed `declared as -1` at the operator. And SQLITE has no `information_schema` at all: the shared catalog query died there with `Failed to prepare statement` and no statement attached, on a dialect the command claims to support. It uses `pragma_table_info` now, reporting no length because sqlite enforces none.
+
+  Measured end to end on postgres, mysql, mariadb, mssql and sqlite: a table holding plaintext, the old encoding and the current encoding side by side converts, every row decodes back to its original value, a re-run writes nothing, and a wrong key refuses with exit 1.
+
+  **Backups and restores were never affected and now say so.** `voltro data export` reads through the raw dialect store, so ciphertext travels verbatim in either encoding — pinned by a test, because a future change that wrapped that store would put plaintext credentials in a bundle.
+- **@voltro/protocol, @voltro/cli** — Three findings from one consumer round, all of the same shape: something the framework knows and does not say.
+
+  **A decode failure on a GUARDED procedure now says the guard did not run.** The payload decodes before the handler, so a guard on a procedure with a malformed payload never gets the chance to refuse. A consumer auditing a guard called one with an incomplete payload, got a decode error instead of a `ScopeError`, and concluded the guard was not applied — the wrong conclusion in the dangerous direction. The title now carries `(guarded — the guard did NOT run: the payload failed to decode first, so this says nothing about access)`. It discloses nothing new: that a procedure is guarded is already visible to anyone who sends a VALID payload. An `openAccess:` declaration is not an enforced guard and gets no such sentence — `hasEnforcedGuard` is the one predicate, read by both the label and the wire error union, because two copies of that rule would disagree invisibly.
+
+  **`middleware.ts`'s `httpOnly` default is documented at the field, and warned about.** It defaults to `HttpOnly`, which is wrong for a session cookie a browser SDK reads back: Supabase's `createBrowserClient` reads `document.cookie`, so a forgotten `httpOnly: false` gives the browser a session it cannot see — the SSR render is perfect and the user is signed out at the first client-side call. The consumer only avoided shipping it because their probes already set the flag. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; an explicit decision either way silences it, because warning on a decision is how a diagnostic becomes noise.
+
+  **`voltro dev` restarts when `middleware.ts` changes.** It is loaded once per boot, that is documented, and a consumer read it and still lost an afternoon: they sabotaged the middleware, saw no change, and concluded it was not wired — in an environment where everything else hot-reloads. It now restarts through the same respawn a hard-restart field in `app.config.ts` uses, extracted so there is one copy of the `execArgv` inheritance and the signal forwarding.
+- **@voltro/cli** — `middleware.ts` now produces ONE view of the request that every downstream reader takes. Previously only `buildLoaderQuery` saw the hook's result, while the loader context (`ctx.headers`), the SSR request snapshot (`useServerRequest()`) and the locale resolver kept reading the raw request — four readers, two answers, within eighty lines of one function.
+
+  The consequence was worse than an inconsistency: a hook that renews purely via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP and the reason the response half exists — moved nothing for the render that ran it. The rpc call still sent the old `Cookie` header, because a renewed cookie only reached the browser.
+
+  `setCookies` is applied to the cookie jar before the render, the `Cookie` header is rebuilt from that jar (an explicit `cookie` in the hook's own `headers` still wins), and `maxAge <= 0` deletes, so a hook that signs someone out renders them signed out. Both SSR boot paths shadow the raw headers out of scope after the hook runs, so a new reader added below is correct without knowing any of this.
+- **@voltro/cli** — `voltro start` dropped `middleware.ts`'s `Set-Cookie` on **streamed** responses — which is the arm a plain `renderMode: 'ssr'` page takes, so it was the common case. The hook renewed the session server-side, the render used the fresh value, and the browser kept the consumed one. Against an IdP that rotates refresh tokens and detects reuse, that is worse than not renewing at all.
+
+  The cause is worth stating because it read as handled: a streamed response hands the socket to `stream(res)` and the caller never looks at the returned `headers`, so the `withCookies(...)` wrapper on that arm was dead code — sitting under a comment promising the cookies were written on every arm. The cookies now travel with the headers `streamSsrResponse` itself writes, and the dead wrapper is gone.
+
+  Found by booting real `voltro dev` and `voltro start` servers against a fixture and reading the response. Every unit test was green throughout, and the render's own HTML was correct — only the wire was wrong.
+
+---
+
 ## [0.40.0] — 2026-08-16
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -2343,6 +2343,46 @@ export declare const decimal: (precision: number, scale?: number) => ColumnBuild
  */
 export declare const declareEnumRename: (enumName: string, rename: EnumValueRename) => void;
 
+/**
+ * Read an encrypted field, in EITHER encoding.
+ *
+ * ── Why this reads two forms when there is only one writer ─────────────────
+ *
+ * Because the old form is already on somebody's production disk, and a fix that
+ * requires rewriting it before the app works is not a fix — it is an outage with
+ * a migration attached. "No back-compat" is about not keeping old CODE paths; a
+ * row written last month is data, and data is read where it is.
+ *
+ * ── Why this is deterministic and not a heuristic ──────────────────────────
+ *
+ * The two forms are `encrypt(JSON.stringify(v))` and `encrypt(v)`. After
+ * decrypting, they are told apart by what the plaintext PARSES to, against the
+ * column's declared type:
+ *
+ *   - parse THROWS               → raw form. A JSON encoding always parses.
+ *   - parse yields a STRING      → JSON form. `JSON.stringify` of any string
+ *                                  yields a quoted string, and a raw secret is
+ *                                  not quoted (see the one exception below).
+ *   - parse yields a NON-string  → depends on the column:
+ *       · a TEXT-like column can only hold a string, so a number/object here is
+ *         the raw form being parsed by accident (`"12345"` → `12345`) → raw.
+ *       · a number / boolean / json column stores exactly that, so the parsed
+ *         value IS the value → JSON form.
+ *
+ * No branch guesses. `expected` is the column's declared type; omit it (the
+ * `string → string` escape hatch) and the text-like rule applies, which is
+ * correct for a caller that can only have written a string.
+ *
+ * ── The one case nothing can separate, stated rather than hidden ───────────
+ *
+ * A raw secret whose literal text is `"abc"` — quotes included as characters —
+ * is byte-identical to the JSON encoding of `abc`. No algorithm can tell them
+ * apart, because they are the same bytes. A token or key never looks like that;
+ * it is written here so the next reader does not go looking for the branch that
+ * handles it.
+ */
+export declare const decodeFieldValue: (cipher: FieldCipher, ciphertext: string, expected?: string) => unknown;
+
 export declare type DecoderDialectId = 'postgres' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql' | 'turso';
 
 /**
@@ -2753,6 +2793,35 @@ export declare interface EagerRootPlan {
 
 declare type EmptyMerge = unknown;
 
+/**
+ * THE encoding for an encrypted field. One definition, called by every writer
+ * and every reader — the store middleware, the raw-SQL escape hatch
+ * (`encryptField` / `decryptField` in `@voltro/runtime`), and the
+ * `voltro db encrypt-column` backfill.
+ *
+ * ── Why this is one function and not three copies ──────────────────────────
+ *
+ * It was three. The store wrote `encrypt(JSON.stringify(v))`, the escape hatch
+ * wrote `encrypt(v)`, and the backfill wrote `encrypt(v)`. All three produce the
+ * `enc:v1:` envelope and NOTHING distinguishes them. A consumer wrote session
+ * rows through the escape hatch and read them through the store, which threw
+ * `FieldDecryptionError` blaming the key — the key was right; the ENCODING was
+ * not. Eight of their ten session rows, and the failure looked like a key
+ * rotation the whole time.
+ *
+ * The JSON form wins because it is the only one that can carry a non-string: an
+ * `.encrypted()` column may be a number or a json column, and `encrypt(v)` for
+ * those was already lossy. The escape hatch's `string → string` signature is
+ * unchanged by it — a stringified string parses back to the same string.
+ *
+ * ── The distinction the error has to make ──────────────────────────────────
+ *
+ * A GCM failure and a JSON failure are different diagnoses with different
+ * remedies, and collapsing them is what cost the consumer a day. `decodeFieldValue`
+ * therefore decrypts and decodes as two separate steps and says which one failed.
+ */
+export declare const encodeFieldValue: (cipher: FieldCipher, value: unknown) => string;
+
 /**
  * Serialize a row's json()/array() cells to JSON strings so they can be
  * bound as scalar SQL parameters. Symmetric to `decodeRowsFromSchema`.
@@ -3477,6 +3546,12 @@ export declare const isNull: <RowOf = Record<string, unknown>, K extends keyof R
 
 export declare const isPrimaryKeyConflictError: (err: unknown) => err is PrimaryKeyConflictError;
 
+/** Is this ciphertext in the OLD raw encoding? Used by `voltro db encrypt-column`
+ *  to normalise a column without touching rows that are already current. Answers
+ *  `undefined` when the two forms coincide (a numeric column, or a value that
+ *  parses to itself) — nothing to do either way. */
+export declare const isRawEncoding: (cipher: FieldCipher, ciphertext: string, expected?: string) => boolean | undefined;
+
 /** Can THIS deployment serve the region? */
 export declare const isRegionServable: (region: string, config: ResidencyConfig) => boolean;