@intentgate-app/intentgate 0.3.0

package/dist/index.js

@@ -0,0 +1,612 @@
+// src/errors.ts
+var IntentGateError = class extends Error {
+  /** JSON-RPC error code from the gateway, or 0 if client-side. */
+  code;
+  /** Optional structured payload from the gateway's `error.data`. */
+  data;
+  constructor(message, opts = {}) {
+    super(message, { cause: opts.cause });
+    this.name = "IntentGateError";
+    this.code = opts.code ?? 0;
+    this.data = opts.data;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /**
+   * 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() {
+    if (typeof this.data === "string" && this.data.length > 0) {
+      return `${this.message}: ${this.data}`;
+    }
+    return this.message;
+  }
+};
+var GatewayError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "GatewayError";
+  }
+};
+var ProtocolError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ProtocolError";
+  }
+};
+var CapabilityError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "CapabilityError";
+  }
+};
+var IntentError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "IntentError";
+  }
+};
+var PolicyError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "PolicyError";
+  }
+};
+var BudgetError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "BudgetError";
+  }
+};
+var ProvenanceError = class extends IntentGateError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ProvenanceError";
+  }
+};
+var CODE_TO_CLASS = {
+  [-32010]: CapabilityError,
+  [-32011]: IntentError,
+  [-32012]: PolicyError,
+  [-32013]: BudgetError,
+  [-32014]: ProvenanceError
+};
+function forCode(code) {
+  return CODE_TO_CLASS[code] ?? ProtocolError;
+}
+
+// src/client.ts
+var TOOLS_CALL_METHOD = "tools/call";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var Gateway = class {
+  url;
+  token;
+  timeoutMs;
+  fetchImpl;
+  nextId = 1;
+  constructor(url, opts = {}) {
+    if (!url) {
+      throw new Error("Gateway: url is required");
+    }
+    let cleaned = url;
+    while (cleaned.endsWith("/")) cleaned = cleaned.slice(0, -1);
+    this.url = cleaned;
+    this.token = opts.token;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "Gateway: no fetch available; pass `fetch` in options or run on Node 18+"
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async toolCall(tool, opts = {}) {
+    if (!tool) {
+      throw new Error("toolCall: tool is required");
+    }
+    const id = opts.requestId ?? this.nextId++;
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method: TOOLS_CALL_METHOD,
+      params: {
+        name: tool,
+        arguments: opts.arguments ?? {}
+      }
+    });
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (opts.intentPrompt) {
+      headers["X-Intent-Prompt"] = opts.intentPrompt;
+    }
+    if (opts.memoryProvenance && opts.memoryProvenance.length > 0) {
+      if (!opts.memoryStore) {
+        throw new Error(
+          "toolCall: memoryProvenance is non-empty but memoryStore is undefined; supply a MemoryStore so the SDK can look up the envelopes"
+        );
+      }
+      const wireEntries = opts.memoryStore.provenanceFor(opts.memoryProvenance);
+      headers["X-Intent-Memory-Provenance"] = Buffer.from(JSON.stringify(wireEntries)).toString(
+        "base64url"
+      );
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await this.fetchImpl(`${this.url}/v1/mcp`, {
+        method: "POST",
+        body,
+        headers,
+        signal: controller.signal
+      });
+    } catch (cause) {
+      const isAbort = cause instanceof Error && cause.name === "AbortError";
+      const msg = isAbort ? `gateway timed out after ${this.timeoutMs}ms` : `transport error reaching gateway: ${stringifyCause(cause)}`;
+      throw new GatewayError(msg, { cause });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!resp.ok) {
+      const text = await safeText(resp);
+      throw new GatewayError(`gateway returned HTTP ${resp.status}`, {
+        data: text || resp.statusText
+      });
+    }
+    let payload;
+    try {
+      payload = await resp.json();
+    } catch (cause) {
+      throw new GatewayError("non-JSON response from gateway", { cause });
+    }
+    return parseResponse(payload);
+  }
+};
+function stringifyCause(cause) {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+async function safeText(resp) {
+  try {
+    const t = await resp.text();
+    return t.slice(0, 500);
+  } catch {
+    return "";
+  }
+}
+function parseResponse(payload) {
+  if (!isObject(payload)) {
+    throw new ProtocolError("response is not a JSON object");
+  }
+  const err = payload["error"];
+  if (err != null) {
+    if (!isObject(err)) {
+      throw new ProtocolError("error field is not an object");
+    }
+    const code = typeof err["code"] === "number" ? err["code"] : 0;
+    const message = typeof err["message"] === "string" ? err["message"] : "gateway error";
+    const data = err["data"];
+    const Cls = forCode(code);
+    throw new Cls(message, { code, data });
+  }
+  const result = payload["result"];
+  if (!isObject(result)) {
+    throw new ProtocolError("response missing 'result' object", { data: payload });
+  }
+  const rawContent = Array.isArray(result["content"]) ? result["content"] : [];
+  const content = [];
+  for (const b of rawContent) {
+    if (!isObject(b)) continue;
+    content.push({
+      type: typeof b["type"] === "string" ? b["type"] : "",
+      text: typeof b["text"] === "string" ? b["text"] : void 0
+    });
+  }
+  let intentgate = null;
+  const ig = result["_intentgate"];
+  if (isObject(ig)) {
+    intentgate = {
+      decision: typeof ig["decision"] === "string" ? ig["decision"] : "",
+      reason: typeof ig["reason"] === "string" ? ig["reason"] : "",
+      check: typeof ig["check"] === "string" ? ig["check"] : "",
+      latencyMs: typeof ig["latency_ms"] === "number" ? ig["latency_ms"] : 0
+    };
+  }
+  return {
+    content,
+    isError: result["isError"] === true,
+    intentgate
+  };
+}
+function isObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+// src/capability.ts
+import { createHmac } from "crypto";
+var CaveatType = {
+  EXPIRY: "exp",
+  TOOL_ALLOW: "tool_allow",
+  TOOL_DENY: "tool_deny",
+  AGENT_LOCK: "agent_lock",
+  MAX_CALLS: "max_calls"
+};
+var AttenuationError = class extends Error {
+  constructor(message, opts) {
+    super(message, { cause: opts?.cause });
+    this.name = "AttenuationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function b64urlDecode(s) {
+  const standard = s.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = standard.length % 4 === 0 ? "" : "=".repeat(4 - standard.length % 4);
+  try {
+    return new Uint8Array(Buffer.from(standard + pad, "base64"));
+  } catch (cause) {
+    throw new AttenuationError(`invalid base64url: ${stringifyCause2(cause)}`, { cause });
+  }
+}
+function b64urlEncode(b) {
+  return Buffer.from(b).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function canonicalCaveatBytes(c) {
+  const obj = {};
+  obj["t"] = c.type;
+  if (c.tools && c.tools.length > 0) {
+    obj["tools"] = [...c.tools];
+  }
+  if (c.agent) {
+    obj["agent"] = c.agent;
+  }
+  if (c.expiry) {
+    obj["exp"] = Math.trunc(c.expiry);
+  }
+  if (c.maxCalls) {
+    obj["max_calls"] = Math.trunc(c.maxCalls);
+  }
+  const json = JSON.stringify(obj);
+  return new TextEncoder().encode(json);
+}
+function decodeToken(token) {
+  const raw = b64urlDecode(token);
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+  } catch (cause) {
+    throw new AttenuationError(`token JSON is malformed: ${stringifyCause2(cause)}`, {
+      cause
+    });
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new AttenuationError("token JSON is not an object");
+  }
+  return parsed;
+}
+function attenuate(token, opts = {}) {
+  const parsed = decodeToken(token);
+  if (typeof parsed["sig"] !== "string") {
+    throw new AttenuationError("token is missing 'sig' field");
+  }
+  if (!Array.isArray(parsed["cav"])) {
+    throw new AttenuationError("token is missing 'cav' field");
+  }
+  if (typeof parsed["root_jti"] !== "string" || parsed["root_jti"] === "") {
+    throw new AttenuationError(
+      "token has no root_jti (was it minted by gateway < v0.7?)"
+    );
+  }
+  if (typeof parsed["tenant"] !== "string" || parsed["tenant"] === "") {
+    throw new AttenuationError(
+      "token has no tenant (was it minted by gateway < v0.9?)"
+    );
+  }
+  const cavs = [...parsed["cav"]];
+  let sig = b64urlDecode(parsed["sig"]);
+  const newCaveats = [];
+  if (opts.addTools && opts.addTools.length > 0) {
+    newCaveats.push({ type: CaveatType.TOOL_ALLOW, tools: [...opts.addTools] });
+  }
+  if (opts.denyTools && opts.denyTools.length > 0) {
+    newCaveats.push({ type: CaveatType.TOOL_DENY, tools: [...opts.denyTools] });
+  }
+  if (opts.maxCalls !== void 0) {
+    if (opts.maxCalls < 0) {
+      throw new AttenuationError("maxCalls must be >= 0");
+    }
+    newCaveats.push({ type: CaveatType.MAX_CALLS, maxCalls: Math.trunc(opts.maxCalls) });
+  }
+  if (opts.expiresAt !== void 0 || opts.expiresInSeconds !== void 0) {
+    const exp = opts.expiresAt ?? Math.floor(Date.now() / 1e3) + (opts.expiresInSeconds ?? 0);
+    newCaveats.push({ type: CaveatType.EXPIRY, expiry: Math.trunc(exp) });
+  }
+  if (opts.extra && opts.extra.length > 0) {
+    newCaveats.push(...opts.extra);
+  }
+  if (newCaveats.length === 0) {
+    throw new AttenuationError(
+      "attenuate() requires at least one narrowing argument (addTools, denyTools, maxCalls, expiresInSeconds, expiresAt, or extra)"
+    );
+  }
+  for (const c of newCaveats) {
+    const cb = canonicalCaveatBytes(c);
+    sig = new Uint8Array(createHmac("sha256", sig).update(cb).digest());
+    cavs.push(JSON.parse(new TextDecoder().decode(cb)));
+  }
+  const child = { ...parsed };
+  child["cav"] = cavs;
+  child["sig"] = b64urlEncode(sig);
+  return b64urlEncode(new TextEncoder().encode(JSON.stringify(child)));
+}
+function stringifyCause2(cause) {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+// src/memory.ts
+import { createHmac as createHmac2, createHash, hkdfSync, timingSafeEqual, randomUUID } from "crypto";
+var DERIVATION_INFO = Buffer.from("intentgate-memory-v1");
+var SESSION_KEY_SIZE = 32;
+var HASH_SIZE = 32;
+var ZERO_HASH = Buffer.alloc(HASH_SIZE);
+var MemoryProvenanceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MemoryProvenanceError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function deriveSessionKey(masterKey, sessionId) {
+  if (!masterKey || masterKey.length === 0) {
+    throw new Error("deriveSessionKey: masterKey is empty");
+  }
+  if (!sessionId) {
+    throw new Error("deriveSessionKey: sessionId is empty");
+  }
+  const out = hkdfSync(
+    "sha256",
+    masterKey,
+    Buffer.from(sessionId, "utf8"),
+    DERIVATION_INFO,
+    SESSION_KEY_SIZE
+  );
+  return Buffer.from(out);
+}
+function canonical(env) {
+  const sid = Buffer.from(env.sessionId, "utf8");
+  const eid = Buffer.from(env.id, "utf8");
+  const total = 4 + sid.length + 4 + eid.length + 8 + 4 + env.prevHash.length + 4 + env.data.length;
+  const out = Buffer.alloc(total);
+  let off = 0;
+  out.writeUInt32BE(sid.length, off);
+  off += 4;
+  sid.copy(out, off);
+  off += sid.length;
+  out.writeUInt32BE(eid.length, off);
+  off += 4;
+  eid.copy(out, off);
+  off += eid.length;
+  out.writeBigUInt64BE(BigInt(env.timestamp) & 0xffffffffffffffffn, off);
+  off += 8;
+  out.writeUInt32BE(env.prevHash.length, off);
+  off += 4;
+  env.prevHash.copy(out, off);
+  off += env.prevHash.length;
+  out.writeUInt32BE(env.data.length, off);
+  off += 4;
+  env.data.copy(out, off);
+  return out;
+}
+function sign(sessionKey, env) {
+  if (!sessionKey || sessionKey.length === 0) {
+    throw new Error("sign: sessionKey is empty");
+  }
+  const mac = createHmac2("sha256", sessionKey);
+  mac.update(canonical(env));
+  return { ...env, hmac: mac.digest() };
+}
+function verify(sessionKey, env) {
+  if (!sessionKey || sessionKey.length === 0) {
+    throw new Error("verify: sessionKey is empty");
+  }
+  if (env.hmac.length !== HASH_SIZE) {
+    throw new MemoryProvenanceError(
+      `hmac field is ${env.hmac.length} bytes; expected ${HASH_SIZE}`
+    );
+  }
+  const expected = createHmac2("sha256", sessionKey).update(canonical(env)).digest();
+  if (!timingSafeEqual(expected, env.hmac)) {
+    throw new MemoryProvenanceError("hmac mismatch");
+  }
+}
+function verifyChain(sessionKey, chain) {
+  if (chain.length === 0) {
+    return;
+  }
+  for (let i = 0; i < chain.length; i++) {
+    const env = chain[i];
+    if (!env) continue;
+    try {
+      verify(sessionKey, env);
+    } catch (e) {
+      if (e instanceof MemoryProvenanceError) {
+        throw new MemoryProvenanceError(`entry ${i}: ${e.message}`);
+      }
+      throw e;
+    }
+    let expectedPrev;
+    if (i === 0) {
+      expectedPrev = ZERO_HASH;
+    } else {
+      const prev = chain[i - 1];
+      if (!prev) continue;
+      expectedPrev = createHash("sha256").update(canonical(prev)).digest();
+    }
+    if (!timingSafeEqual(expectedPrev, env.prevHash)) {
+      throw new MemoryProvenanceError(
+        `entry ${i}: prev_hash does not match previous entry's canonical hash`
+      );
+    }
+  }
+}
+var MemoryStore = class {
+  sessionId;
+  key;
+  fallback = /* @__PURE__ */ new Map();
+  writeHook;
+  readHook;
+  chainHead = ZERO_HASH;
+  /**
+   * @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, memorySigningKey, options = {}) {
+    if (!sessionId) {
+      throw new Error("MemoryStore: sessionId is required");
+    }
+    if (memorySigningKey.length !== SESSION_KEY_SIZE) {
+      throw new Error(
+        `MemoryStore: memorySigningKey must be ${SESSION_KEY_SIZE} bytes, got ${memorySigningKey.length}`
+      );
+    }
+    this.sessionId = sessionId;
+    this.key = Buffer.from(memorySigningKey);
+    this.writeHook = options.writeHook;
+    this.readHook = options.readHook;
+  }
+  /**
+   * 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) {
+    let payload;
+    if (Buffer.isBuffer(data)) {
+      payload = data;
+    } else if (typeof data === "string") {
+      payload = Buffer.from(data, "utf8");
+    } else {
+      payload = Buffer.from(stableStringify(data), "utf8");
+    }
+    const entryId = randomUUID().replaceAll("-", "");
+    const env = sign(this.key, {
+      id: entryId,
+      sessionId: this.sessionId,
+      timestamp: Date.now(),
+      data: payload,
+      prevHash: this.chainHead
+    });
+    if (this.writeHook !== void 0) {
+      this.writeHook(entryId, env);
+    } else {
+      this.fallback.set(entryId, env);
+    }
+    this.chainHead = createHash("sha256").update(canonical(env)).digest();
+    return entryId;
+  }
+  /**
+   * 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) {
+    let env;
+    if (this.readHook !== void 0) {
+      env = this.readHook(entryId);
+    } else {
+      env = this.fallback.get(entryId);
+      if (env === void 0) {
+        throw new Error(`MemoryStore: entry ${entryId} not found`);
+      }
+    }
+    verify(this.key, env);
+    return env;
+  }
+  /**
+   * 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) {
+    return entryIds.map((eid) => {
+      const env = this.read(eid);
+      return {
+        id: env.id,
+        session_id: env.sessionId,
+        ts: env.timestamp,
+        data: env.data.toString("base64url"),
+        prev_hash: env.prevHash.toString("base64url"),
+        hmac: env.hmac.toString("base64url")
+      };
+    });
+  }
+  /** Number of entries in the fallback in-memory store. */
+  get size() {
+    return this.fallback.size;
+  }
+};
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+export {
+  AttenuationError,
+  BudgetError,
+  CapabilityError,
+  CaveatType,
+  Gateway,
+  GatewayError,
+  IntentError,
+  IntentGateError,
+  MemoryProvenanceError,
+  MemoryStore,
+  PolicyError,
+  ProtocolError,
+  ProvenanceError,
+  SESSION_KEY_SIZE,
+  ZERO_HASH,
+  attenuate,
+  canonical,
+  decodeToken,
+  deriveSessionKey,
+  forCode,
+  sign,
+  verify,
+  verifyChain
+};
+//# sourceMappingURL=index.js.map