tapimo 0.13.0 → 0.15.0

package/src/apps/management/routes/webhooks.test.ts

@@ -3,6 +3,7 @@ import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import * as App from '../../../App.js'
 import * as Memberships from '../../../db/tables/memberships.js'
 import * as Cursor from '../../../internal/Cursor.js'
+import type * as Log from '../../../internal/Log.js'
 import * as core_Webhooks from '../../../internal/Webhooks.js'
 import * as TestApp from '../../../../test/App.js'
 import { management } from '../App.js'
@@ -11,7 +12,7 @@ import * as Webhooks from './webhooks.js'
 
 const origin = 'http://localhost'
 const webhook = {
-  applicationEventTypes: ['funding:deposit.updated'],
+  applicationEventTypes: ['routes:deposit.updated', 'routes:transfer.updated'],
   supportedChainIds: [4217, 42431],
 } satisfies App.Webhook
 
@@ -25,15 +26,22 @@ function json(method: 'PATCH' | 'POST', cookie: string, body: unknown) {
 
 function createApp(options: createApp.Options = {}) {
   return App.create({
-    auth: { session: { wallet: { origin } } },
+    auth: {
+      session: { secret: 'test-better-auth-secret-at-least-32-characters', wallet: { origin } },
+    },
     db: options.db ?? TestApp.database(),
     kv: { store: TestApp.kvStore() },
+    ...(options.logger === undefined ? {} : { logger: options.logger }),
   }).route('/', management({ webhook: options.webhook ?? webhook }))
 }
 
 declare namespace createApp {
   type Options = {
+    /** Database source override. */
     db?: App.create.Options['db'] | undefined
+    /** Request logger override. */
+    logger?: App.create.Options['logger'] | undefined
+    /** Webhook capability override. */
     webhook?: App.Webhook | false | undefined
   }
 }
@@ -59,21 +67,22 @@ describe('webhooks', () => {
     const retry = spec.paths['/v1/orgs/{orgId}/webhooks/{id}/deliveries/{deliveryId}/retry'].post
 
     expect({
-      components: [
-        'CreateOrganizationWebhookBetterstackResponse',
-        'CreateOrganizationWebhookRequest',
-        'CreateOrganizationWebhookResponse',
-        'CreateOrganizationWebhookSlackResponse',
-        'CreateOrganizationWebhookUrlResponse',
-        'DeleteOrganizationWebhookResponse',
-        'OrganizationWebhook',
-        'OrganizationWebhookDelivery',
-        'OrganizationWebhookDeliveryList',
-        'OrganizationWebhookDeliverySummary',
-        'OrganizationWebhookList',
-        'RetryOrganizationWebhookDeliveryResponse',
-        'UpdateOrganizationWebhookRequest',
-      ].filter((name) => spec.components.schemas[name]),
+      components: Object.keys(spec.components.schemas)
+        .filter(
+          (name) =>
+            name.startsWith('CreateOrganizationWebhook') ||
+            [
+              'DeleteOrganizationWebhookResponse',
+              'OrganizationWebhook',
+              'OrganizationWebhookDelivery',
+              'OrganizationWebhookDeliveryList',
+              'OrganizationWebhookDeliverySummary',
+              'OrganizationWebhookList',
+              'RetryOrganizationWebhookDeliveryResponse',
+              'UpdateOrganizationWebhookRequest',
+            ].includes(name),
+        )
+        .sort(),
       create: {
         errors: {
           400: collection.post.responses[400].content['application/json'].schema,
@@ -146,9 +155,15 @@ describe('webhooks', () => {
       {
         "components": [
           "CreateOrganizationWebhookBetterstackResponse",
+          "CreateOrganizationWebhookBlockRequest",
+          "CreateOrganizationWebhookLogRequest",
           "CreateOrganizationWebhookRequest",
           "CreateOrganizationWebhookResponse",
+          "CreateOrganizationWebhookRoutesDepositRequest",
+          "CreateOrganizationWebhookRoutesTransferRequest",
           "CreateOrganizationWebhookSlackResponse",
+          "CreateOrganizationWebhookTransactionRequest",
+          "CreateOrganizationWebhookTransferRequest",
           "CreateOrganizationWebhookUrlResponse",
           "DeleteOrganizationWebhookResponse",
           "OrganizationWebhook",
@@ -284,7 +299,7 @@ describe('webhooks', () => {
     `)
   })
 
-  test('creates funding deposit subscriptions without reading the RPC head', async () => {
+  test('creates route transfer subscriptions without reading the RPC head', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
     const cookie = await session(app)
@@ -293,9 +308,9 @@ describe('webhooks', () => {
       `/v1/orgs/${org.id}/webhooks`,
       json('POST', cookie, {
         chainId: 4217,
-        destination: { type: 'url', url: 'https://example.com/funding' },
+        destination: { type: 'url', url: 'https://example.com/routes' },
         environment: 'production',
-        eventType: 'funding:deposit.updated',
+        eventType: 'routes:transfer.updated',
         filters: { status: 'completed' },
       }),
     )
@@ -317,7 +332,7 @@ describe('webhooks', () => {
     expect(await core_Webhooks.getCursor(db, created.id)).toBeNull()
   })
 
-  test('preserves a production funding environment on testnet', async () => {
+  test('preserves a production route environment on testnet', async () => {
     const db = TestApp.database()
     const app = createApp({ db })
     const cookie = await session(app)
@@ -326,9 +341,9 @@ describe('webhooks', () => {
       `/v1/orgs/${org.id}/webhooks`,
       json('POST', cookie, {
         chainId: 42431,
-        destination: { type: 'url', url: 'https://example.com/funding-testnet' },
+        destination: { type: 'url', url: 'https://example.com/routes-testnet' },
         environment: 'production',
-        eventType: 'funding:deposit.updated',
+        eventType: 'routes:deposit.updated',
       }),
     )
     const created = await TestApp.json(response, Webhooks.schema.createWebhook.Response)
@@ -343,7 +358,7 @@ describe('webhooks', () => {
     expect(stored?.environment).toBe('production')
   })
 
-  test('requires an explicit environment for funding deposit subscriptions', async () => {
+  test('requires an explicit environment for route deposit subscriptions', async () => {
     const app = createApp()
     const cookie = await session(app)
     const org = await organization(app, cookie)
@@ -351,8 +366,8 @@ describe('webhooks', () => {
       `/v1/orgs/${org.id}/webhooks`,
       json('POST', cookie, {
         chainId: 4217,
-        destination: { type: 'url', url: 'https://example.com/funding' },
-        eventType: 'funding:deposit.updated',
+        destination: { type: 'url', url: 'https://example.com/routes' },
+        eventType: 'routes:deposit.updated',
       }),
     )
 
@@ -658,7 +673,9 @@ describe('webhooks', () => {
   })
 
   test('uses the shared per-owner limit', async () => {
+    const entries: Log.Entry[] = []
     const app = createApp({
+      logger: (entry) => void entries.push(entry),
       webhook: { maxPerOwner: 1, supportedChainIds: webhook.supportedChainIds },
     })
     const cookie = await session(app)
@@ -675,6 +692,12 @@ describe('webhooks', () => {
     const response = await app.request(collection, json('POST', cookie, body))
     expect(response.status).toBe(403)
     expect(await response.json()).toMatchObject({ error: { code: 'limit_exceeded' } })
+    expect(entries.at(-1)).toMatchObject({
+      errorCode: 'limit_exceeded',
+      method: 'POST',
+      route: '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/webhooks',
+      status: 403,
+    })
   })
 
   test('lists every webhook when the creation limit is lowered', async () => {

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

@@ -8,7 +8,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as WebhookDestination from '../../../internal/WebhookDestination.js'
 import * as Webhooks from '../../../internal/Webhooks.js'
-import { schema as webhookSchema } from '../../data/routes/webhooks.js'
+import * as DataWebhooks from '../../data/routes/webhooks.js'
 import type { Environment } from '../App.js'
 
 const defaultMaxPerOwner = 100
@@ -21,11 +21,11 @@ export namespace schema {
   export const Subscription = OpenApi.component(
     z
       .object({
-        ...webhookSchema.Subscription.shape,
-        context: webhookSchema.Subscription.shape.context.check(
+        ...DataWebhooks.schema.Subscription.shape,
+        context: DataWebhooks.schema.Subscription.shape.context.check(
           z.meta({ examples: [{ title: 'Production transfers' }] }),
         ),
-        destination: webhookSchema.Subscription.shape.destination.check(
+        destination: DataWebhooks.schema.Subscription.shape.destination.check(
           z.meta({ examples: [{ type: 'url', url: 'https://example.com/webhooks' }] }),
         ),
       })
@@ -35,7 +35,7 @@ export namespace schema {
 
   /** Webhook delivery data returned in collection rows. */
   export const Delivery = OpenApi.component(
-    webhookSchema.Delivery,
+    DataWebhooks.schema.Delivery,
     'OrganizationWebhookDeliverySummary',
   )
 
@@ -44,32 +44,87 @@ export namespace schema {
     const Environment = z
       .enum(['production', 'sandbox'])
       .check(
-        z.describe('API-key environment whose private funding deposits are delivered.'),
+        z.describe('API-key environment whose private route resources are delivered.'),
         z.meta({ examples: ['production'] }),
       )
 
+    const BlockBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.BlockBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: z.optional(Environment),
+        })
+        .check(z.meta({ title: 'Block subscription' })),
+      'CreateOrganizationWebhookBlockRequest',
+    )
+    const RoutesDepositBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.RoutesDepositBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: Environment,
+        })
+        .check(z.meta({ title: 'Route deposit subscription' })),
+      'CreateOrganizationWebhookRoutesDepositRequest',
+    )
+    const RoutesTransferBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.RoutesTransferBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: Environment,
+        })
+        .check(z.meta({ title: 'Route transfer subscription' })),
+      'CreateOrganizationWebhookRoutesTransferRequest',
+    )
+    const LogBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.LogBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: z.optional(Environment),
+        })
+        .check(z.meta({ title: 'Log subscription' })),
+      'CreateOrganizationWebhookLogRequest',
+    )
+    const TransactionBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.TransactionBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: z.optional(Environment),
+        })
+        .check(z.meta({ title: 'Included-transaction subscription' })),
+      'CreateOrganizationWebhookTransactionRequest',
+    )
+    const TransferBody = OpenApi.component(
+      z
+        .object({
+          ...DataWebhooks.schema.createWebhook.TransferBody.shape,
+          chainId: DataWebhooks.schema.Subscription.shape.chainId,
+          environment: z.optional(Environment),
+        })
+        .check(z.meta({ title: 'Transfer subscription' })),
+      'CreateOrganizationWebhookTransferRequest',
+    )
+
     /** Organization webhook creation requires an explicit network. */
     export const Body = OpenApi.component(
       z
-        .intersection(
-          webhookSchema.createWebhook.Body,
-          z.object({
-            chainId: webhookSchema.Subscription.shape.chainId,
-            environment: z.optional(Environment),
-          }),
-        )
-        .check(
-          z.refine(
-            (body) =>
-              body.eventType !== 'funding:deposit.updated' || body.environment !== undefined,
-            { error: '`environment` is required for funding deposit subscriptions.' },
-          ),
-          z.describe('Details for creating an organization webhook subscription.'),
-        ),
+        .discriminatedUnion('eventType', [
+          TransferBody,
+          TransactionBody,
+          LogBody,
+          BlockBody,
+          RoutesDepositBody,
+          RoutesTransferBody,
+        ])
+        .check(z.describe('Details for creating an organization webhook subscription.')),
       'CreateOrganizationWebhookRequest',
     )
 
-    const secret = webhookSchema.createWebhook.Response.shape.secret
+    const secret = DataWebhooks.schema.createWebhook.Response.shape.secret
     const urlDestination = z
       .object({
         type: z
@@ -192,7 +247,7 @@ export namespace schema {
   /** Schemas for listing an organization webhook's delivery attempts. */
   export namespace listWebhookDeliveries {
     export const Params = WebhookParams
-    export const Query = webhookSchema.listWebhookDeliveries.Query
+    export const Query = DataWebhooks.schema.listWebhookDeliveries.Query
     export const Response = OpenApi.component(
       z
         .object({
@@ -202,10 +257,10 @@ export namespace schema {
               z.describe('Webhook delivery attempts on this page.'),
               z.meta({ examples: [[]] }),
             ),
-          meta: webhookSchema.listWebhookDeliveries.Response.shape.meta.check(
+          meta: DataWebhooks.schema.listWebhookDeliveries.Response.shape.meta.check(
             z.meta({ examples: [{ totalCount: 1, totalCountCapped: false }] }),
           ),
-          nextCursor: webhookSchema.listWebhookDeliveries.Response.shape.nextCursor,
+          nextCursor: DataWebhooks.schema.listWebhookDeliveries.Response.shape.nextCursor,
         })
         .check(z.describe("A page of an organization's webhook delivery attempts.")),
       'OrganizationWebhookDeliveryList',
@@ -214,7 +269,7 @@ export namespace schema {
 
   const DeliveryParams = z
     .object({
-      deliveryId: webhookSchema.retryWebhookDelivery.Params.shape.deliveryId,
+      deliveryId: DataWebhooks.schema.retryWebhookDelivery.Params.shape.deliveryId,
       id: WebhookParams.shape.id,
       orgId: WebhookParams.shape.orgId,
     })
@@ -227,7 +282,7 @@ export namespace schema {
       z
         .object({
           ...Delivery.shape,
-          envelope: webhookSchema.Envelope,
+          envelope: DataWebhooks.schema.Envelope,
         })
         .check(z.describe('A webhook delivery attempt with the exact JSON payload Tempo sent.')),
       'OrganizationWebhookDelivery',
@@ -238,7 +293,7 @@ export namespace schema {
   export namespace retryWebhookDelivery {
     export const Params = DeliveryParams
     export const Response = OpenApi.component(
-      webhookSchema.retryWebhookDelivery.Response,
+      DataWebhooks.schema.retryWebhookDelivery.Response,
       'RetryOrganizationWebhookDeliveryResponse',
     )
   }
@@ -261,7 +316,7 @@ export namespace schema {
   /** Lifecycle state editable from the console. */
   export const UpdateBody = OpenApi.component(
     z
-      .object({ status: webhookSchema.Status })
+      .object({ status: DataWebhooks.schema.Status })
       .check(z.describe('New delivery state for a webhook subscription.')),
     'UpdateOrganizationWebhookRequest',
   )
@@ -319,7 +374,8 @@ export function webhooks(options: webhooks.Options = {}) {
             },
             403: {
               codes: ['forbidden', 'limit_exceeded'],
-              description: 'Admin access is required and the organization must be under its limit.',
+              description:
+                'Admin access is required; API-key organizations share their creator subscription limit.',
             },
             404: {
               codes: ['organization_not_found', 'webhooks_not_enabled'],
@@ -344,7 +400,7 @@ export function webhooks(options: webhooks.Options = {}) {
 
         const body = c.req.valid('json')
         if (
-          body.eventType === 'funding:deposit.updated' &&
+          DataWebhooks.isRoutesEventType(body.eventType) &&
           !options.webhook.applicationEventTypes?.includes(body.eventType)
         )
           return Response.error(c, {
@@ -362,19 +418,18 @@ export function webhooks(options: webhooks.Options = {}) {
           const db = Db.get(c.get('db'))
           const maxPerOwner = options.webhook.maxPerOwner ?? defaultMaxPerOwner
           const owner_ = owner(Auth.org(c).id)
-          if ((await Webhooks.countSubscriptions(db, owner_)) >= maxPerOwner)
+          if ((await Webhooks.countSubscriptionsForLimit(db, { owner: owner_ })) >= maxPerOwner)
             throw new Webhooks.LimitExceededError(maxPerOwner)
-          const startBlockNumber =
-            body.eventType === 'funding:deposit.updated'
-              ? undefined
-              : Number(await c.get('getClient')(chainId).getBlockNumber())
+          const startBlockNumber = DataWebhooks.isRoutesEventType(body.eventType)
+            ? undefined
+            : Number(await c.get('getClient')(chainId).getBlockNumber())
           const subscription = await Webhooks.createSubscription(
             db,
             {
               chainId,
               ...(body.context === undefined ? {} : { context: body.context }),
               destination: body.destination,
-              ...(body.eventType === 'funding:deposit.updated' && body.environment !== undefined
+              ...(DataWebhooks.isRoutesEventType(body.eventType) && body.environment !== undefined
                 ? { environment: body.environment }
                 : {}),
               eventType: body.eventType,
@@ -754,7 +809,7 @@ function publicSubscription(subscription: Webhooks.Subscription) {
     ...(subscription.context === undefined ? {} : { context: subscription.context }),
     createdAt: subscription.createdAt,
     destination,
-    ...(subscription.eventType === 'funding:deposit.updated' &&
+    ...(DataWebhooks.isRoutesEventType(subscription.eventType) &&
     subscription.environment !== undefined
       ? { environment: subscription.environment }
       : {}),

package/src/apps/mcp.test.ts

@@ -1,6 +1,6 @@
 import { Cli as incur_Cli, z } from 'incur'
-import { App } from 'tapimo'
 import { data } from 'tapimo/apps'
+import { App } from 'tapimo/server'
 
 import * as TestApp from '../../test/App.js'
 import * as Runtime from '../../test/runtime.js'
@@ -151,7 +151,7 @@ test('identifies as Tempo MCP', async () => {
   })
 })
 
-test('scopes tools to the data and inbound funding domains', async () => {
+test('scopes tools to the data and Routes domains', async () => {
   const { app, host } = createHost({ docs: docsStub() })
 
   // The domain filter must drop paths that actually exist in the spec.
@@ -172,8 +172,8 @@ test('scopes tools to the data and inbound funding domains', async () => {
   const tools = (await toolsSearch(host)).map((tool) => tool.name)
 
   expect(tools).toContain('v1_tokens_get')
-  expect(tools).toContain('v1_funding_quotes')
-  expect(tools).toContain('v1_funding_transfers_post')
+  expect(tools).toContain('v1_routes_quotes')
+  expect(tools).toContain('v1_routes_transfers_post')
   expect(tools).toContain('docs_search')
   // RPC is part of the data domain tag group.
   expect(tools.some((name) => name.startsWith('rpc'))).toBe(true)
@@ -184,7 +184,7 @@ test('scopes tools to the data and inbound funding domains', async () => {
   expect(tools.some((name) => name.startsWith('v1_me'))).toBe(false)
 })
 
-test('keeps the data tools functional when funding is omitted', async () => {
+test('keeps the data tools functional when routes is omitted', async () => {
   const app = App.create({ auth: false, db: TestApp.database() }).route('/', data())
   const { host } = createHost({ app })
 
@@ -192,7 +192,7 @@ test('keeps the data tools functional when funding is omitted', async () => {
   const tools = (await toolsSearch(host)).map((tool) => tool.name)
 
   expect(tools).toContain('v1_tokens_get')
-  expect(tools.some((name) => name.startsWith('v1_funding_'))).toBe(false)
+  expect(tools.some((name) => name.startsWith('v1_routes_'))).toBe(false)
 })
 
 test('keeps tool input schemas compact', async () => {

package/src/apps/mcp.ts

@@ -10,15 +10,15 @@ import * as Metadata from './metadata.js'
 /** Required document tag group whose operations surface as MCP tools. */
 const dataTagGroup = 'Data API'
 
-/** Optional document tag group added when the funding app is mounted. */
-const fundingTagGroup = 'Funding & Bridge API'
+/** Optional document tag group added when the routes app is mounted. */
+const routesTagGroup = 'Routes API'
 
 /** Tags inside the group hidden from MCP: partner-shaped CoinGecko mirrors and the MCP endpoint itself. */
 const excludedTags = ['CoinGecko', 'MCP']
 
 /** Usage guidance surfaced to MCP clients on initialize. */
 const instructions =
-  "Tempo MCP provides access to the Tempo API's data and inbound funding domains, plus documentation. Authenticated tools accept a Tempo API key sent as an `Authorization: Bearer` header on the HTTP request. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation."
+  "Tempo MCP provides access to the Tempo API's data and Routes domains, plus documentation. Authenticated tools accept a Tempo API key sent as an `Authorization: Bearer` header on the HTTP request. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation."
 
 /** Zod schemas owned by the MCP endpoint's OpenAPI description. */
 export namespace schema {
@@ -59,7 +59,7 @@ export namespace schema {
 
 /**
  * The MCP route group: a stateless streamable-HTTP MCP server at `/mcp` whose
- * tools mirror the API's data domain and its optional inbound funding domain,
+ * tools mirror the API's data domain and its optional Routes domain,
  * plus the remote Tempo docs tools. Mount alongside the other route groups:
  *
  * ```ts
@@ -226,16 +226,16 @@ type Document = Openapi.OpenAPISpec & {
 const methods: readonly string[] = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'] // prettier-ignore
 
 /**
- * Narrows the document to the data and optional inbound funding domains.
+ * Narrows the document to the data and optional Routes domains.
  * Management, relay, and session operations never surface as tools.
  */
 function scope(document: Document): Openapi.OpenAPISpec {
   const groups = document['x-tagGroups'] ?? []
   const dataGroup = groups.find((entry) => entry.name === dataTagGroup)
   if (!dataGroup) throw new Error(`openapi.json is missing the "${dataTagGroup}" tag group`)
-  const fundingGroup = groups.find((entry) => entry.name === fundingTagGroup)
+  const routesGroup = groups.find((entry) => entry.name === routesTagGroup)
   const tags = new Set(
-    [...dataGroup.tags, ...(fundingGroup?.tags ?? [])].filter((tag) => !excludedTags.includes(tag)),
+    [...dataGroup.tags, ...(routesGroup?.tags ?? [])].filter((tag) => !excludedTags.includes(tag)),
   )
   const paths: Document['paths'] = {}
   for (const [path, item] of Object.entries(document.paths)) {

package/src/apps/mpp/App.ts

@@ -2,6 +2,7 @@ import { Hono, type Context } from 'hono'
 import type * as z from 'zod/mini'
 
 import type * as App from '../../App.js'
+import * as Scope from '../../Scope.js'
 import * as Db from '../../db/Db.js'
 import * as Auth from '../../internal/Auth.js'
 import * as OpenApi from '../../internal/OpenApi.js'
@@ -25,7 +26,7 @@ export function mpp(options: mpp.Options) {
       OpenApi.validate('json', Mpp.schema.RelayInput, bodyValidation),
       OpenApi.describeRoute({
         description:
-          'Checks whether a completed MPP credential can be processed without submitting payment.\n\nTempo validates the challenge and credential, confirms the chain is supported, and screens the payment parties. It does not settle, broadcast, reserve funds, or consume the credential.\n\nRequires `mpp:write`. Well-formed requests return HTTP `200`; inspect `success`. Invalid bodies return `400`; missing or unauthorized API keys return `401` or `403`.',
+          'Checks whether a completed MPP credential can be processed without submitting payment.\n\nTempo validates the challenge and credential, confirms the chain is supported, and screens the payment parties. It does not settle, broadcast, reserve funds, or consume the credential.\n\nRequires `mpp:write` and, for Zones, `zone:<chainId>:read` or `zone:<chainId>:write`. Well-formed requests return HTTP `200`; inspect `success`. Invalid bodies return `400`; missing or unauthorized API keys return `401` or `403`.',
         operationId: 'validateMppCredential',
         responses: responses({
           description: 'The MPP credential validation result.',
@@ -52,7 +53,7 @@ export function mpp(options: mpp.Options) {
       OpenApi.validate('json', Mpp.schema.RelayInput, bodyValidation),
       OpenApi.describeRoute({
         description:
-          'Validates, screens, and submits a completed MPP credential to Tempo.\n\nRequires `mpp:write`. Well-formed requests return HTTP `200`; inspect `success`.\n\nUse `Idempotency-Key` on retries to replay a successful receipt. Reusing a key for a different credential returns `invalid_payment`, and in-flight duplicates return `temporarily_unavailable`.',
+          'Validates, screens, and submits a completed MPP credential to Tempo.\n\nRequires `mpp:write` and, for Zones, `zone:<chainId>:write`. Well-formed requests return HTTP `200`; inspect `success`.\n\nUse `Idempotency-Key` on retries to replay a successful receipt. Reusing a key for a different credential returns `invalid_payment`, and in-flight duplicates return `temporarily_unavailable`.',
         operationId: 'broadcastMppCredential',
         parameters: [
           {
@@ -149,8 +150,24 @@ async function authorizeBroadcast(
 ) {
   const { input, options: options_mpp } = options
   const chainId = Policy.chainId(input) ?? c.get('chainId')
+  const principal = Auth.getPrincipal(c) ?? undefined
   try {
-    Policy.assertSupportedChain({ chainId, supportedChainIds: c.get('supportedChainIds') })
+    Policy.assertChainAccess({
+      chainId,
+      principal,
+      supportedChainIds: c.get('supportedChainIds'),
+      zones: c.get('zones'),
+    })
+    // Validation can read Zone state, but submitting a credential requires broadcast access.
+    const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
+    if (
+      c.get('zones').has(chainId) &&
+      !scopes?.includes(Scope.wildcard) &&
+      !scopes?.includes(`zone:${chainId}:write`)
+    )
+      throw new Policy.PolicyDeniedError(
+        `Broadcasting to zone ${chainId} requires \`zone:${chainId}:write\`.`,
+      )
     return {
       chainId,
       feePayer: await Timing.time(c, 'mpp_fee_payer', () =>
@@ -159,7 +176,8 @@ async function authorizeBroadcast(
           db: Db.get(c.get('db')),
           feePayer: options_mpp.feePayer,
           input,
-          principal: Auth.getPrincipal(c) ?? undefined,
+          principal,
+          zones: c.get('zones'),
         }),
       ),
       type: 'authorized' as const,
@@ -266,17 +284,28 @@ function createAdapter(c: Context<App.Environment>, options: createAdapter.Optio
               principal,
               serializedTransaction,
               txFeeLimit: Billing.toBaseUnits(options_mpp.txFeeLimit ?? '1.00'),
+              zones: c.get('zones'),
             }),
         })
       : undefined
+  const storeKeyPrefix = (() => {
+    if (principal?.type === 'api_key') return `mpp:${principal.environment}:${principal.orgId}:`
+    if (principal?.type === 'super_admin') return 'mpp:super_admin:'
+    throw new Error('MPP relay requires an API key.')
+  })()
   return Adapter.create({
     chainId,
     ...(feePayer ? { feePayer } : {}),
-    getClient: (chainId) => {
-      const resolved = chainId ?? c.get('chainId')
-      Policy.assertSupportedChain({
+    getClient: (chainId_client) => {
+      const resolved = chainId_client ?? chainId
+      // Bind library-selected clients to the chain authorized for this credential.
+      if (resolved !== chainId)
+        throw new Policy.PolicyDeniedError('Credential chain does not match the authorized chain.')
+      Policy.assertChainAccess({
         chainId: resolved,
+        principal: principal ?? undefined,
         supportedChainIds: c.get('supportedChainIds'),
+        zones: c.get('zones'),
       })
       return c.get('getClient')(resolved)
     },
@@ -286,6 +315,7 @@ function createAdapter(c: Context<App.Environment>, options: createAdapter.Optio
       ? {}
       : { reportUnknown: options_mpp.reportUnknown }),
     state: options_mpp.state,
+    storeKeyPrefix,
     time: (name, fn) => Timing.time(c, name, fn),
   })
 }