@highflame/policy 1.1.3

package/src/engine.ts

@@ -0,0 +1,252 @@
+/**
+ * Highflame Policy Engine - TypeScript Wrapper
+ * Wraps @cedar-policy/cedar-wasm with Highflame-specific types
+ */
+
+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";
+
+export interface Decision {
+  effect: "Allow" | "Deny";
+  determining_policies: string[];
+  reason?: string;
+}
+
+export interface EvaluateRequest {
+  principal: EntityUID;
+  action: ActionType;
+  resource: EntityUID;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Convert a value to Cedar JSON format
+ */
+function toCedarValue(value: unknown): cedar.CedarValueJson {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(toCedarValue);
+  }
+  if (typeof value === "object") {
+    const result: Record<string, cedar.CedarValueJson> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = toCedarValue(v);
+    }
+    return result;
+  }
+  return String(value);
+}
+
+/**
+ * PolicyEngine wraps cedar-wasm with Highflame schema types.
+ */
+export class PolicyEngine {
+  private policies: string = "";
+  private schema: string | undefined;
+
+  /**
+   * Load policies from a Cedar policy string.
+   */
+  loadPolicies(policies: string): void {
+    this.policies = policies;
+  }
+
+  /**
+   * 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.
+   */
+  evaluate(req: EvaluateRequest): Decision {
+    // Build EntityUIDs in Cedar JSON format
+    const principal: cedar.EntityUidJson = {
+      type: req.principal.type,
+      id: req.principal.id,
+    };
+    const action: cedar.EntityUidJson = {
+      type: "Action",
+      id: req.action,
+    };
+    const resource: cedar.EntityUidJson = {
+      type: req.resource.type,
+      id: req.resource.id,
+    };
+
+    // Convert context to Cedar format
+    const context: cedar.Context = {};
+    if (req.context) {
+      for (const [k, v] of Object.entries(req.context)) {
+        context[k] = toCedarValue(v);
+      }
+    }
+
+    // Build the authorization call
+    const call: cedar.AuthorizationCall = {
+      principal,
+      action,
+      resource,
+      context,
+      policies: { staticPolicies: this.policies },
+      entities: [],
+    };
+
+    // Add schema if available
+    if (this.schema) {
+      call.schema = this.schema;
+    }
+
+    const result = cedar.isAuthorized(call);
+
+    if (result.type === "failure") {
+      return {
+        effect: "Deny",
+        determining_policies: [],
+        reason: result.errors.map(e => e.message).join("; "),
+      };
+    }
+
+    return {
+      effect: result.response.decision === "allow" ? "Allow" : "Deny",
+      determining_policies: result.response.diagnostics.reason,
+      reason: result.response.diagnostics.errors.length > 0
+        ? result.response.diagnostics.errors.map(e => e.error.message).join("; ")
+        : undefined,
+    };
+  }
+
+  /**
+   * Convenience method for simple evaluations.
+   */
+  evaluateSimple(
+    principalType: EntityType,
+    principalId: string,
+    action: ActionType,
+    resourceType: EntityType,
+    resourceId: string,
+    context?: Record<string, unknown>
+  ): Decision {
+    return this.evaluate({
+      principal: { type: principalType, id: principalId },
+      action,
+      resource: { type: resourceType, id: resourceId },
+      context,
+    });
+  }
+
+  /**
+   * Validate policies against the schema.
+   * Returns validation errors or empty array if valid.
+   */
+  validatePolicies(policies: string): string[] {
+    const schemaToUse = this.schema ?? CEDAR_SCHEMA;
+
+    const result = cedar.validate({
+      validationSettings: { mode: "strict" },
+      schema: schemaToUse,
+      policies: { staticPolicies: policies },
+    });
+
+    if (result.type === "failure") {
+      return result.errors.map(e => e.message);
+    }
+
+    return result.validationErrors.map(e => e.error.message);
+  }
+}
+
+/**
+ * PolicyValidator provides static validation against the Highflame schema.
+ * Use this for quick validation without creating an engine instance.
+ */
+export class PolicyValidator {
+  private schema: string;
+
+  /**
+   * Create a validator with the embedded Highflame schema.
+   */
+  constructor(schema?: string) {
+    this.schema = schema ?? CEDAR_SCHEMA;
+  }
+
+  /**
+   * Validate Cedar policy text against the schema.
+   */
+  validate(policies: string): { valid: boolean; errors: string[] } {
+    const result = cedar.validate({
+      validationSettings: { mode: "strict" },
+      schema: this.schema,
+      policies: { staticPolicies: policies },
+    });
+
+    if (result.type === "failure") {
+      return {
+        valid: false,
+        errors: result.errors.map(e => e.message),
+      };
+    }
+
+    if (result.validationErrors.length > 0) {
+      return {
+        valid: false,
+        errors: result.validationErrors.map(e => e.error.message),
+      };
+    }
+
+    return { valid: true, errors: [] };
+  }
+
+  /**
+   * Check if a policy parses correctly (syntax check only).
+   */
+  checkSyntax(policies: string): { valid: boolean; errors: string[] } {
+    const result = cedar.checkParsePolicySet({ staticPolicies: policies });
+    if (result.type === "failure") {
+      return {
+        valid: false,
+        errors: result.errors.map(e => e.message),
+      };
+    }
+    return { valid: true, errors: [] };
+  }
+}
+
+/**
+ * Validate a Cedar policy against the Highflame schema.
+ * Convenience function that doesn't require creating a validator instance.
+ */
+export function validatePolicy(policy: string): { valid: boolean; errors: string[] } {
+  const validator = new PolicyValidator();
+  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

@@ -0,0 +1,60 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schema/highflame.cedarschema
+
+/**
+ * Entity types defined in the Highflame Cedar schema.
+ */
+export const EntityType = {
+    Agent: 'Agent',
+    Artifact: 'Artifact',
+    FilePath: 'FilePath',
+    HttpEndpoint: 'HttpEndpoint',
+    Package: 'Package',
+    Repository: 'Repository',
+    Resource: 'Resource',
+    ResponseData: 'ResponseData',
+    Scanner: 'Scanner',
+    Server: 'Server',
+    Service: 'Service',
+    Tool: 'Tool',
+    User: 'User',
+} as const;
+
+export type EntityType = (typeof EntityType)[keyof typeof EntityType];
+
+/**
+ * Cedar entity unique identifier.
+ */
+export interface EntityUID {
+    type: EntityType | string;
+    id: string;
+}
+
+/**
+ * Cedar entity with attributes.
+ */
+export interface Entity {
+    uid: EntityUID;
+    attrs?: Record<string, unknown>;
+    parents?: EntityUID[];
+}
+
+/**
+ * Create a new EntityUID.
+ * Services should use this with their own identity from config/environment.
+ * @example newEntityUID(EntityType.Scanner, process.env.SERVICE_ID)
+ */
+export function newEntityUID(type: EntityType | string, id: string): EntityUID {
+    return { type, id };
+}
+
+/**
+ * Create a new Entity.
+ */
+export function newEntity(type: EntityType | string, id: string, attrs?: Record<string, unknown>): Entity {
+    return {
+        uid: { type, id },
+        attrs: attrs ?? {},
+        parents: [],
+    };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schema/highflame.cedarschema
+//
+// NOTE: This module requires Node.js (uses @cedar-policy/cedar-wasm).
+// For browser usage, import from '@highflame/policy/types' instead.
+
+export * from './entities.gen.js';
+export * from './actions.gen.js';
+export * from './context.gen.js';
+export * from './schema.gen.js';
+
+// Non-generated modules (require Node.js)
+export * from './engine.js';
+export * from './builder.js';

package/src/schema.gen.ts

@@ -0,0 +1,301 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schema/highflame.cedarschema
+
+/**
+ * Embedded Cedar schema for policy validation.
+ * This is the Highflame Cedar schema used across all services.
+ */
+export const CEDAR_SCHEMA = `// Highflame Cedar Schema
+// ======================
+// This is the SOURCE OF TRUTH for all entity types, actions, and their relationships
+// across the Highflame platform.
+//
+// All services (authz, Core, Guardian, Palisade) MUST use the types defined here.
+// The codegen tool parses this file and generates typed constants for Go, TypeScript,
+// and Python to ensure consistency.
+//
+// Usage:
+//   - Policies are validated against this schema when created/updated
+//   - Generated types prevent typos in application code
+//   - Cedar CLI can validate: cedar validate --schema highflame.cedarschema --policies policy.cedar
+
+// =============================================================================
+// PRINCIPAL TYPES (Who is making the request)
+// =============================================================================
+
+// Human user or service account making requests
+// Well-known IDs: "mcp_client", "threat_processor"
+entity User {
+    // User type: "external", "internal"
+    user_type: String,
+};
+
+// AI agent or bot
+entity Agent {
+    // Agent type: "llm", "scanner", "bot"
+    agent_type: String,
+};
+
+// Security scanner service
+// Well-known IDs: "ramparts", "palisade"
+entity Scanner {
+    // Scanner type: "ramparts", "palisade"
+    scanner_type: String,
+    // Scanner version
+    version: String,
+};
+
+// Backend service account
+entity Service {
+    // Service name
+    service_name: String,
+    // Environment: "production", "staging", "development"
+    environment: String,
+};
+
+// =============================================================================
+// RESOURCE TYPES (What is being accessed)
+// =============================================================================
+
+// Generic resource
+// Well-known IDs: "threat_analysis", "tools/list", "tools/call", "resources/list",
+//                 "resources/read", "prompts/list", "unknown"
+entity Resource {};
+
+// LLM response data
+// Well-known IDs: "response_data"
+entity ResponseData {};
+
+// MCP tool that can be called
+entity Tool {
+    // Tool name
+    tool_name: String,
+    // Risk level: "safe", "moderate", "dangerous"
+    risk_level: String,
+    // Category: "file", "network", "shell", "api"
+    category: String,
+};
+
+// File system path
+entity FilePath {
+    // Full path
+    path: String,
+    // File extension
+    extension: String,
+    // Whether file is sensitive (.env, credentials, etc.)
+    is_sensitive: Bool,
+};
+
+// HTTP endpoint
+entity HttpEndpoint {
+    // Hostname
+    hostname: String,
+    // Scheme: "http", "https"
+    scheme: String,
+    // Port number
+    port: Long,
+    // Whether endpoint is internal
+    is_internal: Bool,
+};
+
+// MCP Server
+entity Server {
+    // Server name
+    server_name: String,
+};
+
+// ML model artifact (for Palisade)
+entity Artifact {
+    // Format: "safetensors", "pickle", "gguf", "onnx"
+    artifact_type: String,
+    // Source URL or path
+    source: String,
+    // SHA256 hash
+    hash: String,
+    // Whether artifact is signed
+    is_signed: Bool,
+};
+
+// Code repository
+entity Repository {
+    // Repository URL
+    url: String,
+};
+
+// Software package
+entity Package {
+    // Package name
+    name: String,
+    // Package version
+    version: String,
+};
+
+// =============================================================================
+// ACTIONS
+// =============================================================================
+
+// --- LLM/Guardrails Actions ---
+
+// Process an LLM prompt
+// Context: prompt_text, yara_threats, threat_count, max_threat_severity,
+//          user_type, monitoring_enabled
+action process_prompt appliesTo {
+    principal: [User, Agent],
+    resource: [Resource],
+};
+
+// Process an LLM response
+// Context: response_size_mb
+action process_response appliesTo {
+    principal: [User, Agent],
+    resource: [ResponseData],
+};
+
+// --- MCP/Tool Actions ---
+
+// Call an MCP tool
+// Context: tool_name
+action call_tool appliesTo {
+    principal: [User, Agent, Service],
+    resource: [Tool, Resource],
+};
+
+// Connect to an MCP server
+action connect_server appliesTo {
+    principal: [User, Agent, Service],
+    resource: [Server, Resource],
+};
+
+// Access a server-specific resource
+// Context: tool_name, resource_name, prompt_name
+action access_server_resource appliesTo {
+    principal: [User, Agent, Service],
+    resource: [Resource],
+};
+
+// Skip guardrails for an operation
+action skip_guardrails appliesTo {
+    principal: [User, Agent, Service],
+    resource: [Resource],
+};
+
+// --- File System Actions ---
+
+// Read a file
+// Context: path
+action read_file appliesTo {
+    principal: [User, Agent, Scanner],
+    resource: [FilePath, Resource],
+};
+
+// Write a file
+// Context: path
+action write_file appliesTo {
+    principal: [User, Agent],
+    resource: [FilePath, Resource],
+};
+
+// --- HTTP Actions ---
+
+// Make an HTTP request
+// Context: hostname, ip_address, scheme, port
+action http_request appliesTo {
+    principal: [User, Agent, Service],
+    resource: [HttpEndpoint, Resource],
+};
+
+// --- Scanner Actions ---
+
+// Scan a target (MCP server, repository, etc.)
+action scan_target appliesTo {
+    principal: [Scanner, Service],
+    resource: [Resource, Repository, Server],
+};
+
+// Scan a software package
+action scan_package appliesTo {
+    principal: [Scanner, Service],
+    resource: [Package, Resource],
+};
+
+// --- Palisade/ML Actions ---
+
+// Scan an ML artifact
+// Context: environment, artifact_format, artifact_signed, severity, finding_type,
+//          provenance_signer, pickle_exec_path_detected, metadata_malicious_pattern,
+//          tokenizer_added_tokens_count, safetensors_integrity_violation,
+//          gguf_suspicious_metadata, adapter_base_digest_mismatch,
+//          metadata_cosai_level_numeric
+action scan_artifact appliesTo {
+    principal: [Scanner, Service],
+    resource: [Artifact, Resource],
+};
+
+// Validate artifact integrity
+action validate_integrity appliesTo {
+    principal: [Scanner, Service],
+    resource: [Artifact],
+};
+
+// Validate artifact provenance
+action validate_provenance appliesTo {
+    principal: [Scanner, Service],
+    resource: [Artifact],
+};
+
+// Quarantine an artifact
+action quarantine_artifact appliesTo {
+    principal: [Scanner, Service],
+    resource: [Artifact],
+};
+
+// Load an ML model
+action load_model appliesTo {
+    principal: [User, Agent, Service],
+    resource: [Artifact],
+};
+
+// Deploy an ML model
+action deploy_model appliesTo {
+    principal: [User, Service],
+    resource: [Artifact],
+};
+
+// =============================================================================
+// CONTEXT ATTRIBUTES REFERENCE (Documentation Only)
+// =============================================================================
+// Cedar context is dynamic and not enforced by schema, but these are the
+// standard attributes used across Highflame services:
+//
+// GUARDRAILS/CORE:
+//   tool_name: String           - Name of tool being called
+//   resource_name: String       - Name of resource being accessed
+//   prompt_name: String         - Name of prompt
+//   prompt_text: String         - Raw prompt text (for injection detection)
+//   response_size_mb: Long      - Response size in megabytes
+//   yara_threats: Set<String>   - Set of detected YARA threat names
+//   threat_count: Long          - Number of threats detected
+//   max_threat_severity: Long   - Highest severity (0=INFO, 4=CRITICAL)
+//   user_type: String           - "external" or "internal"
+//   monitoring_enabled: Bool    - Whether monitoring is active
+//   path: String                - File path
+//   hostname: String            - HTTP hostname
+//   ip_address: String          - IP address (for SSRF detection)
+//   scheme: String              - HTTP scheme
+//   port: Long                  - Port number
+//
+// PALISADE:
+//   environment: String                    - "production", "development", "research"
+//   artifact_format: String                - "pickle", "safetensors", "gguf", "onnx"
+//   artifact_signed: Bool                  - Whether artifact has signature
+//   severity: String                       - "CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"
+//   finding_type: String                   - Type of security finding
+//   provenance_signer: String              - Who signed ("unknown", "unsigned", or name)
+//   pickle_exec_path_detected: Bool        - RCE path found in pickle
+//   metadata_malicious_pattern: Bool       - Malicious pattern in metadata
+//   tokenizer_added_tokens_count: Long     - Number of added tokens
+//   safetensors_integrity_violation: Bool  - Safetensors integrity failed
+//   gguf_suspicious_metadata: Bool         - Suspicious GGUF metadata
+//   adapter_base_digest_mismatch: Bool     - LoRA adapter digest mismatch
+//   metadata_cosai_level_numeric: Long     - CoSAI maturity level (0-5)
+`;

package/src/types.ts

@@ -0,0 +1,15 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schema/highflame.cedarschema
+//
+// Browser-safe exports - no WASM dependency.
+// Use this entry point in browser environments:
+//   import { EntityType, PolicyBuilder } from '@highflame/policy/types';
+
+// Generated types - work in browser and Node.js
+export * from './entities.gen.js';
+export * from './actions.gen.js';
+export * from './context.gen.js';
+export * from './schema.gen.js';
+
+// PolicyBuilder - works in browser (no WASM dependency)
+export * from './builder.js';