tapimo 0.4.4 → 0.5.0

package/src/ApiKeys.test.ts

@@ -97,6 +97,29 @@ describe('mint', () => {
       ApiKeys.mint(Store.memory(), { orgId: 'org_a', scopes: ['totally:made-up' as never] }),
     ).rejects.toThrowError(/invalid API key input/)
   })
+
+  test('mints a per-zone read scope', async () => {
+    const state = Store.memory()
+    const { token } = await ApiKeys.mint(state, {
+      orgId: 'org_a',
+      scopes: ['zone:421700001:read'],
+    })
+    const resolved = await ApiKeys.resolve(state, token)
+    expect(resolved?.scopes).toEqual(['zone:421700001:read'])
+  })
+
+  test('rejects malformed zone scopes', async () => {
+    for (const scope of [
+      'zone::read',
+      'zone:abc:read',
+      'zone:1.5:read',
+      'zone:-1:read',
+      'zone:1:write',
+    ])
+      await expect(
+        ApiKeys.mint(Store.memory(), { orgId: 'org_a', scopes: [scope as never] }),
+      ).rejects.toThrowError(/invalid API key input/)
+  })
 })
 
 describe('list', () => {

package/src/App.test-d.ts

@@ -17,7 +17,9 @@ describe('App.Endpoint', () => {
 
     expectTypeOf<'GET /v1/bogus'>().not.toExtend<App.Endpoint>()
     // The mounted routes are GET-only; other verbs must not appear.
+    expectTypeOf<'POST /v1/indexer/query'>().not.toExtend<App.Endpoint>()
     expectTypeOf<'POST /v1/tokens'>().not.toExtend<App.Endpoint>()
+    expectTypeOf<'POST /v1/tokens/:token'>().not.toExtend<App.Endpoint>()
     expectTypeOf<'DELETE /v1/tokens/:token'>().not.toExtend<App.Endpoint>()
   })
 

package/src/App.ts

@@ -72,6 +72,8 @@ export type Environment = {
       tidx: Tidx.getClient.Tidx | undefined
       /** Verified-token feature configuration (refresh window), or undefined when the feature is disabled. Token rows live in `db`. */
       verifiedTokens: { refreshMs?: number | undefined } | undefined
+      /** Zone RPC endpoints keyed by chain id; empty when none are configured. */
+      zones: ReadonlyMap<number, Data.data.Zone>
       /** Webhook feature configuration, or undefined when webhooks are disabled. Rows live in `db`. */
       webhook: { maxPerOwner?: number | undefined } | undefined
     } & EdgeCache.Variables &
@@ -398,6 +400,10 @@ export function create<const path extends string = '/'>(options: create.Options<
   let finalized = false
   const finalize = () => {
     if (finalized) return
+    Auth.installMppManagementRoutes(app, {
+      basePath,
+      overrides: options.auth === false ? undefined : options.auth?.overrides,
+    })
     finalized = true
 
     app.get('/openapi.json', async (c) => c.json(await getSpec()))

package/src/Client.test-d.ts

@@ -1189,25 +1189,27 @@ describe('narrows responses by status', () => {
     }
   })
 
-  test('GET /v1/funding/routes', async () => {
+  test('GET /v1/funding/quotes', async () => {
     const client = Client.create()
-    const res = await client.v1.funding.routes.$get({
+    const res = await client.v1.funding.quotes.$get({
       query: {
+        provider: 'relay',
         sourceAmount: '1000000',
         sourceChain: 'base',
         sourceToken: 'USDC',
       },
     })
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | PaidAccessStatus>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | 502 | PaidAccessStatus>()
 
     switch (res.status) {
       case 200: {
         const json = await res.json()
         expectTypeOf(json.data[0]!.sourceAmount).toEqualTypeOf<
-          z.output<typeof Funding.schema.listFundingRoutes.Response>['data'][number]['sourceAmount']
+          z.output<typeof Funding.schema.quoteFunding.Response>['data'][number]['sourceAmount']
         >()
-        expectTypeOf(json.data[0]!.provider.id).toEqualTypeOf<string>()
+        expectTypeOf(json.data[0]!.provider.id).toEqualTypeOf<'relay'>()
+        expectTypeOf(json.data[0]!.quote.outputAmount).toEqualTypeOf<string>()
         void json
         return
       }
@@ -1218,6 +1220,13 @@ describe('narrows responses by status', () => {
         void json
         return
       }
+      case 502: {
+        const json = await res.json()
+        expectTypeOf(json.error.code).toEqualTypeOf<'upstream_error'>()
+        expectTypeOf(json.error.message).toEqualTypeOf<string>()
+        void json
+        return
+      }
     }
   })
 
@@ -1248,24 +1257,24 @@ describe('narrows responses by status', () => {
     }
   })
 
-  test('GET /v1/providers', async () => {
+  test('GET /v1/funding/providers', async () => {
     const client = Client.create()
-    const res = await client.v1.providers.$get({ query: { capability: 'fundingRoutes' } })
+    const res = await client.v1.funding.providers.$get()
 
-    expectTypeOf(res.status).toEqualTypeOf<200 | 400 | PaidAccessStatus>()
+    expectTypeOf(res.status).toEqualTypeOf<200 | PaidAccessStatus>()
 
     switch (res.status) {
       case 200: {
         const json = await res.json()
-        expectTypeOf(json.data[0]!.capabilities).toEqualTypeOf<
-          z.output<typeof Funding.schema.listProviders.Response>['data'][number]['capabilities']
+        expectTypeOf(json.data[0]!.status).toEqualTypeOf<
+          z.output<typeof Funding.schema.listProviders.Response>['data'][number]['status']
         >()
         void json
         return
       }
       case 400: {
         const json = await res.json()
-        expectTypeOf(json.error.code).toEqualTypeOf<Access400<'query_invalid'>>()
+        expectTypeOf(json.error.code).toEqualTypeOf<'api_key_malformed'>()
         expectTypeOf(json.error.message).toEqualTypeOf<string>()
         void json
         return

package/src/Scope.test.ts

@@ -12,6 +12,7 @@ describe('extend', () => {
       ]),
     ).toEqual([
       ...Scope.catalog,
+      Scope.zoneEntry,
       {
         description: 'Read project accounts.',
         scope: 'accounts:read',

package/src/Scope.ts

@@ -4,6 +4,8 @@
  * API-key validation.
  */
 
+import * as z from 'zod/mini'
+
 /**
  * Wildcard scope. A key whose `scopes` contains this value satisfies every
  * required scope, so it never needs re-provisioning when new scopes are added.
@@ -69,8 +71,30 @@ export const catalog = [
   },
 ] as const satisfies readonly Entry[]
 
+/**
+ * Templated `/v1/scopes` entry for per-zone read scopes. Concrete grants use
+ * `zone:<chainId>:read` and are never self-serve.
+ */
+export const zoneEntry = {
+  description: 'Read RPC and indexed data for one zone chain id.',
+  scope: 'zone:<chainId>:read',
+  selfServe: false,
+} as const satisfies Entry
+
+/** Zod schemas owned by the scope vocabulary. */
+export namespace schema {
+  /** A concrete per-zone read scope (`zone:421700001:read`). */
+  export const Zone = z
+    .templateLiteral(['zone:', z.int(), ':read'])
+    // `z.int()` also matches a sign; zone chain ids are positive.
+    .check(z.regex(/^zone:\d+:read$/), z.describe('Per-zone read scope (`zone:<chainId>:read`).'))
+}
+
+/** Per-zone read scope, granting access to one zone chain id. */
+export type Zone = z.output<typeof schema.Zone>
+
 /** Issuable API-key scope identifier, including host-defined scopes. */
-export type Id = (typeof catalog)[number]['scope'] | (string & {})
+export type Id = (typeof catalog)[number]['scope'] | Zone | (string & {})
 
 /** Scope catalog used by API-key issuance and discovery. */
 export type Catalog = readonly Entry[]
@@ -92,7 +116,7 @@ export const selfServe: readonly Id[] = catalog
  */
 export function extend(entries: readonly Entry[] = []): Catalog {
   const identifiers = new Set<string>()
-  const result = [...catalog, ...entries]
+  const result = [...catalog, zoneEntry, ...entries]
   for (const entry of result) {
     if (!entry.scope.trim()) throw new Error('Scope identifier must not be empty.')
     if (identifiers.has(entry.scope)) throw new Error(`Duplicate scope \`${entry.scope}\`.`)
@@ -103,10 +127,12 @@ export function extend(entries: readonly Entry[] = []): Catalog {
 
 /** Returns whether a catalog contains a scope identifier. */
 export function includes(catalog: Catalog, scope: string): scope is Id {
-  return catalog.some((entry) => entry.scope === scope)
+  return schema.Zone.safeParse(scope).success || catalog.some((entry) => entry.scope === scope)
 }
 
 /** Returns the self-issuable identifiers in a scope catalog. */
 export function selfServeFrom(catalog: Catalog): readonly Id[] {
-  return catalog.filter((entry) => entry.selfServe).map((entry) => entry.scope)
+  return catalog
+    .filter((entry) => entry.selfServe && !schema.Zone.safeParse(entry.scope).success)
+    .map((entry) => entry.scope)
 }

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

@@ -1,4 +1,11 @@
+import { Secp256k1 } from 'ox'
+import { ZoneRpcAuthentication } from 'ox/tempo'
+import { Challenge, PaymentRequest } from 'mppx'
+import { RateLimit } from 'tapimo'
+
 import * as TestApp from '../../../test/App.js'
+import * as Tempo from '../../../test/Tempo.js'
+import * as Store from '../../internal/Store.js'
 import * as Viem from '../../internal/Viem.js'
 
 /** A supported non-mainnet chain id, exercising the sandbox testnet allowance. */
@@ -35,6 +42,346 @@ function mainnetDefaultClient() {
   })
 }
 
+type OpenApiDocument = {
+  paths: Record<string, Record<string, unknown>>
+}
+
+const mpp = {
+  secretKey: 'secret_test_key_0123456789abcdef',
+  session: {
+    chainId: Tempo.chain.id,
+    currency: Tempo.currency,
+    decimals: 6,
+    getClient: () => Tempo.client,
+    recipient: Tempo.accounts[2].address,
+  },
+} satisfies NonNullable<TestApp.create.Options['mpp']>
+
+describe('MPP session management', () => {
+  test('keeps generated POST routes private', async () => {
+    const app = TestApp.create({ auth: false })
+    const indexer = await app.request('/v1/indexer/query', { method: 'POST' })
+    const token = await app.request(`/v1/tokens/${TestApp.token}`, { method: 'POST' })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+
+    expect(indexer.status).toBe(404)
+    expect(token.status).toBe(404)
+    expect(spec.paths['/v1/indexer/query']).not.toHaveProperty('post')
+    expect(spec.paths['/v1/tokens/{token}']).not.toHaveProperty('post')
+  })
+
+  test('matches GET scopes for static, parameterized, and hidden resources', async () => {
+    const rateLimitStore = Store.memory()
+    const app = TestApp.create({ mpp, rateLimit: { store: rateLimitStore } })
+    await exhaustPublicQuota(rateLimitStore)
+
+    for (const resource of [
+      {
+        path: `/v1/indexer/query?sql=select%201&chainId=${Tempo.chain.id}`,
+        scope: 'GET /v1/indexer/query',
+      },
+      {
+        path: `/v1/tokens/${TestApp.token}?chainId=${Tempo.chain.id}`,
+        scope: 'GET /v1/tokens/:token',
+      },
+      {
+        path: `/v1/verified-tokens?chainId=${Tempo.chain.id}`,
+        scope: 'GET /v1/verified-tokens',
+      },
+    ]) {
+      const url = new URL(resource.path, 'http://tempo-api.test')
+      const challenged = await app.fetch(new Request(url))
+      url.search = ''
+      const management = await app.fetch(new Request(url, { method: 'POST' }))
+
+      expect(challenged.status).toBe(402)
+      expect(management.status).toBe(402)
+      const expectedScope = PaymentRequest.serialize({
+        _mppx_scope: resource.scope,
+      })
+      expect(Challenge.fromHeaders(challenged.headers).opaque).toBe(expectedScope)
+      expect(Challenge.fromHeaders(management.headers).opaque).toBe(expectedScope)
+    }
+  })
+
+  test('preserves the mounted base path in session scope', async () => {
+    const rateLimitStore = Store.memory()
+    const app = TestApp.create({ mpp, path: '/api', rateLimit: { store: rateLimitStore } })
+    await exhaustPublicQuota(rateLimitStore)
+
+    const resource = new URL(
+      `/api/v1/tokens/${TestApp.token}?chainId=${Tempo.chain.id}`,
+      'http://tempo-api.test',
+    )
+    const challenged = await app.fetch(new Request(resource))
+    resource.search = ''
+    const management = await app.fetch(new Request(resource, { method: 'POST' }))
+
+    expect(challenged.status).toBe(402)
+    expect(management.status).toBe(402)
+    const expectedScope = PaymentRequest.serialize({
+      _mppx_scope: 'GET /api/v1/tokens/:token',
+    })
+    expect(Challenge.fromHeaders(challenged.headers).opaque).toBe(expectedScope)
+    expect(Challenge.fromHeaders(management.headers).opaque).toBe(expectedScope)
+  })
+
+  test('honors endpoint MPP overrides', async () => {
+    const app = TestApp.create({
+      auth: {
+        overrides: {
+          'GET /v1/scopes': { mpp: true },
+          'GET /v1/tokens/:token': { mpp: false },
+        },
+      },
+      mpp,
+    })
+    const enabled = await app.request('/v1/scopes', { method: 'POST' })
+    const disabled = await app.request(`/v1/tokens/${TestApp.token}`, { method: 'POST' })
+
+    expect(enabled.status).toBe(402)
+    expect(disabled.status).toBe(404)
+    expect(Challenge.fromHeaders(enabled.headers).opaque).toBe(
+      PaymentRequest.serialize({ _mppx_scope: 'GET /v1/scopes' }),
+    )
+  })
+})
+
+describe('zone chain gate', () => {
+  /** A consumer-supplied zone chain id (the API never derives these). */
+  const zone = 421_700_001
+  /** A second zone, isolating per-zone grants. */
+  const zoneB = 421_700_002
+
+  function zoneOptions(chainId: number) {
+    return {
+      chainId,
+      forwardRpcUrl: `https://${chainId}.rpc.test`,
+    }
+  }
+
+  /** Zone reader: holds the per-zone scope for `zone` (only). */
+  const zoneReader = {
+    id: 'key_zone',
+    orgId: 'org_test',
+    scopes: ['data:read', `zone:${zone}:read`],
+    token: 'secret_zone',
+  } satisfies TestApp.kvStore.Key
+
+  /** Full-access key: the wildcard covers every zone. */
+  const admin = {
+    id: 'key_admin',
+    orgId: 'org_test',
+    scopes: ['*'],
+    token: 'secret_admin',
+  } satisfies TestApp.kvStore.Key
+
+  /** Data reader without any zone grant. */
+  const outsider = {
+    id: 'key_outsider',
+    orgId: 'org_test',
+    scopes: ['data:read'],
+    token: 'secret_outsider',
+  } satisfies TestApp.kvStore.Key
+
+  /** A deployment serving two zones. */
+  function zoneApp() {
+    return TestApp.create({
+      auth: { keys: [admin, outsider, zoneReader] },
+      zones: [zoneOptions(zone), zoneOptions(zoneB)],
+    })
+  }
+
+  /** Signing key proving that a structurally valid caller token is insufficient for REST. */
+  const privateKey = Secp256k1.randomPrivateKey()
+
+  /** Signs a caller Zone token. */
+  function zoneToken(chainId: number) {
+    const issuedAt = Math.floor(Date.now() / 1000)
+    const authentication = ZoneRpcAuthentication.from({
+      chainId,
+      expiresAt: issuedAt + 300,
+      issuedAt,
+      zoneId: 1,
+    })
+    return ZoneRpcAuthentication.serialize(authentication, {
+      signature: Secp256k1.sign({
+        payload: ZoneRpcAuthentication.getSignPayload(authentication),
+        privateKey,
+      }),
+    })
+  }
+
+  test('zone chain ids are additive: unsupported ids list them as supported', async () => {
+    const app = TestApp.create({ auth: false, zones: [zoneOptions(zone)] })
+    const response = await app.request('/v1/transfers?chainId=999999')
+    const body = (await response.json()) as { error: { code: string; message: string } }
+
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('chain_id_unsupported')
+    expect(body.error.message).toContain(String(zone))
+  })
+
+  test('a default zone still applies authorization', async () => {
+    const app = TestApp.create({
+      auth: false,
+      defaultChainId: zone,
+      rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
+      zones: [zoneOptions(zone)],
+    })
+
+    const rpc = await app.request('/rpc', {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+      method: 'POST',
+    })
+    const transfers = await app.request('/v1/transfers')
+    const tokens = await app.request('/v1/tokens')
+    const scopes = await app.request('/v1/scopes')
+
+    expect(rpc.status).toBe(403)
+    expect(transfers.status).toBe(403)
+    expect(tokens.status).toBe(403)
+    expect(scopes.status).toBe(200)
+  })
+
+  test('a zone-scoped key reads Zone data', async () => {
+    const response = await zoneApp().request(`/v1/tokenlist?chainId=${zone}`, as(zoneReader))
+    expect(response.status).toBe(200)
+  })
+
+  test('zone authorization applies to every data route', async () => {
+    const app = TestApp.create({ auth: false, zones: [zoneOptions(zone)] })
+    for (const path of [
+      `/v1/tokens?chainId=${zone}`,
+      `/v1/addresses/0x0000000000000000000000000000000000000001/activities?chainId=${zone}`,
+      `/v1/transfers?chainId=${zone}&include=token`,
+    ]) {
+      const response = await app.request(path)
+      const body = (await response.json()) as { error: { code: string; message: string } }
+
+      expect(response.status).toBe(403)
+      expect(body.error.code).toBe('api_key_forbidden')
+      expect(body.error.message).toContain('zone')
+    }
+  })
+
+  test('the wildcard scope covers every zone', async () => {
+    const app = zoneApp()
+    expect((await app.request(`/v1/tokenlist?chainId=${zone}`, as(admin))).status).toBe(200)
+    expect((await app.request(`/v1/tokenlist?chainId=${zoneB}`, as(admin))).status).toBe(200)
+  })
+
+  test('a key without the zone scope is refused, naming the scope', async () => {
+    const app = zoneApp()
+    const response = await app.request(`/v1/transfers?chainId=${zone}`, as(outsider))
+    const body = (await response.json()) as { error: { code: string; message: string } }
+
+    expect(response.status).toBe(403)
+    expect(body.error.code).toBe('api_key_forbidden')
+    expect(body.error.message).toContain(`zone:${zone}:read`)
+    expect(body.error.message).not.toContain('X-Authorization-Token')
+  })
+
+  test('a zone scope does not grant another zone', async () => {
+    const app = zoneApp()
+    const response = await app.request(`/v1/transfers?chainId=${zoneB}`, as(zoneReader))
+    const body = (await response.json()) as { error: { code: string; message: string } }
+
+    expect(response.status).toBe(403)
+    expect(body.error.message).toContain(`zone:${zoneB}:read`)
+  })
+
+  test('a caller-signed Zone token cannot authorize REST data', async () => {
+    const response = await zoneApp().request(`/v1/tokenlist?chainId=${zone}`, {
+      headers: { [ZoneRpcAuthentication.headerName]: zoneToken(zone) },
+    })
+    expect(response.status).toBe(403)
+  })
+
+  test('an empty Zone token cannot authorize raw RPC', async () => {
+    const response = await zoneApp().request(`/rpc/${zone}`, {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+      headers: { [ZoneRpcAuthentication.headerName]: '' },
+      method: 'POST',
+    })
+    expect(response.status).toBe(403)
+  })
+
+  test('path chain selectors require Zone authorization', async () => {
+    const app = TestApp.create({ auth: false, zones: [zoneOptions(zone)] })
+    const gecko = await app.request(`/gecko/${zone}/pairs`)
+    const block = await app.request(`/chains/${zone}/blocks/by-timestamp?timestamp=1767225600`)
+
+    expect(gecko.status).toBe(403)
+    expect(block.status).toBe(403)
+  })
+
+  test('applies Zone authorization under a base path', async () => {
+    const app = TestApp.create({ auth: false, path: '/api', zones: [zoneOptions(zone)] })
+
+    expect((await app.request(`/api/v1/tokenlist?chainId=${zone}`)).status).toBe(403)
+    expect((await app.request(`/api/gecko/${zone}/pairs`)).status).toBe(403)
+  })
+
+  test('rejects conflicting path and query Zone selectors', async () => {
+    const response = await zoneApp().request(
+      `/gecko/${zoneB}/pairs?chainId=${zone}`,
+      as(zoneReader),
+    )
+    const body = (await response.json()) as { error: { code: string; message: string } }
+
+    expect(response.status).toBe(400)
+    expect(body.error.code).toBe('chain_id_invalid')
+    expect(body.error.message).toBe('Conflicting chain ids')
+  })
+
+  test('rejects conflicting query aliases', async () => {
+    const response = await zoneApp().request(
+      `/v1/tokenlist?chainId=${zone}&chain_id=${zoneB}`,
+      as(admin),
+    )
+    expect(response.status).toBe(400)
+  })
+
+  test('does not apply the data gate to management routes', async () => {
+    const response = await zoneApp().request(`/v1/scopes?chainId=${zone}`)
+    expect(response.status).toBe(200)
+  })
+
+  test('Zone responses never seed the anonymous edge cache', async () => {
+    const app = zoneApp()
+    const path = `/v1/tokenlist?chainId=${zone}`
+    expect((await app.request(path, as(zoneReader))).status).toBe(200)
+    expect((await app.request(path)).status).toBe(403)
+  })
+
+  test('bypasses stale edge entries after a chain becomes a Zone', async () => {
+    const store = Store.memory()
+    const path = `/v1/tokenlist?chainId=${zone}`
+    const publicApp = TestApp.create({
+      auth: false,
+      cache: { store },
+      supportedChainIds: [zone],
+    })
+    expect((await publicApp.request(path)).status).toBe(200)
+
+    const privateApp = TestApp.create({ auth: false, cache: { store }, zones: [zoneOptions(zone)] }) // prettier-ignore
+    expect((await privateApp.request(path)).status).toBe(403)
+  })
+
+  test('public chains remain edge-cacheable on a Zone deployment', async () => {
+    const store = Store.memory()
+    const app = TestApp.create({ auth: false, cache: { store }, zones: [zoneOptions(zone)] })
+    const path = `/v1/tokenlist?chainId=${Viem.chainId.testnet}`
+
+    const first = await app.request(path)
+    const second = await app.request(path)
+    expect(first.status).toBe(200)
+    expect(second.status).toBe(200)
+    expect(second.headers.get('cache-control')).toContain('public')
+  })
+})
+
 describe('sandbox chain guard', () => {
   test('rejects a sandbox key that omits `chainId` on a mainnet-default deployment', async () => {
     const response = await mainnetDefaultClient().v1.tokenlist.$get({ query: {} }, as(sandbox))
@@ -70,3 +417,10 @@ describe('sandbox chain guard', () => {
     expect(response.status).toBe(200)
   })
 })
+
+async function exhaustPublicQuota(store: Store.Store) {
+  const limit = { perMinute: 60 }
+  const rateLimit = RateLimit.memory({ store })
+  for (let index = 0; index < limit.perMinute; index++)
+    await rateLimit.consume({ key: 'public:anonymous', limit })
+}