@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/tests/traps/ledger.ts

@@ -0,0 +1,248 @@
+/**
+ * The ledger every trap file calls, through the public surface a test of an
+ * app has: `createTestClient` from `@ic-reactor/core/testing`, and the
+ * `icrc1` module `meant gen` wrote for `icrc1.did`.
+ *
+ * It is an ICRC-1 ledger that keeps balances, so a trap can say what a
+ * hand-written integration gets wrong in the terms of money: a transfer that
+ * was sent twice debits twice, a balance that was not read again hides a debit
+ * that did happen, and a read made for one user shows another's.
+ *
+ * Not a test file, and not part of the package: the traps import it, and
+ * nothing else does.
+ */
+import { principal, type Principal } from "@meantjs/schema"
+import { vi } from "vitest"
+import type { Canister, Client } from "../../src/index.js"
+import { createTestClient } from "../../src/testing/index.js"
+import * as icrc1 from "../fixtures/icrc1.js"
+
+/**
+ * The test timeout of a trap file that signs and certifies calls, in
+ * milliseconds. A file sets it for itself, at the top, with
+ * `vi.setConfig({ testTimeout: SIGNED_CALLS_TIMEOUT_MS })`.
+ *
+ * Such a file waits out real delays and runs its tests side by side, and every
+ * call it makes is signed and certified: on a machine that is busy with other
+ * test files a test can take many times what it takes alone. A timeout is for
+ * a call that never arrives, not for a slow one.
+ */
+export const SIGNED_CALLS_TIMEOUT_MS = 30_000
+
+/** The canister id the traps run their ledger at. */
+export const LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+
+/** What the ledger charges on top of every transfer. */
+export const FEE = 10_000n
+
+/**
+ * The principals of the identities of seeds 1 and 2, the same in every run on
+ * every machine (`auth.switchTo(2)` signs in as the second).
+ */
+export const ALICE = principal(
+  "psith-oknjz-x73tv-7x3p4-a2sji-7o6lo-g2754-yfgfl-3vlqe-irrrt-4ae"
+)
+export const BOB = principal(
+  "xledz-fktfc-4ywwn-gai5u-ieqce-5x4qc-7lpel-o4ubn-ucngz-7lrzo-5ae"
+)
+
+/** The anonymous principal: who calls while nobody is signed in. */
+export const ANONYMOUS = principal("2vxsx-fae")
+
+/** Somebody to pay. */
+export const SHOP = principal("rrkah-fqaaa-aaaaa-aaaaq-cai")
+
+type TestClient = ReturnType<typeof createTestClient>
+
+/** The options of `createTestClient`. */
+export type TestClientOptions = NonNullable<
+  Parameters<typeof createTestClient>[0]
+>
+
+/** The transfer `amount` to `SHOP`, as the ledger's argument. */
+export const transferArg = (
+  amount: bigint,
+  to: Principal = SHOP
+): icrc1.TransferArg => ({
+  to: { owner: to, subaccount: null },
+  amount,
+  fee: null,
+  memo: null,
+  from_subaccount: null,
+  created_at_time: null,
+})
+
+/** What a ledger test is handed. */
+export interface Ledger extends TestClient {
+  /** The ledger, called as whoever is signed in. */
+  readonly ledger: Canister<icrc1.Actor>
+  /** Everyone's balance, by principal text. A test may set one. */
+  readonly balances: Map<string, bigint>
+  /** How many transfers changed the ledger's books: what really happened. */
+  readonly executed: () => number
+  /** Every canister request (a query or a call) the fake received, in order. */
+  readonly sent: () => TestClient["requests"][number][]
+  /** The calls (updates) the fake received. */
+  readonly calls: () => TestClient["requests"][number][]
+  /**
+   * Replaces what the ledger does with a transfer. `apply()` books it (debits
+   * the caller, credits the payee, counts it in `executed()`) and returns the
+   * reply a ledger gives; what the function returns, or throws through
+   * `reject()`, is what the call ends with.
+   */
+  onTransfer(handler: (apply: () => icrc1.TransferResult) => unknown): void
+  /**
+   * Runs `handler` before every `icrc1_balance_of` answers, which may fail the
+   * read by calling `reject()` or throwing.
+   */
+  beforeRead(handler: () => void): void
+  /**
+   * Holds every `icrc1_balance_of` read sent as `caller` until the returned
+   * function is called: a slow read, in flight while the user changes.
+   */
+  hold(caller: string): () => void
+}
+
+const made: Client[] = []
+
+/**
+ * Disposes every client the traps made. Call it from the file's `afterAll`:
+ * the traps run their tests side by side to overlap their waits, so a client
+ * must outlive the test that made it until the whole file is done.
+ */
+export const disposeAll = (): void => {
+  for (const client of made.splice(0)) client.dispose()
+}
+
+/** Has {@link disposeAll} dispose `client` too, and returns it. */
+export const track = (client: Client): Client => {
+  made.push(client)
+  return client
+}
+
+/**
+ * A ledger on a test client. The client signs in as the identity of seed 1
+ * (`ALICE`) unless the options say otherwise, and every principal starts with
+ * `balances` (by default: Alice has 1,000,000 and Bob 500,000).
+ *
+ * `icrc1_balance_of` answers for the account it is asked about, to anyone
+ * (with `privateBalances`: to its owner only, and zero to everybody else), and
+ * `icrc1_transfer` debits the caller the amount and the fee, or answers
+ * `InsufficientFunds`.
+ */
+export function setupLedger(
+  options: TestClientOptions & {
+    balances?: Iterable<readonly [string, bigint]>
+    privateBalances?: boolean
+  } = {}
+): Ledger {
+  const { balances: initial, privateBalances, ...clientOptions } = options
+  const test = createTestClient(clientOptions)
+  track(test.client)
+  const balances = new Map<string, bigint>(
+    initial ?? [
+      [ALICE, 1_000_000n],
+      [BOB, 500_000n],
+    ]
+  )
+  let executed = 0
+  let blocks = 0n
+  const holds = new Map<string, Promise<void>>()
+  let transfer: (apply: () => icrc1.TransferResult) => unknown = (apply) =>
+    apply()
+  let beforeRead = (): void => undefined
+
+  test.mock<icrc1.Actor>(icrc1.actor, LEDGER, {
+    icrc1_fee: () => FEE,
+    icrc1_balance_of: async ({ owner }, { caller }) => {
+      beforeRead()
+      await holds.get(caller)
+      // A private ledger tells an account's balance to its owner and shows
+      // everybody else zero, so what a read answers depends on who sent it.
+      return privateBalances === true && owner !== caller
+        ? 0n
+        : (balances.get(owner) ?? 0n)
+    },
+    icrc1_transfer: (arg, { caller }) =>
+      transfer((): icrc1.TransferResult => {
+        const debit = arg.amount + FEE
+        const balance = balances.get(caller) ?? 0n
+        if (balance < debit) {
+          return {
+            tag: "Err",
+            value: { tag: "InsufficientFunds", value: { balance } },
+          }
+        }
+        balances.set(caller, balance - debit)
+        balances.set(
+          arg.to.owner,
+          (balances.get(arg.to.owner) ?? 0n) + arg.amount
+        )
+        executed += 1
+        blocks += 1n
+        return { tag: "Ok", value: blocks }
+      }) as icrc1.TransferResult,
+  })
+
+  const requests = (): TestClient["requests"][number][] => [...test.requests]
+  return {
+    ...test,
+    ledger: test.client.canister<icrc1.Actor>(icrc1.actor, { id: LEDGER }),
+    balances,
+    executed: () => executed,
+    sent: () =>
+      requests().filter(
+        (request) => request.endpoint === "query" || request.endpoint === "call"
+      ),
+    calls: () => requests().filter((request) => request.endpoint === "call"),
+    onTransfer(handler) {
+      transfer = handler
+    },
+    beforeRead(handler) {
+      beforeRead = handler
+    },
+    hold(caller) {
+      let release!: () => void
+      holds.set(
+        caller,
+        new Promise<void>((resolve) => {
+          release = () => {
+            holds.delete(caller)
+            resolve()
+          }
+        })
+      )
+      return release
+    },
+  }
+}
+
+/**
+ * Retries `check` until it stops throwing, polling every 5 ms for up to five
+ * seconds: long enough for a loaded machine, short enough to fail on a call
+ * that was never going to arrive.
+ */
+export const eventually = <T>(check: () => T): Promise<T> =>
+  vi.waitFor(check, { timeout: 5_000, interval: 5 })
+
+/** Waits `ms` milliseconds. */
+export const sleep = (ms: number): Promise<void> =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Waits until every re-send an update could get has been sent (300 ms and then
+ * 600 ms after a failure that allows one), with a margin for signing and
+ * certifying them: whatever the client was ever going to send again is in the
+ * fake's log after this.
+ */
+export const pastResendDelays = (): Promise<void> => sleep(300 + 600 + 250)
+
+/** What a promise rejects with; fails the test when it resolves. */
+export async function rejection(promise: Promise<unknown>): Promise<unknown> {
+  try {
+    await promise
+  } catch (error) {
+    return error
+  }
+  throw new Error("expected the call to reject, and it resolved")
+}

package/packages/core/tests/traps/root-key-off-local.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Trap: a root key fetched from a replica nobody vouches for.
+ *
+ * The mistake a hand-written integration makes: it calls
+ * `agent.fetchRootKey()` for every host that is not mainnet, because that is
+ * what makes a local replica work, and the staging host, the Codespaces
+ * forward and the test network get it too. The key a replica reports is the
+ * one every certificate after it is checked against, so whoever answers at
+ * that host (a proxy, a hijacked domain) chooses what the app believes: a
+ * forged balance, a transfer that "succeeded". Fetching it is the one request
+ * that must never be made to a host the app does not control.
+ *
+ * The guarantee: a given `rootKey` is used and never fetched. Without one the
+ * key is fetched from `localhost`, `*.localhost` and loopback addresses only,
+ * or when the app writes `fetchRootKey: true` (a line a reviewer can find).
+ * Anywhere else the client asks for no key at all, and certificates are
+ * checked against mainnet's, which a forged answer fails. The spy below
+ * stands where the replica would, and records what is asked of it.
+ */
+import { afterAll, describe, expect, it } from "vitest"
+import { createClient, type Network } from "../../src/index.js"
+import * as icrc1 from "../fixtures/icrc1.js"
+import { fetchSpy } from "./fetch-spy.js"
+import { LEDGER, disposeAll, rejection, track } from "./ledger.js"
+
+afterAll(disposeAll)
+
+/** A root key of the right length, which no replica reports. */
+const GIVEN_ROOT_KEY = new Uint8Array(133).fill(5)
+
+/** Reads a fee through a client on `network`, and returns every path the spy was asked for. */
+async function pathsAskedFor(network: Network): Promise<string[]> {
+  const spy = fetchSpy()
+  const client = track(
+    createClient({ network, identity: "anonymous", fetch: spy.fetch })
+  )
+  const ledger = client.canister<icrc1.Actor>(icrc1.actor, { id: LEDGER })
+  // The spy refuses everything, so the read fails: only what was asked of it
+  // is of interest.
+  await rejection(ledger.icrc1_fee())
+  return spy.calls()
+}
+
+const STATUS = "/api/v2/status"
+const QUERY = new RegExp(`/canister/${LEDGER}/query$`)
+
+describe("a replica that is not local", () => {
+  it.each([
+    ["a staging domain", "https://staging.example.com"],
+    ["a Codespaces forward", "https://fluffy-space-5173.app.github.dev"],
+    ["a Gitpod forward", "https://5173-user-repo-abc123.ws-us118.gitpod.io"],
+    ["a name that ends in localhost", "http://notlocalhost:4943"],
+    [
+      "a domain that starts with localhost",
+      "http://localhost.example.com:4943",
+    ],
+    [
+      "a domain that starts with an address",
+      "http://127.0.0.1.example.com:4943",
+    ],
+    [
+      "a host with localhost in its userinfo",
+      "http://localhost@evil.example.com",
+    ],
+    ["an address just outside 127.0.0.0/8", "http://128.0.0.1:4943"],
+  ])("is never asked for its root key: %s", async (_, host) => {
+    const paths = await pathsAskedFor({ host })
+
+    // The read goes out, checked against mainnet's key; no key was requested.
+    expect(paths).toEqual([expect.stringMatching(QUERY)])
+    expect(paths).not.toContain(STATUS)
+  })
+
+  it("is never asked for its root key when mainnet is the network", async () => {
+    const paths = await pathsAskedFor("ic")
+
+    expect(paths).toEqual([expect.stringMatching(QUERY)])
+  })
+
+  it("is asked for it only where the app writes fetchRootKey: true", async () => {
+    const paths = await pathsAskedFor({
+      host: "https://fluffy-space-5173.app.github.dev",
+      fetchRootKey: true,
+    })
+
+    // Asked first, before anything else is sent; the spy refuses, so it ends there.
+    expect(paths).toEqual([STATUS])
+  })
+})
+
+describe("a replica that is local", () => {
+  it.each([
+    ["the local network", "local"],
+    ["127.0.0.1", { host: "http://127.0.0.1:4943" }],
+    ["localhost", { host: "http://localhost:8000" }],
+    ["a subdomain of localhost", { host: "http://abc.localhost:4943" }],
+    [
+      "an address of 127.0.0.0/8 other than the first",
+      { host: "http://127.0.0.2:4943" },
+    ],
+    ["the IPv6 loopback", { host: "http://[::1]:4943" }],
+  ] satisfies [string, Network][])(
+    "is asked for its root key, so a local replica works: %s",
+    async (_, network) => {
+      const paths = await pathsAskedFor(network)
+
+      expect(paths).toEqual([STATUS])
+    }
+  )
+
+  // An invariant, not a regression a fault can reintroduce here: the agent
+  // never fetches a key it was given, whatever the client asks of it.
+  it("is not asked for it when the app gives the root key, which is used as given", async () => {
+    const paths = await pathsAskedFor({
+      host: "http://127.0.0.1:4943",
+      rootKey: GIVEN_ROOT_KEY,
+    })
+
+    expect(paths).toEqual([expect.stringMatching(QUERY)])
+  })
+
+  it("is not asked for it where the app writes fetchRootKey: false", async () => {
+    const paths = await pathsAskedFor({
+      host: "http://127.0.0.1:4943",
+      fetchRootKey: false,
+    })
+
+    expect(paths).toEqual([expect.stringMatching(QUERY)])
+  })
+})

package/packages/core/tests/traps/stale-data-across-users.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Trap: one user's data shown to the next user of the same browser.
+ *
+ * The mistake a hand-written integration makes: its cache key names the
+ * method and the arguments and leaves out who is calling
+ * (`["balance", account]`). After a sign-in, a switch of account or a
+ * sign-out, the cache still holds the previous user's answer under the key
+ * the new user reads, so it is shown to them until a refetch replaces it. And
+ * a read that was slow, started for one user and answered after the switch,
+ * lands in whatever key the app has by then, or is sent again as the user who
+ * is signed in now: either way an answer to one principal sits under another.
+ * Where a canister answers each caller differently (a ledger that tells an
+ * account's balance to its owner only) it is a privacy leak.
+ *
+ * The guarantee: a read's key holds the principal that calls, so after a
+ * sign-in, a switch or a sign-out the new caller's key is empty until it
+ * loads, and a read made for a user is sent as that user and never lands
+ * under another's key. Once the caller has changed, the previous one's reads
+ * leave the cache, and a read made for them is cancelled instead of being
+ * sent as the new one. This file plays a
+ * session through real TanStack Query observers (two views of a private
+ * ledger: the caller's own balance, which a component rebuilds with the
+ * caller, and Alice's, a fixed account that every user of the page looks at)
+ * and requires that nothing an observer shows was meant for somebody else.
+ */
+import { principal } from "@meantjs/schema"
+import { QueryObserver } from "@tanstack/query-core"
+import { afterAll, expect, it, vi } from "vitest"
+import {
+  ALICE,
+  ANONYMOUS,
+  BOB,
+  SIGNED_CALLS_TIMEOUT_MS,
+  disposeAll,
+  eventually,
+  setupLedger,
+} from "./ledger.js"
+
+vi.setConfig({ testTimeout: SIGNED_CALLS_TIMEOUT_MS })
+afterAll(disposeAll)
+
+it("never shows the balance of one principal to another through a sign-in, a switch with a slow read, and a sign-out", async () => {
+  const l = setupLedger({ signedIn: false, privateBalances: true })
+  const { client, ledger, auth } = l
+  const own = new Map<string, bigint>([
+    [ANONYMOUS, 0n],
+    [ALICE, 1_000_000n],
+    [BOB, 500_000n],
+  ])
+
+  // What a component builds on each render: its own balance, and Alice's.
+  const mine = () => ({
+    ...client.queryOptions(ledger, "icrc1_balance_of", {
+      owner: principal(client.caller()),
+      subaccount: null,
+    }),
+    retry: false,
+  })
+  const alices = () => ({
+    ...client.queryOptions(ledger, "icrc1_balance_of", {
+      owner: ALICE,
+      subaccount: null,
+    }),
+    retry: false,
+  })
+  const views = {
+    mine: new QueryObserver(client.queryClient, mine()),
+    alices: new QueryObserver(client.queryClient, alices()),
+  }
+
+  // The balance the ledger tells `viewer` for each view: what they may see.
+  const entitled = (view: keyof typeof views, viewer: string): bigint =>
+    view === "mine"
+      ? (own.get(viewer) ?? 0n)
+      : viewer === ALICE
+        ? 1_000_000n
+        : 0n
+
+  // Everything an observer ever shows, with who was looking: a component
+  // builds its options again when the caller changes, which is what the
+  // client's subscription stands for here.
+  let viewer: string = client.caller()
+  const shown: { view: string; viewer: string; data: bigint | undefined }[] = []
+  const stops = Object.entries(views).map(([view, observer]) =>
+    observer.subscribe((result) =>
+      shown.push({ view, viewer, data: result.data })
+    )
+  )
+  const stop = client.subscribe(() => {
+    viewer = client.caller()
+    views.mine.setOptions(mine())
+    views.alices.setOptions(alices())
+    // What the new caller is shown at the moment of the change, before
+    // anything has loaded for them: empty, or what is theirs to see.
+    shown.push(
+      { view: "mine", viewer, data: views.mine.getCurrentResult().data },
+      { view: "alices", viewer, data: views.alices.getCurrentResult().data }
+    )
+  })
+  const showing = (mineData: bigint, alicesData: bigint) =>
+    eventually(() => {
+      expect(views.mine.getCurrentResult().data).toBe(mineData)
+      expect(views.alices.getCurrentResult().data).toBe(alicesData)
+    })
+
+  // Nobody is signed in: the anonymous principal reads, and sees nothing of
+  // Alice's.
+  await showing(0n, 0n)
+
+  // Alice signs in: both views move to her keys.
+  await client.signIn()
+  expect(client.caller()).toBe(ALICE)
+  await showing(1_000_000n, 1_000_000n)
+  const aliceKey = client.queryKey(ledger, "icrc1_balance_of", {
+    owner: ALICE,
+    subaccount: null,
+  })
+  const aliceOptions = alices()
+
+  // Alice's next read of her balance is held in flight, past her switch to
+  // Bob.
+  const release = l.hold(ALICE)
+  const before = l.sent().length
+  void client.queryClient.refetchQueries({ queryKey: aliceKey })
+  await eventually(() => expect(l.sent()).toHaveLength(before + 1))
+  auth.switchTo(2)
+  expect(client.caller()).toBe(BOB)
+  await showing(500_000n, 0n)
+
+  // Alice's slow read is answered: Bob's views are as they were, and her
+  // answer stays out of the cache, which dropped her reads when Bob became
+  // current.
+  release()
+  await eventually(() =>
+    expect(client.queryClient.isFetching({ queryKey: aliceKey })).toBe(0)
+  )
+  expect(views.mine.getCurrentResult().data).toBe(500_000n)
+  expect(views.alices.getCurrentResult().data).toBe(0n)
+  expect(client.queryClient.getQueryData(aliceKey)).toBeUndefined()
+
+  // A read of Alice's key that starts now runs the function made for Alice.
+  // It must not go out as Bob, whose answer, zero, would sit under her key.
+  const sentBefore = l.sent().length
+  await client.queryClient
+    .fetchQuery({ ...aliceOptions, staleTime: 0 })
+    .catch((error: unknown) => error)
+  expect(l.sent()).toHaveLength(sentBefore)
+  expect(client.queryClient.getQueryData(aliceKey)).toBeUndefined()
+
+  // Back to Alice, and then to nobody.
+  auth.switchTo(1)
+  expect(client.caller()).toBe(ALICE)
+  await showing(1_000_000n, 1_000_000n)
+  await auth.signOut()
+  expect(client.caller()).toBe(ANONYMOUS)
+  await showing(0n, 0n)
+
+  stop()
+  for (const unsubscribe of stops) unsubscribe()
+
+  // Every view of every principal was seen, and what was shown to each of
+  // them was empty or theirs.
+  expect(new Set(shown.map((entry) => entry.viewer))).toEqual(
+    new Set([ANONYMOUS, ALICE, BOB])
+  )
+  for (const { view, viewer: who, data } of shown) {
+    if (data !== undefined) {
+      expect(data, `${view} shown to ${who}`).toBe(
+        entitled(view as keyof typeof views, who)
+      )
+    }
+  }
+})