@highflame/policy 1.1.3 → 1.2.1

package/src/errors.ts

@@ -0,0 +1,195 @@
+/**
+ * Parser error types and codes for highflame-policy.
+ *
+ * This module provides standardized error codes that are consistent
+ * across all language implementations (Rust, Go, TypeScript, Python).
+ */
+
+/**
+ * Error codes for parser errors.
+ *
+ * These codes are stable and consistent across all language implementations.
+ * Format: HFP-<CATEGORY>-<NUMBER>
+ * - HFP = HighFlame Policy
+ * - CATEGORY = SCOPE | ACTION | COND | PARSE
+ * - NUMBER = 3-digit incremental
+ */
+export const ErrorCodes = {
+  // Scope constraint errors (HFP-SCOPE-xxx)
+  /** Scope constraint is missing an entity (for == operator) */
+  SCOPE_MISSING_ENTITY: "HFP-SCOPE-001",
+  /** Scope constraint is missing an entity type (for is operator) */
+  SCOPE_MISSING_ENTITY_TYPE: "HFP-SCOPE-002",
+  /** Scope constraint is missing entity list (for in operator) */
+  SCOPE_MISSING_ENTITY_LIST: "HFP-SCOPE-003",
+  /** Slot constraints are not supported in PolicyRule */
+  SCOPE_SLOT_NOT_SUPPORTED: "HFP-SCOPE-004",
+  /** Unsupported scope operator */
+  SCOPE_UNSUPPORTED_OP: "HFP-SCOPE-005",
+
+  // Action constraint errors (HFP-ACTION-xxx)
+  /** Action constraint is missing an entity (for == operator) */
+  ACTION_MISSING_ENTITY: "HFP-ACTION-001",
+  /** Action constraint is missing entities (for in operator) */
+  ACTION_MISSING_ENTITIES: "HFP-ACTION-002",
+  /** Unsupported action operator */
+  ACTION_UNSUPPORTED_OP: "HFP-ACTION-003",
+  /** Action scope is null/nil */
+  ACTION_SCOPE_NIL: "HFP-ACTION-004",
+
+  // Condition errors (HFP-COND-xxx)
+  /** Unless clauses are not supported in PolicyRule */
+  COND_UNLESS_NOT_SUPPORTED: "HFP-COND-001",
+  /** Complex condition cannot be parsed */
+  COND_COMPLEX_EXPRESSION: "HFP-COND-002",
+
+  // Parse errors (HFP-PARSE-xxx)
+  /** Invalid Cedar syntax */
+  PARSE_INVALID_SYNTAX: "HFP-PARSE-001",
+  /** Failed to convert policy to JSON */
+  PARSE_JSON_CONVERSION: "HFP-PARSE-002",
+  /** Failed to parse Cedar JSON structure */
+  PARSE_JSON_STRUCTURE: "HFP-PARSE-003",
+  /** Unknown policy effect (not permit or forbid) */
+  PARSE_UNKNOWN_EFFECT: "HFP-PARSE-004",
+  /** Duplicate policy ID found */
+  PARSE_DUPLICATE_ID: "HFP-PARSE-005",
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Context information for parser errors.
+ */
+export interface ErrorContext {
+  /** The operator that caused the error (e.g., "==", "in", "is") */
+  operator?: string;
+  /** The field that caused the error (e.g., "principal", "action", "resource") */
+  field?: string;
+  /** The policy ID if available */
+  policyId?: string;
+}
+
+/**
+ * A structured parser error with code, message, and optional context.
+ */
+export class ParserError extends Error {
+  /** Machine-readable error code (e.g., "HFP-SCOPE-001") */
+  public readonly code: ErrorCode;
+  /** Optional context for debugging */
+  public readonly context?: ErrorContext;
+
+  constructor(code: ErrorCode, message: string, context?: ErrorContext) {
+    super(message);
+    this.name = "ParserError";
+    this.code = code;
+    this.context = context;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    const ErrorWithCapture = Error as typeof Error & { captureStackTrace?: (err: Error, constructor: Function) => void };
+    if (ErrorWithCapture.captureStackTrace) {
+      ErrorWithCapture.captureStackTrace(this, ParserError);
+    }
+  }
+
+  /**
+   * Returns a string representation including the error code.
+   */
+  override toString(): string {
+    return `[${this.code}] ${this.message}`;
+  }
+
+  /**
+   * Serializes the error to a plain object for JSON serialization.
+   */
+  toJSON(): { code: string; message: string; context?: ErrorContext } {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.context && { context: this.context }),
+    };
+  }
+
+  // Convenience static factory methods for common errors
+
+  /** Scope constraint is missing an entity */
+  static scopeMissingEntity(operator: string, field: string): ParserError {
+    return new ParserError(
+      ErrorCodes.SCOPE_MISSING_ENTITY,
+      `'${operator}' constraint is missing an entity`,
+      { operator, field }
+    );
+  }
+
+  /** Scope constraint is missing an entity type */
+  static scopeMissingEntityType(field: string): ParserError {
+    return new ParserError(
+      ErrorCodes.SCOPE_MISSING_ENTITY_TYPE,
+      "'is' constraint is missing an entity_type",
+      { operator: "is", field }
+    );
+  }
+
+  /** Scope constraint is missing entity list */
+  static scopeMissingEntityList(field: string): ParserError {
+    return new ParserError(
+      ErrorCodes.SCOPE_MISSING_ENTITY_LIST,
+      "'in' constraint is missing an entity",
+      { operator: "in", field }
+    );
+  }
+
+  /** Slot constraints are not supported */
+  static scopeSlotNotSupported(operator: string, field: string): ParserError {
+    return new ParserError(
+      ErrorCodes.SCOPE_SLOT_NOT_SUPPORTED,
+      `'${operator}' constraint with slot cannot be represented`,
+      { operator, field }
+    );
+  }
+
+  /** Unsupported scope operator */
+  static scopeUnsupportedOp(operator: string, field: string): ParserError {
+    return new ParserError(
+      ErrorCodes.SCOPE_UNSUPPORTED_OP,
+      `Unsupported scope operator: ${operator}`,
+      { operator, field }
+    );
+  }
+
+  /** Action constraint is missing an entity */
+  static actionMissingEntity(operator: string): ParserError {
+    return new ParserError(
+      ErrorCodes.ACTION_MISSING_ENTITY,
+      `Action '${operator}' constraint is missing an entity`,
+      { operator, field: "action" }
+    );
+  }
+
+  /** Action constraint is missing entities */
+  static actionMissingEntities(): ParserError {
+    return new ParserError(
+      ErrorCodes.ACTION_MISSING_ENTITIES,
+      "Action 'in' constraint is missing entities",
+      { operator: "in", field: "action" }
+    );
+  }
+
+  /** Unsupported action operator */
+  static actionUnsupportedOp(operator: string): ParserError {
+    return new ParserError(
+      ErrorCodes.ACTION_UNSUPPORTED_OP,
+      `Unsupported action operator: ${operator}`,
+      { operator, field: "action" }
+    );
+  }
+
+  /** Action scope is nil */
+  static actionScopeNil(): ParserError {
+    return new ParserError(
+      ErrorCodes.ACTION_SCOPE_NIL,
+      "Action scope is nil",
+      { field: "action" }
+    );
+  }
+}

package/src/index.ts

@@ -12,3 +12,5 @@ export * from './schema.gen.js';
 // Non-generated modules (require Node.js)
 export * from './engine.js';
 export * from './builder.js';
+export * from './parser.js';
+export * from './errors.js';

package/src/parser.test.ts

@@ -0,0 +1,169 @@
+/**
+ * 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);
+  });
+
+  it('should store complex conditions as valid JSON array in rawCondition', () => {
+    // Use a condition with boolean AND that can't be mapped to structured format
+    const cedarText = `
+      @id("complex-condition")
+      permit(principal, action, resource)
+      when {
+        context.a == "x" && context.b == "y"
+      };
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.rules).toHaveLength(1);
+
+    const rule = result.rules[0];
+
+    // The complex && condition should be in rawCondition as valid JSON array
+    if (rule.rawCondition) {
+      // Verify it's valid JSON (should not throw)
+      const parsed = JSON.parse(rule.rawCondition);
+      expect(Array.isArray(parsed)).toBe(true);
+      expect(parsed.length).toBeGreaterThan(0);
+    }
+    // Either conditions were mapped or rawCondition contains valid JSON
+    expect(rule.conditions.length > 0 || rule.rawCondition).toBeTruthy();
+  });
+
+  it('should warn about duplicate policy IDs', () => {
+    const cedarText = `
+      @id("duplicate-id")
+      permit(principal, action, resource);
+
+      @id("unique-id")
+      forbid(principal, action, resource);
+
+      @id("duplicate-id")
+      permit(principal is User, action, resource);
+    `;
+
+    const result = parseCedarToRules(cedarText);
+
+    // All policies should still be parsed
+    expect(result.rules).toHaveLength(3);
+
+    // Should have a warning about duplicate ID
+    const duplicateError = result.errors.find(e => e.includes("HFP-PARSE-005"));
+    expect(duplicateError).toBeDefined();
+    expect(duplicateError).toContain("duplicate-id");
+    expect(duplicateError).toContain("[0");  // First occurrence at index 0
+    expect(duplicateError).toContain("2");   // Second occurrence at index 2
+  });
+});