@farmslot/adapter-web 0.1.0 → 0.3.0

package/src/dapp/signature-log.cjs

@@ -0,0 +1,314 @@
+'use strict';
+
+// Read, window and assert the wallet request log a wallet host writes: one
+// JSON line per request the app sent to the wallet (method, EIP-712 primary
+// type, domain/active chain, outcome) and, with a wallet extension, one line
+// per confirmation window it opened. Never holds params, messages or
+// signatures. A cursor file marks where the current window starts.
+//
+// `log` is `{ logFile, cursorFile }`. `policy` adds what the product forbids:
+// - `typedDataClasses`: `{ [counter]: { match(entry), param, defaultMax, failure(count, max) } }`,
+//   typed-data requests counted under `counter`, at most `node[param]`
+//   (default `defaultMax`) allowed;
+// - `forbiddenEntries`: `{ [counter]: { match(entry), failure(count) } }`, log
+//   entries that fail the assertion whenever one is present.
+
+const { mkdir, readFile, writeFile } = require('node:fs/promises');
+const path = require('node:path');
+
+/**
+ * @typedef {{ logFile: string, cursorFile: string }} SignatureLog
+ * @typedef {{ seq: number, kind?: string, [field: string]: any }} LogEntry
+ * @typedef {{ requested: number, signed: number, rejected: number, chainIds: Array<number | null | undefined> }} PrimaryTypeSummary
+ * @typedef {object} SignatureSummary
+ * @property {number} requests
+ * @property {number} typedDataRequests
+ * @property {number} confirmationsShown
+ * @property {number} unattributed
+ * @property {number} outsideAppFrame
+ * @property {Record<string, PrimaryTypeSummary>} byPrimaryType
+ * @property {Record<string, number>} byMethod
+ * @typedef {object} SignaturePolicy
+ * @property {Record<string, { match(entry: LogEntry): boolean, param: string, defaultMax: number, failure(count: number, max: number): string }>} [typedDataClasses]
+ * @property {Record<string, { match(entry: LogEntry): boolean, failure(count: number): string }>} [forbiddenEntries]
+ */
+
+/** @param {string} text @returns {LogEntry[]} */
+function parseLog(text) {
+  return text
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      try {
+        return { seq: index, ...JSON.parse(line) };
+      } catch {
+        return { seq: index, kind: 'unparseable' };
+      }
+    });
+}
+
+/** @param {SignatureLog} log @returns {Promise<LogEntry[]>} */
+async function readLog({ logFile }) {
+  try {
+    return parseLog(await readFile(logFile, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/** @param {SignatureLog} log @returns {Promise<number>} */
+async function readCursor({ cursorFile }) {
+  try {
+    const cursor = JSON.parse(await readFile(cursorFile, 'utf8'));
+    return Number.isInteger(cursor.seq) ? cursor.seq : 0;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+/** @param {SignatureLog} log @param {number} seq */
+async function writeCursor({ cursorFile }, seq) {
+  await writeFile(cursorFile, `${JSON.stringify({ seq, at: new Date().toISOString() })}\n`, {
+    mode: 0o600,
+  });
+}
+
+// "Token:Permit" → "Permit".
+/** @param {unknown} primaryType @returns {string | null} */
+function shortPrimaryType(primaryType) {
+  if (primaryType == null) return null;
+  const raw = String(primaryType);
+  return raw.includes(':') ? raw.slice(raw.lastIndexOf(':') + 1) : raw;
+}
+
+/** @param {LogEntry} entry */
+function isTypedDataRequest(entry) {
+  return entry.kind === 'request' && /^eth_signTypedData/u.test(String(entry.method));
+}
+
+/**
+ * @param {LogEntry[]} entries
+ * @param {SignaturePolicy} [policy]
+ * @returns {SignatureSummary & Record<string, any>} The policy's counters are extra top-level keys.
+ */
+function summarize(entries, policy = {}) {
+  assertPolicyCounters(policy);
+  const requests = entries.filter((entry) => entry.kind === 'request');
+  const typed = requests.filter(isTypedDataRequest);
+  /** @type {Record<string, PrimaryTypeSummary>} */
+  const byPrimaryType = {};
+  for (const entry of typed) {
+    const key = shortPrimaryType(entry.primaryType) ?? '<none>';
+    byPrimaryType[key] ??= { requested: 0, signed: 0, rejected: 0, chainIds: [] };
+    byPrimaryType[key].requested += 1;
+    if (entry.outcome === 'signed') byPrimaryType[key].signed += 1;
+    if (entry.outcome === 'rejected' || entry.outcome === 'error') byPrimaryType[key].rejected += 1;
+    if (!byPrimaryType[key].chainIds.includes(entry.domainChainId))
+      byPrimaryType[key].chainIds.push(entry.domainChainId);
+  }
+  /** @type {Record<string, number>} */
+  const byMethod = {};
+  for (const entry of requests) byMethod[entry.method] = (byMethod[entry.method] ?? 0) + 1;
+  const counted = (rules, list) =>
+    Object.fromEntries(
+      Object.entries(rules ?? {}).map(([counter, rule]) => [
+        counter,
+        list.filter(rule.match).length,
+      ]),
+    );
+  return {
+    requests: requests.length,
+    typedDataRequests: typed.length,
+    ...counted(policy.typedDataClasses, typed),
+    confirmationsShown: entries.filter((entry) => entry.kind === 'confirmation-shown').length,
+    // Forbidden entries and evidence gaps: each one fails the assertion.
+    ...counted(policy.forbiddenEntries, entries),
+    unattributed: entries.filter((entry) => entry.kind === 'unattributed').length,
+    // Calls from an iframe, a foreign page or a blank document: refused, kept as evidence.
+    outsideAppFrame: entries.filter((entry) => entry.kind === 'outside-app-frame').length,
+    byPrimaryType,
+    byMethod,
+  };
+}
+
+// The summary's own keys; a policy counter may not reuse one.
+const SUMMARY_KEYS = Object.freeze([
+  'requests',
+  'typedDataRequests',
+  'confirmationsShown',
+  'unattributed',
+  'outsideAppFrame',
+  'byPrimaryType',
+  'byMethod',
+]);
+
+/** @param {SignaturePolicy} policy */
+function assertPolicyCounters(policy) {
+  const names = [
+    ...Object.keys(policy.typedDataClasses ?? {}),
+    ...Object.keys(policy.forbiddenEntries ?? {}),
+  ];
+  const clash = names.find(
+    (name, index) => SUMMARY_KEYS.includes(name) || names.indexOf(name) !== index,
+  );
+  if (clash !== undefined) {
+    throw new Error(
+      `signature log policy counter "${clash}" is a summary key or used twice; name it something else.`,
+    );
+  }
+}
+
+function exact(label, actual, expected, failures) {
+  if (actual !== expected) failures.push(`${label}: expected ${expected}, got ${actual}`);
+}
+
+// Every expectation in `node` is optional.
+/**
+ * @param {LogEntry[]} entries
+ * @param {Record<string, any>} [node]
+ * @param {SignaturePolicy} [policy]
+ * @returns {{ ok: boolean, failures: string[], summary: SignatureSummary & Record<string, any> }}
+ */
+function evaluateSignatureLog(entries, node = {}, policy = {}) {
+  const summary = summarize(entries, policy);
+  const typed = entries.filter(isTypedDataRequest);
+  const failures = [];
+  for (const [counter, rule] of Object.entries(policy.forbiddenEntries ?? {})) {
+    if (summary[counter] > 0) failures.push(rule.failure(summary[counter]));
+  }
+  if (summary.unattributed > 0)
+    failures.push(
+      `${summary.unattributed} wallet log entr(y/ies) could not be attributed to the app's top frame (unattributed)`,
+    );
+  for (const [counter, rule] of Object.entries(policy.typedDataClasses ?? {})) {
+    const max = node[rule.param] == null ? rule.defaultMax : Number(node[rule.param]);
+    if (summary[counter] > max) failures.push(rule.failure(summary[counter], max));
+  }
+  if (Array.isArray(node.allowed_primary_types)) {
+    const allowed = new Set(node.allowed_primary_types.map(shortPrimaryType));
+    for (const entry of typed) {
+      const type = shortPrimaryType(entry.primaryType);
+      if (!allowed.has(type))
+        failures.push(`primary type ${type} (seq ${entry.seq}) is not allowed`);
+    }
+  }
+  if (node.counts && typeof node.counts === 'object') {
+    for (const [type, expected] of Object.entries(node.counts)) {
+      exact(
+        `signed ${shortPrimaryType(type)}`,
+        summary.byPrimaryType[shortPrimaryType(type)]?.signed ?? 0,
+        Number(expected),
+        failures,
+      );
+    }
+  }
+  if (node.request_counts && typeof node.request_counts === 'object') {
+    for (const [type, expected] of Object.entries(node.request_counts)) {
+      exact(
+        `requested ${shortPrimaryType(type)}`,
+        summary.byPrimaryType[shortPrimaryType(type)]?.requested ?? 0,
+        Number(expected),
+        failures,
+      );
+    }
+  }
+  if (node.methods && typeof node.methods === 'object') {
+    for (const [method, expected] of Object.entries(node.methods)) {
+      exact(`method ${method}`, summary.byMethod[method] ?? 0, Number(expected), failures);
+    }
+  }
+  if (
+    node.max_typed_data_requests != null &&
+    summary.typedDataRequests > Number(node.max_typed_data_requests)
+  ) {
+    failures.push(
+      `typed-data requests ${summary.typedDataRequests} > ${node.max_typed_data_requests}`,
+    );
+  }
+  if (node.expect_confirmations != null) {
+    exact(
+      'confirmations shown',
+      summary.confirmationsShown,
+      Number(node.expect_confirmations),
+      failures,
+    );
+  }
+  if (node.require_active_chain === true) {
+    for (const entry of typed.filter((item) => item.outcome === 'signed')) {
+      if (Number(entry.domainChainId) !== Number(entry.activeChainId)) {
+        failures.push(
+          `seq ${entry.seq} ${shortPrimaryType(entry.primaryType)} signed with domain chainId ${entry.domainChainId} while the wallet was on ${entry.activeChainId}`,
+        );
+      }
+    }
+  }
+  if (node.max_rejected != null) {
+    const rejected = typed.filter(
+      (entry) => entry.outcome === 'rejected' || entry.outcome === 'error',
+    ).length;
+    if (rejected > Number(node.max_rejected))
+      failures.push(`rejected typed-data requests ${rejected} > ${node.max_rejected}`);
+  }
+  return { ok: failures.length === 0, failures, summary };
+}
+
+/** @param {SignatureLog} log */
+async function windowSinceCursor(log) {
+  const [entries, cursor] = await Promise.all([readLog(log), readCursor(log)]);
+  return { cursor, entries: entries.filter((entry) => entry.seq >= cursor), total: entries.length };
+}
+
+// Move the window start to the end of the log, so the next read covers only
+// what follows.
+/** @param {SignatureLog} log */
+async function resetWindow(log) {
+  const entries = await readLog(log);
+  await writeCursor(log, entries.length);
+  return { cursor: entries.length, previousEntries: entries.length };
+}
+
+// Evaluate the current window; entries arrive asynchronously from the wallet
+// host, so a failing evaluation is retried until `node.timeout_ms` passes.
+/** @param {SignatureLog} log @param {Record<string, any>} [node] @param {SignaturePolicy} [policy] */
+async function awaitSignatureLog(log, node = {}, policy = {}) {
+  const deadline = Date.now() + Math.max(0, Number(node.timeout_ms ?? 0));
+  let window = await windowSinceCursor(log);
+  let result = evaluateSignatureLog(window.entries, node, policy);
+  while (!result.ok && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    window = await windowSinceCursor(log);
+    result = evaluateSignatureLog(window.entries, node, policy);
+  }
+  return { window, result };
+}
+
+// Retain a window as run evidence: <artifactsDir>/<folder>/<nodeId>-signature-log.json.
+/**
+ * @param {{ artifactsDir?: string, nodeId: string, folder: string }} target
+ * @param {unknown} payload
+ * @returns {Promise<Array<{ path: string, type: 'report', nodeId: string }>>}
+ */
+async function writeLogArtifact({ artifactsDir, nodeId, folder }, payload) {
+  if (!artifactsDir) return [];
+  const relative = `${folder}/${String(nodeId).replaceAll('/', '__')}-signature-log.json`;
+  await mkdir(path.join(artifactsDir, folder), { recursive: true });
+  await writeFile(path.join(artifactsDir, relative), `${JSON.stringify(payload, null, 2)}\n`);
+  return [{ path: relative, type: 'report', nodeId: String(nodeId) }];
+}
+
+module.exports = {
+  awaitSignatureLog,
+  evaluateSignatureLog,
+  isTypedDataRequest,
+  parseLog,
+  readCursor,
+  readLog,
+  resetWindow,
+  shortPrimaryType,
+  summarize,
+  windowSinceCursor,
+  writeCursor,
+  writeLogArtifact,
+};

package/src/dapp/strict-wallet.cjs

@@ -0,0 +1,169 @@
+'use strict';
+
+// EIP-1193 test wallet that enforces MetaMask's typed-data rule: reject
+// eth_signTypedData_v4 whose domain chainId differs from the active chain.
+// Signs with a viem-style account ({ address, signTypedData, signMessage })
+// the caller holds; never exposes key material.
+
+const DEFAULT_KNOWN_CHAINS = Object.freeze([
+  1, 10, 137, 8453, 42161, 421614, 59144, 59141, 11155111,
+]);
+
+const READ_RPC = {
+  1: 'https://ethereum-rpc.publicnode.com',
+  42161: 'https://arbitrum-one-rpc.publicnode.com',
+  421614: 'https://arbitrum-sepolia-rpc.publicnode.com',
+  59144: 'https://linea-rpc.publicnode.com',
+};
+
+// Only these reads go to the public RPC. Anything else the wallet does not
+// answer itself (eth_sendRawTransaction, account or filter methods, unknown
+// wallet_* calls) is refused before any network request.
+const READ_ONLY_RPC_METHODS = Object.freeze([
+  'eth_blockNumber',
+  'eth_call',
+  'eth_estimateGas',
+  'eth_feeHistory',
+  'eth_gasPrice',
+  'eth_getBalance',
+  'eth_getBlockByHash',
+  'eth_getBlockByNumber',
+  'eth_getCode',
+  'eth_getLogs',
+  'eth_getStorageAt',
+  'eth_getTransactionByHash',
+  'eth_getTransactionCount',
+  'eth_getTransactionReceipt',
+  'eth_maxPriorityFeePerGas',
+  'web3_clientVersion',
+]);
+const READ_ONLY = new Set(READ_ONLY_RPC_METHODS);
+
+function rpcError(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+function toBigIntDeep(types, primaryType, message) {
+  const out = {};
+  for (const field of types[primaryType] ?? []) {
+    const value = message[field.name];
+    if (value === undefined) continue;
+    if (/^u?int\d*$/u.test(field.type)) out[field.name] = BigInt(value);
+    else if (types[field.type]) out[field.name] = toBigIntDeep(types, field.type, value);
+    else out[field.name] = value;
+  }
+  return out;
+}
+
+/**
+ * @param {object} options
+ * @param {{ address: string, signTypedData(args: any): Promise<string>, signMessage(args: any): Promise<string> }} options.account
+ * @param {number} [options.chainId]
+ * @param {readonly number[]} [options.knownChains]
+ * @param {boolean} [options.refuseSwitch]
+ * @param {typeof fetch} [options.fetchImpl]
+ */
+function createStrictWallet({
+  account,
+  chainId = 42161,
+  knownChains = DEFAULT_KNOWN_CHAINS,
+  refuseSwitch = false,
+  fetchImpl = globalThis.fetch,
+}) {
+  let activeChain = chainId;
+  const known = new Set(knownChains);
+  let rpcId = 1;
+
+  /** @param {{ method: string, params?: any[] }} args @returns {Promise<any>} */
+  async function request({ method, params = [] }) {
+    switch (method) {
+      case 'eth_chainId':
+        return `0x${activeChain.toString(16)}`;
+      case 'net_version':
+        return String(activeChain);
+      case 'eth_accounts':
+      case 'eth_requestAccounts':
+        return [account.address];
+      case 'wallet_requestPermissions':
+      case 'wallet_getPermissions':
+        return [
+          {
+            parentCapability: 'eth_accounts',
+            caveats: [{ type: 'restrictReturnedAccounts', value: [account.address.toLowerCase()] }],
+          },
+        ];
+      case 'wallet_revokePermissions':
+        return null;
+      case 'metamask_getProviderState':
+        return {
+          accounts: [account.address.toLowerCase()],
+          chainId: `0x${activeChain.toString(16)}`,
+          isUnlocked: true,
+          networkVersion: String(activeChain),
+        };
+      case 'wallet_switchEthereumChain': {
+        const id = Number.parseInt(params[0].chainId, 16);
+        if (refuseSwitch) throw rpcError('User rejected the request.', 4001);
+        if (!known.has(id)) throw rpcError(`Unrecognized chain ID ${params[0].chainId}`, 4902);
+        activeChain = id;
+        return null;
+      }
+      case 'wallet_addEthereumChain':
+        known.add(Number.parseInt(params[0].chainId, 16));
+        return null;
+      case 'eth_signTypedData_v4': {
+        const [from, raw] = params;
+        const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        const domainChain = Number(BigInt(data.domain.chainId));
+        if (String(from).toLowerCase() !== account.address.toLowerCase())
+          throw rpcError('Unknown account', 4100);
+        if (domainChain !== activeChain) {
+          throw rpcError(
+            `Provided chainId "${domainChain}" must match the active chainId "${activeChain}"`,
+            -32602,
+          );
+        }
+        const types = { ...data.types };
+        delete types.EIP712Domain;
+        return account.signTypedData({
+          domain: { ...data.domain, chainId: domainChain },
+          types,
+          primaryType: data.primaryType,
+          message: toBigIntDeep(types, data.primaryType, data.message),
+        });
+      }
+      case 'personal_sign': {
+        const [message, from] = params;
+        if (String(from).toLowerCase() !== account.address.toLowerCase())
+          throw rpcError('Unknown account', 4100);
+        return account.signMessage({ message: { raw: message } });
+      }
+      case 'eth_sendTransaction':
+      case 'eth_sign':
+        throw rpcError(`${method} is not supported by the strict test wallet`, 4200);
+      default: {
+        if (!READ_ONLY.has(method))
+          throw rpcError(`${method} is not supported by the strict test wallet`, 4200);
+        const url = READ_RPC[activeChain];
+        if (!url) throw rpcError(`No read RPC for chain ${activeChain}`, 4200);
+        const response = await fetchImpl(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ jsonrpc: '2.0', id: rpcId++, method, params }),
+        });
+        const body = await response.json();
+        if (body.error) throw rpcError(body.error.message, body.error.code);
+        return body.result;
+      }
+    }
+  }
+
+  return {
+    request,
+    get chainId() {
+      return activeChain;
+    },
+  };
+}
+
+module.exports = { DEFAULT_KNOWN_CHAINS, READ_ONLY_RPC_METHODS, createStrictWallet };