@optimystic/db-core 0.21.0 → 0.24.0

package/src/cohort-topic/wire/payloads.ts

@@ -1,126 +1,126 @@
-/**
- * Cohort-topic substrate — canonical participant-signature payloads.
- *
- * A participant peer-key-signs its outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the
- * libp2p peer key); a cohort member recomputes the identical byte image to verify that signature
- * before admitting a register (anti-DoS) or honoring a crash-failover `reattach` attestation (so a
- * stray/MITM'd ping cannot usurp a live primary — `docs/cohort-topic.md` §TTL and renewal).
- *
- * Signer and verifier must agree byte-for-byte. Exactly like {@link import("../sig/payloads.js")}
- * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
- * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
- * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
- * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
- * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
- * optional can never disagree across the wire round-trip.
- */
-
-import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
-
-const utf8 = new TextEncoder();
-
-/** A `RegisterV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
-export type RegisterSignable = Omit<RegisterV1, "signature">;
-
-/** A `RenewV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
-export type RenewSignable = Omit<RenewV1, "signature">;
-
-/** Normalize the optional bootstrap-evidence slot: absent and empty-string both map to `null`. */
-function normalizeEvidence(bootstrapEvidence: string | undefined): string | null {
-	return bootstrapEvidence === undefined || bootstrapEvidence === "" ? null : bootstrapEvidence;
-}
-
-/** Canonical signed byte image of a `RegisterV1` body (every field except `signature`). */
-export function registerSigningPayload(body: RegisterSignable): Uint8Array {
-	return utf8.encode(JSON.stringify([
-		"RegisterV1",
-		body.v,
-		body.topicId,
-		body.tier,
-		body.treeTier,
-		body.participantCoord,
-		body.ttl,
-		body.bootstrap ?? false,
-		body.appPayload ?? null,
-		normalizeEvidence(body.bootstrapEvidence),
-		body.timestamp,
-		body.correlationId,
-		// A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
-		// this image identically, so a probe and a register over the same fields produce distinct signatures.
-		body.probe ?? false,
-		// A follow-on cold-start re-issue signs `followOn: true`, everything else `false`. Strictly appended
-		// (sibling to `probe`/`withdraw`) so a MITM cannot strip or flip the follow-on assertion and the
-		// signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
-		// signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
-		body.followOn ?? false,
-	]));
-}
-
-/** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
-export function renewSigningPayload(body: RenewSignable): Uint8Array {
-	return utf8.encode(JSON.stringify([
-		"RenewV1",
-		body.v,
-		body.topicId,
-		body.participantId,
-		body.correlationId,
-		body.timestamp,
-		body.reattach ?? false,
-		// A withdraw tombstone signs `withdraw: true`, a ping/reattach signs `false`. Strictly appended
-		// (array length 7→8) so the reattach-vs-ping distinction is preserved and a third party cannot
-		// evict someone else's registration. Signer (participant) + verifier (db-p2p) move together; no
-		// signatures are persisted, so there is no cross-version concern.
-		body.withdraw ?? false,
-	]));
-}
-
-/** A `CohortGossipV1` minus its `signature` envelope — the bytes the gossiping member peer-key-signs. */
-export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
-
-/**
- * Canonical signed byte image of a `CohortGossipV1` (every field except `signature`). Intra-cohort
- * gossip is peer-key-signed by the originating member so a receiver can drop a frame whose `fromMember`
- * signature does not verify or that comes from a non-cohort member (it can never spoof willingness/load
- * or replicate forged records). Like the other payload helpers, determinism comes from an
- * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
- * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
- * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
- * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
- */
-export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
-	return utf8.encode(JSON.stringify([
-		"CohortGossipV1",
-		g.v,
-		g.fromMember,
-		g.coord,
-		g.cohortEpoch,
-		g.treeTier,
-		g.willingnessBits,
-		g.loadBuckets,
-		g.windowSeconds,
-		g.topicSummaries.map((s) => [
-			s.topicId,
-			s.tier,
-			s.directParticipants,
-			s.arrivalsPerMin,
-			s.queriesPerMin,
-			s.promoted,
-			s.childCohortCount,
-		]),
-		(g.records ?? []).map((r) => [
-			r.topicId,
-			r.participantId,
-			r.tier,
-			r.primary,
-			r.backups,
-			r.attachedAt,
-			r.lastPing,
-			r.ttl,
-			r.appState ?? null,
-		]),
-		(g.evicted ?? []).map((e) => [e.topicId, e.participantId, e.lastPing]),
-		(g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
-		(g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
-		g.timestamp,
-	]));
-}
+/**
+ * Cohort-topic substrate — canonical participant-signature payloads.
+ *
+ * A participant peer-key-signs its outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the
+ * libp2p peer key); a cohort member recomputes the identical byte image to verify that signature
+ * before admitting a register (anti-DoS) or honoring a crash-failover `reattach` attestation (so a
+ * stray/MITM'd ping cannot usurp a live primary — `docs/cohort-topic.md` §TTL and renewal).
+ *
+ * Signer and verifier must agree byte-for-byte. Exactly like {@link import("../sig/payloads.js")}
+ * for the threshold-signed notices, determinism comes from encoding an explicitly-ordered JSON
+ * array (array order is stable, unlike object key order) as UTF-8 — never the `signature` envelope.
+ * Optional fields are normalized to a fixed placeholder (`bootstrap`→`false`, `probe`→`false`,
+ * `followOn`→`false`, `appPayload`→`null`, `bootstrapEvidence`→`null` with an empty string treated as
+ * absent, `reattach`→`false`, `withdraw`→`false`) so an absent optional and a present-but-default
+ * optional can never disagree across the wire round-trip.
+ */
+
+import type { CohortGossipV1, RegisterV1, RenewV1 } from "./types.js";
+
+const utf8 = new TextEncoder();
+
+/** A `RegisterV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
+export type RegisterSignable = Omit<RegisterV1, "signature">;
+
+/** A `RenewV1` minus its `signature` envelope — the bytes the participant peer-key-signs. */
+export type RenewSignable = Omit<RenewV1, "signature">;
+
+/** Normalize the optional bootstrap-evidence slot: absent and empty-string both map to `null`. */
+function normalizeEvidence(bootstrapEvidence: string | undefined): string | null {
+	return bootstrapEvidence === undefined || bootstrapEvidence === "" ? null : bootstrapEvidence;
+}
+
+/** Canonical signed byte image of a `RegisterV1` body (every field except `signature`). */
+export function registerSigningPayload(body: RegisterSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"RegisterV1",
+		body.v,
+		body.topicId,
+		body.tier,
+		body.treeTier,
+		body.participantCoord,
+		body.ttl,
+		body.bootstrap ?? false,
+		body.appPayload ?? null,
+		normalizeEvidence(body.bootstrapEvidence),
+		body.timestamp,
+		body.correlationId,
+		// A read-only probe signs `probe: true`; a normal register signs `false`. Both sides recompute
+		// this image identically, so a probe and a register over the same fields produce distinct signatures.
+		body.probe ?? false,
+		// A follow-on cold-start re-issue signs `followOn: true`, everything else `false`. Strictly appended
+		// (sibling to `probe`/`withdraw`) so a MITM cannot strip or flip the follow-on assertion and the
+		// signer (participant) + verifier (db-p2p cohort) agree byte-for-byte. Safe to append: no register
+		// signatures are persisted (each is recomputed per verify), so there is no cross-version image concern.
+		body.followOn ?? false,
+	]));
+}
+
+/** Canonical signed byte image of a `RenewV1` body (every field except `signature`). */
+export function renewSigningPayload(body: RenewSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"RenewV1",
+		body.v,
+		body.topicId,
+		body.participantId,
+		body.correlationId,
+		body.timestamp,
+		body.reattach ?? false,
+		// A withdraw tombstone signs `withdraw: true`, a ping/reattach signs `false`. Strictly appended
+		// (array length 7→8) so the reattach-vs-ping distinction is preserved and a third party cannot
+		// evict someone else's registration. Signer (participant) + verifier (db-p2p) move together; no
+		// signatures are persisted, so there is no cross-version concern.
+		body.withdraw ?? false,
+	]));
+}
+
+/** A `CohortGossipV1` minus its `signature` envelope — the bytes the gossiping member peer-key-signs. */
+export type CohortGossipSignable = Omit<CohortGossipV1, "signature">;
+
+/**
+ * Canonical signed byte image of a `CohortGossipV1` (every field except `signature`). Intra-cohort
+ * gossip is peer-key-signed by the originating member so a receiver can drop a frame whose `fromMember`
+ * signature does not verify or that comes from a non-cohort member (it can never spoof willingness/load
+ * or replicate forged records). Like the other payload helpers, determinism comes from an
+ * explicitly-ordered array — nested records/summaries/evictions are emitted as fixed ordered tuples so
+ * the signer and the receiver (which re-derives this image from the validated frame) agree byte-for-byte.
+ * Absent optionals (`records`/`evicted`/`childLinks`/`childUnlinks`) normalize to `[]`, and `appState` to
+ * `null`. `childLinks`/`childUnlinks` are covered so a MITM cannot strip or inject a child link/unlink.
+ */
+export function cohortGossipSigningPayload(g: CohortGossipSignable): Uint8Array {
+	return utf8.encode(JSON.stringify([
+		"CohortGossipV1",
+		g.v,
+		g.fromMember,
+		g.coord,
+		g.cohortEpoch,
+		g.treeTier,
+		g.willingnessBits,
+		g.loadBuckets,
+		g.windowSeconds,
+		g.topicSummaries.map((s) => [
+			s.topicId,
+			s.tier,
+			s.directParticipants,
+			s.arrivalsPerMin,
+			s.queriesPerMin,
+			s.promoted,
+			s.childCohortCount,
+		]),
+		(g.records ?? []).map((r) => [
+			r.topicId,
+			r.participantId,
+			r.tier,
+			r.primary,
+			r.backups,
+			r.attachedAt,
+			r.lastPing,
+			r.ttl,
+			r.appState ?? null,
+		]),
+		(g.evicted ?? []).map((e) => [e.topicId, e.participantId, e.lastPing]),
+		(g.childLinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
+		(g.childUnlinks ?? []).map((c) => [c.topicId, c.childCohortCoord, c.effectiveAt]),
+		g.timestamp,
+	]));
+}

package/src/cohort-topic/wire/primitives.ts

@@ -1,188 +1,188 @@
-/**
- * Cohort-topic wire substrate — shared structural-validation primitives.
- *
- * The generic per-field checks every wire codec across the substrate (cohort-topic, matchmaking,
- * reactivity) uses to narrow an already-parsed `unknown` (the output of `JSON.parse` on a decoded
- * frame) into a validated V1 shape. Each helper throws {@link CohortWireError} on a structural defect:
- * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode as
- * base64url, or an out-of-range numeric.
- *
- * These are the *only* generic primitives — domain-specific narrowing (the `validate*V1` functions, the
- * cohort-topic `tier` / `treeTier` semantics, matchmaking utf8 coders, reactivity notification shapes)
- * lives in the modules that own those message shapes. Keeping the primitives in one place means a
- * hardening tweak to a check (e.g. the fixed-length byte-width guard in {@link b64urlFixedLen}) lands
- * once and every consumer inherits it.
- */
-
-import { b64urlToBytes } from "./codec.js";
-
-/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
-export class CohortWireError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = "CohortWireError";
-	}
-}
-
-/** Throw a {@link CohortWireError} with `message`. */
-export function failWire(message: string): never {
-	throw new CohortWireError(message);
-}
-
-/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
-export function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
-	if (value !== undefined) {
-		obj[key] = value;
-	}
-}
-
-/** Narrow `value` to a plain object (not null, not an array), or throw. */
-export function asObject(value: unknown, what: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		failWire(`${what}: expected an object`);
-	}
-	return value as Record<string, unknown>;
-}
-
-/** Require `obj.v === 1`. */
-export function requireV1(obj: Record<string, unknown>, what: string): void {
-	if (obj["v"] !== 1) {
-		failWire(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
-	}
-}
-
-/** Require `obj[key]` to be a string; returns it. */
-export function reqString(obj: Record<string, unknown>, key: string, what: string): string {
-	const value = obj[key];
-	if (typeof value !== "string") {
-		failWire(`${what}: field "${key}" must be a string`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a string, `undefined` when absent; throw on any other type. */
-export function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "string") {
-		failWire(`${what}: field "${key}" must be a string when present`);
-	}
-	return value;
-}
-
-/** Require `obj[key]` to be a finite number; returns it. */
-export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
-	const value = obj[key];
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		failWire(`${what}: field "${key}" must be a finite number`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a finite number, `undefined` when absent; throw on any other type. */
-export function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		failWire(`${what}: field "${key}" must be a finite number when present`);
-	}
-	return value;
-}
-
-/** Require `obj[key]` to be a boolean; returns it. */
-export function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
-	const value = obj[key];
-	if (typeof value !== "boolean") {
-		failWire(`${what}: field "${key}" must be a boolean`);
-	}
-	return value;
-}
-
-/** Return `obj[key]` when it is a boolean, `undefined` when absent; throw on any other type. */
-export function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
-	const value = obj[key];
-	if (value === undefined) {
-		return undefined;
-	}
-	if (typeof value !== "boolean") {
-		failWire(`${what}: field "${key}" must be a boolean when present`);
-	}
-	return value;
-}
-
-/**
- * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
- * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
- * than a pre-extracted value — this composes with the other `req*` helpers.
- */
-export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
-	const value = reqFiniteNumber(obj, key, what);
-	if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
-		const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
-		failWire(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
-	}
-	return value;
-}
-
-/** Require `obj[key]` to be an array of strings; returns it. */
-export function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
-	const value = obj[key];
-	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
-		failWire(`${what}: field "${key}" must be an array of strings`);
-	}
-	return value as string[];
-}
-
-/** Return `obj[key]` when it is an array of strings, `undefined` when absent; throw on any other type. */
-export function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
-	if (obj[key] === undefined) {
-		return undefined;
-	}
-	return reqStringArray(obj, key, what);
-}
-
-/** Require `obj[key]` to be one of `allowed`; returns it narrowed to the enum type. */
-export function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
-	const value = obj[key];
-	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
-		failWire(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
-	}
-	return value as T;
-}
-
-/**
- * Assert a base64url string decodes cleanly; returns it unchanged. Used for variable-width fields —
- * peer ids (multihash-encoded, not 32 raw bytes), signatures, and opaque application payloads.
- *
- * NOTE: no max-length bound here. A hostile peer can still bloat one of these variable-width fields
- * (e.g. `participantCoord`, a signature) into a large map key in the store / rate limiter / replay
- * guard. Their widths aren't pinned by the spec, so a ceiling would be a chosen policy value rather
- * than a decode of the format. If a bloated one is ever seen as a map key in practice, add a
- * `b64urlMaxLen` ceiling here. (Fixed-width hash-derived fields go through `b64urlFixedLen` instead.)
- */
-export function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		failWire(`${what}: field "${key}" is not valid base64url`);
-	}
-	return value;
-}
-
-/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
-export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
-	let bytes: Uint8Array;
-	try {
-		bytes = b64urlToBytes(value);
-	} catch {
-		return failWire(`${what}: field "${key}" is not valid base64url`);
-	}
-	if (bytes.length !== len) {
-		failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
-	}
-	return value;
-}
+/**
+ * Cohort-topic wire substrate — shared structural-validation primitives.
+ *
+ * The generic per-field checks every wire codec across the substrate (cohort-topic, matchmaking,
+ * reactivity) uses to narrow an already-parsed `unknown` (the output of `JSON.parse` on a decoded
+ * frame) into a validated V1 shape. Each helper throws {@link CohortWireError} on a structural defect:
+ * missing required field, wrong `v`, out-of-enum discriminant, a byte field that does not decode as
+ * base64url, or an out-of-range numeric.
+ *
+ * These are the *only* generic primitives — domain-specific narrowing (the `validate*V1` functions, the
+ * cohort-topic `tier` / `treeTier` semantics, matchmaking utf8 coders, reactivity notification shapes)
+ * lives in the modules that own those message shapes. Keeping the primitives in one place means a
+ * hardening tweak to a check (e.g. the fixed-length byte-width guard in {@link b64urlFixedLen}) lands
+ * once and every consumer inherits it.
+ */
+
+import { b64urlToBytes } from "./codec.js";
+
+/** Thrown for any malformed, oversized, or structurally invalid cohort-topic frame. */
+export class CohortWireError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CohortWireError";
+	}
+}
+
+/** Throw a {@link CohortWireError} with `message`. */
+export function failWire(message: string): never {
+	throw new CohortWireError(message);
+}
+
+/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
+export function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
+	if (value !== undefined) {
+		obj[key] = value;
+	}
+}
+
+/** Narrow `value` to a plain object (not null, not an array), or throw. */
+export function asObject(value: unknown, what: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		failWire(`${what}: expected an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+/** Require `obj.v === 1`. */
+export function requireV1(obj: Record<string, unknown>, what: string): void {
+	if (obj["v"] !== 1) {
+		failWire(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
+	}
+}
+
+/** Require `obj[key]` to be a string; returns it. */
+export function reqString(obj: Record<string, unknown>, key: string, what: string): string {
+	const value = obj[key];
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a string, `undefined` when absent; throw on any other type. */
+export function optString(obj: Record<string, unknown>, key: string, what: string): string | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "string") {
+		failWire(`${what}: field "${key}" must be a string when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a finite number; returns it. */
+export function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
+	const value = obj[key];
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a finite number, `undefined` when absent; throw on any other type. */
+export function optFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		failWire(`${what}: field "${key}" must be a finite number when present`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be a boolean; returns it. */
+export function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
+	const value = obj[key];
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean`);
+	}
+	return value;
+}
+
+/** Return `obj[key]` when it is a boolean, `undefined` when absent; throw on any other type. */
+export function optBool(obj: Record<string, unknown>, key: string, what: string): boolean | undefined {
+	const value = obj[key];
+	if (value === undefined) {
+		return undefined;
+	}
+	if (typeof value !== "boolean") {
+		failWire(`${what}: field "${key}" must be a boolean when present`);
+	}
+	return value;
+}
+
+/**
+ * Require `obj[key]` to be an integer `>= min` (and `<= max` when supplied); returns it. Reads and
+ * finite-checks the field itself (via {@link reqFiniteNumber}) so callers pass the object + key rather
+ * than a pre-extracted value — this composes with the other `req*` helpers.
+ */
+export function reqIntInRange(obj: Record<string, unknown>, key: string, what: string, min: number, max?: number): number {
+	const value = reqFiniteNumber(obj, key, what);
+	if (!Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
+		const bound = max === undefined ? `>= ${min}` : `in ${min}..${max}`;
+		failWire(`${what}: field "${key}" must be an integer ${bound}, got ${value}`);
+	}
+	return value;
+}
+
+/** Require `obj[key]` to be an array of strings; returns it. */
+export function reqStringArray(obj: Record<string, unknown>, key: string, what: string): string[] {
+	const value = obj[key];
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		failWire(`${what}: field "${key}" must be an array of strings`);
+	}
+	return value as string[];
+}
+
+/** Return `obj[key]` when it is an array of strings, `undefined` when absent; throw on any other type. */
+export function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
+	if (obj[key] === undefined) {
+		return undefined;
+	}
+	return reqStringArray(obj, key, what);
+}
+
+/** Require `obj[key]` to be one of `allowed`; returns it narrowed to the enum type. */
+export function reqEnum<T extends string>(obj: Record<string, unknown>, key: string, allowed: readonly T[], what: string): T {
+	const value = obj[key];
+	if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+		failWire(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
+	}
+	return value as T;
+}
+
+/**
+ * Assert a base64url string decodes cleanly; returns it unchanged. Used for variable-width fields —
+ * peer ids (multihash-encoded, not 32 raw bytes), signatures, and opaque application payloads.
+ *
+ * NOTE: no max-length bound here. A hostile peer can still bloat one of these variable-width fields
+ * (e.g. `participantCoord`, a signature) into a large map key in the store / rate limiter / replay
+ * guard. Their widths aren't pinned by the spec, so a ceiling would be a chosen policy value rather
+ * than a decode of the format. If a bloated one is ever seen as a map key in practice, add a
+ * `b64urlMaxLen` ceiling here. (Fixed-width hash-derived fields go through `b64urlFixedLen` instead.)
+ */
+export function b64urlField(value: string, key: string, what: string): string {
+	try {
+		b64urlToBytes(value);
+	} catch {
+		failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	return value;
+}
+
+/** Assert a base64url string decodes cleanly to exactly `len` bytes; returns it unchanged. */
+export function b64urlFixedLen(value: string, key: string, len: number, what: string): string {
+	let bytes: Uint8Array;
+	try {
+		bytes = b64urlToBytes(value);
+	} catch {
+		return failWire(`${what}: field "${key}" is not valid base64url`);
+	}
+	if (bytes.length !== len) {
+		failWire(`${what}: field "${key}" must decode to ${len} bytes, got ${bytes.length}`);
+	}
+	return value;
+}