Policy Rule Validator

A utility that validates and evaluates policy rules for a CLI tool execution engine.

Overview

Build a policy rule validation system that can parse TOML-formatted policy rules and determine whether a given tool execution should be allowed, denied, or require user approval. The system should support priority-based matching, pattern matching on tool names and commands, and approval mode filtering.

Capabilities

Parse and validate TOML policy rules

• Parse a valid TOML rule with toolName "run_shell_command", commandRegex "^git push", decision "ask_user", priority 100, and modes ["autoEdit"] @test
• Throw an error when parsing TOML with missing required field "decision" @test
• Throw an error when parsing TOML with invalid decision value "maybe" (valid values are "allow", "deny", "ask_user") @test

Match tool names with wildcard patterns

• Match tool name "github__create_issue" against pattern "github__*" returns true @test
• Match tool name "run_shell_command" against exact pattern "run_shell_command" returns true @test
• Match tool name "read_file" against pattern "github__*" returns false @test

Evaluate rules based on priority

• Given two rules matching the same tool with priorities 50 and 100, apply the rule with priority 100 @test
• Given two rules with same priority 50, apply the first rule encountered @test

Filter rules by approval mode

• Rule with modes ["autoEdit", "yolo"] matches when current mode is "autoEdit" @test
• Rule with modes ["yolo"] does not match when current mode is "autoEdit" @test
• Rule with no modes specified matches any approval mode @test

Implementation

@generates

API

/**
 * Represents a policy rule for tool execution control
 */
export interface PolicyRule {
  toolName: string;
  commandRegex?: string;
  decision: 'allow' | 'deny' | 'ask_user';
  priority: number;
  modes?: string[];
}

/**
 * Parses TOML-formatted policy rules into PolicyRule objects
 *
 * @param tomlContent - TOML string containing rule definitions
 * @returns Array of parsed PolicyRule objects
 * @throws Error if TOML is invalid or missing required fields
 */
export function parseTomlRules(tomlContent: string): PolicyRule[];

/**
 * Checks if a tool name matches a pattern (supports wildcards)
 *
 * @param toolName - The actual tool name to check
 * @param pattern - Pattern to match against (supports * wildcard)
 * @returns true if the tool name matches the pattern
 */
export function matchesToolPattern(toolName: string, pattern: string): boolean;

/**
 * Evaluates which rule should apply for a given tool execution
 * Returns the highest priority matching rule, or null if no rules match
 *
 * @param rules - Array of policy rules to evaluate
 * @param toolName - Name of the tool being executed
 * @param command - Optional command string (for shell tools)
 * @param approvalMode - Current approval mode (e.g., "default", "autoEdit", "yolo")
 * @returns The matching PolicyRule with highest priority, or null
 */
export function evaluatePolicy(
  rules: PolicyRule[],
  toolName: string,
  command: string | null,
  approvalMode: string
): PolicyRule | null;

Dependencies { .dependencies }

@iarna/toml { .dependency }

Provides TOML parsing functionality for reading policy rule files.