@meantjs/consent 0.2.0 → 0.4.0

package/src/evm.mjs

@@ -13,13 +13,20 @@
 //      person must see which contract asks (spec section 11).
 //
 // Refused: a payable function (its native value has no position yet, O2), and a call with no matching selector.
+//
+// A typed message (EIP-712, spec section 15.9) is the other thing an EVM wallet is asked to sign: `eip712Consent`
+// gives it the same model and layouts, after checking that the request is the message a profile describes (its chain,
+// its contract, its domain, its type hash) and reading its values strictly. An amount whose token a field names is
+// shown with that token's decimals and symbol, which the caller supplies per address (`tokens`), and its address.
 
-import { AbiError, decodeParams, parseSignature, readAddress } from "@meantjs/profile/evm";
-import { Renderer } from "./display.mjs";
+import { AbiError, DEFAULT_ABI_LIMITS, decodeParams, eip712TypeHash, keccak256Hex, parseEip712Types, parseSignature, readAddress, typedDataDigest } from "@meantjs/profile/evm";
+import { Renderer, TokenAmount } from "./display.mjs";
 import { CODES, ConsentError, fail } from "./errors.mjs";
+import { grantOf } from "./grant.mjs";
 import { modelOf } from "./model.mjs";
+import { resolvePath } from "./paths.mjs";
 import { renderGeneric, renderPlain } from "./render.mjs";
-import { abiView, methodOf } from "./resolved.mjs";
+import { abiView, entriesOf, methodOf, tagArgs } from "./resolved.mjs";
 import { codeSpan } from "./text.mjs";
 
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -85,6 +92,49 @@ function checkTarget(resolved, to, chain) {
   }
 }
 
+/** The caller's `tokens`: the decimals and symbol of each token, keyed by its address in any valid spelling. */
+function tokenTable(tokens) {
+  if (!isObject(tokens)) fail(CODES.REQUEST, "tokens must be an object of token address to { decimals, symbol }");
+  const out = new Map();
+  for (const [k, v] of Object.entries(tokens)) {
+    let address;
+    try {
+      address = readAddress(k);
+    } catch (e) {
+      if (e instanceof AbiError) fail(CODES.REQUEST, `tokens: ${e.message}`);
+      throw e;
+    }
+    if (!isObject(v)) fail(CODES.REQUEST, `tokens[${JSON.stringify(k)}] must be { decimals, symbol }`);
+    if (out.has(address)) fail(CODES.REQUEST, `tokens lists ${address} twice`);
+    out.set(address, { decimals: v.decimals, symbol: v.symbol });
+  }
+  return out;
+}
+
+/**
+ * The arguments with each amount whose token a field names (spec section 15.9) made a TokenAmount: its base units, the
+ * address that field holds in the same array element, and that token's metadata from `tokens`. A token the caller did
+ * not describe stops the message (E_REF_UNRESOLVED): a number without its decimals is never shown (spec section 12
+ * rule 10).
+ */
+function withTokens(name, viewed, args, tokens) {
+  const box = (node, value, keys, indices) => {
+    if (node.candid === "record") return Object.fromEntries(entriesOf(node.fields).map(([k, child]) => [k, box(child, value[k], [...keys, k], indices)]));
+    if (node.candid === "vec") return value.map((e, i) => box(node.element, e, [...keys, "[]"], [...indices, i]));
+    const token = tagArgs(node, "amount")?.token;
+    if (token === undefined) return value;
+    const where = `${name}(0)${keys.map((k) => (k === "[]" ? "[]" : `.${k}`)).join("")}`;
+    const rp = resolvePath(viewed, String(token));
+    let address = rp.error ? undefined : args[rp.index];
+    let n = 0;
+    for (const step of rp.steps ?? []) address = step.kind === "elem" ? address?.[indices[n++]] : address?.[step.key];
+    if (typeof address !== "string" || rp.node.abi !== "address" || n > indices.length) fail(CODES.RESOLVED_FORM, `${where}: amount.token ${JSON.stringify(token)} does not lead to an address in the same element`);
+    if (!tokens.has(address)) fail(CODES.REF_UNRESOLVED, `${where} is an amount of the token ${address}, whose decimals and symbol were not given (tokens); without them it has no text`);
+    return new TokenAmount(value, address, tokens.get(address));
+  };
+  return args.map((v, i) => box(viewed.args[i], v, [], []));
+}
+
 /**
  * The consent text of an EVM call.
  *
@@ -94,13 +144,17 @@ function checkTarget(resolved, to, chain) {
  * @param {string} input.to  the contract called (shown, and checked against the profiles' deployments)
  * @param {number | bigint | string} [input.chainId]  needed when a profile lists deployments
  * @param {Record<string, unknown>} [input.refs]  resolved dynamic refs, for example { "query:decimals": 6, "query:symbol": "USDC" }
+ * @param {Record<string, { decimals: number, symbol?: string }>} [input.tokens]  for an amount whose token a field
+ *   names (spec section 15.9): each such token's decimals() and symbol(), keyed by its address
  * @param {"generic" | "fields"} [input.form]  default "generic"
  * @param {number | null} [input.utcOffsetMinutes]  generic form only (default 0, UTC)
  * @param {boolean} [input.rawArguments]  append the decoded arguments (spec section 11 item 1)
  * @param {object} [input.limits]  decoder limits (maxBytes, maxDepth, maxElements)
- * @returns {{ form: string, message: string | { intent: string, fields: Array<[string, string]> }, method: string, selector: string, to: string, chainId: string | null, diagnostics: object[], provenance: object, model: object }}
+ * @returns {{ form: string, message: string | { intent: string, fields: Array<[string, string]> }, method: string, selector: string, to: string, chainId: string | null, values: Record<string, unknown>, grant: object | null, diagnostics: object[], provenance: object, model: object }}
+ *   `values` are the decoded arguments as `decodeCalldata` gives them, and `grant` what the call grants (spec section
+ *   5.3, D-056; its token is the contract called unless the amount's tag names a field), or null.
  */
-export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits }) {
+export function evmConsent({ resolved, calldata, to, chainId, refs = {}, tokens = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits }) {
   if (form !== "generic" && form !== "fields") fail(CODES.REQUEST, `form must be "generic" or "fields", got ${JSON.stringify(form)}`);
   let target;
   try {
@@ -115,9 +169,10 @@ export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form =
   const method = methodOf(resolved, name, "evm");
   if (method.state_mutability === "payable") fail(CODES.UNSUPPORTED_TYPE, `${name} is payable: the native value a call sends has no position in a profile yet (spec section 15, O2)`);
   const viewed = { ...method, args: method.args.map((n, i) => abiView(n, `${name}(${i})`)) };
-  const model = modelOf(resolved, name, viewed, viewed.args.length ? [values] : []);
+  const model = modelOf(resolved, name, viewed, viewed.args.length ? withTokens(name, viewed, [values], tokenTable(tokens)) : []);
+  const grant = grantOf({ name, method: viewed, argValues: viewed.args.length ? [values] : [], called: target, diagnostics: model.diagnostics });
   const where = `${target}${chain === null ? "" : ` on chain ${chain}`}`;
-  const done = (rest) => ({ ...rest, method: name, selector, to: target, chainId: chain, diagnostics: model.diagnostics, provenance: model.provenance, model });
+  const done = (rest) => ({ ...rest, method: name, selector, to: target, chainId: chain, values, grant, diagnostics: model.diagnostics, provenance: model.provenance, model });
   if (form === "fields") {
     const plain = renderPlain(model, new Renderer({ refs, diagnostics: model.diagnostics }), { rawArguments });
     plain.fields.push(["Contract", where]);
@@ -127,3 +182,185 @@ export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form =
   const text = `${renderGeneric(model, renderer, { rawArguments })}\n\n**Contract:** ${codeSpan(target)}${chain === null ? "" : ` on chain ${chain}`}`;
   return done({ form, message: text });
 }
+
+// ---------------------------------------------------------------------------------------------- EIP-712 messages
+
+/** The domain's fields in the order EIP-712 lists them, with their types. */
+const DOMAIN_FIELDS = [
+  ["name", "string"],
+  ["version", "string"],
+  ["chainId", "uint256"],
+  ["verifyingContract", "address"],
+  ["salt", "bytes32"],
+];
+
+/** One value of a typed message, read strictly (spec section 15.9): the shapes decodeCalldata gives, or E_DECODE. */
+function readTyped(types, type, value, where, budget) {
+  const bad = (message) => fail(CODES.DECODE, `${where}: ${message}`);
+  const arr = /^(.*)\[(\d*)\]$/.exec(type);
+  if (arr) {
+    if (!Array.isArray(value)) bad(`${type} needs an array`);
+    if (arr[2] !== "" && value.length !== Number(arr[2])) bad(`${type} needs ${arr[2]} elements, got ${value.length}`);
+    budget.elements += value.length;
+    if (budget.elements > budget.maxElements) bad(`more than ${budget.maxElements} array elements in the message`);
+    return value.map((v, i) => readTyped(types, arr[1], v, `${where}[${i}]`, budget));
+  }
+  if (Object.hasOwn(types, type)) {
+    if (!isObject(value)) bad(`${type} needs an object of its members`);
+    const members = types[type];
+    for (const k of Object.keys(value)) if (!members.some((m) => m.name === k)) bad(`${type} has no member ${JSON.stringify(k)}`);
+    return Object.fromEntries(members.map((m) => [m.name, Object.hasOwn(value, m.name) ? readTyped(types, m.type, value[m.name], `${where}.${m.name}`, budget) : bad(`${type} needs its member ${m.name}`)]));
+  }
+  const int = /^(u?)int([0-9]+)$/.exec(type);
+  if (int) {
+    let x;
+    if (typeof value === "number" && Number.isSafeInteger(value)) x = BigInt(value);
+    else if (typeof value === "string" && /^-?(?:0|[1-9][0-9]*)$/.test(value) && value !== "-0") x = BigInt(value);
+    else bad(`${type} needs a decimal string or a JSON integer below 2^53, got ${JSON.stringify(value)}`);
+    const bits = BigInt(int[2]);
+    const [min, max] = int[1] === "u" ? [0n, 2n ** bits - 1n] : [-(2n ** (bits - 1n)), 2n ** (bits - 1n) - 1n];
+    if (x < min || x > max) bad(`${x} is outside ${type}`);
+    return x.toString();
+  }
+  if (type === "address") {
+    try {
+      return readAddress(value);
+    } catch (e) {
+      if (e instanceof AbiError) bad(e.message);
+      throw e;
+    }
+  }
+  if (type === "bool") return typeof value === "boolean" ? value : bad("bool needs true or false");
+  if (type === "string") return typeof value === "string" && value.isWellFormed() ? value : bad("string needs well-formed text");
+  const bytes = /^bytes([0-9]*)$/.exec(type);
+  if (bytes) {
+    if (typeof value !== "string" || !/^0x(?:[0-9a-fA-F]{2})*$/.test(value)) bad(`${type} needs 0x and hex digits`);
+    const b = Uint8Array.from(value.slice(2).match(/../g) ?? [], (h) => parseInt(h, 16));
+    if (bytes[1] !== "" && b.length !== Number(bytes[1])) bad(`${type} needs ${bytes[1]} bytes, got ${b.length}`);
+    if (b.length > budget.maxBytes) bad(`${b.length} bytes is over the limit of ${budget.maxBytes}`);
+    return b;
+  }
+  bad(`unknown type ${type}`);
+}
+
+/** The request's domain: only EIP-712's fields, no salt (O3), and its EIP712Domain type, if given, exactly those fields. */
+function readDomain(domain, declared) {
+  if (!isObject(domain)) fail(CODES.REQUEST, "typedData.domain must be an object");
+  for (const k of Object.keys(domain)) if (!DOMAIN_FIELDS.some(([f]) => f === k)) fail(CODES.DOMAIN, `the domain has a field ${JSON.stringify(k)} EIP-712 does not define`);
+  if (Object.hasOwn(domain, "salt")) fail(CODES.DOMAIN, "a domain with a salt is not supported yet (spec section 15.9, O3)");
+  const fields = DOMAIN_FIELDS.filter(([k]) => Object.hasOwn(domain, k)).map(([name, type]) => ({ name, type }));
+  // Each member's name and type, in order; the order of a member's JSON keys is not part of the type (as for the other structs).
+  const same = Array.isArray(declared) && declared.length === fields.length && declared.every((m, i) => isObject(m) && m.name === fields[i].name && m.type === fields[i].type);
+  if (declared !== undefined && !same) {
+    fail(CODES.DOMAIN, `types.EIP712Domain must list the domain's fields in EIP-712 order (${fields.map((f) => `${f.type} ${f.name}`).join(", ")})`);
+  }
+  for (const k of ["name", "version"]) if (Object.hasOwn(domain, k) && typeof domain[k] !== "string") fail(CODES.DOMAIN, `domain.${k} must be a string`);
+  if (!Object.hasOwn(domain, "chainId")) fail(CODES.DOMAIN, "the domain has no chainId, so the signature is valid on every chain; it is refused");
+  if (!Object.hasOwn(domain, "verifyingContract")) fail(CODES.DOMAIN, "the domain has no verifyingContract: the contract that will act on the signature must be known");
+  const chain = readTyped({}, "uint256", domain.chainId, "domain.chainId", { elements: 0, maxElements: 0, maxBytes: 0 });
+  let contract;
+  try {
+    contract = readAddress(domain.verifyingContract);
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.DOMAIN, `domain.verifyingContract: ${e.message}`);
+    throw e;
+  }
+  return { fields, chain, contract };
+}
+
+/** The message of a resolved form whose type hash is the request's; the entry's own encode_type must hash to it. */
+function messageOf(resolved, primaryType, typeHash) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods) || resolved.chain !== "evm") methodOf(resolved, "", "evm"); // throws the right error
+  if (!isObject(resolved.messages)) fail(CODES.TYPE_HASH, "the resolved form describes no EIP-712 message");
+  const hit = entriesOf(resolved.messages).find(([, m]) => isObject(m) && m.type_hash === typeHash);
+  if (!hit) fail(CODES.TYPE_HASH, `no message of the resolved form has the type hash ${typeHash} (${primaryType}); a request is matched by its type hash, never by its name`);
+  const [name, m] = hit;
+  if (typeof m.encode_type !== "string" || `0x${keccak256Hex(m.encode_type)}` !== typeHash || name !== primaryType || !m.encode_type.startsWith(`${name}(`)) {
+    fail(CODES.RESOLVED_FORM, `messages.${name}: its encode_type does not hash to its type_hash, or names another type`);
+  }
+  if (!Array.isArray(m.args) || m.args.length !== 1) fail(CODES.RESOLVED_FORM, `messages.${name} has no args array of one struct`);
+  return { name, message: m };
+}
+
+/**
+ * Every profile that names the domain (`eip712_domain`) must name the request's: its name and its version each equal,
+ * and absent where the profile's is absent (Permit2's domain has no version; one with a version is another domain).
+ */
+function checkDomain(resolved, domain) {
+  for (const p of Array.isArray(resolved.profiles) ? resolved.profiles : []) {
+    if (!isObject(p?.eip712_domain)) continue;
+    for (const k of ["name", "version"]) {
+      const v = p.eip712_domain[k];
+      if (domain[k] === v) continue;
+      const theirs = domain[k] === undefined ? "a domain without one" : JSON.stringify(domain[k]);
+      fail(CODES.DOMAIN, v === undefined ? `profile ${p.name} describes a domain without a ${k}, not one whose ${k} is ${theirs}` : `profile ${p.name} describes the domain whose ${k} is ${JSON.stringify(v)}, not ${theirs}`);
+    }
+  }
+}
+
+/**
+ * The consent text of an EIP-712 signing request (spec section 15.9): the message a profile describes, its values in
+ * words, and what a signature is. Refused before anything is shown when the request does not match: a domain for
+ * another chain than the wallet's or without a chainId or verifyingContract (E_DOMAIN), a contract its profiles do not
+ * list (E_DEPLOYMENT), a domain name or version other than its profiles' (E_DOMAIN), no message with the request's
+ * type hash (E_TYPE_HASH), a message whose values are not exactly its members, canonically written (E_DECODE).
+ *
+ * @param {object} input
+ * @param {object} input.resolved  an EVM contract's resolved form with `messages`
+ * @param {{ types: object, primaryType: string, domain: object, message: object }} input.typedData  the request
+ *   (`eth_signTypedData_v4`'s JSON); `types.EIP712Domain` may be left out
+ * @param {number | bigint | string} input.chainId  the wallet's active chain
+ * @param {Record<string, unknown>} [input.refs]  resolved dynamic refs: `query:` refs are calls to the verifying contract
+ * @param {Record<string, { decimals: number, symbol?: string }>} [input.tokens]  each token an amount's `token` names
+ * @param {"generic" | "fields"} [input.form]  default "generic"
+ * @param {number | null} [input.utcOffsetMinutes]  generic form only (default 0, UTC)
+ * @param {boolean} [input.rawArguments]  append the message's values (spec section 11 item 1)
+ * @param {{ maxBytes?: number, maxElements?: number }} [input.limits]
+ * @returns the text, `primaryType`, `typeHash`, `digest`, `verifyingContract`, `chainId`, `values` (the message as read
+ *   from the typed data, by member name), `grant` (what the signature grants, spec section 5.3, D-056; its token is
+ *   the verifying contract unless the amount's tag names a field), or null, `diagnostics`, `provenance` and `model`
+ */
+export function eip712Consent({ resolved, typedData, chainId, refs = {}, tokens = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits = {} }) {
+  if (form !== "generic" && form !== "fields") fail(CODES.REQUEST, `form must be "generic" or "fields", got ${JSON.stringify(form)}`);
+  if (!isObject(typedData) || !isObject(typedData.types) || typeof typedData.primaryType !== "string" || !isObject(typedData.message)) {
+    fail(CODES.REQUEST, "typedData must be { types, primaryType, domain, message }");
+  }
+  const active = chainOf(chainId);
+  if (active === null) fail(CODES.REQUEST, "give the wallet's active chainId: a signature for another chain is refused");
+  const { EIP712Domain: declared, ...own } = typedData.types;
+  const { fields: domainType, chain, contract } = readDomain(typedData.domain, declared);
+  if (chain !== active) fail(CODES.DOMAIN, `the domain is for chain ${chain}, the wallet is on chain ${active}`);
+  const parsed = parseEip712Types(own, "typedData.types");
+  if (parsed.errors.length) fail(CODES.REQUEST, parsed.errors.map((e) => `${e.at}: ${e.message}`).join("; "));
+  if (!Object.hasOwn(parsed.types, typedData.primaryType)) fail(CODES.REQUEST, `typedData.types has no ${JSON.stringify(typedData.primaryType)}`);
+  const typeHash = eip712TypeHash(parsed.types, typedData.primaryType);
+  const { name, message } = messageOf(resolved, typedData.primaryType, typeHash);
+  checkTarget(resolved, contract, chain);
+  checkDomain(resolved, typedData.domain);
+
+  const budget = { elements: 0, maxElements: limits.maxElements ?? DEFAULT_ABI_LIMITS.maxElements, maxBytes: limits.maxBytes ?? DEFAULT_ABI_LIMITS.maxBytes };
+  const values = readTyped(parsed.types, name, typedData.message, "message", budget);
+  let digest;
+  try {
+    digest = typedDataDigest({ domain: typedData.domain, types: { ...parsed.types, EIP712Domain: domainType }, primaryType: name, message: typedData.message });
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.DECODE, e.message);
+    throw e;
+  }
+  const viewed = { ...message, args: message.args.map((n, i) => abiView(n, `${name}(${i})`)) };
+  const model = modelOf(resolved, name, viewed, withTokens(name, viewed, [values], tokenTable(tokens)));
+  const grant = grantOf({ name, method: viewed, argValues: [values], called: contract, diagnostics: model.diagnostics });
+  const where = `${contract} on chain ${chain}`;
+  const done = (rest) => ({ ...rest, primaryType: name, typeHash, digest, verifyingContract: contract, chainId: chain, values, grant, diagnostics: model.diagnostics, provenance: model.provenance, model });
+  if (form === "fields") {
+    const plain = renderPlain(model, new Renderer({ refs, diagnostics: model.diagnostics }), { rawArguments });
+    plain.fields.push(["Contract", where], ["Signature", SIGNATURE_NOTE], ["EIP-712 digest", digest]);
+    return done({ form, message: plain });
+  }
+  const renderer = new Renderer({ refs, utcOffsetMinutes: utcOffsetMinutes ?? 0, diagnostics: model.diagnostics });
+  const text = `${renderGeneric(model, renderer, { rawArguments })}\n\n**Contract:** ${codeSpan(contract)} on chain ${chain}\n\n**EIP-712 digest:** ${codeSpan(digest)}\n\n${SIGNATURE_NOTE}.`;
+  return done({ form, message: text });
+}
+
+/** What a typed-data signature is, said with every message (spec section 15.9). */
+const SIGNATURE_NOTE = "This is a signature, not a transaction: whoever holds it can submit it";

package/src/grant.mjs

@@ -0,0 +1,140 @@
+// What a call or a signature grants (docs/profile-v0.md section 5.3, D-056): who may take tokens because of it, which
+// token, how many and until when, read from its effect's `grant` and its decoded values. A wallet compares it with the
+// terms the user confirmed (`@meantjs/consent/terms`).
+//
+// A grant that cannot be read is no grant: `null`, with a W_GRANT diagnostic. The request then needs its confirmation,
+// as any request without a grant does, and the consent text is the same either way.
+
+import { displayAccount, principalFromText, principalToText } from "@meantjs/format";
+import { CODES, fail } from "./errors.mjs";
+import { callTag, tagArgs } from "./resolved.mjs";
+import { resolvePath, valuesAt } from "./paths.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const NATURAL = /^(0|[1-9][0-9]*)$/;
+const INTEGER = /^-?(0|[1-9][0-9]*)$/;
+/** Nanoseconds per unit of a `timestamp` tag (spec section 5.3); every grant end is compared in nanoseconds, exactly. */
+const NS = { s: 1_000_000_000n, ms: 1_000_000n, us: 1_000n, ns: 1n };
+
+/** Nanoseconds as exact seconds: a decimal string with a fraction only when there is one, never rounded. */
+export function secondsText(ns) {
+  const sign = ns < 0n ? "-" : "";
+  const a = ns < 0n ? -ns : ns;
+  const frac = (a % NS.s).toString().padStart(9, "0").replace(/0+$/, "");
+  return `${sign}${a / NS.s}${frac ? `.${frac}` : ""}`;
+}
+
+/** The canonical text of a canister id; anything else is E_REQUEST. */
+export function canisterText(id) {
+  try {
+    return principalToText(principalFromText(id));
+  } catch {
+    fail(CODES.REQUEST, `canisterId must be a principal's text, got ${JSON.stringify(String(id))}`);
+  }
+}
+
+class Skip extends Error {}
+
+/**
+ * @param {object} input
+ * @param {string} input.name  the method or message, for the diagnostic
+ * @param {object} input.method  its resolved-form entry (an EVM one as abiView reads it)
+ * @param {unknown[]} input.argValues  its decoded arguments, before any amount is boxed with its token
+ * @param {string | undefined} input.called  the contract or canister the call is for: the token, unless the amount's
+ *   tag names a field that holds it (spec section 15.9)
+ * @param {object[]} input.diagnostics  where W_GRANT goes
+ * @returns {null | { kind: "transfer" | "approve", spender?: string, to?: string, token: string,
+ *   amount: { units: string | null, unlimited: boolean }, ends: { at: string } | { never: true } | { now: true } }}
+ */
+export function grantOf({ name, method, argValues, called, diagnostics }) {
+  const effect = callTag(method, argValues, "effect");
+  const grant = effect?.args?.grant;
+  if (grant === undefined) return null;
+  try {
+    return read(method, argValues, effect, grant, called);
+  } catch (e) {
+    if (!(e instanceof Skip)) throw e;
+    diagnostics.push({ code: "W_GRANT", at: name, message: `${e.message}; the request has no grant, so terms the user confirmed cannot cover it` });
+    return null;
+  }
+}
+
+function read(method, argValues, effect, grant, called) {
+  const skip = (why) => {
+    throw new Skip(why);
+  };
+  if (effect !== method.tags?.effect) skip("a grant on the effect of a case is not read in this version (D-056)");
+  const { kind } = effect.args;
+  if (kind !== "transfer" && kind !== "approve") skip(`a grant goes with effect kind transfer or approve, not ${String(kind)}`);
+  if (!isObject(grant) || (grant.spender === undefined) === (grant.to === undefined)) skip("the grant names neither or both of spender and to");
+
+  /** The one value at a grant position: no [] and no case of a variant on the way, so a call holds it once at most. */
+  const at = (what, path, mayBeAbsent = false) => {
+    if (typeof path !== "string") skip(`grant ${what} is not a path`);
+    const rp = resolvePath(method, path);
+    if (rp.error) skip(`grant ${what} ${JSON.stringify(path)}: ${rp.error}`);
+    if (rp.steps.some((s) => s.kind !== "field")) skip(`grant ${what} ${JSON.stringify(path)} steps into [] or a case of a variant`);
+    const values = valuesAt(rp, argValues);
+    if (values.length === 0 && !mayBeAbsent) skip(`grant ${what} ${JSON.stringify(path)} is absent from this call`);
+    return { node: rp.node, value: values[0] };
+  };
+
+  const who = grant.spender !== undefined ? "spender" : "to";
+  const party = at(who, grant[who]);
+  let address;
+  if (party.node.abi === "address" && typeof party.value === "string") address = party.value; // EIP-55, as decoded
+  else if (tagArgs(party.node, "account") !== undefined && isObject(party.value)) {
+    try {
+      address = displayAccount(party.value);
+    } catch (e) {
+      skip(`grant ${who}: ${e.message}`);
+    }
+  } else skip(`grant ${who} ${JSON.stringify(grant[who])} is neither an address nor an account`);
+
+  const amt = at("amount", grant.amount);
+  const tag = tagArgs(amt.node, "amount");
+  let amount;
+  if ((amt.node.abi ?? amt.node.candid) === "bool" && typeof amt.value === "boolean") {
+    amount = amt.value ? { units: null, unlimited: true } : { units: "0", unlimited: false }; // DAI's allowed (spec 15.9)
+  } else {
+    if (tag === undefined || typeof amt.value !== "string" || !NATURAL.test(amt.value)) skip(`grant amount ${JSON.stringify(grant.amount)} is neither an amount nor a bool`);
+    if (tag.threshold !== undefined && (typeof tag.threshold !== "string" || !NATURAL.test(tag.threshold))) skip("the amount tag's threshold is not a decimal string");
+    amount = { units: amt.value, unlimited: tag.threshold !== undefined && BigInt(amt.value) >= BigInt(tag.threshold) };
+  }
+
+  let token;
+  if (tag?.token !== undefined) {
+    const t = at("amount token", tag.token);
+    if (t.node.abi !== "address" || typeof t.value !== "string") skip(`the amount's token ${JSON.stringify(tag.token)} is not an address`);
+    token = t.value;
+  } else if (typeof called === "string") token = called;
+  else skip("the canister the call is for was not given (canisterId), so its token is not known");
+
+  let ends;
+  if (grant.ends === undefined) ends = kind === "approve" ? { never: true } : { now: true };
+  else {
+    if (!Array.isArray(grant.ends) || grant.ends.length === 0) skip("grant ends is not a list of paths");
+    let latest = null;
+    let never = false;
+    for (const path of grant.ends) {
+      const end = at("ends", path, true);
+      if (end.value === undefined) { // an optional end left out: the grant never ends (spec 5.3)
+        never = true;
+        continue;
+      }
+      const ts = tagArgs(end.node, "timestamp");
+      if (ts === undefined || !Object.hasOwn(NS, ts.unit) || (ts.epoch ?? "unix") !== "unix" || typeof end.value !== "string" || !INTEGER.test(end.value)) {
+        skip(`grant ends ${JSON.stringify(path)} is not a unix timestamp`);
+      }
+      if (ts.threshold !== undefined && (typeof ts.threshold !== "string" || !NATURAL.test(ts.threshold))) skip(`the timestamp tag of ${JSON.stringify(path)} has a threshold that is not a decimal string`);
+      if (ts.threshold !== undefined && BigInt(end.value) >= BigInt(ts.threshold)) { // at its threshold: never (spec 5.3)
+        never = true;
+        continue;
+      }
+      const ns = BigInt(end.value) * NS[ts.unit]; // a label is how a value is shown; here it is the time it is
+      if (latest === null || ns > latest) latest = ns;
+    }
+    ends = never ? { never: true } : { at: secondsText(latest) };
+  }
+  return { kind, [who]: address, token, amount, ends };
+}

package/src/index.d.mts

@@ -126,6 +126,24 @@ export interface Model {
   [key: string]: unknown;
 }
 
+/**
+ * What a call or a signature grants (spec section 5.3, D-056): who may take tokens because of it, which token, how many
+ * and until when, read from its effect's `grant`. Compare it with terms the user confirmed (`@meantjs/consent/terms`).
+ */
+export interface Grant {
+  kind: "transfer" | "approve";
+  /** Who may take the tokens: an EIP-55 address, or an account in its ICRC-1 text. Exactly one of `spender` and `to`. */
+  spender?: string;
+  /** Who is paid directly: an EIP-55 address, or an account in its ICRC-1 text. */
+  to?: string;
+  /** The token: an EIP-55 address, or a canister id in its canonical text. */
+  token: string;
+  /** Base units as a decimal string; `null` when unlimited without a count (DAI's `allowed: true`). A grant of nothing is `"0"`. */
+  amount: { units: string | null; unlimited: boolean };
+  /** `at`: exact seconds since the Unix epoch as a decimal string, never rounded ("1767225600.123456789"). `now`: a transfer, made when it is sent. */
+  ends: { at: string } | { never: true } | { now: true };
+}
+
 export interface GenerateConsentInput {
   resolved: ResolvedForm;
   method: string;
@@ -138,12 +156,21 @@ export interface GenerateConsentInput {
   utcOffsetMinutes?: number | null;
   rawArguments?: boolean;
   limits?: DecodeLimits;
+  /**
+   * The canister called, the token of a grant. Without it nothing asks what the call grants: `grant` is null, with no
+   * diagnostic. Any spelling of a principal; anything else is E_REQUEST.
+   */
+  canisterId?: string;
 }
 /** 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;
+  /** The decoded arguments, one value tree per argument, as `decodeArguments` gives them. */
+  values: unknown[];
+  /** What the call grants, or null: no `canisterId`, no grant in its effect, or one that cannot be read (a W_GRANT diagnostic says why). */
+  grant: Grant | null;
   diagnostics: ConsentDiagnostic[];
   provenance: Provenance;
   model: Model;
@@ -207,6 +234,8 @@ export const CODES: Readonly<{
   LANGUAGE: "E_LANGUAGE";
   REQUEST: "E_REQUEST";
   DEPLOYMENT: "E_DEPLOYMENT";
+  DOMAIN: "E_DOMAIN";
+  TYPE_HASH: "E_TYPE_HASH";
   UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE";
   RESOLVED_FORM: "E_RESOLVED_FORM";
   TEMPLATE: "E_TEMPLATE";

package/src/sha256.mjs

@@ -0,0 +1,60 @@
+// SHA-256 in plain JavaScript, synchronous, so that the id of confirmed terms (terms.mjs) needs no node:crypto and the
+// ./terms subpath bundles for a browser (WebCrypto is asynchronous). The same code as the resolver's src/sha256.mjs;
+// test/terms.test.mjs compares it with node:crypto.
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 of a byte array, as 32 bytes. */
+export function sha256(bytes) {
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const bitLength = bytes.length * 8;
+  const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLength / 2 ** 32), false);
+  view.setUint32(padded.length - 4, bitLength >>> 0, false);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + 4 * i, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[i] + w[i]) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) | 0;
+    }
+    h[0] += a; h[1] += b; h[2] += c; h[3] += d; h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
+  }
+  const out = new Uint8Array(32);
+  const ov = new DataView(out.buffer);
+  h.forEach((x, i) => ov.setUint32(4 * i, x, false));
+  return out;
+}
+
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes. */
+export function sha256Hex(text) {
+  return Array.from(sha256(new TextEncoder().encode(text)), (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/terms.d.mts

@@ -0,0 +1,103 @@
+// Types for @meantjs/consent/terms: terms the user confirms for one task, and the check of a request's grant against
+// them (spec section 5.3, "Confirmed terms", D-056). Hand-written; the source is src/terms.mjs. scripts/types.test.mjs
+// keeps the declared names equal to the runtime exports.
+import type { Grant } from "./index.mjs";
+
+/** A term the agent wrote that cannot be read, or a step out of order: `message` is written for the agent. */
+export declare class TermsError extends Error {
+  constructor(code: string, message: string);
+  readonly code: TermsCode;
+}
+export declare const TERMS_CODES: {
+  /** A field is missing or empty, or both spender and to are given. */
+  readonly MISSING: "E_TERMS_MISSING";
+  /** A token the wallet does not know. */
+  readonly TOKEN: "E_TERMS_TOKEN";
+  /** An app the wallet does not know, or an address or account that is not one. */
+  readonly PARTY: "E_TERMS_PARTY";
+  /** An amount that cannot be read, or has more decimals than its token: never rounded. */
+  readonly AMOUNT: "E_TERMS_AMOUNT";
+  /** An end that cannot be read, or a date before today. */
+  readonly END: "E_TERMS_END";
+  /** termsGate: a step out of order. */
+  readonly ORDER: "E_TERMS_ORDER";
+};
+export type TermsCode = (typeof TERMS_CODES)[keyof typeof TERMS_CODES];
+
+/** What the terms functions read from the wallet. Pure: the wallet's clock and zone come in here. */
+export interface Wallet {
+  /** The tokens it knows, by symbol: an EVM token's address or a ledger's canister id, and its decimals. */
+  tokens: Record<string, { address: string; decimals: number } | { canister: string; decimals: number }>;
+  /** The apps and people it knows by name: an address, or an account in its ICRC-1 text. */
+  apps?: Record<string, string>;
+  /** Nanoseconds since the Unix epoch. */
+  now: bigint;
+  /** The user's zone (default 0, UTC): a date allows its whole day there. */
+  utcOffsetMinutes?: number;
+}
+
+/** The terms as the agent writes them, a tool's arguments: `spender` or `to`, exactly one. */
+export interface TermsFields {
+  /** The token, by the symbol the wallet knows. */
+  token: string;
+  /** Who may spend the tokens: an app's name as the wallet knows it, or an address or account the user gave. */
+  spender?: string;
+  /** Who is paid directly: a name the wallet knows, or an address or account the user gave. */
+  to?: string;
+  /** The most, in tokens ("100", "0.5", "100 USDC"), or "unlimited". */
+  max_amount: string;
+  /** YYYY-MM-DD (the whole day counts), a length from today ("30 days", "2 weeks", "1 month", "1 year"), hours from now ("2 hours", an exact time), or "never". */
+  expires_by: string;
+}
+
+/** What the user allows for one task, in the wallet's own values: `spender` or `to`, exactly one. */
+export interface Terms {
+  /** The token: an EIP-55 address, or a canister id in its canonical text. */
+  token: string;
+  symbol: string;
+  decimals: number;
+  spender?: string;
+  to?: string;
+  /** The app's name in the wallet's list, or null. */
+  name: string | null;
+  /** The most, in base units as a decimal string; `null` when unlimited. */
+  amount: { units: string; unlimited: false } | { units: null; unlimited: true };
+  /** `at`: the latest end, exact seconds since the Unix epoch as a decimal string; `day`: the local date whose whole day counts. */
+  ends: { at: string; day?: string } | { never: true };
+  utcOffsetMinutes: number;
+  /** The fields as the agent wrote them, trimmed. */
+  written: Record<string, string>;
+}
+/** Terms the user confirmed: `id` is the SHA-256 of their canonical JSON (RFC 8785), lowercase hex. */
+export type ConfirmedTerms = Readonly<Terms & { id: string }>;
+
+/** Reads the agent's terms. Throws TermsError when a term cannot be read; it never guesses a token, an app, decimals or a date. */
+export function readTerms(fields: TermsFields | Record<string, unknown>, wallet: Wallet): Terms;
+/** The terms in words, exactly, for the user to confirm on the wallet's own screen. */
+export function termsText(terms: Terms | ConfirmedTerms): string;
+/** The terms once the user has confirmed exactly `termsText(terms)`: frozen, with their `id`. */
+export function confirmTerms(terms: Terms): ConfirmedTerms;
+/** Whether a request's grant fits confirmed terms, and if not, why, in words. A null grant is not covered by terms. */
+export function checkGrant(confirmed: ConfirmedTerms, grant: Grant | null, wallet: Wallet): { fits: boolean; reasons: string[] };
+
+/** The order of one task: propose, confirm on the wallet's screen, read, check. Steps out of order throw TermsError E_TERMS_ORDER. */
+export interface TermsGate {
+  readonly state: "open" | "proposed" | "confirmed" | "read";
+  readonly proposed: Readonly<Terms> | null;
+  readonly confirmed: ConfirmedTerms | null;
+  /** The agent's draft; replaces an earlier one and its confirmation. Returns the text to show the user. Refused once the request was read. */
+  propose(terms: Terms): string;
+  /** The user confirmed `shown`, which must be exactly the draft's text. */
+  confirm(shown: string): ConfirmedTerms;
+  /** The user said no: the draft is dropped. */
+  reject(): void;
+  /** Before the agent reads the request: refused until the user has confirmed terms. */
+  read(): void;
+  /**
+   * The grant of the request read. `requestId` names the request the wallet will sign or send: eip712Consent's `digest`,
+   * or for a call the wallet's own id of it. The terms cover one request, the first checked: another is refused, even
+   * one that grants the same.
+   */
+  check(grant: Grant | null, wallet: Wallet, requestId: string): { fits: boolean; reasons: string[] };
+}
+export function termsGate(): TermsGate;