highflame 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,644 @@
+/**
+ * Generated types from spec/shield-v1.yaml — DO NOT EDIT.
+ *
+ * Regenerate: python codegen/generate.py --spec spec/shield-v1.yaml
+ */
+/** Type of content being evaluated. */
+type ContentType = "prompt" | "response" | "tool_call" | "file";
+/** Guard evaluation decision. */
+type Decision = "allow" | "deny";
+/** enforce: block on deny. monitor: allow + log. alert: allow + signal. */
+type Mode = "enforce" | "monitor" | "alert";
+/** Authenticated agent identity from token claims. */
+interface AgentIdentityTrace {
+    /** Agent identifier. */
+    agent_id: string;
+    /** Type of agent (e.g. claude, cursor, custom). */
+    agent_type: string;
+    /** Trust level (verified, unverified, etc.). */
+    trust_level: string;
+    /** Agent framework (e.g. Python SDK, Node SDK). */
+    framework?: string;
+    /** Publisher/organization. */
+    publisher?: string;
+    /** Authentication method: api_key or jwt. */
+    auth_method: string;
+}
+/** Specification of a context key emitted by a detector. */
+interface ContextKeySpec {
+    /** Context key name (e.g. injection_score). */
+    key: string;
+    /** Cedar type: long, bool, string, or set. */
+    type: string;
+    /** Human-readable description. */
+    description: string;
+    /** Value range (e.g. 0-100). */
+    range?: string;
+}
+/** Entity in the Cedar evaluation context. */
+interface EntityDebug {
+    /** Entity type. */
+    type: string;
+    /** Entity ID. */
+    id: string;
+    /** Parent entity UIDs. */
+    parents?: string[];
+}
+/** Resolved tenant identity. */
+interface TenantDebug {
+    account_id: string;
+    project_id: string;
+    application_id: string;
+}
+/** Cedar evaluation debug info (when debug=true). */
+interface DebugInfo {
+    /** Product namespace. */
+    product: string;
+    /** Cedar namespace (e.g. Guardrails). */
+    namespace: string;
+    /** Principal entity type. */
+    principal_type: string;
+    /** Principal entity ID. */
+    principal_id: string;
+    /** Cedar action. */
+    action: string;
+    /** Resource entity type. */
+    resource_type: string;
+    /** Resource entity ID. */
+    resource_id: string;
+    /** Entity hierarchy. */
+    entities: EntityDebug[];
+    /** Number of loaded policies. */
+    loaded_policy_count: number;
+    tenant: TenantDebug;
+}
+/** Summary of a loaded Cedar policy. */
+interface PolicySummary {
+    /** Database UUID. */
+    policy_id: string;
+    /** Human-readable name. */
+    policy_name: string;
+    /** Policy mode: enforce, monitor, or alert. */
+    mode: string;
+    /** Policy domain category. */
+    category?: string;
+    /** Cedar @id annotations from this policy. */
+    rule_ids: string[];
+}
+/** Response from GET /v1/debug/policies. */
+interface DebugPoliciesResponse {
+    /** Product namespace inspected. */
+    product: string;
+    /** Whether the evaluator has loaded policies. */
+    has_policies: boolean;
+    /** Number of distinct DB policies loaded. */
+    policy_count: number;
+    /** Loaded policies with metadata. */
+    policies: PolicySummary[];
+}
+/** File operation context. */
+interface FileContext {
+    /** File path. */
+    path: string;
+    /** File operation: read, write, delete, append, etc. */
+    operation: string;
+    /** File size in bytes. */
+    size?: number;
+    /** File MIME type. */
+    mime_type?: string;
+}
+/** MCP server interaction context. */
+interface MCPContext {
+    /** MCP server name. */
+    server_name: string;
+    /** MCP server URL. */
+    server_url?: string;
+    /** Transport protocol: sse, stdio, http. */
+    transport?: string;
+    /** Whether the server passed trust/signature verification. */
+    verified?: boolean;
+    /** Advertised MCP capabilities from server manifest. */
+    capabilities?: string[];
+}
+/** LLM model context (provider, temperature, token usage). */
+interface ModelContext {
+    /** LLM provider (e.g. openai, anthropic). */
+    provider?: string;
+    /** Model name (e.g. gpt-4, claude-3). */
+    model?: string;
+    /** Temperature setting. */
+    temperature?: number;
+    /** Tokens consumed so far in the session. */
+    tokens_used?: number;
+    /** Max token limit for the session. */
+    max_tokens?: number;
+}
+/** Tool call context for agentic evaluation. */
+interface ToolContext {
+    /** Tool name. */
+    name: string;
+    /** Whether the tool is built-in to the LLM or externally registered. */
+    is_builtin: boolean;
+    /** Tool arguments as a JSON object. */
+    arguments?: Record<string, unknown>;
+    /** MCP server ID (for externally-registered tools). */
+    server_id?: string;
+    /** Tool description from MCP manifest, for tool-poisoning analysis. */
+    description?: string;
+}
+/** Request body for POST /v1/detect. Detection only, no policy evaluation. */
+interface DetectRequest {
+    /** Content to analyze. */
+    content: string;
+    content_type: ContentType;
+    /** Specific detectors to run. Empty runs all enabled detectors. */
+    detectors?: string[];
+    /** Caller-provided metadata passed through to detectors. */
+    metadata?: Record<string, unknown>;
+    /** Reference material for context-aware detection. */
+    contexts?: string[];
+    /** Session ID for cross-turn state tracking. */
+    session_id?: string;
+    tool?: ToolContext;
+    model?: ModelContext;
+    file?: FileContext;
+    mcp?: MCPContext;
+}
+/** Result from a single detector execution. */
+interface DetectorResult {
+    /** Detector name (e.g. injection, secrets, toxicity). */
+    name: string;
+    /** Detector tier: fast, standard, or slow. */
+    tier: string;
+    /** Detector execution latency in milliseconds. */
+    latency_ms: number;
+    /** Emitted context attributes (e.g. injection_score, contains_secrets). */
+    context: Record<string, unknown>;
+    /** Detector status: healthy, degraded, error, or timeout. */
+    status: string;
+    /** Error message (when status is error or timeout). */
+    error?: string;
+}
+/** Response from POST /v1/detect. */
+interface DetectResponse {
+    /** Per-detector results. */
+    detectors: DetectorResult[];
+    /** Merged context from all detectors. */
+    context: Record<string, unknown>;
+    /** Total detection latency in milliseconds. */
+    latency_ms: number;
+    /** Detector tiers that ran. */
+    tiers_evaluated: string[];
+}
+/** Metadata about an available detector. */
+interface DetectorInfo {
+    /** Detector name. */
+    name: string;
+    /** Detector version. */
+    version: string;
+    /** Detector tier: fast, standard, or slow. */
+    tier: string;
+    /** Keys this detector may emit. */
+    context_keys: ContextKeySpec[];
+    /** Detector status: healthy, degraded, or disabled. */
+    status: string;
+    /** Human-readable display name. */
+    display_name?: string;
+    /** What the detector detects. */
+    description?: string;
+    /** Detection category (e.g. Security, Content Safety). */
+    category?: string;
+    /** Whether the detector accepts configuration. */
+    configurable?: boolean;
+    /** Configuration schema type (if configurable). */
+    config_type?: string;
+    /** Tags for filtering. */
+    tags?: string[];
+    /** Typical latency estimate. */
+    latency?: string;
+}
+/** Entry in the detector optimization plan. */
+interface DetectorPlanEntry {
+    /** Detector name. */
+    name: string;
+    /** Detector tier. */
+    tier: string;
+    /** Why included/excluded: policy_required, always_run, not_required. */
+    reason: string;
+    /** Full scoped config (dry run only). */
+    config?: Record<string, unknown>;
+}
+/** A Cedar policy that contributed to the guard decision. */
+interface DeterminingPolicy {
+    /** Cedar @id annotation (e.g. secrets-block-prompts). */
+    rule_id: string;
+    /** Database UUID (for dashboard linking). */
+    policy_id?: string;
+    /** Human-readable policy name. */
+    policy_name?: string;
+    /** Cedar effect: permit or forbid. */
+    effect?: string;
+    /** Policy mode: enforce, monitor, or alert. */
+    mode?: string;
+    /** Policy domain (e.g. secrets, pii, injection). */
+    category?: string;
+    /** From Cedar @severity annotation. */
+    severity?: string;
+    /** From Cedar @tags annotation. */
+    tags?: string[];
+    /** Custom Cedar annotations. */
+    annotations?: Record<string, string>;
+}
+/** Request body for POST /v1/guard. */
+interface GuardRequest {
+    /** Content to evaluate (prompt text, tool call arguments, file content, etc.). */
+    content: string;
+    content_type: ContentType;
+    /** Cedar action (e.g. process_prompt, call_tool, read_file, write_file). */
+    action: string;
+    /** Specific detectors to run. Empty runs all enabled detectors. */
+    detectors?: string[];
+    mode?: Mode;
+    /** Enable early exit on deny after each tier (skips slower tiers). */
+    early_exit?: boolean;
+    /** Include structured policy explanation showing why each determining policy matched. */
+    explain?: boolean;
+    /** Caller-provided metadata passed through to detectors. */
+    metadata?: Record<string, unknown>;
+    /** Reference material for context-aware detection (hallucination, groundedness). */
+    contexts?: string[];
+    /** Session ID for cross-turn state tracking. */
+    session_id?: string;
+    tool?: ToolContext;
+    model?: ModelContext;
+    file?: FileContext;
+    mcp?: MCPContext;
+    /** When true, only run detectors whose outputs are referenced by active policies. */
+    optimize?: boolean;
+    /** When true and optimize is true, return the optimization plan without executing. */
+    dry_run?: boolean;
+    /** Include debug_info showing exact Cedar evaluation inputs. */
+    debug?: boolean;
+}
+/** Detector optimization plan (when optimize=true). */
+interface OptimizationReport {
+    /** Context keys required by active policies. */
+    required_context_keys: string[];
+    /** Detectors required by policies. */
+    required_detectors: DetectorPlanEntry[];
+    /** Detectors skipped (not required by policies). */
+    skipped_detectors: DetectorPlanEntry[];
+    /** Policies matching this action/product scope. */
+    active_policies: string[];
+    /** Why this optimization plan was chosen. */
+    reason: string;
+    /** True if fell back to running all detectors. */
+    fallback_to_all: boolean;
+}
+/** Root cause analysis for a triggered detection. */
+interface RootCause {
+    /** Human-readable summary of the root cause. */
+    summary: string;
+    /** Detector that triggered. */
+    detector: string;
+    /** Key-value pairs explaining the threat. */
+    labels?: Record<string, string>;
+    /** Context values that caused the trigger. */
+    triggering_context: Record<string, unknown>;
+    /** Supporting evidence. */
+    evidence?: Record<string, unknown>;
+    /** Policy IDs triggered by this root cause. */
+    triggered_policies: string[];
+}
+/** Session state changes after evaluation. */
+interface SessionDelta {
+    /** Updated turn count. */
+    turn_count: number;
+    /** Updated cumulative risk score (0-100). */
+    cumulative_risk: number;
+    /** Tokens used in this turn. */
+    tokens_used_delta?: number;
+    /** Action performed in this turn. */
+    new_action?: string;
+}
+/** Response from POST /v1/guard. */
+interface GuardResponse {
+    decision: Decision;
+    /** Cedar decision before mode override. */
+    actual_decision?: string;
+    /** True if decision was changed by per-policy mode. */
+    mode_overridden?: boolean;
+    /** Strictest mode among determining policies. */
+    effective_mode?: string;
+    /** True when alert-mode policy fired. */
+    alerted?: boolean;
+    /** Human-readable policy decision reasoning. */
+    policy_reason?: string;
+    /** Mode override explanation (monitor/alert). */
+    mode_reason?: string;
+    /** Cedar diagnostic errors (rare). */
+    eval_errors?: string;
+    /** Unique audit trail ID. */
+    audit_id?: string;
+    /** Request trace ID. */
+    request_id?: string;
+    /** Response timestamp (RFC 3339). */
+    timestamp: string;
+    /** Policies that determined the decision. */
+    determining_policies?: DeterminingPolicy[];
+    /** Per-detector results. */
+    detectors: DetectorResult[];
+    /** Merged detector context. */
+    context: Record<string, unknown>;
+    /** Total evaluation latency in milliseconds. */
+    latency_ms: number;
+    /** Cedar evaluation latency in milliseconds. */
+    eval_latency_ms?: number;
+    /** Detector tiers that ran (fast, standard, slow). */
+    tiers_evaluated: string[];
+    /** Detector tiers skipped due to early exit. */
+    tiers_skipped?: string[];
+    session_delta?: SessionDelta;
+    agent_identity?: AgentIdentityTrace;
+    /** Structured policy explanation (when explain=true). */
+    explanation?: Record<string, unknown>;
+    /** Root cause analysis for triggered detections. */
+    root_causes?: RootCause[];
+    /** Cedar-normalized context (when debug=true). */
+    projected_context?: Record<string, unknown>;
+    optimization?: OptimizationReport;
+    debug_info?: DebugInfo;
+}
+/** Response from GET /v1/health. */
+interface HealthResponse {
+    /** Overall health status. */
+    status: "healthy" | "degraded";
+    /** Per-detector health status. */
+    detectors?: Record<string, string>;
+    /** Cedar evaluator status. */
+    evaluator?: "ready" | "no_policies";
+}
+/** Response from GET /v1/detectors. */
+interface ListDetectorsResponse {
+    /** Available detectors. */
+    detectors: DetectorInfo[];
+    /** Total number of registered detectors. */
+    count: number;
+}
+/** RFC 9457 Problem Details error format. */
+interface ProblemDetails {
+    /** HTTP status code. */
+    status: number;
+    /** Short error title. */
+    title: string;
+    /** Detailed error message. */
+    detail?: string;
+}
+/** A Server-Sent Event from the guard stream. */
+interface StreamEvent {
+    /** Event type: detector_result (per-detector), decision (final), or error. */
+    type: "detector_result" | "decision" | "error";
+    /** Event payload (DetectorResult for detector_result, GuardResponse for decision). */
+    data: Record<string, unknown>;
+}
+/** Response from the token exchange endpoint (used by SDK auth). */
+interface TokenResponse {
+    /** RS256 JWT token. */
+    access_token: string;
+    /** Token type (always Bearer). */
+    token_type?: string;
+    /** Token lifetime in seconds. */
+    expires_in: number;
+    /** Account ID from token claims. */
+    account_id?: string;
+    /** Gateway ID from token claims. */
+    gateway_id?: string;
+    /** Project ID from token claims. */
+    project_id?: string;
+}
+
+/**
+ * Highflame SDK client — resource-based HTTP client for Highflame guardrails.
+ *
+ * Uses native fetch (Node 18+, browsers) with zero runtime dependencies.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import { Highflame } from "highflame";
+ *
+ * const client = new Highflame({ apiKey: "hf_sk_..." });
+ *
+ * // Guard
+ * const resp = await client.guard.evaluatePrompt("Hello world");
+ * const resp = await client.guard.evaluateToolCall("shell", { cmd: "ls" });
+ *
+ * // Detect (no policy evaluation)
+ * const resp = await client.detect.run({ content: "...", content_type: "prompt" });
+ *
+ * // List detectors
+ * const detectors = await client.detectors.list();
+ *
+ * // Debug
+ * const policies = await client.debug.policies();
+ * ```
+ */
+
+/** SDK version — kept in sync with package.json via `make version-sync`. */
+declare const VERSION = "0.2.0";
+/**
+ * Pluggable logger interface.
+ *
+ * Pass any object that satisfies this interface (e.g. `console`, a pino
+ * instance, or a custom wrapper) via `HighflameOptions.logger`.
+ *
+ * When no logger is provided, all logging is silently dropped.
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+}
+interface HighflameOptions {
+    /** Service API key (`hf_sk_...`) or a raw JWT. */
+    apiKey: string;
+    /** Base URL of the guard service. Defaults to Highflame SaaS. */
+    baseUrl?: string;
+    /** Token exchange URL. Defaults to Highflame SaaS. Only used for `hf_sk_*` keys. */
+    tokenUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000. */
+    timeout?: number;
+    /** Number of retries on 429/5xx. Default: 2. */
+    maxRetries?: number;
+    /** Override X-Account-ID header. */
+    accountId?: string;
+    /** Override X-Project-ID header. */
+    projectId?: string;
+    /**
+     * Extra headers merged into every request. Useful for passing
+     * custom routing or identity headers.
+     *
+     * Example: `{ "X-Custom-Routing": "my-service" }`
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional logger for debug/info/warn messages. Pass `console` for quick
+     * debugging, or a structured logger (pino, winston) for production.
+     *
+     * Default: no logging.
+     */
+    logger?: Logger;
+}
+/** Options accepted by individual request methods. */
+interface RequestOptions {
+    /** Per-request timeout override in milliseconds. */
+    timeout?: number;
+}
+declare class GuardResource {
+    private readonly _client;
+    constructor(_client: Highflame);
+    /** Evaluate content against guard policies (POST /v1/guard). */
+    evaluate(request: GuardRequest, options?: RequestOptions): Promise<GuardResponse>;
+    /** Shorthand: evaluate a user prompt. */
+    evaluatePrompt(content: string, options?: {
+        mode?: Mode;
+        session_id?: string;
+    } & RequestOptions): Promise<GuardResponse>;
+    /** Shorthand: evaluate a tool call. */
+    evaluateToolCall(toolName: string, args?: Record<string, unknown>, options?: {
+        mode?: Mode;
+        session_id?: string;
+    } & RequestOptions): Promise<GuardResponse>;
+    /** Stream guard evaluation results (POST /v1/guard/stream). */
+    stream(request: GuardRequest, options?: RequestOptions): AsyncIterable<StreamEvent>;
+}
+declare class DetectResource {
+    private readonly _client;
+    constructor(_client: Highflame);
+    /** Run detectors without policy evaluation (POST /v1/detect). */
+    run(request: DetectRequest, options?: RequestOptions): Promise<DetectResponse>;
+}
+declare class DetectorsResource {
+    private readonly _client;
+    constructor(_client: Highflame);
+    /** List available detectors (GET /v1/detectors). */
+    list(options?: RequestOptions): Promise<ListDetectorsResponse>;
+}
+declare class DebugResource {
+    private readonly _client;
+    constructor(_client: Highflame);
+    /** Inspect loaded policies (GET /v1/debug/policies). */
+    policies(product?: string, options?: RequestOptions): Promise<DebugPoliciesResponse>;
+}
+declare class Highflame {
+    #private;
+    readonly guard: GuardResource;
+    readonly detect: DetectResource;
+    readonly detectors: DetectorsResource;
+    readonly debug: DebugResource;
+    constructor(options: HighflameOptions);
+    get accountId(): string;
+    get projectId(): string;
+    /** Get auth headers (exposed for external use with custom HTTP clients). */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** @internal */
+    _fetchWithRetry(path: string, init: RequestInit, overrideTimeout?: number): Promise<Response>;
+    /** @internal */
+    _postJSON<T>(path: string, body: unknown, overrideTimeout?: number): Promise<T>;
+    /** @internal */
+    _getJSON<T>(path: string, overrideTimeout?: number): Promise<T>;
+    /** @internal */
+    _stream(path: string, body: unknown, overrideTimeout?: number): AsyncGenerator<StreamEvent>;
+    toString(): string;
+}
+
+/**
+ * Error hierarchy for the Highflame SDK.
+ */
+
+/** Base class for all SDK errors. */
+declare class HighflameError extends Error {
+    constructor(message: string);
+}
+/** HTTP error from the API (RFC 9457 Problem Details). */
+declare class APIError extends HighflameError {
+    readonly status: number;
+    readonly title: string;
+    readonly detail: string;
+    constructor(status: number, title: string, detail: string);
+}
+/** 401 Unauthorized — invalid or expired credentials. */
+declare class AuthenticationError extends APIError {
+    constructor(detail?: string);
+}
+/** 429 Too Many Requests — rate limit exceeded. */
+declare class RateLimitError extends APIError {
+    constructor(detail?: string);
+}
+/** Connection or timeout failure communicating with the API. */
+declare class APIConnectionError extends HighflameError {
+    constructor(message: string);
+}
+/** Thrown by Shield wrappers when the guard decision is 'deny'. */
+declare class BlockedError extends HighflameError {
+    readonly response: GuardResponse;
+    constructor(response: GuardResponse);
+}
+
+/**
+ * Shield — higher-order function wrapper for guardrails.
+ *
+ * JavaScript/TypeScript equivalent of the Python Shield decorator facade.
+ * Wraps any function (sync or async) with a guard check that throws
+ * {@link BlockedError} when the guard decision is "deny".
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import { Shield, Highflame, BlockedError } from "highflame";
+ *
+ * const client = new Highflame({ apiKey: "hf_sk_xxx" });
+ * const shield = new Shield(client);
+ *
+ * const chat = shield.prompt(async (message: string) => llm.complete(message));
+ * const shell = shield.tool(async (cmd: string) => exec(cmd));
+ * ```
+ */
+
+interface PromptOptions {
+    mode?: Mode;
+    contentArg?: number;
+    sessionId?: string;
+}
+interface ToolOptions {
+    mode?: Mode;
+    toolName?: string;
+    sessionId?: string;
+}
+interface ToolResponseOptions {
+    mode?: Mode;
+    toolName?: string;
+    sessionId?: string;
+}
+interface ModelResponseOptions {
+    mode?: Mode;
+    sessionId?: string;
+}
+interface WrapOptions {
+    contentType: GuardRequest["content_type"];
+    action: GuardRequest["action"];
+    contentArg?: number;
+    mode?: Mode;
+    sessionId?: string;
+}
+declare class Shield {
+    private readonly client;
+    constructor(client: Highflame);
+    prompt<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: PromptOptions): (...args: TArgs) => Promise<Awaited<TReturn>>;
+    tool<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: ToolOptions): (...args: TArgs) => Promise<Awaited<TReturn>>;
+    toolResponse<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: ToolResponseOptions): (...args: TArgs) => Promise<Awaited<TReturn>>;
+    modelResponse<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: ModelResponseOptions): (...args: TArgs) => Promise<Awaited<TReturn>>;
+    wrap(options: WrapOptions): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>) => (...args: TArgs) => Promise<Awaited<TReturn>>;
+}
+
+export { APIConnectionError, APIError, type AgentIdentityTrace, AuthenticationError, BlockedError, type ContentType, type ContextKeySpec, type DebugInfo, type DebugPoliciesResponse, DebugResource, type Decision, type DetectRequest, DetectResource, type DetectResponse, type DetectorInfo, type DetectorResult, DetectorsResource, type DeterminingPolicy, type FileContext, type GuardRequest, GuardResource, type GuardResponse, type HealthResponse, Highflame, HighflameError, type HighflameOptions, type ListDetectorsResponse, type Logger, type MCPContext, type Mode, type ModelContext, type ModelResponseOptions, type OptimizationReport, type PolicySummary, type ProblemDetails, type PromptOptions, RateLimitError, type RequestOptions, type RootCause, type SessionDelta, Shield, type StreamEvent, type TokenResponse, type ToolContext, type ToolOptions, type ToolResponseOptions, VERSION, type WrapOptions };