tapimo 0.19.0 → 0.20.0

package/src/apps/data/routes/webhooks.ts

@@ -643,12 +643,10 @@ export namespace schema {
         context: z
           .optional(Context)
           .check(z.meta({ examples: [{ title: 'Prod USDC large transfers' }] })),
-        createdAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When the subscription was created, as an ISO 8601 timestamp.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
+        createdAt: Schema.dateTime().check(
+          z.describe('When the subscription was created, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
         destination: PublicDestination,
         environment: z
           .optional(z.enum(['production', 'sandbox']))
@@ -658,7 +656,7 @@ export namespace schema {
           ),
         eventType: EventType.check(z.meta({ examples: ['token:transfer'] })),
         expiresAt: z
-          .optional(z.iso.datetime())
+          .optional(Schema.dateTime())
           .check(
             z.describe(
               'When the subscription expires, as an ISO 8601 timestamp. Only MPP-paid subscriptions expire.',
@@ -686,7 +684,7 @@ export namespace schema {
             z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
         lastDeliveryAt: z
-          .optional(z.iso.datetime())
+          .optional(Schema.dateTime())
           .check(
             z.describe(
               'When Tempo last delivered an event successfully, as an ISO 8601 timestamp. Refreshed at most once per minute during sustained delivery.',
@@ -694,12 +692,10 @@ export namespace schema {
             z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
           ),
         status: Status.check(z.meta({ examples: ['active'] })),
-        updatedAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When the subscription was last changed, as an ISO 8601 timestamp.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
+        updatedAt: Schema.dateTime().check(
+          z.describe('When the subscription was last changed, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
       })
       .check(
         z.describe(
@@ -729,12 +725,10 @@ export namespace schema {
             z.describe('Retry attempt number for this delivery, starting at 1.'),
             z.meta({ examples: [1] }),
           ),
-        createdAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When this delivery attempt was created, as an ISO 8601 timestamp.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
-          ),
+        createdAt: Schema.dateTime().check(
+          z.describe('When this delivery attempt was created, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+        ),
         error: z
           .optional(z.string())
           .check(
@@ -822,12 +816,10 @@ export namespace schema {
           z.describe('Address that sent the transfer.'),
           z.meta({ examples: ['0xe7687128b0a808c2831ff94d4f7b2fb35c65af38'] }),
         ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('Block timestamp as an ISO 8601 string.'),
-            z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
-          ),
+        timestamp: Schema.dateTime().check(
+          z.describe('Block timestamp as an ISO 8601 string.'),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
+        ),
         token: z.optional(
           z
             .object({
@@ -954,12 +946,10 @@ export namespace schema {
             z.describe('Index of the log within its block.'),
             z.meta({ examples: [0] }),
           ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-            z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
-          ),
+        timestamp: Schema.dateTime().check(
+          z.describe('When the block was produced, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
+        ),
         topics: z.array(Schema.Hash).check(
           z.describe(
             'Zero to four log topics; non-anonymous events start with the event signature hash.',
@@ -1051,12 +1041,10 @@ export namespace schema {
             z.describe('Number of transactions included in this block.'),
             z.meta({ examples: [3] }),
           ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('When the block was produced, as an ISO 8601 timestamp.'),
-            z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
-          ),
+        timestamp: Schema.dateTime().check(
+          z.describe('When the block was produced, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2026-01-14T18:38:03.685Z'] }),
+        ),
       })
       .check(z.describe('Payload for a `block:created` event (a new block header).')),
     'WebhookBlockEvent',
@@ -1089,12 +1077,10 @@ export namespace schema {
     context: z
       .optional(Context)
       .check(z.meta({ examples: [{ title: 'Prod USDC large transfers' }] })),
-    createdAt: z.iso
-      .datetime()
-      .check(
-        z.describe('When Tempo built this delivery envelope, as an ISO 8601 timestamp.'),
-        z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
-      ),
+    createdAt: Schema.dateTime().check(
+      z.describe('When Tempo built this delivery envelope, as an ISO 8601 timestamp.'),
+      z.meta({ examples: ['2026-01-14T18:38:03.000Z'] }),
+    ),
     id: z
       .string()
       .check(

package/src/apps/data/routes/zones.test.ts

@@ -95,16 +95,23 @@ function errorCodes(
   return resolveSchema(document, envelope?.properties?.['error'])?.properties?.['code']?.enum
 }
 
-const zoneReader = {
-  id: 'key_zone_withdrawal',
-  orgId: 'org_test',
-  scopes: ['data:read', `zone:${runtime.zone.chainId}:read`],
-  token: 'secret_zone_withdrawal',
-} satisfies TestApp.kvStore.Key
+const zoneReader = TestApp.zoneReader(
+  {
+    id: 'key_zone_withdrawal',
+    orgId: 'org_test',
+    scopes: ['data:read'],
+    token: 'secret_zone_withdrawal',
+  },
+  [runtime.zone.chainId],
+)
+/** Holds the readers' organization delegation for the Zone. */
+const db = TestApp.database()
+await TestApp.delegateZone(db, { chainIds: [runtime.zone.chainId, runtime.zone.chainId + 1] })
 
 function client(options: { keys?: readonly TestApp.kvStore.Key[] | undefined } = {}) {
   return TestApp.client({
     auth: { keys: options.keys ?? [zoneReader] },
+    db,
     zones: [
       TestApp.zone({
         chainId: runtime.zone.chainId,
@@ -330,12 +337,15 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
   )
 
   test('requires the matching Zone read scope', async () => {
-    const otherReader = {
-      id: 'key_other_zone_withdrawal',
-      orgId: 'org_test',
-      scopes: ['data:read', `zone:${runtime.zone.chainId + 1}:read`],
-      token: 'secret_other_zone_withdrawal',
-    } satisfies TestApp.kvStore.Key
+    const otherReader = TestApp.zoneReader(
+      {
+        id: 'key_other_zone_withdrawal',
+        orgId: 'org_test',
+        scopes: ['data:read'],
+        token: 'secret_other_zone_withdrawal',
+      },
+      [runtime.zone.chainId + 1],
+    )
     const response = await client({ keys: [otherReader] }).v1.zones.withdrawals[':senderTag'].$get(
       {
         param: { senderTag },
@@ -348,7 +358,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
     expect(response.status).toBe(403)
     expect(body.error.code).toBe('api_key_forbidden')
     expect(body.error.message).toBe(
-      `Chain ID ${runtime.zone.chainId} is a Zone. Use an API key granting \`zone:${runtime.zone.chainId}:read\`.`,
+      `Chain ID ${runtime.zone.chainId} is a Zone. Use an API key granting \`zone:read\` and tagged for Zone ${runtime.zone.chainId}, issued to an organization delegated that Zone.`,
     )
   })
 
@@ -369,6 +379,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
   test('rejects invalid sender tags and chain ids', async () => {
     const app = TestApp.create({
       auth: { keys: [zoneReader] },
+      db,
       zones: [
         TestApp.zone({
           chainId: runtime.zone.chainId,
@@ -408,6 +419,7 @@ describe('GET /v1/zones/withdrawals/:senderTag', () => {
   test('maps parent indexer failures to the upstream error contract', async () => {
     const app = TestApp.create({
       auth: { keys: [zoneReader] },
+      db,
       tidx: { baseUrl: 'http://127.0.0.1:1' },
       zones: [
         TestApp.zone({
@@ -571,12 +583,15 @@ describe('GET /v1/zones/deposits/:depositHash', () => {
     expect(response.status).toBe(401)
     expect(body.error.code).toBe('api_key_invalid')
 
-    const otherReader = {
-      id: 'key_other_zone_deposit',
-      orgId: 'org_test',
-      scopes: ['data:read', `zone:${runtime.zone.chainId + 1}:read`],
-      token: 'secret_other_zone_deposit',
-    } satisfies TestApp.kvStore.Key
+    const otherReader = TestApp.zoneReader(
+      {
+        id: 'key_other_zone_deposit',
+        orgId: 'org_test',
+        scopes: ['data:read'],
+        token: 'secret_other_zone_deposit',
+      },
+      [runtime.zone.chainId + 1],
+    )
     const denied = await client({ keys: [otherReader] }).v1.zones.deposits[':depositHash'].$get(
       { param: { depositHash }, query: { chainId: String(runtime.zone.chainId) } },
       auth(otherReader),
@@ -589,6 +604,7 @@ describe('GET /v1/zones/deposits/:depositHash', () => {
   test('rejects invalid hashes and unsupported Zones', async () => {
     const app = TestApp.create({
       auth: { keys: [zoneReader] },
+      db,
       zones: [
         TestApp.zone({
           chainId: runtime.zone.chainId,

package/src/apps/management/App.ts

@@ -90,7 +90,7 @@ export function management(options: management.Options = {}) {
     .route('/', orgs())
     .route('/', projects())
     .route('/', routeUsage())
-    .route('/', routesAccessRequests())
+    .route('/', routesAccessRequests(options.routesAccessRequests))
     .route('/', scopes())
     .route('/', usage())
     .route('/', verifiedTokenRequests())
@@ -110,6 +110,8 @@ export declare namespace management {
     consoleUrl?: string | undefined
     /** Legacy group-level transactional email sender. Prefer `App.create({ email })`. */
     email?: Email.Sender | undefined
+    /** Routes access request options, such as a reviewer notifier; omit to send no notices. */
+    routesAccessRequests?: routesAccessRequests.Options | undefined
     /** Webhook capability shared with the data group and host poller; omit or pass false to disable management. */
     webhook?: App.Webhook | false | undefined
   }

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

@@ -9,6 +9,7 @@ import * as TestApp from '../../../../test/App.js'
 import * as Containers from '../../../../test/containers.js'
 import * as ApiKeyAdmissions from '../../../db/tables/apiKeyAdmissions.js'
 import * as Memberships from '../../../db/tables/memberships.js'
+import * as ZoneDelegations from '../../../db/tables/zoneDelegations.js'
 import * as Keys from './api-keys.js'
 import * as Me from './me.js'
 import * as Orgs from './orgs.js'
@@ -244,7 +245,7 @@ test('publishes generator-ready OpenAPI contracts', async () => {
             "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
           },
           "403": {
-            "$ref": "#/components/schemas/ApiKeyForbiddenOrApiKeyIpForbiddenOrForbiddenOrScopeNotIssuableOrZoneKeyApprovalRequiredError",
+            "$ref": "#/components/schemas/ApiKeyForbiddenOrApiKeyIpForbiddenOrForbiddenOrScopeNotIssuableError",
           },
           "404": {
             "$ref": "#/components/schemas/ApiKeysNotEnabledOrOrganizationNotFoundOrProjectNotFoundError",
@@ -337,7 +338,7 @@ test('publishes generator-ready OpenAPI contracts', async () => {
             "$ref": "#/components/schemas/ApiKeyMalformedOrBodyInvalidOrParamInvalidError",
           },
           "403": {
-            "$ref": "#/components/schemas/ApiKeyForbiddenOrApiKeyIpForbiddenOrForbiddenOrZoneKeyApprovalRequiredError",
+            "$ref": "#/components/schemas/ForbiddenError",
           },
           "404": {
             "$ref": "#/components/schemas/ApiKeyNotFoundOrApiKeysNotEnabledOrOrganizationNotFoundOrProjectNotFoundError",
@@ -554,6 +555,7 @@ describe('keys', () => {
     await Memberships.create(db, { orgId: org.id, role: 'admin', userId: user.id })
     const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
     const expiresAt = new Date(Date.now() + 86_400_000).toISOString()
+    await TestApp.delegateZone(db, { chainIds: [421700001, 421700002], orgId: org.id })
 
     // Tags and expiry only narrow a key an admin could mint anyway, so they need no owner.
     const created = await TestApp.json(
@@ -617,8 +619,9 @@ describe('keys', () => {
     )
     await Memberships.create(db, { orgId: org.id, role: 'admin', userId: user.id })
     const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: org.id })
 
-    // Tags name the Zones the key reads; the organization's delegations bound them at request time.
+    // Tags name the Zones the key reads, and must stay within the organization's delegations.
     const response = await app.request(
       base,
       json('POST', admin, { scopes: ['zone:read'], zoneTags: [421700001] }),
@@ -630,6 +633,80 @@ describe('keys', () => {
     })
   })
 
+  test('generic Zone scopes are self-serve and bounded by delegated tags', async () => {
+    const db = TestApp.database()
+    const store = TestApp.kvStore({ keys: [] })
+    const app = createApp({ db, kv: { store } })
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+    const admin = await session(app)
+    const user = await TestApp.json(
+      await app.request('/v1/me', { headers: { cookie: admin } }),
+      Me.schema.User,
+    )
+    await Memberships.create(db, { orgId: org.id, role: 'admin', userId: user.id })
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: org.id })
+    const revoked = await ZoneDelegations.create(db, { accountsAll: true, chainId: 421700002, environment: 'production', orgId: org.id, tokensAll: true }) // prettier-ignore
+    await ZoneDelegations.revoke(db, revoked.id)
+    await TestApp.delegateZone(db, { chainIds: [421700003], environment: 'sandbox', orgId: org.id })
+    const mint = async (body: unknown) => {
+      const response = await app.request(base, json('POST', admin, body))
+      return { body: (await response.json()) as { error?: { code: string; message: string } }, status: response.status } // prettier-ignore
+    }
+
+    // Broadcasts need no delegation coverage at request time, so the delegation's existence bounds the tags at mint.
+    expect(await mint({ scopes: ['zone:write'] })).toMatchObject({
+      body: {
+        error: {
+          code: 'body_invalid',
+          message:
+            'invalid API key input: Zone scopes require `zoneTags` naming Zones the organization is delegated',
+        },
+      },
+      status: 400,
+    })
+    // Revoked, other-environment, and unknown Zones are all undelegated, for reads and writes alike.
+    for (const scope of ['zone:read', 'zone:write'])
+      for (const zoneTags of [[421700002], [421700003], [421700001, 421700009]])
+        expect(await mint({ scopes: [scope], zoneTags })).toMatchObject({
+          body: {
+            error: { code: 'body_invalid', message: expect.stringContaining('not delegated') },
+          },
+          status: 400,
+        })
+    expect((await mint({ scopes: ['zone:read'] })).status).toBe(400)
+    expect((await mint({ scopes: ['zone:read'], zoneTags: [421700001] })).status).toBe(200)
+
+    const created = await TestApp.json(
+      await app.request(
+        base,
+        json('POST', admin, { scopes: ['zone:read', 'zone:write'], zoneTags: [421700001] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    expect(created).toMatchObject({ scopes: ['zone:read', 'zone:write'], zoneTags: [421700001] })
+    expect(await ApiKeys.resolve(store, created.token)).toMatchObject({ zoneTags: [421700001] })
+
+    // Edits keep a Zone key inside its delegations; clearing the tags leaves a broadcasting key nowhere to broadcast.
+    const widened = await app.request(`${base}/${created.id}`, json('PATCH', admin, { zoneTags: [421700001, 421700002] })) // prettier-ignore
+    expect(widened.status).toBe(400)
+    expect(await widened.json()).toMatchObject({ error: { code: 'body_invalid' } })
+    const cleared = await app.request(`${base}/${created.id}`, json('PATCH', admin, { zoneTags: null })) // prettier-ignore
+    expect(cleared.status).toBe(400)
+    expect(await ApiKeys.resolve(store, created.token)).toMatchObject({ zoneTags: [421700001] })
+    const reader = await TestApp.json(
+      await app.request(base, json('POST', admin, { scopes: ['zone:read'], zoneTags: [421700001] })), // prettier-ignore
+      Keys.schema.createApiKey.Response,
+    )
+    const readerWidened = await app.request(`${base}/${reader.id}`, json('PATCH', admin, { zoneTags: [421700002] })) // prettier-ignore
+    expect(readerWidened.status).toBe(400)
+    // A read key may drop its tags: it then reads no Zone.
+    const readerCleared = await app.request(`${base}/${reader.id}`, json('PATCH', admin, { zoneTags: null })) // prettier-ignore
+    expect(readerCleared.status).toBe(200)
+    expect(await ApiKeys.resolve(store, reader.token)).not.toHaveProperty('zoneTags')
+  })
+
   test('derives CLI keys from the source tags and keeps their expiry within the session', async () => {
     const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
@@ -637,6 +714,7 @@ describe('keys', () => {
     const owner = await session(app)
     const { org, project } = await fixture(app, owner)
     const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    await TestApp.delegateZone(db, { chainIds: [421700002], orgId: org.id })
     const cli = await cliSession(app, owner, ['data:read', 'zone:read'])
     const mint = (body: unknown) =>
       app.request(base, { body: JSON.stringify(body), headers: cli.bearer, method: 'POST' })
@@ -675,7 +753,7 @@ describe('keys', () => {
     expect(shortened.expiresAt).toBe(sooner)
   })
 
-  test('protects Zone read issuance and updates while leaving rotation and revocation open', async () => {
+  test('refuses retired per-Zone read scopes and rotates tagged Zone read keys', async () => {
     const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
     const app = createApp({ db, kv: { store } })
@@ -686,15 +764,16 @@ describe('keys', () => {
       base,
       superAdminJson('POST', { scopes: ['zone:421700001:read'] }),
     )
-    expect(response.status).toBe(403)
-    expect(await response.json()).toMatchObject({ error: { code: 'zone_key_approval_required' } })
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
     for (const projectId of [project.id, undefined]) {
       const { record, token } = await ApiKeys.mint(store, {
         orgId: org.id,
         ...(projectId ? { projectId } : {}),
-        scopes: ['zone:421700001:read'],
+        scopes: ['zone:read'],
+        zoneTags: [421700001],
       })
-      // Approved issuance records an admission; rotation copies policies only from admitted keys.
+      // Rotation copies policies only from admitted keys.
       await db.transaction((tx) =>
         ApiKeyAdmissions.admit(tx, {
           expiresAt: null,
@@ -707,18 +786,17 @@ describe('keys', () => {
         }),
       )
       const path = projectId ? `${base}/${record.id}` : `/v1/orgs/${org.id}/api-keys/${record.id}`
-      // Rotation copies the approved scopes unchanged, so it needs no second approval.
       const rotation = await app.request(`${path}/rotate`, {
         headers: { cookie: owner },
         method: 'POST',
       })
       expect(rotation.status).toBe(200)
       const rotated = await TestApp.json(rotation, Keys.schema.rotateApiKey.Response)
-      expect(rotated.scopes).toEqual(['zone:421700001:read'])
+      expect([rotated.scopes, rotated.zoneTags]).toEqual([['zone:read'], [421700001]])
       expect(await ApiKeys.resolve(store, rotated.token)).not.toBeNull()
       if (projectId) {
         const update = await app.request(path, json('PATCH', owner, { allowedIps: [] }))
-        expect(update.status).toBe(403)
+        expect(update.status).toBe(200)
       }
       expect(await ApiKeys.resolve(store, token)).not.toBeNull()
       expect(
@@ -729,11 +807,13 @@ describe('keys', () => {
   })
 
   test('rotates a super-admin-issued Zone write key without delegating scope issuance', async () => {
+    const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
-    const app = createApp({ kv: { store } })
+    const app = createApp({ db, 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`
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: org.id })
     const source = await TestApp.json(
       await app.request(
         base,
@@ -741,7 +821,8 @@ describe('keys', () => {
           allowedIps: ['203.0.113.0/24'],
           environment: 'production',
           name: 'Privy',
-          scopes: ['zone:421700001:write'],
+          scopes: ['zone:write'],
+          zoneTags: [421700001],
         }),
       ),
       Keys.schema.createApiKey.Response,
@@ -759,7 +840,8 @@ describe('keys', () => {
       name: 'Privy',
       orgId: org.id,
       projectId: project.id,
-      scopes: ['zone:421700001:write'],
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
     })
     expect(replacement.createdBy).not.toBe('super_admin')
     expect(replacement.id).not.toBe(source.id)
@@ -834,10 +916,12 @@ describe('keys', () => {
   )
 
   test('rotates an organization-level super-admin-issued zone key', async () => {
+    const db = TestApp.database()
     const store = TestApp.kvStore({ keys: [] })
-    const app = createApp({ kv: { store } })
+    const app = createApp({ db, kv: { store } })
     const owner = await session(app)
     const { org, project } = await fixture(app, owner)
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: org.id })
     const { record: projectSource } = await ApiKeys.mint(store, {
       orgId: org.id,
       projectId: project.id,
@@ -859,7 +943,8 @@ describe('keys', () => {
       environment: 'production',
       name: 'Privy',
       orgId: org.id,
-      scopes: ['zone:421700001:write'],
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
     })
 
     const response = await app.request(`/v1/orgs/${org.id}/api-keys/${source.id}/rotate`, {
@@ -872,7 +957,8 @@ describe('keys', () => {
       environment: 'production',
       name: 'Privy',
       orgId: org.id,
-      scopes: ['zone:421700001:write'],
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
     })
     expect(replacement.projectId).toBeUndefined()
     expect(replacement.createdBy).not.toBe('super_admin')
@@ -913,10 +999,12 @@ describe('keys', () => {
       projectId: project.id,
       scopes: ['data:read', 'webhooks:write'],
     })
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: org.id })
     const { record: zone } = await ApiKeys.mintBounded(db, store, {
       createdBy: 'super_admin',
       orgId: org.id,
-      scopes: ['zone:421700001:write'],
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
     })
     const paths = [`${base}/${webhooks.id}`, `/v1/orgs/${org.id}/api-keys/${zone.id}`]
 
@@ -950,8 +1038,10 @@ describe('keys', () => {
         },
         {
           "caller": "admin",
-          "code": "scope_not_issuable",
-          "status": 403,
+          "scopes": [
+            "zone:write",
+          ],
+          "status": 200,
         },
         {
           "caller": "owner",
@@ -964,7 +1054,7 @@ describe('keys', () => {
         {
           "caller": "owner",
           "scopes": [
-            "zone:421700001:write",
+            "zone:write",
           ],
           "status": 200,
         },
@@ -1047,7 +1137,7 @@ describe('keys', () => {
     const source = await TestApp.json(
       await app.request(
         `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
-        superAdminJson('POST', { scopes: ['zone:421700001:write'] }),
+        superAdminJson('POST', { scopes: ['webhooks:write'] }),
       ),
       Keys.schema.createApiKey.Response,
     )

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

@@ -37,12 +37,10 @@ export namespace schema {
           ),
           z.meta({ examples: [['203.0.113.0/24', '2001:db8::1']] }),
         ),
-        createdAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When the key was minted (ISO 8601).'),
-            z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
-          ),
+        createdAt: Schema.dateTime().check(
+          z.describe('When the key was minted (ISO 8601).'),
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+        ),
         createdBy: z
           .optional(z.string())
           .check(
@@ -53,7 +51,7 @@ export namespace schema {
           .enum(['production', 'sandbox'])
           .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
         expiresAt: z
-          .optional(z.iso.datetime())
+          .optional(Schema.dateTime())
           .check(
             z.describe('When the key expires (ISO 8601). Absent for a non-expiring key.'),
             z.meta({ examples: ['2027-01-01T00:00:00.000Z'] }),
@@ -64,7 +62,7 @@ export namespace schema {
             z.describe('Opaque key id (`key_…`).'),
             z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
           ),
-        lastUsedAt: z.optional(z.iso.datetime()).check(
+        lastUsedAt: z.optional(Schema.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'] }),
         ),
@@ -220,7 +218,7 @@ export namespace schema {
         ),
         zoneTags: ApiKey.schema.ApiKey.shape.zoneTags.check(
           z.describe(
-            "Zone chain ids the key may read among the organization's delegations. Omit for a key that reads no Zone.",
+            "Zone chain ids the key may read or broadcast to among the organization's delegations. Required with `zone:read` or `zone:write`, naming only delegated Zones. Omit for a key that uses no Zone.",
           ),
         ),
       })
@@ -342,7 +340,9 @@ export namespace schema {
           zoneTags: z
             .optional(z.nullable(ApiKey.schema.ZoneTags))
             .check(
-              z.describe('Replacement Zone chain id tags, or `null` to read no Zone.'),
+              z.describe(
+                'Replacement Zone chain id tags, or `null` to use no Zone. Tags stay within delegated Zones.',
+              ),
               z.meta({ examples: [[421700001]] }),
             ),
         })
@@ -382,7 +382,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
               description: 'Malformed API key, invalid path, or invalid body.',
             },
             403: {
-              codes: ['scope_not_issuable', 'zone_key_approval_required'],
+              codes: ['scope_not_issuable'],
               description: 'The requested scopes are not issuable.',
             },
             404: {
@@ -454,6 +454,14 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
         try {
           const orgId = Auth.org(c).id
+          // Self-serve Zone read keys name only delegated Zones; derived keys copy their
+          // source's already bounded tags, and `zone:write` is checked inside the mint.
+          if (!source && body.scopes.includes('zone:read'))
+            await ApiKeys.ensureDelegatedTags(Db.get(c.get('db')), {
+              environment: body.environment,
+              orgId,
+              zoneTags: body.zoneTags,
+            })
           // Snapshot billing onto the record so the auth path throttles a
           // sandbox key to the public quota without a per-request billing read.
           // Only sandbox is gated; production keys carry no snapshot.
@@ -796,9 +804,8 @@ export function apiKeys(options: apiKeys.Options = {}) {
               description: 'Malformed API key, invalid path, or invalid body.',
             },
             403: {
-              codes: ['forbidden', 'zone_key_approval_required'],
-              description:
-                'Widening a reviewed Zone key, or changing anything but its tags and expiry, needs a new approved issuance request.',
+              codes: ['forbidden'],
+              description: 'The caller may not change this key.',
             },
             404: {
               codes: [
@@ -855,6 +862,14 @@ export function apiKeys(options: apiKeys.Options = {}) {
               message: 'An expiry can only move earlier. Mint a new key to extend it.',
               status: 400,
             })
+          // Replacement tags on a Zone key stay within the organization's delegations; `null`
+          // leaves it using no Zone, which narrows (and a write key refuses it inside the update).
+          if (body.zoneTags && record.scopes.some((scope) => scope.startsWith('zone:')))
+            await ApiKeys.ensureDelegatedTags(Db.get(c.get('db')), {
+              environment: record.environment,
+              orgId: record.orgId,
+              zoneTags: body.zoneTags,
+            })
           const updated = await ApiKeys.updateBounded(Db.get(c.get('db')), kv.store, keyId, body, {
             expectedOwner: { orgId: Auth.org(c).id, projectId: Auth.project(c).id },
             scopeCatalog: c.get('scopeCatalog'),
@@ -1091,7 +1106,7 @@ function canRotate(c: Context<App.Environment>, scopes: readonly Scope.Id[]) {
   if (principal?.type === 'super_admin') return true
   if (principal?.type !== 'session') return false
   const selfServe = Scope.selfServeFrom(c.get('scopeCatalog'))
-  // Rotation returns a new token, so copying restricted grants (Routes, webhooks, Zone, wildcard) stays owner-only.
+  // Rotation returns a new token, so copying restricted grants (Routes, webhooks, per-Zone, wildcard) stays owner-only.
   return (
     (!principal.cli || scopes.every((scope) => principal.cli!.scopes.includes(scope))) &&
     ((scopes.every((scope) => selfServe.includes(scope)) && !scopes.includes('management:write')) ||