accounts 0.12.2 → 0.13.0

package/src/server/Kv.test.ts

@@ -47,6 +47,36 @@ describe('memory', () => {
     expect(await kv.get('a')).toMatchInlineSnapshot(`"v2"`)
   })
 
+  test('create: writes only when key is absent', async () => {
+    const kv = Kv.memory()
+
+    expect(await kv.create!('a', 'v1')).toMatchInlineSnapshot(`true`)
+    expect(await kv.create!('a', 'v2')).toMatchInlineSnapshot(`false`)
+    expect(await kv.get('a')).toMatchInlineSnapshot(`"v1"`)
+  })
+
+  test('create: replaces expired entries', async () => {
+    let now = 1_000_000
+    const kv = Kv.memory({ now: () => now })
+
+    await kv.set('a', 'v1', { ttl: 1 })
+    now += 2_000
+    expect(await kv.create!('a', 'v2')).toMatchInlineSnapshot(`true`)
+    expect(await kv.get('a')).toMatchInlineSnapshot(`"v2"`)
+  })
+
+  test('create: concurrent callers — only one writes', async () => {
+    const kv = Kv.memory()
+
+    const results = await Promise.all([kv.create!('a', 'v1'), kv.create!('a', 'v2')])
+    expect(results.filter(Boolean)).toMatchInlineSnapshot(`
+      [
+        true,
+      ]
+    `)
+    expect(await kv.get('a')).toMatchInlineSnapshot(`"v1"`)
+  })
+
   test('take: returns the value and removes the entry', async () => {
     const kv = Kv.memory()
 
@@ -163,6 +193,18 @@ describe('durableObject + NonceStorage', () => {
     `)
   })
 
+  test('create: concurrent callers — only one wins', async () => {
+    const kv = Kv.durableObject(fakeDurableObject())
+
+    const results = await Promise.all([kv.create!('a', 'v1'), kv.create!('a', 'v2')])
+    expect(results.filter(Boolean)).toMatchInlineSnapshot(`
+      [
+        true,
+      ]
+    `)
+    expect(await kv.get('a')).toMatchInlineSnapshot(`"v1"`)
+  })
+
   test('take: missing key returns undefined', async () => {
     const kv = Kv.durableObject(fakeDurableObject())
     expect(await kv.take!('missing')).toMatchInlineSnapshot(`undefined`)
@@ -226,6 +268,15 @@ describe('cloudflare', () => {
     expect(kv.take).toBeUndefined()
   })
 
+  test('create: NOT implemented (CF KV is not linearizable)', () => {
+    const kv = Kv.cloudflare({
+      get: async () => null,
+      put: async () => {},
+      delete: async () => {},
+    })
+    expect(kv.create).toBeUndefined()
+  })
+
   test('ttl: passes expirationTtl seconds to underlying put', async () => {
     const puts: { key: string; value: string; options: unknown }[] = []
     const fakeKv = {

package/src/server/Kv.ts

@@ -16,6 +16,16 @@ export type Kv = {
   set: (key: string, value: unknown, options?: set.Options | undefined) => Promise<void>
   /** Delete a value by key. */
   delete: (key: string) => Promise<void>
+  /**
+   * Atomic create-if-absent. Returns `true` when the value was written,
+   * `false` when a non-expired value already exists.
+   *
+   * Optional. Backends with a linearizable create primitive should
+   * implement this so consumers can atomically reject duplicates.
+   * Consumers may fall back to `get` then `set` when strict atomicity is
+   * not required.
+   */
+  create?: (key: string, value: unknown, options?: set.Options | undefined) => Promise<boolean>
   /**
    * Atomic read-and-delete. Returns the value if present, `undefined` if
    * missing or expired. Across concurrent callers, exactly one observer
@@ -51,11 +61,10 @@ export function from<kv extends Kv>(kv: kv): kv {
  * Cloudflare KV's minimum TTL is 60 seconds; the platform enforces its own
  * minimum independent of what's passed here.
  *
- * **Not safe for one-time-consume semantics.** Cloudflare KV is eventually
- * consistent across data centers — concurrent read+delete races can let
- * the same key be "consumed" twice. `take` is intentionally NOT
- * implemented. Use a Durable Object (or another linearizable backend)
- * for the SIWE challenge nonce store.
+ * **Not safe for one-time-consume or unique-key semantics.**
+ * Cloudflare KV is eventually consistent across data centers, so `take`
+ * and `create` are intentionally NOT implemented. Use a Durable Object
+ * (or another linearizable backend) for the SIWE challenge nonce store.
  */
 export function cloudflare(kv: cloudflare.Parameters): Kv {
   return from({
@@ -84,10 +93,11 @@ export declare namespace cloudflare {
 
 /**
  * Adapt a Cloudflare Durable Object namespace into a `Kv` with atomic
- * `take`. Unlike `Kv.cloudflare`, a Durable Object's storage is
- * single-actor and linearizable — `take` (read+delete) is guaranteed
- * atomic across concurrent callers, which makes this the recommended
- * backend for SIWE challenge nonce storage on Cloudflare Workers.
+ * `take` and `create`. Unlike `Kv.cloudflare`, a Durable Object's
+ * storage is single-actor and linearizable, so `take` (read+delete) and
+ * `create` (create-if-absent) are guaranteed atomic across concurrent
+ * callers. This makes it the recommended backend for SIWE challenge
+ * nonce storage on Cloudflare Workers.
  *
  * Pair with `Kv.NonceStorage` (or your own DO class implementing the
  * same fetch protocol).
@@ -147,6 +157,12 @@ export function durableObject(
     async set(key, value, options) {
       await rpc('set', key, { value, ttl: options?.ttl })
     },
+    async create(key, value, options) {
+      const { created } = (await rpc('create', key, { value, ttl: options?.ttl })) as {
+        created: boolean
+      }
+      return created
+    },
     async delete(key) {
       await rpc('delete', key)
     },
@@ -228,6 +244,17 @@ export class NonceStorage {
       await this.state.storage.put(key, entry)
       return Response.json({})
     }
+    if (op === 'create') {
+      const current = await this.state.storage.get<NonceStorage.Entry>(key)
+      if (current && !isExpired(current)) return Response.json({ created: false })
+
+      const body = (await request.json()) as { value: unknown; ttl?: number }
+      const entry: NonceStorage.Entry = body.ttl
+        ? { value: body.value, expiresAt: Date.now() + body.ttl * 1000 }
+        : { value: body.value }
+      await this.state.storage.put(key, entry)
+      return Response.json({ created: true })
+    }
     if (op === 'delete') {
       await this.state.storage.delete(key)
       return Response.json({})
@@ -280,6 +307,13 @@ export function memory(options: memory.Options = {}): Kv {
       const expiresAt = options?.ttl ? now() + options.ttl * 1000 : undefined
       store.set(key, expiresAt !== undefined ? { value, expiresAt } : { value })
     },
+    async create(key, value, options) {
+      const entry = store.get(key)
+      if (entry && !isExpired(entry)) return false
+      const expiresAt = options?.ttl ? now() + options.ttl * 1000 : undefined
+      store.set(key, expiresAt !== undefined ? { value, expiresAt } : { value })
+      return true
+    },
     // Atomic in-process: the synchronous `Map.get` + `Map.delete` runs
     // in a single microtask, so concurrent `take(key)` callers (within
     // the same Node/Bun/Worker process) cannot both observe the value.

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

@@ -15,6 +15,12 @@ const otherAccount = privateKeyToAccount(
 )
 
 describe('challenge', () => {
+  test('error: requires pinned origin or domain', () => {
+    expect(() => auth()).toThrowErrorMatchingInlineSnapshot(
+      `[Error: \`auth()\` requires \`origin\` or \`domain\` to pin SIWE domain binding.]`,
+    )
+  })
+
   test('returns challenge message with chainId, nonce, zero-address placeholder', async () => {
     const { app } = setup()
 
@@ -689,7 +695,7 @@ describe('getSession', () => {
 
 describe('store: atomic `take` preferred, non-atomic fallback', () => {
   test('Kv.memory() (has `take`) is accepted', () => {
-    expect(() => auth({ store: Kv.memory() })).not.toThrow()
+    expect(() => auth({ domain: 'wallet.example', store: Kv.memory() })).not.toThrow()
   })
 
   test('store without `take` falls back to non-atomic get + delete', async () => {
@@ -726,8 +732,7 @@ describe('store: atomic `take` preferred, non-atomic fallback', () => {
 
 describe('origin / trustProxy', () => {
   test('default: ignores `x-forwarded-host` and `x-forwarded-proto`', async () => {
-    // No domain pin — relies on host header. trustProxy defaults to false.
-    const handler = auth()
+    const handler = auth({ domain: 'real.example' })
     const app = new Hono()
     app.route('/', handler)
 
@@ -747,7 +752,7 @@ describe('origin / trustProxy', () => {
   })
 
   test('trustProxy: true → honors `x-forwarded-host` and `x-forwarded-proto`', async () => {
-    const handler = auth({ trustProxy: true })
+    const handler = auth({ domain: 'app.example', trustProxy: true })
     const app = new Hono()
     app.route('/', handler)
 
@@ -805,7 +810,7 @@ describe('origin / trustProxy', () => {
       configurable: true,
     })
     try {
-      const handler = auth()
+      const handler = auth({ domain: 'app.example' })
       const app = new Hono()
       app.route('/', handler)
 

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

@@ -138,6 +138,9 @@ export function auth(options: auth.Options = {}): auth.ReturnType {
     ...rest
   } = options
 
+  if (!origin_option && !domain)
+    throw new Error('`auth()` requires `origin` or `domain` to pin SIWE domain binding.')
+
   async function take(key: string): Promise<ChallengePayload | undefined> {
     if (store.take) return store.take<ChallengePayload>(key)
     const value = await store.get<ChallengePayload>(key)

package/src/server/internal/handlers/{relay.test.ts → relay.localnet.test.ts}

@@ -414,6 +414,7 @@ describe('behavior: with app-provided feePayer URL', () => {
     walletServer = await createServer(
       relay({
         chains: [chain],
+        internal_allowUnsafeUrls: true,
         transports: { [chain.id]: http() },
       }).listener,
     )
@@ -504,6 +505,7 @@ describe('behavior: with app-provided feePayer URL + autoSwap', () => {
       relay({
         chains: [chain],
         features: 'all',
+        internal_allowUnsafeUrls: true,
         transports: { [chain.id]: http() },
       }).listener,
     )
@@ -625,6 +627,7 @@ describe('behavior: app-provided feePayer URL bypasses wallet validate', () => {
       relay({
         chains: [chain],
         features: 'all',
+        internal_allowUnsafeUrls: true,
         transports: { [chain.id]: http() },
         feePayer: {
           account: feePayerAccount,

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

@@ -74,6 +74,7 @@ export function relay(options: relay.Options = {}): Handler {
   const {
     cacheTtl = defaultCacheTtl,
     chains = [tempo, tempoModerato, tempoDevnet],
+    internal_allowUnsafeUrls = false,
     kv = Kv.memory(),
     onRequest,
     path = '/',
@@ -150,7 +151,11 @@ export function relay(options: relay.Options = {}): Handler {
           const requestFeeToken =
             typeof parameters.feeToken === 'string' ? (parameters.feeToken as Address) : undefined
           const externalFeePayerUrl =
-            typeof parameters.feePayer === 'string' ? parameters.feePayer : undefined
+            typeof parameters.feePayer === 'string'
+              ? normalizeExternalFeePayerUrl(parameters.feePayer, {
+                  allowUnsafe: internal_allowUnsafeUrls,
+                })
+              : undefined
           const requestsSponsorship =
             (!!feePayerOptions || !!externalFeePayerUrl) && parameters.feePayer !== false
           // Default to `true`. Dapps that don't render diffs can pass
@@ -639,6 +644,20 @@ export namespace relay {
           url?: string | undefined
         }
       | undefined
+    /**
+     * Relay features.
+     *
+     * - `'all'` — enables fee token resolution, auto-swap,
+     *   fee payer, and simulation (balance diffs + fee breakdown).
+     * - `undefined` (default) — only fee payers.
+     */
+    features?: 'all' | undefined
+    /**
+     * Allows app-provided external fee payer URLs to use non-HTTPS protocols
+     * or local/private hosts. Intended only for trusted development setups.
+     * @default false
+     */
+    internal_allowUnsafeUrls?: boolean | undefined
     /**
      * Kv store used to cache `resolveTokens` results across requests.
      * Provide `Kv.cloudflare(env.KV)` for cross-instance caching, or omit
@@ -646,6 +665,10 @@ export namespace relay {
      * @default Kv.memory()
      */
     kv?: Kv.Kv | undefined
+    /** Function to call before handling the request. */
+    onRequest?: ((request: RpcRequest.RpcRequest) => Promise<void>) | undefined
+    /** Path to use for the handler. @default "/" */
+    path?: string | undefined
     /**
      * Resolves the list of known tokens for a chain. The relay checks
      * `balanceOf` for each token and picks the one with the highest balance
@@ -655,18 +678,6 @@ export namespace relay {
     resolveTokens?:
       | ((chainId: number) => readonly Tokenlist.Token[] | Promise<readonly Tokenlist.Token[]>)
       | undefined
-    /**
-     * Relay features.
-     *
-     * - `'all'` — enables fee token resolution, auto-swap,
-     *   fee payer, and simulation (balance diffs + fee breakdown).
-     * - `undefined` (default) — only fee payers.
-     */
-    features?: 'all' | undefined
-    /** Function to call before handling the request. */
-    onRequest?: ((request: RpcRequest.RpcRequest) => Promise<void>) | undefined
-    /** Path to use for the handler. @default "/" */
-    path?: string | undefined
     /** Transports keyed by chain ID. Defaults to `http()` for each chain. */
     transports?: Record<number, Transport> | undefined
   }
@@ -1406,6 +1417,120 @@ function mergeCallsFromRequest(
   return merged
 }
 
+/** Normalizes external fee-payer relay URLs before forwarding fill payloads. */
+function normalizeExternalFeePayerUrl(
+  value: string,
+  options: normalizeExternalFeePayerUrl.Options = {},
+): string {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL.' })
+  }
+
+  const allowUnsafe = options.allowUnsafe === true
+  if (url.protocol !== 'http:' && url.protocol !== 'https:')
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+  if (!allowUnsafe && url.protocol !== 'https:')
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+  if (!allowUnsafe && isUnsafeHostname(url.hostname))
+    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL host.' })
+
+  url.username = ''
+  url.password = ''
+  url.hash = ''
+  return url.href
+}
+
+declare namespace normalizeExternalFeePayerUrl {
+  type Options = {
+    /** Whether to allow non-HTTPS or local/private external fee payer URLs. */
+    allowUnsafe?: boolean | undefined
+  }
+}
+
+function isUnsafeHostname(hostname: string): boolean {
+  const host = normalizeHostname(hostname)
+  if (host === 'localhost' || host.endsWith('.localhost')) return true
+  const ipv4 = parseIpv4(host)
+  if (ipv4) return isUnsafeIpv4(ipv4)
+  if (!host.includes(':')) return false
+  const ipv6 = parseIpv6(host)
+  if (!ipv6) return true
+  return isUnsafeIpv6(ipv6)
+}
+
+function normalizeHostname(hostname: string): string {
+  return hostname
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '')
+    .split('%')[0]!
+}
+
+function parseIpv4(value: string): [number, number, number, number] | undefined {
+  const parts = value.split('.')
+  if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined
+  const numbers = parts.map((part) => Number(part))
+  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined
+  return numbers as [number, number, number, number]
+}
+
+function isUnsafeIpv4(parts: [number, number, number, number]): boolean {
+  const [a, b] = parts
+  if (a === 0 || a === 10 || a === 127) return true
+  if (a === 100 && b >= 64 && b <= 127) return true
+  if (a === 169 && b === 254) return true
+  if (a === 172 && b >= 16 && b <= 31) return true
+  if (a === 192 && b === 168) return true
+  if (a >= 224) return true
+  return false
+}
+
+function parseIpv6(
+  value: string,
+): [number, number, number, number, number, number, number, number] | undefined {
+  const halves = value.split('::')
+  if (halves.length > 2) return undefined
+
+  const left = halves[0] ? halves[0].split(':') : []
+  const right = halves[1] ? halves[1].split(':') : []
+  const missing = halves.length === 2 ? 8 - left.length - right.length : 0
+  if (missing < 0) return undefined
+
+  const parts = [...left, ...Array(missing).fill('0'), ...right]
+  if (parts.length !== 8) return undefined
+
+  const numbers = parts.map((part) =>
+    /^[\da-f]{1,4}$/i.test(part) ? Number.parseInt(part, 16) : NaN,
+  )
+  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff)) return undefined
+  return numbers as [number, number, number, number, number, number, number, number]
+}
+
+function isUnsafeIpv6(parts: [number, number, number, number, number, number, number, number]) {
+  const [a] = parts
+  if (parts.every((part) => part === 0)) return true
+  if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return true
+  if ((a & 0xfe00) === 0xfc00) return true
+  if ((a & 0xffc0) === 0xfe80) return true
+  if ((a & 0xffc0) === 0xfec0) return true
+  if ((a & 0xff00) === 0xff00) return true
+
+  const ipv4 = ipv4FromIpv6(parts)
+  if (ipv4) return isUnsafeIpv4(ipv4)
+  return false
+}
+
+function ipv4FromIpv6(
+  parts: [number, number, number, number, number, number, number, number],
+): [number, number, number, number] | undefined {
+  const mapped = parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff
+  const compatible = parts.slice(0, 6).every((part) => part === 0)
+  if (!mapped && !compatible) return undefined
+  return [parts[6]! >> 8, parts[6]! & 0xff, parts[7]! >> 8, parts[7]! & 0xff]
+}
+
 /**
  * Reconstructs a `swap` shape (matching the inner autoSwap branch's return
  * value) from an upstream relay's `capabilities.autoSwap`. Used so a wallet

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

@@ -143,7 +143,7 @@ describe('tokenFromRequest (Node.js headers)', () => {
 
 describe('getSession with http.IncomingMessage', () => {
   const store = Kv.memory()
-  const handler = auth({ store, cookie: false })
+  const handler = auth({ store, cookie: false, domain: 'localhost' })
 
   let authServer: Http.Server
   let authUrl: string

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

@@ -67,6 +67,26 @@ describe('POST /register', () => {
   })
 })
 
+describe('kv', () => {
+  test('store without atomic create is accepted', () => {
+    const kv: Kv.Kv = {
+      async get() {
+        return undefined
+      },
+      async set() {},
+      async delete() {},
+    }
+
+    expect(() =>
+      webAuthn({
+        kv,
+        origin: 'http://localhost',
+        rpId: 'localhost',
+      }),
+    ).not.toThrow()
+  })
+})
+
 describe('POST /login', () => {
   test('error: unknown credential → 400', async () => {
     const response = await fetch(`${server.url}/login`, {

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

@@ -20,6 +20,17 @@ const defaults = {
 
 const sessionKey = (token: string) => `session:${token}`
 
+async function createCredential(
+  kv: Kv.Kv,
+  key: string,
+  value: { publicKey: string; userId?: string | undefined },
+) {
+  if (kv.create) return await kv.create(key, value)
+  if (await kv.get(key)) return false
+  await kv.set(key, value)
+  return true
+}
+
 /**
  * Session payload persisted in the session store and surfaced via
  * `getSession`. Mirrors the shape of the WebAuthn login response so
@@ -149,9 +160,13 @@ export function webAuthn(options: webAuthn.Options): webAuthn.ReturnType {
       const userId = stored.userId
         ? Base64.fromBytes(Bytes.fromString(stored.userId), { pad: false, url: true })
         : undefined
+      const created = await createCredential(kv, `credential:${credentialId}`, {
+        publicKey,
+        ...(userId ? { userId } : {}),
+      })
+      if (!created) throw new Error('Credential already exists')
 
-      const [, hook] = await Promise.all([
-        kv.set(`credential:${credentialId}`, { publicKey, ...(userId ? { userId } : {}) }),
+      const [hook] = await Promise.all([
         onRegister?.({
           credentialId,
           name: stored.name,
@@ -263,17 +278,9 @@ export function webAuthn(options: webAuthn.Options): webAuthn.ReturnType {
       })
       if (!valid) throw new Error('Authentication failed')
 
-      const rawResponse = response.raw?.response as unknown as Record<string, string> | undefined
-      const userHandle = rawResponse?.userHandle
-
       const credentialId = response.id
       const publicKey = credentialData.publicKey
-      // Surface the authenticator-emitted `userHandle` verbatim
-      // (base64url-encoded user id). Fall back to the base64-encoded
-      // userId we stashed during register, so callers see the same
-      // identifier shape across register and login.
-      const userId =
-        userHandle && userHandle.length > 0 ? userHandle : (credentialData.userId ?? undefined)
+      const userId = credentialData.userId
 
       // Hook for side effects (user provisioning, analytics, allow/deny).
       // The legacy contract — return a `Response` to merge fields onto
@@ -400,7 +407,12 @@ export declare namespace webAuthn {
     cookie?: boolean | undefined
     /** Cookie name for the session token. @default "accounts_webauthn" */
     cookieName?: string | undefined
-    /** Key-value store for challenges, credentials, and sessions. */
+    /**
+     * Key-value store for challenges, credentials, and sessions. When
+     * `create` is available, credential registration uses it to reject
+     * duplicates atomically. Otherwise, registration falls back to
+     * best-effort `get` then `set` storage.
+     */
     kv: Kv.Kv
     /** Called after a successful registration. The returned response is merged onto the default JSON response. */
     onRegister?: (parameters: {