@highflame/policy 2.0.8 → 2.0.9

package/src/parser.ts

@@ -1,579 +0,0 @@
-/**
- * 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 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";
-
-/**
- * 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}`;
-
-      // Get engine-serialized Cedar text for rawCondition extraction.
-      // Using cedar-wasm's policyToText ensures we get the official engine's
-      // representation rather than relying on our own text extraction.
-      const engineTextResult = cedar.policyToText(jsonResult.json);
-      const engineText = engineTextResult.type === "success" ? engineTextResult.text : policyText;
-
-      const conversion = cedarJsonToRule(policy, policyId, index, engineText);
-
-      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) => {
-    const ruleId = rule.annotations.id;
-    if (ruleId) {
-      const indices = idOccurrences.get(ruleId) || [];
-      indices.push(idx);
-      idOccurrences.set(ruleId, 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 - uses parseAnnotations to extract structured annotations.
- */
-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 {
-    // 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 = {
-      annotations,
-      customAnnotations,
-      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 conditions
-    const { conditions, rawCondition } = mapConditions(policy.conditions, originalText);
-    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.
- */
-/**
- * Format action entity reference, preserving namespace if present.
- *
- * If entity type is just "Action", returns just the id (e.g., "process_prompt").
- * If entity type has a namespace (e.g., "Overwatch::Action"),
- * returns the fully qualified action string (e.g., 'Overwatch::Action::"process_prompt"').
- */
-function formatActionEntity(entity: { type: string; id: string }): string {
-  if (entity.type !== "Action") {
-    return `${entity.type}::"${entity.id}"`;
-  }
-  return entity.id;
-}
-
-function mapActionScope(scope: CedarActionConstraint): string | string[] {
-  if (scope.op === "All") {
-    return "*";
-  }
-
-  if (scope.op === "==") {
-    if ("entity" in scope) {
-      const entity = normalizeEntityRef(scope.entity);
-      return formatActionEntity(entity);
-    }
-    throw ParserError.actionMissingEntity("==");
-  }
-
-  if (scope.op === "in") {
-    if ("entities" in scope) {
-      const actions = scope.entities.map(e => formatActionEntity(normalizeEntityRef(e)));
-      return actions.length === 1 ? actions[0] : actions;
-    }
-    if ("entity" in scope) {
-      const entity = normalizeEntityRef(scope.entity);
-      return formatActionEntity(entity);
-    }
-    throw ParserError.actionMissingEntities();
-  }
-
-  throw ParserError.actionUnsupportedOp((scope as { op: string }).op);
-}
-
-/**
- * Map Cedar conditions to PolicyCondition array.
- * When conditions can't be mapped to structured format, extract the raw Cedar
- * condition text from the engine-serialized policy text (not JSON AST).
- */
-function mapConditions(conditions: CedarCondition[], originalText?: string): {
-  conditions: PolicyCondition[];
-  rawCondition?: string;
-} {
-  const result: PolicyCondition[] = [];
-  let hasUnmapped = false;
-
-  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) {
-      hasUnmapped = true;
-    }
-  }
-
-  // Extract readable Cedar condition text instead of storing JSON AST
-  let rawCondition: string | undefined;
-  if (hasUnmapped && originalText) {
-    rawCondition = extractWhenClause(originalText);
-  }
-
-  return {
-    conditions: result,
-    rawCondition: rawCondition || undefined,
-  };
-}
-
-/**
- * Extract the readable condition text from a Cedar policy's when clause.
- * Given: `forbid (...)\nwhen { context.path like "/etc/*" };`
- * Returns: `context.path like "/etc/*"`
- */
-function extractWhenClause(cedarText: string): string {
-  const whenPrefix = "when {";
-  const idx = cedarText.indexOf(whenPrefix);
-  if (idx < 0) {
-    return "";
-  }
-
-  const body = cedarText.substring(idx + whenPrefix.length);
-  let depth = 1;
-  for (let i = 0; i < body.length; i++) {
-    if (body[i] === "{") depth++;
-    if (body[i] === "}") {
-      depth--;
-      if (depth === 0) {
-        return body.substring(0, i).trim();
-      }
-    }
-  }
-
-  return body.trim();
-}
-
-/**
- * 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;
-}

package/src/schema.gen.ts

@@ -1,134 +0,0 @@
-// Code generated by highflame-policy-codegen. DO NOT EDIT.
-// Source: schema/highflame.cedarschema
-
-/**
- * Embedded Cedar schema for policy validation.
- * This is the Highflame Cedar schema used across all services.
- */
-export const CEDAR_SCHEMA = `// Highflame Cedar Schema - Entity and Action Definitions
-// =======================================================
-// This file defines all entity types and actions used across Highflame services.
-// Used for code generation (EntityType and ActionType constants).
-//
-// For policy validation, use service-specific schemas:
-// - schemas/overwatch/schema.cedarschema (Guardian IDE security)
-// - schemas/palisade/schema.cedarschema (ML supply chain security)
-
-namespace Highflame {
-
-// =============================================================================
-// ENTITIES
-// =============================================================================
-
-entity User {
-    user_type: String,
-};
-
-entity Agent {
-    agent_type: String,
-};
-
-entity Scanner {
-    scanner_type: String,
-};
-
-entity Service {
-    service_type: String,
-};
-
-entity Resource {};
-
-entity LlmPrompt {
-    prompt_type: String,
-};
-
-entity ResponseData {};
-
-entity Tool {
-    tool_name: String,
-};
-
-entity FilePath {
-    path: String,
-};
-
-entity HttpEndpoint {
-    hostname: String,
-};
-
-entity Server {
-    server_name: String,
-};
-
-entity Artifact {
-    artifact_format: String,
-};
-
-entity Repository {
-    repo_url: String,
-};
-
-entity Package {
-    package_name: String,
-};
-
-entity GitBranch {
-    branch_name: String,
-};
-
-entity Model {
-    model_name: String,
-};
-
-entity ExternalAPI {
-    api_name: String,
-};
-
-entity Memory {
-    memory_type: String,
-};
-
-// =============================================================================
-// ACTIONS
-// =============================================================================
-
-action process_prompt;
-action process_response;
-action invoke_model;
-action filter_content;
-action call_tool;
-action connect_server;
-action access_server_resource;
-action skip_guardrails;
-action read_file;
-action write_file;
-action delete_file;
-action http_request;
-action call_external_api;
-action execute_code;
-action run_tests;
-action run_build;
-action git_operation;
-action git_clone;
-action git_commit;
-action git_push;
-action git_pull;
-action git_merge;
-action git_checkout;
-action git_reset;
-action git_rebase;
-action delegate_task;
-action spawn_subprocess;
-action access_memory;
-action scan_target;
-action scan_package;
-action scan_artifact;
-action validate_integrity;
-action validate_provenance;
-action quarantine_artifact;
-action load_model;
-action deploy_model;
-action transfer_data;
-action export_data;
-}
-`;