@highflame/policy 2.0.2 → 2.0.3

package/src/studio-ui.test.ts

@@ -312,3 +312,502 @@ describe('Studio UI Integration Tests', () => {
     expect(scanPackage.resources).toContain('Package');
   });
 });
+
+/**
+ * Cedar Policy Annotations Integration Tests
+ *
+ * These tests verify the full round-trip of Cedar policy annotations:
+ * PolicyRule → Cedar text → parse back → verify annotations preserved
+ */
+// Import annotation functions for tests
+import {
+  ruleToCedar,
+  rulesToCedar,
+  parseCedarToRules,
+  generateRuleId,
+  isValidAnnotationKey,
+  type PolicyRule,
+  type PolicySeverity,
+  type PolicyEffect,
+  type ConditionOperator,
+} from './index.js';
+
+describe('Cedar Annotations Integration Tests', () => {
+
+  /**
+   * Test 1: Basic Annotations Round-Trip
+   *
+   * Create a PolicyRule with all standard annotations, convert to Cedar,
+   * parse back, and verify all annotations are preserved.
+   */
+  it('should preserve annotations through Cedar round-trip', () => {
+    // Step 1: Create a PolicyRule with full annotations
+    const originalRule: PolicyRule = {
+      annotations: {
+        id: 'rule-001',
+        name: 'Block high-threat tool calls',
+        description: 'Forbids tool calls when threat count exceeds threshold',
+        severity: 'high' as PolicySeverity,
+        tags: ['security', 'baseline', 'v2'],
+      },
+      effect: 'forbid' as PolicyEffect,
+      principal: { type: 'Overwatch::User' },
+      action: 'Overwatch::Action::"call_tool"',
+      resource: { type: 'Overwatch::Tool' },
+      conditions: [{ field: 'threat_count', operator: 'gt' as ConditionOperator, value: 5 }],
+      enabled: true,
+      order: 0,
+    };
+
+    // Step 2: Convert to Cedar text
+    const cedarText = ruleToCedar(originalRule);
+
+    // Verify Cedar text contains annotations in proper syntax
+    expect(cedarText).toContain('@id("rule-001")');
+    expect(cedarText).toContain('@name("Block high-threat tool calls")');
+    expect(cedarText).toContain('@description("Forbids tool calls when threat count exceeds threshold")');
+    expect(cedarText).toContain('@severity("high")');
+    expect(cedarText).toContain('@tags("security,baseline,v2")');
+    expect(cedarText).toContain('forbid');
+    expect(cedarText).toContain('context.threat_count > 5');
+
+    // Step 3: Validate the generated Cedar against Overwatch schema
+    const validator = new PolicyValidator(OVERWATCH_SCHEMA);
+    const validationResult = validator.validate(cedarText);
+    expect(validationResult.valid).toBe(true);
+
+    // Step 4: Parse back to PolicyRule
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+    expect(parseResult.rules).toHaveLength(1);
+
+    const parsedRule = parseResult.rules[0];
+
+    // Step 5: Verify all annotations are preserved
+    expect(parsedRule.annotations.id).toBe('rule-001');
+    expect(parsedRule.annotations.name).toBe('Block high-threat tool calls');
+    expect(parsedRule.annotations.description).toBe(
+      'Forbids tool calls when threat count exceeds threshold'
+    );
+    expect(parsedRule.annotations.severity).toBe('high');
+    expect(parsedRule.annotations.tags).toEqual(['security', 'baseline', 'v2']);
+  });
+
+  /**
+   * Test 2: Custom Annotations Round-Trip
+   *
+   * Verifies that custom user-defined annotations are preserved.
+   */
+  it('should preserve custom annotations through Cedar round-trip', () => {
+    const originalRule: PolicyRule = {
+      annotations: {
+        id: 'compliance-rule',
+        name: 'SOC2 Compliance Policy',
+        severity: 'critical' as PolicySeverity,
+      },
+      customAnnotations: {
+        compliance: 'SOC2',
+        ticket: 'SEC-1234',
+        owner: 'security-team',
+        review_date: '2024-06-01',
+      },
+      effect: 'forbid' as PolicyEffect,
+      principal: null,
+      action: 'Overwatch::Action::"call_tool"',
+      resource: null,
+      conditions: [],
+      rawCondition: 'context.contains_secrets == true',
+      enabled: true,
+      order: 0,
+    };
+
+    // Convert to Cedar
+    const cedarText = ruleToCedar(originalRule);
+
+    // Verify custom annotations in Cedar text (alphabetically ordered)
+    expect(cedarText).toContain('@compliance("SOC2")');
+    expect(cedarText).toContain('@owner("security-team")');
+    expect(cedarText).toContain('@review_date("2024-06-01")');
+    expect(cedarText).toContain('@ticket("SEC-1234")');
+
+    // Validate Cedar
+    const validator = new PolicyValidator(OVERWATCH_SCHEMA);
+    expect(validator.validate(cedarText).valid).toBe(true);
+
+    // Parse back
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+    const parsedRule = parseResult.rules[0];
+
+    // Verify custom annotations preserved
+    expect(parsedRule.customAnnotations).toBeDefined();
+    expect(parsedRule.customAnnotations?.compliance).toBe('SOC2');
+    expect(parsedRule.customAnnotations?.ticket).toBe('SEC-1234');
+    expect(parsedRule.customAnnotations?.owner).toBe('security-team');
+    expect(parsedRule.customAnnotations?.review_date).toBe('2024-06-01');
+  });
+
+  /**
+   * Test 3: Multiple Rules with rulesToCedar
+   *
+   * Verifies that multiple rules are correctly converted and ordered.
+   */
+  it('should handle multiple rules with correct ordering', () => {
+    const rules: PolicyRule[] = [
+      {
+        annotations: { id: 'rule-c', name: 'Third Rule' },
+        effect: 'permit' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"read_file"',
+        resource: null,
+        conditions: [],
+        enabled: true,
+        order: 2,
+      },
+      {
+        annotations: { id: 'rule-a', name: 'First Rule', severity: 'critical' as PolicySeverity },
+        effect: 'forbid' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"call_tool"',
+        resource: null,
+        conditions: [],
+        rawCondition: 'context.threat_count > 0',
+        enabled: true,
+        order: 0,
+      },
+      {
+        annotations: { id: 'rule-b', name: 'Second Rule (Disabled)' },
+        effect: 'forbid' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"write_file"',
+        resource: null,
+        conditions: [],
+        enabled: false, // Disabled rule
+        order: 1,
+      },
+    ];
+
+    // Convert to Cedar (enabled only, sorted by order)
+    const cedarText = rulesToCedar(rules);
+
+    // Verify order (rule-a order=0 should come before rule-c order=2)
+    const ruleAIndex = cedarText.indexOf('@id("rule-a")');
+    const ruleCIndex = cedarText.indexOf('@id("rule-c")');
+    expect(ruleAIndex).toBeLessThan(ruleCIndex);
+
+    // Disabled rule should NOT be included
+    expect(cedarText).not.toContain('@id("rule-b")');
+
+    // Validate the combined policy text
+    const validator = new PolicyValidator(OVERWATCH_SCHEMA);
+    expect(validator.validate(cedarText).valid).toBe(true);
+
+    // Parse back and verify
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+    expect(parseResult.rules).toHaveLength(2); // Only enabled rules
+
+    // Verify parsed rules
+    const ruleIds = parseResult.rules.map((r: any) => r.annotations.id);
+    expect(ruleIds).toContain('rule-a');
+    expect(ruleIds).toContain('rule-c');
+    expect(ruleIds).not.toContain('rule-b');
+  });
+
+  /**
+   * Test 4: Disabled Rules as Comments
+   *
+   * Verifies that includeDisabled=true adds disabled rules as comments.
+   */
+  it('should include disabled rules as comments when requested', () => {
+    const rules: PolicyRule[] = [
+      {
+        annotations: { id: 'active-rule', name: 'Active Rule' },
+        effect: 'permit' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"call_tool"',
+        resource: null,
+        conditions: [],
+        enabled: true,
+        order: 0,
+      },
+      {
+        annotations: { id: 'disabled-rule', name: 'Disabled Rule' },
+        effect: 'forbid' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"call_tool"',
+        resource: null,
+        conditions: [],
+        enabled: false,
+        order: 1,
+      },
+    ];
+
+    // Convert with includeDisabled=true
+    const cedarText = rulesToCedar(rules, true);
+
+    // Active rule should be normal
+    expect(cedarText).toContain('@id("active-rule")');
+    expect(cedarText).not.toMatch(/\/\/ \[DISABLED\].*@id\("active-rule"\)/);
+
+    // Disabled rule should be commented
+    expect(cedarText).toContain('// [DISABLED] @id("disabled-rule")');
+    expect(cedarText).toContain('// [DISABLED] @name("Disabled Rule")');
+    expect(cedarText).toContain('// [DISABLED] forbid');
+  });
+
+  /**
+   * Test 5: Annotation Value Escaping
+   *
+   * Verifies that special characters in annotation values are properly escaped.
+   */
+  it('should properly escape special characters in annotation values', () => {
+    const rule: PolicyRule = {
+      annotations: {
+        id: 'escape-test',
+        name: 'Rule with "quotes" and \\backslashes',
+        description: 'Multi-line text works too',
+      },
+      effect: 'permit' as PolicyEffect,
+      principal: null,
+      action: 'Overwatch::Action::"call_tool"',
+      resource: null,
+      conditions: [],
+      enabled: true,
+      order: 0,
+    };
+
+    const cedarText = ruleToCedar(rule);
+
+    // Quotes and backslashes should be escaped
+    expect(cedarText).toContain('Rule with \\"quotes\\" and \\\\backslashes');
+
+    // Parse back and verify values are unescaped
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+
+    const parsedRule = parseResult.rules[0];
+    expect(parsedRule.annotations.name).toBe('Rule with "quotes" and \\backslashes');
+  });
+
+  /**
+   * Test 6: Annotation Key Validation
+   *
+   * Verifies that only valid annotation keys are accepted.
+   */
+  it('should validate annotation keys correctly', () => {
+    // Valid custom keys
+    expect(isValidAnnotationKey('compliance')).toBe(true);
+    expect(isValidAnnotationKey('ticket_number')).toBe(true);
+    expect(isValidAnnotationKey('_internal')).toBe(true);
+    expect(isValidAnnotationKey('myKey123')).toBe(true);
+
+    // Invalid - predefined keys (handled separately)
+    expect(isValidAnnotationKey('id')).toBe(false);
+    expect(isValidAnnotationKey('name')).toBe(false);
+    expect(isValidAnnotationKey('severity')).toBe(false);
+    expect(isValidAnnotationKey('tags')).toBe(false);
+
+    // Invalid - bad format
+    expect(isValidAnnotationKey('123abc')).toBe(false); // Starts with number
+    expect(isValidAnnotationKey('has-dash')).toBe(false); // Contains dash
+    expect(isValidAnnotationKey('has.dot')).toBe(false); // Contains dot
+    expect(isValidAnnotationKey('')).toBe(false); // Empty
+  });
+
+  /**
+   * Test 7: Generated Rule ID
+   *
+   * Verifies that rule IDs are auto-generated when not provided.
+   */
+  it('should auto-generate rule IDs when not provided', () => {
+    const id1 = generateRuleId();
+    const id2 = generateRuleId();
+
+    // Should be valid UUIDs
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    expect(id1).toMatch(uuidRegex);
+    expect(id2).toMatch(uuidRegex);
+
+    // Should be unique
+    expect(id1).not.toBe(id2);
+  });
+
+  /**
+   * Test 8: Palisade Schema Compatibility
+   *
+   * Verifies annotations work correctly with Palisade schema.
+   */
+  it('should work correctly with Palisade schema', () => {
+    const rule: PolicyRule = {
+      annotations: {
+        id: 'palisade-rule-001',
+        name: 'Block Critical ML Findings',
+        description: 'Prevents loading models with critical security findings',
+        severity: 'critical' as PolicySeverity,
+        tags: ['ml-security', 'compliance'],
+      },
+      customAnnotations: {
+        framework: 'pytorch',
+        scan_type: 'static',
+      },
+      effect: 'forbid' as PolicyEffect,
+      principal: { type: 'Palisade::Scanner' },
+      action: 'Palisade::Action::"load_model"',
+      resource: { type: 'Palisade::Artifact' },
+      conditions: [],
+      rawCondition: 'context.severity == "CRITICAL"',
+      enabled: true,
+      order: 0,
+    };
+
+    const cedarText = ruleToCedar(rule);
+
+    // Validate against Palisade schema
+    const validator = new PolicyValidator(PALISADE_SCHEMA);
+    expect(validator.validate(cedarText).valid).toBe(true);
+
+    // Parse and verify
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+
+    const parsedRule = parseResult.rules[0];
+    expect(parsedRule.annotations.id).toBe('palisade-rule-001');
+    expect(parsedRule.annotations.severity).toBe('critical');
+    expect(parsedRule.customAnnotations?.framework).toBe('pytorch');
+  });
+
+  /**
+   * Test 9: Full Policy Lifecycle with Annotations
+   *
+   * Simulates the complete Studio UI workflow:
+   * 1. Create rules via UI form
+   * 2. Convert to Cedar for storage/evaluation
+   * 3. Validate against schema
+   * 4. Load into engine
+   * 5. Evaluate requests
+   * 6. Parse back for editing
+   */
+  it('should support full policy lifecycle with annotations', () => {
+    // Step 1: Create rules via UI form (simulated)
+    const rules: PolicyRule[] = [
+      {
+        annotations: {
+          id: 'allow-safe-tools',
+          name: 'Allow Safe Tools',
+          description: 'Permits tool calls with no detected threats',
+          severity: 'low' as PolicySeverity,
+        },
+        effect: 'permit' as PolicyEffect,
+        principal: { type: 'Overwatch::User' },
+        action: 'Overwatch::Action::"call_tool"',
+        resource: { type: 'Overwatch::Tool' },
+        conditions: [],
+        rawCondition: 'context.threat_count == 0',
+        enabled: true,
+        order: 0,
+      },
+      {
+        annotations: {
+          id: 'block-high-threats',
+          name: 'Block High Threats',
+          severity: 'critical' as PolicySeverity,
+          tags: ['security'],
+        },
+        effect: 'forbid' as PolicyEffect,
+        principal: null,
+        action: 'Overwatch::Action::"call_tool"',
+        resource: null,
+        conditions: [{ field: 'threat_count', operator: 'gt' as ConditionOperator, value: 0 }],
+        enabled: true,
+        order: 1,
+      },
+    ];
+
+    // Step 2: Convert to Cedar for storage
+    const cedarText = rulesToCedar(rules);
+
+    // Step 3: Validate
+    const validator = new PolicyValidator(OVERWATCH_SCHEMA);
+    expect(validator.validate(cedarText).valid).toBe(true);
+
+    // Step 4: Load into engine
+    const engine = new PolicyEngine({ schema: OVERWATCH_SCHEMA });
+    engine.loadPolicies(cedarText);
+
+    // Step 5: Evaluate - safe request (0 threats) should be allowed
+    const entities = [
+      newEntity('Overwatch::User', 'mcp_client', { user_type: 'external', email: 'test@example.com' }),
+      newEntity('Overwatch::Tool', 'shell', { tool_name: 'shell', risk_level: 'low' }),
+    ];
+
+    const safeRequest = engine.evaluate({
+      principal: newEntityUID('Overwatch::User', 'mcp_client'),
+      action: 'Overwatch::Action::"call_tool"',
+      resource: newEntityUID('Overwatch::Tool', 'shell'),
+      context: {
+        content: 'ls',
+        source: 'claudecode',
+        event: 'PreToolUse',
+        user_email: 'test@example.com',
+        tool_name: 'shell',
+        threat_count: 0,
+        highest_severity: 'low',
+        threat_categories: [],
+        threat_types: [],
+        yara_threats: [],
+        max_threat_severity: 0,
+        contains_secrets: false,
+        mcp_server: '',
+        mcp_tool: '',
+        path: '',
+        cwd: '',
+        workspace_root: '',
+        response_content: '',
+      },
+      entities,
+    });
+    expect(safeRequest.effect).toBe('Allow');
+
+    // Risky request (threats detected) should be denied
+    const riskyRequest = engine.evaluate({
+      principal: newEntityUID('Overwatch::User', 'mcp_client'),
+      action: 'Overwatch::Action::"call_tool"',
+      resource: newEntityUID('Overwatch::Tool', 'shell'),
+      context: {
+        content: 'rm -rf /',
+        source: 'claudecode',
+        event: 'PreToolUse',
+        user_email: 'test@example.com',
+        tool_name: 'shell',
+        threat_count: 3,
+        highest_severity: 'critical',
+        threat_categories: ['destructive'],
+        threat_types: ['shell_command'],
+        yara_threats: [],
+        max_threat_severity: 4,
+        contains_secrets: false,
+        mcp_server: '',
+        mcp_tool: '',
+        path: '',
+        cwd: '',
+        workspace_root: '',
+        response_content: '',
+      },
+      entities,
+    });
+    expect(riskyRequest.effect).toBe('Deny');
+
+    // Step 6: Parse back for editing
+    const parseResult = parseCedarToRules(cedarText);
+    expect(parseResult.errors).toHaveLength(0);
+    expect(parseResult.rules).toHaveLength(2);
+
+    // Verify all rules and annotations are preserved for editing
+    const allowRule = parseResult.rules.find((r: any) => r.annotations.id === 'allow-safe-tools');
+    const blockRule = parseResult.rules.find((r: any) => r.annotations.id === 'block-high-threats');
+    expect(allowRule?.annotations.name).toBe('Allow Safe Tools');
+    expect(blockRule?.annotations.severity).toBe('critical');
+    expect(blockRule?.annotations.tags).toEqual(['security']);
+  });
+});

package/src/types.ts

@@ -17,6 +17,9 @@ export * from './builder.js';
 // Error types - works in browser (no WASM dependency)
 export * from './errors.js';
 
+// Annotations - works in browser (no WASM dependency)
+export * from './annotations.js';
+
 // Service-specific schemas and context (inlined, browser-safe)
 export {
   OVERWATCH_SCHEMA,