@claude-flow/plugin-agent-federation 1.0.0-alpha.10

package/dist/application/policy-engine.js

@@ -0,0 +1,184 @@
+import { TrustLevel, isOperationAllowed } from '../domain/entities/trust-level.js';
+const DEFAULT_SECURITY_POLICY = {
+    maxMessageSizeBytes: 1_048_576,
+    maxMessagesPerMinute: 120,
+    allowedMessageTypes: [
+        'task-assignment', 'memory-query', 'memory-response',
+        'context-share', 'status-broadcast', 'heartbeat',
+        'trust-change', 'topology-change', 'agent-spawn',
+    ],
+    requirePiiScan: true,
+    requireAiDefenceScan: true,
+    minTrustLevelForWrite: TrustLevel.ATTESTED,
+    minTrustLevelForMemory: TrustLevel.TRUSTED,
+    minTrustLevelForSpawn: TrustLevel.PRIVILEGED,
+};
+const CLAIMS_FOR_MESSAGE_TYPE = {
+    'task-assignment': ['federation:write'],
+    'memory-query': ['federation:read', 'federation:memory'],
+    'memory-response': ['federation:read', 'federation:memory'],
+    'context-share': ['federation:write'],
+    'status-broadcast': ['federation:read'],
+    'trust-change': ['federation:admin'],
+    'topology-change': ['federation:admin'],
+    'agent-spawn': ['federation:spawn'],
+    'heartbeat': ['federation:connect'],
+    'challenge': ['federation:connect'],
+    'challenge-response': ['federation:connect'],
+    'handshake-init': ['federation:connect'],
+    'handshake-accept': ['federation:connect'],
+    'handshake-reject': ['federation:connect'],
+    'session-terminate': ['federation:connect'],
+    // ADR-101 Component C — federated claims operations.
+    // claim-event: broadcasts a ClaimDomainEvent (state mutation across peers),
+    // same authorization shape as task-assignment.
+    'claim-event': ['federation:write'],
+    // agent-handoff: transfers claim ownership to a remote agent. Requires
+    // both the write capability (state mutation) AND spawn-lifecycle authority
+    // (handoff is a sibling of agent-spawn — both reshape who owns work).
+    // Matches the consensus-gated security posture in ADR-101.
+    'agent-handoff': ['federation:write', 'federation:spawn'],
+};
+export class PolicyEngine {
+    deps;
+    securityPolicy;
+    piiPolicy;
+    rateLimitCounters;
+    constructor(deps, securityPolicy, piiPolicy) {
+        this.deps = deps;
+        this.securityPolicy = { ...DEFAULT_SECURITY_POLICY, ...securityPolicy };
+        this.piiPolicy = piiPolicy ?? {
+            defaultAction: 'redact',
+            overrides: {},
+            hashAlgorithm: 'sha256',
+            hashSalt: '',
+            redactionPlaceholder: '[REDACTED:{type}]',
+        };
+        this.rateLimitCounters = new Map();
+    }
+    evaluateMessage(messageType, trustLevel, messageSizeBytes, sourceNodeId) {
+        if (!this.securityPolicy.allowedMessageTypes.includes(messageType)) {
+            return {
+                allowed: false,
+                reason: `Message type '${messageType}' is not allowed by security policy`,
+                requiredClaims: [],
+                trustLevelSufficient: false,
+            };
+        }
+        if (messageSizeBytes > this.securityPolicy.maxMessageSizeBytes) {
+            return {
+                allowed: false,
+                reason: `Message size ${messageSizeBytes} exceeds maximum ${this.securityPolicy.maxMessageSizeBytes}`,
+                requiredClaims: [],
+                trustLevelSufficient: true,
+            };
+        }
+        if (!this.checkRateLimit(sourceNodeId)) {
+            return {
+                allowed: false,
+                reason: `Rate limit exceeded for node ${sourceNodeId}`,
+                requiredClaims: [],
+                trustLevelSufficient: true,
+            };
+        }
+        const requiredClaims = CLAIMS_FOR_MESSAGE_TYPE[messageType] ?? [];
+        const missingClaims = requiredClaims.filter(c => !this.deps.checkClaim(c));
+        if (missingClaims.length > 0) {
+            return {
+                allowed: false,
+                reason: `Missing required claims: ${missingClaims.join(', ')}`,
+                requiredClaims,
+                trustLevelSufficient: true,
+            };
+        }
+        const operationForType = this.getOperationForMessageType(messageType);
+        if (!isOperationAllowed(trustLevel, operationForType)) {
+            return {
+                allowed: false,
+                reason: `Trust level ${trustLevel} insufficient for operation '${operationForType}'`,
+                requiredClaims,
+                trustLevelSufficient: false,
+            };
+        }
+        return {
+            allowed: true,
+            reason: 'Policy check passed',
+            requiredClaims,
+            trustLevelSufficient: true,
+        };
+    }
+    evaluatePiiDetection(detection, trustLevel) {
+        const override = this.piiPolicy.overrides[detection.type];
+        if (override?.trustLevelOverride?.[trustLevel]) {
+            return override.trustLevelOverride[trustLevel];
+        }
+        if (override?.action) {
+            return override.action;
+        }
+        return this.piiPolicy.defaultAction;
+    }
+    evaluateTrustChange(currentLevel, proposedLevel) {
+        if (proposedLevel > currentLevel && proposedLevel === TrustLevel.PRIVILEGED) {
+            return {
+                allowed: true,
+                requiresHumanApproval: true,
+                reason: 'Elevation to PRIVILEGED requires institutional attestation and human approval',
+            };
+        }
+        if (proposedLevel > currentLevel) {
+            return {
+                allowed: true,
+                requiresHumanApproval: false,
+                reason: `Trust upgrade from ${currentLevel} to ${proposedLevel} allowed`,
+            };
+        }
+        if (proposedLevel < currentLevel) {
+            return {
+                allowed: true,
+                requiresHumanApproval: false,
+                reason: `Trust downgrade from ${currentLevel} to ${proposedLevel} allowed`,
+            };
+        }
+        return {
+            allowed: false,
+            requiresHumanApproval: false,
+            reason: 'No trust level change',
+        };
+    }
+    checkRateLimit(nodeId) {
+        const now = Date.now();
+        const counter = this.rateLimitCounters.get(nodeId);
+        if (!counter || now - counter.windowStart > 60_000) {
+            this.rateLimitCounters.set(nodeId, { count: 1, windowStart: now });
+            return true;
+        }
+        counter.count++;
+        return counter.count <= this.securityPolicy.maxMessagesPerMinute;
+    }
+    getOperationForMessageType(messageType) {
+        switch (messageType) {
+            case 'memory-query':
+            case 'memory-response':
+                return 'query-redacted';
+            case 'context-share':
+                return 'share-context';
+            case 'task-assignment':
+                return 'send';
+            case 'agent-spawn':
+                return 'remote-spawn';
+            case 'status-broadcast':
+                return 'status';
+            case 'heartbeat':
+            case 'challenge':
+            case 'challenge-response':
+            case 'handshake-init':
+            case 'handshake-accept':
+            case 'handshake-reject':
+            case 'session-terminate':
+                return 'ping';
+            default:
+                return 'send';
+        }
+    }
+}
+//# sourceMappingURL=policy-engine.js.map

package/dist/application/policy-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-engine.js","sourceRoot":"","sources":["../../src/application/policy-engine.ts"],"names":[],"mappings":"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"}

package/dist/application/spend-reporter.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Federation spend-reporting interface (ADR-097 Phase 3 upstream).
+ *
+ * The federation layer doesn't own model pricing — it can't know how much
+ * a downstream agent's work cost until the integrator tells it. So the
+ * coordinator exposes a `reportSpend()` method that callers invoke after
+ * their downstream completes, and that method fans out to:
+ *
+ *   1. The injected SpendReporter (if any) — typically wires to the
+ *      cost-tracker bus / `federation-spend` memory namespace
+ *   2. The injected FederationBreakerService (if any) — its in-memory
+ *      buffer becomes a transparent cache when the cost-tracker
+ *      subscriber lands
+ *
+ * Both deps are constructor-optional. A coordinator with neither still
+ * accepts reportSpend() calls (silent no-op) so callers don't need to
+ * branch on which integrations are wired.
+ *
+ * Event shape matches the consumer contract pinned by
+ * plugins/ruflo-cost-tracker/scripts/federation.mjs:
+ *
+ *   { peerId, taskId, tokensUsed, usdSpent, ts }
+ *
+ * Storage layout (consumer convention): namespace `federation-spend`,
+ * key `fed-spend-<peerId>-<ts>`. The interface is storage-agnostic; the
+ * default in-memory reporter included here is for tests + a reference
+ * implementation. Production integrators write a thin adapter that
+ * persists to ruflo memory / Redis / Datadog / their accounting system.
+ */
+/** A single per-send cost report from the integrator. */
+export interface FederationSpendEvent {
+    /** Peer this cost was incurred against. */
+    readonly peerId: string;
+    /** Optional task correlation key — not all callers will have one. */
+    readonly taskId?: string;
+    /** Tokens consumed (input + output). Negative values clamped to 0 by sink. */
+    readonly tokensUsed: number;
+    /** USD spent. Negative values clamped to 0 by sink. */
+    readonly usdSpent: number;
+    /** ISO 8601 timestamp. Caller-supplied for testability; auto-filled if omitted by reportSpend. */
+    readonly ts: string;
+    /** Whether the underlying send succeeded (drives breaker failure-ratio). */
+    readonly success: boolean;
+}
+/**
+ * Strategy interface the coordinator calls when reportSpend() fires.
+ * Integrators implement this to push the event to whatever backend they
+ * want — cost-tracker bus, Datadog, accounting DB, etc.
+ *
+ * Implementations must be tolerant: dropping or persisting later is
+ * acceptable, but throwing here will surface to the integrator's caller.
+ * Buffer and retry inside the implementation.
+ */
+export interface SpendReporter {
+    reportSpend(event: FederationSpendEvent): Promise<void>;
+}
+/**
+ * In-memory reporter for tests + a reference implementation. Production
+ * code should wire a real SpendReporter that persists to durable storage.
+ *
+ * Buffer is unbounded — fine for tests, NOT fine for long-running
+ * production. The cost-tracker consumer reads from durable storage, not
+ * from this buffer.
+ */
+export declare class InMemorySpendReporter implements SpendReporter {
+    private readonly buffer;
+    reportSpend(event: FederationSpendEvent): Promise<void>;
+    /** Snapshot of all reported events (test inspection). */
+    getEvents(): readonly FederationSpendEvent[];
+    /** Drop everything (test cleanup). */
+    clear(): void;
+}
+/**
+ * Minimal memory-backend interface (ADR-110). The integrator wires this
+ * to whatever store satisfies their durability/consistency needs:
+ * ruflo memory, Redis, DynamoDB, file-backed JSON, etc. The federation
+ * plugin doesn't import any specific memory client — pluggable by
+ * design.
+ */
+export interface MemoryStore {
+    /** Persist a value under (namespace, key). Optional TTL in seconds. */
+    store(args: {
+        namespace: string;
+        key: string;
+        value: string;
+        ttl?: number;
+    }): Promise<void>;
+}
+/** Configuration for `MemorySpendReporter`. See ADR-110. */
+export interface MemorySpendReporterConfig {
+    /** Memory store impl. Required. */
+    readonly memoryStore: MemoryStore;
+    /** Namespace per the cost-tracker consumer contract. Default: `federation-spend`. */
+    readonly namespace?: string;
+    /** Optional TTL in seconds. Default: 7 days. Cost-tracker rolling windows are 1h/24h/7d, so anything older is irrelevant. */
+    readonly ttlSeconds?: number;
+}
+/** Default namespace per cost-tracker's `plugins/ruflo-cost-tracker/scripts/federation.mjs`. */
+export declare const DEFAULT_FEDERATION_SPEND_NAMESPACE = "federation-spend";
+/** Default TTL: 7 days, matching cost-tracker's longest rolling window. */
+export declare const DEFAULT_FEDERATION_SPEND_TTL_SECONDS: number;
+/**
+ * Production reporter (ADR-110) that satisfies the cost-tracker
+ * consumer contract: writes to namespace `federation-spend`, key
+ * `fed-spend-<peerId>-<ts>`. The consumer
+ * (`plugins/ruflo-cost-tracker/scripts/federation.mjs`) `memory list`s
+ * the namespace, retrieves each key, and aggregates into rolling
+ * windows.
+ *
+ * Storage-agnostic: the integrator injects a `MemoryStore`
+ * implementation. Common wirings:
+ *
+ *   // ruflo memory MCP
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async (a) => mcpClient.call('memory_store', a),
+ *     },
+ *   });
+ *
+ *   // ruflo memory CLI shell-out
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async ({namespace, key, value, ttl}) => {
+ *         await execFile('npx', ['ruflo', 'memory', 'store',
+ *           '--namespace', namespace, '--key', key, '--value', value]);
+ *       },
+ *     },
+ *   });
+ *
+ * Errors from the memory backend BUBBLE UP — the reporter does not
+ * retry/swallow. Wrap with the integrator's preferred retry strategy
+ * if needed.
+ *
+ * Negative `tokensUsed` / `usdSpent` are persisted as-is. Clamping is
+ * the breaker's responsibility (see federation-breaker-service.ts);
+ * the audit/spend log is an honest mirror of what the integrator
+ * reported.
+ */
+export declare class MemorySpendReporter implements SpendReporter {
+    private readonly memoryStore;
+    private readonly namespace;
+    private readonly ttlSeconds;
+    constructor(config: MemorySpendReporterConfig);
+    reportSpend(event: FederationSpendEvent): Promise<void>;
+    /** Read configured namespace (for the doctor/debug surface). */
+    getNamespace(): string;
+    /** Read configured TTL in seconds. */
+    getTtlSeconds(): number;
+}
+//# sourceMappingURL=spend-reporter.d.ts.map

package/dist/application/spend-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-reporter.d.ts","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAE/C,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,yDAAyD;IACzD,SAAS,IAAI,SAAS,oBAAoB,EAAE;IAI5C,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6HAA6H;IAC7H,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gGAAgG;AAChG,eAAO,MAAM,kCAAkC,qBAAqB,CAAC;AAErE,2EAA2E;AAC3E,eAAO,MAAM,oCAAoC,QAAmB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,yBAAyB;IAMvC,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7D,gEAAgE;IAChE,YAAY,IAAI,MAAM;IAItB,sCAAsC;IACtC,aAAa,IAAI,MAAM;CAGxB"}

package/dist/application/spend-reporter.js

@@ -0,0 +1,128 @@
+/**
+ * Federation spend-reporting interface (ADR-097 Phase 3 upstream).
+ *
+ * The federation layer doesn't own model pricing — it can't know how much
+ * a downstream agent's work cost until the integrator tells it. So the
+ * coordinator exposes a `reportSpend()` method that callers invoke after
+ * their downstream completes, and that method fans out to:
+ *
+ *   1. The injected SpendReporter (if any) — typically wires to the
+ *      cost-tracker bus / `federation-spend` memory namespace
+ *   2. The injected FederationBreakerService (if any) — its in-memory
+ *      buffer becomes a transparent cache when the cost-tracker
+ *      subscriber lands
+ *
+ * Both deps are constructor-optional. A coordinator with neither still
+ * accepts reportSpend() calls (silent no-op) so callers don't need to
+ * branch on which integrations are wired.
+ *
+ * Event shape matches the consumer contract pinned by
+ * plugins/ruflo-cost-tracker/scripts/federation.mjs:
+ *
+ *   { peerId, taskId, tokensUsed, usdSpent, ts }
+ *
+ * Storage layout (consumer convention): namespace `federation-spend`,
+ * key `fed-spend-<peerId>-<ts>`. The interface is storage-agnostic; the
+ * default in-memory reporter included here is for tests + a reference
+ * implementation. Production integrators write a thin adapter that
+ * persists to ruflo memory / Redis / Datadog / their accounting system.
+ */
+/**
+ * In-memory reporter for tests + a reference implementation. Production
+ * code should wire a real SpendReporter that persists to durable storage.
+ *
+ * Buffer is unbounded — fine for tests, NOT fine for long-running
+ * production. The cost-tracker consumer reads from durable storage, not
+ * from this buffer.
+ */
+export class InMemorySpendReporter {
+    buffer = [];
+    async reportSpend(event) {
+        this.buffer.push(event);
+    }
+    /** Snapshot of all reported events (test inspection). */
+    getEvents() {
+        return [...this.buffer];
+    }
+    /** Drop everything (test cleanup). */
+    clear() {
+        this.buffer.length = 0;
+    }
+}
+/** Default namespace per cost-tracker's `plugins/ruflo-cost-tracker/scripts/federation.mjs`. */
+export const DEFAULT_FEDERATION_SPEND_NAMESPACE = 'federation-spend';
+/** Default TTL: 7 days, matching cost-tracker's longest rolling window. */
+export const DEFAULT_FEDERATION_SPEND_TTL_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Production reporter (ADR-110) that satisfies the cost-tracker
+ * consumer contract: writes to namespace `federation-spend`, key
+ * `fed-spend-<peerId>-<ts>`. The consumer
+ * (`plugins/ruflo-cost-tracker/scripts/federation.mjs`) `memory list`s
+ * the namespace, retrieves each key, and aggregates into rolling
+ * windows.
+ *
+ * Storage-agnostic: the integrator injects a `MemoryStore`
+ * implementation. Common wirings:
+ *
+ *   // ruflo memory MCP
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async (a) => mcpClient.call('memory_store', a),
+ *     },
+ *   });
+ *
+ *   // ruflo memory CLI shell-out
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async ({namespace, key, value, ttl}) => {
+ *         await execFile('npx', ['ruflo', 'memory', 'store',
+ *           '--namespace', namespace, '--key', key, '--value', value]);
+ *       },
+ *     },
+ *   });
+ *
+ * Errors from the memory backend BUBBLE UP — the reporter does not
+ * retry/swallow. Wrap with the integrator's preferred retry strategy
+ * if needed.
+ *
+ * Negative `tokensUsed` / `usdSpent` are persisted as-is. Clamping is
+ * the breaker's responsibility (see federation-breaker-service.ts);
+ * the audit/spend log is an honest mirror of what the integrator
+ * reported.
+ */
+export class MemorySpendReporter {
+    memoryStore;
+    namespace;
+    ttlSeconds;
+    constructor(config) {
+        this.memoryStore = config.memoryStore;
+        this.namespace = config.namespace ?? DEFAULT_FEDERATION_SPEND_NAMESPACE;
+        this.ttlSeconds = config.ttlSeconds ?? DEFAULT_FEDERATION_SPEND_TTL_SECONDS;
+    }
+    async reportSpend(event) {
+        const key = `fed-spend-${event.peerId}-${event.ts}`;
+        const value = JSON.stringify({
+            peerId: event.peerId,
+            taskId: event.taskId ?? null,
+            tokensUsed: event.tokensUsed,
+            usdSpent: event.usdSpent,
+            success: event.success,
+            ts: event.ts,
+        });
+        await this.memoryStore.store({
+            namespace: this.namespace,
+            key,
+            value,
+            ttl: this.ttlSeconds,
+        });
+    }
+    /** Read configured namespace (for the doctor/debug surface). */
+    getNamespace() {
+        return this.namespace;
+    }
+    /** Read configured TTL in seconds. */
+    getTtlSeconds() {
+        return this.ttlSeconds;
+    }
+}
+//# sourceMappingURL=spend-reporter.js.map

package/dist/application/spend-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-reporter.js","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+BH;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAqB;IACf,MAAM,GAA2B,EAAE,CAAC;IAErD,KAAK,CAAC,WAAW,CAAC,KAA2B;QAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,yDAAyD;IACzD,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,sCAAsC;IACtC,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF;AA6BD,gGAAgG;AAChG,MAAM,CAAC,MAAM,kCAAkC,GAAG,kBAAkB,CAAC;AAErE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,mBAAmB;IACb,WAAW,CAAc;IACzB,SAAS,CAAS;IAClB,UAAU,CAAS;IAEpC,YAAY,MAAiC;QAC3C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,kCAAkC,CAAC;QACxE,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,oCAAoC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAA2B;QAC3C,MAAM,GAAG,GAAG,aAAa,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;YAC3B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;YAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,EAAE,EAAE,KAAK,CAAC,EAAE;SACb,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG;YACH,KAAK;YACL,GAAG,EAAE,IAAI,CAAC,UAAU;SACrB,CAAC,CAAC;IACL,CAAC;IAED,gEAAgE;IAChE,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,sCAAsC;IACtC,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/application/trust-evaluator.d.ts

@@ -0,0 +1,42 @@
+import { TrustLevel } from '../domain/entities/trust-level.js';
+import { FederationNode } from '../domain/entities/federation-node.js';
+import { type SessionMetrics } from '../domain/entities/federation-session.js';
+export interface TrustScoreComponents {
+    readonly successRate: number;
+    readonly uptime: number;
+    readonly threatPenalty: number;
+    readonly dataIntegrityScore: number;
+}
+export interface TrustTransitionResult {
+    readonly previousLevel: TrustLevel;
+    readonly newLevel: TrustLevel;
+    readonly score: number;
+    readonly components: TrustScoreComponents;
+    readonly reason: string;
+    readonly requiresHumanApproval: boolean;
+}
+export type ImmediateDowngradeReason = 'repeated-threat-detection' | 'hmac-verification-failure' | 'session-hijack-attempt';
+export interface TrustEvaluatorDeps {
+    onTrustChange?: (nodeId: string, result: TrustTransitionResult) => void;
+}
+export interface ThreatWindow {
+    readonly detections: Date[];
+    readonly windowMs: number;
+    readonly threshold: number;
+}
+export declare class TrustEvaluator {
+    private readonly deps;
+    private readonly threatWindows;
+    constructor(deps?: TrustEvaluatorDeps);
+    computeScore(metrics: SessionMetrics, uptimeRatio: number): {
+        score: number;
+        components: TrustScoreComponents;
+    };
+    evaluateTransition(node: FederationNode, metrics: SessionMetrics, uptimeRatio: number, hasInstitutionalAttestation?: boolean): TrustTransitionResult | null;
+    downgrade(node: FederationNode, reason: ImmediateDowngradeReason): TrustTransitionResult;
+    recordThreatDetection(nodeId: string): boolean;
+    private checkUpgrade;
+    private checkDowngrade;
+    private computeThreatPenalty;
+}
+//# sourceMappingURL=trust-evaluator.d.ts.map

package/dist/application/trust-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-evaluator.d.ts","sourceRoot":"","sources":["../../src/application/trust-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA+B,MAAM,mCAAmC,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,wBAAwB,CAAC;AAE7B,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;gBAExC,IAAI,GAAE,kBAAuB;IAKzC,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,oBAAoB,CAAA;KAAE;IA8B/G,kBAAkB,CAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,2BAA2B,GAAE,OAAe,GAC3C,qBAAqB,GAAG,IAAI;IA4C/B,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,wBAAwB,GAAG,qBAAqB;IAmBxF,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAY9C,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,oBAAoB;CAK7B"}

package/dist/application/trust-evaluator.js

@@ -0,0 +1,132 @@
+import { TrustLevel, TRUST_TRANSITION_THRESHOLDS } from '../domain/entities/trust-level.js';
+const THREAT_WINDOW_CONFIG = {
+    detections: [],
+    windowMs: 3_600_000,
+    threshold: 2,
+};
+export class TrustEvaluator {
+    deps;
+    threatWindows;
+    constructor(deps = {}) {
+        this.deps = deps;
+        this.threatWindows = new Map();
+    }
+    computeScore(metrics, uptimeRatio) {
+        const totalAttempted = metrics.messagesSent + metrics.messagesReceived;
+        const successRate = totalAttempted > 0
+            ? (totalAttempted - metrics.hmacFailures) / totalAttempted
+            : 0;
+        const uptime = Math.max(0, Math.min(1, uptimeRatio));
+        const threatPenalty = this.computeThreatPenalty(metrics.threatDetections, totalAttempted);
+        const dataIntegrityScore = totalAttempted > 0
+            ? 1 - (metrics.hmacFailures / totalAttempted)
+            : 1;
+        const score = 0.4 * successRate +
+            0.2 * uptime +
+            0.2 * (1 - threatPenalty) +
+            0.2 * dataIntegrityScore;
+        const components = {
+            successRate,
+            uptime,
+            threatPenalty,
+            dataIntegrityScore,
+        };
+        return { score: Math.max(0, Math.min(1, score)), components };
+    }
+    evaluateTransition(node, metrics, uptimeRatio, hasInstitutionalAttestation = false) {
+        const { score, components } = this.computeScore(metrics, uptimeRatio);
+        const currentLevel = node.trustLevel;
+        node.updateTrustScore(score);
+        const upgrade = this.checkUpgrade(currentLevel, score, metrics.totalInteractions, hasInstitutionalAttestation);
+        if (upgrade !== null) {
+            const result = {
+                previousLevel: currentLevel,
+                newLevel: upgrade,
+                score,
+                components,
+                reason: `Score ${score.toFixed(3)} meets upgrade threshold for level ${upgrade}`,
+                requiresHumanApproval: upgrade === TrustLevel.PRIVILEGED,
+            };
+            if (!result.requiresHumanApproval) {
+                node.updateTrustLevel(upgrade);
+            }
+            this.deps.onTrustChange?.(node.nodeId, result);
+            return result;
+        }
+        const downgrade = this.checkDowngrade(currentLevel, score);
+        if (downgrade !== null) {
+            const result = {
+                previousLevel: currentLevel,
+                newLevel: downgrade,
+                score,
+                components,
+                reason: `Score ${score.toFixed(3)} dropped below downgrade threshold for level ${currentLevel}`,
+                requiresHumanApproval: false,
+            };
+            node.updateTrustLevel(downgrade);
+            this.deps.onTrustChange?.(node.nodeId, result);
+            return result;
+        }
+        return null;
+    }
+    downgrade(node, reason) {
+        const previousLevel = node.trustLevel;
+        node.updateTrustLevel(TrustLevel.UNTRUSTED);
+        node.updateTrustScore(0);
+        const result = {
+            previousLevel,
+            newLevel: TrustLevel.UNTRUSTED,
+            score: 0,
+            components: { successRate: 0, uptime: 0, threatPenalty: 1, dataIntegrityScore: 0 },
+            reason: `Immediate downgrade: ${reason}`,
+            requiresHumanApproval: false,
+        };
+        this.deps.onTrustChange?.(node.nodeId, result);
+        return result;
+    }
+    recordThreatDetection(nodeId) {
+        const now = new Date();
+        const detections = this.threatWindows.get(nodeId) ?? [];
+        detections.push(now);
+        const windowStart = now.getTime() - THREAT_WINDOW_CONFIG.windowMs;
+        const recentDetections = detections.filter(d => d.getTime() > windowStart);
+        this.threatWindows.set(nodeId, recentDetections);
+        return recentDetections.length >= THREAT_WINDOW_CONFIG.threshold;
+    }
+    checkUpgrade(currentLevel, score, totalInteractions, hasInstitutionalAttestation) {
+        if (currentLevel >= TrustLevel.PRIVILEGED)
+            return null;
+        const nextLevel = currentLevel + 1;
+        const transitionKey = `${currentLevel}->${nextLevel}`;
+        const threshold = TRUST_TRANSITION_THRESHOLDS[transitionKey];
+        if (!threshold)
+            return null;
+        if (score < threshold.upgradeScore)
+            return null;
+        if (totalInteractions < threshold.minInteractions)
+            return null;
+        if (nextLevel === TrustLevel.PRIVILEGED && !hasInstitutionalAttestation) {
+            return null;
+        }
+        return nextLevel;
+    }
+    checkDowngrade(currentLevel, score) {
+        if (currentLevel <= TrustLevel.UNTRUSTED)
+            return null;
+        const transitionKey = `${currentLevel - 1}->${currentLevel}`;
+        const threshold = TRUST_TRANSITION_THRESHOLDS[transitionKey];
+        if (!threshold)
+            return null;
+        if (score < threshold.downgradeScore) {
+            return (currentLevel - 1);
+        }
+        return null;
+    }
+    computeThreatPenalty(threatCount, totalMessages) {
+        if (totalMessages === 0)
+            return 0;
+        const ratio = threatCount / totalMessages;
+        return Math.min(1, ratio * 10);
+    }
+}
+//# sourceMappingURL=trust-evaluator.js.map