@highflame/policy 2.0.0 → 2.0.2

package/src/studio-ui.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Studio UI Integration Tests
+ *
+ * These tests simulate exactly how the Studio UI (Overwatch admin dashboard)
+ * will use the @highflame/policy npm package.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// Browser-safe imports (simulating '@highflame/policy/types')
+import {
+  EntityType,
+  ActionType,
+  PolicyBuilder,
+  OVERWATCH_SCHEMA,
+  PALISADE_SCHEMA,
+  OVERWATCH_CONTEXT,
+  PALISADE_CONTEXT,
+  OverwatchContextKey,
+  PalisadeContextKey,
+  // Entity metadata for UI dropdowns
+  OVERWATCH_ENTITIES,
+  OVERWATCH_ACTION_ENTITIES,
+  PALISADE_ENTITIES,
+  PALISADE_ACTION_ENTITIES,
+  type ServiceContext,
+  type ActionContext,
+  type ServiceEntityMetadata,
+  type ActionEntityMetadata,
+} from './types.js';
+
+// Node.js only imports (for API routes)
+import {
+  PolicyEngine,
+  PolicyValidator,
+  newEntityUID,
+  newEntity,
+} from './index.js';
+
+describe('Studio UI Integration Tests', () => {
+  /**
+   * Test: PolicyBuilder action formatting
+   *
+   * Tests that simple action names are properly formatted to Cedar syntax.
+   * This is the "normal approach" for non-namespaced schemas.
+   */
+  it('should format simple action names to Cedar syntax', () => {
+    // Using simple action name (normal approach)
+    const policy = PolicyBuilder.permit()
+      .principalType('User')
+      .action('call_tool')
+      .resourceType('Tool')
+      .build();
+
+    const cedarText = policy.toCedar();
+
+    // Simple actions should be wrapped as Action::"..."
+    expect(cedarText).toContain('action == Action::"call_tool"');
+    expect(cedarText).not.toContain('Action::"Action::');  // No double-wrapping
+  });
+
+  /**
+   * Test 1: Schema and Context Loading
+   *
+   * Studio UI needs to load schemas for validation and context metadata
+   * for populating form dropdowns.
+   */
+  it('should load schemas and context metadata for form builders', () => {
+    // Schemas should be strings
+    expect(typeof OVERWATCH_SCHEMA).toBe('string');
+    expect(OVERWATCH_SCHEMA).toContain('namespace Overwatch');
+    expect(typeof PALISADE_SCHEMA).toBe('string');
+    expect(PALISADE_SCHEMA).toContain('namespace Palisade');
+
+    // Context metadata should have action definitions
+    expect(OVERWATCH_CONTEXT.service).toBe('overwatch');
+    expect(OVERWATCH_CONTEXT.actions.length).toBeGreaterThan(0);
+
+    // Find call_tool action and verify context attributes
+    const callToolAction = OVERWATCH_CONTEXT.actions.find(
+      (a: ActionContext) => a.name === 'call_tool'
+    );
+    expect(callToolAction).toBeDefined();
+    expect(callToolAction!.context_attributes.length).toBeGreaterThan(0);
+
+    // Context keys should be available for type-safe form building
+    expect(OverwatchContextKey.ToolName).toBe('tool_name');
+    expect(OverwatchContextKey.ThreatCount).toBe('threat_count');
+    expect(PalisadeContextKey.Severity).toBe('severity');
+    expect(PalisadeContextKey.Environment).toBe('environment');
+  });
+
+  /**
+   * Test 2: Full Round-Trip - Create Policy → Validate → Evaluate
+   *
+   * This simulates the complete flow:
+   * 1. User creates a policy using PolicyBuilder in the UI
+   * 2. API validates the policy against the schema
+   * 3. Runtime evaluates the policy
+   */
+  it('should complete full policy lifecycle for Overwatch', () => {
+    // Step 1: User creates policy in form UI
+    const policy = PolicyBuilder.permit()
+      .principalType('Overwatch::User')
+      .action('Overwatch::Action::"call_tool"')
+      .resourceType('Overwatch::Tool')
+      .whenRaw('context.threat_count < 5')
+      .build();
+
+    const cedarText = policy.toCedar();
+    expect(cedarText).toContain('permit');
+    expect(cedarText).toContain('Overwatch::User');
+
+    // Step 2: API validates policy against schema
+    const validator = new PolicyValidator(OVERWATCH_SCHEMA);
+    const validationResult = validator.validate(cedarText);
+    expect(validationResult.valid).toBe(true);
+
+    // Step 3: Runtime loads and evaluates policy
+    const engine = new PolicyEngine({ schema: OVERWATCH_SCHEMA });
+    engine.loadPolicies(cedarText);
+
+    const entities = [
+      newEntity('Overwatch::User', 'mcp_client', { user_type: 'external', email: 'test@example.com' }),
+      newEntity('Overwatch::Tool', 'shell', { tool_name: 'shell', risk_level: 'high' }),
+    ];
+
+    // Full context as Guardian will provide at runtime
+    const baseContext = {
+      content: 'ls -la',
+      source: 'claudecode',
+      event: 'PreToolUse',
+      user_email: 'test@example.com',
+      tool_name: 'shell',
+      mcp_server: 'filesystem',
+      mcp_tool: 'shell',
+      path: '/workspace',
+      cwd: '/workspace',
+      workspace_root: '/workspace',
+      highest_severity: 'low',
+      threat_categories: [],
+      threat_types: [],
+      yara_threats: [],
+      max_threat_severity: 1,
+      contains_secrets: false,
+      response_content: '',
+    };
+
+    // Should allow when threat_count < 5
+    const allowDecision = engine.evaluate({
+      principal: newEntityUID('Overwatch::User', 'mcp_client'),
+      action: 'Overwatch::Action::"call_tool"',
+      resource: newEntityUID('Overwatch::Tool', 'shell'),
+      context: { ...baseContext, threat_count: 3 },
+      entities,
+    });
+    expect(allowDecision.effect).toBe('Allow');
+
+    // Should deny when threat_count >= 5 (no matching permit)
+    const denyDecision = engine.evaluate({
+      principal: newEntityUID('Overwatch::User', 'mcp_client'),
+      action: 'Overwatch::Action::"call_tool"',
+      resource: newEntityUID('Overwatch::Tool', 'shell'),
+      context: { ...baseContext, threat_count: 10 },
+      entities,
+    });
+    expect(denyDecision.effect).toBe('Deny');
+  });
+
+  /**
+   * Test 3: Full Round-Trip for Palisade
+   *
+   * Same flow but for Palisade ML security policies.
+   */
+  it('should complete full policy lifecycle for Palisade', () => {
+    // Step 1: Create a forbid policy for CRITICAL findings
+    const policy = PolicyBuilder.forbid()
+      .principalType('Palisade::Scanner')
+      .action('Palisade::Action::"load_model"')
+      .resourceType('Palisade::Artifact')
+      .whenRaw('context.severity == "CRITICAL"')
+      .build();
+
+    const cedarText = policy.toCedar();
+
+    // Step 2: Validate
+    const validator = new PolicyValidator(PALISADE_SCHEMA);
+    expect(validator.validate(cedarText).valid).toBe(true);
+
+    // Step 3: Evaluate
+    const engine = new PolicyEngine({ schema: PALISADE_SCHEMA });
+    engine.loadPolicies(cedarText);
+
+    const entities = [
+      newEntity('Palisade::Scanner', 'palisade', { scanner_type: 'ml' }),
+      newEntity('Palisade::Artifact', 'model.pkl', {
+        artifact_format: 'pickle',
+        path: '/model.pkl',
+        signed: false,
+        signer: 'unsigned',
+      }),
+    ];
+
+    // Should deny CRITICAL findings
+    const decision = engine.evaluate({
+      principal: newEntityUID('Palisade::Scanner', 'palisade'),
+      action: 'Palisade::Action::"load_model"',
+      resource: newEntityUID('Palisade::Artifact', 'model.pkl'),
+      context: { severity: 'CRITICAL' },
+      entities,
+    });
+    expect(decision.effect).toBe('Deny');
+  });
+
+  /**
+   * Test 4: Entity Metadata for UI Dropdowns - Overwatch
+   *
+   * Studio UI needs to know which entity types can be principals,
+   * which can be resources, and what actions are available.
+   * This data is extracted from Cedar schema appliesTo blocks.
+   */
+  it('should provide correct entity metadata for Overwatch UI dropdowns', () => {
+    // Verify ServiceEntityMetadata structure
+    expect(OVERWATCH_ENTITIES.principals).toBeDefined();
+    expect(OVERWATCH_ENTITIES.resources).toBeDefined();
+    expect(OVERWATCH_ENTITIES.actions).toBeDefined();
+
+    // Overwatch principals should include User and Agent
+    expect(OVERWATCH_ENTITIES.principals).toContain('Agent');
+    expect(OVERWATCH_ENTITIES.principals).toContain('User');
+    expect(OVERWATCH_ENTITIES.principals).toHaveLength(2);
+
+    // Overwatch resources should include all resource types
+    expect(OVERWATCH_ENTITIES.resources).toContain('FilePath');
+    expect(OVERWATCH_ENTITIES.resources).toContain('LlmPrompt');
+    expect(OVERWATCH_ENTITIES.resources).toContain('Server');
+    expect(OVERWATCH_ENTITIES.resources).toContain('Tool');
+    expect(OVERWATCH_ENTITIES.resources).toHaveLength(4);
+
+    // Overwatch actions should match schema
+    expect(OVERWATCH_ENTITIES.actions).toContain('call_tool');
+    expect(OVERWATCH_ENTITIES.actions).toContain('connect_server');
+    expect(OVERWATCH_ENTITIES.actions).toContain('process_prompt');
+    expect(OVERWATCH_ENTITIES.actions).toContain('read_file');
+    expect(OVERWATCH_ENTITIES.actions).toContain('write_file');
+    expect(OVERWATCH_ENTITIES.actions).toHaveLength(5);
+  });
+
+  /**
+   * Test 5: Per-Action Entity Mapping - Overwatch
+   *
+   * Studio UI needs to filter dropdowns based on selected action.
+   * Each action has specific valid principals and resources.
+   */
+  it('should provide per-action entity mapping for Overwatch', () => {
+    // call_tool action should have correct principals and resources
+    const callTool = OVERWATCH_ACTION_ENTITIES['call_tool'];
+    expect(callTool).toBeDefined();
+    expect(callTool.principals).toContain('User');
+    expect(callTool.principals).toContain('Agent');
+    expect(callTool.resources).toContain('Tool');
+    expect(callTool.resources).toContain('FilePath');
+
+    // connect_server action should only apply to Server resource
+    const connectServer = OVERWATCH_ACTION_ENTITIES['connect_server'];
+    expect(connectServer).toBeDefined();
+    expect(connectServer.principals).toContain('User');
+    expect(connectServer.principals).toContain('Agent');
+    expect(connectServer.resources).toContain('Server');
+    expect(connectServer.resources).not.toContain('Tool');
+
+    // process_prompt action should only apply to LlmPrompt resource
+    const processPrompt = OVERWATCH_ACTION_ENTITIES['process_prompt'];
+    expect(processPrompt).toBeDefined();
+    expect(processPrompt.resources).toContain('LlmPrompt');
+    expect(processPrompt.resources).not.toContain('Tool');
+
+    // read_file and write_file should apply to FilePath resource
+    const readFile = OVERWATCH_ACTION_ENTITIES['read_file'];
+    const writeFile = OVERWATCH_ACTION_ENTITIES['write_file'];
+    expect(readFile.resources).toContain('FilePath');
+    expect(writeFile.resources).toContain('FilePath');
+  });
+
+  /**
+   * Test 6: Entity Metadata for Palisade
+   *
+   * Verify Palisade service also has correct entity metadata.
+   */
+  it('should provide correct entity metadata for Palisade UI dropdowns', () => {
+    // Palisade has Scanner as principal
+    expect(PALISADE_ENTITIES.principals).toContain('Scanner');
+
+    // Palisade resources include Artifact and Package
+    expect(PALISADE_ENTITIES.resources).toContain('Artifact');
+    expect(PALISADE_ENTITIES.resources).toContain('Package');
+
+    // Palisade actions
+    expect(PALISADE_ENTITIES.actions).toContain('load_model');
+    expect(PALISADE_ENTITIES.actions).toContain('scan_artifact');
+    expect(PALISADE_ENTITIES.actions).toContain('quarantine_artifact');
+
+    // Per-action mapping - load_model applies to Artifact
+    const loadModel = PALISADE_ACTION_ENTITIES['load_model'];
+    expect(loadModel).toBeDefined();
+    expect(loadModel.principals).toContain('Scanner');
+    expect(loadModel.resources).toContain('Artifact');
+
+    // scan_package applies to Package resource
+    const scanPackage = PALISADE_ACTION_ENTITIES['scan_package'];
+    expect(scanPackage).toBeDefined();
+    expect(scanPackage.resources).toContain('Package');
+  });
+});

package/src/types.ts

@@ -16,3 +16,31 @@ export * from './builder.js';
 
 // Error types - works in browser (no WASM dependency)
 export * from './errors.js';
+
+// Service-specific schemas and context (inlined, browser-safe)
+export {
+  OVERWATCH_SCHEMA,
+  OVERWATCH_CONTEXT,
+  PALISADE_SCHEMA,
+  PALISADE_CONTEXT,
+} from './service-schemas.gen.js';
+export type {
+  ContextAttribute,
+  ActionContext,
+  ServiceContext,
+} from './service-schemas.gen.js';
+
+// Service-specific context key enums
+export { OverwatchContextKey } from './overwatch-context.gen.js';
+export { PalisadeContextKey } from './palisade-context.gen.js';
+
+// Service-specific entity metadata (for UI - principals, resources, actions)
+export {
+  OVERWATCH_ENTITIES,
+  OVERWATCH_ACTION_ENTITIES,
+} from './overwatch-entities.gen.js';
+export {
+  PALISADE_ENTITIES,
+  PALISADE_ACTION_ENTITIES,
+} from './palisade-entities.gen.js';
+export type { ServiceEntityMetadata, ActionEntityMetadata } from './entity-metadata-types.gen.js';