tapimo 0.13.0 → 0.15.0

package/src/apps/management/routes/api-keys.test.ts

@@ -1,10 +1,12 @@
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
+import * as Analytics from '../../../analytics/Analytics.js'
 import * as ApiKeys from '../../../ApiKeys.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Scope from '../../../Scope.js'
 import * as TestApp from '../../../../test/App.js'
+import * as Containers from '../../../../test/containers.js'
 import * as Memberships from '../../../db/tables/memberships.js'
 import * as Keys from './api-keys.js'
 import * as Me from './me.js'
@@ -40,12 +42,14 @@ type State = ReturnType<typeof TestApp.kvStore>
 
 function createApp(
   options: {
+    analytics?: Analytics.Analytics
     db?: ReturnType<typeof TestApp.database>
     kv?: { store: State }
     scopes?: readonly Scope.Entry[]
   } = {},
 ) {
   return TestApp.create({
+    ...(options.analytics ? { analytics: options.analytics } : {}),
     auth: { cache: false, superAdmin: { secret } },
     db: options.db ?? TestApp.database(),
     ...(options.kv ? { kv: options.kv } : {}),
@@ -90,6 +94,21 @@ test('publishes generator-ready OpenAPI contracts', async () => {
   const organization = spec.paths['/v1/orgs/{orgId}/api-keys']
   const rotation = spec.paths['/v1/orgs/{orgId}/projects/{projectId}/api-keys/{keyId}/rotate']
 
+  for (const route of [collection, organization]) {
+    const parameter = route.get.parameters.find(
+      (parameter: { name: string }) => parameter.name === 'include',
+    )
+    expect(parameter?.required ?? false).toBe(false)
+    expect(parameter).toMatchObject({
+      description: expect.stringContaining('Defaults to lastUsedAt'),
+      in: 'query',
+      schema: {
+        items: { enum: ['lastUsedAt'], type: 'string' },
+        type: 'array',
+      },
+    })
+  }
+
   expect({
     components: [
       'ApiKey',
@@ -290,6 +309,87 @@ test('publishes generator-ready OpenAPI contracts', async () => {
 })
 
 describe('keys', () => {
+  test('loads metadata without analytics while retaining default last-used enrichment', async () => {
+    const stack = await Containers.start()
+    try {
+      const connection = {
+        database: 'tempo_api',
+        password: 'clickhouse',
+        url: `http://${stack.endpoints.clickhouse.host}:${stack.endpoints.clickhouse.port}`,
+        user: 'clickhouse',
+      }
+      const analytics = Analytics.clickhouse(connection)
+      await analytics.migrate()
+      const db = TestApp.database()
+      const kv = { store: TestApp.kvStore() }
+      const app = createApp({ analytics, db, kv })
+      const cookie = await session(app)
+      const { org, project } = await fixture(app, cookie)
+      const minted = await ApiKeys.mint(kv.store, {
+        orgId: org.id,
+        projectId: project.id,
+        scopes: ['data:read'],
+      })
+      await analytics.insert('request_events', [
+        {
+          billing_active: 0,
+          chain_id: 4217,
+          duration_ms: 10,
+          environment: 'production',
+          error_code: null,
+          key_environment: 'production',
+          key_id: minted.record.id,
+          method: 'GET',
+          org_id: org.id,
+          principal_type: 'api_key',
+          project_id: project.id,
+          query: '',
+          rate_limit_scope: null,
+          request_id: 'request-last-used',
+          route: '/v1/tokenlist',
+          rpc_error_code: null,
+          rpc_error_count: 0,
+          rpc_error_data_code: null,
+          service: 'api',
+          status: 200,
+          timestamp: '2026-09-01 12:00:00.000',
+          timings: {},
+        },
+      ])
+      const unavailable = createApp({
+        analytics: Analytics.clickhouse({ ...connection, password: 'invalid' }),
+        db,
+        kv,
+      })
+      for (const path of [
+        `/v1/orgs/${org.id}/api-keys`,
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      ]) {
+        for (const query of ['', '?include=lastUsedAt']) {
+          const response = await app.request(`${path}${query}`, { headers: { cookie } })
+          expect(response.status).toBe(200)
+          const { data } = await TestApp.json(response, Keys.schema.ApiKeyList)
+          expect(data[0]?.lastUsedAt).toBe('2026-09-01T12:00:00.000Z')
+        }
+        const response = await unavailable.request(`${path}?include=`, { headers: { cookie } })
+        expect(response.status).toBe(200)
+        const { data } = await TestApp.json(response, Keys.schema.ApiKeyList)
+        expect(data.map(({ id }) => id)).toEqual([minted.record.id])
+        expect(data[0]).not.toHaveProperty('lastUsedAt')
+        for (const query of ['', '?include=lastUsedAt'])
+          expect(
+            (await unavailable.request(`${path}${query}`, { headers: { cookie } })).status,
+          ).toBe(502)
+        expect((await app.request(`${path}?include=unknown`, { headers: { cookie } })).status).toBe(
+          400,
+        )
+        expect((await app.request(`${path}?include=`)).status).toBe(401)
+      }
+    } finally {
+      await stack.stop()
+    }
+  })
+
   test('requires an owner to issue management write keys', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
@@ -421,6 +521,71 @@ describe('keys', () => {
     expect(await ApiKeys.resolve(store, replacement.token)).not.toBeNull()
   })
 
+  test.each(['production', 'sandbox'] as const)(
+    'rotates an approved Routes key in %s without changing its access',
+    async (environment) => {
+      const store = TestApp.kvStore({ keys: [] })
+      const app = createApp({ kv: { store } })
+      const owner = await session(app)
+      const { org, project } = await fixture(app, owner)
+      const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+      const source = await TestApp.json(
+        await app.request(
+          base,
+          superAdminJson('POST', {
+            allowedIps: ['203.0.113.0/24'],
+            environment,
+            name: 'Approved Routes',
+            scopes: ['routes:read', 'routes:write'],
+          }),
+        ),
+        Keys.schema.createApiKey.Response,
+      )
+      expect(source.createdBy).toBe('super_admin')
+
+      const replacement = await TestApp.json(
+        await app.request(`${base}/${source.id}/rotate`, {
+          headers: { cookie: owner },
+          method: 'POST',
+        }),
+        Keys.schema.rotateApiKey.Response,
+      )
+      expect(replacement).toMatchObject({
+        allowedIps: ['203.0.113.0/24'],
+        environment,
+        name: 'Approved Routes',
+        orgId: org.id,
+        projectId: project.id,
+        scopes: ['routes:read', 'routes:write'],
+      })
+      expect(replacement.createdBy).toMatch(/^usr_/)
+      expect(replacement.id).not.toBe(source.id)
+      expect(replacement.token).not.toBe(source.token)
+
+      // Rotation keeps the original usable and authenticates the replacement on real routes.
+      for (const token of [source.token, replacement.token]) {
+        const headers = { 'cf-connecting-ip': '203.0.113.7', 'tempo-api-key': token }
+        const read = await app.request('/v1/routes/transfers', { headers })
+        expect(read.status).toBe(200)
+        expect(await read.json()).toMatchObject({ data: [] })
+
+        // Missing input reaches validation only after the write-scope check, without a transfer.
+        const write = await app.request('/v1/routes/transfers', { headers, method: 'POST' })
+        expect(write.status).toBe(400)
+        expect(await write.json()).toMatchObject({ error: { code: 'idempotency_key_required' } })
+      }
+
+      const denied = await app.request('/v1/routes/transfers', {
+        headers: {
+          'cf-connecting-ip': '198.51.100.7',
+          'tempo-api-key': replacement.token,
+        },
+      })
+      expect(denied.status).toBe(403)
+      expect(await denied.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    },
+  )
+
   test('rotates an organization-level super-admin-issued zone key', async () => {
     const store = TestApp.kvStore({ keys: [] })
     const app = createApp({ kv: { store } })
@@ -477,6 +642,47 @@ describe('keys', () => {
     expect(await ApiKeys.resolve(store, replacement.token)).toBeNull()
   })
 
+  test('returns organization not found when its fence appears during rotation', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ kv: { store } })
+    const owner = await session(app)
+    const { org } = await fixture(app, owner)
+    const { record: source } = await ApiKeys.mint(store, {
+      orgId: org.id,
+      scopes: ['data:read'],
+    })
+    await ApiKeys.markOwnerDeleting(store, { orgId: org.id })
+
+    const response = await app.request(`/v1/orgs/${org.id}/api-keys/${source.id}/rotate`, {
+      headers: { cookie: owner },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(404)
+    expect(await response.json()).toMatchObject({ error: { code: 'organization_not_found' } })
+  })
+
+  test('returns project not found when its fence appears during rotation', async () => {
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ kv: { store } })
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+    const { record: source } = await ApiKeys.mint(store, {
+      orgId: org.id,
+      projectId: project.id,
+      scopes: ['data:read'],
+    })
+    await ApiKeys.markOwnerDeleting(store, { orgId: org.id, projectId: project.id })
+
+    const response = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys/${source.id}/rotate`,
+      { headers: { cookie: owner }, method: 'POST' },
+    )
+
+    expect(response.status).toBe(404)
+    expect(await response.json()).toMatchObject({ error: { code: 'project_not_found' } })
+  })
+
   test('refreshes sandbox billing state during rotation', async () => {
     const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
@@ -724,6 +930,26 @@ describe('keys', () => {
     expect((await authenticate()).status).toBe(200)
   })
 
+  test('does not expose scope updates on the customer API', async () => {
+    const state = TestApp.kvStore()
+    const app = createApp({ kv: { store: state } })
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    const created = await TestApp.json(
+      await app.request(base, superAdminJson('POST', { scopes: ['data:read'] })),
+      Keys.schema.createApiKey.Response,
+    )
+
+    const response = await app.request(
+      `${base}/${created.id}`,
+      json('PATCH', cookie, { allowedIps: [], scopes: ['management:write'] }),
+    )
+
+    expect(response.status).toBe(200)
+    expect((await ApiKeys.resolve(state, created.token))?.scopes).toEqual(['data:read'])
+  })
+
   test('rejects malformed IP allowlists on create and update', async () => {
     const app = createApp()
     const cookie = await session(app)
@@ -798,12 +1024,12 @@ describe('keys', () => {
     const created = await TestApp.json(
       await app.request(
         `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
-        json('POST', cookie, { scopes: ['data:read'] }),
+        json('POST', cookie, { scopes: ['data:read', 'routes:read'] }),
       ),
       Keys.schema.createApiKey.Response,
     )
     expect(created.environment).toBe('production')
-    expect(created.scopes).toEqual(['data:read'])
+    expect(created.scopes).toEqual(['data:read', 'routes:read'])
     // Session-minted, not granted through the super admin.
     expect(created.createdBy).not.toBe('super_admin')
   })
@@ -860,6 +1086,42 @@ describe('keys', () => {
     expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
   })
 
+  test('rejects duplicate scope vectors', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const path = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+
+    const response = await app.request(
+      path,
+      superAdminJson('POST', { scopes: ['data:read', 'data:read'] }),
+    )
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+  })
+
+  test.each(['production', 'sandbox'] as const)(
+    'requires Tempo approval to mint routes:write on %s keys',
+    async (environment) => {
+      const app = createApp()
+      const cookie = await session(app)
+      const { org, project } = await fixture(app, cookie)
+
+      const path = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+      const scopes = ['routes:read', 'routes:write']
+      const response = await app.request(path, json('POST', cookie, { environment, scopes }))
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'scope_not_issuable' } })
+
+      const created = await TestApp.json(
+        await app.request(path, superAdminJson('POST', { environment, scopes })),
+        Keys.schema.createApiKey.Response,
+      )
+      expect(created.scopes).toEqual(scopes)
+      expect(created.createdBy).toBe('super_admin')
+    },
+  )
+
   test('rejects session mints of non-self-serve scopes (webhooks)', async () => {
     const app = createApp()
     const cookie = await session(app)
@@ -882,12 +1144,12 @@ describe('keys', () => {
     const created = await TestApp.json(
       await app.request(
         `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
-        json('POST', cookie, { environment: 'sandbox', scopes: ['data:read'] }),
+        json('POST', cookie, { environment: 'sandbox', scopes: ['data:read', 'routes:read'] }),
       ),
       Keys.schema.createApiKey.Response,
     )
     expect(created.environment).toBe('sandbox')
-    expect(created.scopes).toEqual(['data:read'])
+    expect(created.scopes).toEqual(['data:read', 'routes:read'])
     // Session-minted, not granted through the super admin.
     expect(created.createdBy).not.toBe('super_admin')
   })
@@ -1118,7 +1380,7 @@ describe('keys', () => {
     expect(projectStill.status).toBe(200)
   })
 
-  test('keeps the organization when key revocation fails during organization deletion', async () => {
+  test('keeps organization deletion committed when key revocation fails', async () => {
     const store = TestApp.kvStore({ keys: [] })
     const app = createApp({ kv: { store } })
     const cookie = await session(app)
@@ -1136,10 +1398,10 @@ describe('keys', () => {
       headers: { cookie },
       method: 'DELETE',
     })
-    expect(deletedOrg.status).toBe(502)
+    expect(deletedOrg.status).toBe(200)
 
     const orgStill = await app.request(`/v1/orgs/${org.id}`, { headers: { cookie } })
-    expect(orgStill.status).toBe(200)
+    expect(orgStill.status).toBe(404)
   })
 
   test('mints as the super admin with super admin attribution', async () => {

package/src/apps/management/routes/api-keys.ts

@@ -18,6 +18,14 @@ import * as ManagementError from '../Error.js'
 
 /** Zod schemas owned by the API-keys resource. */
 export namespace schema {
+  const include = z._default(
+    Schema.includeQuery(
+      z.enum(['lastUsedAt']),
+      'Fields to enrich. Defaults to lastUsedAt; pass an empty value to load metadata without analytics.',
+    ),
+    ['lastUsedAt'],
+  )
+
   /** One API key: metadata only — the token appears once, at mint. */
   export const Key = OpenApi.component(
     Schema.describe(
@@ -55,12 +63,10 @@ export namespace schema {
             z.describe('Opaque key id (`key_…`).'),
             z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
           ),
-        lastUsedAt: z
-          .optional(z.iso.datetime())
-          .check(
-            z.describe('When the key last authenticated a request (ISO 8601).'),
-            z.meta({ examples: ['2026-07-21T12:34:56.000Z'] }),
-          ),
+        lastUsedAt: z.optional(z.iso.datetime()).check(
+          z.describe('When the key last authenticated a request (ISO 8601). Omitted with `include=` or when no usage is available.'), // prettier-ignore
+          z.meta({ examples: ['2026-07-21T12:34:56.000Z'] }),
+        ),
         name: z
           .optional(z.string())
           .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
@@ -194,7 +200,11 @@ export namespace schema {
             ),
             [],
           )
-          .check(z.describe('Scopes to grant.'), z.meta({ examples: [['data:read']] })),
+          .check(
+            z.refine((scopes) => new Set(scopes).size === scopes.length),
+            z.describe('Unique scopes to grant.'),
+            z.meta({ examples: [['data:read']] }),
+          ),
       })
       .check(z.describe('Fields for minting an API key.')),
     'CreateApiKeyRequest',
@@ -234,7 +244,7 @@ export namespace schema {
   export namespace listApiKeys {
     /** Query parameters filtering a project's keys. */
     export const Query = z
-      .strictObject({ environment: Schema.Environment })
+      .strictObject({ environment: Schema.Environment, include })
       .check(z.describe("Query parameters for a project's API keys."))
 
     /** Non-paginated list of a project's keys. */
@@ -245,7 +255,7 @@ export namespace schema {
   export namespace listOrgApiKeys {
     /** Query parameters filtering the organization's keys. */
     export const Query = z
-      .strictObject({ environment: Schema.Environment })
+      .strictObject({ environment: Schema.Environment, include })
       .check(z.describe("Query parameters for an organization's API keys."))
 
     /** Non-paginated list of every key in the organization. */
@@ -345,6 +355,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
               codes: ['api_keys_not_enabled', 'organization_not_found', 'project_not_found'],
               description: 'No accessible project or API key surface was found.',
             },
+            409: { codes: ['api_key_limit_reached'], description: 'API-key limit reached.' },
           },
           success: {
             description: 'The minted key, including its one-time token.',
@@ -383,6 +394,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
             status: 400,
           })
 
+        // Session issuers are limited to the finite self-serve catalog, so uniqueness bounds the vector without a new policy cap.
         if (!canIssue(c, body.scopes))
           return Response.error(c, {
             code: 'scope_not_issuable',
@@ -398,7 +410,8 @@ export function apiKeys(options: apiKeys.Options = {}) {
             body.environment === 'sandbox'
               ? await Billing.active(Db.get(c.get('db')), orgId, 'sandbox')
               : undefined
-          const { record, token } = await ApiKeys.mint(
+          const { record, token } = await ApiKeys.mintBounded(
+            Db.get(c.get('db')),
             kv.store,
             {
               createdBy,
@@ -417,6 +430,8 @@ export function apiKeys(options: apiKeys.Options = {}) {
             200,
           )
         } catch (cause) {
+          if (cause instanceof ApiKeys.OwnerDeletedError) return Auth.ensureProjectError(c)
+          if (cause instanceof ApiKeys.LiveKeyLimitError) return keyLimitReached(c)
           return Response.upstream(c, cause)
         }
       },
@@ -480,7 +495,9 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           return c.json(
             Response.validated(schema.listApiKeys.Response, {
-              data: await serializeKeys(c, records),
+              data: c.req.valid('query').include.includes('lastUsedAt')
+                ? await serializeKeys(c, records)
+                : records.map((record) => serializeKey(record)),
             }),
             200,
           )
@@ -547,7 +564,9 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           return c.json(
             Response.validated(schema.listOrgApiKeys.Response, {
-              data: await serializeKeys(c, records),
+              data: c.req.valid('query').include.includes('lastUsedAt')
+                ? await serializeKeys(c, records)
+                : records.map((record) => serializeKey(record)),
             }),
             200,
           )
@@ -580,6 +599,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
               codes: ['api_key_not_found', 'api_keys_not_enabled', 'organization_not_found'],
               description: 'No accessible API key or API key surface was found.',
             },
+            409: { codes: ['api_key_limit_reached'], description: 'API-key limit reached.' },
           },
           success: {
             description: 'The replacement key, including its one-time token.',
@@ -615,8 +635,10 @@ export function apiKeys(options: apiKeys.Options = {}) {
               message: 'The source key contains scopes the caller cannot rotate.',
               status: 403,
             })
-          return rotate(c, kv.store, source, createdBy)
+          return await rotate(c, kv.store, source, createdBy)
         } catch (cause) {
+          if (cause instanceof ApiKeys.OwnerDeletedError) return Auth.ensureOrgError(c)
+          if (cause instanceof ApiKeys.LiveKeyLimitError) return keyLimitReached(c)
           return Response.upstream(c, cause)
         }
       },
@@ -740,9 +762,16 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           if (!record || record.orgId !== Auth.org(c).id || record.projectId !== Auth.project(c).id)
             return keyNotFound(c)
-          const updated = await ApiKeys.update(kv.store, keyId, c.req.valid('json'), {
-            scopeCatalog: c.get('scopeCatalog'),
-          })
+          const updated = await ApiKeys.updateBounded(
+            Db.get(c.get('db')),
+            kv.store,
+            keyId,
+            c.req.valid('json'),
+            {
+              expectedOwner: { orgId: Auth.org(c).id, projectId: Auth.project(c).id },
+              scopeCatalog: c.get('scopeCatalog'),
+            },
+          )
           if (!updated) return keyNotFound(c)
           return c.json(Response.validated(schema.Key, serializeKey(updated)), 200)
         } catch (cause) {
@@ -780,6 +809,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
               ],
               description: 'No accessible API key or API key surface was found.',
             },
+            409: { codes: ['api_key_limit_reached'], description: 'API-key limit reached.' },
           },
           success: {
             description: 'The replacement key, including its one-time token.',
@@ -816,8 +846,10 @@ export function apiKeys(options: apiKeys.Options = {}) {
               message: 'The source key contains scopes the caller cannot rotate.',
               status: 403,
             })
-          return rotate(c, kv.store, source, createdBy)
+          return await rotate(c, kv.store, source, createdBy)
         } catch (cause) {
+          if (cause instanceof ApiKeys.OwnerDeletedError) return Auth.ensureProjectError(c)
+          if (cause instanceof ApiKeys.LiveKeyLimitError) return keyLimitReached(c)
           return Response.upstream(c, cause)
         }
       },
@@ -970,7 +1002,8 @@ async function rotate(
     source.environment === 'sandbox'
       ? await Billing.active(Db.get(c.get('db')), source.orgId, 'sandbox')
       : undefined
-  const { record, token } = await ApiKeys.mint(
+  const { record, token } = await ApiKeys.mintBounded(
+    Db.get(c.get('db')),
     store,
     {
       allowedIps: source.allowedIps,
@@ -978,7 +1011,7 @@ async function rotate(
       environment: source.environment,
       orgId: source.orgId,
       ...(source.projectId === undefined ? {} : { projectId: source.projectId }),
-      scopes: source.scopes,
+      scopes: [...new Set(source.scopes)],
       ...(billingActive === undefined ? {} : { billingActive }),
       ...(source.expiresAt === undefined ? {} : { expiresAt: source.expiresAt }),
       ...(source.name === undefined ? {} : { name: source.name }),
@@ -994,7 +1027,7 @@ async function rotate(
 
 /** Revokes an API key after its route has verified ownership. */
 async function revoke(c: Context<App.Environment>, store: Store.State, keyId: string) {
-  const revoked = await ApiKeys.revoke(store, keyId)
+  const revoked = await ApiKeys.revokeBounded(Db.get(c.get('db')), store, keyId)
   if (!revoked) return keyNotFound(c)
   return c.json(Response.validated(schema.revokeApiKey.Response, { id: keyId }), 200)
 }
@@ -1014,3 +1047,11 @@ function notEnabled(c: Context<App.Environment>) {
     status: 404,
   })
 }
+
+function keyLimitReached(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'api_key_limit_reached',
+    message: `Organizations may have at most ${ApiKeys.maxLiveKeysPerOrganization} live API keys.`,
+    status: 409,
+  })
+}