@tailrace/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,401 @@
+/**
+ * Public type surface for @tailrace/core.
+ *
+ * These types are the contract every integration builds against. They are specified
+ * by docs/policy-engine.md, docs/detection.md, and docs/vault.md - those docs are
+ * normative when a detail here is ambiguous.
+ */
+/** What the policy engine decides to do with a detected span. */
+type Action = "allow" | "mask" | "tokenize" | "block" | "review" | "detokenize";
+/** Deterministic, Tier 0 secret classes. `block` on these cannot be relaxed to `allow`
+ * without `dangerouslyAllowSecrets` (docs/policy-engine.md §3.3). */
+type SecretEntityClass = "api_key" | "jwt" | "private_key" | "high_entropy_secret" | "connection_string";
+/** Structured PII, detected deterministically in Tier 0. */
+type PiiEntityClass = "email" | "phone" | "credit_card" | "iban" | "ssn" | "ip_address" | "url_credentials";
+/** Free-text PII, detected by the optional Tier 1 NER recognizer. */
+type NerEntityClass = "person" | "location" | "organization";
+/**
+ * Any entity class. The `string & {}` member keeps literal autocomplete for the known
+ * classes while still admitting user-defined classes from custom recognizers.
+ */
+type EntityClass = SecretEntityClass | PiiEntityClass | NerEntityClass | (string & {});
+/** The set of secret classes, as a runtime value, for the secrets-cannot-be-allowed rule. */
+declare const SECRET_ENTITY_CLASSES: readonly SecretEntityClass[];
+/** Structured PII classes (Tier 0). */
+declare const PII_ENTITY_CLASSES: readonly PiiEntityClass[];
+/** Free-text PII classes (Tier 1 NER). */
+declare const NER_ENTITY_CLASSES: readonly NerEntityClass[];
+/** A trust boundary a value is about to cross. */
+type Boundary = {
+    kind: "model";
+    provider: string;
+} | {
+    kind: "tool";
+    name: string;
+    direction: "in" | "out";
+} | {
+    kind: "mcp";
+    server: string;
+    tool: string;
+    direction: "in" | "out";
+} | {
+    kind: "telemetry";
+} | {
+    kind: "egress";
+    sink: string;
+};
+/** Who is acting. `agent` is required ("default" if unset). */
+interface Identity {
+    agent: string;
+    claims?: Record<string, string | string[]>;
+}
+/** A detected region of the input. Offsets are UTF-16 code units. */
+interface Span {
+    entity: EntityClass;
+    /** Inclusive start offset (UTF-16 code units). */
+    start: number;
+    /** Exclusive end offset (UTF-16 code units). */
+    end: number;
+    /** 1.0 = validator-confirmed, 0.8 = pattern-only (docs/detection.md §1). */
+    confidence: number;
+    /** Id of the emitting recognizer. */
+    recognizer: string;
+    /** RFC 6901 JSON Pointer when the span came from an object leaf; absent for plain strings. */
+    path?: string;
+}
+/** A detection engine. Tier 0 recognizers MUST be synchronous. */
+interface Recognizer {
+    id: string;
+    entities: EntityClass[];
+    tier: 0 | 1 | 2;
+    scan(text: string): Span[] | Promise<Span[]>;
+}
+/** One resolved policy outcome for one span. Never carries the raw value. */
+interface Decision {
+    action: Action | "restore_miss";
+    entity: EntityClass;
+    boundary: Boundary;
+    identity: Identity;
+    /** Dotted path of the winning rule, e.g. `identities.support-agent.tools.crm.*`. */
+    rule: string;
+    /** JSON path + offsets, never the value. */
+    span: {
+        path: string;
+        start: number;
+        end: number;
+    };
+    /** SHA-256 of the raw value, hex - for audit correlation only. */
+    contentHash: string;
+    /**
+     * When {@link CheckOptions.applyBlockAs} remaps a `block` to another applied action,
+     * the resolved policy action stays `block` and this records what was applied.
+     */
+    appliedAs?: "mask";
+}
+/**
+ * Per-call options for {@link Tailrace.check}. Integration-only knobs; does not change
+ * policy resolution (docs/policy-engine.md §5).
+ */
+interface CheckOptions {
+    /**
+     * When policy resolves to `block`, apply this action instead of throwing.
+     * Default: throw. Used by `@tailrace/ai-sdk` for `streamBlockBehavior: "redact"`.
+     */
+    applyBlockAs?: "mask";
+    /**
+     * Streaming hold-back (docs/vault.md §5). String inputs only.
+     * Detects+resolves on the full input once; applies only spans fully within the safe
+     * emit prefix; returns raw {@link CheckResult.remainder} to carry.
+     */
+    stream?: {
+        /** Trailing chars that may still grow into a match. */
+        holdback: number;
+        /** When true, flush the entire buffer (no hold-back). */
+        final?: boolean;
+    };
+}
+/** A per-entity rule; either a bare action or an action with modifiers. */
+interface EntityRule {
+    action: Action;
+    /** Tokenization output shape (docs/vault.md §3). */
+    format?: "preserve" | "label";
+    /** Required to relax a secret class away from `block` (docs/policy-engine.md §3.3). */
+    dangerouslyAllowSecrets?: boolean;
+}
+type EntityRuleValue = Action | EntityRule;
+/** A scope that maps entities and per-boundary overrides; reused at top level and per identity. */
+interface PolicyScope {
+    entities?: Partial<Record<EntityClass, EntityRuleValue>>;
+    boundaries?: Record<string, {
+        entities?: Partial<Record<string, EntityRuleValue>>;
+    }>;
+}
+/** A full policy document (docs/policy-engine.md §2). */
+interface PolicyDocument extends PolicyScope {
+    defaults?: {
+        action?: Action;
+    };
+    identities?: Record<string, PolicyScope>;
+    /** Global escape hatch for the secrets-cannot-be-allowed rule. */
+    dangerouslyAllowSecrets?: boolean;
+}
+/**
+ * Where a policy comes from. v0.1 ships `staticPolicy`; a hosted plane can slot in later
+ * without a core API change (docs/architecture.md §5).
+ */
+interface PolicySource {
+    load(): Promise<PolicyDocument>;
+    subscribe?(cb: (p: PolicyDocument) => void): () => void;
+}
+/** A single stored token record. */
+interface VaultRecord {
+    value: string;
+    entity: EntityClass;
+}
+interface VaultPutInput {
+    workflowId: string;
+    token: string;
+    entity: EntityClass;
+    value: string;
+    expiresAt?: number;
+}
+/** Reversible token storage (docs/vault.md §2). Values are stored encrypted at rest. */
+interface Vault {
+    put(input: VaultPutInput): Promise<void>;
+    get(workflowId: string, token: string): Promise<VaultRecord | null>;
+    purge(workflowId: string): Promise<void>;
+}
+/** Minimal KV surface backing `kvVault`; structurally compatible with Cloudflare KV. */
+interface KvStore {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, opts?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** One audit record emitted per check/restore. */
+interface AuditEvent {
+    type: "check" | "restore";
+    workflowId: string;
+    timestamp: number;
+    decisions: Decision[];
+}
+/** A destination for audit events (console, JSONL, otel, custom). */
+interface AuditSink {
+    emit(event: AuditEvent): void | Promise<void>;
+}
+/**
+ * Line writer for {@link jsonlSink}. Callers supply filesystem or remote adapters;
+ * core never touches the filesystem.
+ */
+interface AuditWriter {
+    write(line: string): void | Promise<void>;
+}
+/** Master-key and TTL options for the built-in vaults. */
+interface VaultOptions {
+    /** Master key; falls back to `TAILRACE_VAULT_KEY`, then a random per-process key. */
+    key?: string;
+    /** Default token TTL in seconds (docs/vault.md §2). */
+    ttlSeconds?: number;
+}
+/** Options for {@link createTailrace}. Every field has a sensible default. */
+interface TailraceOptions {
+    policy?: PolicyDocument | PolicySource;
+    recognizers?: Recognizer[];
+    vault?: Vault | VaultOptions;
+    audit?: {
+        sinks?: AuditSink[];
+    };
+    /** Emit spans for private/reserved IP ranges (docs/detection.md §2). */
+    includePrivateIps?: boolean;
+    /** Notified with every decision, regardless of configured audit sinks. */
+    onDecision?: (decisions: Decision[]) => void;
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+type JsonObject = {
+    [k: string]: JsonValue;
+};
+interface CheckContext {
+    boundary: Boundary;
+    identity: Identity;
+    workflowId?: string;
+}
+interface CheckResult<T> {
+    output: T;
+    decisions: Decision[];
+    blocked: false;
+    /**
+     * Raw suffix held back when {@link CheckOptions.stream} is set on a string input.
+     * Absent for non-streaming checks.
+     */
+    remainder?: string;
+}
+/**
+ * The core primitive every integration calls. Integrations construct the right
+ * `Boundary`/`Identity` and translate errors; they contain no policy logic.
+ */
+interface Tailrace {
+    /**
+     * Detect + resolve + apply. Throws {@link PolicyViolationError} on a `block`
+     * unless {@link CheckOptions.applyBlockAs} remaps the block.
+     */
+    check<T extends string | JsonObject>(input: T, ctx: CheckContext, options?: CheckOptions): Promise<CheckResult<T>>;
+    /** Restore tokens at a trusted `egress` boundary. Throws at any other boundary. */
+    restore<T extends string | JsonObject>(input: T, ctx: CheckContext): Promise<CheckResult<T>>;
+}
+
+/**
+ * Typed error taxonomy (docs/conventions.md §Error taxonomy).
+ *
+ * Every Tailrace error carries a stable string `code`. Error messages MUST NEVER
+ * contain a detected value - only entity classes, rule paths, and hashes. This is
+ * enforced by a test that greps thrown messages against fixture values.
+ */
+
+/** Base class for every error thrown by Tailrace. */
+declare class TailraceError extends Error {
+    /** Stable, machine-readable error code. */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A `block` policy matched. Integrations translate this into their host framework's
+ * native failure mode. Carries the decisions that triggered the block; never a value.
+ */
+declare class PolicyViolationError extends TailraceError {
+    readonly decisions: Decision[];
+    constructor(message: string, decisions: Decision[]);
+}
+/** A policy document failed schema validation. `path` points at the offending key. */
+declare class PolicyValidationError extends TailraceError {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** An internal contract was breached, e.g. a restore requested at a non-egress boundary. */
+declare class InvariantViolationError extends TailraceError {
+    constructor(message: string);
+}
+/** A vault adapter failed (storage, encryption, or lookup). */
+declare class VaultError extends TailraceError {
+    constructor(message: string);
+}
+/** A recognizer threw while scanning. */
+declare class RecognizerError extends TailraceError {
+    constructor(message: string);
+}
+/** A surface that is specified but not yet implemented in this milestone. */
+declare class NotImplementedError extends TailraceError {
+    constructor(message: string);
+}
+
+/**
+ * Built-in audit sinks (console + JSONL writer).
+ */
+
+/**
+ * Log each audit event as a single JSON line on the console.
+ *
+ * @example
+ * ```ts
+ * const gate = createTailrace({ audit: { sinks: [consoleSink()] } });
+ * ```
+ */
+declare function consoleSink(): AuditSink;
+/**
+ * Write each audit event as a JSON line via a caller-supplied {@link AuditWriter}.
+ * Core never touches the filesystem - pass a file/stream adapter from Node or the CLI.
+ *
+ * @example
+ * ```ts
+ * const lines: string[] = [];
+ * const sink = jsonlSink({ write: (line) => { lines.push(line); } });
+ * ```
+ */
+declare function jsonlSink(writer: AuditWriter): AuditSink;
+
+/**
+ * In-memory vault with TTL sweep. Default vault for createTailrace().
+ */
+
+/**
+ * Create an in-memory vault. Values are encrypted at rest with the resolved master key.
+ *
+ * @example
+ * ```ts
+ * const gate = createTailrace({ vault: memoryVault({ key: "dev-only-key" }) });
+ * ```
+ */
+declare function memoryVault(opts?: VaultOptions): Vault;
+
+/**
+ * KV-backed vault (Cloudflare KV and compatible). Values encrypted at rest.
+ */
+
+/**
+ * Create a vault backed by a minimal KV store.
+ *
+ * @example
+ * ```ts
+ * const gate = createTailrace({ vault: kvVault(env.MY_KV, { key: secret }) });
+ * ```
+ */
+declare function kvVault(kv: KvStore, opts?: VaultOptions): Vault;
+
+/**
+ * @tailrace/core - detection, policy engine, vault, and audit.
+ *
+ * Zero runtime dependencies; runs on Node 20+, Cloudflare Workers, and Vercel Edge.
+ * Public exports are intentionally short - every export is API forever
+ * (docs/architecture.md §6).
+ */
+
+/**
+ * Create a gate. Zero-config by default: all secret classes `block`, common PII `tokenize`.
+ *
+ * @example
+ * ```ts
+ * const tailrace = createTailrace();
+ * const { output } = await tailrace.check(userInput, {
+ *   boundary: { kind: "model", provider: "openai/gpt-4o" },
+ *   identity: { agent: "default" },
+ * });
+ * ```
+ */
+declare function createTailrace(options?: TailraceOptions): Tailrace;
+/**
+ * Author and validate a policy document.
+ *
+ * @example
+ * ```ts
+ * const policy = definePolicy({ entities: { email: "tokenize" } });
+ * ```
+ */
+declare function definePolicy(doc: PolicyDocument): PolicyDocument;
+/**
+ * Define a custom recognizer.
+ *
+ * @example
+ * ```ts
+ * const employeeId = defineRecognizer({
+ *   id: "employee-id",
+ *   entities: ["employee_id"],
+ *   tier: 0,
+ *   scan: (text) => [],
+ * });
+ * ```
+ */
+declare function defineRecognizer(recognizer: Recognizer): Recognizer;
+/**
+ * Wrap a local policy document as a {@link PolicySource}. This is the default source and
+ * the shape a hosted policy plane implements later (docs/architecture.md §5).
+ *
+ * @example
+ * ```ts
+ * const source = staticPolicy(definePolicy({ entities: { email: "tokenize" } }));
+ * ```
+ */
+declare function staticPolicy(doc: PolicyDocument): PolicySource;
+
+export { type Action, type AuditEvent, type AuditSink, type AuditWriter, type Boundary, type CheckContext, type CheckOptions, type CheckResult, type Decision, type EntityClass, type EntityRule, type EntityRuleValue, type Identity, InvariantViolationError, type JsonObject, type JsonValue, type KvStore, NER_ENTITY_CLASSES, type NerEntityClass, NotImplementedError, PII_ENTITY_CLASSES, type PiiEntityClass, type PolicyDocument, type PolicyScope, type PolicySource, PolicyValidationError, PolicyViolationError, type Recognizer, RecognizerError, SECRET_ENTITY_CLASSES, type SecretEntityClass, type Span, type Tailrace, TailraceError, type TailraceOptions, type Vault, VaultError, type VaultOptions, type VaultPutInput, type VaultRecord, consoleSink, createTailrace, definePolicy, defineRecognizer, jsonlSink, kvVault, memoryVault, staticPolicy };