accounts 0.16.2 → 0.17.0

package/src/core/adapters/deviceCode/deviceCode.localnet.test.ts

@@ -0,0 +1,226 @@
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import type { DeviceCode } from 'wata'
+
+import { accounts, chain } from '../../../../test/config.js'
+import { createDeviceCodeHost, submitVerify } from '../../../../test/deviceCode.js'
+import { createServer } from '../../../../test/utils.js'
+import * as Provider from '../../Provider.js'
+import { deviceCode } from './deviceCode.js'
+
+const root = accounts[0]!
+const accessKey = accounts[1]!
+const expiry = Math.floor(Date.now() / 1000) + 3_600
+
+function connectRequest() {
+  return {
+    method: 'wallet_connect',
+    params: [
+      {
+        capabilities: {
+          authorizeAccessKey: {
+            expiry,
+            keyType: accessKey.keyType,
+            publicKey: accessKey.publicKey,
+          },
+        },
+      },
+    ],
+  } as const
+}
+
+function createProvider(options: Partial<deviceCode.Options> & { url: string }) {
+  return Provider.create({
+    adapter: deviceCode({
+      name: 'Accounts Test CLI',
+      onPrompt: (prompt) => void submitVerify(prompt),
+      rdns: 'xyz.tempo.accounts.test',
+      ...options,
+    }),
+    chains: [chain],
+  })
+}
+
+describe('deviceCode', () => {
+  test('default: bootstraps wallet_connect through the device-code flow', async () => {
+    const host = createDeviceCodeHost()
+    const server = await createServer(host.listener)
+    const prompts: DeviceCode.Prompt[] = []
+
+    try {
+      const provider = createProvider({
+        onPrompt: (prompt) => {
+          prompts.push(prompt)
+          void submitVerify(prompt)
+        },
+        url: `${server.url}/auth/device`,
+      })
+
+      const result = await provider.request(connectRequest())
+      const account = result.accounts[0]!
+      const keyAuthorization = account.capabilities.keyAuthorization
+        ? {
+            ...account.capabilities.keyAuthorization,
+            signature: { type: account.capabilities.keyAuthorization.signature.type },
+          }
+        : undefined
+
+      expect(prompts).toHaveLength(1)
+      expect(prompts[0]!.userCode).toMatch(/^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/)
+      expect(prompts[0]!.verificationUri).toBe(`${server.url}/auth/device/verify`)
+      expect(prompts[0]!.verificationUriFull).toBe(
+        `${server.url}/auth/device/verify?user_code=${prompts[0]!.userCode}`,
+      )
+      expect({
+        account: {
+          address: account.address,
+          capabilities: keyAuthorization ? { keyAuthorization } : {},
+        },
+      }).toMatchInlineSnapshot(`
+        {
+          "account": {
+            "address": "${root.address}",
+            "capabilities": {
+              "keyAuthorization": {
+                "address": "${accessKey.address.toLowerCase()}",
+                "chainId": "${Hex.fromNumber(chain.id)}",
+                "expiry": "${Hex.fromNumber(expiry)}",
+                "keyId": "${accessKey.address.toLowerCase()}",
+                "keyType": "secp256k1",
+                "signature": {
+                  "type": "secp256k1",
+                },
+              },
+            },
+          },
+        }
+      `)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: forwards request context to the host', async () => {
+    const host = createDeviceCodeHost()
+    const server = await createServer(host.listener)
+
+    try {
+      const provider = createProvider({ url: `${server.url}/auth/device` })
+      await provider.request(connectRequest())
+
+      expect(host.requests()).toHaveLength(1)
+      expect(host.requests()[0]!.method).toBe('wallet_connect')
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: preserves a null username capability', async () => {
+    const host = createDeviceCodeHost({ username: null })
+    const server = await createServer(host.listener)
+
+    try {
+      const provider = createProvider({ url: `${server.url}/auth/device` })
+      const result = await provider.request(connectRequest())
+
+      expect(result.accounts[0]!.capabilities.username).toBeNull()
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: denial rejects with a user-rejected error', async () => {
+    const host = createDeviceCodeHost()
+    const server = await createServer(host.listener)
+
+    try {
+      const provider = createProvider({
+        onPrompt: (prompt) => void submitVerify(prompt, { action: 'deny' }),
+        url: `${server.url}/auth/device`,
+      })
+
+      await expect(
+        provider.request(connectRequest()).catch((error: { code: number; message: string }) => ({
+          code: error.code,
+          message: error.message,
+        })),
+      ).resolves.toMatchInlineSnapshot(`
+        {
+          "code": 4001,
+          "message": "User denied the device-code request.",
+        }
+      `)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: times out while waiting for authorization', async () => {
+    const host = createDeviceCodeHost({ pollingInterval: 10 })
+    const server = await createServer(host.listener)
+
+    try {
+      const provider = createProvider({
+        onPrompt: () => {},
+        timeout: 100,
+        url: `${server.url}/auth/device`,
+      })
+
+      const error = await provider.request(connectRequest()).then(
+        () => undefined,
+        (error: Error) => error,
+      )
+      expect(error?.message).toMatch(/^Timed out waiting for device code [A-Z-]+\. Continue at /)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: onPrompt failures surface the URL and code', async () => {
+    const host = createDeviceCodeHost()
+    const server = await createServer(host.listener)
+
+    try {
+      const provider = createProvider({
+        onPrompt: () => {
+          throw new Error('browser unavailable')
+        },
+        url: `${server.url}/auth/device`,
+      })
+
+      const error = await provider.request(connectRequest()).then(
+        () => undefined,
+        (error: Error) => error,
+      )
+      expect(error?.message).toMatch(
+        /^Failed to surface device code [A-Z-]+\. Open .*\/auth\/device\/verify\?user_code=[A-Z-]+ manually\.$/,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+
+  test('behavior: rejects methods outside the allowlist without a ceremony', async () => {
+    const host = createDeviceCodeHost()
+    const server = await createServer(host.listener)
+    const prompts: DeviceCode.Prompt[] = []
+
+    try {
+      const provider = createProvider({
+        methods: ['wallet_authorizeAccessKey'],
+        onPrompt: (prompt) => {
+          prompts.push(prompt)
+          void submitVerify(prompt)
+        },
+        url: `${server.url}/auth/device`,
+      })
+
+      await expect(provider.request(connectRequest())).rejects.toThrowErrorMatchingInlineSnapshot(
+        `[Provider.UnsupportedMethodError: \`wallet_connect\` not supported by device-code adapter.]`,
+      )
+      expect(prompts).toHaveLength(0)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})

package/src/core/adapters/deviceCode/deviceCode.test-d.ts

@@ -0,0 +1,19 @@
+import { describe, test } from 'vp/test'
+
+import { deviceCode } from './deviceCode.js'
+
+describe('deviceCode', () => {
+  test('accepts explicitly undefined optional metadata', () => {
+    const description: string | undefined = undefined
+    const icon: string | undefined = undefined
+    const websiteUrl: string | undefined = undefined
+
+    deviceCode({
+      meta: { name: 'Example', description, icon, websiteUrl },
+      name: 'Example',
+      onPrompt() {},
+      rdns: 'com.example',
+      url: 'https://example.com/auth/device',
+    })
+  })
+})

package/src/core/adapters/deviceCode/deviceCode.ts

@@ -0,0 +1,157 @@
+import { Provider as core_Provider } from 'ox'
+import { DeviceCode, Transport, Wata, deviceCode as core_deviceCode } from 'wata'
+
+import type * as Adapter from '../../Adapter.js'
+import type * as Keystore from '../../Keystore.js'
+import { fromRequest } from '../internal/fromRequest.js'
+
+/**
+ * Creates a device-code adapter that forwards wallet RPC through Wata.
+ *
+ * Each request runs one OAuth 2.0 Device Authorization Grant exchange
+ * (RFC 8628 with PKCE): the host issues a user code surfaced via
+ * `onPrompt`, the user approves on the host's verification page, and the
+ * adapter polls until the response arrives.
+ */
+export function deviceCode(options: deviceCode.Options): Adapter.Adapter {
+  const {
+    actions,
+    fetch,
+    icon,
+    keystores,
+    meta,
+    methods,
+    name,
+    onPrompt,
+    pollingInterval,
+    rdns,
+    timeout = 300_000,
+    url,
+  } = options
+
+  return fromRequest({
+    ...(actions ? { actions } : {}),
+    ...(icon ? { icon } : {}),
+    ...(keystores ? { keystores } : {}),
+    name,
+    rdns,
+    async request(request) {
+      if (methods && !methods.includes(request.method))
+        throw new core_Provider.UnsupportedMethodError({
+          message: `\`${request.method}\` not supported by device-code adapter.`,
+        })
+
+      // Device code is single-exchange: one register + poll cycle carries one
+      // RPC request envelope, so a fresh Wata instance backs every request.
+      const wata = Wata.create({
+        transports: [
+          core_deviceCode({
+            ...(fetch !== undefined ? { fetch } : {}),
+            ...(meta ? { meta } : {}),
+            ...(pollingInterval !== undefined ? { pollingInterval } : {}),
+            url,
+          }),
+        ],
+      })
+      const session = wata.start()
+
+      // A failed prompt surface (e.g. browser open) fails the exchange — the
+      // user can never learn the code, so polling would only run out the clock.
+      session.onPrompt((prompt) => {
+        void (async () => onPrompt(prompt))().catch((error) => {
+          void session.close(new PromptError(prompt, error))
+        })
+      })
+
+      const timer = setTimeout(() => {
+        void session.close(new TimeoutError(session.prompt))
+      }, timeout)
+
+      try {
+        const { result } = await session.send({
+          method: request.method,
+          params: request.params ?? [],
+          ...(request.context ? { context: request.context } : {}),
+        })
+        return result
+      } catch (error) {
+        if (error instanceof DeviceCode.UserRejectedError)
+          throw new core_Provider.UserRejectedRequestError({
+            message: 'User denied the device-code request.',
+          })
+        if (error instanceof Transport.ClosedError)
+          throw new Error('Device code expired before authorization completed.', { cause: error })
+        throw error
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+  })
+}
+
+export declare namespace deviceCode {
+  /** Options for {@link deviceCode}. */
+  export type Options = {
+    /** Adapter-specific action overrides layered over the request-forwarding defaults. */
+    actions?: fromRequest.Options['actions'] | undefined
+    /** Override the transport `fetch` implementation. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Data URI of the provider icon, announced via EIP-6963. */
+    icon?: Adapter.Meta['icon'] | undefined
+    /** Keystores backing locally generated access keys (SDK default otherwise). */
+    keystores?: Keystore.Keystores | undefined
+    /** Consumer metadata shown on the host's approval page. */
+    meta?:
+      | {
+          name: string
+          description?: string | undefined
+          icon?: string | undefined
+          websiteUrl?: string | undefined
+        }
+      | undefined
+    /** Allowlist of RPC methods forwarded over the transport. Forwards all when omitted. */
+    methods?: readonly string[] | undefined
+    /** Provider display name. */
+    name: string
+    /** Surfaces the pairing prompt (user code + verification URL) to the user. */
+    onPrompt: (prompt: DeviceCode.Prompt) => Promise<void> | void
+    /** Poll cadence override in milliseconds. Defaults to the host-advertised interval. */
+    pollingInterval?: number | undefined
+    /** Reverse-DNS provider identifier. */
+    rdns: string
+    /** Overall wait for user approval in milliseconds. @default 300000 */
+    timeout?: number | undefined
+    /** Base URL of the host's device-code endpoints (derives `/register` and `/token`). */
+    url: string
+  }
+}
+
+/** Thrown when the `onPrompt` callback fails (e.g. no browser could be opened). */
+export class PromptError extends Error {
+  override cause?: unknown | undefined
+  prompt: DeviceCode.Prompt
+
+  constructor(prompt: DeviceCode.Prompt, cause?: unknown) {
+    super(
+      `Failed to surface device code ${prompt.userCode}. Open ${prompt.verificationUriFull ?? prompt.verificationUri} manually.`,
+    )
+    this.name = 'PromptError'
+    this.cause = cause
+    this.prompt = prompt
+  }
+}
+
+/** Thrown when the user did not approve within {@link deviceCode.Options.timeout}. */
+export class TimeoutError extends Error {
+  prompt: DeviceCode.Prompt | undefined
+
+  constructor(prompt: DeviceCode.Prompt | undefined) {
+    super(
+      prompt
+        ? `Timed out waiting for device code ${prompt.userCode}. Continue at ${prompt.verificationUriFull ?? prompt.verificationUri}.`
+        : 'Timed out waiting for device code approval.',
+    )
+    this.name = 'TimeoutError'
+    this.prompt = prompt
+  }
+}

package/src/core/adapters/deviceCode/index.ts

@@ -0,0 +1,2 @@
+export { PromptError, TimeoutError, deviceCode } from './deviceCode.js'
+export { tempoWallet } from './tempoWallet.js'

package/src/core/adapters/deviceCode/tempoWallet.ts

@@ -0,0 +1,17 @@
+import type * as Adapter from '../../Adapter.js'
+import { deviceCode } from './deviceCode.js'
+
+/** Creates the Tempo Wallet adapter using the Wata device-code transport. */
+export function tempoWallet(options: tempoWallet.Options): Adapter.Adapter {
+  return deviceCode({
+    ...options,
+    name: 'Tempo Wallet',
+    rdns: 'xyz.tempo',
+    url: 'https://wallet.tempo.xyz/auth/device',
+  })
+}
+
+export declare namespace tempoWallet {
+  /** Options for {@link tempoWallet}. */
+  export type Options = Omit<deviceCode.Options, 'name' | 'rdns' | 'url'>
+}

package/src/core/adapters/internal/fromRequest.ts

@@ -16,106 +16,133 @@ import * as Rpc from '../../zod/rpc.js'
  * `request`.
  */
 export function fromRequest(options: fromRequest.Options): Adapter.Adapter {
-  const { bind, cleanup, close, icon, keystores, name, rdns, request: requestRemote } = options
+  const {
+    actions,
+    bind,
+    cleanup,
+    close,
+    icon,
+    keystores,
+    name,
+    rdns,
+    request: requestRemote,
+  } = options
 
-  return Adapter.define({ ...(icon ? { icon } : {}), name, rdns }, ({ getAccount, store }) => {
-    // Late-bind the store so the request channel can reconcile local
-    // connection state (e.g. a wallet `accountsChanged` notification).
-    bind?.({ store })
+  return Adapter.define(
+    { ...(icon ? { icon } : {}), name, rdns },
+    ({ getAccount, getClient, store }) => {
+      // Late-bind the store so the request channel can reconcile local
+      // connection state (e.g. a wallet `accountsChanged` notification).
+      bind?.({ store })
 
-    const provider = core_Provider.from({
-      async request(request) {
-        const { accounts, activeAccount, chainId } = store.getState()
-        if (request.method === 'eth_chainId') return Hex.fromNumber(chainId)
-        // Forward the active account + chain as request context so the wallet
-        // acts against the session the app believes it is using rather than
-        // whatever the wallet last selected for itself.
-        const account = accounts[activeAccount]?.address
-        return await requestRemote({
-          method: request.method,
-          params: request.params as readonly unknown[] | undefined,
-          context: { chainId, ...(account ? { account } : {}) },
-        })
-      },
-    })
+      const provider = core_Provider.from({
+        async request(request) {
+          const { accounts, activeAccount, chainId } = store.getState()
+          if (request.method === 'eth_chainId') return Hex.fromNumber(chainId)
+          // Forward the active account + chain as request context so the wallet
+          // acts against the session the app believes it is using rather than
+          // whatever the wallet last selected for itself.
+          const account = accounts[activeAccount]?.address
+          return await requestRemote({
+            method: request.method,
+            params: request.params as readonly unknown[] | undefined,
+            context: { chainId, ...(account ? { account } : {}) },
+          })
+        },
+      })
 
-    // Connect capabilities are read from the first account only: the remote
-    // wallet connects a single account per exchange.
-    function toConnectReturn(result: Rpc.wallet_connect.Encoded['returns']) {
-      const capabilities = result.accounts[0]?.capabilities
-      return {
-        accounts: result.accounts.map((account) => ({ address: account.address })),
-        ...(capabilities?.auth ? { auth: capabilities.auth } : {}),
-        ...(capabilities?.identity ? { identity: capabilities.identity } : {}),
-        ...(capabilities?.keyAuthorization
-          ? { keyAuthorization: capabilities.keyAuthorization }
-          : {}),
-        ...(capabilities?.personalSign ? { personalSign: capabilities.personalSign } : {}),
-        ...(capabilities?.signature ? { signature: capabilities.signature } : {}),
+      // Connect capabilities are read from the first account only: the remote
+      // wallet connects a single account per exchange.
+      function toConnectReturn(result: Rpc.wallet_connect.Encoded['returns']) {
+        const capabilities = result.accounts[0]?.capabilities
+        return {
+          accounts: result.accounts.map((account) => ({ address: account.address })),
+          ...(capabilities?.auth ? { auth: capabilities.auth } : {}),
+          ...(capabilities?.identity ? { identity: capabilities.identity } : {}),
+          ...(capabilities?.keyAuthorization
+            ? { keyAuthorization: capabilities.keyAuthorization }
+            : {}),
+          ...(capabilities?.personalSign ? { personalSign: capabilities.personalSign } : {}),
+          ...(capabilities?.signature ? { signature: capabilities.signature } : {}),
+          ...(capabilities?.username !== undefined ? { username: capabilities.username } : {}),
+        }
       }
-    }
 
-    return {
-      forwardsAuth: true,
-      ...(keystores ? { accessKey: { keystores } } : {}),
-      actions: {
-        async createAccount(_parameters, request) {
-          return toConnectReturn(
-            (await provider.request(request)) as Rpc.wallet_connect.Encoded['returns'],
-          )
-        },
-        async loadAccounts(_parameters, request) {
-          return toConnectReturn(
-            (await provider.request(request)) as Rpc.wallet_connect.Encoded['returns'],
-          )
-        },
-        async deposit(_parameters, request) {
-          return (await provider.request(request)) as Rpc.wallet_deposit.Encoded['returns']
-        },
-        async depositZone(parameters, request) {
-          return (await provider.request({
-            ...request,
-            params: [z.encode(Rpc.wallet_depositZone.parameters, parameters)] as const,
-          })) as Rpc.wallet_depositZone.Encoded['returns']
-        },
-        // `disconnect` (when `close` is set) only tears down the local
-        // wallet session — it is never forwarded. No `switchChain` action:
-        // chain selection is local state the provider handles itself, and
-        // forwarding it would open a wallet session for nothing.
-        ...(close ? { disconnect: close } : {}),
-        async swap(_parameters, request) {
-          return (await provider.request(request)) as Rpc.wallet_swap.Encoded['returns']
-        },
-        async transfer(parameters, request) {
-          return (await provider.request({
-            ...request,
-            params: [z.encode(Rpc.wallet_transfer.parameters, parameters)] as const,
-          })) as Rpc.wallet_transfer.Encoded['returns']
+      return {
+        forwardsAuth: true,
+        ...(keystores ? { accessKey: { keystores } } : {}),
+        actions: {
+          async createAccount(_parameters, request) {
+            return toConnectReturn(
+              (await provider.request(request)) as Rpc.wallet_connect.Encoded['returns'],
+            )
+          },
+          async loadAccounts(_parameters, request) {
+            return toConnectReturn(
+              (await provider.request(request)) as Rpc.wallet_connect.Encoded['returns'],
+            )
+          },
+          async deposit(_parameters, request) {
+            return (await provider.request(request)) as Rpc.wallet_deposit.Encoded['returns']
+          },
+          async depositZone(parameters, request) {
+            return (await provider.request({
+              ...request,
+              params: [z.encode(Rpc.wallet_depositZone.parameters, parameters)] as const,
+            })) as Rpc.wallet_depositZone.Encoded['returns']
+          },
+          // `disconnect` (when `close` is set) only tears down the local
+          // wallet session — it is never forwarded. No `switchChain` action:
+          // chain selection is local state the provider handles itself, and
+          // forwarding it would open a wallet session for nothing.
+          ...(close ? { disconnect: close } : {}),
+          async swap(_parameters, request) {
+            return (await provider.request(request)) as Rpc.wallet_swap.Encoded['returns']
+          },
+          async transfer(parameters, request) {
+            return (await provider.request({
+              ...request,
+              params: [z.encode(Rpc.wallet_transfer.parameters, parameters)] as const,
+            })) as Rpc.wallet_transfer.Encoded['returns']
+          },
+          async withdrawZone(parameters, request) {
+            return (await provider.request({
+              ...request,
+              params: [z.encode(Rpc.wallet_withdrawZone.parameters, parameters)] as const,
+            })) as Rpc.wallet_withdrawZone.Encoded['returns']
+          },
+          ...actions?.({ getClient, request: requestRemote, store }),
         },
-        async withdrawZone(parameters, request) {
-          return (await provider.request({
-            ...request,
-            params: [z.encode(Rpc.wallet_withdrawZone.parameters, parameters)] as const,
-          })) as Rpc.wallet_withdrawZone.Encoded['returns']
+        ...(cleanup ? { cleanup } : close ? { cleanup: () => void close() } : {}),
+        getAccount(parameters = {}) {
+          return {
+            account: {
+              address: parameters.address ?? getAccount({ signable: false }).address,
+              type: 'json-rpc' as const,
+            },
+            transport: custom(provider),
+          }
         },
-      },
-      ...(cleanup ? { cleanup } : close ? { cleanup: () => void close() } : {}),
-      getAccount(parameters = {}) {
-        return {
-          account: {
-            address: parameters.address ?? getAccount({ signable: false }).address,
-            type: 'json-rpc' as const,
-          },
-          transport: custom(provider),
-        }
-      },
-    }
-  })
+      }
+    },
+  )
 }
 
 export declare namespace fromRequest {
   /** Options for {@link fromRequest}. */
   export type Options = {
+    /**
+     * Adapter-specific action overrides layered over the request-forwarding
+     * defaults. Receives the request channel plus the adapter's client and
+     * store for actions that need local bookkeeping around an exchange.
+     */
+    actions?:
+      | ((context: {
+          getClient: Adapter.SetupFn.Parameters['getClient']
+          request: Options['request']
+          store: Adapter.SetupFn.Parameters['store']
+        }) => Partial<Adapter.Instance['actions']>)
+      | undefined
     /**
      * Called once during setup with the adapter's store, for late wiring
      * that needs to mutate local state (e.g. reconciling connection state