@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/tests/management.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Calls to the management canister (`aaaaa-aa`): each is routed by the
+ * effective canister id its method's row of the table names (D22, DECISIONS
+ * Q13), as the fake replica's request log shows, and a call the table cannot
+ * route is refused before anything is sent.
+ *
+ * The interface is the real one: `fixtures/management.did` is `ic.did` from
+ * dfinity/portal.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest"
+import {
+  principal,
+  resolveSchema,
+  serviceMethods,
+  type AnyFieldSchema,
+} from "@meantjs/schema"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import { EFFECTIVE_ID_FIELD } from "../src/management.js"
+import {
+  LEDGER,
+  MANAGEMENT,
+  SHAPES,
+  canisterRequests,
+  clientAs,
+  replicaWith,
+  serve,
+} from "./canister-helpers.js"
+import * as management from "./fixtures/management.js"
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const controller = Ed25519KeyIdentity.generate()
+const TARGET = principal(SHAPES)
+const STORE = principal(LEDGER)
+const CREATED = principal("bkyz2-fmaaa-aaaaa-qaaaq-cai")
+
+function setup() {
+  const replica = replicaWith({
+    [MANAGEMENT]: serve<management.Actor>(management.actor, {
+      start_canister: () => undefined,
+      fetch_canister_logs: () => ({ canister_log_records: [] }),
+      install_chunked_code: () => undefined,
+      provisional_create_canister_with_cycles: ([arg]) => ({
+        canister_id: arg.specified_id ?? CREATED,
+      }),
+    }),
+  })
+  const ic = clientAs(replica, controller).canister<management.Actor>(
+    management.actor,
+    { id: MANAGEMENT }
+  )
+  return { replica, ic }
+}
+
+describe("the effective canister id of a management call", () => {
+  it("is the canister_id of the argument, for an update", async () => {
+    const { replica, ic } = setup()
+    await expect(
+      ic.start_canister({ canister_id: TARGET })
+    ).resolves.toBeUndefined()
+    expect(canisterRequests(replica)).toMatchObject([
+      {
+        endpoint: "call",
+        canisterId: MANAGEMENT,
+        effectiveCanisterId: TARGET,
+        methodName: "start_canister",
+      },
+    ])
+  })
+
+  it("is the canister_id of the argument, for a query", async () => {
+    const { replica, ic } = setup()
+    await expect(
+      ic.fetch_canister_logs({ canister_id: TARGET })
+    ).resolves.toEqual({ canister_log_records: [] })
+    expect(canisterRequests(replica)).toMatchObject([
+      {
+        endpoint: "query",
+        canisterId: MANAGEMENT,
+        effectiveCanisterId: TARGET,
+      },
+    ])
+  })
+
+  it("is the target_canister of install_chunked_code, not its store_canister", async () => {
+    const { replica, ic } = setup()
+    await ic.install_chunked_code({
+      mode: { tag: "install" },
+      target_canister: TARGET,
+      store_canister: STORE,
+      chunk_hashes_list: [],
+      wasm_module_hash: new Uint8Array(32),
+      arg: new Uint8Array(),
+      sender_canister_version: null,
+    })
+    expect(canisterRequests(replica)).toMatchObject([
+      { canisterId: MANAGEMENT, effectiveCanisterId: TARGET },
+    ])
+  })
+
+  it("is the specified_id of provisional_create_canister_with_cycles", async () => {
+    const { replica, ic } = setup()
+    await expect(
+      ic.provisional_create_canister_with_cycles({
+        amount: null,
+        settings: null,
+        specified_id: CREATED,
+        sender_canister_version: null,
+      })
+    ).resolves.toEqual({ canister_id: CREATED })
+    expect(canisterRequests(replica)).toMatchObject([
+      { canisterId: MANAGEMENT, effectiveCanisterId: CREATED },
+    ])
+  })
+
+  it("cannot be chosen for provisional_create_canister_with_cycles without specified_id: refused, nothing sent", async () => {
+    const { replica, ic } = setup()
+    const error = await ic
+      .provisional_create_canister_with_cycles({
+        amount: null,
+        settings: null,
+        specified_id: null,
+        sender_canister_version: null,
+      })
+      .catch((e: unknown) => e)
+    expect(error).toMatchObject({
+      kind: "invalid_args",
+      code: "effective_canister_id_unknown",
+      mayHaveExecuted: false,
+    })
+    expect((error as Error).message).toContain("specified_id")
+    expect(replica.requests).toEqual([])
+  })
+
+  it("is refused, before anything is sent, for every method the table has no row for", async () => {
+    const { replica, ic } = setup()
+    const unrouted = [...serviceMethods(management.actor).keys()].filter(
+      (method) => !(method in EFFECTIVE_ID_FIELD)
+    )
+    // The canister-only methods and the two that take any principal.
+    expect(unrouted.sort()).toEqual(
+      [
+        "bitcoin_get_balance",
+        "bitcoin_get_block_headers",
+        "bitcoin_get_current_fee_percentiles",
+        "bitcoin_get_utxos",
+        "bitcoin_send_transaction",
+        "canister_info",
+        "canister_metadata",
+        "create_canister",
+        "deposit_cycles",
+        "ecdsa_public_key",
+        "http_request",
+        "list_canisters",
+        "node_metrics_history",
+        "raw_rand",
+        "schnorr_public_key",
+        "sign_with_ecdsa",
+        "sign_with_schnorr",
+        "subnet_info",
+        "vetkd_derive_key",
+        "vetkd_public_key",
+      ].sort()
+    )
+    for (const method of unrouted) {
+      const call = (ic as unknown as Record<string, () => Promise<unknown>>)[
+        method
+      ]
+      await expect(call()).rejects.toMatchObject({
+        kind: "invalid_args",
+        code: "effective_canister_id_unknown",
+        canisterId: MANAGEMENT,
+        method,
+      })
+    }
+    expect(replica.requests).toEqual([])
+  })
+})
+
+describe("the routing table", () => {
+  const resolve = (schema: AnyFieldSchema) => resolveSchema(schema)
+
+  it("names, for each of its methods, a principal field the method's argument really has", () => {
+    const methods = serviceMethods(management.actor)
+    for (const [method, field] of Object.entries(EFFECTIVE_ID_FIELD)) {
+      const spec = methods.get(method)
+      expect(spec, method).toBeDefined()
+      const arg = resolve(spec!.args[0])
+      expect(arg.kind, method).toBe("record")
+      const fields = (arg as { fields: Record<string, AnyFieldSchema> }).fields
+      expect(Object.keys(fields), method).toContain(field)
+      let node = resolve(fields[field])
+      // specified_id is `opt principal`: the id when it is given.
+      if (field === "specified_id") {
+        expect(node.kind, method).toBe("opt")
+        node = resolve((node as { inner: AnyFieldSchema }).inner)
+      }
+      expect(node, method).toMatchObject({
+        kind: "primitive",
+        primitive: "principal",
+      })
+    }
+  })
+})

package/packages/core/tests/network-helpers.ts

@@ -0,0 +1,121 @@
+/**
+ * Fixtures for the network tests: a fake page, the `ic_env` cookie it carries,
+ * and the process environment a server reads.
+ *
+ * The page and the cookie are faked at the global the code reads
+ * (`window`, `document.cookie`, `location`), and the cookie is parsed by the
+ * real `safeGetCanisterEnv`, so the tests cover the cookie's format as well as
+ * the decision about whether to read it.
+ */
+import { vi } from "vitest"
+
+/**
+ * A recognisable root key of the length the cookie reader accepts (133 bytes),
+ * so a key taken from the cookie is distinguishable from the mainnet key the
+ * agent ships with and from the key a replica reports. Any 133 bytes satisfy
+ * the reader, which is exactly why the cookie is not evidence of anything.
+ */
+export const COOKIE_ROOT_KEY = new Uint8Array(133).fill(7)
+
+/** The key a fake replica reports on `/api/v2/status`. */
+export const REPLICA_ROOT_KEY = new Uint8Array(133).fill(9)
+
+/** A key a caller hands in, distinct from the other two. */
+export const GIVEN_ROOT_KEY = new Uint8Array(133).fill(5)
+
+/** The id an attacker-writable cookie would carry. */
+export const COOKIE_CANISTER_ID = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+
+export const hex = (bytes: Uint8Array): string =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")
+
+export const sameBytes = (
+  a: Uint8Array | null | undefined,
+  b: Uint8Array
+): boolean =>
+  a !== null &&
+  a !== undefined &&
+  a.length === b.length &&
+  a.every((byte, i) => byte === b[i])
+
+/**
+ * The value of a `document.cookie` carrying `ic_env`, as an asset canister or
+ * the Vite plugin writes it: URL-encoded `name=value` pairs joined by `&`, the
+ * root key as hex.
+ */
+export const icEnvCookie = (
+  entries: Record<string, string> = {
+    "PUBLIC_CANISTER_ID:backend": COOKIE_CANISTER_ID,
+  },
+  rootKey: Uint8Array | null = COOKIE_ROOT_KEY
+): string => {
+  const pairs = Object.entries(entries).map(([k, v]) => `${k}=${v}`)
+  if (rootKey) pairs.unshift(`ic_root_key=${hex(rootKey)}`)
+  return `ic_env=${encodeURIComponent(pairs.join("&"))}`
+}
+
+export interface FakePage {
+  /** How many times the code read `document.cookie`. */
+  readonly cookieReads: () => number
+}
+
+/**
+ * Makes the code run in a browser page at `origin`, whose `document.cookie` is
+ * `cookie` (the `ic_env` cookie by default). Undo with `vi.unstubAllGlobals()`.
+ */
+export const stubPage = (
+  origin: string,
+  { cookie = icEnvCookie() }: { cookie?: string } = {}
+): FakePage => {
+  let reads = 0
+  vi.stubGlobal("window", {
+    location: { origin, protocol: new URL(origin).protocol },
+  })
+  vi.stubGlobal("document", {
+    get cookie() {
+      reads++
+      return cookie
+    },
+  })
+  return { cookieReads: () => reads }
+}
+
+/**
+ * Makes the code run where there is no `window` but a cookie jar exists to
+ * read: a server (or worker) that a careless reader would still find a
+ * `document` on. `location` is a web worker's, when given.
+ */
+export const stubNoWindow = ({
+  cookie = icEnvCookie(),
+  workerOrigin,
+}: { cookie?: string; workerOrigin?: string } = {}): FakePage => {
+  let reads = 0
+  vi.stubGlobal("window", undefined)
+  vi.stubGlobal("document", {
+    get cookie() {
+      reads++
+      return cookie
+    },
+  })
+  vi.stubGlobal("location", workerOrigin ? { origin: workerOrigin } : undefined)
+  return { cookieReads: () => reads }
+}
+
+/**
+ * Clears the variables a server reads, so a developer's shell cannot change a
+ * result, then sets those given. Undo with `vi.unstubAllEnvs()`.
+ */
+export const stubProcessEnv = (
+  env: Partial<
+    Record<"ICP_NETWORK" | "DFX_NETWORK" | "ICP_HOST" | "IC_HOST", string>
+  > = {}
+): void => {
+  for (const name of [
+    "ICP_NETWORK",
+    "DFX_NETWORK",
+    "ICP_HOST",
+    "IC_HOST",
+  ] as const) {
+    vi.stubEnv(name, env[name])
+  }
+}

package/packages/core/tests/network.test-d.ts

@@ -0,0 +1,78 @@
+/**
+ * Type-level tests for the network surface: `Network` is the one public type,
+ * and what the client builds agents from fits `HttpAgentOptions` as it is.
+ * Checked by `tsc` (the package's `typecheck`), not run.
+ */
+import type { HttpAgentOptions } from "@icp-sdk/core/agent"
+import { expectTypeOf } from "vitest"
+import type { Network } from "../src/index.js"
+import {
+  agentOptionsFor,
+  resolveCanisterId,
+  resolveNetwork,
+  type CanisterIdFailure,
+  type ResolvedNetwork,
+} from "../src/network.js"
+
+// The four shapes a network can take.
+const _ic: Network = "ic"
+const _local: Network = "local"
+const _env: Network = "env"
+const _host: Network = { host: "https://testnet.example.com" }
+const _full: Network = {
+  host: "http://127.0.0.1:4943",
+  rootKey: new Uint8Array(133),
+  name: "dev",
+  fetchRootKey: false,
+}
+
+// @ts-expect-error a network is one of the names, not any string
+const _unknown: Network = "mainnet"
+// @ts-expect-error a custom network needs a host
+const _noHost: Network = { rootKey: new Uint8Array(133) }
+// @ts-expect-error a root key is bytes, not hex text
+const _hexKey: Network = { host: "https://x.example.com", rootKey: "00ff" }
+const _fetchText: Network = {
+  host: "https://x.example.com",
+  // @ts-expect-error fetchRootKey is a boolean
+  fetchRootKey: "yes",
+}
+const _legacy: Network = {
+  host: "https://x.example.com",
+  // @ts-expect-error the v3 spelling is not carried over
+  allowEnvRootKey: true,
+}
+
+// @ts-expect-error `allowEnvConfig` is the only opt-in; the v3 spelling is not carried over
+resolveNetwork("env", { allowEnvRootKey: true })
+
+// Only the type is public: the resolver is for the client, not for apps.
+// @ts-expect-error not exported from the package entry
+import { resolveNetwork as _leaked } from "../src/index.js"
+
+// What the client builds an agent from fits the agent's own options as is.
+const _options: HttpAgentOptions = agentOptionsFor(resolveNetwork("local"))
+expectTypeOf(
+  agentOptionsFor(resolveNetwork("ic")).shouldFetchRootKey
+).toEqualTypeOf<boolean>()
+expectTypeOf(resolveNetwork("ic")).toEqualTypeOf<ResolvedNetwork>()
+expectTypeOf(resolveNetwork("ic").rootKey).toEqualTypeOf<
+  Uint8Array | undefined
+>()
+
+// A failure says which of three problems it was, and a success narrows to an id.
+expectTypeOf<CanisterIdFailure>().toEqualTypeOf<
+  "no_browser" | "untrusted_host" | "absent"
+>()
+const resolution = resolveCanisterId({ name: "backend" }, resolveNetwork("env"))
+if (resolution.ok) {
+  expectTypeOf(resolution.id).toEqualTypeOf<string>()
+  expectTypeOf(resolution).not.toHaveProperty("reason")
+} else {
+  expectTypeOf(resolution.reason).toEqualTypeOf<CanisterIdFailure>()
+  expectTypeOf(resolution.message).toEqualTypeOf<string>()
+  expectTypeOf(resolution).not.toHaveProperty("id")
+}
+
+// @ts-expect-error a target is { id } or { name }
+resolveCanisterId({ address: "x" }, resolveNetwork("ic"))