@polderlabs/bizar 6.3.0 → 7.0.0

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;
+  });
+});

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

@@ -0,0 +1,176 @@
+/**
+ * federation/orchestrator.test.ts — F-038 orchestrator smoke tests.
+ *
+ * Covers the end-to-end `createFederation()` flow:
+ *   - sign() produces a signed envelope.
+ *   - receive() admits a fresh signed envelope.
+ *   - PII redaction applies on sign() (soc2 mode).
+ *   - status() returns the documented snapshot shape.
+ *   - Two-instance roundtrip with shared HMAC secret.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createFederation,
+  type FederationHandle,
+} from "../../src/federation/index.js";
+
+describe("federation/orchestrator — single-instance flow", () => {
+  let dir: string;
+  let handle: FederationHandle;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "bizar-fed-"));
+    handle = createFederation({
+      nodeId: "node-A",
+      secret: "shared-secret",
+      auditPath: join(dir, "audit.log"),
+      budgetPath: join(dir, "budget.json"),
+    });
+    handle.services.trust.setAllowlisted("node-B", true);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("sign() produces a signed envelope with non-empty signature", () => {
+    const env = handle.sign({
+      targetNodeId: "node-B",
+      sessionId: "s1",
+      messageType: "heartbeat",
+      payload: "ping",
+    });
+    expect(env.hmacSignature).toMatch(/^[0-9a-f]{64}$/);
+    expect(env.nonce).toMatch(/^[0-9a-f-]{36}$/);
+    expect(env.sourceNodeId).toBe("node-A");
+    expect(env.targetNodeId).toBe("node-B");
+  });
+
+  test("receive() admits a fresh signed envelope from an allowlisted peer", () => {
+    const peer = createFederation({
+      nodeId: "node-B",
+      secret: "shared-secret",
+      auditPath: join(dir, "audit-B.log"),
+      budgetPath: join(dir, "budget-B.json"),
+    });
+    const sent = peer.sign({
+      targetNodeId: "node-A",
+      sessionId: "s1",
+      messageType: "heartbeat",
+      payload: "hello",
+    });
+    const r = handle.receive(sent);
+    expect(r.hmacValid).toBe(true);
+    expect(r.trusted).toBe(true);
+    expect(r.policyAllowed).toBe(true);
+    expect(r.rejectionReason).toBeUndefined();
+  });
+
+  test("receive() rejects an envelope from a non-allowlisted peer", () => {
+    const peer = createFederation({
+      nodeId: "node-X",
+      secret: "shared-secret",
+      auditPath: join(dir, "audit-X.log"),
+      budgetPath: join(dir, "budget-X.json"),
+    });
+    const sent = peer.sign({
+      targetNodeId: "node-A",
+      sessionId: "s1",
+      messageType: "heartbeat",
+      payload: "hello",
+    });
+    const r = handle.receive(sent);
+    expect(r.hmacValid).toBe(true);
+    expect(r.trusted).toBe(false);
+    expect(r.rejectionReason).toMatch(/trust/);
+  });
+
+  test("receive() rejects a tampered envelope", () => {
+    const peer = createFederation({
+      nodeId: "node-B",
+      secret: "shared-secret",
+      auditPath: join(dir, "audit-B.log"),
+      budgetPath: join(dir, "budget-B.json"),
+    });
+    const sent = peer.sign({
+      targetNodeId: "node-A",
+      sessionId: "s1",
+      messageType: "heartbeat",
+      payload: "hello",
+    });
+    const tampered = { ...sent, payload: "tampered" };
+    const r = handle.receive(tampered);
+    expect(r.hmacValid).toBe(false);
+    expect(r.rejectionReason).toMatch(/hmac/);
+  });
+
+  test("PII redaction applies on sign() under soc2 mode", () => {
+    const env = handle.sign({
+      targetNodeId: "node-B",
+      sessionId: "s1",
+      messageType: "context-share",
+      payload: "contact alice@example.com",
+    });
+    expect(env.payload).not.toContain("alice@example.com");
+    expect(env.payload).toContain("[REDACTED:email]");
+    expect(env.piiScanResult.scanned).toBe(true);
+    expect(env.piiScanResult.piiFound).toBe(true);
+  });
+
+  test("skipPii disables redaction", () => {
+    const env = handle.sign({
+      targetNodeId: "node-B",
+      sessionId: "s1",
+      messageType: "context-share",
+      payload: "contact alice@example.com",
+      skipPii: true,
+    });
+    expect(env.payload).toBe("contact alice@example.com");
+  });
+
+  test("setPiiMode / getPiiMode round-trip", () => {
+    expect(handle.getPiiMode()).toBe("soc2");
+    handle.setPiiMode("gdpr");
+    expect(handle.getPiiMode()).toBe("gdpr");
+    expect(() => handle.setPiiMode("nope" as never)).toThrow();
+  });
+
+  test("status() returns the documented snapshot shape", () => {
+    const snap = handle.status();
+    expect(snap.nodeId).toBe("node-A");
+    expect(snap.auditPath).toContain("audit.log");
+    expect(snap.budget.path).toContain("budget.json");
+    expect(Array.isArray(snap.budget.perPeer)).toBe(true);
+    expect(typeof snap.nonceCacheSize).toBe("number");
+    expect(typeof snap.auditSizeBytes).toBe("number");
+  });
+
+  test("constructor requires nodeId + secret", () => {
+    expect(() => createFederation({ nodeId: "", secret: "x" } as never)).toThrow(/nodeId/);
+    expect(() => createFederation({ nodeId: "x", secret: "" } as never)).toThrow(/secret/);
+  });
+
+  test("nonce replay is rejected on second delivery", () => {
+    const peer = createFederation({
+      nodeId: "node-B",
+      secret: "shared-secret",
+      auditPath: join(dir, "audit-B.log"),
+      budgetPath: join(dir, "budget-B.json"),
+    });
+    const sent = peer.sign({
+      targetNodeId: "node-A",
+      sessionId: "s1",
+      messageType: "heartbeat",
+      payload: "hello",
+    });
+    const r1 = handle.receive(sent);
+    const r2 = handle.receive(sent);
+    expect(r1.hmacValid).toBe(true);
+    expect(r2.hmacValid).toBe(false);
+    if (r2.rejectionReason) expect(r2.rejectionReason).toMatch(/nonce_replay/);
+  });
+});