palaryn 0.1.0 → 0.3.2

package/src/policy/opa-engine.ts

@@ -0,0 +1,829 @@
+import * as http from 'http';
+import * as https from 'https';
+import { URL } from 'url';
+import { ToolCall } from '../types/tool-call';
+import { PolicyDecision, PolicyEvalResult, PolicyTransformation } from '../types/policy';
+import { OPAConfig } from '../types/config';
+
+/**
+ * OPA (Open Policy Agent) policy engine integration.
+ *
+ * Evaluates ToolCall objects against OPA policies either via:
+ *   1. Remote OPA server REST API (when server_url is configured)
+ *   2. Local lightweight Rego subset evaluator (when rego_policy is configured)
+ *
+ * OPA expects input in the format:
+ * {
+ *   "input": {
+ *     "tool_call_id": "...",
+ *     "task_id": "...",
+ *     "workspace_id": "...",
+ *     "actor": { "type": "agent", "id": "...", "display": "..." },
+ *     "source": { "platform": "...", "session_id": "..." },
+ *     "tool": { "name": "http.request", "version": "1.0", "capability": "read" },
+ *     "args": { "method": "GET", "url": "https://...", ... },
+ *     "constraints": { ... },
+ *     "context": { "purpose": "...", "labels": [...] },
+ *     "timestamp": "..."
+ *   }
+ * }
+ *
+ * OPA returns:
+ * {
+ *   "result": {
+ *     "decision": "allow" | "deny" | "transform" | "require_approval",
+ *     "rule_id": "opa_rule_xyz",
+ *     "rule_name": "...",
+ *     "reasons": ["..."],
+ *     "transformations": [...],
+ *     "approval": { "scope": "...", "ttl_seconds": 3600, "reason": "..." }
+ *   }
+ * }
+ */
+type CircuitState = 'closed' | 'open' | 'half-open';
+
+export class OPAEngine {
+  private config: OPAConfig;
+
+  // Circuit breaker state for remote OPA calls
+  private circuitState: CircuitState = 'closed';
+  private consecutiveFailures: number = 0;
+  private lastFailureTime: number = 0;
+  private readonly failureThreshold: number = 3;
+  private readonly recoveryTimeMs: number = 30000; // 30s cooldown
+
+  constructor(config: OPAConfig) {
+    this.config = {
+      policy_path: 'v1/data/palaryn/policy',
+      timeout_ms: 5000,
+      fallback_decision: 'deny',
+      package_name: 'palaryn.policy',
+      ...config,
+    };
+
+    // Validate and normalize server_url if provided
+    if (this.config.server_url) {
+      try {
+        const parsed = new URL(this.config.server_url);
+
+        // In production, require HTTPS to prevent credential exposure
+        if (process.env.NODE_ENV === 'production' && parsed.protocol !== 'https:') {
+          throw new Error(`OPA server URL must use HTTPS in production (got "${parsed.protocol}")`);
+        }
+
+        // Block private/reserved IP addresses to prevent SSRF via config
+        const hostname = parsed.hostname.toLowerCase();
+        if (this.isPrivateOPAHost(hostname)) {
+          // In production, block private IPs entirely
+          if (process.env.NODE_ENV === 'production') {
+            throw new Error(`OPA server URL must not use private/reserved IP address in production: "${hostname}"`);
+          }
+          // In development, allow but warn
+          console.warn(`[OPAEngine] WARNING: OPA server URL points to private address "${hostname}". This would be blocked in production.`);
+        }
+
+        // Normalize: remove trailing slashes for consistency
+        this.config.server_url = parsed.origin + parsed.pathname.replace(/\/+$/, '');
+      } catch (err) {
+        if (err instanceof Error && (err.message.includes('HTTPS in production') || err.message.includes('private/reserved IP'))) {
+          throw err;
+        }
+        throw new Error(`Invalid OPA server URL: "${this.config.server_url}". Must be a valid URL (e.g., "http://localhost:8181").`);
+      }
+    }
+  }
+
+  /**
+   * Evaluate a ToolCall against OPA policies.
+   * If server_url is configured, makes HTTP POST to OPA server.
+   * If rego_policy is configured (inline), evaluates locally.
+   */
+  async evaluate(toolCall: ToolCall): Promise<PolicyEvalResult> {
+    if (this.config.server_url) {
+      // Circuit breaker check for remote OPA
+      if (this.circuitState === 'open') {
+        if (Date.now() - this.lastFailureTime > this.recoveryTimeMs) {
+          // Try half-open: allow one request through
+          this.circuitState = 'half-open';
+        } else {
+          // Circuit open: immediate fallback, no HTTP call
+          return this.fallbackResult('OPA circuit breaker open: too many consecutive failures');
+        }
+      }
+      return this.evaluateRemote(toolCall);
+    }
+    if (this.config.rego_policy) {
+      return this.evaluateLocal(toolCall);
+    }
+    // No OPA configured, return fallback
+    return this.fallbackResult('OPA not configured: no server_url or rego_policy provided');
+  }
+
+  /**
+   * Evaluate against remote OPA server via REST API.
+   * POST ${server_url}/${policy_path} with { input: toolCall }
+   */
+  private async evaluateRemote(toolCall: ToolCall): Promise<PolicyEvalResult> {
+    const url = `${this.config.server_url}/${this.config.policy_path}`;
+    const input = this.buildInput(toolCall);
+
+    try {
+      const response = await this.httpPost(url, { input }, this.config.timeout_ms!);
+      const result = this.parseOPAResponse(response, toolCall);
+
+      // Success: reset circuit breaker
+      this.onSuccess();
+
+      return result;
+    } catch (err) {
+      // Failure: update circuit breaker
+      this.onFailure();
+
+      // OPA unreachable -- use fallback
+      const message = err instanceof Error ? err.message : String(err);
+      return this.fallbackResult(`OPA server error: ${message}`);
+    }
+  }
+
+  /**
+   * Evaluate inline Rego policy locally using a simple rule evaluator.
+   * This is a lightweight Rego subset evaluator -- NOT a full Rego runtime.
+   * Supports basic patterns that cover 80% of policy use cases:
+   * - package declaration
+   * - default decision rules (default decision = "deny")
+   * - Simple condition-based rules with equality checks
+   * - Array membership (input.tool.capability == "admin")
+   * - String matching patterns
+   */
+  private async evaluateLocal(toolCall: ToolCall): Promise<PolicyEvalResult> {
+    const input = this.buildInput(toolCall);
+    try {
+      const result = this.evaluateRegoSubset(this.config.rego_policy!, input);
+      return result;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return this.fallbackResult(`Rego evaluation error: ${message}`);
+    }
+  }
+
+  /**
+   * Lightweight Rego subset evaluator.
+   * Parses basic Rego rules and evaluates them against input.
+   *
+   * Supported Rego patterns:
+   * ```rego
+   * package palaryn.policy
+   *
+   * default decision = "deny"
+   * default rule_id = "opa_local"
+   * default rule_name = "OPA local evaluation"
+   *
+   * decision = "allow" {
+   *   input.tool.capability == "read"
+   * }
+   *
+   * decision = "deny" {
+   *   input.tool.name == "dangerous"
+   * }
+   *
+   * reasons[reason] {
+   *   input.tool.capability == "admin"
+   *   reason := "Admin capability requires approval"
+   * }
+   * ```
+   */
+  evaluateRegoSubset(policy: string, input: Record<string, unknown>): PolicyEvalResult {
+    const lines = policy.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#') && !l.startsWith('import'));
+
+    // Remove package declaration
+    const contentLines = lines.filter(l => !l.startsWith('package '));
+
+    // Parse default values
+    const defaults: Record<string, string> = {};
+    // Parse rules (blocks of the form: head = "value" { conditions })
+    const rules: Array<{ field: string; value: string; conditions: string[] }> = [];
+    // Parse reasons rules (reasons[reason] { ... reason := "..." })
+    const reasonRules: Array<{ conditions: string[]; reason: string }> = [];
+
+    // Join into one string to handle multi-line blocks
+    const joined = contentLines.join('\n');
+
+    // Parse defaults: default <field> = "<value>"
+    const defaultRegex = /default\s+(\w+)\s*=\s*"([^"]*)"/g;
+    let defaultMatch;
+    while ((defaultMatch = defaultRegex.exec(joined)) !== null) {
+      defaults[defaultMatch[1]] = defaultMatch[2];
+    }
+
+    // Parse rule blocks using brace-depth-aware extraction
+    const ruleBlocks = this.extractBraceBlocks(joined);
+    for (const block of ruleBlocks) {
+      // Check if this is a reasons collection rule
+      if (block.head.startsWith('reasons[reason]') || block.head.startsWith('reasons[')) {
+        const bodyLines = block.body.split('\n').map(l => l.trim()).filter(l => l);
+        const conditions: string[] = [];
+        let reason = '';
+        for (const line of bodyLines) {
+          const assignMatch = line.match(/^reason\s*:=\s*"([^"]*)"$/);
+          if (assignMatch) {
+            reason = assignMatch[1];
+          } else {
+            conditions.push(line);
+          }
+        }
+        if (reason) {
+          reasonRules.push({ conditions, reason });
+        }
+        continue;
+      }
+
+      // Parse field = "value" from the head
+      const headMatch = block.head.match(/^(\w+)\s*=\s*"([^"]*)"$/);
+      if (!headMatch) continue;
+
+      const field = headMatch[1];
+      const value = headMatch[2];
+      const conditions = block.body
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith('#') && !l.startsWith('reason'));
+
+      rules.push({ field, value, conditions });
+    }
+
+    // Wrap input for lookups (OPA uses input.X paths)
+    const evalContext = { input };
+
+    // Evaluate rules against input. First matching rule wins for each field.
+    const resolved: Record<string, string> = { ...defaults };
+
+    for (const rule of rules) {
+      // Only override if not already resolved by a higher-priority rule
+      // (rules are evaluated in order; first match wins for each field)
+      if (resolved[rule.field] !== undefined && resolved[rule.field] !== defaults[rule.field]) {
+        // Already resolved by a prior matching rule -- skip unless this is a different field
+        // Actually, in Rego, later matching rules can override. But for our subset,
+        // we want first-match-wins to match common policy patterns.
+        // However, we still need to check all rules since a deny can override an allow.
+        // Let's use last-match-wins to be more Rego-like.
+      }
+      if (this.evaluateConditions(rule.conditions, evalContext)) {
+        resolved[rule.field] = rule.value;
+      }
+    }
+
+    // Collect reasons
+    const reasons: string[] = [];
+    for (const rr of reasonRules) {
+      if (this.evaluateConditions(rr.conditions, evalContext)) {
+        reasons.push(rr.reason);
+      }
+    }
+
+    const decision = this.normalizeDecision(resolved['decision']);
+    const ruleId = resolved['rule_id'] || 'opa_local';
+    const ruleName = resolved['rule_name'] || 'OPA local evaluation';
+
+    if (reasons.length === 0) {
+      reasons.push(`OPA local decision: ${decision}`);
+    }
+
+    return {
+      decision,
+      rule_id: ruleId,
+      rule_name: ruleName,
+      reasons,
+    };
+  }
+
+  /**
+   * Evaluate a list of Rego conditions against the evaluation context.
+   * All conditions must be true (AND logic) for the rule to match.
+   *
+   * Supported condition patterns:
+   * - input.field.path == "value"     (equality)
+   * - input.field.path != "value"     (inequality)
+   * - input.field.path >= / <= / > / < value  (numeric comparisons)
+   * - input.field.path == true/false  (boolean)
+   * - input.field.path == 123         (number)
+   * - startswith(input.field, "prefix")
+   * - endswith(input.field, "suffix")
+   * - contains(input.field, "substring")
+   * - count(input.field) op value     (array/object/string length)
+   * - regex.match("pattern", input.field)  (regex matching)
+   * - is_string/is_number/is_boolean/is_array(input.field)  (type checks)
+   * - "value" in input.field          (array membership)
+   * - some x in input.field; x == "value"  (iteration with existential check)
+   * - input.field.path               (truthy check)
+   * - not input.field.path            (falsy check)
+   */
+  private evaluateConditions(conditions: string[], context: Record<string, unknown>): boolean {
+    if (conditions.length === 0) return true;
+
+    // Expand semicolon-separated conditions into individual conditions
+    const expanded: string[] = [];
+    for (const cond of conditions) {
+      if (cond.includes(';')) {
+        expanded.push(...cond.split(';').map(c => c.trim()).filter(c => c));
+      } else {
+        expanded.push(cond);
+      }
+    }
+
+    // Separate `some` iteration blocks from normal conditions.
+    // `some x in collection` introduces an existential quantifier:
+    // subsequent conditions referencing `x` must hold for at least one element.
+    const normalConditions: string[] = [];
+    const someBlocks: Array<{ varName: string; collectionPath: string; subConditions: string[] }> = [];
+    let currentSome: { varName: string; collectionPath: string; subConditions: string[] } | null = null;
+
+    for (const cond of expanded) {
+      const someMatch = cond.match(/^some\s+(\w+)\s+in\s+([\w.[\]]+)$/);
+      if (someMatch) {
+        // Finalize any previous some block
+        if (currentSome) {
+          someBlocks.push(currentSome);
+        }
+        currentSome = { varName: someMatch[1], collectionPath: someMatch[2], subConditions: [] };
+      } else if (currentSome && this.conditionReferencesVar(cond, currentSome.varName)) {
+        // This condition references the some variable -- attach to current block
+        currentSome.subConditions.push(cond);
+      } else {
+        // Finalize any pending some block before adding a normal condition
+        if (currentSome) {
+          someBlocks.push(currentSome);
+          currentSome = null;
+        }
+        normalConditions.push(cond);
+      }
+    }
+    if (currentSome) {
+      someBlocks.push(currentSome);
+    }
+
+    // Evaluate normal conditions (all must pass -- AND logic)
+    for (const cond of normalConditions) {
+      if (!this.evaluateSingleCondition(cond, context)) {
+        return false;
+      }
+    }
+
+    // Evaluate some blocks (existential: at least one element must satisfy all sub-conditions)
+    for (const block of someBlocks) {
+      const collection = this.resolveValue(block.collectionPath, context);
+      if (!Array.isArray(collection)) return false;
+
+      let anyMatch = false;
+      for (const element of collection) {
+        // Bind the iteration variable in a local context
+        const localContext = { ...context, [block.varName]: element };
+        const allSubCondsMet = block.subConditions.every(c =>
+          this.evaluateSingleCondition(c, localContext)
+        );
+        if (allSubCondsMet) {
+          anyMatch = true;
+          break;
+        }
+      }
+      if (!anyMatch) return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Check whether a condition string references a given variable name.
+   * Uses word-boundary detection to avoid false positives (e.g., "xray" matching "x").
+   */
+  private conditionReferencesVar(condition: string, varName: string): boolean {
+    const regex = new RegExp(`(?:^|[^\\w.])${varName}(?:[^\\w]|$)`);
+    return regex.test(condition);
+  }
+
+  /**
+   * Evaluate a single Rego condition.
+   */
+  private evaluateSingleCondition(condition: string, context: Record<string, unknown>): boolean {
+    const trimmed = condition.trim();
+    if (!trimmed) return true;
+
+    // Equality: input.path == "value"
+    const eqMatch = trimmed.match(/^([\w.[\]]+)\s*==\s*(.+)$/);
+    if (eqMatch) {
+      const left = this.resolveValue(eqMatch[1], context);
+      const right = this.parseRightValue(eqMatch[2].trim());
+      return left === right;
+    }
+
+    // Inequality: input.path != "value"
+    const neqMatch = trimmed.match(/^([\w.[\]]+)\s*!=\s*(.+)$/);
+    if (neqMatch) {
+      const left = this.resolveValue(neqMatch[1], context);
+      const right = this.parseRightValue(neqMatch[2].trim());
+      return left !== right;
+    }
+
+    // Numeric comparisons: >=, <=, >, <
+    const compMatch = trimmed.match(/^([\w.[\]]+)\s*(>=|<=|>|<)\s*(.+)$/);
+    if (compMatch) {
+      const left = this.resolveValue(compMatch[1], context);
+      const right = this.parseRightValue(compMatch[3].trim());
+      if (typeof left !== 'number' || typeof right !== 'number') return false;
+      switch (compMatch[2]) {
+        case '>=': return left >= right;
+        case '<=': return left <= right;
+        case '>': return left > right;
+        case '<': return left < right;
+      }
+    }
+
+    // startswith(input.path, "value")
+    const startsWithMatch = trimmed.match(/^startswith\(\s*([\w.[\]]+)\s*,\s*"([^"]*)"\s*\)$/);
+    if (startsWithMatch) {
+      const val = this.resolveValue(startsWithMatch[1], context);
+      if (typeof val !== 'string') return false;
+      return val.startsWith(startsWithMatch[2]);
+    }
+
+    // endswith(input.path, "value")
+    const endsWithMatch = trimmed.match(/^endswith\(\s*([\w.[\]]+)\s*,\s*"([^"]*)"\s*\)$/);
+    if (endsWithMatch) {
+      const val = this.resolveValue(endsWithMatch[1], context);
+      if (typeof val !== 'string') return false;
+      return val.endsWith(endsWithMatch[2]);
+    }
+
+    // contains(input.path, "value")
+    const containsMatch = trimmed.match(/^contains\(\s*([\w.[\]]+)\s*,\s*"([^"]*)"\s*\)$/);
+    if (containsMatch) {
+      const val = this.resolveValue(containsMatch[1], context);
+      if (typeof val !== 'string') return false;
+      return val.includes(containsMatch[2]);
+    }
+
+    // count(input.path) op value -- returns length of array, object keys, or string
+    const countMatch = trimmed.match(/^count\(\s*([\w.[\]]+)\s*\)\s*(==|!=|>=|<=|>|<)\s*(.+)$/);
+    if (countMatch) {
+      const val = this.resolveValue(countMatch[1], context);
+      const len = Array.isArray(val) ? val.length :
+                  (typeof val === 'object' && val !== null) ? Object.keys(val).length :
+                  (typeof val === 'string') ? val.length : 0;
+      const right = this.parseRightValue(countMatch[3].trim());
+      if (typeof right !== 'number') return false;
+      switch (countMatch[2]) {
+        case '==': return len === right;
+        case '!=': return len !== right;
+        case '>': return len > right;
+        case '<': return len < right;
+        case '>=': return len >= right;
+        case '<=': return len <= right;
+      }
+    }
+
+    // regex.match("pattern", input.path) -- regex pattern matching
+    const regexMatchPattern = trimmed.match(/^regex\.match\(\s*"([^"]*)"\s*,\s*([\w.[\]]+)\s*\)$/);
+    if (regexMatchPattern) {
+      const pattern = regexMatchPattern[1];
+      const val = this.resolveValue(regexMatchPattern[2], context);
+      if (typeof val !== 'string') return false;
+      try {
+        const re = new RegExp(pattern);
+        return re.test(val);
+      } catch {
+        return false;
+      }
+    }
+
+    // Type checks: is_string, is_number, is_boolean, is_array
+    const typeCheckMatch = trimmed.match(/^(is_string|is_number|is_boolean|is_array)\(\s*([\w.[\]]+)\s*\)$/);
+    if (typeCheckMatch) {
+      const val = this.resolveValue(typeCheckMatch[2], context);
+      switch (typeCheckMatch[1]) {
+        case 'is_string': return typeof val === 'string';
+        case 'is_number': return typeof val === 'number';
+        case 'is_boolean': return typeof val === 'boolean';
+        case 'is_array': return Array.isArray(val);
+      }
+    }
+
+    // Array membership: "value" in input.path  or  variable in input.path
+    const inMatch = trimmed.match(/^(.+)\s+in\s+([\w.[\]]+)$/);
+    if (inMatch) {
+      const leftRaw = inMatch[1].trim();
+      let left: unknown;
+      if (leftRaw.startsWith('"') && leftRaw.endsWith('"')) {
+        left = leftRaw.slice(1, -1);
+      } else if (leftRaw === 'true') {
+        left = true;
+      } else if (leftRaw === 'false') {
+        left = false;
+      } else if (leftRaw === 'null') {
+        left = null;
+      } else if (!isNaN(Number(leftRaw)) && leftRaw !== '') {
+        left = Number(leftRaw);
+      } else {
+        // Try to resolve as a path or variable reference
+        left = this.resolveValue(leftRaw, context);
+      }
+      const arr = this.resolveValue(inMatch[2], context);
+      if (Array.isArray(arr)) {
+        return arr.includes(left);
+      }
+      return false;
+    }
+
+    // Negation: not input.path
+    const notMatch = trimmed.match(/^not\s+([\w.[\]]+)$/);
+    if (notMatch) {
+      const val = this.resolveValue(notMatch[1], context);
+      return !val;
+    }
+
+    // Truthy check: input.path
+    if (/^[\w.[\]]+$/.test(trimmed)) {
+      const val = this.resolveValue(trimmed, context);
+      return !!val;
+    }
+
+    // Unknown condition format -- treat as non-match
+    return false;
+  }
+
+  /**
+   * Resolve a dot-notation path against the evaluation context.
+   * E.g., "input.tool.name" resolves to context.input.tool.name
+   */
+  private resolveValue(path: string, context: Record<string, unknown>): unknown {
+    return this.resolvePath(context, path);
+  }
+
+  /**
+   * Parse the right-hand side of a comparison.
+   * Handles quoted strings, booleans, numbers.
+   */
+  private parseRightValue(raw: string): unknown {
+    // Quoted string
+    const strMatch = raw.match(/^"([^"]*)"$/);
+    if (strMatch) return strMatch[1];
+
+    // Boolean
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+
+    // Null
+    if (raw === 'null') return null;
+
+    // Number
+    const num = Number(raw);
+    if (!isNaN(num) && raw !== '') return num;
+
+    // If it looks like a path, resolve it
+    if (/^[\w.[\]]+$/.test(raw)) {
+      return raw; // Return as-is (literal identifier)
+    }
+
+    return raw;
+  }
+
+  /** Convert ToolCall to OPA input format */
+  buildInput(toolCall: ToolCall): Record<string, unknown> {
+    return {
+      tool_call_id: toolCall.tool_call_id,
+      task_id: toolCall.task_id,
+      workspace_id: toolCall.workspace_id,
+      actor: toolCall.actor,
+      source: toolCall.source,
+      tool: toolCall.tool,
+      args: toolCall.args,
+      constraints: toolCall.constraints,
+      context: toolCall.context,
+      timestamp: toolCall.timestamp,
+    };
+  }
+
+  /** Parse OPA REST API response into PolicyEvalResult */
+  parseOPAResponse(response: any, toolCall: ToolCall): PolicyEvalResult {
+    const result = response?.result;
+    if (!result) {
+      return this.fallbackResult('OPA returned empty result');
+    }
+
+    const decision = this.normalizeDecision(result.decision);
+
+    return {
+      decision,
+      rule_id: result.rule_id || 'opa_policy',
+      rule_name: result.rule_name || 'OPA policy evaluation',
+      reasons: Array.isArray(result.reasons) ? result.reasons :
+               result.reasons ? [String(result.reasons)] :
+               [`OPA decision: ${decision}`],
+      transformations: Array.isArray(result.transformations) ? result.transformations : undefined,
+      approval: result.approval,
+    };
+  }
+
+  /** Normalize OPA decision string to PolicyDecision */
+  normalizeDecision(decision: string | undefined): PolicyDecision {
+    if (!decision) return this.config.fallback_decision || 'deny';
+    const lower = String(decision).toLowerCase();
+    if (['allow', 'deny', 'transform', 'require_approval'].includes(lower)) {
+      return lower as PolicyDecision;
+    }
+    // Common OPA patterns
+    if (lower === 'true' || lower === 'allowed') return 'allow';
+    if (lower === 'false' || lower === 'denied') return 'deny';
+    return this.config.fallback_decision || 'deny';
+  }
+
+  /** HTTP POST helper using built-in Node http/https */
+  httpPost(url: string, body: any, timeoutMs: number): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const parsed = new URL(url);
+      const transport = parsed.protocol === 'https:' ? https : http;
+      const data = JSON.stringify(body);
+
+      const req = transport.request({
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+        },
+        timeout: timeoutMs,
+      }, (res) => {
+        let responseData = '';
+        res.on('data', (chunk: string) => responseData += chunk);
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(responseData));
+          } catch {
+            reject(new Error(`Invalid JSON from OPA: ${responseData.substring(0, 200)}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('OPA request timed out')); });
+      req.write(data);
+      req.end();
+    });
+  }
+
+  /** Build fallback result when OPA is unreachable or not configured */
+  fallbackResult(reason: string): PolicyEvalResult {
+    return {
+      decision: this.config.fallback_decision || 'deny',
+      rule_id: 'opa_fallback',
+      rule_name: 'OPA fallback',
+      reasons: [reason],
+    };
+  }
+
+  /**
+   * Extract rule blocks using brace-depth tracking.
+   * Finds patterns like `head { body }` where body may contain nested braces.
+   * Returns array of { head, body } where head is the text before the opening brace
+   * and body is the content between the matched braces.
+   */
+  private extractBraceBlocks(text: string): Array<{ head: string; body: string }> {
+    const blocks: Array<{ head: string; body: string }> = [];
+    let i = 0;
+    while (i < text.length) {
+      // Find the next opening brace that is part of a rule (not inside a string)
+      const braceIdx = text.indexOf('{', i);
+      if (braceIdx === -1) break;
+
+      // Extract the head: text from the last statement boundary to the brace
+      // Walk backwards from braceIdx to find the start of the head
+      let headStart = braceIdx - 1;
+      // Skip whitespace before brace
+      while (headStart >= 0 && text[headStart] === ' ') headStart--;
+      // Find the beginning of this statement (after a newline or previous closing brace)
+      const searchStart = Math.max(0, i);
+      let lineStart = text.lastIndexOf('\n', headStart);
+      if (lineStart < searchStart) lineStart = searchStart;
+      else lineStart++; // skip the newline char
+
+      const head = text.substring(lineStart, braceIdx).trim();
+
+      // Skip if this looks like a default line or not a rule head
+      if (!head || head.startsWith('default ')) {
+        i = braceIdx + 1;
+        continue;
+      }
+
+      // Track brace depth to find the matching closing brace
+      let depth = 1;
+      let j = braceIdx + 1;
+      let inString = false;
+      while (j < text.length && depth > 0) {
+        const ch = text[j];
+        if (ch === '"' && (j === 0 || text[j - 1] !== '\\')) {
+          inString = !inString;
+        } else if (!inString) {
+          if (ch === '{') depth++;
+          else if (ch === '}') depth--;
+        }
+        if (depth > 0) j++;
+      }
+
+      if (depth === 0) {
+        const body = text.substring(braceIdx + 1, j).trim();
+        blocks.push({ head, body });
+        i = j + 1;
+      } else {
+        // Unmatched brace, skip
+        i = braceIdx + 1;
+      }
+    }
+    return blocks;
+  }
+
+  /** Resolve a dot-notation path against an object. E.g., "tool.name" -> obj.tool.name */
+  private resolvePath(obj: any, path: string): any {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+      if (current === undefined || current === null) return undefined;
+      current = current[part];
+    }
+    return current;
+  }
+
+  /** Check if OPA is configured and reachable */
+  async isAvailable(): Promise<boolean> {
+    if (!this.config.server_url) return !!this.config.rego_policy;
+    try {
+      const response = await this.httpPost(
+        `${this.config.server_url}/v1/data`,
+        { input: {} },
+        2000
+      );
+      return !!response;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Record a successful remote OPA call -- reset circuit breaker */
+  private onSuccess(): void {
+    this.consecutiveFailures = 0;
+    this.circuitState = 'closed';
+  }
+
+  /** Record a failed remote OPA call -- trip circuit if threshold reached */
+  private onFailure(): void {
+    this.consecutiveFailures++;
+    this.lastFailureTime = Date.now();
+    if (this.consecutiveFailures >= this.failureThreshold) {
+      this.circuitState = 'open';
+    }
+  }
+
+  /** Get the current circuit breaker state for monitoring */
+  getCircuitState(): { state: CircuitState; failures: number; lastFailure: number } {
+    return {
+      state: this.circuitState,
+      failures: this.consecutiveFailures,
+      lastFailure: this.lastFailureTime,
+    };
+  }
+
+  /** Reset the circuit breaker (for testing/admin) */
+  resetCircuit(): void {
+    this.circuitState = 'closed';
+    this.consecutiveFailures = 0;
+    this.lastFailureTime = 0;
+  }
+
+  /** Check if a hostname is a private/reserved IP address (SSRF protection for OPA config) */
+  private isPrivateOPAHost(hostname: string): boolean {
+    const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+
+    // IPv4 private ranges
+    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(bare)) {
+      const parts = bare.split('.').map(Number);
+      if (parts[0] === 127) return true; // loopback
+      if (parts[0] === 10) return true; // 10.0.0.0/8
+      if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true; // 172.16.0.0/12
+      if (parts[0] === 192 && parts[1] === 168) return true; // 192.168.0.0/16
+      if (parts[0] === 169 && parts[1] === 254) return true; // link-local
+      if (parts[0] === 0) return true; // 0.0.0.0/8
+    }
+
+    // IPv6 private ranges
+    if (bare === '::1') return true; // loopback
+    if (/^fe80:/i.test(bare)) return true; // link-local
+    if (/^f[cd]/i.test(bare)) return true; // unique local (fc00::/7)
+    if (/^ff/i.test(bare)) return true; // multicast
+
+    // Localhost aliases
+    if (bare === 'localhost' || bare === '0.0.0.0') return true;
+
+    return false;
+  }
+
+  getConfig(): OPAConfig { return this.config; }
+}