@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/server/tools.ts

@@ -0,0 +1,116 @@
+// The tools every server has, whichever canisters it lists. A listed
+// canister's methods get their own tools besides these (server.ts).
+import type { Tool } from "@modelcontextprotocol/server"
+
+const CANISTER = {
+  type: "string",
+  description:
+    "A canister id such as ryjl3-tyaaa-aaaaa-aaaba-cai, or the name of a canister this server lists (whoami lists them)",
+}
+const METHOD = {
+  type: "string",
+  description: "The method's name, as list_methods prints it",
+}
+const ARGS = {
+  type: "object",
+  description:
+    "The method's arguments, as describe_method's input schema describes them: {} for none, the fields of a lone record argument, else arg0, arg1, …",
+}
+
+const READ = { readOnlyHint: true, openWorldHint: true } as const
+
+export const WHOAMI: Tool = {
+  name: "whoami",
+  title: "Who calls, and where",
+  description:
+    "The principal this server signs calls as, the network, whether this client can approve updates, and the canisters that take updates.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+}
+
+export const LIST_METHODS: Tool = {
+  name: "list_methods",
+  title: "List a canister's methods",
+  description:
+    "Lists a canister's methods with their Candid signatures, read from the canister's certified candid:service metadata, and says whether updates to it can be sent.",
+  inputSchema: {
+    type: "object",
+    properties: { canister: CANISTER },
+    required: ["canister"],
+    additionalProperties: false,
+  },
+  annotations: READ,
+}
+
+export const DESCRIBE_METHOD: Tool = {
+  name: "describe_method",
+  title: "Describe a method",
+  description:
+    "Shows one method's Candid (the method and every type it uses), its doc comment, and the JSON Schema of the args that query and call take for it.",
+  inputSchema: {
+    type: "object",
+    properties: { canister: CANISTER, method: METHOD },
+    required: ["canister", "method"],
+    additionalProperties: false,
+  },
+  annotations: READ,
+}
+
+export const QUERY: Tool = {
+  name: "query",
+  title: "Run a query method",
+  description:
+    "Runs a query method of any canister and returns the reply as JSON. A query changes nothing. With certified: true the reply is certified by the subnet, at the cost of a slower replicated call made as the anonymous principal, so a method that answers per caller answers for the anonymous principal. Update methods are refused here: use call.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      canister: CANISTER,
+      method: METHOD,
+      args: ARGS,
+      certified: {
+        type: "boolean",
+        description:
+          "Whether the reply must be certified (a replicated call, made as the anonymous principal; not for composite queries). Default false.",
+      },
+    },
+    required: ["canister", "method"],
+    additionalProperties: false,
+  },
+  annotations: READ,
+}
+
+export const CALL: Tool = {
+  name: "call",
+  title: "Send an update",
+  description:
+    "Sends an update call once the person approves that exact call in the client. If they decline, nothing is sent: do not send it again unless they ask. Only canisters this server lists take updates. A query method is run as a query, with no approval.",
+  inputSchema: {
+    type: "object",
+    properties: { canister: CANISTER, method: METHOD, args: ARGS },
+    required: ["canister", "method"],
+    additionalProperties: false,
+  },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+}
+
+/** Every generic tool's name: a typed tool never takes one. */
+export const GENERIC_NAMES = [
+  WHOAMI.name,
+  LIST_METHODS.name,
+  DESCRIBE_METHOD.name,
+  QUERY.name,
+  CALL.name,
+]
+
+/** What the model is told about the server as a whole. */
+export const INSTRUCTIONS = `Tools for Internet Computer canisters, by ic-reactor.
+
+- list_methods and describe_method show a canister's interface. query runs a query method of any canister; it changes nothing. A listed canister's methods also have their own tools.
+- An update is sent only after the person approves that exact call in this client. If they decline or close the form, nothing was sent: do not send it again unless they ask.
+- An update that fails saying it "may have run" can have taken effect: check the canister's state before sending it again.
+- Arguments are JSON: nat, int, nat64 and int64 as decimal strings ("1000000"), smaller integers as numbers, principals as text, blobs as hex or {"utf8": "text"}, an opt as null or its value, a variant as {"tag": "Name", "value": payload}, a record as an object. describe_method gives each method's JSON Schema.`

package/packages/mcp/src/usage.ts

@@ -0,0 +1,40 @@
+// What the command line takes, and the error for a command line it refuses.
+
+/** A command line the server refuses to start with: printed to stderr, exit status 2. */
+export class UsageError extends Error {
+  override name = "UsageError"
+}
+
+export const USAGE = `ic-reactor-mcp: an MCP server for Internet Computer canisters
+
+Usage: ic-reactor-mcp [options]
+
+Every canister's methods can be read with the list_methods, describe_method
+and query tools. A canister named with --canister also gets one tool per
+method, and only such a canister takes updates: each one is sent after the
+person approves that exact call in the MCP client.
+
+Options:
+  --canister <name>=<id>   A canister to give tools and take updates, such as
+                           ledger=ryjl3-tyaaa-aaaaa-aaaba-cai. A bare <id> is
+                           named after its first five characters. Repeatable.
+  --did <name or id>=<path>
+                           Read that canister's interface from this .did file
+                           instead of the network. Repeatable.
+  --identity <pem file>    Sign calls with this Ed25519 or secp256k1 key, such
+                           as \`icp identity export\` prints. The file must be
+                           readable by its owner only (chmod 600). Without it
+                           the server calls as the anonymous principal and
+                           sends no update.
+  --network <ic|local|url> The network: ic (mainnet, the default), local
+                           (http://127.0.0.1:8000), or a replica's URL.
+  --root-key <hex>         The root key of a --network <url> that is not on
+                           this machine (DER, hex). A remote replica's key is
+                           never fetched from it.
+  --help                   Print this and exit.
+  --version                Print the version and exit.
+
+Example, in an MCP client's configuration:
+  "command": "ic-reactor-mcp",
+  "args": ["--canister", "ledger=ryjl3-tyaaa-aaaaa-aaaba-cai"]
+`

package/packages/mcp/tests/approval.test.ts

@@ -0,0 +1,60 @@
+// The approval form's text, for any client: plain, or rendered as Markdown.
+import { describe, expect, it } from "vitest"
+import { approvalMessage, type ApprovalFacts } from "../src/server/approval.ts"
+
+const facts: ApprovalFacts = {
+  canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+  canisterName: "ledger",
+  method: "icrc1_transfer",
+  mode: "update",
+  caller: "2vxsx-fae",
+  callerSource: "from a test key",
+  network: "a fake replica",
+  argsText: '(\n  record { memo = "<!-- hidden -->"; amount = 5 : nat },\n)',
+  argBytes: 42,
+  argSha256: "ab".repeat(32),
+  provenance: { kind: "metadata", certified: true, moduleHash: null },
+}
+
+/** The lines between the opening fence and the first line that closes it, as CommonMark reads them. */
+function fenced(message: string): { fence: string; inside: string[] } {
+  const lines = message.split("\n")
+  const open = lines.findIndex((line) => /^`{3,}$/.test(line))
+  const fence = lines[open] ?? ""
+  const close = lines.findIndex(
+    (line, i) =>
+      i > open && new RegExp(`^ {0,3}\`{${fence.length},}\\s*$`).test(line)
+  )
+  return { fence, inside: lines.slice(open + 1, close) }
+}
+
+describe("approvalMessage", () => {
+  it("puts the facts and the arguments in one code fence", () => {
+    const message = approvalMessage(facts)
+    const { fence, inside } = fenced(message)
+    expect(fence).toBe("```")
+    expect(inside[0]).toBe("Canister: ryjl3-tyaaa-aaaaa-aaaba-cai (ledger)")
+    expect(inside).toContain(
+      '  record { memo = "<!-- hidden -->"; amount = 5 : nat },'
+    )
+    expect(inside.at(-1)).toMatch(/^Interface: /)
+    expect(message.split("\n").at(-1)).toMatch(/^Nothing is sent unless/)
+  })
+
+  it("makes the fence longer than any run of backticks that starts a line inside it", () => {
+    const message = approvalMessage({
+      ...facts,
+      argsText: "(\n```\n   ````\n    `````\n)",
+    })
+    const { fence, inside } = fenced(message)
+    // Four spaces of indentation make a line code, never a closing fence.
+    expect(fence).toBe("`````")
+    expect(inside).toContain("    `````")
+    expect(inside.at(-1)).toMatch(/^Interface: /)
+  })
+
+  it("writes a method name that is not a plain identifier as a Candid string", () => {
+    const message = approvalMessage({ ...facts, method: "send‮" })
+    expect(message).toContain('Method:   "send\\u{202e}"')
+  })
+})

package/packages/mcp/tests/identity.test.ts

@@ -0,0 +1,234 @@
+// Who the server signs as. Keys are generated here, never real ones.
+import { createPublicKey, generateKeyPairSync } from "node:crypto"
+import { Principal } from "@icp-sdk/core/principal"
+import { describe, expect, it } from "vitest"
+import {
+  ANONYMOUS_CALLER,
+  callerFrom,
+  identityFromPem,
+  type KeyFiles,
+} from "../src/identity.ts"
+import { UsageError } from "../src/usage.ts"
+
+function generatePem(algorithm: "ed25519" | "secp256k1"): {
+  readonly pem: string
+  readonly principal: string
+  readonly seed: Uint8Array
+} {
+  const { privateKey, publicKey } =
+    algorithm === "ed25519"
+      ? generateKeyPairSync("ed25519")
+      : generateKeyPairSync("ec", { namedCurve: "secp256k1" })
+  // The IC's self-authenticating principal is a hash of the DER public key.
+  const der = new Uint8Array(publicKey.export({ format: "der", type: "spki" }))
+  const jwk = privateKey.export({ format: "jwk" })
+  return {
+    pem: privateKey
+      .export({
+        format: "pem",
+        type: algorithm === "ed25519" ? "pkcs8" : "sec1",
+      })
+      .toString(),
+    principal: Principal.selfAuthenticating(der).toText(),
+    seed: new Uint8Array(Buffer.from(jwk.d ?? "", "base64url")),
+  }
+}
+
+const filesOf = (
+  entries: Record<string, { readonly text: string; readonly mode?: number }>
+): KeyFiles => ({
+  mode: (path) => {
+    const entry = entries[path]
+    if (entry === undefined) throw new Error(`ENOENT: no such file ${path}`)
+    return entry.mode
+  },
+  read: (path) => {
+    const entry = entries[path]
+    if (entry === undefined) throw new Error(`ENOENT: no such file ${path}`)
+    return entry.text
+  },
+})
+
+describe("callerFrom", () => {
+  it("is anonymous without --identity", () => {
+    expect(callerFrom(undefined, filesOf({}))).toBe(ANONYMOUS_CALLER)
+    expect(ANONYMOUS_CALLER.identity).toBe("anonymous")
+  })
+
+  it.each(["ed25519", "secp256k1"] as const)(
+    "signs as the %s key of a file only its owner can read",
+    (algorithm) => {
+      const key = generatePem(algorithm)
+      const caller = callerFrom(
+        "/keys/me.pem",
+        filesOf({ "/keys/me.pem": { text: key.pem, mode: 0o100600 } })
+      )
+      expect(caller.algorithm).toBe(algorithm)
+      expect(caller.source).toBe(`--identity /keys/me.pem (${algorithm})`)
+      expect(
+        caller.identity === "anonymous"
+          ? undefined
+          : caller.identity.getPrincipal().toText()
+      ).toBe(key.principal)
+    }
+  )
+
+  it("refuses a key file other users can read or write, before reading it", () => {
+    const key = generatePem("ed25519")
+    for (const mode of [0o100644, 0o100640, 0o100604, 0o100620, 0o100666]) {
+      let read = false
+      const files: KeyFiles = {
+        mode: () => mode,
+        read: () => {
+          read = true
+          return key.pem
+        },
+      }
+      expect(() => callerFrom("/keys/me.pem", files)).toThrow(
+        /other users of this machine .*chmod 600 \/keys\/me\.pem/
+      )
+      expect(read).toBe(false)
+    }
+  })
+
+  it("does not check permission bits where there are none (Windows)", () => {
+    const key = generatePem("ed25519")
+    const caller = callerFrom(
+      "C:\\keys\\me.pem",
+      filesOf({ "C:\\keys\\me.pem": { text: key.pem } })
+    )
+    expect(caller.algorithm).toBe("ed25519")
+  })
+
+  it("says a missing file is missing", () => {
+    expect(() => callerFrom("/keys/none.pem", filesOf({}))).toThrow(
+      /--identity \/keys\/none\.pem: ENOENT/
+    )
+  })
+
+  it("never quotes the key in a refusal", () => {
+    const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" })
+    const pem = privateKey.export({ format: "pem", type: "pkcs8" }).toString()
+    const body = pem.split("\n")[1] ?? ""
+    try {
+      callerFrom("/k.pem", filesOf({ "/k.pem": { text: pem, mode: 0o600 } }))
+      expect.unreachable()
+    } catch (error) {
+      expect(error).toBeInstanceOf(UsageError)
+      expect((error as Error).message).toMatch(/P-256/)
+      expect((error as Error).message).not.toContain(body.slice(0, 20))
+    }
+  })
+})
+
+describe("identityFromPem", () => {
+  it("reads a secp256k1 key in PKCS#8 form, and after an EC PARAMETERS block", () => {
+    const { privateKey } = generateKeyPairSync("ec", {
+      namedCurve: "secp256k1",
+    })
+    const pkcs8 = privateKey.export({ format: "pem", type: "pkcs8" }).toString()
+    const sec1 = privateKey.export({ format: "pem", type: "sec1" }).toString()
+    const withParameters = `-----BEGIN EC PARAMETERS-----\nBgUrgQQACg==\n-----END EC PARAMETERS-----\n${sec1}`
+    const expected = identityFromPem(sec1, "sec1").identity.getPrincipal()
+    for (const pem of [pkcs8, withParameters]) {
+      expect(identityFromPem(pem, "pem").identity.getPrincipal().toText()).toBe(
+        expected.toText()
+      )
+    }
+  })
+
+  it("reads dfx's Ed25519 form, which carries the public key too, and checks it", () => {
+    const key = generatePem("ed25519")
+    const publicKey = new Uint8Array(
+      Buffer.from(
+        createPublicKey(key.pem).export({ format: "jwk" }).x ?? "",
+        "base64url"
+      )
+    )
+    // SEQUENCE { version 1, Ed25519, OCTET STRING { OCTET STRING seed }, [1] public key }
+    const der = Uint8Array.from([
+      0x30,
+      0x53,
+      0x02,
+      0x01,
+      0x01,
+      0x30,
+      0x05,
+      0x06,
+      0x03,
+      0x2b,
+      0x65,
+      0x70,
+      0x04,
+      0x22,
+      0x04,
+      0x20,
+      ...key.seed,
+      0xa1,
+      0x23,
+      0x03,
+      0x21,
+      0x00,
+      ...publicKey,
+    ])
+    const pem = `-----BEGIN PRIVATE KEY-----\n${Buffer.from(der).toString("base64")}\n-----END PRIVATE KEY-----\n`
+    expect(identityFromPem(pem, "pem").identity.getPrincipal().toText()).toBe(
+      key.principal
+    )
+
+    const other = generatePem("ed25519").seed
+    const mismatched = Uint8Array.from([
+      ...der.slice(0, 16),
+      ...other,
+      ...der.slice(48),
+    ])
+    const lying = `-----BEGIN PRIVATE KEY-----\n${Buffer.from(mismatched).toString("base64")}\n-----END PRIVATE KEY-----\n`
+    expect(() => identityFromPem(lying, "pem")).toThrow(/public key/)
+  })
+
+  it("refuses an encrypted key, a P-256 key and text that is no key", () => {
+    const { privateKey } = generateKeyPairSync("ed25519")
+    const encrypted = privateKey
+      .export({
+        format: "pem",
+        type: "pkcs8",
+        cipher: "aes-256-cbc",
+        passphrase: "test",
+      })
+      .toString()
+    const p256 = generateKeyPairSync("ec", { namedCurve: "P-256" })
+      .privateKey.export({ format: "pem", type: "pkcs8" })
+      .toString()
+    expect(() => identityFromPem(encrypted, "pem")).toThrow(/encrypted/)
+    expect(() => identityFromPem(p256, "pem")).toThrow(/P-256/)
+    expect(() => identityFromPem("hello", "pem")).toThrow(UsageError)
+  })
+
+  it("refuses a secp256k1 key whose value is past the curve's order, without quoting it", () => {
+    // SEC1: SEQUENCE { INTEGER 1, OCTET STRING d, [0] the secp256k1 OID }.
+    // OpenSSL reads a d of n + 1; the signer does not.
+    const d = Buffer.from(
+      "fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364142",
+      "hex"
+    )
+    const oid = Buffer.from("06052b8104000a", "hex")
+    const body = Buffer.concat([
+      Buffer.from([0x02, 0x01, 0x01, 0x04, d.length]),
+      d,
+      Buffer.from([0xa0, oid.length]),
+      oid,
+    ])
+    const der = Buffer.concat([Buffer.from([0x30, body.length]), body])
+    const pem = `-----BEGIN EC PRIVATE KEY-----\n${der.toString("base64")}\n-----END EC PRIVATE KEY-----\n`
+    let thrown: unknown
+    try {
+      identityFromPem(pem, "--identity k.pem")
+    } catch (error) {
+      thrown = error
+    }
+    expect(thrown).toBeInstanceOf(UsageError)
+    expect((thrown as Error).message).toBe(
+      "--identity k.pem holds a secp256k1 private key that is not valid: its value is not below the curve's order"
+    )
+  })
+})

package/packages/mcp/tests/naming.test.ts

@@ -0,0 +1,62 @@
+// Tool names for listed canisters' methods.
+import { describe, expect, it } from "vitest"
+import { MAX_TOOL_NAME, toolNames } from "../src/server/naming.ts"
+
+describe("toolNames", () => {
+  it("is <canister>_<method> for plain, short names", () => {
+    expect(
+      toolNames(
+        [
+          { canister: "ledger", method: "icrc1_balance_of" },
+          { canister: "ledger", method: "icrc1_transfer" },
+        ],
+        []
+      )
+    ).toEqual(["ledger_icrc1_balance_of", "ledger_icrc1_transfer"])
+  })
+
+  it("hashes a name with other characters, a long one and a taken one", () => {
+    const names = toolNames(
+      [
+        { canister: "c", method: "get balance" },
+        { canister: "c", method: "get_balance" },
+        { canister: "c", method: "a".repeat(60) },
+        { canister: "list", method: "methods" },
+        { canister: "c", method: "ünïcödé" },
+      ],
+      ["list_methods"]
+    )
+    expect(names[1]).toBe("c_get_balance")
+    expect(names[0]).toMatch(/^c_get_balance_[0-9a-f]{8}$/)
+    expect(names[2]).toMatch(/^c_a+_[0-9a-f]{8}$/)
+    expect(names[3]).toMatch(/^list_methods_[0-9a-f]{8}$/)
+    expect(names[4]).toMatch(/^c__n_c_d__[0-9a-f]{8}$/)
+    for (const name of names) {
+      expect(name).toMatch(/^[A-Za-z0-9_-]+$/)
+      expect(name.length).toBeLessThanOrEqual(MAX_TOOL_NAME)
+    }
+    expect(new Set(names).size).toBe(names.length)
+  })
+
+  it("gives the same names for the same input", () => {
+    const pairs = [
+      { canister: "c", method: "x y" },
+      { canister: "d", method: "z".repeat(80) },
+    ]
+    expect(toolNames(pairs, [])).toEqual(toolNames(pairs, []))
+  })
+
+  it("keeps names unique when a method is named like another's hash", () => {
+    const [first] = toolNames([{ canister: "c", method: "x y" }], [])
+    const names = toolNames(
+      [
+        { canister: "c", method: first.slice(2) },
+        { canister: "c", method: "x y" },
+      ],
+      []
+    )
+    expect(names[0]).toBe(first)
+    expect(names[1]).not.toBe(first)
+    expect(names[1]).toMatch(/^c_x_y_[0-9a-f]{8}$/)
+  })
+})

package/packages/mcp/tests/options.test.ts

@@ -0,0 +1,140 @@
+// The command line: canisters, .did files, the network and its root key.
+import { describe, expect, it } from "vitest"
+import { networkFrom } from "../src/network.ts"
+import { parseOptions } from "../src/options.ts"
+import { UsageError } from "../src/usage.ts"
+
+const LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+const GOVERNANCE = "rrkah-fqaaa-aaaaa-aaaaq-cai"
+const home = () => "/home/me"
+
+describe("parseOptions", () => {
+  it("defaults to mainnet, no identity and no canisters", () => {
+    const options = parseOptions([], home)
+    expect(options.network.network).toBe("ic")
+    expect(options.network.read).toEqual({
+      host: "https://icp-api.io",
+      fetchRootKey: false,
+    })
+    expect(options.identityPath).toBeUndefined()
+    expect(options.canisters).toEqual([])
+    expect(options.didFiles.size).toBe(0)
+  })
+
+  it("names canisters, and a bare id after its first five characters", () => {
+    const options = parseOptions(
+      ["--canister", `ledger=${LEDGER}`, "--canister", GOVERNANCE],
+      home
+    )
+    expect(options.canisters).toEqual([
+      { name: "ledger", id: LEDGER },
+      { name: "rrkah", id: GOVERNANCE },
+    ])
+  })
+
+  it("refuses a bad id, the management canister, a bad name and repeats", () => {
+    for (const [argv, reason] of [
+      [["--canister", "ledger=not-an-id"], /--canister ledger=not-an-id/],
+      [["--canister", "ic=aaaaa-aa"], /--canister ic=aaaaa-aa/],
+      [["--canister", `led-ger=${LEDGER}`], /1 to 20 letters, digits or _/],
+      [["--canister", `=${LEDGER}`], /1 to 20 letters/],
+      [
+        ["--canister", `a=${LEDGER}`, "--canister", `a=${GOVERNANCE}`],
+        /the name a is taken/,
+      ],
+      [
+        ["--canister", `a=${LEDGER}`, "--canister", `b=${LEDGER}`],
+        /listed twice/,
+      ],
+    ] as const) {
+      expect(() => parseOptions(argv, home)).toThrow(UsageError)
+      expect(() => parseOptions(argv, home)).toThrow(reason)
+    }
+  })
+
+  it("maps --did to canister ids, by name or id, and expands ~", () => {
+    const options = parseOptions(
+      [
+        "--canister",
+        `ledger=${LEDGER}`,
+        "--did",
+        "ledger=~/dids/ledger.did",
+        "--did",
+        `${GOVERNANCE}=./governance.did`,
+      ],
+      home
+    )
+    expect([...options.didFiles]).toEqual([
+      [LEDGER, "/home/me/dids/ledger.did"],
+      [GOVERNANCE, "./governance.did"],
+    ])
+  })
+
+  it("refuses a --did without a target or path, or for an unknown name", () => {
+    for (const flag of ["ledger", "=x.did", "ledger=", "nope=x.did"]) {
+      expect(() => parseOptions(["--did", flag], home)).toThrow(UsageError)
+    }
+    expect(() =>
+      parseOptions(
+        ["--did", `${LEDGER}=a.did`, "--did", `${LEDGER}=b.did`],
+        home
+      )
+    ).toThrow(/has a .did already/)
+  })
+
+  it("expands ~ in --identity, and refuses unknown flags and positionals", () => {
+    expect(
+      parseOptions(["--identity", "~/.config/key.pem"], home).identityPath
+    ).toBe("/home/me/.config/key.pem")
+    expect(() => parseOptions(["--pem", "key.pem"], home)).toThrow(UsageError)
+    expect(() => parseOptions([LEDGER], home)).toThrow(UsageError)
+  })
+})
+
+describe("networkFrom", () => {
+  it("fetches the root key only from this machine", () => {
+    expect(networkFrom("local", undefined)).toMatchObject({
+      network: "local",
+      read: { host: "http://127.0.0.1:8000", fetchRootKey: true },
+      recheckMs: 0,
+    })
+    expect(networkFrom(undefined, undefined).recheckMs).toBeUndefined()
+    for (const url of [
+      "http://localhost:4943",
+      "http://127.0.0.1:4943",
+      "http://app.localhost:8080",
+      "http://[::1]:8000",
+    ]) {
+      const choice = networkFrom(url, undefined)
+      expect(choice.read.fetchRootKey).toBe(true)
+      expect(choice.read.rootKey).toBeUndefined()
+      expect(choice.recheckMs).toBe(0)
+    }
+    expect(() => networkFrom("https://replica.example.com", undefined)).toThrow(
+      /never fetched from it/
+    )
+  })
+
+  it("takes a remote replica's root key as hex, and only for a URL", () => {
+    const choice = networkFrom("https://replica.example.com/x", "0a0B")
+    expect(choice.network).toEqual({
+      host: "https://replica.example.com",
+      rootKey: Uint8Array.from([0x0a, 0x0b]),
+    })
+    expect(choice.read).toEqual({
+      host: "https://replica.example.com",
+      rootKey: Uint8Array.from([0x0a, 0x0b]),
+      fetchRootKey: false,
+    })
+    expect(() => networkFrom("ic", "0a")).toThrow(/goes with a --network <url>/)
+    expect(() => networkFrom("https://r.example.com", "0g")).toThrow(/not hex/)
+    expect(() => networkFrom("https://r.example.com", "")).toThrow(/not hex/)
+  })
+
+  it("refuses what is not ic, local or an http(s) URL", () => {
+    expect(() => networkFrom("mainnet", undefined)).toThrow(UsageError)
+    expect(() => networkFrom("ftp://127.0.0.1", undefined)).toThrow(
+      /http or https/
+    )
+  })
+})