tapimo 0.19.0 → 0.20.0

package/src/admin/App.ts

@@ -15,6 +15,7 @@ import * as OpenApi from '../internal/OpenApi.js'
 import * as RateLimit from '../internal/RateLimit.js'
 import type * as Store from '../internal/Store.js'
 import * as Response from '../internal/Response.js'
+import * as ZoneDelegationApproval from '../internal/ZoneDelegationApproval.js'
 import * as Viem from '../internal/Viem.js'
 import * as Tidx from '../internal/Tidx.js'
 import * as Zones from '../apps/Zones.js'
@@ -34,9 +35,8 @@ import { sentinel } from './apps/sentinel.js'
 import { subsidies } from './apps/subsidies.js'
 import { verifiedTokens } from './apps/verified-tokens.js'
 import * as Ui from './ui.generated.js'
-import * as ZoneKeyApproval from '../internal/ZoneKeyApproval.js'
+import * as ZoneDelegationRequests from './apps/zone-delegation-requests.js'
 import * as ZoneDelegations from './apps/zone-delegations.js'
-import * as ZoneKeyRequests from './apps/zone-key-requests.js'
 import * as AuditLogs from './apps/audit-logs.js'
 
 /** A verified admin identity, as returned by {@link create.Options.identify}. */
@@ -72,10 +72,10 @@ export type Environment = {
     metrics: Metrics.Metrics | undefined
     /** Zone chains available to admin routes. */
     zones: readonly Chain[]
-    /** Configured authoritative approval flow, absent until provisioned. */
-    zoneKeyApproval: create.Options['zoneKeyApproval']
-    /** Verified session used only by the Zone-key approval routes. */
-    zoneKeyMember: ZoneKeyApproval.Member
+    /** Configured approval flow for Zone delegations, absent until provisioned. */
+    delegationApproval: create.Options['delegationApproval']
+    /** Verified session used only by the delegation-request routes. */
+    approver: ZoneDelegationApproval.Member
   }
 }
 
@@ -117,7 +117,7 @@ export function create(options: create.Options) {
     c.set('metrics', options.metrics)
     c.set('rateLimit', rateLimit)
     c.set('zones', zones)
-    c.set('zoneKeyApproval', options.zoneKeyApproval)
+    c.set('delegationApproval', options.delegationApproval)
     c.set('identity', await identify(c.req.raw, c))
     try {
       return await next()
@@ -148,29 +148,29 @@ export function create(options: create.Options) {
   // `/config.json` and inlined into the shell, so the UI reads it synchronously.
   async function bootstrapConfig(c: Context<Environment>) {
     const identity = c.get('identity')
-    // Only steers navigation; the approval routes re-verify membership on every decision.
-    const zoneKeyApprover = await (async () => {
-      const config = c.get('zoneKeyApproval')
+    // Only steers navigation; the request routes re-verify membership on every decision.
+    const delegationApprover = await (async () => {
+      const config = c.get('delegationApproval')
       if (!identity || !config?.groupId || !config.lookup) return false
       try {
         const member = await config.identify(c.req.raw, c)
         return (
-          ZoneKeyApproval.active(member) &&
+          ZoneDelegationApproval.active(member) &&
           member.eligible &&
           member.email.toLowerCase() === identity.email.toLowerCase()
         )
       } catch {
-        c.get('metrics')?.count('zone_key_approval_failure_count', 1)
+        c.get('metrics')?.count('zone_delegation_approval_failure_count', 1)
         // Unknown, not a denial: the UI keeps Approve and the server re-checks membership.
         return null
       }
     })()
     return {
       auth: {
+        delegationApprover,
         identity,
         ...(ui?.loginUrl ? { loginUrl: ui.loginUrl } : {}),
         ...(ui?.logoutUrl ? { logoutUrl: ui.logoutUrl } : {}),
-        zoneKeyApprover,
       },
       rewards: {
         chainId: options.rewardsChainId ?? Viem.chainId.mainnet,
@@ -212,35 +212,23 @@ export function create(options: create.Options) {
       })
     return next()
   }
+  // Hono's `/x/*` also matches `/x`; listing both would run each middleware (and audit) twice.
   const protectedPaths = [
     '/config.json',
-    '/api-keys',
     '/api-keys/*',
     '/audit-logs/*',
-    '/zone-delegations',
     '/zone-delegations/*',
-    '/zone-key-requests',
-    '/zone-key-requests/*',
-    '/early-access',
+    '/zone-delegation-requests/*',
     '/early-access/*',
     '/openapi.json',
-    '/earn/verified-vaults',
     '/earn/verified-vaults/*',
-    '/prop-amms',
     '/prop-amms/*',
-    '/routes',
     '/routes/*',
-    '/route-policies',
     '/route-policies/*',
-    '/organizations',
     '/organizations/*',
-    '/scopes',
     '/scopes/*',
-    '/sentinel',
     '/sentinel/*',
-    '/subsidies',
     '/subsidies/*',
-    '/verified-tokens',
     '/verified-tokens/*',
   ] as const
   for (const path of protectedPaths) app.use(path, requireAuth)
@@ -296,7 +284,7 @@ export function create(options: create.Options) {
     .route('/api-keys', apiKeys())
     .route('/audit-logs', AuditLogs.auditLogs())
     .route('/zone-delegations', ZoneDelegations.zoneDelegations())
-    .route('/zone-key-requests', ZoneKeyRequests.zoneKeyRequests())
+    .route('/zone-delegation-requests', ZoneDelegationRequests.zoneDelegationRequests())
     .route('/early-access', earlyAccess())
     .route(
       '/earn/verified-vaults',
@@ -323,7 +311,8 @@ export function create(options: create.Options) {
   )
 
   app.onError((cause, c) => {
-    if (cause instanceof ZoneKeyApproval.RequiredError) return Response.keyUpstream(c, cause)
+    if (cause instanceof ZoneDelegationApproval.RequiredError)
+      return Response.error(c, { code: 'zone_delegation_approval_required', message: cause.message, status: 403 }) // prettier-ignore
     if (cause instanceof HTTPException) return cause.getResponse()
     // Redact any leaked API-key token from the logged error/stack.
     console.error(
@@ -364,8 +353,8 @@ export declare namespace create {
 
   /** Options for {@link create}. */
   type Options = {
-    /** Verified identity integration for the Zone key quorum workflow. */
-    zoneKeyApproval?:
+    /** Verified identity integration for the Zone delegation quorum workflow. */
+    delegationApproval?:
       | {
           /** Exact internal identity group required for approvals. */
           groupId: string
@@ -373,9 +362,12 @@ export declare namespace create {
           identify: (
             request: Request,
             context: Context<Environment>,
-          ) => ZoneKeyApproval.Member | null | Promise<ZoneKeyApproval.Member | null>
+          ) => ZoneDelegationApproval.Member | null | Promise<ZoneDelegationApproval.Member | null>
           /** Fetches fresh account/group status using the current request; failures must throw. */
-          lookup: (request: Request, ids: readonly string[]) => ReturnType<ZoneKeyApproval.Lookup>
+          lookup: (
+            request: Request,
+            ids: readonly string[],
+          ) => ReturnType<ZoneDelegationApproval.Lookup>
         }
       | undefined
     /** ClickHouse analytics source used by operational usage reads. */

package/src/admin/Mcp.test.ts

@@ -84,7 +84,8 @@ describe('create', () => {
         'subsidies_transactions_get',
         'subsidies_transactions_id_meter-event',
         'verified-tokens_get',
-        'zone-key-requests_get',
+        'zone-delegation-requests_get',
+        'zone-delegations_rewrite-keys_get',
       ]),
     )
     expect(names.filter((name) => name.includes('logo'))).toEqual([])

package/src/admin/apps/api-keys.test.ts

@@ -116,17 +116,55 @@ describe('POST /api-keys', () => {
     expect(resolved?.environment).toBe('sandbox')
   })
 
-  test('mints a key with concrete Zone write scopes', async () => {
-    const { client, store } = await setup()
-    const scopes = ['zone:421700001:write'] as const
+  test('refuses fresh per-Zone write scopes', async () => {
+    const { client } = await setup()
     const response = await client['api-keys'].$post({
-      json: { ...validBody, scopes },
+      json: { ...validBody, scopes: ['zone:421700001:write'] },
     })
-    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+  })
 
+  test('mints generic Zone write keys only with tags inside active delegations', async () => {
+    const { client, db, store } = await setup()
+    await TestApp.delegateZone(db, { chainIds: [421700001], orgId: validBody.orgId })
+    const mint = (json: object) =>
+      client['api-keys'].$post({ json: { ...validBody, scopes: ['zone:write'], ...json } as never })
+
+    // Admin mints follow the same bound: a broadcasting key names only delegated Zones.
+    for (const json of [
+      {},
+      { zoneTags: [421700002] },
+      { environment: 'sandbox', zoneTags: [421700001] },
+      { orgId: undefined, projectId: undefined },
+    ]) {
+      const response = await mint(json)
+      expect(response.status).toBe(400)
+      expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+    }
+    const response = await mint({ zoneTags: [421700001] })
+    const body = await TestApp.json(response, ApiKeys.schema.createApiKey.Response)
     expect(response.status).toBe(200)
-    expect(body.scopes).toEqual(scopes)
-    expect((await core_ApiKeys.resolve(store, body.token))?.scopes).toEqual(scopes)
+    expect(await core_ApiKeys.resolve(store, body.token)).toMatchObject({
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
+    })
+
+    // Granting the scope by PATCH is bounded the same way; admin read tags are not.
+    const plain = await TestApp.json(
+      await client['api-keys'].$post({ json: validBody }),
+      ApiKeys.schema.createApiKey.Response,
+    )
+    const ungranted = await client['api-keys'][':id'].$patch({ json: { scopes: ['zone:write'] }, param: { id: plain.id } }) // prettier-ignore
+    expect(ungranted.status).toBe(400)
+    const granted = await client['api-keys'][':id'].$patch({ json: { scopes: ['zone:write'], zoneTags: [421700001] }, param: { id: plain.id } }) // prettier-ignore
+    expect(granted.status).toBe(200)
+    expect(await core_ApiKeys.resolve(store, plain.token)).toMatchObject({
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
+    })
+    const reader = await client['api-keys'].$post({ json: { ...validBody, scopes: ['zone:read'], zoneTags: [421700009] } }) // prettier-ignore
+    expect(reader.status).toBe(200)
   })
 
   test('records the expiry when provided', async () => {
@@ -429,8 +467,10 @@ describe('POST /api-keys/:id/rotate', () => {
       orgId: 'org_privy',
       projectId: 'prj_privy',
       rateLimits: { '*': { limit: 10_000, period: 'minute' } },
-      scopes: ['zone:421700001:write'],
+      scopes: ['zone:write'],
+      zoneTags: [421700001],
     })
+    await TestApp.delegateZone(db, { chainIds: [421700001], environment: 'sandbox', orgId: 'org_privy' }) // prettier-ignore
     await RoutesPolicies.save(db, {
       policy: { maxAmount: '12' },
       scope: {
@@ -477,20 +517,48 @@ describe('POST /api-keys/:id/rotate', () => {
     ).toMatchObject({ policy: { maxAmount: '12' }, version: 1 })
   })
 
-  test('keeps the approval quorum on Zone read key rotation', async () => {
+  test('rotates Zone read keys, copying their tags', async () => {
     const { client, db, store } = await setup()
     await Organizations.create(db, { id: 'org_zone', name: 'Zone' })
     const { record: source } = await core_ApiKeys.mint(store, {
       name: 'Zone reader',
       orgId: 'org_zone',
-      scopes: ['zone:421700001:read'],
+      scopes: ['zone:read'],
+      zoneTags: [421700001],
     })
 
-    // A rotation hands out a working credential, so one admin alone may not perform it.
     const response = await client['api-keys'][':id'].rotate.$post({ param: { id: source.id } })
-    expect(response.status).toBe(403)
-    expect(await response.json()).toMatchObject({ error: { code: 'zone_key_approval_required' } })
-    expect(await core_ApiKeys.listByOrg(store, 'org_zone')).toHaveLength(1)
+    expect(response.status).toBe(200)
+    expect(await response.json()).toMatchObject({ scopes: ['zone:read'], zoneTags: [421700001] })
+    expect(await core_ApiKeys.listByOrg(store, 'org_zone')).toHaveLength(2)
+  })
+
+  test('drops the retired per-Zone read scope when rotating or reassigning a rewritten key', async () => {
+    const { client, db, store } = await setup()
+    await Organizations.create(db, { id: 'org_zone', name: 'Zone' })
+    // A record as the rewrite leaves it: the legacy scope beside `zone:read` and its tag.
+    const stored = async (id: string, extra: Record<string, unknown>) => {
+      const token = `secret_${id}`
+      await store.put(
+        ApiKey.keyFor(token),
+        JSON.stringify({ createdAt: '2026-01-01T00:00:00.000Z', environment: 'production', id, scopes: ['zone:421700001:read', 'zone:read'], tokenLast4: token.slice(-4), zoneTags: [421700001], ...extra }), // prettier-ignore
+      )
+      return token
+    }
+    await stored('key_rewritten', { orgId: 'org_zone' })
+    const orphan = await stored('key_orphan', { orgId: 'key_orphan' })
+    await core_ApiKeys.backfill(store)
+
+    const rotated = await client['api-keys'][':id'].rotate.$post({ param: { id: 'key_rewritten' } })
+    expect(rotated.status).toBe(200)
+    expect(await rotated.json()).toMatchObject({ scopes: ['zone:read'], zoneTags: [421700001] })
+
+    const reassigned = await client['api-keys'][':id'].organization.$put({
+      json: { orgId: 'org_zone' },
+      param: { id: 'key_orphan' },
+    })
+    expect(reassigned.status).toBe(200)
+    expect(await core_ApiKeys.resolve(store, orphan)).toMatchObject({ orgId: 'org_zone', scopes: ['zone:read'], zoneTags: [421700001] }) // prettier-ignore
   })
 
   test('unknown id → 404', async () => {
@@ -567,7 +635,8 @@ describe('PUT /api-keys/:id/organization', () => {
     const project = await Projects.create(db, { name: 'Zones', orgId: validBody.orgId })
     const { record, token } = await core_ApiKeys.mint(store, {
       name: 'Legacy zone',
-      scopes: ['zone:421700001:read', 'data:read'],
+      scopes: ['zone:read', 'data:read'],
+      zoneTags: [421700001],
     })
     expect(record.orgId).toBe(record.id)
 
@@ -591,7 +660,7 @@ describe('PUT /api-keys/:id/organization', () => {
       record.id,
     ])
 
-    // The route covers only the first owner; further moves keep their reviewed path.
+    // The route covers only the first owner; further moves go through PATCH like any key edit.
     const again = await client['api-keys'][':id'].organization.$put({
       json: { orgId: validBody.orgId },
       param: { id: record.id },
@@ -602,7 +671,7 @@ describe('PUT /api-keys/:id/organization', () => {
       json: { orgId: validBody.orgId },
       param: { id: record.id },
     })
-    expect(patched.status).toBe(403)
+    expect(patched.status).toBe(200)
   })
 
   test('rejects unknown owners and projects of another organization', async () => {
@@ -611,7 +680,8 @@ describe('PUT /api-keys/:id/organization', () => {
     const project = await Projects.create(db, { name: 'Elsewhere', orgId: other.id })
     const { record } = await core_ApiKeys.mint(store, {
       name: 'Legacy zone',
-      scopes: ['zone:421700001:read'],
+      scopes: ['zone:read'],
+      zoneTags: [421700001],
     })
 
     const unknownOrg = await client['api-keys'][':id'].organization.$put({
@@ -686,14 +756,14 @@ describe('PATCH /api-keys/:id', () => {
     })
 
     const response = await client['api-keys'][':id'].$patch({
-      json: { scopes: ['management:read', 'zone:421700001:write'] },
+      json: { scopes: ['management:read', 'webhooks:write'] },
       param: { id: record.id },
     })
 
     expect(response.status).toBe(200)
     expect((await core_ApiKeys.resolve(store, token))?.scopes).toEqual([
       'management:read',
-      'zone:421700001:write',
+      'webhooks:write',
     ])
   })
 

package/src/admin/apps/api-keys.ts

@@ -137,12 +137,10 @@ export namespace schema {
           z.describe('Replacement per-key quota overrides.'),
         ),
         scopes: z.optional(GrantedScopes).check(z.describe('Replacement granted scopes.')),
-        zoneTags: z
-          .optional(z.nullable(core_ApiKey.schema.ZoneTags))
-          .check(
-            z.describe('Replacement Zone chain id tags, or null to read no Zone.'),
-            z.meta({ examples: [[421700001]] }),
-          ),
+        zoneTags: z.optional(z.nullable(core_ApiKey.schema.ZoneTags)).check(
+          z.describe('Replacement Zone chain id tags, or null to use no Zone. A `zone:write` key keeps every tag within delegated Zones.'), // prettier-ignore
+          z.meta({ examples: [[421700001]] }),
+        ),
       }),
       'Metadata to apply to an API key.',
     )
@@ -408,7 +406,6 @@ export function apiKeys() {
           })
 
         try {
-          // Admin rotation returns a fresh secret, so protected Zone read keys keep their approval quorum until M3.
           const { record, token } = await ApiKeys.mintBounded(
             Db.get(c.get('db')),
             store,
@@ -549,7 +546,7 @@ export function apiKeys() {
             message: 'API key not found.',
             status: 404,
           })
-        // Keys minted before organizations existed own themselves; every other move keeps its reviewed path.
+        // Keys minted before organizations existed own themselves; every other move is an ordinary PATCH.
         if (record.orgId !== record.id)
           return Response.error(c, {
             code: 'organization_assigned',

package/src/admin/apps/audit-logs.ts

@@ -82,7 +82,7 @@ export namespace schema {
         .optional(z.string().check(z.maxLength(1024)))
         .check(
           z.describe('Literal admin API path prefix.'),
-          z.meta({ examples: ['/zone-key-requests'] }),
+          z.meta({ examples: ['/zone-delegations'] }),
         ),
       requestId: z
         .optional(z.string().check(z.maxLength(256)))

package/src/admin/apps/earn-vaults.test.ts

@@ -104,9 +104,15 @@ describe('getVerifiedEarnVault', () => {
         TestApp.json(response, App.schema.getVerifiedEarnVault.Response),
         TestApp.json(publicResponse, Earn.schema.getEarnVault.Response),
       ])
-      // Public vault fields stay identical; earnings configuration is admin-only.
+      // Public vault fields stay identical; curated branding and earnings are admin-only.
       expect(publicVault.meta).toBeUndefined()
-      expect(vault).toStrictEqual({ ...publicVault, earnings: null })
+      expect(vault).toStrictEqual({
+        ...publicVault,
+        description: null,
+        earnings: null,
+        label: publicVault.shareToken.name,
+        slug: null,
+      })
       expect({
         description: vault.description,
         slug: vault.slug,
@@ -161,25 +167,26 @@ describe('listVerifiedEarnVaults', () => {
   })
 
   test.runIf(Runtime.get().mode === 'testnet')(
-    'matches the public verified collection',
+    'matches the public vault fields',
     async () => {
       const db = TestApp.database()
-      await core_EarnVaults.upsert(db, TestEarn.verifiedVault)
+      const record = await core_EarnVaults.upsert(db, TestEarn.verifiedVault)
       const { app } = TestAdmin.setup({ db, zones: [TestEarn.zone] })
       const publicApp = TestApp.create({ auth: false, db, zones: [TestEarn.zone] })
-      const query = `?chainId=${tempoTestnet.id}&include=access,capabilities,zone&limit=5`
+      const query = `?chainId=${tempoTestnet.id}&include=access,capabilities,zone`
       const [response, publicResponse] = await Promise.all([
-        app.request(`/earn/verified-vaults${query}`),
-        publicApp.request(`/v1/earn/vaults/verified${query}`),
+        app.request(`/earn/verified-vaults${query}&limit=5`),
+        publicApp.request(`/v1/earn/vaults/${TestEarn.verifiedVault.vaultAddress}${query}`),
       ])
       expect([response.status, publicResponse.status]).toEqual([200, 200])
-      const [body, publicBody] = await Promise.all([
+      const [body, publicVault] = await Promise.all([
         TestApp.json(response, App.schema.listVerifiedEarnVaults.Response),
-        TestApp.json(publicResponse, Earn.schema.getVerifiedEarnVaults.Response),
+        TestApp.json(publicResponse, Earn.schema.getEarnVault.Response),
       ])
+      const { description, label, slug } = record
       expect(body).toStrictEqual({
-        ...publicBody,
-        data: publicBody.data.map((vault) => ({ ...vault, earnings: null })),
+        data: [{ ...publicVault, description, earnings: null, label, slug }],
+        nextCursor: null,
       })
     },
     90_000,
@@ -934,14 +941,7 @@ describe('deleteVerifiedEarnVault', () => {
       )
       expect(publicResponse.status).toBe(200)
       const vault = await TestApp.json(publicResponse, Earn.schema.getEarnVault.Response)
-      expect({
-        description: vault.description,
-        slug: vault.slug,
-        verified: vault.verified,
-        zone: vault.zone,
-      }).toStrictEqual({
-        description: null,
-        slug: null,
+      expect({ verified: vault.verified, zone: vault.zone }).toStrictEqual({
         verified: false,
         zone: null,
       })

package/src/admin/apps/earn-vaults.ts

@@ -38,7 +38,7 @@ export namespace schema {
   })
 
   /** One Earn vault with its private accounting configuration. */
-  export const Vault = z.intersection(Earn.schema.Vault, earnings)
+  export const Vault = z.intersection(Earn.schema.CuratedVault, earnings)
 
   /** One registry-curated Earn vault with its accounting configuration. */
   export const VerifiedVault = z.intersection(Earn.schema.VerifiedVault, earnings)
@@ -46,12 +46,12 @@ export namespace schema {
   /** Schemas for the listVerifiedEarnVaults operation. */
   export namespace listVerifiedEarnVaults {
     /** Query parameters for verified Earn vaults, without the public rate window. */
-    export const Query = Earn.schema.getVerifiedEarnVaults.BaseQuery
+    export const Query = Earn.schema.VaultCollectionQuery
 
     /** Paginated verified Earn vaults. */
     export const Response = z.object({
       data: z.array(VerifiedVault),
-      nextCursor: Earn.schema.getVerifiedEarnVaults.Response.shape.nextCursor,
+      nextCursor: Schema.NextCursor,
     })
   }
 
@@ -518,7 +518,7 @@ export namespace schema {
             z
               .extend(Distributions.schema.Recipient, {
                 firstRegisteredAt: z
-                  .nullable(z.iso.datetime())
+                  .nullable(Schema.dateTime())
                   .check(
                     z.describe(
                       'First recorded registration time, independent of payment evidence.',
@@ -1611,7 +1611,13 @@ async function serializeVault(
     zoneRoutes: options.zoneRoutes,
     zones: c.get('zones'),
   })
-  return { ...vault, earnings: options.record?.earnings ?? null }
+  return {
+    ...vault,
+    description: options.record?.description ?? null,
+    earnings: options.record?.earnings ?? null,
+    label: options.record?.label ?? shareToken.name,
+    slug: options.record?.slug ?? null,
+  }
 }
 
 declare namespace serializeVault {