@highflame/policy 2.0.2 → 2.0.4

package/src/builder.ts

@@ -14,29 +14,103 @@
  *   .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,
+    generateAnnotationLines,
+    generateRuleId,
+} from './annotations.js';
+
+// ============================================================================
+// Security: Input Validation and Escaping
+// ============================================================================
+
+/**
+ * Valid identifier pattern for Cedar (alphanumeric, underscore, with optional namespace).
+ */
+const VALID_IDENTIFIER_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+/**
+ * Pattern that matches potentially dangerous content in raw conditions.
+ */
+const DANGEROUS_PATTERN_REGEX = /[;}]|\/\/|\/\*|\*\/|permit\s*\(|forbid\s*\(/;
+
+/**
+ * Escape a string value for use in Cedar string literals.
+ * This prevents injection attacks by escaping backslashes and double quotes.
+ */
+function escapeCedarString(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Check if a string is a valid Cedar identifier.
+ */
+function isValidIdentifier(s: string): boolean {
+    return VALID_IDENTIFIER_REGEX.test(s);
+}
+
+/**
+ * Sanitize an identifier, replacing invalid characters with underscores.
+ */
+function sanitizeIdentifier(s: string, context: string): string {
+    if (isValidIdentifier(s)) {
+        return s;
+    }
+    // Replace invalid characters with underscores
+    const sanitized = s.replace(/[^A-Za-z0-9_:]/g, '_');
+    if (sanitized === '' || !isValidIdentifier(sanitized)) {
+        return `invalid_${context}`;
+    }
+    return sanitized;
+}
+
+/**
+ * Validate a raw condition string for potentially dangerous patterns.
+ * Returns true if the condition is safe to use.
+ */
+function isValidRawCondition(condition: string): boolean {
+    return !DANGEROUS_PATTERN_REGEX.test(condition);
+}
 
 /**
  * Format an action string for Cedar policy text.
  * Detects if action is already namespaced (contains 'Action::"') and preserves it,
  * otherwise wraps with Action::"...".
+ * Escapes the action name to prevent injection attacks.
  */
 function formatAction(action: string): string {
     if (action.includes('Action::"')) {
-        // Already namespaced (e.g., 'Overwatch::Action::"call_tool"')
+        // Already namespaced - extract and escape the action name
+        const parts = action.split('Action::"');
+        if (parts.length === 2) {
+            const actionName = parts[1].replace(/"$/, '');
+            return `${parts[0]}Action::"${escapeCedarString(actionName)}"`;
+        }
         return action;
     }
     // Non-namespaced, wrap with Action::"..."
-    return `Action::"${action}"`;
+    return `Action::"${escapeCedarString(action)}"`;
 }
 
 /**
@@ -88,14 +162,14 @@ 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';
+// Re-export PolicySeverity from annotations for backwards compatibility
+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 */
@@ -117,155 +191,125 @@ export interface PolicyJSON {
 }
 
 /**
- * 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 extends PolicyJSON {
-    /** Whether this rule is active (used for toggling rules on/off in UI) */
+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 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 function convertLegacyRule(legacy: LegacyPolicyRule, index: number = 0): PolicyRule {
+    return {
+        annotations: {
+            id: legacy.id || generateRuleId(),
+            name: legacy.name || legacy.id || `Rule ${index + 1}`,
+            description: legacy.description,
+            severity: legacy.severity,
+            tags: legacy.tags,
+        },
+        effect: legacy.effect,
+        principal: legacy.principal,
+        action: legacy.action,
+        resource: legacy.resource,
+        conditions: legacy.conditions,
+        rawCondition: legacy.rawCondition,
+        enabled: legacy.enabled,
+        order: legacy.order,
+    };
+}
+
+/**
+ * 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 class Policy {
     constructor(private readonly data: PolicyJSON) {}
 
     /**
-     * Convert to Cedar policy text
+     * Convert to Cedar policy text.
+     * Uses proper Cedar @annotation syntax.
      */
     toCedar(): string {
         const lines: string[] = [];
 
-        // Policy annotation (comment with name)
-        if (this.data.name) {
-            lines.push(`// @name: ${this.data.name}`);
-        }
-        if (this.data.id) {
-            lines.push(`// @id: ${this.data.id}`);
+        // Generate proper Cedar annotations
+        if (this.data.id || this.data.name) {
+            const annotations: PolicyAnnotations = {
+                id: this.data.id || generateRuleId(),
+                name: this.data.name || this.data.id || 'Unnamed Policy',
+            };
+            lines.push(...generateAnnotationLines(annotations));
         }
 
-        // Effect and principal
-        let policyLine = `${this.data.effect} (`;
-
-        // Principal
-        if (this.data.principal) {
-            if (this.data.principal.id) {
-                policyLine += `\n    principal == ${this.data.principal.type}::\"${this.data.principal.id}\"`;
-            } else {
-                policyLine += `\n    principal is ${this.data.principal.type}`;
-            }
-        } else {
-            policyLine += `\n    principal`;
-        }
-
-        // Action
-        if (Array.isArray(this.data.action)) {
-            if (this.data.action.length === 1) {
-                policyLine += `,\n    action == ${formatAction(this.data.action[0])}`;
-            } else {
-                const actions = this.data.action.map(a => formatAction(a)).join(', ');
-                policyLine += `,\n    action in [${actions}]`;
-            }
-        } else {
-            policyLine += `,\n    action == ${formatAction(this.data.action)}`;
-        }
-
-        // Resource
-        if (this.data.resource) {
-            if (this.data.resource.id) {
-                policyLine += `,\n    resource == ${this.data.resource.type}::\"${this.data.resource.id}\"`;
-            } else {
-                policyLine += `,\n    resource is ${this.data.resource.type}`;
-            }
-        } else {
-            policyLine += `,\n    resource`;
-        }
-
-        policyLine += '\n)';
-        lines.push(policyLine);
-
-        // When clause
-        if (this.data.rawCondition) {
-            lines.push(`when { ${this.data.rawCondition} };`);
-        } else if (this.data.conditions.length > 0) {
-            const conditionStr = this.data.conditions
-                .map(c => this.conditionToCedar(c))
-                .join(' && ');
-            lines.push(`when { ${conditionStr} };`);
-        } else {
-            lines.push(';');
-        }
+        // Generate policy body
+        lines.push(generatePolicyBody(
+            this.data.effect,
+            this.data.principal,
+            this.data.action,
+            this.data.resource,
+            this.data.conditions,
+            this.data.rawCondition
+        ));
 
         return lines.join('\n');
     }
 
-    /**
-     * Convert a condition to Cedar syntax
-     */
-    private conditionToCedar(condition: PolicyCondition): string {
-        const { field, operator, value } = condition;
-        const valueStr = this.valueToString(value);
-
-        switch (operator) {
-            case 'eq':
-                return `context.${field} == ${valueStr}`;
-            case 'neq':
-                return `context.${field} != ${valueStr}`;
-            case 'lt':
-                return `context.${field} < ${valueStr}`;
-            case 'lte':
-                return `context.${field} <= ${valueStr}`;
-            case 'gt':
-                return `context.${field} > ${valueStr}`;
-            case 'gte':
-                return `context.${field} >= ${valueStr}`;
-            case 'contains':
-                return `context.${field}.contains(${valueStr})`;
-            case 'in':
-                if (Array.isArray(value)) {
-                    const items = value.map(v => `\"${v}\"`).join(', ');
-                    return `context.${field} in [${items}]`;
-                }
-                return `context.${field} in ${valueStr}`;
-            case 'like':
-                return `context.${field} like ${valueStr}`;
-            default:
-                return `context.${field} == ${valueStr}`;
-        }
-    }
-
-    /**
-     * Convert a value to Cedar string representation
-     */
-    private valueToString(value: string | number | boolean | string[]): string {
-        if (typeof value === 'string') {
-            return `\"${value}\"`;
-        }
-        if (typeof value === 'number' || typeof value === 'boolean') {
-            return String(value);
-        }
-        if (Array.isArray(value)) {
-            return `[${value.map(v => `\"${v}\"`).join(', ')}]`;
-        }
-        return String(value);
-    }
-
     /**
      * Get JSON representation for storage
      */
@@ -288,6 +332,221 @@ export class Policy {
     }
 }
 
+// ============================================================================
+// Cedar Generation Functions
+// ============================================================================
+
+/**
+ * Convert a condition to Cedar syntax.
+ * Field names are sanitized to prevent injection attacks.
+ */
+function conditionToCedar(condition: PolicyCondition): string {
+    const field = sanitizeIdentifier(condition.field, 'field');
+    const { operator, value } = condition;
+    const valueStr = valueToString(value);
+
+    switch (operator) {
+        case 'eq':
+            return `context.${field} == ${valueStr}`;
+        case 'neq':
+            return `context.${field} != ${valueStr}`;
+        case 'lt':
+            return `context.${field} < ${valueStr}`;
+        case 'lte':
+            return `context.${field} <= ${valueStr}`;
+        case 'gt':
+            return `context.${field} > ${valueStr}`;
+        case 'gte':
+            return `context.${field} >= ${valueStr}`;
+        case 'contains':
+            return `context.${field}.contains(${valueStr})`;
+        case 'in':
+            if (Array.isArray(value)) {
+                const items = value.map(v => `"${escapeCedarString(v)}"`).join(', ');
+                return `context.${field} in [${items}]`;
+            }
+            return `context.${field} in ${valueStr}`;
+        case 'like':
+            return `context.${field} like ${valueStr}`;
+        default:
+            return `context.${field} == ${valueStr}`;
+    }
+}
+
+/**
+ * Convert a value to Cedar string representation.
+ * String values are escaped to prevent injection attacks.
+ */
+function valueToString(value: string | number | boolean | string[]): string {
+    if (typeof value === 'string') {
+        return `"${escapeCedarString(value)}"`;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(v => `"${escapeCedarString(v)}"`).join(', ')}]`;
+    }
+    return String(value);
+}
+
+/**
+ * Generate the Cedar policy body (permit/forbid statement).
+ * All inputs are sanitized/escaped to prevent injection attacks.
+ */
+function generatePolicyBody(
+    effect: PolicyEffect,
+    principal: PolicyEntity | null,
+    action: string | string[],
+    resource: PolicyEntity | null,
+    conditions: PolicyCondition[],
+    rawCondition?: string
+): string {
+    let policyLine = `${effect} (`;
+
+    // Principal
+    if (principal) {
+        const entityType = sanitizeIdentifier(principal.type, 'principal_type');
+        if (principal.id) {
+            policyLine += `\n    principal == ${entityType}::"${escapeCedarString(principal.id)}"`;
+        } else {
+            policyLine += `\n    principal is ${entityType}`;
+        }
+    } else {
+        policyLine += `\n    principal`;
+    }
+
+    // Action
+    if (Array.isArray(action)) {
+        if (action.length === 1) {
+            policyLine += `,\n    action == ${formatAction(action[0])}`;
+        } else {
+            const actions = action.map(a => formatAction(a)).join(', ');
+            policyLine += `,\n    action in [${actions}]`;
+        }
+    } else {
+        policyLine += `,\n    action == ${formatAction(action)}`;
+    }
+
+    // Resource
+    if (resource) {
+        const entityType = sanitizeIdentifier(resource.type, 'resource_type');
+        if (resource.id) {
+            policyLine += `,\n    resource == ${entityType}::"${escapeCedarString(resource.id)}"`;
+        } else {
+            policyLine += `,\n    resource is ${entityType}`;
+        }
+    } else {
+        policyLine += `,\n    resource`;
+    }
+
+    policyLine += '\n)';
+
+    // When clause
+    // SECURITY: rawCondition is validated to prevent injection attacks.
+    // If validation fails, fall back to structured conditions.
+    if (rawCondition) {
+        if (isValidRawCondition(rawCondition)) {
+            policyLine += `\nwhen { ${rawCondition} };`;
+        } else if (conditions.length > 0) {
+            // Fallback to structured conditions if rawCondition is rejected
+            const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+            policyLine += `\nwhen { ${conditionStr} };`;
+        } else {
+            policyLine += ';';
+        }
+    } else if (conditions.length > 0) {
+        const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
+        policyLine += `\nwhen { ${conditionStr} };`;
+    } else {
+        policyLine += ';';
+    }
+
+    return policyLine;
+}
+
+/**
+ * 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 function ruleToCedar(rule: PolicyRule): string {
+    const lines: string[] = [];
+
+    // 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
+    ));
+
+    return lines.join('\n');
+}
+
+/**
+ * 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 function rulesToCedar(rules: PolicyRule[], includeDisabled: boolean = false): string {
+    const sortedRules = [...rules].sort((a, b) => a.order - b.order);
+
+    const cedarPolicies: string[] = [];
+    for (const rule of sortedRules) {
+        if (rule.enabled) {
+            cedarPolicies.push(ruleToCedar(rule));
+        } else if (includeDisabled) {
+            // Include disabled rules as comments
+            const cedarLines = ruleToCedar(rule).split('\n');
+            cedarPolicies.push(cedarLines.map(line => `// [DISABLED] ${line}`).join('\n'));
+        }
+    }
+
+    return cedarPolicies.join('\n\n');
+}
+
 /**
  * Builder for constructing Cedar policies with type safety.
  */

package/src/index.ts

@@ -14,6 +14,7 @@ export * from './engine.js';
 export * from './builder.js';
 export * from './parser.js';
 export * from './errors.js';
+export * from './annotations.js';
 
 // Service-specific schemas and context (inlined)
 export {

package/src/parser.test.ts

@@ -26,7 +26,7 @@ describe('parseCedarToRules', () => {
     expect(result.unstructured).toHaveLength(0);
 
     const rule = result.rules[0];
-    expect(rule.id).toBe('allow-read-files');
+    expect(rule.annotations.id).toBe('allow-read-files');
     expect(rule.effect).toBe('permit');
     expect(rule.principal).toEqual({ type: 'User' });
     expect(rule.action).toBe('read_file');
@@ -53,7 +53,7 @@ describe('parseCedarToRules', () => {
     expect(result.rules).toHaveLength(1);
 
     const rule = result.rules[0];
-    expect(rule.id).toBe('block-high-risk');
+    expect(rule.annotations.id).toBe('block-high-risk');
     expect(rule.effect).toBe('forbid');
     expect(rule.action).toBe('execute_tool');
 

package/src/parser.ts

@@ -6,11 +6,12 @@
  *
  * Architecture:
  * 1. Cedar text → Cedar JSON (via cedar-wasm policyToJson)
- * 2. Cedar JSON → PolicyRule (simple JSON mapping)
+ * 2. Cedar JSON → PolicyRule (simple JSON mapping with annotation extraction)
  */
 
 import * as cedar from "@cedar-policy/cedar-wasm/nodejs";
 import type { PolicyRule, PolicyCondition, PolicyEntity, PolicyEffect, ConditionOperator } from "./builder.js";
+import { parseAnnotations, generateRuleId } from "./annotations.js";
 import { ParserError, ErrorCodes } from "./errors.js";
 
 /**
@@ -145,10 +146,11 @@ export function parseCedarToRules(cedarText: string): ParseResult {
   // Check for duplicate policy IDs and add warnings
   const idOccurrences = new Map<string, number[]>();
   result.rules.forEach((rule, idx) => {
-    if (rule.id) {
-      const indices = idOccurrences.get(rule.id) || [];
+    const ruleId = rule.annotations.id;
+    if (ruleId) {
+      const indices = idOccurrences.get(ruleId) || [];
       indices.push(idx);
-      idOccurrences.set(rule.id, indices);
+      idOccurrences.set(ruleId, indices);
     }
   });
   for (const [id, indices] of idOccurrences) {
@@ -164,7 +166,7 @@ export function parseCedarToRules(cedarText: string): ParseResult {
 
 /**
  * Convert Cedar JSON policy to PolicyRule.
- * This is pure JSON mapping - no parsing logic.
+ * This is pure JSON mapping - uses parseAnnotations to extract structured annotations.
  */
 function cedarJsonToRule(
   policy: CedarPolicyJSON,
@@ -181,9 +183,20 @@ function cedarJsonToRule(
   }
 
   try {
+    // Parse annotations using the shared utility
+    const { annotations, customAnnotations } = parseAnnotations(policy.annotations);
+
+    // Ensure id and name have sensible defaults
+    if (!annotations.id) {
+      annotations.id = policyId || generateRuleId();
+    }
+    if (!annotations.name) {
+      annotations.name = annotations.id;
+    }
+
     const rule: PolicyRule = {
-      id: policy.annotations?.id || policyId,
-      name: policy.annotations?.name || policy.annotations?.id || policyId,
+      annotations,
+      customAnnotations,
       effect: policy.effect as PolicyEffect,
       principal: mapScopeToEntity(policy.principal, "principal"),
       action: mapActionScope(policy.action),
@@ -193,11 +206,6 @@ function cedarJsonToRule(
       order: index,
     };
 
-    // Map description from annotations
-    if (policy.annotations?.description) {
-      rule.description = policy.annotations.description;
-    }
-
     // Map conditions
     const { conditions, rawCondition } = mapConditions(policy.conditions);
     rule.conditions = conditions;