tapimo 0.4.1 → 0.4.4

package/src/internal/Auth.test.ts

@@ -1,14 +1,23 @@
-import { Hono } from 'hono'
+import { Hono, type Context } from 'hono'
 import { requestId } from 'hono/request-id'
+import { Challenge, Receipt } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
-import { RateLimit } from 'tapimo'
+import type { Session } from 'mppx/tempo'
+import { RateLimit, Store } from 'tapimo'
+import { Actions } from 'viem/tempo'
 import * as ApiKey from '../ApiKey.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'
+import * as Projects from '../db/tables/projects.js'
+import * as Users from '../db/tables/users.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 TestStore from '../../test/Store.js'
 import * as Tempo from '../../test/Tempo.js'
 
 const key = {
@@ -75,12 +84,13 @@ describe('require', () => {
       `)
     })
 
-    test('accepts API key from deprecated key query param', async () => {
+    test('accepts API key from 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(response.headers.get('cache-control')).toMatchInlineSnapshot(`"private"`)
       expect(body).toMatchInlineSnapshot(`
         {
           "id": "key_test",
@@ -90,11 +100,30 @@ describe('require', () => {
       `)
     })
 
-    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.
+    test('keeps query-authenticated responses private after downstream caching', async () => {
+      const auth = {
+        apiKey: { resolve: TestApp.resolver({ 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('/cached', Auth.require({ apiKey: { scopes: ['data:read'] } }))
+      app.get('/cached', (c) => {
+        c.header('Cache-Control', 'public, max-age=86400')
+        return c.json({ ok: true })
+      })
+
+      const response = await app.request(`/cached?key=${token}`)
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('cache-control')).toMatchInlineSnapshot(`"private"`)
+    })
+
+    test('strips the key query param before route validation', async () => {
+      // Auth owns `key`, so strict route schemas must not see it.
       const auth = {
         apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
         rateLimit: RateLimit.memory(),
@@ -534,7 +563,7 @@ describe('require', () => {
       const policy: Auth.require.Policy = {
         apiKey: { scopes: [Scope.wildcard] },
         ...(options.public === false ? {} : { public: { rateLimit: { perMinute: 60 } } }),
-        ...(options.mpp ? { mpp: { charge: { amount: '1' } } } : {}),
+        ...(options.mpp ? { mpp: { session: { amount: '1' } } } : {}),
       }
       const app = new Hono<Auth.Environment>()
       app.use('*', async (c, next) => {
@@ -714,6 +743,121 @@ describe('require', () => {
   })
 
   describe('mpp', () => {
+    test('uses a default paid-request limit of 100 per minute', async () => {
+      const rateLimit = underQuota()
+      const consume = vi.spyOn(rateLimit, 'consume')
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppHandler(),
+          rateLimit,
+        },
+        policy: { mpp: { session: { amount: '1' } } },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          authorization: 'Payment paid',
+          'x-forwarded-for': '203.0.113.10',
+        },
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('RateLimit-Limit')).toBe('100')
+      expect(response.headers.get('RateLimit-Scope')).toBe('mpp')
+      expect(consume).toHaveBeenCalledWith({
+        key: 'mpp:public:203.0.113.10',
+        limit: { perMinute: 100 },
+      })
+    })
+
+    test('buckets paid API-key requests by key ID', async () => {
+      const rateLimit = underQuota()
+      const consume = vi.spyOn(rateLimit, 'consume')
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppHandler(),
+          rateLimit,
+        },
+        policy: {
+          apiKey: { scopes: ['data:read'] },
+          mpp: { session: { amount: '1' } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          authorization: 'Payment paid',
+          'tempo-api-key': token,
+          'x-forwarded-for': '203.0.113.10',
+        },
+      })
+
+      expect(response.status).toBe(200)
+      expect(consume).toHaveBeenCalledWith({
+        key: 'mpp:api_key:key_test',
+        limit: { perMinute: 100 },
+      })
+    })
+
+    test('uses the configured global paid-request limit', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppHandler({ rateLimit: { perMinute: 25 } }),
+          rateLimit: underQuota(),
+        },
+        policy: { mpp: { session: { amount: '1' } } },
+      })
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Payment paid' },
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('RateLimit-Limit')).toBe('25')
+    })
+
+    test('route paid-request limit overrides the global limit', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppHandler({ rateLimit: { perMinute: 25 } }),
+          rateLimit: underQuota(),
+        },
+        policy: {
+          mpp: {
+            rateLimit: { perMinute: 5 },
+            session: { amount: '1' },
+          },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Payment paid' },
+      })
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('RateLimit-Limit')).toBe('5')
+    })
+
+    test('rejects paid requests over quota before accepting payment', async () => {
+      const onPayment = vi.fn()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppHandler({ onPayment }),
+          rateLimit: overQuota(),
+        },
+        policy: { mpp: { session: { amount: '1' } } },
+      })
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Payment paid' },
+      })
+
+      expect(response.status).toBe(429)
+      expect(response.headers.get('RateLimit-Limit')).toBe('100')
+      expect((await response.json()).error.code).toBe('rate_limit_exceeded')
+      expect(onPayment).not.toHaveBeenCalled()
+    })
+
     test('returns payment challenge for public over-quota requests', async () => {
       const mpp = createMppServer()
       const app = createApp({
@@ -723,7 +867,7 @@ describe('require', () => {
           rateLimit: overQuota(),
         },
         policy: {
-          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          mpp: { session: { amount: '1', description: 'Protected data' } },
           public: { rateLimit: { perMinute: 1 } },
         },
       })
@@ -735,16 +879,16 @@ describe('require', () => {
       ).toMatchInlineSnapshot(`true`)
     })
 
-    test('accepts paid public retry without consuming quota', async () => {
+    test('accepts paid public retry without consuming public quota', async () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
           apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
-          rateLimit: overQuotaOnce(),
+          rateLimit: overQuotaExceptMpp(),
         },
         policy: {
-          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          mpp: { session: { amount: '1', description: 'Protected data' } },
           public: { rateLimit: { perMinute: 1 } },
         },
       })
@@ -779,7 +923,7 @@ describe('require', () => {
             rateLimit: { perMinute: 1 },
             scopes: ['data:read'],
           },
-          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          mpp: { session: { amount: '1', description: 'Protected data' } },
         },
       })
       const response = await app.request('/protected', {
@@ -798,14 +942,14 @@ describe('require', () => {
         auth: {
           apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
-          rateLimit: overQuotaOnce(),
+          rateLimit: overQuotaExceptMpp(),
         },
         policy: {
           apiKey: {
             rateLimit: { perMinute: 1 },
             scopes: ['data:read'],
           },
-          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          mpp: { session: { amount: '1', description: 'Protected data' } },
         },
       })
       const response = await createMppClient(app).fetch('http://tempo-api.test/protected', {
@@ -830,6 +974,220 @@ describe('require', () => {
         }
       `)
     })
+
+    test('session challenge advertises the configured request defaults', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await app.request('/protected')
+      const challenge = Challenge.fromHeaders(response.headers)
+
+      expect(response.status).toBe(402)
+      expect(challenge.method).toBe('tempo')
+      expect(challenge.intent).toBe('session')
+      expect(challenge.realm).toBe('tempo-api-test')
+      expect(challenge.description).toBe('Protected data')
+      expect(challenge.request).toMatchObject({
+        // Wire amounts are raw token units: '1' at 6 decimals.
+        amount: '1000000',
+        currency: Tempo.currency,
+        methodDetails: {
+          chainId: Tempo.chain.id,
+          escrowContract: '0x4d50500000000000000000000000000000000000',
+          sessionProtocol: 'v2',
+        },
+        recipient: Tempo.accounts[2].address,
+        unitType: 'request',
+      })
+    })
+
+    test('route session overrides propagate to the challenge', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          mpp: { session: { amount: '2.5', suggestedDeposit: '10' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await app.request('/protected')
+      const challenge = Challenge.fromHeaders(response.headers)
+
+      expect(response.status).toBe(402)
+      expect(challenge.request).toMatchObject({
+        // Wire amounts are raw token units at 6 decimals.
+        amount: '2500000',
+        suggestedDeposit: '10000000',
+      })
+    })
+
+    test('paid retry opens a funded on-chain channel', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', description: 'Protected data' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await createMppClient(app).fetch('http://tempo-api.test/protected')
+
+      expect(response.status).toBe(200)
+      const receipt = sessionReceipt(response)
+      expect(receipt.method).toBe('tempo')
+      expect(receipt.intent).toBe('session')
+      expect(receipt.status).toBe('success')
+      expect(receipt.channelId).toMatch(/^0x[0-9a-fA-F]{64}$/)
+      // One paid request at amount '1' with 6 decimals.
+      expect(receipt.spent).toBe('1000000')
+      expect(BigInt(receipt.acceptedCumulative)).toBeGreaterThanOrEqual(1_000_000n)
+
+      const state = await Actions.channel.getStates(Tempo.client, {
+        channel: receipt.channelId,
+      })
+      // 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.closeRequestedAt).toBe(0)
+    })
+
+    test('reuses the session channel across paid requests', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          // The suggested deposit pre-funds the channel for both requests.
+          mpp: { session: { amount: '1', suggestedDeposit: '2' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const client = createMppClient(app)
+
+      const first = await client.fetch('http://tempo-api.test/protected')
+      const second = await client.fetch('http://tempo-api.test/protected')
+
+      expect(first.status).toBe(200)
+      expect(second.status).toBe(200)
+
+      const receipt1 = sessionReceipt(first)
+      const receipt2 = sessionReceipt(second)
+      expect(receipt2.channelId).toBe(receipt1.channelId)
+      expect(BigInt(receipt2.acceptedCumulative)).toBeGreaterThan(
+        BigInt(receipt1.acceptedCumulative),
+      )
+      expect(receipt2.spent).toBe('2000000')
+
+      const state = await Actions.channel.getStates(Tempo.client, {
+        channel: receipt1.channelId,
+      })
+      expect(state.deposit).toBe(2_000_000n)
+    })
+
+    test('reuses persisted session state after server restart', async () => {
+      const { namespace } = TestStore.durableObjectNamespace()
+      const createStore = () => Store.durableObject(namespace)
+      let app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppServer({ store: createStore() }),
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', suggestedDeposit: '2' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const client = createMppClient({ fetch: (request) => app.fetch(request) })
+
+      const first = await client.fetch('http://tempo-api.test/protected')
+      app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp: createMppServer({ store: createStore() }),
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1', suggestedDeposit: '2' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const second = await client.fetch('http://tempo-api.test/protected')
+
+      expect(first.status).toBe(200)
+      expect(second.status).toBe(200)
+      expect(sessionReceipt(second)).toMatchObject({
+        channelId: sessionReceipt(first).channelId,
+        spent: '2000000',
+      })
+    })
+
+    test('rejects a voucher that exceeds the channel deposit', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuotaExceptMpp(),
+        },
+        policy: {
+          mpp: { session: { amount: '1' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const client = createMppClient(app)
+
+      // The opening deposit covers one request; the second voucher overruns
+      // it and the low-level client cannot top up, so the server re-challenges.
+      const first = await client.fetch('http://tempo-api.test/protected')
+      const second = await client.fetch('http://tempo-api.test/protected')
+
+      expect(first.status).toBe(200)
+      expect(second.status).toBe(402)
+      expect(second.headers.get('www-authenticate')?.startsWith('Payment ')).toBe(true)
+    })
+
+    test('rejects a malformed payment credential with a fresh challenge', async () => {
+      const mpp = createMppServer()
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: underQuota(),
+        },
+        policy: {
+          mpp: { session: { amount: '1' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { authorization: 'Payment not-a-credential' },
+      })
+
+      expect(response.status).toBe(402)
+      expect(response.headers.get('www-authenticate')?.startsWith('Payment ')).toBe(true)
+    })
   })
 
   describe('rateLimit', () => {
@@ -1281,7 +1639,7 @@ describe('require', () => {
         },
         policy: {
           apiKey: { rateLimit: { perMinute: 1 }, scopes: ['data:read'] },
-          mpp: { charge: { amount: '1', description: 'Protected data' } },
+          mpp: { session: { amount: '1', description: 'Protected data' } },
         },
       })
       const response = await app.request('/protected', {
@@ -1298,6 +1656,87 @@ describe('require', () => {
   })
 })
 
+describe('ensureProject', () => {
+  test('authorizes a flat project route against the API key organization', async () => {
+    const db = TestApp.database()
+    const organization = await Organizations.create(db, { id: key.orgId, name: 'Test org' })
+    const project = await Projects.create(db, { name: 'Test project', orgId: organization.id })
+    const response = await createProjectGuardApp(db, apiKeyPrincipal(organization.id)).request(
+      `/v1/projects/${project.id}/resource`,
+    )
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(await response.json()).toEqual({
+      membership: null,
+      orgId: organization.id,
+      projectId: project.id,
+    })
+  })
+
+  test('hides a flat project from an API key in another organization', async () => {
+    const db = TestApp.database()
+    const organization = await Organizations.create(db, { id: key.orgId, name: 'Test org' })
+    const project = await Projects.create(db, { name: 'Test project', orgId: organization.id })
+    const response = await createProjectGuardApp(db, apiKeyPrincipal('org_foreign')).request(
+      `/v1/projects/${project.id}/resource`,
+    )
+
+    expect(response.status).toMatchInlineSnapshot(`404`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "project_not_found",
+          "message": "Project not found",
+        },
+      }
+    `)
+  })
+
+  test('resolves session membership for a flat project route', async () => {
+    const db = TestApp.database()
+    const user = await Users.upsertByAddress(db, {
+      address: '0x0000000000000000000000000000000000000001',
+    })
+    const organization = await Organizations.create(db, { name: 'Test org' })
+    await Memberships.create(db, { orgId: organization.id, role: 'member', userId: user.id })
+    const project = await Projects.create(db, { name: 'Test project', orgId: organization.id })
+    const response = await createProjectGuardApp(db, sessionPrincipal(user.id)).request(
+      `/v1/projects/${project.id}/resource`,
+    )
+    const body = (await response.json()) as Record<string, unknown>
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(body).toEqual({
+      membership: 'member',
+      orgId: organization.id,
+      projectId: project.id,
+    })
+  })
+
+  test('preserves nested organization role authorization', async () => {
+    const db = TestApp.database()
+    const user = await Users.upsertByAddress(db, {
+      address: '0x0000000000000000000000000000000000000001',
+    })
+    const organization = await Organizations.create(db, { name: 'Test org' })
+    await Memberships.create(db, { orgId: organization.id, role: 'member', userId: user.id })
+    const project = await Projects.create(db, { name: 'Test project', orgId: organization.id })
+    const response = await createNestedProjectGuardApp(db, sessionPrincipal(user.id)).request(
+      `/v1/orgs/${organization.id}/projects/${project.id}/resource`,
+    )
+
+    expect(response.status).toMatchInlineSnapshot(`403`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "forbidden",
+          "message": "Requires the admin role",
+        },
+      }
+    `)
+  })
+})
+
 function createScopedApp(options: {
   auth?: Auth.Context | undefined
   routes: readonly { path: string; policy: Auth.require.Policy }[]
@@ -1322,6 +1761,67 @@ function createScopedApp(options: {
   return app
 }
 
+type GuardEnvironment = {
+  Variables: Auth.Variables & { db: Db.Source }
+}
+
+function createProjectGuardApp(db: Db.Source, principal: Auth.Principal) {
+  const app = new Hono<GuardEnvironment>()
+  app.use('*', async (c, next) => {
+    c.set('db', db)
+    c.set('principal', principal)
+    await next()
+  })
+  app.get('/v1/projects/:projectId/resource', Auth.ensureProject(), projectGuardHandler)
+  return app
+}
+
+function createNestedProjectGuardApp(db: Db.Source, principal: Auth.Principal) {
+  const app = new Hono<GuardEnvironment>()
+  app.use('*', async (c, next) => {
+    c.set('db', db)
+    c.set('principal', principal)
+    await next()
+  })
+  app.get(
+    '/v1/orgs/:orgId/projects/:projectId/resource',
+    Auth.ensureOrg({ role: 'admin' }),
+    Auth.ensureProject(),
+    projectGuardHandler,
+  )
+  return app
+}
+
+function projectGuardHandler(c: Context<GuardEnvironment>) {
+  return c.json({
+    membership: Auth.membership(c)?.role ?? null,
+    orgId: Auth.org(c).id,
+    projectId: Auth.project(c).id,
+  })
+}
+
+function apiKeyPrincipal(orgId: string): Auth.Principal {
+  const apiKey = { ...key, orgId }
+  return {
+    apiKey,
+    environment: apiKey.environment,
+    id: apiKey.id,
+    orgId,
+    type: 'api_key',
+  }
+}
+
+function sessionPrincipal(id: string): Auth.Principal {
+  return {
+    id,
+    identity: {
+      provider: 'wallet',
+      subject: '0x0000000000000000000000000000000000000001',
+    },
+    type: 'session',
+  }
+}
+
 type Options = {
   auth?: Auth.Context | undefined
   logger?: Log.Emit | undefined
@@ -1349,15 +1849,18 @@ function createApp(options: Options = {}) {
   return app
 }
 
-function createMppServer() {
+function createMppServer(options: createMppServer.Options = {}) {
   return Mppx.create({
     methods: [
-      tempo.charge({
+      tempo.session({
+        bootstrap: false,
         chainId: Tempo.chain.id,
         currency: Tempo.currency,
         decimals: 6,
         getClient: () => Tempo.client,
         recipient: Tempo.accounts[2].address,
+        ...options,
+        unitType: 'request',
       }),
     ],
     realm: 'tempo-api-test',
@@ -1365,6 +1868,34 @@ function createMppServer() {
   })
 }
 
+declare namespace createMppServer {
+  type Options = Pick<NonNullable<Parameters<typeof tempo.session>[0]>, 'store'>
+}
+
+function createMppHandler(
+  options: createMppHandler.Options = {},
+): NonNullable<Auth.Context['mpp']> {
+  return {
+    ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
+    session: () => async (_c, next) => {
+      options.onPayment?.()
+      await next()
+    },
+  }
+}
+
+declare namespace createMppHandler {
+  type Options = {
+    onPayment?: (() => void) | undefined
+    rateLimit?: RateLimit.Limit | undefined
+  }
+}
+
+/** Reads the session receipt attached to a paid response. */
+function sessionReceipt(response: Response) {
+  return Receipt.fromResponse(response) as Session.Precompile.Protocol.SessionReceipt
+}
+
 function overQuota(): RateLimit.Store {
   return {
     async consume(options) {
@@ -1378,12 +1909,29 @@ function overQuota(): RateLimit.Store {
   }
 }
 
-function overQuotaOnce(): RateLimit.Store {
-  let consumed = false
+function underQuota(): RateLimit.Store {
+  return {
+    async consume(options) {
+      return {
+        allowed: true,
+        limit: options.limit.perMinute,
+        remaining: Math.max(options.limit.perMinute - 1, 0),
+        reset: Math.ceil(Date.now() / 1_000) + 60,
+      }
+    },
+  }
+}
+
+function overQuotaExceptMpp(): RateLimit.Store {
   return {
     async consume(options) {
-      if (consumed) throw new Error('rate limit should not be consumed after payment')
-      consumed = true
+      if (options.key.startsWith('mpp:'))
+        return {
+          allowed: true,
+          limit: options.limit.perMinute,
+          remaining: Math.max(options.limit.perMinute - 1, 0),
+          reset: Math.ceil(Date.now() / 1_000) + 60,
+        }
       return {
         allowed: false,
         limit: options.limit.perMinute,