@highflame/policy 2.0.8 → 2.0.10

package/_schemas/overwatch/context.json

@@ -100,61 +100,61 @@
         {
           "key": "violence_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Violence content detection score (0-100)"
         },
         {
           "key": "weapons_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Weapons content detection score (0-100)"
         },
         {
           "key": "hate_speech_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Hate speech detection score (0-100)"
         },
         {
           "key": "crime_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Criminal content detection score (0-100)"
         },
         {
           "key": "sexual_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Sexual content detection score (0-100)"
         },
         {
           "key": "profanity_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Profanity detection score (0-100)"
         },
         {
           "key": "pii_confidence",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "PII detection classifier confidence (0-100)"
         },
         {
           "key": "injection_confidence",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Prompt injection classifier confidence (0-100)"
         },
         {
           "key": "jailbreak_confidence",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Jailbreak detection classifier confidence (0-100)"
         },
         {
           "key": "indirect_injection_score",
           "type": "number",
-          "required": false,
+          "required": true,
           "description": "Indirect prompt injection risk score (0-100)"
         }
       ]
@@ -226,44 +226,44 @@
         {
           "key": "threat_count",
           "type": "number",
-          "required": true,
-          "description": "Total threats detected"
+          "required": false,
+          "description": "Total threats detected (if scanning ran)"
         },
         {
           "key": "highest_severity",
           "type": "string",
-          "required": true,
-          "description": "Highest severity: critical, high, medium, low"
+          "required": false,
+          "description": "Highest severity (if scanning ran)"
         },
         {
           "key": "threat_categories",
           "type": "array",
-          "required": true,
-          "description": "Threat category names"
+          "required": false,
+          "description": "Threat category names (if scanning ran)"
         },
         {
           "key": "threat_types",
           "type": "array",
-          "required": true,
-          "description": "YARA threat categories"
+          "required": false,
+          "description": "YARA threat categories (if scanning ran)"
         },
         {
           "key": "yara_threats",
           "type": "array",
-          "required": true,
-          "description": "YARA rule names"
+          "required": false,
+          "description": "YARA rule names (if scanning ran)"
         },
         {
           "key": "max_threat_severity",
           "type": "number",
-          "required": true,
-          "description": "Numeric severity (0-4)"
+          "required": false,
+          "description": "Numeric severity 0-4 (if scanning ran)"
         },
         {
           "key": "contains_secrets",
           "type": "boolean",
-          "required": true,
-          "description": "Whether secrets detected"
+          "required": false,
+          "description": "Whether secrets detected (if scanning ran)"
         },
         {
           "key": "response_content",
@@ -358,8 +358,8 @@
         {
           "key": "content",
           "type": "string",
-          "required": true,
-          "description": "Raw content being scanned"
+          "required": false,
+          "description": "Raw content being scanned (if available)"
         },
         {
           "key": "source",
@@ -388,26 +388,26 @@
         {
           "key": "threat_count",
           "type": "number",
-          "required": true,
-          "description": "Total threats detected"
+          "required": false,
+          "description": "Total threats detected (if scanning ran)"
         },
         {
           "key": "highest_severity",
           "type": "string",
-          "required": true,
-          "description": "Highest severity level"
+          "required": false,
+          "description": "Highest severity level (if scanning ran)"
         },
         {
           "key": "threat_categories",
           "type": "array",
-          "required": true,
-          "description": "Threat category names"
+          "required": false,
+          "description": "Threat category names (if scanning ran)"
         },
         {
           "key": "max_threat_severity",
           "type": "number",
-          "required": true,
-          "description": "Numeric severity (0-4)"
+          "required": false,
+          "description": "Numeric severity 0-4 (if scanning ran)"
         },
         {
           "key": "tool_poisoning_score",
@@ -484,32 +484,32 @@
         {
           "key": "threat_count",
           "type": "number",
-          "required": true,
-          "description": "Total threats detected"
+          "required": false,
+          "description": "Total threats detected (if scanning ran)"
         },
         {
           "key": "highest_severity",
           "type": "string",
-          "required": true,
-          "description": "Highest severity level"
+          "required": false,
+          "description": "Highest severity level (if scanning ran)"
         },
         {
           "key": "threat_categories",
           "type": "array",
-          "required": true,
-          "description": "Threat categories"
+          "required": false,
+          "description": "Threat categories (if scanning ran)"
         },
         {
           "key": "max_threat_severity",
           "type": "number",
-          "required": true,
-          "description": "Numeric severity (0-4)"
+          "required": false,
+          "description": "Numeric severity 0-4 (if scanning ran)"
         },
         {
           "key": "contains_secrets",
           "type": "boolean",
-          "required": true,
-          "description": "Whether secrets detected"
+          "required": false,
+          "description": "Whether secrets detected (if scanning ran)"
         }
       ]
     },
@@ -562,32 +562,32 @@
         {
           "key": "threat_count",
           "type": "number",
-          "required": true,
-          "description": "Total threats detected"
+          "required": false,
+          "description": "Total threats detected (if scanning ran)"
         },
         {
           "key": "highest_severity",
           "type": "string",
-          "required": true,
-          "description": "Highest severity level"
+          "required": false,
+          "description": "Highest severity level (if scanning ran)"
         },
         {
           "key": "threat_categories",
           "type": "array",
-          "required": true,
-          "description": "Threat categories"
+          "required": false,
+          "description": "Threat categories (if scanning ran)"
         },
         {
           "key": "max_threat_severity",
           "type": "number",
-          "required": true,
-          "description": "Numeric severity (0-4)"
+          "required": false,
+          "description": "Numeric severity 0-4 (if scanning ran)"
         },
         {
           "key": "contains_secrets",
           "type": "boolean",
-          "required": true,
-          "description": "Whether secrets detected"
+          "required": false,
+          "description": "Whether secrets detected (if scanning ran)"
         }
       ]
     }

package/_schemas/overwatch/schema.cedarschema

@@ -84,8 +84,8 @@ action process_prompt appliesTo {
     user_email: String,             // User identifier
 
     // Workspace
-    cwd: String,                   // Current working directory
-    workspace_root: String,        // Workspace/repository root
+    cwd?: String,                   // Current working directory
+    workspace_root?: String,        // Workspace/repository root
 
     // Threat Detection
     threat_count: Long,             // Total threats detected
@@ -94,24 +94,27 @@ action process_prompt appliesTo {
     yara_threats: Set<String>,      // YARA rule names
     max_threat_severity: Long,      // Numeric severity (0-4)
     contains_secrets: Bool,         // Whether secrets detected
-    prompt_text: String,           // Same as content (legacy)
-    response_content: String,      // Response content (if available)
+    prompt_text?: String,           // Same as content (legacy)
+    response_content?: String,      // Response content (if available)
 
     // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    violence_score: Long,          // Violence content detection score
-    weapons_score: Long,           // Weapons content detection score
-    hate_speech_score: Long,       // Hate speech detection score
-    crime_score: Long,             // Criminal content detection score
-    sexual_score: Long,            // Sexual content detection score
-    profanity_score: Long,         // Profanity detection score
+    // Required: content safety classifiers always run for prompt processing
+    violence_score: Long,           // Violence content detection score
+    weapons_score: Long,            // Weapons content detection score
+    hate_speech_score: Long,        // Hate speech detection score
+    crime_score: Long,              // Criminal content detection score
+    sexual_score: Long,             // Sexual content detection score
+    profanity_score: Long,          // Profanity detection score
 
     // Detector Confidence Scores (0-100, ML classifier confidence)
-    pii_confidence: Long,          // PII detection confidence
-    injection_confidence: Long,    // Prompt injection confidence
-    jailbreak_confidence: Long,    // Jailbreak detection confidence
+    // Required: ML classifiers always run for prompt processing
+    pii_confidence: Long,           // PII detection confidence
+    injection_confidence: Long,     // Prompt injection confidence
+    jailbreak_confidence: Long,     // Jailbreak detection confidence
 
     // Agent Security (0-100)
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Required: agent security scanners always run for prompt processing
+    indirect_injection_score: Long,  // Indirect prompt injection risk
   },
 };
 
@@ -127,46 +130,50 @@ action call_tool appliesTo {
     user_email: String,             // User identifier
 
     // Tool & MCP
-    tool_name: String,             // Normalized tool name ("shell", "read_file", etc.)
-    mcp_server: String,            // MCP server name
-    mcp_tool: String,              // MCP tool name
+    tool_name?: String,             // Normalized tool name ("shell", "read_file", etc.)
+    mcp_server?: String,            // MCP server name
+    mcp_tool?: String,              // MCP tool name
 
     // File & Path
-    path: String,                  // File path (if file operation)
+    path?: String,                  // File path (if file operation)
 
     // Workspace
-    cwd: String,
-    workspace_root: String,
-
-    // Threat Detection
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    yara_threats: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
-    response_content: String,
+    cwd?: String,
+    workspace_root?: String,
+
+    // Threat Detection (optional: scanning may not have run before tool call)
+    threat_count?: Long,
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    yara_threats?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
+    response_content?: String,
 
     // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    violence_score: Long,          // Violence content detection score
-    weapons_score: Long,           // Weapons content detection score
-    hate_speech_score: Long,       // Hate speech detection score
-    crime_score: Long,             // Criminal content detection score
-    sexual_score: Long,            // Sexual content detection score
-    profanity_score: Long,         // Profanity detection score
+    // Optional: only present when trust/safety classifiers have run
+    violence_score?: Long,          // Violence content detection score
+    weapons_score?: Long,           // Weapons content detection score
+    hate_speech_score?: Long,       // Hate speech detection score
+    crime_score?: Long,             // Criminal content detection score
+    sexual_score?: Long,            // Sexual content detection score
+    profanity_score?: Long,         // Profanity detection score
 
     // Detector Confidence Scores (0-100, ML classifier confidence)
-    pii_confidence: Long,          // PII detection confidence
-    injection_confidence: Long,    // Prompt injection confidence
-    jailbreak_confidence: Long,    // Jailbreak detection confidence
+    // Optional: only present when ML classifiers have run
+    pii_confidence?: Long,          // PII detection confidence
+    injection_confidence?: Long,    // Prompt injection confidence
+    jailbreak_confidence?: Long,    // Jailbreak detection confidence
 
     // Agent Security (0-100)
-    tool_poisoning_score: Long,    // Tool description manipulation risk
-    rug_pull_score: Long,          // Tool behavior mismatch risk
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Optional: only present when agent security scanners have run
+    tool_poisoning_score?: Long,    // Tool description manipulation risk
+    rug_pull_score?: Long,          // Tool behavior mismatch risk
+    indirect_injection_score?: Long, // Indirect prompt injection risk
 
     // MCP Trust
-    mcp_server_verified: Bool,     // Whether server is from verified registry
+    // Optional: only present when MCP server verification has run
+    mcp_server_verified?: Bool,     // Whether server is from verified registry
   },
 };
 
@@ -175,23 +182,25 @@ action connect_server appliesTo {
   principal: [User, Agent],
   resource: [Server],
   context: {
-    content: String,
+    content?: String,               // No content to scan when connecting
     source: String,
     event: String,
     user_email: String,
-    mcp_server: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
+    mcp_server?: String,
+    threat_count?: Long,            // Threat scanning may not run for connections
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
 
     // Agent Security (0-100)
-    tool_poisoning_score: Long,    // Tool description manipulation risk
-    rug_pull_score: Long,          // Tool behavior mismatch risk
-    indirect_injection_score: Long, // Indirect prompt injection risk
+    // Optional: only present when agent security scanners have run
+    tool_poisoning_score?: Long,    // Tool description manipulation risk
+    rug_pull_score?: Long,          // Tool behavior mismatch risk
+    indirect_injection_score?: Long, // Indirect prompt injection risk
 
     // MCP Trust
-    mcp_server_verified: Bool,     // Whether server is from verified registry
+    // Optional: only present when MCP server verification has run
+    mcp_server_verified?: Bool,     // Whether server is from verified registry
   },
 };
 
@@ -204,14 +213,14 @@ action read_file appliesTo {
     source: String,
     event: String,
     user_email: String,
-    path: String,
-    cwd: String,
-    workspace_root: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
+    path?: String,
+    cwd?: String,
+    workspace_root?: String,
+    threat_count?: Long,             // Threat scanning may not have run
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
   },
 };
 
@@ -224,14 +233,14 @@ action write_file appliesTo {
     source: String,
     event: String,
     user_email: String,
-    path: String,
-    cwd: String,
-    workspace_root: String,
-    threat_count: Long,
-    highest_severity: String,
-    threat_categories: Set<String>,
-    max_threat_severity: Long,
-    contains_secrets: Bool,
+    path?: String,
+    cwd?: String,
+    workspace_root?: String,
+    threat_count?: Long,             // Threat scanning may not have run
+    highest_severity?: String,
+    threat_categories?: Set<String>,
+    max_threat_severity?: Long,
+    contains_secrets?: Bool,
   },
 };
 

package/dist/actions.gen.d.ts

@@ -47,4 +47,3 @@ export type ActionType = (typeof ActionType)[keyof typeof ActionType];
  * Create an EntityUID for an action.
  */
 export declare function actionUID(action: ActionType): EntityUID;
-//# sourceMappingURL=actions.gen.d.ts.map

package/dist/actions.gen.js

@@ -49,4 +49,3 @@ export const ActionType = {
 export function actionUID(action) {
     return { type: 'Action', id: action };
 }
-//# sourceMappingURL=actions.gen.js.map

package/dist/annotations.d.ts

@@ -124,4 +124,3 @@ export declare function parseAnnotations(rawAnnotations: Record<string, string>
  * Uses crypto.randomUUID if available, falls back to manual generation.
  */
 export declare function generateRuleId(): string;
-//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.js

@@ -172,4 +172,3 @@ export function generateRuleId() {
         return v.toString(16);
     });
 }
-//# sourceMappingURL=annotations.js.map

package/dist/builder.d.ts

@@ -33,6 +33,7 @@
 import { EntityType, EntityUID } from './entities.gen.js';
 import { ActionType } from './actions.gen.js';
 import { type PolicyAnnotations, type CustomAnnotations, type PolicySeverity } from './annotations.js';
+import type { ServiceContext } from './service-schemas.gen.js';
 /**
  * Policy effect - permit or forbid
  */
@@ -163,8 +164,11 @@ export declare class Policy {
     /**
      * Convert to Cedar policy text.
      * Uses proper Cedar @annotation syntax.
+     *
+     * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+     *                         Use `getOptionalFields()` to compute this from service context metadata.
      */
-    toCedar(): string;
+    toCedar(optionalFields?: Set<string>): string;
     /**
      * Get JSON representation for storage
      */
@@ -178,10 +182,35 @@ export declare class Policy {
      */
     getName(): string | undefined;
 }
+/**
+ * Get the set of optional context fields for the given action(s).
+ *
+ * A field is considered optional if it has `required: false` in ANY of the
+ * targeted actions. This is the safe choice because at evaluation time,
+ * the policy could be matched against any of the specified actions.
+ *
+ * @param serviceContext - The service context metadata (from OVERWATCH_CONTEXT, etc.)
+ * @param actions - Single action name or array of action names
+ * @returns Set of field names that are optional and need `context has` guards
+ *
+ * @example
+ * ```typescript
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ *
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * // Set { 'tool_name', 'mcp_server', 'threat_count', ... }
+ *
+ * const cedar = ruleToCedar(rule, optionalFields);
+ * // Conditions on optional fields auto-get `context has` guards
+ * ```
+ */
+export declare function getOptionalFields(serviceContext: ServiceContext, actions: string | string[]): Set<string>;
 /**
  * Convert a PolicyRule to Cedar policy text with proper annotations.
  *
  * @param rule - The PolicyRule to convert
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text string
  *
  * @example
@@ -197,35 +226,38 @@ export declare class Policy {
  *   order: 0,
  * };
  *
+ * // Without optional fields - no guards injected
  * const cedar = ruleToCedar(rule);
- * // Output:
- * // @id("rule-001")
- * // @name("Block threats")
- * // @severity("high")
- * // forbid (
- * //     principal,
- * //     action == Action::"call_tool",
- * //     resource
- * // )
- * // when { context.threat_count > 0 };
+ *
+ * // With optional fields - auto-injects `context has` guards
+ * import { OVERWATCH_CONTEXT } from '@highflame/policy/types';
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarWithGuards = ruleToCedar(rule, optionalFields);
+ * // when { context has threat_count && context.threat_count > 0 };
  * ```
  */
-export declare function ruleToCedar(rule: PolicyRule): string;
+export declare function ruleToCedar(rule: PolicyRule, optionalFields?: Set<string>): string;
 /**
  * Convert multiple PolicyRules to Cedar policy text.
  * Only enabled rules are included, sorted by order.
  *
  * @param rules - Array of PolicyRules to convert
  * @param includeDisabled - If true, include disabled rules as comments (default: false)
+ * @param optionalFields - Set of context field names that are optional and need `context has` guards.
+ *                         Use `getOptionalFields()` to compute this from service context metadata.
  * @returns Cedar policy text with all rules separated by blank lines
  *
  * @example
  * ```typescript
  * const rules: PolicyRule[] = [...];
  * const cedarText = rulesToCedar(rules);
+ *
+ * // With optional fields awareness
+ * const optionalFields = getOptionalFields(OVERWATCH_CONTEXT, 'call_tool');
+ * const cedarText = rulesToCedar(rules, false, optionalFields);
  * ```
  */
-export declare function rulesToCedar(rules: PolicyRule[], includeDisabled?: boolean): string;
+export declare function rulesToCedar(rules: PolicyRule[], includeDisabled?: boolean, optionalFields?: Set<string>): string;
 /**
  * Builder for constructing Cedar policies with type safety.
  */
@@ -311,4 +343,3 @@ export declare class PolicyBuilder {
  * Complex hand-written policies may not parse correctly.
  */
 export declare function parseCedarPolicy(cedarText: string): PolicyJSON | null;
-//# sourceMappingURL=builder.d.ts.map