@highflame/policy 2.0.9 → 2.1.0

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

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);
     }

package/dist/entities.gen.d.ts

@@ -2,7 +2,9 @@
  * Entity types defined in the Highflame Cedar schema.
  */
 export declare const EntityType: {
+    readonly Account: "Account";
     readonly Agent: "Agent";
+    readonly App: "App";
     readonly Artifact: "Artifact";
     readonly ExternalAPI: "ExternalAPI";
     readonly FilePath: "FilePath";
@@ -12,12 +14,14 @@ export declare const EntityType: {
     readonly Memory: "Memory";
     readonly Model: "Model";
     readonly Package: "Package";
+    readonly Project: "Project";
     readonly Repository: "Repository";
     readonly Resource: "Resource";
     readonly ResponseData: "ResponseData";
     readonly Scanner: "Scanner";
     readonly Server: "Server";
     readonly Service: "Service";
+    readonly Session: "Session";
     readonly Tool: "Tool";
     readonly User: "User";
 };

package/dist/entities.gen.js

@@ -4,7 +4,9 @@
  * Entity types defined in the Highflame Cedar schema.
  */
 export const EntityType = {
+    Account: 'Account',
     Agent: 'Agent',
+    App: 'App',
     Artifact: 'Artifact',
     ExternalAPI: 'ExternalAPI',
     FilePath: 'FilePath',
@@ -14,12 +16,14 @@ export const EntityType = {
     Memory: 'Memory',
     Model: 'Model',
     Package: 'Package',
+    Project: 'Project',
     Repository: 'Repository',
     Resource: 'Resource',
     ResponseData: 'ResponseData',
     Scanner: 'Scanner',
     Server: 'Server',
     Service: 'Service',
+    Session: 'Session',
     Tool: 'Tool',
     User: 'User',
 };

package/dist/explain.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Policy Decision Explanation
+ *
+ * Provides structured explanations for Cedar policy decisions by matching
+ * determining policies against their structured conditions and the request context.
+ *
+ * Browser-safe — no WASM or Node.js dependencies.
+ */
+import type { PolicyRule, PolicyEffect, ConditionOperator, ConditionExpression } from "./builder.js";
+/**
+ * Duck-typed decision input — accepts the Decision class from engine.ts
+ * without importing cedar-wasm (keeps this module browser-safe).
+ */
+export interface DecisionInput {
+    effect: "Allow" | "Deny";
+    determining_policies: Array<{
+        id: string;
+        annotations: Record<string, string>;
+    }>;
+}
+/**
+ * Result of explaining a policy decision.
+ */
+export interface ExplainedDecision {
+    /** The original decision effect */
+    effect: "Allow" | "Deny";
+    /** Enriched explanations for each determining policy */
+    explanations: PolicyExplanation[];
+    /** Determining policy IDs that had no matching rule in the provided rules array */
+    unmatched_policies: string[];
+}
+/**
+ * Explanation for a single determining policy.
+ */
+export interface PolicyExplanation {
+    /** Policy ID */
+    policy_id: string;
+    /** Policy effect (permit or forbid) */
+    effect: PolicyEffect;
+    /** Human-readable summary */
+    summary: string;
+    /** Recursive evaluated condition tree with actual values (from conditionExpression) */
+    evaluated_expression?: EvaluatedExpression;
+    /** Per-condition match results (flat, from structured conditions[]) */
+    condition_results: ConditionResult[];
+    /** Raw Cedar condition text if the policy uses rawCondition instead of structured conditions */
+    raw_condition?: string;
+}
+/**
+ * Result of evaluating a single condition against the request context.
+ */
+export interface ConditionResult {
+    /** Context field name */
+    field: string;
+    /** Comparison operator */
+    operator: ConditionOperator;
+    /** Expected value (threshold from the rule) */
+    expected: string | number | boolean | string[];
+    /** Actual value from the context (undefined if field was missing) */
+    actual?: unknown;
+    /** Whether this condition matched */
+    matched: boolean;
+}
+/** Evaluated comparison: context.field <op> value */
+export interface EvaluatedComparison {
+    kind: 'comparison';
+    field: string;
+    operator: ConditionOperator;
+    expected: string | number | boolean | string[];
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated contains: context.field.contains(value) */
+export interface EvaluatedContains {
+    kind: 'contains';
+    field: string;
+    expected: string | number | boolean;
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated like: context.field like "pattern" */
+export interface EvaluatedLike {
+    kind: 'like';
+    field: string;
+    pattern: string;
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated has: context has field */
+export interface EvaluatedHas {
+    kind: 'has';
+    field: string;
+    matched: boolean;
+}
+/** Evaluated AND */
+export interface EvaluatedAnd {
+    kind: 'and';
+    children: EvaluatedExpression[];
+    matched: boolean;
+}
+/** Evaluated OR */
+export interface EvaluatedOr {
+    kind: 'or';
+    children: EvaluatedExpression[];
+    matched: boolean;
+}
+/** Evaluated NOT */
+export interface EvaluatedNot {
+    kind: 'not';
+    child: EvaluatedExpression;
+    matched: boolean;
+}
+/** Evaluated raw (cannot be decomposed) */
+export interface EvaluatedRaw {
+    kind: 'raw';
+    text: string;
+    matched: boolean;
+}
+/**
+ * Recursive evaluated condition expression tree.
+ * Produced by evaluateExpression() by walking ConditionExpression against context.
+ * Every node has a `matched` boolean; leaf nodes include `actual` values.
+ */
+export type EvaluatedExpression = EvaluatedComparison | EvaluatedContains | EvaluatedLike | EvaluatedHas | EvaluatedAnd | EvaluatedOr | EvaluatedNot | EvaluatedRaw;
+/**
+ * Explain a policy decision by matching determining policies against their
+ * structured conditions and the request context.
+ *
+ * @param decision - The decision from PolicyEngine.evaluate()
+ * @param rules - The PolicyRule[] that were loaded (parsed or built)
+ * @param context - The context map that was passed to evaluate()
+ * @returns Structured explanation with per-condition match details
+ *
+ * @example
+ * ```typescript
+ * const decision = engine.evaluate(request);
+ * const explained = explainDecision(decision, rules, request.context);
+ *
+ * for (const explanation of explained.explanations) {
+ *   console.log(explanation.summary);
+ *   // "forbid process_prompt — threat_count (10) > 5"
+ * }
+ * ```
+ */
+export declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>): ExplainedDecision;
+/**
+ * Recursively evaluate a ConditionExpression tree against a context map.
+ * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ */
+export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>): EvaluatedExpression;