@highflame/policy 1.2.0 → 2.0.0

package/src/context.gen.ts

@@ -5,103 +5,6 @@
  * Context attribute keys for Cedar policy evaluation.
  */
 export const ContextKey = {
-    // Guardrails/Core context attributes
-    /** Name of tool being called */
-    ToolName: 'tool_name',
-    /** Name of resource being accessed */
-    ResourceName: 'resource_name',
-    /** Name of prompt */
-    PromptName: 'prompt_name',
-    /** Raw prompt text */
-    PromptText: 'prompt_text',
-    /** Response size in megabytes */
-    ResponseSizeMb: 'response_size_mb',
-    /** Set of detected YARA threat names */
-    YaraThreats: 'yara_threats',
-    /** Number of threats detected */
-    ThreatCount: 'threat_count',
-    /** Highest severity (0-4) */
-    MaxThreatSeverity: 'max_threat_severity',
-    /** User type: external or internal */
-    UserType: 'user_type',
-    /** Whether monitoring is active */
-    MonitoringEnabled: 'monitoring_enabled',
-    /** File path */
-    Path: 'path',
-    /** HTTP hostname */
-    Hostname: 'hostname',
-    /** IP address */
-    IpAddress: 'ip_address',
-    /** Whether the IP is private/loopback (set by application layer) */
-    IsPrivateIp: 'is_private_ip',
-    /** HTTP scheme */
-    Scheme: 'scheme',
-    /** Port number */
-    Port: 'port',
-
-    // Palisade context attributes
-    /** Environment: production, development, research */
-    Environment: 'environment',
-    /** Format: pickle, safetensors, gguf, onnx */
-    ArtifactFormat: 'artifact_format',
-    /** Whether artifact has signature */
-    ArtifactSigned: 'artifact_signed',
-    /** Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO */
-    Severity: 'severity',
-    /** Type of security finding */
-    FindingType: 'finding_type',
-    /** Who signed the artifact */
-    ProvenanceSigner: 'provenance_signer',
-    /** RCE path found in pickle */
-    PickleExecPathDetected: 'pickle_exec_path_detected',
-    /** Malicious pattern in metadata */
-    MetadataMaliciousPattern: 'metadata_malicious_pattern',
-    /** Number of added tokens */
-    TokenizerAddedTokensCount: 'tokenizer_added_tokens_count',
-    /** Safetensors integrity failed */
-    SafetensorsIntegrityViolation: 'safetensors_integrity_violation',
-    /** Suspicious GGUF metadata */
-    GgufSuspiciousMetadata: 'gguf_suspicious_metadata',
-    /** LoRA adapter digest mismatch */
-    AdapterBaseDigestMismatch: 'adapter_base_digest_mismatch',
-    /** CoSAI maturity level (0-5) */
-    MetadataCosaiLevelNumeric: 'metadata_cosai_level_numeric',
-
-    // Overwatch context attributes
-    /** IDE source: cursor, claudecode, vscode, geminicli */
-    Source: 'source',
-    /** Hook event type: beforeShellExecution, PreToolUse, etc. */
-    Event: 'event',
-    /** The prompt/request content being evaluated */
-    Content: 'content',
-    /** User's email address (or 'anonymous') */
-    UserEmail: 'user_email',
-    /** Custom principal ID for policy evaluation */
-    CedarPrincipal: 'cedar_principal',
-    /** MCP server name: filesystem, playwright, etc. */
-    ServerName: 'server_name',
-    /** Whether the path is within the workspace */
-    IsWithinWorkspace: 'is_within_workspace',
-    /** Response content from tool execution */
-    ResponseContent: 'response_content',
-    /** Highest severity level: critical, high, medium, low */
-    HighestSeverity: 'highest_severity',
-    /** Array of threat types detected */
-    ThreatTypes: 'threat_types',
-    /** Array of threat categories found */
-    ThreatCategories: 'threat_categories',
-    /** Whether secrets were detected in the content */
-    ContainsSecrets: 'contains_secrets',
-    /** Number of concurrent calls */
-    ConcurrentCalls: 'concurrent_calls',
-    /** Request rate per minute */
-    RequestsPerMinute: 'requests_per_minute',
-    /** User trust level: high, medium, low */
-    UserTrustLevel: 'user_trust_level',
-    /** Whether alerting is enabled for this request */
-    AlertEnabled: 'alert_enabled',
-    /** Type of security scan being performed */
-    ScanType: 'scan_type',
 } as const;
 
 export type ContextKey = (typeof ContextKey)[keyof typeof ContextKey];

package/src/engine.test.ts

@@ -11,7 +11,6 @@ import {
   Decision,
   EntityType,
   ActionType,
-  ContextKey,
   InputValidationError,
   DEFAULT_LIMITS,
 } from './index.js';

package/src/engine.ts

@@ -6,7 +6,6 @@
 import * as cedar from "@cedar-policy/cedar-wasm/nodejs";
 import { EntityType, EntityUID, Entity } from "./entities.gen.js";
 import { ActionType } from "./actions.gen.js";
-import { CEDAR_SCHEMA } from "./schema.gen.js";
 
 // =============================================================================
 // INPUT VALIDATION LIMITS (consistent across all language SDKs)
@@ -35,6 +34,8 @@ export interface InputLimits {
 }
 
 export interface EngineOptions {
+  /** Cedar schema string (optional - can also use loadSchema() method) */
+  schema?: string;
   /** Custom input validation limits */
   limits?: InputLimits;
   /** Skip input validation (not recommended for production) */
@@ -142,9 +143,15 @@ export interface Decision {
 
 export interface EvaluateRequest {
   principal: EntityUID;
-  action: ActionType;
+  /**
+   * Action to evaluate. Can be:
+   * - A generated ActionType value (e.g., ActionType.CallTool)
+   * - A namespaced action string (e.g., 'Overwatch::Action::"call_tool"')
+   */
+  action: ActionType | string;
   resource: EntityUID;
   context?: Record<string, unknown>;
+  entities?: Entity[];
 }
 
 /**
@@ -170,6 +177,33 @@ function toCedarValue(value: unknown): cedar.CedarValueJson {
   return String(value);
 }
 
+/**
+ * Parse an action string into Cedar EntityUID format.
+ * Handles both non-namespaced and namespaced actions:
+ * - "call_tool" → { type: "Action", id: "call_tool" }
+ * - "Overwatch::Action::\"call_tool\"" → { type: "Overwatch::Action", id: "call_tool" }
+ * - "Overwatch::Action::call_tool" → { type: "Overwatch::Action", id: "call_tool" }
+ */
+function parseActionString(action: string): cedar.EntityUidJson {
+  // Check if action contains namespace separator
+  if (!action.includes("::")) {
+    // Non-namespaced action
+    return { type: "Action", id: action };
+  }
+
+  // Namespaced action - find the last :: separator
+  const lastSeparator = action.lastIndexOf("::");
+  const actionType = action.substring(0, lastSeparator);
+  let actionId = action.substring(lastSeparator + 2);
+
+  // Remove surrounding quotes if present (e.g., "call_tool" → call_tool)
+  if (actionId.startsWith('"') && actionId.endsWith('"')) {
+    actionId = actionId.slice(1, -1);
+  }
+
+  return { type: actionType, id: actionId };
+}
+
 /**
  * PolicyEngine wraps cedar-wasm with Highflame schema types.
  */
@@ -181,6 +215,7 @@ export class PolicyEngine {
 
   constructor(options?: EngineOptions) {
     this.options = options ?? {};
+    this.schema = options?.schema;
     this.limits = {
       maxContextKeys: options?.limits?.maxContextKeys ?? DEFAULT_LIMITS.maxContextKeys,
       maxStringLength: options?.limits?.maxStringLength ?? DEFAULT_LIMITS.maxStringLength,
@@ -198,19 +233,11 @@ export class PolicyEngine {
 
   /**
    * Load schema from a Cedar schema string.
-   * If not called, uses the embedded Highflame schema.
    */
   loadSchema(schema: string): void {
     this.schema = schema;
   }
 
-  /**
-   * Load the embedded Highflame schema.
-   */
-  loadHighflameSchema(): void {
-    this.schema = CEDAR_SCHEMA;
-  }
-
   /**
    * Evaluate a policy request and return a decision.
    * @throws InputValidationError if context validation fails
@@ -226,10 +253,7 @@ export class PolicyEngine {
       type: req.principal.type,
       id: req.principal.id,
     };
-    const action: cedar.EntityUidJson = {
-      type: "Action",
-      id: req.action,
-    };
+    const action: cedar.EntityUidJson = parseActionString(req.action);
     const resource: cedar.EntityUidJson = {
       type: req.resource.type,
       id: req.resource.id,
@@ -243,6 +267,15 @@ export class PolicyEngine {
       }
     }
 
+    // Convert entities to Cedar JSON format
+    const entities = (req.entities || []).map(e => ({
+      uid: e.uid,
+      attrs: e.attrs ? Object.fromEntries(
+        Object.entries(e.attrs).map(([k, v]) => [k, toCedarValue(v)])
+      ) : {},
+      parents: e.parents || [],
+    }));
+
     // Build the authorization call
     const call: cedar.AuthorizationCall = {
       principal,
@@ -250,7 +283,7 @@ export class PolicyEngine {
       resource,
       context,
       policies: { staticPolicies: this.policies },
-      entities: [],
+      entities,
     };
 
     // Add schema if available
@@ -284,7 +317,7 @@ export class PolicyEngine {
   evaluateSimple(
     principalType: EntityType,
     principalId: string,
-    action: ActionType,
+    action: ActionType | string,
     resourceType: EntityType,
     resourceId: string,
     context?: Record<string, unknown>
@@ -302,11 +335,13 @@ export class PolicyEngine {
    * Returns validation errors or empty array if valid.
    */
   validatePolicies(policies: string): string[] {
-    const schemaToUse = this.schema ?? CEDAR_SCHEMA;
+    if (!this.schema) {
+      throw new Error("Schema is required for validation. Provide schema via constructor options or loadSchema().");
+    }
 
     const result = cedar.validate({
       validationSettings: { mode: "strict" },
-      schema: schemaToUse,
+      schema: this.schema,
       policies: { staticPolicies: policies },
     });
 
@@ -326,10 +361,11 @@ export class PolicyValidator {
   private schema: string;
 
   /**
-   * Create a validator with the embedded Highflame schema.
+   * Create a validator with a Cedar schema.
+   * @param schema Cedar schema string (required)
    */
-  constructor(schema?: string) {
-    this.schema = schema ?? CEDAR_SCHEMA;
+  constructor(schema: string) {
+    this.schema = schema;
   }
 
   /**
@@ -375,23 +411,16 @@ export class PolicyValidator {
 }
 
 /**
- * Validate a Cedar policy against the Highflame schema.
+ * Validate a Cedar policy against a schema.
  * Convenience function that doesn't require creating a validator instance.
+ * @param schema Cedar schema string
+ * @param policy Policy text to validate
  */
-export function validatePolicy(policy: string): { valid: boolean; errors: string[] } {
-  const validator = new PolicyValidator();
+export function validatePolicy(schema: string, policy: string): { valid: boolean; errors: string[] } {
+  const validator = new PolicyValidator(schema);
   return validator.validate(policy);
 }
 
-/**
- * Get the embedded Highflame Cedar schema.
- */
-export function getHighflameSchema(): string {
-  return CEDAR_SCHEMA;
-}
-
 // Re-export types
 export { EntityType, EntityUID, Entity, newEntityUID, newEntity } from "./entities.gen.js";
 export { ActionType, actionUID } from "./actions.gen.js";
-export * from "./context.gen.js";
-export { CEDAR_SCHEMA } from "./schema.gen.js";

package/src/entities.gen.ts

@@ -11,6 +11,7 @@ export const EntityType = {
     FilePath: 'FilePath',
     GitBranch: 'GitBranch',
     HttpEndpoint: 'HttpEndpoint',
+    LlmPrompt: 'LlmPrompt',
     Memory: 'Memory',
     Model: 'Model',
     Package: 'Package',

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/overwatch-context.gen.ts

@@ -0,0 +1,34 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schemas/overwatch/context.json
+
+/**
+ * Context attribute keys for Overwatch Overwatch (Guardian) IDE security & policy enforcement.
+ * 
+ * These constants correspond to the context attributes defined in the
+ * Overwatch Cedar schema and are used at policy evaluation time.
+ */
+export const OverwatchContextKey = {
+  ContainsSecrets: 'contains_secrets',
+  Content: 'content',
+  Cwd: 'cwd',
+  Event: 'event',
+  FilePath: 'file_path',
+  HighestSeverity: 'highest_severity',
+  MaxThreatSeverity: 'max_threat_severity',
+  McpServer: 'mcp_server',
+  McpTool: 'mcp_tool',
+  Path: 'path',
+  PromptText: 'prompt_text',
+  ResponseContent: 'response_content',
+  ServerName: 'server_name',
+  Source: 'source',
+  ThreatCategories: 'threat_categories',
+  ThreatCount: 'threat_count',
+  ThreatTypes: 'threat_types',
+  ToolName: 'tool_name',
+  UserEmail: 'user_email',
+  WorkspaceRoot: 'workspace_root',
+  YaraThreats: 'yara_threats',
+} as const;
+
+export type OverwatchContextKey = (typeof OverwatchContextKey)[keyof typeof OverwatchContextKey];

package/src/palisade-context.gen.ts

@@ -0,0 +1,28 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schemas/palisade/context.json
+
+/**
+ * Context attribute keys for Palisade Palisade ML supply chain security & artifact scanning.
+ * 
+ * These constants correspond to the context attributes defined in the
+ * Palisade Cedar schema and are used at policy evaluation time.
+ */
+export const PalisadeContextKey = {
+  AdapterBaseDigestMismatch: 'adapter_base_digest_mismatch',
+  ArtifactFormat: 'artifact_format',
+  ArtifactSigned: 'artifact_signed',
+  Environment: 'environment',
+  FindingType: 'finding_type',
+  GgufSuspiciousMetadata: 'gguf_suspicious_metadata',
+  MatchCount: 'match_count',
+  MetadataCosaiLevelNumeric: 'metadata_cosai_level_numeric',
+  MetadataMaliciousPattern: 'metadata_malicious_pattern',
+  Path: 'path',
+  PickleExecPathDetected: 'pickle_exec_path_detected',
+  ProvenanceSigner: 'provenance_signer',
+  SafetensorsIntegrityViolation: 'safetensors_integrity_violation',
+  Severity: 'severity',
+  TokenizerAddedTokensCount: 'tokenizer_added_tokens_count',
+} as const;
+
+export type PalisadeContextKey = (typeof PalisadeContextKey)[keyof typeof PalisadeContextKey];

package/src/parser.test.ts

@@ -113,4 +113,57 @@ describe('parseCedarToRules', () => {
     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
+  });
 });