@highflame/policy 2.0.8 → 2.0.10

package/dist/builder.js

@@ -133,8 +133,11 @@ export 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() {
+    toCedar(optionalFields) {
         const lines = [];
         // Generate proper Cedar annotations
         if (this.data.id || this.data.name) {
@@ -145,7 +148,7 @@ export class Policy {
             lines.push(...generateAnnotationLines(annotations));
         }
         // Generate policy body
-        lines.push(generatePolicyBody(this.data.effect, this.data.principal, this.data.action, this.data.resource, this.data.conditions, this.data.rawCondition));
+        lines.push(generatePolicyBody(this.data.effect, this.data.principal, this.data.action, this.data.resource, this.data.conditions, this.data.rawCondition, optionalFields));
         return lines.join('\n');
     }
     /**
@@ -170,40 +173,99 @@ export class Policy {
 // ============================================================================
 // Cedar Generation Functions
 // ============================================================================
+/**
+ * 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 function getOptionalFields(serviceContext, actions) {
+    const actionList = Array.isArray(actions) ? actions : [actions];
+    const optionalFields = new Set();
+    for (const actionName of actionList) {
+        const action = serviceContext.actions.find(a => a.name === actionName);
+        if (action) {
+            for (const attr of action.context_attributes) {
+                if (!attr.required) {
+                    optionalFields.add(attr.key);
+                }
+            }
+        }
+    }
+    return optionalFields;
+}
 /**
  * Convert a condition to Cedar syntax.
  * Field names are sanitized to prevent injection attacks.
+ *
+ * When `optionalFields` is provided and the condition's field is in the set,
+ * the output is wrapped with a `context has` guard:
+ *   `context has field && context.field > value`
  */
-function conditionToCedar(condition) {
+function conditionToCedar(condition, optionalFields) {
     const field = sanitizeIdentifier(condition.field, 'field');
     const { operator, value } = condition;
     const valueStr = valueToString(value);
+    let expr;
     switch (operator) {
         case 'eq':
-            return `context.${field} == ${valueStr}`;
+            expr = `context.${field} == ${valueStr}`;
+            break;
         case 'neq':
-            return `context.${field} != ${valueStr}`;
+            expr = `context.${field} != ${valueStr}`;
+            break;
         case 'lt':
-            return `context.${field} < ${valueStr}`;
+            expr = `context.${field} < ${valueStr}`;
+            break;
         case 'lte':
-            return `context.${field} <= ${valueStr}`;
+            expr = `context.${field} <= ${valueStr}`;
+            break;
         case 'gt':
-            return `context.${field} > ${valueStr}`;
+            expr = `context.${field} > ${valueStr}`;
+            break;
         case 'gte':
-            return `context.${field} >= ${valueStr}`;
+            expr = `context.${field} >= ${valueStr}`;
+            break;
         case 'contains':
-            return `context.${field}.contains(${valueStr})`;
+            expr = `context.${field}.contains(${valueStr})`;
+            break;
         case 'in':
             if (Array.isArray(value)) {
                 const items = value.map(v => `"${escapeCedarString(v)}"`).join(', ');
-                return `context.${field} in [${items}]`;
+                expr = `context.${field} in [${items}]`;
+            }
+            else {
+                expr = `context.${field} in ${valueStr}`;
             }
-            return `context.${field} in ${valueStr}`;
+            break;
         case 'like':
-            return `context.${field} like ${valueStr}`;
+            expr = `context.${field} like ${valueStr}`;
+            break;
         default:
-            return `context.${field} == ${valueStr}`;
+            expr = `context.${field} == ${valueStr}`;
+            break;
+    }
+    // Auto-inject `context has` guard for optional fields
+    if (optionalFields?.has(field)) {
+        return `context has ${field} && ${expr}`;
     }
+    return expr;
 }
 /**
  * Convert a value to Cedar string representation.
@@ -225,7 +287,7 @@ function valueToString(value) {
  * Generate the Cedar policy body (permit/forbid statement).
  * All inputs are sanitized/escaped to prevent injection attacks.
  */
-function generatePolicyBody(effect, principal, action, resource, conditions, rawCondition) {
+function generatePolicyBody(effect, principal, action, resource, conditions, rawCondition, optionalFields) {
     let policyLine = `${effect} (`;
     // Principal
     if (principal) {
@@ -283,7 +345,7 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
         }
         else if (conditions.length > 0) {
             // Fallback to structured conditions if rawCondition is rejected
-            const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+            const conditionStr = conditions.map(c => conditionToCedar(c, optionalFields)).join(' && ');
             policyLine += `\nwhen { ${conditionStr} };`;
         }
         else {
@@ -291,7 +353,7 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
         }
     }
     else if (conditions.length > 0) {
-        const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+        const conditionStr = conditions.map(c => conditionToCedar(c, optionalFields)).join(' && ');
         policyLine += `\nwhen { ${conditionStr} };`;
     }
     else {
@@ -303,6 +365,8 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
  * 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
@@ -318,25 +382,22 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
  *   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 function ruleToCedar(rule) {
+export function ruleToCedar(rule, optionalFields) {
     const lines = [];
     // Generate Cedar annotations
     lines.push(...generateAnnotationLines(rule.annotations, rule.customAnnotations));
     // Generate policy body
-    lines.push(generatePolicyBody(rule.effect, rule.principal, rule.action, rule.resource, rule.conditions, rule.rawCondition));
+    lines.push(generatePolicyBody(rule.effect, rule.principal, rule.action, rule.resource, rule.conditions, rule.rawCondition, optionalFields));
     return lines.join('\n');
 }
 /**
@@ -345,24 +406,30 @@ export function ruleToCedar(rule) {
  *
  * @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 function rulesToCedar(rules, includeDisabled = false) {
+export function rulesToCedar(rules, includeDisabled = false, optionalFields) {
     const sortedRules = [...rules].sort((a, b) => a.order - b.order);
     const cedarPolicies = [];
     for (const rule of sortedRules) {
         if (rule.enabled) {
-            cedarPolicies.push(ruleToCedar(rule));
+            cedarPolicies.push(ruleToCedar(rule, optionalFields));
         }
         else if (includeDisabled) {
             // Include disabled rules as comments
-            const cedarLines = ruleToCedar(rule).split('\n');
+            const cedarLines = ruleToCedar(rule, optionalFields).split('\n');
             cedarPolicies.push(cedarLines.map(line => `// [DISABLED] ${line}`).join('\n'));
         }
     }
@@ -586,4 +653,3 @@ export function parseCedarPolicy(cedarText) {
         return null;
     }
 }
-//# sourceMappingURL=builder.js.map

package/dist/context.gen.d.ts

@@ -3,4 +3,3 @@
  */
 export declare const ContextKey: {};
 export type ContextKey = (typeof ContextKey)[keyof typeof ContextKey];
-//# sourceMappingURL=context.gen.d.ts.map

package/dist/context.gen.js

@@ -4,4 +4,3 @@
  * Context attribute keys for Cedar policy evaluation.
  */
 export const ContextKey = {};
-//# sourceMappingURL=context.gen.js.map

package/dist/engine.d.ts

@@ -38,11 +38,21 @@ export interface EngineOptions {
 export declare class InputValidationError extends Error {
     constructor(message: string);
 }
+/**
+ * A policy that contributed to the authorization decision,
+ * enriched with its Cedar annotations.
+ */
+export interface DeterminingPolicy {
+    /** Policy ID (from @id annotation or positional fallback) */
+    id: string;
+    /** All annotations from this policy as key-value pairs */
+    annotations: Record<string, string>;
+}
 export declare class Decision {
     readonly effect: "Allow" | "Deny";
-    readonly determining_policies: string[];
+    readonly determining_policies: DeterminingPolicy[];
     readonly reason?: string;
-    constructor(effect: "Allow" | "Deny", determining_policies: string[], reason?: string);
+    constructor(effect: "Allow" | "Deny", determining_policies: DeterminingPolicy[], reason?: string);
     isAllowed(): boolean;
     isDenied(): boolean;
 }
@@ -63,6 +73,7 @@ export interface EvaluateRequest {
  */
 export declare class PolicyEngine {
     private policySet;
+    private policyAnnotations;
     private schema;
     private options;
     private limits;
@@ -74,11 +85,13 @@ export declare class PolicyEngine {
     /**
      * Load a single Cedar policy text string.
      * Uses @id annotations as policy IDs when available.
+     * Stores all annotations per policy for enriching evaluation results.
      */
     loadPolicy(policy: string): void;
     /**
      * Load multiple Cedar policy texts (concatenated with newlines).
      * Uses @id annotations as policy IDs when available.
+     * Stores all annotations per policy for enriching evaluation results.
      */
     loadPolicies(policies: string[]): void;
     /**
@@ -89,6 +102,11 @@ export declare class PolicyEngine {
      * Load schema from a Cedar schema file.
      */
     loadSchemaFromFile(path: string): void;
+    /**
+     * Returns stored annotations for a given policy ID.
+     * Returns undefined if the policy ID is not found.
+     */
+    getPolicyAnnotations(policyId: string): Record<string, string> | undefined;
     /**
      * Evaluate a policy request and return a decision.
      * @throws InputValidationError if context validation fails
@@ -143,4 +161,3 @@ export declare function validatePolicy(schema: string, policy: string): {
 };
 export { EntityType, EntityUID, Entity, newEntityUID, newEntity } from "./entities.gen.js";
 export { ActionType, actionUID } from "./actions.gen.js";
-//# sourceMappingURL=engine.d.ts.map

package/dist/engine.js

@@ -147,39 +147,51 @@ function parseActionString(action) {
     }
     return { type: actionType, id: actionId };
 }
+/**
+ * Regex to extract Cedar annotations from policy text.
+ * Matches `@key("value")` with proper escaped-quote handling.
+ */
+const ANNOTATION_REGEX = /@(\w+)\("((?:[^"\\]|\\.)*)"\)/g;
+/**
+ * Extract all `@key("value")` annotations from a single Cedar policy text string.
+ */
+function extractAnnotationsFromText(policyText) {
+    const annotations = {};
+    let match;
+    const regex = new RegExp(ANNOTATION_REGEX.source, ANNOTATION_REGEX.flags);
+    while ((match = regex.exec(policyText)) !== null) {
+        // Unescape the annotation value (reverse Cedar escaping)
+        annotations[match[1]] = match[2].replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    return annotations;
+}
 /**
  * Extract @id annotations from Cedar policy text and return a
- * Record<PolicyId, Policy> for cedar-wasm. This ensures that
- * determining_policies in evaluation results use the @id values
- * instead of positional IDs (policy0, policy1...).
- *
- * Falls back to the raw string when no @id annotations are found.
+ * Record<PolicyId, Policy> for cedar-wasm, along with a map of
+ * all annotations per policy for enriching evaluation results.
  */
-function extractPolicyIds(policyText) {
+function extractPolicies(policyText) {
+    const annotationsMap = new Map();
     const parts = cedar.policySetTextToParts(policyText);
     if (parts.type !== "success" || parts.policies.length === 0) {
-        return policyText;
+        return { policySet: policyText, annotations: annotationsMap };
     }
     const policyMap = {};
-    let hasAnnotationIds = false;
     for (let i = 0; i < parts.policies.length; i++) {
         const policy = parts.policies[i];
-        const idMatch = policy.match(/@id\("([^"]+)"\)/);
-        if (idMatch) {
-            policyMap[idMatch[1]] = policy;
-            hasAnnotationIds = true;
-        }
-        else {
-            policyMap[`policy${i}`] = policy;
-        }
+        const policyAnnotations = extractAnnotationsFromText(policy);
+        const policyId = policyAnnotations["id"] || `policy${i}`;
+        policyMap[policyId] = policy;
+        annotationsMap.set(policyId, policyAnnotations);
     }
-    return hasAnnotationIds ? policyMap : policyText;
+    return { policySet: policyMap, annotations: annotationsMap };
 }
 /**
  * PolicyEngine wraps cedar-wasm with Highflame schema types.
  */
 export class PolicyEngine {
     policySet = "";
+    policyAnnotations = new Map();
     schema;
     options;
     limits;
@@ -203,16 +215,22 @@ export class PolicyEngine {
     /**
      * Load a single Cedar policy text string.
      * Uses @id annotations as policy IDs when available.
+     * Stores all annotations per policy for enriching evaluation results.
      */
     loadPolicy(policy) {
-        this.policySet = extractPolicyIds(policy);
+        const extracted = extractPolicies(policy);
+        this.policySet = extracted.policySet;
+        this.policyAnnotations = extracted.annotations;
     }
     /**
      * Load multiple Cedar policy texts (concatenated with newlines).
      * Uses @id annotations as policy IDs when available.
+     * Stores all annotations per policy for enriching evaluation results.
      */
     loadPolicies(policies) {
-        this.policySet = extractPolicyIds(policies.join("\n"));
+        const extracted = extractPolicies(policies.join("\n"));
+        this.policySet = extracted.policySet;
+        this.policyAnnotations = extracted.annotations;
     }
     /**
      * Load schema from a Cedar schema string.
@@ -227,6 +245,13 @@ export class PolicyEngine {
         const content = fs.readFileSync(path, "utf-8");
         this.loadSchema(content);
     }
+    /**
+     * Returns stored annotations for a given policy ID.
+     * Returns undefined if the policy ID is not found.
+     */
+    getPolicyAnnotations(policyId) {
+        return this.policyAnnotations.get(policyId);
+    }
     /**
      * Evaluate a policy request and return a decision.
      * @throws InputValidationError if context validation fails
@@ -276,7 +301,12 @@ export class PolicyEngine {
         if (result.type === "failure") {
             return new Decision("Deny", [], result.errors.map(e => e.message).join("; "));
         }
-        return new Decision(result.response.decision === "allow" ? "Allow" : "Deny", result.response.diagnostics.reason, result.response.diagnostics.errors.length > 0
+        // Build enriched DeterminingPolicy objects with annotations
+        const determiningPolicies = result.response.diagnostics.reason.map(id => ({
+            id,
+            annotations: this.policyAnnotations.get(id) || {},
+        }));
+        return new Decision(result.response.decision === "allow" ? "Allow" : "Deny", determiningPolicies, result.response.diagnostics.errors.length > 0
             ? result.response.diagnostics.errors.map(e => e.error.message).join("; ")
             : undefined);
     }
@@ -374,4 +404,3 @@ export function validatePolicy(schema, policy) {
 // Re-export types
 export { EntityType, newEntityUID, newEntity } from "./entities.gen.js";
 export { ActionType, actionUID } from "./actions.gen.js";
-//# sourceMappingURL=engine.js.map

package/dist/entities.gen.d.ts

@@ -47,4 +47,3 @@ export declare function newEntityUID(type: EntityType | string, id: string): Ent
  * Create a new Entity.
  */
 export declare function newEntity(type: EntityType | string, id: string, attrs?: Record<string, unknown>): Entity;
-//# sourceMappingURL=entities.gen.d.ts.map

package/dist/entities.gen.js

@@ -41,4 +41,3 @@ export function newEntity(type, id, attrs) {
         parents: [],
     };
 }
-//# sourceMappingURL=entities.gen.js.map

package/dist/entity-metadata-types.gen.d.ts

@@ -14,4 +14,3 @@ export interface ActionEntityMetadata {
     readonly principals: readonly string[];
     readonly resources: readonly string[];
 }
-//# sourceMappingURL=entity-metadata-types.gen.d.ts.map

package/dist/entity-metadata-types.gen.js

@@ -1,3 +1,2 @@
 // Code generated by highflame-policy-codegen. DO NOT EDIT.
 export {};
-//# sourceMappingURL=entity-metadata-types.gen.js.map

package/dist/errors.d.ts

@@ -99,4 +99,3 @@ export declare class ParserError extends Error {
     /** Action scope is nil */
     static actionScopeNil(): ParserError;
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -124,4 +124,3 @@ export class ParserError extends Error {
         return new ParserError(ErrorCodes.ACTION_SCOPE_NIL, "Action scope is nil", { field: "action" });
     }
 }
-//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -16,4 +16,3 @@ export { PALISADE_ENTITIES, PALISADE_ACTION_ENTITIES, } from './palisade-entitie
 export type { ServiceEntityMetadata, ActionEntityMetadata } from './entity-metadata-types.gen.js';
 export { OVERWATCH_DEFAULTS, OVERWATCH_TEMPLATES, OVERWATCH_CATEGORIES, OVERWATCH_TEMPLATES_JSON, getOverwatchDefaultsByCategory, getOverwatchTemplatesByCategory, getOverwatchTemplateById, } from './overwatch-defaults.gen.js';
 export type { OverwatchCategory, OverwatchCategoryInfo, OverwatchDefaultPolicy, OverwatchTemplate, } from './overwatch-defaults.gen.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -23,4 +23,3 @@ export { OVERWATCH_ENTITIES, OVERWATCH_ACTION_ENTITIES, } from './overwatch-enti
 export { PALISADE_ENTITIES, PALISADE_ACTION_ENTITIES, } from './palisade-entities.gen.js';
 // Service-specific default policies, templates, and categories
 export { OVERWATCH_DEFAULTS, OVERWATCH_TEMPLATES, OVERWATCH_CATEGORIES, OVERWATCH_TEMPLATES_JSON, getOverwatchDefaultsByCategory, getOverwatchTemplatesByCategory, getOverwatchTemplateById, } from './overwatch-defaults.gen.js';
-//# sourceMappingURL=index.js.map

package/dist/overwatch-context.gen.d.ts

@@ -39,4 +39,3 @@ export declare const OverwatchContextKey: {
     readonly YaraThreats: "yara_threats";
 };
 export type OverwatchContextKey = (typeof OverwatchContextKey)[keyof typeof OverwatchContextKey];
-//# sourceMappingURL=overwatch-context.gen.d.ts.map

package/dist/overwatch-context.gen.js

@@ -40,4 +40,3 @@ export const OverwatchContextKey = {
     WorkspaceRoot: 'workspace_root',
     YaraThreats: 'yara_threats',
 };
-//# sourceMappingURL=overwatch-context.gen.js.map

package/dist/overwatch-defaults.gen.d.ts

@@ -59,4 +59,3 @@ export declare const OVERWATCH_TEMPLATES_JSON: string;
 export declare function getOverwatchDefaultsByCategory(category: OverwatchCategory): OverwatchDefaultPolicy[];
 export declare function getOverwatchTemplatesByCategory(category: OverwatchCategory): OverwatchTemplate[];
 export declare function getOverwatchTemplateById(id: string): OverwatchTemplate | undefined;
-//# sourceMappingURL=overwatch-defaults.gen.d.ts.map