@optimystic/db-core 0.14.0 → 0.16.2

package/src/transaction/transaction.ts

@@ -1,3 +1,5 @@
+import { randomBytes } from "@noble/hashes/utils.js";
+import { toString as uint8ArrayToString } from "uint8arrays/to-string";
 import type { BlockId } from "../blocks/index.js";
 import type { CollectionId } from "../collection/index.js";
 import { hashString } from "../utility/hash-string.js";
@@ -24,6 +26,17 @@ export type TransactionStamp = {
 	/** Absolute ms epoch after which transaction is invalid */
 	expiration: number;
 
+	/**
+	 * Random per-transaction nonce, folded into {@link TransactionStamp.id}.
+	 *
+	 * Anti-replay for read-free transactions: a transaction with no reads has nothing
+	 * binding it to a point in history beyond {@link expiration}, so without this a
+	 * captured signed read-free transaction could be re-submitted within the TTL window.
+	 * The nonce makes two otherwise-identical transactions from the same peer at the
+	 * same millisecond produce different ids (hence different signed bytes).
+	 */
+	nonce: string;
+
 	/** Hash of the stamp fields (computed) - stable identifier throughout transaction */
 	id: string;
 };
@@ -52,6 +65,44 @@ export type Transaction = {
 	 * Final transaction identity, used in logs
 	 */
 	id: string;
+
+	/**
+	 * Optional client signature (base64url) over {@link clientSignaturePayload}
+	 * `(stamp.id, statements, reads)`, produced at commit by an injected
+	 * {@link TransactionSigner}.
+	 *
+	 * A node that wires a {@link ClientSignatureVerifier} into its
+	 * {@link TransactionValidator} verifies this at pend; where no verifier is wired,
+	 * unsigned transactions are still accepted (migration / single-node-dev posture).
+	 * Plain field on the transaction, so it rides along through serialization/persistence
+	 * for later recovery-time re-verification.
+	 *
+	 * NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
+	 * NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
+	 * reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
+	 * can re-run at recovery time.
+	 */
+	signature?: string;
+
+	/**
+	 * Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
+	 * attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
+	 * capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
+	 * concurrent race between two simultaneously-pending conflicting transactions
+	 * (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
+	 * (priority-0) rivals instead of losing at random forever.
+	 *
+	 * FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
+	 * transaction id, or the client signature. It is deliberately excluded from
+	 * {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
+	 * logical transaction (differing only in priority) keep the same id and signature; folding it
+	 * into either would churn identity/anti-replay on every retry. It rides inside the signed
+	 * cluster `message` (via the pend operation), so it is integrity-protected in transit — a
+	 * relaying peer cannot strip or inflate it without invalidating the message hash — but the
+	 * originating coordinator can still self-assert it (a fairness concern, not a safety one; see
+	 * `docs/correctness.md` Theorem 9).
+	 */
+	priority?: number;
 };
 
 /**
@@ -73,11 +124,58 @@ export type TransactionRef = string; // The transaction ID
 /** Default transaction time-to-live in milliseconds (30 seconds). */
 export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
 
+/**
+ * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
+ * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
+ * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
+ * commits). Two transactions capped out at `MaxPriority` fall back to the existing promise-count /
+ * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
+ */
+export const MaxPriority = 8;
+
+/**
+ * Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
+ * input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
+ * to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
+ * cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
+ * cannot exceed the cap.
+ */
+export function clampPriority(priority: number | undefined): number {
+	if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
+		return 0;
+	}
+	// A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
+	// DOWN to the cap; anything strictly inside the range is floored to an integer.
+	if (priority >= MaxPriority) {
+		return MaxPriority;
+	}
+	return Math.floor(priority);
+}
+
 /** Check whether a transaction stamp has expired. */
 export function isTransactionExpired(stamp: TransactionStamp): boolean {
 	return Date.now() > stamp.expiration;
 }
 
+/** The stamp fields that feed the id hash (everything except the id itself). */
+export type StampFields = Omit<TransactionStamp, 'id'>;
+
+/**
+ * Compute the canonical stamp id from its fields. MUST match the historical field order
+ * (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
+ * existing stamp id and client signature. Both {@link createTransactionStamp} and the
+ * validator's integrity check derive the id through this one function, so a validating node
+ * can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
+ */
+export async function computeStampId(fields: StampFields): Promise<string> {
+	// Destructure and rebuild in fixed order rather than passing `fields` straight to
+	// JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
+	// so the serialized bytes depend on exactly the six fields and nothing else.
+	const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
+	const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
+	return `stamp:${await hashString(stampData)}`;
+}
+
 /**
  * Create a transaction stamp with computed id.
  * The id is a hash of the stamp fields (including expiration).
@@ -90,14 +188,27 @@ export async function createTransactionStamp(
 	ttlMs: number = DEFAULT_TRANSACTION_TTL_MS
 ): Promise<TransactionStamp> {
 	const expiration = timestamp + ttlMs;
-	const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration });
-	const id = `stamp:${await hashString(stampData)}`;
-	return { peerId, timestamp, schemaHash, engineId, expiration, id };
+	// Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
+	// db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
+	// id hash so two otherwise-identical stamps diverge.
+	const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
+	const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
+	return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
 }
 
 /**
  * Create a transaction id from stamp id, statements, and reads.
  * This is the final transaction identity used in logs.
+ *
+ * NOTE: reads are serialized in their given order here (non-canonical). This differs
+ * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
+ * intentional for this ticket — the signature payload is self-contained — but the
+ * non-canonical ordering here is a separate hygiene concern (see
+ * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
+ * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
+ * priority produce the SAME id. Do not add priority here.
  */
 export async function createTransactionId(
 	stampId: string,
@@ -108,6 +219,55 @@ export async function createTransactionId(
 	return `tx:${await hashString(txData)}`;
 }
 
+/**
+ * Version prefix for the client-signature payload, so the signed form can evolve
+ * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
+ * canonical form — this covers transaction INPUTS, not operations.
+ */
+export const CLIENT_SIG_VERSION = 'txsig:v1';
+
+/**
+ * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
+ * (blockId, then revision); statements keep their sequential order.
+ *
+ * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
+ * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
+ * binding" for anti-replay). Both signer and verifier derive the bytes from
+ * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
+ * one function, so they reproduce identical bytes regardless of read ordering.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
+ * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
+ * add priority here.
+ */
+export function clientSignaturePayload(
+	stampId: string,
+	statements: readonly string[],
+	reads: readonly ReadDependency[]
+): Uint8Array {
+	const canonicalReads = [...reads].sort(
+		(a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
+			: a.revision - b.revision
+	);
+	const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
+	return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
+}
+
+/**
+ * Signs the canonical client-signature payload, returning base64url. Async to allow
+ * libp2p `PrivateKey.sign`; tests pass a synchronous fake.
+ */
+export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
+
+/**
+ * Returns true iff `signature` (base64url) is a valid client signature over `payload`
+ * for signer identity `peerId`. Total: returns false, never throws, on any malformed
+ * input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
+ * pass a fake.
+ */
+export type ClientSignatureVerifier =
+	(peerId: string, payload: Uint8Array, signature: string) => boolean;
+
 
 
 /**
@@ -118,8 +278,41 @@ export async function createTransactionId(
  * 1. Parsing the engine-specific statements
  * 2. Executing/re-executing to produce actions
  * 3. Returning the resulting actions per collection
+ *
+ * CONTRACT — an engine must never cause the same action to be applied twice. The
+ * caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
+ * {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
+ * `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
+ * exactly ONE of:
+ *
+ *   (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
+ *       statements, RETURN the actions, and do NOT apply them / do NOT call
+ *       `coordinator.applyActions` / do NOT mutate any collection state. The caller
+ *       applies them exactly once.
+ *
+ *   (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
+ *       Quereus vtab path stages rows into the coordinator during `db.exec`) and then
+ *       RETURN an EMPTY actions array, so the caller re-applies nothing.
+ *
+ * An engine that BOTH applies as a side effect AND returns those same actions
+ * double-applies (the caller re-applies the returned actions). Additionally, a
+ * side-effecting engine used for validation must apply only to the validator's
+ * ISOLATED coordinator — applying to the main coordinator leaks into the validating
+ * node's live state.
  */
 export interface ITransactionEngine {
+	/**
+	 * Stable identifier for this engine.
+	 *
+	 * This is the value stamped into {@link TransactionStamp.engineId} when a
+	 * {@link TransactionSession} builds a transaction, and the key a
+	 * {@link TransactionValidator} resolves the engine by. It MUST match the key the
+	 * engine is registered under in the validator's `engines` map — otherwise a
+	 * validating node rejects the transaction as `Unknown engine: <id>` before it
+	 * ever re-executes.
+	 */
+	readonly id: string;
+
 	/**
 	 * Process a transaction statements to produce actions.
 	 *
@@ -145,6 +338,16 @@ export type ExecutionResult = {
 	results?: Map<CollectionId, any[]>;
 	/** Error message if execution failed */
 	error?: string;
+	/**
+	 * On a PARTIAL multi-collection commit failure, the collections that DID durably
+	 * commit through consensus before the failure (and thus CANNOT be rolled back —
+	 * reconciliation is required). Absent/empty means nothing durably committed, so
+	 * the caller may treat the failure as a clean abort. See
+	 * {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
+	 */
+	committedCollections?: CollectionId[];
+	/** On a partial multi-collection commit failure, the collections that failed to commit. */
+	failedCollections?: CollectionId[];
 };
 
 /**
@@ -196,7 +399,11 @@ export interface ITransactionValidator {
 	/**
 	 * Validate a transaction by re-executing and comparing operations hash.
 	 *
-	 * Validation steps:
+	 * Validation steps (see TransactionValidator.validate for the authoritative order):
+	 * 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
+	 *      since every later step trusts a stamp field)
+	 * 0. Verify the stamp has not expired
+	 * 0.5. Verify the client signature (only if a signature verifier is wired)
 	 * 1. Verify stamp.engineId matches a known engine
 	 * 2. Verify stamp.schemaHash matches local schema
 	 * 3. Verify read dependencies (no stale reads)

package/src/transaction/validator.ts

@@ -1,17 +1,8 @@
-import type { BlockId, CollectionId, IBlock, BlockOperations, Transforms } from '../index.js';
-import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions } from './transaction.js';
+import type { BlockId, CollectionId, Transforms } from '../index.js';
+import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions, ClientSignatureVerifier } from './transaction.js';
 import type { BlockActionState } from '../network/struct.js';
-import { isTransactionExpired } from './transaction.js';
-import { hashString } from '../utility/hash-string.js';
-
-/**
- * Represents an operation on a block within a collection.
- * Must match the Operation type in coordinator.ts for consistent hashing.
- */
-type Operation =
-	| { readonly type: 'insert'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly block: IBlock }
-	| { readonly type: 'update'; readonly collectionId: CollectionId; readonly blockId: BlockId; readonly operations: BlockOperations }
-	| { readonly type: 'delete'; readonly collectionId: CollectionId; readonly blockId: BlockId };
+import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
+import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
 
 /**
  * Engine registration for validation.
@@ -52,13 +43,24 @@ export class TransactionValidator implements ITransactionValidator {
 	constructor(
 		private readonly engines: Map<string, EngineRegistration>,
 		private readonly createValidationCoordinator: ValidationCoordinatorFactory,
-		private readonly blockStateProvider?: BlockStateProvider
+		private readonly blockStateProvider?: BlockStateProvider,
+		private readonly verifyClientSignature?: ClientSignatureVerifier
 	) {}
 
 	async validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult> {
 		const { stamp } = transaction;
 
-		// 0. Check expiration before any other work
+		// 0.0. Integrity: the id must be the true hash of the stamp fields. Runs FIRST because
+		// every later step (expiration, signature, engine/schema selection) trusts a stamp field.
+		// Always-on (one SHA-256, cheap) and independent of whether a signature verifier is wired —
+		// a tampered stamp corrupts expiration and engine selection regardless of signatures.
+		const expectedId = await computeStampId(stamp);
+		if (expectedId !== stamp.id) {
+			return { valid: false, reason: 'Tampered transaction stamp' };
+		}
+
+		// 0. Check expiration before any other work. Ordered BEFORE the signature check so
+		// an attacker cannot learn signature-validity for an already-expired transaction.
 		if (isTransactionExpired(stamp)) {
 			return {
 				valid: false,
@@ -66,6 +68,19 @@ export class TransactionValidator implements ITransactionValidator {
 			};
 		}
 
+		// 0.5. Verify the client signature, if a verifier port is wired. When the port is
+		// absent (migration / single-node-dev posture) unsigned AND signed transactions
+		// both pass — the p2p enforcement flag decides whether to inject the port at all.
+		if (this.verifyClientSignature) {
+			if (transaction.signature === undefined) {
+				return { valid: false, reason: 'Missing client signature' };
+			}
+			const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
+			if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
+				return { valid: false, reason: 'Invalid client signature' };
+			}
+		}
+
 		// 1. Verify engine exists
 		const registration = this.engines.get(stamp.engineId);
 		if (!registration) {
@@ -102,7 +117,24 @@ export class TransactionValidator implements ITransactionValidator {
 		const validationCoordinator = this.createValidationCoordinator();
 
 		try {
-			// 5. Re-execute transaction through engine
+			// 5. Re-execute transaction through engine.
+			//
+			// Which of the two ITransactionEngine models the registered engine uses decides
+			// where isolation comes from (see the contract in transaction.ts):
+			//
+			//   (a) PURE TRANSLATOR (ActionsEngine) — execute() parses statements into
+			//       actions and mutates NOTHING, so even an engine constructed against the
+			//       MAIN coordinator cannot leak into main state here. The returned actions
+			//       are applied once, on the isolated validationCoordinator at step 6.
+			//
+			//   (b) SIDE-EFFECT APPLY (QuereusEngine) — execute() applies while translating
+			//       (db.exec drives the vtab into coordinator.applyActions) and returns EMPTY
+			//       actions. That application lands on whatever coordinator the engine/vtab is
+			//       bound to, NOT on validationCoordinator, so isolation is the caller's job:
+			//       the createValidationCoordinator wiring must bind/reset an isolated world
+			//       (see quereus-validator, which resets the coordinator before each run and
+			//       makes its validationCoordinator.applyActions a no-op). Step 6 is then
+			//       skipped by the empty-actions guard.
 			const result = await registration.engine.execute(transaction);
 			if (!result.success) {
 				return {
@@ -111,20 +143,39 @@ export class TransactionValidator implements ITransactionValidator {
 				};
 			}
 
-			// 6. Apply actions to validation coordinator (builds transforms)
+			// 6. Apply actions to the isolated validation coordinator (builds transforms).
+			// Reached only for pure-translator engines that RETURNED actions; a side-effect
+			// engine returns empty and already applied during execute() (see above).
 			if (result.actions && result.actions.length > 0) {
 				await validationCoordinator.applyActions(result.actions, stamp.id);
 			}
 
 			// 7. Collect operations from validation coordinator
 			const transforms = validationCoordinator.getTransforms();
-			const allOperations = this.collectOperations(transforms);
 
-			// 8. Compute hash
-			const computedHash = await this.hashOperations(allOperations);
-
-			// 9. Compare with sender's hash
+			// 8. Compute hash via the shared operations-hash module — the SAME collect +
+			// canonicalise + hash the coordinator ran, so an honest sender and this
+			// validator cannot diverge on ordering.
+			const computedHash = await hashOperations(collectOperations(transforms));
+
+			// 9. Compare with sender's hash. Split the failure into two distinct causes so
+			// version skew is diagnosable rather than looking like a content fault:
+			//   - VERSION SKEW: the sender's token carries a format version this node does not
+			//     produce (a foreign vN, a bare legacy `ops:`, or an unparseable token → null).
+			//     These bytes are not even comparable, so surface a clear "unsupported format
+			//     version" error. This is DETECTION only — the node cannot cross-compute the
+			//     peer's format, so a mixed-version cluster fails legibly, not silently.
+			//   - CONTENT MISMATCH: same format version, different bytes — a genuine operations
+			//     disagreement (or a Byzantine lie); the existing error is unchanged.
 			if (computedHash !== operationsHash) {
+				const senderVersion = opsHashVersion(operationsHash);
+				if (senderVersion !== OPS_HASH_VERSION) {
+					return {
+						valid: false,
+						reason: `Unsupported operations-hash format version: local=${OPS_HASH_VERSION}, sender=${senderVersion ?? 'unrecognized'}`,
+						computedHash
+					};
+				}
 				return {
 					valid: false,
 					reason: `Operations hash mismatch`,
@@ -142,31 +193,5 @@ export class TransactionValidator implements ITransactionValidator {
 		const registration = this.engines.get(engineId);
 		return registration ? await registration.getSchemaHash() : undefined;
 	}
-
-	/**
-	 * Collect all operations from transforms.
-	 */
-	private collectOperations(transforms: Map<CollectionId, Transforms>): readonly Operation[] {
-		return Array.from(transforms.entries()).flatMap(([collectionId, t]) => [
-			...Object.entries(t.inserts ?? {}).map(([blockId, block]) =>
-				({ type: 'insert' as const, collectionId, blockId, block })
-			),
-			...Object.entries(t.updates ?? {}).map(([blockId, operations]) =>
-				({ type: 'update' as const, collectionId, blockId, operations })
-			),
-			...(t.deletes ?? []).map(blockId =>
-				({ type: 'delete' as const, collectionId, blockId })
-			)
-		]);
-	}
-
-	/**
-	 * Compute hash of all operations.
-	 * Must match TransactionCoordinator.hashOperations for consistent validation.
-	 */
-	private async hashOperations(operations: readonly Operation[]): Promise<string> {
-		const operationsData = JSON.stringify(operations);
-		return `ops:${await hashString(operationsData)}`;
-	}
 }