tapimo 0.19.0 → 0.20.0

package/src/internal/ZoneDelegation.test.ts

@@ -6,7 +6,6 @@ const token = `0x${'cd'.repeat(20)}`
 const delegation = {
   accounts: 'all',
   id: 'zd_read',
-  projects: 'all',
   tokens: 'all',
 } satisfies ZoneDelegation.Delegation
 
@@ -16,7 +15,6 @@ describe('decide', () => {
       ZoneDelegation.decide({
         accounts: [],
         delegation: undefined,
-        grant: 'scope',
         tokens: [],
       }),
     ).toMatchInlineSnapshot(`
@@ -28,7 +26,6 @@ describe('decide', () => {
       ZoneDelegation.decide({
         accounts: [],
         delegation: undefined,
-        grant: 'scope',
         tokens: [],
       }),
     ).toMatchInlineSnapshot(`
@@ -43,7 +40,6 @@ describe('decide', () => {
       ZoneDelegation.decide({
         accounts: [],
         delegation,
-        grant: 'scope',
         tokens: [],
       }),
     ).toMatchInlineSnapshot(`
@@ -56,33 +52,17 @@ describe('decide', () => {
       ZoneDelegation.decide({
         accounts: [account],
         delegation,
-        grant: 'wildcard',
         tokens: [token],
       }).decision,
     ).toBe('allow')
   })
 
-  test('narrows by project, with organization-wide keys needing all projects', () => {
-    const narrowed = { ...delegation, projects: ['prj_a'] }
-    const decide = (projectId: string | undefined) =>
-      ZoneDelegation.decide({ accounts: [], delegation: narrowed, grant: 'scope', projectId, tokens: [] }) // prettier-ignore
-        .decision
-    expect([decide('prj_a'), decide('prj_b'), decide(undefined)]).toMatchInlineSnapshot(`
-      [
-        "allow",
-        "deny",
-        "deny",
-      ]
-    `)
-  })
-
   test('narrows by account, with zone-wide requests needing all accounts', () => {
     const narrowed = { ...delegation, accounts: [account] }
     const decide = (accounts: readonly string[]) =>
       ZoneDelegation.decide({
         accounts,
         delegation: narrowed,
-        grant: 'scope',
         tokens: [],
       }).decision
     expect([decide([account]), decide([account, `0x${'ef'.repeat(20)}`]), decide([])])
@@ -101,7 +81,6 @@ describe('decide', () => {
       ZoneDelegation.decide({
         accounts: [],
         delegation: narrowed,
-        grant: 'scope',
         tokens,
       }).decision
     expect([decide([token]), decide([`0x${'ef'.repeat(20)}`]), decide([])]).toMatchInlineSnapshot(`
@@ -113,21 +92,11 @@ describe('decide', () => {
     `)
   })
 
-  test('denies a key whose own scopes refuse, naming the delegation it would have used', () => {
-    expect(ZoneDelegation.decide({ accounts: [], delegation, tokens: [] })).toMatchInlineSnapshot(`
-      {
-        "decision": "deny",
-        "id": "zd_read",
-      }
-    `)
-  })
-
   test('reports the delegation id even when its narrowing denies', () => {
     expect(
       ZoneDelegation.decide({
         accounts: [],
         delegation: { ...delegation, accounts: [account] },
-        grant: 'scope',
         tokens: [],
       }),
     ).toMatchInlineSnapshot(`
@@ -144,8 +113,6 @@ describe('schema', () => {
     expect(ZoneDelegation.schema.AddressList.parse([`0x${'AB'.repeat(20)}`])).toEqual([account])
     expect(ZoneDelegation.schema.AddressList.safeParse([]).success).toBe(false)
     expect(ZoneDelegation.schema.AddressList.safeParse(['0xnope']).success).toBe(false)
-    expect(ZoneDelegation.schema.Projects.parse('all')).toBe('all')
-    expect(ZoneDelegation.schema.Projects.safeParse(['key_1']).success).toBe(false)
   })
 })
 
@@ -159,8 +126,7 @@ describe('fromKeys', () => {
         { ...base, environment: 'sandbox', id: 'key_3', scopes: ['zone:421700002:read'] },
         { ...base, id: 'key_4', name: 'Integration', orgId: 'org_b', scopes: ['*', 'zone:421700003:read'] }, // prettier-ignore
         { ...base, id: 'key_5', scopes: ['data:read'] },
-        { ...base, id: 'key_6', orgId: 'org_c', projectId: 'prj_a', scopes: ['zone:421700002:read'] }, // prettier-ignore
-        { ...base, id: 'key_7', orgId: 'org_c', projectId: 'prj_b', scopes: ['zone:421700002:read'] }, // prettier-ignore
+        { ...base, id: 'key_6', orgId: 'org_c', scopes: ['zone:421700002:read'] },
       ]),
     ).toMatchInlineSnapshot(`
       {
@@ -170,7 +136,6 @@ describe('fromKeys', () => {
             "chainId": 421700002,
             "environment": "production",
             "orgId": "org_a",
-            "projects": "all",
             "tokensAll": true,
           },
           {
@@ -178,7 +143,6 @@ describe('fromKeys', () => {
             "chainId": 421700002,
             "environment": "sandbox",
             "orgId": "org_a",
-            "projects": "all",
             "tokensAll": true,
           },
           {
@@ -186,10 +150,6 @@ describe('fromKeys', () => {
             "chainId": 421700002,
             "environment": "production",
             "orgId": "org_c",
-            "projects": [
-              "prj_a",
-              "prj_b",
-            ],
             "tokensAll": true,
           },
         ],

package/src/internal/ZoneDelegation.ts

@@ -3,7 +3,6 @@ import * as z from 'zod/mini'
 import type * as ApiKey from '../ApiKey.js'
 import * as Scope from '../Scope.js'
 import * as Schema from './Schema.js'
-import type * as ZoneAccess from './ZoneAccess.js'
 
 /** Resources a delegation covers: every resource, or an explicit lowercase list. */
 export type Selection = 'all' | readonly string[]
@@ -14,8 +13,6 @@ export type Delegation = {
   accounts: Selection
   /** Delegation id (`zd_…`). */
   id: string
-  /** Project ids the delegation covers, or `all`. */
-  projects: Selection
   /** Requested tokens the delegation lists, or `all`. */
   tokens: Selection
 }
@@ -25,7 +22,7 @@ export type Decision = 'allow' | 'deny'
 
 /** Delegation decision for one request. */
 export type Result = {
-  /** Whether delegations alone would admit the request. */
+  /** Whether the organization's delegation covers the request. */
   decision: Decision
   /** Active delegation for the Zone, when one exists; absent when the organization holds none. */
   id?: string | undefined
@@ -39,18 +36,6 @@ export namespace schema {
       z.describe('API-key environment the delegation applies to.'),
       z.meta({ examples: ['production'] }),
     )
-  export const Projects = z
-    .union([
-      z.literal('all'),
-      z.pipe(
-        z.array(z.string().check(z.regex(/^prj_[A-Za-z0-9_-]+$/))).check(z.maxLength(1_000)),
-        z.transform((ids) => [...new Set(ids)]),
-      ),
-    ])
-    .check(
-      z.describe('Project ids the delegation covers, or `all`.'),
-      z.meta({ examples: ['all'] }),
-    )
   export const AddressList = z
     .pipe(
       z.array(Schema.Address).check(z.minLength(1), z.maxLength(1_000)),
@@ -63,16 +48,13 @@ export namespace schema {
 }
 
 /**
- * Decides whether an organization's delegation admits one Zone read from a key
- * whose own scopes allow it. The key's project must be covered, and every
+ * Decides whether an organization's delegation covers one Zone read: every
  * requested account and token must be covered (a request naming none needs
- * `all`).
+ * `all`). The key's own scope and tags are checked by the gate before this runs.
  */
 export function decide(options: decide.Options): Result {
-  const { accounts, delegation, grant, projectId, tokens } = options
+  const { accounts, delegation, tokens } = options
   if (!delegation) return { decision: 'deny' }
-  // The key's own Zone scope stays its allowlist: a delegation grants nothing to a key without one.
-  if (grant === undefined) return { decision: 'deny', id: delegation.id }
   // A request naming nothing from a list sees everything (raw RPC, unfiltered lists,
   // balances across every token), so only an `all` selection covers it.
   const covers = (selection: Selection, values: readonly string[]) => {
@@ -80,12 +62,7 @@ export function decide(options: decide.Options): Result {
     const members = new Set(selection)
     return values.length > 0 && values.every((value) => members.has(value))
   }
-  // A key without a project is organization-wide, so only an `all` delegation covers it.
-  const projectCovered =
-    delegation.projects === 'all' ||
-    (projectId !== undefined && delegation.projects.includes(projectId))
-  const allowed =
-    projectCovered && covers(delegation.accounts, accounts) && covers(delegation.tokens, tokens)
+  const allowed = covers(delegation.accounts, accounts) && covers(delegation.tokens, tokens)
   return { decision: allowed ? 'allow' : 'deny', id: delegation.id }
 }
 
@@ -96,10 +73,6 @@ export declare namespace decide {
     accounts: readonly string[]
     /** The organization's active delegation for the Zone, when one exists. */
     delegation?: Delegation | undefined
-    /** Grant the key's own scopes produced for this request; absent when they refuse it. */
-    grant?: ZoneAccess.Grant | undefined
-    /** Project attributed to the API key, when any. */
-    projectId?: string | undefined
     /** Lowercase token contracts the request is about; empty when not token-scoped. */
     tokens: readonly string[]
   }
@@ -107,10 +80,9 @@ export declare namespace decide {
 
 /**
  * Derives the whole-zone delegations that preserve each key's current Zone
- * read scopes, one per organization, environment, and Zone, covering the
- * projects of the source keys. Write scopes need no delegation. Wildcard keys
- * are returned separately and derive nothing: a delegation for them is a
- * decision, not a backfill.
+ * read scopes, one per organization, environment, and Zone. Write scopes need
+ * no delegation. Wildcard keys are returned separately and derive nothing: a
+ * delegation for them is a decision, not a backfill.
  */
 export function fromKeys(keys: readonly fromKeys.Key[]): fromKeys.Result {
   const delegations = new Map<string, fromKeys.Input>()
@@ -124,19 +96,11 @@ export function fromKeys(keys: readonly fromKeys.Key[]): fromKeys.Result {
     for (const scope of key.scopes) {
       const chainId = Scope.zoneReadChainId(scope)
       if (chainId === undefined) continue
-      const id = `${key.orgId}:${key.environment}:${chainId}`
-      const existing = delegations.get(id)
-      // Projects widen to the union of the source keys; an organization-wide key means every project.
-      const projects: Selection =
-        existing?.projects === 'all' || key.projectId === undefined
-          ? 'all'
-          : [...new Set([...(existing?.projects ?? []), key.projectId])]
-      delegations.set(id, {
+      delegations.set(`${key.orgId}:${key.environment}:${chainId}`, {
         accountsAll: true,
         chainId,
         environment: key.environment,
         orgId: key.orgId,
-        projects,
         tokensAll: true,
       })
     }
@@ -146,7 +110,7 @@ export function fromKeys(keys: readonly fromKeys.Key[]): fromKeys.Result {
 
 export declare namespace fromKeys {
   /** Key fields the derivation reads. */
-  type Key = Pick<ApiKey.ApiKey, 'environment' | 'id' | 'orgId' | 'projectId' | 'scopes'> & {
+  type Key = Pick<ApiKey.ApiKey, 'environment' | 'id' | 'orgId' | 'scopes'> & {
     /** Human-readable key name, when set. */
     name?: string | undefined
   }
@@ -161,8 +125,6 @@ export declare namespace fromKeys {
     environment: ApiKey.ApiKey['environment']
     /** Receiving organization id. */
     orgId: string
-    /** Projects of the source keys, or `all` when any key is organization-wide. */
-    projects: Selection
     /** Every token is covered. */
     tokensAll: true
   }

package/src/internal/ZoneDelegationApproval.test.ts

@@ -0,0 +1,22 @@
+import * as ZoneDelegationApproval from './ZoneDelegationApproval.js'
+
+describe('active', () => {
+  test('rejects absent, expired, malformed, or incomplete session identities', () => {
+    const member = {
+      email: 'staff@tempo.xyz',
+      eligible: false,
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      id: 'employee_staff',
+    }
+    expect(ZoneDelegationApproval.active(member)).toBe(true)
+    for (const value of [
+      null,
+      undefined,
+      { ...member, expiresAt: new Date().toISOString() },
+      { ...member, expiresAt: 'invalid' },
+      { ...member, id: '' },
+      { ...member, email: '' },
+    ])
+      expect(ZoneDelegationApproval.active(value)).toBe(false)
+  })
+})

package/src/internal/{ZoneKeyApproval.ts → ZoneDelegationApproval.ts}

@@ -1,16 +1,9 @@
-import * as Scope from '../Scope.js'
-
-/** Number of independent approvals required for Zone read credentials. */
+/** Number of independent approvals required to create a Zone delegation. */
 export const quorum = 2
 
 /** Maximum lifetime of an approval, matching the request lifetime and bounded by its authenticated session. */
 export const approvalLifetime = 24 * 60 * 60 * 1_000
 
-/** Returns whether scopes grant access subject to Zone read approval. */
-export function required(scopes: readonly string[]): boolean {
-  return scopes.some((scope) => scope === '*' || Scope.parseZone(scope)?.verb === 'read')
-}
-
 /** An authenticated identity supplied by the host's verified identity integration. */
 export type Member = {
   /** Verified employee email, used for attribution only. */
@@ -41,11 +34,11 @@ export type Status = {
 /** Looks up current account and group status, throwing when fresh results are unavailable. */
 export type Lookup = (ids: readonly string[]) => Promise<readonly Status[]>
 
-/** Expected rejection of a Zone key request or an unapproved issuance path. */
+/** Expected rejection of a delegation request, or of a direct write that widens Zone access. */
 export class RequiredError extends Error {
-  override name = 'ZoneKeyApproval.RequiredError'
+  override name = 'ZoneDelegationApproval.RequiredError'
   constructor(
-    message = 'Zone read keys require two independent group approvals through the admin key-request workflow.',
+    message = 'Zone delegations require two independent group approvals through the admin delegation-request workflow.',
   ) {
     super(message)
   }

package/src/internal/ZoneKeyRewrite.ts

@@ -0,0 +1,231 @@
+import type * as ApiKey from '../ApiKey.js'
+import * as ApiKeys from '../ApiKeys.js'
+import type * as Db from '../db/Db.js'
+import * as ApiKeyAdmissions from '../db/tables/apiKeyAdmissions.js'
+import * as Organizations from '../db/tables/organizations.js'
+import * as ZoneDelegations from '../db/tables/zoneDelegations.js'
+import type * as Store from './Store.js'
+
+/** The additive rewrite adding `zone:read` plus tags beside stored per-Zone read scopes, and what it leaves out. */
+export type Plan = {
+  /** Keys holding per-Zone read scopes, with the scopes and tags they end up holding; `complete` ones are only checked. */
+  changes: readonly Change[]
+  /** Keys expiring within a minute; KV refuses their TTL and they lapse on their own, so they are left unchanged. */
+  expiring: readonly Key[]
+  /** Keys whose rewritten record the schema refuses (say, past the tag limit); left unchanged for a manual fix. */
+  invalid: readonly Key[]
+  /** Live, unfenced key records read from the store. */
+  keys: number
+  /** Keys whose per-Zone write Zones differ from their read Zones; one tag list cannot express both, so they are re-minted by hand. */
+  mixed: readonly Key[]
+  /** Active delegations listing members for a planned Zone; apply refuses until they are whole-Zone. */
+  narrow: readonly ZoneDelegations.Record[]
+  /** Zone slots an admin revoked that a planned key still reads through its scope; the key stays unwritten until an admin delegates it again. */
+  revoked: readonly ZoneDelegations.Record[]
+  /** Keys owned by themselves (no organization row); left unchanged until `PUT /api-keys/{id}/organization` assigns one. */
+  orgless: readonly Key[]
+  /** Keys holding `zone:read` without tags or per-Zone scopes; they read no Zone and are listed, not changed. */
+  tagless: readonly Key[]
+  /** Zone chain ids named by per-Zone scopes that this deployment does not serve; no tag, delegations revoked. */
+  unconfigured: readonly number[]
+  /** Records the store could not read (expired, or scopes outside the catalog); left unchanged. */
+  unreadableRecords: number
+  /** Wildcard keys, listed for an explicit decision and left unchanged. */
+  wildcard: readonly Key[]
+}
+
+/** A key named in a plan. */
+export type Key = {
+  /** Key environment. */
+  environment: ApiKey.ApiKey['environment']
+  /** Key id. */
+  id: string
+  /** Human-readable key name, when set. */
+  name?: string | undefined
+  /** Owning organization id, or the key id for legacy keys minted without one. */
+  orgId: string
+  /** Attributed project id, when any. */
+  projectId?: string | undefined
+}
+
+/** One key the rewrite changes or checks. */
+export type Change = Key & {
+  /** Whether the record already holds `zone:read` and every tag; only its delegations are ensured, nothing is written. */
+  complete: boolean
+  /** Zones the per-Zone scopes grant whose delegation an admin revoked; the key is left unwritten while any remain. */
+  revoked: readonly number[]
+  /** Scopes the key holds after the rewrite. */
+  scopes: readonly string[]
+  /** Zones the per-Zone scopes grant that lack any delegation for the organization; applying ensures one for each. */
+  undelegated: readonly number[]
+  /** Zone chain ids the key reads after the rewrite. */
+  zoneTags: readonly number[]
+}
+
+/** A plan after its changes were written. */
+export type Applied = Plan & {
+  /** Whole-Zone delegations this run created so rewritten keys keep their reads. */
+  createdDelegations: number
+  /** Active delegations for unconfigured Zones this run revoked. */
+  revokedDelegations: number
+  /** Records this run rewrote. */
+  rewritten: number
+}
+
+/**
+ * Derives the rewrite from the live key store without writing: every key
+ * holding a per-Zone read scope, the tags it would carry, and which of those
+ * Zones its organization is not yet delegated.
+ */
+export async function plan(options: Options): Promise<Plan> {
+  const { db, store, zones } = options
+  return summarize(db, await ApiKeys.planZoneReadRewrite(store, { zones }))
+}
+
+/**
+ * Rewrites every planned key so it keeps the reads it has today: ensures a
+ * whole-Zone delegation for each tagged Zone without one, then writes each
+ * record under its admission lock. Self-owned keys, and keys reading a Zone
+ * whose delegation an admin revoked, are skipped and reported. Throws
+ * {@link NarrowDelegationsError} before writing anything when an active
+ * delegation for a planned Zone lists members.
+ */
+export async function apply(options: Options): Promise<Applied> {
+  const { db, store, zones } = options
+  const planned = await ApiKeys.planZoneReadRewrite(store, { zones })
+  const summary = await summarize(db, planned)
+  if (summary.narrow.length) throw new NarrowDelegationsError(summary.narrow)
+  // A key reading a Zone an admin revoked keeps its scope untouched, so the gap stays in the plan.
+  const rewritable = summary.changes.filter(({ revoked }) => revoked.length === 0)
+  // Keys of one organization, environment, and Zone share a slot; one whole-Zone row covers them all.
+  const slots = new Map<string, ZoneDelegations.Scope>()
+  for (const change of rewritable)
+    for (const chainId of change.undelegated)
+      slots.set(`${change.orgId}:${change.environment}:${chainId}`, { chainId, environment: change.environment, orgId: change.orgId }) // prettier-ignore
+  let createdDelegations = 0
+  for (const slot of slots.values()) {
+    // Delegations grant reads only, so a whole-Zone row restores exactly what the scopes granted.
+    const result = await ZoneDelegations.ensure(db, { ...slot, accountsAll: true, tokensAll: true })
+    if (result.created) createdDelegations += 1
+  }
+  // Delegations for the unconfigured Zones an owner's own keys name grant nothing; they go with the tags.
+  let revokedDelegations = 0
+  const unconfiguredBy = new Map<string, Set<number>>()
+  for (const { record, unconfigured } of planned.changes) {
+    const owner = `${record.orgId}:${record.environment}`
+    unconfiguredBy.set(owner, new Set([...(unconfiguredBy.get(owner) ?? []), ...unconfigured]))
+  }
+  for (const [owner, chainIds] of unconfiguredBy) {
+    if (chainIds.size === 0) continue
+    const [orgId, environment] = owner.split(':') as [string, ZoneDelegations.Record['environment']]
+    for (const row of await ZoneDelegations.listActive(db, { environment, orgId }))
+      if (chainIds.has(row.chainId) && (await ZoneDelegations.revoke(db, row.id))) revokedDelegations += 1 // prettier-ignore
+  }
+  // Each record is written under the key's admission lock, re-read and re-planned there, so an owner edit committed meanwhile is never overwritten.
+  let rewritten = 0
+  const ids = new Set(rewritable.map(({ id }) => id))
+  for (const change of planned.changes.filter(({ record }) => ids.has(record.id)))
+    rewritten += await db.transaction(async (tx) => {
+      await ApiKeyAdmissions.lock(tx, change.record.id)
+      return ApiKeys.applyZoneReadRewrite(store, [change], { zones })
+    })
+  // The response describes the store as the run left it, not the snapshot it started from.
+  const final = await ApiKeys.planZoneReadRewrite(store, { zones })
+  return { ...(await summarize(db, final)), createdDelegations, revokedDelegations, rewritten }
+}
+
+/** Classifies planned changes by organization row and delegation coverage. */
+async function summarize(db: Db.Db, planned: ApiKeys.planZoneReadRewrite.Result): Promise<Plan> {
+  const organizations = new Set(
+    (
+      await Organizations.listByIds(db, [
+        ...new Set(planned.changes.map(({ record }) => record.orgId)),
+      ])
+    ).map(({ id }) => id),
+  )
+  // Self-owned keys cannot hold a delegation, so they are reported rather than rewritten.
+  const owned = planned.changes.filter(({ record }) => organizations.has(record.orgId))
+  // One listing per organization and environment, revoked rows included, shared by every key it owns.
+  const rows = new Map<string, readonly ZoneDelegations.Record[]>()
+  for (const { record } of owned) {
+    const owner = `${record.orgId}:${record.environment}`
+    if (!rows.has(owner)) rows.set(owner, await ZoneDelegations.list(db, { environment: record.environment, orgId: record.orgId })) // prettier-ignore
+  }
+  const narrow = new Map<string, ZoneDelegations.Record>()
+  const revokedSlots = new Map<string, ZoneDelegations.Record>()
+  const changes = owned.map(({ chainIds, complete, record, rewritten, writeChainIds }) => {
+    const listed = rows.get(`${record.orgId}:${record.environment}`) ?? []
+    const active = listed.filter((row) => row.revokedAt === undefined)
+    // Only Zones the per-Zone scopes grant are repaired; tags added by hand never earn a delegation.
+    // Any active row covers (projects are not part of the model); one listing members would narrow a
+    // whole-Zone reader, so it blocks the apply instead. Broadcasts never check members, so write
+    // Zones only need a row to exist.
+    for (const row of active)
+      if (chainIds.includes(row.chainId) && !(row.accountsAll && row.tokensAll)) narrow.set(row.id, row) // prettier-ignore
+    const undelegated = [...new Set([...chainIds, ...writeChainIds])]
+      .sort((a, b) => a - b)
+      .filter((chainId) => !active.some((row) => row.chainId === chainId))
+    // A slot an admin revoked is a decision the rewrite must not undo; the key is reported instead.
+    const revoked = undelegated.filter((chainId) => {
+      const row = listed.find((candidate) => candidate.chainId === chainId)
+      if (row) revokedSlots.set(row.id, row)
+      return row !== undefined
+    })
+    return {
+      ...key(rewritten),
+      complete,
+      revoked,
+      scopes: rewritten.scopes,
+      undelegated,
+      zoneTags: rewritten.zoneTags ?? [],
+    }
+  })
+  return {
+    changes,
+    expiring: planned.expiring.map(key),
+    invalid: planned.invalid.map(key),
+    keys: planned.keys,
+    mixed: planned.mixed.map(key),
+    narrow: [...narrow.values()],
+    revoked: [...revokedSlots.values()],
+    orgless: planned.changes
+      .map(({ record }) => record)
+      .filter((record) => !organizations.has(record.orgId))
+      .map(key),
+    tagless: planned.tagless.map(key),
+    unconfigured: [...new Set(planned.changes.flatMap(({ unconfigured }) => unconfigured))].sort((a, b) => a - b), // prettier-ignore
+    unreadableRecords: planned.unreadableRecords,
+    wildcard: planned.wildcard.map(key),
+  }
+}
+
+/** Stores the rewrite reads and writes, and the Zones this deployment serves. */
+export type Options = {
+  /** Authoritative Postgres database holding organizations and delegations. */
+  db: Db.Db
+  /** KV state store holding API-key records and fences. */
+  store: Store.State
+  /** Chain ids of the hosted Zones; per-Zone scopes naming any other Zone earn no tag. */
+  zones: ReadonlySet<number>
+}
+
+function key(record: ApiKeys.Record): Key {
+  return {
+    environment: record.environment,
+    id: record.id,
+    ...(record.name === undefined ? {} : { name: record.name }),
+    orgId: record.orgId,
+    ...(record.projectId === undefined ? {} : { projectId: record.projectId }),
+  }
+}
+
+/** Thrown by {@link apply} when an active delegation for a planned Zone lists members; nothing was written. */
+export class NarrowDelegationsError extends Error {
+  override readonly name = 'ZoneKeyRewrite.NarrowDelegationsError'
+  /** The delegations to widen to whole-Zone coverage (or revoke) before applying. */
+  readonly rows: readonly ZoneDelegations.Record[]
+  constructor(rows: readonly ZoneDelegations.Record[]) {
+    super(`${rows.length} active Zone delegation(s) list members; revoke them or request whole-Zone ones before rewriting keys.`) // prettier-ignore
+    this.rows = rows
+  }
+}

package/src/internal/rewards/Campaigns.ts

@@ -811,6 +811,8 @@ export type RunEvidence = {
   deferredRecipients?: number | undefined
   /** Stable registration high-water mark consumed by the run. */
   eligibilityCheckpoint?: string | undefined
+  /** When the run was delivered, in Unix seconds. */
+  deliveredAt?: number | undefined
   /** Exact eligibility snapshot identity used by resumable calculation. */
   eligibilityVersion?: Hex | undefined
   /** Exact effective exclusion set identity used by resumable calculation. */

package/src/internal/rewards/Distributions.ts

@@ -79,12 +79,10 @@ export namespace schema {
           z.describe('Recipients skipped by the batch.'),
           z.meta({ examples: [0] }),
         ),
-      timestamp: z.iso
-        .datetime()
-        .check(
-          z.describe('Indexed block timestamp.'),
-          z.meta({ examples: ['2026-10-13T16:01:22.000Z'] }),
-        ),
+      timestamp: Schema.dateTime().check(
+        z.describe('Indexed block timestamp.'),
+        z.meta({ examples: ['2026-10-13T16:01:22.000Z'] }),
+      ),
       transactionHash: Schema.Hash.check(
         z.describe('Distribution transaction hash.'),
         z.meta({ examples: [`0x${'11'.repeat(32)}`] }),
@@ -164,12 +162,10 @@ export namespace schema {
           z.describe('Chain block number.'),
           z.meta({ examples: [123456] }),
         ),
-      timestamp: z.iso
-        .datetime()
-        .check(
-          z.describe('Chain block timestamp.'),
-          z.meta({ examples: ['2026-10-13T16:01:22.000Z'] }),
-        ),
+      timestamp: Schema.dateTime().check(
+        z.describe('Chain block timestamp.'),
+        z.meta({ examples: ['2026-10-13T16:01:22.000Z'] }),
+      ),
     })
     .check(
       z.describe('Chain block supporting the displayed evidence.'),