@blockcast/fec-worker 0.1.0

package/src/__tests__/fec-worker-pending-queue.test.ts

@@ -0,0 +1,315 @@
+/**
+ * Unit tests for the deferred ALTA verification queue (08-07 Path 3).
+ *
+ * When ALTA's MAC-chain anchor is unresolvable at packet arrival (late joiner
+ * before first signed packet, or packet that references a not-yet-recovered
+ * predecessor), the packet is queued rather than failed. After every
+ * successful verify seeds the verifier's ring buffer, the queue drains and
+ * retries previously-pending entries.
+ *
+ * These tests mirror `fec-worker.ts`'s runDetachedVerify / enqueuePendingVerify
+ * / drainPendingVerify in a test-harness-friendly form. The real module is a
+ * Worker entry file (self, onmessage) and can't be imported; the inline
+ * simulation matches the pattern in `fec-worker-alta.test.ts`.
+ */
+
+import { describe, it, expect } from "vitest";
+
+// ── Mock verifier ─────────────────────────────────────────────────────
+
+type Outcome = "valid" | "failed" | "pending";
+
+/** Controllable verifier whose result depends on whether a seq is "in ring buffer". */
+class MockVerifier {
+	ringBuffer = new Set<number>(); // seqs with raw bytes available
+	tamperSeqs = new Set<number>(); // seqs that should hard-fail (tamper)
+
+	verifyDetached(
+		auth: Uint8Array,
+		_payload: Uint8Array,
+	): { valid: boolean; error?: string } {
+		const seq = seqFromAuth(auth);
+		if (this.tamperSeqs.has(seq)) {
+			return { valid: false, error: "MAC mismatch on 1 slot(s)" };
+		}
+		// Signer references seq - 2 (offset=1) as primary MAC ref. If that's in
+		// the ring buffer, verify passes. Else pending.
+		const macRef = seq - 2;
+		if (macRef <= 0 || this.ringBuffer.has(macRef)) {
+			this.ringBuffer.add(seq);
+			return { valid: true };
+		}
+		return {
+			valid: false,
+			error: "No trust anchor (signature absent, no MAC refs in buffer)",
+		};
+	}
+}
+
+function seqFromAuth(auth: Uint8Array): number {
+	return (
+		((auth[0]! << 24) | (auth[1]! << 16) | (auth[2]! << 8) | auth[3]!) >>> 0
+	);
+}
+
+function mkAuth(seq: number): Uint8Array {
+	const auth = new Uint8Array(40);
+	auth[0] = (seq >>> 24) & 0xff;
+	auth[1] = (seq >>> 16) & 0xff;
+	auth[2] = (seq >>> 8) & 0xff;
+	auth[3] = seq & 0xff;
+	return auth;
+}
+
+// ── Inline simulation of fec-worker queue logic ──────────────────────
+
+interface PendingVerify {
+	seq: number;
+	auth: Uint8Array;
+	payload: Uint8Array;
+	arrivalTs: number;
+}
+
+interface Harness {
+	verifier: MockVerifier;
+	queue: Map<number, PendingVerify>;
+	cap: number;
+	ttlMs: number;
+	now: number;
+	altaVerified: number;
+	altaFailed: number;
+	altaPending: number;
+}
+
+function runVerify(h: Harness, auth: Uint8Array, payload: Uint8Array): Outcome {
+	const r = h.verifier.verifyDetached(auth, payload);
+	if (r.valid) return "valid";
+	const err = r.error ?? "";
+	if (err.startsWith("No trust anchor")) return "pending";
+	return "failed";
+}
+
+function enqueue(h: Harness, auth: Uint8Array, payload: Uint8Array): void {
+	const seq = seqFromAuth(auth);
+	if (h.queue.has(seq)) return;
+
+	// Mirror fec-worker.ts: when the queue is at cap, sweep TTL'd entries
+	// first, then reject the NEW entry if still full. Never evict legitimate
+	// pending entries that a flood of "No trust anchor" packets could
+	// otherwise displace.
+	if (h.queue.size >= h.cap) {
+		for (const [staleSeq, entry] of h.queue) {
+			if (h.now - entry.arrivalTs > h.ttlMs) {
+				h.queue.delete(staleSeq);
+				h.altaPending++;
+			}
+		}
+		if (h.queue.size >= h.cap) {
+			h.altaPending++; // cap-rejection counts the rejected incoming
+			return;
+		}
+	}
+
+	h.queue.set(seq, { seq, auth, payload, arrivalTs: h.now });
+}
+
+function drain(h: Harness): void {
+	const keys = Array.from(h.queue.keys());
+	for (const seq of keys) {
+		const entry = h.queue.get(seq);
+		if (!entry) continue;
+		if (h.now - entry.arrivalTs > h.ttlMs) {
+			h.queue.delete(seq);
+			h.altaPending++;
+			continue;
+		}
+		const outcome = runVerify(h, entry.auth, entry.payload);
+		if (outcome === "valid") {
+			h.queue.delete(seq);
+			h.altaVerified++;
+		} else if (outcome === "failed") {
+			h.queue.delete(seq);
+			h.altaFailed++;
+		}
+	}
+}
+
+function processDirectSource(
+	h: Harness,
+	auth: Uint8Array,
+	payload: Uint8Array,
+): void {
+	const outcome = runVerify(h, auth, payload);
+	if (outcome === "valid") {
+		h.altaVerified++;
+		drain(h);
+	} else if (outcome === "failed") {
+		h.altaFailed++;
+	} else {
+		enqueue(h, auth, payload);
+	}
+}
+
+function makeHarness(opts?: { cap?: number; ttlMs?: number }): Harness {
+	return {
+		verifier: new MockVerifier(),
+		queue: new Map(),
+		cap: opts?.cap ?? 8,
+		ttlMs: opts?.ttlMs ?? 10_000,
+		now: 0,
+		altaVerified: 0,
+		altaFailed: 0,
+		altaPending: 0,
+	};
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe("deferred ALTA verification queue", () => {
+	it("valid direct verify increments altaVerified, queue stays empty", () => {
+		const h = makeHarness();
+		// Seed ring buffer with seq=1 so seq=3's MAC ref (seq=1) resolves.
+		h.verifier.ringBuffer.add(1);
+		processDirectSource(h, mkAuth(3), new Uint8Array(1400));
+		expect(h.altaVerified).toBe(1);
+		expect(h.altaFailed).toBe(0);
+		expect(h.queue.size).toBe(0);
+	});
+
+	it("pending direct verify enqueues, counters untouched", () => {
+		const h = makeHarness();
+		// No seed — seq=10's MAC ref (seq=8) not in ring buffer.
+		processDirectSource(h, mkAuth(10), new Uint8Array(1400));
+		expect(h.queue.size).toBe(1);
+		expect(h.queue.has(10)).toBe(true);
+		expect(h.altaVerified).toBe(0);
+		expect(h.altaFailed).toBe(0);
+		expect(h.altaPending).toBe(0);
+	});
+
+	it("tamper (MAC mismatch) fails immediately — not queued", () => {
+		const h = makeHarness();
+		h.verifier.ringBuffer.add(8);
+		h.verifier.tamperSeqs.add(10);
+		processDirectSource(h, mkAuth(10), new Uint8Array(1400));
+		expect(h.altaFailed).toBe(1);
+		expect(h.queue.size).toBe(0);
+	});
+
+	it("seed arrives → drain retries queued entry → altaVerified", () => {
+		const h = makeHarness();
+		// First: seq=10 enqueued (no anchor).
+		processDirectSource(h, mkAuth(10), new Uint8Array(1400));
+		expect(h.queue.size).toBe(1);
+		// Now seed: seq=8's ref (seq=6) isn't in buffer, so seq=8 itself would
+		// also be pending. Bootstrap via seq=2 (early-warmup path — no ref).
+		processDirectSource(h, mkAuth(2), new Uint8Array(1400));
+		expect(h.altaVerified).toBe(1); // seq=2 verified
+		// seq=2 is now in buffer. seq=8 would need seq=6 (not buffered),
+		// seq=10 needs seq=8 (not buffered yet either). Queue still has seq=10.
+		// Verify needs seq=4, which needs seq=2. Let's feed seq=4 and seq=8.
+		processDirectSource(h, mkAuth(4), new Uint8Array(1400));
+		processDirectSource(h, mkAuth(6), new Uint8Array(1400));
+		processDirectSource(h, mkAuth(8), new Uint8Array(1400));
+		// Now seq=8 is in the ring buffer. Next drain should resolve seq=10.
+		// Re-feed seq=12 to trigger drain via its successful verify.
+		processDirectSource(h, mkAuth(12), new Uint8Array(1400));
+		// After that cascade, queue should be empty and seq=10 counted verified.
+		expect(h.queue.size).toBe(0);
+		expect(h.altaVerified).toBeGreaterThanOrEqual(5);
+	});
+
+	it("TTL expiry → evicts as altaPending on drain", () => {
+		const h = makeHarness({ ttlMs: 1000 });
+		processDirectSource(h, mkAuth(100), new Uint8Array(1400));
+		expect(h.queue.size).toBe(1);
+		// Advance time past TTL, then trigger drain via a valid seed.
+		h.now = 2000;
+		processDirectSource(h, mkAuth(2), new Uint8Array(1400)); // bootstraps
+		// drain ran; seq=100 expired, counted pending.
+		expect(h.queue.size).toBe(0);
+		expect(h.altaPending).toBe(1);
+		expect(h.altaFailed).toBe(0);
+	});
+
+	it("cap rejection → NEW entry dropped as altaPending (08-08 flood resistance)", () => {
+		const h = makeHarness({ cap: 3 });
+		// Enqueue 4 pending entries at the same tick (no TTL sweep eligible).
+		// Pre-08-08: the 4th would evict the 1st. Post-fix: the 1st is
+		// retained and the 4th is rejected.
+		for (const seq of [100, 101, 102, 103]) {
+			processDirectSource(h, mkAuth(seq), new Uint8Array(1400));
+		}
+		expect(h.queue.size).toBe(3);
+		expect(h.queue.has(100)).toBe(true); // oldest retained
+		expect(h.queue.has(101)).toBe(true);
+		expect(h.queue.has(102)).toBe(true);
+		expect(h.queue.has(103)).toBe(false); // newest rejected
+		expect(h.altaPending).toBe(1); // rejected counts as pending
+	});
+
+	it("attacker flood does NOT evict legitimate pending entries", () => {
+		// Scenario: a legit packet at seq=500 is queued awaiting its anchor.
+		// An attacker then emits a burst of forged "No trust anchor" packets
+		// (e.g. seq 600..650). Pre-08-08 those would evict seq=500. Post-fix
+		// seq=500 stays put and the attacker's packets get rejected.
+		const h = makeHarness({ cap: 10 });
+
+		// 1. Legit pending entry lands first.
+		processDirectSource(h, mkAuth(500), new Uint8Array(1400));
+		expect(h.queue.has(500)).toBe(true);
+
+		// 2. Attacker flood: 100 packets, every one returning "pending"
+		//    (no anchor for any of their seqs). Only the first 9 should
+		//    land (fill queue to cap=10 with the 1 legit entry). The rest
+		//    must be rejected without touching seq=500.
+		for (let seq = 600; seq < 700; seq++) {
+			processDirectSource(h, mkAuth(seq), new Uint8Array(1400));
+		}
+
+		// Legit entry survived.
+		expect(h.queue.has(500)).toBe(true);
+		// Queue filled to cap.
+		expect(h.queue.size).toBe(10);
+		// 91 attacker packets were rejected (100 attempted − 9 admitted).
+		expect(h.altaPending).toBe(91);
+		// No tamper-failure spurious counting.
+		expect(h.altaFailed).toBe(0);
+	});
+
+	it("stale entries are swept on cap pressure, making room for new arrivals", () => {
+		const h = makeHarness({ cap: 3, ttlMs: 1000 });
+		// Fill the queue at t=0.
+		for (const seq of [100, 101, 102]) {
+			processDirectSource(h, mkAuth(seq), new Uint8Array(1400));
+		}
+		expect(h.queue.size).toBe(3);
+
+		// Advance past TTL, then attempt a new enqueue.
+		h.now = 2000;
+		processDirectSource(h, mkAuth(200), new Uint8Array(1400));
+		// The three stale entries were swept by the pre-admission sweep, the
+		// new entry (seq=200) got in.
+		expect(h.queue.size).toBe(1);
+		expect(h.queue.has(200)).toBe(true);
+		expect(h.queue.has(100)).toBe(false);
+		expect(h.altaPending).toBe(3); // three TTL-swept
+	});
+
+	it("dedup: re-feeding same seq doesn't duplicate queue entry", () => {
+		const h = makeHarness();
+		processDirectSource(h, mkAuth(50), new Uint8Array(1400));
+		processDirectSource(h, mkAuth(50), new Uint8Array(1400));
+		expect(h.queue.size).toBe(1);
+	});
+
+	it("drain keeps entries that are still pending (ref still not in buffer)", () => {
+		const h = makeHarness();
+		// Enqueue seq=50 (needs seq=48, not in buffer).
+		processDirectSource(h, mkAuth(50), new Uint8Array(1400));
+		// Valid seed seq=2 triggers drain but doesn't resolve seq=50.
+		processDirectSource(h, mkAuth(2), new Uint8Array(1400));
+		expect(h.queue.size).toBe(1); // seq=50 still pending
+		expect(h.altaPending).toBe(0);
+	});
+});