@meantjs/consent 0.0.0-bootstrap → 0.1.0

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;
+}

package/src/icrc21.mjs

@@ -0,0 +1,139 @@
+// The ICRC-21 entry point: `icrc21_canister_call_consent_message` as a function.
+//
+// Request  : { method, arg, user_preferences: { metadata: { language, utc_offset_minutes }, device_spec } }
+// Response : { Ok: { consent_message, metadata } } | { Err: { UnsupportedCanisterCall | ConsentMessageUnavailable
+//            | InsufficientPayment | GenericError } }                       (shapes: see icrc21-codec.mjs)
+//
+// Behaviors the ICRC-21 text fixes (topics/ICRC-21/ICRC-21.did and icrc_21_consent_msg.md of dfinity/wg-identity-authentication):
+//   - "Providing a message should be preferred over sending an icrc21_error": a language other than English gets the
+//     English message, and `metadata.language` says "en" ("the metadata must match the consent_message provided").
+//     Set `languagePolicy: "error"` to refuse instead (UnsupportedCanisterCall).
+//   - A missing `device_spec` falls back to GenericDisplay (the spec: "one of the values defined in this spec").
+//   - `utc_offset_minutes` absent in the request: the generic message is in UTC. Absent in the response means the
+//     message is not time-zone sensitive; the response carries the applied offset exactly when a time is shown in
+//     the generic form. The fields form carries seconds since the epoch and is never zone-sensitive.
+//   - The consent message must not depend on state: this function has no network access; dynamic refs (decimals,
+//     symbol) are values the caller resolved (spec section 4).
+
+import { bytesOf } from "./bytes.mjs";
+import { ConsentError, CODES, GENERIC_ERROR_CODES } from "./errors.mjs";
+import { generateConsent } from "./consent.mjs";
+import { decodeConsentRequest, encodeConsentResponse } from "./icrc21-codec.mjs";
+
+/** The only language v0 emits (profile `language: "en"`; spec section 1: multi-language templates are a non-goal). */
+export const SUPPORTED_LANGUAGE = "en";
+const MAX_OFFSET_MINUTES = 24 * 60;
+const MAX_DESCRIPTION = 1000;
+
+const BCP47 = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8})*$/;
+
+/**
+ * @param {object} request  the ICRC-21 request in the JS shape
+ * @param {object} context
+ * @param {object} context.resolved  the resolved form of the target canister (docs/profile-v0.md section 10)
+ * @param {Record<string, unknown>} [context.refs]  resolved dynamic refs, keyed by `from`: { "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }
+ * @param {"fallback" | "error"} [context.languagePolicy]  default "fallback" (the ICRC-21 preference)
+ * @param {boolean} [context.rawArguments]  append the decoded raw arguments (spec section 11 item 1)
+ * @param {object} [context.limits]  decoder limits
+ * @returns {{ Ok: object } | { Err: object }}  plus two non-enumerable properties on the result: `diagnostics` (what was
+ *   adjusted on the way: format fallbacks, language fallback) and `provenance` (`{ intent: { origin, profile } | null, profiles }`,
+ *   so a signer can warn when the words come from a profile and not from the canister)
+ */
+export function icrc21ConsentMessage(request, context) {
+  const diagnostics = [];
+  const extras = { provenance: null };
+  let result;
+  try {
+    result = { Ok: build(request, context, diagnostics, extras) };
+  } catch (e) {
+    result = { Err: toIcrc21Error(e) };
+    diagnostics.push({ code: e instanceof ConsentError ? e.code : "E_INTERNAL", at: "request", message: String(e?.message ?? e) });
+  }
+  Object.defineProperty(result, "diagnostics", { value: diagnostics, enumerable: false });
+  Object.defineProperty(result, "provenance", { value: extras.provenance, enumerable: false });
+  return result;
+}
+
+function build(request, context, diagnostics, extras) {
+  const { resolved, refs = {}, languagePolicy = "fallback", rawArguments = false, limits } = context ?? {};
+  if (request === null || typeof request !== "object") throw new ConsentError(CODES.REQUEST, "the request is not an object");
+  const { method, user_preferences: prefs } = request;
+  const arg = bytesOf(request.arg);
+  if (typeof method !== "string") throw new ConsentError(CODES.REQUEST, "request.method must be text");
+  if (arg === null) throw new ConsentError(CODES.REQUEST, "request.arg must be bytes: a Uint8Array, an ArrayBuffer or an array of integers 0 to 255");
+  const language = prefs?.metadata?.language;
+  if (typeof language !== "string") throw new ConsentError(CODES.REQUEST, "user_preferences.metadata.language must be text");
+
+  // language
+  const primary = BCP47.test(language) ? language.split(/[-_]/)[0].toLowerCase() : null;
+  if (primary !== SUPPORTED_LANGUAGE && languagePolicy === "error") {
+    throw new ConsentError(CODES.LANGUAGE, `language ${JSON.stringify(language.slice(0, 40))} is not supported; this generator writes "${SUPPORTED_LANGUAGE}"`);
+  }
+  const answeredLanguage = primary === SUPPORTED_LANGUAGE ? language.replace("_", "-") : SUPPORTED_LANGUAGE;
+  if (primary !== SUPPORTED_LANGUAGE) diagnostics.push({ code: "I_LANGUAGE_FALLBACK", at: "user_preferences", message: `language ${JSON.stringify(language.slice(0, 40))} is not supported; the message is in "${SUPPORTED_LANGUAGE}" and the metadata says so` });
+
+  // device spec
+  const spec = deviceSpecOf(prefs.device_spec);
+
+  // time zone
+  let offset = prefs.metadata.utc_offset_minutes ?? null;
+  if (offset !== null && (!Number.isInteger(offset) || Math.abs(offset) > MAX_OFFSET_MINUTES)) {
+    diagnostics.push({ code: "W_UTC_OFFSET_IGNORED", at: "user_preferences", message: `utc_offset_minutes ${String(offset)} is outside +-${MAX_OFFSET_MINUTES}; UTC is used` });
+    offset = null;
+  }
+
+  const r = generateConsent({ resolved, method, arg, refs, form: spec === "FieldsDisplay" ? "fields" : "generic", utcOffsetMinutes: offset, rawArguments, limits });
+  diagnostics.push(...r.diagnostics);
+  extras.provenance = r.provenance;
+  return {
+    consent_message: r.message,
+    metadata: { language: answeredLanguage, utc_offset_minutes: r.zoneSensitive ? (offset ?? 0) : null },
+  };
+}
+
+function deviceSpecOf(spec) {
+  if (spec === undefined || spec === null) return "GenericDisplay";
+  if (spec === "GenericDisplay" || spec === "FieldsDisplay") return spec;
+  const keys = typeof spec === "object" ? Object.keys(spec) : [];
+  if (keys.length === 1 && (keys[0] === "GenericDisplay" || keys[0] === "FieldsDisplay")) return keys[0];
+  throw new ConsentError(CODES.REQUEST, "device_spec must be GenericDisplay or FieldsDisplay");
+}
+
+const clip = (s) => (s.length > MAX_DESCRIPTION ? `${s.slice(0, MAX_DESCRIPTION)}...` : s);
+
+/** ConsentError (or any thrown value) -> the ICRC-21 `icrc21_error` variant. */
+export function toIcrc21Error(e) {
+  if (!(e instanceof ConsentError)) return { GenericError: { error_code: GENERIC_ERROR_CODES.INTERNAL, description: clip(`internal error: ${String(e?.message ?? e)}`) } };
+  const description = clip(`${e.code}: ${e.message}`);
+  switch (e.code) {
+    case CODES.METHOD_UNKNOWN:
+    case CODES.DECODE:
+    case CODES.TOO_LARGE:
+    case CODES.LANGUAGE:
+    case CODES.REQUEST:
+      return { UnsupportedCanisterCall: { description } };
+    case CODES.UNSUPPORTED_TYPE:
+      return { ConsentMessageUnavailable: { description } };
+    default:
+      return { GenericError: { error_code: GENERIC_ERROR_CODES[e.code] ?? GENERIC_ERROR_CODES.INTERNAL, description } };
+  }
+}
+
+/**
+ * The canister-side wrapper: the Candid-encoded argument of `icrc21_canister_call_consent_message` in, the
+ * Candid-encoded `icrc21_consent_message_response` out. A request that does not decode gets an
+ * UnsupportedCanisterCall reply, as the ICRC-21 interface prescribes for a malformed call.
+ *
+ * @param {Uint8Array} requestBytes
+ * @param {object} context  as for icrc21ConsentMessage
+ * @returns {Uint8Array}
+ */
+export function handleConsentRequest(requestBytes, context) {
+  let response;
+  try {
+    response = icrc21ConsentMessage(decodeConsentRequest(requestBytes), context);
+  } catch (e) {
+    response = { Err: toIcrc21Error(e) };
+  }
+  return encodeConsentResponse(response);
+}