@meantjs/consent 0.0.0-stage → 0.1.0

package/src/decode.mjs

@@ -0,0 +1,140 @@
+// Step 1: Candid argument bytes -> a value tree aligned with the resolved form's positions.
+//
+// Codec: @candid-core/schema 0.5.0 `decodeArgs` (schema-directed, with the Candid coercion relation and explicit
+// resource budgets). The expected schema is built from the method's resolved-form tree, so the decoder never
+// trusts the types the bytes claim: an argument is read as the signature says or the call is refused.
+//
+// Value tree (lossless; the same shape at every position of the resolved form):
+//   nat, int, nat8..nat64, int8..int64   decimal string       (D-006: never a JavaScript number)
+//   float32, float64                     number
+//   bool, text                           boolean, string
+//   null, reserved                       null
+//   principal                            canonical text
+//   blob (vec nat8)                      Uint8Array
+//   opt T                                null when absent, else the value of T
+//   record                               plain object keyed exactly like the resolved form's `fields`
+//   variant                              { tag: <key of the resolved form's `cases`>, value }   (value null for a bare tag)
+//   vec T                                array
+//
+// Limits of the resolved form, refused (E_UNSUPPORTED_TYPE) rather than guessed:
+//   - a value that reaches a position with `recursive: true` (the resolver cut a cycle or a depth of 8 there; the type
+//     below is unknown). The position is decoded as `reserved`, which every Candid type is a subtype of, so the bytes
+//     there are skipped without trusting their type; a call whose value lies there (the case is chosen, the `opt` is
+//     present, the field exists, the `vec` has an element) is refused when the value tree is built. A call whose value
+//     never goes there gets its message (spec section 12, rule 12; D-042);
+//   - `func` and `service` positions anywhere in the method (the resolved form does not carry their signatures);
+//   - nested `opt` (`opt opt T` collapses to one `optional` flag in the resolved form).
+
+import { c } from "@candid-core/schema";
+import { decodeArgs } from "@candid-core/schema/codec";
+import { bytesOf } from "./bytes.mjs";
+import { CODES, fail } from "./errors.mjs";
+import { entriesOf } from "./resolved.mjs";
+
+/** A consent message is for one ingress message at most (IC limit: 2 MiB). */
+export const DEFAULT_LIMITS = Object.freeze({ maxBytes: 2 * 1024 * 1024, maxDepth: 64, maxElements: 100_000 });
+
+const INTEGERS = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"]);
+const FLOATS = new Set(["float32", "float64"]);
+const PRIMITIVES = new Set(["null", "bool", "text", "principal", "reserved", "empty", ...INTEGERS, ...FLOATS]);
+const MAX_NODE_DEPTH = 64;
+
+/** The codec's name for a resolved-form key: `#123` has no name, so the codec's `_123_` convention carries the id. */
+const codecName = (key) => (/^#(0|[1-9][0-9]{0,9})$/.test(key) ? `_${key.slice(1)}_` : key);
+
+const NO_OPT_BOX = new Set(["null", "reserved"]); // `opt null` and `opt reserved` are boxed by the codec
+
+/** Build the codec schema for one position of the resolved form. */
+export function schemaFor(node, where = "argument", depth = 0) {
+  if (node === null || typeof node !== "object" || typeof node.candid !== "string") {
+    fail(CODES.RESOLVED_FORM, `${where}: not a resolved-form position`);
+  }
+  if (depth > MAX_NODE_DEPTH) fail(CODES.UNSUPPORTED_TYPE, `${where}: nested deeper than ${MAX_NODE_DEPTH}`);
+  const inner = node.recursive === true ? c.reserved : innerSchema(node, where, depth);
+  return node.optional === true ? c.opt(inner) : inner;
+}
+
+function innerSchema(node, where, depth) {
+  const kind = node.candid;
+  if (PRIMITIVES.has(kind)) return c[kind];
+  switch (kind) {
+    case "blob":
+      return c.blob();
+    case "vec": {
+      if (node.element === undefined) fail(CODES.UNSUPPORTED_TYPE, `${where}: vec without an element type`);
+      return c.vec(schemaFor(node.element, `${where}[]`, depth + 1));
+    }
+    case "record": {
+      const fields = Object.create(null);
+      for (const [key, child] of entriesOf(node.fields)) fields[codecName(key)] = schemaFor(child, `${where}.${key}`, depth + 1);
+      return c.record(fields);
+    }
+    case "variant": {
+      const arms = Object.create(null);
+      for (const [key, child] of entriesOf(node.cases)) arms[codecName(key)] = schemaFor(child, `${where}.${key}`, depth + 1);
+      return c.variant(arms);
+    }
+    default:
+      fail(CODES.UNSUPPORTED_TYPE, `${where}: ${kind} positions cannot be decoded (the resolved form carries no signature for them)`);
+  }
+}
+
+const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+/** Own enumerable property, also for a key like "__proto__" (assignment would set the prototype instead). */
+export function setOwn(obj, key, value) {
+  Object.defineProperty(obj, key, { value, enumerable: true, writable: true, configurable: true });
+}
+
+/** Codec value -> value tree. `node` is the resolved-form position the schema was built from. */
+export function toTree(node, v, where = "argument") {
+  if (node.recursive === true) {
+    if (node.optional === true && v === null) return null;
+    fail(CODES.UNSUPPORTED_TYPE, `${where}: the resolved form cuts this ${node.candid} at a cycle (recursive: true), so its type below is unknown`);
+  }
+  if (node.optional === true) {
+    if (v === null) return null;
+    if (NO_OPT_BOX.has(node.candid)) v = v.some; // boxed opt null / opt reserved
+  }
+  const kind = node.candid;
+  if (INTEGERS.has(kind)) return String(v);
+  if (FLOATS.has(kind) || kind === "bool" || kind === "text" || kind === "principal" || kind === "blob") return v;
+  if (kind === "null" || kind === "reserved") return null;
+  if (kind === "vec") return v.map((e, i) => toTree(node.element, e, `${where}[${i}]`));
+  if (kind === "record") {
+    const out = {};
+    for (const [key, child] of entriesOf(node.fields)) setOwn(out, key, toTree(child, v[codecName(key)], `${where}.${key}`));
+    return out;
+  }
+  if (kind === "variant") {
+    const cases = entriesOf(node.cases);
+    const hit = cases.find(([key]) => codecName(key) === v.tag);
+    if (hit === undefined) fail(CODES.DECODE, `${where}: the decoder returned the case ${JSON.stringify(v.tag)}, which the resolved form lacks`);
+    return { tag: hit[0], value: hasOwn(v, "value") ? toTree(hit[1], v.value, `${where}.${hit[0]}`) : null };
+  }
+  fail(CODES.UNSUPPORTED_TYPE, `${where}: cannot convert ${kind}`);
+}
+
+/**
+ * Decode the Candid-encoded argument tuple of a call against a resolved-form method.
+ *
+ * @param {{ args: object[] }} method  an entry of `resolved.methods`
+ * @param {Uint8Array | ArrayBuffer | number[]} arg  the bytes of the call's argument (the `arg` of the ICRC-21 request)
+ * @param {{ maxBytes?: number, maxDepth?: number, maxElements?: number }} [limits]
+ * @returns {unknown[]} one value tree per argument, in order
+ * @throws {ConsentError} E_DECODE, E_TOO_LARGE, E_UNSUPPORTED_TYPE, E_RESOLVED_FORM
+ */
+export function decodeArguments(method, arg, limits = {}) {
+  const bytes = bytesOf(arg);
+  if (bytes === null) fail(CODES.DECODE, "the argument is not bytes: a Uint8Array, an ArrayBuffer or an array of integers 0 to 255");
+  const opts = { ...DEFAULT_LIMITS, ...limits };
+  if (bytes.length > opts.maxBytes) fail(CODES.TOO_LARGE, `the argument is ${bytes.length} bytes; the limit for a consent message is ${opts.maxBytes}`);
+  const schemas = method.args.map((node, i) => schemaFor(node, `argument ${i}`));
+  const r = decodeArgs(schemas, bytes, opts);
+  if (!r.ok) {
+    const first = r.issues[0];
+    const code = first.code === "resource_limit_exceeded" ? CODES.TOO_LARGE : CODES.DECODE;
+    fail(code, `the argument bytes do not decode as the method's signature: ${first.code} at ${first.path}: ${first.message}`);
+  }
+  return r.values.map((v, i) => toTree(method.args[i], v, `argument ${i}`));
+}

package/src/display.mjs

@@ -0,0 +1,218 @@
+// Turning one value of the tree into text, and into an ICRC-21 `Value`.
+//
+// Formatting goes through `formatterFor` of @meantjs/format for every tagged position
+// (spec section 6: "rendered with the formatter of the tag at that position"); nothing here converts a unit,
+// a decimal or an account by itself. An untagged position renders as Candid text.
+//
+// A formatter can fail on a value (for example a 5-byte subaccount, which no ledger accepts). The value is then
+// shown as raw Candid text instead of hiding it, and the failure is recorded in `diagnostics`. A formatter that
+// cannot be built (a dynamic ref the caller did not supply, a bad tag argument) is a configuration error and
+// stops the message: showing a number without its decimals would be worse than no message.
+
+import { FormatError, convertUnit, displayTimestamp, formatterFor } from "@meantjs/format";
+import { CODES, ConsentError, fail } from "./errors.mjs";
+import { entriesOf } from "./resolved.mjs";
+import { visible } from "./text.mjs";
+
+const U64_MAX = 2n ** 64n - 1n;
+const CONFIG_CODES = new Set(["E_REF_UNRESOLVED", "E_ARG", "E_TAG_TYPE", "E_TAG_CONFLICT", "E_TYPE"]);
+
+/** Budget for the text of one message: a consent message is read by a person (ICRC-21: short and concise). */
+export const MAX_MESSAGE_CHARS = 32 * 1024;
+
+export class Renderer {
+  /** Set while `plainTupleText` runs: no formatter applies. */
+  #plain = false;
+
+  /**
+   * @param {{ refs?: Record<string, unknown>, utcOffsetMinutes?: number | null, diagnostics?: object[] }} options
+   *   `refs`: the resolved dynamic values, keyed by their `from` string (for example `query:icrc1_decimals`).
+   *   `utcOffsetMinutes`: when a number, timestamps are shown in that zone (the generic form); otherwise in UTC.
+   */
+  constructor({ refs = {}, utcOffsetMinutes = null, diagnostics = [] } = {}) {
+    this.refs = refs;
+    this.utcOffsetMinutes = utcOffsetMinutes;
+    this.diagnostics = diagnostics;
+    this.chars = 0;
+    this.formatters = new WeakMap();
+    /** Set when a timestamp was shown in the requested zone, so the response can say the text is zone-sensitive. */
+    this.usedZone = false;
+  }
+
+  /** @returns {import("@meantjs/format").Formatter | null} */
+  formatter(node) {
+    if (this.formatters.has(node)) return this.formatters.get(node);
+    let f;
+    try {
+      f = formatterFor(node, { refs: this.refs });
+    } catch (e) {
+      if (e instanceof FormatError && CONFIG_CODES.has(e.code)) throw new ConsentError(e.code, e.message, { cause: e });
+      throw e;
+    }
+    this.formatters.set(node, f);
+    return f;
+  }
+
+  charge(text) {
+    this.chars += text.length;
+    if (this.chars > MAX_MESSAGE_CHARS) fail(CODES.TOO_LARGE, `the message would exceed ${MAX_MESSAGE_CHARS} characters; it is never truncated`);
+    return text;
+  }
+
+  /**
+   * Plain display text of one value, not yet escaped for any format: the formatter of its tag, or Candid text
+   * (spec section 6; a bare principal is its canonical text).
+   * @param {object} node  the resolved-form position
+   * @param {unknown} value  its value (a tree node, never absent)
+   * @param {string} where  for diagnostics
+   */
+  text(node, value, where) {
+    const shown = this.#formatted(node, value, where);
+    if (shown !== null) return this.charge(shown);
+    // An untagged principal is its canonical text, as everywhere else on the Internet Computer. Inside a composite it
+    // stays `principal "..."` so that the Candid text of the composite is still Candid.
+    if (node.candid === "principal") return this.charge(value);
+    return this.charge(this.#raw(node, value, where));
+  }
+
+  /** Candid text of a whole argument tuple (the "raw arguments" of spec section 11 item 1), tagged children formatted. */
+  tupleText(nodes, values) {
+    return this.charge(`(${nodes.map((n, i) => this.#child(n, values[i], `argument ${i}`)).join(", ")})`);
+  }
+
+  /**
+   * Candid text of a whole argument tuple with no formatter applied: base units, nanoseconds, blobs as bytes. A view
+   * that does not depend on the profile's units, for a reader who checks the profile itself (spec section 11 item 1).
+   */
+  plainTupleText(nodes, values) {
+    this.#plain = true;
+    try {
+      return this.charge(`(${nodes.map((n, i) => this.#child(n, values[i], `argument ${i}`)).join(", ")})`);
+    } finally {
+      this.#plain = false;
+    }
+  }
+
+  /** The formatter's text, or null when the position has no value tag or the formatter refuses the value. */
+  #formatted(node, value, where) {
+    if (this.#plain) return null;
+    const f = this.formatter(node);
+    if (f === null) return null;
+    try {
+      return f.tag === "timestamp" && this.utcOffsetMinutes !== null ? this.#zoned(f, value) : f.display(value);
+    } catch (e) {
+      if (!(e instanceof FormatError)) throw e;
+      this.diagnostics.push({ code: "W_FORMAT_FALLBACK", at: where, message: `the ${f.tag} formatter refused the value (${e.code}: ${e.message}); it is shown as raw Candid text` });
+      return null;
+    }
+  }
+
+  /** A timestamp in the requested zone: the instant shifted by whole minutes, then shown with the library's calendar code. */
+  #zoned(f, value) {
+    const offset = this.utcOffsetMinutes;
+    const local = BigInt(convertUnit(value, f.args.unit, "ns")) + BigInt(offset) * 60_000_000_000n;
+    const utc = displayTimestamp(local, { unit: "ns", candid: "int" });
+    this.usedZone = true;
+    return `${utc.slice(0, -1).replace("T", " ")} ${zoneName(offset)}`;
+  }
+
+  /** A child of a composite: absent is `null`, a tagged child uses its formatter, any other is raw (`opt` marks a present optional). */
+  #child(node, value, where) {
+    if (node.optional === true && value === null) return "null";
+    const shown = this.#formatted(node, value, where);
+    if (shown !== null) return shown;
+    const raw = this.#raw(node, value, where);
+    return node.optional === true ? `opt ${raw}` : raw;
+  }
+
+  #raw(node, value, where) {
+    switch (node.candid) {
+      case "null":
+      case "reserved":
+        return "null";
+      case "bool":
+        return value ? "true" : "false";
+      case "text":
+        return candidString(value);
+      case "principal":
+        return `principal "${value}"`;
+      case "blob":
+        return `blob "${[...value].map((b) => `\\${b.toString(16).padStart(2, "0")}`).join("")}"`;
+      case "float32":
+      case "float64":
+        return Number.isNaN(value) ? "nan" : value === Infinity ? "inf" : value === -Infinity ? "-inf" : String(value);
+      case "vec":
+        return value.length === 0 ? "vec {}" : `vec { ${value.map((e, i) => this.#child(node.element, e, `${where}[${i}]`)).join("; ")} }`;
+      case "record": {
+        const parts = entriesOf(node.fields).map(([key, child]) => `${candidLabel(key)} = ${this.#child(child, value[key], `${where}.${key}`)}`);
+        return parts.length === 0 ? "record {}" : `record { ${parts.join("; ")} }`;
+      }
+      case "variant": {
+        const arm = entriesOf(node.cases).find(([key]) => key === value.tag);
+        const key = arm === undefined ? String(value.tag) : arm[0];
+        if (arm === undefined || (arm[1].candid === "null" && arm[1].optional !== true)) return `variant { ${candidLabel(key)} }`;
+        return `variant { ${candidLabel(key)} = ${this.#child(arm[1], value.value, `${where}.${key}`)} }`;
+      }
+      default:
+        return String(value); // integers (decimal strings)
+    }
+  }
+
+  /**
+   * The ICRC-21 `Value` of one value (spec section 12). Falls back to `Text` whenever the typed form cannot carry
+   * the value exactly: an amount above nat64 or negative or without a symbol, a timestamp or duration that is not a
+   * whole number of seconds, below zero or above nat64.
+   *
+   * @returns {{ TokenAmount: object } | { TimestampSeconds: object } | { DurationSeconds: object } | { Text: { content: string } }}
+   */
+  icrc21Value(node, value, where) {
+    const f = this.formatter(node);
+    if (f !== null && typeof value === "string") {
+      const typed = this.#typed(f, value);
+      if (typed !== null) return typed;
+    }
+    return { Text: { content: this.text(node, value, where) } };
+  }
+
+  #typed(f, value) {
+    try {
+      if (f.tag === "amount") {
+        const amount = BigInt(value);
+        const { decimals, symbol } = f.args;
+        if (amount < 0n || amount > U64_MAX || typeof symbol !== "string") return null;
+        f.display(value); // the library must accept the value too (type range), or it is shown as raw text
+        return { TokenAmount: { decimals, amount, symbol } };
+      }
+      if (f.tag === "timestamp" || f.tag === "duration") {
+        const seconds = BigInt(convertUnit(value, f.args.unit, "s")); // throws E_INEXACT when not whole seconds
+        if (seconds < 0n || seconds > U64_MAX) return null;
+        f.display(value);
+        return f.tag === "timestamp" ? { TimestampSeconds: { amount: seconds } } : { DurationSeconds: { amount: seconds } };
+      }
+    } catch (e) {
+      if (e instanceof FormatError) return null;
+      throw e;
+    }
+    return null;
+  }
+}
+
+/** `UTC`, `UTC+02:00`, `UTC-05:30`. */
+export function zoneName(offsetMinutes) {
+  if (offsetMinutes === 0) return "UTC";
+  const abs = Math.abs(offsetMinutes);
+  return `UTC${offsetMinutes < 0 ? "-" : "+"}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+
+/** A Candid text literal: quotes, backslashes and invisible characters escaped. */
+function candidString(s) {
+  const escaped = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+  return `"${visible(escaped)}"`;
+}
+
+/** A record field or variant case label as Candid writes it: an identifier, a number for `#id`, else quoted. */
+function candidLabel(key) {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return key;
+  if (/^#(0|[1-9][0-9]*)$/.test(key)) return key.slice(1);
+  return candidString(key);
+}

package/src/errors.mjs

@@ -0,0 +1,51 @@
+// Every failure of this package is a ConsentError with a stable `code`. The ICRC-21 entry point maps
+// the codes to the ICRC-21 error variants (icrc21.mjs); the lower-level functions throw them.
+
+export class ConsentError extends Error {
+  /**
+   * @param {string} code  one of CODES
+   * @param {string} message  written for a developer, not for the end user (ICRC-21: icrc21_error_info.description)
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "ConsentError";
+    this.code = code;
+  }
+}
+
+export const CODES = Object.freeze({
+  // the call is malformed (ICRC-21 UnsupportedCanisterCall)
+  METHOD_UNKNOWN: "E_METHOD_UNKNOWN", // the resolved form has no such method
+  DECODE: "E_DECODE", // the argument bytes do not decode against the method's signature
+  TOO_LARGE: "E_TOO_LARGE", // the arguments exceed the bounds of a consent message (never truncated)
+  LANGUAGE: "E_LANGUAGE", // only with languagePolicy "error": the requested language is not supported
+  REQUEST: "E_REQUEST", // the ICRC-21 request itself is malformed
+  // this generator cannot describe the call (ICRC-21 ConsentMessageUnavailable)
+  UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE", // a position the resolved form cannot type (recursive cut, func, service)
+  // the profile or the caller's context is wrong (ICRC-21 GenericError)
+  RESOLVED_FORM: "E_RESOLVED_FORM", // the resolved form is malformed
+  TEMPLATE: "E_TEMPLATE", // the intent template does not parse
+  TEMPLATE_PATH: "E_TEMPLATE_PATH", // a placeholder names a position the method does not have
+  // pass-through of the format library's configuration errors (a dynamic ref the caller did not supply, a bad tag argument)
+  REF_UNRESOLVED: "E_REF_UNRESOLVED",
+  ARG: "E_ARG",
+  TAG_TYPE: "E_TAG_TYPE",
+  TAG_CONFLICT: "E_TAG_CONFLICT",
+});
+
+/** ICRC-21 GenericError.error_code values this package uses (a nat chosen by the canister; see the README). */
+export const GENERIC_ERROR_CODES = Object.freeze({
+  [CODES.RESOLVED_FORM]: 1000n,
+  [CODES.TEMPLATE]: 1001n,
+  [CODES.TEMPLATE_PATH]: 1002n,
+  [CODES.REF_UNRESOLVED]: 1100n,
+  [CODES.ARG]: 1101n,
+  [CODES.TAG_TYPE]: 1102n,
+  [CODES.TAG_CONFLICT]: 1103n,
+  INTERNAL: 1999n,
+});
+
+export function fail(code, message, options) {
+  throw new ConsentError(code, message, options);
+}

package/src/icrc21-codec.mjs

@@ -0,0 +1,160 @@
+// The ICRC-21 types (topics/ICRC-21/ICRC-21.did of dfinity/wg-identity-authentication, commit pinned in
+// test/upstream/icrc21/SOURCE.json) as @candid-core/schema schemas, and the conversion between the JS shapes
+// this package uses and the shapes of the codec.
+//
+// JS shape (what `icrc21ConsentMessage` takes and returns):
+//   variant   { Tag: payload }                  a bare case is { Tag: null }
+//   opt T     null when absent, else the value
+//   nat, nat64   bigint            nat8, int16   number            blob   Uint8Array
+//   vec record { text; Value }   array of [label, value] pairs
+// Codec shape: variants are { tag, value } (a bare case is { tag }).
+
+import { c } from "@candid-core/schema";
+import { decode, encode } from "@candid-core/schema/codec";
+import { asUint8Array } from "@meantjs/format";
+import { CODES, fail } from "./errors.mjs";
+
+const Metadata = c.record({ language: c.text, utc_offset_minutes: c.opt(c.int16) });
+const DeviceSpec = c.variant({ GenericDisplay: c.null, FieldsDisplay: c.null });
+const MessageSpec = c.record({ metadata: Metadata, device_spec: c.opt(DeviceSpec) });
+export const RequestSchema = c.record({ method: c.text, arg: c.blob(), user_preferences: MessageSpec });
+
+const TokenAmount = c.record({ decimals: c.nat8, amount: c.nat64, symbol: c.text });
+const TimestampSeconds = c.record({ amount: c.nat64 });
+const DurationSeconds = c.record({ amount: c.nat64 });
+const TextValue = c.record({ content: c.text });
+const Value = c.variant({ TokenAmount, TimestampSeconds, DurationSeconds, Text: TextValue });
+const ConsentMessage = c.variant({
+  GenericDisplayMessage: c.text,
+  FieldsDisplayMessage: c.record({ intent: c.text, fields: c.vec(c.tuple([c.text, Value])) }),
+});
+const ConsentInfo = c.record({ consent_message: ConsentMessage, metadata: Metadata });
+const ErrorInfo = c.record({ description: c.text });
+const Icrc21Error = c.variant({
+  UnsupportedCanisterCall: ErrorInfo,
+  ConsentMessageUnavailable: ErrorInfo,
+  InsufficientPayment: ErrorInfo,
+  GenericError: c.record({ error_code: c.nat, description: c.text }),
+});
+export const ResponseSchema = c.variant({ Ok: ConsentInfo, Err: Icrc21Error });
+
+// ------------------------------------------------------------------------------------------ shape conversion
+
+function toCodec(schema, v, where) {
+  switch (schema.kind) {
+    case "variant": {
+      const keys = v !== null && typeof v === "object" ? Object.keys(v) : [];
+      if (keys.length !== 1 || !Object.hasOwn(schema.arms, keys[0])) fail(CODES.REQUEST, `${where}: expected a variant with exactly one of ${Object.keys(schema.arms).join(", ")}`);
+      const arm = schema.arms[keys[0]];
+      return arm.kind === "primitive" && arm.primitive === "null" ? { tag: keys[0] } : { tag: keys[0], value: toCodec(arm, v[keys[0]], `${where}.${keys[0]}`) };
+    }
+    case "record":
+      return Object.fromEntries(Object.entries(schema.fields).map(([k, s]) => [k, toCodec(s, v?.[k], `${where}.${k}`)]));
+    case "tuple":
+      return schema.elements.map((s, i) => toCodec(s, v?.[i], `${where}[${i}]`));
+    case "vec":
+      return v.map((e, i) => toCodec(schema.inner, e, `${where}[${i}]`));
+    case "opt":
+      return v === null || v === undefined ? null : toCodec(schema.inner, v, where);
+    default:
+      return v;
+  }
+}
+
+function fromCodec(schema, v) {
+  switch (schema.kind) {
+    case "variant": {
+      const arm = schema.arms[v.tag];
+      return { [v.tag]: arm.kind === "primitive" && arm.primitive === "null" ? null : fromCodec(arm, v.value) };
+    }
+    case "record":
+      return Object.fromEntries(Object.entries(schema.fields).map(([k, s]) => [k, fromCodec(s, v[k])]));
+    case "tuple":
+      return schema.elements.map((s, i) => fromCodec(s, v[i]));
+    case "vec":
+      return v.map((e) => fromCodec(schema.inner, e));
+    case "opt":
+      return v === null ? null : fromCodec(schema.inner, v);
+    default:
+      return v;
+  }
+}
+
+/** The widths the JS shape accepts for the numbers the codec wants as bigint. */
+function widen(schema, v) {
+  switch (schema.kind) {
+    case "primitive":
+      return schema.primitive === "nat" || schema.primitive === "nat64" ? (typeof v === "number" && Number.isSafeInteger(v) ? BigInt(v) : v) : v;
+    case "variant":
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, schema.arms[k] ? widen(schema.arms[k], x) : x]));
+    case "record":
+      return Object.fromEntries(Object.entries(schema.fields).map(([k, s]) => [k, widen(s, v?.[k])]));
+    case "tuple":
+      return schema.elements.map((s, i) => widen(s, v?.[i]));
+    case "vec":
+      return Array.isArray(v) ? v.map((e) => widen(schema.inner, e)) : v;
+    case "opt":
+      return v === null || v === undefined ? null : widen(schema.inner, v);
+    default:
+      return v;
+  }
+}
+
+function run(schema, value, what) {
+  const r = encode(schema, toCodec(schema, widen(schema, value), what));
+  if (!r.ok) fail(CODES.REQUEST, `${what} does not match the ICRC-21 type: ${r.issues[0].code} at ${r.issues[0].path}: ${r.issues[0].message}`);
+  return r.bytes;
+}
+
+/**
+ * Candid-encode an `icrc21_consent_message_response` (the reply of `icrc21_canister_call_consent_message`).
+ * @param {{ Ok: object } | { Err: object }} response  the JS shape of `icrc21ConsentMessage`'s result
+ * @returns {Uint8Array}
+ */
+export function encodeConsentResponse(response) {
+  return run(ResponseSchema, response, "response");
+}
+
+/** Decode a Candid-encoded `icrc21_consent_message_response` into the JS shape. */
+export function decodeConsentResponse(bytes) {
+  const r = decode(ResponseSchema, bytes);
+  if (!r.ok) fail(CODES.DECODE, `not an icrc21_consent_message_response: ${r.issues[0].code} at ${r.issues[0].path}`);
+  return fromCodec(ResponseSchema, r.value);
+}
+
+/** Candid-encode an `icrc21_consent_message_request` (the argument of the ICRC-21 call). */
+export function encodeConsentRequest(request) {
+  return run(RequestSchema, request, "request");
+}
+
+/** Decode the argument of `icrc21_canister_call_consent_message` into the JS shape. Throws E_REQUEST on bytes that are not one. */
+export function decodeConsentRequest(bytes) {
+  const r = decode(RequestSchema, bytes, { maxBytes: 2 * 1024 * 1024 + 4096 });
+  if (!r.ok) fail(CODES.REQUEST, `not an icrc21_consent_message_request: ${r.issues[0].code} at ${r.issues[0].path}: ${r.issues[0].message}`);
+  return fromCodec(RequestSchema, r.value);
+}
+
+const HEX_DIGITS = new TextEncoder().encode("0123456789abcdef");
+const ascii = new TextDecoder();
+/**
+ * Lowercase hex of the bytes (no Buffer: this module runs in a browser too). The digits go into one byte array and
+ * are decoded once, so a blob near the 2 MiB request limit costs two buffers, not a string per byte.
+ */
+function hex(bytes) {
+  const out = new Uint8Array(bytes.length * 2);
+  for (let i = 0; i < bytes.length; i++) {
+    out[2 * i] = HEX_DIGITS[bytes[i] >> 4];
+    out[2 * i + 1] = HEX_DIGITS[bytes[i] & 15];
+  }
+  return ascii.decode(out);
+}
+
+/** JSON-safe copy of a JS-shape value: bigint as a decimal string (D-006), Uint8Array as { hex }. For fixtures and logs. */
+export function toJson(value) {
+  if (typeof value === "bigint") return value.toString();
+  const bytes = asUint8Array(value); // from any realm
+  if (bytes !== null) return { hex: hex(bytes) };
+  if (Array.isArray(value)) return value.map(toJson);
+  if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toJson(v)]));
+  return value;
+}