@multiplatform.one/web3 7.18.0 → 7.20.0

package/src/clients/evm.spec.ts

@@ -0,0 +1,265 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  createPublicClient,
+  custom,
+  decodeFunctionData,
+  encodeAbiParameters,
+  erc20Abi,
+  toHex,
+  type Address,
+  type Hex,
+} from "viem";
+import { mainnet } from "viem/chains";
+import { evmClient } from "./evm";
+
+const account = "0x1111111111111111111111111111111111111111" as Address;
+const token = "0x2222222222222222222222222222222222222222" as Address;
+const spender = "0x3333333333333333333333333333333333333333" as Address;
+const txHash = `0x${"ab".repeat(32)}` as Hex;
+const hashFor = (n: number) => `0x${n.toString(16).padStart(64, "0")}` as Hex;
+
+interface Call {
+  method: string;
+  params?: unknown;
+}
+
+interface ChainState {
+  allowance: bigint;
+  balance: bigint;
+  /** USDT: transfer/approve return no data, and approve reverts non-zero to non-zero. */
+  usdt?: boolean;
+  /** Hashes whose receipt comes back reverted. */
+  reverted?: Set<Hex>;
+}
+
+const revert = () => Object.assign(new Error("execution reverted"), { code: 3, data: "0x" as Hex });
+
+function mockProvider(state: ChainState) {
+  const calls: Call[] = [];
+  const sent: Hex[] = [];
+  const provider = {
+    async request({ method, params }: Call) {
+      calls.push({ method, params });
+      switch (method) {
+        case "eth_chainId":
+          return toHex(mainnet.id);
+        case "personal_sign":
+          return "0xsigned";
+        case "eth_sendTransaction": {
+          const [{ data }] = params as [{ data?: Hex }];
+          const hash = sent.length === 0 ? txHash : hashFor(sent.length + 1);
+          sent.push(hash);
+          if (data) {
+            const { functionName, args } = decodeFunctionData({ abi: erc20Abi, data });
+            if (functionName === "approve" && !state.reverted?.has(hash)) {
+              state.allowance = (args as [Address, bigint])[1];
+            }
+          }
+          return hash;
+        }
+        case "eth_getTransactionReceipt": {
+          const [hash] = params as [Hex];
+          if (!sent.includes(hash)) return null;
+          return {
+            transactionHash: hash,
+            transactionIndex: "0x0",
+            blockHash: `0x${"cd".repeat(32)}`,
+            blockNumber: "0x10",
+            from: account,
+            to: token,
+            cumulativeGasUsed: "0x5208",
+            gasUsed: "0x5208",
+            effectiveGasPrice: "0x1",
+            contractAddress: null,
+            logs: [],
+            logsBloom: `0x${"00".repeat(256)}`,
+            status: state.reverted?.has(hash) ? "0x0" : "0x1",
+            type: "0x2",
+          };
+        }
+        case "eth_estimateGas":
+          return "0x5208";
+        case "eth_blockNumber":
+          return "0x10";
+        case "eth_call": {
+          const [{ data }] = params as [{ data: Hex }];
+          const { functionName, args } = decodeFunctionData({ abi: erc20Abi, data });
+          if (functionName === "allowance")
+            return encodeAbiParameters([{ type: "uint256" }], [state.allowance]);
+          if (functionName === "balanceOf")
+            return encodeAbiParameters([{ type: "uint256" }], [state.balance]);
+          if (functionName === "decimals") return encodeAbiParameters([{ type: "uint8" }], [18]);
+          if (!state.usdt) return encodeAbiParameters([{ type: "bool" }], [true]);
+          if (
+            functionName === "approve" &&
+            state.allowance > 0n &&
+            (args as [Address, bigint])[1] > 0n
+          ) {
+            throw revert();
+          }
+          return "0x";
+        }
+        default:
+          throw new Error(`unmocked ${method}`);
+      }
+    },
+  };
+  const sentTransaction = <T>() => {
+    const call = calls.find((c) => c.method === "eth_sendTransaction");
+    if (!call) throw new Error("no eth_sendTransaction");
+    return (call.params as [T])[0];
+  };
+  /** Each ERC-20 approve amount sent, in order. */
+  const approvals = () =>
+    calls
+      .filter((c) => c.method === "eth_sendTransaction")
+      .map((c) =>
+        decodeFunctionData({ abi: erc20Abi, data: (c.params as [{ data: Hex }])[0].data }),
+      )
+      .filter((d) => d.functionName === "approve")
+      .map((d) => (d.args as [Address, bigint])[1]);
+  return { provider, calls, sent, sentTransaction, approvals };
+}
+
+describe("evmClient", () => {
+  let state: ChainState;
+  let mock: ReturnType<typeof mockProvider>;
+  let client: ReturnType<typeof evmClient>;
+
+  beforeEach(() => {
+    state = { allowance: 0n, balance: 5n * 10n ** 18n };
+    mock = mockProvider(state);
+    client = evmClient({
+      provider: mock.provider as never,
+      account,
+      chain: mainnet,
+      publicClient: createPublicClient({
+        chain: mainnet,
+        pollingInterval: 1,
+        transport: custom(mock.provider),
+      }),
+    });
+  });
+
+  it("shares the common client shape", () => {
+    expect(client.family).toBe("evm");
+    expect(client.address).toBe(account);
+    expect(client.chainId).toBe(1);
+    expect(client.capabilities).toEqual(["signMessage", "sendTransaction", "writeContract"]);
+  });
+
+  it("signs with personal_sign on the connected account", async () => {
+    await expect(client.signMessage("hello")).resolves.toBe("0xsigned");
+    const call = mock.calls.find((c) => c.method === "personal_sign");
+    expect(call?.params).toEqual([toHex("hello"), account]);
+  });
+
+  it("sends a transaction from the connected account", async () => {
+    await expect(client.sendTransaction({ to: spender, value: 1n })).resolves.toBe(txHash);
+    const tx = mock.sentTransaction<{ from: Address; to: Address; value: Hex }>();
+    expect(tx.from.toLowerCase()).toBe(account.toLowerCase());
+    expect(tx.to).toBe(spender);
+    expect(tx.value).toBe("0x1");
+  });
+
+  it("writes a contract call", async () => {
+    await client.writeContract({
+      address: token,
+      abi: erc20Abi,
+      functionName: "transfer",
+      args: [spender, 7n],
+    });
+    const tx = mock.sentTransaction<{ to: Address; data: Hex }>();
+    expect(tx.to).toBe(token);
+    expect(decodeFunctionData({ abi: erc20Abi, data: tx.data })).toEqual({
+      functionName: "transfer",
+      args: [spender, 7n],
+    });
+  });
+
+  it("simulates an ERC-20 transfer before sending it", async () => {
+    await expect(client.erc20.transfer({ token, to: spender, amount: 3n })).resolves.toBe(txHash);
+    const methods = mock.calls.map((c) => c.method);
+    expect(methods.indexOf("eth_call")).toBeLessThan(methods.indexOf("eth_sendTransaction"));
+    const tx = mock.sentTransaction<{ data: Hex }>();
+    expect(decodeFunctionData({ abi: erc20Abi, data: tx.data })).toEqual({
+      functionName: "transfer",
+      args: [spender, 3n],
+    });
+  });
+
+  it("approves a spender", async () => {
+    await client.erc20.approve({ token, spender, amount: 9n });
+    const tx = mock.sentTransaction<{ data: Hex }>();
+    expect(decodeFunctionData({ abi: erc20Abi, data: tx.data })).toEqual({
+      functionName: "approve",
+      args: [spender, 9n],
+    });
+  });
+
+  it("reads balance, allowance and decimals", async () => {
+    state.allowance = 4n;
+    await expect(client.erc20.balanceOf(token)).resolves.toBe(5n * 10n ** 18n);
+    await expect(client.erc20.allowance(token, spender)).resolves.toBe(4n);
+    await expect(client.erc20.decimals(token)).resolves.toBe(18);
+  });
+
+  it("skips the approval when the allowance already covers the amount", async () => {
+    state.allowance = 100n;
+    await expect(client.erc20.ensureAllowance({ token, spender, amount: 50n })).resolves.toBeNull();
+    expect(mock.calls.some((c) => c.method === "eth_sendTransaction")).toBe(false);
+  });
+
+  it("sends transfer and approve to a token that returns nothing, as USDT does", async () => {
+    state.usdt = true;
+    await expect(client.erc20.transfer({ token, to: spender, amount: 3n })).resolves.toBe(txHash);
+    await expect(client.erc20.approve({ token, spender, amount: 9n })).resolves.toBe(hashFor(2));
+  });
+
+  it("approves from a zero allowance and waits for the approval to be mined", async () => {
+    await expect(client.erc20.ensureAllowance({ token, spender, amount: 50n })).resolves.toBe(
+      txHash,
+    );
+    expect(mock.approvals()).toEqual([50n]);
+    const methods = mock.calls.map((c) => c.method);
+    expect(methods.indexOf("eth_getTransactionReceipt")).toBeGreaterThan(
+      methods.indexOf("eth_sendTransaction"),
+    );
+  });
+
+  it("resets a non-zero allowance to 0 before raising it, which USDT requires", async () => {
+    state.usdt = true;
+    state.allowance = 5n;
+    await expect(client.erc20.ensureAllowance({ token, spender, amount: 50n })).resolves.toBe(
+      hashFor(2),
+    );
+    expect(mock.approvals()).toEqual([0n, 50n]);
+    expect(state.allowance).toBe(50n);
+    const receipts = mock.calls.filter((c) => c.method === "eth_getTransactionReceipt");
+    expect(receipts.map((c) => (c.params as [Hex])[0])).toContain(txHash);
+  });
+
+  it("throws when the approval reverts", async () => {
+    state.reverted = new Set([txHash]);
+    await expect(client.erc20.ensureAllowance({ token, spender, amount: 50n })).rejects.toThrow(
+      `approve ${txHash} reverted`,
+    );
+    expect(state.allowance).toBe(0n);
+  });
+
+  it("stops at a reverted reset and never sends the second approval", async () => {
+    state.usdt = true;
+    state.allowance = 5n;
+    state.reverted = new Set([txHash]);
+    await expect(client.erc20.ensureAllowance({ token, spender, amount: 50n })).rejects.toThrow(
+      /reverted/,
+    );
+    expect(mock.approvals()).toEqual([0n]);
+  });
+
+  it("wraps an existing viem wallet client", () => {
+    const wrapped = evmClient({ walletClient: client.walletClient });
+    expect(wrapped.address).toBe(account);
+    expect(wrapped.chain.id).toBe(1);
+  });
+});

package/src/clients/evm.ts

@@ -0,0 +1,223 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  custom,
+  erc20Abi,
+  http,
+  type Abi,
+  type Account,
+  type Address,
+  type Chain,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type EIP1193Provider,
+  type Hash,
+  type Hex,
+  type PublicClient,
+  type SendTransactionParameters,
+  type TransactionReceipt,
+  type Transport,
+  type WalletClient,
+  type WriteContractParameters,
+} from "viem";
+import type { ChainClient, ClientCapability } from "./types";
+
+/** A viem wallet client with its account and chain hoisted, the shape wagmi's getWalletClient returns. */
+export type EvmWalletClient = WalletClient<Transport, Chain, Account>;
+
+type WritableFunctionName<abi extends Abi | readonly unknown[]> = ContractFunctionName<
+  abi,
+  "nonpayable" | "payable"
+>;
+
+export type EvmWriteContractParameters<
+  abi extends Abi | readonly unknown[] = Abi,
+  functionName extends WritableFunctionName<abi> = WritableFunctionName<abi>,
+  args extends ContractFunctionArgs<abi, "nonpayable" | "payable", functionName> =
+    ContractFunctionArgs<abi, "nonpayable" | "payable", functionName>,
+> = WriteContractParameters<abi, functionName, args, Chain, Account>;
+
+export type EvmSendTransactionParameters = SendTransactionParameters<Chain, Account>;
+
+export interface Erc20Actions {
+  balanceOf(token: Address, owner?: Address): Promise<bigint>;
+  allowance(token: Address, spender: Address, owner?: Address): Promise<bigint>;
+  decimals(token: Address): Promise<number>;
+  /** Simulates, then sends `transfer(to, amount)`. `amount` is in the token's base units. */
+  transfer(args: { token: Address; to: Address; amount: bigint }): Promise<Hash>;
+  /** Simulates, then sends `approve(spender, amount)`. */
+  approve(args: { token: Address; spender: Address; amount: bigint }): Promise<Hash>;
+  /**
+   * Approves `amount` only when the allowance is below it, and waits for that
+   * approval to be mined so a purchase call right after it sees the allowance.
+   * A non-zero allowance is reset to 0 first, since USDT refuses to move one
+   * non-zero allowance to another. Returns the final approval hash, or null
+   * when the allowance already covered it. Throws if an approval reverts.
+   */
+  ensureAllowance(args: { token: Address; spender: Address; amount: bigint }): Promise<Hash | null>;
+}
+
+export interface EvmClient extends ChainClient<"evm"> {
+  readonly address: Address;
+  readonly chainId: number;
+  readonly chain: Chain;
+  /** The wallet side: anything viem's wallet actions can do. */
+  readonly walletClient: EvmWalletClient;
+  /** Reads, simulation and receipts. */
+  readonly publicClient: PublicClient;
+  /** personal_sign; returns the 0x signature. */
+  signMessage(message: string): Promise<Hex>;
+  sendTransaction(parameters: EvmSendTransactionParameters): Promise<Hash>;
+  writeContract<
+    const abi extends Abi | readonly unknown[],
+    functionName extends WritableFunctionName<abi>,
+    args extends ContractFunctionArgs<abi, "nonpayable" | "payable", functionName>,
+  >(
+    parameters: EvmWriteContractParameters<abi, functionName, args>,
+  ): Promise<Hash>;
+  waitForTransactionReceipt(hash: Hash): Promise<TransactionReceipt>;
+  readonly erc20: Erc20Actions;
+}
+
+export type EvmClientConfig = (
+  | {
+      /** A viem wallet client, e.g. wagmi's `getWalletClient(config)`. */
+      walletClient: EvmWalletClient;
+    }
+  | {
+      /** An EIP-1193 provider: injected, MetaMask Connect, or the native WebView bridge. */
+      provider: EIP1193Provider;
+      account: Address;
+      chain: Chain;
+    }
+) & {
+  /** Reads go here. Defaults to an http client on `rpcUrl`, else the chain's default RPC. */
+  publicClient?: PublicClient;
+  rpcUrl?: string;
+};
+
+/**
+ * transfer and approve with no outputs. USDT and other pre-standard tokens
+ * return nothing, and simulating them against erc20Abi's `returns (bool)`
+ * fails to decode the empty result, so the helpers simulate against this.
+ */
+const erc20WriteAbi = [
+  {
+    type: "function",
+    name: "transfer",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "approve",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+const capabilities: readonly ClientCapability[] = [
+  "signMessage",
+  "sendTransaction",
+  "writeContract",
+];
+
+/** Bind a viem WalletClient and PublicClient into the mpo EVM client. */
+export function evmClient(config: EvmClientConfig): EvmClient {
+  const walletClient: EvmWalletClient =
+    "walletClient" in config
+      ? config.walletClient
+      : createWalletClient({
+          account: config.account,
+          chain: config.chain,
+          transport: custom(config.provider),
+        });
+  const chain = walletClient.chain;
+  if (!chain) throw new Error("evmClient: the wallet client has no chain");
+  const publicClient =
+    config.publicClient ??
+    (createPublicClient({ chain, transport: http(config.rpcUrl) }) as PublicClient);
+  const account = walletClient.account;
+
+  const writeContract = (parameters: EvmWriteContractParameters) =>
+    walletClient.writeContract({ account, chain, ...parameters } as EvmWriteContractParameters);
+
+  const simulateAndWrite = async (parameters: {
+    address: Address;
+    functionName: "transfer" | "approve";
+    args: readonly [Address, bigint];
+  }): Promise<Hash> => {
+    const { request } = await publicClient.simulateContract({
+      account,
+      address: parameters.address,
+      abi: erc20WriteAbi,
+      functionName: parameters.functionName,
+      args: parameters.args,
+    });
+    return walletClient.writeContract({ ...request, account, chain } as EvmWriteContractParameters);
+  };
+
+  const approveAndWait = async (token: Address, spender: Address, amount: bigint) => {
+    const hash = await erc20.approve({ token, spender, amount });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") throw new Error(`approve ${hash} reverted`);
+    return hash;
+  };
+
+  const erc20: Erc20Actions = {
+    balanceOf: (token, owner = account.address) =>
+      publicClient.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "balanceOf",
+        args: [owner],
+      }),
+    allowance: (token, spender, owner = account.address) =>
+      publicClient.readContract({
+        address: token,
+        abi: erc20Abi,
+        functionName: "allowance",
+        args: [owner, spender],
+      }),
+    decimals: (token) =>
+      publicClient.readContract({ address: token, abi: erc20Abi, functionName: "decimals" }),
+    transfer: ({ token, to, amount }) =>
+      simulateAndWrite({ address: token, functionName: "transfer", args: [to, amount] }),
+    approve: ({ token, spender, amount }) =>
+      simulateAndWrite({ address: token, functionName: "approve", args: [spender, amount] }),
+    async ensureAllowance({ token, spender, amount }) {
+      const current = await erc20.allowance(token, spender);
+      if (current >= amount) return null;
+      if (current > 0n) await approveAndWait(token, spender, 0n);
+      return approveAndWait(token, spender, amount);
+    },
+  };
+
+  return {
+    family: "evm",
+    address: account.address,
+    chainId: chain.id,
+    chain,
+    capabilities,
+    walletClient,
+    publicClient,
+    signMessage: (message) => walletClient.signMessage({ account, message }),
+    sendTransaction: (parameters) =>
+      walletClient.sendTransaction({
+        account,
+        chain,
+        ...parameters,
+      } as EvmSendTransactionParameters),
+    writeContract: writeContract as EvmClient["writeContract"],
+    waitForTransactionReceipt: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+    erc20,
+  };
+}

package/src/clients/gpg.spec.ts

@@ -0,0 +1,169 @@
+// @vitest-environment happy-dom
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { gpgSignatureCovers } from "@multiplatform.one/gpg/signer";
+import {
+  assertGpgSignature,
+  createGpgSigner,
+  gpgSignCommand,
+  useGpgSigner,
+  type GpgSignRequest,
+} from "./gpg";
+
+// Real `gpg --detach-sign --armor` output from a throwaway key (GnuPG 2.2.40):
+// ed25519 over "sign me" with SHA-256 and SHA-512, ed25519 --textmode over
+// "line one\nline two", RSA-2048 over "sign me".
+const signature = [
+  "-----BEGIN PGP SIGNATURE-----",
+  "",
+  "iHUEABYIAB0WIQSTkGTQEc3oIZuZ2HdhXGslcfiVLQUCarhXCwAKCRBhXGslcfiV",
+  "LQ0LAQCXGCKwc0BQsbKZLC3dGO8G+JcugVvc8pXoLwVEhzHg5gEA9ymdo09WgZpg",
+  "ucbH3UOfZUAeoo8/udpgkA8x6FJQPQQ=",
+  "=ORhi",
+  "-----END PGP SIGNATURE-----",
+].join("\n");
+const signatureSha512 = [
+  "-----BEGIN PGP SIGNATURE-----",
+  "",
+  "iHUEABYKAB0WIQSTkGTQEc3oIZuZ2HdhXGslcfiVLQUCarhXCwAKCRBhXGslcfiV",
+  "LRKTAQD9KN/ePxTrwxYDVP1Vtv+xWw/ADZTMOBIfM5mG662+UwEAjqKNIAR77Qtd",
+  "Yz5lxQdmvudeeATH/0mGrq7h+JHSxwA=",
+  "=lq5g",
+  "-----END PGP SIGNATURE-----",
+].join("\n");
+const textSignature = [
+  "-----BEGIN PGP SIGNATURE-----",
+  "",
+  "iHUEARYIAB0WIQSTkGTQEc3oIZuZ2HdhXGslcfiVLQUCarhXCwAKCRBhXGslcfiV",
+  "LV9cAPwML2fE5cLHDhKjgnHpGjyBJqluiVRkkKwdA8UT64knWgEA9yLAavBGXwOR",
+  "VJ6lQNJ4dEUzc4PcrhSY/XoXchB2/wI=",
+  "=3t6i",
+  "-----END PGP SIGNATURE-----",
+].join("\n");
+const rsaSignature = [
+  "-----BEGIN PGP SIGNATURE-----",
+  "",
+  "iQFIBAABCgAyFiEE5BSx1a7VdcvuJBKxk/hBDWJyGKcFAmq4VwsUHHJzYUBleGFt",
+  "cGxlLmludmFsaWQACgkQk/hBDWJyGKfxuAf/RpMSEstfkVr+LSVbqdqvUwb+eFvS",
+  "g257dJ/p75cyySijNHMJiKz/Eg++CxGslryotHAse8cDhhaVNdvhsyWdXgeZAlMw",
+  "Yb+PN/Hyr185HXMzVGEm5mbyHOZoh1e68K+BZRRW7g8mu32GxuMPlCfSEJ8Ca+cH",
+  "JRRm3gdIXejJzYL8+ECHB1ZA/5rrjMRoluCpzIaO/JuOrUka488bEpZa0SM5R/E0",
+  "oxgNj/5h9WV99mIBTKP6uPhsduwLOmETKSzJ53wMqND7DUyVhehMcFh0jR39QQWj",
+  "/pFp7YB8/krLA03SRbLuuwSJ0tX9Pjb8pXxTUUnnht9+WuxQSIMYFCvtEg==",
+  "=TLuY",
+  "-----END PGP SIGNATURE-----",
+].join("\n");
+const publicKey = [
+  "-----BEGIN PGP PUBLIC KEY BLOCK-----",
+  "",
+  "mDMEarhXCxYJKwYBBAHaRw8BAQdAMFGusqeWs1dEHGDmMnoDwOBl5noKtQUIGORr",
+  "ONGF5GC0JW1wbyBmaXh0dXJlIDxmaXh0dXJlQGV4YW1wbGUuaW52YWxpZD6IkAQT",
+  "FggAOBYhBJOQZNARzeghm5nYd2FcayVx+JUtBQJquFcLAhsDBQsJCAcCBhUKCQgL",
+  "AgQWAgMBAh4BAheAAAoJEGFcayVx+JUt4OoA/1D+/ZAGt3HeS8d7oLydIaRK2s8h",
+  "Ew8OhTBk7hzPJKHAAQD7T5AOlLH3r+MzFkqawLdlWy1FnUiVrwyqIrLDvmniCA==",
+  "=yro2",
+  "-----END PGP PUBLIC KEY BLOCK-----",
+].join("\n");
+const blob = `${signature}\n${publicKey}`;
+
+const pendingOf = (signer: ReturnType<typeof createGpgSigner>) => signer.pending as GpgSignRequest;
+
+describe("GPG signer", () => {
+  it("parks a request with the terminal command and resolves with the pasted blob", async () => {
+    const signer = createGpgSigner();
+    expect(signer.family).toBe("gpg");
+    expect(signer.address).toBeNull();
+    const signed = signer.signMessage("sign me");
+    expect(signer.pending).toEqual({ message: "sign me", command: gpgSignCommand("sign me") });
+    signer.submit(`\n  ${blob}\n`, pendingOf(signer));
+    await expect(signed).resolves.toBe(blob);
+    expect(signer.pending).toBeNull();
+  });
+
+  it("keeps the request pending when the paste is missing a block", async () => {
+    const signer = createGpgSigner();
+    const signed = signer.signMessage("sign me");
+    expect(() => signer.submit(signature, pendingOf(signer))).toThrow(/PUBLIC KEY/);
+    expect(signer.pending?.message).toBe("sign me");
+    signer.submit(blob, pendingOf(signer));
+    await expect(signed).resolves.toBe(blob);
+  });
+
+  it("refuses a paste for a superseded request, even one for the same message", async () => {
+    const signer = createGpgSigner();
+    const first = signer.signMessage("sign me");
+    const stale = pendingOf(signer);
+    const second = signer.signMessage("sign me");
+    await expect(first).rejects.toThrow(/superseded/);
+    expect(() => signer.submit(blob, stale)).toThrow(/superseded/);
+    expect(signer.pending).not.toBe(stale);
+    signer.submit(blob, pendingOf(signer));
+    await expect(second).resolves.toBe(blob);
+  });
+
+  it("refuses a signature over a different message and keeps the request", async () => {
+    const signer = createGpgSigner();
+    const signed = signer.signMessage("sign me, nonce 2");
+    const request = pendingOf(signer);
+    expect(() => signer.submit(blob, request)).toThrow(/different message/);
+    expect(signer.pending).toBe(request);
+    signer.cancel();
+    await expect(signed).rejects.toThrow(/cancelled/);
+  });
+
+  it("rejects on cancel and when a newer request replaces it", async () => {
+    const signer = createGpgSigner();
+    const first = signer.signMessage("one");
+    const second = signer.signMessage("two");
+    await expect(first).rejects.toThrow(/superseded/);
+    expect(signer.pending?.message).toBe("two");
+    const request = pendingOf(signer);
+    signer.cancel();
+    await expect(second).rejects.toThrow(/cancelled/);
+    expect(() => signer.submit(blob, request)).toThrow(/No GPG signature was requested/);
+  });
+
+  it("escapes single quotes so a message cannot break out of the command", () => {
+    expect(gpgSignCommand("it's")).toBe(
+      `{ printf %s 'it'\\''s' | gpg --detach-sign --armor; gpg --armor --export; }`,
+    );
+  });
+
+  it("tells which message a real gpg signature covers", () => {
+    expect(gpgSignatureCovers(blob, "sign me")).toBe(true);
+    expect(gpgSignatureCovers(blob, "sign me!")).toBe(false);
+    expect(gpgSignatureCovers(signatureSha512, "sign me")).toBe(true);
+    expect(gpgSignatureCovers(rsaSignature, "sign me")).toBe(true);
+    expect(gpgSignatureCovers(rsaSignature, "sign you")).toBe(false);
+    // --textmode hashes CRLF line endings, so both spellings of the message match.
+    expect(gpgSignatureCovers(textSignature, "line one\nline two")).toBe(true);
+    expect(gpgSignatureCovers(textSignature, "line one\r\nline two")).toBe(true);
+    expect(gpgSignatureCovers(textSignature, "line one\nline 2")).toBe(false);
+    expect(() => gpgSignatureCovers(publicKey, "sign me")).toThrow(/No PGP SIGNATURE/);
+  });
+
+  it("trims a complete paste and rejects an incomplete one", () => {
+    expect(assertGpgSignature(`  ${blob}  `)).toBe(blob);
+    expect(() => assertGpgSignature("nope")).toThrow(/FULL output/);
+  });
+
+  it("re-renders a subscribed component as requests come and go", async () => {
+    const signer = createGpgSigner();
+    const { result } = renderHook(() => useGpgSigner(signer).pending);
+    expect(result.current).toBeNull();
+    let signed!: Promise<string>;
+    act(() => {
+      signed = signer.signMessage("sign me");
+    });
+    expect(result.current?.message).toBe("sign me");
+    act(() => signer.submit(blob, pendingOf(signer)));
+    expect(result.current).toBeNull();
+    await expect(signed).resolves.toBe(blob);
+  });
+
+  it("shares one app-wide signer when none is passed", () => {
+    const a = renderHook(() => useGpgSigner());
+    const b = renderHook(() => useGpgSigner());
+    expect(a.result.current).toBe(b.result.current);
+  });
+});

package/src/clients/gpg.ts

@@ -0,0 +1,8 @@
+export {
+  assertGpgSignature,
+  createGpgSigner,
+  gpgSignCommand,
+  useGpgSigner,
+  type GpgSigner,
+  type GpgSignRequest,
+} from "@multiplatform.one/gpg/signer";