@muxoai/sdk 1.2.3 → 1.4.2

package/dist/providers/microsoft-governance.js

@@ -0,0 +1,1062 @@
+import crypto from "node:crypto";
+import { AgentIdentity, AuditLogger, ContextPoisoningDetector, ExecutionRing, FacetRegistry, KillSwitch, McpSecurityScanner, PolicyEngine, RingEnforcer, TrustManager, extractK8sFacets, extractProtocolFacets, extractSqlFacets, } from "../../vendor/microsoft-governance/dist/index.js";
+import { describePolicyInPlainEnglish, evaluateParameterPolicyRules, formatHumanFriendlyExplanation, } from "../policy.js";
+const SDK_VERSION = "5.0.0";
+const POLICY_ID = "muxo-microsoft-agent-governance-v5";
+export const RING_LABELS = {
+    [ExecutionRing.Ring0]: "Ring 0 (Kernel / Destructive & Root Boundary)",
+    [ExecutionRing.Ring1]: "Ring 1 (Supervisor / Provisioning, Financial & Admin)",
+    [ExecutionRing.Ring2]: "Ring 2 (Standard Agent / Governed Write)",
+    [ExecutionRing.Ring3]: "Ring 3 (Unprivileged Sandbox / Read-Only)",
+};
+function requiredRingForRisk(riskLevel) {
+    switch (riskLevel) {
+        case "destructive":
+            return ExecutionRing.Ring0;
+        case "admin":
+        case "financial":
+        case "provisioning":
+            return ExecutionRing.Ring1;
+        case "write":
+            return ExecutionRing.Ring2;
+        case "read":
+        default:
+            return ExecutionRing.Ring3;
+    }
+}
+// PKCS#8 DER prefix for a 32-byte Ed25519 private key seed (OID 1.3.101.112)
+const ED25519_PKCS8_PREFIX = Buffer.from([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70,
+    0x04, 0x22, 0x04, 0x20,
+]);
+function deriveDeterministicIdentity(seedMaterial, agentId, capabilities, opts) {
+    const rawSeed = crypto
+        .createHmac("sha256", seedMaterial)
+        .update(`muxo-ed25519-agent-identity:${agentId}`)
+        .digest();
+    const pkcs8Der = Buffer.concat([ED25519_PKCS8_PREFIX, rawSeed]);
+    const privateKeyObj = crypto.createPrivateKey({
+        key: pkcs8Der,
+        format: "der",
+        type: "pkcs8",
+    });
+    const publicKeyObj = crypto.createPublicKey(privateKeyObj);
+    const pubDer = Buffer.from(publicKeyObj.export({ type: "spki", format: "der" }));
+    const privDer = Buffer.from(privateKeyObj.export({ type: "pkcs8", format: "der" }));
+    const fingerprint = crypto
+        .createHash("sha256")
+        .update(pubDer)
+        .digest("hex")
+        .slice(0, 16);
+    const did = `did:agentmesh:${agentId}:${fingerprint}`;
+    return AgentIdentity.fromJSON({
+        did,
+        publicKey: pubDer.toString("base64"),
+        privateKey: privDer.toString("base64"),
+        capabilities,
+        name: opts.name || agentId,
+        organization: opts.organization || "muxo.ai",
+        createdAt: opts.createdAt || new Date().toISOString(),
+    });
+}
+export class MicrosoftGovernanceAdapter {
+    scanner;
+    contextPoisoningDetector;
+    facetRegistry;
+    trustManager;
+    killSwitch;
+    activeKillSwitches = new Map();
+    seedMaterial;
+    auditLoggers = new Map();
+    identities = new Map();
+    defaultIdentity;
+    constructor(seed) {
+        this.scanner = new McpSecurityScanner();
+        this.contextPoisoningDetector = new ContextPoisoningDetector({
+            maxContextSizeBytes: 100_000,
+            maxEntriesPerSession: 250,
+            entropyThreshold: 5.5,
+            similarityThreshold: 0.92,
+            enableIsolation: true,
+        });
+        this.facetRegistry = new FacetRegistry();
+        this.facetRegistry.register("sql", extractSqlFacets);
+        this.facetRegistry.register("k8s", extractK8sFacets);
+        this.facetRegistry.register("infra", (sub) => ({
+            provider: String(sub.provider ?? "").toLowerCase(),
+            service: String(sub.service ?? "").toLowerCase(),
+            action: String(sub.action ?? "read").toLowerCase(),
+            destructive: Boolean(sub.destructive),
+        }));
+        this.trustManager = new TrustManager({
+            initialScore: 0.75,
+            decayFactor: 0.98,
+        });
+        this.killSwitch = new KillSwitch({
+            enabled: true,
+            defaultSubstituteAgentId: "muxo-safe-mode-guardian",
+        });
+        this.seedMaterial = Buffer.isBuffer(seed)
+            ? seed
+            : Buffer.from(String(seed ||
+                process.env.MUXO_VAULT_SECRET ||
+                process.env.COMPOSIO_API_KEY ||
+                "muxo-governance-ed25519-seed-v5"), "utf8");
+        this.defaultIdentity = deriveDeterministicIdentity(this.seedMaterial, "muxo-control-plane", [
+            "instant.*",
+            "app.*",
+            "resource.*",
+            "mcp.execute",
+            "governance.verify",
+        ], {
+            name: "Muxo Control Plane Agent",
+            organization: "muxo.ai",
+        });
+    }
+    /**
+     * Returns (or deterministically derives) the Ed25519 AgentIdentity (`did:agentmesh:...`) for a workspace.
+     */
+    getWorkspaceIdentity(workspace) {
+        let identity = this.identities.get(workspace.id);
+        if (!identity) {
+            identity = deriveDeterministicIdentity(this.seedMaterial, `muxo-workspace-${workspace.slug || workspace.id}`, [
+                "instant.*",
+                "app.*",
+                "resource.*",
+                "mcp.execute",
+                "governance.verify",
+            ], {
+                name: `${workspace.name} Agent Boundary`,
+                organization: workspace.id,
+                createdAt: workspace.createdAt,
+            });
+            this.identities.set(workspace.id, identity);
+        }
+        return identity;
+    }
+    /**
+     * Returns (or lazily initializes) the SHA-256 hash-chained AuditLogger for a workspace.
+     */
+    getWorkspaceAuditLogger(workspaceId) {
+        let logger = this.auditLoggers.get(workspaceId);
+        if (!logger) {
+            logger = new AuditLogger();
+            this.auditLoggers.set(workspaceId, logger);
+        }
+        return logger;
+    }
+    /**
+     * Scans memory or prompt context for OWASP ASI-06 Context Poisoning (prompt injection,
+     * roleplay overrides, delimiter injection, high-entropy exfiltration payloads, and session isolation).
+     */
+    scanMemoryContent(params) {
+        const safeAgentKey = params.workspaceId.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const safeSessionKey = (params.sessionId || "default").replace(/[^a-zA-Z0-9_-]/g, "_");
+        const entryId = params.entryId || `mem_${crypto.randomBytes(6).toString("hex")}`;
+        const entry = {
+            id: entryId,
+            entryId,
+            agentId: safeAgentKey,
+            sessionId: safeSessionKey,
+            role: params.role || "user",
+            content: String(params.content || ""),
+            timestamp: new Date().toISOString(),
+        };
+        const findings = this.contextPoisoningDetector.scanEntry(entry);
+        // Augment with credential/secret exfiltration detection in memory content
+        if (/(cat|curl|wget)\s+.*(\/etc\/passwd|\.env|id_rsa|AWS_SECRET_ACCESS_KEY)/i.test(entry.content) ||
+            /send\s+(all\s+)?(api\s+keys|secrets|tokens|credentials)\s+to\s+https?:\/\//i.test(entry.content)) {
+            findings.push({
+                entryId: entry.id,
+                patternId: "MEMORY_EXFILTRATION_DIRECTIVE",
+                patternName: "Persistent Memory Credential Exfiltration Directive",
+                severity: "critical",
+                description: "Memory payload attempts to persist credential or file exfiltration instructions across agent runs",
+                matchedText: entry.content.slice(0, 100),
+                timestamp: Date.now(),
+            });
+        }
+        const hasCritical = findings.some((f) => f.severity === "critical");
+        const hasHigh = findings.some((f) => f.severity === "high");
+        const hasMedium = findings.some((f) => f.severity === "medium");
+        const riskLevel = hasCritical
+            ? "critical"
+            : hasHigh
+                ? "high"
+                : hasMedium
+                    ? "medium"
+                    : findings.length > 0
+                        ? "low"
+                        : "none";
+        const safe = !hasCritical && !hasHigh;
+        if (params.recordInDetector !== false && safe) {
+            try {
+                this.contextPoisoningDetector.addEntry(entry);
+            }
+            catch {
+                // Ignore session capacity overflow in long-running processes
+            }
+        }
+        const integrity = this.contextPoisoningDetector.verifyIntegrity(safeAgentKey, safeSessionKey);
+        const integrityValid = typeof integrity === "boolean" ? integrity : Boolean(integrity?.valid ?? true);
+        return {
+            safe,
+            riskLevel,
+            findingsCount: findings.length,
+            findings: findings.map((f) => ({
+                patternId: String(f.patternId || ""),
+                patternName: String(f.patternName || ""),
+                severity: String(f.severity || ""),
+                description: String(f.description || ""),
+            })),
+            integrityValid,
+        };
+    }
+    getContextPoisoningReport(workspaceId, sessionId = "default") {
+        const safeAgentKey = workspaceId.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const safeSessionKey = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+        return this.contextPoisoningDetector.scan(safeAgentKey, safeSessionKey);
+    }
+    /**
+     * Extracts structured SQL, Kubernetes, and Infrastructure protocol facets from tool input.
+     */
+    extractActionFacets(tool, input) {
+        const rawContext = {};
+        // Detect SQL payload in input
+        const candidateSql = typeof input.sql === "string"
+            ? input.sql
+            : typeof input.statement === "string"
+                ? input.statement
+                : typeof input.query === "string" &&
+                    (tool.slug.includes("sql") ||
+                        tool.slug.includes("postgres") ||
+                        tool.slug.includes("neon") ||
+                        tool.slug.includes("turso") ||
+                        tool.slug.includes("supabase") ||
+                        tool.slug.includes("db") ||
+                        /^\s*(SELECT|INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|WITH)\b/i.test(input.query))
+                    ? input.query
+                    : null;
+        if (candidateSql) {
+            rawContext.sql = { query: candidateSql };
+        }
+        // Detect Kubernetes payload in input
+        const candidateK8sPath = typeof input.k8s_path === "string"
+            ? input.k8s_path
+            : typeof input.path === "string" &&
+                (input.path.startsWith("/api/v1/") ||
+                    input.path.startsWith("/apis/"))
+                ? input.path
+                : null;
+        if (candidateK8sPath) {
+            rawContext.k8s = {
+                method: typeof input.method === "string" ? input.method : "GET",
+                path: candidateK8sPath,
+            };
+        }
+        else if (input.k8s &&
+            typeof input.k8s === "object" &&
+            !Array.isArray(input.k8s)) {
+            rawContext.k8s = input.k8s;
+        }
+        // Detect Infrastructure / Resource provisioning facets
+        if (tool.lane === "stripe_projects" ||
+            tool.slug.startsWith("resource.") ||
+            tool.riskLevel === "provisioning" ||
+            tool.riskLevel === "destructive") {
+            rawContext.infra = {
+                provider: tool.providerSlug,
+                service: tool.upstreamSlug,
+                action: tool.riskLevel,
+                destructive: tool.riskLevel === "destructive" ||
+                    tool.slug.includes("delete") ||
+                    tool.slug.includes("destroy"),
+            };
+        }
+        const extracted = extractProtocolFacets(rawContext, this.facetRegistry);
+        const result = {};
+        if (extracted.sql) {
+            const sqlVerb = String(extracted.sql.verb || "UNKNOWN").toUpperCase();
+            const isDestructiveSql = sqlVerb === "DROP" ||
+                sqlVerb === "TRUNCATE" ||
+                (sqlVerb === "UNKNOWN" && Boolean(candidateSql?.includes(";"))) ||
+                (sqlVerb === "DELETE" &&
+                    Boolean(candidateSql) &&
+                    !/\bWHERE\b/i.test(candidateSql || ""));
+            result.sql = {
+                verb: sqlVerb,
+                target: String(extracted.sql.target || ""),
+                tables: String(extracted.sql.tables || ""),
+                functions: String(extracted.sql.functions || ""),
+                destructive: isDestructiveSql,
+            };
+        }
+        if (extracted.k8s) {
+            result.k8s = {
+                verb: String(extracted.k8s.verb || ""),
+                resource: String(extracted.k8s.resource || ""),
+                namespace: String(extracted.k8s.namespace || ""),
+                name: String(extracted.k8s.name || ""),
+                subresource: String(extracted.k8s.subresource || ""),
+            };
+        }
+        if (extracted.infra) {
+            result.infra = {
+                provider: String(extracted.infra.provider || tool.providerSlug),
+                service: String(extracted.infra.service || tool.upstreamSlug),
+                action: String(extracted.infra.action || tool.riskLevel),
+                destructive: Boolean(extracted.infra.destructive),
+            };
+        }
+        return result;
+    }
+    /**
+     * Evaluates hardware-style privilege rings (Ring 0..Ring 3) via Microsoft RingEnforcer.
+     */
+    evaluateRingEnforcement(workspace, tool, ownerApproved) {
+        const requiredRing = requiredRingForRisk(tool.riskLevel);
+        const policy = workspace.policy;
+        const requiresApproval = policy.mode === "enforce" &&
+            (policy.requireApprovalFor || []).includes(tool.riskLevel);
+        const agentRing = ownerApproved
+            ? ExecutionRing.Ring0
+            : policy.executionRing !== undefined
+                ? policy.executionRing
+                : requiresApproval
+                    ? ExecutionRing.Ring2
+                    : requiredRing;
+        const enforcer = new RingEnforcer({
+            agentRing,
+            defaultRing: ExecutionRing.Ring3,
+            actionRings: {
+                "read:*": ExecutionRing.Ring3,
+                "write:*": ExecutionRing.Ring2,
+                "admin:*": ExecutionRing.Ring1,
+                "financial:*": ExecutionRing.Ring1,
+                "provisioning:*": ExecutionRing.Ring1,
+                "destructive:*": ExecutionRing.Ring0,
+            },
+        });
+        const actionKey = `${tool.riskLevel}:${tool.slug}`;
+        const allowed = enforcer.canExecute(actionKey);
+        return {
+            agentRing,
+            requiredRing,
+            allowed,
+            ringLabel: RING_LABELS[requiredRing] || `Ring ${requiredRing}`,
+        };
+    }
+    /**
+     * Records an agent execution outcome in the Bayesian TrustManager and returns the updated TrustScore.
+     */
+    recordAgentOutcome(workspaceId, succeeded, weight = 0.05) {
+        if (succeeded) {
+            this.trustManager.recordSuccess(workspaceId, weight);
+        }
+        else {
+            this.trustManager.recordFailure(workspaceId, weight * 2);
+        }
+        return this.trustManager.getTrustScore(workspaceId);
+    }
+    /**
+     * Returns the current Bayesian TrustScore for a workspace agent boundary.
+     */
+    getWorkspaceTrustScore(workspaceId) {
+        const score = this.trustManager.getTrustScore(workspaceId);
+        return {
+            overall: Number(score.overall.toFixed(4)),
+            tier: score.tier,
+            reliability: Number(score.dimensions.reliability.toFixed(4)),
+            consistency: Number(score.dimensions.consistency.toFixed(4)),
+        };
+    }
+    /**
+     * Activates the emergency KillSwitch for a workspace agent boundary.
+     */
+    async activateKillSwitch(workspaceId, reason, action = "quarantine") {
+        const result = await this.killSwitch.kill(workspaceId, {
+            action,
+            reason: reason || "Emergency kill-switch activated by workspace operator",
+        });
+        this.activeKillSwitches.set(workspaceId, result);
+        this.trustManager.recordFailure(workspaceId, 0.25);
+        return result;
+    }
+    /**
+     * Resumes a workspace agent boundary after a KillSwitch quarantine/suspension.
+     */
+    resumeKillSwitch(workspaceId) {
+        const existed = this.activeKillSwitches.delete(workspaceId);
+        return {
+            resumed: existed,
+            workspaceId,
+            resumedAt: new Date().toISOString(),
+        };
+    }
+    isKillSwitchActive(workspaceId) {
+        return this.activeKillSwitches.get(workspaceId) || null;
+    }
+    /**
+     * Compiles the workspace's GovernancePolicy into a declarative Microsoft PolicyEngine instance.
+     */
+    createPolicyEngine(policy) {
+        const engine = new PolicyEngine();
+        const rules = [];
+        if (policy.killSwitchActive) {
+            rules.push({
+                name: "deny-kill-switch-active",
+                ruleAction: "deny",
+                priority: 200,
+                condition: {
+                    workspace_active: true,
+                },
+            });
+        }
+        for (const blockedSlug of policy.blockedToolSlugs || []) {
+            const normalized = blockedSlug.trim();
+            if (!normalized)
+                continue;
+            rules.push({
+                name: `deny-blocked-tool-${normalized.replace(/[^a-zA-Z0-9_-]/g, "_")}`,
+                ruleAction: "deny",
+                priority: 100,
+                condition: {
+                    tool_slug: normalized,
+                },
+            });
+        }
+        if (policy.mode === "enforce" && policy.blockDestructiveSql !== false) {
+            rules.push({
+                name: "deny-multi-statement-sql-injection",
+                ruleAction: "deny",
+                priority: 96,
+                condition: {
+                    "sql.verb": "UNKNOWN",
+                    "sql.destructive": true,
+                },
+            });
+            rules.push({
+                name: "require-approval-destructive-sql-drop",
+                ruleAction: "require_approval",
+                priority: 94,
+                condition: {
+                    "sql.verb": "DROP",
+                    owner_approved: false,
+                },
+            });
+            rules.push({
+                name: "require-approval-destructive-sql-truncate",
+                ruleAction: "require_approval",
+                priority: 94,
+                condition: {
+                    "sql.verb": "TRUNCATE",
+                    owner_approved: false,
+                },
+            });
+            rules.push({
+                name: "deny-k8s-delete-kube-system",
+                ruleAction: "deny",
+                priority: 95,
+                condition: {
+                    "k8s.verb": "delete",
+                    "k8s.namespace": "kube-system",
+                },
+            });
+        }
+        if (policy.mode === "enforce") {
+            for (const risk of policy.requireApprovalFor || []) {
+                rules.push({
+                    name: `require-owner-approval-for-${risk}`,
+                    ruleAction: "require_approval",
+                    priority: 80,
+                    condition: {
+                        risk_level: risk,
+                        owner_approved: false,
+                    },
+                });
+            }
+        }
+        rules.push({
+            name: "allow-governed-action",
+            ruleAction: "allow",
+            priority: 10,
+            condition: {
+                workspace_active: true,
+            },
+        });
+        engine.loadJson(JSON.stringify({
+            apiVersion: "governance.toolkit/v1",
+            name: POLICY_ID,
+            version: "5.0.0",
+            description: "Muxo Unified Execution Boundary Policy",
+            scope: "tenant",
+            default_action: "deny",
+            rules,
+        }));
+        return engine;
+    }
+    /**
+     * Runs the full Microsoft Agent Governance pipeline:
+     * Agent ──► KillSwitch ──► McpSecurityScanner & ContextPoisoningDetector (ASI-06) ──► ProtocolFacets (SQL/K8s/Infra) ──► RingEnforcer ──► PolicyEngine ──► TrustManager ──► AgentIdentity (Ed25519 DID) ──► AuditLogger ──► DecisionRecord
+     */
+    evaluateAction(params) {
+        const { workspace, actorId, tool, input, reason, stage } = params;
+        const ownerApproved = Boolean(params.ownerApproved);
+        const decidedAt = new Date().toISOString();
+        // 1. McpSecurityScanner + ContextPoisoningDetector (OWASP ASI-06): inspect tool definition + input arguments
+        const serializedInput = JSON.stringify(input || {});
+        const scanResult = this.scanner.scan({
+            name: tool.slug,
+            description: `${tool.description}\nReason: ${reason}\nArgs: ${serializedInput}`,
+            parameters: tool.inputSchema,
+        });
+        const contextPoisoning = this.scanMemoryContent({
+            workspaceId: workspace.id,
+            sessionId: stage,
+            role: "user",
+            content: `${reason}\n${serializedInput}`,
+            recordInDetector: false,
+        });
+        const extraFindings = [
+            ...(scanResult.threats || []).map((t) => ({
+                category: String(t.type || "mcp_scan"),
+                severity: String(t.severity || "medium"),
+                description: String(t.description || "Security scanner finding"),
+            })),
+            ...contextPoisoning.findings.map((f) => ({
+                category: `asi06_${f.patternId.toLowerCase()}`,
+                severity: f.severity,
+                description: `${f.patternName}: ${f.description}`,
+            })),
+        ];
+        // Additional argument-level prompt-injection / secret-exfiltration heuristics
+        const suspiciousPatterns = [
+            {
+                regex: /ignore\s+(all\s+)?previous\s+instructions/i,
+                category: "prompt_injection",
+                severity: "high",
+                description: "Detected prompt injection override phrase in tool arguments or reason",
+            },
+            {
+                regex: /(cat|curl|wget)\s+.*(\/etc\/passwd|\.env|id_rsa|AWS_SECRET_ACCESS_KEY)/i,
+                category: "credential_exfiltration",
+                severity: "high",
+                description: "Detected credential or sensitive file exfiltration pattern in arguments",
+            },
+        ];
+        for (const pat of suspiciousPatterns) {
+            if (pat.regex.test(serializedInput) || pat.regex.test(reason)) {
+                extraFindings.push({
+                    category: pat.category,
+                    severity: pat.severity,
+                    description: pat.description,
+                });
+            }
+        }
+        const highSeverityFinding = extraFindings.some((f) => f.severity === "high" || f.severity === "critical");
+        // 2. Protocol Facets Extraction (SQL, Kubernetes, Infrastructure)
+        const protocolFacets = this.extractActionFacets(tool, input);
+        // 3. PolicyEngine + KillSwitch + Parameter Guardrail evaluation
+        const policy = workspace.policy;
+        const paramRuleCheck = evaluateParameterPolicyRules({
+            policy,
+            toolSlug: tool.slug,
+            input,
+        });
+        if (paramRuleCheck.violated && paramRuleCheck.reason) {
+            extraFindings.push({
+                category: "parameter_policy_rule",
+                severity: paramRuleCheck.action === "block" ? "high" : "medium",
+                description: paramRuleCheck.reason,
+            });
+        }
+        const effectiveApproved = ownerApproved ||
+            Boolean(paramRuleCheck.explicitAllow && paramRuleCheck.action === "auto_approve");
+        // 4. Hardware-style Execution Ring Enforcement (Ring 0..Ring 3)
+        const ringEnforcement = this.evaluateRingEnforcement(workspace, tool, effectiveApproved);
+        const activeKill = this.isKillSwitchActive(workspace.id);
+        const killSwitchActive = Boolean(activeKill || policy.killSwitchActive);
+        const killSwitchReason = activeKill?.reason || policy.killSwitchReason || null;
+        const policyEngine = this.createPolicyEngine(policy);
+        const identity = this.getWorkspaceIdentity(workspace);
+        const policyDecision = policyEngine.evaluatePolicy(identity.did, {
+            tool_slug: tool.slug,
+            risk_level: tool.riskLevel,
+            lane: tool.lane,
+            stage,
+            owner_approved: effectiveApproved,
+            workspace_active: true,
+            ...(protocolFacets.sql ? { sql: protocolFacets.sql } : {}),
+            ...(protocolFacets.k8s ? { k8s: protocolFacets.k8s } : {}),
+            ...(protocolFacets.infra ? { infra: protocolFacets.infra } : {}),
+        });
+        let finalDecision = policyDecision.action === "deny"
+            ? "deny"
+            : policyDecision.action === "require_approval"
+                ? "require_approval"
+                : "allow";
+        let matchedRule = paramRuleCheck.explicitAllow &&
+            paramRuleCheck.action === "auto_approve" &&
+            finalDecision === "allow"
+            ? paramRuleCheck.matchedRule?.id || "auto-approve-parameter-policy-rule"
+            : policyDecision.matchedRule ?? null;
+        // Enforce KillSwitch, blocked tools, parameter rules, high-severity scanner/context-poisoning findings, or Ring breach
+        if (killSwitchActive) {
+            finalDecision = "deny";
+            matchedRule = "kill-switch-emergency-quarantine";
+        }
+        else if ((policy.blockedToolSlugs || []).includes(tool.slug)) {
+            finalDecision = "deny";
+            matchedRule = matchedRule || `deny-blocked-tool-${tool.slug}`;
+        }
+        else if (paramRuleCheck.violated &&
+            paramRuleCheck.action === "block" &&
+            policy.mode === "enforce") {
+            finalDecision = "deny";
+            matchedRule = paramRuleCheck.matchedRule?.id || "deny-parameter-policy-rule";
+        }
+        else if (paramRuleCheck.violated &&
+            paramRuleCheck.action === "require_approval" &&
+            !ownerApproved &&
+            policy.mode === "enforce") {
+            finalDecision = "require_approval";
+            matchedRule = paramRuleCheck.matchedRule?.id || "approval-parameter-policy-rule";
+        }
+        else if (highSeverityFinding && policy.mode === "enforce") {
+            finalDecision = "deny";
+            matchedRule = "mcp-security-scanner-high-severity";
+            this.trustManager.recordFailure(workspace.id, 0.1);
+        }
+        else if (!ringEnforcement.allowed && finalDecision === "allow" && policy.mode === "enforce") {
+            finalDecision = "require_approval";
+            matchedRule = `ring-enforcer-requires-ring-${ringEnforcement.requiredRing}`;
+        }
+        const trustScore = this.getWorkspaceTrustScore(workspace.id);
+        // 5. AuditLogger: append tamper-evident SHA-256 hash-chained log entry
+        const auditLogger = this.getWorkspaceAuditLogger(workspace.id);
+        const auditDecision = finalDecision === "deny" ? "deny" : "allow";
+        const auditEntry = auditLogger.log({
+            agentId: identity.did,
+            action: `${stage}.${tool.riskLevel}:${tool.slug}`,
+            decision: auditDecision,
+            skillAuditMetadata: {
+                skillName: tool.slug,
+                skillOrigin: tool.lane,
+                provenanceSourceTrust: trustScore.tier === "Verified" || trustScore.tier === "Trusted"
+                    ? "trusted"
+                    : undefined,
+            },
+        });
+        const chainVerified = auditLogger.verify();
+        // 6. AgentIdentity (Ed25519 DID): cryptographically sign the decision record
+        const bindingHash = crypto
+            .createHash("sha256")
+            .update(JSON.stringify({
+            workspaceId: workspace.id,
+            actorId,
+            toolSlug: tool.slug,
+            riskLevel: tool.riskLevel,
+            stage,
+            input,
+            finalDecision,
+            auditHash: auditEntry.hash,
+            decidedAt,
+        }))
+            .digest("hex");
+        const signaturePayload = [
+            POLICY_ID,
+            identity.did,
+            workspace.id,
+            actorId,
+            tool.slug,
+            tool.riskLevel,
+            finalDecision,
+            auditEntry.hash,
+            auditEntry.previousHash,
+            bindingHash,
+            decidedAt,
+        ].join("|");
+        const sigBytes = identity.sign(Buffer.from(signaturePayload, "utf8"));
+        const ed25519Signature = Buffer.from(sigBytes).toString("hex");
+        const publicKeyHex = Buffer.from(identity.publicKey).toString("hex");
+        const verdict = finalDecision === "require_approval" ? "escalate" : finalDecision;
+        const decisionReason = finalDecision === "deny"
+            ? killSwitchActive
+                ? `Blocked by Emergency KillSwitch: ${killSwitchReason || "Workspace agent boundary is quarantined"}`
+                : paramRuleCheck.violated && paramRuleCheck.reason
+                    ? paramRuleCheck.reason
+                    : highSeverityFinding
+                        ? `Blocked by McpSecurityScanner / ContextPoisoningDetector: ${extraFindings.map((f) => f.description).join("; ")}`
+                        : `Denied by policy rule ${matchedRule || "default"}`
+            : finalDecision === "require_approval"
+                ? paramRuleCheck.violated && paramRuleCheck.reason
+                    ? paramRuleCheck.reason
+                    : `Escalated for human owner approval (${tool.riskLevel} risk lane, ${ringEnforcement.ringLabel})`
+                : `Allowed by Microsoft Agent Governance (${matchedRule || "allow-governed-action"})`;
+        const record = {
+            id: `dec_${crypto.randomBytes(8).toString("hex")}`,
+            sdk: "@microsoft/agent-governance-sdk",
+            sdkVersion: SDK_VERSION,
+            policyId: POLICY_ID,
+            mode: policy.mode,
+            agentDid: identity.did,
+            agentPublicKey: publicKeyHex,
+            actorId,
+            workspaceId: workspace.id,
+            action: `${stage}.${tool.riskLevel}:${tool.slug}`,
+            riskLevel: tool.riskLevel,
+            decision: finalDecision,
+            verdict,
+            reason: decisionReason,
+            matchedRule,
+            securityScan: {
+                safe: scanResult.safe && !highSeverityFinding && contextPoisoning.safe,
+                riskLevel: highSeverityFinding
+                    ? "high"
+                    : scanResult.risk_score > 50 || contextPoisoning.findingsCount > 0
+                        ? "medium"
+                        : "low",
+                findingsCount: extraFindings.length,
+                findings: extraFindings,
+            },
+            auditEntry: {
+                timestamp: auditEntry.timestamp,
+                agentId: auditEntry.agentId,
+                action: auditEntry.action,
+                decision: auditDecision,
+                hash: auditEntry.hash,
+                previousHash: auditEntry.previousHash,
+                chainVerified,
+            },
+            protocolFacets,
+            ringEnforcement,
+            trustScore,
+            contextPoisoning: {
+                safe: contextPoisoning.safe,
+                riskLevel: contextPoisoning.riskLevel,
+                findingsCount: contextPoisoning.findingsCount,
+                findings: contextPoisoning.findings,
+            },
+            killSwitch: {
+                active: killSwitchActive,
+                killedAt: activeKill?.killedAt || null,
+                reason: killSwitchReason,
+            },
+            ed25519Signature,
+            signature: ed25519Signature,
+            bindingHash,
+            decidedAt,
+        };
+        record.explanation = explainDecisionRecord(record, policy);
+        return record;
+    }
+    evaluatePlan(params) {
+        return this.evaluateAction({
+            ...params,
+            stage: "plan",
+        });
+    }
+    evaluateExecution(params) {
+        return this.evaluateAction({
+            workspace: params.workspace,
+            actorId: params.actorId,
+            tool: params.tool,
+            input: params.plan.input,
+            reason: params.plan.reason,
+            stage: "execute",
+            ownerApproved: params.plan.approvalStatus === "approved" ||
+                params.plan.approvalStatus === "auto_approved",
+        });
+    }
+    /**
+     * Verifies a DecisionRecord's Ed25519 signature and the workspace's SHA-256 audit hash chain.
+     */
+    verifyDecisionRecord(workspaceOrRecord, maybeRecord) {
+        const record = maybeRecord || workspaceOrRecord;
+        const workspace = maybeRecord ? workspaceOrRecord : undefined;
+        const identity = workspace
+            ? this.getWorkspaceIdentity(workspace)
+            : this.identities.get(record.workspaceId) || this.defaultIdentity;
+        const stagePrefix = record.action.split(":")[0] || "";
+        const toolSlug = record.action.slice(stagePrefix.length + 1);
+        const signaturePayload = [
+            record.policyId,
+            record.agentDid,
+            record.workspaceId,
+            record.actorId,
+            toolSlug,
+            record.riskLevel,
+            record.decision,
+            record.auditEntry.hash,
+            record.auditEntry.previousHash,
+            record.bindingHash,
+            record.decidedAt,
+        ].join("|");
+        let ed25519Verified = false;
+        try {
+            if (identity.did === record.agentDid) {
+                ed25519Verified = identity.verify(Buffer.from(signaturePayload, "utf8"), Buffer.from(record.ed25519Signature, "hex"));
+            }
+            else if (record.agentPublicKey && record.ed25519Signature) {
+                const pubKeyObj = crypto.createPublicKey({
+                    key: Buffer.from(record.agentPublicKey, "hex"),
+                    format: "der",
+                    type: "spki",
+                });
+                ed25519Verified = crypto.verify(null, Buffer.from(signaturePayload, "utf8"), pubKeyObj, Buffer.from(record.ed25519Signature, "hex"));
+            }
+        }
+        catch {
+            ed25519Verified = false;
+        }
+        const auditLogger = this.getWorkspaceAuditLogger(record.workspaceId);
+        const auditChainVerified = auditLogger.verify();
+        return ed25519Verified && auditChainVerified;
+    }
+    /**
+     * Builds a portable Ed25519-signed AgenticReceipt envelope (compatible with the `agentic-receipts` spec)
+     * so external verifiers can validate input/output SHA-256 hashes, hash chaining, and Ed25519 signature
+     * using only the workspace's public key and DID without needing the internal vault HMAC key.
+     */
+    buildPortableAgenticReceipt(params) {
+        const { receipt, run, workspace } = params;
+        const identity = workspace
+            ? this.getWorkspaceIdentity(workspace)
+            : this.identities.get(receipt.workspaceId) || this.defaultIdentity;
+        const actionType = receipt.lane === "stripe_projects" ? "ApiCall" : "ToolCall";
+        const startedAt = run?.startedAt || receipt.issuedAt;
+        const completedAt = run?.completedAt || receipt.issuedAt;
+        const latencyMs = Math.max(0, Number(run?.durationMs ?? 0));
+        const nonce = crypto
+            .createHash("sha256")
+            .update(`muxo-agentic-receipt-nonce:${receipt.id}:${receipt.runId}`)
+            .digest("hex")
+            .slice(0, 32);
+        const previousReceiptHash = receipt.prevReceiptHash || "genesis_0000000000000000";
+        const canonicalPayload = [
+            "0.1.0",
+            receipt.id,
+            identity.did,
+            receipt.runId,
+            actionType,
+            receipt.toolSlug || "",
+            receipt.inputHash,
+            receipt.outputHash,
+            startedAt,
+            completedAt,
+            String(latencyMs),
+            nonce,
+            previousReceiptHash || "genesis",
+            receipt.receiptHash,
+        ].join("|");
+        const sigBytes = identity.sign(Buffer.from(canonicalPayload, "utf8"));
+        const signatureHex = Buffer.from(sigBytes).toString("hex");
+        const publicKeyHex = Buffer.from(identity.publicKey).toString("hex");
+        return {
+            version: "0.1.0",
+            receipt_id: receipt.id,
+            agent_id: identity.did,
+            task_id: receipt.runId,
+            action_type: actionType,
+            tool_name: receipt.toolSlug,
+            model_id: null,
+            input_hash: receipt.inputHash,
+            output_hash: receipt.outputHash,
+            started_at: startedAt,
+            completed_at: completedAt,
+            latency_ms: latencyMs,
+            nonce,
+            previous_receipt_hash: previousReceiptHash,
+            receipt_hash: receipt.receiptHash,
+            signature_algorithm: "Ed25519",
+            public_key_hex: publicKeyHex,
+            signature_hex: signatureHex,
+        };
+    }
+    /**
+     * Verifies a PortableAgenticReceipt's Ed25519 signature over its canonical hash-chained payload.
+     */
+    verifyPortableAgenticReceipt(agenticReceipt, workspace) {
+        if (!agenticReceipt || !agenticReceipt.signature_hex || !agenticReceipt.public_key_hex) {
+            return false;
+        }
+        const canonicalPayload = [
+            agenticReceipt.version || "0.1.0",
+            agenticReceipt.receipt_id,
+            agenticReceipt.agent_id,
+            agenticReceipt.task_id,
+            agenticReceipt.action_type,
+            agenticReceipt.tool_name || "",
+            agenticReceipt.input_hash,
+            agenticReceipt.output_hash,
+            agenticReceipt.started_at,
+            agenticReceipt.completed_at,
+            String(agenticReceipt.latency_ms ?? 0),
+            agenticReceipt.nonce,
+            agenticReceipt.previous_receipt_hash || "genesis",
+            agenticReceipt.receipt_hash,
+        ].join("|");
+        try {
+            const identity = workspace ? this.getWorkspaceIdentity(workspace) : null;
+            if (identity && identity.did === agenticReceipt.agent_id) {
+                return identity.verify(Buffer.from(canonicalPayload, "utf8"), Buffer.from(agenticReceipt.signature_hex, "hex"));
+            }
+            const pubKeyBytes = Buffer.from(agenticReceipt.public_key_hex, "hex");
+            const spkiKey = pubKeyBytes.length === 32
+                ? Buffer.concat([
+                    Buffer.from("302a300506032b6570032100", "hex"),
+                    pubKeyBytes,
+                ])
+                : pubKeyBytes;
+            const pubKeyObj = crypto.createPublicKey({
+                key: spkiKey,
+                format: "der",
+                type: "spki",
+            });
+            return crypto.verify(null, Buffer.from(canonicalPayload, "utf8"), pubKeyObj, Buffer.from(agenticReceipt.signature_hex, "hex"));
+        }
+        catch {
+            return false;
+        }
+    }
+    getStatus(workspace) {
+        const identity = workspace
+            ? this.getWorkspaceIdentity(workspace)
+            : this.identities.values().next().value || this.defaultIdentity;
+        let totalEntries = 0;
+        let allVerified = true;
+        for (const logger of this.auditLoggers.values()) {
+            totalEntries += logger.length;
+            if (!logger.verify())
+                allVerified = false;
+        }
+        return {
+            sdk: "@microsoft/agent-governance-sdk",
+            sdkVersion: SDK_VERSION,
+            policyId: POLICY_ID,
+            pipeline: "Agent ──► McpSecurityScanner ──► PolicyEngine ──► AgentIdentity (Ed25519 DID) ──► AuditLogger ──► DecisionRecord",
+            agentDid: identity.did,
+            publicKeyHex: Buffer.from(identity.publicKey).toString("hex"),
+            auditEntriesCount: totalEntries,
+            auditChainIntegrity: allVerified,
+        };
+    }
+    /**
+     * Returns a live governance status report for a workspace.
+     */
+    getGovernanceStatus(workspace) {
+        const identity = this.getWorkspaceIdentity(workspace);
+        const auditLogger = this.getWorkspaceAuditLogger(workspace.id);
+        const entries = auditLogger.getEntries();
+        const activeKill = this.isKillSwitchActive(workspace.id);
+        const killSwitchActive = Boolean(activeKill || workspace.policy.killSwitchActive);
+        const contextPoisoningReport = this.getContextPoisoningReport(workspace.id, "default");
+        return {
+            sdk: "@microsoft/agent-governance-sdk",
+            sdkVersion: SDK_VERSION,
+            policyId: POLICY_ID,
+            pipeline: "Agent ──► KillSwitch ──► McpSecurityScanner & ContextPoisoningDetector (ASI-06) ──► ProtocolFacets (SQL/K8s/Infra) ──► RingEnforcer ──► PolicyEngine ──► TrustManager ──► AgentIdentity (Ed25519 DID) ──► AuditLogger ──► DecisionRecord",
+            modules: [
+                "McpSecurityScanner",
+                "ContextPoisoningDetector",
+                "ProtocolFacets",
+                "RingEnforcer",
+                "PolicyEngine",
+                "TrustManager",
+                "KillSwitch",
+                "AgentIdentity",
+                "AuditLogger",
+            ],
+            agentIdentity: identity.toJSON(),
+            policy: workspace.policy,
+            trustScore: this.getWorkspaceTrustScore(workspace.id),
+            killSwitch: {
+                active: killSwitchActive,
+                killedAt: activeKill?.killedAt || null,
+                reason: activeKill?.reason || workspace.policy.killSwitchReason || null,
+                historyCount: this.killSwitch.getHistory().length,
+            },
+            contextPoisoning: {
+                poisoned: Boolean(contextPoisoningReport.poisoned ??
+                    (contextPoisoningReport.findings?.length > 0)),
+                riskScore: Number(contextPoisoningReport.riskScore ?? 0),
+                findingsCount: contextPoisoningReport.findings.length,
+                findings: contextPoisoningReport.findings.slice(-10),
+            },
+            auditChain: {
+                entriesCount: entries.length,
+                chainVerified: auditLogger.verify(),
+                recentEntries: entries.slice(-15).reverse(),
+            },
+            plainEnglishPolicy: describePolicyInPlainEnglish(workspace.policy),
+            explanation: explainGovernanceStatus({
+                workspace,
+                agentDid: identity.did,
+                trustScore: this.getWorkspaceTrustScore(workspace.id),
+                killSwitchActive,
+                killSwitchReason: activeKill?.reason || workspace.policy.killSwitchReason || null,
+                poisoned: Boolean(contextPoisoningReport.poisoned ??
+                    (contextPoisoningReport.findings?.length > 0)),
+                findingsCount: contextPoisoningReport.findings.length,
+                auditEntriesCount: entries.length,
+                chainVerified: auditLogger.verify(),
+            }),
+        };
+    }
+}
+export function explainDecisionRecord(record, policy, languageMode) {
+    const toolSlug = record.action.includes(":")
+        ? record.action.split(":").slice(1).join(":")
+        : record.action;
+    const stage = record.action.startsWith("execute.") ? "Execution" : "Plan";
+    const headline = record.decision === "allow"
+        ? `${stage} allowed: ${toolSlug} passed all workspace safety checks.`
+        : record.decision === "require_approval"
+            ? `Approval needed: ${toolSlug} (${record.riskLevel}) is paused until you approve it.`
+            : `Action blocked: ${toolSlug} was stopped by your workspace safety rules.`;
+    const scanPlain = record.securityScan.safe
+        ? "Safety scan: Clean (no prompt injection, data exfiltration, or destructive command patterns detected)."
+        : `Safety warning: Flagged ${record.securityScan.findingsCount} security issue(s) (${record.securityScan.findings.map((f) => f.description).join("; ")}).`;
+    const whyPlain = record.decision === "allow"
+        ? `This ${record.riskLevel}-level action is permitted under your active guardrails.`
+        : record.decision === "require_approval"
+            ? `Your guardrails require human sign-off before running ${record.riskLevel} actions.`
+            : record.killSwitch?.active
+                ? `Your workspace Emergency Pause is active (${record.killSwitch.reason || "all agents paused"}).`
+                : `Stopped because: ${record.reason}.`;
+    const trustPct = record.trustScore
+        ? `${Math.round(record.trustScore.overall * 100)}% (${record.trustScore.tier})`
+        : "75% (Provisional)";
+    const nonTechnical = `${headline} ${whyPlain} ${scanPlain} Agent reliability score: ${trustPct}. Recorded in your tamper-proof audit log.`;
+    const technical = `decisionId=${record.id} | decision=${record.decision} (verdict=${record.verdict}) | matchedRule=${record.matchedRule || "none"} | mode=${record.mode} | ring=${record.ringEnforcement?.agentRing ?? "?"}->${record.ringEnforcement?.requiredRing ?? "?"} (${record.ringEnforcement?.ringLabel || "Ring"}) | securityScan=(safe=${record.securityScan.safe}, risk=${record.securityScan.riskLevel}, findings=${record.securityScan.findingsCount}) | asi06Poisoning=(safe=${record.contextPoisoning?.safe ?? true}, risk=${record.contextPoisoning?.riskLevel || "none"}) | trustScore=${record.trustScore?.overall ?? 0.75} (${record.trustScore?.tier || "Provisional"}) | agentDid=${record.agentDid} | auditHash=${record.auditEntry.hash.slice(0, 16)}... (prev=${record.auditEntry.previousHash.slice(0, 16)}..., chainVerified=${record.auditEntry.chainVerified}) | bindingHash=${record.bindingHash.slice(0, 16)}... | ed25519Sig=${record.ed25519Signature.slice(0, 16)}...`;
+    return formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy,
+        languageMode,
+    });
+}
+export function explainGovernanceStatus(params) {
+    const plainPolicy = describePolicyInPlainEnglish(params.workspace.policy);
+    const trustPct = Math.round((params.trustScore.overall || 0.75) * 100);
+    const headline = params.killSwitchActive
+        ? `Emergency Pause Active: All agent actions are paused (${params.killSwitchReason || "operator pause"}).`
+        : `Governance Active: 9 safety modules protecting ${params.workspace.name} (${params.trustScore.tier} trust, ${trustPct}% score).`;
+    const nonTechnical = [
+        headline,
+        `Current posture: ${plainPolicy.headline}`,
+        params.poisoned
+            ? `Prompt-injection scanner: ${params.findingsCount} suspicious pattern(s) flagged and isolated.`
+            : "Prompt-injection & memory scanner: Clean (0 threats detected).",
+        `Tamper-proof audit log: ${params.auditEntriesCount} action${params.auditEntriesCount === 1 ? "" : "s"} verified (${params.chainVerified ? "intact" : "check required"}).`,
+    ].join(" ");
+    const technical = `sdk=@microsoft/agent-governance-sdk@${SDK_VERSION} | policyId=${POLICY_ID} | agentDid=${params.agentDid} | killSwitchActive=${params.killSwitchActive} | trustScore=${params.trustScore.overall} (tier=${params.trustScore.tier}, reliability=${params.trustScore.reliability}, consistency=${params.trustScore.consistency}) | asi06Poisoned=${params.poisoned} (findings=${params.findingsCount}) | auditChain=(entries=${params.auditEntriesCount}, verified=${params.chainVerified}) | ${plainPolicy.technical}`;
+    return formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy: params.workspace.policy,
+        languageMode: params.languageMode,
+    });
+}