@highflame/policy 1.1.3 → 1.2.1

package/src/parser.ts

@@ -0,0 +1,517 @@
+/**
+ * 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";
+import { ParserError, ErrorCodes } from "./errors.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)}`);
+  }
+
+  // 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) || [];
+      indices.push(idx);
+      idOccurrences.set(rule.id, indices);
+    }
+  });
+  for (const [id, indices] of idOccurrences) {
+    if (indices.length > 1) {
+      result.errors.push(
+        `[${ErrorCodes.PARSE_DUPLICATE_ID}] Duplicate policy ID '${id}' found at indices [${indices.join(", ")}]`
+      );
+    }
+  }
+
+  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 };
+  }
+
+  try {
+    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, "principal"),
+      action: mapActionScope(policy.action),
+      resource: mapScopeToEntity(policy.resource, "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 };
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e);
+    const raw = originalText || getRawCedar(policyId, policy);
+    return { raw, error };
+  }
+}
+
+/**
+ * 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
+  }
+  // Sanitize policyId to prevent newline injection attacks
+  const safeId = policyId.replace(/[\n\r]/g, " ");
+  return `// Complex policy: ${safeId}`;
+}
+
+/**
+ * Map Cedar scope constraint to PolicyEntity
+ *
+ * Returns null for unconstrained ("All") scopes.
+ * Throws ParserError for malformed constraints to prevent silent misinterpretation.
+ *
+ * @param scope - The Cedar scope constraint
+ * @param field - The field name ("principal" or "resource") for error context
+ */
+function mapScopeToEntity(scope: CedarScopeConstraint, field: string): 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 };
+    }
+    if ("slot" in scope) {
+      throw ParserError.scopeSlotNotSupported("==", field);
+    }
+    throw ParserError.scopeMissingEntity("==", field);
+  }
+
+  if (scope.op === "is") {
+    if (scope.entity_type) {
+      return { type: scope.entity_type };
+    }
+    throw ParserError.scopeMissingEntityType(field);
+  }
+
+  if (scope.op === "in") {
+    if ("entity" in scope) {
+      const entity = normalizeEntityRef(scope.entity);
+      return { type: entity.type, id: entity.id };
+    }
+    if ("slot" in scope) {
+      throw ParserError.scopeSlotNotSupported("in", field);
+    }
+    throw ParserError.scopeMissingEntityList(field);
+  }
+
+  throw ParserError.scopeUnsupportedOp((scope as { op: string }).op, field);
+}
+
+/**
+ * Map action scope to action string(s)
+ *
+ * Throws ParserError for malformed constraints to prevent silent misinterpretation.
+ */
+function mapActionScope(scope: CedarActionConstraint): string | string[] {
+  if (scope.op === "All") {
+    return "*";
+  }
+
+  if (scope.op === "==") {
+    if ("entity" in scope) {
+      const entity = normalizeEntityRef(scope.entity);
+      return entity.id;
+    }
+    throw ParserError.actionMissingEntity("==");
+  }
+
+  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;
+    }
+    throw ParserError.actionMissingEntities();
+  }
+
+  throw ParserError.actionUnsupportedOp((scope as { op: string }).op);
+}
+
+/**
+ * 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);
+    }
+  }
+
+  // Store raw conditions as a valid JSON array instead of joining with " && "
+  // This ensures downstream systems can parse the rawCondition field
+  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*")
+  // Escape literal * characters to distinguish from wildcards on round-trip
+  const patternStr = args.pattern.map(p => {
+    if (p === "Wildcard") return "*";
+    if (typeof p === "object" && "Literal" in p) return p.Literal.replace(/\*/g, "\\*");
+    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;
+}