@polderlabs/bizar 9.0.0 → 10.0.7

package/packages/sdk/dist/federation/envelope.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare const FEDERATION_MESSAGE_TYPES: readonly ["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"];
+export type FederationMessageType = (typeof FEDERATION_MESSAGE_TYPES)[number];
+/** Is `t` a recognised federation message kind? Useful for validation. */
+export declare function isFederationMessageType(t: unknown): t is FederationMessageType;
+/** 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 declare const TRUST_AFFECTING_MESSAGE_TYPES: ReadonlySet<FederationMessageType>;
+/** 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 declare function emptyScanResult(): PiiScanResult;
+/** 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;
+    readonly nonce: string;
+    readonly hmacSignature: string;
+    readonly piiScanResult: PiiScanResult;
+    readonly budget?: EnvelopeBudget;
+    readonly hopCount?: number;
+    readonly hopsRemaining?: number;
+}
+/** Canonical JSON form signed by HMAC. Field order MUST stay stable
+ *  across sender + receiver or signatures will mismatch. */
+export declare function canonicalSignablePayload<T>(e: FederationEnvelope<T>): string;
+/** `Date.now()`-based envelope age in milliseconds. */
+export declare function envelopeAgeMs(e: FederationEnvelope, now?: number): number;
+//# sourceMappingURL=envelope.d.ts.map

package/packages/sdk/dist/federation/envelope.js

@@ -0,0 +1,92 @@
+/**
+ * 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",
+];
+/** Is `t` a recognised federation message kind? Useful for validation. */
+export function isFederationMessageType(t) {
+    return typeof t === "string" && FEDERATION_MESSAGE_TYPES.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 = new Set([
+    "trust-change",
+    "topology-change",
+    "agent-spawn",
+    "agent-handoff",
+]);
+/** Empty / no-op scan result — used by senders that opt out of PII
+ *  scanning for the given message kind. */
+export function emptyScanResult() {
+    return {
+        scanned: false,
+        piiFound: false,
+        detections: [],
+        actionsApplied: [],
+        scanDurationMs: 0,
+    };
+}
+/** Canonical JSON form signed by HMAC. Field order MUST stay stable
+ *  across sender + receiver or signatures will mismatch. */
+export function canonicalSignablePayload(e) {
+    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, now = Date.now()) {
+    const ts = new Date(e.timestamp).getTime();
+    if (!Number.isFinite(ts))
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, now - ts);
+}
+//# sourceMappingURL=envelope.js.map

package/packages/sdk/dist/federation/hmac.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { type FederationEnvelope } from "./envelope.js";
+/** Default freshness window for HMAC verification (5 minutes). */
+export declare const DEFAULT_NONCE_WINDOW_MS: number;
+/** Compute a deterministic 64-char hex HMAC-SHA-256 over the envelope's
+ *  canonical signable payload. */
+export declare function signEnvelope<T>(envelope: FederationEnvelope<T>, secret: string): string;
+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 declare function verifySignature<T>(envelope: FederationEnvelope<T>, secret: string, seen: ReadonlySet<string>, opts?: VerifyOptions): VerifyOutcome;
+/** Mutable nonce cache with TTL eviction + hard cap. The receiver
+ *  keeps one per remote node (or a single global one for the skeleton). */
+export declare class NonceCache {
+    private readonly seen;
+    private readonly windowMs;
+    constructor(windowMs?: number);
+    /** True if the nonce is fresh (not seen in windowMs). Adds it
+     *  to the cache as a side effect. */
+    check(nonce: string, now?: number): boolean;
+    /** True if the nonce is in the cache (read-only). */
+    has(nonce: string): boolean;
+    size(): number;
+    clear(): void;
+    private evict;
+}
+/** Helper — produce a fresh nonce via `crypto.randomUUID()`. */
+export declare function freshNonce(): string;
+//# sourceMappingURL=hmac.d.ts.map

package/packages/sdk/dist/federation/hmac.js

@@ -0,0 +1,120 @@
+/**
+ * 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, } 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(envelope, secret) {
+    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");
+}
+/** Pure verifier — no shared state. The caller owns the seen-nonce
+ *  cache (see `NonceCache` below) and passes it in via `seen`. */
+export function verifySignature(envelope, secret, seen, opts = {}) {
+    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;
+    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 {
+    seen = new Map(); // nonce → expiryMs
+    windowMs;
+    constructor(windowMs = 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, now = Date.now()) {
+        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) {
+        return this.seen.has(nonce);
+    }
+    size() {
+        return this.seen.size;
+    }
+    clear() {
+        this.seen.clear();
+    }
+    evict(now) {
+        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() {
+    return randomUUID();
+}
+//# sourceMappingURL=hmac.js.map

package/packages/sdk/dist/federation/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { canonicalSignablePayload, type EnvelopeBudget, type FederationEnvelope, type FederationMessageType } from "./envelope.js";
+import { NonceCache } from "./hmac.js";
+import { type PiiMode, type PiiResult } from "./pii.js";
+import { TrustEvaluator, type PeerState } from "./trust.js";
+import { PolicyEngine } from "./policy.js";
+import { AuditService } from "./audit.js";
+import { FederationBudget, type PerPeerBudget } from "./budget.js";
+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";
+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 declare function createFederation(opts: CreateFederationOpts): FederationHandle;
+export { canonicalSignablePayload as buildSignablePayload };
+export declare function freshEnvelopeId(): string;
+//# sourceMappingURL=index.d.ts.map