@highflame/policy 1.1.3

package/src/builder.ts

@@ -0,0 +1,478 @@
+/**
+ * PolicyBuilder - Type-safe Cedar policy construction for Highflame.
+ *
+ * This builder ensures that policies created from the UI are always valid
+ * by construction. It uses the generated types from the Cedar schema to
+ * provide compile-time safety and autocomplete support.
+ *
+ * Example usage:
+ * ```typescript
+ * const policy = PolicyBuilder.permit()
+ *   .principal(EntityType.User, "user-123")
+ *   .action(ActionType.ReadFile)
+ *   .resource(EntityType.FilePath, "/data/reports")
+ *   .when("context.environment == \"production\"")
+ *   .build();
+ *
+ * // Get Cedar policy text
+ * const cedarText = policy.toCedar();
+ *
+ * // Get JSON representation (for storage/editing)
+ * const policyJson = policy.toJSON();
+ * ```
+ */
+
+import { EntityType, EntityUID } from './entities.gen.js';
+import { ActionType } from './actions.gen.js';
+import { ContextKey } from './context.gen.js';
+
+/**
+ * Policy effect - permit or forbid
+ */
+export type PolicyEffect = 'permit' | 'forbid';
+
+/**
+ * Condition operator types
+ */
+export type ConditionOperator =
+    | 'eq'        // ==
+    | 'neq'       // !=
+    | 'lt'        // <
+    | 'lte'       // <=
+    | 'gt'        // >
+    | 'gte'       // >=
+    | 'contains'  // .contains()
+    | 'in'        // in
+    | 'like';     // like
+
+/**
+ * A single condition in a policy
+ */
+export interface PolicyCondition {
+    /** The context key or attribute path */
+    field: string;
+    /** The comparison operator */
+    operator: ConditionOperator;
+    /** The value to compare against */
+    value: string | number | boolean | string[];
+}
+
+/**
+ * JSON representation of a policy for storage and editing
+ */
+export interface PolicyJSON {
+    /** Unique identifier for this policy */
+    id?: string;
+    /** Human-readable name/description */
+    name?: string;
+    /** Policy effect */
+    effect: PolicyEffect;
+    /** Principal constraint */
+    principal: {
+        type: string;
+        id?: string;
+    } | null;
+    /** Action constraint */
+    action: string | string[];
+    /** Resource constraint */
+    resource: {
+        type: string;
+        id?: string;
+    } | null;
+    /** Conditions (when clause) */
+    conditions: PolicyCondition[];
+    /** Raw condition string (for advanced users) */
+    rawCondition?: string;
+}
+
+/**
+ * A built policy that can be converted to Cedar text or JSON
+ */
+export class Policy {
+    constructor(private readonly data: PolicyJSON) {}
+
+    /**
+     * Convert to Cedar policy text
+     */
+    toCedar(): string {
+        const lines: string[] = [];
+
+        // Policy annotation (comment with name)
+        if (this.data.name) {
+            lines.push(`// @name: ${this.data.name}`);
+        }
+        if (this.data.id) {
+            lines.push(`// @id: ${this.data.id}`);
+        }
+
+        // Effect and principal
+        let policyLine = `${this.data.effect} (`;
+
+        // Principal
+        if (this.data.principal) {
+            if (this.data.principal.id) {
+                policyLine += `\n    principal == ${this.data.principal.type}::\"${this.data.principal.id}\"`;
+            } else {
+                policyLine += `\n    principal is ${this.data.principal.type}`;
+            }
+        } else {
+            policyLine += `\n    principal`;
+        }
+
+        // Action
+        if (Array.isArray(this.data.action)) {
+            if (this.data.action.length === 1) {
+                policyLine += `,\n    action == Action::\"${this.data.action[0]}\"`;
+            } else {
+                const actions = this.data.action.map(a => `Action::\"${a}\"`).join(', ');
+                policyLine += `,\n    action in [${actions}]`;
+            }
+        } else {
+            policyLine += `,\n    action == Action::\"${this.data.action}\"`;
+        }
+
+        // Resource
+        if (this.data.resource) {
+            if (this.data.resource.id) {
+                policyLine += `,\n    resource == ${this.data.resource.type}::\"${this.data.resource.id}\"`;
+            } else {
+                policyLine += `,\n    resource is ${this.data.resource.type}`;
+            }
+        } else {
+            policyLine += `,\n    resource`;
+        }
+
+        policyLine += '\n)';
+        lines.push(policyLine);
+
+        // When clause
+        if (this.data.rawCondition) {
+            lines.push(`when { ${this.data.rawCondition} };`);
+        } else if (this.data.conditions.length > 0) {
+            const conditionStr = this.data.conditions
+                .map(c => this.conditionToCedar(c))
+                .join(' && ');
+            lines.push(`when { ${conditionStr} };`);
+        } else {
+            lines.push(';');
+        }
+
+        return lines.join('\n');
+    }
+
+    /**
+     * Convert a condition to Cedar syntax
+     */
+    private conditionToCedar(condition: PolicyCondition): string {
+        const { field, operator, value } = condition;
+        const valueStr = this.valueToString(value);
+
+        switch (operator) {
+            case 'eq':
+                return `context.${field} == ${valueStr}`;
+            case 'neq':
+                return `context.${field} != ${valueStr}`;
+            case 'lt':
+                return `context.${field} < ${valueStr}`;
+            case 'lte':
+                return `context.${field} <= ${valueStr}`;
+            case 'gt':
+                return `context.${field} > ${valueStr}`;
+            case 'gte':
+                return `context.${field} >= ${valueStr}`;
+            case 'contains':
+                return `context.${field}.contains(${valueStr})`;
+            case 'in':
+                if (Array.isArray(value)) {
+                    const items = value.map(v => `\"${v}\"`).join(', ');
+                    return `context.${field} in [${items}]`;
+                }
+                return `context.${field} in ${valueStr}`;
+            case 'like':
+                return `context.${field} like ${valueStr}`;
+            default:
+                return `context.${field} == ${valueStr}`;
+        }
+    }
+
+    /**
+     * Convert a value to Cedar string representation
+     */
+    private valueToString(value: string | number | boolean | string[]): string {
+        if (typeof value === 'string') {
+            return `\"${value}\"`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        if (Array.isArray(value)) {
+            return `[${value.map(v => `\"${v}\"`).join(', ')}]`;
+        }
+        return String(value);
+    }
+
+    /**
+     * Get JSON representation for storage
+     */
+    toJSON(): PolicyJSON {
+        return { ...this.data };
+    }
+
+    /**
+     * Get the policy ID
+     */
+    getId(): string | undefined {
+        return this.data.id;
+    }
+
+    /**
+     * Get the policy name
+     */
+    getName(): string | undefined {
+        return this.data.name;
+    }
+}
+
+/**
+ * Builder for constructing Cedar policies with type safety.
+ */
+export class PolicyBuilder {
+    private data: PolicyJSON = {
+        effect: 'permit',
+        principal: null,
+        action: '',
+        resource: null,
+        conditions: [],
+    };
+
+    private constructor(effect: PolicyEffect) {
+        this.data.effect = effect;
+    }
+
+    /**
+     * Start building a permit policy
+     */
+    static permit(): PolicyBuilder {
+        return new PolicyBuilder('permit');
+    }
+
+    /**
+     * Start building a forbid policy
+     */
+    static forbid(): PolicyBuilder {
+        return new PolicyBuilder('forbid');
+    }
+
+    /**
+     * Create a builder from existing JSON (for editing)
+     */
+    static fromJSON(json: PolicyJSON): PolicyBuilder {
+        const builder = new PolicyBuilder(json.effect);
+        builder.data = { ...json };
+        return builder;
+    }
+
+    /**
+     * Set policy ID
+     */
+    id(id: string): PolicyBuilder {
+        this.data.id = id;
+        return this;
+    }
+
+    /**
+     * Set policy name/description
+     */
+    name(name: string): PolicyBuilder {
+        this.data.name = name;
+        return this;
+    }
+
+    /**
+     * Set principal constraint by type only (any entity of this type)
+     */
+    principalType(type: EntityType | string): PolicyBuilder {
+        this.data.principal = { type };
+        return this;
+    }
+
+    /**
+     * Set principal constraint by type and ID (specific entity)
+     */
+    principal(type: EntityType | string, id: string): PolicyBuilder {
+        this.data.principal = { type, id };
+        return this;
+    }
+
+    /**
+     * Set principal from EntityUID
+     */
+    principalEntity(entity: EntityUID): PolicyBuilder {
+        this.data.principal = { type: entity.type, id: entity.id };
+        return this;
+    }
+
+    /**
+     * Set single action constraint
+     */
+    action(action: ActionType | string): PolicyBuilder {
+        this.data.action = action;
+        return this;
+    }
+
+    /**
+     * Set multiple action constraints (action in [list])
+     */
+    actions(actions: (ActionType | string)[]): PolicyBuilder {
+        this.data.action = actions;
+        return this;
+    }
+
+    /**
+     * Set resource constraint by type only (any entity of this type)
+     */
+    resourceType(type: EntityType | string): PolicyBuilder {
+        this.data.resource = { type };
+        return this;
+    }
+
+    /**
+     * Set resource constraint by type and ID (specific entity)
+     */
+    resource(type: EntityType | string, id: string): PolicyBuilder {
+        this.data.resource = { type, id };
+        return this;
+    }
+
+    /**
+     * Set resource from EntityUID
+     */
+    resourceEntity(entity: EntityUID): PolicyBuilder {
+        this.data.resource = { type: entity.type, id: entity.id };
+        return this;
+    }
+
+    /**
+     * Add a structured condition
+     */
+    when(field: ContextKey | string, operator: ConditionOperator, value: string | number | boolean | string[]): PolicyBuilder {
+        this.data.conditions.push({ field, operator, value });
+        return this;
+    }
+
+    /**
+     * Add a raw condition string (for advanced users)
+     */
+    whenRaw(condition: string): PolicyBuilder {
+        this.data.rawCondition = condition;
+        return this;
+    }
+
+    /**
+     * Clear all conditions
+     */
+    clearConditions(): PolicyBuilder {
+        this.data.conditions = [];
+        this.data.rawCondition = undefined;
+        return this;
+    }
+
+    /**
+     * Build the policy
+     */
+    build(): Policy {
+        // Validate required fields
+        if (!this.data.action || (Array.isArray(this.data.action) && this.data.action.length === 0)) {
+            throw new Error('Policy must have at least one action');
+        }
+
+        return new Policy({ ...this.data });
+    }
+
+    /**
+     * Get current state as JSON (for preview/debugging)
+     */
+    toJSON(): PolicyJSON {
+        return { ...this.data };
+    }
+}
+
+/**
+ * Parse Cedar policy text back to PolicyJSON (best effort)
+ * Note: This is a simplified parser for policies created by PolicyBuilder.
+ * Complex hand-written policies may not parse correctly.
+ */
+export function parseCedarPolicy(cedarText: string): PolicyJSON | null {
+    try {
+        const result: PolicyJSON = {
+            effect: 'permit',
+            principal: null,
+            action: '',
+            resource: null,
+            conditions: [],
+        };
+
+        // Extract name from annotation
+        const nameMatch = cedarText.match(/\/\/ @name: (.+)/);
+        if (nameMatch) {
+            result.name = nameMatch[1].trim();
+        }
+
+        // Extract id from annotation
+        const idMatch = cedarText.match(/\/\/ @id: (.+)/);
+        if (idMatch) {
+            result.id = idMatch[1].trim();
+        }
+
+        // Extract effect
+        if (cedarText.includes('forbid')) {
+            result.effect = 'forbid';
+        }
+
+        // Extract principal
+        const principalMatch = cedarText.match(/principal\s*==\s*(\w+)::"([^"]+)"/);
+        if (principalMatch) {
+            result.principal = { type: principalMatch[1], id: principalMatch[2] };
+        } else {
+            const principalTypeMatch = cedarText.match(/principal\s+is\s+(\w+)/);
+            if (principalTypeMatch) {
+                result.principal = { type: principalTypeMatch[1] };
+            }
+        }
+
+        // Extract action(s)
+        const actionMatch = cedarText.match(/action\s*==\s*Action::"([^"]+)"/);
+        if (actionMatch) {
+            result.action = actionMatch[1];
+        } else {
+            const actionsMatch = cedarText.match(/action\s+in\s+\[([^\]]+)\]/);
+            if (actionsMatch) {
+                const actions = actionsMatch[1].match(/Action::"([^"]+)"/g);
+                if (actions) {
+                    result.action = actions.map(a => a.replace(/Action::"([^"]+)"/, '$1'));
+                }
+            }
+        }
+
+        // Extract resource
+        const resourceMatch = cedarText.match(/resource\s*==\s*(\w+)::"([^"]+)"/);
+        if (resourceMatch) {
+            result.resource = { type: resourceMatch[1], id: resourceMatch[2] };
+        } else {
+            const resourceTypeMatch = cedarText.match(/resource\s+is\s+(\w+)/);
+            if (resourceTypeMatch) {
+                result.resource = { type: resourceTypeMatch[1] };
+            }
+        }
+
+        // Extract when clause (as raw condition)
+        const whenMatch = cedarText.match(/when\s*\{([^}]+)\}/);
+        if (whenMatch) {
+            result.rawCondition = whenMatch[1].trim();
+        }
+
+        return result;
+    } catch {
+        return null;
+    }
+}

package/src/context.gen.ts

@@ -0,0 +1,107 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schema/context.yaml
+
+/**
+ * Context attribute keys for Cedar policy evaluation.
+ */
+export const ContextKey = {
+    // Guardrails/Core context attributes
+    /** Name of tool being called */
+    ToolName: 'tool_name',
+    /** Name of resource being accessed */
+    ResourceName: 'resource_name',
+    /** Name of prompt */
+    PromptName: 'prompt_name',
+    /** Raw prompt text */
+    PromptText: 'prompt_text',
+    /** Response size in megabytes */
+    ResponseSizeMb: 'response_size_mb',
+    /** Set of detected YARA threat names */
+    YaraThreats: 'yara_threats',
+    /** Number of threats detected */
+    ThreatCount: 'threat_count',
+    /** Highest severity (0-4) */
+    MaxThreatSeverity: 'max_threat_severity',
+    /** User type: external or internal */
+    UserType: 'user_type',
+    /** Whether monitoring is active */
+    MonitoringEnabled: 'monitoring_enabled',
+    /** File path */
+    Path: 'path',
+    /** HTTP hostname */
+    Hostname: 'hostname',
+    /** IP address */
+    IpAddress: 'ip_address',
+    /** Whether the IP is private/loopback (set by application layer) */
+    IsPrivateIp: 'is_private_ip',
+    /** HTTP scheme */
+    Scheme: 'scheme',
+    /** Port number */
+    Port: 'port',
+
+    // Palisade context attributes
+    /** Environment: production, development, research */
+    Environment: 'environment',
+    /** Format: pickle, safetensors, gguf, onnx */
+    ArtifactFormat: 'artifact_format',
+    /** Whether artifact has signature */
+    ArtifactSigned: 'artifact_signed',
+    /** Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO */
+    Severity: 'severity',
+    /** Type of security finding */
+    FindingType: 'finding_type',
+    /** Who signed the artifact */
+    ProvenanceSigner: 'provenance_signer',
+    /** RCE path found in pickle */
+    PickleExecPathDetected: 'pickle_exec_path_detected',
+    /** Malicious pattern in metadata */
+    MetadataMaliciousPattern: 'metadata_malicious_pattern',
+    /** Number of added tokens */
+    TokenizerAddedTokensCount: 'tokenizer_added_tokens_count',
+    /** Safetensors integrity failed */
+    SafetensorsIntegrityViolation: 'safetensors_integrity_violation',
+    /** Suspicious GGUF metadata */
+    GgufSuspiciousMetadata: 'gguf_suspicious_metadata',
+    /** LoRA adapter digest mismatch */
+    AdapterBaseDigestMismatch: 'adapter_base_digest_mismatch',
+    /** CoSAI maturity level (0-5) */
+    MetadataCosaiLevelNumeric: 'metadata_cosai_level_numeric',
+
+    // Overwatch context attributes
+    /** IDE source: cursor, claudecode, vscode, geminicli */
+    Source: 'source',
+    /** Hook event type: beforeShellExecution, PreToolUse, etc. */
+    Event: 'event',
+    /** The prompt/request content being evaluated */
+    Content: 'content',
+    /** User's email address (or 'anonymous') */
+    UserEmail: 'user_email',
+    /** Custom principal ID for policy evaluation */
+    CedarPrincipal: 'cedar_principal',
+    /** MCP server name: filesystem, playwright, etc. */
+    ServerName: 'server_name',
+    /** Whether the path is within the workspace */
+    IsWithinWorkspace: 'is_within_workspace',
+    /** Response content from tool execution */
+    ResponseContent: 'response_content',
+    /** Highest severity level: critical, high, medium, low */
+    HighestSeverity: 'highest_severity',
+    /** Array of threat types detected */
+    ThreatTypes: 'threat_types',
+    /** Array of threat categories found */
+    ThreatCategories: 'threat_categories',
+    /** Whether secrets were detected in the content */
+    ContainsSecrets: 'contains_secrets',
+    /** Number of concurrent calls */
+    ConcurrentCalls: 'concurrent_calls',
+    /** Request rate per minute */
+    RequestsPerMinute: 'requests_per_minute',
+    /** User trust level: high, medium, low */
+    UserTrustLevel: 'user_trust_level',
+    /** Whether alerting is enabled for this request */
+    AlertEnabled: 'alert_enabled',
+    /** Type of security scan being performed */
+    ScanType: 'scan_type',
+} as const;
+
+export type ContextKey = (typeof ContextKey)[keyof typeof ContextKey];