tapimo 0.7.2 → 0.8.0

package/src/apps/index.ts

@@ -1,4 +1,5 @@
 export { data, FxOracle } from './data/index.js'
+export { funding } from './funding/index.js'
 export { management } from './management/index.js'
 export { mcp } from './mcp.js'
 export { mpp } from './mpp/index.js'

package/src/apps/management/routes/api-keys.test.ts

@@ -256,6 +256,99 @@ describe('keys', () => {
     expect(empty).toEqual({ data: [] })
   })
 
+  test('creates, reads, updates, enforces, and clears an IP allowlist', async () => {
+    const state = TestApp.kvStore()
+    const app = TestApp.create({
+      // Avoid waiting for the accepted KV and isolate-cache propagation delay.
+      auth: { cache: false, superAdmin: { secret } },
+      kv: { store: state },
+      session: { wallet: { origin } },
+    }).get(
+      '/custom/allowlist-test',
+      Auth.policy({ apiKey: { scopes: ['data:read'] } }),
+      OpenApi.describeRoute({
+        operationId: 'getAllowlistTest',
+        responses: { 200: { description: 'Allowlist test response.' } },
+        summary: 'Test allowlist',
+      }),
+      (c) => c.json({ ok: true }, 200),
+    )
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    const created = await TestApp.json(
+      await app.request(
+        base,
+        superAdminJson('POST', {
+          allowedIps: ['203.0.113.0/24'],
+          scopes: ['data:read'],
+        }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+
+    expect(created.allowedIps).toEqual(['203.0.113.0/24'])
+    const authenticate = (address?: string) =>
+      app.request('/custom/allowlist-test', {
+        headers: {
+          ...(address ? { 'cf-connecting-ip': address } : {}),
+          'tempo-api-key': created.token,
+        },
+      })
+    const listed = await TestApp.json(
+      await app.request(base, { headers: { cookie } }),
+      Keys.schema.listApiKeys.Response,
+    )
+    expect(listed.data[0]?.allowedIps).toEqual(['203.0.113.0/24'])
+
+    expect((await authenticate('203.0.113.7')).status).toBe(200)
+    const denied = await authenticate('198.51.100.7')
+    expect(denied.status).toBe(403)
+    expect(await denied.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+
+    const updated = await TestApp.json(
+      await app.request(
+        `${base}/${created.id}`,
+        json('PATCH', cookie, { allowedIps: ['198.51.100.7'] }),
+      ),
+      Keys.schema.Key,
+    )
+    expect(updated.allowedIps).toEqual(['198.51.100.7'])
+
+    expect((await authenticate('203.0.113.7')).status).toBe(403)
+    expect((await authenticate('198.51.100.7')).status).toBe(200)
+
+    const cleared = await TestApp.json(
+      await app.request(`${base}/${created.id}`, json('PATCH', cookie, { allowedIps: [] })),
+      Keys.schema.Key,
+    )
+    expect(cleared.allowedIps).toEqual([])
+    expect((await authenticate()).status).toBe(200)
+  })
+
+  test('rejects malformed IP allowlists on create and update', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+
+    const invalidCreate = await app.request(
+      base,
+      json('POST', cookie, { allowedIps: ['203.0.113.0/33'], scopes: ['data:read'] }),
+    )
+    expect(invalidCreate.status).toBe(400)
+
+    const created = await TestApp.json(
+      await app.request(base, json('POST', cookie, { scopes: ['data:read'] })),
+      Keys.schema.createApiKey.Response,
+    )
+    const invalidUpdate = await app.request(
+      `${base}/${created.id}`,
+      json('PATCH', cookie, { allowedIps: ['*'] }),
+    )
+    expect(invalidUpdate.status).toBe(400)
+  })
+
   test('rejects the wildcard scope at mint', async () => {
     const app = createApp()
     const cookie = await session(app)
@@ -427,6 +520,11 @@ describe('keys', () => {
       { headers: { cookie: owner }, method: 'DELETE' },
     )
     expect(crossRevoke.status).toBe(404)
+    const crossUpdate = await app.request(
+      `/v1/orgs/${org.id}/projects/${other.id}/api-keys/${minted.id}`,
+      json('PATCH', owner, { allowedIps: ['203.0.113.0/24'] }),
+    )
+    expect(crossUpdate.status).toBe(404)
 
     // Foreign session: the whole surface 404s at the org-ownership link.
     const stranger = await session(app)

package/src/apps/management/routes/api-keys.ts

@@ -3,6 +3,7 @@ import * as z from 'zod/mini'
 
 import * as Analytics from '../../../analytics/Analytics.js'
 import * as RequestEvents from '../../../analytics/tables/requestEvents.js'
+import * as ApiKey from '../../../ApiKey.js'
 import * as ApiKeys from '../../../ApiKeys.js'
 import type * as App from '../../../App.js'
 import * as Db from '../../../db/Db.js'
@@ -19,6 +20,12 @@ export namespace schema {
   /** One API key: metadata only — the token appears once, at mint. */
   export const Key = Schema.describe(
     z.object({
+      allowedIps: ApiKey.schema.AllowedIps.check(
+        z.describe(
+          'Client IP addresses and CIDR ranges allowed to use this key. An empty list means unrestricted.',
+        ),
+        z.meta({ examples: [['203.0.113.0/24', '2001:db8::1']] }),
+      ),
       createdAt: z
         .string()
         .check(
@@ -140,6 +147,14 @@ export namespace schema {
   /** Request body minting a key. The wildcard scope is not issuable here. */
   export const KeyBody = z
     .object({
+      allowedIps: z
+        .optional(ApiKey.schema.AllowedIps)
+        .check(
+          z.describe(
+            'Client IP addresses and CIDR ranges allowed to use the key. Omit or use an empty list for unrestricted access.',
+          ),
+          z.meta({ examples: [['203.0.113.0/24']] }),
+        ),
       environment: z
         ._default(z.enum(['production', 'sandbox']), 'production')
         .check(z.describe('Key environment.'), z.meta({ examples: ['sandbox'] })),
@@ -224,10 +239,25 @@ export namespace schema {
       })
       .check(z.describe('Confirmation that the key was revoked.'))
   }
+
+  /** Schemas for the updateApiKey operation. */
+  export namespace updateApiKey {
+    /** Request body replacing or clearing a key's IP allowlist. */
+    export const Body = z
+      .object({
+        allowedIps: ApiKey.schema.AllowedIps.check(
+          z.describe(
+            'Replacement client IP/CIDR allowlist. Use an empty list for unrestricted access.',
+          ),
+          z.meta({ examples: [['203.0.113.0/24']] }),
+        ),
+      })
+      .check(z.describe("Fields for updating an API key's network access."))
+  }
 }
 
 /**
- * Mounts project-attributed API key mint, list, and revoke routes plus the org-wide list. Project routes enforce caller organization and project attribution.
+ * Mounts project-attributed API key mint, list, update, and revoke routes plus the org-wide list. Project routes enforce caller organization and project attribution.
  */
 export function apiKeys(options: apiKeys.Options = {}) {
   const hidden = !options.enabled
@@ -313,6 +343,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
             {
               createdBy,
               environment: body.environment,
+              ...(body.allowedIps === undefined ? {} : { allowedIps: body.allowedIps }),
               ...(billingActive === undefined ? {} : { billingActive }),
               ...(body.name === undefined ? {} : { name: body.name }),
               orgId,
@@ -453,6 +484,69 @@ export function apiKeys(options: apiKeys.Options = {}) {
         }
       },
     )
+    .patch(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
+      Auth.ensureOrg({ role: 'admin' }),
+      Auth.ensureProject(),
+      OpenApi.validate('param', schema.KeyParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('json', schema.updateApiKey.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        description:
+          "Replace an API key's client IP/CIDR allowlist. An empty list removes the restriction.",
+        hide: hidden,
+        operationId: 'updateApiKey',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'No accessible API key was found for this id.',
+          },
+          success: {
+            description: 'The updated API key metadata.',
+            schema: schema.Key,
+          },
+        }),
+        summary: 'Update API key',
+        tags: ['API Keys'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (Auth.narrowScope) return Auth.ensureProjectError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const kv = c.get('kv')
+        if (!kv) return notEnabled(c)
+        const { keyId } = c.req.valid('param')
+        try {
+          const record = await ApiKeys.get(kv.store, keyId, {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
+          if (!record || record.orgId !== Auth.org(c).id || record.projectId !== Auth.project(c).id)
+            return keyNotFound(c)
+          const updated = await ApiKeys.update(kv.store, keyId, c.req.valid('json'), {
+            scopeCatalog: c.get('scopeCatalog'),
+          })
+          if (!updated) return keyNotFound(c)
+          return c.json(Response.validated(schema.Key, serializeKey(updated)), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}/api-keys/:keyId{key_[A-Za-z0-9_-]+}',
       Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
@@ -532,6 +626,7 @@ async function serializeKeys(c: Context<App.Environment>, records: readonly ApiK
 /** Projects a persisted record onto the management key shape (no rate limits, no token). */
 function serializeKey(record: ApiKeys.Record, lastUsedAt?: string) {
   return {
+    allowedIps: [...record.allowedIps],
     createdAt: record.createdAt,
     ...(record.createdBy === undefined ? {} : { createdBy: record.createdBy }),
     environment: record.environment,

package/src/apps/mcp.test.ts

@@ -1,4 +1,6 @@
 import { Cli as incur_Cli, z } from 'incur'
+import { App } from 'tapimo'
+import { data } from 'tapimo/apps'
 
 import * as TestApp from '../../test/App.js'
 import * as Runtime from '../../test/runtime.js'
@@ -17,7 +19,7 @@ const reader = {
 /** Composes a test app with the MCP group mounted, dispatching in-process. */
 function createHost(
   options: {
-    app?: ReturnType<typeof TestApp.create> | undefined
+    app?: Host | undefined
     docs?: mcp.Options['docs'] | undefined
   } = {},
 ) {
@@ -149,7 +151,7 @@ test('identifies as Tempo MCP', async () => {
   })
 })
 
-test('scopes tools to the data domain', async () => {
+test('scopes tools to the data and inbound funding domains', async () => {
   const { app, host } = createHost({ docs: docsStub() })
 
   // The domain filter must drop paths that actually exist in the spec.
@@ -170,6 +172,8 @@ test('scopes tools to the data domain', 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('docs_search')
   // RPC is part of the data domain tag group.
   expect(tools.some((name) => name.startsWith('rpc'))).toBe(true)
@@ -180,6 +184,17 @@ test('scopes tools to the data domain', async () => {
   expect(tools.some((name) => name.startsWith('v1_me'))).toBe(false)
 })
 
+test('keeps the data tools functional when funding is omitted', async () => {
+  const app = App.create({ auth: false, db: TestApp.database() }).route('/', data())
+  const { host } = createHost({ app })
+
+  await initialize(host)
+  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)
+})
+
 test('keeps tool input schemas compact', async () => {
   const { host } = createHost()
   await initialize(host)

package/src/apps/mcp.ts

@@ -7,15 +7,18 @@ import * as Auth from '../internal/Auth.js'
 import * as OpenApi from '../internal/OpenApi.js'
 import * as Metadata from './metadata.js'
 
-/** Document tag group whose operations surface as MCP tools (the data domain). */
-const tagGroup = 'Data API'
+/** 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'
 
 /** 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 domain and 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 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."
 
 /** Zod schemas owned by the MCP endpoint's OpenAPI description. */
 export namespace schema {
@@ -56,9 +59,8 @@ export namespace schema {
 
 /**
  * The MCP route group: a stateless streamable-HTTP MCP server at `/mcp` whose
- * tools mirror the API's data domain (scoped via the OpenAPI document's
- * `Data API` tag group), plus the remote Tempo docs tools. Mount alongside
- * the other route groups:
+ * tools mirror the API's data domain and its optional inbound funding domain,
+ * plus the remote Tempo docs tools. Mount alongside the other route groups:
  *
  * ```ts
  * const app = App.create(options)
@@ -208,7 +210,7 @@ const openapi = {
         'A hosted Model Context Protocol server: the data domain and Tempo docs exposed as tools.',
     },
   ],
-  'x-tagGroups': [{ name: tagGroup, tags: ['MCP'] }],
+  'x-tagGroups': [{ name: dataTagGroup, tags: ['MCP'] }],
 } satisfies App.create.Metadata
 
 /** The slice of the OpenAPI document the domain filter reads. */
@@ -221,14 +223,17 @@ type Document = Openapi.OpenAPISpec & {
 const methods: readonly string[] = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'] // prettier-ignore
 
 /**
- * Narrows the document to the data domain: operations tagged inside the
- * `Data API` tag group, minus excluded tags. Management, relay, and session
- * operations never surface as tools.
+ * Narrows the document to the data and optional inbound funding domains.
+ * Management, relay, and session operations never surface as tools.
  */
 function scope(document: Document): Openapi.OpenAPISpec {
-  const group = document['x-tagGroups']?.find((entry) => entry.name === tagGroup)
-  if (!group) throw new Error(`openapi.json is missing the "${tagGroup}" tag group`)
-  const tags = new Set(group.tags.filter((tag) => !excludedTags.includes(tag)))
+  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 tags = new Set(
+    [...dataGroup.tags, ...(fundingGroup?.tags ?? [])].filter((tag) => !excludedTags.includes(tag)),
+  )
   const paths: Document['paths'] = {}
   for (const [path, item] of Object.entries(document.paths)) {
     // Keep in-domain operations; non-method keys (parameters, summary) ride along.

package/src/apps/metadata.ts

@@ -7,6 +7,7 @@ import type * as App from '../App.js'
 // `App.create` reads it back on mount. The `WeakMap` keeps the association off
 // the app's type, so `testClient`/`hc` inference is untouched.
 const registry = new WeakMap<Hono<any, any>, App.create.Metadata>()
+const defaultChainRegistry = new WeakSet<Hono<any, any>>()
 
 /** Attaches a group's OpenAPI metadata to its app instance for `create` to collect on mount. */
 export function attach<const app extends Hono<any, any>>(
@@ -21,3 +22,14 @@ export function attach<const app extends Hono<any, any>>(
 export function read(app: Hono<any, any>): App.create.Metadata | undefined {
   return registry.get(app)
 }
+
+/** Marks a group whose routes use the root app's default chain access policy. */
+export function defaultChain<const app extends Hono<any, any>>(app: app): app {
+  defaultChainRegistry.add(app)
+  return app
+}
+
+/** Returns whether a group uses the root app's default chain access policy. */
+export function usesDefaultChain(app: Hono<any, any>): boolean {
+  return defaultChainRegistry.has(app)
+}

package/src/apps/mpp/internal/Policy.test.ts

@@ -20,7 +20,13 @@ const input = {
 } satisfies Mpp.RelayInput
 
 const principal = {
-  apiKey: { environment: 'production', id: 'key_mpp', orgId: 'org_mpp', scopes: ['mpp:write'] },
+  apiKey: {
+    allowedIps: [],
+    environment: 'production',
+    id: 'key_mpp',
+    orgId: 'org_mpp',
+    scopes: ['mpp:write'],
+  },
   environment: 'production',
   id: 'key_mpp',
   orgId: 'org_mpp',