@polderlabs/bizar 9.0.0 → 10.0.7

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

@@ -0,0 +1,275 @@
+/**
+ * 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, } from "./envelope.js";
+import { freshNonce, NonceCache, signEnvelope, verifySignature } from "./hmac.js";
+import { apply, isPiiMode } from "./pii.js";
+import { TrustEvaluator } from "./trust.js";
+import { PolicyEngine } from "./policy.js";
+import { AuditService } from "./audit.js";
+import { FederationBudget, validateBudgetInput } from "./budget.js";
+// ---------------------------------------------------------------------------
+// Public re-exports
+// ---------------------------------------------------------------------------
+export { FEDERATION_MESSAGE_TYPES, TRUST_AFFECTING_MESSAGE_TYPES, isFederationMessageType, canonicalSignablePayload, envelopeAgeMs, emptyScanResult, } from "./envelope.js";
+export { DEFAULT_NONCE_WINDOW_MS, NonceCache, freshNonce, signEnvelope, verifySignature, } from "./hmac.js";
+export { PII_MODES, isPiiMode, PiiPipeline, apply, } from "./pii.js";
+export { MAX_TRUST_AGE_MS, MIN_TRUST_SCORE, TrustEvaluator, } from "./trust.js";
+export { DEFAULT_MAX_HOPS, PolicyEngine, } from "./policy.js";
+export { DEFAULT_AUDIT_PATH, AuditService, } from "./audit.js";
+export { DEFAULT_BUDGET_PATH, MAX_TOKENS_CEILING, MAX_USD_CEILING, FederationBudget, validateBudgetInput, } from "./budget.js";
+/** Build the orchestrator handle. */
+export function createFederation(opts) {
+    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: 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() { return modeRef.value; }
+    function setPiiMode(m) {
+        if (!isPiiMode(m))
+            throw new Error(`unknown PII mode: ${m}`);
+        modeRef.value = m;
+    }
+    function sign(input) {
+        const validated = input.budget
+            ? validateBudgetInput(input.budget)
+            : { ok: true, maxTokens: Number.POSITIVE_INFINITY, maxUsd: Number.POSITIVE_INFINITY, maxHops: 8 };
+        if (!validated.ok)
+            throw new Error(`sign: bad budget: ${validated.error}`);
+        const env = {
+            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 = { 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 = {
+            ...env,
+            payload: (pii.transformed ? pii.transformed : 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 = { ...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(envelope) {
+        // 1. HMAC + freshness + nonce replay
+        const verifyOut = verifySignature(envelope, opts.secret, nonces);
+        if (verifyOut.ok) {
+            nonces.check(envelope.nonce);
+        }
+        const piiScanResult = envelope.piiScanResult ?? emptyScanResult();
+        const pii = {
+            transformed: typeof envelope.payload === "string" ? envelope.payload : "",
+            detections: piiScanResult.detections.map((d) => ({
+                category: d.type,
+                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;
+        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 = 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 = 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() {
+        // Synthesize a peer list from audit history + TrustEvaluator internal map.
+        const peerIds = new Set();
+        const tail = audit.tail(1000);
+        for (const entry of tail)
+            peerIds.add(entry.sourceNodeId);
+        const peerSnapshots = [];
+        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() {
+    return randomUUID();
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,72 @@
+/**
+ * federation/pii.ts — PII redaction pipeline with 4 compliance modes.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts`
+ * but simplified per spec ("For v1, focus on redact (regex-based:
+ * emails, SSNs, credit cards, IPs)") while keeping the same
+ * 4-mode surface (`soc2 | gdpr | hipaa | permissive`).
+ *
+ * Compliance modes map to the detection + action matrix:
+ *
+ *   soc2       — strict; redact emails, IPs, SSNs, credit cards.
+ *   gdpr       — strict; redact emails, IPs, names, addresses.
+ *   hipaa      — strictest; redact everything we recognise (incl. SSN).
+ *   permissive — only block the most damaging (credit cards, JWTs,
+ *                AWS keys, private keys, GitHub tokens); pass through
+ *                emails / IPs / phone numbers.
+ *
+ * The transforms are PURE: no I/O, no clocks (other than explicit
+ * `now` injection). `apply()` returns a transformed string + the
+ * list of detections + a `blocked` flag (true if a hard-blocked
+ * PII was found — the caller decides whether to drop the message).
+ *
+ * No native deps.
+ */
+/** 4 supported compliance modes for the skeleton. */
+export type PiiMode = "soc2" | "gdpr" | "hipaa" | "permissive";
+export declare const PII_MODES: readonly PiiMode[];
+export declare function isPiiMode(m: unknown): m is PiiMode;
+export type PiiAction = "redact" | "hash" | "pass" | "block";
+/** Internal PII categories — finer-grained than the modes. */
+export type PiiCategory = "email" | "ssn" | "credit_card" | "ip_address" | "phone" | "name" | "address" | "jwt" | "aws_key" | "private_key" | "github_token";
+export interface PiiDetection {
+    readonly category: PiiCategory;
+    readonly value: string;
+    readonly offset: number;
+    readonly confidence: number;
+}
+export interface PiiResult {
+    readonly transformed: string;
+    readonly detections: readonly PiiDetection[];
+    readonly actionsApplied: readonly {
+        category: PiiCategory;
+        action: PiiAction;
+    }[];
+    readonly blocked: boolean;
+    readonly mode: PiiMode;
+}
+export interface ApplyOptions {
+    /** Salt for hash() actions. Defaults to "bizar". */
+    readonly salt?: string;
+}
+/** Pure-function PII pipeline. Walks the regex table, decides an
+ *  action per category under the chosen mode, applies the
+ *  replacement. Returns enough metadata for the audit service to
+ *  log what was stripped. */
+export declare function apply(text: string, mode: PiiMode, opts?: ApplyOptions): PiiResult;
+/** PiiPipeline — class wrapper for parity with ruflo's
+ *  PIIPipelineService shape. Holds a default mode + salt, exposes
+ *  `process(text)` and `setMode(mode)`. */
+export declare class PiiPipeline {
+    private mode;
+    private readonly salt;
+    constructor(opts?: {
+        mode?: PiiMode;
+        salt?: string;
+    });
+    setMode(mode: PiiMode): void;
+    getMode(): PiiMode;
+    process(text: string): PiiResult;
+}
+//# sourceMappingURL=pii.d.ts.map

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

@@ -0,0 +1,178 @@
+/**
+ * federation/pii.ts — PII redaction pipeline with 4 compliance modes.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/services/pii-pipeline-service.ts`
+ * but simplified per spec ("For v1, focus on redact (regex-based:
+ * emails, SSNs, credit cards, IPs)") while keeping the same
+ * 4-mode surface (`soc2 | gdpr | hipaa | permissive`).
+ *
+ * Compliance modes map to the detection + action matrix:
+ *
+ *   soc2       — strict; redact emails, IPs, SSNs, credit cards.
+ *   gdpr       — strict; redact emails, IPs, names, addresses.
+ *   hipaa      — strictest; redact everything we recognise (incl. SSN).
+ *   permissive — only block the most damaging (credit cards, JWTs,
+ *                AWS keys, private keys, GitHub tokens); pass through
+ *                emails / IPs / phone numbers.
+ *
+ * The transforms are PURE: no I/O, no clocks (other than explicit
+ * `now` injection). `apply()` returns a transformed string + the
+ * list of detections + a `blocked` flag (true if a hard-blocked
+ * PII was found — the caller decides whether to drop the message).
+ *
+ * No native deps.
+ */
+export const PII_MODES = ["soc2", "gdpr", "hipaa", "permissive"];
+export function isPiiMode(m) {
+    return typeof m === "string" && PII_MODES.includes(m);
+}
+/** Detection table — order matters: more-specific patterns come first
+ *  so we don't double-match. */
+const PATTERNS = [
+    // secrets/keys — block in every mode except permissive (which still blocks them)
+    { category: "aws_key", pattern: /\bAKIA[0-9A-Z]{16}\b/g, confidence: 0.99 },
+    { category: "private_key", pattern: /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+)?PRIVATE\s+KEY-----/g, confidence: 0.99 },
+    { category: "github_token", pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36,}\b/g, confidence: 0.97 },
+    { category: "jwt", pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, confidence: 0.95 },
+    { category: "credit_card", pattern: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g, confidence: 0.94 },
+    { category: "ssn", pattern: /\b\d{3}-\d{2}-\d{4}\b/g, confidence: 0.93 },
+    { category: "email", pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, confidence: 0.9 },
+    { category: "ip_address", pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g, confidence: 0.85 },
+    { category: "phone", pattern: /(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g, confidence: 0.8 },
+    { category: "name", pattern: /\b(?:Mr\.|Mrs\.|Ms\.|Dr\.)\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g, confidence: 0.7 },
+    { category: "address", pattern: /\b\d{1,5}\s+(?:[A-Z][a-z]+\s+){1,3}(?:St|Ave|Blvd|Dr|Ln|Rd|Way|Ct)\b/g, confidence: 0.7 },
+];
+/** Per-mode action policy. `block` means the envelope is rejected
+ *  outright (caller drops it); `redact` replaces with
+ *  `[REDACTED:<category>]`; `hash` replaces with
+ *  `[HASH:<8-char-prefix>]`; `pass` lets it through unchanged. */
+const MODE_POLICY = {
+    soc2: {
+        email: "redact", ssn: "redact", credit_card: "block", ip_address: "redact",
+        phone: "redact", name: "pass", address: "pass",
+        jwt: "block", aws_key: "block", private_key: "block", github_token: "block",
+    },
+    gdpr: {
+        email: "redact", ssn: "redact", credit_card: "block", ip_address: "redact",
+        phone: "redact", name: "redact", address: "redact",
+        jwt: "block", aws_key: "block", private_key: "block", github_token: "block",
+    },
+    hipaa: {
+        email: "redact", ssn: "redact", credit_card: "block", ip_address: "redact",
+        phone: "redact", name: "redact", address: "redact",
+        jwt: "block", aws_key: "block", private_key: "block", github_token: "block",
+    },
+    permissive: {
+        email: "pass", ssn: "redact", credit_card: "block", ip_address: "pass",
+        phone: "pass", name: "pass", address: "pass",
+        jwt: "block", aws_key: "block", private_key: "block", github_token: "block",
+    },
+};
+const REDACT_TOKEN = (cat) => `[REDACTED:${cat}]`;
+const HASH_PREFIX = 8;
+function deterministicHash(value, salt) {
+    // Lightweight, no-native-dep hash: FNV-1a 32-bit, hex-encoded, then
+    // salted + first-N chars. The skeleton doesn't need crypto-grade
+    // hashing here — the HMAC envelope signature already provides
+    // integrity. This is purely for irreversible string replacement.
+    let h = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        h ^= value.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    const salted = `${salt}:${h.toString(16).padStart(8, "0")}`;
+    let h2 = 0x811c9dc5;
+    for (let i = 0; i < salted.length; i++) {
+        h2 ^= salted.charCodeAt(i);
+        h2 = Math.imul(h2, 0x01000193) >>> 0;
+    }
+    return h2.toString(16).padStart(8, "0");
+}
+/** Pure-function PII pipeline. Walks the regex table, decides an
+ *  action per category under the chosen mode, applies the
+ *  replacement. Returns enough metadata for the audit service to
+ *  log what was stripped. */
+export function apply(text, mode, opts = {}) {
+    if (!isPiiMode(mode)) {
+        throw new Error(`apply: unknown mode '${String(mode)}'`);
+    }
+    const salt = opts.salt ?? "bizar";
+    const policy = MODE_POLICY[mode];
+    const detections = [];
+    const actionsApplied = [];
+    let blocked = false;
+    let transformed = text;
+    // Two-phase: (1) collect ALL detections across ALL categories first,
+    // (2) apply per-category actions in reverse-offset order so a
+    // `block` on one category doesn't hide detections in later ones.
+    for (const entry of PATTERNS) {
+        const regex = new RegExp(entry.pattern.source, entry.pattern.flags);
+        let m;
+        while ((m = regex.exec(transformed)) !== null) {
+            detections.push({
+                category: entry.category,
+                value: m[0],
+                offset: m.index,
+                confidence: entry.confidence,
+            });
+        }
+    }
+    // Now compute actions per category. `block` short-circuits the
+    // whole transform but we still report every detection.
+    for (const entry of PATTERNS) {
+        const inCategory = detections.filter((d) => d.category === entry.category);
+        if (inCategory.length === 0)
+            continue;
+        const action = policy[entry.category];
+        actionsApplied.push({ category: entry.category, action });
+        if (action === "block") {
+            blocked = true;
+            continue;
+        }
+        if (action === "pass")
+            continue;
+        // Apply right-to-left so earlier offsets remain valid.
+        for (const hit of inCategory.reverse()) {
+            const replacement = action === "redact"
+                ? REDACT_TOKEN(entry.category)
+                : `[HASH:${deterministicHash(hit.value, salt).slice(0, HASH_PREFIX)}]`;
+            transformed =
+                transformed.slice(0, hit.offset) +
+                    replacement +
+                    transformed.slice(hit.offset + hit.value.length);
+        }
+    }
+    if (blocked)
+        transformed = "";
+    return {
+        transformed,
+        detections,
+        actionsApplied,
+        blocked,
+        mode,
+    };
+}
+/** PiiPipeline — class wrapper for parity with ruflo's
+ *  PIIPipelineService shape. Holds a default mode + salt, exposes
+ *  `process(text)` and `setMode(mode)`. */
+export class PiiPipeline {
+    mode;
+    salt;
+    constructor(opts = {}) {
+        this.mode = opts.mode ?? "soc2";
+        this.salt = opts.salt ?? "bizar";
+    }
+    setMode(mode) {
+        if (!isPiiMode(mode))
+            throw new Error(`PiiPipeline: unknown mode '${mode}'`);
+        this.mode = mode;
+    }
+    getMode() {
+        return this.mode;
+    }
+    process(text) {
+        return apply(text, this.mode, { salt: this.salt });
+    }
+}
+//# sourceMappingURL=pii.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * federation/policy.ts — PolicyEngine: enforces per-call envelope
+ * constraints (maxHops, action allowlist, peer blocklist).
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/application/policy-engine.ts`
+ * but stripped to the three checks the skeleton needs:
+ *
+ *   1. maxHops  — envelope.hopCount must be < budget.maxHops
+ *                 (default ceiling = 3 hops).
+ *   2. message  — envelope.messageType must be in the action
+ *                 allowlist.
+ *   3. peer     — source node must NOT be in the blocklist.
+ *
+ * `enforce(envelope, budget)` returns a discriminated result so
+ * callers can map directly to an MCP error string.
+ */
+import { type EnvelopeBudget, type FederationEnvelope, type FederationMessageType } from "./envelope.js";
+/** Hard ceiling on hops — matches the spec's "≤ 3" rule. */
+export declare const DEFAULT_MAX_HOPS = 3;
+export type PolicyDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    denialReason: "max_hops_exceeded" | "message_type_not_allowed" | "peer_blocked" | "budget_missing" | "budget_invalid";
+};
+export interface PolicyConfig {
+    /** Set of message kinds accepted by this node. Defaults to all
+     *  16 ruflo kinds — narrow via `allowedMessageTypes`. */
+    readonly allowedMessageTypes?: readonly FederationMessageType[];
+    /** Set of sourceNodeIds that are NEVER accepted (blocklist). */
+    readonly peerBlocklist?: readonly string[];
+    /** Override the default maxHops ceiling. */
+    readonly maxHops?: number;
+}
+export declare class PolicyEngine {
+    private readonly allowed;
+    private readonly blocked;
+    private readonly maxHops;
+    constructor(cfg?: PolicyConfig);
+    /** Runtime mutator — narrow the allowlist after construction. */
+    allowMessageType(t: FederationMessageType): void;
+    /** Runtime mutator — narrow the allowlist after construction. */
+    denyMessageType(t: FederationMessageType): void;
+    /** Runtime mutator — block / unblock a peer at runtime. */
+    setBlocked(nodeId: string, blocked: boolean): void;
+    /** Admit or reject an envelope given its budget context. */
+    enforce(envelope: FederationEnvelope, budget: EnvelopeBudget | undefined): PolicyDecision;
+}
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1,76 @@
+/**
+ * federation/policy.ts — PolicyEngine: enforces per-call envelope
+ * constraints (maxHops, action allowlist, peer blocklist).
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/application/policy-engine.ts`
+ * but stripped to the three checks the skeleton needs:
+ *
+ *   1. maxHops  — envelope.hopCount must be < budget.maxHops
+ *                 (default ceiling = 3 hops).
+ *   2. message  — envelope.messageType must be in the action
+ *                 allowlist.
+ *   3. peer     — source node must NOT be in the blocklist.
+ *
+ * `enforce(envelope, budget)` returns a discriminated result so
+ * callers can map directly to an MCP error string.
+ */
+import { FEDERATION_MESSAGE_TYPES, isFederationMessageType, } from "./envelope.js";
+/** Hard ceiling on hops — matches the spec's "≤ 3" rule. */
+export const DEFAULT_MAX_HOPS = 3;
+export class PolicyEngine {
+    allowed;
+    blocked;
+    maxHops;
+    constructor(cfg = {}) {
+        this.allowed = new Set(cfg.allowedMessageTypes ?? FEDERATION_MESSAGE_TYPES);
+        this.blocked = new Set((cfg.peerBlocklist ?? []).map((s) => String(s)));
+        this.maxHops = cfg.maxHops ?? DEFAULT_MAX_HOPS;
+    }
+    /** Runtime mutator — narrow the allowlist after construction. */
+    allowMessageType(t) {
+        this.allowed.add(t);
+    }
+    /** Runtime mutator — narrow the allowlist after construction. */
+    denyMessageType(t) {
+        this.allowed.delete(t);
+    }
+    /** Runtime mutator — block / unblock a peer at runtime. */
+    setBlocked(nodeId, blocked) {
+        if (blocked)
+            this.blocked.add(nodeId);
+        else
+            this.blocked.delete(nodeId);
+    }
+    /** Admit or reject an envelope given its budget context. */
+    enforce(envelope, budget) {
+        // 0. The budget object must exist — without it we can't enforce
+        // the maxHops ceiling.
+        if (!budget)
+            return { allowed: false, denialReason: "budget_missing" };
+        if (typeof budget.maxHops !== "number" || !Number.isFinite(budget.maxHops)) {
+            return { allowed: false, denialReason: "budget_invalid" };
+        }
+        // 1. Peer blocklist
+        if (this.blocked.has(envelope.sourceNodeId)) {
+            return { allowed: false, denialReason: "peer_blocked" };
+        }
+        // 2. Message type allowlist
+        if (!isFederationMessageType(envelope.messageType)) {
+            return { allowed: false, denialReason: "message_type_not_allowed" };
+        }
+        if (!this.allowed.has(envelope.messageType)) {
+            return { allowed: false, denialReason: "message_type_not_allowed" };
+        }
+        // 3. maxHops — current hopCount must be strictly LESS than the
+        // ceiling. A freshly-origin envelope has hopCount=0 so a
+        // maxHops=3 budget admits it.
+        const hopCount = envelope.hopCount ?? 0;
+        const effectiveCeiling = Math.min(budget.maxHops, this.maxHops);
+        if (hopCount >= effectiveCeiling) {
+            return { allowed: false, denialReason: "max_hops_exceeded" };
+        }
+        return { allowed: true };
+    }
+}
+//# sourceMappingURL=policy.js.map