web3-tools-mcp 2.0.2 → 3.1.0

package/src/oauth.ts

@@ -3,7 +3,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js'
-import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js'
+import { InvalidGrantError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js'
 import type { AuthorizationParams, OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js'
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'
 import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
@@ -29,15 +29,26 @@ interface StoredCode {
   redirectUri: string
   resource?: string
   scopes: string[]
+  address?: string
+  credential?: string
   expiresAt: number
 }
 
 interface StoredToken {
   clientId: string
   scopes: string[]
+  address?: string
+  credential?: string
   expiresAt: number
 }
 
+/** Codes expire in milliseconds, tokens in seconds — the unit OAuth reports them in. */
+function expired(key: string, value: unknown): boolean {
+  const expiresAt = (value as { expiresAt?: number } | undefined)?.expiresAt
+  if (expiresAt === undefined) return false
+  return (key.startsWith('code:') ? expiresAt : expiresAt * 1000) < Date.now()
+}
+
 /** Redis where configured, a JSON file otherwise — issued tokens must outlive a restart. */
 class Store {
   private redis: KeyValueStorage | undefined
@@ -67,10 +78,12 @@ class Store {
     return this.read()[key] as T | undefined
   }
 
-  async set<T>(key: string, value: T): Promise<void> {
-    if (this.redis) return this.redis.setItem(`oauth:${key}`, value)
+  /** `ttl` in seconds lets Redis drop the entry itself; the file is pruned on every write. */
+  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+    if (this.redis) return this.redis.setItem(`oauth:${key}`, value, ttl)
     const data = this.read()
     data[key] = value
+    for (const [name, stored] of Object.entries(data)) if (expired(name, stored)) delete data[name]
     writeFileSync(this.file, JSON.stringify(data), { mode: 0o600 })
   }
 
@@ -92,18 +105,37 @@ function constantTimeEquals(a: string, b: string): boolean {
   return left.length === right.length && timingSafeEqual(left, right)
 }
 
-function loginPage(params: { error?: string; fields: Record<string, string> }): string {
-  // The SDK's authorize handler reads its parameters from the body on POST, so the form
-  // has to carry the whole authorization request back, not just the token.
-  const hidden = Object.entries(params.fields)
-    .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
-    .join('\n  ')
+/**
+ * How a deployment decides who is at the authorize screen.
+ *
+ * Deliberately free of any type from the MCP SDK, a chain library, or this package: an
+ * implementation renders a page and reads back a form, and everything about *how* somebody
+ * proves who they are — a shared token, a wallet signature, a company SSO — stays outside.
+ * Returning an address makes the issued token that person's; returning none authenticates
+ * the deployment rather than anybody in particular.
+ */
+export interface Login {
+  /**
+   * The page served at GET /authorize. `hidden` must be placed inside its form. `request`
+   * names who is asking and where the code will be sent, so a person can tell a phishing
+   * client from their own; like `error`, its values arrive HTML-escaped.
+   */
+  page(hidden: string, error?: string, request?: { client: string; redirectHost: string }): string | Promise<string>
+  /** Reads the posted form. An `error` re-renders the page; an `address` names the person. */
+  identify(form: Record<string, string>): Promise<{ address?: string; error?: string }>
+  /**
+   * Form fields this login owns. They are kept out of the hidden inputs replayed into the
+   * page, so a credential can never be echoed back into the HTML.
+   */
+  owns?: string[]
+  /**
+   * A shared secret this login checks against, if it has one. Everything issued is bound to
+   * it, so rotating the secret revokes every code and token handed out under the old one.
+   */
+  credential?: string
+}
 
-  return `<!doctype html>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Connect to web3-tools-mcp</title>
-<style>
+const PAGE_STYLE = `
   :root { color-scheme: light dark; }
   body { font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 26rem;
          margin: 12vh auto; padding: 0 1.25rem; }
@@ -113,22 +145,51 @@ function loginPage(params: { error?: string; fields: Record<string, string> }):
                   box-sizing: border-box; }
   input { border: 1px solid #ccd; font-family: ui-monospace, monospace; }
   button { margin-top: .75rem; border: 0; background: #3856d6; color: #fff; font-weight: 600; }
-  .error { color: #b3251d; font-weight: 600; }
+  .error { color: #b3251d; font-weight: 600; }`
+
+/** The default: one shared credential, so a self-hoster needs no identity provider. */
+export function tokenLogin(accessToken: string): Login {
+  return {
+    owns: ['token'],
+    credential: accessToken,
+    page: (hidden, error, request) => `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to web3-tools-mcp</title>
+<style>${PAGE_STYLE}
 </style>
 <h1>Connect to web3-tools-mcp</h1>
+${request ? `<p><strong>${request.client}</strong> is asking for access, and will be sent back to <strong>${request.redirectHost}</strong>.</p>` : ''}
 <p>Paste this server's access token to authorise the client.</p>
-${params.error ? `<p class="error">${params.error}</p>` : ''}
+${error ? `<p class="error">${error}</p>` : ''}
 <form method="post">
   ${hidden}
   <input name="token" type="password" placeholder="MCP_TOKEN" autocomplete="off" autofocus>
   <button type="submit">Authorise</button>
-</form>`
+</form>`,
+    async identify(form) {
+      if (!constantTimeEquals(form.token ?? '', accessToken)) return { error: 'That token was not accepted.' }
+      // No address: this authenticates the deployment, not a person.
+      return {}
+    }
+  }
 }
 
-export class SingleUserOAuthProvider implements OAuthServerProvider {
+export class OAuthProvider implements OAuthServerProvider {
   private store = new Store()
+  // A hash, so the secret itself never lands in the store.
+  private credential: string | undefined
 
-  constructor(private accessToken: string) {}
+  /**
+   * `staticToken` is accepted verbatim in an Authorization header, for clients that can send
+   * one and skip the flow entirely. It names no person, so it carries no identity.
+   */
+  constructor(
+    private login: Login,
+    private staticToken?: string
+  ) {
+    this.credential = login.credential && createHash('sha256').update(login.credential).digest('hex').slice(0, 16)
+  }
 
   get clientsStore(): OAuthRegisteredClientsStore {
     const store = this.store
@@ -151,82 +212,118 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
   }
 
   /**
-   * GET renders the token prompt; POST checks it and redirects back with a code. Handling
-   * both here keeps the whole login inside the SDK's authorize route.
+   * GET renders the login; POST hands the form to it and, if it names somebody, redirects
+   * back with a code. Handling both here keeps the whole login inside the SDK's authorize
+   * route, which is the only place the client will follow a redirect from.
    */
   async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> {
     const request = res.req
-    const submitted = (request.body as { token?: string } | undefined)?.token ?? ''
-
-    // Everything except the token itself is replayed into the form, so the handler sees a
-    // complete authorization request when the form posts back.
-    const fields = Object.fromEntries(
-      Object.entries({ ...(request.query as Record<string, string>), ...(request.body as Record<string, string>) }).filter(
-        ([name, value]) => name !== 'token' && typeof value === 'string'
-      )
-    ) as Record<string, string>
-
-    if (request.method !== 'POST') {
-      res.setHeader('content-type', 'text/html; charset=utf-8').send(loginPage({ fields }))
-      return
+    const form = { ...(request.query as Record<string, string>), ...(request.body as Record<string, string>) }
+
+    // The SDK's authorize handler reads its parameters from the body on POST, so the form
+    // has to carry the whole authorization request back — minus whatever the login owns,
+    // which would mean echoing a credential into the HTML.
+    const owned = new Set(this.login.owns ?? [])
+    const hidden = Object.entries(form)
+      .filter(([name, value]) => !owned.has(name) && typeof value === 'string')
+      .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+      .join('\n  ')
+
+    const redirectTo = new URL(params.redirectUri)
+    const shown = {
+      client: escapeHtml(client.client_name || 'An unnamed client'),
+      redirectHost: escapeHtml(redirectTo.host || redirectTo.href)
     }
 
-    if (!constantTimeEquals(submitted, this.accessToken)) {
+    // A login page that can be framed can be clickjacked into authorising somebody else.
+    res.setHeader('X-Frame-Options', 'DENY')
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'none'")
+
+    const render = async (status: number, error?: string) => {
       res
-        .status(401)
+        .status(status)
         .setHeader('content-type', 'text/html; charset=utf-8')
-        .send(loginPage({ fields, error: 'That token was not accepted.' }))
-      return
+        .send(await this.login.page(hidden, error ? escapeHtml(error) : undefined, shown))
     }
 
+    if (request.method !== 'POST') return render(200)
+
+    const identified = await this.login.identify(form)
+    if (identified.error) return render(401, identified.error)
+
     const code = randomBytes(24).toString('hex')
-    await this.store.set<StoredCode>(`code:${code}`, {
-      clientId: client.client_id,
-      codeChallenge: params.codeChallenge,
-      redirectUri: params.redirectUri,
-      resource: params.resource?.href,
-      scopes: params.scopes ?? [],
-      expiresAt: Date.now() + CODE_TTL
-    })
-
-    const redirect = new URL(params.redirectUri)
-    redirect.searchParams.set('code', code)
-    if (params.state) redirect.searchParams.set('state', params.state)
-    res.redirect(redirect.href)
+    await this.store.set<StoredCode>(
+      `code:${code}`,
+      {
+        clientId: client.client_id,
+        codeChallenge: params.codeChallenge,
+        redirectUri: params.redirectUri,
+        resource: params.resource?.href,
+        scopes: params.scopes ?? [],
+        address: identified.address,
+        credential: this.credential,
+        expiresAt: Date.now() + CODE_TTL
+      },
+      CODE_TTL / 1000
+    )
+
+    redirectTo.searchParams.set('code', code)
+    if (params.state) redirectTo.searchParams.set('state', params.state)
+    res.redirect(redirectTo.href)
   }
 
-  async challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+  // Refusals here must be InvalidGrantError: the SDK answers anything else with a 500,
+  // where a client needs the 400 invalid_grant to know it should start the flow again.
+  private async validCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<StoredCode> {
     const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
-    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
-    return stored.codeChallenge
+    if (!stored || stored.expiresAt < Date.now() || stored.credential !== this.credential) {
+      throw new InvalidGrantError('Authorization code is invalid or expired')
+    }
+    if (stored.clientId !== client.client_id) throw new InvalidGrantError('Authorization code was issued to a different client')
+    return stored
   }
 
-  async exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<OAuthTokens> {
-    const stored = await this.store.get<StoredCode>(`code:${authorizationCode}`)
-    if (!stored || stored.expiresAt < Date.now()) throw new Error('Authorization code is invalid or expired')
-    if (stored.clientId !== client.client_id) throw new Error('Authorization code was issued to a different client')
+  async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+    return (await this.validCode(client, authorizationCode)).codeChallenge
+  }
+
+  async exchangeAuthorizationCode(
+    client: OAuthClientInformationFull,
+    authorizationCode: string,
+    _codeVerifier?: string,
+    redirectUri?: string
+  ): Promise<OAuthTokens> {
+    const stored = await this.validCode(client, authorizationCode)
+    // Optional at the token endpoint because the SDK lets a single-URI client omit it at
+    // /authorize too; when sent, it must be the one the code was issued for.
+    if (redirectUri !== undefined && redirectUri !== stored.redirectUri) {
+      throw new InvalidGrantError('redirect_uri does not match the authorization request')
+    }
 
     // One use only: a replayed code must not mint a second token.
     await this.store.remove(`code:${authorizationCode}`)
-    return this.issue(client.client_id, stored.scopes)
+    return this.issue(client.client_id, stored.scopes, stored.address)
   }
 
   async exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[]): Promise<OAuthTokens> {
     const stored = await this.store.get<StoredToken>(`refresh:${refreshToken}`)
-    if (!stored) throw new Error('Refresh token is invalid')
-    if (stored.clientId !== client.client_id) throw new Error('Refresh token was issued to a different client')
+    if (!stored || stored.credential !== this.credential) throw new InvalidGrantError('Refresh token is invalid')
+    if (stored.clientId !== client.client_id) throw new InvalidGrantError('Refresh token was issued to a different client')
 
     await this.store.remove(`refresh:${refreshToken}`)
-    return this.issue(client.client_id, scopes ?? stored.scopes)
+    if (stored.expiresAt * 1000 < Date.now()) throw new InvalidGrantError('Refresh token has expired')
+    // The refreshed token stays the same person's: a refresh proves possession, not identity.
+    return this.issue(client.client_id, scopes ?? stored.scopes, stored.address)
   }
 
-  private async issue(clientId: string, scopes: string[]): Promise<OAuthTokens> {
+  private async issue(clientId: string, scopes: string[], address?: string): Promise<OAuthTokens> {
     const accessToken = randomBytes(32).toString('hex')
     const refreshToken = randomBytes(32).toString('hex')
     const expiresAt = Math.floor(Date.now() / 1000) + TOKEN_TTL
+    const stored: StoredToken = { clientId, scopes, address, credential: this.credential, expiresAt }
 
-    await this.store.set<StoredToken>(`token:${accessToken}`, { clientId, scopes, expiresAt })
-    await this.store.set<StoredToken>(`refresh:${refreshToken}`, { clientId, scopes, expiresAt })
+    await this.store.set(`token:${accessToken}`, stored, TOKEN_TTL)
+    await this.store.set(`refresh:${refreshToken}`, stored, TOKEN_TTL)
 
     return {
       access_token: accessToken,
@@ -237,9 +334,9 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
     }
   }
 
-  /** Accepts an issued token, or MCP_TOKEN itself so a client that can send a header still works. */
+  /** Accepts an issued token, or the static one so a client that can send a header still works. */
   async verifyAccessToken(token: string): Promise<AuthInfo> {
-    if (constantTimeEquals(token, this.accessToken)) {
+    if (this.staticToken && constantTimeEquals(token, this.staticToken)) {
       // requireBearerAuth refuses a token with no expiry, and this one never expires.
       return { token, clientId: 'static', scopes: [], expiresAt: Math.floor(Date.now() / 1000) + TOKEN_TTL }
     }
@@ -247,13 +344,21 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
     // Must be InvalidTokenError specifically: the SDK turns anything else into a 500, and
     // a client needs the 401 to know it should authenticate again.
     const stored = await this.store.get<StoredToken>(`token:${token}`)
-    if (!stored) throw new InvalidTokenError('Invalid access token')
+    if (!stored || stored.credential !== this.credential) throw new InvalidTokenError('Invalid access token')
     if (stored.expiresAt * 1000 < Date.now()) {
       await this.store.remove(`token:${token}`)
       throw new InvalidTokenError('Access token has expired')
     }
 
-    return { token, clientId: stored.clientId, scopes: stored.scopes, expiresAt: stored.expiresAt }
+    // `extra.address` is where the tools read the caller's identity from; a token that names
+    // nobody leaves it unset, and everything falls back to the shared identity.
+    return {
+      token,
+      clientId: stored.clientId,
+      scopes: stored.scopes,
+      expiresAt: stored.expiresAt,
+      ...(stored.address ? { extra: { address: stored.address } } : {})
+    }
   }
 
   async revokeToken(_client: OAuthClientInformationFull, request: { token: string }): Promise<void> {
@@ -262,6 +367,13 @@ export class SingleUserOAuthProvider implements OAuthServerProvider {
   }
 }
 
+/** One shared credential, which is all a self-hosted server needs. */
+export class SingleUserOAuthProvider extends OAuthProvider {
+  constructor(accessToken: string) {
+    super(tokenLogin(accessToken), accessToken)
+  }
+}
+
 /** PKCE helper, used by the tests to drive the flow the way a real client would. */
 export function pkce(): { verifier: string; challenge: string } {
   const verifier = randomBytes(32).toString('base64url')

package/src/preview.ts

@@ -23,6 +23,8 @@ export interface AssetChange {
   to: string
   amount: string
   humanAmount?: string
+  /** Set for an ERC-721 transfer, which moves this one token rather than an amount. */
+  tokenId?: string
 }
 
 export interface TxPreview {
@@ -83,15 +85,17 @@ function stringify(value: unknown): string {
  * Decode calldata into labelled fields (clear signing). Token amounts on the standard
  * ERC20 selectors are formatted with on-chain decimals and unlimited approvals flagged.
  */
-async function decodeCalldata(chain: ChainName, tx: RawTx): Promise<TxPreview['decoded']> {
+async function decodeCalldata(chain: ChainName, tx: RawTx, from?: string): Promise<TxPreview['decoded']> {
   if (!tx.data || tx.data === '0x') return undefined
 
   const { abi, source, proxy } = await loadAbi(chain, tx.to)
   const { functionName, args } = decodeFunctionData({ abi, data: tx.data as `0x${string}` })
 
-  const abiItem = abi.find((item): item is AbiFunction => item.type === 'function' && item.name === functionName)
+  // By selector, not name: an overloaded name would otherwise pick the wrong inputs.
+  const selector = tx.data.slice(0, 10).toLowerCase()
+  const abiItem = abi.find((item): item is AbiFunction => item.type === 'function' && toFunctionSelector(item) === selector)
   const inputs = abiItem?.inputs ?? []
-  const erc20 = ERC20_AMOUNT_ARGS[tx.data.slice(0, 10)]
+  const erc20 = ERC20_AMOUNT_ARGS[selector]
   const meta = erc20 ? await tokenMeta(chain, tx.to).catch(() => ({ symbol: undefined, decimals: undefined })) : undefined
 
   const fields: PreviewField[] = (args ?? []).map((value, i) => {
@@ -135,7 +139,7 @@ async function decodeCalldata(chain: ChainName, tx: RawTx): Promise<TxPreview['d
 
   // A registry descriptor says what the call means and how the protocol wants each field
   // labelled, which beats raw ABI argument names. Fall back to those when it has none.
-  const clearSigning = await resolveClearSigning(chain, tx, named).catch(() => null)
+  const clearSigning = await resolveClearSigning(chain, { ...tx, from }, named).catch(() => null)
   if (clearSigning) {
     return {
       functionName,
@@ -162,13 +166,30 @@ function topicToAddress(topic: string): string {
   return `0x${topic.slice(-40)}`
 }
 
-async function enrichTransfers(chain: ChainName, logs: readonly { address: string; topics: readonly string[]; data: string }[]) {
+export async function enrichTransfers(
+  chain: ChainName,
+  logs: readonly { address: string; topics: readonly string[]; data: string }[]
+) {
   const transfers = logs.filter((log) => log.topics[0]?.toLowerCase() === TRANSFER_TOPIC && log.topics.length >= 3)
 
   return Promise.all(
     transfers.map(async (log): Promise<AssetChange> => {
-      const amount = log.data && log.data !== '0x' ? BigInt(log.data).toString() : '0'
       const meta = await tokenMeta(chain, log.address).catch(() => ({ symbol: undefined, decimals: undefined }))
+
+      // ERC-721 shares ERC-20's Transfer topic but indexes the token id as a fourth topic,
+      // leaving the data empty — read as ERC-20, a mint looks like a transfer of nothing.
+      if (log.topics.length === 4) {
+        return {
+          token: log.address,
+          symbol: meta.symbol,
+          from: topicToAddress(log.topics[1]!),
+          to: topicToAddress(log.topics[2]!),
+          amount: '1',
+          tokenId: BigInt(log.topics[3]!).toString()
+        }
+      }
+
+      const amount = log.data && log.data !== '0x' ? BigInt(log.data).toString() : '0'
       return {
         token: log.address,
         symbol: meta.symbol,
@@ -237,7 +258,7 @@ export async function buildTxPreview(chain: ChainName, tx: RawTx, from?: string)
   const [decoded, simulation, toLabel] = await Promise.all([
     // A preview that cannot be built must not block the transaction, but swallowing the
     // reason makes "no details shown" impossible to diagnose.
-    decodeCalldata(chain, tx).catch((error) => {
+    decodeCalldata(chain, tx, from).catch((error) => {
       console.error('[Preview] Could not decode calldata:', error instanceof Error ? error.message : error)
       return undefined
     }),

package/src/signing-requests.ts

@@ -0,0 +1,198 @@
+import { randomBytes } from 'node:crypto'
+import { log } from './log.js'
+
+/**
+ * A signature that outlives the tool call that asked for it.
+ *
+ * Approving happens on a human's schedule. A browser signer is told to come — the tab opens
+ * and the badge flashes — but a phone wallet is only as loud as the wallet itself, and some
+ * send no notification at all. So the wait routinely outlives whatever timeout the MCP
+ * client applies, and the agent is left holding a tool call that never returns while the
+ * request is still perfectly alive in the wallet.
+ *
+ * Each request gets an id and outlives its call. Settling quickly still returns inline, so
+ * the common case — a browser tab that pops up and is approved in seconds — is unchanged.
+ * Past that the call hands back the id and the agent collects the result later.
+ *
+ * Held in memory on purpose: a request is only meaningful while the socket or WalletConnect
+ * session that carries it is alive, and both die with the process anyway.
+ */
+
+/**
+ * How long to wait on a signer that has been told to come — the browser page, whose tab
+ * opens and whose title flashes. Comfortably under any MCP client's tool timeout.
+ *
+ * A signer that cannot raise the alarm does not use this at all: it calls `waiting()` the
+ * moment the request is with the wallet, and the call returns then. Waiting on a phone that
+ * never buzzed is dead time either way.
+ */
+export const GRACE_MS = 25_000
+
+/** How long a finished result stays collectable. */
+const RESULT_TTL = 15 * 60_000
+
+export type SigningState = 'pending' | 'done' | 'failed'
+
+export interface SigningRequest {
+  id: string
+  identity: string
+  /** What is being asked for, in a line, so a later check can say what it was. */
+  summary: string
+  signer: 'browser' | 'phone'
+  /** Waiting on a person, or on the chain. They deserve different things said about them. */
+  stage: 'approval' | 'mining'
+  /** Known once approved, so a request can be followed on an explorer before it settles. */
+  txHash?: string
+  startedAt: number
+  state: SigningState
+  settledAt?: number
+  result?: unknown
+  error?: string
+}
+
+/** How a signing job says where it has got to. */
+export interface SigningProgress {
+  /**
+   * The request is with the wallet and only a human is left. Everything that fails quickly —
+   * no session, an unapproved chain, a reverted simulation — has already thrown.
+   */
+  waiting: () => void
+  /** Approved and broadcast. Nothing is settled until it is mined. */
+  mining: (txHash: string) => void
+}
+
+interface Tracked extends SigningRequest {
+  /** Already has a catch attached, so awaiting it again can never be unhandled. */
+  settled: Promise<void>
+}
+
+const requests = new Map<string, Tracked>()
+
+function sweep(): void {
+  const now = Date.now()
+  for (const [id, request] of requests) {
+    if (request.settledAt && now - request.settledAt > RESULT_TTL) requests.delete(id)
+  }
+}
+
+function view(request: Tracked): SigningRequest {
+  const { settled: _settled, ...rest } = request
+  return rest
+}
+
+/** Resolves when the request settles, or when the grace runs out — whichever comes first. */
+function race(request: Tracked, graceMs: number, handoff?: Promise<void>): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, graceMs)
+    // A request nobody is waiting for must not keep a stdio server alive after its client
+    // has gone; shutdown is what ends it.
+    timer.unref?.()
+
+    const done = () => {
+      clearTimeout(timer)
+      resolve()
+    }
+
+    request.settled.then(done)
+    handoff?.then(done)
+  })
+}
+
+/**
+ * Run a signing request, waiting only as long as a tool call reasonably can.
+ *
+ * The work starts here either way — returning `done: false` means nobody has approved yet,
+ * never that nothing was asked.
+ */
+export async function signingCall<T>(
+  context: { identity: string; summary: string; signer: 'browser' | 'phone'; graceMs?: number },
+  run: (progress: SigningProgress) => Promise<T>
+): Promise<{ done: true; result: T } | { done: false; request: SigningRequest }> {
+  sweep()
+
+  const id = randomBytes(16).toString('hex')
+
+  // Ends the wait: until it is called, a failure is a real error the caller should see
+  // rather than something to be collected later.
+  let handedOff: () => void
+  const handoff = new Promise<void>((resolve) => {
+    handedOff = resolve
+  })
+
+  // Built before `run` starts, because a signer is free to report progress synchronously.
+  const request: Tracked = {
+    id,
+    identity: context.identity,
+    summary: context.summary,
+    signer: context.signer,
+    stage: 'approval',
+    startedAt: Date.now(),
+    state: 'pending',
+    settled: Promise.resolve()
+  }
+
+  // Broadcasting does not end the wait. On a fast chain the receipt is seconds away, and a
+  // caller still inside its grace would rather have the mined result than a request id.
+  const started = run({
+    waiting: () => handedOff(),
+    mining: (txHash) => {
+      request.stage = 'mining'
+      request.txHash = txHash
+    }
+  })
+
+  request.settled = started.then(
+    (result) => {
+      request.state = 'done'
+      request.result = result
+      request.settledAt = Date.now()
+    },
+    (error: unknown) => {
+      request.state = 'failed'
+      request.error = error instanceof Error ? error.message : String(error)
+      request.settledAt = Date.now()
+    }
+  )
+
+  requests.set(id, request)
+  await race(request, context.graceMs ?? GRACE_MS, handoff)
+
+  if (request.state === 'done') {
+    requests.delete(id)
+    return { done: true, result: request.result as T }
+  }
+  if (request.state === 'failed') {
+    requests.delete(id)
+    throw new Error(request.error)
+  }
+
+  log('info', 'Signing', `${context.summary} is still waiting for approval — handed back as ${id.slice(0, 8)}`)
+  return { done: false, request: view(request) }
+}
+
+/**
+ * Collect a request handed back earlier, waiting out another grace period if it is still
+ * pending — so an agent that checks in a loop paces itself rather than spinning.
+ *
+ * Scoped to the caller: an id is unguessable, but on a server carrying several people that
+ * is not the reason one of them cannot read another's signature.
+ */
+export async function collectSigningRequest(id: string, identity: string, graceMs = GRACE_MS): Promise<SigningRequest> {
+  sweep()
+
+  const request = requests.get(id)
+  if (!request || request.identity !== identity) {
+    throw new Error(`No signing request ${id} is waiting. It may have been collected already, or it expired.`)
+  }
+
+  if (request.state === 'pending') await race(request, graceMs)
+  if (request.state !== 'pending') requests.delete(id)
+
+  return view(request)
+}
+
+/** Everything this identity still has in front of a wallet. */
+export function pendingSigningRequests(identity: string): SigningRequest[] {
+  sweep()
+  return [...requests.values()].filter((request) => request.identity === identity && request.state === 'pending').map(view)
+}