tapimo 0.19.0 → 0.20.0

package/src/analytics/tables/requestEvents.test.ts

@@ -78,6 +78,13 @@ describe('readBillableCounts', () => {
           request_id: 'request-client-canceled',
           status: 499,
         },
+        // A Zone request refused because delegations could not be read never bills, nor do its retries.
+        {
+          ...rows[0]!,
+          error_code: 'zone_access_unavailable',
+          request_id: 'request-zone-access-unavailable',
+          status: 503,
+        },
         // Admitted handlers may already have reached upstreams, so the cancellation bills.
         {
           ...rows[0]!,
@@ -103,7 +110,7 @@ describe('readBillableCounts', () => {
         .toMatchInlineSnapshot(`
           [
             {
-              "count": 16,
+              "count": 18,
             },
           ]
         `)
@@ -554,9 +561,12 @@ describe('createQueueSink', () => {
   test('stores the Zone access decision and trusted client IP', async () => {
     const chainId = 421_700_001
     const rows: RequestEvents.Table[] = []
-    const key = { ...TestApp.key, scopes: ['data:read', `zone:${chainId}:read`] }
+    const key = TestApp.zoneReader({ ...TestApp.key, scopes: ['data:read'] }, [chainId])
+    const db = TestApp.database()
+    await TestApp.delegateZone(db, { chainIds: [chainId] })
     const app = TestApp.create({
       auth: { keys: [key] },
+      db,
       metrics: Metrics.cloudflare({
         analytics: RequestEvents.createQueueSink({
           async send(row) {
@@ -591,7 +601,7 @@ describe('createQueueSink', () => {
           "principal_type": "api_key",
           "zone_accounts": [],
           "zone_chain_id": 421700001,
-          "zone_grant": "scope",
+          "zone_grant": "delegation",
         },
         {
           "client_ip": null,

package/src/analytics/tables/requestEvents.ts

@@ -507,7 +507,8 @@ export async function readBillableCounts(
           'client_canceled',
           'forbidden',
           'payment_required',
-          'rate_limit_exceeded'
+          'rate_limit_exceeded',
+          'zone_access_unavailable'
         )
         AND key_environment = ${ClickHouseValue.literal(options.environment)}
         ${sandboxGate}
@@ -582,8 +583,8 @@ function event(entry: Log.Entry, context: Metrics.cloudflare.Context): Table {
     timings: entry.timings ?? {},
     zone_accounts: entry.zoneAccounts ?? [],
     zone_chain_id: entry.zoneChainId ?? null,
-    zone_decision_agreement:
-      entry.zoneDecisionAgreement === undefined ? null : Number(entry.zoneDecisionAgreement),
+    // Retired column: delegations decide admission, so there is no scope decision to compare against.
+    zone_decision_agreement: null,
     zone_delegation_decision: entry.zoneDelegationDecision ?? null,
     zone_delegation_id: entry.zoneDelegationId ?? null,
     zone_grant: entry.zoneGrant ?? null,

package/src/apps/data/App.test.ts

@@ -211,12 +211,15 @@ describe('zone chain gate', () => {
   /** A second zone, isolating per-zone grants. */
   const zoneB = 4_217_000_002
 
-  const legacyModeratoReader = {
-    id: 'key_legacy_moderato',
-    orgId: 'org_test',
-    scopes: ['data:read', 'indexer:query', `zone:${legacyModerato}:read`],
-    token: 'secret_legacy_moderato',
-  } satisfies TestApp.kvStore.Key
+  const legacyModeratoReader = TestApp.zoneReader(
+    {
+      id: 'key_legacy_moderato',
+      orgId: 'org_test',
+      scopes: ['data:read', 'indexer:query'],
+      token: 'secret_legacy_moderato',
+    },
+    [moderato],
+  )
 
   function zoneOptions(
     chainId: number,
@@ -229,21 +232,22 @@ describe('zone chain gate', () => {
     })
   }
 
-  /** Zone reader: holds the per-zone scope for `zone` (only). */
-  const zoneReader = {
-    id: 'key_zone',
-    orgId: 'org_test',
-    scopes: ['data:read', `zone:${zone}:read`],
-    token: 'secret_zone',
-  } satisfies TestApp.kvStore.Key
+  /** Zone reader: tagged for `zone` (only) under a delegated organization. */
+  const zoneReader = TestApp.zoneReader(
+    { id: 'key_zone', orgId: 'org_test', scopes: ['data:read'], token: 'secret_zone' },
+    [zone],
+  )
 
   /** Zone reader owned by an organization outside the OIDC rollout. */
-  const otherOrganizationReader = {
-    id: 'key_other_organization',
-    orgId: 'org_other',
-    scopes: ['data:read', `zone:${zone}:read`],
-    token: 'secret_other_organization',
-  } satisfies TestApp.kvStore.Key
+  const otherOrganizationReader = TestApp.zoneReader(
+    {
+      id: 'key_other_organization',
+      orgId: 'org_other',
+      scopes: ['data:read'],
+      token: 'secret_other_organization',
+    },
+    [zone],
+  )
 
   /** Zone writer: broadcasts signed transactions to `zone` without reading its data. */
   const zoneWriter = {
@@ -253,14 +257,40 @@ describe('zone chain gate', () => {
     token: 'secret_zone_writer',
   } satisfies TestApp.kvStore.Key
 
-  /** Full-access key: the wildcard covers every zone. */
+  /** Zone writer through the generic scope, tagged for `zone`. */
+  const taggedZoneWriter = {
+    id: 'key_tagged_zone_writer',
+    orgId: 'org_test',
+    scopes: ['data:read', 'zone:write'],
+    token: 'secret_tagged_zone_writer',
+    zoneTags: [zone],
+  } satisfies TestApp.kvStore.Key
+
+  /** Full-access key: the wildcard reads Zones only through an explicit `zone:read` plus tags. */
   const admin = {
     id: 'key_admin',
     orgId: 'org_test',
-    scopes: ['*'],
+    scopes: ['*', 'zone:read'],
     token: 'secret_admin',
+    zoneTags: [zone, zoneB],
   } satisfies TestApp.kvStore.Key
 
+  /** Wildcard key with tags but no `zone:read`: the wildcard grants no Zone. */
+  const adminUntagged = {
+    id: 'key_admin_untagged',
+    orgId: 'org_test',
+    scopes: ['*'],
+    token: 'secret_admin_untagged',
+    zoneTags: [zone],
+  } satisfies TestApp.kvStore.Key
+
+  /** Organizations of the readers hold whole-Zone delegations. */
+  const db = TestApp.database()
+  beforeAll(async () => {
+    await TestApp.delegateZone(db, { chainIds: [zone, zoneB, moderato] })
+    await TestApp.delegateZone(db, { chainIds: [zone], orgId: 'org_other' })
+  })
+
   /** Data reader without any zone grant. */
   const outsider = {
     id: 'key_outsider',
@@ -272,7 +302,8 @@ describe('zone chain gate', () => {
   /** A deployment serving two zones. */
   function zoneApp() {
     return TestApp.create({
-      auth: { keys: [admin, outsider, zoneReader, zoneWriter] },
+      auth: { keys: [admin, adminUntagged, outsider, taggedZoneWriter, zoneReader, zoneWriter] },
+      db,
       zones: [zoneOptions(zone), zoneOptions(zoneB)],
     })
   }
@@ -366,6 +397,7 @@ describe('zone chain gate', () => {
       .sign(privateKey)
     const app = TestApp.create({
       auth: { keys: [admin, otherOrganizationReader, zoneReader] },
+      db,
       logger: (entry) => void entries.push(entry),
       vercelOidc,
       zones: [
@@ -443,7 +475,7 @@ describe('zone chain gate', () => {
     expect(entries[4]).not.toHaveProperty('vercelOidc')
   })
 
-  test('the legacy Moderato id and read scope route to current upstreams', async () => {
+  test('the legacy Moderato id routes to current upstreams', async () => {
     const fetch = vi
       .spyOn(globalThis, 'fetch')
       .mockResolvedValueOnce(Response.json({ id: 1, jsonrpc: '2.0', result: '0x54e89ac3' }))
@@ -451,6 +483,7 @@ describe('zone chain gate', () => {
     try {
       const app = TestApp.create({
         auth: { keys: [legacyModeratoReader] },
+        db,
         rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
         tidx: { baseUrl: (chainId) => `https://${chainId}.tidx.test` },
         zones: true,
@@ -476,9 +509,11 @@ describe('zone chain gate', () => {
   })
 
   test('a Zone write scope cannot read Zone data', async () => {
-    const response = await zoneApp().request(`/v1/tokenlist?chainId=${zone}`, as(zoneWriter))
-    expect(response.status).toBe(403)
-    expect(await response.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
+    for (const writer of [zoneWriter, taggedZoneWriter]) {
+      const response = await zoneApp().request(`/v1/tokenlist?chainId=${zone}`, as(writer))
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
+    }
   })
 
   test('zone authorization applies to every data route', async () => {
@@ -497,30 +532,32 @@ describe('zone chain gate', () => {
     }
   })
 
-  test('the wildcard scope covers every zone', async () => {
+  test('a wildcard key reads only the delegated zones its explicit zone:read and tags name', async () => {
     const app = zoneApp()
     expect((await app.request(`/v1/tokenlist?chainId=${zone}`, as(admin))).status).toBe(200)
     expect((await app.request(`/v1/tokenlist?chainId=${zoneB}`, as(admin))).status).toBe(200)
+    // The wildcard alone grants no Zone, tags or not.
+    expect((await app.request(`/v1/tokenlist?chainId=${zone}`, as(adminUntagged))).status).toBe(403) // prettier-ignore
   })
 
-  test('a key without the zone scope is refused, naming the scope', async () => {
+  test('a key without the zone grant is refused, naming the grant', async () => {
     const app = zoneApp()
     const response = await app.request(`/v1/transfers?chainId=${zone}`, as(outsider))
     const body = (await response.json()) as { error: { code: string; message: string } }
 
     expect(response.status).toBe(403)
     expect(body.error.code).toBe('api_key_forbidden')
-    expect(body.error.message).toContain(`zone:${zone}:read`)
+    expect(body.error.message).toContain(`\`zone:read\` and tagged for Zone ${zone}`)
     expect(body.error.message).not.toContain('X-Authorization-Token')
   })
 
-  test('a zone scope does not grant another zone', async () => {
+  test('a zone tag does not grant another zone', async () => {
     const app = zoneApp()
     const response = await app.request(`/v1/transfers?chainId=${zoneB}`, as(zoneReader))
     const body = (await response.json()) as { error: { code: string; message: string } }
 
     expect(response.status).toBe(403)
-    expect(body.error.message).toContain(`zone:${zoneB}:read`)
+    expect(body.error.message).toContain(`tagged for Zone ${zoneB}`)
   })
 
   test('a caller-signed Zone token cannot authorize REST data', async () => {
@@ -638,12 +675,12 @@ describe('sandbox chain guard', () => {
   })
 
   test('rejects a sandbox key on a mainnet-backed Zone', async () => {
-    const key = {
-      ...sandbox,
-      scopes: ['data:read', `zone:${mainnetZone}:read`],
-    } satisfies TestApp.kvStore.Key
+    const key = TestApp.zoneReader({ ...sandbox, scopes: ['data:read'] }, [mainnetZone])
+    const db = TestApp.database()
+    await TestApp.delegateZone(db, { chainIds: [mainnetZone], environment: 'sandbox', orgId: key.orgId }) // prettier-ignore
     const client = TestApp.client({
       auth: { keys: [key] },
+      db,
       zones: [
         TestApp.zone({
           chainId: mainnetZone,

package/src/apps/data/App.ts

@@ -190,6 +190,7 @@ export function data(options: data.Options = {}) {
             message: '`include=zones` requires an API key with readable Zone scopes.',
             status: 403,
           })
+        await ZoneAccess.ensure(c)
         const zoneChainIds = ZoneSelection.readableChainIds(c, {
           parentChainId: selection.chainId,
           principal,
@@ -197,23 +198,33 @@ export function data(options: data.Options = {}) {
           tidx: tidx_config,
           zones,
         })
-        if (zoneChainIds.length === 0)
+        // Each candidate Zone is decided on its own against the request's
+        // addresses; the selection keeps the admitted ones and the recorded
+        // decision is an admitted one, before workload identity runs.
+        const zoneChainIds_readable: number[] = []
+        let unavailable: ZoneAccess.check.Denial | undefined
+        for (const zoneChainId of zoneChainIds) {
+          const access = await ZoneAccess.authorize(c, { ...pathAddresses(c), chainId: zoneChainId, verb: 'read' }) // prettier-ignore
+          if (access.allowed) zoneChainIds_readable.push(zoneChainId)
+          else if (access.error.status === 503) unavailable = access.error
+        }
+        // Answering with only the Zones that could be verified would silently drop the rest.
+        if (unavailable) return Response.error(c, unavailable)
+        if (zoneChainIds_readable.length === 0)
           return Response.error(c, {
             code: 'api_key_forbidden',
             message: 'The API key has no readable configured Zones.',
             status: 403,
           })
-        // Every selected Zone is readable; record one granted decision before
-        // workload identity runs so a refusal keeps its Zone attribution.
-        for (const zoneChainId of zoneChainIds)
-          ZoneAccess.authorize(c, { ...pathAddresses(c), chainId: zoneChainId, verb: 'read' })
+        const last = zoneChainIds_readable.at(-1)
+        c.set('zoneAccess', c.get('zoneAccessDecisions')?.find((decision) => decision.chainId === last)) // prettier-ignore
         const policy = c.get('vercelOidc')
         if (policy?.applies(principal)) {
           const results = await Auth.check(c, {
             allows: (results) => results.every((result) => !VercelOidc.authorizationError(result)),
             fn: () =>
               Promise.all(
-                zoneChainIds.flatMap((chainId) => {
+                zoneChainIds_readable.flatMap((chainId) => {
                   const zone = zones.get(chainId)
                   if (zone?.sourceId === undefined || !Viem.isMainnet(zone.sourceId)) return []
                   return [policy.verify(c.req.raw, zone)]
@@ -230,8 +241,8 @@ export function data(options: data.Options = {}) {
             return Response.error(c, error)
           }
         }
-        c.set('supportedChainIds', new Set([selection.chainId, ...zoneChainIds]))
-        c.set('zoneChainIds', zoneChainIds)
+        c.set('supportedChainIds', new Set([selection.chainId, ...zoneChainIds_readable]))
+        c.set('zoneChainIds', zoneChainIds_readable)
         return next()
       }
       c.set('chainId', selection.chainId)
@@ -260,7 +271,7 @@ export function data(options: data.Options = {}) {
       // Record the attempt first so a workload-identity refusal keeps its Zone
       // attribution; the raw RPC handler re-records per method afterwards.
       const zoneToken = Boolean(c.req.header(ZoneRpcAuthentication.headerName)?.trim())
-      const access = ZoneAccess.authorize(c, {
+      const access = await ZoneAccess.authorize(c, {
         ...pathAddresses(c),
         chainId,
         verb: 'read',
@@ -281,15 +292,20 @@ export function data(options: data.Options = {}) {
           return Response.error(c, error)
         }
       }
-      // Raw RPC decides and records per method in its handler; this gate only
-      // refuses callers holding no Zone grant at all.
+      // Raw RPC decides and records per method with the batch's accounts in its
+      // handler; this gate only refuses callers holding no Zone grant at all.
       if (selection.rpc) {
+        const write = ZoneAccess.check(c, { chainId, verb: 'write', zoneToken })
+        // An unreadable delegation passes too: the handler answers broadcasts 503 and reads the key cannot perform 403.
         const granted =
-          access.allowed || ZoneAccess.check(c, { chainId, verb: 'write', zoneToken }).allowed
+          access.allowed ||
+          ZoneAccess.eligible(c, { chainId }) ||
+          write.allowed ||
+          write.error.status === 503
         if (!granted) {
           return Response.error(c, {
             code: 'api_key_forbidden',
-            message: `Chain ID ${chainId} is a Zone. Use an API key granting \`zone:${chainId}:read\` (or \`zone:${chainId}:write\` for broadcasts), or pass a Zone token via \`X-Authorization-Token\`.`,
+            message: `Chain ID ${chainId} is a Zone. Use an API key granting \`zone:read\` and tagged for Zone ${chainId}, issued to an organization delegated that Zone (or \`zone:write\` with a tag for Zone ${chainId} for broadcasts), or pass a Zone token via \`X-Authorization-Token\`.`,
             status: 403,
           })
         }

package/src/apps/data/ZoneSelection.test.ts

@@ -53,29 +53,23 @@ describe('transaction activity Zone query', () => {
 })
 
 describe('readableChainIds', () => {
-  test('intersects the parent chain, read scopes, and configured routable Zones', () => {
-    const principal = apiKeyPrincipal({
-      scopes: [
-        'data:read',
-        `zone:${Zones.zoneMainnetInternal.id}:read`,
-        `zone:${Zones.zoneModeratoInternal.id}:read`,
-      ],
-    })
+  const both = [Zones.zoneMainnetInternal.id, Zones.zoneModeratoInternal.id]
+  const hosted = new Map(Zones.chains.map((zone) => [zone.id, zone]))
 
-    expect(
-      readable({
-        parentChainId: Viem.chainId.testnet,
-        principal,
-        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-      }),
-    ).toStrictEqual([Zones.zoneModeratoInternal.id])
-    expect(
-      readable({
-        parentChainId: Viem.chainId.mainnet,
-        principal,
-        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-      }),
-    ).toStrictEqual([Zones.zoneMainnetInternal.id])
+  test('intersects the parent chain, tags, delegations, and configured routable Zones', () => {
+    const principal = apiKeyPrincipal({ scopes: ['data:read', 'zone:read'], zoneTags: both })
+
+    expect(readable({ parentChainId: Viem.chainId.testnet, principal, zones: hosted }, both)).toStrictEqual([Zones.zoneModeratoInternal.id]) // prettier-ignore
+    expect(readable({ parentChainId: Viem.chainId.mainnet, principal, zones: hosted }, both)).toStrictEqual([Zones.zoneMainnetInternal.id]) // prettier-ignore
+  })
+
+  test('requires both a tag and a delegation for each Zone', () => {
+    const tagged = apiKeyPrincipal({ scopes: ['data:read', 'zone:read'], zoneTags: [Zones.zoneModeratoInternal.id] }) // prettier-ignore
+    const untagged = apiKeyPrincipal({ scopes: ['data:read', 'zone:read'] })
+
+    expect(readable({ parentChainId: Viem.chainId.testnet, principal: tagged, zones: hosted }, both)).toStrictEqual([Zones.zoneModeratoInternal.id]) // prettier-ignore
+    expect(readable({ parentChainId: Viem.chainId.testnet, principal: tagged, zones: hosted }, [Zones.zoneMainnetInternal.id])).toStrictEqual([]) // prettier-ignore
+    expect(readable({ parentChainId: Viem.chainId.testnet, principal: untagged, zones: hosted }, both)).toStrictEqual([]) // prettier-ignore
   })
 
   test('never treats broadcast-only Zone write scopes as readable', () => {
@@ -88,49 +82,26 @@ describe('readableChainIds', () => {
     })
 
     for (const parentChainId of [Viem.chainId.mainnet, Viem.chainId.testnet])
-      expect(
-        readable({
-          parentChainId,
-          principal,
-          zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-        }),
-      ).toStrictEqual([])
+      expect(readable({ parentChainId, principal, zones: hosted }, both)).toStrictEqual([])
   })
 
-  test('lets wildcard keys read every configured routable Zone of the parent chain', () => {
+  test('lets wildcard keys read delegated Zones only through an explicit zone:read and tags', () => {
     expect(
-      readable({
-        parentChainId: Viem.chainId.testnet,
-        principal: apiKeyPrincipal({ scopes: ['*'] }),
-        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-      }),
+      readable(
+        { parentChainId: Viem.chainId.testnet, principal: apiKeyPrincipal({ scopes: ['*', 'zone:read'], zoneTags: both }), zones: hosted }, // prettier-ignore
+        both,
+      ),
     ).toStrictEqual([Zones.zoneModeratoInternal.id])
+    expect(
+      readable({ parentChainId: Viem.chainId.testnet, principal: apiKeyPrincipal({ scopes: ['*'], zoneTags: both }), zones: hosted }, both), // prettier-ignore
+    ).toStrictEqual([])
   })
 
   test('filters sandbox keys by each Zone parent chain', () => {
-    const principal = apiKeyPrincipal({
-      environment: 'sandbox',
-      scopes: [
-        'data:read',
-        `zone:${Zones.zoneMainnetInternal.id}:read`,
-        `zone:${Zones.zoneModeratoInternal.id}:read`,
-      ],
-    })
+    const principal = apiKeyPrincipal({ environment: 'sandbox', scopes: ['data:read', 'zone:read'], zoneTags: both }) // prettier-ignore
 
-    expect(
-      readable({
-        parentChainId: Viem.chainId.testnet,
-        principal,
-        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-      }),
-    ).toStrictEqual([Zones.zoneModeratoInternal.id])
-    expect(
-      readable({
-        parentChainId: Viem.chainId.mainnet,
-        principal,
-        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
-      }),
-    ).toStrictEqual([])
+    expect(readable({ parentChainId: Viem.chainId.testnet, principal, zones: hosted }, both)).toStrictEqual([Zones.zoneModeratoInternal.id]) // prettier-ignore
+    expect(readable({ parentChainId: Viem.chainId.mainnet, principal, zones: hosted }, both)).toStrictEqual([]) // prettier-ignore
   })
 
   test('requires data read access and both upstreams', () => {
@@ -142,18 +113,16 @@ describe('readableChainIds', () => {
     const zones = new Map([[zone.id, zone]])
 
     expect(
-      readable({
-        parentChainId: zone.sourceId,
-        principal: apiKeyPrincipal({ scopes: [`zone:${zone.id}:read`] }),
-        zones,
-      }),
+      readable(
+        { parentChainId: zone.sourceId, principal: apiKeyPrincipal({ scopes: ['zone:read'], zoneTags: [zone.id] }), zones }, // prettier-ignore
+        [zone.id],
+      ),
     ).toStrictEqual([])
     expect(
-      readable({
-        parentChainId: zone.sourceId,
-        principal: apiKeyPrincipal({ scopes: ['data:read', `zone:${zone.id}:read`] }),
-        zones,
-      }),
+      readable(
+        { parentChainId: zone.sourceId, principal: apiKeyPrincipal({ scopes: ['data:read', 'zone:read'], zoneTags: [zone.id] }), zones }, // prettier-ignore
+        [zone.id],
+      ),
     ).toStrictEqual([])
   })
 })
@@ -191,12 +160,24 @@ describe('uniqueMatch', () => {
   })
 })
 
-/** Runs `readableChainIds` on a context carrying the principal. */
-function readable(options: ZoneSelection.readableChainIds.Options) {
+/** Runs `readableChainIds` on a context carrying the principal and its organization's whole-Zone delegations. */
+function readable(options: ZoneSelection.readableChainIds.Options, delegated: readonly number[]) {
   const c = new Context(new Request('http://tempo-api.test/'))
   c.set('principal' as never, options.principal as never)
+  const records = delegated.map((chainId) => ({
+    accountsAll: true,
+    chainId,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    environment: options.principal.environment,
+    id: `zd_${chainId}`,
+    orgId: options.principal.orgId,
+    projects: 'all',
+    tokensAll: true,
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  }))
+  c.set('zoneDelegations' as never, { records } as never)
   const chainIds = ZoneSelection.readableChainIds(c as never, options)
-  // Filtering decides visibility only; the data gate records the selected Zones.
+  // Filtering decides eligibility only; the data gate decides and records the selected Zones.
   expect(c.get('zoneAccess' as never)).toBeUndefined()
   return chainIds
 }
@@ -216,6 +197,7 @@ function apiKeyPrincipal(
     id: apiKey.id,
     orgId: apiKey.orgId,
     type: 'api_key',
+    ...(options.zoneTags === undefined ? {} : { zoneTags: options.zoneTags }),
   }
 }
 
@@ -223,5 +205,6 @@ declare namespace apiKeyPrincipal {
   type Options = {
     environment?: 'production' | 'sandbox' | undefined
     scopes: readonly string[]
+    zoneTags?: readonly number[] | undefined
   }
 }

package/src/apps/data/ZoneSelection.ts

@@ -7,7 +7,7 @@ import * as Viem from '../../internal/Viem.js'
 import * as ZoneAccess from '../../internal/ZoneAccess.js'
 import * as Scope from '../../Scope.js'
 
-/** Returns configured and routable Zones that an API key may read. */
+/** Returns configured and routable Zones an API key is eligible to read, after `ZoneAccess.ensure` settled; the gate decides each with the request addresses. */
 export function readableChainIds<environment extends ZoneAccess.Environment>(
   c: Context<environment>,
   options: readableChainIds.Options,
@@ -18,7 +18,7 @@ export function readableChainIds<environment extends ZoneAccess.Environment>(
 
   const chainIds = [...zones.values()].flatMap((zone) => {
     if (zone.sourceId !== parentChainId) return []
-    if (!ZoneAccess.check(c, { chainId: zone.id, verb: 'read' }).allowed) return []
+    if (!ZoneAccess.eligible(c, { chainId: zone.id })) return []
     if (
       principal.environment === 'sandbox' &&
       (zone.sourceId === undefined || Viem.isMainnet(zone.sourceId))