@polderlabs/bizar 6.2.5 → 7.0.0

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

@@ -0,0 +1,156 @@
+/**
+ * federation/audit.ts — AuditService: NDJSON log of every
+ * federation decision.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/services/audit-service.ts`
+ * stripped to the parts the skeleton needs:
+ *
+ *   - record(envelope, decision) appends ONE NDJSON line to
+ *     `.harness/federation-audit.log`.
+ *   - When the file exceeds 10 MB, it rotates to
+ *     `.harness/federation-audit.log.1` (single generation).
+ *   - tail() reads the last N lines for the `federation_status` MCP tool.
+ *   - size() returns the on-disk file size for the status payload.
+ *
+ * Writes are synchronous (fs.appendFileSync) — the skeleton is
+ * in-process and not throughput-bound; an async path would only
+ * complicate testing.
+ *
+ * The `.harness/` directory is created on first write. The audit
+ * log file is added to `.gitignore` by the Makefile/install step.
+ */
+
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Default audit log path — colocated with the rest of `.harness/`. */
+export const DEFAULT_AUDIT_PATH = ".harness/federation-audit.log";
+
+/** Rotate when the file exceeds this size. */
+const ROTATION_THRESHOLD_BYTES = 10 * 1024 * 1024; // 10 MB
+
+/** Tail size cap — protects against reading gigabytes into memory. */
+const TAIL_MAX_BYTES = 1 * 1024 * 1024; // 1 MB
+
+/** Decisions recorded by the orchestrator — matches the schema the
+ *  `federation_status` MCP tool reads back. */
+export type AuditDecision =
+  | { allowed: true; reason: string }
+  | { allowed: false; reason: string };
+
+export interface AuditEntry {
+  readonly ts: string;
+  readonly envelopeId: string;
+  readonly sourceNodeId: string;
+  readonly targetNodeId: string;
+  readonly messageType: string;
+  readonly nonce: string;
+  readonly allowed: boolean;
+  readonly reason: string;
+  readonly layer: "trust" | "policy" | "hmac" | "budget" | "received" | "sent";
+  readonly nodeId: string;
+}
+
+export interface AuditServiceOpts {
+  /** Override the audit file path (defaults to .harness/federation-audit.log). */
+  readonly path?: string;
+  /** Local nodeId stamped into every entry. */
+  readonly nodeId: string;
+}
+
+export class AuditService {
+  private readonly path: string;
+  private readonly nodeId: string;
+  private rotated = false;
+
+  constructor(opts: AuditServiceOpts) {
+    if (!opts || typeof opts.nodeId !== "string" || opts.nodeId.length === 0) {
+      throw new Error("AuditService: nodeId is required");
+    }
+    this.path = opts.path ?? DEFAULT_AUDIT_PATH;
+    this.nodeId = opts.nodeId;
+  }
+
+  getPath(): string {
+    return this.path;
+  }
+
+  /** Append an NDJSON line. Triggers rotation if the file would
+   *  exceed the threshold after the write. */
+  record(entry: Omit<AuditEntry, "nodeId">): void {
+    const full: AuditEntry = { ...entry, nodeId: this.nodeId };
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    // Pre-write rotation check: if appending would exceed the
+    // threshold AND we haven't already rotated this session, rotate
+    // first. We keep a single generation (`.log.1`); older logs
+    // are the operator's responsibility (or a separate cron).
+    if (!this.rotated && existsSync(this.path)) {
+      try {
+        const size = statSync(this.path).size;
+        if (size + 256 > ROTATION_THRESHOLD_BYTES) {
+          this.rotate();
+        }
+      } catch {
+        // stat failed (file gone between check and write) — fall through.
+      }
+    }
+
+    appendFileSync(this.path, JSON.stringify(full) + "\n", "utf-8");
+  }
+
+  /** Rotate the current log to `.log.1`. Subsequent writes go to a
+   *  fresh `.log` file. Idempotent within a single service lifetime. */
+  rotate(): void {
+    const target = `${this.path}.1`;
+    if (existsSync(this.path)) {
+      try { renameSync(this.path, target); }
+      catch { /* ignore — best-effort */ }
+    }
+    this.rotated = true;
+  }
+
+  /** On-disk size in bytes. 0 if file missing. */
+  size(): number {
+    try {
+      return existsSync(this.path) ? statSync(this.path).size : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Read the last `n` entries from the log. Bounded by TAIL_MAX_BYTES. */
+  tail(n: number = 50): AuditEntry[] {
+    if (!existsSync(this.path)) return [];
+    let raw: string;
+    try {
+      const stats = statSync(this.path);
+      const start = Math.max(0, stats.size - TAIL_MAX_BYTES);
+      const buffer = Buffer.alloc(stats.size - start);
+      // Read the last TAIL_MAX_BYTES via a small open/read/close dance.
+      const handle = openSync(this.path, "r");
+      try { readSync(handle, buffer, 0, buffer.length, start); }
+      finally { closeSync(handle); }
+      raw = buffer.toString("utf-8");
+    } catch {
+      raw = readFileSync(this.path, "utf-8");
+    }
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const slice = lines.slice(-n);
+    const out: AuditEntry[] = [];
+    for (const line of slice) {
+      try { out.push(JSON.parse(line) as AuditEntry); }
+      catch { /* malformed line — skip */ }
+    }
+    return out;
+  }
+
+  /** Wipe the audit log. Test-only helper. */
+  reset(): void {
+    this.rotated = false;
+    try { if (existsSync(this.path)) renameSync(this.path, `${this.path}.deleted`); }
+    catch { /* ignore */ }
+  }
+}

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