@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/interface/read-candid.test.ts

@@ -0,0 +1,300 @@
+// What a verified certificate proves, read through the agent-backed source,
+// and the agent `createReadAgent` builds. The certificate is stubbed (no BLS
+// signature), but each path is looked up with the agent's own `lookup_path`
+// over a hand-built hash tree, so a pruned branch answers Unknown and a
+// missing label Absent, as on the IC. No test here touches the network:
+// `fetch` is stubbed wherever the agent would send a request.
+import {
+  Cbor,
+  HttpFetchErrorCode,
+  IC_ROOT_KEY,
+  lookup_path,
+  NodeType,
+  TransportError,
+  type HashTree,
+  type HttpAgent,
+  type KnownPath,
+  type NodeHash,
+  type NodeLabel,
+  type NodeValue,
+} from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import type { CandidCli } from "./compile.ts"
+import { toHex } from "./hex.ts"
+import { createInterfaceLoader } from "./loader.ts"
+import {
+  agentCandidSource,
+  classifyReadError,
+  createReadAgent,
+  MAINNET_HOST,
+  UnprovenPathError,
+} from "./read-candid.ts"
+
+const ICP_LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+const LIFELINE = "rno2w-sqaaa-aaaaa-aaacq-cai"
+const LOCAL_HOST = "http://127.0.0.1:4943"
+const DID = "service : { icrc1_symbol : () -> (text) query }"
+const HASH = new Uint8Array(32).fill(0xa1)
+
+// The tree's byte types are branded; these are plain bytes.
+const utf8 = (text: string) => new TextEncoder().encode(text)
+const labelled = (bytes: Uint8Array, tree: HashTree): HashTree => [
+  NodeType.Labeled,
+  bytes as NodeLabel,
+  tree,
+]
+const label = (text: string, tree: HashTree): HashTree =>
+  labelled(utf8(text), tree)
+const leaf = (bytes: Uint8Array): HashTree => [
+  NodeType.Leaf,
+  bytes as NodeValue,
+]
+const fork = (left: HashTree, right: HashTree): HashTree => [
+  NodeType.Fork,
+  left,
+  right,
+]
+// What a party between the replica and the server can put in place of any
+// subtree without changing the root hash.
+const pruned: HashTree = [
+  NodeType.Pruned,
+  new Uint8Array(32).fill(7) as NodeHash,
+]
+
+type Part = "present" | "absent" | "pruned"
+
+// canister/<id>/{metadata/candid:service, module_hash}, labels in order.
+function treeOf(candid: Part, hash: Part): HashTree {
+  const metadata =
+    candid === "present"
+      ? label("candid:service", leaf(utf8(DID)))
+      : candid === "pruned"
+        ? label("candid:service", pruned)
+        : label("candid:args", leaf(utf8("()")))
+  const children = [label("metadata", metadata)]
+  if (hash === "present") children.push(label("module_hash", leaf(HASH)))
+  if (hash === "pruned") children.push(label("module_hash", pruned))
+  const [first, second] = children
+  if (first === undefined) throw new Error("unreachable")
+  return label(
+    "canister",
+    labelled(
+      Principal.fromText(ICP_LEDGER).toUint8Array(),
+      second === undefined ? first : fork(first, second)
+    )
+  )
+}
+
+/**
+ * An agent whose read_state answers with a certificate over `tree`. Its
+ * `values` map behaves as the agent's does (null for any lookup that is not
+ * Found), which is what the source must not rely on.
+ */
+function agentOver(tree: HashTree) {
+  const query = vi.fn(() => {
+    throw new Error("the tmp hack query was sent")
+  })
+  const agent = {
+    readState: vi.fn(async () => ({
+      certificate: new Uint8Array(),
+      verifiedCertificate: {
+        lookup_path: (path: Uint8Array[]) => lookup_path(path, tree),
+      },
+      values: {
+        get<T>(path: KnownPath<T>): T | null {
+          const found = lookup_path(path.path, tree)
+          return found.status === "Found" ? path.decode(found.value) : null
+        },
+      },
+    })),
+    query,
+  }
+  return { agent: agent as unknown as HttpAgent, query }
+}
+
+// None of these loads gets as far as a compile.
+const noCompiler: CandidCli = {
+  didToContract: () => Promise.reject(new Error("no compile expected")),
+  didToModule: () => Promise.reject(new Error("no compile expected")),
+  projectDid: () => Promise.reject(new Error("no compile expected")),
+  checkCompatible: () => Promise.reject(new Error("no compile expected")),
+}
+
+function loaderOver(tree: HashTree) {
+  const { agent, query } = agentOver(tree)
+  const loader = createInterfaceLoader({
+    source: agentCandidSource(agent),
+    cli: noCompiler,
+  })
+  return { loader, query }
+}
+
+describe("agentCandidSource", () => {
+  it("reads the candid:service and the module hash the certificate shows", async () => {
+    const { agent } = agentOver(treeOf("present", "present"))
+    const read = await agentCandidSource(agent).readCandidAndHash(ICP_LEDGER)
+    expect(read).toEqual({ did: DID, moduleHash: HASH })
+  })
+
+  it("gives null only for what the certificate proves absent", async () => {
+    const { agent } = agentOver(treeOf("absent", "absent"))
+    const source = agentCandidSource(agent)
+    expect(await source.readCandidAndHash(ICP_LEDGER)).toEqual({
+      did: null,
+      moduleHash: null,
+    })
+    expect(await source.readModuleHash(ICP_LEDGER)).toBeNull()
+  })
+
+  it.each([
+    ["a pruned candid:service", treeOf("pruned", "present")],
+    ["a pruned module_hash", treeOf("present", "pruned")],
+  ])("throws for %s, which proves nothing", async (_, tree) => {
+    const { agent } = agentOver(tree)
+    const error: unknown = await agentCandidSource(agent)
+      .readCandidAndHash(ICP_LEDGER)
+      .catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(UnprovenPathError)
+    expect(classifyReadError(error, "metadata")).toMatchObject({
+      kind: "failed",
+      code: "trust_error",
+    })
+  })
+
+  it("throws for a pruned module_hash read alone", async () => {
+    const { agent } = agentOver(treeOf("present", "pruned"))
+    await expect(
+      agentCandidSource(agent).readModuleHash(ICP_LEDGER)
+    ).rejects.toBeInstanceOf(UnprovenPathError)
+  })
+})
+
+describe("the loader over a pruned certificate", () => {
+  it("never takes a pruned candid:service for an absent one: no tmp hack", async () => {
+    const { loader, query } = loaderOver(treeOf("pruned", "present"))
+    expect(await loader.load(ICP_LEDGER)).toMatchObject({
+      ok: false,
+      code: "trust_error",
+    })
+    expect(query).not.toHaveBeenCalled()
+  })
+
+  it("never takes a pruned module_hash for 'no module installed'", async () => {
+    const { loader } = loaderOver(treeOf("absent", "pruned"))
+    expect(await loader.load(ICP_LEDGER)).toMatchObject({
+      ok: false,
+      code: "trust_error",
+    })
+  })
+
+  it("falls back only when the certificate proves the metadata absent", async () => {
+    const { loader, query } = loaderOver(treeOf("absent", "present"))
+    await loader.load(ICP_LEDGER)
+    expect(query).toHaveBeenCalled()
+  })
+})
+
+describe("classifyReadError", () => {
+  it("reports a request the bounded fetch stopped as a timeout", () => {
+    const stopped = TransportError.fromCode(
+      new HttpFetchErrorCode(
+        new DOMException(
+          "The operation was aborted due to timeout",
+          "TimeoutError"
+        )
+      )
+    )
+    expect(classifyReadError(stopped, "metadata")).toEqual({
+      kind: "failed",
+      code: "timeout",
+      message: "The IC did not answer within 10 s.",
+    })
+  })
+})
+
+describe("createReadAgent", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  /** Stubs `fetch` with `answer`, and returns the stub to inspect. */
+  function stubFetch(answer: (url: string) => Promise<Response>) {
+    const fetch = vi.fn((input: string | URL | Request, _init?: RequestInit) =>
+      answer(String(input))
+    )
+    vi.stubGlobal("fetch", fetch)
+    return fetch
+  }
+
+  it("checks certificates against mainnet's root key by default, and fetches nothing", async () => {
+    const fetch = stubFetch(() => Promise.reject(new Error("no request")))
+    const agent = await createReadAgent({
+      host: MAINNET_HOST,
+      fetchRootKey: false,
+    })
+    expect(toHex(agent.rootKey ?? new Uint8Array())).toBe(IC_ROOT_KEY)
+    expect(fetch).not.toHaveBeenCalled()
+  })
+
+  it("uses the root key it is given, which wins over fetching one", async () => {
+    const fetch = stubFetch(() => Promise.reject(new Error("no request")))
+    const key = new Uint8Array(133).fill(3)
+    const agent = await createReadAgent({
+      host: LOCAL_HOST,
+      rootKey: key,
+      fetchRootKey: true,
+    })
+    expect(agent.rootKey).toBe(key)
+    expect(fetch).not.toHaveBeenCalled()
+  })
+
+  it("fetches the root key from the host when asked, through the bounded fetch", async () => {
+    const key = new Uint8Array(133).fill(9)
+    const fetch = stubFetch(async () => {
+      const body = Cbor.encode({ root_key: key })
+      return new Response(new Uint8Array(body), { status: 200 })
+    })
+    const agent = await createReadAgent({
+      host: LOCAL_HOST,
+      fetchRootKey: true,
+    })
+    expect(toHex(agent.rootKey ?? new Uint8Array())).toBe(toHex(key))
+    expect(fetch).toHaveBeenCalledOnce()
+    const [url, init] = fetch.mock.calls[0] ?? []
+    expect(String(url)).toBe(`${LOCAL_HOST}/api/v2/status`)
+    expect(init?.signal).toBeInstanceOf(AbortSignal)
+  })
+
+  it("rejects, after one attempt, when the root key cannot be fetched", async () => {
+    const fetch = stubFetch(() => Promise.reject(new TypeError("fetch failed")))
+    await expect(
+      createReadAgent({ host: LOCAL_HOST, fetchRootKey: true })
+    ).rejects.toThrow(
+      /^Fetching the root key from http:\/\/127\.0\.0\.1:4943 failed: /
+    )
+    expect(fetch).toHaveBeenCalledOnce()
+  })
+
+  it("sends a refused read_state once, not three times over", async () => {
+    const fetch = stubFetch(
+      async () =>
+        new Response(
+          "Custom section candid:service can only be requested by the controllers of the canister.",
+          { status: 403, statusText: "Forbidden" }
+        )
+    )
+    const agent = await createReadAgent({
+      host: MAINNET_HOST,
+      fetchRootKey: false,
+    })
+    const error: unknown = await agentCandidSource(agent)
+      .readCandidAndHash(LIFELINE)
+      .catch((e: unknown) => e)
+    expect(classifyReadError(error, "metadata")).toEqual({ kind: "private" })
+    expect(fetch).toHaveBeenCalledOnce()
+    expect(String(fetch.mock.calls[0]?.[0])).toBe(
+      `${MAINNET_HOST}/api/v3/canister/${LIFELINE}/read_state`
+    )
+  })
+})

package/packages/mcp/src/interface/read-candid.ts

@@ -0,0 +1,259 @@
+// Reading a canister's Candid from the IC, on any network the server is
+// pointed at. The loader takes a `CandidSource`, so tests hand it a fake one
+// and never touch the network.
+import {
+  Actor,
+  AgentError,
+  HttpAgent,
+  HttpErrorCode,
+  HttpFetchErrorCode,
+  LookupPathStatus,
+  RejectError,
+  StatePaths,
+  TrustError,
+  type KnownPath,
+  type ReadStateResponse,
+} from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+import type { InterfaceErrorCode } from "./types.ts"
+
+/** Mainnet's API boundary nodes. */
+export const MAINNET_HOST = "https://icp-api.io"
+
+/** Each HTTP request to the IC gives up after this long. */
+export const REQUEST_TIMEOUT_MS = 10_000
+
+/**
+ * Where a canister's Candid comes from. The agent-backed source reads the
+ * IC; each method throws the agent's own errors, which `classifyReadError`
+ * sorts into the loader's error codes.
+ */
+export interface CandidSource {
+  /**
+   * One certified `read_state` of `candid:service` and `module_hash`: a
+   * `null` value means the certificate proves the path absent (no such
+   * metadata section, or no module installed). A path the certificate
+   * neither shows nor proves absent throws an `UnprovenPathError`.
+   */
+  readCandidAndHash(canisterId: string): Promise<{
+    did: string | null
+    moduleHash: Uint8Array | null
+  }>
+  /** A certified `read_state` of `module_hash` alone, read the same way. */
+  readModuleHash(canisterId: string): Promise<Uint8Array | null>
+  /**
+   * The canister's `__get_candid_interface_tmp_hack` query: the answer of
+   * one replica, not certified.
+   */
+  readTmpHack(canisterId: string): Promise<string>
+}
+
+/**
+ * A path a verified certificate leaves unproven: its tree holds neither the
+ * value nor a proof that there is none, only a pruned branch. An honest
+ * replica answers every path it was asked; a party between it and the
+ * server (a boundary node) can prune a genuine certificate without breaking
+ * its signature. `classifyReadError` reports it as `trust_error`, so the
+ * loader never takes it for an absence and falls back.
+ */
+export class UnprovenPathError extends Error {
+  override name = "UnprovenPathError"
+}
+
+/**
+ * A `CandidSource` over an agent (`createReadAgent`). Paths are built from
+ * the parsed principal, never from text.
+ */
+export function agentCandidSource(agent: HttpAgent): CandidSource {
+  return {
+    async readCandidAndHash(canisterId) {
+      const id = Principal.fromText(canisterId)
+      const candid = StatePaths.canisterCandid(id)
+      const hash = StatePaths.canisterModuleHash(id)
+      const response = await agent.readState(
+        { canisterId: id },
+        { paths: [candid, hash] }
+      )
+      return {
+        did: provenValue(response, candid, "candid:service"),
+        moduleHash: provenValue(response, hash, "module_hash"),
+      }
+    },
+    async readModuleHash(canisterId) {
+      const id = Principal.fromText(canisterId)
+      const hash = StatePaths.canisterModuleHash(id)
+      const response = await agent.readState(
+        { canisterId: id },
+        { paths: [hash] }
+      )
+      return provenValue(response, hash, "module_hash")
+    },
+    async readTmpHack(canisterId) {
+      const service = Actor.createActor<{
+        __get_candid_interface_tmp_hack: () => Promise<string>
+      }>(
+        ({ IDL: idl }) =>
+          idl.Service({
+            __get_candid_interface_tmp_hack: idl.Func(
+              [],
+              [idl.Text],
+              ["query"]
+            ),
+          }),
+        { agent, canisterId }
+      )
+      return service.__get_candid_interface_tmp_hack()
+    },
+  }
+}
+
+// The value at `path`, `null` only when the certificate proves it absent.
+// The agent's `values` map gives null for an unproven path too, so this
+// asks the verified certificate itself.
+function provenValue<T>(
+  response: ReadStateResponse,
+  path: KnownPath<T>,
+  label: string
+): T | null {
+  const found = response.verifiedCertificate.lookup_path(path.path)
+  switch (found.status) {
+    case LookupPathStatus.Found:
+      return path.decode(found.value)
+    case LookupPathStatus.Absent:
+      return null
+    default:
+      throw new UnprovenPathError(
+        `The certificate neither shows nor rules out the canister's ${label}.`
+      )
+  }
+}
+
+export interface ReadAgentOptions {
+  readonly host: string
+  /** The root key every certificate is checked against; mainnet's when absent and not fetched. */
+  readonly rootKey?: Uint8Array
+  /** Fetch the root key from `host` (a replica on this machine only). */
+  readonly fetchRootKey: boolean
+}
+
+/**
+ * The agent the loader reads with: anonymous, for `host`, every request
+ * bounded by `REQUEST_TIMEOUT_MS`, and `retryTimes: 0`. HttpAgent otherwise
+ * re-sends every non-2xx response (a 403 or a `canister_not_found` too)
+ * three times with backoff, which turns each miss into 3 to 5 seconds.
+ *
+ * Every certificate is verified against `rootKey` when it is given (it wins
+ * over `fetchRootKey`), else against the key `host` serves when
+ * `fetchRootKey` is set (fetched here, once: this rejects when it cannot
+ * be), else against the mainnet root key the agent has built in.
+ */
+export async function createReadAgent(
+  options: ReadAgentOptions
+): Promise<HttpAgent> {
+  const fetchKey = options.rootKey === undefined && options.fetchRootKey
+  const agent = HttpAgent.createSync({
+    host: options.host,
+    retryTimes: 0,
+    fetch: boundedFetch,
+    ...(options.rootKey === undefined
+      ? { shouldFetchRootKey: fetchKey }
+      : { rootKey: options.rootKey }),
+  })
+  if (fetchKey) {
+    try {
+      await agent.fetchRootKey()
+    } catch (error) {
+      throw new Error(
+        `Fetching the root key from ${options.host} failed: ${agentMessage(error)}`,
+        { cause: error }
+      )
+    }
+  }
+  return agent
+}
+
+const boundedFetch: typeof fetch = (input, init) => {
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  const signal =
+    init?.signal != null ? AbortSignal.any([init.signal, timeout]) : timeout
+  return fetch(input, { ...init, signal })
+}
+
+/** Which read failed, for `classifyReadError`. */
+export type ReadStage = "metadata" | "module_hash" | "tmp_hack"
+
+/** A read failure, sorted into what the loader does next. */
+export type ReadError =
+  /** `candid:service` is readable by the canister's controllers only. */
+  | { kind: "private" }
+  /** The tmp hack query was rejected: the canister has no such method. */
+  | { kind: "no_tmp_hack" }
+  | { kind: "failed"; code: InterfaceErrorCode; message: string }
+
+/**
+ * Sorts an error thrown by a `CandidSource` read. A `TrustError` (a
+ * certificate or signature that did not verify) and an `UnprovenPathError`
+ * are always `trust_error`, at every stage, so the loader never falls back
+ * past them. A 403 at the metadata stage is `private`: it is not signed,
+ * so it only ever leads to the labelled, uncertified tmp hack.
+ */
+export function classifyReadError(error: unknown, stage: ReadStage): ReadError {
+  if (error instanceof TrustError || error instanceof UnprovenPathError) {
+    return {
+      kind: "failed",
+      code: "trust_error",
+      message: `The IC's answer did not verify, so it was not used: ${agentMessage(error)}`,
+    }
+  }
+  if (error instanceof AgentError && error.code instanceof HttpErrorCode) {
+    const { status, bodyText = "" } = error.code
+    if (status === 403 && stage === "metadata") return { kind: "private" }
+    if (status === 400 && bodyText.includes("canister_not_found")) {
+      return {
+        kind: "failed",
+        code: "canister_not_found",
+        message: "No canister has this id on the network the server reads.",
+      }
+    }
+    return {
+      kind: "failed",
+      code: "network",
+      message: `The IC answered HTTP ${status}: ${bodyText.slice(0, 200) || error.code.statusText}`,
+    }
+  }
+  if (stage === "tmp_hack" && error instanceof RejectError) {
+    return { kind: "no_tmp_hack" }
+  }
+  if (isRequestTimeout(error)) {
+    return {
+      kind: "failed",
+      code: "timeout",
+      message: `The IC did not answer within ${REQUEST_TIMEOUT_MS / 1000} s.`,
+    }
+  }
+  return {
+    kind: "failed",
+    code: "network",
+    message: `Reading the interface failed: ${agentMessage(error)}`,
+  }
+}
+
+// The agent wraps a failed fetch, so the abort of `boundedFetch` arrives as
+// an HttpFetchErrorCode holding the TimeoutError.
+function isRequestTimeout(error: unknown): boolean {
+  const cause =
+    error instanceof AgentError && error.code instanceof HttpFetchErrorCode
+      ? error.code.error
+      : error
+  // A DOMException, which is not an Error subclass in every runtime.
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    Reflect.get(cause, "name") === "TimeoutError"
+  )
+}
+
+function agentMessage(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error)
+  return text.split("\n")[0]?.slice(0, 200) ?? ""
+}

package/packages/mcp/src/interface/types.ts

@@ -0,0 +1,113 @@
+// The contract of the interface loader: what the server gets for a canister
+// id. Plain data plus the schemas built from the canister's .did.
+import type { AnyFieldSchema, AnySchema, MethodMode } from "@meantjs/schema"
+
+/** Where a canister's interface came from, and how far it can be trusted. */
+export type InterfaceProvenance =
+  /** `candid:service` metadata, read with a certified `read_state`. */
+  | {
+      readonly kind: "metadata"
+      readonly certified: true
+      readonly moduleHash: string | null
+    }
+  /**
+   * The `__get_candid_interface_tmp_hack` query: one replica's answer, NOT
+   * certified. Only when the certificate proves the metadata absent, or the
+   * metadata is readable by the canister's controllers only (a 403).
+   */
+  | {
+      readonly kind: "tmp_hack"
+      readonly certified: false
+      readonly moduleHash: string | null
+      readonly reason: "absent" | "private"
+    }
+  /** A `.did` file the person named on the command line (`--did`). */
+  | { readonly kind: "file"; readonly certified: false; readonly path: string }
+
+/** One callable method. */
+export interface MethodInfo {
+  readonly name: string
+  readonly mode: MethodMode
+  readonly args: readonly AnyFieldSchema[]
+  readonly results: readonly AnyFieldSchema[]
+  /**
+   * The method's doc comment in the .did, when it has one: the `///` (or
+   * `//`) lines just above it, as the compiler reads them.
+   */
+  readonly doc?: string
+}
+
+export interface CanisterInterface {
+  readonly canisterId: string
+  readonly provenance: InterfaceProvenance
+  /** The .did text. */
+  readonly did: string
+  /** sha256 of the .did's UTF-8 bytes, hex. */
+  readonly didSha256: string
+  /** `candid-core:interface:v1:sha256:…`: equal ids, the same interface. */
+  readonly interfaceId: string
+  /** The service schema: what `client.canister()` takes. */
+  readonly actor: AnySchema
+  /** Every callable method, by name, in name order. Map-backed: names are canister text. */
+  readonly methods: ReadonlyMap<string, MethodInfo>
+  /** Declarations and methods the schema loader left out, and why. */
+  readonly omitted: readonly {
+    readonly kind: "declaration" | "method"
+    readonly name: string
+    readonly reason: string
+    readonly via?: string
+  }[]
+  /** When it was read or last confirmed by its module hash (ms since the epoch). */
+  readonly loadedAt: number
+}
+
+export type InterfaceErrorCode =
+  | "invalid_canister_id"
+  | "management_canister"
+  | "no_interface"
+  | "private_interface"
+  | "canister_not_found"
+  | "too_large"
+  | "compile_failed"
+  | "network"
+  | "trust_error"
+  | "timeout"
+  | "file_error"
+
+export type LoadResult =
+  | { readonly ok: true; readonly iface: CanisterInterface }
+  | {
+      readonly ok: false
+      readonly canisterId: string
+      readonly code: InterfaceErrorCode
+      readonly message: string
+      readonly diagnostics?: readonly {
+        readonly code: string
+        readonly message: string
+      }[]
+    }
+
+export interface LoadOptions {
+  /**
+   * Confirm the module hash against the canister now, whatever the cache's
+   * age, and fail rather than answer from the cache when that read fails.
+   * For a write: the call is built from the interface of the module that is
+   * installed when the person is asked.
+   */
+  readonly fresh?: boolean
+}
+
+export interface InterfaceLoader {
+  /** A canister's interface, cached; never throws. */
+  load(canisterId: string, options?: LoadOptions): Promise<LoadResult>
+  /** The method's part of the .did (the method and every type it uses), cached. */
+  methodDid(
+    iface: CanisterInterface,
+    method: string
+  ): Promise<
+    | { readonly ok: true; readonly did: string }
+    | { readonly ok: false; readonly message: string }
+  >
+  /** Stops the compiler worker. */
+  close(): Promise<void>
+}