@provos/ironcurtain 0.1.0

package/dist/trusted-process/path-utils.js

@@ -0,0 +1,158 @@
+/**
+ * Path normalization utilities for the trusted process security boundary.
+ *
+ * Provides annotation-driven normalization via `prepareToolArgs()` and a
+ * legacy heuristic fallback via `normalizeToolArgPaths()`. The heuristic
+ * is retained for defense-in-depth and as a fallback when annotations are
+ * unavailable.
+ */
+import { resolve } from 'node:path';
+import { getRoleDefinition, resolveRealPath, expandTilde } from '../types/argument-roles.js';
+export { expandTilde } from '../types/argument-roles.js';
+/** Returns true if the string looks like a filesystem path. */
+function looksLikePath(value) {
+    return value.startsWith('/') || value.startsWith('.') || value.startsWith('~');
+}
+/** Resolves a path-like string to its canonical real path, following symlinks. */
+function normalizePath(value) {
+    return resolveRealPath(expandTilde(value));
+}
+/**
+ * Returns a new arguments object with all path-like string values
+ * fully resolved (tilde expanded, relative resolved, traversals collapsed).
+ *
+ * A string value is considered path-like if it starts with `/`, `.`, or `~`.
+ * Array values have each string element checked individually.
+ * Non-string and non-path values pass through unchanged.
+ *
+ * The input object is never mutated.
+ *
+ * @deprecated Use `prepareToolArgs()` with annotation-driven normalization.
+ * Retained as a fallback when annotations are unavailable.
+ */
+export function normalizeToolArgPaths(args) {
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === 'string' && looksLikePath(value)) {
+            result[key] = normalizePath(value);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map(item => typeof item === 'string' && looksLikePath(item)
+                ? normalizePath(item)
+                : item);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Absolute vs relative path detection
+// ---------------------------------------------------------------------------
+/** Returns true if the path is absolute (starts with `/` or `~`). */
+function isAbsolutePath(value) {
+    return value.startsWith('/') || value.startsWith('~');
+}
+/**
+ * Resolves a relative path against the sandbox directory for policy evaluation.
+ * Applies tilde expansion first, then resolves against the sandbox base,
+ * then follows symlinks via resolveRealPath.
+ */
+function resolveAgainstSandbox(value, sandboxDir) {
+    const expanded = expandTilde(value);
+    const absolute = resolve(sandboxDir, expanded);
+    return resolveRealPath(absolute);
+}
+/**
+ * Finds the first resource-identifier role in a role array, or undefined
+ * if all roles are non-resource (e.g., 'none').
+ */
+function findResourceRole(roles) {
+    return roles.find(r => getRoleDefinition(r).isResourceIdentifier);
+}
+/**
+ * Normalizes a single argument value using a role's normalizer.
+ * Handles both string and string-array values. Non-string values
+ * pass through unchanged.
+ */
+function normalizeArgValue(value, normalize) {
+    if (typeof value === 'string') {
+        return normalize(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => typeof item === 'string' ? normalize(item) : item);
+    }
+    return value;
+}
+/**
+ * Normalizes a single path argument for transport, handling the
+ * absolute/relative split. Absolute paths get full normalization;
+ * relative paths pass through unchanged (the MCP server resolves
+ * them against its own CWD, which is the sandbox directory).
+ */
+function normalizePathForTransport(value, def) {
+    return normalizeArgValue(value, v => isAbsolutePath(v) ? def.normalize(v) : v);
+}
+/**
+ * Normalizes a single path argument for policy evaluation. Absolute
+ * paths get full normalization; relative paths are resolved against
+ * the sandbox (allowedDirectory) so the policy engine can perform
+ * containment checks with absolute canonical paths.
+ */
+function normalizePathForPolicy(value, def, allowedDirectory) {
+    return normalizeArgValue(value, v => isAbsolutePath(v) ? def.normalize(v) : resolveAgainstSandbox(v, allowedDirectory));
+}
+/**
+ * Annotation-driven normalization of tool call arguments.
+ *
+ * For each argument, looks up its annotated roles and applies the
+ * corresponding normalizer from the registry. Returns two argument
+ * objects: one for transport (MCP server) and one for policy evaluation.
+ *
+ * For path-category roles, relative paths (not starting with `/` or `~`)
+ * are treated differently:
+ *   - Transport: passed through unchanged (the MCP server resolves them
+ *     against its own sandbox CWD)
+ *   - Policy: resolved against `allowedDirectory` so the policy engine
+ *     has absolute canonical paths for containment checks
+ *
+ * When `annotation` is undefined (unknown tool), falls back to the
+ * heuristic `normalizeToolArgPaths()` for both outputs.
+ *
+ * The input object is never mutated.
+ */
+export function prepareToolArgs(args, annotation, allowedDirectory) {
+    if (!annotation) {
+        const fallback = normalizeToolArgPaths(args);
+        return { argsForTransport: fallback, argsForPolicy: fallback };
+    }
+    const argsForTransport = {};
+    const argsForPolicy = {};
+    for (const [key, value] of Object.entries(args)) {
+        const roles = annotation.args[key];
+        const resourceRole = roles ? findResourceRole(roles) : undefined;
+        if (resourceRole) {
+            const def = getRoleDefinition(resourceRole);
+            if (def.category === 'path' && allowedDirectory) {
+                // Path roles with sandbox context: split relative vs absolute
+                argsForTransport[key] = normalizePathForTransport(value, def);
+                argsForPolicy[key] = normalizePathForPolicy(value, def, allowedDirectory);
+            }
+            else {
+                // Non-path roles (URLs, opaque) or no sandbox: normalize for both
+                const transportValue = normalizeArgValue(value, def.normalize);
+                argsForTransport[key] = transportValue;
+                // Domain extraction (prepareForPolicy) is handled later by
+                // the policy engine's resolveUrlForDomainCheck().
+                argsForPolicy[key] = transportValue;
+            }
+        }
+        else {
+            argsForTransport[key] = value;
+            argsForPolicy[key] = value;
+        }
+    }
+    return { argsForTransport, argsForPolicy };
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/trusted-process/path-utils.js.map

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

package/dist/trusted-process/policy-engine.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PolicyEngine -- Two-phase declarative policy evaluation.
+ *
+ * Phase 1: Hardcoded structural invariants (protected paths, unknown tools).
+ *          These are never overridden by compiled rules. Sandbox containment
+ *          is checked per-role: roles whose paths are all within the sandbox
+ *          are resolved here and skipped in Phase 2.
+ *
+ * Phase 2: Compiled declarative rules loaded from compiled-policy.json.
+ *          Each distinct role from the tool's annotation is evaluated
+ *          independently through the rule chain (first-match-wins per role).
+ *          The most restrictive result wins: deny > escalate > allow.
+ *          Roles already resolved by Phase 1 sandbox containment are skipped.
+ */
+import type { ToolCallRequest } from '../types/mcp.js';
+import type { EvaluationResult } from './policy-types.js';
+import type { CompiledPolicyFile, ToolAnnotationsFile, ToolAnnotation } from '../pipeline/types.js';
+/**
+ * Checks whether a domain matches any pattern in an allowlist.
+ * Supports exact match, `*` wildcard (matches everything),
+ * and `*.example.com` prefix wildcards (matches example.com and *.example.com).
+ */
+export declare function domainMatchesAllowlist(domain: string, allowedDomains: readonly string[]): boolean;
+export declare class PolicyEngine {
+    private annotationMap;
+    private compiledPolicy;
+    private protectedPaths;
+    private allowedDirectory?;
+    private serverDomainAllowlists;
+    constructor(compiledPolicy: CompiledPolicyFile, toolAnnotations: ToolAnnotationsFile, protectedPaths: string[], allowedDirectory?: string, serverDomainAllowlists?: ReadonlyMap<string, readonly string[]>);
+    private buildAnnotationMap;
+    /** Returns the annotation for a tool, or undefined if unknown. */
+    getAnnotation(serverName: string, toolName: string): ToolAnnotation | undefined;
+    evaluate(request: ToolCallRequest): EvaluationResult;
+    /**
+     * Phase 1: Hardcoded structural invariants.
+     *
+     * 1a. Protected path check (deny)
+     * 1b. Sandbox containment for path-category roles (allow/partial)
+     * 1c. Domain allowlist for url-category roles (escalate)
+     * 1d. Unknown tool denial (deny)
+     *
+     * Uses the union of heuristic and annotation-based path extraction
+     * for defense-in-depth. Returns a StructuralResult with either a
+     * final decision or a set of roles resolved by sandbox containment.
+     */
+    private evaluateStructuralInvariants;
+    /**
+     * Phase 2: Evaluate compiled declarative rules.
+     *
+     * For tools with multiple roles (e.g., edit_file has read-path + write-path),
+     * each role is evaluated independently through the rule chain. The most
+     * restrictive result across all roles wins (deny > escalate > allow).
+     * Roles already resolved by Phase 1 sandbox containment are skipped.
+     *
+     * For tools with no roles (e.g., list_allowed_directories), the chain is
+     * evaluated once without role filtering.
+     */
+    private evaluateCompiledRules;
+    /**
+     * Evaluates the rule chain for a single role (or all roles if undefined).
+     *
+     * When evaluatingRole is set, only rules that are either role-agnostic
+     * (no roles/paths conditions) or relevant to the specified role are
+     * considered. First matching rule wins; default deny if none match.
+     *
+     * For roles with multiple extracted paths, delegates to
+     * evaluateRulesForMultiPaths for per-element evaluation.
+     */
+    private evaluateRulesForRole;
+    /**
+     * Per-element path evaluation for roles with multiple paths.
+     *
+     * Each path is independently "discharged" by the first rule whose
+     * paths.within contains it. Rules without path conditions match all
+     * remaining paths. The most restrictive decision across all discharged
+     * paths wins (deny > escalate > allow). Undischarged paths default-deny.
+     */
+    private evaluateRulesForMultiPaths;
+    /**
+     * Checks non-path conditions in a rule's `if` block: roles, server, tool, sideEffects.
+     */
+    private ruleMatchesNonPathConditions;
+    /**
+     * Checks whether all conditions in a rule's `if` block are satisfied.
+     */
+    private ruleMatches;
+}