@protobase/server 0.33.4 → 0.34.1

package/dist/encryption/apply.js

@@ -0,0 +1,99 @@
+import { bindingOf, movedBinding } from "./binding.js";
+import { Sealed, sealText } from "./envelope-seal.js";
+import { columnId, tableId } from "../sql-parts.js";
+import { cascadingKeys } from "./cascading-keys.js";
+import { captureOff } from "./capture-off.js";
+import { scrubHistory, scrubOutbox } from "./remnants.js";
+import { scanColumn } from "./scan.js";
+import { encryptedFields, examine } from "./status.js";
+import { sql } from "kysely";
+//#region src/encryption/apply.ts
+const rebindsField = (rebind, entry, field) => rebind !== void 0 && rebind.resource === entry.name && (rebind.field === void 0 || rebind.field === field.name) ? rebind : void 0;
+const changeOf = (keyring, entry, field, row, rebind) => {
+	const binding = bindingOf(entry.model, field, row.record);
+	const seal = (plaintext, count) => ({
+		address: row.address,
+		old: row.stored,
+		value: Sealed.textOf(sealText(keyring.current, binding, plaintext)),
+		count
+	});
+	const found = examine(keyring, entry, field, row, binding);
+	if (found.kind === "plaintext") return seal(row.stored, "encrypted");
+	if (found.kind === "open") return found.kid === keyring.current.id ? void 0 : seal(found.plaintext, "reencrypted");
+	if (found.entry.kind !== "failed-authentication" || !rebind) return found.entry;
+	const moved = examine(keyring, entry, field, row, movedBinding(binding, rebind.from));
+	return moved.kind === "open" ? seal(moved.plaintext, "rebound") : found.entry;
+};
+const write = async (trx, entry, field, change) => {
+	const { model } = entry;
+	const keys = model.primaryKey.map((name, i) => sql`${columnId(model.fields[name])} = ${change.address.key[i]}`);
+	const tenant = model.tenant ? [sql`${columnId(model.fields[model.tenant])} is not distinct from ${change.address.tenant}`] : [];
+	const conditions = sql.join([
+		...keys,
+		...tenant,
+		sql`${columnId(field)} = ${change.old}`
+	], sql` and `);
+	const result = await sql`update ${tableId(model)} set ${columnId(field)} = ${change.value} where ${conditions}`.execute(trx);
+	return Number(result.numAffectedRows ?? 0n) > 0;
+};
+const applyField = async (db, entry, field, keyring, changesSchema, rebind) => {
+	const applied = {
+		resource: entry.name,
+		field: field.name,
+		encrypted: 0,
+		reencrypted: 0,
+		rebound: 0,
+		skipped: 0,
+		unreadable: [],
+		historyScrubbed: 0,
+		outboxScrubbed: 0
+	};
+	await scanColumn(db, entry, field, async (rows, connection) => {
+		const changes = [];
+		for (const row of rows) {
+			const change = changeOf(keyring, entry, field, row, rebind);
+			if (change && "address" in change) changes.push(change);
+			else if (change) applied.unreadable.push(change);
+		}
+		if (changes.length === 0) return;
+		await captureOff(connection, changesSchema, async (trx) => {
+			for (const change of changes) if (await write(trx, entry, field, change)) applied[change.count]++;
+			else applied.skipped++;
+		});
+	});
+	applied.historyScrubbed = await scrubHistory(db, changesSchema, entry.model, field);
+	applied.outboxScrubbed = await scrubOutbox(db, changesSchema, entry.model, field);
+	return applied;
+};
+const keyIdsOf = async (db, entry, field) => {
+	const { rows } = await sql`select distinct split_part(${columnId(field)}, ':', 3) as kid from ${tableId(entry.model)} where ${columnId(field)} like 'pbenc:%'`.execute(db);
+	return rows.map(({ kid }) => kid);
+};
+const checkKeys = async (db, entries, keyring) => {
+	for (const entry of entries) for (const field of encryptedFields(entry)) {
+		const kids = await keyIdsOf(db, entry, field);
+		if (kids.length > 0 && !kids.some((kid) => keyring.byId.has(kid))) throw new Error(`${entry.name}.${field.name} holds values under keys ${kids.join(", ")} only, none of which this run has (key ${keyring.current.id}): run with the keys the app serves with`);
+	}
+};
+/**
+* Brings every encrypted field's column to the current key: plaintext values are encrypted, values under a previous key
+* encrypted again, and with `rebind` values sealed where they were before a rename sealed where they are now. Values that
+* do not open are listed and left alone. Then the fields' old values are removed from the history and the changes not
+* yet dispatched. Its writes capture no change. It refuses to run when a column holds envelopes under none of its keys.
+*/
+const applyEncryption = async (db, entries, keyring, changesSchema, options = {}) => {
+	await checkKeys(db, entries, keyring);
+	const fields = [];
+	const warnings = [];
+	for (const entry of entries) {
+		for (const field of encryptedFields(entry)) fields.push(await applyField(db, entry, field, keyring, changesSchema, rebindsField(options.rebind, entry, field)));
+		if (encryptedFields(entry).length > 0) warnings.push(...await cascadingKeys(db, entry.model));
+	}
+	return {
+		kid: keyring.current.id,
+		fields,
+		warnings
+	};
+};
+//#endregion
+export { applyEncryption };

package/dist/encryption/binding.d.ts

@@ -0,0 +1,2 @@
+import "../types.js";
+import { ResourceModel } from "@protobase/schema";

package/dist/encryption/binding.js

@@ -0,0 +1,53 @@
+import { parseTable } from "@protobase/schema/internal";
+//#region src/encryption/binding.ts
+const textOf = (record, name) => {
+	const value = record[name];
+	if (value === void 0) throw new Error(`Binding an encrypted value needs the record's "${name}"`);
+	return String(value);
+};
+const tableOf = (model, field) => ({
+	schema: model.table.schema ?? null,
+	table: model.table.name,
+	column: field.column
+});
+/**
+* The binding of `field` in `record`. The record must be a row as `fetchRecord`, `insertRecord` and `updateRecord` return
+* it, its columns selected under their field names and passed through `exposeRow`, so its key and tenant are the text the
+* API shows (a lowercase uuid, a bigint as text, a timestamptz as ISO text with milliseconds).
+*/
+const bindingOf = (model, field, record) => ({
+	...tableOf(model, field),
+	tenant: model.tenant && record[model.tenant] !== null ? textOf(record, model.tenant) : null,
+	key: model.primaryKey.map((name) => textOf(record, name))
+});
+/** The binding of a create's first write, whose key the database has not made yet: it is bound again in the same transaction. */
+const pendingBinding = (model, field) => ({
+	...tableOf(model, field),
+	tenant: null,
+	key: null
+});
+/** Where a value was before a rename: `binding` with the table (as `.table()` wrote it) or the column that `from` names. */
+const movedBinding = (binding, from) => {
+	const table = from.table === void 0 ? void 0 : parseTable(from.table);
+	return {
+		...binding,
+		...table && {
+			schema: table.schema ?? null,
+			table: table.name
+		},
+		...from.column !== void 0 && { column: from.column }
+	};
+};
+/** The additional authenticated data of an envelope: JSON of an array, which no dot in a name or order of a key confuses. */
+const aadOf = (kid, { schema, table, column, tenant, key }) => Buffer.from(JSON.stringify([
+	"pbenc",
+	1,
+	kid,
+	schema,
+	table,
+	column,
+	tenant,
+	key
+]), "utf8");
+//#endregion
+export { aadOf, bindingOf, movedBinding, pendingBinding };

package/dist/encryption/capture-off.js

@@ -0,0 +1,12 @@
+import { sql } from "kysely";
+//#region src/encryption/capture-off.ts
+/**
+* Runs `work` in a transaction on one connection that change capture skips (`<changes>.capture` set to `off` for this
+* transaction only): rewriting stored values is no change of a record, for history, events or webhooks.
+*/
+const captureOff = (db, changesSchema, work) => db.transaction().execute(async (trx) => {
+	await sql`select set_config(${`${changesSchema}.capture`}, 'off', true)`.execute(trx);
+	return work(trx);
+});
+//#endregion
+export { captureOff };

package/dist/encryption/cascading-keys.d.ts

@@ -0,0 +1,9 @@
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/encryption/cascading-keys.d.ts
+/** A foreign key that rewrites part of a resource's key when the record it points at changes its own. */
+export type CascadingKey = {
+  resource: string;
+  constraint: string;
+};
+//#endregion

package/dist/encryption/cascading-keys.js

@@ -0,0 +1,21 @@
+import { sql } from "kysely";
+//#region src/encryption/cascading-keys.ts
+/**
+* The foreign keys of the resource's table, `on update cascade` or `set default`, over a column of its key: a key change
+* of the other record rewrites this record's key, and every encrypted value of the row then no longer opens.
+*/
+const cascadingKeys = async (db, model) => {
+	const columns = model.primaryKey.map((name) => model.fields[name].column);
+	const { rows } = await sql`select c.conname as "constraint"
+from pg_constraint c
+where c.contype = 'f' and c.confupdtype in ('c', 'd')
+  and c.conrelid = to_regclass(${model.table.schema === void 0 ? sql`quote_ident(${model.table.name})` : sql`quote_ident(${model.table.schema}) || '.' || quote_ident(${model.table.name})`})
+  and exists (select 1 from pg_attribute a where a.attrelid = c.conrelid and a.attnum = any(c.conkey) and a.attname = any(${columns}::text[]))
+order by c.conname`.execute(db);
+	return rows.map(({ constraint }) => ({
+		resource: model.name,
+		constraint
+	}));
+};
+//#endregion
+export { cascadingKeys };

package/dist/encryption/envelope-open.d.ts

@@ -0,0 +1,5 @@
+import "./binding.js";
+//#region src/encryption/envelope-open.d.ts
+/** Why a stored value does not open. */
+export type UnreadableKind = 'not-encrypted' | 'malformed' | 'unknown-key' | 'failed-authentication';
+//#endregion

package/dist/encryption/envelope-open.js

@@ -0,0 +1,57 @@
+import { aadOf } from "./binding.js";
+import "./envelope-seal.js";
+import { createDecipheriv } from "node:crypto";
+//#region src/encryption/envelope-open.ts
+/** A stored value of an encrypted field that does not open. Its message never holds the value. */
+var UnreadableValue = class extends Error {
+	kind;
+	kid;
+	constructor(kind, subject, binding, kid) {
+		super(`${subject.resource}.${subject.field} of record ${JSON.stringify(binding.key)} cannot be decrypted: ${kind}${kid ? ` (key ${kid})` : ""}`);
+		this.kind = kind;
+		this.kid = kid;
+		this.name = "UnreadableValue";
+	}
+};
+const ivLength = 12;
+const tagLength = 16;
+const parse = (stored) => {
+	if (!stored.startsWith("pbenc:")) return "not-encrypted";
+	const parts = stored.split(":");
+	if (parts.length !== 4 || parts[1] !== "1") return "malformed";
+	const [, , kid, payload] = parts;
+	if (!/^[A-Za-z0-9_-]{8}$/.test(kid)) return "malformed";
+	const bytes = Buffer.from(payload, "base64url");
+	if (bytes.toString("base64url") !== payload || bytes.length < 28) return "malformed";
+	return {
+		kid,
+		bytes
+	};
+};
+const decrypt = (aes, aad, bytes) => {
+	const decipher = createDecipheriv("aes-256-gcm", aes, bytes.subarray(0, ivLength), { authTagLength: tagLength });
+	decipher.setAAD(aad);
+	decipher.setAuthTag(bytes.subarray(bytes.length - tagLength));
+	const body = decipher.update(bytes.subarray(ivLength, bytes.length - tagLength));
+	try {
+		return Buffer.concat([body, decipher.final()]).toString("utf8");
+	} catch (error) {
+		if (error instanceof Error) return void 0;
+		throw error;
+	}
+};
+/**
+* The plaintext of `stored`, sealed under `binding` with a key of `keyring`, or an `UnreadableValue` thrown with why it
+* does not open. The only place, with the CLI's status and apply, that decrypts.
+*/
+const openText = (keyring, binding, stored, subject) => {
+	const parsed = parse(stored);
+	if (typeof parsed === "string") throw new UnreadableValue(parsed, subject, binding);
+	const key = keyring.byId.get(parsed.kid);
+	if (!key) throw new UnreadableValue("unknown-key", subject, binding, parsed.kid);
+	const plaintext = decrypt(key.aes, aadOf(parsed.kid, binding), parsed.bytes);
+	if (plaintext === void 0) throw new UnreadableValue("failed-authentication", subject, binding, parsed.kid);
+	return plaintext;
+};
+//#endregion
+export { UnreadableValue, openText };

package/dist/encryption/envelope-seal.js

@@ -0,0 +1,38 @@
+import { aadOf } from "./binding.js";
+import { createCipheriv, randomBytes } from "node:crypto";
+//#region src/encryption/envelope-seal.ts
+/** The envelope's prefix and version: `pbenc:1:<key id>:<base64url of iv, ciphertext and tag>`. */
+const envelopePrefix = "pbenc:";
+let seal;
+/**
+* A value sealed by `sealText`, the only thing the record writes accept for an encrypted field: nothing else can make
+* one, so a write path that forgets to encrypt throws instead of storing plaintext.
+*/
+var Sealed = class Sealed {
+	#text;
+	constructor(text) {
+		this.#text = text;
+	}
+	static {
+		seal = (text) => new Sealed(text);
+	}
+	/** The envelope text the column stores. */
+	static textOf(value) {
+		return value.#text;
+	}
+};
+/** Seals `plaintext` with AES-256-GCM under `key`, bound to `binding`, with a fresh random IV. */
+const sealText = (key, binding, plaintext) => {
+	const iv = randomBytes(12);
+	const cipher = createCipheriv("aes-256-gcm", key.aes, iv, { authTagLength: 16 });
+	cipher.setAAD(aadOf(key.id, binding));
+	const body = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	const payload = Buffer.concat([
+		iv,
+		body,
+		cipher.getAuthTag()
+	]).toString("base64url");
+	return seal(`${envelopePrefix}1:${key.id}:${payload}`);
+};
+//#endregion
+export { Sealed, envelopePrefix, sealText };

package/dist/encryption/keyring.js

@@ -0,0 +1,60 @@
+import { createHmac } from "node:crypto";
+//#region src/encryption/keyring.ts
+const currentVariable = "PROTOBASE_ENCRYPTION_KEY";
+const previousVariable = "PROTOBASE_ENCRYPTION_PREVIOUS_KEYS";
+const derive = (root, label) => createHmac("sha256", root).update(label).digest();
+const keyOf = (root) => ({
+	id: derive(root, "protobase field encryption key id").toString("base64url").slice(0, 8),
+	aes: derive(root, "protobase field encryption key v1")
+});
+const rootOf = ({ text, where }) => {
+	if (text === "") throw new Error(`${where} is empty`);
+	const bytes = Buffer.from(text, "base64");
+	if (bytes.toString("base64") !== text || bytes.length !== 32) throw new Error(`${where} is not 32 bytes in standard base64, such as the output of openssl rand -base64 32`);
+	if (bytes.every((byte) => byte === bytes[0])) throw new Error(`${where} is 32 identical bytes, not a random key`);
+	return bytes;
+};
+const entriesOf = (env) => {
+	const current = {
+		text: (env[currentVariable] ?? "").trim(),
+		where: currentVariable
+	};
+	const previous = env[previousVariable];
+	if (previous === void 0 || previous.trim() === "") return [current];
+	return [current, ...previous.split(",").map((text, i) => ({
+		text: text.trim(),
+		where: `${previousVariable} entry ${i + 1}`
+	}))];
+};
+const checkApart = (entries, env) => {
+	for (const name of ["BETTER_AUTH_SECRET", "PROTOBASE_SECRET_KEY"]) {
+		const secret = env[name]?.trim();
+		const same = secret && entries.find((entry) => entry.text === secret);
+		if (same) throw new Error(`${same.where} is the same as ${name}: give encryption a key of its own`);
+	}
+};
+/**
+* The keys from `PROTOBASE_ENCRYPTION_KEY` and the comma separated `PROTOBASE_ENCRYPTION_PREVIOUS_KEYS`. Throws on a key
+* that is not 32 random bytes in base64, a key given twice, or one that is the sign-in or API secret, naming the
+* variable and the entry, never the key.
+*/
+const encryptionKeyring = (env) => {
+	const entries = entriesOf(env);
+	checkApart(entries, env);
+	const byId = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const root = rootOf(entry);
+		if (seen.has(root.toString("base64"))) throw new Error(`${entry.where} is a key given before`);
+		seen.add(root.toString("base64"));
+		const key = keyOf(root);
+		if (byId.has(key.id)) throw new Error(`${entry.where} has the same key id as a key given before`);
+		byId.set(key.id, key);
+	}
+	return {
+		current: byId.values().next().value,
+		byId
+	};
+};
+//#endregion
+export { encryptionKeyring };

package/dist/encryption/mask-stored.js

@@ -0,0 +1,16 @@
+import { encrypted } from "@protobase/schema";
+//#region src/encryption/mask-stored.ts
+/**
+* A stored row as app code gets it: each encrypted field that holds a value as `encrypted`, never the ciphertext, so
+* rules, validators and hooks know whether it is set and nothing else. An empty one stays `null`.
+*/
+const maskEncrypted = (model, row) => {
+	const masked = Object.values(model.fields).filter((field) => field.encrypted && row[field.name] != null);
+	if (masked.length === 0) return row;
+	return {
+		...row,
+		...Object.fromEntries(masked.map((field) => [field.name, encrypted]))
+	};
+};
+//#endregion
+export { maskEncrypted };

package/dist/encryption/rebind-check.js

@@ -0,0 +1,28 @@
+import { parseTable } from "@protobase/schema/internal";
+//#region src/encryption/rebind-check.ts
+const sources = (entry, rebind) => {
+	const table = rebind.from.table === void 0 ? entry.model.table : parseTable(rebind.from.table);
+	return Object.values(entry.model.fields).filter((field) => field.encrypted && (rebind.field === void 0 || field.name === rebind.field)).map((field) => ({
+		table,
+		column: rebind.from.column ?? field.column
+	}));
+};
+const sameTable = (a, b) => a.name === b.name && (a.schema === void 0 || b.schema === void 0 || a.schema === b.schema);
+/**
+* Why `rebind` cannot run, or `undefined`: it must name a resource with encrypted fields, an encrypted field of it, and
+* where they were before; and no resource may still encrypt a field over that place, whose values it would take over.
+*/
+const rebindProblem = (entries, rebind) => {
+	const entry = entries.find((candidate) => candidate.name === rebind.resource);
+	if (!entry) return `There is no resource "${rebind.resource}"`;
+	if (rebind.field !== void 0 && !entry.model.fields[rebind.field]?.encrypted) return `${rebind.resource}.${rebind.field} is not an encrypted field`;
+	if (!Object.values(entry.model.fields).some((field) => field.encrypted)) return `${rebind.resource} has no encrypted fields`;
+	if (rebind.from.table === void 0 && rebind.from.column === void 0) return "Name the table or the column the values were in before";
+	if (rebind.from.column !== void 0 && rebind.field === void 0) return "Name the field whose column was renamed";
+	for (const { table, column } of sources(entry, rebind)) {
+		const owner = entries.find((other) => sameTable(other.model.table, table) && Object.values(other.model.fields).some((field) => field.encrypted && field.column === column));
+		if (owner) return `${owner.name} still encrypts a field over ${table.schema ? `${table.schema}.` : ""}${table.name}.${column}, so its values are not ${rebind.resource}'s to take over`;
+	}
+};
+//#endregion
+export { rebindProblem };

package/dist/encryption/remnants.js

@@ -0,0 +1,53 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+import { captureOff } from "./capture-off.js";
+import { sql } from "kysely";
+//#region src/encryption/remnants.ts
+const history = {
+	table: "history",
+	old: "before",
+	new: "after",
+	key: (field) => field.name
+};
+const outbox = {
+	table: "outbox",
+	old: "old",
+	new: "new",
+	key: (field) => field.column
+};
+const batchSize = 500;
+const tableOf = (schema, store) => `${quoteIdent(schema)}.${quoteIdent(store.table)}`;
+const exists = async (db, schema, store) => {
+	const { rows } = await sql`select to_regclass(${tableOf(schema, store)}) is not null as found`.execute(db);
+	return rows[0].found;
+};
+const holding = (store, model, field) => sql`"resource" = ${model.name} and (${sql.id(store.old)} ? ${store.key(field)}::text or ${sql.id(store.new)} ? ${store.key(field)}::text)`;
+const count = async (db, schema, store, model, field) => {
+	if (!await exists(db, schema, store)) return 0;
+	const { rows } = await sql`select count(*)::text as count from ${sql.raw(tableOf(schema, store))} where ${holding(store, model, field)}`.execute(db);
+	return Number(rows[0].count);
+};
+const scrub = async (db, schema, store, model, field) => {
+	if (!await exists(db, schema, store)) return 0;
+	const table = sql.raw(tableOf(schema, store));
+	const key = sql`${store.key(field)}::text`;
+	let total = 0;
+	for (;;) {
+		const scrubbed = await captureOff(db, schema, async (trx) => {
+			const result = await sql`with batch as (select "id" from ${table} where ${holding(store, model, field)} limit ${sql.raw(String(batchSize))})
+update ${table} as t set ${sql.id(store.old)} = t.${sql.id(store.old)} - ${key}, ${sql.id(store.new)} = t.${sql.id(store.new)} - ${key} from batch where t."id" = batch."id"`.execute(trx);
+			return Number(result.numAffectedRows ?? 0n);
+		});
+		total += scrubbed;
+		if (scrubbed < batchSize) return total;
+	}
+};
+/** The history rows of `model` that still hold `field`, kept from before it was encrypted. */
+const historyRemnants = (db, schema, model, field) => count(db, schema, history, model, field);
+/** Removes `field` from the history of `model`, returning how many rows held it. */
+const scrubHistory = (db, schema, model, field) => scrub(db, schema, history, model, field);
+/** The changes of `model` not yet dispatched that still hold `field`'s column. */
+const outboxRemnants = (db, schema, model, field) => count(db, schema, outbox, model, field);
+/** Removes `field`'s column from the changes of `model` not yet dispatched, returning how many rows held it. */
+const scrubOutbox = (db, schema, model, field) => scrub(db, schema, outbox, model, field);
+//#endregion
+export { historyRemnants, outboxRemnants, scrubHistory, scrubOutbox };

package/dist/encryption/runtime.d.ts

@@ -0,0 +1 @@
+import { ResourceModel } from "@protobase/schema";

package/dist/encryption/runtime.js

@@ -0,0 +1,18 @@
+import { sharedColumnProblems } from "./shared-columns.js";
+import { encryptionKeyring } from "./keyring.js";
+//#region src/encryption/runtime.ts
+const encryptedFieldNames = (models) => models.flatMap((model) => Object.values(model.fields).flatMap((field) => field.encrypted ? [`${model.name}.${field.name}`] : []));
+/**
+* The runtime, when a resource has an encrypted field. It fails at startup when another resource over the same column
+* would write plaintext into it or bind it differently, or when the key is missing or unfit. It needs no database.
+*/
+const createEncryptionRuntime = ({ models, env }) => {
+	const fields = encryptedFieldNames(models);
+	if (fields.length === 0) return void 0;
+	const problems = sharedColumnProblems(models);
+	if (problems.length > 0) throw new Error(problems.join("; "));
+	if (!env.PROTOBASE_ENCRYPTION_KEY?.trim()) throw new Error(`Encrypted fields (${fields.join(", ")}) need a key: set PROTOBASE_ENCRYPTION_KEY to 32 random bytes in base64, such as the output of openssl rand -base64 32`);
+	return { keyring: encryptionKeyring(env) };
+};
+//#endregion
+export { createEncryptionRuntime };

package/dist/encryption/scan.d.ts

@@ -0,0 +1,4 @@
+import "../types.js";
+import "../registry.js";
+import "@protobase/schema";
+import { Db } from "@protobase/query";

package/dist/encryption/scan.js

@@ -0,0 +1,61 @@
+import { aliasedColumn, columnId, tableId } from "../sql-parts.js";
+import { exposeRow } from "../rows.js";
+import { sql } from "kysely";
+//#region src/encryption/scan.ts
+const batchSize = 500;
+const cursor = sql.id("pb_encryption_scan");
+const keyAlias = (i) => `__pb_key_${i}`;
+const tenantAlias = "__pb_tenant";
+/** The fields a binding needs, and the field itself. */
+const scannedFields = (entry, field) => {
+	const { model } = entry;
+	return [.../* @__PURE__ */ new Set([
+		...model.primaryKey,
+		...model.tenant ? [model.tenant] : [],
+		field.name
+	])].map((name) => model.fields[name]);
+};
+const declareScan = (entry, field) => {
+	const { model } = entry;
+	const keys = model.primaryKey.map((name, i) => sql`${columnId(model.fields[name])}::text as ${sql.id(keyAlias(i))}`);
+	const tenant = model.tenant ? [sql`${columnId(model.fields[model.tenant])}::text as ${sql.id(tenantAlias)}`] : [];
+	const columns = sql.join([
+		...scannedFields(entry, field).map(aliasedColumn),
+		...keys,
+		...tenant
+	]);
+	return sql`declare ${cursor} no scroll cursor with hold for select ${columns} from ${tableId(model)} where ${columnId(field)} is not null`;
+};
+const scanned = (entry, field, row) => ({
+	record: exposeRow(entry.model, row),
+	address: {
+		key: entry.model.primaryKey.map((_, i) => String(row[keyAlias(i)])),
+		tenant: row[tenantAlias] ?? null
+	},
+	stored: String(row[field.name])
+});
+/**
+* Reads every row of the table whose column `field` is not null, every tenant and soft-deleted rows included, in batches
+* handed to `onBatch` with the connection the scan runs on. A holdable cursor keeps the rows as they were when the scan
+* began, so each comes once without an order, and the batches' writes run on the same connection in transactions of
+* their own: a pool of one connection is enough. Rows written after the scan began are not in it.
+*/
+const scanColumn = (db, entry, field, onBatch) => db.connection().execute(async (connection) => {
+	let declared = false;
+	try {
+		await sql`begin`.execute(connection);
+		await declareScan(entry, field).execute(connection);
+		declared = true;
+		await sql`commit`.execute(connection);
+		for (;;) {
+			const { rows } = await sql`fetch ${sql.raw(String(batchSize))} from ${cursor}`.execute(connection);
+			if (rows.length === 0) return;
+			await onBatch(rows.map((row) => scanned(entry, field, row)), connection);
+		}
+	} finally {
+		await sql`rollback`.execute(connection);
+		if (declared) await sql`close ${cursor}`.execute(connection);
+	}
+});
+//#endregion
+export { scanColumn, scannedFields };

package/dist/encryption/seal-values.js

@@ -0,0 +1,30 @@
+import { sealText } from "./envelope-seal.js";
+//#region src/encryption/seal-values.ts
+const encryptedIn = (model, values) => Object.keys(values).flatMap((name) => {
+	const field = model.fields[name];
+	return field?.encrypted && values[name] !== null ? [field] : [];
+});
+/** Whether `values` set an encrypted field to a value. */
+const hasEncryptedValues = (model, values) => encryptedIn(model, values).length > 0;
+/** The encrypted fields of `values` that hold a value. */
+const encryptedValuesOf = (model, values) => Object.fromEntries(encryptedIn(model, values).map((field) => [field.name, values[field.name]]));
+/**
+* `values` with each encrypted field's value sealed under `binding(field)`. What was given is always sealed, even text
+* that looks like an envelope, so a client cannot store another record's ciphertext as its own.
+*/
+const sealValues = (runtime, model, values, binding) => {
+	const fields = encryptedIn(model, values);
+	if (fields.length === 0) return values;
+	if (!runtime) throw new Error(`"${model.name}" has encrypted fields but no encryption runtime`);
+	const sealed = fields.map((field) => {
+		const value = values[field.name];
+		if (typeof value !== "string") throw new Error(`"${field.name}" is encrypted and takes text only`);
+		return [field.name, sealText(runtime.keyring.current, binding(field), value)];
+	});
+	return {
+		...values,
+		...Object.fromEntries(sealed)
+	};
+};
+//#endregion
+export { encryptedValuesOf, hasEncryptedValues, sealValues };

package/dist/encryption/shared-columns.js

@@ -0,0 +1,19 @@
+//#region src/encryption/shared-columns.ts
+/** Whether two resources are over one table: the same name, and the same schema or either one naming none. */
+const sameTable = (a, b) => a.table.name === b.table.name && (a.table.schema === void 0 || b.table.schema === void 0 || a.table.schema === b.table.schema);
+const columnOf = (model, name) => name === void 0 ? null : model.fields[name]?.column ?? name;
+const bindsAlike = (a, b) => (a.table.schema ?? null) === (b.table.schema ?? null) && columnOf(a, a.tenant) === columnOf(b, b.tenant) && JSON.stringify(a.primaryKey.map((name) => columnOf(a, name))) === JSON.stringify(b.primaryKey.map((name) => columnOf(b, name)));
+const isOver = (field, column) => field.column === column || (field.relation?.columns.includes(column) ?? false);
+const ownProblems = (model, field) => Object.values(model.fields).filter((other) => other !== field && isOver(other, field.column)).map((other) => `${model.name}.${other.name} is over ${model.table.name}.${field.column}, which ${model.name}.${field.name} encrypts: leave the column out of it`);
+/**
+* Every other field over the column of an encrypted field that would write plaintext into it or bind its values
+* differently: in its own resource, any; in another resource, one that is not `.encrypted()` too over the same
+* `.table()`, tenant and key.
+*/
+const sharedColumnProblems = (models) => models.flatMap((model) => Object.values(model.fields).filter((field) => field.encrypted).flatMap((field) => [...ownProblems(model, field), ...models.filter((other) => other !== model && sameTable(model, other)).flatMap((other) => {
+	const shared = Object.values(other.fields).find((candidate) => isOver(candidate, field.column));
+	if (!shared || shared.encrypted && shared.column === field.column && bindsAlike(model, other)) return [];
+	return [`${other.name}.${shared.name} is over ${model.table.name}.${field.column}, which ${model.name} encrypts: declare it .encrypted() too, with the same table, tenant and key, or leave the column out`];
+})]));
+//#endregion
+export { sameTable, sharedColumnProblems };

package/dist/encryption/status.d.ts

@@ -0,0 +1,39 @@
+import "../registry.js";
+import "./binding.js";
+import { CascadingKey } from "./cascading-keys.js";
+import { UnreadableKind } from "./envelope-open.js";
+import "./scan.js";
+import "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/encryption/status.d.ts
+/** A stored value that does not open, by its record's key: never the value. */
+export type UnreadableEntry = {
+  key: string[];
+  kid?: string;
+  kind: UnreadableKind;
+};
+/** What an encrypted field's column holds, and where its old plaintext remains. */
+export type FieldStatus = {
+  resource: string;
+  field: string;
+  /** The values that open, by the id of the key they are under. */
+  byKey: Record<string, number>;
+  plaintext: number;
+  unreadable: UnreadableEntry[];
+  /** History rows and undispatched changes that still hold the field from before it was encrypted. */
+  history: number;
+  outbox: number;
+};
+/** Envelopes in a text field that is not encrypted, such as one whose `.encrypted()` was removed. */
+export type StrayValues = {
+  resource: string;
+  field: string;
+  count: number;
+};
+export type EncryptionStatus = {
+  kid: string;
+  fields: FieldStatus[];
+  stray: StrayValues[];
+  cascading: CascadingKey[];
+};
+//#endregion