@node9/policy-engine 1.67.0 → 1.67.2

package/dist/index.d.mts

@@ -166,6 +166,10 @@ declare function redactText(text: string): {
     found: string[];
 };
 
+/**
+ * The POSIX reading of a command. Kept as the single-string API every existing
+ * caller (canonical.ts, the detectors, `explain`) already depends on.
+ */
 declare function normalizeCommandForPolicy(command: string): string;
 /**
  * AST-based detection of dangerous shell execution patterns.
@@ -193,6 +197,31 @@ interface FsOpVerdict {
 declare const BASH_TOOL_NAMES: Set<string>;
 declare function isBashTool(toolName: string): boolean;
 declare const AST_FS_REGEX_RULES: Set<string>;
+/**
+ * Does `toolName` carry a shell command? True for BASH_TOOL_NAMES spellings and
+ * for any tool whose toolInspection field is `command` (e.g. `terminal.execute`).
+ *
+ * THE definition of "shell-shaped" — the gate, the CLI scan, and `explain` must
+ * all use this one, or they disagree about which rules apply to which tool
+ * (/code-review 2026-08-13: the gate reviewed `sudo …` on `shell` while scan
+ * reported nothing, so the customer-facing report under-counted).
+ */
+declare function isShellShapedTool(toolName: string, toolInspection?: Record<string, string>): boolean;
+/**
+ * Does a smart rule's `tool` scope cover this tool? Adds the shell-shape alias:
+ * the six default shell-safety rules and shield bundles are written
+ * `tool:'bash'`, and an agent's choice of tool-name spelling (`shell`,
+ * `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
+ * void them. An absent rule scope matches everything (callers' prior semantics).
+ */
+declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: Record<string, string>): boolean;
+/**
+ * AST-aware inline-execution detector. Returns true when the command runs code
+ * supplied on the command line, via stdin, or via a pipe into a bare
+ * interpreter. Structural, so it is not fooled by quoting, escapes, option
+ * bundles, or wrapper nesting. Pure.
+ */
+declare function detectInlineExec(command: string): boolean;
 /**
  * True when `path` is under $HOME (~ or absolute /home/* or /root) AND not in
  * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
@@ -367,6 +396,15 @@ interface PolicyContext {
     activeEnvironment?: {
         requireApproval?: boolean;
     };
+    /**
+     * Task #20: evaluate the full rule chain even for an ignoredTools match.
+     * Set by the orchestrator's jail guard AFTER it has already found a
+     * jailed/sensitive path in a file-tool call — without this, the tier-1
+     * fast path below returns 'allow' before the jail shield's `tool:'*'`
+     * rules are ever consulted, making the jail engine-invisible to
+     * Read/Grep/Glob. Opt-in per call; never set on the hot path.
+     */
+    skipIgnoredFastPath?: boolean;
 }
 type ProvenanceTrust = 'system' | 'managed' | 'user' | 'suspect' | 'unknown';
 interface ProvenanceLookup {
@@ -1079,7 +1117,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v6";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v8";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1090,7 +1128,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v6";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "a0e2bb339fe67e19";
+declare const CANONICAL_EXTRACTOR_HASH = "80f40f974263b281";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1117,4 +1155,4 @@ declare function previewArgs(input: Record<string, unknown>, max: number): strin
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -166,6 +166,10 @@ declare function redactText(text: string): {
     found: string[];
 };
 
+/**
+ * The POSIX reading of a command. Kept as the single-string API every existing
+ * caller (canonical.ts, the detectors, `explain`) already depends on.
+ */
 declare function normalizeCommandForPolicy(command: string): string;
 /**
  * AST-based detection of dangerous shell execution patterns.
@@ -193,6 +197,31 @@ interface FsOpVerdict {
 declare const BASH_TOOL_NAMES: Set<string>;
 declare function isBashTool(toolName: string): boolean;
 declare const AST_FS_REGEX_RULES: Set<string>;
+/**
+ * Does `toolName` carry a shell command? True for BASH_TOOL_NAMES spellings and
+ * for any tool whose toolInspection field is `command` (e.g. `terminal.execute`).
+ *
+ * THE definition of "shell-shaped" — the gate, the CLI scan, and `explain` must
+ * all use this one, or they disagree about which rules apply to which tool
+ * (/code-review 2026-08-13: the gate reviewed `sudo …` on `shell` while scan
+ * reported nothing, so the customer-facing report under-counted).
+ */
+declare function isShellShapedTool(toolName: string, toolInspection?: Record<string, string>): boolean;
+/**
+ * Does a smart rule's `tool` scope cover this tool? Adds the shell-shape alias:
+ * the six default shell-safety rules and shield bundles are written
+ * `tool:'bash'`, and an agent's choice of tool-name spelling (`shell`,
+ * `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
+ * void them. An absent rule scope matches everything (callers' prior semantics).
+ */
+declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: Record<string, string>): boolean;
+/**
+ * AST-aware inline-execution detector. Returns true when the command runs code
+ * supplied on the command line, via stdin, or via a pipe into a bare
+ * interpreter. Structural, so it is not fooled by quoting, escapes, option
+ * bundles, or wrapper nesting. Pure.
+ */
+declare function detectInlineExec(command: string): boolean;
 /**
  * True when `path` is under $HOME (~ or absolute /home/* or /root) AND not in
  * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
@@ -367,6 +396,15 @@ interface PolicyContext {
     activeEnvironment?: {
         requireApproval?: boolean;
     };
+    /**
+     * Task #20: evaluate the full rule chain even for an ignoredTools match.
+     * Set by the orchestrator's jail guard AFTER it has already found a
+     * jailed/sensitive path in a file-tool call — without this, the tier-1
+     * fast path below returns 'allow' before the jail shield's `tool:'*'`
+     * rules are ever consulted, making the jail engine-invisible to
+     * Read/Grep/Glob. Opt-in per call; never set on the hot path.
+     */
+    skipIgnoredFastPath?: boolean;
 }
 type ProvenanceTrust = 'system' | 'managed' | 'user' | 'suspect' | 'unknown';
 interface ProvenanceLookup {
@@ -1079,7 +1117,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v6";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v8";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1090,7 +1128,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v6";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "a0e2bb339fe67e19";
+declare const CANONICAL_EXTRACTOR_HASH = "80f40f974263b281";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1117,4 +1155,4 @@ declare function previewArgs(input: Record<string, unknown>, max: number): strin
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };