@meantjs/consent 0.0.0-bootstrap → 0.1.0

package/src/index.d.mts

@@ -0,0 +1,234 @@
+// 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";
+  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 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).

package/src/model.mjs

@@ -0,0 +1,159 @@
+// The neutral model of one consent message: a title, an optional sentence (the rendered intent template as
+// literal and field parts) and the fields. Both ICRC-21 forms are rendered from it (render.mjs), so they cannot
+// disagree about which values the call carries.
+//
+// Which fields appear:
+//   - a method with an `intent` tag: the placeholders of its template that are present (spec section 6; section 12:
+//     "one (label, Value) row per placeholder"), in template order, once per distinct path;
+//   - a method without one: the generic intent. Title from `describe.label` of the method, else `Call <method>`;
+//     one field per leaf of the decoded arguments (records are flattened, tagged positions such as accounts are
+//     leaves, absent optionals are left out). More than MAX_FIELDS fields or MAX_ELEMENTS list elements is
+//     refused (E_TOO_LARGE), never truncated.
+
+import { VALUE_TAGS } from "@meantjs/format";
+import { decodeArguments } from "./decode.mjs";
+import { CODES, ConsentError, fail } from "./errors.mjs";
+import { effectKind, entriesOf, labelOf, methodOf } from "./resolved.mjs";
+import { parseTemplate } from "./template.mjs";
+import { resolvePath, valuesAt } from "./paths.mjs";
+
+export const MAX_FIELDS = 64;
+export const MAX_ELEMENTS = 256;
+
+/**
+ * @typedef {object} Field
+ * @property {string} path  the placeholder path, or the dotted path of a flattened leaf
+ * @property {string} label  describe.label of the position, else its field name (raw, not yet escaped)
+ * @property {object} node  the resolved-form position
+ * @property {unknown[]} values  the present values: none (absent), one, or one per list element
+ *
+ * @typedef {{ lit: string } | { field: Field }} SentencePart
+ *
+ * @typedef {object} Model
+ * @property {string} method
+ * @property {string} effect  the effect kind of the method (spec section 5.3)
+ * @property {string} title
+ * @property {SentencePart[] | null} sentence  null for a method without an intent template
+ * @property {Field[]} fields
+ * @property {object[]} argNodes
+ * @property {unknown[]} argValues
+ * @property {object[]} diagnostics
+ * @property {{ intent: { origin: string, profile?: string } | null, profiles: object[] }} provenance  where the words come from
+ *   (ICRC-49: a signer warns when it, not the canister, wrote the message; spec section 11 item 1: a profile is a claim)
+ */
+
+/**
+ * @param {{ resolved: object, method: string, arg: Uint8Array | ArrayBuffer | number[], limits?: object }} input
+ * @returns {Model}
+ */
+export function buildModel({ resolved, method: name, arg, limits }) {
+  const method = methodOf(resolved, name);
+  const argValues = decodeArguments(method, arg, limits);
+  const diagnostics = [];
+  const intent = method.tags?.intent?.args;
+  const title = typeof intent?.title === "string" && intent.title.trim() !== "" ? intent.title : (labelOf(method) ?? `Call ${name}`);
+  const tagOrigin = intent ? { origin: method.tags.intent.origin, ...(method.tags.intent.profile === undefined ? {} : { profile: method.tags.intent.profile }) } : null;
+  const provenance = { intent: tagOrigin, profiles: Array.isArray(resolved.profiles) ? resolved.profiles : [] };
+  const base = { method: name, effect: effectKind(method), title, argNodes: method.args, argValues, diagnostics, provenance };
+
+  if (intent && typeof intent.template === "string") {
+    try {
+      const { sentence, fields } = applyTemplate(method, argValues, parseTemplate(intent.template));
+      return { ...base, sentence, fields };
+    } catch (e) {
+      // A template the profile got wrong must not leave the user without a message: fall back to the generic
+      // intent, which lists every argument, and say so.
+      if (!(e instanceof ConsentError) || (e.code !== CODES.TEMPLATE && e.code !== CODES.TEMPLATE_PATH)) throw e;
+      diagnostics.push({ code: "W_TEMPLATE_FALLBACK", at: name, message: `${e.code}: ${e.message}; the generic intent is used instead` });
+    }
+  }
+  return { ...base, sentence: null, fields: flatten(method, argValues) };
+}
+
+// ---------------------------------------------------------------------------------------------- template
+
+function nameOf(path, resolvedPath) {
+  for (let i = resolvedPath.steps.length - 1; i >= 0; i--) {
+    const s = resolvedPath.steps[i];
+    if (s.kind !== "elem") return s.key;
+  }
+  return `Argument ${resolvedPath.index + 1}`;
+}
+
+function applyTemplate(method, argValues, parts) {
+  const known = new Map(); // path -> Field
+  const sentence = [];
+  const fields = [];
+
+  const lookup = (path) => {
+    const hit = known.get(path);
+    if (hit) return { field: hit, fresh: false };
+    const rp = resolvePath(method, path);
+    if (rp.error) return { error: rp.error };
+    const values = valuesAt(rp, argValues);
+    if (values.length > MAX_ELEMENTS) fail(CODES.TOO_LARGE, `{${path}} has ${values.length} values; the limit is ${MAX_ELEMENTS}`);
+    return { field: { path, label: labelOf(rp.node) ?? nameOf(path, rp), node: rp.node, values }, fresh: true };
+  };
+  const register = ({ field, fresh }) => {
+    if (!fresh) return field;
+    known.set(field.path, field);
+    fields.push(field);
+    if (fields.length > MAX_FIELDS) fail(CODES.TOO_LARGE, `the template has more than ${MAX_FIELDS} distinct placeholders`);
+    return field;
+  };
+
+  for (const part of parts) {
+    if (part.t === "lit") sentence.push({ lit: part.text });
+    else if (part.t === "ph") {
+      const found = lookup(part.path);
+      if (found.error) fail(CODES.TEMPLATE_PATH, `{${part.path}}: ${found.error}`);
+      sentence.push({ field: register(found) });
+    } else {
+      // [ ... ]: dropped when any placeholder inside is absent (null) or names a position this method lacks.
+      const looked = part.parts.map((p) => (p.t === "ph" ? lookup(p.path) : null));
+      const unresolved = looked.find((l) => l?.error);
+      if (unresolved || looked.some((l) => l && l.field.values.length === 0)) continue;
+      for (let i = 0; i < part.parts.length; i++) {
+        const p = part.parts[i];
+        sentence.push(p.t === "lit" ? { lit: p.text } : { field: register(looked[i]) });
+      }
+    }
+  }
+  return { sentence, fields };
+}
+
+// ---------------------------------------------------------------------------------------------- generic intent
+
+const hasValueTag = (node) => VALUE_TAGS.some((t) => node.tags && Object.hasOwn(node.tags, t));
+
+/**
+ * Field order of the resolved form is canonical id order (spec section 10), which reads as random. `ui.order`
+ * ("use ui.order for presentation") puts the fields that have one first, ascending; the rest keep id order.
+ */
+function presentationOrder(entries) {
+  const order = (child) => {
+    const n = child.tags?.ui?.args?.order;
+    return Number.isFinite(n) ? n : Infinity;
+  };
+  return entries.map((e, i) => ({ e, i })).sort((a, b) => order(a.e[1]) - order(b.e[1]) || a.i - b.i).map(({ e }) => e);
+}
+
+function flatten(method, argValues) {
+  const fields = [];
+  const multi = method.args.length > 1;
+  const emit = (node, value, keys, index) => {
+    const dotted = keys.join(".");
+    const label = labelOf(node) ?? (multi ? `Argument ${index + 1}${dotted ? ` ${dotted}` : ""}` : dotted || `Argument ${index + 1}`);
+    if (node.candid === "vec" && value.length > MAX_ELEMENTS) fail(CODES.TOO_LARGE, `${label} has ${value.length} elements; the limit is ${MAX_ELEMENTS}`);
+    fields.push({ path: `(${index})${keys.map((k) => `.${k}`).join("")}`, label, node, values: [value] });
+    if (fields.length > MAX_FIELDS) fail(CODES.TOO_LARGE, `the arguments have more than ${MAX_FIELDS} fields`);
+  };
+  const walk = (node, value, keys, index) => {
+    if (node.optional === true && value === null) return;
+    const children = node.candid === "record" && node.recursive !== true && !hasValueTag(node) ? presentationOrder(entriesOf(node.fields)) : [];
+    if (children.length > 0) for (const [key, child] of children) walk(child, value[key], [...keys, key], index);
+    else emit(node, value, keys, index);
+  };
+  method.args.forEach((node, i) => walk(node, argValues[i], [], i));
+  return fields;
+}

package/src/paths.mjs

@@ -0,0 +1,74 @@
+// Placeholder paths (docs/profile-v0.md section 3.2 rule 9): `{amount}`, `{to.owner}`, `{(0).amount}`, `{items[]}`.
+// A relpath resolves against the method's argument tuple; with one argument it is relative to argument 0.
+//
+// Beyond what section 6 says (decisions of this package, listed in the README):
+//   - a path that crosses a variant case selects that case; when the value has another case the placeholder is absent;
+//   - a path that crosses `[]` yields one value per element (absent elements dropped);
+//   - a path the method does not have is "unresolved": absent inside `[ ... ]`, an error outside (the resolver
+//     already reports it as E_TEMPLATE_PATH; a pack placeholder the service lacks is skipped by the resolver).
+
+import { parseRelPath } from "@meantjs/profile/address";
+import { entriesOf, keyId } from "./resolved.mjs";
+
+/**
+ * @typedef {{ kind: "field" | "case", key: string } | { kind: "elem" }} Step
+ * @typedef {{ index: number, steps: Step[], node: object, nodes: object[] }} ResolvedPath
+ */
+
+/** @returns {ResolvedPath | { error: string }} */
+export function resolvePath(method, relpath) {
+  const parsed = parseRelPath(relpath);
+  if (!parsed) return { error: `bad relative path ${JSON.stringify(relpath)}` };
+  let index = parsed.index;
+  if (index === null) {
+    if (method.args.length !== 1) return { error: `path ${JSON.stringify(relpath)} must start with (i): the method has ${method.args.length} arguments` };
+    index = 0;
+  }
+  if (index >= method.args.length) return { error: `argument index ${index} is out of range` };
+  let node = method.args[index];
+  const nodes = [node];
+  const steps = [];
+  for (const seg of parsed.segs) {
+    if (node.recursive === true) return { error: `${JSON.stringify(relpath)} enters a position the resolved form cuts at a cycle` };
+    if (seg.kind === "elem") {
+      if (node.candid !== "vec" || node.element === undefined) return { error: `"[]" applied to ${node.candid}` };
+      steps.push({ kind: "elem" });
+      node = node.element;
+    } else {
+      const field = entriesOf(node.fields).find(([key]) => keyId(key) === seg.id);
+      const arm = field === undefined ? entriesOf(node.cases).find(([key]) => keyId(key) === seg.id) : undefined;
+      const hit = field ?? arm;
+      if (hit === undefined) return { error: `no field or case ${JSON.stringify(seg.label)} in ${node.candid}` };
+      steps.push({ kind: field ? "field" : "case", key: hit[0] });
+      node = hit[1];
+    }
+    nodes.push(node);
+  }
+  return { index, steps, node, nodes };
+}
+
+/**
+ * The present values at a resolved path. An absent optional anywhere on the way (null), a variant with another
+ * case, or an empty vector gives no values.
+ *
+ * @param {ResolvedPath} path
+ * @param {unknown[]} values  the decoded argument trees
+ * @returns {unknown[]}
+ */
+export function valuesAt(path, values) {
+  let current = [values[path.index]];
+  for (let depth = 0; depth < path.steps.length; depth++) {
+    const step = path.steps[depth];
+    const parentNode = path.nodes[depth];
+    const next = [];
+    for (const v of current) {
+      if (parentNode.optional === true && v === null) continue;
+      if (step.kind === "elem") next.push(...v);
+      else if (step.kind === "field") next.push(v[step.key]);
+      else if (v.tag === step.key) next.push(v.value);
+    }
+    current = next;
+  }
+  const leaf = path.node;
+  return current.filter((v) => !(leaf.optional === true && v === null));
+}

package/src/render.mjs

@@ -0,0 +1,86 @@
+// The two ICRC-21 forms from a Model (docs/profile-v0.md section 12).
+//
+// FieldsDisplayMessage (plain text, no formatting; times are UTC seconds, so the message does not depend on the
+// user's time zone):
+//   intent  = title + ": " + the rendered template      (no template: the title alone)
+//   fields  = one (label, Value) row per placeholder; label = describe.label, else the field name
+//
+// GenericDisplayMessage (Markdown, the layout of the ICRC-21 examples: a `#` title, one paragraph, then
+// `**label:**` lines). Every value comes from the call, which the relying party controls, so it goes into a
+// code span, where Markdown is not parsed. Template text and labels come from the profile and are plain text:
+// their Markdown punctuation is escaped.
+
+import { codeBlock, codeSpan, emptyMarkdown, escapeLineStart, escapeMarkdown, oneLine, visible } from "./text.mjs";
+
+const NONE_PLAIN = "(none)";
+const NONE_MARKDOWN = "*(none)*";
+
+/** Label and title: one line, trimmed, never empty. */
+function plainLabel(raw, fallback) {
+  const s = oneLine(raw).trim();
+  return s === "" ? fallback : s;
+}
+
+/** The text of a field's values, plain: the values joined by ", ", or "(none)". */
+function fieldPlain(field, renderer) {
+  if (field.values.length === 0) return NONE_PLAIN;
+  return field.values.map((v, i) => visible(renderer.text(field.node, v, field.path + (field.values.length > 1 ? `[${i}]` : "")))).join(", ");
+}
+
+function fieldMarkdown(field, renderer) {
+  if (field.values.length === 0) return NONE_MARKDOWN;
+  return field.values.map((v, i) => codeSpan(renderer.text(field.node, v, field.path + (field.values.length > 1 ? `[${i}]` : "")))).join(", ");
+}
+
+/**
+ * @param {import("./model.mjs").Model} model
+ * @param {import("./display.mjs").Renderer} renderer  UTC (no zone)
+ * @param {{ rawArguments?: boolean }} [options]
+ * @returns {{ intent: string, fields: Array<[string, object]> }}
+ */
+export function renderFields(model, renderer, { rawArguments = false } = {}) {
+  const title = plainLabel(model.title, model.method);
+  let intent = title;
+  if (model.sentence !== null) {
+    const sentence = model.sentence.map((p) => ("lit" in p ? oneLine(p.lit) : fieldPlain(p.field, renderer))).join("");
+    if (sentence.trim() !== "") intent = `${title}: ${sentence.trim()}`;
+  }
+  const fields = model.fields.map((f) => [plainLabel(f.label, f.path), fieldValue(f, renderer)]);
+  if (rawArguments) fields.push(["Raw arguments", { Text: { content: visible(renderer.tupleText(model.argNodes, model.argValues)) } }]);
+  return { intent, fields };
+}
+
+/** One row's ICRC-21 Value: typed when the field is a single value the typed form carries exactly, else Text. */
+function fieldValue(field, renderer) {
+  if (field.values.length === 1) {
+    const v = renderer.icrc21Value(field.node, field.values[0], field.path);
+    if (v.Text) v.Text.content = visible(v.Text.content);
+    return v;
+  }
+  return { Text: { content: fieldPlain(field, renderer) } };
+}
+
+/**
+ * @param {import("./model.mjs").Model} model
+ * @param {import("./display.mjs").Renderer} renderer  zoned when the request carried a utc_offset_minutes
+ * @param {{ rawArguments?: boolean, headingLevel?: number }} [options]  `headingLevel`: the title's heading level
+ *   (default 1; an SNS validator rendering sits under governance's own `##` headings and uses 3)
+ * @returns {string}
+ */
+export function renderGeneric(model, renderer, { rawArguments = false, headingLevel = 1 } = {}) {
+  const blocks = [`${"#".repeat(headingLevel)} ${escapeMarkdown(plainLabel(model.title, model.method))}`];
+  if (model.sentence !== null) {
+    let paragraph = model.sentence.map((p) => ("lit" in p ? escapeMarkdown(oneLine(p.lit)) : fieldMarkdown(p.field, renderer))).join("").trim();
+    if (model.sentence[0] && "lit" in model.sentence[0]) paragraph = escapeLineStart(paragraph);
+    if (paragraph !== "") blocks.push(paragraph);
+  }
+  if (model.fields.length > 0) {
+    blocks.push(model.fields.map((f) => `- **${escapeMarkdown(plainLabel(f.label, f.path))}:** ${fieldMarkdown(f, renderer)}`).join("\n"));
+  } else if (model.sentence === null) {
+    blocks.push("This call has no arguments.");
+  }
+  if (rawArguments) blocks.push(`**Raw arguments:**\n\n${codeBlock(renderer.tupleText(model.argNodes, model.argValues))}`);
+  return blocks.join("\n\n");
+}
+
+export { emptyMarkdown };

package/src/resolved.mjs

@@ -0,0 +1,45 @@
+// Read-only accessors over the resolved form (docs/profile-v0.md section 10). The resolved form is data from
+// a resolver, so nothing here trusts its shape beyond what the code reads.
+
+import { idlHash } from "@meantjs/profile/address";
+import { CODES, fail } from "./errors.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The method entry of a resolved form, or a ConsentError. */
+export function methodOf(resolved, name) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods)) {
+    fail(CODES.RESOLVED_FORM, "not a candid-profile-resolved document (format, methods)");
+  }
+  if (typeof name !== "string" || !Object.hasOwn(resolved.methods, name)) {
+    fail(CODES.METHOD_UNKNOWN, `the resolved form has no method ${JSON.stringify(String(name))}`);
+  }
+  const m = resolved.methods[name];
+  if (!isObject(m) || !Array.isArray(m.args)) fail(CODES.RESOLVED_FORM, `method ${name} has no args array`);
+  return m;
+}
+
+/** The Candid field or case id of a resolved-form key: `#123` is the raw id, any other key is a name. */
+export function keyId(key) {
+  return /^#(0|[1-9][0-9]{0,9})$/.test(key) ? Number(key.slice(1)) : idlHash(key);
+}
+
+/** Own entries of a `fields` or `cases` object (never walks the prototype chain). */
+export function entriesOf(bucket) {
+  return isObject(bucket) ? Object.entries(bucket) : [];
+}
+
+/** `describe.label` of a position or method, when it is a non-empty string. */
+export function labelOf(node) {
+  const label = node?.tags?.describe?.args?.label;
+  return typeof label === "string" && label.trim() !== "" ? label : undefined;
+}
+
+export function tagArgs(node, tag) {
+  return node?.tags && Object.hasOwn(node.tags, tag) ? (node.tags[tag]?.args ?? {}) : undefined;
+}
+
+/** The effect kind of a method: its tag, or the spec default (section 5.3: queries read, updates write). */
+export function effectKind(method) {
+  return method.tags?.effect?.args?.kind ?? (method.mode === "query" || method.mode === "composite_query" ? "read" : "write");
+}

package/src/sns.d.mts

@@ -0,0 +1,54 @@
+// Types for @meantjs/consent/sns (Node only: it hashes with node:crypto). Hand-written; the source is
+// src/sns.mjs. test/types.test.mjs keeps the declared names equal to the runtime exports.
+import type { Bytes, ConsentDiagnostic, DecodeLimits, Provenance, ResolvedForm } from "./index.mjs";
+
+export type ValidatorResult = { Ok: string } | { Err: string };
+
+/** The name and version of the rules a rendering follows; part of every rendering. */
+export const SNS_RENDERING_RULES: "candid-profile-sns/v0";
+
+/** An SNS generic-function validator as a function, with non-enumerable `diagnostics` and `provenance`. */
+export function snsValidatorRendering(input: {
+  /** The target method's Candid argument bytes, as governance passes them. */
+  payload: Bytes;
+  resolved: ResolvedForm;
+  /** The target method this validator is registered for. */
+  method: string;
+  refs?: Record<string, unknown>;
+  limits?: DecodeLimits;
+}): ValidatorResult & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
+/** The canister-side wrapper: payload bytes in, the Candid-encoded `variant { Ok : text; Err : text }` out. */
+export function handleSnsValidatorCall(payload: Uint8Array, context: { resolved: ResolvedForm; method: string; refs?: Record<string, unknown>; limits?: DecodeLimits }): Uint8Array;
+export function encodeValidatorResult(result: ValidatorResult): Uint8Array;
+export function decodeValidatorResult(bytes: Uint8Array): ValidatorResult;
+
+export interface GovernanceRendering {
+  functionText: string;
+  payloadSha256: string;
+  payloadRendering: string;
+  targetMethod: string | null;
+  targetCanisterId: string | null;
+  validatorMethod: string | null;
+  validatorCanisterId: string | null;
+}
+/** A stored `payload_text_rendering` split into governance's parts, or null when it is not governance's layout. */
+export function parseGovernanceRendering(text: string): GovernanceRendering | null;
+
+export interface SnsCheck {
+  name: string;
+  ok: boolean;
+  expected?: string;
+  found?: string | null;
+  note?: string;
+}
+/** The reviewer's check of a stored proposal rendering against what the profile renders for the payload. */
+export function verifySnsRendering(input: {
+  payloadTextRendering: string;
+  payload: Bytes;
+  resolved: ResolvedForm;
+  /** The canister the reviewer expects governance to call, as text. */
+  targetCanisterId: string;
+  method: string;
+  refs?: Record<string, unknown>;
+  limits?: DecodeLimits;
+}): { ok: boolean; checks: SnsCheck[]; expectedRendering: string | null; parsed: GovernanceRendering | null };