@optimystic/quereus-plugin-crypto 0.13.5 → 0.16.2

package/src/crypto.ts

@@ -7,7 +7,7 @@
 
 import { sha256, sha512 } from '@noble/hashes/sha2.js';
 import { blake3 } from '@noble/hashes/blake3.js';
-import { randomBytes as nobleRandomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+import { randomBytes as nobleRandomBytes, utf8ToBytes, concatBytes } from '@noble/hashes/utils.js';
 import { secp256k1 } from '@noble/curves/secp256k1.js';
 import { p256 } from '@noble/curves/nist.js';
 import { ed25519 } from '@noble/curves/ed25519.js';
@@ -19,6 +19,27 @@ export type HashAlgorithm = 'sha256' | 'sha512' | 'blake3';
 export type CurveType = 'secp256k1' | 'p256' | 'ed25519';
 export type Encoding = 'base64url' | 'base64' | 'hex' | 'utf8' | 'bytes';
 
+/** Encodings valid for hash *output* (no 'utf8' — a digest is not UTF-8 text). */
+export type OutputEncoding = 'base64url' | 'base64' | 'hex' | 'bytes';
+
+/** A single value in a multi-field digest. Mirrors the SQL value space. */
+export type DigestField =
+	| string
+	| number
+	| bigint
+	| boolean
+	| Uint8Array
+	| null
+	| undefined
+	| { readonly [key: string]: unknown }
+	| readonly unknown[];
+
+/** A resolved hash function: raw bytes in, digest bytes out. */
+export type DigestHasher = (input: Uint8Array) => Uint8Array;
+
+/** A resolved output encoder: digest bytes in, encoded form out. */
+export type OutputEncoder = (bytes: Uint8Array) => string | Uint8Array;
+
 /**
  * Convert input to Uint8Array, handling various encodings
  */
@@ -69,51 +90,247 @@ function fromBytes(bytes: Uint8Array, encoding: Encoding = 'base64url'): string
 	}
 }
 
+// --- Algorithm / encoding resolution (done once, no per-call switching) --- //
+
+/** Hash algorithm → noble hasher. Keyed lookup so the digest hot path never branches. */
+const HASHERS: Record<HashAlgorithm, DigestHasher> = {
+	sha256,
+	sha512,
+	blake3,
+};
+
+/** Output encoding → encoder closure. */
+const OUTPUT_ENCODERS: Record<OutputEncoding, OutputEncoder> = {
+	base64url: (bytes) => uint8ArrayToString(bytes, 'base64url'),
+	base64: (bytes) => uint8ArrayToString(bytes, 'base64'),
+	hex: (bytes) => bytesToHex(bytes),
+	bytes: (bytes) => bytes,
+};
+
+/**
+ * Resolve a hash algorithm name to its hasher. Throws on unknown algorithm.
+ * Call once (e.g. at plugin registration) and capture the result so the digest
+ * hot path performs no per-call algorithm branching.
+ */
+export function resolveHasher(algorithm: HashAlgorithm): DigestHasher {
+	const hasher = HASHERS[algorithm];
+	if (!hasher) {
+		throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+	}
+	return hasher;
+}
+
+/**
+ * Resolve an output encoding name to its encoder. Throws on unknown encoding.
+ */
+export function resolveOutputEncoder(encoding: OutputEncoding): OutputEncoder {
+	const encoder = OUTPUT_ENCODERS[encoding];
+	if (!encoder) {
+		throw new Error(`Unsupported output encoding: ${encoding}`);
+	}
+	return encoder;
+}
+
+// --- Canonical, injective multi-field encoding --- //
+
+/**
+ * Format version for {@link encodeFields}. Prepended to every encoding so the
+ * framing can evolve, and so a framed digest is domain-separated from a bare
+ * hash of the same bytes. Bump only with a deliberate, breaking format change.
+ */
+const DIGEST_FORMAT_V1 = 0x01;
+
+// Per-field type tags. Distinct tags keep distinct SQL types from colliding
+// (e.g. INTEGER 123 vs TEXT '123' vs BOOL true).
+//
+// Note on INT vs REAL: the tag is derived from the JS value, not from SQL
+// affinity (a scalar function does not receive affinity). An integer-VALUED
+// number — including a REAL like 2.0, which reaches JS as the number 2 — is
+// encoded as INTEGER. So INTEGER 2 and REAL 2.0 produce the same digest. This is
+// replicable (every peer sees the same JS value) but not int/real-distinguishing.
+const TAG_NULL = 0x00; // bare tag, no length/payload
+const TAG_INT = 0x01;  // payload: canonical decimal string (number-integer & bigint unified via BigInt)
+const TAG_REAL = 0x02; // payload: ECMAScript Number::toString (non-integer numbers only)
+const TAG_TEXT = 0x03; // payload: UTF-8 bytes
+const TAG_BOOL = 0x04; // payload: single 0x00/0x01 byte
+const TAG_BLOB = 0x05; // payload: raw bytes
+const TAG_JSON = 0x06; // payload: UTF-8 of key-sorted canonical JSON
+
+/** Append an unsigned LEB128 varint (safe for lengths up to MAX_SAFE_INTEGER). */
+function writeVarint(out: number[], value: number): void {
+	if (!Number.isInteger(value) || value < 0) {
+		throw new Error(`varint expects a non-negative integer, got ${value}`);
+	}
+	let v = value;
+	while (v >= 0x80) {
+		out.push((v & 0x7f) | 0x80);
+		v = Math.floor(v / 128);
+	}
+	out.push(v);
+}
+
+/** tag ‖ varint(len) ‖ payload */
+function framed(tag: number, payload: Uint8Array): Uint8Array {
+	const header: number[] = [tag];
+	writeVarint(header, payload.length);
+	return concatBytes(Uint8Array.from(header), payload);
+}
+
+/**
+ * Strict, deterministic JSON canonicalization for a native object/array field:
+ * object keys recursively sorted, no incidental whitespace. Unlike `JSON.stringify`,
+ * it THROWS rather than silently collapsing non-JSON inputs (`undefined`, non-finite
+ * numbers, `bigint`, non-plain objects like `Date`/`Map`) — silent collapse would
+ * break injectivity (`{a:undefined}` vs `{}`, `NaN` vs `null`, `new Date(0)` vs `{}`).
+ */
+function canonicalJson(value: unknown): string {
+	if (value === null) return 'null';
+	const t = typeof value;
+	if (t === 'string') return JSON.stringify(value);
+	if (t === 'boolean') return value ? 'true' : 'false';
+	if (t === 'number') {
+		if (!Number.isFinite(value)) {
+			throw new Error('digest: cannot encode a non-finite number inside a JSON field');
+		}
+		return JSON.stringify(value) as string; // deterministic Number::toString
+	}
+	if (t === 'bigint') {
+		throw new Error('digest: bigint is not representable inside a JSON field');
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((el) => {
+			if (el === undefined) {
+				throw new Error('digest: undefined / sparse element inside a JSON field');
+			}
+			return canonicalJson(el);
+		}).join(',')}]`;
+	}
+	if (t === 'object') {
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== Object.prototype && proto !== null) {
+			throw new Error('digest: only plain objects are allowed inside a JSON field');
+		}
+		const obj = value as Record<string, unknown>;
+		const keys = Object.keys(obj).sort();
+		return `{${keys.map((k) => {
+			if (obj[k] === undefined) {
+				throw new Error(`digest: undefined value for JSON key '${k}'`);
+			}
+			return `${JSON.stringify(k)}:${canonicalJson(obj[k])}`;
+		}).join(',')}}`;
+	}
+	throw new Error(`digest: unsupported value of type '${t}' inside a JSON field`);
+}
+
+/** Encode one field as tag (‖ length ‖ payload). NULL/undefined is a bare tag. */
+function encodeField(field: DigestField): Uint8Array {
+	if (field === null || field === undefined) {
+		return Uint8Array.of(TAG_NULL);
+	}
+	switch (typeof field) {
+		case 'boolean':
+			return Uint8Array.of(TAG_BOOL, field ? 1 : 0);
+		case 'bigint':
+			return framed(TAG_INT, utf8ToBytes(field.toString()));
+		case 'number':
+			if (!Number.isFinite(field)) {
+				throw new Error('digest: cannot encode a non-finite number');
+			}
+			// Integer-valued numbers go through BigInt so they encode identically to
+			// the equal-valued bigint (e.g. 1e21 → full digits, not "1e+21").
+			return Number.isInteger(field)
+				? framed(TAG_INT, utf8ToBytes(BigInt(field).toString()))
+				: framed(TAG_REAL, utf8ToBytes(field.toString()));
+		case 'string':
+			return framed(TAG_TEXT, utf8ToBytes(field));
+		case 'object':
+			if (field instanceof Uint8Array) {
+				return framed(TAG_BLOB, field);
+			}
+			return framed(TAG_JSON, utf8ToBytes(canonicalJson(field)));
+		default:
+			throw new Error(`digest: unsupported field type '${typeof field}'`);
+	}
+}
+
+/**
+ * Canonically encode an ordered tuple of fields into bytes such that distinct
+ * tuples never collide (injective framing).
+ *
+ * Layout: `version ‖ field*` where each field is `tag ‖ varint(len) ‖ payload`
+ * (NULL is a bare tag). Properties:
+ * - order-preserving and arity-safe (self-delimiting fields → uniquely decodable),
+ * - NULL distinguishable from empty string,
+ * - type distinguishable (INTEGER 123 ≠ TEXT '123' ≠ BOOL true ≠ BLOB),
+ * - delimiter-safe (a separator inside a string is just payload under its length).
+ *
+ * Replicability notes:
+ * - Integer `number` and `bigint` of equal value encode identically (both via
+ *   `BigInt(...).toString()`); a non-integer REAL uses ECMAScript `Number::toString`
+ *   (deterministic across JS engines, but not guaranteed across other languages).
+ * - INT vs REAL is derived from the JS value, not SQL affinity: an integer-valued
+ *   REAL (e.g. 2.0 → number 2) encodes as INTEGER, so INTEGER 2 and REAL 2.0 collide.
+ * - A native JSON object/array field must contain only valid JSON (no `undefined`,
+ *   non-finite numbers, `bigint`, or non-plain objects) — otherwise it throws.
+ */
+export function encodeFields(fields: readonly DigestField[]): Uint8Array {
+	const chunks: Uint8Array[] = [Uint8Array.of(DIGEST_FORMAT_V1)];
+	for (const field of fields) {
+		chunks.push(encodeField(field));
+	}
+	return concatBytes(...chunks);
+}
+
 /**
- * Compute hash digest of input data
+ * Low-level multi-field digest: canonically encode the fields, then hash and
+ * encode with the supplied (pre-resolved) hasher/encoder. No per-call branching
+ * on algorithm or encoding — resolve once via {@link resolveHasher} /
+ * {@link resolveOutputEncoder} and reuse.
+ */
+export function digestFields(
+	fields: readonly DigestField[],
+	hasher: DigestHasher,
+	encode: OutputEncoder
+): string | Uint8Array {
+	return encode(hasher(encodeFields(fields)));
+}
+
+/**
+ * Compute an injective digest over an ordered tuple of fields.
  *
- * @param data - Data to hash (base64url string or Uint8Array)
+ * @param fields - Ordered tuple of values to hash (any SQL value type)
  * @param algorithm - Hash algorithm (default: 'sha256')
- * @param inputEncoding - Encoding of input string (default: 'base64url')
- * @param outputEncoding - Encoding of output (default: 'base64url')
- * @returns Hash digest in specified encoding
+ * @param encoding - Output encoding (default: 'base64url')
+ * @returns Hash digest in the specified encoding
  *
  * @example
  * ```typescript
- * // Hash UTF-8 text, output as base64url
- * const hash = digest('hello world', 'sha256', 'utf8');
+ * // Hash a tuple of fields — distinct tuples never collide
+ * const h = digest(['alice', 42, null, true]);
  *
- * // Hash base64url data with SHA-512
- * const hash2 = digest('SGVsbG8', 'sha512');
- *
- * // Get raw bytes
- * const bytes = digest('data', 'blake3', 'utf8', 'bytes');
+ * // Pick algorithm / output encoding
+ * const h512 = digest(['a', 'b'], 'sha512', 'hex');
  * ```
+ *
+ * Note: this is a *framed* digest, not a bare hash of raw bytes —
+ * `digest(['hello'])` is not `sha256("hello")`. Use `hashMod` for sharding a
+ * single value.
  */
 export function digest(
-	data: string | Uint8Array,
+	fields: readonly DigestField[],
 	algorithm: HashAlgorithm = 'sha256',
-	inputEncoding: Encoding = 'base64url',
-	outputEncoding: Encoding = 'base64url'
+	encoding: OutputEncoding = 'base64url'
 ): string | Uint8Array {
-	const bytes = toBytes(data, inputEncoding);
-
-	let hashBytes: Uint8Array;
-	switch (algorithm) {
-		case 'sha256':
-			hashBytes = sha256(bytes);
-			break;
-		case 'sha512':
-			hashBytes = sha512(bytes);
-			break;
-		case 'blake3':
-			hashBytes = blake3(bytes);
-			break;
-		default:
-			throw new Error(`Unsupported hash algorithm: ${algorithm}`);
+	if (!Array.isArray(fields)) {
+		throw new Error(
+			`digest(fields, algorithm?, encoding?): 'fields' must be an array of values. ` +
+			`The digest API changed in v0.14: it is now variadic/injective over fields, ` +
+			`the per-call inputEncoding was removed, and algorithm + output encoding are bound at plugin load time. ` +
+			`Migrate digest(value, algo, inputEncoding, outputEncoding) → digest([value], algo, outputEncoding) — ` +
+			`note the result is now a *framed* digest, not a bare hash of the bytes.`
+		);
 	}
-
-	return fromBytes(hashBytes, outputEncoding);
+	return digestFields(fields, resolveHasher(algorithm), resolveOutputEncoder(encoding));
 }
 
 /**
@@ -145,7 +362,8 @@ export function hashMod(
 		throw new Error('Bits must be between 1 and 53 (JavaScript safe integer limit)');
 	}
 
-	const hashBytes = toBytes(digest(data, algorithm, inputEncoding, 'base64url') as string, 'base64url');
+	// Single-blob hash for sharding (not the field-framed digest).
+	const hashBytes = resolveHasher(algorithm)(toBytes(data, inputEncoding));
 
 	// Take first 8 bytes and convert to number
 	const view = new DataView(hashBytes.buffer, hashBytes.byteOffset, Math.min(8, hashBytes.length));

package/src/index.ts

@@ -2,7 +2,9 @@
  * Quereus Crypto Functions Plugin
  *
  * Provides cryptographic functions for SQL queries and ES modules:
- * - digest: Hash functions (SHA-256, SHA-512, BLAKE3) with base64url encoding
+ * - digest: Injective multi-field hash (SHA-256, SHA-512, BLAKE3) with base64url encoding
+ * - cid / cidV1 / cidDecode: Self-describing, interoperable CIDv1 content identifiers
+ * - setCommit / setDisclose / setVerify: Salted-leaf set commitment for per-attribute selective disclosure
  * - sign: ECC signature generation (secp256k1, P-256, Ed25519)
  * - verify: ECC signature verification
  * - hashMod: Hash with modulo for fixed-size outputs
@@ -14,6 +16,10 @@
 // Export idiomatic lowercase functions (primary API)
 export {
 	digest,
+	digestFields,
+	encodeFields,
+	resolveHasher,
+	resolveOutputEncoder,
 	sign,
 	verify,
 	hashMod,
@@ -23,11 +29,30 @@ export {
 	type HashAlgorithm,
 	type CurveType,
 	type Encoding,
+	type OutputEncoding,
+	type DigestField,
+	type DigestHasher,
+	type OutputEncoder,
 } from './crypto.js';
 
-// Legacy exports for backwards compatibility (if needed)
-export { Digest, type DigestInput, type DigestOptions } from './digest.js';
-export { Sign, type PrivateKeyInput, type SignOptions } from './sign.js';
-export { SignatureValid, type BytesInput, type VerifyOptions } from './signature-valid.js';
+// Self-describing content identifiers (CIDv1) layered on top of digest.
+export {
+	cid,
+	cidV1,
+	cidDecode,
+	type Multicodec,
+	type MultihashCode,
+	type Multibase,
+	type CidParts,
+} from './cid.js';
 
+// Salted-leaf set commitment for per-attribute selective disclosure, layered on digest.
+export {
+	leafDigest,
+	setCommit,
+	setDisclose,
+	setVerify,
+	type SaltedLeaf,
+	type SetDisclosure,
+} from './sd.js';
 

package/src/plugin.ts

@@ -7,7 +7,101 @@
 
 import type { Database, SqlValue } from '@quereus/quereus';
 import { FunctionFlags, TEXT_TYPE, INTEGER_TYPE, BOOLEAN_TYPE } from '@quereus/quereus';
-import { digest, sign, verify, hashMod, randomBytes } from './crypto.js';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import {
+	sign, verify, hashMod, randomBytes,
+	digestFields, resolveHasher, resolveOutputEncoder,
+	type HashAlgorithm, type OutputEncoding, type DigestField,
+} from './crypto.js';
+import {
+	cid, cidV1, cidDecode,
+	type Multicodec, type MultihashCode, type Multibase,
+} from './cid.js';
+import {
+	setCommit, setVerify,
+	type SaltedLeaf,
+} from './sd.js';
+
+const DIGEST_ALGORITHMS: readonly HashAlgorithm[] = ['sha256', 'sha512', 'blake3'];
+// SQL digest returns TEXT, so only text-producing encodings are valid here ('bytes' is JS-only).
+const DIGEST_TEXT_ENCODINGS: readonly OutputEncoding[] = ['base64url', 'base64', 'hex'];
+
+function configAlgorithm(config: Record<string, SqlValue>): HashAlgorithm {
+	const value = config.algorithm == null ? 'sha256' : String(config.algorithm);
+	if (!DIGEST_ALGORITHMS.includes(value as HashAlgorithm)) {
+		throw new Error(`crypto plugin: unsupported digest algorithm '${value}' (expected one of ${DIGEST_ALGORITHMS.join(', ')})`);
+	}
+	return value as HashAlgorithm;
+}
+
+function configEncoding(config: Record<string, SqlValue>): OutputEncoding {
+	const value = config.encoding == null ? 'base64url' : String(config.encoding);
+	if (!DIGEST_TEXT_ENCODINGS.includes(value as OutputEncoding)) {
+		throw new Error(`crypto plugin: unsupported digest encoding '${value}' (expected one of ${DIGEST_TEXT_ENCODINGS.join(', ')})`);
+	}
+	return value as OutputEncoding;
+}
+
+/**
+ * Coerce a SQL `data`/`digest` argument to raw bytes. A BLOB arrives as a
+ * Uint8Array and is used directly; TEXT is interpreted as base64url — the
+ * plugin's canonical text encoding — so `cid_v1(digest(...))` composes with the
+ * base64url string `digest` returns, with no extra round-trip.
+ */
+function toContentBytes(value: SqlValue | undefined, fnName: string): Uint8Array {
+	if (value instanceof Uint8Array) {
+		return value;
+	}
+	if (typeof value === 'string') {
+		return uint8ArrayFromString(value, 'base64url');
+	}
+	throw new Error(`${fnName}: expected a BLOB or base64url TEXT argument, got ${value == null ? 'NULL' : typeof value}`);
+}
+
+/**
+ * Parse one JSON leaf — either `[name, value, salt]` or `{ name, value, salt }` —
+ * into a {@link SaltedLeaf}. The JSON value maps directly to the `encodeFields` value
+ * space (INTEGER vs REAL by JS value, TEXT, BOOL, null, nested object/array → JSON).
+ *
+ * Note: a BLOB-valued attribute is passed as its base64url TEXT and committed AS TEXT
+ * (JSON has no blob type); callers needing a true BLOB value must use the JS API with a
+ * `Uint8Array`. The salt is likewise base64url TEXT (decoded to bytes by `set_commit`).
+ */
+function leafFromJson(entry: unknown, fnName: string): SaltedLeaf {
+	if (Array.isArray(entry)) {
+		if (entry.length < 3) {
+			throw new Error(`${fnName}: a leaf array must be [name, value, salt]`);
+		}
+		const [name, value, salt] = entry;
+		if (typeof name !== 'string') {
+			throw new Error(`${fnName}: leaf name must be a string`);
+		}
+		return { name, value: value as DigestField, salt: salt as string };
+	}
+	if (entry !== null && typeof entry === 'object') {
+		const o = entry as Record<string, unknown>;
+		if (typeof o.name !== 'string') {
+			throw new Error(`${fnName}: leaf name must be a string`);
+		}
+		// Require an explicit `value` key (symmetric with the array form, which demands all
+		// three positions): a silently-absent value would commit NULL and mask a malformed
+		// leaf. To commit a null-valued attribute, pass `value: null` explicitly.
+		if (!('value' in o)) {
+			throw new Error(`${fnName}: leaf '${o.name}' is missing a value (pass value: null for a null-valued attribute)`);
+		}
+		return { name: o.name, value: o.value as DigestField, salt: o.salt as string };
+	}
+	throw new Error(`${fnName}: each leaf must be a [name, value, salt] array or { name, value, salt } object`);
+}
+
+/** Parse a JSON array of leaves. Throws on unparseable / non-array input. */
+function parseLeaves(json: string, fnName: string): SaltedLeaf[] {
+	const parsed = JSON.parse(json);
+	if (!Array.isArray(parsed)) {
+		throw new Error(`${fnName}: expected a JSON array of leaves`);
+	}
+	return parsed.map((entry) => leafFromJson(entry, fnName));
+}
 
 // Flags for deterministic functions (UTF8 + DETERMINISTIC)
 const DETERMINISTIC_FLAGS = FunctionFlags.UTF8 | FunctionFlags.DETERMINISTIC;
@@ -18,18 +112,112 @@ const NON_DETERMINISTIC_FLAGS = FunctionFlags.UTF8;
  * Plugin registration function
  * This is called by Quereus when the plugin is loaded
  */
-export default function register(_db: Database, _config: Record<string, SqlValue> = {}) {
+export default function register(_db: Database, config: Record<string, SqlValue> = {}) {
+	// Resolve the digest algorithm + output encoding ONCE, at registration, from
+	// load-time config — so the per-call path never branches on them, and so the
+	// digest is stable for the lifetime of the database (a precondition for
+	// `replicable`: every peer that loads the plugin with the same config agrees).
+	const digestHasher = resolveHasher(configAlgorithm(config));
+	const digestEncoder = resolveOutputEncoder(configEncoding(config));
+
 	// Register crypto functions with Quereus
 	const functions = [
 		{
 			schema: {
 				name: 'digest',
-				numArgs: -1, // Variable arguments: data, algorithm?, inputEncoding?, outputEncoding?
+				numArgs: -1, // Variadic over data fields: digest(f1, f2, ..., fN)
 				flags: DETERMINISTIC_FLAGS, // digest is deterministic
+				// Bit-identical across peers/platforms — these digests are signed and persisted.
+				replicable: true,
+				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
+				implementation: (...fields: SqlValue[]) =>
+					digestFields(fields as DigestField[], digestHasher, digestEncoder) as string,
+			},
+		},
+		{
+			schema: {
+				name: 'cid',
+				numArgs: -1, // cid(data, codec?, hash?, base?) — trailing args optional
+				flags: DETERMINISTIC_FLAGS,
+				// Self-describing content address; signed/persisted, so byte-identical across peers.
+				replicable: true,
 				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
 				implementation: (...args: SqlValue[]) => {
-					const [data, algorithm = 'sha256', inputEncoding = 'base64url', outputEncoding = 'base64url'] = args;
-					return digest(data as string, algorithm as any, inputEncoding as any, outputEncoding as any);
+					const [data, codec = 'raw', hash = 'sha2-256', base = 'base32'] = args;
+					return cid(toContentBytes(data, 'cid'), codec as Multicodec, hash as MultihashCode, base as Multibase);
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'cid_v1',
+				numArgs: -1, // cid_v1(digest, hash, codec?, base?) — hash required, trailing args optional
+				flags: DETERMINISTIC_FLAGS,
+				replicable: true,
+				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
+				implementation: (...args: SqlValue[]) => {
+					const [digest, hash, codec = 'raw', base = 'base32'] = args;
+					if (hash == null) {
+						throw new Error("cid_v1: 'hash' argument is required (the multihash code asserting which algorithm produced the digest)");
+					}
+					return cidV1(toContentBytes(digest, 'cid_v1'), hash as MultihashCode, codec as Multicodec, base as Multibase);
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'cid_decode',
+				numArgs: 1, // cid_decode(cid) -> JSON text { version, codec, hashCode, digest }
+				flags: DETERMINISTIC_FLAGS,
+				replicable: true,
+				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
+				implementation: (value: SqlValue) => {
+					const parts = cidDecode(value as string);
+					// JSON object (Quereus has native JSON); digest is base64url, the plugin's canonical text encoding.
+					return JSON.stringify({
+						version: parts.version,
+						codec: parts.codec,
+						hashCode: parts.hashCode,
+						digest: uint8ArrayToString(parts.digest, 'base64url'),
+					});
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'set_commit',
+				numArgs: 1, // set_commit(leaves_json) -> root over a JSON array of [name, value, salt] leaves
+				flags: DETERMINISTIC_FLAGS,
+				// The root is signed and persisted as a commitment, same bar as `digest`.
+				replicable: true,
+				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
+				implementation: (leavesJson: SqlValue) => {
+					if (typeof leavesJson !== 'string') {
+						throw new Error('set_commit: expected a JSON TEXT array of [name, value, salt] leaves');
+					}
+					const leaves = parseLeaves(leavesJson, 'set_commit');
+					return setCommit(leaves, digestHasher, digestEncoder) as string;
+				},
+			},
+		},
+		{
+			schema: {
+				name: 'set_verify',
+				numArgs: 3, // set_verify(root, disclosed_json, hidden_json) -> BOOLEAN
+				flags: DETERMINISTIC_FLAGS, // pure, not persisted — matches `verify` (no `replicable`)
+				returnType: { typeClass: 'scalar' as const, logicalType: BOOLEAN_TYPE, nullable: false },
+				implementation: (root: SqlValue, disclosedJson: SqlValue, hiddenJson: SqlValue) => {
+					// Forgiving contract (mirrors `verify`): any malformed input → false, never throw.
+					try {
+						if (typeof root !== 'string' && !(root instanceof Uint8Array)) return false;
+						if (typeof disclosedJson !== 'string' || typeof hiddenJson !== 'string') return false;
+						const disclosed = parseLeaves(disclosedJson, 'set_verify');
+						const hidden = JSON.parse(hiddenJson);
+						if (!Array.isArray(hidden) || !hidden.every((h) => typeof h === 'string')) return false;
+						return setVerify(root, { disclosed, hidden: hidden as string[] }, digestHasher, digestEncoder);
+					} catch {
+						return false;
+					}
 				},
 			},
 		},
@@ -38,6 +226,15 @@ export default function register(_db: Database, _config: Record<string, SqlValue
 				name: 'sign',
 				numArgs: -1, // Variable arguments: data, privateKey, curve?, inputEncoding?, keyEncoding?, outputEncoding?
 				flags: DETERMINISTIC_FLAGS, // sign is deterministic (same key + data = same signature)
+				// Security: passing a private key as the second argument (literal or bound
+				// parameter) is SAFE with respect to replication. The Quereus engine rebuilds
+				// the replicated statement from evaluated column values, not from source SQL
+				// text, so the key argument is discarded before the record is written — peers
+				// re-execute `INSERT ... VALUES (<signature>)`, never `sign(..., key)`. What
+				// to avoid: storing a raw private key AS a column value, since any persisted
+				// column value is replicated. See docs/transactions.md § "Secrets and the
+				// replicated statement record" and the regression guard in
+				// quereus-plugin-optimystic/test/statement-secret-arg-redaction.spec.ts.
 				returnType: { typeClass: 'scalar' as const, logicalType: TEXT_TYPE, nullable: false },
 				implementation: (...args: SqlValue[]) => {
 					const [data, privateKey, curve = 'secp256k1', inputEncoding = 'base64url', keyEncoding = 'base64url', outputEncoding = 'base64url'] = args;