@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/src/federation/hmac.ts

@@ -0,0 +1,160 @@
+/**
+ * federation/hmac.ts — HMAC-SHA-256 signing + verification for
+ * federation envelopes.
+ *
+ * F-038 — security-critical. Pinned by AGENTS.md hard constraint:
+ *   "MUST use crypto.timingSafeEqual for HMAC comparison
+ *    (timing-attack resistant)."
+ *   "MUST use crypto.randomUUID() for nonces (128-bit random)."
+ *
+ * Nonce strategy:
+ *   - Sender generates a fresh `crypto.randomUUID()` per envelope.
+ *   - Receiver tracks every nonce it has seen in a TTL-bounded Set.
+ *   - An envelope whose nonce appears twice is a replay → reject.
+ *   - An envelope whose timestamp is older than `nonceWindowMs`
+ *     (default 5 min) is also a replay → reject.
+ *
+ * No native deps. Pure Node `node:crypto`.
+ */
+
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  canonicalSignablePayload,
+  type FederationEnvelope,
+} from "./envelope.js";
+
+/** Default freshness window for HMAC verification (5 minutes). */
+export const DEFAULT_NONCE_WINDOW_MS = 5 * 60 * 1000;
+
+/** Cap on the receiver's seen-nonce set so it can't grow unbounded. */
+const SEEN_NONCE_CAP = 10_000;
+
+/** Compute a deterministic 64-char hex HMAC-SHA-256 over the envelope's
+ *  canonical signable payload. */
+export function signEnvelope<T>(
+  envelope: FederationEnvelope<T>,
+  secret: string,
+): string {
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new Error("signEnvelope: secret must be a non-empty string");
+  }
+  const payload = canonicalSignablePayload(envelope);
+  return createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+export interface VerifyOptions {
+  /** Freshness window. Envelopes older than this are rejected.
+   *  Defaults to 5 minutes. */
+  readonly nonceWindowMs?: number;
+  /** Optional clock-skew offset (ms) to *add* to the freshness
+   *  window (e.g. for poorly-synced peers). Defaults to 0. */
+  readonly clockSkewMs?: number;
+  /** Optional explicit timestamp for deterministic tests. */
+  readonly now?: number;
+}
+
+export type VerifyOutcome =
+  | { ok: true }
+  | {
+      ok: false;
+      reason:
+        | "signature_mismatch"
+        | "nonce_replay"
+        | "envelope_expired"
+        | "envelope_from_future"
+        | "invalid_signature_format";
+    };
+
+/** Pure verifier — no shared state. The caller owns the seen-nonce
+ *  cache (see `NonceCache` below) and passes it in via `seen`. */
+export function verifySignature<T>(
+  envelope: FederationEnvelope<T>,
+  secret: string,
+  seen: ReadonlySet<string>,
+  opts: VerifyOptions = {},
+): VerifyOutcome {
+  if (typeof secret !== "string" || secret.length === 0) {
+    return { ok: false, reason: "invalid_signature_format" };
+  }
+  if (typeof envelope.hmacSignature !== "string" || envelope.hmacSignature.length === 0) {
+    return { ok: false, reason: "invalid_signature_format" };
+  }
+
+  // Freshness — reject before we touch the HMAC code path so we
+  // don't burn cycles on ancient replays.
+  const now = opts.now ?? Date.now();
+  const ts = new Date(envelope.timestamp).getTime();
+  if (!Number.isFinite(ts)) return { ok: false, reason: "envelope_expired" };
+  const ageMs = now - ts;
+  const window = (opts.nonceWindowMs ?? DEFAULT_NONCE_WINDOW_MS) + (opts.clockSkewMs ?? 0);
+  if (ageMs > window) return { ok: false, reason: "envelope_expired" };
+  if (ageMs < -window) return { ok: false, reason: "envelope_from_future" };
+
+  // Nonce replay — checked AFTER freshness so a delayed-but-unique
+  // envelope doesn't get falsely fingerprinted as a replay.
+  if (seen.has(envelope.nonce)) return { ok: false, reason: "nonce_replay" };
+
+  // Constant-time signature compare. Both buffers must be the same
+  // length for timingSafeEqual; if lengths differ, signature_mismatch.
+  const expected = signEnvelope(envelope, secret);
+  const a = Buffer.from(expected, "hex");
+  let b: Buffer;
+  try {
+    b = Buffer.from(envelope.hmacSignature, "hex");
+  } catch {
+    return { ok: false, reason: "invalid_signature_format" };
+  }
+  if (a.length !== b.length) return { ok: false, reason: "signature_mismatch" };
+  if (!timingSafeEqual(a, b)) return { ok: false, reason: "signature_mismatch" };
+
+  return { ok: true };
+}
+
+/** Mutable nonce cache with TTL eviction + hard cap. The receiver
+ *  keeps one per remote node (or a single global one for the skeleton). */
+export class NonceCache {
+  private readonly seen = new Map<string, number>(); // nonce → expiryMs
+  private readonly windowMs: number;
+
+  constructor(windowMs: number = DEFAULT_NONCE_WINDOW_MS) {
+    this.windowMs = windowMs;
+  }
+
+  /** True if the nonce is fresh (not seen in windowMs). Adds it
+   *  to the cache as a side effect. */
+  check(nonce: string, now: number = Date.now()): boolean {
+    this.evict(now);
+    if (this.seen.has(nonce)) return false;
+    if (this.seen.size >= SEEN_NONCE_CAP) {
+      // Hard cap — evict the oldest entry to make room.
+      const oldest = this.seen.keys().next().value;
+      if (oldest !== undefined) this.seen.delete(oldest);
+    }
+    this.seen.set(nonce, now + this.windowMs);
+    return true;
+  }
+
+  /** True if the nonce is in the cache (read-only). */
+  has(nonce: string): boolean {
+    return this.seen.has(nonce);
+  }
+
+  size(): number {
+    return this.seen.size;
+  }
+
+  clear(): void {
+    this.seen.clear();
+  }
+
+  private evict(now: number): void {
+    for (const [nonce, expiry] of this.seen) {
+      if (expiry <= now) this.seen.delete(nonce);
+    }
+  }
+}
+
+/** Helper — produce a fresh nonce via `crypto.randomUUID()`. */
+export function freshNonce(): string {
+  return randomUUID();
+}

package/packages/sdk/src/federation/index.ts

@@ -0,0 +1,443 @@
+/**
+ * federation/index.ts — top-level orchestrator + public exports.
+ *
+ * F-038 — composes the eight federation primitives into a single
+ * `createFederation(opts)` factory. The orchestrator wires:
+ *
+ *   sign    — produce a signed FederationEnvelope (with fresh nonce +
+ *             PII redaction + audit log entry).
+ *   verify  — verify an inbound envelope (HMAC + nonce window +
+ *             trust + policy + audit log entry).
+ *   send    — high-level helper: sign + persist outgoing audit.
+ *   receive — high-level helper: verify + accept-or-reject + persist
+ *             inbound audit.
+ *   status  — snapshot for the `federation_status` MCP tool.
+ *
+ * No native deps. Pure TS over Node `crypto` + `fs`.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import {
+  canonicalSignablePayload,
+  emptyScanResult,
+  type EnvelopeBudget,
+  type FederationEnvelope,
+  type FederationMessageType,
+} from "./envelope.js";
+import { freshNonce, NonceCache, signEnvelope, verifySignature } from "./hmac.js";
+import { apply, isPiiMode, type PiiMode, type PiiResult } from "./pii.js";
+import { TrustEvaluator, type PeerState } from "./trust.js";
+import { PolicyEngine, type PolicyDecision } from "./policy.js";
+import { AuditService } from "./audit.js";
+import { FederationBudget, validateBudgetInput, type PerPeerBudget } from "./budget.js";
+
+// ---------------------------------------------------------------------------
+// Public re-exports
+// ---------------------------------------------------------------------------
+
+export {
+  FEDERATION_MESSAGE_TYPES,
+  TRUST_AFFECTING_MESSAGE_TYPES,
+  isFederationMessageType,
+  canonicalSignablePayload,
+  envelopeAgeMs,
+  emptyScanResult,
+  type EnvelopeBudget,
+  type FederationEnvelope,
+  type FederationMessageType,
+  type PiiScanAction,
+  type PiiScanDetection,
+  type PiiScanResult,
+} from "./envelope.js";
+
+export {
+  DEFAULT_NONCE_WINDOW_MS,
+  NonceCache,
+  freshNonce,
+  signEnvelope,
+  verifySignature,
+  type VerifyOptions,
+  type VerifyOutcome,
+} from "./hmac.js";
+
+export {
+  PII_MODES,
+  isPiiMode,
+  PiiPipeline,
+  apply,
+  type ApplyOptions,
+  type PiiAction,
+  type PiiCategory,
+  type PiiDetection,
+  type PiiMode,
+  type PiiResult,
+} from "./pii.js";
+
+export {
+  MAX_TRUST_AGE_MS,
+  MIN_TRUST_SCORE,
+  TrustEvaluator,
+  type PeerState,
+  type TrustDecision,
+} from "./trust.js";
+
+export {
+  DEFAULT_MAX_HOPS,
+  PolicyEngine,
+  type PolicyConfig,
+  type PolicyDecision,
+} from "./policy.js";
+
+export {
+  DEFAULT_AUDIT_PATH,
+  AuditService,
+  type AuditDecision,
+  type AuditEntry,
+  type AuditServiceOpts,
+} from "./audit.js";
+
+export {
+  DEFAULT_BUDGET_PATH,
+  MAX_TOKENS_CEILING,
+  MAX_USD_CEILING,
+  FederationBudget,
+  validateBudgetInput,
+  type FederationBudgetOpts,
+  type PerPeerBudget,
+  type ReserveResult,
+} from "./budget.js";
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+export interface FederationStatusSnapshot {
+  readonly nodeId: string;
+  readonly nonceCacheSize: number;
+  readonly auditSizeBytes: number;
+  readonly auditPath: string;
+  readonly budget: {
+    readonly path: string;
+    readonly perPeer: readonly PerPeerBudget[];
+    readonly outstandingReservations: number;
+  };
+  readonly peers: readonly PeerState[];
+}
+
+export interface CreateFederationOpts {
+  /** Local node id stamped into audit + status payloads. */
+  readonly nodeId: string;
+  /** Shared HMAC secret. Sender + receiver MUST match. */
+  readonly secret: string;
+  /** PII redaction mode applied on `sign()`. */
+  readonly piiMode?: PiiMode;
+  /** Override audit log path. */
+  readonly auditPath?: string;
+  /** Override budget JSON path. */
+  readonly budgetPath?: string;
+  /** Optional explicit PolicyEngine (for custom allowlists/blocklists). */
+  readonly policy?: PolicyEngine;
+  /** Optional explicit TrustEvaluator (custom allowlist). */
+  readonly trust?: TrustEvaluator;
+  /** Optional explicit AuditService (test-only override). */
+  readonly audit?: AuditService;
+  /** Optional explicit FederationBudget (test-only override). */
+  readonly budget?: FederationBudget;
+}
+
+export interface FederationHandle {
+  readonly nodeId: string;
+  /** PII redaction mode currently in effect. */
+  getPiiMode(): PiiMode;
+  setPiiMode(mode: PiiMode): void;
+  /** Sign + redact + audit. The resulting envelope is ready to
+   *  transmit to the peer. */
+  sign<T>(input: SignInput<T>): FederationEnvelope<T>;
+  /** Verify + admit-or-reject + audit. The caller decides what
+   *  to do with the result. */
+  receive<T>(envelope: FederationEnvelope<T>): ReceiveResult;
+  /** Snapshot for the `federation_status` MCP tool. */
+  status(): FederationStatusSnapshot;
+  /** Direct access to the underlying services — for advanced
+   *  consumers + tests. */
+  readonly services: {
+    readonly trust: TrustEvaluator;
+    readonly policy: PolicyEngine;
+    readonly audit: AuditService;
+    readonly budget: FederationBudget;
+    readonly nonces: NonceCache;
+  };
+}
+
+export interface SignInput<T> {
+  readonly targetNodeId: string;
+  readonly sessionId: string;
+  readonly messageType: FederationMessageType;
+  readonly payload: T;
+  readonly budget?: EnvelopeBudget;
+  /** If true, skip PII redaction. Defaults to false. */
+  readonly skipPii?: boolean;
+}
+
+export interface ReceiveResult {
+  readonly trusted: boolean;
+  readonly policyAllowed: boolean;
+  readonly hmacValid: boolean;
+  readonly pii: PiiResult;
+  readonly envelope: FederationEnvelope;
+  readonly rejectionReason?: string;
+}
+
+/** Build the orchestrator handle. */
+export function createFederation(opts: CreateFederationOpts): FederationHandle {
+  if (!opts || typeof opts.nodeId !== "string" || opts.nodeId.length === 0) {
+    throw new Error("createFederation: nodeId is required");
+  }
+  if (typeof opts.secret !== "string" || opts.secret.length === 0) {
+    throw new Error("createFederation: secret is required");
+  }
+  const modeRef: { value: PiiMode } = { value: isPiiMode(opts.piiMode) ? opts.piiMode : "soc2" };
+
+  const trust = opts.trust ?? new TrustEvaluator({ allowlist: [] });
+  const policy = opts.policy ?? new PolicyEngine();
+  const audit = opts.audit ?? new AuditService({ nodeId: opts.nodeId, path: opts.auditPath });
+  const budget = opts.budget ?? new FederationBudget({ path: opts.budgetPath });
+  const nonces = new NonceCache();
+
+  function getPiiMode(): PiiMode { return modeRef.value; }
+  function setPiiMode(m: PiiMode): void {
+    if (!isPiiMode(m)) throw new Error(`unknown PII mode: ${m}`);
+    modeRef.value = m;
+  }
+
+  function sign<T>(input: SignInput<T>): FederationEnvelope<T> {
+    const validated = input.budget
+      ? validateBudgetInput(input.budget)
+      : { ok: true as const, maxTokens: Number.POSITIVE_INFINITY, maxUsd: Number.POSITIVE_INFINITY, maxHops: 8 };
+    if (!validated.ok) throw new Error(`sign: bad budget: ${validated.error}`);
+
+    const env: FederationEnvelope<T> = {
+      envelopeId: randomUUID(),
+      sourceNodeId: opts.nodeId,
+      targetNodeId: input.targetNodeId,
+      sessionId: input.sessionId,
+      messageType: input.messageType,
+      payload: input.payload,
+      timestamp: new Date().toISOString(),
+      nonce: freshNonce(),
+      hmacSignature: "", // filled in below
+      piiScanResult: emptyScanResult(),
+      budget: {
+        maxTokens: validated.maxTokens,
+        maxUsd: validated.maxUsd,
+        maxHops: validated.maxHops,
+      },
+      hopCount: 0,
+      hopsRemaining: validated.maxHops,
+    };
+
+    // PII redaction over the stringified payload — keep the result
+    // in `piiScanResult` so the receiver can audit what was stripped.
+    let pii: PiiResult = { transformed: "", detections: [], actionsApplied: [], blocked: false, mode: modeRef.value };
+    if (!input.skipPii && typeof input.payload === "string") {
+      pii = apply(input.payload, modeRef.value);
+      if (pii.blocked) {
+        audit.record({
+          ts: new Date().toISOString(),
+          envelopeId: env.envelopeId,
+          sourceNodeId: env.sourceNodeId,
+          targetNodeId: env.targetNodeId,
+          messageType: env.messageType,
+          nonce: env.nonce,
+          allowed: false,
+          reason: `pii_blocked (mode=${modeRef.value})`,
+          layer: "budget",
+        });
+      }
+    }
+
+    const finalEnv: FederationEnvelope<T> = {
+      ...env,
+      payload: (pii.transformed ? (pii.transformed as unknown as T) : input.payload),
+      piiScanResult: pii.detections.length > 0
+        ? {
+            scanned: true,
+            piiFound: true,
+            detections: pii.detections.map((d) => ({
+              type: d.category,
+              action: "redact",
+              confidence: d.confidence,
+              count: 1,
+            })),
+            actionsApplied: pii.actionsApplied.map((a) => a.action),
+            scanDurationMs: 0,
+          }
+        : emptyScanResult(),
+    };
+
+    const signature = signEnvelope(finalEnv, opts.secret);
+    const signed: FederationEnvelope<T> = { ...finalEnv, hmacSignature: signature };
+
+    audit.record({
+      ts: signed.timestamp,
+      envelopeId: signed.envelopeId,
+      sourceNodeId: signed.sourceNodeId,
+      targetNodeId: signed.targetNodeId,
+      messageType: signed.messageType,
+      nonce: signed.nonce,
+      allowed: true,
+      reason: `signed (pii_mode=${modeRef.value})`,
+      layer: "sent",
+    });
+    return signed;
+  }
+
+  function receive<T>(envelope: FederationEnvelope<T>): ReceiveResult {
+    // 1. HMAC + freshness + nonce replay
+    const verifyOut = verifySignature(envelope, opts.secret, nonces as unknown as ReadonlySet<string>);
+    if (verifyOut.ok) {
+      nonces.check(envelope.nonce);
+    }
+
+    const piiScanResult = envelope.piiScanResult ?? emptyScanResult();
+    const pii: PiiResult = {
+      transformed: typeof envelope.payload === "string" ? envelope.payload : "",
+      detections: piiScanResult.detections.map((d) => ({
+        category: d.type as never,
+        value: "",
+        offset: 0,
+        confidence: d.confidence,
+      })),
+      actionsApplied: piiScanResult.actionsApplied.map((a) => ({ category: "email", action: a })),
+      blocked: false,
+      mode: modeRef.value,
+    };
+
+    let trusted = false;
+    let policyAllowed = false;
+    let rejectionReason: string | undefined;
+
+    if (!verifyOut.ok) {
+      rejectionReason = `hmac:${verifyOut.reason}`;
+      audit.record({
+        ts: new Date().toISOString(),
+        envelopeId: envelope.envelopeId,
+        sourceNodeId: envelope.sourceNodeId,
+        targetNodeId: envelope.targetNodeId,
+        messageType: envelope.messageType,
+        nonce: envelope.nonce,
+        allowed: false,
+        reason: rejectionReason,
+        layer: "hmac",
+      });
+    } else {
+      // 2. Trust
+      const peer: PeerState = trust.getPeerState(envelope.sourceNodeId);
+      const trustOut = trust.evaluate(envelope, peer);
+      trusted = trustOut.allowed;
+      if (!trusted) {
+        rejectionReason = `trust:${trustOut.reason}`;
+        trust.recordOutcome(envelope.sourceNodeId, false);
+        audit.record({
+          ts: new Date().toISOString(),
+          envelopeId: envelope.envelopeId,
+          sourceNodeId: envelope.sourceNodeId,
+          targetNodeId: envelope.targetNodeId,
+          messageType: envelope.messageType,
+          nonce: envelope.nonce,
+          allowed: false,
+          reason: rejectionReason,
+          layer: "trust",
+        });
+      } else {
+        trust.recordOutcome(envelope.sourceNodeId, true);
+        // 3. Policy (hops + blocklist + message allowlist)
+        const polOut: PolicyDecision = policy.enforce(envelope, envelope.budget);
+        policyAllowed = polOut.allowed;
+        if (!polOut.allowed) {
+          rejectionReason = `policy:${polOut.denialReason}`;
+          audit.record({
+            ts: new Date().toISOString(),
+            envelopeId: envelope.envelopeId,
+            sourceNodeId: envelope.sourceNodeId,
+            targetNodeId: envelope.targetNodeId,
+            messageType: envelope.messageType,
+            nonce: envelope.nonce,
+            allowed: false,
+            reason: rejectionReason,
+            layer: "policy",
+          });
+        } else {
+          audit.record({
+            ts: new Date().toISOString(),
+            envelopeId: envelope.envelopeId,
+            sourceNodeId: envelope.sourceNodeId,
+            targetNodeId: envelope.targetNodeId,
+            messageType: envelope.messageType,
+            nonce: envelope.nonce,
+            allowed: true,
+            reason: `accepted (score=${trustOut.score.toFixed(3)})`,
+            layer: "received",
+          });
+        }
+      }
+    }
+
+    return {
+      trusted,
+      policyAllowed,
+      hmacValid: verifyOut.ok,
+      pii,
+      envelope,
+      rejectionReason,
+    };
+  }
+
+  function status(): FederationStatusSnapshot {
+    // Synthesize a peer list from audit history + TrustEvaluator internal map.
+    const peerIds = new Set<string>();
+    const tail = audit.tail(1000);
+    for (const entry of tail) peerIds.add(entry.sourceNodeId);
+    const peerSnapshots: PeerState[] = [];
+    for (const id of peerIds) peerSnapshots.push(trust.getPeerState(id));
+
+    return {
+      nodeId: opts.nodeId,
+      nonceCacheSize: nonces.size(),
+      auditSizeBytes: audit.size(),
+      auditPath: audit.getPath(),
+      budget: {
+        path: opts.budgetPath ?? ".harness/federation-budget.json",
+        perPeer: budget.snapshot(),
+        outstandingReservations: budget.outstanding().length,
+      },
+      peers: peerSnapshots,
+    };
+  }
+
+  return {
+    nodeId: opts.nodeId,
+    getPiiMode,
+    setPiiMode,
+    sign,
+    receive,
+    status,
+    services: { trust, policy, audit, budget, nonces },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Convenience helper — re-export `canonicalSignablePayload` so callers
+// that want to compute their own signature can import it from the top.
+// ---------------------------------------------------------------------------
+
+export { canonicalSignablePayload as buildSignablePayload };
+
+// ---------------------------------------------------------------------------
+// Helper for tests — produce a fresh envelope-id.
+// ---------------------------------------------------------------------------
+
+export function freshEnvelopeId(): string {
+  return randomUUID();
+}