@polderlabs/bizar 6.3.0 → 7.0.0

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

@@ -0,0 +1,269 @@
+/**
+ * federation/budget.ts — FederationBudget: per-peer reserved →
+ * committed → released state machine for token / USD spend.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts`
+ * (validateBudget + enforceBudget shape) and folded into a class
+ * that tracks actual spend per peer across calls.
+ *
+ * State machine (per peer):
+ *   reserved:  amount is held back (the peer is going to spend ≤ N).
+ *   committed: amount was actually spent (the call completed and we
+ *              know the real cost).
+ *   released:  amount returned to the peer (call failed before
+ *              commit; we give the hold back).
+ *
+ * Persistence: optional JSON snapshot at
+ * `.harness/federation-budget.json` so the budget survives a
+ * Claude Code session restart. The file is gitignored.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Default budget JSON path. */
+export const DEFAULT_BUDGET_PATH = ".harness/federation-budget.json";
+
+/** Hard ceilings — matches ruflo's MAX_*_CEILING values, kept here
+ *  so callers can't ask for absurdly large budgets. */
+export const MAX_USD_CEILING = 1_000_000;
+export const MAX_TOKENS_CEILING = 1_000_000_000;
+
+export type ReserveResult =
+  | { ok: true; reservationId: string }
+  | { ok: false; reason: "peer_over_budget" | "invalid_amount" };
+
+export interface PerPeerBudget {
+  readonly nodeId: string;
+  readonly maxTokens: number;
+  readonly maxUsd: number;
+  readonly maxHops: number;
+  readonly spentTokens: number;
+  readonly spentUsd: number;
+}
+
+export interface PersistedBudget {
+  readonly version: 1;
+  readonly updatedAt: string;
+  readonly perPeer: PerPeerBudget[];
+}
+
+interface Reservation {
+  readonly id: string;
+  readonly nodeId: string;
+  readonly tokens: number;
+  readonly usd: number;
+  readonly atMs: number;
+}
+
+let reservationCounter = 0;
+
+function nextReservationId(): string {
+  reservationCounter++;
+  // 128-bit random suffix avoids collision across processes.
+  return `res-${Date.now().toString(36)}-${reservationCounter.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Pure validator — borrowed from ruflo's `validateBudget` and
+ *  simplified. Returns a discriminated result. */
+export function validateBudgetInput(raw: unknown): { ok: true; maxTokens: number; maxUsd: number; maxHops: number } | { ok: false; error: string } {
+  if (raw == null) {
+    return {
+      ok: true,
+      maxTokens: MAX_TOKENS_CEILING,
+      maxUsd: MAX_USD_CEILING,
+      maxHops: 8,
+    };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "budget must be an object" };
+  }
+  const obj = raw as Record<string, unknown>;
+  const hops = typeof obj.maxHops === "number" && Number.isFinite(obj.maxHops) ? obj.maxHops : 8;
+  const tokens = typeof obj.maxTokens === "number" && Number.isFinite(obj.maxTokens) ? obj.maxTokens : MAX_TOKENS_CEILING;
+  const usd = typeof obj.maxUsd === "number" && Number.isFinite(obj.maxUsd) ? obj.maxUsd : MAX_USD_CEILING;
+  if (hops < 0 || hops > 64) return { ok: false, error: "maxHops out of range" };
+  if (tokens < 0 || tokens > MAX_TOKENS_CEILING) return { ok: false, error: "maxTokens out of range" };
+  if (usd < 0 || usd > MAX_USD_CEILING) return { ok: false, error: "maxUsd out of range" };
+  return { ok: true, maxTokens: tokens, maxUsd: usd, maxHops: hops };
+}
+
+export interface FederationBudgetOpts {
+  /** Override the JSON persistence path. */
+  readonly path?: string;
+  /** Default per-peer limits applied when a peer is first seen. */
+  readonly defaultMaxTokens?: number;
+  readonly defaultMaxUsd?: number;
+  readonly defaultMaxHops?: number;
+}
+
+export class FederationBudget {
+  private readonly path: string;
+  private readonly perPeer = new Map<string, PerPeerBudget>();
+  private readonly reservations = new Map<string, Reservation>();
+  private readonly defaults: { maxTokens: number; maxUsd: number; maxHops: number };
+
+  constructor(opts: FederationBudgetOpts = {}) {
+    this.path = opts.path ?? DEFAULT_BUDGET_PATH;
+    this.defaults = {
+      maxTokens: opts.defaultMaxTokens ?? MAX_TOKENS_CEILING,
+      maxUsd: opts.defaultMaxUsd ?? MAX_USD_CEILING,
+      maxHops: opts.defaultMaxHops ?? 8,
+    };
+    this.loadFromDisk();
+  }
+
+  /** Get or lazily-create the per-peer budget record. */
+  getOrCreate(nodeId: string): PerPeerBudget {
+    let existing = this.perPeer.get(nodeId);
+    if (!existing) {
+      existing = {
+        nodeId,
+        maxTokens: this.defaults.maxTokens,
+        maxUsd: this.defaults.maxUsd,
+        maxHops: this.defaults.maxHops,
+        spentTokens: 0,
+        spentUsd: 0,
+      };
+      this.perPeer.set(nodeId, existing);
+    }
+    return existing;
+  }
+
+  /** Override the limits for a specific peer. */
+  setLimits(nodeId: string, limits: { maxTokens?: number; maxUsd?: number; maxHops?: number }): void {
+    const peer = this.getOrCreate(nodeId);
+    this.perPeer.set(nodeId, {
+      ...peer,
+      maxTokens: limits.maxTokens ?? peer.maxTokens,
+      maxUsd: limits.maxUsd ?? peer.maxUsd,
+      maxHops: limits.maxHops ?? peer.maxHops,
+    });
+    this.saveToDisk();
+  }
+
+  /** Reserve `tokens` + `usd` against a peer's budget. The caller
+   *  MUST eventually `commit()` or `release()` — un-released
+   *  reservations are surfaced via `outstanding()`. */
+  reserve(nodeId: string, tokens: number, usd: number): ReserveResult {
+    if (!Number.isFinite(tokens) || tokens < 0 || !Number.isFinite(usd) || usd < 0) {
+      return { ok: false, reason: "invalid_amount" };
+    }
+    const peer = this.getOrCreate(nodeId);
+    const remainingTokens = peer.maxTokens - peer.spentTokens;
+    const remainingUsd = peer.maxUsd - peer.spentUsd;
+    if (tokens > remainingTokens || usd > remainingUsd) {
+      return { ok: false, reason: "peer_over_budget" };
+    }
+    const id = nextReservationId();
+    this.reservations.set(id, {
+      id,
+      nodeId,
+      tokens,
+      usd,
+      atMs: Date.now(),
+    });
+    // Optimistically charge the spend against the budget so a
+    // concurrent reserve from the same peer cannot double-spend.
+    // If commit() reports less, the diff is refunded. If the call
+    // fails and release() is called, the full reservation is
+    // refunded.
+    this.perPeer.set(nodeId, {
+      ...peer,
+      spentTokens: peer.spentTokens + tokens,
+      spentUsd: peer.spentUsd + usd,
+    });
+    return { ok: true, reservationId: id };
+  }
+
+  /** Commit a reservation — caller reports the ACTUAL spend which
+   *  may be less than the reserved amount. Difference is refunded. */
+  commit(reservationId: string, actual: { tokens?: number; usd?: number } = {}): boolean {
+    const r = this.reservations.get(reservationId);
+    if (!r) return false;
+    const actualTokens = Math.max(0, actual.tokens ?? r.tokens);
+    const actualUsd = Math.max(0, actual.usd ?? r.usd);
+    const peer = this.perPeer.get(r.nodeId);
+    if (!peer) {
+      this.reservations.delete(reservationId);
+      return false;
+    }
+    // Refund the difference between reserved and actual.
+    const tokenRefund = r.tokens - actualTokens;
+    const usdRefund = r.usd - actualUsd;
+    this.perPeer.set(r.nodeId, {
+      ...peer,
+      spentTokens: Math.max(0, peer.spentTokens - tokenRefund),
+      spentUsd: Math.max(0, peer.spentUsd - usdRefund),
+    });
+    this.reservations.delete(reservationId);
+    this.saveToDisk();
+    return true;
+  }
+
+  /** Release a reservation — full refund. */
+  release(reservationId: string): boolean {
+    const r = this.reservations.get(reservationId);
+    if (!r) return false;
+    const peer = this.perPeer.get(r.nodeId);
+    if (peer) {
+      this.perPeer.set(r.nodeId, {
+        ...peer,
+        spentTokens: Math.max(0, peer.spentTokens - r.tokens),
+        spentUsd: Math.max(0, peer.spentUsd - r.usd),
+      });
+    }
+    this.reservations.delete(reservationId);
+    this.saveToDisk();
+    return true;
+  }
+
+  /** List outstanding reservations. */
+  outstanding(): Reservation[] {
+    return [...this.reservations.values()];
+  }
+
+  /** Snapshot every per-peer budget — for the status MCP tool. */
+  snapshot(): PerPeerBudget[] {
+    return [...this.perPeer.values()];
+  }
+
+  /** Serialize to the persisted JSON shape. */
+  toJSON(): PersistedBudget {
+    return {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      perPeer: this.snapshot(),
+    };
+  }
+
+  /** Write to disk (atomic tmp + rename). */
+  saveToDisk(): void {
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const tmp = `${this.path}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify(this.toJSON(), null, 2), "utf-8");
+      renameSync(tmp, this.path);
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  /** Re-read from disk, replacing in-memory state. */
+  loadFromDisk(): void {
+    if (!existsSync(this.path)) return;
+    try {
+      const raw = readFileSync(this.path, "utf-8");
+      const parsed = JSON.parse(raw) as PersistedBudget;
+      if (parsed.version !== 1 || !Array.isArray(parsed.perPeer)) return;
+      this.perPeer.clear();
+      for (const p of parsed.perPeer) {
+        if (typeof p.nodeId === "string") this.perPeer.set(p.nodeId, p);
+      }
+    } catch {
+      /* malformed — keep defaults */
+    }
+  }
+}

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

@@ -0,0 +1,144 @@
+/**
+ * federation/envelope.ts — Federation envelope type and message kinds.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/entities/federation-envelope.ts:1-20`
+ * (the 16-kind `FederationMessageType` union + `FederationEnvelope` shape).
+ *
+ * This module is intentionally minimal: it exports ONLY types + a
+ * tiny `emptyScanResult()` helper. The runtime signing/verification
+ * lives in `./hmac.ts`, PII in `./pii.ts`, audit in `./audit.ts`,
+ * budget in `./budget.ts`. Keeping the type isolated here avoids a
+ * cycle with the signing/policy modules that import from this file.
+ *
+ * Backward-compat note: Bizar's v6.4.0 release (current `master`)
+ * shipped zero federation code, so anything we add is purely
+ * additive — no consumers can break. The 16 message kinds are
+ * defined as a `readonly` array AND a union type so the validator
+ * surface (e.g. PolicyEngine) can iterate without re-listing them.
+ */
+
+/**
+ * Wire-level message kinds carried inside a federation envelope.
+ * 16 total — kept identical to the ruflo source so cross-installation
+ * pairs can interoperate if both run a Bizar build ≥ v6.5.0.
+ */
+export const FEDERATION_MESSAGE_TYPES = [
+  "task-assignment",
+  "memory-query",
+  "memory-response",
+  "context-share",
+  "status-broadcast",
+  "trust-change",
+  "topology-change",
+  "agent-spawn",
+  "heartbeat",
+  "challenge",
+  "challenge-response",
+  "handshake-init",
+  "handshake-accept",
+  "handshake-reject",
+  "session-terminate",
+  "claim-event",
+  "agent-handoff",
+] as const;
+
+export type FederationMessageType = (typeof FEDERATION_MESSAGE_TYPES)[number];
+
+/** Is `t` a recognised federation message kind? Useful for validation. */
+export function isFederationMessageType(t: unknown): t is FederationMessageType {
+  return typeof t === "string" && (FEDERATION_MESSAGE_TYPES as readonly string[]).includes(t);
+}
+
+/** Subset of message kinds that mutate trust / topology state — those
+ *  that should require extra policy scrutiny (mirrors ruflo's
+ *  CONSENSUS_REQUIRED_TYPES set, minus the consensus-vote-specific
+ *  types that don't apply to the skeleton). */
+export const TRUST_AFFECTING_MESSAGE_TYPES: ReadonlySet<FederationMessageType> = new Set<FederationMessageType>([
+  "trust-change",
+  "topology-change",
+  "agent-spawn",
+  "agent-handoff",
+]);
+
+/** Outcome of a PII scan over the envelope payload. Mirrors ruflo's
+ *  PIIScanResult so audit consumers can read either implementation
+ *  interchangeably. */
+export type PiiScanAction = "pass" | "redact" | "hash" | "block";
+
+export interface PiiScanDetection {
+  readonly type: string;
+  readonly action: PiiScanAction;
+  readonly confidence: number;
+  readonly count: number;
+}
+
+export interface PiiScanResult {
+  readonly scanned: boolean;
+  readonly piiFound: boolean;
+  readonly detections: readonly PiiScanDetection[];
+  readonly actionsApplied: readonly PiiScanAction[];
+  readonly scanDurationMs: number;
+}
+
+/** Empty / no-op scan result — used by senders that opt out of PII
+ *  scanning for the given message kind. */
+export function emptyScanResult(): PiiScanResult {
+  return {
+    scanned: false,
+    piiFound: false,
+    detections: [],
+    actionsApplied: [],
+    scanDurationMs: 0,
+  };
+}
+
+/** Per-peer budget attached to every envelope. `maxTokens` and
+ *  `maxUsd` are the sender's original limits for the call; the
+ *  remote decrements them as the message fans out. `maxHops` is
+ *  the absolute hop ceiling (sender's value). */
+export interface EnvelopeBudget {
+  readonly maxTokens: number;
+  readonly maxUsd: number;
+  readonly maxHops: number;
+}
+
+export interface FederationEnvelope<T = unknown> {
+  readonly envelopeId: string;
+  readonly sourceNodeId: string;
+  readonly targetNodeId: string;
+  readonly sessionId: string;
+  readonly messageType: FederationMessageType;
+  readonly payload: T;
+  readonly timestamp: string; // ISO-8601, parsed back via new Date()
+  readonly nonce: string; // 128-bit random via crypto.randomUUID()
+  readonly hmacSignature: string; // hex SHA-256 HMAC over canonical payload
+  readonly piiScanResult: PiiScanResult;
+  readonly budget?: EnvelopeBudget;
+  readonly hopCount?: number; // present on re-emit, defaults to 0 on origin
+  readonly hopsRemaining?: number;
+}
+
+/** Canonical JSON form signed by HMAC. Field order MUST stay stable
+ *  across sender + receiver or signatures will mismatch. */
+export function canonicalSignablePayload<T>(e: FederationEnvelope<T>): string {
+  const obj = {
+    envelopeId: e.envelopeId,
+    sourceNodeId: e.sourceNodeId,
+    targetNodeId: e.targetNodeId,
+    sessionId: e.sessionId,
+    messageType: e.messageType,
+    payload: e.payload,
+    timestamp: e.timestamp,
+    nonce: e.nonce,
+    hopCount: e.hopCount ?? 0,
+  };
+  return JSON.stringify(obj);
+}
+
+/** `Date.now()`-based envelope age in milliseconds. */
+export function envelopeAgeMs(e: FederationEnvelope, now: number = Date.now()): number {
+  const ts = new Date(e.timestamp).getTime();
+  if (!Number.isFinite(ts)) return Number.POSITIVE_INFINITY;
+  return Math.max(0, now - ts);
+}

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