tapimo 0.14.0 → 0.15.1

package/src/internal/Auth.test.ts

@@ -1,11 +1,19 @@
+import { serve } from '@hono/node-server'
+import * as Accounts from 'accounts/server'
 import { Hono, type Context } from 'hono'
 import { requestId } from 'hono/request-id'
-import { Challenge, Receipt } from 'mppx'
+import { exportJWK, generateKeyPair } from 'jose'
+import { Challenge, Receipt, Store as MppStore } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
-import type { Session } from 'mppx/tempo'
-import { RateLimit, Store } from 'tapimo'
-import { Actions } from 'viem/tempo'
+import { Session } from 'mppx/tempo'
+import { RateLimit, Store } from 'tapimo/server'
+import { createClient, custom, decodeFunctionData, isAddressEqual, maxUint256 } from 'viem'
+import { getTransaction } from 'viem/actions'
+import { Actions, Transaction } from 'viem/tempo'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import * as App from '../App.js'
 import * as ApiKey from '../ApiKey.js'
+import * as Management from '../apps/management/App.js'
 import type * as Db from '../db/Db.js'
 import * as Memberships from '../db/tables/memberships.js'
 import * as Organizations from '../db/tables/organizations.js'
@@ -67,6 +75,36 @@ describe('require', () => {
       `)
     })
 
+    test('isolates an explicit endpoint bucket from the shared scope quota', async () => {
+      const app = createScopedApp({
+        routes: [
+          {
+            path: '/other',
+            policy: {
+              apiKey: { rateLimit: { limit: 1, period: 'minute' }, scopes: ['data:read'] },
+            },
+          },
+          {
+            path: '/protected',
+            policy: {
+              apiKey: {
+                bucket: 'protected',
+                rateLimit: { limit: 1, period: 'minute' },
+                scopes: ['data:read'],
+              },
+            },
+          },
+        ],
+      })
+      const options = { headers: { 'tempo-api-key': token } }
+
+      const other = await app.request('/other', options)
+      const protected_ = await app.request('/protected', options)
+      const overflow = await app.request('/protected', options)
+
+      expect([other.status, protected_.status, overflow.status]).toEqual([200, 200, 429])
+    })
+
     test('does not parse payment authorization as bearer fallback', async () => {
       const app = createApp()
       const response = await app.request('/protected', {
@@ -1009,6 +1047,7 @@ describe('require', () => {
       })
 
       expect(response.status).toBe(200)
+      expect(consume).toHaveBeenCalledTimes(1)
       expect(consume).toHaveBeenCalledWith({
         key: 'mpp:api_key:key_test',
         limit: { limit: 100, period: 'minute' },
@@ -1032,6 +1071,42 @@ describe('require', () => {
       expect(response.headers.get('RateLimit-Limit')).toBe('25')
     })
 
+    test('isolates an explicit endpoint bucket from unrelated paid requests', async () => {
+      const auth = {
+        apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+        mpp: createMppHandler(),
+        rateLimit: RateLimit.memory(),
+      } satisfies Auth.Context
+      const app = createScopedApp({
+        auth,
+        routes: [
+          {
+            path: '/other',
+            policy: {
+              mpp: { rateLimit: { limit: 1, period: 'minute' }, session: { amount: '1' } },
+            },
+          },
+          {
+            path: '/protected',
+            policy: {
+              mpp: {
+                bucket: 'protected',
+                rateLimit: { limit: 1, period: 'minute' },
+                session: { amount: '1' },
+              },
+            },
+          },
+        ],
+      })
+      const options = { headers: { authorization: 'Payment paid' } }
+
+      const other = await app.request('/other', options)
+      const protected_ = await app.request('/protected', options)
+      const overflow = await app.request('/protected', options)
+
+      expect([other.status, protected_.status, overflow.status]).toEqual([200, 200, 429])
+    })
+
     test('route paid-request limit overrides the global limit', async () => {
       const app = createApp({
         auth: {
@@ -1310,8 +1385,8 @@ describe('require', () => {
       })
     })
 
-    test('paid retry opens a funded on-chain channel', async () => {
-      const mpp = createMppServer()
+    test('paid retry settles the accepted voucher on-chain', async () => {
+      const mpp = createMppServer({ settlementSchedule: { units: 1 } })
       const app = createApp({
         auth: {
           apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
@@ -1340,9 +1415,150 @@ describe('require', () => {
       })
       // The client deposits the request amount when no deposit is suggested.
       expect(state.deposit).toBe(1_000_000n)
-      // No settlement schedule configured, so nothing settles inline.
-      expect(state.settled).toBe(0n)
+      expect(state.settled).toBe(BigInt(receipt.acceptedCumulative))
       expect(state.closeRequestedAt).toBe(0)
+
+      const transaction = await getTransaction(Tempo.client, { hash: receipt.txHash! })
+      expect(transaction.nonceKey).toBe(maxUint256)
+      expect(transaction.nonce).toBe(0)
+    })
+
+    test('settles independent session channels concurrently', async () => {
+      const mpp = createMppServer({ settlementSchedule: { units: 1 } })
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { limit: 1, period: 'minute' } },
+        },
+      })
+
+      const responses = await Promise.all([
+        createMppClient(app).fetch('http://tempo-api.test/protected'),
+        createMppClient(app).fetch('http://tempo-api.test/protected'),
+      ])
+      const receipts = responses.map(sessionReceipt)
+      const transactions = await Promise.all(
+        receipts.map((receipt) => getTransaction(Tempo.client, { hash: receipt.txHash! })),
+      )
+
+      expect(responses.map((response) => response.status)).toEqual([200, 200])
+      expect(receipts[0]!.channelId).not.toBe(receipts[1]!.channelId)
+      expect(transactions.map((transaction) => [transaction.nonceKey, transaction.nonce])).toEqual([
+        [maxUint256, 0],
+        [maxUint256, 0],
+      ])
+    })
+
+    test('rolls back the request charge when scheduled settlement fails', async () => {
+      const failures: Session.Server.SessionSettlementFailureContext[] = []
+      const store = MppStore.memory()
+      const mpp = createMppServer({
+        account: Tempo.accounts[3],
+        onSessionSettlementFailure: (context) => {
+          failures.push(context)
+        },
+        recipient: Tempo.accounts[3].address,
+        settlementSchedule: { units: 1 },
+        store,
+      })
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { limit: 1, period: 'minute' } },
+        },
+      })
+
+      const response = await createMppClient(app).fetch('http://tempo-api.test/protected')
+
+      expect(response.status).toBe(402)
+      expect(failures.length).toBeGreaterThan(0)
+      for (const failure of failures) {
+        expect(failure).toMatchObject({
+          chainId: Tempo.chain.id,
+          outcome: 'failed',
+          stage: 'settlement',
+          trigger: 'scheduled',
+        })
+        expect(failure.error).toBeInstanceOf(Error)
+      }
+      const channels = Session.Server.ChannelStore.fromStore(store)
+      for (const channelId of new Set(failures.map(({ channelId }) => channelId))) {
+        const channel = await channels.getChannel(channelId)
+        expect({ spent: channel?.spent, units: channel?.units }).toEqual({ spent: 0n, units: 0 })
+      }
+    })
+
+    test('leaves request charges untouched when settlement submission is ambiguous', async () => {
+      const failures: Session.Server.SessionSettlementFailureContext[] = []
+      const store = MppStore.memory()
+      const client = createClient({
+        account: Tempo.accounts[2],
+        chain: Tempo.chain,
+        transport: custom({
+          request(parameters) {
+            if (parameters.method === 'eth_sendRawTransaction') {
+              const transaction = Transaction.deserialize(parameters.params[0] as `0x76${string}`)
+              const isSettlement = transaction.calls.some(
+                (call) =>
+                  call.to &&
+                  call.data &&
+                  isAddressEqual(call.to, Session.Precompile.Protocol.tip20ChannelEscrow) &&
+                  decodeFunctionData({ abi: Session.Precompile.escrowAbi, data: call.data })
+                    .functionName === 'settle',
+              )
+              if (isSettlement) throw new Error('settlement submission timed out')
+            }
+            return Tempo.client.request(parameters as never)
+          },
+        }),
+      })
+      const mpp = createMppServer({
+        getClient: () => client,
+        onSessionSettlementFailure: (context) => {
+          failures.push(context)
+        },
+        settlementSchedule: { units: 1 },
+        store,
+      })
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { limit: 1, period: 'minute' } },
+        },
+      })
+
+      const response = await createMppClient(app).fetch('http://tempo-api.test/protected')
+
+      expect(response.status).toBe(402)
+      expect(failures.length).toBeGreaterThan(0)
+      const channels = Session.Server.ChannelStore.fromStore(store)
+      for (const failure of failures) {
+        expect(failure).toMatchObject({
+          chainId: Tempo.chain.id,
+          outcome: 'ambiguous',
+          stage: 'settlement',
+          trigger: 'scheduled',
+        })
+        await expect(channels.getChannel(failure.channelId)).resolves.toMatchObject({
+          spent: 0n,
+          units: 0,
+        })
+      }
     })
 
     test('reuses the session channel across paid requests', async () => {
@@ -1498,6 +1714,32 @@ describe('require', () => {
       `)
     })
 
+    test('isolates an explicit endpoint bucket from unrelated public requests', async () => {
+      const app = createScopedApp({
+        routes: [
+          {
+            path: '/other',
+            policy: { public: { rateLimit: { limit: 1, period: 'minute' } } },
+          },
+          {
+            path: '/protected',
+            policy: {
+              public: {
+                bucket: 'protected',
+                rateLimit: { limit: 1, period: 'minute' },
+              },
+            },
+          },
+        ],
+      })
+
+      const other = await app.request('/other')
+      const protected_ = await app.request('/protected')
+      const overflow = await app.request('/protected')
+
+      expect([other.status, protected_.status, overflow.status]).toEqual([200, 200, 429])
+    })
+
     test('returns rate-limit error without payment context', async () => {
       const app = createApp({
         auth: {
@@ -2224,6 +2466,7 @@ function createMppServer(options: createMppServer.Options = {}) {
   return Mppx.create({
     methods: [
       tempo.session({
+        account: Tempo.accounts[2],
         bootstrap: false,
         chainId: Tempo.chain.id,
         currency: Tempo.currency,
@@ -2242,7 +2485,13 @@ function createMppServer(options: createMppServer.Options = {}) {
 declare namespace createMppServer {
   type Options = Pick<
     NonNullable<Parameters<typeof tempo.session>[0]>,
-    'chainId' | 'getClient' | 'store'
+    | 'account'
+    | 'chainId'
+    | 'getClient'
+    | 'onSessionSettlementFailure'
+    | 'recipient'
+    | 'settlementSchedule'
+    | 'store'
   >
 }
 
@@ -2366,3 +2615,1401 @@ function normalizePaymentPayer(value: unknown) {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value)
 }
+
+const origin = 'https://api.example.com'
+const secret = 'test-better-auth-secret-at-least-32-characters'
+
+describe('Google sign-in', () => {
+  test('resolves a Google session without an email sender', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      db,
+      session: {
+        google: {
+          clientId: 'google-client-id',
+          clientSecret: 'google-client-secret',
+        },
+        secret,
+        wallet: { origin },
+      },
+    })
+    const now = new Date()
+    const sessionToken = 'google-session-token'
+
+    try {
+      await db.kysely
+        .insertInto('users')
+        .values({
+          address: null,
+          createdAt: now.toISOString(),
+          email: 'developer@example.com',
+          emailVerified: true,
+          id: 'usr_google',
+          image: null,
+          name: 'Tempo Developer',
+          updatedAt: now.toISOString(),
+        })
+        .execute()
+      await db.kysely
+        .insertInto('auth_sessions')
+        .values({
+          createdAt: now,
+          expiresAt: new Date(now.getTime() + 60_000),
+          id: 'ses_google',
+          ipAddress: null,
+          provider: 'google',
+          token: sessionToken,
+          updatedAt: now,
+          userAgent: null,
+          userId: 'usr_google',
+        })
+        .execute()
+      const sessionKey = await crypto.subtle.importKey(
+        'raw',
+        new TextEncoder().encode(secret),
+        { hash: 'SHA-256', name: 'HMAC' },
+        false,
+        ['sign'],
+      )
+      const signature = await crypto.subtle.sign(
+        'HMAC',
+        sessionKey,
+        new TextEncoder().encode(sessionToken),
+      )
+      const cookie = `${sessionToken}.${btoa(String.fromCharCode(...new Uint8Array(signature)))}`
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { cookie: `tempo_auth.session_token=${cookie}` },
+      })
+
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchObject({
+        email: 'developer@example.com',
+        id: 'usr_google',
+      })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('uses a trusted forwarded Console origin for its callback', async () => {
+    const consoleOrigin = 'https://console.example.com'
+    const app = TestApp.create({
+      session: {
+        google: {
+          clientId: 'google-client-id',
+          clientSecret: 'google-client-secret',
+        },
+        secret,
+        trustedOrigins: [consoleOrigin],
+        wallet: { origin },
+      },
+    })
+    const response = await app.request(`${origin}/v1/auth/sign-in/social`, {
+      body: JSON.stringify({ callbackURL: `${consoleOrigin}/`, provider: 'google' }),
+      headers: {
+        'content-type': 'application/json',
+        origin: consoleOrigin,
+        'x-forwarded-host': 'console.example.com',
+        'x-forwarded-proto': 'https',
+      },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(200)
+    const body = (await response.json()) as { url: string }
+    expect(new URL(body.url).searchParams.get('redirect_uri')).toBe(
+      `${consoleOrigin}/v1/auth/callback/google`,
+    )
+  })
+})
+
+describe('email OTP', () => {
+  test.each([
+    {
+      body: '{',
+      name: 'malformed challenge JSON',
+      path: '/v1/auth/siwe/challenge',
+    },
+    {
+      body: JSON.stringify([]),
+      name: 'schema-invalid challenge JSON',
+      path: '/v1/auth/siwe/challenge',
+    },
+    { body: JSON.stringify({}), name: 'schema-invalid verification JSON', path: '/v1/auth/siwe' },
+  ])('validates $name', async ({ body, path }) => {
+    const app = TestApp.create({ session: { secret, wallet: { origin } } })
+
+    const response = await app.request(`${origin}${path}`, {
+      body,
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({
+      error: { code: 'body_invalid', message: 'Invalid request body' },
+    })
+  })
+
+  test('leaves unmatched auth requests available to later routes', async () => {
+    const app = TestApp.create({
+      session: { secret, wallet: { origin } },
+    }).route(
+      '/',
+      new Hono().post('/v1/auth/dev-oidc/token', async (c) =>
+        c.json({ idToken: 'test', request: await c.req.json() }),
+      ),
+    )
+
+    const response = await app.request(
+      '/v1/auth/dev-oidc/token',
+      json({ subject: 'developer@example.com' }),
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      idToken: 'test',
+      request: { subject: 'developer@example.com' },
+    })
+  })
+
+  test('keeps Better Auth routes out of OpenAPI while using the session scheme', async () => {
+    const app = TestApp.create({
+      session: { secret, wallet: { origin } },
+    })
+    const spec = await (await app.request('/openapi.json')).json()
+
+    expect(spec.paths['/v1/auth/email-otp/send-verification-otp']).toBeUndefined()
+    expect(spec.paths['/v1/auth/sign-in/email-otp']).toBeUndefined()
+    expect(spec.paths['/v1/auth/sign-out']).toBeUndefined()
+    expect(spec.paths['/v1/auth/email-otp']).toBeUndefined()
+    expect(spec.paths['/v1/auth/siwe/logout']).toBeUndefined()
+    expect(spec.components.securitySchemes.emailSession).toBeUndefined()
+    expect(spec.components.securitySchemes.session).toMatchObject({
+      in: 'header',
+      name: 'Cookie',
+      type: 'apiKey',
+    })
+    expect(spec.paths['/v1/auth/logout'].post.responses['204']).toBeDefined()
+    expect(spec.paths['/v1/auth/logout'].post.security).toEqual([])
+    expect(spec.paths['/v1/me'].get.security).toContainEqual({ session: [] })
+  })
+
+  test('sends email OTP without the management group', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = App.create({
+      auth: { session: { secret, wallet: { origin } } },
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      kv: { store: Store.memory() },
+    })
+
+    try {
+      const response = await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'developer@example.com', type: 'sign-in' }),
+      )
+
+      expect(response.status).toBe(200)
+      expect(messages).toHaveLength(1)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('accepts the legacy management email option', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = App.create({
+      auth: { session: { secret, wallet: { origin } } },
+      db,
+      kv: { store: Store.memory() },
+    }).route(
+      '/',
+      Management.management({
+        email: {
+          from: 'noreply@example.com',
+          send: async (message) => void messages.push(message),
+        },
+      }),
+    )
+
+    try {
+      const response = await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'developer@example.com', type: 'sign-in' }),
+      )
+
+      expect(response.status).toBe(200)
+      expect(messages).toHaveLength(1)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('creates a canonical Tempo user and Better Auth session', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: {
+        secret,
+        wallet: { origin },
+      },
+    })
+
+    try {
+      const sent = await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'Developer@Example.com', type: 'sign-in' }),
+      )
+      expect(sent.status).toBe(200)
+      expect(await sent.json()).toEqual({ success: true })
+      expect(messages).toHaveLength(1)
+      const otp = messages[0]!.text.match(/\b\d{6}\b/)?.[0]
+      expect(otp).toBeDefined()
+      expect(messages[0]).toMatchObject({
+        from: 'noreply@example.com',
+        subject: `${otp} is your Tempo sign-in code`,
+        to: 'developer@example.com',
+      })
+
+      const verification = await db.kysely
+        .selectFrom('auth_verifications')
+        .select(['value'])
+        .executeTakeFirstOrThrow()
+      expect(verification.value).not.toContain(otp!)
+
+      const verified = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp }),
+      )
+      expect(verified.status).toBe(200)
+      expect(await verified.json()).toMatchObject({ user: { email: 'developer@example.com' } })
+
+      const existing = await Users.getByEmail(db, 'developer@example.com')
+      expect(existing).toBeDefined()
+
+      const setCookie = verified.headers.get('set-cookie')
+      expect(setCookie).toContain('tempo_auth.session_token=')
+      expect(setCookie).toContain('Max-Age=86400')
+      expect(setCookie).toContain('Path=/')
+      expect(setCookie).toContain('HttpOnly')
+      expect(setCookie).toContain('Secure')
+      expect(setCookie).toContain('SameSite=Lax')
+
+      const session = await app.request(`${origin}/v1/auth/get-session`, {
+        headers: { cookie: setCookie!.split(';', 1)[0]! },
+      })
+      expect(await session.json()).toMatchObject({ session: { provider: 'email' } })
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { cookie: setCookie!.split(';', 1)[0]! },
+      })
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchObject({
+        email: 'developer@example.com',
+        id: existing!.id,
+      })
+
+      const users = await db.kysely.selectFrom('users').selectAll().execute()
+      expect(users).toHaveLength(1)
+      expect(users[0]).toMatchObject({
+        email: 'developer@example.com',
+        emailVerified: true,
+      })
+      expect(users[0]!.createdAt).toMatch(/Z$/)
+      expect(users[0]!.updatedAt).toMatch(/Z$/)
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('selects the oldest user for a duplicate email', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      await db.kysely
+        .insertInto('users')
+        .values([
+          {
+            address: null,
+            createdAt: '2025-01-01T00:00:00.000Z',
+            email: 'developer@example.com',
+            emailVerified: true,
+            id: 'usr_duplicate_oldest',
+            image: null,
+            name: 'Oldest user',
+            updatedAt: '2025-01-01T00:00:00.000Z',
+          },
+          {
+            address: null,
+            createdAt: '2026-01-01T00:00:00.000Z',
+            email: 'developer@example.com',
+            emailVerified: true,
+            id: 'usr_duplicate_newest',
+            image: null,
+            name: 'Newest user',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+          },
+        ])
+        .execute()
+      const cookie = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { cookie },
+      })
+
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchObject({ id: 'usr_duplicate_oldest' })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('mounts the Better Auth handler surface', async () => {
+    const app = TestApp.create({
+      session: { secret, wallet: { origin } },
+    })
+
+    const response = await app.request(`${origin}/v1/auth/get-session`)
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toBeNull()
+  })
+
+  test('mounts Better Auth under the app base path', async () => {
+    const app = TestApp.create({
+      path: '/api',
+      session: { secret, wallet: { origin } },
+    })
+
+    const response = await app.request(`${origin}/api/v1/auth/get-session`)
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toBeNull()
+  })
+
+  test('handles SIWE routes under an application path', async () => {
+    const app = TestApp.create({
+      path: '/api',
+      session: { secret, wallet: { origin } },
+    })
+    const account = privateKeyToAccount(generatePrivateKey())
+
+    const { verifyResponse } = await TestApp.signIn(
+      { request: (path, init) => app.request(`/api${path}`, init) },
+      account,
+    )
+
+    expect(verifyResponse.status).toBe(200)
+  })
+
+  test('returns the canonical error envelope when the SIWE store fails', async () => {
+    const entries: Log.Entry[] = []
+    const app = TestApp.create({
+      kv: {
+        store: Store.from({
+          ...Store.memory(),
+          async put() {
+            throw new Error('Session store unavailable')
+          },
+        }),
+      },
+      logger: (entry) => void entries.push(entry),
+      session: { secret, wallet: { origin } },
+    })
+
+    const response = await app.request(`${origin}/v1/auth/siwe/challenge`, json({}))
+
+    expect(response.status).toBe(500)
+    expect(await response.json()).toMatchObject({
+      error: { code: 'internal_error', message: 'Internal server error' },
+    })
+    expect(entries.at(-1)).toMatchObject({ errorCode: 'internal_error', level: 'error' })
+  })
+
+  test('does not mount Better Auth without session authentication', async () => {
+    const app = TestApp.create({ auth: false })
+
+    const response = await app.request(`${origin}/v1/auth/get-session`)
+
+    expect(response.status).toBe(404)
+  })
+
+  test('signs out through the Better Auth handler', async () => {
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+    const cookie = await signInEmail(app, {
+      email: 'developer@example.com',
+      messages,
+    })
+
+    const response = await app.request(`${origin}/v1/auth/sign-out`, {
+      headers: { cookie },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchObject({ success: true })
+    expect(response.headers.get('set-cookie')).toContain('tempo_auth.session_token=')
+    expect(
+      await app.request(`${origin}/v1/me`, {
+        headers: { cookie },
+      }),
+    ).toMatchObject({ status: 401 })
+  })
+
+  test('rejects unsupported OTP purposes before delivery', async () => {
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    const response = await app.request(
+      `${origin}/v1/auth/email-otp/send-verification-otp`,
+      json({ email: 'developer@example.com', type: 'email-verification' }),
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+    expect(messages).toHaveLength(0)
+  })
+
+  test('signs out Better Auth through the canonical logout route', async () => {
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+    const cookie = await signInEmail(app, {
+      email: 'developer@example.com',
+      messages,
+    })
+
+    const response = await app.request(`${origin}/v1/auth/logout`, {
+      headers: { cookie },
+      method: 'POST',
+    })
+
+    expectSessionsCleared(response)
+    expect(
+      await app.request(`${origin}/v1/me`, {
+        headers: { cookie },
+      }),
+    ).toMatchObject({ status: 401 })
+  })
+
+  test('signs out wallet sessions without email configuration', async () => {
+    const app = TestApp.create({ session: { secret, wallet: { origin } } })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const { cookie } = await TestApp.signIn(app, account)
+
+    const response = await app.request(`${origin}/v1/auth/logout`, {
+      headers: { cookie: cookie! },
+      method: 'POST',
+    })
+
+    expectSessionsCleared(response)
+    expect(
+      await app.request(`${origin}/v1/me`, {
+        headers: { cookie: cookie! },
+      }),
+    ).toMatchObject({ status: 401 })
+  })
+
+  test('reports wallet session-store logout failures', async () => {
+    const entries: Log.Entry[] = []
+    const source = Store.memory()
+    let failDeletes = false
+    const app = TestApp.create({
+      kv: {
+        store: Store.from({
+          ...source,
+          async delete(key) {
+            if (failDeletes) throw new Error('Session store unavailable')
+            await source.delete(key)
+          },
+        }),
+      },
+      logger: (entry) => void entries.push(entry),
+      session: { secret, wallet: { origin } },
+    })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const { cookie } = await TestApp.signIn(app, account)
+    entries.length = 0
+    failDeletes = true
+
+    const response = await app.request(`${origin}/v1/auth/logout`, {
+      headers: { cookie: cookie! },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(500)
+    expect(await response.json()).toMatchObject({
+      error: { code: 'session_logout_failed', message: 'Session logout failed' },
+    })
+    expect(entries).toHaveLength(1)
+    expect(entries[0]).toMatchObject({ errorCode: 'session_logout_failed', level: 'error' })
+  })
+
+  test('does not resolve email sessions when email is unconfigured', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const email = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+    const cookie = await signInEmail(email, {
+      email: 'developer@example.com',
+      messages,
+    })
+    const wallet = TestApp.create({
+      db,
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      const unauthorized = await wallet.request(`${origin}/v1/me`, {
+        headers: { cookie },
+      })
+      expect(unauthorized.status).toBe(401)
+
+      const logout = await wallet.request(`${origin}/v1/auth/logout`, {
+        headers: { cookie },
+        method: 'POST',
+      })
+      expectSessionsCleared(logout)
+
+      const session = await email.request(`${origin}/v1/auth/get-session`, {
+        headers: { cookie },
+      })
+      expect(await session.json()).toBeNull()
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('clears invalid sessions idempotently', async () => {
+    const app = TestApp.create({ session: { secret, wallet: { origin } } })
+
+    const response = await app.request(`${origin}/v1/auth/logout`, {
+      headers: {
+        cookie: 'accounts_auth=expired; tempo_auth.session_token=expired',
+      },
+      method: 'POST',
+    })
+
+    expectSessionsCleared(response)
+  })
+
+  test('reports session database failures', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+    const cookie = await signInEmail(app, {
+      email: 'developer@example.com',
+      messages,
+    })
+    await db.close()
+
+    const response = await app.request(`${origin}/v1/me`, {
+      headers: { cookie },
+    })
+
+    expect(response.status).toBe(500)
+    expect(await response.json()).toMatchObject({ error: { code: 'internal_error' } })
+  })
+
+  test('rejects consumed and superseded codes without revealing the cause', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'developer@example.com', type: 'sign-in' }),
+      )
+      const first = messages[0]!.text.match(/\b\d{6}\b/)![0]!
+      await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'developer@example.com', type: 'sign-in' }),
+      )
+      const second = messages[1]!.text.match(/\b\d{6}\b/)![0]!
+
+      const superseded = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp: first }),
+      )
+      expect(superseded.status).toBe(400)
+      expect(await superseded.json()).toMatchObject({ code: 'INVALID_OTP' })
+
+      const verified = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp: second }),
+      )
+      expect(verified.status).toBe(200)
+
+      const consumed = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp: second }),
+      )
+      expect(consumed.status).toBe(400)
+      expect(await consumed.json()).toMatchObject({ code: 'INVALID_OTP' })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('rejects expired codes through Better Auth', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      await app.request(
+        `${origin}/v1/auth/email-otp/send-verification-otp`,
+        json({ email: 'developer@example.com', type: 'sign-in' }),
+      )
+      const otp = messages[0]!.text.match(/\b\d{6}\b/)![0]!
+      await db.kysely
+        .updateTable('auth_verifications')
+        .set({ expiresAt: new Date(0) })
+        .execute()
+
+      const response = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp }),
+      )
+
+      expect(response.status).toBe(400)
+      expect(await response.json()).toMatchObject({ code: 'OTP_EXPIRED' })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('uses Better Auth rate limits across request-scoped instances', async () => {
+    const app = TestApp.create({
+      auth: { clientIp: (request) => request.headers.get('x-trusted-ip') ?? undefined },
+      email: { from: 'noreply@example.com', send: async () => {} },
+      rateLimit: { now: () => new Date('2026-01-01T00:00:00.000Z') },
+      session: { secret, wallet: { origin } },
+    })
+
+    for (let index = 0; index < 3; index++) {
+      const response = await app.request(`${origin}/v1/auth/email-otp/send-verification-otp`, {
+        ...json({ email: `developer-${index}@example.com`, type: 'sign-in' }),
+        headers: {
+          'cf-connecting-ip': `198.51.100.${index}`,
+          'content-type': 'application/json',
+          'x-trusted-ip': '203.0.113.10',
+        },
+      })
+      expect(response.status).toBe(200)
+    }
+
+    const response = await app.request(`${origin}/v1/auth/email-otp/send-verification-otp`, {
+      ...json({ email: 'developer-3@example.com', type: 'sign-in' }),
+      headers: {
+        'cf-connecting-ip': '198.51.100.4',
+        'content-type': 'application/json',
+        'x-trusted-ip': '203.0.113.10',
+      },
+    })
+    expect(response.status).toBe(429)
+    expect(response.headers.get('x-retry-after')).toBe('60')
+    expect(await response.json()).toMatchObject({ message: expect.any(String) })
+  })
+
+  test('limits verification attempts', async () => {
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+    await app.request(
+      `${origin}/v1/auth/email-otp/send-verification-otp`,
+      json({ email: 'developer@example.com', type: 'sign-in' }),
+    )
+    const otp = messages[0]!.text.match(/\b\d{6}\b/)![0]!
+    const wrong = `${otp[0] === '0' ? '1' : '0'}${otp.slice(1)}`
+
+    for (let index = 0; index < 3; index++) {
+      const response = await app.request(
+        `${origin}/v1/auth/sign-in/email-otp`,
+        json({ email: 'developer@example.com', otp: wrong }),
+      )
+      expect(response.status).toBe(400)
+    }
+    const response = await app.request(
+      `${origin}/v1/auth/sign-in/email-otp`,
+      json({ email: 'developer@example.com', otp: wrong }),
+    )
+    expect(response.status).toBe(429)
+    expect(await response.json()).toMatchObject({ message: expect.any(String) })
+  })
+
+  test('accepts matching email and wallet sessions', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      const account = privateKeyToAccount(generatePrivateKey())
+      const wallet = await TestApp.signIn(app, account)
+      expect(wallet.verifyResponse.status).toBe(200)
+      const user = await Users.getByAddress(db, account.address)
+      expect(user).toBeDefined()
+      await Users.setEmail(db, user!.id, 'developer@example.com')
+      const email = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { cookie: `${email}; ${wallet.cookie}` },
+      })
+
+      expect(response.status).toBe(200)
+      expect(await response.json()).toMatchObject({ email: 'developer@example.com', id: user!.id })
+
+      const logout = await app.request(`${origin}/v1/auth/logout`, {
+        headers: { cookie: `${email}; ${wallet.cookie}` },
+        method: 'POST',
+      })
+      expect(logout.status).toBe(204)
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { cookie: email },
+        }),
+      ).toMatchObject({ status: 401 })
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { cookie: wallet.cookie! },
+        }),
+      ).toMatchObject({ status: 401 })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('rejects conflicting email and wallet sessions', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: {
+        secret,
+        wallet: { origin },
+      },
+    })
+
+    try {
+      const account = privateKeyToAccount(generatePrivateKey())
+      const wallet = await TestApp.signIn(app, account)
+      expect(wallet.verifyResponse.status).toBe(200)
+      const email = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { cookie: `${email}; ${wallet.cookie}` },
+      })
+
+      expect(response.status).toBe(401)
+
+      const logout = await app.request(`${origin}/v1/auth/logout`, {
+        headers: { cookie: `${email}; ${wallet.cookie}` },
+        method: 'POST',
+      })
+      expectSessionsCleared(logout)
+      const emailSession = await app.request(`${origin}/v1/auth/get-session`, {
+        headers: { cookie: email },
+      })
+      expect(emailSession.status).toBe(200)
+      expect(await emailSession.json()).toBeNull()
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { cookie: email },
+        }),
+      ).toMatchObject({ status: 401 })
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { cookie: wallet.cookie! },
+        }),
+      ).toMatchObject({ status: 401 })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('signs out conflicting wallet bearer and email cookie sessions', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      const account = privateKeyToAccount(generatePrivateKey())
+      const wallet = await TestApp.signIn(app, account, { returnToken: true })
+      expect(wallet.verifyResponse.status).toBe(200)
+      const { token } = (await wallet.verifyResponse.json()) as { token: string }
+      const email = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+
+      const response = await app.request(`${origin}/v1/me`, {
+        headers: { authorization: `Bearer ${token}`, cookie: email },
+      })
+      expect(response.status).toBe(401)
+
+      const logout = await app.request(`${origin}/v1/auth/logout`, {
+        headers: { authorization: `Bearer ${token}`, cookie: email },
+        method: 'POST',
+      })
+      expectSessionsCleared(logout)
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { cookie: email },
+        }),
+      ).toMatchObject({ status: 401 })
+      expect(
+        await app.request(`${origin}/v1/me`, {
+          headers: { authorization: `Bearer ${token}` },
+        }),
+      ).toMatchObject({ status: 401 })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('signs out wallet cookies when a bearer credential is also present', async () => {
+    const app = TestApp.create({ session: { secret, wallet: { origin } } })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const wallet = await TestApp.signIn(app, account)
+
+    const logout = await app.request(`${origin}/v1/auth/logout`, {
+      headers: {
+        authorization: 'Bearer unrelated-credential',
+        cookie: wallet.cookie!,
+      },
+      method: 'POST',
+    })
+
+    expectSessionsCleared(logout)
+    expect(
+      await app.request(`${origin}/v1/me`, {
+        headers: { cookie: wallet.cookie! },
+      }),
+    ).toMatchObject({ status: 401 })
+  })
+
+  test('rate limits unauthenticated logout requests', async () => {
+    const app = TestApp.create({ session: { secret, wallet: { origin } } })
+
+    for (let index = 0; index < 60; index++)
+      expect(
+        await app.request(`${origin}/v1/auth/logout`, {
+          method: 'POST',
+        }),
+      ).toMatchObject({ status: 204 })
+
+    const response = await app.request(`${origin}/v1/auth/logout`, {
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(429)
+    expect(await response.json()).toMatchObject({ error: { code: 'rate_limit_exceeded' } })
+  })
+})
+
+describe('one-time session tokens', () => {
+  test('redeems the current Better Auth session once', async () => {
+    const db = TestApp.database()
+    const messages: App.Email.Message[] = []
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: { secret, wallet: { origin } },
+    })
+
+    try {
+      const cookie = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+      const generated = await app.request(`${origin}/v1/auth/one-time-token/generate`, {
+        headers: { cookie },
+      })
+      const { token } = (await generated.json()) as { token: string }
+      const redeem = () => app.request(`${origin}/v1/auth/one-time-token/verify`, json({ token }))
+
+      expect(generated.status).toBe(200)
+      const first = await redeem()
+      expect(first.status).toBe(200)
+      expect(first.headers.get('set-cookie')).toBeNull()
+      expect(await first.json()).toMatchObject({
+        user: { email: 'developer@example.com', emailVerified: true },
+      })
+      expect((await redeem()).status).toBe(400)
+    } finally {
+      await db.close()
+    }
+  })
+})
+
+describe('identity sign-in', () => {
+  test('rejects cross-site form bodies', async () => {
+    const app = TestApp.create({
+      session: { identity: { audience: origin }, secret, wallet: { origin } },
+    })
+
+    const response = await app.request(`${origin}/v1/auth/identity`, {
+      body: JSON.stringify({ idToken: 'attacker-token', padding: '' }),
+      headers: {
+        'content-type': 'text/plain',
+        origin: 'https://attacker.example.com',
+      },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({
+      error: { code: 'body_invalid', message: 'Invalid request body' },
+    })
+    expect(response.headers.get('set-cookie')).toBeNull()
+  })
+
+  test('verifies a Wallet identity and creates an API session', async () => {
+    const db = TestApp.database()
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const app = TestApp.create({
+      db,
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+
+    try {
+      const response = await app.request(
+        `${origin}/v1/auth/identity`,
+        json({ idToken: await issuer.mint({ address: account.address, audience: origin }) }),
+      )
+      const cookie = response.headers.get('set-cookie')?.split(';', 1)[0]
+
+      expect(response.status).toBe(200)
+      expect(cookie).toMatch(/^tempo_identity=/)
+      expect(response.headers.get('set-cookie')).toContain('Max-Age=86400')
+      expect(response.headers.get('set-cookie')).toContain('HttpOnly')
+      expect(response.headers.get('set-cookie')).toContain('SameSite=Lax')
+      expect(response.headers.get('set-cookie')).toContain('Secure')
+
+      const me = await app.request(`${origin}/v1/me`, { headers: { cookie: cookie! } })
+      expect(me.status).toBe(200)
+      expect(await me.json()).toMatchObject({
+        address: account.address.toLowerCase(),
+        email: 'developer@example.com',
+      })
+
+      const logout = await app.request(`${origin}/v1/auth/logout`, {
+        headers: { cookie: cookie! },
+        method: 'POST',
+      })
+      expect(logout.status).toBe(204)
+      expect(logout.headers.getSetCookie()).toEqual(
+        expect.arrayContaining([expect.stringContaining('tempo_identity=')]),
+      )
+      expect(await app.request(`${origin}/v1/me`, { headers: { cookie: cookie! } })).toMatchObject({
+        status: 401,
+      })
+    } finally {
+      await issuer.close()
+      await db.close()
+    }
+  })
+
+  test('clears the identity cookie when session revocation fails', async () => {
+    const db = TestApp.database()
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const source = Store.memory()
+    let failDeletes = false
+    const app = TestApp.create({
+      db,
+      kv: {
+        store: Store.from({
+          ...source,
+          async delete(key) {
+            if (failDeletes) throw new Error('Session store unavailable')
+            await source.delete(key)
+          },
+        }),
+      },
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+    const account = privateKeyToAccount(generatePrivateKey())
+
+    try {
+      const identity = await app.request(
+        `${origin}/v1/auth/identity`,
+        json({ idToken: await issuer.mint({ address: account.address, audience: origin }) }),
+      )
+      const cookie = identity.headers.get('set-cookie')?.split(';', 1)[0]
+      failDeletes = true
+      const logout = await app.request(`${origin}/v1/auth/logout`, {
+        headers: { cookie: cookie! },
+        method: 'POST',
+      })
+
+      expect(logout.status).toBe(500)
+      expect(logout.headers.getSetCookie()).toEqual(
+        expect.arrayContaining([expect.stringMatching(/^tempo_identity=; Max-Age=0;/)]),
+      )
+    } finally {
+      await issuer.close()
+      await db.close()
+    }
+  })
+
+  test('does not resolve identity sessions when identity is unconfigured', async () => {
+    const db = TestApp.database()
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const store = Store.memory()
+    const configured = TestApp.create({
+      db,
+      kv: { store },
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+    const unconfigured = TestApp.create({
+      db,
+      kv: { store },
+      session: { secret, wallet: { origin } },
+    })
+    const account = privateKeyToAccount(generatePrivateKey())
+
+    try {
+      const identity = await configured.request(
+        `${origin}/v1/auth/identity`,
+        json({ idToken: await issuer.mint({ address: account.address, audience: origin }) }),
+      )
+      const cookie = identity.headers.get('set-cookie')?.split(';', 1)[0]
+      const response = await unconfigured.request(`${origin}/v1/me`, {
+        headers: { cookie: cookie! },
+      })
+
+      expect(identity.status).toBe(200)
+      expect(response.status).toBe(401)
+    } finally {
+      await issuer.close()
+      await db.close()
+    }
+  })
+
+  test('reports identity issuer failures', async () => {
+    const db = TestApp.database()
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const idToken = await issuer.mint({ address: account.address, audience: origin })
+    const entries: Log.Entry[] = []
+    const app = TestApp.create({
+      db,
+      logger: (entry) => void entries.push(entry),
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+    await issuer.close()
+
+    try {
+      const response = await app.request(`${origin}/v1/auth/identity`, json({ idToken }))
+
+      expect(response.status).toBe(500)
+      expect(await response.json()).toMatchObject({
+        error: { code: 'internal_error', message: 'Internal server error' },
+      })
+      expect(entries.at(-1)).toMatchObject({ errorCode: 'internal_error', level: 'error' })
+    } finally {
+      await db.close()
+    }
+  })
+
+  test('reconciles the Wallet address into an active email session', async () => {
+    const db = TestApp.database()
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const messages: App.Email.Message[] = []
+    const account = privateKeyToAccount(generatePrivateKey())
+    const app = TestApp.create({
+      db,
+      email: {
+        from: 'noreply@example.com',
+        send: async (message) => void messages.push(message),
+      },
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+
+    try {
+      const emailCookie = await signInEmail(app, {
+        email: 'developer@example.com',
+        messages,
+      })
+      const identity = await app.request(
+        `${origin}/v1/auth/identity`,
+        json({ idToken: await issuer.mint({ address: account.address, audience: origin }) }),
+      )
+      const identityCookie = identity.headers.get('set-cookie')?.split(';', 1)[0]
+      const me = await app.request(`${origin}/v1/me`, {
+        headers: { cookie: `${emailCookie}; ${identityCookie}` },
+      })
+
+      expect(identity.status).toBe(200)
+      expect(await me.json()).toMatchObject({
+        address: account.address.toLowerCase(),
+        email: 'developer@example.com',
+      })
+    } finally {
+      await issuer.close()
+      await db.close()
+    }
+  })
+
+  test('rejects an identity issued for another audience', async () => {
+    const issuer = await createIdentityIssuer({ email: 'developer@example.com' })
+    const account = privateKeyToAccount(generatePrivateKey())
+    const app = TestApp.create({
+      session: {
+        identity: { audience: origin, issuer: issuer.url },
+        secret,
+        wallet: { origin },
+      },
+    })
+
+    try {
+      const response = await app.request(
+        `${origin}/v1/auth/identity`,
+        json({
+          idToken: await issuer.mint({
+            address: account.address,
+            audience: 'https://attacker.example.com',
+          }),
+        }),
+      )
+
+      expect(response.status).toBe(401)
+      expect(await response.json()).toMatchObject({
+        error: { code: 'identity_invalid', message: 'Invalid identity token' },
+      })
+      expect(response.headers.get('set-cookie')).toBeNull()
+    } finally {
+      await issuer.close()
+    }
+  })
+
+  test('documents identity sign-in only when configured', async () => {
+    const configured = TestApp.create({
+      session: { identity: { audience: origin }, secret, wallet: { origin } },
+    })
+    const unconfigured = TestApp.create({ session: { secret, wallet: { origin } } })
+
+    const configuredSpec = await (await configured.request('/openapi.json')).json()
+    const unconfiguredSpec = await (await unconfigured.request('/openapi.json')).json()
+
+    expect(configuredSpec.paths['/v1/auth/identity'].post).toBeDefined()
+    expect(unconfiguredSpec.paths['/v1/auth/identity']).toBeUndefined()
+  })
+})
+
+function json(body: unknown) {
+  return {
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json' },
+    method: 'POST',
+  }
+}
+
+function expectSessionsCleared(response: globalThis.Response) {
+  expect(response.status).toBe(204)
+  expect(response.headers.getSetCookie()).toEqual(
+    expect.arrayContaining([
+      expect.stringContaining('accounts_auth='),
+      expect.stringContaining('tempo_auth.session_token='),
+    ]),
+  )
+}
+
+/** Local Wallet-style OIDC issuer for identity verification tests. */
+async function createIdentityIssuer(options: createIdentityIssuer.Options) {
+  const { privateKey, publicKey } = await generateKeyPair('EdDSA', { extractable: true })
+  let provider!: ReturnType<typeof Accounts.Handler.oidcProvider>
+  type Listener = { close: () => Promise<void>; url: string }
+  const { close, url } = await new Promise<Listener>((resolve) => {
+    const server = serve({ fetch: (request) => provider.fetch(request), port: 0 }, (info) =>
+      resolve({
+        close: () => new Promise((done) => server.close(() => done())),
+        url: `http://127.0.0.1:${info.port}`,
+      }),
+    )
+  })
+  provider = Accounts.Handler.oidcProvider({
+    getClaims: () => ({ email: options.email, email_verified: true }),
+    issuer: url,
+    publicKey: JSON.stringify(await exportJWK(publicKey)),
+    signingKey: JSON.stringify(await exportJWK(privateKey)),
+  })
+  return {
+    close,
+    async mint(parameters: createIdentityIssuer.MintParameters) {
+      const response = await provider.fetch(
+        new Request(`${url}/token`, {
+          body: JSON.stringify({
+            audience: parameters.audience,
+            subject: parameters.address,
+          }),
+          headers: { 'content-type': 'application/json' },
+          method: 'POST',
+        }),
+      )
+      const { idToken } = (await response.json()) as { idToken: string }
+      return idToken
+    },
+    url,
+  }
+}
+
+declare namespace createIdentityIssuer {
+  type MintParameters = {
+    /** Wallet address used as the token subject. */
+    address: string
+    /** Origin used as the token audience. */
+    audience: string
+  }
+
+  type Options = {
+    /** Verified email included in issued tokens. */
+    email: string
+  }
+}
+
+async function signInEmail(app: TestApp.signIn.App, options: signInEmail.Options) {
+  await app.request(
+    `${origin}/v1/auth/email-otp/send-verification-otp`,
+    json({ email: options.email, type: 'sign-in' }),
+  )
+  const otp = options.messages.at(-1)!.text.match(/\b\d{6}\b/)![0]!
+  const response = await app.request(
+    `${origin}/v1/auth/sign-in/email-otp`,
+    json({ email: options.email, otp }),
+  )
+  expect(response.status).toBe(200)
+  return response.headers.get('set-cookie')!.split(';', 1)[0]!
+}
+
+declare namespace signInEmail {
+  type Options = {
+    /** Email to authenticate. */
+    email: string
+    /** Captured outbound messages. */
+    messages: readonly App.Email.Message[]
+  }
+}