@anthropic-field/core 0.1.0

package/dist/src/policy/toml-loader.js

@@ -0,0 +1,366 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PolicyDecision, ApprovalMode, InProcessCheckerType, } from './types.js';
+import { buildArgsPatterns } from './utils.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import toml from '@iarna/toml';
+import { z } from 'zod';
+/**
+ * Schema for a single policy rule in the TOML file (before transformation).
+ */
+const PolicyRuleSchema = z.object({
+    toolName: z.union([z.string(), z.array(z.string())]).optional(),
+    mcpName: z.string().optional(),
+    argsPattern: z.string().optional(),
+    commandPrefix: z.union([z.string(), z.array(z.string())]).optional(),
+    commandRegex: z.string().optional(),
+    decision: z.nativeEnum(PolicyDecision),
+    // Priority must be in range [0, 999] to prevent tier overflow.
+    // With tier transformation (tier + priority/1000), this ensures:
+    // - Tier 1 (default): range [1.000, 1.999]
+    // - Tier 2 (user): range [2.000, 2.999]
+    // - Tier 3 (admin): range [3.000, 3.999]
+    priority: z
+        .number({
+        required_error: 'priority is required',
+        invalid_type_error: 'priority must be a number',
+    })
+        .int({ message: 'priority must be an integer' })
+        .min(0, { message: 'priority must be >= 0' })
+        .max(999, {
+        message: 'priority must be <= 999 to prevent tier overflow. Priorities >= 1000 would jump to the next tier.',
+    }),
+    modes: z.array(z.nativeEnum(ApprovalMode)).optional(),
+    allow_redirection: z.boolean().optional(),
+    deny_message: z.string().optional(),
+});
+/**
+ * Schema for a single safety checker rule in the TOML file.
+ */
+const SafetyCheckerRuleSchema = z.object({
+    toolName: z.union([z.string(), z.array(z.string())]).optional(),
+    mcpName: z.string().optional(),
+    argsPattern: z.string().optional(),
+    commandPrefix: z.union([z.string(), z.array(z.string())]).optional(),
+    commandRegex: z.string().optional(),
+    priority: z.number().int().default(0),
+    modes: z.array(z.nativeEnum(ApprovalMode)).optional(),
+    checker: z.discriminatedUnion('type', [
+        z.object({
+            type: z.literal('in-process'),
+            name: z.nativeEnum(InProcessCheckerType),
+            required_context: z.array(z.string()).optional(),
+            config: z.record(z.unknown()).optional(),
+        }),
+        z.object({
+            type: z.literal('external'),
+            name: z.string(),
+            required_context: z.array(z.string()).optional(),
+            config: z.record(z.unknown()).optional(),
+        }),
+    ]),
+});
+/**
+ * Schema for the entire policy TOML file.
+ */
+const PolicyFileSchema = z.object({
+    rule: z.array(PolicyRuleSchema).optional(),
+    safety_checker: z.array(SafetyCheckerRuleSchema).optional(),
+});
+/**
+ * Converts a tier number to a human-readable tier name.
+ */
+function getTierName(tier) {
+    if (tier === 1)
+        return 'default';
+    if (tier === 2)
+        return 'user';
+    if (tier === 3)
+        return 'admin';
+    return 'default';
+}
+/**
+ * Formats a Zod validation error into a readable error message.
+ */
+function formatSchemaError(error, ruleIndex) {
+    const issues = error.issues
+        .map((issue) => {
+        const path = issue.path.join('.');
+        return `  - Field "${path}": ${issue.message}`;
+    })
+        .join('\n');
+    return `Invalid policy rule (rule #${ruleIndex + 1}):\n${issues}`;
+}
+/**
+ * Validates shell command convenience syntax rules.
+ * Returns an error message if invalid, or null if valid.
+ */
+function validateShellCommandSyntax(rule, ruleIndex) {
+    const hasCommandPrefix = rule.commandPrefix !== undefined;
+    const hasCommandRegex = rule.commandRegex !== undefined;
+    const hasArgsPattern = rule.argsPattern !== undefined;
+    if (hasCommandPrefix || hasCommandRegex) {
+        // Must have exactly toolName = "run_shell_command"
+        if (rule.toolName !== 'run_shell_command' || Array.isArray(rule.toolName)) {
+            return (`Rule #${ruleIndex + 1}: commandPrefix and commandRegex can only be used with toolName = "run_shell_command"\n` +
+                `  Found: toolName = ${JSON.stringify(rule.toolName)}\n` +
+                `  Fix: Set toolName = "run_shell_command" (not an array)`);
+        }
+        // Can't combine with argsPattern
+        if (hasArgsPattern) {
+            return (`Rule #${ruleIndex + 1}: cannot use both commandPrefix/commandRegex and argsPattern\n` +
+                `  These fields are mutually exclusive\n` +
+                `  Fix: Use either commandPrefix/commandRegex OR argsPattern, not both`);
+        }
+        // Can't use both commandPrefix and commandRegex
+        if (hasCommandPrefix && hasCommandRegex) {
+            return (`Rule #${ruleIndex + 1}: cannot use both commandPrefix and commandRegex\n` +
+                `  These fields are mutually exclusive\n` +
+                `  Fix: Use either commandPrefix OR commandRegex, not both`);
+        }
+    }
+    return null;
+}
+/**
+ * Transforms a priority number based on the policy tier.
+ * Formula: tier + priority/1000
+ *
+ * @param priority The priority value from the TOML file
+ * @param tier The tier (1=default, 2=user, 3=admin)
+ * @returns The transformed priority
+ */
+function transformPriority(priority, tier) {
+    return tier + priority / 1000;
+}
+/**
+ * Loads and parses policies from TOML files in the specified directories.
+ *
+ * This function:
+ * 1. Scans directories for .toml files
+ * 2. Parses and validates each file
+ * 3. Transforms rules (commandPrefix, arrays, mcpName, priorities)
+ * 4. Collects detailed error information for any failures
+ *
+ * @param policyDirs Array of directory paths to scan for policy files
+ * @param getPolicyTier Function to determine tier (1-3) for a directory
+ * @returns Object containing successfully parsed rules and any errors encountered
+ */
+export async function loadPoliciesFromToml(policyDirs, getPolicyTier) {
+    const rules = [];
+    const checkers = [];
+    const errors = [];
+    for (const dir of policyDirs) {
+        const tier = getPolicyTier(dir);
+        const tierName = getTierName(tier);
+        // Scan directory for all .toml files
+        let filesToLoad;
+        try {
+            const dirEntries = await fs.readdir(dir, { withFileTypes: true });
+            filesToLoad = dirEntries
+                .filter((entry) => entry.isFile() && entry.name.endsWith('.toml'))
+                .map((entry) => entry.name);
+        }
+        catch (e) {
+            const error = e;
+            if (error.code === 'ENOENT') {
+                // Directory doesn't exist, skip it (not an error)
+                continue;
+            }
+            errors.push({
+                filePath: dir,
+                fileName: path.basename(dir),
+                tier: tierName,
+                errorType: 'file_read',
+                message: `Failed to read policy directory`,
+                details: error.message,
+            });
+            continue;
+        }
+        for (const file of filesToLoad) {
+            const filePath = path.join(dir, file);
+            try {
+                // Read file
+                const fileContent = await fs.readFile(filePath, 'utf-8');
+                // Parse TOML
+                let parsed;
+                try {
+                    parsed = toml.parse(fileContent);
+                }
+                catch (e) {
+                    const error = e;
+                    errors.push({
+                        filePath,
+                        fileName: file,
+                        tier: tierName,
+                        errorType: 'toml_parse',
+                        message: 'TOML parsing failed',
+                        details: error.message,
+                        suggestion: 'Check for syntax errors like missing quotes, brackets, or commas',
+                    });
+                    continue;
+                }
+                // Validate schema
+                const validationResult = PolicyFileSchema.safeParse(parsed);
+                if (!validationResult.success) {
+                    errors.push({
+                        filePath,
+                        fileName: file,
+                        tier: tierName,
+                        errorType: 'schema_validation',
+                        message: 'Schema validation failed',
+                        details: formatSchemaError(validationResult.error, 0),
+                        suggestion: 'Ensure all required fields (decision, priority) are present with correct types',
+                    });
+                    continue;
+                }
+                // Validate shell command convenience syntax
+                const tomlRules = validationResult.data.rule ?? [];
+                for (let i = 0; i < tomlRules.length; i++) {
+                    const rule = tomlRules[i];
+                    const validationError = validateShellCommandSyntax(rule, i);
+                    if (validationError) {
+                        errors.push({
+                            filePath,
+                            fileName: file,
+                            tier: tierName,
+                            ruleIndex: i,
+                            errorType: 'rule_validation',
+                            message: 'Invalid shell command syntax',
+                            details: validationError,
+                        });
+                        // Continue to next rule, don't skip the entire file
+                    }
+                }
+                // Transform rules
+                const parsedRules = (validationResult.data.rule ?? [])
+                    .flatMap((rule) => {
+                    const argsPatterns = buildArgsPatterns(rule.argsPattern, rule.commandPrefix, rule.commandRegex);
+                    // For each argsPattern, expand toolName arrays
+                    return argsPatterns.flatMap((argsPattern) => {
+                        const toolNames = rule.toolName
+                            ? Array.isArray(rule.toolName)
+                                ? rule.toolName
+                                : [rule.toolName]
+                            : [undefined];
+                        // Create a policy rule for each tool name
+                        return toolNames.map((toolName) => {
+                            // Transform mcpName field to composite toolName format
+                            let effectiveToolName;
+                            if (rule.mcpName && toolName) {
+                                effectiveToolName = `${rule.mcpName}__${toolName}`;
+                            }
+                            else if (rule.mcpName) {
+                                effectiveToolName = `${rule.mcpName}__*`;
+                            }
+                            else {
+                                effectiveToolName = toolName;
+                            }
+                            const policyRule = {
+                                toolName: effectiveToolName,
+                                decision: rule.decision,
+                                priority: transformPriority(rule.priority, tier),
+                                modes: rule.modes,
+                                allowRedirection: rule.allow_redirection,
+                                source: `${tierName.charAt(0).toUpperCase() + tierName.slice(1)}: ${file}`,
+                                denyMessage: rule.deny_message,
+                            };
+                            // Compile regex pattern
+                            if (argsPattern) {
+                                try {
+                                    policyRule.argsPattern = new RegExp(argsPattern);
+                                }
+                                catch (e) {
+                                    const error = e;
+                                    errors.push({
+                                        filePath,
+                                        fileName: file,
+                                        tier: tierName,
+                                        errorType: 'regex_compilation',
+                                        message: 'Invalid regex pattern',
+                                        details: `Pattern: ${argsPattern}\nError: ${error.message}`,
+                                        suggestion: 'Check regex syntax for errors like unmatched brackets or invalid escape sequences',
+                                    });
+                                    // Skip this rule if regex compilation fails
+                                    return null;
+                                }
+                            }
+                            return policyRule;
+                        });
+                    });
+                })
+                    .filter((rule) => rule !== null);
+                rules.push(...parsedRules);
+                // Transform checkers
+                const parsedCheckers = (validationResult.data.safety_checker ?? [])
+                    .flatMap((checker) => {
+                    const argsPatterns = buildArgsPatterns(checker.argsPattern, checker.commandPrefix, checker.commandRegex);
+                    return argsPatterns.flatMap((argsPattern) => {
+                        const toolNames = checker.toolName
+                            ? Array.isArray(checker.toolName)
+                                ? checker.toolName
+                                : [checker.toolName]
+                            : [undefined];
+                        return toolNames.map((toolName) => {
+                            let effectiveToolName;
+                            if (checker.mcpName && toolName) {
+                                effectiveToolName = `${checker.mcpName}__${toolName}`;
+                            }
+                            else if (checker.mcpName) {
+                                effectiveToolName = `${checker.mcpName}__*`;
+                            }
+                            else {
+                                effectiveToolName = toolName;
+                            }
+                            const safetyCheckerRule = {
+                                toolName: effectiveToolName,
+                                priority: checker.priority,
+                                checker: checker.checker,
+                                modes: checker.modes,
+                            };
+                            if (argsPattern) {
+                                try {
+                                    safetyCheckerRule.argsPattern = new RegExp(argsPattern);
+                                }
+                                catch (e) {
+                                    const error = e;
+                                    errors.push({
+                                        filePath,
+                                        fileName: file,
+                                        tier: tierName,
+                                        errorType: 'regex_compilation',
+                                        message: 'Invalid regex pattern in safety checker',
+                                        details: `Pattern: ${argsPattern}\nError: ${error.message}`,
+                                    });
+                                    return null;
+                                }
+                            }
+                            return safetyCheckerRule;
+                        });
+                    });
+                })
+                    .filter((checker) => checker !== null);
+                checkers.push(...parsedCheckers);
+            }
+            catch (e) {
+                const error = e;
+                // Catch-all for unexpected errors
+                if (error.code !== 'ENOENT') {
+                    errors.push({
+                        filePath,
+                        fileName: file,
+                        tier: tierName,
+                        errorType: 'file_read',
+                        message: 'Failed to read policy file',
+                        details: error.message,
+                    });
+                }
+            }
+        }
+    }
+    return { rules, checkers, errors };
+}
+//# sourceMappingURL=toml-loader.js.map

package/dist/src/policy/toml-loader.js.map

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

package/dist/src/policy/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SafetyCheckInput } from '../safety/protocol.js';
+export declare enum PolicyDecision {
+    ALLOW = "allow",
+    DENY = "deny",
+    ASK_USER = "ask_user"
+}
+/**
+ * Valid sources for hook execution
+ */
+export type HookSource = 'project' | 'user' | 'system' | 'extension';
+/**
+ * Safely extract and validate hook source from input
+ * Returns 'project' as default if the value is invalid or missing
+ */
+export declare function getHookSource(input: Record<string, unknown>): HookSource;
+export declare enum ApprovalMode {
+    DEFAULT = "default",
+    AUTO_EDIT = "autoEdit",
+    YOLO = "yolo",
+    PLAN = "plan"
+}
+/**
+ * Configuration for the built-in allowed-path checker.
+ */
+export interface AllowedPathConfig {
+    /**
+     * Explicitly include argument keys to be checked as paths.
+     */
+    included_args?: string[];
+    /**
+     * Explicitly exclude argument keys from being checked as paths.
+     */
+    excluded_args?: string[];
+}
+/**
+ * Base interface for external checkers.
+ */
+export interface ExternalCheckerConfig {
+    type: 'external';
+    name: string;
+    config?: unknown;
+    required_context?: Array<keyof SafetyCheckInput['context']>;
+}
+export declare enum InProcessCheckerType {
+    ALLOWED_PATH = "allowed-path"
+}
+/**
+ * Base interface for in-process checkers.
+ */
+export interface InProcessCheckerConfig {
+    type: 'in-process';
+    name: InProcessCheckerType;
+    config?: AllowedPathConfig;
+    required_context?: Array<keyof SafetyCheckInput['context']>;
+}
+/**
+ * A discriminated union for all safety checker configurations.
+ */
+export type SafetyCheckerConfig = ExternalCheckerConfig | InProcessCheckerConfig;
+export interface PolicyRule {
+    /**
+     * A unique name for the policy rule, useful for identification and debugging.
+     */
+    name?: string;
+    /**
+     * The name of the tool this rule applies to.
+     * If undefined, the rule applies to all tools.
+     */
+    toolName?: string;
+    /**
+     * Pattern to match against tool arguments.
+     * Can be used for more fine-grained control.
+     */
+    argsPattern?: RegExp;
+    /**
+     * The decision to make when this rule matches.
+     */
+    decision: PolicyDecision;
+    /**
+     * Priority of this rule. Higher numbers take precedence.
+     * Default is 0.
+     */
+    priority?: number;
+    /**
+     * Approval modes this rule applies to.
+     * If undefined or empty, it applies to all modes.
+     */
+    modes?: ApprovalMode[];
+    /**
+     * If true, allows command redirection even if the policy engine would normally
+     * downgrade ALLOW to ASK_USER for redirected commands.
+     * Only applies when decision is ALLOW.
+     */
+    allowRedirection?: boolean;
+    /**
+     * Effect of the rule's source.
+     * e.g. "my-policies.toml", "Settings (MCP Trusted)", etc.
+     */
+    source?: string;
+    /**
+     * Optional message to display when this rule results in a DENY decision.
+     * This message will be returned to the model/user.
+     */
+    denyMessage?: string;
+}
+export interface SafetyCheckerRule {
+    /**
+     * The name of the tool this rule applies to.
+     * If undefined, the rule applies to all tools.
+     */
+    toolName?: string;
+    /**
+     * Pattern to match against tool arguments.
+     * Can be used for more fine-grained control.
+     */
+    argsPattern?: RegExp;
+    /**
+     * Priority of this checker. Higher numbers run first.
+     * Default is 0.
+     */
+    priority?: number;
+    /**
+     * Specifies an external or built-in safety checker to execute for
+     * additional validation of a tool call.
+     */
+    checker: SafetyCheckerConfig;
+    /**
+     * Approval modes this rule applies to.
+     * If undefined or empty, it applies to all modes.
+     */
+    modes?: ApprovalMode[];
+}
+export interface HookExecutionContext {
+    eventName: string;
+    hookSource?: HookSource;
+    trustedFolder?: boolean;
+}
+/**
+ * Rule for applying safety checkers to hook executions.
+ * Similar to SafetyCheckerRule but with hook-specific matching criteria.
+ */
+export interface HookCheckerRule {
+    /**
+     * The name of the hook event this rule applies to.
+     * If undefined, the rule applies to all hook events.
+     */
+    eventName?: string;
+    /**
+     * The source of hooks this rule applies to.
+     * If undefined, the rule applies to all hook sources.
+     */
+    hookSource?: HookSource;
+    /**
+     * Priority of this checker. Higher numbers run first.
+     * Default is 0.
+     */
+    priority?: number;
+    /**
+     * Specifies an external or built-in safety checker to execute for
+     * additional validation of a hook execution.
+     */
+    checker: SafetyCheckerConfig;
+}
+export interface PolicyEngineConfig {
+    /**
+     * List of policy rules to apply.
+     */
+    rules?: PolicyRule[];
+    /**
+     * List of safety checkers to apply to tool calls.
+     */
+    checkers?: SafetyCheckerRule[];
+    /**
+     * List of safety checkers to apply to hook executions.
+     */
+    hookCheckers?: HookCheckerRule[];
+    /**
+     * Default decision when no rules match.
+     * Defaults to ASK_USER.
+     */
+    defaultDecision?: PolicyDecision;
+    /**
+     * Whether to allow tools in non-interactive mode.
+     * When true, ASK_USER decisions become DENY.
+     */
+    nonInteractive?: boolean;
+    /**
+     * Whether to allow hooks to execute.
+     * When false, all hooks are denied.
+     * Defaults to true.
+     */
+    allowHooks?: boolean;
+    /**
+     * Current approval mode.
+     * Used to filter rules that have specific 'modes' defined.
+     */
+    approvalMode?: ApprovalMode;
+}
+export interface PolicySettings {
+    mcp?: {
+        excluded?: string[];
+        allowed?: string[];
+    };
+    tools?: {
+        exclude?: string[];
+        allowed?: string[];
+    };
+    mcpServers?: Record<string, {
+        trust?: boolean;
+    }>;
+}
+export interface CheckResult {
+    decision: PolicyDecision;
+    rule?: PolicyRule;
+}

package/dist/src/policy/types.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var PolicyDecision;
+(function (PolicyDecision) {
+    PolicyDecision["ALLOW"] = "allow";
+    PolicyDecision["DENY"] = "deny";
+    PolicyDecision["ASK_USER"] = "ask_user";
+})(PolicyDecision || (PolicyDecision = {}));
+/**
+ * Array of valid hook source values for runtime validation
+ */
+const VALID_HOOK_SOURCES = [
+    'project',
+    'user',
+    'system',
+    'extension',
+];
+/**
+ * Safely extract and validate hook source from input
+ * Returns 'project' as default if the value is invalid or missing
+ */
+export function getHookSource(input) {
+    const source = input['hook_source'];
+    if (typeof source === 'string' &&
+        VALID_HOOK_SOURCES.includes(source)) {
+        return source;
+    }
+    return 'project';
+}
+export var ApprovalMode;
+(function (ApprovalMode) {
+    ApprovalMode["DEFAULT"] = "default";
+    ApprovalMode["AUTO_EDIT"] = "autoEdit";
+    ApprovalMode["YOLO"] = "yolo";
+    ApprovalMode["PLAN"] = "plan";
+})(ApprovalMode || (ApprovalMode = {}));
+export var InProcessCheckerType;
+(function (InProcessCheckerType) {
+    InProcessCheckerType["ALLOWED_PATH"] = "allowed-path";
+})(InProcessCheckerType || (InProcessCheckerType = {}));
+//# sourceMappingURL=types.js.map

package/dist/src/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,iCAAe,CAAA;IACf,+BAAa,CAAA;IACb,uCAAqB,CAAA;AACvB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB;AAOD;;GAEG;AACH,MAAM,kBAAkB,GAAiB;IACvC,SAAS;IACT,MAAM;IACN,QAAQ;IACR,WAAW;CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAA8B;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IACpC,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,kBAAkB,CAAC,QAAQ,CAAC,MAAoB,CAAC,EACjD,CAAC;QACD,OAAO,MAAoB,CAAC;IAC9B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,sCAAsB,CAAA;IACtB,6BAAa,CAAA;IACb,6BAAa,CAAA;AACf,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AA2BD,MAAM,CAAN,IAAY,oBAEX;AAFD,WAAY,oBAAoB;IAC9B,qDAA6B,CAAA;AAC/B,CAAC,EAFW,oBAAoB,KAApB,oBAAoB,QAE/B"}

package/dist/src/policy/utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Escapes a string for use in a regular expression.
+ */
+export declare function escapeRegex(text: string): string;
+/**
+ * Builds a list of args patterns for policy matching.
+ *
+ * This function handles the transformation of command prefixes and regexes into
+ * the internal argsPattern representation used by the PolicyEngine.
+ *
+ * @param argsPattern An optional raw regex string for arguments.
+ * @param commandPrefix An optional command prefix (or list of prefixes) to allow.
+ * @param commandRegex An optional command regex string to allow.
+ * @returns An array of string patterns (or undefined) for the PolicyEngine.
+ */
+export declare function buildArgsPatterns(argsPattern?: string, commandPrefix?: string | string[], commandRegex?: string): Array<string | undefined>;