tapimo 0.19.0 → 0.20.0

package/src/internal/ZoneAccess.ts

@@ -1,26 +1,33 @@
 import type { Context } from 'hono'
+import { HTTPException } from 'hono/http-exception'
 
 import * as Db from '../db/Db.js'
 import * as ZoneDelegations from '../db/tables/zoneDelegations.js'
 import type * as Metrics from '../Metrics.js'
-import * as Scope from '../Scope.js'
 import * as Auth from './Auth.js'
 import * as ExecutionContext from './ExecutionContext.js'
+import * as Response from './Response.js'
 import * as Store from './Store.js'
 import * as Timeout from './Timeout.js'
+import * as Timing from './Timing.js'
 import * as ZoneDelegation from './ZoneDelegation.js'
 
-/** Hono variables written by {@link authorize}, {@link deny}, and {@link settle}, read by the request logger. */
+/** Hono variables written by {@link ensure}, {@link authorize}, and {@link deny}, read by the request logger. */
 export type Variables = {
   /** Zone access decision for the Zone the request is about, recorded even when denied. */
   zoneAccess?: Access | undefined
-  /** Delegation evaluation started by {@link authorize} for the recorded access, awaited by {@link settle}. */
-  zoneDelegationDecision?: Promise<ZoneDelegation.Result> | undefined
+  /** Every decision {@link authorize} recorded for this request, metered once by {@link settle}. */
+  zoneAccessDecisions?: Access[] | undefined
+  /** The caller organization's active delegations once {@link ensure} settled; absent or failed denies every Zone read. */
+  zoneDelegations?: Delegations | undefined
+  /** The delegation read {@link ensure} started for this request, awaited by every later caller. */
+  zoneDelegationsPending?: Promise<Delegations> | undefined
 }
 
-/** Hono environment required by {@link check}, {@link authorize}, and {@link settle}. */
+/** Hono environment required by {@link ensure}, {@link check}, {@link authorize}, and {@link settle}. */
 export type Environment = {
   Variables: Auth.Variables &
+    Timing.Variables &
     Variables & {
       /** Authoritative store holding Zone delegations. */
       db: Db.Source
@@ -28,74 +35,136 @@ export type Environment = {
       metrics: Metrics.Metrics | undefined
       /** Cache store for memoized delegation reads. */
       store: Store.Store
+      /** Hosted Zones keyed by chain id; no Zones means no delegation reads. */
+      zones: ReadonlyMap<number, unknown>
     }
 }
 
-/** Bounded counter of Zone decisions by Zone, scope outcome, grant, and delegation agreement. */
+/** Bounded counter of Zone decisions by Zone, outcome, and grant. */
 export const decisionMetric = 'zone_access_decision_count'
 
-/** Counter of delegation reads that failed, leaving a decision without a shadow comparison. */
+/** Counter of failed delegation reads: `phase="request"` refused a request with a `503`, `phase="refresh"` was a background refresh that left the cached copy serving. */
 export const lookupFailureMetric = 'zone_delegation_lookup_failure_count'
 
-/** How long one organization's delegations are cached per colo; Postgres stays authoritative. */
+/** Age after which a cached delegation read is refreshed in the background while still answering. */
 export const delegationTtl = 30_000
 
-/** Longest a delegation read may run; the comparison is advisory, so it gives up early. */
-export const delegationTimeout = 2_000
+/** Oldest cached delegation read that may answer; beyond it the request reads Postgres. Bounds revocation latency per colo. */
+export const delegationMaxAge = 60_000
 
-/** Longest {@link settle} waits for a read still in flight once the handler returned. */
-export const settleGrace = 100
+/** Longest a delegation read (cache and Postgres together) may run before it fails. */
+export const delegationTimeout = 5_000
 
-/** Operation a Zone request performs; a write scope never reads and a read scope never broadcasts. */
+/** Operation a Zone request performs; a write scope never reads and a delegation never broadcasts. */
 export type Verb = 'read' | 'write'
 
 /** How a Zone request was admitted. */
-export type Grant = 'scope' | 'wildcard' | 'zone_token'
+export type Grant = 'delegation' | 'scope' | 'zone_token'
+
+/** The caller organization's active delegations as {@link ensure} left them. */
+export type Delegations =
+  | {
+      /** Active delegations across the organization's Zones in the key's environment. */
+      records: readonly ZoneDelegations.Record[]
+    }
+  | {
+      /** The read failed or timed out with no usable cached copy, so every delegated Zone read is unavailable. */
+      failed: true
+    }
 
 /** Recorded Zone access decision. */
 export type Access = {
   /** Lowercase account addresses the request is about; empty when not account-scoped. */
   accounts: readonly string[]
-  /** Whether the delegation decision agrees with the scope decision; absent until {@link settle} compares them. */
-  agreement?: boolean | undefined
   /** Zone chain id. */
   chainId: number
-  /** Delegation decision computed beside the scope decision; absent until {@link settle} runs or when no organization applies. */
+  /** Delegation decision for a read the key was otherwise eligible for; absent for writes, tokens, and ineligible keys. */
   delegation?: ZoneDelegation.Result | undefined
   /** Grant that admitted the request; absent when denied, including by a later check such as quota or sandbox. */
   grant?: Grant | undefined
-  /** Grant the scope decision produced, kept through {@link deny} because delegations replace scopes only. */
-  scopeGrant?: Grant | undefined
   /** Lowercase token addresses the request is about; empty when not token-scoped. */
   tokens: readonly string[]
   /** Requested operation. */
   verb: Verb
 }
 
+/**
+ * Loads the caller organization's active delegations on first demand and
+ * shares the read across the request, for API keys that can read or broadcast
+ * to a Zone at all. Call it before {@link check} or {@link eligible} decide;
+ * requests never touching a Zone pay nothing. Client cache directives are
+ * ignored. A read Postgres cannot answer refuses delegated Zone access with a
+ * retriable `503`.
+ */
+export function ensure<environment extends Environment>(
+  c: Context<environment>,
+): Promise<Delegations | undefined> {
+  const pending = c.get('zoneDelegationsPending' as never) as Promise<Delegations> | undefined
+  if (pending) return pending
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'api_key' || !zoneCapable(principal)) return Promise.resolve(undefined)
+  const zones = c.get('zones' as never) as ReadonlyMap<number, unknown> | undefined
+  if (!zones?.size) return Promise.resolve(undefined)
+  const owner = { environment: principal.environment, orgId: principal.orgId }
+  const started = Timing.time(c, 'zone_delegations', () => Cached.read(c, owner)).then(
+    (records): Delegations => ({ records }),
+    (): Delegations => {
+      metrics(c)?.count(lookupFailureMetric, 1, { phase: 'request' })
+      return { failed: true }
+    },
+  )
+  void started.then((delegations) => c.set('zoneDelegations' as never, delegations as never))
+  c.set('zoneDelegationsPending' as never, started as never)
+  return started
+}
+
 /**
  * Decides whether the caller may access one Zone without recording anything.
- * Filters narrowing a Zone list use this; the gate for the Zone a request is
- * about uses {@link authorize}. Scopes are inspected only here.
+ * Filters narrowing a Zone list use this after awaiting {@link ensure}; the gate
+ * for the Zone a request is about uses {@link authorize}. Without the request's
+ * addresses, only a delegation covering every account and token admits a read.
  */
 export function check<environment extends Environment>(
   c: Context<environment>,
   options: check.Options,
 ): check.Result {
-  const { chainId, verb, zoneToken = false } = options
-  const principal = Auth.getPrincipal(c)
-  const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
-  // A forwarded Zone token is the operative credential, so it outranks scopes.
-  const grant = ((): Grant | undefined => {
-    if (zoneToken) return 'zone_token'
-    if (scopes?.includes(Scope.wildcard)) return 'wildcard'
-    if (scopes?.includes(`zone:${chainId}:${verb}`)) return 'scope'
-    return undefined
-  })()
-  if (grant) return { allowed: true, grant }
-  return {
-    allowed: false,
-    error: { code: 'api_key_forbidden', message: denialMessage(options), status: 403 },
-  }
+  const gated = gate(c, options)
+  if (!('eligible' in gated)) return gated
+  const delegation = ZoneDelegation.decide({
+    accounts: [],
+    delegation: coverage(gated.record, { accounts: [], tokens: [] }),
+    tokens: [],
+  })
+  return conclude(options, delegation)
+}
+
+/**
+ * Whether the caller could read one Zone given a covering request: the key is
+ * tagged and scoped for it and its organization holds an active delegation.
+ * Selection filters use this before {@link authorize} decides each Zone with
+ * the request's addresses; an unreadable delegation counts, so `authorize` answers `503`.
+ */
+export function eligible<environment extends Environment>(
+  c: Context<environment>,
+  options: Pick<check.Options, 'chainId'>,
+): boolean {
+  const gated = gate(c, { chainId: options.chainId, verb: 'read' })
+  return 'eligible' in gated || gated.allowed || gated.error.status === 503
+}
+
+/**
+ * Whether a listing may include one Zone the caller reads, after awaiting
+ * {@link ensure}. Throws a `503` when the delegations could not be read, so a
+ * listing never silently omits Zones it could not verify.
+ */
+export function visible<environment extends Environment>(
+  c: Context<environment>,
+  options: Pick<check.Options, 'chainId'>,
+): boolean {
+  const result = check(c, { chainId: options.chainId, verb: 'read' })
+  if (!result.allowed && result.error.status === 503)
+    throw new HTTPException(503, { res: Response.error(c, result.error) })
+  return result.allowed
 }
 
 export declare namespace check {
@@ -126,42 +195,65 @@ export declare namespace check {
         error: Denial
       }
 
-  /** Denial error envelope fields. */
-  type Denial = {
-    /** Stable error code. */
-    code: 'api_key_forbidden'
-    /** Corrective guidance naming the missing grant. */
-    message: string
-    /** HTTP status. */
-    status: 403
-  }
+  /** Denial error envelope fields: a missing grant, or delegations that could not be read. */
+  type Denial =
+    | {
+        /** Stable error code. */
+        code: 'api_key_forbidden'
+        /** Corrective guidance naming the missing grant. */
+        message: string
+        /** HTTP status. */
+        status: 403
+      }
+    | {
+        /** Stable error code. */
+        code: 'zone_access_unavailable'
+        /** Guidance to retry. */
+        message: string
+        /** HTTP status. */
+        status: 503
+      }
 }
 
 /**
  * Decides whether the caller may access the Zone the request is about and
- * records the decision on the context for the request log. The caller
- * organization's delegations start loading here so {@link settle} can compare
- * them against the final scope decision without delaying the response.
+ * records the decision on the context for the request log. A read loads the
+ * delegations, then checks the requested accounts and tokens against the
+ * delegation's members; a failed read refuses the request with a retriable `503`.
  */
-export function authorize<environment extends Environment>(
+export async function authorize<environment extends Environment>(
   c: Context<environment>,
   options: authorize.Options,
-): authorize.Result {
-  const result = check(c, options)
+): Promise<authorize.Result> {
+  const addresses = { accounts: normalize(options.accounts), tokens: normalize(options.tokens) }
+  // A disconnect while the delegation or member reads are pending logs after the decision, so denials stay unbilled.
+  const { delegation, result } = await Auth.check(c, {
+    allows: (decided) => decided.result.allowed,
+    fn: async () => {
+      // Generic writes need the delegation too; a forwarded Zone token never does.
+      if (!options.zoneToken) await ensure(c)
+      const gated = gate(c, options)
+      if (!('eligible' in gated)) return { delegation: undefined, result: gated }
+      const delegation = await evaluate(c, gated, addresses)
+      if (delegation) return { delegation, result: conclude(options, delegation) }
+      const denied: ZoneDelegation.Result = { decision: 'deny', id: gated.record.id }
+      return { delegation: denied, result: unavailable(options) }
+    },
+  })
   const access: Access = {
-    accounts: normalize(options.accounts),
+    ...addresses,
     chainId: options.chainId,
-    ...(result.allowed ? { grant: result.grant, scopeGrant: result.grant } : {}),
-    tokens: normalize(options.tokens),
+    ...(delegation === undefined ? {} : { delegation }),
+    ...(result.allowed ? { grant: result.grant } : {}),
     verb: options.verb,
   }
   c.set('zoneAccess' as never, access as never)
-  const scope = delegationScope(c, access)
-  // Starts the evaluation behind the handler; `settle` awaits this same promise.
-  // A rejection is reported there, so an evaluation nobody settles stays quiet.
-  const decision = scope ? evaluate(c, access, scope) : undefined
-  decision?.catch(() => undefined)
-  c.set('zoneDelegationDecision' as never, decision as never)
+  // A later decision for the same Zone (raw RPC per method, relay per item) supersedes the earlier one.
+  const decisions = (c.get('zoneAccessDecisions' as never) as Access[] | undefined) ?? []
+  const index = decisions.findIndex((decision) => decision.chainId === access.chainId)
+  if (index === -1) decisions.push(access)
+  else decisions[index] = access
+  c.set('zoneAccessDecisions' as never, decisions as never)
   return result
 }
 
@@ -184,117 +276,174 @@ export function deny<environment extends Environment>(c: Context<environment>) {
   if (access?.grant === undefined) return
   const { grant: _grant, ...denied } = access
   c.set('zoneAccess' as never, denied as never)
+  const decisions = c.get('zoneAccessDecisions' as never) as Access[] | undefined
+  if (decisions) {
+    const index = decisions.indexOf(access)
+    if (index !== -1) decisions[index] = denied
+  }
+}
+
+/** Meters every Zone decision recorded for the request once the handler finished, after later refusals applied. */
+export function settle<environment extends Environment>(c: Context<environment>): void {
+  const decisions = c.get('zoneAccessDecisions' as never) as Access[] | undefined
+  // A disconnected client already emitted its log entry; its decisions were never final.
+  if (!decisions?.length || c.req.raw.signal.aborted) return
+  for (const access of decisions)
+    metrics(c)?.count(decisionMetric, 1, {
+      chain_id: access.chainId,
+      grant: access.grant ?? 'none',
+      outcome: access.grant === undefined ? 'deny' : 'allow',
+    })
+}
+
+/** A read the key may perform if its organization's delegation covers the request. */
+type Eligible = {
+  /** Marks the gate outcome as awaiting the delegation decision. */
+  eligible: true
+  /** The organization's active delegation for the Zone. */
+  record: ZoneDelegations.Record
 }
 
 /**
- * Computes the delegation decision for the recorded Zone access once the
- * handler finished and records it with the agreement flag and one bounded
- * metric. Agreement compares against the scope decision alone: later refusals
- * (quota, method allowlist, sandbox, workload identity) stay in place when
- * delegations replace scopes, so they are not disagreements. Admission is
- * already decided; a failed delegation read only leaves the comparison out.
+ * Applies the credential checks that need no addresses: a forwarded Zone token
+ * outranks everything, writes stay on `zone:<chainId>:write`, and a read needs
+ * `zone:read`, a tag naming the Zone, and an active delegation. `*` grants no Zone.
  */
-export async function settle<environment extends Environment>(
+function gate<environment extends Environment>(
   c: Context<environment>,
-): Promise<void> {
-  const access = c.get('zoneAccess' as never) as Access | undefined
-  if (!access) return
-  // A disconnected client already emitted its log entry without these fields.
-  if (c.req.raw.signal.aborted) return
-  const metrics = c.get('metrics' as never) as Metrics.Metrics | undefined
-  const tags = { chain_id: access.chainId, grant: access.grant ?? 'none', outcome: access.grant === undefined ? 'deny' : 'allow' } // prettier-ignore
-  const decision = c.get('zoneDelegationDecision' as never) as
-    | Promise<ZoneDelegation.Result>
-    | undefined
-  if (!decision) {
-    metrics?.count(decisionMetric, 1, { ...tags, agreement: 'skipped' })
-    return
-  }
-  // The evaluation usually finished behind the handler; a cold miss must not extend the response.
-  const pending = decision.then(
-    (value) => ({ value }),
-    () => ({ value: undefined }),
-  )
-  const outcome = await Timeout.run(() => pending, { timeout: settleGrace }).catch(() => undefined)
-  if (outcome === undefined) {
-    // The read finishes in the background to warm the cache; a late failure still counts.
-    ExecutionContext.waitUntil(c)?.(
-      pending.then(({ value }) => {
-        if (value === undefined) metrics?.count(lookupFailureMetric, 1)
-      }),
-    )
-    metrics?.count(decisionMetric, 1, { ...tags, agreement: 'pending' })
-    return
-  }
-  const delegation = outcome.value
-  if (!delegation) {
-    metrics?.count(lookupFailureMetric, 1)
-    metrics?.count(decisionMetric, 1, { ...tags, agreement: 'unavailable' })
-    return
+  options: check.Options,
+): check.Result | Eligible {
+  const { chainId, verb, zoneToken = false } = options
+  const principal = Auth.getPrincipal(c)
+  if (zoneToken) return { allowed: true, grant: 'zone_token' }
+  const refuse = (): check.Result => ({
+    allowed: false,
+    error: { code: 'api_key_forbidden', message: denialMessage(options), status: 403 },
+  })
+  if (principal?.type !== 'api_key') return refuse()
+  const { scopes } = principal.apiKey
+  // Absent tags mean no Zone, so a later delegation never widens an existing key.
+  const tagged = principal.zoneTags?.includes(chainId) ?? false
+  if (verb === 'write') {
+    // A stored per-Zone write scope keeps admitting its own Zone this release, exactly as before,
+    // until the write rewrite has run and the cleanup release strips it.
+    if (scopes.includes(`zone:${chainId}:write`)) return { allowed: true, grant: 'scope' }
+    // Broadcasts are account-signed, so the delegation's existence is the whole bound: revoking it
+    // stops the key, accounts and tokens are never checked, and the wildcard grants no Zone.
+    if (!scopes.includes('zone:write') || !tagged) return refuse()
+    if (lookupFailed(c)) return unavailable(options)
+    if (!delegationFor(c, chainId)) return refuse()
+    return { allowed: true, grant: 'scope' }
   }
-  const agreement = (delegation.decision === 'allow') === (access.scopeGrant !== undefined)
-  c.set('zoneAccess' as never, { ...access, agreement, delegation } as never)
-  metrics?.count(decisionMetric, 1, { ...tags, agreement: agreement ? 'agree' : 'disagree' })
+  if (!readable(principal) || !tagged) return refuse()
+  // Only keys a delegation could admit learn the read failed; others keep their 403.
+  if (lookupFailed(c)) return unavailable(options)
+  const record = delegationFor(c, chainId)
+  if (!record) return refuse()
+  return { eligible: true, record }
 }
 
-/**
- * Organization and environment whose delegations decide the request, or
- * undefined when no delegation applies: writes, anonymous and session callers
- * (no organization), and forwarded Zone tokens (the operative credential).
- */
-function delegationScope<environment extends Environment>(
+/** The organization's active delegation for one Zone; undefined when none, or when `ensure` never ran or failed, so callers fail closed. */
+function delegationFor<environment extends Environment>(
   c: Context<environment>,
-  access: Access,
-): ZoneDelegations.Owner | undefined {
-  const principal = Auth.getPrincipal(c)
-  // Broadcasts are user-signed, so they stay on key scopes and are never compared.
-  if (access.verb === 'write') return undefined
-  if (principal?.type !== 'api_key' || access.scopeGrant === 'zone_token') return undefined
-  return { environment: principal.environment, orgId: principal.orgId }
+  chainId: number,
+): ZoneDelegations.Record | undefined {
+  const delegations = c.get('zoneDelegations' as never) as Delegations | undefined
+  if (!delegations || 'failed' in delegations) return undefined
+  return delegations.records.find((candidate) => candidate.chainId === chainId)
+}
+
+/** Whether {@link ensure} ran and its delegation read failed with no recent copy to answer from. */
+function lookupFailed<environment extends Environment>(c: Context<environment>): boolean {
+  const delegations = c.get('zoneDelegations' as never) as Delegations | undefined
+  return delegations !== undefined && 'failed' in delegations
+}
+
+/** Refusal for a key a delegation might admit when the delegations could not be read. */
+function unavailable(options: check.Options): check.Result {
+  return {
+    allowed: false,
+    error: {
+      code: 'zone_access_unavailable',
+      message: `Zone ${options.chainId} access could not be verified. Retry the request.`,
+      status: 503,
+    },
+  }
+}
+
+/** Whether the key's scopes and tags let it read any Zone at all: `zone:read` plus at least one tag. */
+function readable(principal: Extract<Auth.Principal, { type: 'api_key' }>): boolean {
+  return principal.apiKey.scopes.includes('zone:read') && (principal.zoneTags?.length ?? 0) > 0
+}
+
+/** Whether the key's scopes and tags let it use any Zone at all, reading or broadcasting. */
+function zoneCapable(principal: Extract<Auth.Principal, { type: 'api_key' }>): boolean {
+  const { scopes } = principal.apiKey
+  return (
+    (scopes.includes('zone:read') || scopes.includes('zone:write')) &&
+    (principal.zoneTags?.length ?? 0) > 0
+  )
+}
+
+/** Maps a delegation decision onto the gate result for the requested Zone. */
+function conclude(options: check.Options, delegation: ZoneDelegation.Result): check.Result {
+  if (delegation.decision === 'allow') return { allowed: true, grant: 'delegation' }
+  return {
+    allowed: false,
+    error: { code: 'api_key_forbidden', message: denialMessage(options), status: 403 },
+  }
 }
 
 /**
- * Evaluates the caller organization's delegation for one recorded access: the
- * delegation rows are cached per organization and environment, and the
- * requested accounts and tokens are checked for membership in one statement
- * each, cached per address, so a request never loads a whole member set.
- * Client cache directives are ignored throughout. Rejections surface in {@link settle}.
+ * Decides an eligible read against the delegation's members: the requested
+ * accounts and tokens are checked for membership in one statement each, cached
+ * per address, so a request never loads a whole member set. Returns undefined
+ * when the member read failed, which the caller refuses as unavailable.
  */
 async function evaluate<environment extends Environment>(
   c: Context<environment>,
-  access: Access,
-  scope: ZoneDelegations.Owner,
-): Promise<ZoneDelegation.Result> {
-  const principal = Auth.getPrincipal(c)
+  eligible: Eligible,
+  addresses: Addresses,
+): Promise<ZoneDelegation.Result | undefined> {
+  const { record } = eligible
+  const decide = (delegation: ZoneDelegation.Delegation) =>
+    ZoneDelegation.decide({ ...addresses, delegation })
+  const listed = { accounts: !record.accountsAll, tokens: !record.tokensAll }
+  if (
+    (!listed.accounts || !addresses.accounts.length) &&
+    (!listed.tokens || !addresses.tokens.length)
+  )
+    return decide(coverage(record, { accounts: [], tokens: [] }))
   const db = Db.get(c.get('db' as never) as Db.Source)
   const store = Store.authoritative(c.get('store' as never) as Store.Store)
-  const records = await Store.memoize(() => ZoneDelegations.listActive(db, scope), {
-    flightTimeout: delegationTimeout,
-    key: `zone_delegations:v1:${scope.orgId}:${scope.environment}`,
-    store,
-    ttl: delegationTtl,
-  })
-  const record = records.find((candidate) => candidate.chainId === access.chainId)
-  const grant = access.scopeGrant
-  const decide = (delegation?: ZoneDelegation.Delegation) =>
-    ZoneDelegation.decide({
-      accounts: access.accounts,
-      delegation,
-      grant,
-      projectId: principal?.type === 'api_key' ? principal.projectId : undefined,
-      tokens: access.tokens,
-    })
-  // A key without its own grant is denied before coverage matters, so its members are never read.
-  if (!record || grant === undefined)
-    return decide(record && { accounts: [], id: record.id, projects: record.projects, tokens: [] })
   const wiring = { c, db, id: record.id, store }
-  const [accounts, tokens] = await Promise.all([
-    record.accountsAll
-      ? ('all' as const)
-      : covered({ ...wiring, addresses: access.accounts, kind: 'account' }),
-    record.tokensAll ? ('all' as const) : covered({ ...wiring, addresses: access.tokens, kind: 'token' }), // prettier-ignore
-  ])
-  return decide({ accounts, id: record.id, projects: record.projects, tokens })
+  try {
+    const [accounts, tokens] = await Promise.all([
+      listed.accounts ? covered({ ...wiring, addresses: addresses.accounts, kind: 'account' }) : [],
+      listed.tokens ? covered({ ...wiring, addresses: addresses.tokens, kind: 'token' }) : [],
+    ])
+    return decide(coverage(record, { accounts, tokens }))
+  } catch {
+    metrics(c)?.count(lookupFailureMetric, 1, { phase: 'request' })
+    return undefined
+  }
+}
+
+/** Builds the gate's view of a delegation from its row and the members already resolved. */
+function coverage(record: ZoneDelegations.Record, members: Addresses): ZoneDelegation.Delegation {
+  return {
+    accounts: record.accountsAll ? 'all' : members.accounts,
+    id: record.id,
+    tokens: record.tokensAll ? 'all' : members.tokens,
+  }
+}
+
+/** Lowercase accounts and tokens a request names. */
+type Addresses = {
+  /** Account addresses. */
+  accounts: readonly string[]
+  /** Token contract addresses. */
+  tokens: readonly string[]
 }
 
 /**
@@ -331,6 +480,106 @@ async function covered<environment extends Environment>(
   return addresses.filter((address) => hits.get(address) === '1' || found.has(address))
 }
 
+/**
+ * Per-colo delegation cache with stale-while-revalidate: entries younger than
+ * {@link delegationTtl} answer directly, older ones up to {@link delegationMaxAge}
+ * answer while a background read refreshes them, and anything older reads Postgres.
+ */
+namespace Cached {
+  type Entry = {
+    /** When Postgres returned the records, in epoch milliseconds. */
+    at: number
+    /** Active delegations at that time. */
+    records: readonly ZoneDelegations.Record[]
+  }
+
+  /** Keys whose background refresh this isolate started, by start time, so concurrent requests start one. */
+  const refreshing = new Map<string, number>()
+
+  export async function read<environment extends Environment>(
+    c: Context<environment>,
+    owner: ZoneDelegations.Owner,
+  ): Promise<readonly ZoneDelegations.Record[]> {
+    const deadline = performance.now() + delegationTimeout
+    const db = Db.get(c.get('db' as never) as Db.Source)
+    // Client cache directives never bypass or refresh authorization data.
+    const store = Store.authoritative(c.get('store' as never) as Store.Store)
+    // v2 entries carry their read time; v1 entries were bare records.
+    const key = `zone_delegations:v2:${owner.orgId}:${owner.environment}`
+    const entry = await Timing.time(c, 'zone_delegations_cache', () =>
+      Timeout.run(() => store.get(key), { timeout: delegationTimeout }).then(
+        decode,
+        () => undefined,
+      ),
+    )
+    const age = entry ? Date.now() - entry.at : Infinity
+    const wiring = { db, key, owner, store, waitUntil: ExecutionContext.waitUntil(c) }
+    if (entry && age <= delegationMaxAge) {
+      if (age > delegationTtl) refresh(c, wiring)
+      return entry.records
+    }
+    // A cache read that spent the budget never starts a query the caller no longer awaits.
+    const remaining = deadline - performance.now()
+    if (remaining <= 0) throw new Error('Zone delegation read exceeded its budget.')
+    // Present on a failed request, this stage shows how long Postgres (through Hyperdrive) took.
+    return Timing.time(c, 'zone_delegations_query', () => load({ ...wiring, timeout: remaining }))
+  }
+
+  type Options = {
+    /** Database to read. */
+    db: Db.Db
+    /** Cache key. */
+    key: string
+    /** Organization and environment whose delegations are read. */
+    owner: ZoneDelegations.Owner
+    /** Colo cache store. */
+    store: Store.Store
+    /** Keeps background work alive after the response; absent outside Workers. */
+    waitUntil: ExecutionContext.waitUntil.ReturnType
+  }
+
+  /** Reads Postgres within the timeout and caches the result; cache writes are best-effort and never delay it. */
+  async function load(options: Options & { timeout: number }) {
+    const { db, key, owner, store, timeout, waitUntil } = options
+    const records = await Timeout.run(() => ZoneDelegations.listActive(db, owner), { timeout })
+    const entry: Entry = { at: Date.now(), records }
+    const persist = store
+      .put(key, JSON.stringify(entry), { ttl: delegationMaxAge })
+      .catch(() => undefined)
+    waitUntil?.(persist)
+    return records
+  }
+
+  /** Refreshes an aging entry after the response; a failure leaves the entry answering until it is too old. */
+  function refresh<environment extends Environment>(c: Context<environment>, options: Options) {
+    const started = refreshing.get(options.key)
+    if (started !== undefined && Date.now() - started < delegationTimeout) return
+    refreshing.set(options.key, Date.now())
+    const work = load({ ...options, timeout: delegationTimeout })
+      .catch(() => {
+        // The request's metrics already flushed, so a late count flushes itself.
+        metrics(c)?.count(lookupFailureMetric, 1, { phase: 'refresh' })
+        metrics(c)?.flush()
+      })
+      .finally(() => refreshing.delete(options.key))
+    options.waitUntil?.(work)
+  }
+
+  function decode(raw: string | null): Entry | undefined {
+    if (raw === null) return undefined
+    try {
+      const entry = JSON.parse(raw) as Entry
+      return typeof entry.at === 'number' && Array.isArray(entry.records) ? entry : undefined
+    } catch {
+      return undefined
+    }
+  }
+}
+
+function metrics<environment extends Environment>(c: Context<environment>) {
+  return c.get('metrics' as never) as Metrics.Metrics | undefined
+}
+
 /** Lowercases addresses so logged accounts and tokens compare exactly. */
 function normalize(addresses: readonly string[] | undefined): readonly string[] {
   return addresses?.map((address) => address.toLowerCase()) ?? []
@@ -339,11 +588,14 @@ function normalize(addresses: readonly string[] | undefined): readonly string[]
 /** Denial guidance per verb, keeping each route's published wording. */
 function denialMessage(options: check.Options): string {
   const { chainId, suggestZoneToken = false, verb } = options
-  if (verb === 'write')
+  if (verb === 'write') {
+    const grant = `Broadcasting to zone ${chainId} requires \`zone:write\` with a tag for Zone ${chainId}, issued to an organization delegated that Zone`
     return suggestZoneToken
-      ? `Broadcasting to zone ${chainId} requires \`zone:${chainId}:write\`, or a Zone token via \`X-Authorization-Token\`.`
-      : `Broadcasting to zone ${chainId} requires \`zone:${chainId}:write\`.`
+      ? `${grant}, or a Zone token via \`X-Authorization-Token\`.`
+      : `${grant}.`
+  }
+  const grant = `Use an API key granting \`zone:read\` and tagged for Zone ${chainId}, issued to an organization delegated that Zone`
   return suggestZoneToken
-    ? `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`
-    : `Chain ID ${chainId} is a Zone. Use an API key granting \`zone:${chainId}:read\`.`
+    ? `Chain ID ${chainId} is a Zone. ${grant}, or pass a Zone token via \`X-Authorization-Token\`.`
+    : `Chain ID ${chainId} is a Zone. ${grant}.`
 }