@optimystic/db-core 0.14.1 → 0.16.2

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

@@ -8,8 +8,28 @@
  * narrow cleanly or throw.
  */
 
-import { b64urlToBytes } from "./codec.js";
+import { DEFAULT_D_MAX_CAP } from "../dmax.js";
+import {
+	assignDefined,
+	asObject,
+	b64urlField,
+	b64urlFixedLen,
+	failWire as fail,
+	optBool,
+	optFiniteNumber,
+	optString,
+	optStringArray,
+	reqBool,
+	reqEnum,
+	reqFiniteNumber,
+	reqString,
+	reqStringArray,
+	requireV1,
+} from "./primitives.js";
 import type {
+	ChildLinkRefV1,
+	ChildLinkReplyV1,
+	ChildLinkV1,
 	CohortGossipV1,
 	CohortTopicSummary,
 	DemotionNoticeV1,
@@ -28,109 +48,11 @@ import type {
 	TopicTrafficV1,
 } from "./types.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";
-	}
-}
-
-function fail(message: string): never {
-	throw new CohortWireError(message);
-}
-
-/** Set `obj[key]` only when `value` is defined — keeps absent optionals off the decoded object. */
-function assignDefined<T extends object, K extends keyof T>(obj: T, key: K, value: T[K] | undefined): void {
-	if (value !== undefined) {
-		obj[key] = value;
-	}
-}
-
-function asObject(value: unknown, what: string): Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		fail(`${what}: expected an object`);
-	}
-	return value as Record<string, unknown>;
-}
-
-function requireV1(obj: Record<string, unknown>, what: string): void {
-	if (obj["v"] !== 1) {
-		fail(`${what}: expected v === 1, got ${JSON.stringify(obj["v"])}`);
-	}
-}
-
-function reqString(obj: Record<string, unknown>, key: string, what: string): string {
-	const value = obj[key];
-	if (typeof value !== "string") {
-		fail(`${what}: field "${key}" must be a string`);
-	}
-	return value;
-}
-
-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") {
-		fail(`${what}: field "${key}" must be a string when present`);
-	}
-	return value;
-}
-
-function reqFiniteNumber(obj: Record<string, unknown>, key: string, what: string): number {
-	const value = obj[key];
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		fail(`${what}: field "${key}" must be a finite number`);
-	}
-	return value;
-}
-
-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)) {
-		fail(`${what}: field "${key}" must be a finite number when present`);
-	}
-	return value;
-}
-
-function reqBool(obj: Record<string, unknown>, key: string, what: string): boolean {
-	const value = obj[key];
-	if (typeof value !== "boolean") {
-		fail(`${what}: field "${key}" must be a boolean`);
-	}
-	return value;
-}
-
-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") {
-		fail(`${what}: field "${key}" must be a boolean when present`);
-	}
-	return value;
-}
-
-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")) {
-		fail(`${what}: field "${key}" must be an array of strings`);
-	}
-	return value as string[];
-}
-
-function optStringArray(obj: Record<string, unknown>, key: string, what: string): string[] | undefined {
-	if (obj[key] === undefined) {
-		return undefined;
-	}
-	return reqStringArray(obj, key, what);
-}
+// The generic structural-validation primitives (`fail`/`asObject`/`req*`/`opt*`/`b64url*`/`reqEnum`/…)
+// live in ./primitives.js and are imported above; only the cohort-topic domain validators and the
+// tier-semantics helpers below stay local. `CohortWireError` is re-exported here so existing importers
+// of this module (codec, wire/index, matchmaking, reactivity) are unaffected by the move.
+export { CohortWireError } from "./primitives.js";
 
 function tier(value: number, what: string): number {
 	if (!Number.isInteger(value) || value < 0 || value > 3) {
@@ -139,23 +61,24 @@ function tier(value: number, what: string): number {
 	return value;
 }
 
-/** Assert a base64url string decodes cleanly; returns it unchanged. */
-function b64urlField(value: string, key: string, what: string): string {
-	try {
-		b64urlToBytes(value);
-	} catch {
-		fail(`${what}: field "${key}" is not valid base64url`);
+/**
+ * Validate a `treeTier` (the walk-toward-root start tier `d` a register/redirect targets): an integer in
+ * `0..DEFAULT_D_MAX_CAP`. `d_max_cap` (60) is the substrate's own ceiling on useful walk depth, so a
+ * `treeTier` above it cannot correspond to a real walk position. Rejecting here keeps an out-of-range value
+ * from reaching `addressing.coord()` downstream — whose `coordD` throws a raw `RangeError` for a
+ * non-integer / negative / `> 255` tier, an unclassified crash rather than a clean malformed-frame rejection.
+ */
+function treeTier(value: number, what: string): number {
+	if (!Number.isInteger(value) || value < 0 || value > DEFAULT_D_MAX_CAP) {
+		fail(`${what}: treeTier must be an integer in 0..${DEFAULT_D_MAX_CAP}, got ${value}`);
 	}
 	return value;
 }
 
-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)) {
-		fail(`${what}: field "${key}" must be one of ${allowed.join(" | ")}`);
-	}
-	return value as T;
-}
+/** Ring-coord / topic-id / epoch byte width (SHA-256 truncated to the ring width). */
+const COORD_BYTES = 32;
+/** Correlation-id byte width (a 16-byte nonce minted per walk probe / renew). */
+const CORRELATION_BYTES = 16;
 
 const REGISTER_RESULTS: readonly RegisterResult[] = [
 	"accepted",
@@ -171,13 +94,13 @@ export function validateRegisterV1(value: unknown): RegisterV1 {
 	requireV1(obj, what);
 	const out: RegisterV1 = {
 		v: 1,
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
 		tier: tier(reqFiniteNumber(obj, "tier", what), what),
-		treeTier: reqFiniteNumber(obj, "treeTier", what),
+		treeTier: treeTier(reqFiniteNumber(obj, "treeTier", what), what),
 		participantCoord: b64urlField(reqString(obj, "participantCoord", what), "participantCoord", what),
 		ttl: reqFiniteNumber(obj, "ttl", what),
 		timestamp: reqFiniteNumber(obj, "timestamp", what),
-		correlationId: b64urlField(reqString(obj, "correlationId", what), "correlationId", what),
+		correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
 		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
 	};
 	const bootstrap = optBool(obj, "bootstrap", what);
@@ -188,6 +111,21 @@ export function validateRegisterV1(value: unknown): RegisterV1 {
 	if (probe !== undefined) {
 		out.probe = probe;
 	}
+	const followOn = optBool(obj, "followOn", what);
+	if (followOn !== undefined) {
+		out.followOn = followOn;
+	}
+	// `bootstrap`, `followOn`, and `probe` are pairwise mutually exclusive — the walk sets at most one
+	// (bootstrap only at the tier-0 root re-issue, followOn only at a `treeTier >= 1` redirect target,
+	// probe never instantiates). A frame that sets more than one is malformed / adversarial.
+	if ([bootstrap, followOn, probe].filter((flag) => flag === true).length > 1) {
+		fail(`${what}: at most one of bootstrap, followOn, probe may be set`);
+	}
+	// A follow-on is by definition a deeper-than-root growth point, so `treeTier >= 1`. A `followOn: true`
+	// at the root (treeTier 0) would be a bootstrap, not a follow-on — reject it as malformed.
+	if (followOn === true && out.treeTier < 1) {
+		fail(`${what}: followOn requires treeTier >= 1, got ${out.treeTier}`);
+	}
 	const appPayload = optString(obj, "appPayload", what);
 	if (appPayload !== undefined) {
 		out.appPayload = b64urlField(appPayload, "appPayload", what);
@@ -226,12 +164,17 @@ export function validateRegisterReplyV1(value: unknown): RegisterReplyV1 {
 	assignDefined(out, "backups", optStringArray(obj, "backups", what));
 	const cohortEpoch = optString(obj, "cohortEpoch", what);
 	if (cohortEpoch !== undefined) {
+		// NOTE: cohortEpoch is NOT length-pinned though real epochs are a 32-byte SHA-256 — several
+		// test fixtures (db-core reactivity + db-p2p) feed 1-byte synthetic epochs. Pinning is tracked
+		// by debt-cohort-topic-pin-cohort-epoch. See b64urlField's note.
 		out.cohortEpoch = b64urlField(cohortEpoch, "cohortEpoch", what);
 	}
 	assignDefined(out, "cohortMembers", optStringArray(obj, "cohortMembers", what));
 	if (obj["topicTraffic"] !== undefined) {
 		out.topicTraffic = validateTopicTrafficV1(obj["topicTraffic"]);
 	}
+	// NOTE: `targetTier` is range-checked in the walk loop (walk.ts, case "promoted"), not here — an
+	// out-of-range redirect must surface as a `retry_later` outcome, not a decode-time throw.
 	assignDefined(out, "targetTier", optFiniteNumber(obj, "targetTier", what));
 	assignDefined(out, "candidateMembers", optStringArray(obj, "candidateMembers", what));
 	assignDefined(out, "retryAfterMs", optFiniteNumber(obj, "retryAfterMs", what));
@@ -245,9 +188,9 @@ export function validateRenewV1(value: unknown): RenewV1 {
 	requireV1(obj, what);
 	const out: RenewV1 = {
 		v: 1,
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
 		participantId: reqString(obj, "participantId", what),
-		correlationId: b64urlField(reqString(obj, "correlationId", what), "correlationId", what),
+		correlationId: b64urlFixedLen(reqString(obj, "correlationId", what), "correlationId", CORRELATION_BYTES, what),
 		timestamp: reqFiniteNumber(obj, "timestamp", what),
 		signature: b64urlField(reqString(obj, "signature", what), "signature", what),
 	};
@@ -268,6 +211,8 @@ export function validateRenewReplyV1(value: unknown): RenewReplyV1 {
 	assignDefined(out, "newBackups", optStringArray(obj, "newBackups", what));
 	const cohortEpoch = optString(obj, "cohortEpoch", what);
 	if (cohortEpoch !== undefined) {
+		// NOTE: cohortEpoch is NOT length-pinned — see validateRegisterReplyV1's note and
+		// debt-cohort-topic-pin-cohort-epoch.
 		out.cohortEpoch = b64urlField(cohortEpoch, "cohortEpoch", what);
 	}
 	return out;
@@ -277,11 +222,17 @@ export function validatePromotionNoticeV1(value: unknown): PromotionNoticeV1 {
 	const what = "PromotionNoticeV1";
 	const obj = asObject(value, what);
 	requireV1(obj, what);
+	const fromTier = treeTier(reqFiniteNumber(obj, "fromTier", what), what);
+	const toTier = treeTier(reqFiniteNumber(obj, "toTier", what), what);
+	if (toTier !== fromTier + 1) {
+		fail(`${what}: toTier must equal fromTier + 1, got fromTier=${fromTier} toTier=${toTier}`);
+	}
 	return {
 		v: 1,
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
-		fromTier: tier(reqFiniteNumber(obj, "fromTier", what), what),
-		toTier: tier(reqFiniteNumber(obj, "toTier", what), what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
+		fromTier,
+		toTier,
+		cohortCoord: b64urlFixedLen(reqString(obj, "cohortCoord", what), "cohortCoord", COORD_BYTES, what),
 		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
 		thresholdSig: b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what),
 		signers: reqStringArray(obj, "signers", what),
@@ -295,9 +246,10 @@ export function validateDemotionNoticeV1(value: unknown): DemotionNoticeV1 {
 	requireV1(obj, what);
 	return {
 		v: 1,
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
-		tier: tier(reqFiniteNumber(obj, "tier", what), what),
-		parentCohortCoord: b64urlField(reqString(obj, "parentCohortCoord", what), "parentCohortCoord", what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
+		tier: treeTier(reqFiniteNumber(obj, "tier", what), what),
+		parentCohortCoord: b64urlFixedLen(reqString(obj, "parentCohortCoord", what), "parentCohortCoord", COORD_BYTES, what),
+		cohortCoord: b64urlFixedLen(reqString(obj, "cohortCoord", what), "cohortCoord", COORD_BYTES, what),
 		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
 		thresholdSig: b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what),
 		signers: reqStringArray(obj, "signers", what),
@@ -305,6 +257,56 @@ export function validateDemotionNoticeV1(value: unknown): DemotionNoticeV1 {
 	};
 }
 
+/**
+ * Validate a {@link ChildLinkV1}. Enforces `childTier >= 1` (the root never links), `tier` in 0..3, and
+ * well-formed base64url on every byte field. The hash-derived fields (`topicId` / `childCohortCoord` /
+ * `cohortEpoch`) are additionally length-checked to exactly 32 bytes (each is a SHA-256 truncation); the
+ * `childParticipantCoord` follows the lenient `RegisterV1` convention (base64url only — a participant
+ * coord is not always 32 raw bytes, e.g. a multihash-encoded peer id in tests). When `minSigs`
+ * is supplied AND the frame carries a threshold signature (`thresholdSig` non-empty), `signers.length` must
+ * be `>= minSigs`; a key-less-interim frame carries neither, so that cross-field bound is skipped. `minSigs`
+ * is optional so a bare structural decode (no quorum context) still narrows the frame.
+ */
+export function validateChildLinkV1(value: unknown, minSigs?: number): ChildLinkV1 {
+	const what = "ChildLinkV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const childTier = reqFiniteNumber(obj, "childTier", what);
+	if (!Number.isInteger(childTier) || childTier < 1) {
+		fail(`${what}: childTier must be an integer >= 1, got ${childTier}`);
+	}
+	const thresholdSig = b64urlField(reqString(obj, "thresholdSig", what), "thresholdSig", what);
+	const signers = reqStringArray(obj, "signers", what).map((s) => b64urlField(s, "signers", what));
+	if (minSigs !== undefined && thresholdSig.length > 0 && signers.length < minSigs) {
+		fail(`${what}: a signed child-link needs signers.length >= ${minSigs}, got ${signers.length}`);
+	}
+	return {
+		v: 1,
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
+		childCohortCoord: b64urlFixedLen(reqString(obj, "childCohortCoord", what), "childCohortCoord", COORD_BYTES, what),
+		childParticipantCoord: b64urlField(reqString(obj, "childParticipantCoord", what), "childParticipantCoord", what),
+		childTier,
+		tier: tier(reqFiniteNumber(obj, "tier", what), what),
+		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
+		thresholdSig,
+		signers,
+		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+	};
+}
+
+/** Validate a {@link ChildLinkReplyV1}: `result` in `linked | rejected`, optional human-readable `reason`. */
+export function validateChildLinkReplyV1(value: unknown): ChildLinkReplyV1 {
+	const what = "ChildLinkReplyV1";
+	const obj = asObject(value, what);
+	requireV1(obj, what);
+	const out: ChildLinkReplyV1 = {
+		v: 1,
+		result: reqEnum(obj, "result", ["linked", "rejected"] as const, what),
+	};
+	assignDefined(out, "reason", optString(obj, "reason", what));
+	return out;
+}
+
 function validateCohortTopicSummary(value: unknown): CohortTopicSummary {
 	const what = "CohortTopicSummary";
 	const obj = asObject(value, what);
@@ -323,7 +325,7 @@ function validateGossipRecordV1(value: unknown): GossipRecordV1 {
 	const what = "GossipRecordV1";
 	const obj = asObject(value, what);
 	const out: GossipRecordV1 = {
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
 		participantId: b64urlField(reqString(obj, "participantId", what), "participantId", what),
 		tier: tier(reqFiniteNumber(obj, "tier", what), what),
 		primary: b64urlField(reqString(obj, "primary", what), "primary", what),
@@ -343,8 +345,19 @@ function validateGossipRecordRefV1(value: unknown): GossipRecordRefV1 {
 	const what = "GossipRecordRefV1";
 	const obj = asObject(value, what);
 	return {
-		topicId: b64urlField(reqString(obj, "topicId", what), "topicId", what),
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
 		participantId: b64urlField(reqString(obj, "participantId", what), "participantId", what),
+		lastPing: reqFiniteNumber(obj, "lastPing", what),
+	};
+}
+
+function validateChildLinkRefV1(value: unknown): ChildLinkRefV1 {
+	const what = "ChildLinkRefV1";
+	const obj = asObject(value, what);
+	return {
+		topicId: b64urlFixedLen(reqString(obj, "topicId", what), "topicId", COORD_BYTES, what),
+		childCohortCoord: b64urlField(reqString(obj, "childCohortCoord", what), "childCohortCoord", what),
+		effectiveAt: reqFiniteNumber(obj, "effectiveAt", what),
 	};
 }
 
@@ -372,11 +385,16 @@ export function validateCohortGossipV1(value: unknown): CohortGossipV1 {
 	if (!Array.isArray(summaries)) {
 		fail(`${what}: field "topicSummaries" must be an array`);
 	}
+	const treeTier = reqFiniteNumber(obj, "treeTier", what);
+	if (!Number.isInteger(treeTier) || treeTier < 0) {
+		fail(`${what}: field "treeTier" must be a non-negative integer, got ${treeTier}`);
+	}
 	const out: CohortGossipV1 = {
 		v: 1,
 		fromMember: reqString(obj, "fromMember", what),
-		coord: b64urlField(reqString(obj, "coord", what), "coord", what),
+		coord: b64urlFixedLen(reqString(obj, "coord", what), "coord", COORD_BYTES, what),
 		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
+		treeTier,
 		willingnessBits,
 		loadBuckets: loadBuckets as number[],
 		windowSeconds: reqFiniteNumber(obj, "windowSeconds", what),
@@ -398,10 +416,24 @@ export function validateCohortGossipV1(value: unknown): CohortGossipV1 {
 		}
 		out.evicted = evicted.map(validateGossipRecordRefV1);
 	}
+	const childLinks = obj["childLinks"];
+	if (childLinks !== undefined) {
+		if (!Array.isArray(childLinks)) {
+			fail(`${what}: field "childLinks" must be an array when present`);
+		}
+		out.childLinks = childLinks.map(validateChildLinkRefV1);
+	}
+	const childUnlinks = obj["childUnlinks"];
+	if (childUnlinks !== undefined) {
+		if (!Array.isArray(childUnlinks)) {
+			fail(`${what}: field "childUnlinks" must be an array when present`);
+		}
+		out.childUnlinks = childUnlinks.map(validateChildLinkRefV1);
+	}
 	return out;
 }
 
-const SIGN_KINDS: readonly SignKind[] = ["membership", "promotion", "demotion", "rotation"];
+const SIGN_KINDS: readonly SignKind[] = ["membership", "promotion", "demotion", "rotation", "childlink"];
 
 export function validateSignRequestV1(value: unknown): SignRequestV1 {
 	const what = "SignRequestV1";
@@ -410,7 +442,7 @@ export function validateSignRequestV1(value: unknown): SignRequestV1 {
 	return {
 		v: 1,
 		kind: reqEnum(obj, "kind", SIGN_KINDS, what),
-		coord: b64urlField(reqString(obj, "coord", what), "coord", what),
+		coord: b64urlFixedLen(reqString(obj, "coord", what), "coord", COORD_BYTES, what),
 		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
 		payload: b64urlField(reqString(obj, "payload", what), "payload", what),
 	};
@@ -440,7 +472,7 @@ export function validateMembershipCertV1(value: unknown): MembershipCertV1 {
 	requireV1(obj, what);
 	const out: MembershipCertV1 = {
 		v: 1,
-		cohortCoord: b64urlField(reqString(obj, "cohortCoord", what), "cohortCoord", what),
+		cohortCoord: b64urlFixedLen(reqString(obj, "cohortCoord", what), "cohortCoord", COORD_BYTES, what),
 		cohortEpoch: b64urlField(reqString(obj, "cohortEpoch", what), "cohortEpoch", what),
 		members: reqStringArray(obj, "members", what),
 		stabilizedAt: reqFiniteNumber(obj, "stabilizedAt", what),
@@ -472,6 +504,8 @@ function validateRotationAttestation(obj: Record<string, unknown>, out: Membersh
 	if (presentCount !== 3) {
 		fail(`${what}: rotation attestation requires all of prevEpoch, rotationSig, rotationSigners — or none`);
 	}
+	// prevEpoch is a prior cohortEpoch, so it inherits cohortEpoch's leniency (see the b64urlField note
+	// and debt-cohort-topic-pin-cohort-epoch).
 	out.prevEpoch = b64urlField(prevEpoch!, "prevEpoch", what);
 	out.rotationSig = b64urlField(rotationSig!, "rotationSig", what);
 	out.rotationSigners = rotationSigners!;