@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/tests/federation/audit.test.ts

@@ -0,0 +1,164 @@
+/**
+ * federation/audit.test.ts — F-038 AuditService tests.
+ *
+ * Covers:
+ *   - record() appends NDJSON lines to the file.
+ *   - size() reports on-disk bytes.
+ *   - tail() returns parsed entries from the tail.
+ *   - rotate() moves the file to .log.1.
+ *   - reset() wipes the log file.
+ *   - Constructor throws on missing nodeId.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuditService, DEFAULT_AUDIT_PATH } from "../../src/federation/audit.js";
+
+describe("federation/audit — AuditService", () => {
+  let dir: string;
+  let path: string;
+  let audit: AuditService;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "bizar-audit-"));
+    path = join(dir, "federation-audit.log");
+    audit = new AuditService({ nodeId: "test-node", path });
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("record() appends an NDJSON line", () => {
+    audit.record({
+      ts: new Date().toISOString(),
+      envelopeId: "env-1",
+      sourceNodeId: "node-A",
+      targetNodeId: "node-B",
+      messageType: "heartbeat",
+      nonce: "n1",
+      allowed: true,
+      reason: "ok",
+      layer: "sent",
+    });
+    expect(existsSync(path)).toBe(true);
+    const lines = readFileSync(path, "utf-8").split("\n").filter((l) => l.length > 0);
+    expect(lines.length).toBe(1);
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.envelopeId).toBe("env-1");
+    expect(parsed.nodeId).toBe("test-node");
+  });
+
+  test("size() reports on-disk bytes", () => {
+    expect(audit.size()).toBe(0);
+    audit.record({
+      ts: new Date().toISOString(),
+      envelopeId: "env-1",
+      sourceNodeId: "node-A",
+      targetNodeId: "node-B",
+      messageType: "heartbeat",
+      nonce: "n1",
+      allowed: true,
+      reason: "ok",
+      layer: "sent",
+    });
+    expect(audit.size()).toBeGreaterThan(0);
+  });
+
+  test("tail() returns parsed entries from the end of the file", () => {
+    for (let i = 0; i < 5; i++) {
+      audit.record({
+        ts: new Date().toISOString(),
+        envelopeId: `env-${i}`,
+        sourceNodeId: "node-A",
+        targetNodeId: "node-B",
+        messageType: "heartbeat",
+        nonce: `n${i}`,
+        allowed: true,
+        reason: `entry-${i}`,
+        layer: "sent",
+      });
+    }
+    const tail = audit.tail(3);
+    expect(tail.length).toBe(3);
+    expect(tail[2].envelopeId).toBe("env-4");
+    expect(tail[2].reason).toBe("entry-4");
+  });
+
+  test("tail() returns [] when file missing", () => {
+    const a = new AuditService({ nodeId: "x", path: join(dir, "never-created.log") });
+    expect(a.tail()).toEqual([]);
+  });
+
+  test("rotate() moves the current log to .log.1", () => {
+    audit.record({
+      ts: new Date().toISOString(),
+      envelopeId: "env-1",
+      sourceNodeId: "node-A",
+      targetNodeId: "node-B",
+      messageType: "heartbeat",
+      nonce: "n1",
+      allowed: true,
+      reason: "ok",
+      layer: "sent",
+    });
+    audit.rotate();
+    expect(existsSync(path)).toBe(false);
+    expect(existsSync(`${path}.1`)).toBe(true);
+  });
+
+  test("getPath() returns the configured path", () => {
+    expect(audit.getPath()).toBe(path);
+  });
+
+  test("constructor requires nodeId", () => {
+    expect(() => new AuditService({ nodeId: "" as unknown as string })).toThrow(/nodeId/);
+  });
+
+  test("reset() removes the file (rename to .deleted)", () => {
+    audit.record({
+      ts: new Date().toISOString(),
+      envelopeId: "env-1",
+      sourceNodeId: "node-A",
+      targetNodeId: "node-B",
+      messageType: "heartbeat",
+      nonce: "n1",
+      allowed: true,
+      reason: "ok",
+      layer: "sent",
+    });
+    audit.reset();
+    // After reset, the file was renamed to .deleted (or removed on race).
+    expect(existsSync(path)).toBe(false);
+  });
+
+  test("DEFAULT_AUDIT_PATH is the harness-local path", () => {
+    expect(DEFAULT_AUDIT_PATH).toBe(".harness/federation-audit.log");
+  });
+
+  test("rotation triggered when appending would exceed threshold", () => {
+    // Pre-fill the file to just below the threshold.
+    const huge = "x".repeat(10 * 1024 * 1024 - 200);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, huge, "utf-8");
+    expect(statSync(path).size).toBeGreaterThan(10 * 1024 * 1024 - 1024);
+    audit.record({
+      ts: new Date().toISOString(),
+      envelopeId: "env-1",
+      sourceNodeId: "node-A",
+      targetNodeId: "node-B",
+      messageType: "heartbeat",
+      nonce: "n1",
+      allowed: true,
+      reason: "ok",
+      layer: "sent",
+    });
+    // After the write, the previous file should have been rotated to .log.1
+    // and the new entry written to the fresh .log.
+    expect(existsSync(`${path}.1`)).toBe(true);
+    const newSize = statSync(path).size;
+    expect(newSize).toBeLessThan(1024);
+  });
+});

package/packages/sdk/tests/federation/budget.test.ts

@@ -0,0 +1,189 @@
+/**
+ * federation/budget.test.ts — F-038 FederationBudget tests.
+ *
+ * Covers:
+ *   - reserve/commit/release state machine.
+ *   - setLimits overrides per-peer limits.
+ *   - getOrCreate lazily creates peer records.
+ *   - validateBudgetInput rejects invalid inputs.
+ *   - Persistence: saveToDisk + loadFromDisk round-trip.
+ *   - outstanding() tracks un-released reservations.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_BUDGET_PATH,
+  FederationBudget,
+  MAX_TOKENS_CEILING,
+  MAX_USD_CEILING,
+  validateBudgetInput,
+} from "../../src/federation/budget.js";
+
+describe("federation/budget — validateBudgetInput", () => {
+  test("accepts null → defaults", () => {
+    const r = validateBudgetInput(null);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.maxHops).toBe(8);
+      expect(r.maxTokens).toBe(MAX_TOKENS_CEILING);
+      expect(r.maxUsd).toBe(MAX_USD_CEILING);
+    }
+  });
+
+  test("accepts a fully-specified budget", () => {
+    const r = validateBudgetInput({ maxTokens: 1000, maxUsd: 0.5, maxHops: 4 });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.maxTokens).toBe(1000);
+      expect(r.maxUsd).toBe(0.5);
+      expect(r.maxHops).toBe(4);
+    }
+  });
+
+  test("rejects non-object inputs", () => {
+    expect(validateBudgetInput(42).ok).toBe(false);
+    expect(validateBudgetInput("foo").ok).toBe(false);
+    expect(validateBudgetInput([]).ok).toBe(false);
+  });
+
+  test("rejects maxHops out of range", () => {
+    expect(validateBudgetInput({ maxHops: 100 }).ok).toBe(false);
+    expect(validateBudgetInput({ maxHops: -1 }).ok).toBe(false);
+  });
+
+  test("rejects maxUsd out of range", () => {
+    expect(validateBudgetInput({ maxUsd: -1 }).ok).toBe(false);
+    expect(validateBudgetInput({ maxUsd: MAX_USD_CEILING + 1 }).ok).toBe(false);
+  });
+
+  test("rejects maxTokens out of range", () => {
+    expect(validateBudgetInput({ maxTokens: -1 }).ok).toBe(false);
+    expect(validateBudgetInput({ maxTokens: MAX_TOKENS_CEILING + 1 }).ok).toBe(false);
+  });
+});
+
+describe("federation/budget — FederationBudget lifecycle", () => {
+  let dir: string;
+  let path: string;
+  let budget: FederationBudget;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "bizar-budget-"));
+    path = join(dir, "federation-budget.json");
+    budget = new FederationBudget({
+      path,
+      defaultMaxTokens: 10_000,
+      defaultMaxUsd: 5,
+      defaultMaxHops: 8,
+    });
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("getOrCreate lazily creates a peer", () => {
+    const peer = budget.getOrCreate("node-A");
+    expect(peer.nodeId).toBe("node-A");
+    expect(peer.maxTokens).toBe(10_000);
+    expect(peer.maxUsd).toBe(5);
+    expect(peer.spentTokens).toBe(0);
+  });
+
+  test("reserve + commit round-trip debits spent then refunds the diff", () => {
+    const r = budget.reserve("node-A", 100, 0.5);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    let peer = budget.getOrCreate("node-A");
+    expect(peer.spentTokens).toBe(100);
+    expect(peer.spentUsd).toBe(0.5);
+    // Commit reports actual was lower than reserved.
+    const ok = budget.commit(r.reservationId, { tokens: 60, usd: 0.2 });
+    expect(ok).toBe(true);
+    peer = budget.getOrCreate("node-A");
+    expect(peer.spentTokens).toBe(60);
+    expect(peer.spentUsd).toBe(0.2);
+  });
+
+  test("reserve + release round-trip refunds full reservation", () => {
+    const r = budget.reserve("node-A", 100, 0.5);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    budget.release(r.reservationId);
+    const peer = budget.getOrCreate("node-A");
+    expect(peer.spentTokens).toBe(0);
+    expect(peer.spentUsd).toBe(0);
+  });
+
+  test("reserve over budget denies", () => {
+    budget.setLimits("node-A", { maxTokens: 50, maxUsd: 1 });
+    const r = budget.reserve("node-A", 100, 0.5);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("peer_over_budget");
+  });
+
+  test("reserve with invalid amount denies", () => {
+    const r = budget.reserve("node-A", Number.NaN, 0);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("invalid_amount");
+
+    const r2 = budget.reserve("node-A", -1, 0);
+    expect(r2.ok).toBe(false);
+    if (!r2.ok) expect(r2.reason).toBe("invalid_amount");
+  });
+
+  test("outstanding() tracks un-released reservations", () => {
+    const r = budget.reserve("node-A", 10, 0.1);
+    expect(budget.outstanding().length).toBe(1);
+    if (r.ok) budget.commit(r.reservationId);
+    expect(budget.outstanding().length).toBe(0);
+  });
+
+  test("commit unknown reservation returns false", () => {
+    expect(budget.commit("not-a-real-id")).toBe(false);
+    expect(budget.release("not-a-real-id")).toBe(false);
+  });
+
+  test("saveToDisk + loadFromDisk round-trip", () => {
+    budget.setLimits("node-A", { maxTokens: 999, maxUsd: 0.99, maxHops: 4 });
+    expect(existsSync(path)).toBe(true);
+    const fresh = new FederationBudget({ path });
+    const peer = fresh.getOrCreate("node-A");
+    expect(peer.maxTokens).toBe(999);
+    expect(peer.maxUsd).toBe(0.99);
+    expect(peer.maxHops).toBe(4);
+  });
+
+  test("snapshot returns every per-peer budget", () => {
+    budget.getOrCreate("node-A");
+    budget.getOrCreate("node-B");
+    const snap = budget.snapshot();
+    expect(snap.length).toBe(2);
+    expect(new Set(snap.map((p) => p.nodeId))).toEqual(new Set(["node-A", "node-B"]));
+  });
+
+  test("toJSON returns the documented shape", () => {
+    budget.setLimits("node-A", { maxTokens: 100, maxUsd: 0.5, maxHops: 2 });
+    const json = budget.toJSON();
+    expect(json.version).toBe(1);
+    expect(json.perPeer.length).toBe(1);
+    expect(json.perPeer[0].nodeId).toBe("node-A");
+    expect(typeof json.updatedAt).toBe("string");
+  });
+
+  test("DEFAULT_BUDGET_PATH is the harness-local path", () => {
+    expect(DEFAULT_BUDGET_PATH).toBe(".harness/federation-budget.json");
+  });
+
+  test("loadFromDisk is tolerant of malformed JSON", () => {
+    // Write garbage, then construct a new instance — it should
+    // not throw.
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, "not json", "utf-8");
+    const fresh = new FederationBudget({ path });
+    expect(fresh.getOrCreate("node-A").maxTokens).toBe(MAX_TOKENS_CEILING);
+  });
+});

package/packages/sdk/tests/federation/envelope.test.ts

@@ -0,0 +1,120 @@
+/**
+ * federation/envelope.test.ts — F-038 envelope type tests.
+ *
+ * Covers:
+ *   - The 16 FederationMessageType kinds round-trip through
+ *     isFederationMessageType (positive + negative).
+ *   - canonicalSignablePayload is deterministic + field-order stable.
+ *   - envelopeAgeMs clamps correctly for fresh + old + future.
+ *   - emptyScanResult returns the documented zero shape.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  FEDERATION_MESSAGE_TYPES,
+  TRUST_AFFECTING_MESSAGE_TYPES,
+  canonicalSignablePayload,
+  emptyScanResult,
+  envelopeAgeMs,
+  isFederationMessageType,
+  type FederationEnvelope,
+} from "../../src/federation/envelope.js";
+
+describe("federation/envelope — message kinds", () => {
+  test("FEDERATION_MESSAGE_TYPES has 17 entries (16 ruflo kinds + claim-event)", () => {
+    expect(FEDERATION_MESSAGE_TYPES.length).toBe(17);
+  });
+
+  test("each declared kind passes isFederationMessageType", () => {
+    for (const k of FEDERATION_MESSAGE_TYPES) {
+      expect(isFederationMessageType(k)).toBe(true);
+    }
+  });
+
+  test("isFederationMessageType rejects unknown / mistyped values", () => {
+    expect(isFederationMessageType("not-a-kind")).toBe(false);
+    expect(isFederationMessageType(null)).toBe(false);
+    expect(isFederationMessageType(undefined)).toBe(false);
+    expect(isFederationMessageType(42)).toBe(false);
+    expect(isFederationMessageType({})).toBe(false);
+  });
+
+  test("TRUST_AFFECTING_MESSAGE_TYPES contains the 4 risk kinds", () => {
+    expect(["trust-change", "topology-change", "agent-spawn", "agent-handoff"])
+      .toEqual(expect.arrayContaining([...TRUST_AFFECTING_MESSAGE_TYPES]));
+  });
+});
+
+describe("federation/envelope — canonical payload", () => {
+  const sample: FederationEnvelope = {
+    envelopeId: "env-1",
+    sourceNodeId: "node-A",
+    targetNodeId: "node-B",
+    sessionId: "sess-1",
+    messageType: "heartbeat",
+    payload: { ok: true },
+    timestamp: "2026-07-12T00:00:00.000Z",
+    nonce: "nonce-1",
+    hmacSignature: "sig-1",
+    piiScanResult: emptyScanResult(),
+    hopCount: 0,
+  };
+
+  test("canonicalSignablePayload is deterministic", () => {
+    const a = canonicalSignablePayload(sample);
+    const b = canonicalSignablePayload(sample);
+    expect(a).toBe(b);
+  });
+
+  test("canonicalSignablePayload excludes hmacSignature + piiScanResult", () => {
+    const json = canonicalSignablePayload(sample);
+    expect(json).not.toContain("hmacSignature");
+    expect(json).not.toContain("piiScanResult");
+  });
+
+  test("canonicalSignablePayload includes hopCount", () => {
+    const json = canonicalSignablePayload(sample);
+    expect(JSON.parse(json).hopCount).toBe(0);
+  });
+
+  test("mutating the source envelope changes the payload", () => {
+    const before = canonicalSignablePayload(sample);
+    const tampered: FederationEnvelope = { ...sample, payload: { ok: false } };
+    const after = canonicalSignablePayload(tampered);
+    expect(before).not.toBe(after);
+  });
+});
+
+describe("federation/envelope — age", () => {
+  test("envelopeAgeMs is 0 for a now() envelope", () => {
+    const env: FederationEnvelope = {
+      envelopeId: "e", sourceNodeId: "a", targetNodeId: "b",
+      sessionId: "s", messageType: "heartbeat",
+      payload: null, timestamp: new Date().toISOString(),
+      nonce: "n", hmacSignature: "h", piiScanResult: emptyScanResult(),
+    };
+    expect(envelopeAgeMs(env)).toBeGreaterThanOrEqual(0);
+    expect(envelopeAgeMs(env)).toBeLessThan(100);
+  });
+
+  test("envelopeAgeMs is large for an old envelope", () => {
+    const old = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+    const env: FederationEnvelope = {
+      envelopeId: "e", sourceNodeId: "a", targetNodeId: "b",
+      sessionId: "s", messageType: "heartbeat",
+      payload: null, timestamp: old,
+      nonce: "n", hmacSignature: "h", piiScanResult: emptyScanResult(),
+    };
+    expect(envelopeAgeMs(env)).toBeGreaterThanOrEqual(10 * 60 * 1000);
+  });
+
+  test("envelopeAgeMs clamps invalid timestamps to Infinity", () => {
+    const env: FederationEnvelope = {
+      envelopeId: "e", sourceNodeId: "a", targetNodeId: "b",
+      sessionId: "s", messageType: "heartbeat",
+      payload: null, timestamp: "not-a-date",
+      nonce: "n", hmacSignature: "h", piiScanResult: emptyScanResult(),
+    };
+    expect(envelopeAgeMs(env)).toBe(Number.POSITIVE_INFINITY);
+  });
+});

package/packages/sdk/tests/federation/hmac.test.ts

@@ -0,0 +1,194 @@
+/**
+ * federation/hmac.test.ts — F-038 HMAC + nonce tests.
+ *
+ * Covers:
+ *   - signEnvelope produces a stable 64-char hex digest.
+ *   - verifySignature accepts a fresh signed envelope.
+ *   - verifySignature rejects a tampered envelope.
+ *   - verifySignature rejects an expired envelope.
+ *   - NonceCache rejects duplicates within the window.
+ *   - NonceCache evicts old entries (size capped).
+ *   - freshNonce returns crypto.randomUUID() — 128-bit random.
+ */
+
+import { describe, test, expect, beforeEach } from "vitest";
+import {
+  DEFAULT_NONCE_WINDOW_MS,
+  freshNonce,
+  NonceCache,
+  signEnvelope,
+  verifySignature,
+} from "../../src/federation/hmac.js";
+import {
+  canonicalSignablePayload,
+  emptyScanResult,
+  type FederationEnvelope,
+} from "../../src/federation/envelope.js";
+
+const SECRET = "test-secret-123";
+
+function makeEnvelope(overrides: Partial<FederationEnvelope> = {}): FederationEnvelope {
+  return {
+    envelopeId: "env-1",
+    sourceNodeId: "node-A",
+    targetNodeId: "node-B",
+    sessionId: "sess-1",
+    messageType: "heartbeat",
+    payload: { ok: true },
+    timestamp: new Date().toISOString(),
+    nonce: freshNonce(),
+    hmacSignature: "",
+    piiScanResult: emptyScanResult(),
+    ...overrides,
+  };
+}
+
+describe("federation/hmac — signEnvelope", () => {
+  test("produces a 64-char hex digest", () => {
+    const e = makeEnvelope();
+    const sig = signEnvelope(e, SECRET);
+    expect(sig).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("deterministic for the same payload", () => {
+    const e = makeEnvelope({ nonce: "n1", timestamp: "2026-07-12T00:00:00.000Z" });
+    const s1 = signEnvelope(e, SECRET);
+    const s2 = signEnvelope(e, SECRET);
+    expect(s1).toBe(s2);
+  });
+
+  test("different secret → different signature", () => {
+    const e = makeEnvelope({ nonce: "n1", timestamp: "2026-07-12T00:00:00.000Z" });
+    const a = signEnvelope(e, "secret-A");
+    const b = signEnvelope(e, "secret-B");
+    expect(a).not.toBe(b);
+  });
+
+  test("rejects empty secret", () => {
+    const e = makeEnvelope();
+    expect(() => signEnvelope(e, "")).toThrow(/non-empty/);
+  });
+});
+
+describe("federation/hmac — verifySignature", () => {
+  let envelope: FederationEnvelope;
+
+  beforeEach(() => {
+    envelope = makeEnvelope();
+    envelope.hmacSignature = signEnvelope(envelope, SECRET);
+  });
+
+  test("accepts a fresh signed envelope with empty seen set", () => {
+    const r = verifySignature(envelope, SECRET, new Set());
+    expect(r.ok).toBe(true);
+  });
+
+  test("rejects tampered payload", () => {
+    const tampered: FederationEnvelope = { ...envelope, payload: { evil: true } };
+    const r = verifySignature(tampered, SECRET, new Set());
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("signature_mismatch");
+  });
+
+  test("rejects wrong secret", () => {
+    const r = verifySignature(envelope, "wrong-secret", new Set());
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("signature_mismatch");
+  });
+
+  test("rejects envelope past freshness window", () => {
+    const old = makeEnvelope({
+      timestamp: new Date(Date.now() - DEFAULT_NONCE_WINDOW_MS - 1000).toISOString(),
+    });
+    old.hmacSignature = signEnvelope(old, SECRET);
+    const r = verifySignature(old, SECRET, new Set());
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("envelope_expired");
+  });
+
+  test("rejects envelope from the far future", () => {
+    const future = makeEnvelope({
+      timestamp: new Date(Date.now() + DEFAULT_NONCE_WINDOW_MS + 60_000).toISOString(),
+    });
+    future.hmacSignature = signEnvelope(future, SECRET);
+    const r = verifySignature(future, SECRET, new Set());
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("envelope_from_future");
+  });
+
+  test("rejects nonce seen in the seen-set (replay)", () => {
+    const seen = new Set([envelope.nonce]);
+    const r = verifySignature(envelope, SECRET, seen);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe("nonce_replay");
+  });
+
+  test("rejects empty secret", () => {
+    const r = verifySignature(envelope, "", new Set());
+    expect(r.ok).toBe(false);
+  });
+
+  test("rejects empty signature", () => {
+    const e = makeEnvelope({ hmacSignature: "" });
+    const r = verifySignature(e, SECRET, new Set());
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("federation/hmac — NonceCache", () => {
+  test("check() returns true for fresh nonce, false for replay", () => {
+    const cache = new NonceCache();
+    expect(cache.check("n1")).toBe(true);
+    expect(cache.check("n1")).toBe(false);
+    expect(cache.check("n2")).toBe(true);
+    expect(cache.size()).toBe(2);
+  });
+
+  test("has() reflects the cache state without side effects", () => {
+    const cache = new NonceCache();
+    cache.check("n1");
+    expect(cache.has("n1")).toBe(true);
+    expect(cache.has("n2")).toBe(false);
+  });
+
+  test("clear() empties the cache", () => {
+    const cache = new NonceCache();
+    cache.check("n1");
+    cache.check("n2");
+    cache.clear();
+    expect(cache.size()).toBe(0);
+    expect(cache.check("n1")).toBe(true); // fresh again
+  });
+
+  test("evicts entries past the window", () => {
+    const cache = new NonceCache(1000); // 1s window
+    const t = Date.now();
+    expect(cache.check("n1", t)).toBe(true);
+    // 2 seconds later — entry should have expired.
+    expect(cache.check("n1", t + 2000)).toBe(true);
+  });
+});
+
+describe("federation/hmac — freshNonce", () => {
+  test("returns a 128-bit random UUID", () => {
+    const a = freshNonce();
+    const b = freshNonce();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  test("produces 1000 unique nonces (probabilistic)", () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 1000; i++) seen.add(freshNonce());
+    expect(seen.size).toBe(1000);
+  });
+
+  test("is used by sign() in the orchestrator", () => {
+    // Sanity — round-trip through canonicalSignablePayload works.
+    const e = makeEnvelope();
+    const sig = signEnvelope(e, SECRET);
+    expect(typeof sig).toBe("string");
+    expect(sig.length).toBe(64);
+    void canonicalSignablePayload;
+  });
+});