@meantjs/consent 0.3.0 → 0.5.0

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;