@highflame/policy 1.1.3 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Highflame Cedar policy types and engine wrapper",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,13 +42,15 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@cedar-policy/cedar-wasm": "^4.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
   },
   "files": [
     "dist",

package/src/actions.gen.ts

@@ -7,20 +7,41 @@ import { EntityUID } from './entities.gen.js';
  * Action types defined in the Highflame Cedar schema.
  */
 export const ActionType = {
+    AccessMemory: 'access_memory',
     AccessServerResource: 'access_server_resource',
+    CallExternalApi: 'call_external_api',
     CallTool: 'call_tool',
     ConnectServer: 'connect_server',
+    DelegateTask: 'delegate_task',
+    DeleteFile: 'delete_file',
     DeployModel: 'deploy_model',
+    ExecuteCode: 'execute_code',
+    ExportData: 'export_data',
+    FilterContent: 'filter_content',
+    GitCheckout: 'git_checkout',
+    GitClone: 'git_clone',
+    GitCommit: 'git_commit',
+    GitMerge: 'git_merge',
+    GitOperation: 'git_operation',
+    GitPull: 'git_pull',
+    GitPush: 'git_push',
+    GitRebase: 'git_rebase',
+    GitReset: 'git_reset',
     HttpRequest: 'http_request',
+    InvokeModel: 'invoke_model',
     LoadModel: 'load_model',
     ProcessPrompt: 'process_prompt',
     ProcessResponse: 'process_response',
     QuarantineArtifact: 'quarantine_artifact',
     ReadFile: 'read_file',
+    RunBuild: 'run_build',
+    RunTests: 'run_tests',
     ScanArtifact: 'scan_artifact',
     ScanPackage: 'scan_package',
     ScanTarget: 'scan_target',
     SkipGuardrails: 'skip_guardrails',
+    SpawnSubprocess: 'spawn_subprocess',
+    TransferData: 'transfer_data',
     ValidateIntegrity: 'validate_integrity',
     ValidateProvenance: 'validate_provenance',
     WriteFile: 'write_file',

package/src/builder.ts

@@ -58,7 +58,31 @@ export interface PolicyCondition {
 }
 
 /**
- * JSON representation of a policy for storage and editing
+ * Principal or resource entity constraint.
+ * Used to specify type-only constraints (any entity of type) or
+ * specific entity constraints (type + id).
+ */
+export interface PolicyEntity {
+    /** Entity type (e.g., "Agent", "Tool", "FilePath", "User") */
+    type: string;
+    /** Optional specific entity ID. If omitted, matches any entity of this type. */
+    id?: string;
+}
+
+/** Alias for PolicyEntity when used as principal constraint */
+export type PolicyPrincipal = PolicyEntity;
+
+/** Alias for PolicyEntity when used as resource constraint */
+export type PolicyResource = PolicyEntity;
+
+/**
+ * Rule severity levels for UI display and prioritization
+ */
+export type PolicySeverity = 'critical' | 'high' | 'medium' | 'low';
+
+/**
+ * JSON representation of a policy for storage and editing.
+ * This is the base interface used by PolicyBuilder.
  */
 export interface PolicyJSON {
     /** Unique identifier for this policy */
@@ -68,23 +92,41 @@ export interface PolicyJSON {
     /** Policy effect */
     effect: PolicyEffect;
     /** Principal constraint */
-    principal: {
-        type: string;
-        id?: string;
-    } | null;
-    /** Action constraint */
+    principal: PolicyEntity | null;
+    /** Action constraint - single action or array of actions */
     action: string | string[];
     /** Resource constraint */
-    resource: {
-        type: string;
-        id?: string;
-    } | null;
+    resource: PolicyEntity | null;
     /** Conditions (when clause) */
     conditions: PolicyCondition[];
     /** Raw condition string (for advanced users) */
     rawCondition?: string;
 }
 
+/**
+ * A policy rule with UI/storage metadata.
+ * Extends PolicyJSON with fields needed for UI editing and database storage.
+ *
+ * This is the canonical type used across all Highflame services:
+ * - highflame-studio (UI)
+ * - highflame-authz (Go backend)
+ * - Any Python services
+ *
+ * Each PolicyRule maps 1:1 to a Cedar policy statement.
+ */
+export interface PolicyRule extends PolicyJSON {
+    /** Whether this rule is active (used for toggling rules on/off in UI) */
+    enabled: boolean;
+    /** Display/evaluation order (0-indexed) */
+    order: number;
+    /** Optional description (separate from name for longer explanations) */
+    description?: string;
+    /** Rule severity for display and prioritization */
+    severity?: PolicySeverity;
+    /** Optional tags for categorization and filtering */
+    tags?: string[];
+}
+
 /**
  * A built policy that can be converted to Cedar text or JSON
  */

package/src/engine.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Engine unit tests
+ *
+ * Tests the PolicyEngine evaluate() function.
+ * These tests are consistent across Go, TypeScript, and Python SDKs.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  PolicyEngine,
+  Decision,
+  EntityType,
+  ActionType,
+  ContextKey,
+  InputValidationError,
+  DEFAULT_LIMITS,
+} from './index.js';
+
+describe('PolicyEngine', () => {
+  let engine: PolicyEngine;
+
+  const permitAllPolicy = `
+    permit(principal, action, resource);
+  `;
+
+  const denyAllPolicy = `
+    forbid(principal, action, resource);
+  `;
+
+  // Simple context-based policy without action constraint for testing context evaluation
+  const contextBasedPolicy = `
+    @id("allow-production")
+    permit(
+      principal,
+      action,
+      resource
+    )
+    when { context.environment == "production" };
+
+    @id("deny-all")
+    forbid(principal, action, resource);
+  `;
+
+  beforeEach(() => {
+    engine = new PolicyEngine();
+  });
+
+  describe('basic evaluation', () => {
+    it('should allow when permit policy matches', () => {
+      engine.loadPolicies(permitAllPolicy);
+
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test-scanner',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors'
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should deny when forbid policy matches', () => {
+      engine.loadPolicies(denyAllPolicy);
+
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test-scanner',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors'
+      );
+
+      expect(decision.effect).toBe('Deny');
+    });
+
+    it('should deny when no policies match (default deny)', () => {
+      engine.loadPolicies(''); // No policies
+
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test-scanner',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors'
+      );
+
+      expect(decision.effect).toBe('Deny');
+    });
+  });
+
+  describe('context-based evaluation', () => {
+    beforeEach(() => {
+      engine.loadPolicies(contextBasedPolicy);
+    });
+
+    it('should allow when context matches permit condition', () => {
+      // Use simple permit policy to test context evaluation in isolation
+      const simplePermitPolicy = `
+        permit(principal, action, resource)
+        when { context.environment == "production" };
+      `;
+      const testEngine = new PolicyEngine();
+      testEngine.loadPolicies(simplePermitPolicy);
+
+      const decision = testEngine.evaluateSimple(
+        EntityType.Scanner,
+        'palisade',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { environment: 'production' }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should deny when context does not match permit condition', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'palisade',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { environment: 'development' }
+      );
+
+      expect(decision.effect).toBe('Deny');
+    });
+
+    it('should deny when context is missing required field', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'palisade',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        {} // Missing environment
+      );
+
+      expect(decision.effect).toBe('Deny');
+    });
+  });
+
+  describe('input validation', () => {
+    beforeEach(() => {
+      engine.loadPolicies(permitAllPolicy);
+    });
+
+    it('should accept valid context', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        {
+          environment: 'production',
+          severity: 'HIGH',
+          count: 42,
+          enabled: true,
+        }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should reject context with too many keys', () => {
+      const engine = new PolicyEngine({ limits: { maxContextKeys: 5 } });
+      engine.loadPolicies(permitAllPolicy);
+
+      const bigContext: Record<string, unknown> = {};
+      for (let i = 0; i < 10; i++) {
+        bigContext[`key${i}`] = 'value';
+      }
+
+      expect(() => {
+        engine.evaluateSimple(
+          EntityType.Scanner,
+          'test',
+          ActionType.ScanArtifact,
+          EntityType.Artifact,
+          '/model.safetensors',
+          bigContext
+        );
+      }).toThrow(InputValidationError);
+    });
+
+    it('should reject context with too long strings', () => {
+      const engine = new PolicyEngine({ limits: { maxStringLength: 100 } });
+      engine.loadPolicies(permitAllPolicy);
+
+      const longString = 'x'.repeat(200);
+
+      expect(() => {
+        engine.evaluateSimple(
+          EntityType.Scanner,
+          'test',
+          ActionType.ScanArtifact,
+          EntityType.Artifact,
+          '/model.safetensors',
+          { value: longString }
+        );
+      }).toThrow(InputValidationError);
+    });
+
+    it('should reject deeply nested context', () => {
+      const engine = new PolicyEngine({ limits: { maxNestingDepth: 3 } });
+      engine.loadPolicies(permitAllPolicy);
+
+      const deepContext = {
+        level1: {
+          level2: {
+            level3: {
+              level4: {
+                level5: 'too deep',
+              },
+            },
+          },
+        },
+      };
+
+      expect(() => {
+        engine.evaluateSimple(
+          EntityType.Scanner,
+          'test',
+          ActionType.ScanArtifact,
+          EntityType.Artifact,
+          '/model.safetensors',
+          deepContext
+        );
+      }).toThrow(InputValidationError);
+    });
+
+    it('should allow skipping validation', () => {
+      const engine = new PolicyEngine({
+        skipValidation: true,
+        limits: { maxContextKeys: 1 },
+      });
+      engine.loadPolicies(permitAllPolicy);
+
+      // This would normally fail validation
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { key1: 'value1', key2: 'value2', key3: 'value3' }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+  });
+
+  describe('complex context types', () => {
+    beforeEach(() => {
+      engine.loadPolicies(permitAllPolicy);
+    });
+
+    it('should handle array context values', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { threats: ['malware', 'backdoor', 'injection'] }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should handle nested object context', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        {
+          metadata: {
+            format: 'safetensors',
+            size: 1024,
+          },
+        }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should handle empty context', () => {
+      // Cedar doesn't have null values - this tests that empty context works
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        {}
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should handle boolean context values', () => {
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { is_signed: true, is_malicious: false }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+
+    it('should handle integer context values', () => {
+      // Cedar uses Long type for numbers (integers only, no floats)
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors',
+        { severity_score: 7, count: 100 }
+      );
+
+      expect(decision.effect).toBe('Allow');
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle invalid policy syntax gracefully', () => {
+      const invalidPolicy = `permit(principal, action, resource`; // Missing closing paren
+
+      expect(() => {
+        engine.loadPolicies(invalidPolicy);
+        engine.evaluateSimple(
+          EntityType.Scanner,
+          'test',
+          ActionType.ScanArtifact,
+          EntityType.Artifact,
+          '/model.safetensors'
+        );
+      }).not.toThrow();
+
+      // Should return deny with reason
+      engine.loadPolicies(invalidPolicy);
+      const decision = engine.evaluateSimple(
+        EntityType.Scanner,
+        'test',
+        ActionType.ScanArtifact,
+        EntityType.Artifact,
+        '/model.safetensors'
+      );
+
+      expect(decision.effect).toBe('Deny');
+    });
+  });
+
+  describe('DEFAULT_LIMITS', () => {
+    it('should have consistent default values', () => {
+      expect(DEFAULT_LIMITS.maxContextKeys).toBe(100);
+      expect(DEFAULT_LIMITS.maxStringLength).toBe(1_000_000);
+      expect(DEFAULT_LIMITS.maxNestingDepth).toBe(10);
+      expect(DEFAULT_LIMITS.maxContextSizeBytes).toBe(10_000_000);
+    });
+  });
+});

package/src/engine.ts

@@ -8,6 +8,132 @@ 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)
+// =============================================================================
+
+/**
+ * Default limits for input validation.
+ * These are consistent across Go, TypeScript, and Python SDKs.
+ */
+export const DEFAULT_LIMITS = {
+  /** Maximum number of keys in a context map */
+  maxContextKeys: 100,
+  /** Maximum length of any string value (1MB) */
+  maxStringLength: 1_000_000,
+  /** Maximum nesting depth for objects/arrays */
+  maxNestingDepth: 10,
+  /** Maximum total context size in bytes (10MB) */
+  maxContextSizeBytes: 10_000_000,
+} as const;
+
+export interface InputLimits {
+  maxContextKeys?: number;
+  maxStringLength?: number;
+  maxNestingDepth?: number;
+  maxContextSizeBytes?: number;
+}
+
+export interface EngineOptions {
+  /** Custom input validation limits */
+  limits?: InputLimits;
+  /** Skip input validation (not recommended for production) */
+  skipValidation?: boolean;
+}
+
+/**
+ * Error thrown when input validation fails.
+ */
+export class InputValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InputValidationError";
+  }
+}
+
+/**
+ * Validate context input against configured limits.
+ * @throws InputValidationError if validation fails
+ */
+function validateContext(
+  context: Record<string, unknown> | undefined,
+  limits: Required<InputLimits>,
+  depth: number = 0
+): void {
+  if (!context) return;
+
+  // Check nesting depth
+  if (depth > limits.maxNestingDepth) {
+    throw new InputValidationError(
+      `Context nesting depth exceeds maximum of ${limits.maxNestingDepth}`
+    );
+  }
+
+  const keys = Object.keys(context);
+
+  // Check number of keys (only at top level)
+  if (depth === 0 && keys.length > limits.maxContextKeys) {
+    throw new InputValidationError(
+      `Context has ${keys.length} keys, exceeds maximum of ${limits.maxContextKeys}`
+    );
+  }
+
+  // Check total size (only at top level)
+  if (depth === 0) {
+    let contextStr: string;
+    try {
+      contextStr = JSON.stringify(context);
+    } catch (e) {
+      throw new InputValidationError(
+        `Context is invalid or too complex: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+    if (contextStr.length > limits.maxContextSizeBytes) {
+      throw new InputValidationError(
+        `Context size (${contextStr.length} bytes) exceeds maximum of ${limits.maxContextSizeBytes} bytes`
+      );
+    }
+  }
+
+  // Validate each value
+  for (const value of Object.values(context)) {
+    validateValue(value, limits, depth);
+  }
+}
+
+function validateValue(
+  value: unknown,
+  limits: Required<InputLimits>,
+  depth: number
+): void {
+  if (value === null || value === undefined) return;
+
+  if (typeof value === "string") {
+    if (value.length > limits.maxStringLength) {
+      throw new InputValidationError(
+        `String value length (${value.length}) exceeds maximum of ${limits.maxStringLength}`
+      );
+    }
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    if (depth + 1 > limits.maxNestingDepth) {
+      throw new InputValidationError(
+        `Array nesting depth exceeds maximum of ${limits.maxNestingDepth}`
+      );
+    }
+    for (const item of value) {
+      validateValue(item, limits, depth + 1);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    validateContext(value as Record<string, unknown>, limits, depth + 1);
+  }
+}
+
 export interface Decision {
   effect: "Allow" | "Deny";
   determining_policies: string[];
@@ -50,6 +176,18 @@ function toCedarValue(value: unknown): cedar.CedarValueJson {
 export class PolicyEngine {
   private policies: string = "";
   private schema: string | undefined;
+  private options: EngineOptions;
+  private limits: Required<InputLimits>;
+
+  constructor(options?: EngineOptions) {
+    this.options = options ?? {};
+    this.limits = {
+      maxContextKeys: options?.limits?.maxContextKeys ?? DEFAULT_LIMITS.maxContextKeys,
+      maxStringLength: options?.limits?.maxStringLength ?? DEFAULT_LIMITS.maxStringLength,
+      maxNestingDepth: options?.limits?.maxNestingDepth ?? DEFAULT_LIMITS.maxNestingDepth,
+      maxContextSizeBytes: options?.limits?.maxContextSizeBytes ?? DEFAULT_LIMITS.maxContextSizeBytes,
+    };
+  }
 
   /**
    * Load policies from a Cedar policy string.
@@ -75,8 +213,14 @@ export class PolicyEngine {
 
   /**
    * Evaluate a policy request and return a decision.
+   * @throws InputValidationError if context validation fails
    */
   evaluate(req: EvaluateRequest): Decision {
+    // Validate input unless explicitly skipped
+    if (!this.options.skipValidation) {
+      validateContext(req.context, this.limits);
+    }
+
     // Build EntityUIDs in Cedar JSON format
     const principal: cedar.EntityUidJson = {
       type: req.principal.type,
@@ -135,6 +279,7 @@ export class PolicyEngine {
 
   /**
    * Convenience method for simple evaluations.
+   * @throws InputValidationError if context validation fails
    */
   evaluateSimple(
     principalType: EntityType,

package/src/entities.gen.ts

@@ -7,8 +7,12 @@
 export const EntityType = {
     Agent: 'Agent',
     Artifact: 'Artifact',
+    ExternalAPI: 'ExternalAPI',
     FilePath: 'FilePath',
+    GitBranch: 'GitBranch',
     HttpEndpoint: 'HttpEndpoint',
+    Memory: 'Memory',
+    Model: 'Model',
     Package: 'Package',
     Repository: 'Repository',
     Resource: 'Resource',