@highflame/policy 1.1.3 → 1.2.0

package/src/parser.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Parser unit tests
+ *
+ * Tests the Cedar text → PolicyRule conversion using the official Cedar engine.
+ * These tests demonstrate how a client like highflame-authz would use the parser.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseCedarToRules } from './parser.js';
+
+describe('parseCedarToRules', () => {
+  it('should parse a simple permit policy', () => {
+    const cedarText = `
+      @id("allow-read-files")
+      permit(
+        principal is User,
+        action == Action::"read_file",
+        resource is FilePath
+      );
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.rules).toHaveLength(1);
+    expect(result.unstructured).toHaveLength(0);
+
+    const rule = result.rules[0];
+    expect(rule.id).toBe('allow-read-files');
+    expect(rule.effect).toBe('permit');
+    expect(rule.principal).toEqual({ type: 'User' });
+    expect(rule.action).toBe('read_file');
+    expect(rule.resource).toEqual({ type: 'FilePath' });
+    expect(rule.enabled).toBe(true);
+  });
+
+  it('should parse a policy with when conditions', () => {
+    const cedarText = `
+      @id("block-high-risk")
+      forbid(
+        principal,
+        action == Action::"execute_tool",
+        resource
+      )
+      when {
+        context.threat_level == "high"
+      };
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.rules).toHaveLength(1);
+
+    const rule = result.rules[0];
+    expect(rule.id).toBe('block-high-risk');
+    expect(rule.effect).toBe('forbid');
+    expect(rule.action).toBe('execute_tool');
+
+    // Check condition was parsed
+    expect(rule.conditions.length).toBeGreaterThanOrEqual(0);
+    // If condition parsing works, it should have the condition
+    // If not, it should be in rawCondition
+    if (rule.conditions.length > 0) {
+      expect(rule.conditions[0].field).toBe('threat_level');
+      expect(rule.conditions[0].operator).toBe('eq');
+      expect(rule.conditions[0].value).toBe('high');
+    } else {
+      expect(rule.rawCondition).toBeDefined();
+    }
+  });
+
+  it('should return errors for invalid Cedar syntax', () => {
+    const invalidCedar = `
+      permit(
+        principal is User
+        // missing comma and rest of policy
+    `;
+
+    const result = parseCedarToRules(invalidCedar);
+
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('should handle multiple policies', () => {
+    const cedarText = `
+      @id("rule-1")
+      permit(principal, action == Action::"read", resource);
+
+      @id("rule-2")
+      forbid(principal, action == Action::"delete", resource);
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.rules).toHaveLength(2);
+    expect(result.rules[0].effect).toBe('permit');
+    expect(result.rules[1].effect).toBe('forbid');
+  });
+
+  it('should put policies with unless clauses in unstructured', () => {
+    const cedarText = `
+      permit(principal, action, resource)
+      unless {
+        context.is_blocked == true
+      };
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    // Unless clauses can't be represented as PolicyRule
+    expect(result.rules).toHaveLength(0);
+    expect(result.unstructured.length).toBeGreaterThan(0);
+  });
+});

package/src/parser.ts

@@ -0,0 +1,470 @@
+/**
+ * Cedar Policy Parser
+ *
+ * Converts Cedar policy text to structured PolicyRule format using the
+ * official Cedar engine (cedar-wasm) for parsing.
+ *
+ * Architecture:
+ * 1. Cedar text → Cedar JSON (via cedar-wasm policyToJson)
+ * 2. Cedar JSON → PolicyRule (simple JSON mapping)
+ */
+
+import * as cedar from "@cedar-policy/cedar-wasm/nodejs";
+import type { PolicyRule, PolicyCondition, PolicyEntity, PolicyEffect, ConditionOperator } from "./builder.js";
+
+/**
+ * Result of parsing Cedar policies
+ */
+export interface ParseResult {
+  /** Policies successfully converted to PolicyRule format */
+  rules: PolicyRule[];
+  /** Policies that couldn't be fully represented as PolicyRule (raw Cedar text) */
+  unstructured: string[];
+  /** Any parsing errors encountered */
+  errors: string[];
+}
+
+/**
+ * Cedar's JSON policy format (from cedar-wasm)
+ * @see https://docs.cedarpolicy.com/policies/json-format.html
+ */
+interface CedarPolicyJSON {
+  effect: "permit" | "forbid";
+  principal: CedarScopeConstraint;
+  action: CedarActionConstraint;
+  resource: CedarScopeConstraint;
+  conditions: CedarCondition[];
+  annotations?: Record<string, string>;
+}
+
+// Principal/Resource constraint types
+type CedarScopeConstraint =
+  | { op: "All" }
+  | { op: "=="; entity: CedarEntityRef }
+  | { op: "=="; slot: string }
+  | { op: "in"; entity: CedarEntityRef }
+  | { op: "in"; slot: string }
+  | { op: "is"; entity_type: string; in?: { entity: CedarEntityRef } | { slot: string } };
+
+// Action constraint types (slightly different from principal/resource)
+type CedarActionConstraint =
+  | { op: "All" }
+  | { op: "=="; entity: CedarEntityRef }
+  | { op: "in"; entity: CedarEntityRef }
+  | { op: "in"; entities: CedarEntityRef[] };
+
+// Entity UID can be { type, id } or { __entity: { type, id } }
+type CedarEntityRef =
+  | { type: string; id: string }
+  | { __entity: { type: string; id: string } };
+
+interface CedarCondition {
+  kind: "when" | "unless";
+  body: Record<string, unknown>;
+}
+
+/**
+ * Normalize entity reference to simple { type, id } format
+ */
+function normalizeEntityRef(ref: CedarEntityRef): { type: string; id: string } {
+  if ("__entity" in ref) {
+    return ref.__entity;
+  }
+  return ref;
+}
+
+/**
+ * Parse Cedar policy text and convert to PolicyRule format.
+ *
+ * Uses the official cedar-wasm engine for parsing, ensuring correctness.
+ * Policies with features that can't be represented as PolicyRule (e.g.,
+ * unless clauses, complex expressions) are returned in the unstructured array.
+ *
+ * @param cedarText - Cedar policy text to parse
+ * @returns ParseResult with structured rules, unstructured policies, and errors
+ */
+export function parseCedarToRules(cedarText: string): ParseResult {
+  const result: ParseResult = {
+    rules: [],
+    unstructured: [],
+    errors: [],
+  };
+
+  try {
+    // Split the policy set into individual policies and templates
+    const partsResult = cedar.policySetTextToParts(cedarText);
+
+    if (partsResult.type === "failure") {
+      for (const error of partsResult.errors) {
+        result.errors.push(error.message);
+      }
+      return result;
+    }
+
+    // Process each policy
+    let index = 0;
+    for (const policyText of partsResult.policies) {
+      // Convert individual policy to JSON using cedar-wasm
+      const jsonResult = cedar.policyToJson(policyText);
+
+      if (jsonResult.type === "failure") {
+        for (const error of jsonResult.errors) {
+          result.errors.push(`Policy ${index}: ${error.message}`);
+        }
+        index++;
+        continue;
+      }
+
+      const policy = jsonResult.json as CedarPolicyJSON;
+      const policyId = policy.annotations?.id || `policy${index}`;
+      const conversion = cedarJsonToRule(policy, policyId, index, policyText);
+
+      if (conversion.error) {
+        result.errors.push(`Policy ${policyId}: ${conversion.error}`);
+      }
+
+      if (conversion.rule) {
+        result.rules.push(conversion.rule);
+      } else if (conversion.raw) {
+        result.unstructured.push(conversion.raw);
+      }
+
+      index++;
+    }
+
+    // Templates can't be represented as PolicyRule
+    for (const templateText of partsResult.policy_templates) {
+      result.unstructured.push(templateText);
+    }
+
+  } catch (e) {
+    result.errors.push(`Parse error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  return result;
+}
+
+/**
+ * Convert Cedar JSON policy to PolicyRule.
+ * This is pure JSON mapping - no parsing logic.
+ */
+function cedarJsonToRule(
+  policy: CedarPolicyJSON,
+  policyId: string,
+  index: number,
+  originalText?: string
+): { rule?: PolicyRule; raw?: string; error?: string } {
+
+  // Check if this policy can be represented as PolicyRule
+  if (!canRepresentAsRule(policy)) {
+    // Return original text if available, otherwise convert back from JSON
+    const raw = originalText || getRawCedar(policyId, policy);
+    return { raw };
+  }
+
+  const rule: PolicyRule = {
+    id: policy.annotations?.id || policyId,
+    name: policy.annotations?.name || policy.annotations?.id || policyId,
+    effect: policy.effect as PolicyEffect,
+    principal: mapScopeToEntity(policy.principal),
+    action: mapActionScope(policy.action),
+    resource: mapScopeToEntity(policy.resource),
+    conditions: [],
+    enabled: true,
+    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;
+  if (rawCondition) {
+    rule.rawCondition = rawCondition;
+  }
+
+  return { rule };
+}
+
+/**
+ * Check if a Cedar policy can be represented as PolicyRule
+ */
+function canRepresentAsRule(policy: CedarPolicyJSON): boolean {
+  // Unless clauses can't be represented
+  for (const cond of policy.conditions) {
+    if (cond.kind === "unless") {
+      return false;
+    }
+  }
+
+  // Template slots can't be represented
+  if (hasSlot(policy.principal) || hasSlot(policy.resource)) {
+    return false;
+  }
+
+  // Multiple entity "in" constraints are complex
+  const action = policy.action;
+  if (action.op === "in" && "entities" in action && action.entities.length > 1) {
+    // Multiple actions are OK, we handle those
+  }
+
+  return true;
+}
+
+/**
+ * Check if a scope constraint uses a slot (template)
+ */
+function hasSlot(scope: CedarScopeConstraint): boolean {
+  if (scope.op === "All" || scope.op === "is") {
+    return false;
+  }
+  return "slot" in scope;
+}
+
+/**
+ * Get raw Cedar text for a policy that can't be represented as PolicyRule
+ */
+function getRawCedar(policyId: string, policy: CedarPolicyJSON): string {
+  try {
+    // policyToText accepts Policy which is string | PolicyJson
+    const textResult = cedar.policyToText(policy as cedar.PolicyJson);
+    if (textResult.type === "success") {
+      return textResult.text;
+    }
+  } catch {
+    // Ignore conversion errors
+  }
+  return `// Complex policy: ${policyId}`;
+}
+
+/**
+ * Map Cedar scope constraint to PolicyEntity
+ */
+function mapScopeToEntity(scope: CedarScopeConstraint): PolicyEntity | null {
+  if (scope.op === "All") {
+    return null;
+  }
+
+  if (scope.op === "==") {
+    if ("entity" in scope) {
+      const entity = normalizeEntityRef(scope.entity);
+      return { type: entity.type, id: entity.id };
+    }
+    // Slot - can't represent
+    return null;
+  }
+
+  if (scope.op === "is") {
+    // Type constraint
+    return { type: scope.entity_type };
+  }
+
+  if (scope.op === "in") {
+    if ("entity" in scope) {
+      const entity = normalizeEntityRef(scope.entity);
+      return { type: entity.type, id: entity.id };
+    }
+    // Slot - can't represent
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Map action scope to action string(s)
+ */
+function mapActionScope(scope: CedarActionConstraint): string | string[] {
+  if (scope.op === "All") {
+    return "*";
+  }
+
+  if (scope.op === "==") {
+    const entity = normalizeEntityRef(scope.entity);
+    return entity.id;
+  }
+
+  if (scope.op === "in") {
+    if ("entities" in scope) {
+      const actions = scope.entities.map(e => normalizeEntityRef(e).id);
+      return actions.length === 1 ? actions[0] : actions;
+    }
+    if ("entity" in scope) {
+      const entity = normalizeEntityRef(scope.entity);
+      return entity.id;
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Map Cedar conditions to PolicyCondition array
+ */
+function mapConditions(conditions: CedarCondition[]): {
+  conditions: PolicyCondition[];
+  rawCondition?: string;
+} {
+  const result: PolicyCondition[] = [];
+  const rawParts: string[] = [];
+
+  for (const cond of conditions) {
+    if (cond.kind !== "when") {
+      continue;
+    }
+
+    const parsed = mapConditionBody(cond.body);
+    if (parsed.condition) {
+      result.push(parsed.condition);
+    } else if (parsed.raw) {
+      rawParts.push(parsed.raw);
+    }
+  }
+
+  return {
+    conditions: result,
+    rawCondition: rawParts.length > 0 ? rawParts.join(" && ") : undefined,
+  };
+}
+
+/**
+ * Cedar expression types (subset used for condition mapping)
+ */
+interface CedarExpr {
+  "."?: { left: CedarExpr; attr: string };
+  Var?: string;
+  Value?: unknown;
+  "=="?: { left: CedarExpr; right: CedarExpr };
+  "!="?: { left: CedarExpr; right: CedarExpr };
+  "<"?: { left: CedarExpr; right: CedarExpr };
+  "<="?: { left: CedarExpr; right: CedarExpr };
+  ">"?: { left: CedarExpr; right: CedarExpr };
+  ">="?: { left: CedarExpr; right: CedarExpr };
+  contains?: { left: CedarExpr; right: CedarExpr };
+  like?: { left: CedarExpr; pattern: Array<"Wildcard" | { Literal: string }> };
+}
+
+/**
+ * Map a Cedar expression body to PolicyCondition
+ *
+ * Cedar JSON expressions use nested objects with operator keys.
+ * Comparison format: { "==": { left: { ".": { left: { Var: "context" }, attr: "field" } }, right: { Value: "x" } } }
+ */
+function mapConditionBody(body: Record<string, unknown>): {
+  condition?: PolicyCondition;
+  raw?: string;
+} {
+  const expr = body as CedarExpr;
+
+  // Check comparison operators
+  for (const op of ["==", "!=", "<", "<=", ">", ">="] as const) {
+    const comparison = expr[op];
+    if (comparison) {
+      const condition = mapComparison(op, comparison);
+      if (condition) return { condition };
+    }
+  }
+
+  // Check contains
+  if (expr.contains) {
+    const condition = mapContains(expr.contains);
+    if (condition) return { condition };
+  }
+
+  // Check like
+  if (expr.like) {
+    const condition = mapLike(expr.like);
+    if (condition) return { condition };
+  }
+
+  // Can't map - return as raw JSON
+  return { raw: JSON.stringify(body) };
+}
+
+function mapComparison(op: string, args: { left: CedarExpr; right: CedarExpr }): PolicyCondition | null {
+  const field = extractContextField(args.left);
+  if (!field) return null;
+
+  const value = extractLiteralValue(args.right);
+  if (value === undefined) return null;
+
+  const operator = mapOperator(op);
+  if (!operator) return null;
+
+  return { field, operator, value };
+}
+
+function mapContains(args: { left: CedarExpr; right: CedarExpr }): PolicyCondition | null {
+  const field = extractContextField(args.left);
+  if (!field) return null;
+
+  const value = extractLiteralValue(args.right);
+  if (value === undefined) return null;
+
+  return { field, operator: "contains", value };
+}
+
+function mapLike(args: { left: CedarExpr; pattern: Array<"Wildcard" | { Literal: string }> }): PolicyCondition | null {
+  const field = extractContextField(args.left);
+  if (!field) return null;
+
+  // Convert pattern to string (e.g., ["Wildcard", { Literal: "foo" }, "Wildcard"] -> "*foo*")
+  const patternStr = args.pattern.map(p => {
+    if (p === "Wildcard") return "*";
+    if (typeof p === "object" && "Literal" in p) return p.Literal;
+    return "";
+  }).join("");
+
+  return { field, operator: "like", value: patternStr };
+}
+
+/**
+ * Extract field name from context.field access pattern
+ * Pattern: { ".": { left: { Var: "context" }, attr: "field_name" } }
+ */
+function extractContextField(expr: CedarExpr): string | null {
+  const dotAccess = expr["."];
+  if (!dotAccess) return null;
+
+  // Check if accessing context variable
+  const leftExpr = dotAccess.left;
+  if (leftExpr.Var !== "context") return null;
+
+  return dotAccess.attr;
+}
+
+/**
+ * Extract literal value from Cedar JSON
+ * Pattern: { Value: <literal> }
+ */
+function extractLiteralValue(expr: CedarExpr): string | number | boolean | string[] | undefined {
+  if (!("Value" in expr)) return undefined;
+
+  const value = expr.Value;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value) && value.every(v => typeof v === "string")) {
+    return value as string[];
+  }
+
+  return undefined;
+}
+
+/**
+ * Map Cedar operator to ConditionOperator
+ */
+function mapOperator(cedarOp: string): ConditionOperator | null {
+  const mapping: Record<string, ConditionOperator> = {
+    "==": "eq",
+    "!=": "neq",
+    "<": "lt",
+    "<=": "lte",
+    ">": "gt",
+    ">=": "gte",
+  };
+  return mapping[cedarOp] || null;
+}