accounts 0.16.2 → 0.17.0

package/src/server/CliAuth.test.ts

@@ -1,4 +1,4 @@
-import { Base64 } from 'ox'
+import { Base64, Hex } from 'ox'
 import { KeyAuthorization } from 'ox/tempo'
 import { createClient, custom, encodeErrorResult, encodeFunctionResult } from 'viem'
 import { Abis, Account as TempoAccount } from 'viem/tempo'
@@ -23,6 +23,22 @@ const limits = [
   },
 ] as const
 
+describe('keyAuthorization', () => {
+  test('behavior: preserves spending limit periods', () => {
+    const authorization = z.decode(CliAuth.keyAuthorization, {
+      address: accessKey.address,
+      chainId: '0xa5bf',
+      expiry: Hex.fromNumber(expiry),
+      keyId: accessKey.address,
+      keyType: accessKey.keyType,
+      limits: [{ limit: '0x3e8', period: Hex.fromNumber(86_400), token }],
+      signature: { r: '0x1', s: '0x2', type: 'secp256k1', yParity: '0x0' },
+    })
+
+    expect(authorization.limits).toEqual([{ limit, period: 86_400, token }])
+  })
+})
+
 function createMissingAccessKeyClient() {
   return createClient({
     chain,
@@ -744,23 +760,18 @@ Received 2 bytes.]`)
       limits: Array.from({ length: 11 }, () => item),
     })
 
-    expect(result).toMatchInlineSnapshot(`
-    	{
-    	  "error": [$ZodError: [
-    	  {
-    	    "origin": "array",
-    	    "code": "too_big",
-    	    "maximum": 10,
-    	    "inclusive": true,
-    	    "path": [
-    	      "limits"
-    	    ],
-    	    "message": "Invalid input"
-    	  }
-    	]],
-    	  "success": false,
-    	}
-    `)
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.issues).toEqual([
+      {
+        code: 'too_big',
+        inclusive: true,
+        maximum: 10,
+        message: 'Invalid input',
+        origin: 'array',
+        path: ['limits'],
+      },
+    ])
   })
 
   test('behavior: rejects malformed limit tokens', async () => {

package/src/server/CliAuth.ts

@@ -12,7 +12,11 @@ import type { MaybePromise } from '../internal/types.js'
 import type { Kv } from './Kv.js'
 
 const maxLimits = 10
-const limit = z.object({ token: u.address(), limit: u.bigint() })
+const limit = z.object({
+  token: u.address(),
+  limit: u.bigint(),
+  period: z.optional(u.number()),
+})
 const limits = z.readonly(z.array(limit).check(z.maxLength(maxLimits)))
 const showDeposit = z.optional(
   z.union([
@@ -249,7 +253,10 @@ export const entry = u.oneOf([
   }),
 ])
 
-/** Shared CLI auth helper with pre-bound defaults and cached clients. */
+/**
+ * Shared CLI auth helper with pre-bound defaults and cached clients.
+ * @deprecated Use `Handler.deviceCode` with the Wata device-code transport.
+ */
 export type CliAuth = {
   /** Creates and stores a new device code. */
   createDeviceCode: (options: createDeviceCode.Parameters) => Promise<createDeviceCode.ReturnType>
@@ -622,6 +629,7 @@ export const RateLimit = {
  * Instantiates a CLI auth helper with shared defaults and cached clients.
  *
  *
+ * @deprecated Use `Handler.deviceCode` with the Wata device-code transport.
  * @param {from.Options} options - Shared CLI auth defaults.
  * @returns {CliAuth} CLI auth helper.
  *

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

@@ -1,42 +1,28 @@
 import { hc } from 'hono/client'
 import type { ExtractSchema } from 'hono/types'
-import { http, type Chain, type Transport } from 'viem'
-import { tempo, tempoModerato } from 'viem/tempo/chains'
 import { describe, expectTypeOf, test } from 'vp/test'
+import { Store } from 'wata/host'
 
-import * as CliAuth from './CliAuth.js'
 import * as Handler from './Handler.js'
 
-describe('codeAuth options', () => {
-  test('supports chain-agnostic chains/transports configuration', () => {
-    expectTypeOf<Handler.codeAuth.Options>().toMatchTypeOf<{
-      chains?: readonly [Chain, ...Chain[]] | undefined
-      transports?: Record<number, Transport> | undefined
-    }>()
-  })
-
-  test('accepts derived clients from chains/transports', () => {
-    void Handler.codeAuth({
-      chains: [tempo, tempoModerato],
-      transports: {
-        [tempo.id]: http('https://rpc.tempo.xyz'),
-        [tempoModerato.id]: http('https://rpc.moderato.tempo.xyz'),
+describe('deviceCode', () => {
+  test('accepts host deployment options', () => {
+    const handler = Handler.deviceCode({
+      baseUrl: (request) => new URL(request.url).origin,
+      html: {
+        render: () => new Response('verify'),
       },
-    })
-  })
-
-  test('accepts a shared rate limiter', () => {
-    void Handler.codeAuth({
-      rateLimit: CliAuth.RateLimit.memory({ max: 120, windowMs: 60_000 }),
-    })
-    void Handler.codeAuth({
-      rateLimit: false,
-    })
-    void Handler.codeAuth({
-      rateLimitKey(request) {
-        return request.headers.get('x-forwarded-for') ?? 'unknown'
+      store: Store.memory(),
+      validate(options) {
+        expectTypeOf(options.record).toEqualTypeOf<import('wata/host').DeviceCode.PendingRecord>()
+        expectTypeOf(options.request.id).toEqualTypeOf<string | number>()
+        expectTypeOf(options.result).toBeUnknown()
+        expectTypeOf(options.userCode).toBeString()
+        return undefined
       },
     })
+
+    expectTypeOf(handler).toMatchTypeOf<Handler.Handler>()
   })
 })
 
@@ -125,11 +111,11 @@ describe('compose', () => {
   })
 
   test('handlers without a route schema (legacy `Handler`) compose without errors', () => {
-    // `Handler.codeAuth` returns plain `Handler` (default `Hono`), no route
+    // `Handler.from` returns plain `Handler` (default `Hono`), no route
     // schema. Mixing it with typed handlers must not break inference for the
     // typed siblings.
-    const codeAuth = Handler.codeAuth() as unknown as Handler.Handler
-    const composed = Handler.compose([codeAuth, makeAlpha()], { path: '/api' })
+    const plain = Handler.from() as unknown as Handler.Handler
+    const composed = Handler.compose([plain, makeAlpha()], { path: '/api' })
     const client = hc<typeof composed>('http://localhost')
 
     expectTypeOf(client.api.alpha.ping.$post).toBeFunction()

package/src/server/Handler.ts

@@ -7,6 +7,7 @@ import * as RequestListener from './internal/requestListener.js'
 export { auth } from './internal/handlers/auth.js'
 export { type SessionRequest } from './internal/handlers/session.js'
 export { codeAuth } from './internal/handlers/codeAuth.js'
+export { deviceCode } from './internal/handlers/deviceCode.js'
 export { exchange } from './internal/handlers/exchange.js'
 export { oidcProvider } from './internal/handlers/oidcProvider.js'
 export { relay } from './internal/handlers/relay.js'
@@ -51,7 +52,7 @@ export type ComposedSchema<subs extends readonly unknown[], path extends string>
  * import { hc } from 'hono/client'
  *
  * const app = Handler.compose(
- *   [Handler.exchange(), Handler.codeAuth({ store })],
+ *   [Handler.exchange(), Handler.relay()],
  *   { path: '/api' },
  * )
  * type App = typeof app

package/src/server/index.ts

@@ -1,5 +1,6 @@
 export { hc } from 'hono/client'
 
+/** @deprecated Use `Handler.deviceCode` with the Wata device-code transport. */
 export * as CliAuth from './CliAuth.js'
 export * as Handler from './Handler.js'
 export * as Identity from './Identity.js'

package/src/server/internal/handlers/codeAuth.ts

@@ -15,6 +15,7 @@ import { type Handler, from } from '../../Handler.js'
  * - `POST /auth/pkce/poll/:code`
  * - `POST /auth/pkce`
  *
+ * @deprecated Use `Handler.deviceCode` with the Wata device-code transport.
  * @param {codeAuth.Options} options - Options.
  * @returns {Handler} Request handler.
  */

package/src/server/internal/handlers/deviceCode.test.ts

@@ -0,0 +1,140 @@
+import { Base64, Bytes, Hash } from 'ox'
+import { describe, expect, test, vi } from 'vp/test'
+
+import { deviceCode } from './deviceCode.js'
+
+const verifier = 'test-device-code-verifier-0123456789'
+
+function createHandler(validate = vi.fn(() => undefined)) {
+  return {
+    handler: deviceCode({
+      html: { render: () => new Response('verify') },
+      pollingInterval: 1,
+      validate,
+    }),
+    validate,
+  }
+}
+
+async function register(handler: ReturnType<typeof deviceCode>) {
+  const response = await handler.fetch(
+    new Request('https://wallet.example.com/auth/device/register', {
+      body: JSON.stringify({
+        code_challenge: Base64.fromBytes(Hash.sha256(Bytes.fromString(verifier), { as: 'Bytes' }), {
+          pad: false,
+          url: true,
+        }),
+        code_challenge_method: 'S256',
+        message: {
+          payload: [{ id: 1, jsonrpc: '2.0', method: 'wallet_connect', params: [] }],
+          type: 'rpc-requests',
+        },
+        meta: { name: 'Test CLI' },
+      }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    }),
+  )
+  return (await response.json()) as { device_code: string; user_code: string }
+}
+
+async function verify(
+  handler: ReturnType<typeof deviceCode>,
+  userCode: string,
+  response:
+    | { error: { code: number; data?: unknown; message: string }; id: number }
+    | {
+        id: number
+        result: unknown
+      },
+) {
+  return await handler.fetch(
+    new Request('https://wallet.example.com/auth/device/verify', {
+      body: JSON.stringify({ action: 'approve', results: [response], user_code: userCode }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    }),
+  )
+}
+
+async function token(handler: ReturnType<typeof deviceCode>, code: string) {
+  const response = await handler.fetch(
+    new Request('https://wallet.example.com/auth/device/token', {
+      body: JSON.stringify({
+        code_verifier: verifier,
+        device_code: code,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    }),
+  )
+  return { body: await response.json(), status: response.status }
+}
+
+describe('deviceCode', () => {
+  test('default: validates approved results before relaying them', async () => {
+    const { handler, validate } = createHandler()
+    const registered = await register(handler)
+
+    const approved = await verify(handler, registered.user_code, { id: 1, result: '0x1' })
+
+    expect(approved.status).toMatchInlineSnapshot(`200`)
+    expect(validate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        request: expect.objectContaining({ id: 1, method: 'wallet_connect' }),
+        result: '0x1',
+        userCode: registered.user_code,
+      }),
+    )
+    await expect(token(handler, registered.device_code)).resolves.toMatchInlineSnapshot(`
+      {
+        "body": {
+          "payload": [
+            {
+              "id": 1,
+              "jsonrpc": "2.0",
+              "result": "0x1",
+            },
+          ],
+          "type": "rpc-responses",
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('behavior: relays submitted RPC errors', async () => {
+    const { handler, validate } = createHandler()
+    const registered = await register(handler)
+
+    const approved = await verify(handler, registered.user_code, {
+      error: { code: 4001, data: { reason: 'cancelled' }, message: 'Request rejected.' },
+      id: 1,
+    })
+
+    expect(approved.status).toMatchInlineSnapshot(`200`)
+    expect(validate).not.toHaveBeenCalled()
+    await expect(token(handler, registered.device_code)).resolves.toMatchInlineSnapshot(`
+      {
+        "body": {
+          "payload": [
+            {
+              "error": {
+                "code": 4001,
+                "data": {
+                  "reason": "cancelled",
+                },
+                "message": "Request rejected.",
+              },
+              "id": 1,
+              "jsonrpc": "2.0",
+            },
+          ],
+          "type": "rpc-responses",
+        },
+        "status": 200,
+      }
+    `)
+  })
+})

package/src/server/internal/handlers/deviceCode.ts

@@ -0,0 +1,323 @@
+import { type DeviceCode, Store, Wata, deviceCode as core_deviceCode } from 'wata/host'
+import * as z from 'zod/mini'
+
+import { type Handler, from } from '../../Handler.js'
+
+const maxVerifyBodyBytes = 65_536
+
+const verifyRequest = z.object({
+  action: z.union([z.literal('approve'), z.literal('deny')]),
+  results: z.optional(
+    z.array(
+      z.union([
+        z.object({
+          error: z.object({
+            code: z.number(),
+            data: z.optional(z.json()),
+            message: z.string(),
+          }),
+          id: z.union([z.string(), z.number()]),
+        }),
+        z.object({ id: z.union([z.string(), z.number()]), result: z.json() }),
+      ]),
+    ),
+  ),
+  user_code: z.string(),
+})
+
+type PendingRequest = {
+  context?: { account?: string | undefined; chainId?: number | undefined } | undefined
+  id: string | number
+  method: string
+  params?: unknown
+}
+
+/**
+ * Instantiates a Wata device-code handler for wallet RPC requests.
+ *
+ * The handler implements the OAuth 2.0 Device Authorization Grant endpoints,
+ * accepts browser-submitted RPC results, and returns them to the polling
+ * consumer. The consuming host is responsible for deciding which methods
+ * its approval UI supports.
+ *
+ * @param options - Options.
+ * @returns Request handler.
+ */
+export function deviceCode(options: deviceCode.Options): Handler {
+  const {
+    baseUrl,
+    expiresIn,
+    fetch,
+    html,
+    maxBodyBytes = maxVerifyBodyBytes,
+    path = '/auth/device',
+    pollingInterval,
+    store = Store.memory(),
+    validate,
+    ...rest
+  } = options
+
+  const router = from(rest)
+  router.all(`${path}/*`, async (c) => {
+    const request = c.req.raw
+    const origin = typeof baseUrl === 'function' ? baseUrl(request) : baseUrl
+    const results = new Map<
+      string | number,
+      { result: unknown } | { error: { code: number; data?: unknown; message: string } }
+    >()
+    let settle: ((error?: Error) => void) | undefined
+    const responded = new Promise<void>((resolve, reject) => {
+      settle = (error) => (error ? reject(error) : resolve())
+    })
+
+    const wata = Wata.create({
+      transports: [
+        core_deviceCode({
+          ...(origin ? { baseUrl: origin } : {}),
+          ...(expiresIn !== undefined ? { expiresIn } : {}),
+          ...(fetch !== undefined ? { fetch } : {}),
+          html: {
+            async authenticate({ actions, request }) {
+              const body = await readVerifyBody(request, maxBodyBytes)
+              if (!body.ok) return body.response
+              const { action, results: submitted, user_code } = body.value
+
+              const userCode = normalizeUserCode(user_code)
+              const record = await actions.get(userCode)
+              if (!record)
+                return Response.json(
+                  { error: 'unknown_code', error_description: 'Unknown or expired device code.' },
+                  { status: 404 },
+                )
+              if (record.status !== 'pending')
+                return Response.json(
+                  { error: 'not_pending', error_description: 'Device code already completed.' },
+                  { status: 409 },
+                )
+
+              if (action === 'deny') {
+                await actions.deny(userCode)
+                return Response.json({ status: 'denied' })
+              }
+
+              const requests = pendingRequests(record)
+              const [pending] = requests
+              if (requests.length !== 1 || !pending)
+                return Response.json(
+                  {
+                    error: 'invalid_request',
+                    error_description: 'Expected one pending request.',
+                  },
+                  { status: 400 },
+                )
+
+              const response = submitted?.find((entry) => entry.id === pending.id)
+              if (!response)
+                return Response.json(
+                  {
+                    error: 'invalid_request',
+                    error_description: 'Missing response for pending request.',
+                  },
+                  { status: 400 },
+                )
+
+              if ('result' in response) {
+                const validation = await validate({
+                  record,
+                  request: pending,
+                  result: response.result,
+                  userCode,
+                })
+                if (validation) return validation
+              }
+
+              results.set(pending.id, response)
+              await actions.approve(userCode)
+              await responded
+              return Response.json({ status: 'approved' })
+            },
+            render: html.render,
+          },
+          path,
+          ...(pollingInterval !== undefined ? { pollingInterval } : {}),
+          store: normalizeStore(store),
+        }),
+      ],
+    })
+
+    const session = wata.start()
+    session.onRequest(async (event) => {
+      const response = results.get(event.id)
+      try {
+        if (!response)
+          await event.reject({ code: -32603, message: 'No result supplied for request.' })
+        else if ('error' in response) await event.reject(response.error)
+        else await event.respond(response.result)
+        settle?.()
+      } catch (error) {
+        settle?.(error as Error)
+      }
+    })
+
+    return await normalizeRegisterResponse(await wata.fetch(request), request, path)
+  })
+
+  return router
+}
+
+export declare namespace deviceCode {
+  /** Options for {@link deviceCode}. */
+  export type Options = from.Options & {
+    /** Public host origin or a request-based origin resolver. */
+    baseUrl?: string | ((request: Request) => string) | undefined
+    /** Authorization intent lifetime in seconds. @default 600 */
+    expiresIn?: number | undefined
+    /** Discovery fetch implementation. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Approval page hooks. */
+    html: {
+      /** Renders or redirects the approval page. */
+      render: DeviceCode.html.Hooks['render']
+    }
+    /** Maximum approval request body size in bytes. @default 65536 */
+    maxBodyBytes?: number | undefined
+    /** Device-code endpoint path. @default "/auth/device" */
+    path?: string | undefined
+    /** Suggested polling interval in milliseconds. */
+    pollingInterval?: number | undefined
+    /** Device-code persistence. @default in-memory */
+    store?: Store.Store | undefined
+    /** Host policy applied before an approved result is relayed to the consumer. */
+    validate: (options: {
+      /** Pending device-code record. */
+      record: DeviceCode.PendingRecord
+      /** Pending JSON-RPC request matched to the submitted result. */
+      request: PendingRequest
+      /** Browser-submitted result. */
+      result: unknown
+      /** Normalized raw user code. */
+      userCode: string
+    }) => Promise<Response | undefined> | Response | undefined
+  }
+}
+
+function pendingRequests(record: DeviceCode.PendingRecord): PendingRequest[] {
+  if (record.message.type !== 'rpc-requests') return []
+  return record.message.payload.filter(
+    (message) => typeof message === 'object' && message !== null && 'id' in message,
+  ) as unknown as PendingRequest[]
+}
+
+function normalizeUserCode(value: string): string {
+  return value.replace(/[\s-]/g, '').toUpperCase()
+}
+
+function normalizeStore(store: Store.Store): Store.Store {
+  function key(value: string) {
+    if (!value.startsWith('user:')) return value
+    return `user:${normalizeUserCode(value.slice('user:'.length))}`
+  }
+
+  return Store.from({
+    delete: (value) => store.delete(key(value)),
+    get: <value = unknown>(name: string) => store.get<value>(key(name)),
+    set: (name, value, options) => store.set(key(name), value, options),
+    ...(store.take
+      ? { take: <value = unknown>(name: string) => store.take!<value>(key(name)) }
+      : {}),
+  })
+}
+
+async function normalizeRegisterResponse(response: Response, request: Request, path: string) {
+  if (!response.ok || new URL(request.url).pathname !== `${path}/register`) return response
+
+  const body = (await response.clone().json()) as {
+    user_code?: unknown
+    verification_uri_complete?: unknown
+  }
+  if (typeof body.user_code !== 'string') return response
+
+  const userCode = normalizeUserCode(body.user_code)
+  const verificationUriComplete =
+    typeof body.verification_uri_complete === 'string'
+      ? (() => {
+          const url = new URL(body.verification_uri_complete)
+          url.searchParams.set('user_code', userCode)
+          return url.toString()
+        })()
+      : body.verification_uri_complete
+  const headers = new Headers(response.headers)
+  headers.delete('content-length')
+  return Response.json(
+    {
+      ...body,
+      user_code: userCode,
+      ...(verificationUriComplete ? { verification_uri_complete: verificationUriComplete } : {}),
+    },
+    { headers, status: response.status },
+  )
+}
+
+async function readVerifyBody(
+  request: Request,
+  maxBodyBytes: number,
+): Promise<
+  { ok: true; value: z.output<typeof verifyRequest> } | { ok: false; response: Response }
+> {
+  const invalid = (description: string) => ({
+    ok: false as const,
+    response: Response.json(
+      { error: 'invalid_request', error_description: description },
+      { status: 400 },
+    ),
+  })
+
+  let json: unknown
+  try {
+    const body = await readBody(request, maxBodyBytes)
+    if (!body.ok) return invalid('Request body is too large.')
+    json = JSON.parse(body.text)
+  } catch {
+    return invalid('Expected a JSON body.')
+  }
+
+  const parsed = z.safeParse(verifyRequest, json)
+  if (!parsed.success) return invalid('Malformed verify request.')
+  return { ok: true, value: parsed.data }
+}
+
+async function readBody(
+  request: Request,
+  maxBodyBytes: number,
+): Promise<{ ok: true; text: string } | { ok: false }> {
+  const length = request.headers.get('content-length')
+  if (length && Number(length) > maxBodyBytes) return { ok: false }
+  if (!request.body) return { ok: true, text: '' }
+
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > maxBodyBytes) {
+        await reader.cancel().catch(() => undefined)
+        return { ok: false }
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return { ok: true, text: new TextDecoder().decode(bytes) }
+}