@node9/policy-engine 1.45.0 → 1.47.0

package/dist/index.d.mts

@@ -49,6 +49,19 @@ interface SmartRule {
      * permanently destroy teammates' work."
      */
     description?: string;
+    /**
+     * Provenance of a synced cloud rule, e.g. "SHIELD:aws" or "USER". Shipped by
+     * the SaaS so the proxy can attribute a rule to its origin shield (so
+     * `node9 shield list` can show a shield as cloud-enabled). Absent on local rules.
+     */
+    source?: string;
+    /**
+     * Manager "pinned" rule (Phase 3b): when set, this rule wins a conflict — a
+     * developer's local rule can't override it. Cloud-authored + admin-gated;
+     * local rules never set it. See resolvePinned. Default unset = a normal rule,
+     * resolved exactly as today (first match wins).
+     */
+    pinned?: boolean;
 }
 /**
  * Result of a DLP scan — either a single match or null. The redactedSample
@@ -365,6 +378,19 @@ interface PolicyVerdict {
     /** Plain-English description of what the rule does (from SmartRule.description). */
     ruleDescription?: string;
 }
+/**
+ * Resolve which of several MATCHING smart rules decides the verdict (the
+ * pinned-only conflict engine, Phase 3b). The model:
+ *   1. If any matching rule is `pinned` (a manager "keep mine" cloud rule),
+ *      only the pinned rules compete and the MOST-RESTRICTIVE pinned wins
+ *      (block > review > allow) — so a manager's locked rule can't be
+ *      overridden by a developer's local rule.
+ *   2. Otherwise the FIRST match wins — byte-for-byte the previous `.find()`
+ *      behaviour. This is the zero-regression guarantee: with nothing pinned,
+ *      nothing changes.
+ * Exported so the resolution is unit-testable in isolation.
+ */
+declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
 /**
  * Checks a SQL string for dangerous unscoped mutations.
  * Returns a reason string if dangerous, null if safe.
@@ -1029,4 +1055,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, 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, 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, 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 };

package/dist/index.d.ts

@@ -49,6 +49,19 @@ interface SmartRule {
      * permanently destroy teammates' work."
      */
     description?: string;
+    /**
+     * Provenance of a synced cloud rule, e.g. "SHIELD:aws" or "USER". Shipped by
+     * the SaaS so the proxy can attribute a rule to its origin shield (so
+     * `node9 shield list` can show a shield as cloud-enabled). Absent on local rules.
+     */
+    source?: string;
+    /**
+     * Manager "pinned" rule (Phase 3b): when set, this rule wins a conflict — a
+     * developer's local rule can't override it. Cloud-authored + admin-gated;
+     * local rules never set it. See resolvePinned. Default unset = a normal rule,
+     * resolved exactly as today (first match wins).
+     */
+    pinned?: boolean;
 }
 /**
  * Result of a DLP scan — either a single match or null. The redactedSample
@@ -365,6 +378,19 @@ interface PolicyVerdict {
     /** Plain-English description of what the rule does (from SmartRule.description). */
     ruleDescription?: string;
 }
+/**
+ * Resolve which of several MATCHING smart rules decides the verdict (the
+ * pinned-only conflict engine, Phase 3b). The model:
+ *   1. If any matching rule is `pinned` (a manager "keep mine" cloud rule),
+ *      only the pinned rules compete and the MOST-RESTRICTIVE pinned wins
+ *      (block > review > allow) — so a manager's locked rule can't be
+ *      overridden by a developer's local rule.
+ *   2. Otherwise the FIRST match wins — byte-for-byte the previous `.find()`
+ *      behaviour. This is the zero-regression guarantee: with nothing pinned,
+ *      nothing changes.
+ * Exported so the resolution is unit-testable in isolation.
+ */
+declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
 /**
  * Checks a SQL string for dangerous unscoped mutations.
  * Returns a reason string if dangerous, null if safe.
@@ -1029,4 +1055,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, 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, 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, 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 };

package/dist/index.js

@@ -92,6 +92,7 @@ __export(src_exports, {
   parseDestHost: () => parseDestHost,
   previewArgs: () => previewArgs,
   redactText: () => redactText,
+  resolvePinned: () => resolvePinned,
   scanArgs: () => scanArgs,
   scanInjection: () => scanInjection,
   scanText: () => scanText,
@@ -2083,6 +2084,19 @@ function evaluateSmartConditions(args, rule) {
 }
 
 // src/policy/index.ts
+var VERDICT_RANK = {
+  allow: 0,
+  review: 1,
+  block: 2
+};
+function resolvePinned(matches) {
+  if (matches.length === 0) return void 0;
+  const pinned = matches.filter((r) => r.pinned);
+  if (pinned.length === 0) return matches[0];
+  return pinned.reduce(
+    (best, r) => VERDICT_RANK[r.verdict] > VERDICT_RANK[best.verdict] ? r : best
+  );
+}
 function tokenize2(toolName) {
   return toolName.toLowerCase().split(/[_.\-\s]+/).filter(Boolean);
 }
@@ -2204,9 +2218,10 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     }
   }
   if (config.policy.smartRules.length > 0) {
-    const matchedRule = config.policy.smartRules.find(
+    const matches = config.policy.smartRules.filter(
       (rule) => matchesPattern(toolName, rule.tool) && !(bashCommand !== null && rule.name && AST_FS_REGEX_RULES.has(rule.name)) && evaluateSmartConditions(args, rule)
     );
+    const matchedRule = resolvePinned(matches);
     if (matchedRule) {
       if (matchedRule.verdict === "allow")
         return { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
@@ -3929,6 +3944,7 @@ var ENGINE_VERSION = "1.4.0";
   parseDestHost,
   previewArgs,
   redactText,
+  resolvePinned,
   scanArgs,
   scanInjection,
   scanText,

package/dist/index.mjs

@@ -1975,6 +1975,19 @@ function evaluateSmartConditions(args, rule) {
 }
 
 // src/policy/index.ts
+var VERDICT_RANK = {
+  allow: 0,
+  review: 1,
+  block: 2
+};
+function resolvePinned(matches) {
+  if (matches.length === 0) return void 0;
+  const pinned = matches.filter((r) => r.pinned);
+  if (pinned.length === 0) return matches[0];
+  return pinned.reduce(
+    (best, r) => VERDICT_RANK[r.verdict] > VERDICT_RANK[best.verdict] ? r : best
+  );
+}
 function tokenize2(toolName) {
   return toolName.toLowerCase().split(/[_.\-\s]+/).filter(Boolean);
 }
@@ -2096,9 +2109,10 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     }
   }
   if (config.policy.smartRules.length > 0) {
-    const matchedRule = config.policy.smartRules.find(
+    const matches = config.policy.smartRules.filter(
       (rule) => matchesPattern(toolName, rule.tool) && !(bashCommand !== null && rule.name && AST_FS_REGEX_RULES.has(rule.name)) && evaluateSmartConditions(args, rule)
     );
+    const matchedRule = resolvePinned(matches);
     if (matchedRule) {
       if (matchedRule.verdict === "allow")
         return { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
@@ -3820,6 +3834,7 @@ export {
   parseDestHost,
   previewArgs,
   redactText,
+  resolvePinned,
   scanArgs,
   scanInjection,
   scanText,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node9/policy-engine",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "description": "Shared policy evaluation engine for node9 — DLP, smart rules, AST shell parsing, shields, loop detection. Pure functions, no I/O. Used by both node9-proxy and the node9 SaaS firewall.",
   "license": "Apache-2.0",
   "homepage": "https://node9.ai",