tapimo 0.0.0 → 0.0.2

package/src/internal/Auth.test.ts

@@ -0,0 +1,980 @@
+import { Hono } from 'hono'
+import { requestId } from 'hono/request-id'
+import { Mppx, tempo } from 'mppx/hono'
+import { RateLimit } from 'cadent'
+import * as ApiKey from '../ApiKey.js'
+import * as Auth from './Auth.js'
+import * as Log from './Log.js'
+import * as Scope from '../Scope.js'
+import * as Viem from './Viem.js'
+import * as TestApp from '../../test/App.js'
+import { createClient as createMppClient } from '../../test/Mppx.js'
+import * as Tempo from '../../test/Tempo.js'
+
+const key = {
+  environment: 'production',
+  id: 'key_test',
+  name: 'Test key',
+  orgId: 'org_test',
+  scopes: ['data:read'],
+} satisfies ApiKey.ApiKey
+
+const token = 'secret_test_key'
+
+describe('require', () => {
+  describe('apiKey', () => {
+    test('accepts API key from tempo-api-key', async () => {
+      const app = createApp()
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+
+    test('accepts bearer API key when authorization is not payment', async () => {
+      const app = createApp()
+      const response = await app.request('/protected', {
+        headers: { authorization: `Bearer ${token}` },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+
+    test('does not parse payment authorization as bearer fallback', async () => {
+      const app = createApp()
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Payment paid' },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_missing",
+            "message": "Missing API key",
+          },
+        }
+      `)
+    })
+
+    test('accepts API key from deprecated key query param', async () => {
+      const app = createApp()
+      const response = await app.request(`/protected?key=${token}`)
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+
+    test('strips the deprecated key query param before route validation', async () => {
+      // Regression: route query schemas are strict (`z.strictObject`), so the
+      // `key` auth param must be removed from the URL once consumed — otherwise
+      // the downstream validator rejects it as `query_invalid` and the legacy
+      // `?key=...` lane breaks on every strict-query endpoint.
+      const auth = {
+        apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+        rateLimit: RateLimit.memory(),
+      }
+      const app = new Hono<Auth.Environment>()
+      app.use('*', async (c, next) => {
+        c.set('auth', auth)
+        await next()
+      })
+      app.use('/strict', Auth.require({ apiKey: { scopes: ['data:read'] } }))
+      app.get('/strict', (c) =>
+        c.json({ key: c.req.query('key') ?? null, limit: c.req.query('limit') ?? null }),
+      )
+
+      const response = await app.request(`/strict?limit=5&key=${token}`)
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "key": null,
+          "limit": "5",
+        }
+      `)
+    })
+
+    test('rejects invalid API key without falling back to public quota', async () => {
+      const app = createApp({
+        policy: {
+          apiKey: { scopes: ['data:read'] },
+          public: { rateLimit: { perMinute: 60 } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': 'wrong' },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_invalid",
+            "message": "Invalid API key",
+          },
+        }
+      `)
+    })
+
+    test('records auth error codes for request logs', async () => {
+      const entries: Log.Entry[] = []
+      const app = createApp({
+        logger: (entry) => void entries.push(entry),
+        policy: {
+          apiKey: { scopes: ['data:read'] },
+          public: { rateLimit: { perMinute: 60 } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': 'wrong' },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(entries[0]?.errorCode).toMatchInlineSnapshot(`"api_key_invalid"`)
+    })
+
+    test('records resolved key principal for forbidden-scope logs', async () => {
+      const entries: Log.Entry[] = []
+      const app = createApp({
+        logger: (entry) => void entries.push(entry),
+        policy: { apiKey: { scopes: ['webhooks:write'] } },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`403`)
+      expect(entries[0]?.errorCode).toMatchInlineSnapshot(`"api_key_forbidden"`)
+      expect(entries[0]?.principal).toMatchInlineSnapshot(`
+        {
+          "environment": "production",
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+
+    test('rejects malformed API key', async () => {
+      const app = createApp()
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Basic wrong' },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`400`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_malformed",
+            "message": "Malformed API key",
+          },
+        }
+      `)
+    })
+
+    test('rejects missing API key when no public or payment lane exists', async () => {
+      const app = createApp()
+      const response = await app.request('/protected')
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_missing",
+            "message": "Missing API key",
+          },
+        }
+      `)
+    })
+
+    test('rejects missing scope', async () => {
+      const app = createApp({
+        policy: { apiKey: { scopes: ['webhooks:write'] } },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`403`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_forbidden",
+            "message": "API key missing required scope",
+          },
+        }
+      `)
+    })
+
+    test('wildcard scope satisfies any required scope', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            source: TestApp.source({
+              keys: [{ ...key, scopes: [Scope.wildcard], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+        policy: {
+          apiKey: { scopes: ['data:read', 'webhooks:write'] },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+  })
+
+  describe('environment', () => {
+    const sandboxToken = 'secret_sandbox'
+
+    function createChainApp(options: { public?: boolean } = {}) {
+      const auth: Auth.Context = {
+        apiKey: {
+          source: TestApp.source({
+            keys: [
+              { ...key, scopes: [Scope.wildcard], token },
+              {
+                environment: 'sandbox',
+                id: 'key_sandbox',
+                orgId: 'org_test',
+                scopes: [Scope.wildcard],
+                token: sandboxToken,
+              },
+            ],
+          }),
+        },
+        rateLimit: RateLimit.memory(),
+      }
+      const policy: Auth.require.Policy = {
+        apiKey: { scopes: [Scope.wildcard] },
+        ...(options.public === false ? {} : { public: { rateLimit: { perMinute: 60 } } }),
+      }
+      const app = new Hono<Auth.Environment>()
+      app.use('*', async (c, next) => {
+        c.set('auth', auth)
+        // Mirror the app default so sandbox steering toward testnet is observable.
+        c.set('chainId' as never, Viem.defaultChainId as never)
+        await next()
+      })
+      app.use('/protected', Auth.require(policy))
+      app.get('/protected', (c) => {
+        // Mirror how real handlers resolve the effective chain: explicit query
+        // wins, else the context default (which auth may steer to testnet).
+        const raw = c.req.query('chainId')
+        const chainId = raw ? Number(raw) : ((c.get('chainId' as never) as number | null) ?? null)
+        return c.json({ chainId, principal: Auth.getPrincipal(c)?.type ?? null })
+      })
+      return app
+    }
+
+    test('falls through to the public policy for a sandbox key on explicit mainnet', async () => {
+      const app = createChainApp()
+      const response = await app.request('/protected?chainId=4217', {
+        headers: { 'tempo-api-key': sandboxToken },
+      })
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      // Treated as anonymous (public) rather than rejected; chain stays mainnet.
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "chainId": 4217,
+          "principal": "public",
+        }
+      `)
+    })
+
+    test('falls through to the public policy for a sandbox key on the mainnet alias', async () => {
+      const app = createChainApp()
+      const response = await app.request('/protected?chainId=mainnet', {
+        headers: { 'tempo-api-key': sandboxToken },
+      })
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect((await response.json()).principal).toMatchInlineSnapshot(`"public"`)
+    })
+
+    test('a sandbox key on mainnet with no public lane is rejected as missing', async () => {
+      const app = createChainApp({ public: false })
+      const response = await app.request('/protected?chainId=4217', {
+        headers: { 'tempo-api-key': sandboxToken },
+      })
+      // With no public lane, the public policy closes to "missing API key".
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_missing",
+            "message": "Missing API key",
+          },
+        }
+      `)
+    })
+
+    test('uses a sandbox key on an explicit non-mainnet chain', async () => {
+      const app = createChainApp()
+      const response = await app.request('/protected?chainId=42431', {
+        headers: { 'tempo-api-key': sandboxToken },
+      })
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "chainId": 42431,
+          "principal": "api_key",
+        }
+      `)
+    })
+
+    test('defaults a sandbox key with no chain to testnet', async () => {
+      const app = createChainApp()
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': sandboxToken },
+      })
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "chainId": 42431,
+          "principal": "api_key",
+        }
+      `)
+    })
+
+    test('uses a production key on mainnet', async () => {
+      const app = createChainApp()
+      const response = await app.request('/protected?chainId=4217', {
+        headers: { 'tempo-api-key': token },
+      })
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "chainId": 4217,
+          "principal": "api_key",
+        }
+      `)
+    })
+  })
+
+  describe('mpp', () => {
+    test('returns payment challenge for public over-quota requests', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await app.request('/protected')
+
+      expect(response.status).toMatchInlineSnapshot(`402`)
+      expect(
+        response.headers.get('www-authenticate')?.startsWith('Payment '),
+      ).toMatchInlineSnapshot(`true`)
+    })
+
+    test('accepts paid public retry without consuming quota', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaOnce(),
+        },
+        policy: {
+          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await createMppClient(app).fetch('http://tempo-api.test/protected')
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.has('payment-receipt')).toMatchInlineSnapshot(`true`)
+      expect(normalizePaymentPayer(body)).toMatchInlineSnapshot(`
+        {
+          "id": "anonymous",
+          "payment": {
+            "payer": "did:pkh:eip155:...:0x...",
+            "reason": "public_over_quota",
+            "type": "mpp",
+          },
+          "type": "public",
+        }
+      `)
+    })
+
+    test('returns payment challenge for API-key over-quota requests', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          apiKey: {
+            rateLimit: { perMinute: 1 },
+            scopes: ['data:read'],
+          },
+          mpp: { charge: { amount: '1', description: 'Protected data' } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`402`)
+      expect(
+        response.headers.get('www-authenticate')?.startsWith('Payment '),
+      ).toMatchInlineSnapshot(`true`)
+    })
+
+    test('accepts paid API-key overflow retry', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaOnce(),
+        },
+        policy: {
+          apiKey: {
+            rateLimit: { perMinute: 1 },
+            scopes: ['data:read'],
+          },
+          mpp: { charge: { amount: '1', description: 'Protected data' } },
+        },
+      })
+      const response = await createMppClient(app).fetch('http://tempo-api.test/protected', {
+        headers: {
+          'tempo-api-key': token,
+        },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.has('payment-receipt')).toMatchInlineSnapshot(`true`)
+      expect(normalizePaymentPayer(body)).toMatchInlineSnapshot(`
+        {
+          "id": "key_test",
+          "orgId": "org_test",
+          "payment": {
+            "payer": "did:pkh:eip155:...:0x...",
+            "reason": "api_key_over_quota",
+            "type": "mpp",
+          },
+          "type": "api_key",
+        }
+      `)
+    })
+  })
+
+  describe('rateLimit', () => {
+    test('allows anonymous public requests under quota', async () => {
+      const app = createApp({
+        policy: { public: { rateLimit: { perMinute: 60 } } },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'x-forwarded-for': '203.0.113.10' },
+      })
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"60"`)
+      expect(response.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"59"`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": "203.0.113.10",
+          "type": "public",
+        }
+      `)
+    })
+
+    test('returns rate-limit error without payment context', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          rateLimit: overQuota(),
+        },
+        policy: { public: { rateLimit: { perMinute: 1 } } },
+      })
+      const response = await app.request('/protected')
+      const body = await response.json()
+
+      expect(response.status).toMatchInlineSnapshot(`429`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "rate_limit_exceeded",
+            "message": "Rate limit exceeded",
+          },
+        }
+      `)
+    })
+
+    test('fails open when the public rate-limit store errors', async () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+      try {
+        const app = createApp({
+          auth: {
+            apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+            rateLimit: {
+              async consume() {
+                throw new Error('Network connection lost.')
+              },
+            },
+          },
+          policy: { public: { rateLimit: { perMinute: 1 } } },
+        })
+        const response = await app.request('/protected', {
+          headers: { 'x-forwarded-for': '203.0.113.10' },
+        })
+        const body = await response.json()
+
+        expect(response.status).toMatchInlineSnapshot(`200`)
+        expect(response.headers.has('ratelimit-limit')).toMatchInlineSnapshot(`false`)
+        expect(body).toMatchInlineSnapshot(`
+          {
+            "id": "203.0.113.10",
+            "type": "public",
+          }
+        `)
+        expect(error.mock.calls.length).toMatchInlineSnapshot(`1`)
+      } finally {
+        error.mockRestore()
+      }
+    })
+
+    test('fails open when the API-key rate-limit store errors', async () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+      try {
+        const app = createApp({
+          auth: {
+            apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+            rateLimit: {
+              async consume() {
+                throw new Error('Network connection lost.')
+              },
+            },
+          },
+        })
+        const response = await app.request('/protected', {
+          headers: { 'tempo-api-key': token },
+        })
+
+        expect(response.status).toMatchInlineSnapshot(`200`)
+        expect(response.headers.has('ratelimit-limit')).toMatchInlineSnapshot(`false`)
+        expect(error.mock.calls.length).toMatchInlineSnapshot(`1`)
+      } finally {
+        error.mockRestore()
+      }
+    })
+  })
+
+  describe('rateLimit per-scope', () => {
+    test('consumes the route scope bucket and emits the scope header', async () => {
+      const app = createScopedApp({
+        routes: [{ path: '/protected', policy: { apiKey: { scopes: ['data:read'] } } }],
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"data:read"`)
+    })
+
+    test('does not share quota across scopes', async () => {
+      const auth = {
+        apiKey: {
+          rateLimits: { 'data:read': { perMinute: 1 }, 'webhooks:write': { perMinute: 1 } },
+          source: TestApp.source({
+            keys: [{ ...key, scopes: [Scope.wildcard], token }],
+          }),
+        },
+        rateLimit: RateLimit.memory(),
+      } satisfies Auth.Context
+      const app = createScopedApp({
+        auth,
+        routes: [
+          { path: '/read', policy: { apiKey: { scopes: ['data:read'] } } },
+          { path: '/write', policy: { apiKey: { scopes: ['webhooks:write'] } } },
+        ],
+      })
+
+      await app.request('/read', { headers: { 'tempo-api-key': token } })
+      const readAgain = await app.request('/read', { headers: { 'tempo-api-key': token } })
+      const write = await app.request('/write', { headers: { 'tempo-api-key': token } })
+
+      // Exhausting the `read` bucket leaves the `write` bucket untouched.
+      expect(readAgain.status).toMatchInlineSnapshot(`429`)
+      expect(write.status).toMatchInlineSnapshot(`200`)
+      expect(write.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"webhooks:write"`)
+    })
+
+    test('uses the * bucket for a zero-scope route', async () => {
+      const app = createScopedApp({
+        routes: [{ path: '/protected', policy: { apiKey: { scopes: [] } } }],
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"*"`)
+    })
+
+    test('buckets a multi-scope route by its first required scope', async () => {
+      const app = createScopedApp({
+        routes: [
+          { path: '/protected', policy: { apiKey: { scopes: ['data:read', 'webhooks:write'] } } },
+        ],
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"data:read"`)
+    })
+
+    test('route cap overrides the configured scope limit', async () => {
+      const auth = {
+        apiKey: {
+          rateLimits: { 'data:read': { perMinute: 1_000 } },
+          source: TestApp.source({
+            keys: [{ ...key, scopes: [Scope.wildcard], token }],
+          }),
+        },
+        rateLimit: RateLimit.memory(),
+      } satisfies Auth.Context
+      const app = createScopedApp({
+        auth,
+        routes: [
+          {
+            path: '/protected',
+            policy: { apiKey: { rateLimit: { perMinute: 5 }, scopes: ['data:read'] } },
+          },
+        ],
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"5"`)
+      expect(response.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"data:read"`)
+    })
+
+    test('per-key default overrides config default but not a route cap', async () => {
+      const source = TestApp.source({
+        keys: [
+          {
+            ...key,
+            rateLimits: { '*': { perMinute: 7 } },
+            scopes: [Scope.wildcard],
+            token,
+          },
+        ],
+      })
+
+      const open = createScopedApp({
+        auth: {
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          rateLimit: RateLimit.memory(),
+        },
+        routes: [{ path: '/protected', policy: { apiKey: { scopes: ['data:read'] } } }],
+      })
+      const openResponse = await open.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      const capped = createScopedApp({
+        auth: {
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          rateLimit: RateLimit.memory(),
+        },
+        routes: [
+          {
+            path: '/protected',
+            policy: { apiKey: { rateLimit: { perMinute: 5 }, scopes: ['data:read'] } },
+          },
+        ],
+      })
+      const cappedResponse = await capped.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      // Per-key `'*'` beats the config default (1000)…
+      expect(openResponse.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"7"`)
+      // …but a route's protective cap (5) still wins over it.
+      expect(cappedResponse.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"5"`)
+    })
+
+    test('per-key per-scope overrides everything including a route cap', async () => {
+      const auth = {
+        apiKey: {
+          source: TestApp.source({
+            keys: [
+              {
+                ...key,
+                rateLimits: { 'data:read': { perMinute: 9 } },
+                scopes: [Scope.wildcard],
+                token,
+              },
+            ],
+          }),
+        },
+        rateLimit: RateLimit.memory(),
+      } satisfies Auth.Context
+      const app = createScopedApp({
+        auth,
+        routes: [
+          {
+            path: '/protected',
+            policy: { apiKey: { rateLimit: { perMinute: 5 }, scopes: ['data:read'] } },
+          },
+        ],
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"9"`)
+    })
+
+    test('emits the scope header alongside a 429 over-quota error', async () => {
+      const entries: Log.Entry[] = []
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          rateLimit: overQuota(),
+        },
+        logger: (entry) => void entries.push(entry),
+        policy: { apiKey: { rateLimit: { perMinute: 1 }, scopes: ['data:read'] } },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toMatchInlineSnapshot(`429`)
+      expect(response.headers.get('ratelimit-scope')).toMatchInlineSnapshot(`"data:read"`)
+      expect(response.headers.get('ratelimit-limit')).toMatchInlineSnapshot(`"1"`)
+      expect(entries[0]?.principal).toMatchInlineSnapshot(`
+        {
+          "environment": "production",
+          "id": "key_test",
+          "orgId": "org_test",
+          "type": "api_key",
+        }
+      `)
+    })
+
+    test('still returns a protocol-native payment challenge on overflow', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          apiKey: { rateLimit: { perMinute: 1 }, scopes: ['data:read'] },
+          mpp: { charge: { amount: '1', description: 'Protected data' } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      // The 402 challenge is owned by the payment protocol (mppx returns its own
+      // Response), so rate-limit headers ride the 429 path, not the challenge.
+      expect(response.status).toMatchInlineSnapshot(`402`)
+      expect(
+        response.headers.get('www-authenticate')?.startsWith('Payment '),
+      ).toMatchInlineSnapshot(`true`)
+    })
+  })
+})
+
+function createScopedApp(options: {
+  auth?: Auth.Context | undefined
+  routes: readonly { path: string; policy: Auth.require.Policy }[]
+}) {
+  const auth = options.auth ?? {
+    apiKey: {
+      source: TestApp.source({ keys: [{ ...key, scopes: [Scope.wildcard], token }] }),
+    },
+    rateLimit: RateLimit.memory(),
+  }
+  const app = new Hono<Auth.Environment>()
+
+  app.use('*', async (c, next) => {
+    c.set('auth', auth)
+    await next()
+  })
+  for (const route of options.routes) {
+    app.use(route.path, Auth.require(route.policy))
+    app.get(route.path, (c) => c.json(serializePrincipal(Auth.getPrincipal(c))))
+  }
+
+  return app
+}
+
+type Options = {
+  auth?: Auth.Context | undefined
+  logger?: Log.Emit | undefined
+  policy?: Auth.require.Policy | undefined
+}
+
+function createApp(options: Options = {}) {
+  const auth = options.auth ?? {
+    apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+    rateLimit: RateLimit.memory(),
+  }
+  const app = new Hono<Auth.Environment>()
+
+  if (options.logger) {
+    app.use('*', requestId())
+    app.use('*', Log.middleware({ emit: options.logger }))
+  }
+  app.use('*', async (c, next) => {
+    c.set('auth', auth)
+    await next()
+  })
+  app.use('/protected', Auth.require(options.policy ?? { apiKey: { scopes: ['data:read'] } }))
+  app.get('/protected', (c) => c.json(serializePrincipal(Auth.getPrincipal(c))))
+
+  return app
+}
+
+function createMppServer() {
+  return Mppx.create({
+    methods: [
+      tempo.charge({
+        chainId: Tempo.chain.id,
+        currency: Tempo.currency,
+        decimals: 6,
+        getClient: () => Tempo.client,
+        recipient: Tempo.accounts[2].address,
+      }),
+    ],
+    realm: 'tempo-api-test',
+    secretKey: 'secret_test_key_0123456789abcdef',
+  })
+}
+
+function overQuota(): RateLimit.Store {
+  return {
+    async consume(options) {
+      return {
+        allowed: false,
+        limit: options.limit.perMinute,
+        remaining: 0,
+        reset: Math.ceil(Date.now() / 1_000) + 60,
+      }
+    },
+  }
+}
+
+function overQuotaOnce(): RateLimit.Store {
+  let consumed = false
+  return {
+    async consume(options) {
+      if (consumed) throw new Error('rate limit should not be consumed after payment')
+      consumed = true
+      return {
+        allowed: false,
+        limit: options.limit.perMinute,
+        remaining: 0,
+        reset: Math.ceil(Date.now() / 1_000) + 60,
+      }
+    },
+  }
+}
+
+function serializePrincipal(principal: Auth.Principal | null) {
+  if (!principal) return null
+  const payment = principal.payment ? { payment: principal.payment } : {}
+
+  if (principal.type === 'api_key')
+    return {
+      id: principal.id,
+      orgId: principal.orgId,
+      ...payment,
+      type: principal.type,
+    }
+
+  return {
+    id: principal.id,
+    ...payment,
+    type: principal.type,
+  }
+}
+
+function normalizePaymentPayer(value: unknown) {
+  if (!isRecord(value) || !isRecord(value['payment'])) return value
+
+  // The payer account is generated from a random mnemonic each run. Keep the
+  // chain-qualified DID shape in snapshots without pinning the address.
+  return {
+    ...value,
+    payment: {
+      ...value['payment'],
+      payer:
+        typeof value['payment']['payer'] === 'string'
+          ? value['payment']['payer'].replace(
+              /^did:pkh:eip155:\d+:0x[0-9a-fA-F]{40}$/,
+              'did:pkh:eip155:...:0x...',
+            )
+          : value['payment']['payer'],
+    },
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}