@highflame/policy 1.2.0 → 2.0.0

package/README.md

@@ -0,0 +1,219 @@
+# @highflame/policy - TypeScript Package
+
+[![npm version](https://badge.fury.io/js/%40highflame%2Fpolicy.svg)](https://www.npmjs.com/package/@highflame/policy)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.5%2B-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Cedar policy engine and typed constants for the Highflame security platform. Ensures entity/action consistency across all Highflame services.
+
+## Features
+
+- 🔒 **Cedar Policy Evaluation** - Wraps `@cedar-policy/cedar-wasm` with Highflame types
+- 📝 **Typed Constants** - Auto-generated entity types, actions, and context keys
+- 🎨 **PolicyBuilder** - Type-safe policy builder for UI (works in browser!)
+- 🔄 **Cedar Parser** - Convert Cedar text to structured PolicyRule JSON
+- ✅ **Schema Validation** - Full schema validation with embedded schemas
+- 🌐 **Namespace Support** - Generic support for namespaced actions
+- 🌍 **Browser + Node.js** - Separate entry points for each environment
+
+## Installation
+
+```bash
+npm install @highflame/policy
+```
+
+## Quick Start
+
+### Node.js - Policy Evaluation (Palisade Example)
+
+```typescript
+import { PolicyEngine, EntityType, ActionType, schemas } from '@highflame/policy';
+import { PalisadeContextKey } from '@highflame/policy/schemas';
+
+const engine = new PolicyEngine();
+engine.loadSchema(schemas.PALISADE_SCHEMA);
+engine.loadPolicies(policyContent);
+
+const decision = engine.evaluateSimple(
+  EntityType.Scanner,
+  "palisade",
+  ActionType.ScanArtifact,
+  EntityType.Artifact,
+  "/model.safetensors",
+  {
+    [PalisadeContextKey.ArtifactFormat]: "safetensors",
+    [PalisadeContextKey.Severity]: "HIGH",
+    [PalisadeContextKey.Environment]: "production",
+  }
+);
+
+if (decision.effect === "Deny") {
+  console.log(`Blocked by: ${decision.determining_policies}`);
+}
+```
+
+### Browser - PolicyBuilder (No WASM!)
+
+```typescript
+import { PolicyBuilder, EntityType, ActionType } from '@highflame/policy/types';
+import { PalisadeContextKey } from '@highflame/policy/schemas';
+
+// Works in browser - no Cedar WASM dependency!
+const policy = PolicyBuilder.permit()
+    .name("Allow artifact scanning in production")
+    .principalType(EntityType.Scanner)
+    .action(ActionType.ScanArtifact)
+    .resourceType(EntityType.Artifact)
+    .when(PalisadeContextKey.Environment, 'eq', 'production')
+    .build();
+
+const cedarText = policy.toCedar();
+// Send to backend for validation + storage
+```
+
+### Service-Specific Schemas
+
+```typescript
+import { PolicyEngine, schemas } from '@highflame/policy';
+
+// Use Overwatch schema for IDE security (Guardian)
+const engine = new PolicyEngine();
+engine.loadSchema(schemas.OVERWATCH_SCHEMA);
+
+const decision = engine.evaluateSimple(
+    "Overwatch::User",
+    "mcp_client",
+    'Overwatch::Action::"call_tool"',
+    "Overwatch::Tool",
+    "shell",
+    { threat_count: 3 }
+);
+```
+
+## Entry Points
+
+### `@highflame/policy` (Node.js)
+Full package including PolicyEngine, validation, and schemas.
+
+```typescript
+import {
+  PolicyEngine,      // Cedar evaluation
+  validatePolicy,    // Schema validation
+  parseCedarToRules, // Parser
+  EntityType,        // Constants
+  ActionType,
+  schemas            // Service schemas
+} from '@highflame/policy';
+
+// Import service-specific context keys
+import { OverwatchContextKey, PalisadeContextKey } from '@highflame/policy/schemas';
+```
+
+### `@highflame/policy/types` (Browser + Node.js)
+Types, constants, and PolicyBuilder only - no WASM dependency.
+
+```typescript
+import {
+  EntityType,
+  ActionType,
+  PolicyBuilder
+} from '@highflame/policy/types';
+
+// Import service-specific context keys
+import { OverwatchContextKey, PalisadeContextKey } from '@highflame/policy/schemas';
+```
+
+## PolicyBuilder API
+
+Perfect for building policies in UI:
+
+```typescript
+import { PolicyBuilder, EntityType, ActionType } from '@highflame/policy/types';
+import { PalisadeContextKey } from '@highflame/policy/schemas';
+
+const policy = PolicyBuilder.permit()
+    .name("Allow scanners to scan artifacts in production")
+    .principalType(EntityType.Scanner)
+    .action(ActionType.ScanArtifact)
+    .resourceType(EntityType.Artifact)
+    .when(PalisadeContextKey.Environment, 'eq', 'production')
+    .when(PalisadeContextKey.Severity, 'eq', 'HIGH')
+    .build();
+
+// Get Cedar text
+const cedarText = policy.toCedar();
+
+// Get JSON for editing
+const policyJson = policy.toJSON();
+```
+
+## Cedar Parser
+
+Parse existing policies for UI editing:
+
+```typescript
+import { parseCedarToRules } from '@highflame/policy';
+
+const result = parseCedarToRules(cedarText);
+
+// Successfully parsed policies
+result.rules.forEach(rule => {
+  console.log(rule.id, rule.effect);
+  // Edit in UI, then rebuild with PolicyBuilder
+});
+
+// Policies that can't be represented (unless clauses, templates)
+result.unstructured.forEach(policy => {
+  // Show as raw Cedar text
+});
+```
+
+## Available Constants
+
+- **17 Entity Types**: `EntityType.User`, `Scanner`, `Artifact`, `Tool`, etc.
+- **38 Actions**: `ActionType.ScanArtifact`, `CallTool`, `LoadModel`, etc.
+- **Service-Specific Context Keys**:
+  - **Overwatch**: `OverwatchContextKey.ThreatCount`, `ToolName`, `UserEmail`, etc.
+  - **Palisade**: `PalisadeContextKey.Environment`, `Severity`, `ArtifactFormat`, etc.
+
+## Service Schemas
+
+### Overwatch (Guardian)
+```typescript
+import { schemas } from '@highflame/policy';
+
+// schemas.OVERWATCH_SCHEMA - Cedar schema
+// schemas.OVERWATCH_CONTEXT - Context metadata (JSON)
+```
+
+### Palisade
+```typescript
+// schemas.PALISADE_SCHEMA - Cedar schema
+// schemas.PALISADE_CONTEXT - Context metadata (JSON)
+```
+
+## Why Typed Constants?
+
+**Without types (error-prone):**
+```typescript
+context: {
+  "enviroment": "production",  // Typo! Policy won't match
+}
+```
+
+**With types (autocomplete + type checking):**
+```typescript
+import { PalisadeContextKey } from '@highflame/policy/schemas';
+
+context: {
+  [PalisadeContextKey.Environment]: "production",  // ✓ Autocomplete works!
+}
+```
+
+## Documentation
+
+Full documentation: [CLAUDE.md](https://github.com/highflame-ai/highflame-policy/blob/main/CLAUDE.md)
+
+## License
+
+Apache 2.0

package/_schemas/overwatch/context.json

@@ -0,0 +1,463 @@
+{
+  "service": "overwatch",
+  "version": "1.0.0",
+  "description": "Overwatch (Guardian) IDE security & policy enforcement",
+  "actions": [
+    {
+      "name": "process_prompt",
+      "description": "User submits a prompt or receives AI response",
+      "context_attributes": [
+        {
+          "key": "content",
+          "type": "string",
+          "required": true,
+          "description": "Raw content being scanned (prompt, command, etc.)"
+        },
+        {
+          "key": "source",
+          "type": "string",
+          "required": true,
+          "description": "IDE source: cursor, claudecode, github_copilot"
+        },
+        {
+          "key": "event",
+          "type": "string",
+          "required": true,
+          "description": "Hook event name (e.g., beforeSubmitPrompt, UserPromptSubmit)"
+        },
+        {
+          "key": "user_email",
+          "type": "string",
+          "required": true,
+          "description": "User identifier (OAuth verified or fallback)"
+        },
+        {
+          "key": "cwd",
+          "type": "string",
+          "required": false,
+          "description": "Current working directory"
+        },
+        {
+          "key": "workspace_root",
+          "type": "string",
+          "required": false,
+          "description": "Workspace/repository root path"
+        },
+        {
+          "key": "threat_count",
+          "type": "number",
+          "required": true,
+          "description": "Total number of threats detected by YARA/Javelin"
+        },
+        {
+          "key": "highest_severity",
+          "type": "string",
+          "required": true,
+          "description": "Highest severity level: critical, high, medium, low"
+        },
+        {
+          "key": "threat_categories",
+          "type": "array",
+          "required": true,
+          "description": "Threat category names from aggregator"
+        },
+        {
+          "key": "threat_types",
+          "type": "array",
+          "required": true,
+          "description": "YARA threat category names"
+        },
+        {
+          "key": "yara_threats",
+          "type": "array",
+          "required": true,
+          "description": "YARA rule names that matched"
+        },
+        {
+          "key": "max_threat_severity",
+          "type": "number",
+          "required": true,
+          "description": "Numeric severity (0-4, where 4=CRITICAL)"
+        },
+        {
+          "key": "contains_secrets",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether secrets or credentials were detected"
+        },
+        {
+          "key": "prompt_text",
+          "type": "string",
+          "required": false,
+          "description": "Same as content (legacy field)"
+        },
+        {
+          "key": "response_content",
+          "type": "string",
+          "required": false,
+          "description": "Response content from AI (if available)"
+        }
+      ]
+    },
+    {
+      "name": "call_tool",
+      "description": "User calls a tool (native IDE tool or MCP tool)",
+      "context_attributes": [
+        {
+          "key": "content",
+          "type": "string",
+          "required": true,
+          "description": "Raw content being scanned (e.g., shell command)"
+        },
+        {
+          "key": "source",
+          "type": "string",
+          "required": true,
+          "description": "IDE source: cursor, claudecode, github_copilot"
+        },
+        {
+          "key": "event",
+          "type": "string",
+          "required": true,
+          "description": "Hook event name (e.g., beforeShellExecution, PreToolUse)"
+        },
+        {
+          "key": "user_email",
+          "type": "string",
+          "required": true,
+          "description": "User identifier"
+        },
+        {
+          "key": "tool_name",
+          "type": "string",
+          "required": false,
+          "description": "Normalized tool name: shell, read_file, write_file, edit_file, etc."
+        },
+        {
+          "key": "mcp_server",
+          "type": "string",
+          "required": false,
+          "description": "MCP server name (e.g., filesystem, playwright)"
+        },
+        {
+          "key": "mcp_tool",
+          "type": "string",
+          "required": false,
+          "description": "MCP tool name (e.g., list_directory, navigate)"
+        },
+        {
+          "key": "server_name",
+          "type": "string",
+          "required": false,
+          "description": "Alias for mcp_server (duplicate field)"
+        },
+        {
+          "key": "path",
+          "type": "string",
+          "required": false,
+          "description": "File path (if file operation)"
+        },
+        {
+          "key": "file_path",
+          "type": "string",
+          "required": false,
+          "description": "Duplicate of path field"
+        },
+        {
+          "key": "cwd",
+          "type": "string",
+          "required": false,
+          "description": "Current working directory"
+        },
+        {
+          "key": "workspace_root",
+          "type": "string",
+          "required": false,
+          "description": "Workspace/repository root path"
+        },
+        {
+          "key": "threat_count",
+          "type": "number",
+          "required": true,
+          "description": "Total threats detected"
+        },
+        {
+          "key": "highest_severity",
+          "type": "string",
+          "required": true,
+          "description": "Highest severity: critical, high, medium, low"
+        },
+        {
+          "key": "threat_categories",
+          "type": "array",
+          "required": true,
+          "description": "Threat category names"
+        },
+        {
+          "key": "threat_types",
+          "type": "array",
+          "required": true,
+          "description": "YARA threat categories"
+        },
+        {
+          "key": "yara_threats",
+          "type": "array",
+          "required": true,
+          "description": "YARA rule names"
+        },
+        {
+          "key": "max_threat_severity",
+          "type": "number",
+          "required": true,
+          "description": "Numeric severity (0-4)"
+        },
+        {
+          "key": "contains_secrets",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether secrets detected"
+        },
+        {
+          "key": "response_content",
+          "type": "string",
+          "required": false,
+          "description": "Response content (if available)"
+        }
+      ]
+    },
+    {
+      "name": "connect_server",
+      "description": "Connect to an MCP server",
+      "context_attributes": [
+        {
+          "key": "content",
+          "type": "string",
+          "required": true,
+          "description": "Raw content being scanned"
+        },
+        {
+          "key": "source",
+          "type": "string",
+          "required": true,
+          "description": "IDE source"
+        },
+        {
+          "key": "event",
+          "type": "string",
+          "required": true,
+          "description": "Hook event name"
+        },
+        {
+          "key": "user_email",
+          "type": "string",
+          "required": true,
+          "description": "User identifier"
+        },
+        {
+          "key": "mcp_server",
+          "type": "string",
+          "required": false,
+          "description": "MCP server name"
+        },
+        {
+          "key": "server_name",
+          "type": "string",
+          "required": false,
+          "description": "Alias for mcp_server"
+        },
+        {
+          "key": "threat_count",
+          "type": "number",
+          "required": true,
+          "description": "Total threats detected"
+        },
+        {
+          "key": "highest_severity",
+          "type": "string",
+          "required": true,
+          "description": "Highest severity level"
+        },
+        {
+          "key": "threat_categories",
+          "type": "array",
+          "required": true,
+          "description": "Threat category names"
+        },
+        {
+          "key": "max_threat_severity",
+          "type": "number",
+          "required": true,
+          "description": "Numeric severity (0-4)"
+        }
+      ]
+    },
+    {
+      "name": "read_file",
+      "description": "Read a file from disk",
+      "context_attributes": [
+        {
+          "key": "content",
+          "type": "string",
+          "required": true,
+          "description": "File content or operation details"
+        },
+        {
+          "key": "source",
+          "type": "string",
+          "required": true,
+          "description": "IDE source"
+        },
+        {
+          "key": "event",
+          "type": "string",
+          "required": true,
+          "description": "Hook event name (e.g., beforeReadFile)"
+        },
+        {
+          "key": "user_email",
+          "type": "string",
+          "required": true,
+          "description": "User identifier"
+        },
+        {
+          "key": "path",
+          "type": "string",
+          "required": false,
+          "description": "File path being read"
+        },
+        {
+          "key": "file_path",
+          "type": "string",
+          "required": false,
+          "description": "Duplicate of path field"
+        },
+        {
+          "key": "cwd",
+          "type": "string",
+          "required": false,
+          "description": "Current working directory"
+        },
+        {
+          "key": "workspace_root",
+          "type": "string",
+          "required": false,
+          "description": "Workspace root path"
+        },
+        {
+          "key": "threat_count",
+          "type": "number",
+          "required": true,
+          "description": "Total threats detected"
+        },
+        {
+          "key": "highest_severity",
+          "type": "string",
+          "required": true,
+          "description": "Highest severity level"
+        },
+        {
+          "key": "threat_categories",
+          "type": "array",
+          "required": true,
+          "description": "Threat categories"
+        },
+        {
+          "key": "max_threat_severity",
+          "type": "number",
+          "required": true,
+          "description": "Numeric severity (0-4)"
+        },
+        {
+          "key": "contains_secrets",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether secrets detected"
+        }
+      ]
+    },
+    {
+      "name": "write_file",
+      "description": "Write a file to disk",
+      "context_attributes": [
+        {
+          "key": "content",
+          "type": "string",
+          "required": true,
+          "description": "File content being written"
+        },
+        {
+          "key": "source",
+          "type": "string",
+          "required": true,
+          "description": "IDE source"
+        },
+        {
+          "key": "event",
+          "type": "string",
+          "required": true,
+          "description": "Hook event name"
+        },
+        {
+          "key": "user_email",
+          "type": "string",
+          "required": true,
+          "description": "User identifier"
+        },
+        {
+          "key": "path",
+          "type": "string",
+          "required": false,
+          "description": "File path being written"
+        },
+        {
+          "key": "file_path",
+          "type": "string",
+          "required": false,
+          "description": "Duplicate of path field"
+        },
+        {
+          "key": "cwd",
+          "type": "string",
+          "required": false,
+          "description": "Current working directory"
+        },
+        {
+          "key": "workspace_root",
+          "type": "string",
+          "required": false,
+          "description": "Workspace root path"
+        },
+        {
+          "key": "threat_count",
+          "type": "number",
+          "required": true,
+          "description": "Total threats detected"
+        },
+        {
+          "key": "highest_severity",
+          "type": "string",
+          "required": true,
+          "description": "Highest severity level"
+        },
+        {
+          "key": "threat_categories",
+          "type": "array",
+          "required": true,
+          "description": "Threat categories"
+        },
+        {
+          "key": "max_threat_severity",
+          "type": "number",
+          "required": true,
+          "description": "Numeric severity (0-4)"
+        },
+        {
+          "key": "contains_secrets",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether secrets detected"
+        }
+      ]
+    }
+  ]
+}