@phala/pay 0.1.2 → 0.2.0

package/src/server/sweeps.ts

@@ -0,0 +1,197 @@
+import {
+  encodeFunctionData,
+  getAddress,
+  isHex,
+  keccak256,
+  stringToBytes,
+  type Address,
+  type Hex,
+} from "viem";
+
+const FLUSH_ABI = [
+  {
+    type: "function",
+    name: "flush",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "treasury", type: "address" },
+      { name: "salts", type: "bytes32[]" },
+      { name: "token", type: "address" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+/** A contract call as a wallet or the Safe Transaction Builder takes it. */
+export interface Call {
+  to: Address;
+  data: Hex;
+  /** Native value in wei, a decimal string: `"0"` for a flush. */
+  value: string;
+}
+
+/**
+ * `factory.flush(treasury, salts, token)`, encoded offline from the exported forwarders
+ * (`GET /v1/forwarders`): every listed forwarder's whole balance of `token` moves to `treasury`,
+ * the only address it can pay. Anyone may send it; the sender pays the gas.
+ */
+export function flushTransaction(
+  factory: string,
+  treasury: string,
+  salts: readonly Hex[],
+  token: string,
+): Call {
+  if (salts.length === 0) {
+    throw new TypeError("flush needs at least one salt");
+  }
+  if (!salts.every((salt) => isHex(salt) && salt.length === 66)) {
+    throw new TypeError("a salt is 32 bytes of hex");
+  }
+  return {
+    to: getAddress(factory),
+    data: encodeFunctionData({
+      abi: FLUSH_ABI,
+      functionName: "flush",
+      args: [getAddress(treasury), salts, getAddress(token)],
+    }),
+    value: "0",
+  };
+}
+
+/** A forwarder as `GET /v1/forwarders` returns it. */
+export interface ForwarderObject {
+  chain_id: number;
+  factory: string;
+  treasury: string;
+  salt: string;
+}
+
+/**
+ * Groups forwarders of one chain, such as `GET /v1/forwarders?sweepable=<token>` lists, into
+ * `flushTransaction` calls: one per factory and treasury, of at most `maxSalts` forwarders.
+ */
+export function flushTransactions(
+  forwarders: Iterable<ForwarderObject>,
+  token: string,
+  maxSalts = 200,
+): Call[] {
+  const groups = new Map<string, { factory: string; treasury: string; salts: Hex[] }>();
+  const chains = new Set<number>();
+  for (const forwarder of forwarders) {
+    chains.add(forwarder.chain_id);
+    const factory = getAddress(forwarder.factory);
+    const treasury = getAddress(forwarder.treasury);
+    const key = `${factory}:${treasury}`;
+    const group = groups.get(key) ?? { factory, treasury, salts: [] };
+    if (!isHex(forwarder.salt)) {
+      throw new TypeError("a salt is 32 bytes of hex");
+    }
+    group.salts.push(forwarder.salt);
+    groups.set(key, group);
+  }
+  if (chains.size > 1) {
+    throw new TypeError("a batch of flush calls is for one chain");
+  }
+  const calls: Call[] = [];
+  for (const { factory, treasury, salts } of groups.values()) {
+    for (let start = 0; start < salts.length; start += maxSalts) {
+      calls.push(flushTransaction(factory, treasury, salts.slice(start, start + maxSalts), token));
+    }
+  }
+  return calls;
+}
+
+/**
+ * The Safe Transaction Builder's batch file, its `BatchFile` type
+ * (safe-global/safe-react-apps, `apps/tx-builder/src/typings/models.ts` at commit
+ * e8cccfb9a1042fa2954087988bae59c3b8c81780).
+ */
+export interface BatchFile {
+  version: string;
+  chainId: string;
+  createdAt: number;
+  meta: BatchFileMeta;
+  transactions: BatchTransaction[];
+}
+
+export interface BatchFileMeta {
+  txBuilderVersion?: string;
+  checksum?: string;
+  createdFromSafeAddress?: string;
+  createdFromOwnerAddress?: string;
+  name: string;
+  description?: string;
+}
+
+export interface BatchTransaction {
+  to: string;
+  value: string;
+  data?: string;
+  contractMethod?: { inputs: unknown[]; name: string; payable: boolean };
+  contractInputsValues?: { [key: string]: string };
+}
+
+export interface SafeBatchOptions {
+  name?: string;
+  description?: string;
+  /** Milliseconds; now by default. */
+  createdAt?: number;
+}
+
+/**
+ * A Transaction Builder batch file of `calls` for the Safe `safe` on `chainId`, with the app's
+ * `meta.checksum`, so it imports without the "modified since it was generated" warning. A Safe
+ * owner imports it in Safe{Wallet} > Apps > Transaction Builder; the owners sign and execute it.
+ */
+export function safeBatch(
+  chainId: number,
+  safe: string,
+  calls: readonly Call[],
+  options: SafeBatchOptions = {},
+): BatchFile {
+  if (calls.length === 0) {
+    throw new TypeError("a batch needs at least one call");
+  }
+  const batch: BatchFile = {
+    version: "1.0",
+    chainId: String(chainId),
+    createdAt: options.createdAt ?? Date.now(),
+    meta: {
+      name: options.name ?? "Phala Pay sweep",
+      description: options.description ?? "",
+      createdFromSafeAddress: getAddress(safe),
+    },
+    transactions: calls.map((call) => {
+      if (!/^\d+$/.test(call.value) || !isHex(call.data)) {
+        throw new TypeError("a call needs hex data and a decimal value");
+      }
+      return { to: getAddress(call.to), value: call.value, data: call.data };
+    }),
+  };
+  batch.meta.checksum = batchChecksum(batch);
+  return batch;
+}
+
+/**
+ * The Transaction Builder's `meta.checksum` (`apps/tx-builder/src/lib/checksum.ts`): Keccak-256
+ * of its key-sorted serialization with `meta.name` set to `null`, over the file without its
+ * checksum, as the app's `validateChecksum` recomputes it.
+ */
+export function batchChecksum(batch: BatchFile): Hex {
+  const meta: Record<string, unknown> = { ...batch.meta, name: null };
+  delete meta["checksum"];
+  return keccak256(stringToBytes(serialize({ ...batch, meta })));
+}
+
+/** The app's `serializeJSONObject`. */
+function serialize(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(serialize).join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const record = value as Record<string, unknown>;
+    const keys = Object.keys(record).sort();
+    return `{${JSON.stringify(keys)}${keys.map((key) => `${serialize(record[key])},`).join("")}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}

package/src/server/webhook.ts

@@ -0,0 +1,202 @@
+/**
+ * Standard Webhooks `v1a` verification of Phala Pay deliveries (design D11): an ed25519 signature
+ * over `{webhook-id}.{webhook-timestamp}.{body}` by your account's webhook key in the endpoint's
+ * mode, pinned from `GET /v1/attestation`. Uses WebCrypto, so it runs on Node 20+, Deno, Bun, and
+ * edge runtimes.
+ */
+
+/** A delivery that did not verify: answer `400` and do nothing. */
+export class WebhookSignatureError extends Error {
+  override readonly name = "WebhookSignatureError";
+}
+
+/** A verified event. `data.object` is the object the event is about, such as a deposit. */
+export interface WebhookEvent {
+  /** `evt_…`, stable across retries and resends: process each id once. */
+  id: string;
+  object: "event";
+  /** Your account, `acct_…`. */
+  account: string;
+  livemode: boolean;
+  /** Such as `deposit.credited`; claw back a `deposit.reversed` deposit's credit. */
+  type: string;
+  created: number;
+  /** Who caused it: an API key id (`key_…`), `admin`, or `system`. */
+  actor?: string;
+  /**
+   * The API request that caused it, with the `Idempotency-Key` it sent; `null` when the
+   * service's own workers did (a payment credited, a quote expired).
+   */
+  request?: { id: string; idempotency_key: string | null } | null;
+  /**
+   * `object` is the object as it was when the event happened, never re-rendered; `*.updated`
+   * events add `previous_attributes`, the former values of what changed.
+   */
+  data: { object: Record<string, unknown>; previous_attributes?: Record<string, unknown> };
+}
+
+export interface ConstructEventOptions {
+  /** Your account id, `acct_…`: an event of another account fails closed. */
+  expectedAccount: string;
+  /** The mode of the endpoint receiving it: an event of the other mode fails closed. */
+  expectedLivemode: boolean;
+  /** Seconds a delivery's timestamp may differ from now; default 300. */
+  tolerance?: number;
+  /** Current time in Unix seconds; for tests. */
+  now?: number;
+}
+
+/**
+ * Verifies a delivery and returns its event, as Stripe's `constructEvent` does, failing closed
+ * unless a `v1a` signature verifies with one of `publicKeys` (hex or base64 raw ed25519 keys; pass
+ * both while a rotation overlaps), the timestamp is within tolerance, the body's id is the
+ * `webhook-id`, and the event is `expectedAccount`'s in `expectedLivemode`.
+ *
+ * `payload` is the raw request body, before any JSON parsing.
+ */
+export async function constructEvent(
+  payload: string | Uint8Array,
+  headers: Headers | Record<string, string | string[] | undefined>,
+  publicKeys: string | readonly string[],
+  options: ConstructEventOptions,
+): Promise<WebhookEvent> {
+  if (options.expectedAccount === "") {
+    throw new TypeError("expectedAccount is required");
+  }
+  const body = typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+  const id = header(headers, "webhook-id");
+  const timestamp = header(headers, "webhook-timestamp");
+  const signatures = header(headers, "webhook-signature");
+  if (id === undefined || timestamp === undefined || signatures === undefined) {
+    throw new WebhookSignatureError("webhook headers missing");
+  }
+  if (!/^\d+$/.test(timestamp)) {
+    throw new WebhookSignatureError("webhook timestamp malformed");
+  }
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  if (Math.abs(now - Number(timestamp)) > (options.tolerance ?? 300)) {
+    throw new WebhookSignatureError("webhook timestamp outside tolerance");
+  }
+  const signed = concat(new TextEncoder().encode(`${id}.${timestamp}.`), body);
+  const keys = await Promise.all(
+    (typeof publicKeys === "string" ? [publicKeys] : publicKeys).map(importKey),
+  );
+  if (keys.length === 0) {
+    throw new TypeError("no webhook public key pinned");
+  }
+  let verified = false;
+  for (const entry of signatures.split(" ")) {
+    const [version, encoded] = entry.split(",", 2);
+    const signature = version === "v1a" && encoded !== undefined ? base64(encoded) : undefined;
+    if (signature === undefined) {
+      continue;
+    }
+    for (const key of keys) {
+      if (await crypto.subtle.verify("Ed25519", key, signature, signed)) {
+        verified = true;
+      }
+    }
+  }
+  if (!verified) {
+    throw new WebhookSignatureError("no valid webhook signature");
+  }
+  let event: unknown;
+  try {
+    event = JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    throw new TypeError("webhook body is not an event");
+  }
+  if (typeof event !== "object" || event === null) {
+    throw new TypeError("webhook body is not an event");
+  }
+  const e = event as Record<string, unknown>;
+  const data = e["data"];
+  const object: unknown =
+    typeof data === "object" && data !== null ? (data as Record<string, unknown>)["object"] : null;
+  const { id: eventId, type, account, livemode, created, actor } = e;
+  if (
+    e["object"] !== "event" ||
+    typeof eventId !== "string" ||
+    typeof type !== "string" ||
+    typeof account !== "string" ||
+    typeof livemode !== "boolean" ||
+    typeof created !== "number" ||
+    !Number.isSafeInteger(created) ||
+    typeof object !== "object" ||
+    object === null ||
+    !(actor === undefined || typeof actor === "string")
+  ) {
+    throw new TypeError("webhook body is not an event");
+  }
+  if (eventId !== id) {
+    throw new WebhookSignatureError("webhook id does not match the event");
+  }
+  if (account !== options.expectedAccount) {
+    throw new WebhookSignatureError("webhook event is for another account");
+  }
+  if (livemode !== options.expectedLivemode) {
+    throw new WebhookSignatureError("webhook event is for the other mode");
+  }
+  const previous = (data as Record<string, unknown>)["previous_attributes"];
+  return {
+    id: eventId,
+    object: "event",
+    account,
+    livemode,
+    type,
+    created,
+    ...(actor === undefined ? {} : { actor }),
+    data: {
+      object: object as Record<string, unknown>,
+      ...(typeof previous === "object" && previous !== null
+        ? { previous_attributes: previous as Record<string, unknown> }
+        : {}),
+    },
+  };
+}
+
+function header(
+  headers: Headers | Record<string, string | string[] | undefined>,
+  name: string,
+): string | undefined {
+  if (headers instanceof Headers) {
+    return headers.get(name)?.trim() ?? undefined;
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) {
+      return (Array.isArray(value) ? value.join(" ") : value)?.trim();
+    }
+  }
+  return undefined;
+}
+
+async function importKey(encoded: string): Promise<CryptoKey> {
+  const value = encoded.trim().replace(/^0x/, "");
+  const raw = /^[0-9a-fA-F]{64}$/.test(value) ? hex(value) : base64(value);
+  if (raw?.length !== 32) {
+    throw new TypeError("a webhook public key is 32 bytes of hex or base64");
+  }
+  return crypto.subtle.importKey("raw", raw, "Ed25519", false, ["verify"]);
+}
+
+function hex(value: string): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(value.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function base64(value: string): Uint8Array<ArrayBuffer> | undefined {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) {
+    return undefined;
+  }
+  return Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+}
+
+function concat(left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer> {
+  const joined = new Uint8Array(left.length + right.length);
+  joined.set(left);
+  joined.set(right, left.length);
+  return joined;
+}

package/src/wallet.ts

@@ -1,7 +1,11 @@
+import { createStore } from "mipd";
 import {
+  BaseError,
   createWalletClient,
   custom,
   erc20Abi,
+  SwitchChainError,
+  UserRejectedRequestError,
   type Hash,
   type WalletClient,
 } from "viem";
@@ -31,57 +35,52 @@ export interface Wallet {
 /** The legacy `window.ethereum` provider, offered when no wallet announces itself (EIP-6963). */
 export const INJECTED_WALLET_UUID = "injected";
 
-interface AnnounceProviderEvent extends Event {
-  detail?: { info?: Partial<WalletInfo>; provider?: EthereumProvider };
-}
-
 /**
- * Discovers browser wallets with EIP-6963, falling back to `window.ethereum`, and calls `onChange`
- * with the current list whenever a wallet announces itself. Returns the function that stops
- * listening.
+ * Discovers browser wallets with EIP-6963 (through mipd's store), falling back to
+ * `window.ethereum`, and calls `onChange` with the current list whenever a wallet announces
+ * itself. Returns the function that stops listening.
  */
 export function watchWallets(onChange: (wallets: Wallet[]) => void): () => void {
   if (typeof window === "undefined") {
     onChange([]);
     return () => undefined;
   }
-  const announced = new Map<string, Wallet>();
-  const emit = () => {
-    const wallets = [...announced.values()];
-    const injected = (window as { ethereum?: EthereumProvider }).ethereum;
-    if (wallets.length === 0 && injected !== undefined) {
-      wallets.push({
-        info: { uuid: INJECTED_WALLET_UUID, name: "Browser wallet", icon: "", rdns: "" },
-        provider: injected,
-      });
-    }
-    onChange(wallets);
+  const store = createStore();
+  const unsubscribe = store.subscribe((details) => onChange(walletsFrom(details)), {
+    emitImmediately: true,
+  });
+  return () => {
+    unsubscribe();
+    store.destroy();
   };
-  const onAnnounce = (event: Event) => {
-    const detail = (event as AnnounceProviderEvent).detail;
-    const info = detail?.info;
-    if (
-      detail?.provider === undefined ||
-      typeof info?.uuid !== "string" ||
-      typeof info.name !== "string"
-    ) {
-      return;
+}
+
+type Announcement = { info?: Partial<WalletInfo>; provider?: unknown };
+
+/** Announcements are untrusted page events: keep well-formed ones, and only data-URI icons. */
+function walletsFrom(announcements: readonly Announcement[]): Wallet[] {
+  const wallets: Wallet[] = [];
+  for (const { info, provider } of announcements) {
+    if (!isProvider(provider) || typeof info?.uuid !== "string" || typeof info.name !== "string") {
+      continue;
     }
-    announced.set(info.uuid, {
-      info: {
-        uuid: info.uuid,
-        name: info.name,
-        icon: typeof info.icon === "string" && info.icon.startsWith("data:image/") ? info.icon : "",
-        rdns: typeof info.rdns === "string" ? info.rdns : "",
-      },
-      provider: detail.provider,
+    const icon = typeof info.icon === "string" && info.icon.startsWith("data:image/") ? info.icon : "";
+    const rdns = typeof info.rdns === "string" ? info.rdns : "";
+    wallets.push({ info: { uuid: info.uuid, name: info.name, icon, rdns }, provider });
+  }
+  // Wallets that predate EIP-6963, such as some in-app mobile browsers, only set `window.ethereum`.
+  const injected = (window as { ethereum?: EthereumProvider }).ethereum;
+  if (wallets.length === 0 && injected !== undefined) {
+    wallets.push({
+      info: { uuid: INJECTED_WALLET_UUID, name: "Browser wallet", icon: "", rdns: "" },
+      provider: injected,
     });
-    emit();
-  };
-  window.addEventListener("eip6963:announceProvider", onAnnounce);
-  window.dispatchEvent(new Event("eip6963:requestProvider"));
-  emit();
-  return () => window.removeEventListener("eip6963:announceProvider", onAnnounce);
+  }
+  return wallets;
+}
+
+function isProvider(value: unknown): value is EthereumProvider {
+  return typeof (value as Partial<EthereumProvider> | null | undefined)?.request === "function";
 }
 
 export type WalletErrorCode = "rejected" | "no_account" | "wrong_chain" | "failed";
@@ -99,20 +98,25 @@ export class WalletError extends Error {
 }
 
 /**
- * Pays a quote from a browser wallet: connects, switches to (or adds) the quote's chain, and sends
- * the ERC-20 `transfer` that the quote's `payment_uri` states. Resolves with the transaction hash
- * once the wallet has broadcast it; the checkout's status follows the payment from there.
+ * Pays a quote from a wallet: a viem `WalletClient` (for example wagmi's `useWalletClient()`), or an
+ * EIP-1193 provider such as a discovered `Wallet`'s. Connects (unless the client already has an
+ * account), switches to (or adds) the quote's chain, and sends the ERC-20 `transfer` that the quote's
+ * `payment_uri` states. Resolves with the transaction hash once the wallet has broadcast it; the
+ * checkout's status follows the payment from there.
  */
-export async function payWithWallet(provider: EthereumProvider, quote: ClientQuote): Promise<Hash> {
+export async function payWithWallet(
+  wallet: WalletClient | EthereumProvider,
+  quote: ClientQuote,
+): Promise<Hash> {
   const transfer = quoteTransfer(quote);
-  const wallet = createWalletClient({ transport: custom(provider) });
+  const client = isWalletClient(wallet) ? wallet : createWalletClient({ transport: custom(wallet) });
   try {
-    const [account] = await wallet.requestAddresses();
+    const account = client.account ?? (await client.requestAddresses())[0];
     if (account === undefined) {
       throw new WalletError("no_account", "The wallet shared no account");
     }
-    await ensureChain(wallet, transfer.chainId);
-    return await wallet.writeContract({
+    await ensureChain(client, transfer.chainId);
+    return await client.writeContract({
       account,
       chain: knownChain(transfer.chainId) ?? null,
       address: transfer.token,
@@ -124,13 +128,17 @@ export async function payWithWallet(provider: EthereumProvider, quote: ClientQuo
     if (error instanceof WalletError) {
       throw error;
     }
-    if (hasCode(error, 4001)) {
+    if (isRejection(error)) {
       throw new WalletError("rejected", "The request was rejected in the wallet", { cause: error });
     }
     throw new WalletError("failed", "The wallet could not send the payment", { cause: error });
   }
 }
 
+function isWalletClient(wallet: WalletClient | EthereumProvider): wallet is WalletClient {
+  return "writeContract" in wallet;
+}
+
 async function ensureChain(wallet: WalletClient, chainId: number): Promise<void> {
   if ((await wallet.getChainId()) === chainId) {
     return;
@@ -138,10 +146,9 @@ async function ensureChain(wallet: WalletClient, chainId: number): Promise<void>
   try {
     await wallet.switchChain({ id: chainId });
   } catch (error) {
-    // 4902: the wallet does not know the chain yet.
     const chain = knownChain(chainId);
-    if (!hasCode(error, 4902) || chain === undefined) {
-      throw hasCode(error, 4001)
+    if (!isUnknownChain(error) || chain === undefined) {
+      throw isRejection(error)
         ? error
         : new WalletError("wrong_chain", `Switch your wallet to ${networkName(chainId)}`, {
             cause: error,
@@ -157,19 +164,18 @@ async function ensureChain(wallet: WalletClient, chainId: number): Promise<void>
   }
 }
 
-/** Whether an error or any of its causes carries an EIP-1193 error code; some mobile wallets nest
- * the original error under `data.originalError`. */
-function hasCode(error: unknown, code: number): boolean {
-  for (let current = error; typeof current === "object" && current !== null; ) {
-    const value = current as { code?: unknown; cause?: unknown; data?: { originalError?: unknown } };
-    if (value.code === code) {
-      return true;
-    }
-    const nested = value.data?.originalError;
-    if (typeof nested === "object" && nested !== null && hasCode(nested, code)) {
-      return true;
-    }
-    current = value.cause;
-  }
-  return false;
+function isRejection(error: unknown): boolean {
+  return error instanceof BaseError && error.walk((e) => e instanceof UserRejectedRequestError) !== null;
+}
+
+/** Whether the wallet does not know the chain (4902). MetaMask Mobile nests that code in an internal
+ * error's `data.originalError`, which wagmi's injected connector also unwraps. */
+function isUnknownChain(error: unknown): boolean {
+  return (
+    error instanceof BaseError &&
+    error.walk((e) => {
+      const nested = (e as { data?: { originalError?: { code?: unknown } } } | null)?.data;
+      return e instanceof SwitchChainError || nested?.originalError?.code === SwitchChainError.code;
+    }) !== null
+  );
 }