@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/e2e/src/declarations/hello_actor.envelope.json

@@ -0,0 +1,175 @@
+{
+  "contract": {
+    "actor": {
+      "kind": "service",
+      "service": 0
+    },
+    "canonicalization_profile": "candid-core-canon-1",
+    "declarations": [],
+    "format": "candid-core",
+    "format_version": 1,
+    "identities": {
+      "contract": "candid-core:contract:v1:sha256:3c269a3883246042ec21a9326cfc89966d171232cb97404252dbb5953c857f68",
+      "interface": "candid-core:interface:v1:sha256:d0f851dbcd30a25d32b59eba0e0c37265ec3a01023b97fb94d160fc77a930059"
+    },
+    "producer": {
+      "candid_parser_version": "0.4.0",
+      "candid_version": "0.10.30",
+      "name": "meant",
+      "version": "0.1.0"
+    },
+    "semantics_profile": "candid-1",
+    "types": [
+      {
+        "kind": "service",
+        "methods": [
+          {
+            "function": 1,
+            "id": 838796847,
+            "name": "increment"
+          },
+          {
+            "function": 3,
+            "id": 1092322347,
+            "name": "boom"
+          },
+          {
+            "function": 4,
+            "id": 1248019663,
+            "name": "count"
+          },
+          {
+            "function": 5,
+            "id": 2582449865,
+            "name": "greet"
+          },
+          {
+            "function": 7,
+            "id": 2677914640,
+            "name": "is_replicated"
+          },
+          {
+            "function": 9,
+            "id": 3217878399,
+            "name": "whoami"
+          },
+          {
+            "function": 11,
+            "id": 3993120039,
+            "name": "increment_by"
+          },
+          {
+            "function": 3,
+            "id": 4293699796,
+            "name": "refuse"
+          }
+        ]
+      },
+      {
+        "args": [],
+        "kind": "func",
+        "mode": "update",
+        "results": [
+          2
+        ]
+      },
+      {
+        "kind": "primitive",
+        "primitive": "nat"
+      },
+      {
+        "args": [],
+        "kind": "func",
+        "mode": "update",
+        "results": []
+      },
+      {
+        "args": [],
+        "kind": "func",
+        "mode": "query",
+        "results": [
+          2
+        ]
+      },
+      {
+        "args": [
+          6
+        ],
+        "kind": "func",
+        "mode": "query",
+        "results": [
+          6
+        ]
+      },
+      {
+        "kind": "primitive",
+        "primitive": "text"
+      },
+      {
+        "args": [],
+        "kind": "func",
+        "mode": "query",
+        "results": [
+          8
+        ]
+      },
+      {
+        "kind": "primitive",
+        "primitive": "bool"
+      },
+      {
+        "args": [],
+        "kind": "func",
+        "mode": "query",
+        "results": [
+          10
+        ]
+      },
+      {
+        "kind": "primitive",
+        "primitive": "principal"
+      },
+      {
+        "args": [
+          12
+        ],
+        "kind": "func",
+        "mode": "update",
+        "results": [
+          13
+        ]
+      },
+      {
+        "kind": "primitive",
+        "primitive": "nat64"
+      },
+      {
+        "fields": [
+          {
+            "id": 17724,
+            "type": 2
+          },
+          {
+            "id": 3456837,
+            "type": 6
+          }
+        ],
+        "kind": "variant"
+      }
+    ]
+  },
+  "extensions": {
+    "org.candid-core.field-names/v1": [
+      [
+        13,
+        17724,
+        "Ok"
+      ],
+      [
+        13,
+        3456837,
+        "Err"
+      ]
+    ]
+  }
+}

package/e2e/src/declarations/hello_actor.ts

@@ -0,0 +1,15 @@
+// Generated by Meant from a Meant Contract. Do not edit.
+import * as $ from "@meantjs/schema";
+
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ increment: $.c.func([], [$.c.nat], "update"), boom: $.c.func([], [], "update"), count: $.c.func([], [$.c.nat], "query"), greet: $.c.func([$.c.text], [$.c.text], "query"), is_replicated: $.c.func([], [$.c.bool], "query"), whoami: $.c.func([], [$.c.principal], "query"), increment_by: $.c.func([$.c.nat64], [$.c.variant({ Ok: $.c.nat, Err: $.c.text })], "update"), refuse: $.c.func([], [], "update") }));
+export type Actor = {
+  increment: (() => Promise<bigint>) & $.WithMode<"update">;
+  boom: (() => Promise<void>) & $.WithMode<"update">;
+  count: (() => Promise<bigint>) & $.WithMode<"query">;
+  greet: ((arg0: string) => Promise<string>) & $.WithMode<"query">;
+  is_replicated: (() => Promise<boolean>) & $.WithMode<"query">;
+  whoami: (() => Promise<$.Principal>) & $.WithMode<"query">;
+  increment_by: ((arg0: bigint) => Promise<{ tag: "Ok"; value: bigint } | { tag: "Err"; value: string }>) & $.WithMode<"update">;
+  refuse: (() => Promise<void>) & $.WithMode<"update">;
+};
+export { $actor as actor };

package/e2e/src/errors.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Failures on the real replica, as `ReactorError`s: a reject 4 from
+ * `ic0.msg_reject`, a trap (reject 5), the `Err` arm of a Result (Q7), an
+ * anonymous write refused before sending, and a `{ name }` with no id.
+ */
+import { createClient } from "@ic-reactor/core"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "./declarations/hello_actor"
+import { ANONYMOUS, ed25519, network, rejection, target } from "./replica"
+
+const clients: { dispose(): void }[] = []
+const signedIn = () => {
+  const client = createClient({ network, identity: ed25519() })
+  clients.push(client)
+  return client
+}
+afterEach(() => {
+  for (const client of clients.splice(0)) client.dispose()
+})
+
+describe("failures on the local replica", () => {
+  it("a reject from ic0.msg_reject is `rejected` with code 4, and the update may have executed", async () => {
+    const hello = signedIn().canister<Actor>(actor, target)
+
+    const error = await rejection(hello.refuse())
+    expect(error).toMatchObject({
+      name: "ReactorError",
+      kind: "rejected",
+      rejectCode: 4,
+      mayHaveExecuted: true,
+      method: "refuse",
+      canisterId: target.id,
+    })
+    expect(error.message).toContain("refused: this method always rejects")
+  })
+
+  it("a trap is `rejected` with code 5, and the update may have executed", async () => {
+    const hello = signedIn().canister<Actor>(actor, target)
+
+    const error = await rejection(hello.boom())
+    expect(error).toMatchObject({
+      kind: "rejected",
+      rejectCode: 5,
+      mayHaveExecuted: true,
+      method: "boom",
+    })
+    expect(error.message).toContain("boom: this method always traps")
+  })
+
+  it("a Result resolves with its `Ok` value and rejects `canister_err` with its `Err` value, which did not leave the outcome open (Q7)", async () => {
+    const hello = signedIn().canister<Actor>(actor, target)
+
+    const ok = await hello.increment_by(2n)
+    expect(typeof ok).toBe("bigint")
+
+    const error = await rejection(hello.increment_by(0n))
+    expect(error).toMatchObject({
+      kind: "canister_err",
+      err: "by must be positive",
+      mayHaveExecuted: false,
+      method: "increment_by",
+    })
+    expect(error.rejectCode).toBeUndefined()
+    // The Err arm changed nothing.
+    await expect(hello.count()).resolves.toBe(ok)
+  })
+
+  it("an anonymous write is refused before it is sent", async () => {
+    const client = createClient({ network, identity: "anonymous" })
+    clients.push(client)
+    const hello = client.canister<Actor>(actor, target)
+    expect(client.caller()).toBe(ANONYMOUS)
+
+    const before = await hello.count()
+    const error = await rejection(hello.increment())
+    expect(error).toMatchObject({
+      kind: "unauthenticated",
+      code: "anonymous_write",
+      mayHaveExecuted: false,
+      method: "increment",
+    })
+    // The replica takes anonymous updates: had the call gone out, the
+    // counter would have moved.
+    await expect(hello.count()).resolves.toBe(before)
+  })
+
+  it("an unresolved `{ name }` target rejects `invalid_args` (canister_id_unresolved)", async () => {
+    const client = createClient({ network, identity: ed25519() })
+    clients.push(client)
+    // This page is local and so is the replica, so the ic_env cookie is
+    // trusted, and it has no entry for this name.
+    const missing = client.canister<Actor>(actor, { name: "not_deployed" })
+
+    for (const call of [
+      () => missing.greet("nobody"),
+      () => missing.increment(),
+    ]) {
+      const error = await rejection(call())
+      expect(error).toMatchObject({
+        kind: "invalid_args",
+        code: "canister_id_unresolved",
+        mayHaveExecuted: false,
+      })
+      expect(error.message).toContain("not_deployed")
+    }
+  })
+})

package/e2e/src/frontend-headers.test.ts

@@ -0,0 +1,253 @@
+// @vitest-environment node
+/**
+ * The response headers of the docs guide "Deploy to a frontend canister"
+ * (docs/src/content/docs/guides/deploy.mdx), as DFINITY's two asset canisters
+ * serve them through the local HTTP gateway: the asset canister with the
+ * wallet example's `.ic-assets.json5`, and the certified-assets canister of
+ * icp-cli's static-site recipe with the guide's `_headers`.
+ * `frontends/build.mjs` copied both files, unchanged, into what `icp deploy`
+ * uploaded.
+ */
+import { execFileSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { runInNewContext } from "node:vm"
+import { describe, expect, it } from "vitest"
+import {
+  fences,
+  guideFile,
+  guideHeaders,
+  icAssetsFile,
+} from "../frontends/build.mjs"
+import { replica } from "./replica"
+
+const guide = readFileSync(guideFile, "utf8")
+const icAssets = readFileSync(icAssetsFile, "utf8")
+
+interface AssetRule {
+  readonly match: string
+  readonly security_policy: string
+  readonly headers: Readonly<Record<string, string>>
+  readonly allow_raw_access: boolean
+}
+
+/** `.ic-assets.json5`, read as the object literal JSON5 is. */
+const rules = runInNewContext(`(${icAssets})`) as readonly AssetRule[]
+
+/** The guide's `_headers`, as [name, value] pairs. */
+const headersFile: readonly (readonly [string, string])[] = guideHeaders(guide)
+  .split("\n")
+  .slice(1)
+  .filter((line) => line.trim() !== "")
+  .map((line) => {
+    const colon = line.indexOf(":")
+    return [line.slice(0, colon).trim(), line.slice(colon + 1).trim()] as const
+  })
+
+/** What the asset canister's "hardened" policy adds, as the guide lists it. */
+const hardened = {
+  "strict-transport-security": "max-age=31536000; includeSubDomains",
+  "x-frame-options": "DENY",
+  "x-content-type-options": "nosniff",
+  "referrer-policy": "same-origin",
+  "x-xss-protection": "1; mode=block",
+}
+
+/** Every header the asset canister sends from the file and its policy, lower-cased. */
+const assetHeaders = [
+  ...Object.keys(rules[0]?.headers ?? {}),
+  ...Object.keys(hardened),
+  "permissions-policy",
+].map((name) => name.toLowerCase())
+
+/** Lines that are not comments, as the guide and the example compare. */
+const code = (text: string): string =>
+  text
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("//"))
+    .join("\n")
+    .trim()
+
+/** `/` of a frontend canister, through the local gateway. */
+const page = (canisterId: string): Promise<Response> =>
+  fetch(`${replica.host}/?canisterId=${canisterId}`)
+
+/** The headers a response's `ic-certificateexpression` certifies, lower-cased. */
+function certified(response: Response): string[] {
+  const expression = response.headers.get("ic-certificateexpression") ?? ""
+  const list =
+    /certified_response_headers: ResponseHeaderList\{headers: \[([^\]]*)\]/.exec(
+      expression
+    )
+  if (list === null) throw new Error(`no header list in ${expression}`)
+  return [...list[1]!.matchAll(/"([^"]+)"/g)].map(([, name]) =>
+    name!.toLowerCase()
+  )
+}
+
+/**
+ * The status and the `Location` a canister's `http_request` answers a GET for
+ * `url` on `host` with: the query a gateway makes, here with a Host the local
+ * gateway does not route.
+ */
+function httpRequest(
+  canister: string,
+  url: string,
+  host: string
+): { status: number; location: string | undefined } {
+  const arg = `(record { method = "GET"; url = "${url}"; headers = vec { record { "Host"; "${host}" } }; body = blob ""; certificate_version = opt 2 })`
+  const output = execFileSync(
+    "icp",
+    [
+      "canister",
+      "call",
+      canister,
+      "http_request",
+      arg,
+      "--query",
+      "-e",
+      "local",
+      "--json",
+    ],
+    {
+      cwd: fileURLToPath(new URL("..", import.meta.url)),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }
+  )
+  const reply = String(JSON.parse(output).response_candid)
+  const status = /status_code = (\d+) : nat16/.exec(reply)?.[1]
+  if (status === undefined) throw new Error(`no status_code in ${reply}`)
+  return {
+    status: Number(status),
+    location: /"Location";\s*"([^"]+)"/.exec(reply)?.[1],
+  }
+}
+
+const { assetCanister, staticSite } = replica.frontends
+
+describe("the deploy guide's headers", () => {
+  it("are the wallet example's .ic-assets.json5 in the guide and in core's llms.txt, comments aside", () => {
+    const shown = fences(guide).filter(
+      (fence) =>
+        fence.lang === "json5" &&
+        fence.body.startsWith("// public/.ic-assets.json5\n")
+    )
+    expect(shown).toHaveLength(1)
+    expect(code(shown[0]!.body)).toBe(code(icAssets))
+    const consumerGuide = readFileSync(
+      new URL("../../packages/core/llms.txt", import.meta.url),
+      "utf8"
+    )
+    const inLlms = fences(consumerGuide).filter(
+      (fence) => fence.lang === "json5"
+    )
+    expect(inLlms).toHaveLength(1)
+    expect(code(inLlms[0]!.body)).toBe(code(icAssets))
+    expect(rules).toEqual([
+      {
+        match: "**/*",
+        security_policy: "hardened",
+        headers: expect.any(Object),
+        allow_raw_access: false,
+      },
+    ])
+  })
+
+  it("are deployed here with the recipes the guide names, as the wallet example's are", () => {
+    /** Each asset recipe of an icp.yaml text, with its asset canister version. */
+    const recipes = (yaml: string): string[] =>
+      [
+        ...yaml.matchAll(
+          /type: "(@dfinity\/(?:asset-canister|static-site)@[^"]+)"(?:\s+configuration:\s+version: (\S+))?/g
+        ),
+      ]
+        .map(([, type, version]) => (version ? `${type} ${version}` : type!))
+        .sort()
+    const named = recipes(
+      fences(guide)
+        .filter((fence) => fence.lang === "yaml")
+        .map((fence) => fence.body)
+        .join("\n")
+    )
+    expect(named).toEqual([
+      "@dfinity/asset-canister@v2.3.0 0.30.2",
+      "@dfinity/static-site@v0.4.2",
+    ])
+    const file = (relative: string): string =>
+      readFileSync(new URL(relative, import.meta.url), "utf8")
+    expect(recipes(file("../icp.yaml"))).toEqual(named)
+    expect(recipes(file("../../examples/vite-wallet/icp.yaml"))).toEqual([
+      named[0],
+    ])
+  })
+
+  it("are served by the asset canister, with its hardened policy's own, and certified", async () => {
+    const response = await page(assetCanister)
+    expect(response.status).toBe(200)
+    const [rule] = rules
+    for (const [name, value] of Object.entries(rule!.headers)) {
+      expect(response.headers.get(name), name).toBe(value)
+    }
+    for (const [name, value] of Object.entries(hardened)) {
+      expect(response.headers.get(name), name).toBe(value)
+    }
+    // A Permissions-Policy that turns off every feature it lists, the
+    // clipboard's included.
+    const features = (response.headers.get("permissions-policy") ?? "")
+      .split(",")
+      .map((feature) => feature.trim())
+    expect(features).toContain("clipboard-write=()")
+    expect(features.filter((feature) => !feature.endsWith("=()"))).toEqual([])
+    expect(certified(response)).toEqual(expect.arrayContaining(assetHeaders))
+  })
+
+  it("are served by the static-site canister as its _headers lists them, and certified", async () => {
+    const response = await page(staticSite)
+    expect(response.status).toBe(200)
+    for (const [name, value] of headersFile) {
+      expect(response.headers.get(name), name).toBe(value)
+    }
+    expect(certified(response)).toEqual(
+      expect.arrayContaining(headersFile.map(([name]) => name.toLowerCase()))
+    )
+    // It adds none of its own: the one header of the asset canister's policy
+    // that _headers leaves out is not sent.
+    expect(response.headers.get("x-xss-protection")).toBeNull()
+  })
+
+  it("are the same on both canisters, but X-XSS-Protection and the Permissions-Policy", async () => {
+    // _headers lists every header the asset canister sends but one.
+    expect(headersFile.map(([name]) => name.toLowerCase()).sort()).toEqual(
+      assetHeaders.filter((name) => name !== "x-xss-protection").sort()
+    )
+    const assets = (await page(assetCanister)).headers
+    for (const [name, value] of headersFile) {
+      if (name !== "Permissions-Policy") {
+        expect(assets.get(name), name).toBe(value)
+      }
+    }
+  })
+
+  it("send a visitor of the asset canister's raw host to the checked one, path and query kept", () => {
+    expect(
+      httpRequest(
+        "asset_canister",
+        "/send?to=bob",
+        `${assetCanister}.raw.icp0.io`
+      )
+    ).toEqual({
+      status: 308,
+      location: `https://${assetCanister}.icp0.io/send?to=bob`,
+    })
+    expect(
+      httpRequest("asset_canister", "/", `${assetCanister}.icp0.io`)
+    ).toEqual({ status: 200, location: undefined })
+  })
+
+  it("leave the static-site canister's raw host served as the other", () => {
+    expect(
+      httpRequest("static_site", "/", `${staticSite}.raw.icp0.io`)
+    ).toEqual({ status: 200, location: undefined })
+  })
+})

package/e2e/src/identity.test.ts

@@ -0,0 +1,61 @@
+/**
+ * An identity switch between two Ed25519 identities on one client: the caller
+ * the canister sees changes, and so do the query keys, and the reads of the
+ * identity that left are removed from the cache.
+ */
+import { createClient } from "@ic-reactor/core"
+import { describe, expect, it } from "vitest"
+import { actor, type Actor } from "./declarations/hello_actor"
+import { ed25519, network, switchableAuth, target } from "./replica"
+
+describe("an identity switch on the local replica", () => {
+  it("calls as the identity signed in now, under that principal's keys", async () => {
+    const alice = ed25519()
+    const bob = ed25519()
+    const aliceText = alice.getPrincipal().toText()
+    const bobText = bob.getPrincipal().toText()
+    expect(aliceText).not.toBe(bobText)
+
+    const { auth, switchTo } = switchableAuth(alice)
+    const client = createClient({ network, auth: () => auth })
+    try {
+      const hello = client.canister<Actor>(actor, target)
+
+      expect(client.caller()).toBe(aliceText)
+      await expect(hello.whoami()).resolves.toBe(aliceText)
+      const aliceOptions = client.queryOptions(hello, "whoami")
+      expect(aliceOptions.queryKey[2]).toBe(aliceText)
+      await expect(client.queryClient.fetchQuery(aliceOptions)).resolves.toBe(
+        aliceText
+      )
+
+      switchTo(bob)
+
+      expect(client.caller()).toBe(bobText)
+      // Signed by Bob's key now: the canister sees his principal.
+      await expect(hello.whoami()).resolves.toBe(bobText)
+      const bobOptions = client.queryOptions(hello, "whoami")
+      expect(bobOptions.queryKey[2]).toBe(bobText)
+      expect(bobOptions.queryKey).not.toEqual(aliceOptions.queryKey)
+      // Alice's answer is not served to Bob: the switch removed it.
+      expect(
+        client.queryClient.getQueryData(aliceOptions.queryKey)
+      ).toBeUndefined()
+      expect(
+        client.queryClient.getQueryData(bobOptions.queryKey)
+      ).toBeUndefined()
+      await expect(client.queryClient.fetchQuery(bobOptions)).resolves.toBe(
+        bobText
+      )
+
+      // And back: Bob's answer goes the same way.
+      switchTo(alice)
+      expect(
+        client.queryClient.getQueryData(bobOptions.queryKey)
+      ).toBeUndefined()
+      await expect(hello.whoami()).resolves.toBe(aliceText)
+    } finally {
+      client.dispose()
+    }
+  })
+})

package/e2e/src/react.test.tsx

@@ -0,0 +1,59 @@
+/**
+ * One React render against the replica: ReactorProvider builds the client,
+ * useClient hands it to a component, and useQuery reads through it, as the
+ * caller signed in now.
+ */
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider, useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import { act, cleanup, render, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "./declarations/hello_actor"
+import { ed25519, network, switchableAuth, target } from "./replica"
+
+afterEach(cleanup)
+
+const wait = { timeout: 20_000 }
+
+function Whoami() {
+  const client = useClient()
+  const hello = client.canister<Actor>(actor, target)
+  const greeting = useQuery(client.queryOptions(hello, "greet", "React"))
+  const caller = useQuery(client.queryOptions(hello, "whoami"))
+  return (
+    <>
+      <p data-testid="greeting">{greeting.data ?? "…"}</p>
+      <p data-testid="caller">{caller.data ?? "…"}</p>
+    </>
+  )
+}
+
+describe("React against the local replica", () => {
+  it("renders what the canister answers, read as whoever is signed in", async () => {
+    const alice = ed25519()
+    const bob = ed25519()
+    const { auth, switchTo } = switchableAuth(alice)
+
+    render(
+      <ReactorProvider
+        client={() => createClient({ network, auth: () => auth })}
+      >
+        <Whoami />
+      </ReactorProvider>
+    )
+
+    const greeting = await screen.findByText("Hello, React!", undefined, wait)
+    expect(greeting.dataset.testid).toBe("greeting")
+    // The canister saw Alice's principal, not the anonymous one.
+    const caller = await screen.findByText(
+      alice.getPrincipal().toText(),
+      undefined,
+      wait
+    )
+    expect(caller.dataset.testid).toBe("caller")
+
+    // A switch re-renders the component, which reads again as Bob.
+    act(() => switchTo(bob))
+    await screen.findByText(bob.getPrincipal().toText(), undefined, wait)
+  })
+})