@highflame/policy 2.0.7 → 2.0.9

package/src/builder.ts

@@ -1,799 +0,0 @@
-/**
- * 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 (with proper @annotations)
- * const cedarText = policy.toCedar();
- *
- * // Get JSON representation (for storage/editing)
- * const policyJson = policy.toJSON();
- * ```
- *
- * Cedar Annotations:
- * Policies include proper Cedar annotations that are embedded in the policy text:
- * ```cedar
- * @id("rule-001")
- * @name("Block critical threats")
- * @severity("high")
- * permit(...) when {...};
- * ```
- */
-
-import { EntityType, EntityUID } from './entities.gen.js';
-import { ActionType } from './actions.gen.js';
-import {
-    type PolicyAnnotations,
-    type CustomAnnotations,
-    type PolicySeverity,
-    generateAnnotationLines,
-    generateRuleId,
-} from './annotations.js';
-
-// ============================================================================
-// Security: Input Validation and Escaping
-// ============================================================================
-
-/**
- * Valid identifier pattern for Cedar (alphanumeric, underscore, with optional namespace).
- */
-const VALID_IDENTIFIER_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*$/;
-
-/**
- * Pattern that matches potentially dangerous content in raw conditions.
- * Note: '}' is NOT blocked because raw conditions may contain valid Cedar
- * record literals or nested expressions. The ';' blocks when-clause escapes.
- */
-const DANGEROUS_PATTERN_REGEX = /;|\/\/|\/\*|\*\/|permit\s*\(|forbid\s*\(/;
-
-/**
- * Escape a string value for use in Cedar string literals.
- * This prevents injection attacks by escaping backslashes and double quotes.
- */
-function escapeCedarString(value: string): string {
-    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
-
-/**
- * Check if a string is a valid Cedar identifier.
- */
-function isValidIdentifier(s: string): boolean {
-    return VALID_IDENTIFIER_REGEX.test(s);
-}
-
-/**
- * Sanitize an identifier, replacing invalid characters with underscores.
- */
-function sanitizeIdentifier(s: string, context: string): string {
-    if (isValidIdentifier(s)) {
-        return s;
-    }
-    // Replace invalid characters with underscores
-    const sanitized = s.replace(/[^A-Za-z0-9_:]/g, '_');
-    if (sanitized === '' || !isValidIdentifier(sanitized)) {
-        return `invalid_${context}`;
-    }
-    return sanitized;
-}
-
-/**
- * Validate a raw condition string for potentially dangerous patterns.
- * Returns true if the condition is safe to use.
- */
-function isValidRawCondition(condition: string): boolean {
-    return !DANGEROUS_PATTERN_REGEX.test(condition);
-}
-
-/**
- * Format an action string for Cedar policy text.
- * Detects if action is already namespaced (contains 'Action::"') and preserves it,
- * otherwise wraps with Action::"...".
- * Escapes the action name to prevent injection attacks.
- */
-function formatAction(action: string): string {
-    if (action.includes('Action::"')) {
-        // Already namespaced - extract and escape the action name
-        const parts = action.split('Action::"');
-        if (parts.length === 2) {
-            const actionName = parts[1].replace(/"$/, '');
-            return `${parts[0]}Action::"${escapeCedarString(actionName)}"`;
-        }
-        return action;
-    }
-    // Non-namespaced, wrap with Action::"..."
-    return `Action::"${escapeCedarString(action)}"`;
-}
-
-/**
- * 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[];
-}
-
-/**
- * Principal or resource entity constraint.
- * Used to specify type-only constraints (any entity of type) or
- * specific entity constraints (type + id).
- */
-export interface PolicyEntity {
-    /** Entity type (e.g., "Agent", "Tool", "FilePath", "User") */
-    type: string;
-    /** Optional specific entity ID. If omitted, matches any entity of this type. */
-    id?: string;
-}
-
-/** Alias for PolicyEntity when used as principal constraint */
-export type PolicyPrincipal = PolicyEntity;
-
-/** Alias for PolicyEntity when used as resource constraint */
-export type PolicyResource = PolicyEntity;
-
-// Re-export PolicySeverity from annotations for backwards compatibility
-export type { PolicySeverity } from './annotations.js';
-
-/**
- * JSON representation of a policy for storage and editing.
- * This is the base interface used by PolicyBuilder (legacy format).
- *
- * @deprecated Use PolicyRule with annotations for new code.
- */
-export interface PolicyJSON {
-    /** Unique identifier for this policy */
-    id?: string;
-    /** Human-readable name/description */
-    name?: string;
-    /** Policy effect */
-    effect: PolicyEffect;
-    /** Principal constraint */
-    principal: PolicyEntity | null;
-    /** Action constraint - single action or array of actions */
-    action: string | string[];
-    /** Resource constraint */
-    resource: PolicyEntity | null;
-    /** Conditions (when clause) */
-    conditions: PolicyCondition[];
-    /** Raw condition string (for advanced users) */
-    rawCondition?: string;
-}
-
-/**
- * A policy rule with full Cedar annotation support.
- *
- * This is the canonical type used across all Highflame services:
- * - highflame-studio (UI)
- * - highflame-authz (Go backend)
- * - Any Python services
- *
- * Each PolicyRule maps 1:1 to a Cedar policy statement with proper annotations.
- *
- * Annotations are embedded in Cedar text:
- * ```cedar
- * @id("rule-001")
- * @name("Block critical threats")
- * @severity("high")
- * @tags("security,baseline")
- * @compliance("SOC2")
- * forbid(...) when {...};
- * ```
- */
-export interface PolicyRule {
-    /** Predefined annotations (embedded in Cedar text) */
-    annotations: PolicyAnnotations;
-    /** Custom user-defined annotations (embedded in Cedar text) */
-    customAnnotations?: CustomAnnotations;
-
-    /** Policy effect - permit or forbid */
-    effect: PolicyEffect;
-    /** Principal constraint */
-    principal: PolicyEntity | null;
-    /** Action constraint - single action or array of actions */
-    action: string | string[];
-    /** Resource constraint */
-    resource: PolicyEntity | null;
-    /** Structured conditions (when clause) */
-    conditions: PolicyCondition[];
-    /** Raw condition string (for advanced/complex conditions) */
-    rawCondition?: string;
-
-    /** Whether this rule is active - NOT embedded in Cedar (runtime state) */
-    enabled: boolean;
-    /** Display/evaluation order - NOT embedded in Cedar (runtime state) */
-    order: number;
-}
-
-/**
- * Legacy PolicyRule format for backwards compatibility.
- * Used when parsing policies that don't have the new annotations structure.
- *
- * @deprecated Use PolicyRule with annotations for new code.
- */
-export interface LegacyPolicyRule extends PolicyJSON {
-    enabled: boolean;
-    order: number;
-    description?: string;
-    severity?: PolicySeverity;
-    tags?: string[];
-}
-
-/**
- * Convert a legacy PolicyRule to the new annotations-based format.
- */
-export function convertLegacyRule(legacy: LegacyPolicyRule, index: number = 0): PolicyRule {
-    return {
-        annotations: {
-            id: legacy.id || generateRuleId(),
-            name: legacy.name || legacy.id || `Rule ${index + 1}`,
-            description: legacy.description,
-            severity: legacy.severity,
-            tags: legacy.tags,
-        },
-        effect: legacy.effect,
-        principal: legacy.principal,
-        action: legacy.action,
-        resource: legacy.resource,
-        conditions: legacy.conditions,
-        rawCondition: legacy.rawCondition,
-        enabled: legacy.enabled,
-        order: legacy.order,
-    };
-}
-
-/**
- * A built policy that can be converted to Cedar text or JSON.
- * This class is used by PolicyBuilder for the legacy API.
- *
- * For new code, use ruleToCedar() and rulesToCedar() functions with PolicyRule.
- */
-export class Policy {
-    constructor(private readonly data: PolicyJSON) {}
-
-    /**
-     * Convert to Cedar policy text.
-     * Uses proper Cedar @annotation syntax.
-     */
-    toCedar(): string {
-        const lines: string[] = [];
-
-        // Generate proper Cedar annotations
-        if (this.data.id || this.data.name) {
-            const annotations: PolicyAnnotations = {
-                id: this.data.id || generateRuleId(),
-                name: this.data.name || this.data.id || 'Unnamed Policy',
-            };
-            lines.push(...generateAnnotationLines(annotations));
-        }
-
-        // Generate policy body
-        lines.push(generatePolicyBody(
-            this.data.effect,
-            this.data.principal,
-            this.data.action,
-            this.data.resource,
-            this.data.conditions,
-            this.data.rawCondition
-        ));
-
-        return lines.join('\n');
-    }
-
-    /**
-     * 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;
-    }
-}
-
-// ============================================================================
-// Cedar Generation Functions
-// ============================================================================
-
-/**
- * Convert a condition to Cedar syntax.
- * Field names are sanitized to prevent injection attacks.
- */
-function conditionToCedar(condition: PolicyCondition): string {
-    const field = sanitizeIdentifier(condition.field, 'field');
-    const { operator, value } = condition;
-    const valueStr = 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 => `"${escapeCedarString(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.
- * String values are escaped to prevent injection attacks.
- */
-function valueToString(value: string | number | boolean | string[]): string {
-    if (typeof value === 'string') {
-        return `"${escapeCedarString(value)}"`;
-    }
-    if (typeof value === 'number' || typeof value === 'boolean') {
-        return String(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(v => `"${escapeCedarString(v)}"`).join(', ')}]`;
-    }
-    return String(value);
-}
-
-/**
- * Generate the Cedar policy body (permit/forbid statement).
- * All inputs are sanitized/escaped to prevent injection attacks.
- */
-function generatePolicyBody(
-    effect: PolicyEffect,
-    principal: PolicyEntity | null,
-    action: string | string[],
-    resource: PolicyEntity | null,
-    conditions: PolicyCondition[],
-    rawCondition?: string
-): string {
-    let policyLine = `${effect} (`;
-
-    // Principal
-    if (principal) {
-        const entityType = sanitizeIdentifier(principal.type, 'principal_type');
-        if (principal.id) {
-            policyLine += `\n    principal == ${entityType}::"${escapeCedarString(principal.id)}"`;
-        } else {
-            policyLine += `\n    principal is ${entityType}`;
-        }
-    } else {
-        policyLine += `\n    principal`;
-    }
-
-    // Action
-    if (Array.isArray(action)) {
-        const filtered = action.filter(a => a !== '*');
-        if (filtered.length === 0) {
-            policyLine += `,\n    action`;
-        } else if (filtered.length === 1) {
-            policyLine += `,\n    action == ${formatAction(filtered[0])}`;
-        } else {
-            const actions = filtered.map(a => formatAction(a)).join(', ');
-            policyLine += `,\n    action in [${actions}]`;
-        }
-    } else if (!action || action === '*') {
-        policyLine += `,\n    action`;
-    } else {
-        policyLine += `,\n    action == ${formatAction(action)}`;
-    }
-
-    // Resource
-    if (resource) {
-        const entityType = sanitizeIdentifier(resource.type, 'resource_type');
-        if (resource.id) {
-            policyLine += `,\n    resource == ${entityType}::"${escapeCedarString(resource.id)}"`;
-        } else {
-            policyLine += `,\n    resource is ${entityType}`;
-        }
-    } else {
-        policyLine += `,\n    resource`;
-    }
-
-    policyLine += '\n)';
-
-    // When clause
-    // SECURITY: rawCondition is validated to prevent injection attacks.
-    // If validation fails, fall back to structured conditions.
-    if (rawCondition) {
-        if (isValidRawCondition(rawCondition)) {
-            policyLine += `\nwhen { ${rawCondition} };`;
-        } else if (conditions.length > 0) {
-            // Fallback to structured conditions if rawCondition is rejected
-            const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
-            policyLine += `\nwhen { ${conditionStr} };`;
-        } else {
-            policyLine += ';';
-        }
-    } else if (conditions.length > 0) {
-        const conditionStr = conditions.map(c => conditionToCedar(c)).join(' && ');
-        policyLine += `\nwhen { ${conditionStr} };`;
-    } else {
-        policyLine += ';';
-    }
-
-    return policyLine;
-}
-
-/**
- * Convert a PolicyRule to Cedar policy text with proper annotations.
- *
- * @param rule - The PolicyRule to convert
- * @returns Cedar policy text string
- *
- * @example
- * ```typescript
- * const rule: PolicyRule = {
- *   annotations: { id: 'rule-001', name: 'Block threats', severity: 'high' },
- *   effect: 'forbid',
- *   principal: null,
- *   action: 'call_tool',
- *   resource: null,
- *   conditions: [{ field: 'threat_count', operator: 'gt', value: 0 }],
- *   enabled: true,
- *   order: 0,
- * };
- *
- * const cedar = ruleToCedar(rule);
- * // Output:
- * // @id("rule-001")
- * // @name("Block threats")
- * // @severity("high")
- * // forbid (
- * //     principal,
- * //     action == Action::"call_tool",
- * //     resource
- * // )
- * // when { context.threat_count > 0 };
- * ```
- */
-export function ruleToCedar(rule: PolicyRule): string {
-    const lines: string[] = [];
-
-    // Generate Cedar annotations
-    lines.push(...generateAnnotationLines(rule.annotations, rule.customAnnotations));
-
-    // Generate policy body
-    lines.push(generatePolicyBody(
-        rule.effect,
-        rule.principal,
-        rule.action,
-        rule.resource,
-        rule.conditions,
-        rule.rawCondition
-    ));
-
-    return lines.join('\n');
-}
-
-/**
- * Convert multiple PolicyRules to Cedar policy text.
- * Only enabled rules are included, sorted by order.
- *
- * @param rules - Array of PolicyRules to convert
- * @param includeDisabled - If true, include disabled rules as comments (default: false)
- * @returns Cedar policy text with all rules separated by blank lines
- *
- * @example
- * ```typescript
- * const rules: PolicyRule[] = [...];
- * const cedarText = rulesToCedar(rules);
- * ```
- */
-export function rulesToCedar(rules: PolicyRule[], includeDisabled: boolean = false): string {
-    const sortedRules = [...rules].sort((a, b) => a.order - b.order);
-
-    const cedarPolicies: string[] = [];
-    for (const rule of sortedRules) {
-        if (rule.enabled) {
-            cedarPolicies.push(ruleToCedar(rule));
-        } else if (includeDisabled) {
-            // Include disabled rules as comments
-            const cedarLines = ruleToCedar(rule).split('\n');
-            cedarPolicies.push(cedarLines.map(line => `// [DISABLED] ${line}`).join('\n'));
-        }
-    }
-
-    return cedarPolicies.join('\n\n');
-}
-
-/**
- * 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: 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;
-    }
-}