@matimo/core 0.1.0-alpha.9 → 0.1.2

package/dist/policy/default-policy.js

@@ -0,0 +1,241 @@
+/**
+ * Default Policy Engine for Matimo.
+ *
+ * Conservative defaults that protect against malicious agent-created tools.
+ * Frozen at boot time — agents cannot modify policy at runtime.
+ */
+import { validateToolContent } from './content-validator.js';
+import { classifyRisk } from './risk-classifier.js';
+import { extractAuthPlaceholders } from '../mcp/tool-converter.js';
+const DEFAULT_CONFIG = {
+    allowedDomains: [],
+    allowedCredentials: [],
+    allowedHttpMethods: ['GET', 'POST'],
+    allowCommandTools: false,
+    allowFunctionTools: false,
+    protectedNamespaces: ['matimo_'],
+    enableHITL: false,
+    quarantineRiskLevels: ['medium'],
+};
+export class DefaultPolicyEngine {
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Check whether a tool definition may be created/proposed.
+     * First applies the tier gate (fast early-return for TIER 3 blocked tools),
+     * then runs ContentValidator rules.
+     */
+    canCreate(context, toolDef) {
+        // Hard TIER 3 gate — blocked regardless of content validator.
+        // Each check uses a reason string that the policy tests assert (.toContain).
+        const protectedNamespaces = this.config.protectedNamespaces;
+        if (protectedNamespaces.some((ns) => toolDef.name.startsWith(ns))) {
+            return {
+                allowed: false,
+                reason: `reserved-namespace: Tool "${toolDef.name}" uses a protected namespace (${protectedNamespaces.join(', ')})`,
+                riskLevel: 'critical',
+            };
+        }
+        if (toolDef.execution.type === 'function') {
+            return {
+                allowed: false,
+                reason: `no-function-execution: Agent-created tools may not use execution type "function"`,
+                riskLevel: 'critical',
+            };
+        }
+        if (toolDef.execution.type === 'command') {
+            return {
+                allowed: false,
+                reason: `no-command-execution: Agent-created tools may not use execution type "command"`,
+                riskLevel: 'critical',
+            };
+        }
+        if (toolDef.execution.type === 'http') {
+            const url = toolDef.execution.url ?? '';
+            if (isBlockedUrl(url)) {
+                return {
+                    allowed: false,
+                    reason: `no-ssrf: URL "${url}" targets a blocked internal/metadata address`,
+                    riskLevel: 'critical',
+                };
+            }
+        }
+        const result = validateToolContent(toolDef, {
+            source: 'untrusted',
+            policy: this.config,
+        });
+        if (!result.valid) {
+            const critical = result.violations.filter((v) => v.severity === 'critical' || v.severity === 'high');
+            if (critical.length > 0) {
+                return {
+                    allowed: false,
+                    reason: critical.map((v) => `[${v.rule}] ${v.message}`).join('; '),
+                    riskLevel: critical[0].severity,
+                };
+            }
+            // No high/critical violations, but the content is still invalid.
+            // Treat these (e.g., medium "forced-draft-status") as policy violations:
+            // either deny or quarantine for HITL, rather than silently allowing.
+            if (result.violations.length > 0) {
+                const orderedSeverities = ['low', 'medium', 'high', 'critical'];
+                const mostSevere = result.violations
+                    .map((v) => v.severity)
+                    .sort((a, b) => orderedSeverities.indexOf(b) - orderedSeverities.indexOf(a))[0];
+                const reason = result.violations.map((v) => `[${v.rule}] ${v.message}`).join('; ');
+                // Gate pending_approval behind quarantineRiskLevels: only quarantine if this risk level
+                // is explicitly configured for HITL. High/critical violations block unless explicitly allowed.
+                if (this.config.enableHITL && this.config.quarantineRiskLevels.includes(mostSevere)) {
+                    return {
+                        allowed: 'pending_approval',
+                        reason,
+                        riskLevel: mostSevere,
+                        toolName: toolDef.name,
+                    };
+                }
+                return {
+                    allowed: false,
+                    reason,
+                    riskLevel: mostSevere,
+                };
+            }
+        }
+        // In production, block anything above low risk — unless HITL is enabled
+        // for the tool's risk level, in which case quarantine it for human review
+        const risk = classifyRisk(toolDef);
+        if (context.environment === 'prod' && risk !== 'low') {
+            if (this.config.enableHITL && this.config.quarantineRiskLevels.includes(risk)) {
+                return {
+                    allowed: 'pending_approval',
+                    reason: `Tool risk level "${risk}" requires human approval in production`,
+                    riskLevel: risk,
+                    toolName: toolDef.name,
+                };
+            }
+            return {
+                allowed: false,
+                reason: `Tool risk level "${risk}" is too high for production environment`,
+                riskLevel: risk,
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Check whether the caller is allowed to execute a given tool.
+     */
+    canExecute(context, tool) {
+        const status = tool.status;
+        // Block deprecated tools
+        if (status === 'deprecated' || tool.deprecated === true) {
+            return {
+                allowed: false,
+                reason: tool.deprecation_message ?? `Tool "${tool.name}" is deprecated`,
+            };
+        }
+        // Draft tools in prod: deny
+        if (status === 'draft' && context.environment === 'prod') {
+            return {
+                allowed: false,
+                reason: `Draft tool "${tool.name}" is not available in production`,
+                riskLevel: 'medium',
+            };
+        }
+        // Draft tools without admin role: deny
+        if (status === 'draft' && !context.roles?.includes('admin')) {
+            return {
+                allowed: false,
+                reason: `Draft tool "${tool.name}" requires admin role`,
+                riskLevel: 'medium',
+            };
+        }
+        // In prod, tools requiring approval need admin or operator role
+        if (context.environment === 'prod' &&
+            tool.requires_approval === true &&
+            !context.roles?.includes('admin') &&
+            !context.roles?.includes('operator')) {
+            return {
+                allowed: false,
+                reason: `Tool "${tool.name}" requires approval and caller lacks admin/operator role in production`,
+                riskLevel: 'high',
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Filter tools to only those the caller is allowed to see and use.
+     */
+    filterForAgent(context, tools) {
+        return tools.filter((tool) => {
+            const decision = this.canExecute(context, tool);
+            return decision.allowed;
+        });
+    }
+    /** Expose the resolved config (read-only snapshot). */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Hot-reload policy configuration at runtime.
+     * Merges the new config with DEFAULT_CONFIG (preserving conservative defaults
+     * for any unset fields), then replaces the active config atomically.
+     */
+    updateConfig(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+}
+/**
+ * Pure utility: classify an agent-proposed tool into a policy tier.
+ *
+ * - `blocked`: reserved namespace, function/command execution type, SSRF URL
+ * - `approval-required`: any auth credential, non-GET HTTP method, any data write
+ * - `auto`: low-risk read-only HTTP GET with no auth
+ *
+ * This runs BEFORE content validation and is a hard gate — `blocked` tools
+ * are rejected immediately without running the full content-validator.
+ */
+export function getTierForTool(tool, config) {
+    const protectedNamespaces = config?.protectedNamespaces ?? ['matimo_'];
+    // TIER 3 — ALWAYS BLOCKED
+    if (protectedNamespaces.some((ns) => tool.name.startsWith(ns)))
+        return 'blocked';
+    if (tool.execution.type === 'function')
+        return 'blocked';
+    if (tool.execution.type === 'command')
+        return 'blocked';
+    if (tool.execution.type === 'http') {
+        const url = tool.execution.url ?? '';
+        if (isBlockedUrl(url))
+            return 'blocked';
+    }
+    // TIER 2 — APPROVAL REQUIRED
+    if (tool.execution.type === 'http') {
+        const method = (tool.execution.method ?? 'GET').toUpperCase();
+        if (method !== 'GET')
+            return 'approval-required';
+        const authVars = extractAuthPlaceholders(tool);
+        if (authVars.length > 0)
+            return 'approval-required';
+    }
+    // TIER 1 — AUTO (low-risk read-only)
+    return 'auto';
+}
+/** Check if a URL targets a blocked/internal destination (mirrors content-validator SSRF check). */
+function isBlockedUrl(url) {
+    if (!url)
+        return false;
+    try {
+        const parsed = new URL(url);
+        const hostname = parsed.hostname.toLowerCase();
+        return (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '::1' ||
+            hostname.startsWith('169.254.') || // link-local / AWS metadata
+            hostname.startsWith('10.') ||
+            hostname.startsWith('192.168.') ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(hostname));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=default-policy.js.map

package/dist/policy/default-policy.js.map

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

package/dist/policy/events.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Typed audit events for Matimo.
+ *
+ * Host applications subscribe via `onEvent` in InitOptions and route
+ * events to their own logging/audit system.
+ */
+import type { RiskLevel } from './types.js';
+import type { Violation } from './types.js';
+export type MatimoEvent = {
+    type: 'tool:created';
+    toolName: string;
+    source: 'trusted' | 'untrusted';
+    riskLevel: RiskLevel;
+    timestamp: string;
+} | {
+    type: 'tool:approved';
+    toolName: string;
+    approvedBy?: string;
+    hash: string;
+    timestamp: string;
+} | {
+    type: 'tool:rejected';
+    toolName: string;
+    violations: Violation[];
+    timestamp: string;
+} | {
+    type: 'tool:revoked';
+    toolName: string;
+    reason: string;
+    timestamp: string;
+} | {
+    type: 'tool:executed';
+    toolName: string;
+    agentId?: string;
+    duration: number;
+    success: boolean;
+    timestamp: string;
+} | {
+    type: 'tool:execution_denied';
+    toolName: string;
+    reason: string;
+    agentId?: string;
+    timestamp: string;
+} | {
+    type: 'tool:quarantined';
+    toolName: string;
+    riskLevel: RiskLevel;
+    reason: string;
+    environment?: string;
+    timestamp: string;
+} | {
+    type: 'tool:quarantine_approved';
+    toolName: string;
+    approvedBy?: string;
+    timestamp: string;
+} | {
+    type: 'tool:quarantine_rejected';
+    toolName: string;
+    timestamp: string;
+} | {
+    type: 'policy:reloaded';
+    timestamp: string;
+} | {
+    type: 'tools:reloaded';
+    loaded: number;
+    removed: number;
+    rejected: string[];
+    timestamp: string;
+};
+export type MatimoEventHandler = (event: MatimoEvent) => void;
+//# sourceMappingURL=events.d.ts.map

package/dist/policy/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/policy/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,0BAA0B,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,0BAA0B,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC"}

package/dist/policy/events.js

@@ -0,0 +1,8 @@
+/**
+ * Typed audit events for Matimo.
+ *
+ * Host applications subscribe via `onEvent` in InitOptions and route
+ * events to their own logging/audit system.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/policy/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/policy/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/policy/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Policy Engine — barrel export.
+ */
+export type { PolicyEngine, PolicyContext, PolicyDecision, PolicyConfig, RiskLevel, Violation, ValidationResult, ValidationContext, } from './types.js';
+export { DefaultPolicyEngine } from './default-policy.js';
+export { validateToolContent, isSSRFTarget } from './content-validator.js';
+export { classifyRisk } from './risk-classifier.js';
+export { ToolIntegrityTracker } from './integrity-tracker.js';
+export type { IntegrityRecord, IntegrityAction } from './integrity-tracker.js';
+export { ApprovalManifest } from './approval-manifest.js';
+export type { ApprovalRecord } from './approval-manifest.js';
+export type { MatimoEvent, MatimoEventHandler } from './events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/policy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/policy/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/policy/index.js

@@ -0,0 +1,9 @@
+/**
+ * Policy Engine — barrel export.
+ */
+export { DefaultPolicyEngine } from './default-policy.js';
+export { validateToolContent, isSSRFTarget } from './content-validator.js';
+export { classifyRisk } from './risk-classifier.js';
+export { ToolIntegrityTracker } from './integrity-tracker.js';
+export { ApprovalManifest } from './approval-manifest.js';
+//# sourceMappingURL=index.js.map

package/dist/policy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/policy/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/policy/integrity-tracker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool Integrity Tracker.
+ *
+ * Tracks SHA-256 hashes of tool YAML content to detect modifications.
+ * Used during hot-reload to decide whether re-validation is needed.
+ */
+export interface IntegrityRecord {
+    hash: string;
+    source: 'trusted' | 'untrusted';
+    validatedAt: Date;
+}
+export type IntegrityAction = {
+    action: 'keep';
+    reason: 'unchanged';
+} | {
+    action: 'revalidate';
+    reason: 'content-modified';
+} | {
+    action: 'revalidate';
+    reason: 'source-changed';
+} | {
+    action: 'validate';
+    reason: 'new-tool';
+};
+export declare class ToolIntegrityTracker {
+    private readonly records;
+    /**
+     * Compute SHA-256 hash of content.
+     */
+    computeHash(content: string): string;
+    /**
+     * Called when a tool is loaded. Compares the content hash and source with the stored
+     * record and returns what action the caller should take.
+     * If the tool moved between trusted/untrusted paths, revalidate is required even if content unchanged.
+     */
+    onToolLoaded(toolName: string, yamlContent: string, source: 'trusted' | 'untrusted'): IntegrityAction;
+    /**
+     * Record a tool's hash after successful validation/loading.
+     */
+    record(toolName: string, yamlContent: string, source: 'trusted' | 'untrusted'): void;
+    /**
+     * Get the stored record for a tool.
+     */
+    getRecord(toolName: string): IntegrityRecord | undefined;
+    /**
+     * Get the stored hash for a tool.
+     */
+    getHash(toolName: string): string | undefined;
+    /**
+     * Remove a tool entry (e.g. when it's been removed from disk).
+     */
+    removeEntry(toolName: string): boolean;
+    /**
+     * Clear all records. Used when doing a full reset.
+     */
+    clear(): void;
+    /**
+     * Get the number of tracked tools.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=integrity-tracker.d.ts.map

package/dist/policy/integrity-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-tracker.d.ts","sourceRoot":"","sources":["../../src/policy/integrity-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACpD;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAE/C,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAEnE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;OAIG;IACH,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAAG,WAAW,GAC9B,eAAe;IAoBlB;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,IAAI;IAQpF;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIxD;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/policy/integrity-tracker.js

@@ -0,0 +1,79 @@
+/**
+ * Tool Integrity Tracker.
+ *
+ * Tracks SHA-256 hashes of tool YAML content to detect modifications.
+ * Used during hot-reload to decide whether re-validation is needed.
+ */
+import { createHash } from 'crypto';
+export class ToolIntegrityTracker {
+    constructor() {
+        this.records = new Map();
+    }
+    /**
+     * Compute SHA-256 hash of content.
+     */
+    computeHash(content) {
+        return createHash('sha256').update(content, 'utf8').digest('hex');
+    }
+    /**
+     * Called when a tool is loaded. Compares the content hash and source with the stored
+     * record and returns what action the caller should take.
+     * If the tool moved between trusted/untrusted paths, revalidate is required even if content unchanged.
+     */
+    onToolLoaded(toolName, yamlContent, source) {
+        const hash = this.computeHash(yamlContent);
+        const existing = this.records.get(toolName);
+        if (!existing) {
+            return { action: 'validate', reason: 'new-tool' };
+        }
+        // Check if source changed (trusted ↔ untrusted): must revalidate for policy enforcement
+        if (existing.source !== source) {
+            return { action: 'revalidate', reason: 'source-changed' };
+        }
+        if (existing.hash === hash) {
+            return { action: 'keep', reason: 'unchanged' };
+        }
+        return { action: 'revalidate', reason: 'content-modified' };
+    }
+    /**
+     * Record a tool's hash after successful validation/loading.
+     */
+    record(toolName, yamlContent, source) {
+        this.records.set(toolName, {
+            hash: this.computeHash(yamlContent),
+            source,
+            validatedAt: new Date(),
+        });
+    }
+    /**
+     * Get the stored record for a tool.
+     */
+    getRecord(toolName) {
+        return this.records.get(toolName);
+    }
+    /**
+     * Get the stored hash for a tool.
+     */
+    getHash(toolName) {
+        return this.records.get(toolName)?.hash;
+    }
+    /**
+     * Remove a tool entry (e.g. when it's been removed from disk).
+     */
+    removeEntry(toolName) {
+        return this.records.delete(toolName);
+    }
+    /**
+     * Clear all records. Used when doing a full reset.
+     */
+    clear() {
+        this.records.clear();
+    }
+    /**
+     * Get the number of tracked tools.
+     */
+    get size() {
+        return this.records.size;
+    }
+}
+//# sourceMappingURL=integrity-tracker.js.map

package/dist/policy/integrity-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-tracker.js","sourceRoot":"","sources":["../../src/policy/integrity-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAcpC,MAAM,OAAO,oBAAoB;IAAjC;QACmB,YAAO,GAAiC,IAAI,GAAG,EAAE,CAAC;IAmFrE,CAAC;IAjFC;;OAEG;IACH,WAAW,CAAC,OAAe;QACzB,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,YAAY,CACV,QAAgB,EAChB,WAAmB,EACnB,MAA+B;QAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QACpD,CAAC;QAED,wFAAwF;QACxF,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QAC5D,CAAC;QAED,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACjD,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAgB,EAAE,WAAmB,EAAE,MAA+B;QAC3E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE;YACzB,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC;YACnC,MAAM;YACN,WAAW,EAAE,IAAI,IAAI,EAAE;SACxB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,QAAgB;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAgB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/policy/policy-loader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Policy-as-YAML loader for Matimo.
+ *
+ * Allows the developer to configure the policy engine through a YAML file
+ * instead of inline TypeScript, making it easy to adjust policy across
+ * environments without rebuilding.
+ *
+ * Schema for policy.yaml:
+ *
+ * ```yaml
+ * allowedDomains:
+ *   - api.slack.com
+ *   - slack.com
+ *
+ * allowedCredentials:
+ *   - SLACK_BOT_TOKEN
+ *   - OPENAI_API_KEY
+ *
+ * allowedHttpMethods:
+ *   - GET
+ *   - POST
+ *
+ * allowCommandTools: false
+ * allowFunctionTools: false
+ *
+ * protectedNamespaces:
+ *   - matimo_
+ * ```
+ *
+ * Usage:
+ *   const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ */
+import type { PolicyEngine, PolicyConfig } from './types.js';
+/**
+ * Parse a YAML policy file and return a PolicyEngine configured from it.
+ *
+ * Throws `MatimoError(INVALID_SCHEMA)` if the file cannot be read or fails validation.
+ *
+ * @param filePath - Absolute or cwd-relative path to the policy YAML file
+ * @returns A frozen `DefaultPolicyEngine` built from the parsed config
+ *
+ * @example
+ * ```ts
+ * // Direct usage
+ * const engine = loadPolicyFromFile('./policy.yaml');
+ * const matimo = await MatimoInstance.init({ policy: engine });
+ *
+ * // Or use the shorthand InitOption (preferred)
+ * const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ * ```
+ */
+export declare function loadPolicyFromFile(filePath: string): PolicyEngine;
+/**
+ * Parse a YAML policy file into a PolicyConfig (without creating an engine).
+ * Useful for hot-reload: parse the new file, then call engine.updateConfig().
+ */
+export declare function parsePolicyFile(filePath: string): PolicyConfig;
+//# sourceMappingURL=policy-loader.d.ts.map

package/dist/policy/policy-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.d.ts","sourceRoot":"","sources":["../../src/policy/policy-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAoC7D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAqCjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAoC9D"}