accounts 0.4.0 → 0.4.2

package/src/cli/adapter.ts

@@ -0,0 +1,229 @@
+import { spawn } from 'node:child_process'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { Base64, Hash, Hex, Provider as core_Provider, RpcResponse } from 'ox'
+import * as z from 'zod/mini'
+
+import * as Adapter from '../core/Adapter.js'
+import * as CliAuth from '../server/CliAuth.js'
+
+/**
+ * Creates a CLI bootstrap adapter backed by the device-code protocol.
+ *
+ * Only `wallet_connect` is supported in v1.
+ */
+export function cli(options: cli.Options): Adapter.Adapter {
+  const { name = 'Tempo CLI', rdns = 'xyz.tempo.cli' } = options
+
+  return Adapter.define({ name, rdns }, () => ({
+    actions: {
+      async createAccount(params, request) {
+        return this.loadAccounts(params, request)
+      },
+      async loadAccounts(parameters) {
+        const {
+          host,
+          open = defaultOpen,
+          pollIntervalMs = 2_000,
+          timeoutMs = 5 * 60 * 1_000,
+        } = options
+        const authorizeAccessKey = parameters?.authorizeAccessKey
+
+        if (!authorizeAccessKey?.publicKey)
+          throw new RpcResponse.InvalidParamsError({
+            message:
+              '`wallet_connect` on the CLI adapter requires `capabilities.authorizeAccessKey.publicKey`.',
+          })
+        if (parameters?.digest)
+          throw unsupported('`wallet_connect` digest signing not supported by CLI adapter.')
+
+        const codeVerifier = createCodeVerifier()
+        const codeChallenge = createCodeChallenge(codeVerifier)
+        const created = await post({
+          body: {
+            codeChallenge,
+            ...(typeof authorizeAccessKey.expiry !== 'undefined'
+              ? { expiry: authorizeAccessKey.expiry }
+              : {}),
+            ...(authorizeAccessKey.keyType ? { keyType: authorizeAccessKey.keyType } : {}),
+            ...(authorizeAccessKey.limits ? { limits: authorizeAccessKey.limits } : {}),
+            pubKey: authorizeAccessKey.publicKey,
+          } satisfies z.output<typeof CliAuth.createRequest>,
+          request: CliAuth.createRequest,
+          response: CliAuth.createResponse,
+          url: getApiUrl(host, 'code'),
+        })
+        const url = getBrowserUrl(host, created.code)
+
+        try {
+          await open(url)
+        } catch (error) {
+          throw new OpenError(url, created.code, error)
+        }
+
+        const startedAt = Date.now()
+
+        while (Date.now() - startedAt < timeoutMs) {
+          const result = await post({
+            body: {
+              codeVerifier,
+            } satisfies z.output<typeof CliAuth.pollRequest>,
+            request: CliAuth.pollRequest,
+            response: CliAuth.pollResponse,
+            url: getApiUrl(host, `poll/${created.code}`),
+          })
+
+          if (result.status === 'pending') {
+            await sleep(pollIntervalMs)
+            continue
+          }
+          if (result.status === 'expired')
+            throw new Error('Device code expired before authorization completed.')
+
+          return {
+            accounts: [
+              {
+                address: result.accountAddress,
+                capabilities: {},
+              },
+            ],
+            keyAuthorization: z.encode(CliAuth.keyAuthorization, result.keyAuthorization),
+          }
+        }
+
+        throw new TimeoutError(url, created.code)
+      },
+      async revokeAccessKey() {
+        throw unsupported('`wallet_revokeAccessKey` not supported by CLI adapter.')
+      },
+      async sendTransaction() {
+        throw unsupported('`eth_sendTransaction` not supported by CLI adapter.')
+      },
+      async sendTransactionSync() {
+        throw unsupported('`eth_sendTransactionSync` not supported by CLI adapter.')
+      },
+      async signPersonalMessage() {
+        throw unsupported('`personal_sign` not supported by CLI adapter.')
+      },
+      async signTransaction() {
+        throw unsupported('`eth_signTransaction` not supported by CLI adapter.')
+      },
+      async signTypedData() {
+        throw unsupported('`eth_signTypedData_v4` not supported by CLI adapter.')
+      },
+    },
+  }))
+}
+
+export declare namespace cli {
+  export type Options = {
+    /** Host URL for the device-code flow. API calls are made under the same base path. */
+    host: string
+    /** Provider display name. @default "Tempo CLI" */
+    name?: string | undefined
+    /** Browser opener override. */
+    open?: ((url: string) => Promise<void> | void) | undefined
+    /** Poll interval in milliseconds. @default 2000 */
+    pollIntervalMs?: number | undefined
+    /** Reverse-DNS provider identifier. @default "xyz.tempo.cli" */
+    rdns?: string | undefined
+    /** Poll timeout in milliseconds. @default 300000 */
+    timeoutMs?: number | undefined
+  }
+}
+
+class OpenError extends Error {
+  code: string
+  cause?: unknown | undefined
+  url: string
+
+  constructor(url: string, code: string, cause?: unknown) {
+    super(`Failed to open browser for device code ${formatCode(code)}. Open ${url} manually.`)
+    this.name = 'OpenError'
+    this.code = code
+    this.cause = cause
+    this.url = url
+  }
+}
+
+class TimeoutError extends Error {
+  code: string
+  url: string
+
+  constructor(url: string, code: string) {
+    super(`Timed out waiting for device code ${formatCode(code)}. Continue at ${url}.`)
+    this.name = 'TimeoutError'
+    this.code = code
+    this.url = url
+  }
+}
+
+function createCodeChallenge(codeVerifier: string) {
+  return Base64.fromBytes(Hash.sha256(Hex.fromString(codeVerifier), { as: 'Bytes' }), {
+    pad: false,
+    url: true,
+  })
+}
+
+function createCodeVerifier() {
+  return Base64.fromBytes(Hex.toBytes(Hex.random(32)), { pad: false, url: true })
+}
+
+function formatCode(code: string) {
+  return code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code
+}
+
+function defaultOpen(url: string) {
+  const command =
+    process.platform === 'darwin'
+      ? { command: 'open', args: [url] }
+      : process.platform === 'win32'
+        ? { command: 'cmd', args: ['/c', 'start', '', url] }
+        : { command: 'xdg-open', args: [url] }
+
+  const child = spawn(command.command, command.args, {
+    detached: true,
+    stdio: 'ignore',
+  })
+  child.unref()
+}
+
+function getApiUrl(serviceUrl: string, path: string) {
+  const url = new URL(serviceUrl)
+  url.pathname = `${url.pathname.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+  url.search = ''
+  return url.toString()
+}
+
+function getBrowserUrl(serviceUrl: string, code: string) {
+  const url = new URL(serviceUrl)
+  url.searchParams.set('code', code)
+  return url.toString()
+}
+
+async function post<
+  const request extends z.ZodMiniType,
+  const response extends z.ZodMiniType,
+>(options: {
+  body: z.output<request>
+  request: request
+  response: response
+  url: string
+}): Promise<z.output<response>> {
+  const result = await fetch(options.url, {
+    body: JSON.stringify(z.encode(options.request, options.body)),
+    headers: { 'content-type': 'application/json' },
+    method: 'POST',
+  })
+  const json = (await result.json().catch(() => ({}))) as z.input<response>
+
+  if (!result.ok) {
+    const error = (json as { error?: unknown }).error
+    throw new Error(typeof error === 'string' ? error : `Request failed: ${result.status}`)
+  }
+
+  return z.decode(options.response, json)
+}
+
+function unsupported(message: string) {
+  return new core_Provider.UnsupportedMethodError({ message })
+}

package/src/cli/index.ts

@@ -0,0 +1,2 @@
+export * as Provider from './Provider.js'
+export { cli } from './adapter.js'

package/src/core/Dialog.ts

@@ -1,3 +1,4 @@
+import * as IO from './IntersectionObserver.js'
 import * as Messenger from './Messenger.js'
 import type * as Store from './Store.js'
 
@@ -207,6 +208,19 @@ export function iframe(): Dialog {
       }
     }
 
+    messenger.on('switch-mode', () => {
+      hideDialog()
+      activatePage()
+      open = false
+
+      const pending = store
+        .getState()
+        .requestQueue.filter(
+          (x): x is Store.QueuedRequest & { status: 'pending' } => x.status === 'pending',
+        )
+      if (pending.length > 0) fallback.syncRequests(pending)
+    })
+
     return {
       close() {
         fallback.close()
@@ -241,7 +255,23 @@ export function iframe(): Dialog {
           isSafari() &&
           requests.some((x) => ['wallet_connect', 'eth_requestAccounts'].includes(x.request.method))
 
-        if (unsupported) {
+        const secure = await (async () => {
+          const { trustedHosts } = await messenger.waitForReady()
+          const ioSupported = IO.supported()
+          const trusted = Boolean(trustedHosts?.includes(window.location.hostname))
+          return ioSupported || trusted
+        })()
+
+        if (unsupported || !secure) {
+          if (!secure)
+            console.warn(
+              [
+                `[accounts] Browser does not support IntersectionObserver v2 and "${window.location.hostname}" is not a trusted host.`,
+                'Falling back to popup dialog.',
+                '',
+                'To enable the iframe dialog, add your hostname to the trusted hosts list.',
+              ].join('\n'),
+            )
           fallback.syncRequests(requests)
         } else {
           const requiresConfirm = requests.some((x) => x.status === 'pending')

package/src/core/IntersectionObserver.ts

@@ -0,0 +1,6 @@
+/** Whether IntersectionObserver v2 (with `isVisible`) is supported. */
+export const supported = () =>
+  'IntersectionObserver' in window &&
+  'IntersectionObserverEntry' in window &&
+  'intersectionRatio' in IntersectionObserverEntry.prototype &&
+  'isVisible' in IntersectionObserverEntry.prototype

package/src/core/Messenger.ts

@@ -20,19 +20,25 @@ export type Messenger = {
   ) => Promise<{ id: string; topic: topic; payload: Payload<topic> }>
 }
 
+/** Options sent with the `ready` signal from the remote frame. */
+export type ReadyOptions = {
+  /** Hostnames trusted by the remote embed to render in an iframe. */
+  trustedHosts?: string[] | undefined
+}
+
 /** Bridge messenger that waits for a `ready` signal from the remote frame. */
 export type Bridge = Messenger & {
   /** Signal readiness (called by the remote frame). */
-  ready: () => void
+  ready: (options?: ReadyOptions | undefined) => void
   /** Promise that resolves when the remote frame signals ready. */
-  waitForReady: () => Promise<void>
+  waitForReady: () => Promise<ReadyOptions>
 }
 
 /** Message schema for cross-frame communication. */
 export type Schema = [
   {
     topic: 'ready'
-    payload: undefined
+    payload: ReadyOptions
   },
   {
     topic: 'rpc-requests'
@@ -52,6 +58,10 @@ export type Schema = [
     topic: 'close'
     payload: undefined
   },
+  {
+    topic: 'switch-mode'
+    payload: { mode: 'popup' }
+  },
 ]
 
 /** Union of all topic strings. */
@@ -116,8 +126,8 @@ export function bridge(parameters: bridge.Parameters): Bridge {
 
   let pending = false
 
-  const ready = withResolvers<void>()
-  from_.on('ready', ready.resolve)
+  const ready = withResolvers<ReadyOptions>()
+  from_.on('ready', (payload) => ready.resolve(payload ?? {}))
 
   const messenger = from({
     destroy() {
@@ -137,8 +147,8 @@ export function bridge(parameters: bridge.Parameters): Bridge {
 
   return {
     ...messenger,
-    ready() {
-      void messenger.send('ready', undefined)
+    ready(options) {
+      void messenger.send('ready', options ?? {})
     },
     waitForReady() {
       return ready.promise
@@ -169,7 +179,7 @@ export function noop(): Bridge {
     },
     ready() {},
     waitForReady() {
-      return Promise.resolve()
+      return Promise.resolve({})
     },
   }
 }

package/src/core/Provider.test.ts

@@ -1482,10 +1482,15 @@ describe.each(adapters)('$name', ({ adapter }: (typeof adapters)[number]) => {
 
       const connected = await connect(provider)
       await fund(connected)
+      const syncTransferCall = Actions.token.transfer.call({
+        to: '0x0000000000000000000000000000000000000001',
+        token: Addresses.pathUsd,
+        amount: parseUnits('2', 6),
+      })
 
       const receipt = await provider.request({
         method: 'eth_sendTransactionSync',
-        params: [{ calls: [transferCall], feePayer: server.url }],
+        params: [{ calls: [syncTransferCall], feePayer: server.url }],
       })
 
       expect(receipt.feePayer).toBe(feePayerAccount.address.toLowerCase())
@@ -1536,10 +1541,15 @@ describe.each(adapters)('$name', ({ adapter }: (typeof adapters)[number]) => {
 
       const connected = await connect(provider)
       await fund(connected)
+      const syncTransferCall = Actions.token.transfer.call({
+        to: '0x0000000000000000000000000000000000000001',
+        token: Addresses.pathUsd,
+        amount: parseUnits('3', 6),
+      })
 
       const receipt = await provider.request({
         method: 'eth_sendTransactionSync',
-        params: [{ calls: [transferCall], feePayer: true }],
+        params: [{ calls: [syncTransferCall], feePayer: true }],
       })
 
       expect(receipt.feePayer).toBe(feePayerAccount.address.toLowerCase())

package/src/core/Remote.ts

@@ -1,7 +1,6 @@
 import { Hex } from 'ox'
 import * as Provider from 'ox/Provider'
 import * as RpcResponse from 'ox/RpcResponse'
-import { useStore } from 'zustand'
 import type { StoreApi } from 'zustand/vanilla'
 import { createStore } from 'zustand/vanilla'
 
@@ -35,6 +34,10 @@ export type Remote = {
    * Remote context store.
    */
   store: StoreApi<State>
+  /**
+   * Hostnames trusted to render the embed in an iframe.
+   */
+  trustedHosts: readonly string[]
   /**
    * Subscribes to user-facing RPC requests from the parent context.
    *
@@ -109,7 +112,7 @@ export declare namespace respond {
 
 /** Creates a remote context for the dialog app. */
 export function create(options: create.Options): Remote {
-  const { messenger, provider } = options
+  const { messenger, provider, trustedHosts } = options
   const ready =
     typeof window !== 'undefined' && !new URLSearchParams(window.location.search).get('mode')
   const store = createStore<State>(() => ({
@@ -123,6 +126,7 @@ export function create(options: create.Options): Remote {
     messenger,
     provider,
     store,
+    trustedHosts: trustedHosts ?? [],
 
     onUserRequest(cb) {
       return this.onRequests(async (requests, event, { account }) => {
@@ -171,7 +175,7 @@ export function create(options: create.Options): Remote {
     },
 
     ready() {
-      messenger.ready()
+      messenger.ready({ trustedHosts })
 
       if (typeof window !== 'undefined') {
         const params = new URLSearchParams(window.location.search)
@@ -251,12 +255,7 @@ export declare namespace create {
     messenger: Messenger.Bridge
     /** Provider to execute RPC requests against. */
     provider: CoreProvider.Provider
+    /** Hostnames trusted to render the embed in an iframe. */
+    trustedHosts?: string[] | undefined
   }
 }
-
-/** React hook to select state from a remote context's store. */
-export function useState(remote: Remote): State
-export function useState<selected>(remote: Remote, selector: (state: State) => selected): selected
-export function useState(remote: Remote, selector?: (state: State) => unknown) {
-  return useStore(remote.store, selector as never)
-}

package/src/core/adapters/local.ts

@@ -207,8 +207,13 @@ export function local(options: local.Options): Adapter.Adapter {
         },
         async signTypedData({ data, address }) {
           const account = getAccount({ address, signable: true })
-          const { domain, types, primaryType, message } = JSON.parse(data)
-          return await account.signTypedData({ domain, types, primaryType, message })
+          const parsed = JSON.parse(data) as {
+            domain: Record<string, unknown>
+            message: Record<string, unknown>
+            primaryType: string
+            types: Record<string, unknown>
+          }
+          return await account.signTypedData(parsed)
         },
         async sendTransaction(parameters) {
           const { feePayer, ...rest } = parameters

package/src/index.ts

@@ -1,4 +1,5 @@
 export * as Ceremony from './core/Ceremony.js'
+export * as IntersectionObserver from './core/IntersectionObserver.js'
 export * as Dialog from './core/Dialog.js'
 export * as Messenger from './core/Messenger.js'
 export * as Schema from './core/Schema.js'

package/src/react/Remote.ts

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useMemo, useRef, useState as react_useState } from 'react'
+import { useStore } from 'zustand'
+
+import * as IO from '../core/IntersectionObserver.js'
+import type * as CoreRemote from '../core/Remote.js'
+
+/** Monitors element visibility using IntersectionObserver v2. */
+export function useEnsureVisibility(
+  remote: CoreRemote.Remote,
+  options: useEnsureVisibility.Options = {},
+): useEnsureVisibility.ReturnType {
+  const { enabled = true } = options
+
+  const origin = useState(remote, (s) => s.origin)
+
+  const trusted = useMemo(() => {
+    if (!origin) return false
+    try {
+      const hostname = new URL(origin).hostname
+      return remote.trustedHosts.includes(hostname)
+    } catch {
+      return false
+    }
+  }, [origin, remote.trustedHosts])
+
+  const active = enabled && !trusted
+
+  const ref = useRef<HTMLDivElement>(null)
+  const [visible, setVisible] = react_useState(true)
+
+  useEffect(() => {
+    if (!active) return
+    if (!ref.current) return
+
+    if (!IO.supported()) {
+      setVisible(false)
+      return
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0]
+        if (!entry) return
+        const isVisible =
+          (entry as unknown as { isVisible: boolean | undefined }).isVisible || false
+        setVisible(isVisible)
+      },
+      {
+        delay: 100,
+        threshold: [0.99],
+        trackVisibility: true,
+      } as IntersectionObserverInit,
+    )
+
+    observer.observe(ref.current)
+    return () => observer.disconnect()
+  }, [active])
+
+  const invokePopup = useCallback(
+    () => remote.messenger.send('switch-mode', { mode: 'popup' }),
+    [remote],
+  )
+
+  return { invokePopup, ref, visible }
+}
+
+/** React hook to select state from a remote context's store. */
+export function useState(remote: CoreRemote.Remote): CoreRemote.State
+export function useState<selected>(
+  remote: CoreRemote.Remote,
+  selector: (state: CoreRemote.State) => selected,
+): selected
+export function useState(
+  remote: CoreRemote.Remote,
+  selector?: (state: CoreRemote.State) => unknown,
+) {
+  return useStore(remote.store, selector as never)
+}
+
+export declare namespace useEnsureVisibility {
+  type Options = {
+    /** Whether visibility monitoring is enabled. @default true */
+    enabled?: boolean | undefined
+  }
+
+  type ReturnType = {
+    /** Requests the host switch to a popup dialog. */
+    invokePopup: () => void
+    /** Ref to attach to the element being monitored. */
+    ref: React.RefObject<HTMLDivElement | null>
+    /** Whether the element is currently visible. */
+    visible: boolean
+  }
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export * as Remote from './Remote.js'

package/src/server/CliAuth.test-d.ts

@@ -0,0 +1,56 @@
+import type { Hex } from 'viem'
+import { describe, expectTypeOf, test } from 'vp/test'
+import * as z from 'zod/mini'
+
+import * as CliAuth from './CliAuth.js'
+
+describe('createRequest', () => {
+  test('includes the v1 device-code request fields', () => {
+    expectTypeOf<z.output<typeof CliAuth.createRequest>>().toMatchTypeOf<{
+      account?: Hex | undefined
+      codeChallenge: string
+      expiry?: number | undefined
+      keyType?: 'secp256k1' | 'p256' | 'webAuthn' | undefined
+      limits?: readonly { token: Hex; limit: bigint }[] | undefined
+      pubKey: Hex
+    }>()
+  })
+
+  test('does not include scopes in v1', () => {
+    type Request = z.output<typeof CliAuth.createRequest>
+    expectTypeOf<Request>().not.toHaveProperty('scopes')
+  })
+})
+
+describe('pollResponse', () => {
+  test('authorized responses carry the normal keyAuthorization shape', () => {
+    type Response = Extract<z.output<typeof CliAuth.pollResponse>, { status: 'authorized' }>
+    expectTypeOf<Response>().toMatchTypeOf<{
+      accountAddress: Hex
+      keyAuthorization: z.output<typeof CliAuth.keyAuthorization>
+      status: 'authorized'
+    }>()
+  })
+})
+
+describe('pendingResponse', () => {
+  test('pending responses expose the browser approval payload', () => {
+    expectTypeOf<z.output<typeof CliAuth.pendingResponse>>().toMatchTypeOf<{
+      accessKeyAddress: Hex
+      account?: Hex | undefined
+      chainId: bigint
+      code: string
+      expiry: number
+      keyType: 'secp256k1' | 'p256' | 'webAuthn'
+      limits?: readonly { token: Hex; limit: bigint }[] | undefined
+      pubKey: Hex
+      status: 'pending'
+    }>()
+  })
+})
+
+describe('Store', () => {
+  test('memory helper satisfies the shared store contract', () => {
+    expectTypeOf(CliAuth.Store.memory).returns.toMatchTypeOf<CliAuth.Store>()
+  })
+})