@intentgate-app/intentgate 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,537 @@
+/**
+ * Memory provenance primitives for the IntentGate TypeScript SDK.
+ *
+ * This module implements the SDK side of the AAI03 (Memory Poisoning)
+ * defense. The agent wraps its memory backend (vector DB, Redis,
+ * in-memory dict, anything) with {@link MemoryStore}, which signs
+ * every write with an HMAC-SHA256 keyed by a per-session signing key
+ * derived (via HKDF) from the capability token. At tool-call time the
+ * agent declares which memory entries influenced the call via the
+ * `memoryProvenance` parameter on `Gateway.toolCall`; the gateway
+ * re-derives the session key and verifies each entry.
+ *
+ * # Cross-implementation contract
+ *
+ * The byte encoding of an {@link Envelope} (see {@link canonical})
+ * MUST match the Go gateway's `internal/provenance.Canonical`
+ * byte-for-byte AND match the Python SDK's `intentgate.memory.canonical`
+ * byte-for-byte. The KDF MUST be HKDF-SHA256 with info=
+ * `intentgate-memory-v1`. The HMAC MUST be HMAC-SHA256.
+ *
+ * Drift in any of these contracts means the SDK and the gateway
+ * silently disagree on signatures — a class of bug caught by the
+ * cross-implementation KAT test in `tests/memory.test.ts`. If you
+ * change anything in this file, run that test against the Go gateway's
+ * `TestDeriveSessionKey_KnownAnswer` and the Python SDK's
+ * `test_hkdf_kat_matches_go_gateway` to confirm the wire contract
+ * still holds.
+ *
+ * # Zero runtime dependencies
+ *
+ * Uses only `node:crypto` (createHmac, createHash, hkdfSync,
+ * timingSafeEqual, randomUUID). No third-party crypto package. The
+ * Node 18+ baseline is documented in package.json.
+ */
+/** Length of a derived session signing key in bytes. Matches the Go
+ * gateway's SessionKeySize and the Python SDK's SESSION_KEY_SIZE. */
+declare const SESSION_KEY_SIZE = 32;
+/** The conventional PrevHash value for the first entry in a session.
+ * Named so the special-case is obvious at the call site. */
+declare const ZERO_HASH: Buffer;
+/**
+ * Raised when the SDK cannot produce or verify a memory envelope.
+ * Distinct from the gateway-side `ProvenanceError` in `errors.ts`
+ * (which is raised by `Gateway.toolCall` when the gateway rejected
+ * the provenance check). This class is for SDK-internal failures —
+ * a tampered entry detected at read time, a malformed envelope, etc.
+ */
+declare class MemoryProvenanceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Derive the per-session memory signing key.
+ *
+ * Matches the gateway's `provenance.DeriveSessionKey` and the Python
+ * SDK's `derive_session_key`: HKDF-SHA256 with salt = `sessionId` (as
+ * UTF-8 bytes), info = `intentgate-memory-v1`, length = 32.
+ *
+ * @throws if `masterKey` is empty or `sessionId` is empty.
+ */
+declare function deriveSessionKey(masterKey: Buffer | Uint8Array, sessionId: string): Buffer;
+/** One signed memory entry. Stored opaquely by the customer's memory
+ * backend; produced by `MemoryStore.write`; verified by the gateway. */
+interface Envelope {
+    /** Stable identifier for the entry. */
+    id: string;
+    /** The capability token's `jti` whose signing key signed this. */
+    sessionId: string;
+    /** Creation time as Unix milliseconds. */
+    timestamp: number;
+    /** Application-level payload bytes. */
+    data: Buffer;
+    /** SHA-256 of the canonical bytes of the previous entry in this
+     * session, or ZERO_HASH for the first entry. */
+    prevHash: Buffer;
+    /** HMAC-SHA256 of canonical(envelope) under the session key. */
+    hmac: Buffer;
+}
+/**
+ * Produce the byte sequence the envelope's HMAC covers.
+ *
+ * Encoding is a length-prefixed concatenation of the immutable fields
+ * in order: sessionId (utf-8), id (utf-8), timestamp (big-endian
+ * uint64), prevHash, data. Lengths are big-endian uint32.
+ *
+ * The encoding is deliberately NOT JSON — same byte sequence the Go
+ * gateway produces in `provenance.Canonical` and the Python SDK
+ * produces in `canonical`. Cross-verified by the KAT test.
+ *
+ * The `hmac` field is excluded (a signature cannot cover itself).
+ */
+declare function canonical(env: Pick<Envelope, "id" | "sessionId" | "timestamp" | "data" | "prevHash">): Buffer;
+/**
+ * Return a copy of `env` with the `hmac` field populated.
+ *
+ * Used at memory-write time by `MemoryStore.write` and by tests.
+ * Computes `HMAC-SHA256(sessionKey, canonical(env))`.
+ *
+ * @throws if `sessionKey` is empty.
+ */
+declare function sign(sessionKey: Buffer, env: Omit<Envelope, "hmac">): Envelope;
+/**
+ * Check `env.hmac` against `sessionKey`. Returns `undefined` on a
+ * valid signature; throws {@link MemoryProvenanceError} otherwise.
+ * Comparison uses `timingSafeEqual` — constant-time with respect to
+ * signature contents.
+ */
+declare function verify(sessionKey: Buffer, env: Envelope): void;
+/**
+ * Check a list of envelopes as a per-session chain.
+ *
+ * Each entry's HMAC must verify and each entry's `prevHash` must
+ * equal SHA-256 of the canonical bytes of the previous entry. The
+ * first entry's `prevHash` must equal {@link ZERO_HASH}.
+ *
+ * Empty chain is valid (let policy decide whether absence of memory
+ * provenance is a deny condition for the tool).
+ */
+declare function verifyChain(sessionKey: Buffer, chain: readonly Envelope[]): void;
+/** Customer-supplied write hook for a backing store. */
+type MemoryWriteHook = (entryId: string, env: Envelope) => void;
+/** Customer-supplied read hook. Must throw if entry not found. */
+type MemoryReadHook = (entryId: string) => Envelope;
+/**
+ * Sign-on-write, verify-on-read wrapper around a memory backend.
+ *
+ * The customer plugs their underlying memory store (Pinecone, Redis,
+ * pgvector, an in-memory Map, anything) into this wrapper by
+ * supplying two callables: a write-hook and a read-hook. The wrapper
+ * signs entries on write and verifies them on read, so a tampered
+ * entry surfaces immediately at the agent's read site rather than
+ * waiting until the gateway rejects the tool call.
+ *
+ * The default storage backend is an in-memory Map — suitable for SDK
+ * tests, demos, and small agents. Production agents pass their real
+ * backend's read/write callables.
+ */
+declare class MemoryStore {
+    private readonly sessionId;
+    private readonly key;
+    private readonly fallback;
+    private readonly writeHook?;
+    private readonly readHook?;
+    private chainHead;
+    /**
+     * @param sessionId The `jti` of the capability token this store is bound to.
+     *   Used as the HKDF salt to derive the signing key.
+     * @param memorySigningKey The 32-byte signing key returned by
+     *   `POST /v1/admin/mint` when `with_memory_signing_key: true`.
+     * @param options Optional `writeHook` / `readHook` callables; when
+     *   absent the wrapper uses an in-memory Map fallback.
+     */
+    constructor(sessionId: string, memorySigningKey: Buffer | Uint8Array, options?: {
+        writeHook?: MemoryWriteHook;
+        readHook?: MemoryReadHook;
+    });
+    /**
+     * Sign `data` into a new envelope and store it. Returns the entry
+     * ID, which the caller passes to `Gateway.toolCall` via the
+     * `memoryProvenance` list.
+     *
+     * `data` may be a Buffer, a string (utf-8 encoded), or any JSON-
+     * serializable value (encoded with sorted keys + no whitespace so
+     * equivalent inputs produce identical envelope bytes).
+     */
+    write(data: Buffer | string | Record<string, unknown> | unknown[]): string;
+    /**
+     * Fetch and verify the envelope identified by `entryId`.
+     *
+     * @throws if the entry is missing (`Error`) or if the HMAC fails
+     *   ({@link MemoryProvenanceError}, indicating the entry was
+     *   tampered with after writing).
+     */
+    read(entryId: string): Envelope;
+    /**
+     * Build the wire-format provenance entries for a tool call. Each
+     * entry is verified before inclusion — if any envelope was tampered
+     * with at the storage layer, {@link MemoryProvenanceError} is
+     * raised here rather than at the gateway.
+     *
+     * The returned objects use base64url (no padding) encoding for byte
+     * fields — same shape the Go gateway parses.
+     */
+    provenanceFor(entryIds: readonly string[]): Array<{
+        id: string;
+        session_id: string;
+        ts: number;
+        data: string;
+        prev_hash: string;
+        hmac: string;
+    }>;
+    /** Number of entries in the fallback in-memory store. */
+    get size(): number;
+}
+
+/**
+ * Exception hierarchy for the IntentGate SDK.
+ *
+ * Every gateway response that isn't a clean allow becomes a typed
+ * Error. The hierarchy lets callers catch broadly (`catch (e) { if
+ * (e instanceof IntentGateError) ... }`) or narrowly (`if (e instanceof
+ * CapabilityError) ...`) depending on whether they want to distinguish
+ * which check fired.
+ *
+ * Stage codes are stable across gateway versions:
+ *
+ *   CapabilityError     -32010
+ *   IntentError         -32011
+ *   PolicyError         -32012
+ *   BudgetError         -32013
+ *   ProvenanceError     -32014  (opt-in, AAI03 memory-poisoning defense)
+ *
+ * Anything else (parse errors, method not found, internal errors) is
+ * a `ProtocolError`. Network and HTTP transport failures (timeouts,
+ * connection refused, non-JSON responses) are `GatewayError` —
+ * distinguish "the gateway is unreachable" from "the gateway said no".
+ */
+declare class IntentGateError extends Error {
+    /** JSON-RPC error code from the gateway, or 0 if client-side. */
+    readonly code: number;
+    /** Optional structured payload from the gateway's `error.data`. */
+    readonly data: unknown;
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+    /**
+     * Human-friendly string. When `data` is a string, it usually carries
+     * the operator-facing reason (e.g. the Rego rule's explanation), so
+     * we surface it on `toString`.
+     */
+    toString(): string;
+}
+/** Network or transport failure reaching the gateway. */
+declare class GatewayError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** JSON-RPC error not in the four stage-specific codes. */
+declare class ProtocolError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** Capability stage denied: token signature, expiry, agent lock, etc. */
+declare class CapabilityError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** Intent stage denied: requested tool isn't in the extracted intent. */
+declare class IntentError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** Policy stage denied: a Rego rule fired. */
+declare class PolicyError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** Budget stage denied: max-calls caveat exhausted. */
+declare class BudgetError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * Provenance stage denied: the opt-in AAI03 memory-poisoning defense
+ * rejected the call. Raised when the X-Intent-Memory-Provenance header
+ * carries an entry whose HMAC does not verify, whose prev_hash chain
+ * is broken, or whose envelope is structurally malformed.
+ *
+ * JSON-RPC code -32014. Only emitted by gateways with provenance
+ * enabled (INTENTGATE_PROVENANCE_ENABLED=true); not raised against
+ * the default four-check pipeline.
+ */
+declare class ProvenanceError extends IntentGateError {
+    constructor(message: string, opts?: {
+        code?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * Pick the typed exception class for a JSON-RPC error code. Codes in
+ * the stage range produce the matching stage class; anything else
+ * (parse, invalid request, method not found, internal error,
+ * out-of-range custom codes) maps to ProtocolError.
+ */
+declare function forCode(code: number): typeof IntentGateError;
+
+/** One piece of the tool's response, in MCP shape. */
+interface ContentBlock {
+    type: string;
+    text?: string;
+}
+/**
+ * Per-call gateway decision metadata, lifted from the `_intentgate`
+ * vendor extension on the JSON-RPC result. Always present on a
+ * successful tool_call; the gateway populates it on every allow.
+ */
+interface IntentGateMetadata {
+    decision: string;
+    reason: string;
+    check: string;
+    latencyMs: number;
+}
+/** Successful tool-call response. */
+interface ToolCallResult {
+    content: ContentBlock[];
+    /** Tool's own `isError` flag — distinct from gateway transport errors. */
+    isError: boolean;
+    intentgate: IntentGateMetadata | null;
+}
+interface ToolCallOptions {
+    /** Tool arguments. The gateway logs only the keys, never the values. */
+    arguments?: Record<string, unknown>;
+    /**
+     * The user's original prompt. Sent in `X-Intent-Prompt`; the gateway
+     * feeds it to the intent extractor and verifies the requested tool
+     * is consistent with the extracted intent. Optional, but strongly
+     * recommended in production — without it the intent check is
+     * skipped (or denies in strict mode).
+     */
+    intentPrompt?: string;
+    /**
+     * JSON-RPC request id. When unset, the Gateway uses a sequential
+     * per-instance counter — fine for most agents.
+     */
+    requestId?: number | string;
+    /**
+     * Optional list of memory entry IDs that influenced this tool call.
+     * When supplied together with `memoryStore`, the SDK looks up the
+     * corresponding signed envelopes and packs them into the
+     * `X-Intent-Memory-Provenance` header. The gateway re-derives the
+     * session signing key from the capability token's jti, verifies
+     * each HMAC, and walks the chain — closing the sophisticated AAI03
+     * (Memory Poisoning) case. Used only when the gateway has
+     * provenance enabled; otherwise the header is ignored. See
+     * `MemoryStore`.
+     */
+    memoryProvenance?: readonly string[];
+    /**
+     * MemoryStore instance the SDK queries for the envelopes named in
+     * `memoryProvenance`. Required iff `memoryProvenance` is non-empty.
+     */
+    memoryStore?: MemoryStore;
+}
+interface GatewayOptions {
+    /**
+     * Capability token from `igctl mint` or your tenant's mint service.
+     * When omitted, no Authorization header is sent and the gateway
+     * will reject with CapabilityError if it's in strict mode.
+     */
+    token?: string;
+    /** Per-request timeout in milliseconds. Default 10s. */
+    timeoutMs?: number;
+    /**
+     * Pluggable fetch implementation. Defaults to the global
+     * `fetch` (Node 18+, browsers, and most modern runtimes). Useful
+     * for test injection, custom transports, or shared connection
+     * pooling.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Thin client for the IntentGate gateway.
+ *
+ * @example
+ * ```ts
+ * import { Gateway } from "@intentgate-app/intentgate";
+ *
+ * const gw = new Gateway("http://localhost:8080", {
+ *   token: process.env.INTENTGATE_TOKEN,
+ * });
+ * const result = await gw.toolCall("read_invoice", {
+ *   arguments: { id: "123" },
+ *   intentPrompt: "Process today's AP invoices",
+ * });
+ * ```
+ */
+declare class Gateway {
+    private readonly url;
+    private readonly token;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private nextId;
+    constructor(url: string, opts?: GatewayOptions);
+    /**
+     * Invoke a tool through the gateway.
+     *
+     * Resolves with a {@link ToolCallResult} for an allowed call. Throws
+     * one of the typed errors (CapabilityError / IntentError /
+     * PolicyError / BudgetError / ProtocolError / GatewayError) when
+     * the gateway denies, the request fails to reach the gateway, or
+     * the response isn't well-formed JSON-RPC.
+     */
+    toolCall(tool: string, opts?: ToolCallOptions): Promise<ToolCallResult>;
+}
+
+/**
+ * Pure-TypeScript capability-token helpers.
+ *
+ * The IntentGate gateway issues capability tokens with a Macaroons-
+ * style chained-HMAC signature: a token holder can derive a strictly
+ * more restrictive child token by appending a caveat and HMAC'ing it
+ * under the parent's signature **without ever touching the master
+ * key**. That is the defining property of capability tokens, and the
+ * reason this module ships in the SDK.
+ *
+ * Use case. A parent agent receives a token allowing tools `[a, b,
+ * c]`, spawns a sub-agent for one task, and wants the sub-agent's
+ * token to allow only `[a]`. The parent calls {@link attenuate} and
+ * hands the resulting token string to the sub-agent. The gateway
+ * (which has the master key) accepts the attenuated token and rejects
+ * any sub-agent call that would have needed `b` or `c`.
+ *
+ * What we don't do here:
+ *
+ * - **No master key access.** By design — that's what makes
+ *   attenuation safe. To mint a brand-new root token, use the
+ *   gateway's `POST /v1/admin/mint` endpoint, not this module.
+ * - **No semantic narrowing check.** Adding a "broader" caveat
+ *   doesn't widen the chain because the parent's narrower caveat
+ *   fires first on the gateway side. We don't second-guess the
+ *   caller; policy belongs in the gateway, not the SDK.
+ *
+ * # Wire format
+ *
+ * We mirror the Go gateway's serialization byte-for-byte on the one
+ * place it matters: the new caveat's canonical JSON, which seeds the
+ * HMAC step. Anywhere else, JSON ordering doesn't affect correctness
+ * because the gateway re-marshals from its parsed Go struct during
+ * `Verify`. Every implementation in this package matches the Python
+ * SDK byte-for-byte against the same fixtures, so a token attenuated
+ * by either SDK verifies on the same gateway.
+ */
+/**
+ * Caveat-type identifiers, kept in sync with the Go consts in
+ * gateway/internal/capability/token.go.
+ */
+declare const CaveatType: {
+    readonly EXPIRY: "exp";
+    readonly TOOL_ALLOW: "tool_allow";
+    readonly TOOL_DENY: "tool_deny";
+    readonly AGENT_LOCK: "agent_lock";
+    readonly MAX_CALLS: "max_calls";
+};
+/**
+ * A structured restriction recorded in a token's chain. Only fields
+ * relevant to the {@link type} are emitted; the rest are omitted from
+ * the JSON output (matching Go's `omitempty` tags).
+ *
+ * Field order on the wire: `t, tools, agent, exp, max_calls`. This
+ * matches Go's encoding/json declaration-order behavior and seeds
+ * the HMAC step that derives the child's signature.
+ */
+interface Caveat {
+    type: string;
+    tools?: string[];
+    agent?: string;
+    /** Unix seconds. */
+    expiry?: number;
+    maxCalls?: number;
+}
+declare class AttenuationError extends Error {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Decode a base64url(JSON) token into its parsed object. No signature
+ * check (the gateway does that). Useful for inspecting the chain —
+ * `decodeToken(t).cav` lists the caveats bound to the token.
+ */
+declare function decodeToken(token: string): Record<string, unknown>;
+interface AttenuateOptions {
+    /** Narrow to this tool whitelist (caveat type `tool_allow`). */
+    addTools?: string[];
+    /** Add a deny list (caveat type `tool_deny`). Additive on top of any parent deny. */
+    denyTools?: string[];
+    /** Cap remaining calls (caveat type `max_calls`). The chain enforces the minimum. */
+    maxCalls?: number;
+    /** Set absolute expiry (Unix seconds). Caveat type `exp`. */
+    expiresAt?: number;
+    /** Convenience: now + N seconds. Caveat type `exp`. */
+    expiresInSeconds?: number;
+    /** User-supplied caveats appended last (advanced). */
+    extra?: Caveat[];
+}
+/**
+ * Append narrowing caveats to a parent token and return a new token
+ * string that the gateway accepts as a cryptographic descendant of
+ * the parent.
+ *
+ * Each option groups one common attenuation pattern. Multiple options
+ * combine; each generates one caveat in this order:
+ *
+ *   1. `addTools`         → `tool_allow` caveat
+ *   2. `denyTools`        → `tool_deny` caveat
+ *   3. `maxCalls`         → `max_calls` caveat
+ *   4. `expiresAt` /      → `exp` caveat (absolute Unix seconds)
+ *      `expiresInSeconds`
+ *   5. `extra`            → user-supplied caveats appended last
+ *
+ * @example
+ * ```ts
+ * import { attenuate } from "@intentgate-app/intentgate";
+ *
+ * // Parent token: agent allowed [search, read, email] for 1h.
+ * // Child: only [search, read], one call max.
+ * const child = attenuate(parentToken, {
+ *   addTools: ["search", "read"],
+ *   maxCalls: 1,
+ * });
+ *
+ * // Hand `child` to the sub-agent.
+ * ```
+ */
+declare function attenuate(token: string, opts?: AttenuateOptions): string;
+
+export { type AttenuateOptions, AttenuationError, BudgetError, CapabilityError, type Caveat, CaveatType, type ContentBlock, type Envelope, Gateway, GatewayError, type GatewayOptions, IntentError, IntentGateError, type IntentGateMetadata, MemoryProvenanceError, type MemoryReadHook, MemoryStore, type MemoryWriteHook, PolicyError, ProtocolError, ProvenanceError, SESSION_KEY_SIZE, type ToolCallOptions, type ToolCallResult, ZERO_HASH, attenuate, canonical, decodeToken, deriveSessionKey, forCode, sign, verify, verifyChain };