ethagent 1.1.2 → 2.0.0

package/src/identity/wallet/browserWallet/session.ts

@@ -0,0 +1,325 @@
+import http from 'node:http'
+import { randomUUID } from 'node:crypto'
+import { recoverAddressFromSignature } from '../../crypto/eth.js'
+import { normalizeWalletPayloadPurpose } from '../walletPurposeCompat.js'
+import { walletPage } from './html.js'
+import { readJson, respondHtml, respondJson } from './http.js'
+import {
+  BrowserWalletError,
+  type BrowserWalletSession,
+  type BrowserWalletSignAndTransaction,
+  type BrowserWalletSignature,
+  type BrowserWalletTransaction,
+  type PendingPrompt,
+  type ReadyHandler,
+  type SignAndTransactionRequest,
+} from './types.js'
+import {
+  accountMismatchError,
+  chainIdHex,
+  parseAccount,
+  parseBrowserWalletErrorBody,
+  parseHex,
+} from './validation.js'
+
+export async function openBrowserWalletSession(args: {
+  title?: string
+  onReady?: ReadyHandler
+} = {}): Promise<BrowserWalletSession> {
+  const title = args.title ?? 'ethagent wallet session'
+  const sseClients: Set<http.ServerResponse> = new Set()
+  let pending: PendingPrompt | null = null
+  let closed = false
+
+  const pushEvent = (kind: string, data: Record<string, unknown>): void => {
+    const payload = `event: ${kind}\ndata: ${JSON.stringify(data)}\n\n`
+    for (const res of sseClients) {
+      try { res.write(payload) } catch { }
+    }
+  }
+
+  const failPending = (err: unknown): void => {
+    if (!pending) return
+    clearTimeout(pending.timeout)
+    pending.reject(err instanceof Error ? err : new Error(String(err)))
+    pending = null
+  }
+
+  const handleRequest = async (req: http.IncomingMessage, res: http.ServerResponse): Promise<void> => {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/ethagent')) {
+      respondHtml(res, walletPage(title, '', { kind: 'session-wait' }))
+      return
+    }
+    if (req.method === 'GET' && url.pathname === '/events') {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+        'connection': 'keep-alive',
+      })
+      res.write(`: connected\n\n`)
+      sseClients.add(res)
+      req.on('close', () => sseClients.delete(res))
+      if (pending) {
+        res.write(`event: prompt\ndata: ${JSON.stringify({ sessionToken: pending.sessionToken, ...pending.payload })}\n\n`)
+      }
+      return
+    }
+    if (req.method === 'POST' && url.pathname === '/prepare') {
+      const body = await readJson(req)
+      if (!pending || body.sessionToken !== pending.sessionToken) {
+        respondJson(res, 409, { ok: false, error: 'no active prompt' })
+        return
+      }
+      if (!pending.prepare) {
+        respondJson(res, 400, { ok: false, error: 'this prompt does not have a prepare step' })
+        return
+      }
+      respondJson(res, 200, { ok: true, ...pending.prepare(body) })
+      return
+    }
+    if (req.method === 'POST' && url.pathname === '/prepare-transaction') {
+      const body = await readJson(req)
+      if (!pending || body.sessionToken !== pending.sessionToken) {
+        respondJson(res, 409, { ok: false, error: 'no active prompt' })
+        return
+      }
+      if (!pending.prepareTransaction) {
+        respondJson(res, 400, { ok: false, error: 'this prompt does not prepare transactions' })
+        return
+      }
+      respondJson(res, 200, { ok: true, ...(await pending.prepareTransaction(body)) })
+      return
+    }
+    if (req.method === 'POST' && url.pathname === '/complete') {
+      const body = await readJson(req)
+      if (!pending || body.sessionToken !== pending.sessionToken) {
+        respondJson(res, 409, { ok: false, error: 'no active prompt' })
+        return
+      }
+      const finished = pending
+      pending = null
+      respondJson(res, 200, { ok: true })
+      clearTimeout(finished.timeout)
+      finished.resolve(body)
+      return
+    }
+    if (req.method === 'POST' && url.pathname === '/cancel') {
+      const body = await readJson(req)
+      if (pending && body.sessionToken === pending.sessionToken) {
+        respondJson(res, 200, { ok: true })
+        failPending(new Error('wallet request was cancelled'))
+        return
+      }
+      respondJson(res, 409, { ok: false, error: 'no active prompt' })
+      return
+    }
+    if (req.method === 'POST' && url.pathname === '/error') {
+      const body = await readJson(req)
+      if (pending && body.sessionToken === pending.sessionToken) {
+        respondJson(res, 200, { ok: true })
+        failPending(new BrowserWalletError(parseBrowserWalletErrorBody(body)))
+        return
+      }
+      respondJson(res, 409, { ok: false, error: 'no active prompt' })
+      return
+    }
+    respondJson(res, 404, { ok: false, error: 'wallet session not found' })
+  }
+
+  const server = http.createServer((req, res) => {
+    void handleRequest(req, res).catch(err => {
+      respondJson(res, 500, { ok: false, error: (err as Error).message })
+    })
+  })
+
+  const url = await new Promise<string>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address()
+      if (!addr || typeof addr === 'string') {
+        reject(new Error('could not start wallet server'))
+        return
+      }
+      resolve(`http://localhost:${addr.port}/`)
+    })
+  })
+  args.onReady?.({ url })
+
+  const dispatch = <T>(opts: {
+    payload: Record<string, unknown>
+    prepare?: (body: Record<string, unknown>) => Record<string, unknown>
+    prepareTransaction?: (body: Record<string, unknown>) => Promise<Record<string, unknown>>
+    complete: (body: Record<string, unknown>) => T
+    timeoutMs?: number
+  }): Promise<T> => {
+    if (closed) return Promise.reject(new Error('wallet session is closed'))
+    if (pending) return Promise.reject(new Error('wallet session has another prompt in flight'))
+    const sessionToken = randomUUID()
+    const payload = normalizeWalletPayloadPurpose(opts.payload)
+    return new Promise<T>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        failPending(new Error('Wallet Request Timed Out'))
+      }, opts.timeoutMs ?? 5 * 60_000)
+      pending = {
+        sessionToken,
+        payload,
+        ...(opts.prepare ? { prepare: opts.prepare } : {}),
+        ...(opts.prepareTransaction ? { prepareTransaction: opts.prepareTransaction } : {}),
+        resolve: body => {
+          try { resolve(opts.complete(body)) } catch (err) { reject(err) }
+        },
+        reject,
+        timeout,
+      }
+      pushEvent('prompt', { sessionToken, ...payload })
+    })
+  }
+
+  return {
+    url,
+    requestSignature: async (req): Promise<BrowserWalletSignature> => {
+      if (!req.message && !req.messageForAccount) throw new Error('Wallet signature request needs a message')
+      return dispatch<BrowserWalletSignature>({
+        payload: {
+          kind: 'sign',
+          chainIdHex: chainIdHex(req.chainId),
+          message: req.message,
+          ...(req.expectedAccount ? { expectedAccount: req.expectedAccount } : {}),
+          ...(req.purpose ? { purpose: req.purpose } : {}),
+          ...(req.flowId ? { flowId: req.flowId } : {}),
+          ...(typeof req.flowStep === 'number' ? { flowStep: req.flowStep } : {}),
+          ...(req.tokenChainName ? { tokenChainName: req.tokenChainName } : {}),
+        },
+        ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+        prepare: body => {
+          const account = parseAccount(body.account)
+          if (req.expectedAccount && account.toLowerCase() !== req.expectedAccount.toLowerCase()) {
+            throw accountMismatchError(account, req.expectedAccount, req.purpose)
+          }
+          const message = req.messageForAccount ? req.messageForAccount(account) : req.message!
+          return { message }
+        },
+        complete: body => {
+          const account = parseAccount(body.account)
+          const message = typeof body.message === 'string' ? body.message : ''
+          const signature = parseHex(body.signature, 'wallet signature')
+          if (req.expectedAccount && account.toLowerCase() !== req.expectedAccount.toLowerCase()) {
+            throw accountMismatchError(account, req.expectedAccount, req.purpose)
+          }
+          const recovered = recoverAddressFromSignature(message, signature)
+          if (recovered.toLowerCase() !== account.toLowerCase()) {
+            throw new Error('Wallet signature does not match connected account')
+          }
+          return { account, message, signature }
+        },
+      })
+    },
+    sendTransaction: async (req): Promise<BrowserWalletTransaction> => dispatch<BrowserWalletTransaction>({
+      payload: {
+        kind: 'transaction',
+        chainIdHex: chainIdHex(req.chainId),
+        expectedAccount: req.expectedAccount,
+        tx: { to: req.to, data: req.data, ...(req.value ? { value: req.value } : {}) },
+        ...(req.purpose ? { purpose: req.purpose } : {}),
+        ...(req.flowId ? { flowId: req.flowId } : {}),
+        ...(typeof req.flowStep === 'number' ? { flowStep: req.flowStep } : {}),
+        ...(req.tokenChainName ? { tokenChainName: req.tokenChainName } : {}),
+      },
+      ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+      complete: body => {
+        const account = parseAccount(body.account)
+        if (account.toLowerCase() !== req.expectedAccount.toLowerCase()) {
+          throw accountMismatchError(account, req.expectedAccount, req.purpose)
+        }
+        return { account, txHash: parseHex(body.txHash, 'transaction hash') }
+      },
+    }),
+    requestSignatureAndTransaction: async <TPrepared>(
+      req: SignAndTransactionRequest<TPrepared>,
+    ): Promise<BrowserWalletSignAndTransaction<TPrepared>> => {
+      if (!req.message && !req.messageForAccount) throw new Error('Wallet signature request needs a message')
+      let prepared:
+        | {
+            account: `0x${string}`
+            message: string
+            signature: `0x${string}`
+            tx: { to: `0x${string}`; data: `0x${string}`; value?: `0x${string}` }
+            prepared: TPrepared
+          }
+        | null = null
+      return dispatch<BrowserWalletSignAndTransaction<TPrepared>>({
+        payload: {
+          kind: 'sign-transaction',
+          chainIdHex: chainIdHex(req.chainId),
+          message: req.message,
+          ...(req.expectedAccount ? { expectedAccount: req.expectedAccount } : {}),
+          ...(req.purpose ? { purpose: req.purpose } : {}),
+          ...(req.flowId ? { flowId: req.flowId } : {}),
+          ...(typeof req.flowStep === 'number' ? { flowStep: req.flowStep } : {}),
+          ...(req.tokenChainName ? { tokenChainName: req.tokenChainName } : {}),
+        },
+        ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+        prepare: body => {
+          const account = parseAccount(body.account)
+          if (req.expectedAccount && account.toLowerCase() !== req.expectedAccount.toLowerCase()) {
+            throw accountMismatchError(account, req.expectedAccount, req.purpose)
+          }
+          const message = req.messageForAccount ? req.messageForAccount(account) : req.message!
+          return { message }
+        },
+        prepareTransaction: async body => {
+          const account = parseAccount(body.account)
+          const message = typeof body.message === 'string' ? body.message : ''
+          const signature = parseHex(body.signature, 'wallet signature')
+          if (req.expectedAccount && account.toLowerCase() !== req.expectedAccount.toLowerCase()) {
+            throw accountMismatchError(account, req.expectedAccount, req.purpose)
+          }
+          const recovered = recoverAddressFromSignature(message, signature)
+          if (recovered.toLowerCase() !== account.toLowerCase()) {
+            throw new Error('Wallet signature does not match connected account')
+          }
+          const next = await req.prepareTransaction({ account, message, signature })
+          prepared = {
+            account,
+            message,
+            signature,
+            tx: {
+              to: next.to,
+              data: next.data,
+              ...(next.value ? { value: next.value } : {}),
+            },
+            prepared: next.prepared,
+          }
+          return { tx: prepared.tx }
+        },
+        complete: body => {
+          if (!prepared) throw new Error('Wallet transaction was not prepared')
+          const account = parseAccount(body.account)
+          if (account.toLowerCase() !== prepared.account.toLowerCase()) {
+            throw accountMismatchError(account, prepared.account, req.purpose)
+          }
+          return {
+            account,
+            message: prepared.message,
+            signature: prepared.signature,
+            txHash: parseHex(body.txHash, 'transaction hash'),
+            prepared: prepared.prepared,
+          }
+        },
+      })
+    },
+    close: async (): Promise<void> => {
+      if (closed) return
+      closed = true
+      if (pending) failPending(new Error('wallet session closed before request completed'))
+      pushEvent('done', {})
+      await new Promise(resolve => setTimeout(resolve, 250))
+      for (const res of sseClients) {
+        try { res.end() } catch { }
+      }
+      sseClients.clear()
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    },
+  }
+}

package/src/identity/wallet/browserWallet/types.ts

@@ -0,0 +1,192 @@
+import type { Address, Hex, PublicClient } from 'viem'
+
+export type ReadyHandler = (session: BrowserWalletReady) => void
+
+export type BrowserWalletReady = {
+  url: string
+}
+
+export type WalletPurpose =
+  | 'connect-operator-wallet'
+  | 'create-agent'
+  | 'restore-owner-wallet'
+  | 'restore-operator-wallet'
+  | 'update-snapshot-owner'
+  | 'update-snapshot-operator'
+  | 'update-snapshot-connected'
+  | 'update-ens'
+  | 'clear-ens'
+  | 'update-profile-owner'
+  | 'update-profile-operator'
+  | 'update-profile-connected'
+  | 'update-ens-records'
+  | 'clear-ens-records'
+  | 'create-simple-ens-subdomain'
+  | 'set-simple-ens-records'
+  | 'create-agent-ens-subdomain'
+  | 'set-agent-ens-records'
+  | 'update-operators'
+  | 'operator-proof'
+  | 'authorize-operator-wallet-resolver'
+  | 'revoke-operator-wallet-resolver'
+  | 'reconcile-resolver-approvals'
+  | 'sync-operator-vault'
+  | 'refetch-snapshot'
+  | 'prepare-transfer-sender'
+  | 'prepare-transfer-target'
+  | 'publish-transfer-snapshot'
+  | 'deploy-agent-vault'
+  | 'deposit-agent-vault'
+  | 'unwrap-agent-vault'
+  | 'rotate-agent-uri-vault-owner'
+  | 'rotate-agent-uri-vault-operator'
+  | 'withdraw-vault'
+  | 'register-root-commit'
+  | 'register-root-tx'
+  | 'delete-ens-subdomain'
+
+export type SignatureRequest = {
+  chainId: number
+  expectedAccount?: Address
+  message?: string
+  messageForAccount?: (account: Address) => string
+  timeoutMs?: number
+  onReady?: ReadyHandler
+  purpose?: WalletPurpose
+  flowId?: string
+  flowStep?: number
+  tokenChainName?: string
+}
+
+export type TransactionRequest = {
+  chainId: number
+  expectedAccount: Address
+  to?: Address
+  data: Hex
+  value?: Hex
+  gas?: Hex
+  maxFeePerGas?: Hex
+  maxPriorityFeePerGas?: Hex
+  timeoutMs?: number
+  onReady?: ReadyHandler
+  purpose?: WalletPurpose
+  flowId?: string
+  flowStep?: number
+  tokenChainName?: string
+}
+
+export type SignAndTransactionRequest<TPrepared> = {
+  chainId: number
+  expectedAccount?: Address
+  message?: string
+  messageForAccount?: (account: Address) => string
+  timeoutMs?: number
+  onReady?: ReadyHandler
+  purpose?: WalletPurpose
+  flowId?: string
+  flowStep?: number
+  tokenChainName?: string
+  prepareTransaction: (wallet: BrowserWalletSignature) => Promise<{
+    to: Address
+    data: Hex
+    value?: Hex
+    prepared: TPrepared
+  }>
+}
+
+export type AccountRequest = {
+  timeoutMs?: number
+  onReady?: ReadyHandler
+  purpose?: WalletPurpose
+  flowId?: string
+  flowStep?: number
+  tokenChainName?: string
+}
+
+export type BrowserWalletErrorPayload = {
+  message: string
+  code?: string
+  data?: string
+  causes?: readonly string[]
+  method?: string
+  purpose?: string
+  chainIdHex?: string
+  title?: string
+}
+
+export class BrowserWalletError extends Error {
+  readonly code?: string
+  readonly data?: string
+  readonly causes: readonly string[]
+  readonly method?: string
+  readonly purpose?: string
+  readonly chainIdHex?: string
+  readonly title?: string
+  constructor(payload: BrowserWalletErrorPayload) {
+    super(payload.message || 'Wallet request failed')
+    this.name = 'BrowserWalletError'
+    if (payload.code !== undefined) this.code = payload.code
+    if (payload.data !== undefined) this.data = payload.data
+    this.causes = payload.causes ?? []
+    if (payload.method !== undefined) this.method = payload.method
+    if (payload.purpose !== undefined) this.purpose = payload.purpose
+    if (payload.chainIdHex !== undefined) this.chainIdHex = payload.chainIdHex
+    if (payload.title !== undefined) this.title = payload.title
+  }
+}
+
+export type PrepareTransactionGasFeeClient = Pick<PublicClient, 'estimateGas' | 'estimateFeesPerGas'>
+
+export type PrepareTransactionGasFeeArgs = {
+  client: PrepareTransactionGasFeeClient
+  account: Address
+  to?: Address
+  data: Hex
+  value?: bigint
+}
+
+export type PreparedGasFee = {
+  gas: Hex
+  maxFeePerGas: Hex
+  maxPriorityFeePerGas: Hex
+}
+
+export type BrowserWalletSignature = {
+  account: Address
+  message: string
+  signature: Hex
+}
+
+export type BrowserWalletTransaction = {
+  account: Address
+  txHash: Hex
+}
+
+export type BrowserWalletSignAndTransaction<TPrepared> = BrowserWalletSignature & {
+  txHash: Hex
+  prepared: TPrepared
+}
+
+export type BrowserWalletAccount = {
+  account: Address
+}
+
+export type BrowserWalletSession = {
+  url: string
+  requestSignature: (req: SignatureRequest) => Promise<BrowserWalletSignature>
+  sendTransaction: (req: TransactionRequest) => Promise<BrowserWalletTransaction>
+  requestSignatureAndTransaction: <TPrepared>(
+    req: SignAndTransactionRequest<TPrepared>,
+  ) => Promise<BrowserWalletSignAndTransaction<TPrepared>>
+  close: () => Promise<void>
+}
+
+export type PendingPrompt = {
+  sessionToken: string
+  payload: Record<string, unknown>
+  prepare?: (body: Record<string, unknown>) => Record<string, unknown>
+  prepareTransaction?: (body: Record<string, unknown>) => Promise<Record<string, unknown>>
+  resolve: (body: Record<string, unknown>) => void
+  reject: (err: unknown) => void
+  timeout: NodeJS.Timeout
+}

package/src/identity/wallet/browserWallet/validation.ts

@@ -0,0 +1,74 @@
+import { getAddress, type Address, type Hex } from 'viem'
+import { normalizeWalletPurposeValue } from '../walletPurposeCompat.js'
+import type { BrowserWalletErrorPayload, WalletPurpose } from './types.js'
+
+export function parseBrowserWalletErrorBody(body: Record<string, unknown>): BrowserWalletErrorPayload {
+  const message = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : 'Wallet request failed'
+  const code = typeof body.code === 'string' && body.code.trim() ? body.code.trim() : undefined
+  const data = typeof body.data === 'string' && body.data.trim() ? body.data.trim() : undefined
+  const rawCauses = Array.isArray(body.causes) ? body.causes : []
+  const causes = rawCauses.filter((c): c is string => typeof c === 'string' && c.trim().length > 0).slice(0, 5)
+  const method = typeof body.method === 'string' && body.method.trim() ? body.method.trim() : undefined
+  const purpose = normalizeWalletPurposeValue(body.purpose)
+  const chainIdHex = typeof body.chainIdHex === 'string' && body.chainIdHex.trim() ? body.chainIdHex.trim() : undefined
+  const title = typeof body.title === 'string' && body.title.trim() ? body.title.trim() : undefined
+  return { message, code, data, causes, method, purpose, chainIdHex, title }
+}
+
+export function parseAccount(value: unknown): Address {
+  if (typeof value !== 'string') throw new Error('Wallet account is missing')
+  return getAddress(value)
+}
+
+export function parseHex(value: unknown, label: string): Hex {
+  if (typeof value !== 'string' || !/^0x[0-9a-fA-F]+$/.test(value)) throw new Error(`${label} is invalid`)
+  return value as Hex
+}
+
+export function accountMismatchError(account: Address, expectedAccount: Address, purpose?: WalletPurpose): Error {
+  if (isOwnerWalletPurpose(purpose)) {
+    return new Error(`Owner Wallet Required: connected wallet ${account} does not match owner wallet ${expectedAccount}`)
+  }
+  if (isOperatorWalletPurpose(purpose)) {
+    return new Error(`Operator Wallet Required: connected wallet ${account} does not match operator wallet ${expectedAccount}`)
+  }
+  if (purpose === 'prepare-transfer-sender' || purpose === 'publish-transfer-snapshot') {
+    return new Error(`Sender Wallet Required: connected wallet ${account} does not match sender wallet ${expectedAccount}`)
+  }
+  if (purpose === 'prepare-transfer-target') {
+    return new Error(`Receiver Wallet Required: connected wallet ${account} does not match receiver wallet ${expectedAccount}. Switch accounts in your wallet to the receiver address and retry.`)
+  }
+  return new Error(`Connected wallet ${account} does not match expected wallet ${expectedAccount}`)
+}
+
+export function assertSessionToken(body: Record<string, unknown>, sessionToken: string): void {
+  if (body.sessionToken !== sessionToken) throw new Error('Wallet session token is invalid')
+}
+
+export function chainIdHex(chainId: number): Hex {
+  return `0x${chainId.toString(16)}` as Hex
+}
+
+function isOwnerWalletPurpose(purpose: WalletPurpose | undefined): boolean {
+  return purpose === 'restore-owner-wallet'
+    || purpose === 'create-agent'
+    || purpose === 'create-agent-ens-subdomain'
+    || purpose === 'set-agent-ens-records'
+    || purpose === 'update-operators'
+    || purpose === 'update-snapshot-owner'
+    || purpose === 'update-profile-owner'
+    || purpose === 'update-ens'
+    || purpose === 'clear-ens'
+    || purpose === 'deploy-agent-vault'
+    || purpose === 'sync-operator-vault'
+    || purpose === 'rotate-agent-uri-vault-owner'
+}
+
+function isOperatorWalletPurpose(purpose: WalletPurpose | undefined): boolean {
+  return purpose === 'restore-operator-wallet'
+    || purpose === 'operator-proof'
+    || purpose === 'connect-operator-wallet'
+    || purpose === 'update-snapshot-operator'
+    || purpose === 'update-profile-operator'
+    || purpose === 'rotate-agent-uri-vault-operator'
+}