tapimo 0.7.2 → 0.8.0

package/src/db/tables/fundingDeposits.test.ts

@@ -77,6 +77,79 @@ describe('listByAddress', () => {
   })
 })
 
+describe('listByRecipient', () => {
+  test('pages recipient deposits across addresses and hides foreign ownership', async () => {
+    const recipient = '0xABcdEFABcdEFabcdEfAbCdefabcdeFABcDEFabCD'
+    const firstAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_first', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const secondAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_second', name: 'Relay' },
+        recipient,
+        subsidize: true,
+      }),
+    })
+    const first = await seedDeposit(firstAddress)
+    const second = await seedDeposit(secondAddress)
+    const third = await seedDeposit(firstAddress)
+    const unrelatedAddress = await seedAddress()
+    await seedDeposit(unrelatedAddress)
+    const foreignAddress = await seedAddress({
+      orgId: 'org_other',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_foreign', name: 'Relay' },
+        recipient,
+      }),
+    })
+    await seedDeposit(foreignAddress)
+
+    const page = await FundingDeposits.listByRecipient(db, {
+      limit: 2,
+      owner,
+      recipient: recipient.toLowerCase(),
+    })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id])
+    const rest = await FundingDeposits.listByRecipient(db, {
+      cursor: { createdAt: second.createdAt, id: second.id },
+      limit: 2,
+      owner,
+      recipient: recipient.toLowerCase(),
+    })
+    expect(rest.map((row) => row.id)).toEqual([first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const recipient = `0x${'ab'.repeat(20)}`
+    const firstAddress = await seedAddress({
+      projectId: 'prj_deposit',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_project', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const secondAddress = await seedAddress({
+      projectId: 'prj_other',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_other_project', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const first = await seedDeposit(firstAddress)
+    await seedDeposit(secondAddress)
+
+    const rows = await FundingDeposits.listByRecipient(db, {
+      limit: 10,
+      owner: { ...owner, projectId: 'prj_deposit' },
+      recipient,
+    })
+    expect(rows.map((row) => row.id)).toEqual([first.id])
+  })
+})
+
 describe('getOwned', () => {
   test('returns owned deposits and hides foreign ownership', async () => {
     const address = await seedAddress()
@@ -227,6 +300,71 @@ describe('update', () => {
   })
 })
 
+describe('recordRequestObservation', () => {
+  test('attaches the first poll and webhook timestamps without changing material state', async () => {
+    const address = await seedAddress()
+    const record = await seedDeposit(address, { providerRequestId: 'relay_observed' })
+    await FundingDeposits.recordRequestObservation(db, {
+      depositAddressId: address.id,
+      pollObservedAt: '2026-01-02T00:00:02.000Z',
+      providerRequestId: 'relay_observed',
+      webhookReceivedAt: '2026-01-02T00:00:03.000Z',
+    })
+    await FundingDeposits.recordRequestObservation(db, {
+      depositAddressId: address.id,
+      pollObservedAt: '2026-01-02T00:00:01.000Z',
+      providerRequestId: 'relay_observed',
+      webhookReceivedAt: '2026-01-02T00:00:04.000Z',
+    })
+
+    expect(await FundingDeposits.get(db, record.id)).toMatchInlineSnapshot(
+      {
+        createdAt: expect.any(String),
+        depositAddressId: expect.any(String),
+        id: expect.any(String),
+        providerOutputToken: expect.any(Object),
+        snapshot: expect.any(Object),
+        updatedAt: expect.any(String),
+      },
+      `
+      {
+        "createdAt": Any<String>,
+        "depositAddressId": Any<String>,
+        "detectionTrigger": null,
+        "environment": "production",
+        "id": Any<String>,
+        "orgId": "org_deposits",
+        "pollObservedAt": "2026-01-02T00:00:01.000Z",
+        "projectId": null,
+        "providerOutputAmount": null,
+        "providerOutputToken": Any<Object>,
+        "providerRequestId": "relay_observed",
+        "providerRequestIds": [
+          "relay_observed",
+        ],
+        "providerState": null,
+        "providerTransactionHashes": [],
+        "providerTransferIndex": 0,
+        "retryState": null,
+        "settlementTransaction": null,
+        "settlementTransactionHash": null,
+        "snapshot": Any<Object>,
+        "sourceChainId": "tron:0x2b6653dc",
+        "sourceTransactionHash": "0000000000000000000000000000000000000000000000000000000000000011",
+        "sourceTransferIndex": 0,
+        "status": "detected",
+        "statusReason": null,
+        "subsidyAmount": null,
+        "tempoGasPaid": null,
+        "updatedAt": Any<String>,
+        "version": 1,
+        "webhookReceivedAt": "2026-01-02T00:00:03.000Z",
+      }
+    `,
+    )
+  })
+})
+
 describe('toPublic', () => {
   test('omits private reconciliation and settlement state', async () => {
     const address = await seedAddress()

package/src/db/tables/fundingDeposits.ts

@@ -1,4 +1,4 @@
-import type { JSONColumnType, Selectable } from 'kysely'
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
 
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
@@ -40,6 +40,63 @@ export function insert(db: Db.Db, record: Record): Promise<Record> {
     .executeTakeFirstOrThrow()
 }
 
+/** Inserts a chain-observed source transfer or returns its existing deposit. */
+export async function insertOrGetSource(
+  db: Db.Db,
+  record: Record & { sourceTransferIndex: number },
+): Promise<insertOrGetSource.Result> {
+  const inserted = await db.kysely
+    .insertInto('funding_deposits')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+      providerTransactionHashes: JSON.stringify(record.providerTransactionHashes),
+    })
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'sourceTransactionHash', 'sourceTransferIndex']).doNothing(),
+    )
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { record: inserted, type: 'created' }
+  const existing = await db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', record.depositAddressId)
+    .where('sourceTransactionHash', '=', record.sourceTransactionHash)
+    .where('sourceTransferIndex', '=', record.sourceTransferIndex)
+    .executeTakeFirstOrThrow()
+  return { record: existing, type: 'existing' }
+}
+
+export declare namespace insertOrGetSource {
+  /** Result of idempotently persisting one verified source transfer. */
+  type Result = { record: Record; type: 'created' | 'existing' }
+}
+
+/** Serializes source attribution for one address and transaction. */
+export function withSourceTransaction<const result>(
+  db: Db.Db,
+  options: withSourceTransaction.Options<result>,
+): Promise<result> {
+  return db.transaction(async (tx) => {
+    const key = `${options.depositAddressId}:${options.sourceTransactionHash.toLowerCase()}`
+    await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx.kysely)
+    return options.fn(tx)
+  })
+}
+
+export declare namespace withSourceTransaction {
+  /** Source identity and transaction-scoped work protected by its advisory lock. */
+  type Options<result> = {
+    /** Funding deposit address that received the transfer. */
+    depositAddressId: string
+    /** Database work serialized for the source transaction. */
+    fn: (db: Db.Db) => Promise<result>
+    /** Source transaction whose deposit attribution must not race. */
+    sourceTransactionHash: string
+  }
+}
+
 /** Gets deposits created from one provider-observed source transaction. */
 export function listByProviderObservation(
   db: Db.Db,
@@ -67,6 +124,45 @@ export declare namespace listByProviderObservation {
   }
 }
 
+/** Attaches first-observation timestamps to every deposit from one provider request. */
+export function recordRequestObservation(
+  db: Db.Db,
+  options: recordRequestObservation.Options,
+): Promise<Record[]> {
+  return db.kysely
+    .updateTable('funding_deposits')
+    .set({
+      ...(options.pollObservedAt
+        ? {
+            pollObservedAt: sql<string>`LEAST(COALESCE(poll_observed_at, ${options.pollObservedAt}), ${options.pollObservedAt})`,
+          }
+        : {}),
+      ...(options.webhookReceivedAt
+        ? {
+            webhookReceivedAt: sql<string>`LEAST(COALESCE(webhook_received_at, ${options.webhookReceivedAt}), ${options.webhookReceivedAt})`,
+          }
+        : {}),
+    })
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .returningAll()
+    .execute()
+}
+
+export declare namespace recordRequestObservation {
+  /** First observations associated with one provider request. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** When polling first observed the provider request. */
+    pollObservedAt?: string | undefined
+    /** Provider request identifier. */
+    providerRequestId: string
+    /** When Tempo first received an authenticated provider webhook. */
+    webhookReceivedAt?: string | undefined
+  }
+}
+
 /** Gets deposits associated with one address and source transaction. */
 export function listBySourceTransaction(
   db: Db.Db,
@@ -91,6 +187,20 @@ export declare namespace listBySourceTransaction {
   }
 }
 
+/** Returns whether an address has a nonterminal source transfer awaiting provider attribution. */
+export async function hasUnattributed(db: Db.Db, depositAddressId: string): Promise<boolean> {
+  return Boolean(
+    await db.kysely
+      .selectFrom('funding_deposits')
+      .select('id')
+      .where('depositAddressId', '=', depositAddressId)
+      .where('providerRequestId', 'is', null)
+      .where('status', 'not in', ['completed', 'refunded'])
+      .limit(1)
+      .executeTakeFirst(),
+  )
+}
+
 /** Gets a funding deposit without ownership scoping. */
 export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely
@@ -155,6 +265,40 @@ export declare namespace listByAddress {
   }
 }
 
+/** Lists one recipient's owner-visible deposits newest-first. */
+export function listByRecipient(db: Db.Db, options: listByRecipient.Options): Promise<Record[]> {
+  const { cursor, limit, owner, recipient } = options
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('orgId', '=', owner.orgId)
+    .where(sql<boolean>`lower(snapshot->>'recipient') = ${recipient.toLowerCase()}`)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('createdAt', '<', cursor.createdAt),
+        eb.and([eb('createdAt', '=', cursor.createdAt), eb('id', '<', cursor.id)]),
+      ]),
+    )
+  return query.orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(limit).execute()
+}
+
+export declare namespace listByRecipient {
+  /** Recipient filter, ownership, and paging options. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: listByAddress.Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+    /** Tempo account that receives completed deposits. */
+    recipient: string
+  }
+}
+
 /** Applies a version-guarded deposit update. */
 export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
   return db.kysely

package/src/internal/Auth.test.ts

@@ -21,6 +21,7 @@ import * as TestStore from '../../test/Store.js'
 import * as Tempo from '../../test/Tempo.js'
 
 const key = {
+  allowedIps: [],
   environment: 'production',
   id: 'key_test',
   name: 'Test key',
@@ -295,6 +296,135 @@ describe('require', () => {
         }
       `)
     })
+
+    test.each([
+      ['tempo-api-key', '/protected', { 'tempo-api-key': token }],
+      ['Bearer', '/protected', { authorization: `Bearer ${token}` }],
+      ['x-api-key', '/protected', { 'x-api-key': token }],
+      ['query key', `/protected?key=${token}`, {}],
+    ] as const)('enforces an allowlist for the %s credential', async (_name, path, credential) => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request(path, {
+        headers: { ...credential, 'cf-connecting-ip': '198.51.100.7' },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('rejects a missing client IP', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('does not trust a Cloudflare IP header outside Cloudflare', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'cf-connecting-ip': '203.0.113.7',
+          'tempo-api-key': token,
+        },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('uses the Cloudflare IP header with Cloudflare request metadata', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const request = Object.assign(
+        new Request('http://localhost/protected', {
+          headers: {
+            'cf-connecting-ip': '203.0.113.7',
+            'tempo-api-key': token,
+          },
+        }),
+        { cf: {} },
+      )
+      const response = await app.fetch(request)
+
+      expect(response.status).toBe(200)
+    })
+
+    test('uses the configured trusted client-IP resolver', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          publicClientIp: (request) => request.headers.get('x-real-ip') ?? undefined,
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'cf-connecting-ip': '198.51.100.7',
+          'tempo-api-key': token,
+          'x-real-ip': '203.0.113.7',
+        },
+      })
+
+      expect(response.status).toBe(200)
+    })
+
+    test('treats an empty allowlist as unrestricted', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({ keys: [{ ...key, allowedIps: [], token }] }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toBe(200)
+    })
   })
 
   describe('session', () => {
@@ -383,6 +513,37 @@ describe('require', () => {
       `)
     })
 
+    test('applies the session-only route error before key restrictions', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          publicClientIp: (request) => request.headers.get('x-real-ip') ?? undefined,
+          rateLimit: RateLimit.memory(),
+        },
+        policy: { session: true },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'tempo-api-key': token,
+          'x-real-ip': '198.51.100.7',
+        },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "forbidden",
+            "message": "API key not permitted for this route",
+          },
+        }
+      `)
+    })
+
     test('is not consulted on lane-less routes', async () => {
       const app = createSessionApp({
         policy: {},
@@ -1228,7 +1389,7 @@ describe('require', () => {
       })
     })
 
-    test('rejects a voucher that exceeds the channel deposit', async () => {
+    test('tops up the channel before signing a voucher that exceeds its deposit', async () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
@@ -1243,14 +1404,25 @@ describe('require', () => {
       })
       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.
+      // The opening deposit covers one request. The client tops up the channel
+      // before signing the second voucher.
       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)
+      expect(second.status).toBe(200)
+
+      const receipt1 = sessionReceipt(first)
+      const receipt2 = sessionReceipt(second)
+      expect(receipt2).toMatchObject({
+        channelId: receipt1.channelId,
+        spent: '2000000',
+      })
+
+      const state = await Actions.channel.getStates(Tempo.client, {
+        channel: receipt1.channelId,
+      })
+      expect(state.deposit).toBe(2_000_000n)
     })
 
     test('rejects a malformed payment credential with a fresh challenge', async () => {

package/src/internal/Auth.ts

@@ -18,6 +18,7 @@ import * as ApiKeys from '../ApiKeys.js'
 import * as Db from '../db/Db.js'
 import type * as Store from './Store.js'
 import * as Memberships from '../db/tables/memberships.js'
+import * as IpAllowlist from './IpAllowlist.js'
 import * as Metadata from '../apps/metadata.js'
 import * as OpenApi from './OpenApi.js'
 import * as Organizations from '../db/tables/organizations.js'
@@ -438,12 +439,16 @@ export function accessError(c: hono_Context) {
       status: 401,
     })
   }
-  if (status === 403)
+  if (status === 403) {
+    const ipForbidden = c.req.header('tempo-narrow-access-code') === 'api_key_ip_forbidden'
     return Response.error(c, {
-      code: 'api_key_forbidden',
-      message: 'API key missing required scope',
+      code: ipForbidden ? 'api_key_ip_forbidden' : 'api_key_forbidden',
+      message: ipForbidden
+        ? 'API key not permitted from this IP address'
+        : 'API key missing required scope',
       status: 403,
     })
+  }
   const code =
     c.req.header('tempo-narrow-access-code') === 'rate_limit_exceeded'
       ? 'rate_limit_exceeded'
@@ -511,8 +516,8 @@ export function middleware<
   // store is configured, every token resolves to `null` (closed).
   // Resolution is cached per isolate by default (positive 60s / negative 10s,
   // keyed by token sha256) so hot keys skip the backend read on the auth path
-  // of every request. Pass `apiKey.cache: false` when instant revocation
-  // matters more than the per-request read.
+  // of every request. Pass `apiKey.cache: false` when immediate key updates
+  // matter more than the per-request read.
   const resolve = (() => {
     const uncached = (c: hono_Context, token: string) => {
       const kv = contextKv(c)
@@ -606,8 +611,8 @@ export declare namespace middleware {
           /**
            * Resolve-cache tuning (per-isolate, positive 60s / negative 10s by
            * default), or `false` to resolve uncached on every request — e.g.
-           * when instant revocation matters more than the per-request backend
-           * read.
+           * when immediate key updates matter more than the per-request
+           * backend read.
            */
           cache?: Cache | false | undefined
           /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
@@ -624,7 +629,7 @@ export declare namespace middleware {
     /** Default public access policy. Pass false to disable anonymous access. */
     public?:
       | {
-          /** Resolves the client IP from trusted runtime or proxy metadata. Defaults to `cf-connecting-ip`. */
+          /** Resolves the client IP from trusted runtime or proxy metadata. Required outside Cloudflare for API-key allowlists. */
           clientIp?: ((request: Request) => string | undefined) | undefined
           /** Anonymous public quota for protected routes. */
           rateLimit?: RateLimit.Limit | undefined
@@ -1448,6 +1453,28 @@ export function require<environment extends Environment = Environment>(
       const principal = principalFromApiKey(apiKey)
       c.set('principal', principal)
 
+      // Default-deny: routes with no API-key lane allow only the super admin.
+      // A valid key is authenticated but forbidden.
+      if (!policy.apiKey)
+        return jsonError(c, {
+          code: 'forbidden',
+          message: 'API key not permitted for this route',
+          status: 403,
+        })
+
+      if (
+        apiKey.allowedIps.length &&
+        !(await IpAllowlist.allows(c, {
+          address: trustedClientIp(c, auth),
+          rules: apiKey.allowedIps,
+        }))
+      )
+        return jsonError(c, {
+          code: 'api_key_ip_forbidden',
+          message: 'API key not permitted from this IP address',
+          status: 403,
+        })
+
       if (
         apiKey.environment === 'sandbox' &&
         explicitChain !== undefined &&
@@ -1459,14 +1486,6 @@ export function require<environment extends Environment = Environment>(
           status: 403,
         })
 
-      // Default-deny: routes with no API-key lane allow only the super admin.
-      // A valid key is authenticated but forbidden.
-      if (!policy.apiKey)
-        return jsonError(c, {
-          code: 'forbidden',
-          message: 'API key not permitted for this route',
-          status: 403,
-        })
       const missing = apiKey.scopes.includes(Scope.wildcard)
         ? []
         : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
@@ -1821,6 +1840,17 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
   return null
 }
 
+function clientIp(c: hono_Context, auth: Context): string | undefined {
+  return auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip')
+}
+
+function trustedClientIp(c: hono_Context, auth: Context): string | undefined {
+  if (auth.publicClientIp) return auth.publicClientIp(c.req.raw)
+  // Cloudflare supplies both the request metadata and this header.
+  if (!('cf' in c.req.raw)) return undefined
+  return c.req.header('cf-connecting-ip')
+}
+
 /** Removes the reserved auth query parameter before route validation. */
 function stripApiKeyQuery(c: hono_Context) {
   const url = new URL(c.req.url)
@@ -1936,7 +1966,7 @@ function principalFromApiKey(apiKey: ApiKey.ApiKey): Principal {
 }
 
 function principalFromPublic(c: hono_Context, auth: Context): Principal {
-  const ip = auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip')
+  const ip = clientIp(c, auth)
   return {
     id: ip ? RateLimit.normalizeIp(ip) : 'anonymous',
     type: 'public',
@@ -2056,7 +2086,7 @@ const cachedMaxEntries = 10_000
  * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
  * key is usable quickly; concurrent misses for one token are single-flighted.
  * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
- * plaintext. A revoked key may stay resolvable for up to `ttl` — the accepted
+ * plaintext. Key updates may remain stale for up to `ttl`, the accepted
  * trade-off for removing a backend read from the auth path.
  */
 function cachedResolve(