tapimo 0.4.0 → 0.4.3

package/src/apps/data/routes/funding.ts

@@ -8,6 +8,7 @@ import * as FundingRoutes from '../../../internal/FundingRoutes.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
+import * as FundingRouteProviders from '../FundingRouteProviders.js'
 
 /** Zod schemas owned by the funding routes resource. */
 export namespace schema {
@@ -268,6 +269,111 @@ export namespace schema {
     'Provider-derived quote, limit, and freshness data for a route candidate.',
   )
 
+  /** Token reference attached to a normalized quote fee. */
+  export const QuoteFeeToken = Schema.describe(
+    z.object({
+      address: z
+        .string()
+        .check(
+          z.describe('Contract address of the fee token.'),
+          z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
+        ),
+      chainId: z
+        .string()
+        .check(z.describe('CAIP-2 chain id of the fee token.'), z.meta({ examples: ['eip155:8453'] })), // prettier-ignore
+      decimals: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Number of decimal places used by the fee token.'),
+          z.meta({ examples: [6] }),
+        ),
+      symbol: z
+        .string()
+        .check(z.describe('Ticker symbol of the fee token.'), z.meta({ examples: ['USDC'] })),
+    }),
+    'Token in which a normalized quote fee is denominated.',
+  )
+
+  /** Normalized fee summary for an explicit funding quote. */
+  export const QuoteFee = Schema.describe(
+    z.object({
+      amount: Schema.DecimalString.check(
+        z.describe("Fee amount in the fee token's smallest unit."),
+        z.meta({ examples: ['1200'] }),
+      ),
+      amountUsd: z
+        .nullable(z.string().check(z.regex(/^\d+(\.\d+)?$/)))
+        .check(
+          z.describe('Provider-estimated USD value of the fee.'),
+          z.meta({ examples: ['0.0012'] }),
+        ),
+      bps: z
+        .nullable(z.number().check(z.int(), z.nonnegative()))
+        .check(z.describe('Fee as basis points of the quoted input.'), z.meta({ examples: [12] })),
+      token: QuoteFeeToken,
+    }),
+    'Provider-neutral fee amount and denomination.',
+  )
+
+  /** Explicit depositor-specific quote for one curated funding route. */
+  export const FundingQuote = Schema.describe(
+    z.object({
+      destinationChain: Chain.check(z.describe('Destination chain for the quoted route.')),
+      destinationToken: Token.check(z.describe('Token received on the destination chain.')),
+      estimatedSeconds: z
+        .nullable(z.number().check(z.int(), z.nonnegative()))
+        .check(z.describe('Estimated settlement time in seconds.'), z.meta({ examples: [2] })),
+      expiresAt: z.iso
+        .datetime()
+        .check(
+          z.describe('Timestamp after which the quote must not be used.'),
+          z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
+        ),
+      fees: z
+        .object({
+          total: QuoteFee.check(z.describe('Current estimated total fee.')),
+          totalMax: QuoteFee.check(z.describe('Maximum total fee allowed by the quote.')),
+        })
+        .check(z.describe('Current and maximum provider fee summaries.')),
+      inputAmount: Schema.DecimalString.check(
+        z.describe('Exact source amount quoted in base units.'),
+        z.meta({ examples: ['1000000'] }),
+      ),
+      minimumOutputAmount: Schema.DecimalString.check(
+        z.describe('Slippage-adjusted minimum destination amount in base units.'),
+        z.meta({ examples: ['988000'] }),
+      ),
+      outputAmount: Schema.DecimalString.check(
+        z.describe('Expected destination amount in base units.'),
+        z.meta({ examples: ['990000'] }),
+      ),
+      outputAmountFormatted: z
+        .string()
+        .check(
+          z.describe('Expected destination amount rendered with token decimals.'),
+          z.meta({ examples: ['0.99'] }),
+        ),
+      provider: ProviderRef.check(z.describe('Provider that produced the quote.')),
+      routeId: z
+        .string()
+        .check(
+          z.describe('Stable id of the curated route that was quoted.'),
+          z.meta({ examples: ['base-usdc-tempo-usdce-across'] }),
+        ),
+      sampledAt: z.iso
+        .datetime()
+        .check(
+          z.describe('Timestamp when Tempo sampled the provider quote.'),
+          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
+        ),
+      sourceChain: Chain.check(z.describe('Source chain for the quoted route.')),
+      sourceToken: Token.check(z.describe('Token spent on the source chain.')),
+    }),
+    'Normalized quote information without provider execution payloads.',
+  )
+
   /** Static or live funding route candidate. */
   export const RouteCandidate = Schema.describe(
     z.object({
@@ -422,6 +528,63 @@ export namespace schema {
     )
   }
 
+  /** Schemas for the quoteFundingRoute operation. */
+  export namespace quoteFundingRoute {
+    /** JSON body for an explicit funding route quote. */
+    export const Body = z
+      .strictObject({
+        depositor: Schema.Address.check(
+          z.describe('Address that would submit the funding transaction.'),
+        ),
+        destinationToken: z
+          .optional(z.string())
+          .check(
+            z.describe('Tempo destination token symbol, address, or token key.'),
+            z.meta({ examples: ['USDC.e'] }),
+          ),
+        provider: z
+          .literal('across')
+          .check(
+            z.describe('Provider id selected from funding route discovery.'),
+            z.meta({ examples: ['across'] }),
+          ),
+        recipient: z
+          .optional(Schema.Address)
+          .check(z.describe('Optional destination recipient; defaults to the depositor.')),
+        sourceAmount: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Exact source amount to quote.'),
+            z.meta({ examples: ['1000000'] }),
+          ),
+        sourceAmountUnits: z
+          ._default(z.enum(['baseUnits', 'decimal']), 'baseUnits')
+          .check(
+            z.describe('Whether `sourceAmount` uses base units or decimal notation.'),
+            z.meta({ examples: ['baseUnits'] }),
+          ),
+        sourceChain: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source chain alias or CAIP-2 id.'),
+            z.meta({ examples: ['base'] }),
+          ),
+        sourceToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source token symbol, address, mint, or token key.'),
+            z.meta({ examples: ['USDC'] }),
+          ),
+      })
+      .check(z.describe('Parameters for a depositor-specific exact-input funding quote.'))
+
+    /** Normalized funding quote without provider execution payloads. */
+    export const Response = FundingQuote
+  }
+
   /** Schemas for the listFundingChains operation. */
   export namespace listFundingChains {
     /** Non-paginated source-chain inventory. */
@@ -518,6 +681,56 @@ const providersResponseExample = {
   data: FundingRoutes.listProviders(),
 } satisfies z.output<typeof schema.listProviders.Response>
 
+const [fundingQuoteRouteExample] = FundingRoutes.listStaticRoutes({
+  destinationToken: 'USDC.e',
+  limit: 1,
+  provider: 'across',
+  sourceAmount: '1000000',
+  sourceAmountUnits: 'baseUnits',
+  sourceChain: 'base',
+  sourceToken: 'USDC',
+})
+
+const fundingQuoteResponseExample = {
+  destinationChain: fundingQuoteRouteExample!.destinationChain,
+  destinationToken: fundingQuoteRouteExample!.destinationToken,
+  estimatedSeconds: 2,
+  expiresAt: '2026-01-01T00:01:00Z',
+  fees: {
+    total: {
+      amount: '1200',
+      amountUsd: '0.0012',
+      bps: 12,
+      token: {
+        address: fundingQuoteRouteExample!.sourceToken.address,
+        chainId: fundingQuoteRouteExample!.sourceChain.id,
+        decimals: fundingQuoteRouteExample!.sourceToken.decimals,
+        symbol: fundingQuoteRouteExample!.sourceToken.symbol,
+      },
+    },
+    totalMax: {
+      amount: '1800',
+      amountUsd: '0.0018',
+      bps: 18,
+      token: {
+        address: fundingQuoteRouteExample!.sourceToken.address,
+        chainId: fundingQuoteRouteExample!.sourceChain.id,
+        decimals: fundingQuoteRouteExample!.sourceToken.decimals,
+        symbol: fundingQuoteRouteExample!.sourceToken.symbol,
+      },
+    },
+  },
+  inputAmount: '1000000',
+  minimumOutputAmount: '988000',
+  outputAmount: '990000',
+  outputAmountFormatted: '0.99',
+  provider: fundingQuoteRouteExample!.provider,
+  routeId: fundingQuoteRouteExample!.id,
+  sampledAt: '2026-01-01T00:00:00Z',
+  sourceChain: fundingQuoteRouteExample!.sourceChain,
+  sourceToken: fundingQuoteRouteExample!.sourceToken,
+} satisfies z.output<typeof schema.quoteFundingRoute.Response>
+
 /** Mounts funding route discovery and generic provider inventory endpoints. */
 export function funding(options: funding.Options = {}) {
   return new Hono<App.Environment>()
@@ -585,6 +798,103 @@ export function funding(options: funding.Options = {}) {
         }
       },
     )
+    .post(
+      '/v1/funding/routes/quote',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('json', schema.quoteFundingRoute.Body, {
+        code: 'body_invalid',
+        message: 'Invalid quote parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Gets a depositor-specific exact-input quote for one curated funding route. The response excludes provider transaction calldata, approvals, and wallet balance details.',
+        operationId: 'quoteFundingRoute',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid'] },
+            404: { codes: ['route_not_found', 'quote_unavailable'] },
+            501: { codes: ['provider_unconfigured'] },
+            502: { codes: ['provider_error', 'provider_rate_limited', 'provider_timeout'] },
+          },
+          success: {
+            description: 'Normalized route quote without provider execution payloads.',
+            example: fundingQuoteResponseExample,
+            schema: schema.quoteFundingRoute.Response,
+          },
+        }),
+        summary: 'Quote funding route',
+        tags: ['Funding'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Invalid quote parameters',
+          })
+
+        const body = c.req.valid('json')
+        try {
+          const quote = await FundingRoutes.quoteRoute({
+            depositor: body.depositor,
+            destinationToken: body.destinationToken,
+            provider: body.provider,
+            quote: options.acrossQuote,
+            quoteTimeoutMs: options.quoteTimeoutMs,
+            recipient: body.recipient,
+            sourceAmount: body.sourceAmount,
+            sourceAmountUnits: body.sourceAmountUnits,
+            sourceChain: body.sourceChain,
+            sourceToken: body.sourceToken,
+          })
+          c.header('Cache-Control', 'no-store')
+          return c.json(Response.validated(schema.quoteFundingRoute.Response, quote), 200)
+        } catch (cause) {
+          const message = requestErrorMessage(cause)
+          if (message) return Response.error(c, { code: 'body_invalid', message, status: 400 })
+          if (cause instanceof FundingRoutes.FundingRouteNotFoundError)
+            return Response.error(c, {
+              code: 'route_not_found',
+              message: 'No curated funding route matches the request.',
+              status: 404,
+            })
+          if (cause instanceof FundingRoutes.ProviderQuoteUnavailableError)
+            return Response.error(c, {
+              code: 'quote_unavailable',
+              message: 'The provider cannot quote this route.',
+              status: 404,
+            })
+          if (cause instanceof FundingRoutes.ProviderNotConfiguredError)
+            return Response.error(c, {
+              code: 'provider_unconfigured',
+              message: 'The provider quote integration is not configured.',
+              status: 501,
+            })
+          if (cause instanceof FundingRoutes.ProviderRateLimitError)
+            return Response.error(c, {
+              code: 'provider_rate_limited',
+              message: 'The provider temporarily rate-limited this quote.',
+              status: 502,
+            })
+          if (cause instanceof FundingRoutes.ProviderAdapterTimeoutError)
+            return Response.error(c, {
+              code: 'provider_timeout',
+              message: 'The provider quote timed out.',
+              status: 502,
+            })
+          if (cause instanceof Error) {
+            const providerFailure = FundingRouteProviders.acrossQuoteFailure({ cause })
+            if (providerFailure) c.set('providerFailure', providerFailure)
+            return Response.error(c, {
+              code: 'provider_error',
+              message: 'The provider could not complete the quote.',
+              status: 502,
+            })
+          }
+          throw cause
+        }
+      },
+    )
     .get(
       '/v1/funding/chains',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -658,6 +968,7 @@ export function funding(options: funding.Options = {}) {
             data: FundingRoutes.listProviders({
               adapters: options.adapters,
               capability: query.capability,
+              configuredProviders: options.acrossQuote ? ['across'] : [],
             }),
           }),
           200,
@@ -669,10 +980,14 @@ export function funding(options: funding.Options = {}) {
 export declare namespace funding {
   /** Options for funding route discovery. */
   type Options = {
+    /** Across explicit quote capability. */
+    acrossQuote?: FundingRoutes.ProviderQuote | undefined
     /** Provider adapters used to enrich static inventory with live data. */
     adapters?: FundingRoutes.ProviderAdapters | undefined
     /** Per-provider quote timeout in milliseconds. */
     adapterTimeoutMs?: number | undefined
+    /** Timeout for depositor-specific provider quotes. */
+    quoteTimeoutMs?: number | undefined
   }
 }
 

package/src/apps/data/routes/rpc.test.ts

@@ -338,6 +338,39 @@ describe('POST /rpc', () => {
       fetch.restore()
     }
   })
+
+  test('uses the RPC path for sandbox chain checks', async () => {
+    const app = TestApp.create({
+      auth: {
+        keys: [
+          {
+            environment: 'sandbox',
+            id: 'key_sandbox',
+            orgId: 'org_test',
+            scopes: ['data:read'],
+            token: 'secret_sandbox_key',
+          },
+        ],
+      },
+      defaultChainId: 4217,
+    })
+    const request = (path: string) =>
+      app.fetch(
+        new Request(`http://tempo-api.test${path}`, {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          headers: { 'tempo-api-key': 'secret_sandbox_key' },
+          method: 'POST',
+        }),
+      )
+
+    const rejected = await request('/rpc/4217?chainId=42431')
+    const rejectedDefault = await request('/rpc?chainId=42431')
+    const rejectedTrailing = await request('/rpc/?chainId=42431')
+
+    expect(rejected.status).toMatchInlineSnapshot(`403`)
+    expect(rejectedDefault.status).toMatchInlineSnapshot(`403`)
+    expect(rejectedTrailing.status).toMatchInlineSnapshot(`404`)
+  })
 })
 
 describe('POST /rpc/relay', () => {

package/src/apps/management/App.ts

@@ -87,8 +87,8 @@ export type Environment = {
  * invitations, and API-key management. Every route reads its dependencies from
  * request context set by {@link App.create}.
  *
- * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
- * {@link App.create}, so management routes gate on a session without owning it.
+ * The session-auth surface is owned by {@link App.create}; management routes
+ * reference it alongside scoped API-key access.
  *
  * ```ts
  * App.create(options).route('/', management())

package/src/apps/management/Billing.ts

@@ -7,6 +7,7 @@ import type * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Fees from '../../internal/Fees.js'
 import * as RequestUsage from '../../db/tables/requestUsage.js'
+import type * as Scope from '../../Scope.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as Viem from '../../internal/Viem.js'
@@ -641,7 +642,7 @@ export async function listActive(
 export function createKeyBillingSyncer(
   options: createKeyBillingSyncer.Options,
 ): createKeyBillingSyncer.Syncer {
-  const { db, environments = ['sandbox'], kv } = options
+  const { db, environments = ['sandbox'], kv, scopeCatalog } = options
   return {
     async tick() {
       // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
@@ -655,7 +656,12 @@ export function createKeyBillingSyncer(
           checked += 1
           // `setBillingActive` writes only drifted records, so a converged
           // fleet costs list reads and no writes.
-          updated += await ApiKeys.setBillingActive(kv, { active, environment, orgId })
+          updated += await ApiKeys.setBillingActive(kv, {
+            active,
+            environment,
+            orgId,
+            scopeCatalog,
+          })
         }
       }
       return { checked, updated }
@@ -672,6 +678,8 @@ export declare namespace createKeyBillingSyncer {
     environments?: readonly StripeCustomers.Record['environment'][] | undefined
     /** KV state store holding API-key records. */
     kv: Store.State
+    /** Scope catalog accepted while reconciling API-key records. */
+    scopeCatalog?: Scope.Catalog | undefined
   }
 
   /** A scheduled snapshot-reconcile job. */

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

@@ -1,8 +1,13 @@
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
 import * as ApiKeys from '../../../ApiKeys.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Scope from '../../../Scope.js'
 import * as TestApp from '../../../../test/App.js'
+import * as Memberships from '../../../db/tables/memberships.js'
 import * as Keys from './api-keys.js'
+import * as Me from './me.js'
 import * as Orgs from './orgs.js'
 import * as Projects from './projects.js'
 
@@ -33,10 +38,18 @@ function superAdminJson(method: 'PATCH' | 'POST', body: unknown) {
 // Resolve-cache disabled so revocation assertions observe the store directly.
 type State = ReturnType<typeof TestApp.kvStore>
 
-function createApp(options: { kv?: { store: State } } = {}) {
+function createApp(
+  options: {
+    db?: ReturnType<typeof TestApp.database>
+    kv?: { store: State }
+    scopes?: readonly Scope.Entry[]
+  } = {},
+) {
   return TestApp.create({
     auth: { cache: false, superAdmin: { secret } },
+    db: options.db ?? TestApp.database(),
     ...(options.kv ? { kv: options.kv } : {}),
+    ...(options.scopes ? { scopes: options.scopes } : {}),
     session: { wallet: { origin } },
   })
 }
@@ -70,6 +83,77 @@ async function fixture(app: ReturnType<typeof createApp>, cookie: string) {
 }
 
 describe('keys', () => {
+  test('requires an owner to issue management write keys', async () => {
+    const db = TestApp.database()
+    const app = createApp({ db })
+    const owner = await session(app)
+    const { org, project } = await fixture(app, owner)
+    const admin = await session(app)
+    const user = await TestApp.json(
+      await app.request('/v1/me', { headers: { cookie: admin } }),
+      Me.schema.User,
+    )
+    await Memberships.create(db, {
+      orgId: org.id,
+      role: 'admin',
+      userId: user.id,
+    })
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+
+    const read = await app.request(base, json('POST', admin, { scopes: ['management:read'] }))
+    expect(read.status).toBe(200)
+
+    const denied = await app.request(base, json('POST', admin, { scopes: ['management:write'] }))
+    expect(denied.status).toBe(403)
+    expect(await denied.json()).toMatchObject({ error: { code: 'scope_not_issuable' } })
+
+    const write = await app.request(base, json('POST', owner, { scopes: ['management:write'] }))
+    expect(write.status).toBe(200)
+  })
+
+  test('lets management keys manage org credentials without delegating issuance', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+    const other = await TestApp.json(
+      await app.request(`/v1/orgs/${org.id}/projects`, json('POST', cookie, { name: 'Payments' })),
+      Projects.schema.Project,
+    )
+    const base = `/v1/orgs/${org.id}/projects/${project.id}/api-keys`
+    const siblingBase = `/v1/orgs/${org.id}/projects/${other.id}/api-keys`
+    const manager = await TestApp.json(
+      await app.request(
+        base,
+        superAdminJson('POST', {
+          scopes: ['management:read', 'management:write'],
+        }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    const target = await TestApp.json(
+      await app.request(siblingBase, superAdminJson('POST', { scopes: ['data:read'] })),
+      Keys.schema.createApiKey.Response,
+    )
+
+    const listed = await app.request(siblingBase, {
+      headers: { 'tempo-api-key': manager.token },
+    })
+    expect(listed.status).toBe(200)
+
+    const delegated = await app.request(base, {
+      body: JSON.stringify({ scopes: ['management:read'] }),
+      headers: { 'content-type': 'application/json', 'tempo-api-key': manager.token },
+      method: 'POST',
+    })
+    expect(delegated.status).toBe(403)
+
+    const revoked = await app.request(`${siblingBase}/${target.id}`, {
+      headers: { 'tempo-api-key': manager.token },
+      method: 'DELETE',
+    })
+    expect(revoked.status).toBe(200)
+  })
+
   test('mints, lists, authenticates, and revokes a project key', async () => {
     const app = createApp()
     const cookie = await session(app)
@@ -187,6 +271,58 @@ describe('keys', () => {
     expect(created.createdBy).not.toBe('super_admin')
   })
 
+  test('mints and authenticates host scopes', async () => {
+    const app = createApp({
+      scopes: [
+        {
+          description: 'Read project accounts.',
+          scope: 'accounts:read',
+          selfServe: true,
+        },
+      ],
+    }).get(
+      '/custom/accounts',
+      Auth.policy({ apiKey: { scopes: ['accounts:read'] } }),
+      OpenApi.describeRoute({
+        operationId: 'getCustomAccounts',
+        responses: { 200: { description: 'Custom accounts response.' } },
+        summary: 'Get custom accounts',
+      }),
+      (c) => c.json({ ok: true }, 200),
+    )
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const created = await TestApp.json(
+      await app.request(
+        `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+        json('POST', cookie, { scopes: ['accounts:read'] }),
+      ),
+      Keys.schema.createApiKey.Response,
+    )
+    const response = await app.request('/custom/accounts', {
+      headers: { 'tempo-api-key': created.token },
+    })
+
+    expect(created.scopes).toEqual(['accounts:read'])
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true })
+  })
+
+  test('rejects unregistered host scopes', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const response = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      superAdminJson('POST', { scopes: ['accounts:read'] }),
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({ error: { code: 'body_invalid' } })
+  })
+
   test('rejects session mints of non-self-serve scopes (webhooks)', async () => {
     const app = createApp()
     const cookie = await session(app)