@highflame/policy 2.0.9 → 2.1.0

package/dist/explain.js

@@ -0,0 +1,363 @@
+/**
+ * Policy Decision Explanation
+ *
+ * Provides structured explanations for Cedar policy decisions by matching
+ * determining policies against their structured conditions and the request context.
+ *
+ * Browser-safe — no WASM or Node.js dependencies.
+ */
+// =============================================================================
+// Main Function
+// =============================================================================
+/**
+ * Explain a policy decision by matching determining policies against their
+ * structured conditions and the request context.
+ *
+ * @param decision - The decision from PolicyEngine.evaluate()
+ * @param rules - The PolicyRule[] that were loaded (parsed or built)
+ * @param context - The context map that was passed to evaluate()
+ * @returns Structured explanation with per-condition match details
+ *
+ * @example
+ * ```typescript
+ * const decision = engine.evaluate(request);
+ * const explained = explainDecision(decision, rules, request.context);
+ *
+ * for (const explanation of explained.explanations) {
+ *   console.log(explanation.summary);
+ *   // "forbid process_prompt — threat_count (10) > 5"
+ * }
+ * ```
+ */
+export function explainDecision(decision, rules, context) {
+    // Build lookup map: annotations.id → PolicyRule
+    const ruleMap = new Map();
+    for (const rule of rules) {
+        const id = rule.annotations?.id;
+        if (id) {
+            ruleMap.set(id, rule);
+        }
+    }
+    const explanations = [];
+    const unmatchedPolicies = [];
+    for (const dp of decision.determining_policies) {
+        const rule = ruleMap.get(dp.id);
+        if (!rule) {
+            unmatchedPolicies.push(dp.id);
+            continue;
+        }
+        // Recursive condition evaluation
+        let evaluatedExpression;
+        if (rule.conditionExpression) {
+            evaluatedExpression = evaluateExpression(rule.conditionExpression, context);
+        }
+        // Populate condition_results: prefer leaf extraction from expression tree,
+        // fall back to flat conditions[] for backward compat with simple policies
+        let conditionResults;
+        if (evaluatedExpression) {
+            conditionResults = collectLeafResults(evaluatedExpression);
+        }
+        else {
+            const conditions = rule.conditions || [];
+            conditionResults = conditions.map(cond => {
+                const actual = context[cond.field];
+                const matched = evaluateCondition(cond.operator, actual, cond.value);
+                return { field: cond.field, operator: cond.operator, expected: cond.value, actual, matched };
+            });
+        }
+        // Surface rawCondition when there are no structured conditions and no expression tree
+        const rawCondition = conditionResults.length === 0 && !evaluatedExpression && rule.rawCondition
+            ? rule.rawCondition
+            : undefined;
+        const summary = evaluatedExpression
+            ? buildTreeSummary(rule, evaluatedExpression)
+            : buildSummary(rule, conditionResults, rawCondition);
+        explanations.push({
+            policy_id: dp.id,
+            effect: rule.effect ?? "forbid",
+            summary,
+            evaluated_expression: evaluatedExpression,
+            condition_results: conditionResults,
+            raw_condition: rawCondition,
+        });
+    }
+    return {
+        effect: decision.effect,
+        explanations,
+        unmatched_policies: unmatchedPolicies,
+    };
+}
+// =============================================================================
+// Recursive Expression Evaluation
+// =============================================================================
+/**
+ * Recursively evaluate a ConditionExpression tree against a context map.
+ * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ */
+export function evaluateExpression(expr, context) {
+    switch (expr.kind) {
+        case 'and': {
+            const children = expr.children.map(c => evaluateExpression(c, context));
+            return { kind: 'and', children, matched: children.every(c => c.matched) };
+        }
+        case 'or': {
+            const children = expr.children.map(c => evaluateExpression(c, context));
+            return { kind: 'or', children, matched: children.some(c => c.matched) };
+        }
+        case 'not': {
+            const child = evaluateExpression(expr.child, context);
+            return { kind: 'not', child, matched: !child.matched };
+        }
+        case 'has': {
+            const matched = expr.field in context && context[expr.field] !== undefined;
+            return { kind: 'has', field: expr.field, matched };
+        }
+        case 'comparison': {
+            const actual = context[expr.field];
+            const matched = evaluateCondition(expr.operator, actual, expr.value);
+            return { kind: 'comparison', field: expr.field, operator: expr.operator, expected: expr.value, actual, matched };
+        }
+        case 'contains': {
+            const actual = context[expr.field];
+            const matched = evaluateContains(actual, expr.value);
+            return { kind: 'contains', field: expr.field, expected: expr.value, actual, matched };
+        }
+        case 'like': {
+            const actual = context[expr.field];
+            const matched = evaluateLike(actual, expr.pattern);
+            return { kind: 'like', field: expr.field, pattern: expr.pattern, actual, matched };
+        }
+        case 'raw':
+            return { kind: 'raw', text: expr.text, matched: false };
+    }
+}
+// =============================================================================
+// Condition Evaluation
+// =============================================================================
+/**
+ * Evaluate a single condition against an actual context value.
+ * Returns false for missing values, type mismatches, or unsupported operators.
+ */
+function evaluateCondition(operator, actual, expected) {
+    if (actual === undefined || actual === null) {
+        return false;
+    }
+    switch (operator) {
+        case "eq":
+            return compareEqual(actual, expected);
+        case "neq":
+            return !compareEqual(actual, expected);
+        case "lt":
+            return compareNumeric(actual, expected, (a, b) => a < b);
+        case "lte":
+            return compareNumeric(actual, expected, (a, b) => a <= b);
+        case "gt":
+            return compareNumeric(actual, expected, (a, b) => a > b);
+        case "gte":
+            return compareNumeric(actual, expected, (a, b) => a >= b);
+        case "contains":
+            return evaluateContains(actual, expected);
+        case "in":
+            return evaluateIn(actual, expected);
+        case "like":
+            return evaluateLike(actual, expected);
+        default:
+            return false;
+    }
+}
+function compareEqual(actual, expected) {
+    if (typeof actual === "number" && typeof expected === "number") {
+        return actual === expected;
+    }
+    if (typeof actual === "string" && typeof expected === "string") {
+        return actual === expected;
+    }
+    if (typeof actual === "boolean" && typeof expected === "boolean") {
+        return actual === expected;
+    }
+    // Cross-type: try loose comparison for number/string
+    if (typeof actual === "number" && typeof expected === "string") {
+        return actual === Number(expected);
+    }
+    if (typeof actual === "string" && typeof expected === "number") {
+        return Number(actual) === expected;
+    }
+    return false;
+}
+function compareNumeric(actual, expected, comparator) {
+    const a = toNumber(actual);
+    const b = toNumber(expected);
+    if (a === null || b === null)
+        return false;
+    return comparator(a, b);
+}
+function toNumber(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return Number.isNaN(n) ? null : n;
+    }
+    return null;
+}
+function evaluateContains(actual, expected) {
+    // String contains — substring match
+    if (typeof actual === "string" && typeof expected === "string") {
+        return actual.includes(expected);
+    }
+    // Array contains — type-aware element match
+    if (Array.isArray(actual)) {
+        return actual.some((item) => compareEqual(item, expected));
+    }
+    return false;
+}
+function evaluateIn(actual, expected) {
+    if (Array.isArray(expected)) {
+        return expected.some((item) => compareEqual(actual, item));
+    }
+    return false;
+}
+function evaluateLike(actual, expected) {
+    if (typeof actual !== "string" || typeof expected !== "string") {
+        return false;
+    }
+    const regex = likePatternToRegex(expected);
+    return regex.test(actual);
+}
+/**
+ * Convert a Cedar `like` pattern to a JavaScript RegExp.
+ * Cedar `like` uses `*` as a wildcard (zero or more characters).
+ * `\*` is a literal asterisk.
+ */
+function likePatternToRegex(pattern) {
+    let regex = "^";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\" && i + 1 < pattern.length && pattern[i + 1] === "*") {
+            regex += "\\*";
+            i++; // skip the escaped *
+        }
+        else if (ch === "*") {
+            regex += ".*";
+        }
+        else {
+            // Escape regex special characters
+            regex += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    regex += "$";
+    return new RegExp(regex);
+}
+// =============================================================================
+// Summary Generation
+// =============================================================================
+function buildSummary(rule, conditionResults, rawCondition) {
+    const effect = rule.effect ?? "forbid";
+    const action = getActionLabel(rule);
+    if (rawCondition) {
+        return `${effect} ${action} — (raw condition: ${rawCondition})`;
+    }
+    if (conditionResults.length === 0) {
+        return `${effect} ${action} — (no conditions)`;
+    }
+    const parts = conditionResults.map((cr) => {
+        const op = OPERATOR_SYMBOLS[cr.operator] ?? cr.operator;
+        const actualStr = formatValue(cr.actual);
+        const expectedStr = formatValue(cr.expected);
+        return `${cr.field} (${actualStr}) ${op} ${expectedStr}`;
+    });
+    return `${effect} ${action} — ${parts.join(", ")}`;
+}
+/**
+ * Build a human-readable summary from an evaluated expression tree.
+ * Skips 'has' nodes (they're just null-guards) and focuses on leaf conditions.
+ */
+function buildTreeSummary(rule, evaluated) {
+    const effect = rule.effect ?? "forbid";
+    const action = getActionLabel(rule);
+    const parts = collectLeafSummaries(evaluated);
+    if (parts.length === 0) {
+        return `${effect} ${action} — (no conditions)`;
+    }
+    return `${effect} ${action} — ${parts.join(", ")}`;
+}
+/**
+ * Collect flat ConditionResult[] from leaf nodes in the evaluated expression tree.
+ * Skips 'has' (null-guards) and 'raw' (can't decompose) nodes.
+ * Recurses into and/or/not to reach all leaves.
+ */
+function collectLeafResults(expr) {
+    switch (expr.kind) {
+        case 'and':
+        case 'or':
+            return expr.children.flatMap(collectLeafResults);
+        case 'not':
+            return collectLeafResults(expr.child);
+        case 'has':
+        case 'raw':
+            return [];
+        case 'comparison':
+            return [{ field: expr.field, operator: expr.operator, expected: expr.expected, actual: expr.actual, matched: expr.matched }];
+        case 'contains':
+            return [{ field: expr.field, operator: 'contains', expected: expr.expected, actual: expr.actual, matched: expr.matched }];
+        case 'like':
+            return [{ field: expr.field, operator: 'like', expected: expr.pattern, actual: expr.actual, matched: expr.matched }];
+    }
+}
+/**
+ * Collect human-readable summaries from leaf nodes in the evaluated tree.
+ * Skips 'has' and 'raw' nodes; recurses into and/or/not.
+ */
+function collectLeafSummaries(expr) {
+    switch (expr.kind) {
+        case 'and':
+        case 'or':
+            return expr.children.flatMap(collectLeafSummaries);
+        case 'not':
+            return collectLeafSummaries(expr.child).map(s => `NOT (${s})`);
+        case 'has':
+            return []; // skip null-guards in summary
+        case 'comparison': {
+            const op = OPERATOR_SYMBOLS[expr.operator] ?? expr.operator;
+            return [`${expr.field}: ${formatValue(expr.actual)} ${op} ${formatValue(expr.expected)}`];
+        }
+        case 'contains':
+            return [`${expr.field}: ${formatValue(expr.actual)} contains ${formatValue(expr.expected)}`];
+        case 'like':
+            return [`${expr.field}: ${formatValue(expr.actual)} like ${formatValue(expr.pattern)}`];
+        case 'raw':
+            return [`(raw: ${expr.text})`];
+    }
+}
+function getActionLabel(rule) {
+    const action = rule.action;
+    if (!action)
+        return "*";
+    if (typeof action === "string") {
+        return action.replace(/^.*Action::"/, "").replace(/"$/, "");
+    }
+    if (Array.isArray(action) && action.length > 0) {
+        return action.map((a) => a.replace(/^.*Action::"/, "").replace(/"$/, "")).join(", ");
+    }
+    return "*";
+}
+function formatValue(value) {
+    if (value === undefined || value === null)
+        return "undefined";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+    return String(value);
+}
+const OPERATOR_SYMBOLS = {
+    eq: "==",
+    neq: "!=",
+    lt: "<",
+    lte: "<=",
+    gt: ">",
+    gte: ">=",
+    contains: "contains",
+    in: "in",
+    like: "like",
+};

package/dist/guardrails-context.gen.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Context attribute keys for Guardrails Guardrails (Shield) content security & policy enforcement for LLM applications.
+ *
+ * These constants correspond to the context attributes defined in the
+ * Guardrails Cedar schema and are used at policy evaluation time.
+ */
+export declare const GuardrailsContextKey: {
+    readonly BudgetExceeded: "budget_exceeded";
+    readonly BudgetRemainingPct: "budget_remaining_pct";
+    readonly ContainsInvisibleChars: "contains_invisible_chars";
+    readonly ContainsSecrets: "contains_secrets";
+    readonly ContentTopics: "content_topics";
+    readonly ContentType: "content_type";
+    readonly CrimeScore: "crime_score";
+    readonly DetectorCount: "detector_count";
+    readonly Direction: "direction";
+    readonly HateSpeechScore: "hate_speech_score";
+    readonly InjectionScore: "injection_score";
+    readonly InjectionType: "injection_type";
+    readonly InvisibleCharsScore: "invisible_chars_score";
+    readonly JailbreakScore: "jailbreak_score";
+    readonly LoopCount: "loop_count";
+    readonly LoopDetected: "loop_detected";
+    readonly LoopTool: "loop_tool";
+    readonly McpServer: "mcp_server";
+    readonly McpServerVerified: "mcp_server_verified";
+    readonly McpTool: "mcp_tool";
+    readonly PatternType: "pattern_type";
+    readonly PiiCount: "pii_count";
+    readonly PiiDetected: "pii_detected";
+    readonly PiiTypes: "pii_types";
+    readonly ProfanityScore: "profanity_score";
+    readonly RequestId: "request_id";
+    readonly SecretCount: "secret_count";
+    readonly SecretTypes: "secret_types";
+    readonly SequenceRisk: "sequence_risk";
+    readonly SexualScore: "sexual_score";
+    readonly SuspiciousPattern: "suspicious_pattern";
+    readonly Timestamp: "timestamp";
+    readonly ToolCategory: "tool_category";
+    readonly ToolIsBuiltin: "tool_is_builtin";
+    readonly ToolIsSensitive: "tool_is_sensitive";
+    readonly ToolName: "tool_name";
+    readonly ToolRiskScore: "tool_risk_score";
+    readonly TopicConfidence: "topic_confidence";
+    readonly ViolenceScore: "violence_score";
+    readonly WeaponsScore: "weapons_score";
+};
+export type GuardrailsContextKey = (typeof GuardrailsContextKey)[keyof typeof GuardrailsContextKey];

package/dist/guardrails-context.gen.js

@@ -0,0 +1,50 @@
+// Code generated by highflame-policy-codegen. DO NOT EDIT.
+// Source: schemas/guardrails/context.json
+/**
+ * Context attribute keys for Guardrails Guardrails (Shield) content security & policy enforcement for LLM applications.
+ *
+ * These constants correspond to the context attributes defined in the
+ * Guardrails Cedar schema and are used at policy evaluation time.
+ */
+export const GuardrailsContextKey = {
+    BudgetExceeded: 'budget_exceeded',
+    BudgetRemainingPct: 'budget_remaining_pct',
+    ContainsInvisibleChars: 'contains_invisible_chars',
+    ContainsSecrets: 'contains_secrets',
+    ContentTopics: 'content_topics',
+    ContentType: 'content_type',
+    CrimeScore: 'crime_score',
+    DetectorCount: 'detector_count',
+    Direction: 'direction',
+    HateSpeechScore: 'hate_speech_score',
+    InjectionScore: 'injection_score',
+    InjectionType: 'injection_type',
+    InvisibleCharsScore: 'invisible_chars_score',
+    JailbreakScore: 'jailbreak_score',
+    LoopCount: 'loop_count',
+    LoopDetected: 'loop_detected',
+    LoopTool: 'loop_tool',
+    McpServer: 'mcp_server',
+    McpServerVerified: 'mcp_server_verified',
+    McpTool: 'mcp_tool',
+    PatternType: 'pattern_type',
+    PiiCount: 'pii_count',
+    PiiDetected: 'pii_detected',
+    PiiTypes: 'pii_types',
+    ProfanityScore: 'profanity_score',
+    RequestId: 'request_id',
+    SecretCount: 'secret_count',
+    SecretTypes: 'secret_types',
+    SequenceRisk: 'sequence_risk',
+    SexualScore: 'sexual_score',
+    SuspiciousPattern: 'suspicious_pattern',
+    Timestamp: 'timestamp',
+    ToolCategory: 'tool_category',
+    ToolIsBuiltin: 'tool_is_builtin',
+    ToolIsSensitive: 'tool_is_sensitive',
+    ToolName: 'tool_name',
+    ToolRiskScore: 'tool_risk_score',
+    TopicConfidence: 'topic_confidence',
+    ViolenceScore: 'violence_score',
+    WeaponsScore: 'weapons_score',
+};

package/dist/guardrails-defaults.gen.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Guardrails policy category identifiers.
+ * Maps to UI tab names in Studio.
+ */
+export type GuardrailsCategory = 'security' | 'privacy' | 'trust_safety' | 'agentic_security' | 'organization';
+/**
+ * Category metadata for UI display.
+ */
+export interface GuardrailsCategoryInfo {
+    id: GuardrailsCategory;
+    name: string;
+    description: string;
+}
+/**
+ * A default policy that is auto-created for new projects.
+ */
+export interface GuardrailsDefaultPolicy {
+    /** Template identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description for UI display */
+    description: string;
+    /** Policy category */
+    category: GuardrailsCategory;
+    /** Cedar policy text (source of truth) */
+    cedarText: string;
+    /** Severity level */
+    severity: string;
+    /** Tags for filtering */
+    tags: string[];
+    /** Whether this default should be activated immediately */
+    isActive: boolean;
+}
+/**
+ * A policy template available for users to create from.
+ */
+export interface GuardrailsTemplate {
+    /** Template identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description for UI display */
+    description: string;
+    /** Policy category */
+    category: GuardrailsCategory;
+    /** Cedar policy text */
+    cedarText: string;
+    /** Severity level */
+    severity: string;
+    /** Tags for filtering */
+    tags: string[];
+}
+export declare const GUARDRAILS_CATEGORIES: GuardrailsCategoryInfo[];
+export declare const GUARDRAILS_DEFAULTS: GuardrailsDefaultPolicy[];
+export declare const GUARDRAILS_TEMPLATES: GuardrailsTemplate[];
+/** Raw templates.json metadata for the Guardrails service. */
+export declare const GUARDRAILS_TEMPLATES_JSON: string;
+export declare function getGuardrailsDefaultsByCategory(category: GuardrailsCategory): GuardrailsDefaultPolicy[];
+export declare function getGuardrailsTemplatesByCategory(category: GuardrailsCategory): GuardrailsTemplate[];
+export declare function getGuardrailsTemplateById(id: string): GuardrailsTemplate | undefined;