@highflame/policy 2.0.10 → 2.1.0

package/_schemas/guardrails/templates/templates.json

@@ -0,0 +1,213 @@
+{
+  "service": "guardrails",
+  "version": "1.0.0",
+  "description": "Guardrails policy templates for LLM application security",
+  "categories": [
+    {
+      "id": "security",
+      "name": "Security",
+      "description": "Detect and block prompt injection, jailbreak attempts, and credential leakage"
+    },
+    {
+      "id": "privacy",
+      "name": "Privacy",
+      "description": "Detect and block personally identifiable information (PII) in prompts and responses"
+    },
+    {
+      "id": "trust_safety",
+      "name": "Trust & Safety",
+      "description": "Detect and block toxic, violent, hateful, sexual, or profane content"
+    },
+    {
+      "id": "agentic_security",
+      "name": "Agentic Security",
+      "description": "Detect tool abuse, data exfiltration patterns, infinite loops, and budget violations"
+    },
+    {
+      "id": "organization",
+      "name": "Organization",
+      "description": "Organization-wide baselines and default permit/deny policies"
+    }
+  ],
+  "defaults": [
+    {
+      "id": "baseline-default",
+      "name": "Baseline Permit",
+      "description": "Permits all actions by default — threat-specific forbid policies override this when threats are detected",
+      "category": "organization",
+      "file": "defaults/baseline.cedar",
+      "severity": "low",
+      "tags": ["baseline", "permit-default", "organization"],
+      "is_active": true
+    },
+    {
+      "id": "secrets-default",
+      "name": "Secrets Detection",
+      "description": "Block content containing API keys, tokens, credentials, or other secrets",
+      "category": "security",
+      "file": "defaults/secrets.cedar",
+      "severity": "critical",
+      "tags": ["secrets", "api-keys", "credentials", "data-leak"],
+      "is_active": true
+    },
+    {
+      "id": "injection-default",
+      "name": "Injection & Jailbreak Detection",
+      "description": "Block prompt injection, jailbreak attempts, and command injection using ML confidence scores",
+      "category": "security",
+      "file": "defaults/injection.cedar",
+      "severity": "high",
+      "tags": ["injection", "jailbreak", "security"],
+      "is_active": true
+    },
+    {
+      "id": "pii-default",
+      "name": "PII Detection",
+      "description": "Block content containing PII such as SSN, credit cards, or passport numbers in outputs",
+      "category": "privacy",
+      "file": "defaults/pii.cedar",
+      "severity": "high",
+      "tags": ["pii", "privacy", "data-protection"],
+      "is_active": true
+    },
+    {
+      "id": "toxicity-default",
+      "name": "Toxicity & Content Moderation",
+      "description": "Block toxic, violent, hateful, sexual, and profane content based on classifier scores",
+      "category": "trust_safety",
+      "file": "defaults/toxicity.cedar",
+      "severity": "critical",
+      "tags": ["toxicity", "trust-safety", "content-moderation"],
+      "is_active": true
+    },
+    {
+      "id": "tool-risk-default",
+      "name": "Tool Risk",
+      "description": "Block dangerous tool calls, shell execution, and sensitive tool usage based on risk scoring",
+      "category": "agentic_security",
+      "file": "defaults/tool_risk.cedar",
+      "severity": "critical",
+      "tags": ["tools", "agentic", "security"],
+      "is_active": true
+    },
+    {
+      "id": "agentic-safety-default",
+      "name": "Agentic Safety",
+      "description": "Block tool call loops, data exfiltration patterns, high-risk sequences, and budget violations",
+      "category": "agentic_security",
+      "file": "defaults/agentic_safety.cedar",
+      "severity": "high",
+      "tags": ["agentic", "safety", "loops", "exfiltration", "budget"],
+      "is_active": true
+    }
+  ],
+  "templates": [
+    {
+      "id": "mcp-tool-permissions",
+      "name": "MCP Tool Permissions",
+      "description": "Per-tool access control for MCP servers — allow specific tools while denying others, exclude servers org-wide, block unverified sources",
+      "category": "agentic_security",
+      "file": "mcp_tool_permissions.cedar",
+      "severity": "high",
+      "tags": ["mcp", "tools", "least-privilege", "per-server", "exclusion"]
+    },
+    {
+      "id": "chat-assistant-security",
+      "name": "Chat Assistant — Security",
+      "description": "Aggressive injection and jailbreak defense for customer-facing chatbots with lower thresholds",
+      "category": "security",
+      "file": "profiles/chat_assistant/security.cedar",
+      "severity": "high",
+      "tags": ["profile", "chat-assistant", "injection", "jailbreak", "security"]
+    },
+    {
+      "id": "chat-assistant-privacy",
+      "name": "Chat Assistant — Privacy",
+      "description": "Block PII in both user inputs and assistant outputs for chat applications",
+      "category": "privacy",
+      "file": "profiles/chat_assistant/privacy.cedar",
+      "severity": "high",
+      "tags": ["profile", "chat-assistant", "pii", "privacy"]
+    },
+    {
+      "id": "chat-assistant-trust-safety",
+      "name": "Chat Assistant — Trust & Safety",
+      "description": "Strict content moderation with lower toxicity thresholds and topic restrictions for public-facing chat",
+      "category": "trust_safety",
+      "file": "profiles/chat_assistant/trust_safety.cedar",
+      "severity": "critical",
+      "tags": ["profile", "chat-assistant", "toxicity", "trust-safety", "topics"]
+    },
+    {
+      "id": "code-agent-agentic-security",
+      "name": "Code Agent — Agentic Security",
+      "description": "Tool risk controls, shell blocking, loop detection, exfiltration prevention, and budget enforcement for coding assistants",
+      "category": "agentic_security",
+      "file": "profiles/code_agent/agentic_security.cedar",
+      "severity": "high",
+      "tags": ["profile", "code-agent", "tools", "agentic", "exfiltration", "budget"]
+    },
+    {
+      "id": "code-agent-security",
+      "name": "Code Agent — Security",
+      "description": "Prevent code agents from writing detected secrets to output files",
+      "category": "security",
+      "file": "profiles/code_agent/security.cedar",
+      "severity": "critical",
+      "tags": ["profile", "code-agent", "secrets", "security"]
+    },
+    {
+      "id": "data-pipeline-privacy",
+      "name": "Data Pipeline — Privacy",
+      "description": "Strict PII protection with zero-tolerance for sensitive PII types in data pipelines",
+      "category": "privacy",
+      "file": "profiles/data_pipeline/privacy.cedar",
+      "severity": "critical",
+      "tags": ["profile", "data-pipeline", "pii", "privacy", "compliance"]
+    },
+    {
+      "id": "data-pipeline-security",
+      "name": "Data Pipeline — Security",
+      "description": "Strict secrets detection and lower injection thresholds for RAG and data processing pipelines",
+      "category": "security",
+      "file": "profiles/data_pipeline/security.cedar",
+      "severity": "critical",
+      "tags": ["profile", "data-pipeline", "secrets", "injection", "security"]
+    },
+    {
+      "id": "data-pipeline-agentic-security",
+      "name": "Data Pipeline — Agentic Security",
+      "description": "Exfiltration prevention and tool risk controls for data processing pipelines",
+      "category": "agentic_security",
+      "file": "profiles/data_pipeline/agentic_security.cedar",
+      "severity": "critical",
+      "tags": ["profile", "data-pipeline", "exfiltration", "tools"]
+    }
+  ],
+  "profiles": [
+    {
+      "id": "chat-assistant",
+      "name": "Chat Assistant",
+      "description": "Optimized for customer-facing chatbots — strict toxicity, PII blocking, aggressive injection defense, topic restrictions",
+      "severity": "high",
+      "tags": ["chat-assistant", "toxicity", "pii", "injection"],
+      "template_ids": ["chat-assistant-security", "chat-assistant-privacy", "chat-assistant-trust-safety"]
+    },
+    {
+      "id": "code-agent",
+      "name": "Code Agent",
+      "description": "Optimized for coding assistants — tool risk controls, shell blocking, loop detection, exfiltration prevention, budget enforcement",
+      "severity": "high",
+      "tags": ["code-agent", "tools", "agentic", "exfiltration"],
+      "template_ids": ["code-agent-agentic-security", "code-agent-security"]
+    },
+    {
+      "id": "data-pipeline",
+      "name": "Data Pipeline",
+      "description": "Optimized for RAG and data processing — strict PII/secrets protection, exfiltration detection, pipeline injection defense",
+      "severity": "critical",
+      "tags": ["data-pipeline", "pii", "secrets", "exfiltration"],
+      "template_ids": ["data-pipeline-privacy", "data-pipeline-security", "data-pipeline-agentic-security"]
+    }
+  ]
+}

package/dist/builder.d.ts

@@ -53,16 +53,75 @@ export interface PolicyCondition {
     /** The value to compare against */
     value: string | number | boolean | string[];
 }
+/** context.field <op> value */
+export interface ConditionComparison {
+    kind: 'comparison';
+    field: string;
+    operator: ConditionOperator;
+    value: string | number | boolean | string[];
+}
+/** context.field.contains(value) */
+export interface ConditionContains {
+    kind: 'contains';
+    field: string;
+    value: string | number | boolean;
+}
+/** context.field like "pattern" */
+export interface ConditionLike {
+    kind: 'like';
+    field: string;
+    pattern: string;
+}
+/** context has field (existence check) */
+export interface ConditionHas {
+    kind: 'has';
+    field: string;
+}
+/** N-ary AND (flattened from binary && chains) */
+export interface ConditionAnd {
+    kind: 'and';
+    children: ConditionExpression[];
+}
+/** N-ary OR (flattened from binary || chains) */
+export interface ConditionOr {
+    kind: 'or';
+    children: ConditionExpression[];
+}
+/** Unary NOT */
+export interface ConditionNot {
+    kind: 'not';
+    child: ConditionExpression;
+}
+/** Fallback for expressions that cannot be decomposed */
+export interface ConditionRaw {
+    kind: 'raw';
+    text: string;
+}
+/**
+ * Recursive condition expression tree parsed from Cedar JSON AST.
+ * Used by Studio UI for visual condition block rendering and by
+ * explainDecision() for per-condition evaluation with actual values.
+ */
+export type ConditionExpression = ConditionComparison | ConditionContains | ConditionLike | ConditionHas | ConditionAnd | ConditionOr | ConditionNot | ConditionRaw;
 /**
  * Principal or resource entity constraint.
  * Used to specify type-only constraints (any entity of type) or
  * specific entity constraints (type + id).
+ *
+ * The `operator` field controls Cedar scope syntax:
+ * - `'eq'` (default): `resource == Type::"id"` — exact match
+ * - `'in'`: `resource in Type::"id"` — hierarchy match (descendants)
+ *
+ * Use `'in'` for container resource types (Account, Project, App) to match
+ * all descendant entities. Use `'eq'` for leaf types (Session, Tool).
  */
 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;
+    /** Scope operator: 'eq' for exact match (==), 'in' for hierarchy match (in). Default: 'eq' */
+    operator?: 'eq' | 'in';
 }
 /** Alias for PolicyEntity when used as principal constraint */
 export type PolicyPrincipal = PolicyEntity;
@@ -130,6 +189,8 @@ export interface PolicyRule {
     conditions: PolicyCondition[];
     /** Raw condition string (for advanced/complex conditions) */
     rawCondition?: string;
+    /** Recursive condition expression tree from Cedar JSON AST */
+    conditionExpression?: ConditionExpression;
     /** Whether this rule is active - NOT embedded in Cedar (runtime state) */
     enabled: boolean;
     /** Display/evaluation order - NOT embedded in Cedar (runtime state) */

package/dist/builder.js

@@ -293,7 +293,8 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
     if (principal) {
         const entityType = sanitizeIdentifier(principal.type, 'principal_type');
         if (principal.id) {
-            policyLine += `\n    principal == ${entityType}::"${escapeCedarString(principal.id)}"`;
+            const op = principal.operator === 'in' ? 'in' : '==';
+            policyLine += `\n    principal ${op} ${entityType}::"${escapeCedarString(principal.id)}"`;
         }
         else {
             policyLine += `\n    principal is ${entityType}`;
@@ -326,7 +327,8 @@ function generatePolicyBody(effect, principal, action, resource, conditions, raw
     if (resource) {
         const entityType = sanitizeIdentifier(resource.type, 'resource_type');
         if (resource.id) {
-            policyLine += `,\n    resource == ${entityType}::"${escapeCedarString(resource.id)}"`;
+            const op = resource.operator === 'in' ? 'in' : '==';
+            policyLine += `,\n    resource ${op} ${entityType}::"${escapeCedarString(resource.id)}"`;
         }
         else {
             policyLine += `,\n    resource is ${entityType}`;

package/dist/entities.gen.d.ts

@@ -2,7 +2,9 @@
  * Entity types defined in the Highflame Cedar schema.
  */
 export declare const EntityType: {
+    readonly Account: "Account";
     readonly Agent: "Agent";
+    readonly App: "App";
     readonly Artifact: "Artifact";
     readonly ExternalAPI: "ExternalAPI";
     readonly FilePath: "FilePath";
@@ -12,12 +14,14 @@ export declare const EntityType: {
     readonly Memory: "Memory";
     readonly Model: "Model";
     readonly Package: "Package";
+    readonly Project: "Project";
     readonly Repository: "Repository";
     readonly Resource: "Resource";
     readonly ResponseData: "ResponseData";
     readonly Scanner: "Scanner";
     readonly Server: "Server";
     readonly Service: "Service";
+    readonly Session: "Session";
     readonly Tool: "Tool";
     readonly User: "User";
 };

package/dist/entities.gen.js

@@ -4,7 +4,9 @@
  * Entity types defined in the Highflame Cedar schema.
  */
 export const EntityType = {
+    Account: 'Account',
     Agent: 'Agent',
+    App: 'App',
     Artifact: 'Artifact',
     ExternalAPI: 'ExternalAPI',
     FilePath: 'FilePath',
@@ -14,12 +16,14 @@ export const EntityType = {
     Memory: 'Memory',
     Model: 'Model',
     Package: 'Package',
+    Project: 'Project',
     Repository: 'Repository',
     Resource: 'Resource',
     ResponseData: 'ResponseData',
     Scanner: 'Scanner',
     Server: 'Server',
     Service: 'Service',
+    Session: 'Session',
     Tool: 'Tool',
     User: 'User',
 };

package/dist/explain.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ */
+import type { PolicyRule, PolicyEffect, ConditionOperator, ConditionExpression } from "./builder.js";
+/**
+ * Duck-typed decision input — accepts the Decision class from engine.ts
+ * without importing cedar-wasm (keeps this module browser-safe).
+ */
+export interface DecisionInput {
+    effect: "Allow" | "Deny";
+    determining_policies: Array<{
+        id: string;
+        annotations: Record<string, string>;
+    }>;
+}
+/**
+ * Result of explaining a policy decision.
+ */
+export interface ExplainedDecision {
+    /** The original decision effect */
+    effect: "Allow" | "Deny";
+    /** Enriched explanations for each determining policy */
+    explanations: PolicyExplanation[];
+    /** Determining policy IDs that had no matching rule in the provided rules array */
+    unmatched_policies: string[];
+}
+/**
+ * Explanation for a single determining policy.
+ */
+export interface PolicyExplanation {
+    /** Policy ID */
+    policy_id: string;
+    /** Policy effect (permit or forbid) */
+    effect: PolicyEffect;
+    /** Human-readable summary */
+    summary: string;
+    /** Recursive evaluated condition tree with actual values (from conditionExpression) */
+    evaluated_expression?: EvaluatedExpression;
+    /** Per-condition match results (flat, from structured conditions[]) */
+    condition_results: ConditionResult[];
+    /** Raw Cedar condition text if the policy uses rawCondition instead of structured conditions */
+    raw_condition?: string;
+}
+/**
+ * Result of evaluating a single condition against the request context.
+ */
+export interface ConditionResult {
+    /** Context field name */
+    field: string;
+    /** Comparison operator */
+    operator: ConditionOperator;
+    /** Expected value (threshold from the rule) */
+    expected: string | number | boolean | string[];
+    /** Actual value from the context (undefined if field was missing) */
+    actual?: unknown;
+    /** Whether this condition matched */
+    matched: boolean;
+}
+/** Evaluated comparison: context.field <op> value */
+export interface EvaluatedComparison {
+    kind: 'comparison';
+    field: string;
+    operator: ConditionOperator;
+    expected: string | number | boolean | string[];
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated contains: context.field.contains(value) */
+export interface EvaluatedContains {
+    kind: 'contains';
+    field: string;
+    expected: string | number | boolean;
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated like: context.field like "pattern" */
+export interface EvaluatedLike {
+    kind: 'like';
+    field: string;
+    pattern: string;
+    actual: unknown;
+    matched: boolean;
+}
+/** Evaluated has: context has field */
+export interface EvaluatedHas {
+    kind: 'has';
+    field: string;
+    matched: boolean;
+}
+/** Evaluated AND */
+export interface EvaluatedAnd {
+    kind: 'and';
+    children: EvaluatedExpression[];
+    matched: boolean;
+}
+/** Evaluated OR */
+export interface EvaluatedOr {
+    kind: 'or';
+    children: EvaluatedExpression[];
+    matched: boolean;
+}
+/** Evaluated NOT */
+export interface EvaluatedNot {
+    kind: 'not';
+    child: EvaluatedExpression;
+    matched: boolean;
+}
+/** Evaluated raw (cannot be decomposed) */
+export interface EvaluatedRaw {
+    kind: 'raw';
+    text: string;
+    matched: boolean;
+}
+/**
+ * Recursive evaluated condition expression tree.
+ * Produced by evaluateExpression() by walking ConditionExpression against context.
+ * Every node has a `matched` boolean; leaf nodes include `actual` values.
+ */
+export type EvaluatedExpression = EvaluatedComparison | EvaluatedContains | EvaluatedLike | EvaluatedHas | EvaluatedAnd | EvaluatedOr | EvaluatedNot | EvaluatedRaw;
+/**
+ * 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 declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>): ExplainedDecision;
+/**
+ * Recursively evaluate a ConditionExpression tree against a context map.
+ * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ */
+export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>): EvaluatedExpression;