@highflame/policy 2.0.7 → 2.0.9

package/src/engine.ts

@@ -1,497 +0,0 @@
-/**
- * Highflame Policy Engine - TypeScript Wrapper
- * Wraps @cedar-policy/cedar-wasm with Highflame-specific types
- */
-
-import * as fs from "node:fs";
-import * as cedar from "@cedar-policy/cedar-wasm/nodejs";
-import { EntityType, EntityUID, Entity } from "./entities.gen.js";
-import { ActionType } from "./actions.gen.js";
-
-// =============================================================================
-// INPUT VALIDATION LIMITS (consistent across all language SDKs)
-// =============================================================================
-
-/**
- * Default limits for input validation.
- * These are consistent across Go, TypeScript, and Python SDKs.
- */
-export const DEFAULT_LIMITS = {
-  /** Maximum number of keys in a context map */
-  maxContextKeys: 100,
-  /** Maximum length of any string value (1MB) */
-  maxStringLength: 1_000_000,
-  /** Maximum nesting depth for objects/arrays */
-  maxNestingDepth: 10,
-  /** Maximum total context size in bytes (10MB) */
-  maxContextSizeBytes: 10_000_000,
-} as const;
-
-export interface InputLimits {
-  maxContextKeys?: number;
-  maxStringLength?: number;
-  maxNestingDepth?: number;
-  maxContextSizeBytes?: number;
-}
-
-export interface EngineOptions {
-  /** Cedar schema string (optional - can also use loadSchema() method) */
-  schema?: string;
-  /** Custom input validation limits */
-  limits?: InputLimits;
-  /** Skip input validation (not recommended for production) */
-  skipValidation?: boolean;
-}
-
-/**
- * Error thrown when input validation fails.
- */
-export class InputValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "InputValidationError";
-  }
-}
-
-/**
- * Validate context input against configured limits.
- * @throws InputValidationError if validation fails
- */
-function validateContext(
-  context: Record<string, unknown> | undefined,
-  limits: Required<InputLimits>,
-  depth: number = 0
-): void {
-  if (!context) return;
-
-  // Check nesting depth
-  if (depth > limits.maxNestingDepth) {
-    throw new InputValidationError(
-      `Context nesting depth exceeds maximum of ${limits.maxNestingDepth}`
-    );
-  }
-
-  const keys = Object.keys(context);
-
-  // Check number of keys (only at top level)
-  if (depth === 0 && keys.length > limits.maxContextKeys) {
-    throw new InputValidationError(
-      `Context has ${keys.length} keys, exceeds maximum of ${limits.maxContextKeys}`
-    );
-  }
-
-  // Check total size (only at top level)
-  if (depth === 0) {
-    let contextStr: string;
-    try {
-      contextStr = JSON.stringify(context);
-    } catch (e) {
-      throw new InputValidationError(
-        `Context is invalid or too complex: ${e instanceof Error ? e.message : String(e)}`
-      );
-    }
-    if (contextStr.length > limits.maxContextSizeBytes) {
-      throw new InputValidationError(
-        `Context size (${contextStr.length} bytes) exceeds maximum of ${limits.maxContextSizeBytes} bytes`
-      );
-    }
-  }
-
-  // Validate each value
-  for (const value of Object.values(context)) {
-    validateValue(value, limits, depth);
-  }
-}
-
-function validateValue(
-  value: unknown,
-  limits: Required<InputLimits>,
-  depth: number
-): void {
-  if (value === null || value === undefined) return;
-
-  if (typeof value === "string") {
-    if (value.length > limits.maxStringLength) {
-      throw new InputValidationError(
-        `String value length (${value.length}) exceeds maximum of ${limits.maxStringLength}`
-      );
-    }
-    return;
-  }
-
-  if (Array.isArray(value)) {
-    if (depth + 1 > limits.maxNestingDepth) {
-      throw new InputValidationError(
-        `Array nesting depth exceeds maximum of ${limits.maxNestingDepth}`
-      );
-    }
-    for (const item of value) {
-      validateValue(item, limits, depth + 1);
-    }
-    return;
-  }
-
-  if (typeof value === "object") {
-    validateContext(value as Record<string, unknown>, limits, depth + 1);
-  }
-}
-
-export class Decision {
-  readonly effect: "Allow" | "Deny";
-  readonly determining_policies: string[];
-  readonly reason?: string;
-
-  constructor(effect: "Allow" | "Deny", determining_policies: string[], reason?: string) {
-    this.effect = effect;
-    this.determining_policies = determining_policies;
-    this.reason = reason;
-  }
-
-  isAllowed(): boolean {
-    return this.effect === "Allow";
-  }
-
-  isDenied(): boolean {
-    return this.effect === "Deny";
-  }
-}
-
-export interface EvaluateRequest {
-  principal: EntityUID;
-  /**
-   * Action to evaluate. Can be:
-   * - A generated ActionType value (e.g., ActionType.CallTool)
-   * - A namespaced action string (e.g., 'Overwatch::Action::"call_tool"')
-   */
-  action: ActionType | string;
-  resource: EntityUID;
-  context?: Record<string, unknown>;
-  entities?: Entity[];
-}
-
-/**
- * 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);
-}
-
-/**
- * Parse an action string into Cedar EntityUID format.
- * Handles both non-namespaced and namespaced actions:
- * - "call_tool" → { type: "Action", id: "call_tool" }
- * - "Overwatch::Action::\"call_tool\"" → { type: "Overwatch::Action", id: "call_tool" }
- * - "Overwatch::Action::call_tool" → { type: "Overwatch::Action", id: "call_tool" }
- */
-function parseActionString(action: string): cedar.EntityUidJson {
-  // Check if action contains namespace separator
-  if (!action.includes("::")) {
-    // Non-namespaced action
-    return { type: "Action", id: action };
-  }
-
-  // Namespaced action - find the last :: separator
-  const lastSeparator = action.lastIndexOf("::");
-  const actionType = action.substring(0, lastSeparator);
-  let actionId = action.substring(lastSeparator + 2);
-
-  // Remove surrounding quotes if present (e.g., "call_tool" → call_tool)
-  if (actionId.startsWith('"') && actionId.endsWith('"')) {
-    actionId = actionId.slice(1, -1);
-  }
-
-  return { type: actionType, id: actionId };
-}
-
-/**
- * Extract @id annotations from Cedar policy text and return a
- * Record<PolicyId, Policy> for cedar-wasm. This ensures that
- * determining_policies in evaluation results use the @id values
- * instead of positional IDs (policy0, policy1...).
- *
- * Falls back to the raw string when no @id annotations are found.
- */
-function extractPolicyIds(policyText: string): cedar.StaticPolicySet {
-  const parts = cedar.policySetTextToParts(policyText);
-  if (parts.type !== "success" || parts.policies.length === 0) {
-    return policyText;
-  }
-
-  const policyMap: Record<string, string> = {};
-  let hasAnnotationIds = false;
-
-  for (let i = 0; i < parts.policies.length; i++) {
-    const policy = parts.policies[i];
-    const idMatch = policy.match(/@id\("([^"]+)"\)/);
-    if (idMatch) {
-      policyMap[idMatch[1]] = policy;
-      hasAnnotationIds = true;
-    } else {
-      policyMap[`policy${i}`] = policy;
-    }
-  }
-
-  return hasAnnotationIds ? policyMap : policyText;
-}
-
-/**
- * PolicyEngine wraps cedar-wasm with Highflame schema types.
- */
-export class PolicyEngine {
-  private policySet: cedar.StaticPolicySet = "";
-  private schema: string | undefined;
-  private options: EngineOptions;
-  private limits: Required<InputLimits>;
-
-  constructor(options?: EngineOptions) {
-    this.options = options ?? {};
-    this.schema = options?.schema;
-    this.limits = {
-      maxContextKeys: options?.limits?.maxContextKeys ?? DEFAULT_LIMITS.maxContextKeys,
-      maxStringLength: options?.limits?.maxStringLength ?? DEFAULT_LIMITS.maxStringLength,
-      maxNestingDepth: options?.limits?.maxNestingDepth ?? DEFAULT_LIMITS.maxNestingDepth,
-      maxContextSizeBytes: options?.limits?.maxContextSizeBytes ?? DEFAULT_LIMITS.maxContextSizeBytes,
-    };
-  }
-
-  /**
-   * Load Cedar policies from a file.
-   */
-  loadPoliciesFromFile(path: string): void {
-    const content = fs.readFileSync(path, "utf-8");
-    this.loadPolicy(content);
-  }
-
-  /**
-   * Load a single Cedar policy text string.
-   * Uses @id annotations as policy IDs when available.
-   */
-  loadPolicy(policy: string): void {
-    this.policySet = extractPolicyIds(policy);
-  }
-
-  /**
-   * Load multiple Cedar policy texts (concatenated with newlines).
-   * Uses @id annotations as policy IDs when available.
-   */
-  loadPolicies(policies: string[]): void {
-    this.policySet = extractPolicyIds(policies.join("\n"));
-  }
-
-  /**
-   * Load schema from a Cedar schema string.
-   */
-  loadSchema(schema: string): void {
-    this.schema = schema;
-  }
-
-  /**
-   * Load schema from a Cedar schema file.
-   */
-  loadSchemaFromFile(path: string): void {
-    const content = fs.readFileSync(path, "utf-8");
-    this.loadSchema(content);
-  }
-
-  /**
-   * Evaluate a policy request and return a decision.
-   * @throws InputValidationError if context validation fails
-   */
-  evaluate(req: EvaluateRequest): Decision {
-    // Validate input unless explicitly skipped
-    if (!this.options.skipValidation) {
-      validateContext(req.context, this.limits);
-    }
-
-    // Build EntityUIDs in Cedar JSON format
-    const principal: cedar.EntityUidJson = {
-      type: req.principal.type,
-      id: req.principal.id,
-    };
-    const action: cedar.EntityUidJson = parseActionString(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);
-      }
-    }
-
-    // Convert entities to Cedar JSON format
-    const entities = (req.entities || []).map(e => ({
-      uid: e.uid,
-      attrs: e.attrs ? Object.fromEntries(
-        Object.entries(e.attrs).map(([k, v]) => [k, toCedarValue(v)])
-      ) : {},
-      parents: e.parents || [],
-    }));
-
-    // Build the authorization call
-    const call: cedar.AuthorizationCall = {
-      principal,
-      action,
-      resource,
-      context,
-      policies: { staticPolicies: this.policySet },
-      entities,
-    };
-
-    // Add schema if available
-    if (this.schema) {
-      call.schema = this.schema;
-    }
-
-    const result = cedar.isAuthorized(call);
-
-    if (result.type === "failure") {
-      return new Decision(
-        "Deny",
-        [],
-        result.errors.map(e => e.message).join("; "),
-      );
-    }
-
-    return new Decision(
-      result.response.decision === "allow" ? "Allow" : "Deny",
-      result.response.diagnostics.reason,
-      result.response.diagnostics.errors.length > 0
-        ? result.response.diagnostics.errors.map(e => e.error.message).join("; ")
-        : undefined,
-    );
-  }
-
-  /**
-   * Convenience method for simple evaluations.
-   * @throws InputValidationError if context validation fails
-   */
-  evaluateSimple(
-    principalType: EntityType,
-    principalId: string,
-    action: ActionType | string,
-    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[] {
-    if (!this.schema) {
-      throw new Error("Schema is required for validation. Provide schema via constructor options or loadSchema().");
-    }
-
-    const result = cedar.validate({
-      validationSettings: { mode: "strict" },
-      schema: this.schema,
-      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 a Cedar schema.
-   * @param schema Cedar schema string (required)
-   */
-  constructor(schema: string) {
-    this.schema = 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 a schema.
- * Convenience function that doesn't require creating a validator instance.
- * @param schema Cedar schema string
- * @param policy Policy text to validate
- */
-export function validatePolicy(schema: string, policy: string): { valid: boolean; errors: string[] } {
-  const validator = new PolicyValidator(schema);
-  return validator.validate(policy);
-}
-
-// Re-export types
-export { EntityType, EntityUID, Entity, newEntityUID, newEntity } from "./entities.gen.js";
-export { ActionType, actionUID } from "./actions.gen.js";

package/src/entities.gen.ts

@@ -1,65 +0,0 @@
-// 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',
-    ExternalAPI: 'ExternalAPI',
-    FilePath: 'FilePath',
-    GitBranch: 'GitBranch',
-    HttpEndpoint: 'HttpEndpoint',
-    LlmPrompt: 'LlmPrompt',
-    Memory: 'Memory',
-    Model: 'Model',
-    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/entity-metadata-types.gen.ts

@@ -1,19 +0,0 @@
-// Code generated by highflame-policy-codegen. DO NOT EDIT.
-
-/**
- * Entity metadata for a service, extracted from Cedar schema appliesTo blocks.
- * Used by Studio UI to populate dropdowns in policy editor.
- */
-export interface ServiceEntityMetadata {
-  readonly principals: readonly string[];
-  readonly resources: readonly string[];
-  readonly actions: readonly string[];
-}
-
-/**
- * Entity metadata for a specific action.
- */
-export interface ActionEntityMetadata {
-  readonly principals: readonly string[];
-  readonly resources: readonly string[];
-}