@highflame/policy 2.1.37 → 2.1.39

package/dist/aarm-annotations.gen.d.ts

@@ -0,0 +1,82 @@
+export declare const AARM_ANNOTATION_REGISTRY_VERSION = "1.0.0";
+export declare const AARM_ANNOTATION_REGISTRY_INTRODUCED_IN = "R4";
+export declare const AARM_ANNOTATION_REGISTRY_SPEC_URL = "https://aarm.dev/conformance/requirements";
+/**
+* Declared runtime type of an AARM annotation parameter.
+* Constrained to the four primitives the registry parser allows.
+*/
+export type AARMParameterType = 'string' | 'int' | 'float' | 'bool';
+/**
+* Typed parameter value used in Default / Min / Max. Discriminator
+* matches `AARMParameterType`; consumers should type-narrow on the
+* `kind` field rather than reading `value` directly.
+*/
+export type AARMParameterValue = {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'int';
+    value: number;
+} | {
+    kind: 'float';
+    value: number;
+} | {
+    kind: 'bool';
+    value: boolean;
+};
+/** One parameter on an AARM annotation. */
+export interface AARMParameterDef {
+    name: string;
+    type: AARMParameterType;
+    required: boolean;
+    positional: boolean;
+    description: string;
+    /** Default value when the parameter is omitted; null for required. */
+    default: AARMParameterValue | null;
+    /** Inclusive lower bound for int/float; null otherwise. */
+    min: AARMParameterValue | null;
+    /** Inclusive upper bound for int/float; null otherwise. */
+    max: AARMParameterValue | null;
+    /** Regex pattern (for string parameters); empty string when unset. */
+    pattern: string;
+    /** Runtime source identifier for typeahead (e.g. 'authn.roles'). */
+    valueSource: string;
+}
+/**
+* One entry in the platform's annotation registry.
+*
+*  - `key` is the @<name> bare identifier as it appears in Cedar policy text.
+*  - `decisionEffect`, when non-empty, names the Shield decision this
+*    annotation drives ('step_up' | 'defer' | 'modify').
+*  - `promotesCapability`, when non-empty, names the capabilities.yaml
+*    row that becomes implementable once Shield emits the named effect.
+*  - `parameters` preserve the order produced by the registry parser:
+*    the positional parameter (if any) first, then the rest alphabetically.
+*/
+export interface AARMAnnotationDef {
+    key: string;
+    description: string;
+    aarmRequirement: string;
+    promotesCapability: string;
+    decisionEffect: string;
+    parameters: AARMParameterDef[];
+}
+/**
+ * Authoritative annotation registry. Treat as read-only —
+ * mutation is a programming error.
+ */
+export declare const AARM_ANNOTATIONS: readonly AARMAnnotationDef[];
+/**
+* O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw
+* policy annotations against the registry; the array form is for
+* iteration and stable order.
+*
+* The backing object is built with `Object.create(null)` so a
+* registry author who somehow lands `__proto__` / `constructor` /
+* `hasOwnProperty` as an annotation key (rejected by the Rust
+* registry validator, but defense-in-depth) cannot prototype-
+* pollute the lookup. `Object.freeze` is applied on top to lock
+* the top-level key set; consumers should still treat values as
+* immutable (see the `as const` literal types above).
+*/
+export declare const AARM_ANNOTATION_BY_KEY: Readonly<Record<string, AARMAnnotationDef>>;

package/dist/aarm-annotations.gen.js

@@ -0,0 +1,117 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schemas/annotations.json
+//
+// AARM-aware annotation registry. Single source of truth for the
+// annotations Shield's scheduler interprets at evaluation time and
+// that Studio's editor surfaces for autocomplete/lint. Generic Cedar
+// annotations (@id, @name, @description, @severity, @tags) remain
+// free-form and are unrelated.
+export const AARM_ANNOTATION_REGISTRY_VERSION = '1.0.0';
+export const AARM_ANNOTATION_REGISTRY_INTRODUCED_IN = 'R4';
+export const AARM_ANNOTATION_REGISTRY_SPEC_URL = 'https://aarm.dev/conformance/requirements';
+/**
+ * Authoritative annotation registry. Treat as read-only —
+ * mutation is a programming error.
+ */
+export const AARM_ANNOTATIONS = [
+    {
+        key: 'defer_below_confidence',
+        description: 'Defer the decision when ANY detector this policy conditions on returned a confidence below the threshold. AARM R3 DEFER on low confidence: prevents both false-positive blocks and false-negative permits at the gray-zone boundary, suspending until a stronger signal arrives.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [
+            {
+                name: 'threshold',
+                type: 'float',
+                required: true,
+                positional: true,
+                description: 'Confidence threshold in [0.0, 1.0]. Detector scores strictly less than this value trigger a deferral. 0.0 disables (matches no detector). 1.0 always defers.',
+                default: null,
+                min: { kind: 'float', value: 0.0 },
+                max: { kind: 'float', value: 1.0 },
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
+    {
+        key: 'defer_on_conflict',
+        description: 'Defer the decision when two or more equal-priority `forbid` rules disagree about whether to block this action. AARM R3 + R4 DEFER on policy conflict: the scheduler suspends rather than picking deny-by-default, so a policy author can resolve the conflict explicitly. Default behavior absent this annotation remains deny-overrides.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [],
+    },
+    {
+        key: 'defer_until_context',
+        description: 'Defer the decision when a named Cedar context field is null, missing, or the empty string. AARM R3 DEFER on missing context: lets the policy author require a populated field (e.g. `session_max_sensitivity`, `agent_identity_verified`) before letting a decision land, suspending the action rather than evaluating against a half-built session.',
+        aarmRequirement: 'R3',
+        promotesCapability: 'CAP-ENF-005',
+        decisionEffect: 'defer',
+        parameters: [
+            {
+                name: 'field',
+                type: 'string',
+                required: true,
+                positional: true,
+                description: 'Dotted Cedar context-attribute path (e.g. `session_max_sensitivity`, `agent.identity_verified`). Matched against the request\'s projected context at evaluation time.',
+                default: null,
+                min: null,
+                max: null,
+                pattern: '^[a-zA-Z_][a-zA-Z0-9_.]*$',
+                valueSource: '',
+            },
+        ],
+    },
+    {
+        key: 'step_up_required',
+        description: 'Suspend the action pending human approval from an approver with the named role. AARM R4 STEP_UP decision: action does not execute until POST /v1/approvals/{id}/resolve returns allow, OR timeout_seconds elapses (fail-closed: timeout DENYs the action, never permits).',
+        aarmRequirement: 'R4',
+        promotesCapability: 'CAP-ENF-004',
+        decisionEffect: 'step_up',
+        parameters: [
+            {
+                name: 'role',
+                type: 'string',
+                required: true,
+                positional: true,
+                description: 'AuthN role string the approver must carry (e.g. "finance_lead", "security_oncall"). Validated against authn.roles at deploy time; unknown roles reject the policy.',
+                default: null,
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: 'authn.roles',
+            },
+            {
+                name: 'timeout_seconds',
+                type: 'int',
+                required: false,
+                positional: false,
+                description: 'Seconds the action waits for approval before fail-closed DENY. Default 24h (86400s); bounded [60s, 7d].',
+                default: { kind: 'int', value: 86400 },
+                min: { kind: 'int', value: 60 },
+                max: { kind: 'int', value: 604800 },
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
+];
+/**
+* O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw
+* policy annotations against the registry; the array form is for
+* iteration and stable order.
+*
+* The backing object is built with `Object.create(null)` so a
+* registry author who somehow lands `__proto__` / `constructor` /
+* `hasOwnProperty` as an annotation key (rejected by the Rust
+* registry validator, but defense-in-depth) cannot prototype-
+* pollute the lookup. `Object.freeze` is applied on top to lock
+* the top-level key set; consumers should still treat values as
+* immutable (see the `as const` literal types above).
+*/
+export const AARM_ANNOTATION_BY_KEY = Object.freeze(AARM_ANNOTATIONS.reduce((acc, ann) => {
+    acc[ann.key] = ann;
+    return acc;
+}, Object.create(null)));

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+export * from './aarm-annotations.gen.js';
 export * from './engine.js';
 export * from './builder.js';
 export * from './parser.js';

package/dist/index.js

@@ -7,6 +7,9 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+// AARM-aware annotation registry (typed Cedar annotation vocabulary
+// Shield interprets at decision time; Studio/Admin use for lint).
+export * from './aarm-annotations.gen.js';
 // Non-generated modules (require Node.js)
 export * from './engine.js';
 export * from './builder.js';

package/dist/overwatch-defaults.gen.js

@@ -171,17 +171,21 @@ when {
 
 @id("data-protection.block-env-file-paths")
 @name("Block dotenv file access")
-@description("Blocks read_file and write_file when path matches *.env*.")
+@description("Blocks read_file and write_file when path matches a .env file or .env.<suffix> variant.")
 @severity("high")
 @tags("category:data-protection,threat:secrets,detection:pattern,compliance:nist-si-3")
-@reject_message("File access blocked: .env file targeted — these files typically contain secrets and database credentials.")
+@reject_message("File access blocked: .env file targeted, these files typically contain secrets and database credentials.")
 forbid (
     principal,
     action in [Overwatch::Action::"read_file", Overwatch::Action::"write_file"],
     resource
 )
 when {
-    context has path && context.path like "*.env*"
+    context has path &&
+    (
+        context.path like "*.env" ||
+        context.path like "*.env.*"
+    )
 };
 `;
 const OVERWATCH_SEMANTIC_DEFAULTS_CEDAR = `// =============================================================================
@@ -455,58 +459,60 @@ when {
 const OVERWATCH_TOOLS_DEFAULTS_CEDAR = `// =============================================================================
 // Tool Permissioning (Default)
 // =============================================================================
-// Controls IDE tool execution, shell access, sensitive file system paths, and
-// threat-severity-based blocking. Sections 1–2 are opt-in (inactive unless
-// explicitly enabled); sections 3–4 are active baseline.
+// Sensitive system-path file access and destructive MCP file-operation
+// blocking. Shell-execution blocking lives in tools_shell_block.cedar as a
+// separate opt-in template and is not bundled with this default.
 //
 // Context keys consumed:
-//   - tool_name:           String
-//   - path:                String
-//   - max_threat_severity: Long (0-4)
+//   - path:      String
+//   - tool_name: String
 //
 // Compliance:
 //   - NIST 800-53 AC-3, AC-6, CM-7
-//   - OWASP LLM06, OWASP ASI02
-//   - MITRE ATT&CK T1059, T1005
+//   - OWASP ASI02; MITRE ATT&CK T1005
 //
 // Category:  tools
 // Namespace: Overwatch
 // =============================================================================
 
 // ---------------------------------------------------------------------------
-// Section 1: Shell execution (opt-in)
+// Section 1: Sensitive system paths
 // ---------------------------------------------------------------------------
 
-@id("tools.block-shell")
-@name("Block shell and command execution")
-@description("Blocks call_tool when tool_name is shell, bash, sh, terminal, cmd, or powershell.")
-@severity("critical")
-@tags("category:tools,threat:command-injection,detection:rule,surface:call-tool,owasp:llm06,mitre:t1059")
-@reject_message("Tool execution blocked: shell/command execution is restricted in this environment.")
+@id("tools.block-system-paths")
+@name("Block system directory access")
+@description("Blocks read_file and write_file when path matches a sensitive Linux or macOS system directory.")
+@severity("high")
+@tags("category:tools,threat:path-traversal,detection:pattern,mitre:t1005")
+@reject_message("File access blocked: sensitive system directory targeted (/etc, /proc, /sys, /root, /var, /System, /Library, /private).")
 forbid (
     principal,
-    action == Overwatch::Action::"call_tool",
+    action in [Overwatch::Action::"read_file", Overwatch::Action::"write_file"],
     resource
 )
 when {
-    context has tool_name &&
+    context has path &&
     (
-        context.tool_name == "shell" ||
-        context.tool_name == "bash" ||
-        context.tool_name == "sh" ||
-        context.tool_name == "terminal" ||
-        context.tool_name == "cmd" ||
-        context.tool_name == "powershell"
+        context.path like "/etc/*" ||
+        context.path like "/proc/*" ||
+        context.path like "/sys/*" ||
+        context.path like "/root/*" ||
+        context.path like "/var/log/*" ||
+        context.path like "/var/run/*" ||
+        context.path like "/private/etc/*" ||
+        context.path like "/private/var/*" ||
+        context.path like "/Library/*" ||
+        context.path like "/System/*"
     )
 };
 
 // ---------------------------------------------------------------------------
-// Section 2: Destructive file operations (opt-in)
+// Section 2: Destructive MCP file operations
 // ---------------------------------------------------------------------------
 
 @id("tools.block-destructive-ops")
 @name("Block destructive file operations")
-@description("Blocks call_tool when tool_name is a destructive file operation.")
+@description("Blocks call_tool when tool_name is a destructive MCP file operation.")
 @severity("high")
 @tags("category:tools,detection:rule,surface:call-tool,owasp:asi02")
 @reject_message("Tool execution blocked: destructive file operations (delete, rmdir, unlink) require explicit human approval.")
@@ -526,56 +532,47 @@ when {
         context.tool_name == "remove_directory"
     )
 };
+`;
+const OVERWATCH_TOOLS_BLOCK_SHELL_CEDAR = `// =============================================================================
+// Tool Permissioning — Shell execution block (Opt-in)
+// =============================================================================
+// Blocks shell and command execution tools. Inactive unless explicitly enabled
+// because it blocks ALL shell access (including safe commands like git and
+// echo). Intended for high-security environments where shell access is
+// prohibited.
+//
+// Context keys consumed:
+//   - tool_name: String
+//
+// Compliance:
+//   - NIST 800-53 CM-7; OWASP LLM06; MITRE ATT&CK T1059
+//
+// Category:  tools
+// Namespace: Overwatch
+// =============================================================================
 
-// ---------------------------------------------------------------------------
-// Section 3: Sensitive system paths (active)
-// ---------------------------------------------------------------------------
-
-@id("tools.block-system-paths")
-@name("Block system directory access")
-@description("Blocks read_file and write_file when path matches a sensitive Linux or macOS system directory.")
-@severity("high")
-@tags("category:tools,threat:path-traversal,detection:pattern,mitre:t1005")
-@reject_message("File access blocked: sensitive system directory targeted (/etc, /proc, /sys, /root, /var, /System, /Library, /private).")
+@id("tools.block-shell")
+@name("Block shell and command execution")
+@description("Blocks call_tool when tool_name is shell, bash, sh, terminal, cmd, or powershell.")
+@severity("critical")
+@tags("category:tools,threat:command-injection,detection:rule,surface:call-tool,owasp:llm06,mitre:t1059")
+@reject_message("Tool execution blocked: shell/command execution is restricted in this environment.")
 forbid (
     principal,
-    action in [Overwatch::Action::"read_file", Overwatch::Action::"write_file"],
+    action == Overwatch::Action::"call_tool",
     resource
 )
 when {
-    context has path &&
+    context has tool_name &&
     (
-        context.path like "/etc/*" ||
-        context.path like "/proc/*" ||
-        context.path like "/sys/*" ||
-        context.path like "/root/*" ||
-        context.path like "/var/log/*" ||
-        context.path like "/var/run/*" ||
-        context.path like "/private/etc/*" ||
-        context.path like "/private/var/*" ||
-        context.path like "/Library/*" ||
-        context.path like "/System/*"
+        context.tool_name == "shell" ||
+        context.tool_name == "bash" ||
+        context.tool_name == "sh" ||
+        context.tool_name == "terminal" ||
+        context.tool_name == "cmd" ||
+        context.tool_name == "powershell"
     )
 };
-
-// ---------------------------------------------------------------------------
-// Section 4: Threat-severity catch-all
-// ---------------------------------------------------------------------------
-
-@id("tools.block-high-severity")
-@name("Block high-severity tool calls")
-@description("Blocks call_tool when max_threat_severity >= 3.")
-@severity("high")
-@tags("category:tools,detection:aggregate,surface:call-tool,posture:catch-all")
-@reject_message("Tool execution blocked: high or critical severity threats detected in content.")
-forbid (
-    principal,
-    action == Overwatch::Action::"call_tool",
-    resource
-)
-when {
-    context has max_threat_severity && context.max_threat_severity >= 3
-};
 `;
 const OVERWATCH_PRIVACY_DEFAULTS_CEDAR = `// =============================================================================
 // PII Detection (Default)
@@ -1036,11 +1033,20 @@ export const OVERWATCH_TEMPLATES = [
     {
         id: 'tools.defaults',
         name: 'Tool Permissioning',
-        description: 'Block sensitive system paths and tool calls with high-severity threats; opt-in shell and destructive-op blocking.',
+        description: 'Block sensitive system-path file access and destructive MCP file-operation tools.',
         category: 'tools',
         cedarText: OVERWATCH_TOOLS_DEFAULTS_CEDAR,
+        severity: 'high',
+        tags: ['category:tools', 'threat:path-traversal', 'detection:pattern', 'mitre:t1005', 'owasp:asi02'],
+    },
+    {
+        id: 'tools.block-shell',
+        name: 'Block shell and command execution',
+        description: 'Blocks call_tool when tool_name is shell, bash, sh, terminal, cmd, or powershell.',
+        category: 'tools',
+        cedarText: OVERWATCH_TOOLS_BLOCK_SHELL_CEDAR,
         severity: 'critical',
-        tags: ['category:tools', 'threat:command-injection', 'owasp:llm06'],
+        tags: ['category:tools', 'threat:command-injection', 'detection:rule', 'surface:call-tool', 'owasp:llm06', 'mitre:t1059'],
     },
     {
         id: 'privacy.defaults',
@@ -1190,7 +1196,13 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "semantic",
       "file": "defaults/semantic.cedar",
       "severity": "critical",
-      "tags": ["category:semantic", "threat:injection", "threat:jailbreak", "owasp:llm01", "owasp:llm02"]
+      "tags": [
+        "category:semantic",
+        "threat:injection",
+        "threat:jailbreak",
+        "owasp:llm01",
+        "owasp:llm02"
+      ]
     },
     {
       "id": "trust-safety.defaults",
@@ -1199,16 +1211,43 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "trust-safety",
       "file": "defaults/content_safety.cedar",
       "severity": "critical",
-      "tags": ["category:trust-safety", "threat:harmful", "compliance:eu-ai-act", "compliance:iso-42001"]
+      "tags": [
+        "category:trust-safety",
+        "threat:harmful",
+        "compliance:eu-ai-act",
+        "compliance:iso-42001"
+      ]
     },
     {
       "id": "tools.defaults",
       "name": "Tool Permissioning",
-      "description": "Block sensitive system paths and tool calls with high-severity threats; opt-in shell and destructive-op blocking.",
+      "description": "Block sensitive system-path file access and destructive MCP file-operation tools.",
       "category": "tools",
       "file": "defaults/tools.cedar",
+      "severity": "high",
+      "tags": [
+        "category:tools",
+        "threat:path-traversal",
+        "detection:pattern",
+        "mitre:t1005",
+        "owasp:asi02"
+      ]
+    },
+    {
+      "id": "tools.block-shell",
+      "name": "Block shell and command execution",
+      "description": "Blocks call_tool when tool_name is shell, bash, sh, terminal, cmd, or powershell.",
+      "category": "tools",
+      "file": "tools_shell_block.cedar",
       "severity": "critical",
-      "tags": ["category:tools", "threat:command-injection", "owasp:llm06"]
+      "tags": [
+        "category:tools",
+        "threat:command-injection",
+        "detection:rule",
+        "surface:call-tool",
+        "owasp:llm06",
+        "mitre:t1059"
+      ]
     },
     {
       "id": "privacy.defaults",
@@ -1217,7 +1256,13 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "privacy",
       "file": "defaults/pii.cedar",
       "severity": "critical",
-      "tags": ["category:privacy", "threat:pii", "compliance:pci-dss", "compliance:gdpr", "compliance:hipaa"]
+      "tags": [
+        "category:privacy",
+        "threat:pii",
+        "compliance:pci-dss",
+        "compliance:gdpr",
+        "compliance:hipaa"
+      ]
     },
     {
       "id": "tools.mcp-server-allowlist",
@@ -1235,7 +1280,11 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "tools",
       "file": "mcp_tool_permissions.cedar",
       "severity": "critical",
-      "tags": ["category:tools", "threat:supply-chain", "posture:permit-default"]
+      "tags": [
+        "category:tools",
+        "threat:supply-chain",
+        "posture:permit-default"
+      ]
     },
     {
       "id": "organization.deny-baseline",
@@ -1244,7 +1293,11 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "organization",
       "file": "default_deny_all.cedar",
       "severity": "high",
-      "tags": ["category:organization", "posture:deny-default", "scope:org-wide"]
+      "tags": [
+        "category:organization",
+        "posture:deny-default",
+        "scope:org-wide"
+      ]
     },
     {
       "id": "organization.audit-all",
@@ -1253,7 +1306,11 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "organization",
       "file": "audit_all_actions.cedar",
       "severity": "low",
-      "tags": ["category:organization", "posture:permit-default", "compliance:soc2"]
+      "tags": [
+        "category:organization",
+        "posture:permit-default",
+        "compliance:soc2"
+      ]
     },
     {
       "id": "organization.team-permissions",
@@ -1262,7 +1319,11 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "organization",
       "file": "team_permissions.cedar",
       "severity": "medium",
-      "tags": ["category:organization", "scope:per-tool", "posture:deny-default"]
+      "tags": [
+        "category:organization",
+        "scope:per-tool",
+        "posture:deny-default"
+      ]
     },
     {
       "id": "agent-identity.agent-guardrails",
@@ -1271,7 +1332,12 @@ export const OVERWATCH_TEMPLATES_JSON = `{
       "category": "agent-identity",
       "file": "agent_guardrails.cedar",
       "severity": "critical",
-      "tags": ["category:agent-identity", "scope:per-agent", "threat:injection", "threat:pii"]
+      "tags": [
+        "category:agent-identity",
+        "scope:per-agent",
+        "threat:injection",
+        "threat:pii"
+      ]
     }
   ]
 }

package/dist/types.d.ts

@@ -2,6 +2,7 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+export * from './aarm-annotations.gen.js';
 export * from './builder.js';
 export * from './errors.js';
 export * from './annotations.js';

package/dist/types.js

@@ -9,6 +9,9 @@ export * from './entities.gen.js';
 export * from './actions.gen.js';
 export * from './context.gen.js';
 export * from './schema.gen.js';
+// AARM-aware annotation registry (browser-safe — Studio uses this
+// for Monaco autocomplete + lint of @step_up_required / @defer_* keys).
+export * from './aarm-annotations.gen.js';
 // PolicyBuilder - works in browser (no WASM dependency)
 export * from './builder.js';
 // Error types - works in browser (no WASM dependency)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "2.1.37",
+  "version": "2.1.39",
   "engines": {
     "node": ">=18"
   },