@meantjs/consent 0.0.0-stage → 0.2.0

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

package/src/index.d.mts

@@ -0,0 +1,236 @@
+// Types for @meantjs/consent. Hand-written; the source is plain ES modules (src/*.mjs).
+// test/types.test.mjs keeps the declared names equal to the runtime exports, and `npm run types` compiles a consumer
+// against these declarations under strict TypeScript.
+import type { Formatter } from "@meantjs/format";
+
+/** A candid-profile-resolved v0 document (docs/profile-v0.md section 10). */
+export interface ResolvedForm {
+  format: "candid-profile-resolved";
+  format_version: 0;
+  methods: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** Argument bytes as this package takes them. */
+export type Bytes = Uint8Array | ArrayBuffer | readonly number[];
+
+export interface DecodeLimits {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxElements?: number;
+}
+
+// ------------------------------------------------------------------ the ICRC-21 shapes (ICRC-21.did, JS shape)
+// A variant is { Tag: payload }, opt T is null or the value, nat and nat64 are bigint, nat8 and int16 numbers.
+
+export interface Icrc21Metadata {
+  language: string;
+  utc_offset_minutes: number | null;
+}
+export type Icrc21DeviceSpec = { GenericDisplay: null } | { FieldsDisplay: null };
+export interface Icrc21ConsentMessageSpec {
+  metadata: Icrc21Metadata;
+  device_spec: Icrc21DeviceSpec | null;
+}
+export interface Icrc21ConsentMessageRequest {
+  method: string;
+  arg: Uint8Array;
+  user_preferences: Icrc21ConsentMessageSpec;
+}
+export type Icrc21Value =
+  | { TokenAmount: { decimals: number; amount: bigint; symbol: string } }
+  | { TimestampSeconds: { amount: bigint } }
+  | { DurationSeconds: { amount: bigint } }
+  | { Text: { content: string } };
+export type Icrc21ConsentMessage =
+  | { GenericDisplayMessage: string }
+  | { FieldsDisplayMessage: { intent: string; fields: [string, Icrc21Value][] } };
+export interface Icrc21ConsentInfo {
+  consent_message: Icrc21ConsentMessage;
+  metadata: Icrc21Metadata;
+}
+export type Icrc21Error =
+  | { UnsupportedCanisterCall: { description: string } }
+  | { ConsentMessageUnavailable: { description: string } }
+  | { InsufficientPayment: { description: string } }
+  | { GenericError: { error_code: bigint; description: string } };
+export type Icrc21ConsentMessageResponse = { Ok: Icrc21ConsentInfo } | { Err: Icrc21Error };
+
+/** Where the words of a message come from (ICRC-49: a signer warns when a profile, not the canister, wrote them). */
+export interface Provenance {
+  intent: { origin: string; profile?: string } | null;
+  profiles: unknown[];
+}
+export interface ConsentDiagnostic {
+  code: string;
+  at: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+export interface Icrc21Context {
+  resolved: ResolvedForm;
+  /** Resolved dynamic refs, keyed by `from`: `{ "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }`. */
+  refs?: Record<string, unknown>;
+  /** Default "fallback" (the ICRC-21 preference). */
+  languagePolicy?: "fallback" | "error";
+  /** Append the decoded raw arguments (spec section 11 item 1). */
+  rawArguments?: boolean;
+  limits?: DecodeLimits;
+}
+
+/** The response, with two non-enumerable properties: what was adjusted, and where the words come from. */
+export type Icrc21Result = Icrc21ConsentMessageResponse & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
+
+/** The ICRC-21 call as a function. `arg` may also be an ArrayBuffer or an array of byte values. */
+export function icrc21ConsentMessage(request: Omit<Icrc21ConsentMessageRequest, "arg"> & { arg: Bytes }, context: Icrc21Context): Icrc21Result;
+/** Candid bytes of `icrc21_consent_message_request` in, Candid bytes of `icrc21_consent_message_response` out. */
+export function handleConsentRequest(requestBytes: Uint8Array, context: Icrc21Context): Uint8Array;
+/** A ConsentError (or any thrown value) as the ICRC-21 error variant. */
+export function toIcrc21Error(error: unknown): Icrc21Error;
+/** The only language v0 emits. */
+export const SUPPORTED_LANGUAGE: "en";
+
+export function encodeConsentResponse(response: Icrc21ConsentMessageResponse): Uint8Array;
+export function decodeConsentResponse(bytes: Uint8Array): Icrc21ConsentMessageResponse;
+export function encodeConsentRequest(request: Icrc21ConsentMessageRequest): Uint8Array;
+/** Throws E_REQUEST on bytes that are not a request. */
+export function decodeConsentRequest(bytes: Uint8Array): Icrc21ConsentMessageRequest;
+/** A JSON-safe copy: bigint as a decimal string, Uint8Array as `{ hex }`. */
+export function toJson(value: unknown): unknown;
+
+// ------------------------------------------------------------------ one form, and the parts
+
+export interface ModelField {
+  /** The placeholder path, or the dotted path of a flattened leaf. */
+  path: string;
+  /** `describe.label` of the position, else its field name (raw, not yet escaped). */
+  label: string;
+  node: unknown;
+  /** The present values: none (absent), one, or one per list element. */
+  values: unknown[];
+}
+export type SentencePart = { lit: string } | { field: ModelField };
+export interface Model {
+  method: string;
+  /** The method's effect kind (spec section 5.3). */
+  effect: string;
+  title: string;
+  /** null for a method without an intent template. */
+  sentence: SentencePart[] | null;
+  fields: ModelField[];
+  argNodes: unknown[];
+  argValues: unknown[];
+  diagnostics: ConsentDiagnostic[];
+  provenance: Provenance;
+  [key: string]: unknown;
+}
+
+export interface GenerateConsentInput {
+  resolved: ResolvedForm;
+  method: string;
+  /** The Candid-encoded argument tuple. */
+  arg: Bytes;
+  refs?: Record<string, unknown>;
+  /** Default "generic". */
+  form?: "fields" | "generic";
+  /** Generic form only: show timestamps in this zone (default UTC). */
+  utcOffsetMinutes?: number | null;
+  rawArguments?: boolean;
+  limits?: DecodeLimits;
+}
+/** One form without the ICRC-21 envelope. `zoneSensitive` is true when a timestamp was shown in the requested zone. */
+export function generateConsent(input: GenerateConsentInput): {
+  form: "fields" | "generic";
+  message: Icrc21ConsentMessage;
+  zoneSensitive: boolean;
+  diagnostics: ConsentDiagnostic[];
+  provenance: Provenance;
+  model: Model;
+};
+export function buildModel(input: { resolved: ResolvedForm; method: string; arg: Bytes; limits?: DecodeLimits }): Model;
+/** Argument bytes to one value tree per argument. Throws E_DECODE, E_TOO_LARGE, E_UNSUPPORTED_TYPE or E_RESOLVED_FORM. */
+export function decodeArguments(method: { args: unknown[] }, arg: Bytes, limits?: DecodeLimits): unknown[];
+/** The candid-core codec schema of one resolved-form position. */
+export function schemaFor(node: unknown, where?: string, depth?: number): unknown;
+
+export type TemplateLiteralPart = { t: "lit"; text: string } | { t: "ph"; path: string };
+export type TemplatePart = TemplateLiteralPart | { t: "opt"; parts: TemplateLiteralPart[] };
+/** Throws E_TEMPLATE. */
+export function parseTemplate(template: string): TemplatePart[];
+
+export type PathStep = { kind: "field" | "case"; key: string } | { kind: "elem" };
+export interface ResolvedPath {
+  index: number;
+  steps: PathStep[];
+  node: unknown;
+  nodes: unknown[];
+}
+export function resolvePath(method: { args: unknown[] }, relpath: string): ResolvedPath | { error: string };
+/** The present values at a resolved path. */
+export function valuesAt(path: ResolvedPath, values: unknown[]): unknown[];
+
+/** Renders positions as text, with a budget per message. Used by `renderFields` and `renderGeneric`. */
+export declare class Renderer {
+  /** `utcOffsetMinutes` as a number shows timestamps in that zone (the generic form); otherwise UTC. */
+  constructor(options?: { refs?: Record<string, unknown>; utcOffsetMinutes?: number | null; diagnostics?: ConsentDiagnostic[] });
+  refs: Record<string, unknown>;
+  utcOffsetMinutes: number | null;
+  diagnostics: ConsentDiagnostic[];
+  chars: number;
+  /** Set when a timestamp was shown in the requested zone. */
+  usedZone: boolean;
+  formatter(node: unknown): Formatter | null;
+  charge(text: string): string;
+  text(node: unknown, value: unknown, where?: string): string;
+  tupleText(nodes: unknown[], values: unknown[]): string;
+  plainTupleText(nodes: unknown[], values: unknown[]): string;
+}
+/** `UTC`, `UTC+02:00`, `UTC-05:30`. */
+export function zoneName(offsetMinutes: number): string;
+export function renderFields(model: Model, renderer: Renderer, options?: { rawArguments?: boolean }): { intent: string; fields: [string, Icrc21Value][] };
+/** `headingLevel`: the title's heading level (default 1). */
+export function renderGeneric(model: Model, renderer: Renderer, options?: { rawArguments?: boolean; headingLevel?: number }): string;
+
+/** A Markdown code span that shows the string verbatim (invisible characters made visible). */
+export function codeSpan(s: string): string;
+export function escapeMarkdown(s: string): string;
+/** Invisible characters shown as `\u{202e}`; nothing is dropped. */
+export function visible(s: string): string;
+
+// ------------------------------------------------------------------ errors
+
+export const CODES: Readonly<{
+  METHOD_UNKNOWN: "E_METHOD_UNKNOWN";
+  DECODE: "E_DECODE";
+  TOO_LARGE: "E_TOO_LARGE";
+  LANGUAGE: "E_LANGUAGE";
+  REQUEST: "E_REQUEST";
+  DEPLOYMENT: "E_DEPLOYMENT";
+  UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE";
+  RESOLVED_FORM: "E_RESOLVED_FORM";
+  TEMPLATE: "E_TEMPLATE";
+  TEMPLATE_PATH: "E_TEMPLATE_PATH";
+  REF_UNRESOLVED: "E_REF_UNRESOLVED";
+  ARG: "E_ARG";
+  TAG_TYPE: "E_TAG_TYPE";
+  TAG_CONFLICT: "E_TAG_CONFLICT";
+  EXPORT: "E_EXPORT";
+}>;
+export type ConsentErrorCode = (typeof CODES)[keyof typeof CODES];
+/** ICRC-21 `GenericError.error_code` values this package uses. */
+export const GENERIC_ERROR_CODES: Readonly<{
+  E_RESOLVED_FORM: 1000n;
+  E_TEMPLATE: 1001n;
+  E_TEMPLATE_PATH: 1002n;
+  E_REF_UNRESOLVED: 1100n;
+  E_ARG: 1101n;
+  E_TAG_TYPE: 1102n;
+  E_TAG_CONFLICT: 1103n;
+  INTERNAL: 1999n;
+}>;
+export declare class ConsentError extends Error {
+  constructor(code: ConsentErrorCode, message: string, options?: { cause?: unknown });
+  name: "ConsentError";
+  code: ConsentErrorCode;
+}

package/src/index.mjs

@@ -0,0 +1,13 @@
+export { icrc21ConsentMessage, handleConsentRequest, toIcrc21Error, SUPPORTED_LANGUAGE } from "./icrc21.mjs";
+export { encodeConsentResponse, decodeConsentResponse, encodeConsentRequest, decodeConsentRequest, toJson } from "./icrc21-codec.mjs";
+export { generateConsent } from "./consent.mjs";
+export { buildModel } from "./model.mjs";
+export { decodeArguments, schemaFor } from "./decode.mjs";
+export { parseTemplate } from "./template.mjs";
+export { resolvePath, valuesAt } from "./paths.mjs";
+export { Renderer, zoneName } from "./display.mjs";
+export { renderFields, renderGeneric } from "./render.mjs";
+export { codeSpan, escapeMarkdown, visible } from "./text.mjs";
+export { ConsentError, CODES, GENERIC_ERROR_CODES } from "./errors.mjs";
+// SNS validator renderings are the `./sns` subpath (`@meantjs/consent/sns`): they hash with node:crypto,
+// and this entry must bundle for a browser (test/browser-bundle.test.mjs).