@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/interface/server-result.ts

@@ -0,0 +1,42 @@
+// Every call of a server function goes through `serverResult`: a call can
+// resolve with no result at all instead of rejecting.
+
+/**
+ * What a tool shows when a server function gave no result: it runs on the
+ * studio's server, which StackBlitz cannot run.
+ */
+class ServerUnavailableError extends Error {
+  override name = "ServerUnavailableError"
+
+  constructor() {
+    super(
+      "This tool runs on the studio's server, which did not answer. StackBlitz cannot run the studio's server: clone the repository to use it."
+    )
+  }
+}
+
+/**
+ * The result of a server function call, checked. Where server functions
+ * cannot run (StackBlitz's WebContainer has no AsyncLocalStorage), the
+ * server answers a plain, unserialized 500, and TanStack Start's client
+ * resolves the call with `undefined` instead of rejecting. This throws a
+ * `ServerUnavailableError` for that, and for anything else that is not a
+ * `{ ok: boolean }` result.
+ */
+export async function serverResult<T extends { ok: boolean }>(
+  call: Promise<T>
+): Promise<T> {
+  const result: unknown = await call
+  if (
+    typeof result !== "object" ||
+    result === null ||
+    typeof (result as { ok?: unknown }).ok !== "boolean"
+  ) {
+    throw new ServerUnavailableError()
+  }
+  return result as T
+}
+
+/** An interface without its .did's hash cannot name the version a tool must use. */
+export const NO_DID_HASH =
+  "This interface has no .did hash to pin the tool to. Reload the page."

package/examples/canister-studio/src/interface/typed.ts

@@ -0,0 +1,68 @@
+// Registry canisters: their interface is a committed .did and the module
+// generated from it, so they need no live read and no compiler.
+import { sha256Hex } from "../lib/hex.ts"
+import type { RegistryEntry } from "../lib/registry.ts"
+import { methodDocsFromModule } from "./docs.ts"
+import type { InterfacePayload } from "./types.ts"
+
+// Lazy: each module's text is its own chunk, fetched only when a page of
+// that canister needs its docs or its source.
+const MODULE_TEXT: Record<
+  RegistryEntry["module"],
+  () => Promise<{ default: string }>
+> = {
+  icrc1: () => import("../canisters/icrc1.ts?raw"),
+  icp_ledger: () => import("../canisters/icp_ledger.ts?raw"),
+  ckbtc_minter: () => import("../canisters/ckbtc_minter.ts?raw"),
+}
+
+/** The committed generated module of a registry canister, as text. */
+export async function typedModuleText(
+  module: RegistryEntry["module"]
+): Promise<string> {
+  return (await MODULE_TEXT[module]()).default
+}
+
+const payloads = new Map<
+  string,
+  Promise<Extract<InterfacePayload, { ok: true }>>
+>()
+
+/**
+ * The payload of a registry canister: its committed .did, and the docs of
+ * the module generated from it. The same promise for the same canister.
+ */
+export function typedPayload(
+  entry: RegistryEntry
+): Promise<Extract<InterfacePayload, { ok: true }>> {
+  let payload = payloads.get(entry.id)
+  if (payload === undefined) {
+    payload = buildTypedPayload(entry)
+    payloads.set(entry.id, payload)
+  }
+  return payload
+}
+
+async function buildTypedPayload(
+  entry: RegistryEntry
+): Promise<Extract<InterfacePayload, { ok: true }>> {
+  const [didSha256, docs] = await Promise.all([
+    sha256Hex(new TextEncoder().encode(entry.did)),
+    typedModuleText(entry.module).then(methodDocsFromModule, () => {
+      // A chunk that fails to load costs the docs, not the page; the next
+      // payload asks again.
+      payloads.delete(entry.id)
+      return {}
+    }),
+  ])
+  return {
+    ok: true,
+    canisterId: entry.id,
+    source: { kind: "typed", module: entry.module },
+    did: entry.did,
+    didSha256,
+    docs,
+    fetchedAt: 0,
+    cache: "typed",
+  }
+}

package/examples/canister-studio/src/interface/types.ts

@@ -0,0 +1,121 @@
+import type { AnyFieldSchema, AnySchema, MethodMode } from "@meantjs/schema"
+import type { RegistryEntry } from "../lib/registry.ts"
+
+/** Where a canister's interface came from, and how far it can be trusted. */
+export type InterfaceSource =
+  /** A committed .did, generated into a typed module at build time. */
+  | { kind: "typed"; module: RegistryEntry["module"] }
+  /** The canister's `candid:service` metadata, read with a certified read_state. */
+  | { kind: "metadata"; certified: true; moduleHash: string | null }
+  /**
+   * The `__get_candid_interface_tmp_hack` query: one replica's answer, NOT
+   * certified. The UI labels it so. Used only when the certificate proves
+   * the metadata absent (`reason: "absent"`) or the metadata is readable by
+   * the canister's controllers only (`"private"`, a 403).
+   */
+  | {
+      kind: "tmp_hack"
+      certified: false
+      moduleHash: string | null
+      reason?: "absent" | "private"
+    }
+  /** A .did the user pasted (the playground). */
+  | { kind: "pasted"; certified: false }
+
+/** One method of a canister, ready for a form and a reply viewer. */
+export interface MethodInfo {
+  name: string
+  mode: MethodMode
+  args: readonly AnyFieldSchema[]
+  results: readonly AnyFieldSchema[]
+  /** From didToModule's JSDoc (runtime interfaces) or a typed hint. */
+  doc?: string
+}
+
+/** A canister's interface, rebuilt from an `InterfacePayload` on either side. */
+export interface CanisterInterface {
+  canisterId: string
+  name: string
+  /** The service schema: what `client.canister()` takes. */
+  actor: AnySchema
+  /** Every callable method, sorted by name. */
+  methods: readonly MethodInfo[]
+  /** Map-backed: method names are canister text and may be "__proto__". */
+  method(name: string): MethodInfo | undefined
+  source: InterfaceSource
+  did?: string
+  didSha256?: string
+  /** Declarations and methods the schema loader left out, and why. */
+  omitted: readonly {
+    kind: "declaration" | "method"
+    name: string
+    reason: string
+    via?: string
+  }[]
+  registry?: RegistryEntry
+}
+
+/**
+ * What loaders and server functions return: plain, serializable data (no
+ * schemas, no functions), the same on the server and in the browser.
+ */
+export type InterfacePayload =
+  | {
+      ok: true
+      canisterId: string
+      source: InterfaceSource
+      did: string
+      didSha256: string
+      /** The compact `didToContract` envelope JSON; absent for typed canisters. */
+      envelopeJson?: string
+      /**
+       * Method docs by method name (read them with `Object.hasOwn`: the
+       * names are canister text).
+       */
+      docs: Record<string, string>
+      /**
+       * When the interface was last confirmed against the canister (ms since
+       * the epoch): read, or its module hash re-checked unchanged. 0 for
+       * typed and pasted interfaces.
+       */
+      fetchedAt: number
+      /**
+       * `"hit"`: answered from the loader's cache (at most a module-hash
+       * re-check); `"miss"`: read from the canister now; `"typed"`: a
+       * registry canister, from the committed .did.
+       */
+      cache: "hit" | "miss" | "typed"
+      /**
+       * The compiled interface's identity (`candid-core:interface:v1:…`):
+       * equal ids, the same interface. Absent for typed canisters.
+       */
+      interfaceId?: string
+      /**
+       * Where the .did was compiled: on the server, or in the browser (a
+       * pasted .did, or a live read when server functions were unavailable).
+       * Absent for typed canisters.
+       */
+      compiledIn?: "server" | "browser"
+    }
+  | {
+      ok: false
+      canisterId: string
+      code: InterfaceErrorCode
+      message: string
+      diagnostics?: { code: string; message: string }[]
+    }
+
+export type InterfaceErrorCode =
+  | "invalid_canister_id"
+  | "not_a_canister"
+  | "management_canister"
+  | "no_interface"
+  | "private_interface"
+  | "canister_not_found"
+  | "too_large"
+  | "compile_failed"
+  | "network"
+  | "trust_error"
+  | "timeout"
+  /** The server failed on its side (its log says why); never mainnet's fault. */
+  | "server_error"

package/examples/canister-studio/src/lib/format.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest"
+import {
+  formatByteSize,
+  formatNanos,
+  formatTokens,
+  groupDigits,
+  shortPrincipal,
+} from "./format.ts"
+
+describe("groupDigits", () => {
+  it("groups bigints and integers in threes", () => {
+    expect(groupDigits(0n)).toBe("0")
+    expect(groupDigits(999n)).toBe("999")
+    expect(groupDigits(1000n)).toBe("1,000")
+    expect(groupDigits(1234567n)).toBe("1,234,567")
+    expect(groupDigits(-1234567n)).toBe("-1,234,567")
+    expect(groupDigits(2n ** 64n - 1n)).toBe("18,446,744,073,709,551,615")
+    expect(groupDigits(4_294_967_295)).toBe("4,294,967,295")
+    expect(groupDigits(-12)).toBe("-12")
+  })
+
+  it("groups only the integer part of other numbers", () => {
+    expect(groupDigits(1234.5)).toBe("1,234.5")
+    expect(groupDigits(-0.25)).toBe("-0.25")
+    expect(groupDigits(1e21)).toBe("1e+21")
+    expect(groupDigits(Number.NaN)).toBe("NaN")
+    expect(groupDigits(Number.NEGATIVE_INFINITY)).toBe("-Infinity")
+  })
+})
+
+describe("shortPrincipal", () => {
+  it("keeps the first and last groups", () => {
+    expect(shortPrincipal("ryjl3-tyaaa-aaaaa-aaaba-cai")).toBe("ryjl3-…-cai")
+    expect(
+      shortPrincipal(
+        "4twgc-viha4-dqoby-ha4dq-obyha-4dqob-yha4d-qobyh-a4dqo-byha4-dqe"
+      )
+    ).toBe("4twgc-…-dqe")
+  })
+
+  it("returns short text whole", () => {
+    expect(shortPrincipal("2vxsx-fae")).toBe("2vxsx-fae")
+    expect(shortPrincipal("aaaaa-aa")).toBe("aaaaa-aa")
+    expect(shortPrincipal("")).toBe("")
+  })
+})
+
+describe("formatTokens", () => {
+  it("formats base units exactly, grouped, with the symbol", () => {
+    expect(formatTokens(123_456_789_000n, 8, "ICP")).toBe("1,234.56789 ICP")
+    expect(formatTokens(10_000n, 8, "ICP")).toBe("0.0001 ICP")
+    expect(formatTokens(0n, 8)).toBe("0")
+    expect(formatTokens(-1n, 8)).toBe("-0.00000001")
+    expect(formatTokens(1234n * 10n ** 18n + 1n, 18, "ckETH")).toBe(
+      "1,234.000000000000000001 ckETH"
+    )
+    expect(formatTokens(5n, 0, "")).toBe("5")
+  })
+})
+
+describe("formatNanos", () => {
+  it("formats the epoch and fractions to ms, µs or ns", () => {
+    expect(formatNanos(0n)).toBe("1970-01-01 00:00:00 UTC")
+    expect(formatNanos(1_700_000_000_123_000_000n)).toBe(
+      "2023-11-14 22:13:20.123 UTC"
+    )
+    expect(formatNanos(1_700_000_000_123_456_000n)).toBe(
+      "2023-11-14 22:13:20.123456 UTC"
+    )
+    expect(formatNanos(1_700_000_000_000_000_001n)).toBe(
+      "2023-11-14 22:13:20.000000001 UTC"
+    )
+  })
+
+  it("handles leap days, times before the epoch and the nat64 maximum", () => {
+    expect(formatNanos(951_782_400n * 1_000_000_000n)).toBe(
+      "2000-02-29 00:00:00 UTC"
+    )
+    expect(formatNanos(-1n)).toBe("1969-12-31 23:59:59.999999999 UTC")
+    expect(formatNanos(2n ** 64n - 1n)).toBe(
+      "2554-07-21 23:34:33.709551615 UTC"
+    )
+  })
+
+  it("agrees with Date for whole milliseconds across four centuries", () => {
+    // Test-only use of Date: formatNanos itself never reads it.
+    const start = -2_208_988_800_000 // 1900-01-01
+    const step = 7_777_777_777_777 // about 246 years in ms, never round
+    for (let ms = start; ms < 10_000_000_000_000; ms += step / 61) {
+      const whole = Math.floor(ms)
+      const iso = new Date(whole).toISOString() // YYYY-MM-DDTHH:MM:SS.sssZ
+      const expected = `${iso.slice(0, 10)} ${iso.slice(11, 19)}${
+        iso.slice(19, 23) === ".000" ? "" : iso.slice(19, 23)
+      } UTC`
+      expect(formatNanos(BigInt(whole) * 1_000_000n)).toBe(expected)
+    }
+  })
+})
+
+describe("formatByteSize", () => {
+  it("uses B, KiB and MiB", () => {
+    expect(formatByteSize(0)).toBe("0 B")
+    expect(formatByteSize(73)).toBe("73 B")
+    expect(formatByteSize(16 * 1024)).toBe("16.0 KiB")
+    expect(formatByteSize(1_891_788)).toBe("1.8 MiB")
+  })
+})

package/examples/canister-studio/src/lib/format.ts

@@ -0,0 +1,139 @@
+import { formatUnits } from "@ic-reactor/core"
+
+// Everything here is deterministic text: the same input gives the same output
+// on the server and in every browser. Never `toLocaleString` or `Intl`: the
+// server's locale and time zone are not the reader's, and a render that
+// differs between the two is a hydration mismatch.
+
+/**
+ * How a ledger's base units read as tokens: `icrc1_decimals` and
+ * `icrc1_symbol`. Forms edit such amounts as decimals (`parseUnits`), viewers
+ * show them with `formatTokens`.
+ */
+export interface TokenUnits {
+  readonly decimals: number
+  readonly symbol: string
+}
+
+/** Comma groups of three in a string of decimal digits (no sign, no point). */
+function groupIntegerDigits(digits: string): string {
+  let out = ""
+  for (let i = 0; i < digits.length; i++) {
+    if (i > 0 && (digits.length - i) % 3 === 0) out += ","
+    out += digits[i]
+  }
+  return out
+}
+
+/** Groups the integer part of plain decimal text: "-1234.5" → "-1,234.5". */
+function groupDecimalText(text: string): string {
+  const negative = text.startsWith("-")
+  const unsigned = negative ? text.slice(1) : text
+  const point = unsigned.indexOf(".")
+  const integer = point === -1 ? unsigned : unsigned.slice(0, point)
+  const fraction = point === -1 ? "" : unsigned.slice(point)
+  return `${negative ? "-" : ""}${groupIntegerDigits(integer)}${fraction}`
+}
+
+/**
+ * An integer with comma groups of three: `1234567n` → "1,234,567". A
+ * non-integer number groups its integer part; a number JavaScript writes in
+ * exponent form, `NaN` and the infinities are returned as JavaScript writes
+ * them.
+ */
+export function groupDigits(n: bigint | number): string {
+  if (typeof n === "bigint") return groupDecimalText(n.toString())
+  const text = String(n)
+  if (!Number.isFinite(n) || /e/i.test(text)) return text
+  return groupDecimalText(text)
+}
+
+/**
+ * Principal text cut to its first and last groups: "ryjl3-…-cai". Text with
+ * fewer than three groups (the anonymous principal "2vxsx-fae") is returned
+ * whole.
+ */
+export function shortPrincipal(text: string): string {
+  const groups = text.split("-")
+  if (groups.length < 3) return text
+  return `${groups[0]}-…-${groups[groups.length - 1]}`
+}
+
+/**
+ * A token amount in base units as grouped decimal text, with the symbol when
+ * given: `123456789000n, 8, "ICP"` → "1,234.56789 ICP". Exact (bigint all the
+ * way, through `formatUnits`); trailing zeros of the fraction are dropped.
+ */
+export function formatTokens(
+  units: bigint,
+  decimals: number,
+  symbol?: string
+): string {
+  const amount = groupDecimalText(formatUnits(units, decimals))
+  return symbol === undefined || symbol === "" ? amount : `${amount} ${symbol}`
+}
+
+// Floor division by a positive bigint (`/` truncates toward zero, so a
+// negative dividend with a remainder rounds one step further down).
+function floorDiv(a: bigint, b: bigint): bigint {
+  const q = a / b
+  return a % b < 0n ? q - 1n : q
+}
+
+const pad = (n: bigint, width: number): string =>
+  n.toString().padStart(width, "0")
+
+const NANOS_PER_SECOND = 1_000_000_000n
+const SECONDS_PER_DAY = 86_400n
+
+/**
+ * Nanoseconds since the Unix epoch (an IC timestamp, `created_at_time`) as a
+ * UTC date and time: "2026-10-12 02:31:05.123456789 UTC". The fraction is
+ * shown to the millisecond, microsecond or nanosecond, as far as it has
+ * digits, and left out when it is zero. Computed in bigint, so any nat64 or
+ * int64 is exact and nothing depends on the host's clock or time zone.
+ */
+export function formatNanos(ns: bigint): string {
+  const seconds = floorDiv(ns, NANOS_PER_SECOND)
+  const nanos = ns - seconds * NANOS_PER_SECOND
+  const days = floorDiv(seconds, SECONDS_PER_DAY)
+  const secondOfDay = seconds - days * SECONDS_PER_DAY
+
+  // Days to a proleptic Gregorian date (Howard Hinnant's civil_from_days).
+  const z = days + 719_468n
+  const era = floorDiv(z, 146_097n)
+  const dayOfEra = z - era * 146_097n
+  const yearOfEra =
+    (dayOfEra - dayOfEra / 1_460n + dayOfEra / 36_524n - dayOfEra / 146_096n) /
+    365n
+  const dayOfYear =
+    dayOfEra - (365n * yearOfEra + yearOfEra / 4n - yearOfEra / 100n)
+  const mp = (5n * dayOfYear + 2n) / 153n
+  const day = dayOfYear - (153n * mp + 2n) / 5n + 1n
+  const month = mp < 10n ? mp + 3n : mp - 9n
+  const year = yearOfEra + era * 400n + (month <= 2n ? 1n : 0n)
+
+  const hour = secondOfDay / 3_600n
+  const minute = (secondOfDay % 3_600n) / 60n
+  const second = secondOfDay % 60n
+
+  let fraction = ""
+  if (nanos !== 0n) {
+    fraction = `.${pad(nanos, 9)}`
+    if (fraction.endsWith("000000")) fraction = fraction.slice(0, 4)
+    else if (fraction.endsWith("000")) fraction = fraction.slice(0, 7)
+  }
+
+  const yearText = year < 0n ? `-${pad(-year, 4)}` : pad(year, 4)
+  return `${yearText}-${pad(month, 2)}-${pad(day, 2)} ${pad(hour, 2)}:${pad(minute, 2)}:${pad(second, 2)}${fraction} UTC`
+}
+
+/**
+ * A byte count for people: "73 B", "16.0 KiB", "1.9 MiB". One decimal above
+ * a kibibyte (`toFixed`, which is not locale-dependent).
+ */
+export function formatByteSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`
+}

package/examples/canister-studio/src/lib/hex.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest"
+import { fromHex, sha256Hex, toHex } from "./hex.ts"
+
+describe("toHex / fromHex", () => {
+  it("round-trips bytes as lower-case hex", () => {
+    const bytes = new Uint8Array([0, 1, 15, 16, 127, 128, 254, 255])
+    expect(toHex(bytes)).toBe("00010f107f80feff")
+    expect(fromHex("00010f107f80feff")).toEqual(bytes)
+    expect(toHex(new Uint8Array())).toBe("")
+    expect(fromHex("")).toEqual(new Uint8Array())
+  })
+
+  it("reads a 0x prefix, upper case and surrounding whitespace", () => {
+    expect(fromHex("0x4449444C0000")).toEqual(
+      new Uint8Array([0x44, 0x49, 0x44, 0x4c, 0, 0])
+    )
+    expect(fromHex("  0Xab \n")).toEqual(new Uint8Array([0xab]))
+  })
+
+  it("refuses odd lengths, separators and non-hex digits", () => {
+    for (const text of ["abc", "0x0", "ab cd", "ab:cd", "zz", "0xg0", "-1"]) {
+      expect(fromHex(text)).toBeUndefined()
+    }
+  })
+})
+
+describe("sha256Hex", () => {
+  it("hashes with Web Crypto", async () => {
+    expect(await sha256Hex(new Uint8Array())).toBe(
+      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    )
+    expect(await sha256Hex(new TextEncoder().encode("abc"))).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+    )
+  })
+
+  it("hashes only the view's bytes, not its whole buffer", async () => {
+    const buffer = new Uint8Array([0, 0x61, 0x62, 0x63, 0])
+    expect(await sha256Hex(buffer.subarray(1, 4))).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+    )
+  })
+})

package/examples/canister-studio/src/lib/hex.ts

@@ -0,0 +1,33 @@
+const HEX_DIGITS = /^[0-9a-f]*$/i
+
+/** Lower-case hex of `bytes`, two digits per byte, no prefix. */
+export function toHex(bytes: Uint8Array): string {
+  let out = ""
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0")
+  return out
+}
+
+/**
+ * The bytes of hex text, or `undefined` when it is not hex: an odd number of
+ * digits, or anything but digits after an optional `0x`. Upper and lower case
+ * are both read. Surrounding whitespace is ignored; separators inside are not
+ * (this reads argument bytes from URLs, where a typo must not pass).
+ */
+export function fromHex(text: string): Uint8Array | undefined {
+  const trimmed = text.trim()
+  const digits = /^0x/i.test(trimmed) ? trimmed.slice(2) : trimmed
+  if (digits.length % 2 !== 0 || !HEX_DIGITS.test(digits)) return undefined
+  const bytes = new Uint8Array(digits.length / 2)
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(digits.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}
+
+/** SHA-256 of `bytes` as lower-case hex, with Web Crypto (browser and Node). */
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  // A copy, so the digest gets an ArrayBuffer-backed view even when `bytes`
+  // is a view over a SharedArrayBuffer or a larger buffer.
+  const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes))
+  return toHex(new Uint8Array(digest))
+}

package/examples/canister-studio/src/lib/ids.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest"
+import {
+  checkCanisterId,
+  isCanisterId,
+  MANAGEMENT_CANISTER_ID,
+  principalProblem,
+} from "./ids.ts"
+
+// A self-authenticating (user) principal: 29 bytes ending in 0x02.
+const USER = "4twgc-viha4-dqoby-ha4dq-obyha-4dqob-yha4d-qobyh-a4dqo-byha4-dqe"
+// Canonical principal text of 10 bytes ending in 0x02: not opaque.
+const TEN_BYTES_NOT_OPAQUE = "bwcas-wqaaa-aaaaa-aaaaa-aaq"
+// Canonical principal text of 9 bytes ending in 0x01: opaque, wrong length.
+const NINE_BYTES = "sehci-oaaaa-aaaaa-aaaaa-c"
+
+describe("checkCanisterId", () => {
+  it("accepts mainnet canister ids", () => {
+    for (const id of [
+      "ryjl3-tyaaa-aaaaa-aaaba-cai",
+      "mxzaz-hqaaa-aaaar-qaada-cai",
+      "mqygn-kiaaa-aaaar-qaadq-cai",
+      "rdmx6-jaaaa-aaaaa-aaadq-cai",
+    ]) {
+      expect(checkCanisterId(id)).toEqual({ ok: true, id })
+      expect(isCanisterId(id)).toBe(true)
+    }
+  })
+
+  it("refuses the management canister by name", () => {
+    const check = checkCanisterId(MANAGEMENT_CANISTER_ID)
+    expect(check).toMatchObject({ ok: false, code: "management_canister" })
+  })
+
+  it("refuses principals that are not canister ids", () => {
+    for (const text of ["2vxsx-fae", USER, TEN_BYTES_NOT_OPAQUE, NINE_BYTES]) {
+      expect(checkCanisterId(text)).toMatchObject({
+        ok: false,
+        code: "not_a_canister",
+      })
+    }
+  })
+
+  it("refuses text that is not canonical, without repairing it", () => {
+    for (const text of [
+      "",
+      "RYJL3-TYAAA-AAAAA-AAABA-CAI",
+      " ryjl3-tyaaa-aaaaa-aaaba-cai",
+      "ryjl3tyaaaaaaaaaaabacai",
+      "ryjl3-tyaaa-aaaaa-aaaba-cal",
+      "ryjl3-tyaaa-aaaaa-aaaba-cai/",
+      "x".repeat(10_000),
+    ]) {
+      const check = checkCanisterId(text)
+      expect(check.ok).toBe(false)
+      if (!check.ok) {
+        expect(check.code).toBe("invalid_canister_id")
+        expect(check.message.length).toBeGreaterThan(0)
+      }
+    }
+  })
+})
+
+describe("principalProblem", () => {
+  it("is undefined for canonical text and a message otherwise", () => {
+    expect(principalProblem("aaaaa-aa")).toBeUndefined()
+    expect(principalProblem("2vxsx-fae")).toBeUndefined()
+    expect(principalProblem("AAAAA-AA")).toMatch(/./)
+    expect(principalProblem("y".repeat(64))).toMatch(/at most 63/)
+  })
+})