@highflame/policy 2.0.1 → 2.0.3

package/dist/annotations.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Cedar Policy Annotations
+ *
+ * Provides types and utilities for working with Cedar policy annotations.
+ * Annotations are key-value pairs attached to Cedar policies that provide
+ * metadata without affecting policy evaluation.
+ *
+ * Cedar annotation syntax:
+ *   @id("rule-001")
+ *   @name("Block critical threats")
+ *   @severity("high")
+ *   permit(...) when {...};
+ *
+ * @see https://docs.cedarpolicy.com/policies/syntax-policy.html
+ */
+/**
+ * Rule severity levels for UI display and prioritization.
+ * Used to indicate the importance/criticality of a rule.
+ */
+export type PolicySeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Predefined annotation keys with known semantics.
+ * These annotations are extracted/embedded with special handling in the parser/builder.
+ */
+export declare const PREDEFINED_ANNOTATION_KEYS: readonly ["id", "name", "description", "severity", "tags"];
+export type PredefinedAnnotationKey = (typeof PREDEFINED_ANNOTATION_KEYS)[number];
+/**
+ * Predefined Cedar annotations with known semantics.
+ * These are embedded in Cedar policy text using @annotation("value") syntax.
+ *
+ * id and name are required for all rules created via the UI.
+ */
+export interface PolicyAnnotations {
+    /** Unique identifier for this rule (auto-generated UUID if not provided) */
+    id: string;
+    /** Human-readable rule name (required) */
+    name: string;
+    /** Longer explanation of what this rule does */
+    description?: string;
+    /** Severity/priority level for display and filtering */
+    severity?: PolicySeverity;
+    /** Categorization tags for grouping and filtering */
+    tags?: string[];
+}
+/**
+ * Custom user-defined annotations.
+ * Keys must be valid Cedar identifiers (alphanumeric + underscore, starting with letter/underscore).
+ * Values are always strings (Cedar annotation constraint).
+ *
+ * Common use cases:
+ * - @compliance("SOC2"), @compliance("HIPAA")
+ * - @ticket("SEC-1234"), @jira("PROJ-123")
+ * - @owner("security-team"), @team("platform")
+ * - @review_date("2024-06-01")
+ */
+export type CustomAnnotations = Record<string, string>;
+/**
+ * Check if a key is a predefined annotation key.
+ *
+ * @param key - The annotation key to check
+ * @returns true if the key is a predefined annotation key
+ */
+export declare function isPredefinedAnnotationKey(key: string): boolean;
+/**
+ * Validate a custom annotation key.
+ * Cedar annotation keys must be valid identifiers: start with letter or underscore,
+ * followed by letters, numbers, or underscores.
+ *
+ * @param key - The annotation key to validate
+ * @returns true if the key is valid for Cedar annotations
+ */
+export declare function isValidAnnotationKey(key: string): boolean;
+/**
+ * Escape a string value for use in Cedar annotation.
+ * Escapes backslashes and double quotes.
+ *
+ * @param value - The value to escape
+ * @returns Escaped string safe for Cedar annotation value
+ */
+export declare function escapeAnnotationValue(value: string): string;
+/**
+ * Unescape a Cedar annotation value.
+ * Reverses the escaping done by escapeAnnotationValue.
+ *
+ * @param value - The escaped value
+ * @returns Unescaped string
+ */
+export declare function unescapeAnnotationValue(value: string): string;
+/**
+ * Generate Cedar annotation syntax for a single annotation.
+ *
+ * @param key - The annotation key
+ * @param value - The annotation value (will be escaped)
+ * @returns Cedar annotation string, e.g., '@severity("high")'
+ */
+export declare function formatAnnotation(key: string, value: string): string;
+/**
+ * Generate all Cedar annotations from PolicyAnnotations and optional custom annotations.
+ * Returns array of annotation lines to prepend to policy.
+ *
+ * @param annotations - Predefined annotations
+ * @param customAnnotations - Optional custom annotations
+ * @returns Array of Cedar annotation strings
+ */
+export declare function generateAnnotationLines(annotations: PolicyAnnotations, customAnnotations?: CustomAnnotations): string[];
+/**
+ * Result of parsing Cedar annotations.
+ * Separates predefined annotations from custom annotations.
+ */
+export interface ParseAnnotationsResult {
+    annotations: PolicyAnnotations;
+    customAnnotations?: CustomAnnotations;
+}
+/**
+ * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Separates predefined annotations from custom annotations.
+ *
+ * @param rawAnnotations - Raw annotation map from Cedar JSON
+ * @returns Parsed annotations object
+ */
+export declare function parseAnnotations(rawAnnotations: Record<string, string> | undefined): ParseAnnotationsResult;
+/**
+ * Generate a UUID v4 for rule IDs.
+ * Uses crypto.randomUUID if available, falls back to manual generation.
+ */
+export declare function generateRuleId(): string;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,0BAA0B,4DAA6D,CAAC;AACrG,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,iBAAiB,EAC9B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,MAAM,EAAE,CA6BV;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,sBAAsB,CA+C3G;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAUvC"}

package/dist/annotations.js

@@ -0,0 +1,175 @@
+/**
+ * Cedar Policy Annotations
+ *
+ * Provides types and utilities for working with Cedar policy annotations.
+ * Annotations are key-value pairs attached to Cedar policies that provide
+ * metadata without affecting policy evaluation.
+ *
+ * Cedar annotation syntax:
+ *   @id("rule-001")
+ *   @name("Block critical threats")
+ *   @severity("high")
+ *   permit(...) when {...};
+ *
+ * @see https://docs.cedarpolicy.com/policies/syntax-policy.html
+ */
+/**
+ * Predefined annotation keys with known semantics.
+ * These annotations are extracted/embedded with special handling in the parser/builder.
+ */
+export const PREDEFINED_ANNOTATION_KEYS = ['id', 'name', 'description', 'severity', 'tags'];
+/**
+ * Check if a key is a predefined annotation key.
+ *
+ * @param key - The annotation key to check
+ * @returns true if the key is a predefined annotation key
+ */
+export function isPredefinedAnnotationKey(key) {
+    return PREDEFINED_ANNOTATION_KEYS.includes(key);
+}
+/**
+ * Validate a custom annotation key.
+ * Cedar annotation keys must be valid identifiers: start with letter or underscore,
+ * followed by letters, numbers, or underscores.
+ *
+ * @param key - The annotation key to validate
+ * @returns true if the key is valid for Cedar annotations
+ */
+export function isValidAnnotationKey(key) {
+    // Must not be a predefined key (those are handled separately)
+    if (isPredefinedAnnotationKey(key)) {
+        return false;
+    }
+    // Must be a valid Cedar identifier
+    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key);
+}
+/**
+ * Escape a string value for use in Cedar annotation.
+ * Escapes backslashes and double quotes.
+ *
+ * @param value - The value to escape
+ * @returns Escaped string safe for Cedar annotation value
+ */
+export function escapeAnnotationValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Unescape a Cedar annotation value.
+ * Reverses the escaping done by escapeAnnotationValue.
+ *
+ * @param value - The escaped value
+ * @returns Unescaped string
+ */
+export function unescapeAnnotationValue(value) {
+    return value.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+/**
+ * Generate Cedar annotation syntax for a single annotation.
+ *
+ * @param key - The annotation key
+ * @param value - The annotation value (will be escaped)
+ * @returns Cedar annotation string, e.g., '@severity("high")'
+ */
+export function formatAnnotation(key, value) {
+    return `@${key}("${escapeAnnotationValue(value)}")`;
+}
+/**
+ * Generate all Cedar annotations from PolicyAnnotations and optional custom annotations.
+ * Returns array of annotation lines to prepend to policy.
+ *
+ * @param annotations - Predefined annotations
+ * @param customAnnotations - Optional custom annotations
+ * @returns Array of Cedar annotation strings
+ */
+export function generateAnnotationLines(annotations, customAnnotations) {
+    const lines = [];
+    // Predefined annotations in consistent order
+    lines.push(formatAnnotation('id', annotations.id));
+    lines.push(formatAnnotation('name', annotations.name));
+    if (annotations.description) {
+        lines.push(formatAnnotation('description', annotations.description));
+    }
+    if (annotations.severity) {
+        lines.push(formatAnnotation('severity', annotations.severity));
+    }
+    if (annotations.tags && annotations.tags.length > 0) {
+        // Cedar annotations are single string values, so join tags with comma
+        lines.push(formatAnnotation('tags', annotations.tags.join(',')));
+    }
+    // Custom annotations (alphabetical order for consistency)
+    if (customAnnotations) {
+        const sortedKeys = Object.keys(customAnnotations).sort();
+        for (const key of sortedKeys) {
+            if (isValidAnnotationKey(key)) {
+                lines.push(formatAnnotation(key, customAnnotations[key]));
+            }
+        }
+    }
+    return lines;
+}
+/**
+ * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Separates predefined annotations from custom annotations.
+ *
+ * @param rawAnnotations - Raw annotation map from Cedar JSON
+ * @returns Parsed annotations object
+ */
+export function parseAnnotations(rawAnnotations) {
+    const annotations = {
+        id: '',
+        name: '',
+    };
+    const customAnnotations = {};
+    if (!rawAnnotations) {
+        return { annotations };
+    }
+    for (const [key, value] of Object.entries(rawAnnotations)) {
+        const unescapedValue = unescapeAnnotationValue(value);
+        switch (key) {
+            case 'id':
+                annotations.id = unescapedValue;
+                break;
+            case 'name':
+                annotations.name = unescapedValue;
+                break;
+            case 'description':
+                annotations.description = unescapedValue;
+                break;
+            case 'severity':
+                if (['critical', 'high', 'medium', 'low'].includes(unescapedValue)) {
+                    annotations.severity = unescapedValue;
+                }
+                break;
+            case 'tags':
+                annotations.tags = unescapedValue.split(',').map((t) => t.trim()).filter(Boolean);
+                break;
+            default:
+                // Custom annotation
+                customAnnotations[key] = unescapedValue;
+        }
+    }
+    // Use id as name if name not provided
+    if (!annotations.name && annotations.id) {
+        annotations.name = annotations.id;
+    }
+    return {
+        annotations,
+        customAnnotations: Object.keys(customAnnotations).length > 0 ? customAnnotations : undefined,
+    };
+}
+/**
+ * Generate a UUID v4 for rule IDs.
+ * Uses crypto.randomUUID if available, falls back to manual generation.
+ */
+export function generateRuleId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for older environments
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"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"}

package/dist/builder.d.ts

@@ -14,15 +14,25 @@
  *   .when("context.environment == \"production\"")
  *   .build();
  *
- * // Get Cedar policy text
+ * // Get Cedar policy text (with proper @annotations)
  * const cedarText = policy.toCedar();
  *
  * // Get JSON representation (for storage/editing)
  * const policyJson = policy.toJSON();
  * ```
+ *
+ * Cedar Annotations:
+ * Policies include proper Cedar annotations that are embedded in the policy text:
+ * ```cedar
+ * @id("rule-001")
+ * @name("Block critical threats")
+ * @severity("high")
+ * permit(...) when {...};
+ * ```
  */
 import { EntityType, EntityUID } from './entities.gen.js';
 import { ActionType } from './actions.gen.js';
+import { type PolicyAnnotations, type CustomAnnotations, type PolicySeverity } from './annotations.js';
 /**
  * Policy effect - permit or forbid
  */
@@ -57,13 +67,12 @@ export interface PolicyEntity {
 export type PolicyPrincipal = PolicyEntity;
 /** Alias for PolicyEntity when used as resource constraint */
 export type PolicyResource = PolicyEntity;
-/**
- * Rule severity levels for UI display and prioritization
- */
-export type PolicySeverity = 'critical' | 'high' | 'medium' | 'low';
+export type { PolicySeverity } from './annotations.js';
 /**
  * JSON representation of a policy for storage and editing.
- * This is the base interface used by PolicyBuilder.
+ * This is the base interface used by PolicyBuilder (legacy format).
+ *
+ * @deprecated Use PolicyRule with annotations for new code.
  */
 export interface PolicyJSON {
     /** Unique identifier for this policy */
@@ -84,46 +93,78 @@ export interface PolicyJSON {
     rawCondition?: string;
 }
 /**
- * A policy rule with UI/storage metadata.
- * Extends PolicyJSON with fields needed for UI editing and database storage.
+ * A policy rule with full Cedar annotation support.
  *
  * This is the canonical type used across all Highflame services:
  * - highflame-studio (UI)
  * - highflame-authz (Go backend)
  * - Any Python services
  *
- * Each PolicyRule maps 1:1 to a Cedar policy statement.
+ * Each PolicyRule maps 1:1 to a Cedar policy statement with proper annotations.
+ *
+ * Annotations are embedded in Cedar text:
+ * ```cedar
+ * @id("rule-001")
+ * @name("Block critical threats")
+ * @severity("high")
+ * @tags("security,baseline")
+ * @compliance("SOC2")
+ * forbid(...) when {...};
+ * ```
+ */
+export interface PolicyRule {
+    /** Predefined annotations (embedded in Cedar text) */
+    annotations: PolicyAnnotations;
+    /** Custom user-defined annotations (embedded in Cedar text) */
+    customAnnotations?: CustomAnnotations;
+    /** Policy effect - permit or forbid */
+    effect: PolicyEffect;
+    /** Principal constraint */
+    principal: PolicyEntity | null;
+    /** Action constraint - single action or array of actions */
+    action: string | string[];
+    /** Resource constraint */
+    resource: PolicyEntity | null;
+    /** Structured conditions (when clause) */
+    conditions: PolicyCondition[];
+    /** Raw condition string (for advanced/complex conditions) */
+    rawCondition?: string;
+    /** Whether this rule is active - NOT embedded in Cedar (runtime state) */
+    enabled: boolean;
+    /** Display/evaluation order - NOT embedded in Cedar (runtime state) */
+    order: number;
+}
+/**
+ * Legacy PolicyRule format for backwards compatibility.
+ * Used when parsing policies that don't have the new annotations structure.
+ *
+ * @deprecated Use PolicyRule with annotations for new code.
  */
-export interface PolicyRule extends PolicyJSON {
-    /** Whether this rule is active (used for toggling rules on/off in UI) */
+export interface LegacyPolicyRule extends PolicyJSON {
     enabled: boolean;
-    /** Display/evaluation order (0-indexed) */
     order: number;
-    /** Optional description (separate from name for longer explanations) */
     description?: string;
-    /** Rule severity for display and prioritization */
     severity?: PolicySeverity;
-    /** Optional tags for categorization and filtering */
     tags?: string[];
 }
 /**
- * A built policy that can be converted to Cedar text or JSON
+ * Convert a legacy PolicyRule to the new annotations-based format.
+ */
+export declare function convertLegacyRule(legacy: LegacyPolicyRule, index?: number): PolicyRule;
+/**
+ * A built policy that can be converted to Cedar text or JSON.
+ * This class is used by PolicyBuilder for the legacy API.
+ *
+ * For new code, use ruleToCedar() and rulesToCedar() functions with PolicyRule.
  */
 export declare class Policy {
     private readonly data;
     constructor(data: PolicyJSON);
     /**
-     * Convert to Cedar policy text
+     * Convert to Cedar policy text.
+     * Uses proper Cedar @annotation syntax.
      */
     toCedar(): string;
-    /**
-     * Convert a condition to Cedar syntax
-     */
-    private conditionToCedar;
-    /**
-     * Convert a value to Cedar string representation
-     */
-    private valueToString;
     /**
      * Get JSON representation for storage
      */
@@ -137,6 +178,54 @@ export declare class Policy {
      */
     getName(): string | undefined;
 }
+/**
+ * Convert a PolicyRule to Cedar policy text with proper annotations.
+ *
+ * @param rule - The PolicyRule to convert
+ * @returns Cedar policy text string
+ *
+ * @example
+ * ```typescript
+ * const rule: PolicyRule = {
+ *   annotations: { id: 'rule-001', name: 'Block threats', severity: 'high' },
+ *   effect: 'forbid',
+ *   principal: null,
+ *   action: 'call_tool',
+ *   resource: null,
+ *   conditions: [{ field: 'threat_count', operator: 'gt', value: 0 }],
+ *   enabled: true,
+ *   order: 0,
+ * };
+ *
+ * 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 };
+ * ```
+ */
+export declare function ruleToCedar(rule: PolicyRule): 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)
+ * @returns Cedar policy text with all rules separated by blank lines
+ *
+ * @example
+ * ```typescript
+ * const rules: PolicyRule[] = [...];
+ * const cedarText = rulesToCedar(rules);
+ * ```
+ */
+export declare function rulesToCedar(rules: PolicyRule[], includeDisabled?: boolean): string;
 /**
  * Builder for constructing Cedar policies with type safety.
  */

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}