tapimo 0.15.0 → 0.18.0

package/src/apps/routes/Access.test.ts

@@ -0,0 +1,319 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as ApiKeys from '../../ApiKeys.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as Projects from '../../db/tables/projects.js'
+import * as RoutesPolicies from '../../db/tables/routesPolicies.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
+import * as Auth from '../../internal/Auth.js'
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Store from '../../internal/Store.js'
+import * as Policy from '../../internal/routes/Policy.js'
+import * as Relay from '../../internal/routes/providers/relay.js'
+import * as Access from './Access.js'
+
+const route = {
+  sourceChainId: 'eip155:8453',
+  sourceTokenId: 'USDC',
+  destinationChainId: 'eip155:4217',
+  destinationTokenId: 'USDC.e',
+  providerId: 'relay',
+} satisfies Policy.Rule
+
+describe('filterCatalog', () => {
+  test('allows a per-route enable through a disabled legacy gate', () => {
+    const catalogRoute = TestRoutes.snapshot.routes.find((item) => item.providerId === 'relay')!
+    const input = context({ terms: [{ ...Policy.fromRoute(catalogRoute), subsidyEnabled: true }] })
+    input.layers[0] = { access: null, subsidyRoutes: null }
+    const filtered = Access.filterCatalog(TestRoutes.snapshot, input, true)
+
+    expect(filtered.routes.map((item) => item.providerId)).toContain('relay')
+  })
+
+  test('keeps the legacy not-enabled error when no catalog route is enabled', () => {
+    const input = context({ subsidyEnabled: false })
+    expect(() => Access.filterCatalog(TestRoutes.snapshot, input, true)).toThrowError(
+      expect.objectContaining({
+        code: 'routes_subsidy_not_enabled',
+        message:
+          'Route subsidies are not enabled for this request. Contact Tempo to enable them, or use an API key from an organization with subsidies enabled.',
+      }),
+    )
+  })
+})
+
+describe('commitment', () => {
+  test('allows Tempo-paid production without customer billing and clamps the expense cap', async () => {
+    const db = TestApp.database()
+    const result = await Access.commitment(
+      db,
+      context({ subsidyPayer: 'tempo', maxAmount: '12.345678' }),
+      route,
+      '10.25',
+    )
+
+    expect(result).toEqual({
+      maxAmount: '10.25',
+      scope: { apiKeyId: 'key_policy', environment: 'production', orgId: 'org_policy' },
+      subsidyPayer: 'tempo',
+      versions: [1, 2],
+    })
+  })
+
+  test('pins inherited terms for a route enabled over legacy false', async () => {
+    const input = context({
+      terms: [{ ...route, subsidyEnabled: true, subsidyPayer: 'tempo', maxAmount: '3' }],
+    })
+    input.layers[0] = { access: null, subsidyRoutes: null }
+
+    await expect(Access.commitment(TestApp.database(), input, route, '9')).resolves.toMatchObject({
+      maxAmount: '3',
+      subsidyPayer: 'tempo',
+      versions: [1, 2],
+    })
+  })
+
+  test('requires active billing for enterprise-paid production', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_policy', name: 'Policy' })
+    const input = context({ subsidyPayer: 'enterprise', maxAmount: '5' })
+
+    await expect(Access.commitment(db, input, route, '9')).rejects.toMatchObject({
+      code: 'billing_required',
+    })
+    await StripeCustomers.create(db, { orgId: 'org_policy', stripeCustomerId: 'cus_policy' })
+    await StripeCustomers.setStatus(db, 'org_policy', 'active')
+    await expect(Access.commitment(db, input, route, '9')).resolves.toMatchObject({
+      maxAmount: '5',
+      subsidyPayer: 'enterprise',
+    })
+  })
+
+  test.each<[string, Policy.Overrides, Access.PolicyError['code']]>([
+    ['inaccessible', { access: [] }, 'routes_not_allowed'],
+    ['suspended', {}, 'routes_suspended'],
+    ['ineligible', { terms: [{ ...route, subsidyEligible: false }] }, 'routes_subsidy_not_allowed'],
+    ['globally disabled', { subsidyEnabled: false }, 'routes_subsidy_not_enabled'],
+  ])('rejects an %s route before creating a commitment', async (_name, policy, code) => {
+    const input = context(policy)
+    if (_name === 'suspended') input.layers[0] = { ...input.layers[0], suspended: true }
+    await expect(Access.commitment(TestApp.database(), input, route, '9')).rejects.toMatchObject({
+      code,
+    })
+  })
+})
+
+describe('assertPolicy', () => {
+  test.each(['organization', 'project'] as const)(
+    'rejects inherited-policy acceptance after %s reassignment without a key override',
+    async (kind) => {
+      const db = TestApp.database()
+      const state = Store.memory()
+      const org = await Organizations.create(db, { name: 'Original owner' })
+      const project =
+        kind === 'project'
+          ? await Projects.create(db, { orgId: org.id, name: 'Original project' })
+          : undefined
+      const parent = {
+        environment: 'production',
+        orgId: org.id,
+        ...(project ? { projectId: project.id } : {}),
+      } as const
+      await RoutesPolicies.save(db, {
+        scope: parent,
+        version: 0,
+        policy: { access: null, subsidyEnabled: true, subsidyPayer: 'tempo', maxAmount: '1' },
+      })
+      const { record } = await ApiKeys.mintBounded(db, state, {
+        ...parent,
+        scopes: ['routes:write'],
+      })
+      const scope = { ...parent, apiKeyId: record.id }
+      const loaded = await RoutesPolicies.load(db, scope)
+      const pending = {
+        scope,
+        layers: loaded.layers.map((layer) => layer.policy),
+        legacy: loaded.legacy,
+        versions: loaded.layers.map((layer) => layer.version),
+      }
+      expect(await RoutesPolicies.get(db, scope)).toBeUndefined()
+      await expect(
+        db.transaction((tx) => Access.assertPolicy(tx, pending)),
+      ).resolves.toBeUndefined()
+
+      const destination =
+        kind === 'organization'
+          ? { orgId: (await Organizations.create(db, { name: 'New owner' })).id }
+          : { projectId: (await Projects.create(db, { orgId: org.id, name: 'New project' })).id }
+      const moved = await ApiKeys.updateBounded(db, state, record.id, destination)
+      expect(moved).toMatchObject({ ...destination, scopes: ['routes:write'] })
+      // No explicit key policy existed, so clearing it cannot invalidate these versions.
+      expect(await RoutesPolicies.load(db, scope)).toEqual(loaded)
+      await expect(db.transaction((tx) => Access.assertPolicy(tx, pending))).rejects.toMatchObject({
+        code: 'route_policy_changed',
+      })
+    },
+  )
+
+  test.each([
+    ['revision', { maxAmount: '2' }],
+    ['suspension', { maxAmount: '1', suspended: true }],
+  ] as const)(
+    'detects a concurrent %s after taking the organization lock',
+    async (_name, policy) => {
+      const db = TestApp.database()
+      await Organizations.create(db, { id: 'org_assert', name: 'Assert' })
+      const scope = {
+        ...(_name === 'revision' ? { apiKeyId: 'key_assert' } : {}),
+        environment: 'production',
+        orgId: 'org_assert',
+      } as const
+      await RoutesPolicies.save(db, {
+        policy: { maxAmount: '1' },
+        scope,
+        version: 0,
+      })
+      const loaded = await RoutesPolicies.load(db, scope)
+      const stale = {
+        scope,
+        layers: loaded.layers.map((layer) => layer.policy),
+        legacy: loaded.legacy,
+        versions: loaded.layers.map((layer) => layer.version),
+      }
+      await RoutesPolicies.save(db, { policy, scope, version: 1 })
+
+      await expect(db.transaction((tx) => Access.assertPolicy(tx, stale))).rejects.toMatchObject({
+        code: 'route_policy_changed',
+      })
+    },
+  )
+})
+
+describe('loadPolicy', () => {
+  test('keeps missing organization policies in legacy mode until the first environment-specific save', async () => {
+    const db = TestApp.database()
+    const org = await Organizations.create(db, { name: 'Legacy policies' })
+    const keys = (['production', 'sandbox'] as const).map((environment) => ({
+      id: `key_legacy_${environment}`,
+      orgId: org.id,
+      environment,
+      token: `secret_legacy_${environment}`,
+      scopes: ['routes:read'],
+    }))
+    const app = TestApp.create({ db, auth: { keys } }).get(
+      '/policy',
+      Auth.policy({ apiKey: { scopes: ['routes:read'] } }),
+      OpenApi.describeRoute({ hide: true }),
+      async (c) => {
+        const loaded = (await Access.loadPolicy(c))!
+        return c.json({
+          access: Policy.resolve(loaded).access,
+          legacy: Access.isLegacy(loaded),
+          routes: Access.filterCatalog(TestRoutes.snapshot, loaded, false).routes.length,
+        })
+      },
+    )
+    const read = async (index: number) =>
+      (
+        await app.request('/policy', {
+          headers: { authorization: `Bearer ${keys[index]!.token}` },
+        })
+      ).json()
+    expect(await read(0)).toEqual({
+      access: null,
+      legacy: true,
+      routes: TestRoutes.snapshot.routes.length,
+    })
+    // A child can explicitly narrow legacy access without changing another key/environment.
+    await RoutesPolicies.save(db, {
+      scope: { orgId: org.id, environment: 'production', apiKeyId: keys[0]!.id },
+      policy: { access: [] },
+      version: 0,
+    })
+    expect(await read(0)).toEqual({ access: [], legacy: false, routes: 0 })
+    expect(await read(1)).toEqual({
+      access: null,
+      legacy: true,
+      routes: TestRoutes.snapshot.routes.length,
+    })
+    await RoutesPolicies.save(db, {
+      scope: { orgId: org.id, environment: 'sandbox' },
+      policy: {},
+      version: 0,
+    })
+    expect(await read(1)).toEqual({ access: [], legacy: false, routes: 0 })
+  })
+
+  test('enforces key access and organization suspension through composed creation and quote routes', async () => {
+    const db = TestApp.database()
+    const key = {
+      id: 'key_runtime_policy',
+      orgId: 'org_runtime_policy',
+      token: 'secret_runtime_policy',
+      scopes: ['routes:write', 'data:read'],
+    }
+    const scope = { apiKeyId: key.id, orgId: key.orgId, environment: 'production' } as const
+    await Organizations.create(db, { id: key.orgId, name: 'Policy runtime' })
+    await TestRoutes.publish(db)
+    const app = TestApp.create({
+      db,
+      defaultChainId: 4217,
+      auth: { keys: [key] },
+      providers: [Relay.relay()],
+    })
+    const headers = {
+      'Tempo-API-Key': key.token,
+      'Content-Type': 'application/json',
+      'Idempotency-Key': 'policy-request',
+    }
+    const body = {
+      amount: '1000000',
+      sourceChain: 'eip155:8453',
+      sourceToken: 'usdc',
+      destinationToken: 'usdce',
+      recipient: `0x${'11'.repeat(20)}`,
+    }
+    await RoutesPolicies.save(db, { scope, version: 0, policy: { access: [] } })
+    const quote = await app.request(
+      '/v1/routes/quotes?sourceChain=base&sourceToken=usdc&destinationToken=usdce&sourceAmount=1000000',
+      { headers },
+    )
+    expect({ status: quote.status, body: await quote.json() }).toMatchObject({
+      status: 400,
+      body: { error: { code: 'route_unavailable' } },
+    })
+    const denied = await app.request('/v1/routes/deposit-addresses', {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ ...body, refundAddress: `0x${'22'.repeat(20)}` }),
+    })
+    expect({ status: denied.status, body: await denied.json() }).toMatchObject({
+      status: 403,
+      body: { error: { code: 'routes_not_allowed' } },
+    })
+    await RoutesPolicies.save(db, {
+      scope: { orgId: key.orgId, environment: 'production' },
+      version: 0,
+      policy: { suspended: true },
+    })
+    await RoutesPolicies.save(db, { scope, version: 1, policy: { access: null } })
+    const suspended = await app.request('/v1/routes/transfers', {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ ...body, mode: 'exactSource', sender: `0x${'22'.repeat(20)}` }),
+    })
+    expect({ status: suspended.status, body: await suspended.json() }).toMatchObject({
+      status: 403,
+      body: { error: { code: 'routes_suspended' } },
+    })
+  })
+})
+
+function context(keyPolicy: Policy.Overrides): Access.PolicyContext {
+  return {
+    scope: { apiKeyId: 'key_policy', environment: 'production', orgId: 'org_policy' },
+    layers: [{ access: null, subsidyEnabled: true, subsidyRoutes: null }, keyPolicy],
+    legacy: { subsidyEnabled: false, maxAmount: '0', subsidyPayer: 'enterprise' },
+    versions: [1, 2],
+  }
+}

package/src/apps/routes/Access.ts

@@ -1,9 +1,17 @@
 import type { Context } from 'hono'
+import { Value } from 'ox'
 
 import type * as App from '../../App.js'
+import * as Db from '../../db/Db.js'
+import * as ApiKeyAdmissions from '../../db/tables/apiKeyAdmissions.js'
+import * as RoutesPolicies from '../../db/tables/routesPolicies.js'
+import * as RoutesSubsidies from '../../db/tables/routesSubsidies.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import type * as RoutesTransfers from '../../db/tables/routesTransfers.js'
 import * as Auth from '../../internal/Auth.js'
 import * as Response from '../../internal/Response.js'
+import * as Policy from '../../internal/routes/Policy.js'
+import type * as Catalog from '../../internal/routes/Catalog.js'
 
 /** Returns the routes owner encoded by an API-key principal. */
 export function owner(c: Context<App.Environment>): RoutesTransfers.Owner | null {
@@ -24,3 +32,142 @@ export function unauthorized(c: Context<App.Environment>) {
     status: 401,
   })
 }
+
+/** Request-local authoritative policy context. Public quotes have no context. */
+export type PolicyContext = {
+  scope: Policy.Scope
+  layers: Policy.Overrides[]
+  legacy: Policy.Legacy
+  defaultAccess?: null
+  versions: number[]
+}
+
+/** Reads grants from the primary database, never the API-key KV/cache. */
+export async function loadPolicy(c: Context<App.Environment>): Promise<PolicyContext | undefined> {
+  const principal = Auth.getPrincipal(c)
+  if (principal?.type !== 'api_key') return undefined
+  const scope: Policy.Scope = {
+    apiKeyId: principal.id,
+    environment: principal.environment,
+    orgId: principal.orgId,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+  }
+  const loaded = await RoutesPolicies.load(Db.get(c.get('db')), scope)
+  return {
+    scope,
+    ...(loaded.layers[0]?.version === 0 ? { defaultAccess: null } : {}),
+    layers: loaded.layers.map((layer) => layer.policy),
+    legacy: loaded.legacy,
+    versions: loaded.layers.map((layer) => layer.version),
+  }
+}
+
+/** No saved policy in this scope chain: retain the original subsidy/provisioning contract. */
+export function isLegacy(context: PolicyContext): boolean {
+  return context.versions.every((version) => version === 0)
+}
+
+/** Applies independent access and subsidy gates before provider selection. */
+export function filterCatalog(
+  catalog: Catalog.Snapshot,
+  context: PolicyContext,
+  subsidize: boolean,
+): Catalog.Snapshot {
+  if (isLegacy(context)) return catalog
+  const effective = Policy.resolve(context)
+  if (effective.suspended) throw new PolicyError('routes_suspended')
+  if (
+    subsidize &&
+    !catalog.routes.some(
+      (route) => Policy.resolve({ ...context, route: Policy.fromRoute(route) }).subsidyEnabled,
+    )
+  )
+    throw new PolicyError('routes_subsidy_not_enabled')
+  return Policy.filter(catalog, { ...context, subsidize })
+}
+
+/** Checks financial eligibility and pins a platform-bounded expense ceiling. */
+export async function commitment(
+  db: Db.Db,
+  context: PolicyContext,
+  route: Policy.Rule,
+  platformMaxAmount: string,
+): Promise<Policy.Commitment> {
+  const effective = Policy.resolve({ ...context, route })
+  if (effective.suspended) throw new PolicyError('routes_suspended')
+  if (!Policy.allows(effective.access, route)) throw new PolicyError('routes_not_allowed')
+  if (!effective.subsidyEnabled) throw new PolicyError('routes_subsidy_not_enabled')
+  if (!effective.subsidyEligible) throw new PolicyError('routes_subsidy_not_allowed')
+  if (context.scope.environment === 'production' && effective.subsidyPayer === 'enterprise') {
+    const billing = await StripeCustomers.get(db, context.scope.orgId)
+    if (billing?.status === 'past_due') throw new PolicyError('billing_past_due')
+    if (billing?.status !== 'active') throw new PolicyError('billing_required')
+  }
+  const limit = Value.from(effective.maxAmount, 6)
+  const platformLimit = Value.from(platformMaxAmount, 6)
+  return {
+    maxAmount: Value.format(limit < platformLimit ? limit : platformLimit, 6),
+    scope: context.scope,
+    subsidyPayer: effective.subsidyPayer,
+    versions: context.versions,
+  }
+}
+
+/** Serializes acceptance against admin changes; call inside the resource transaction. */
+export async function assertPolicy(db: Db.Db, context: PolicyContext): Promise<void> {
+  await RoutesSubsidies.lockOrganization(db, context.scope.orgId)
+  // Reassignment takes this organization lock even when no key override exists.
+  // Policy versions alone cannot fence requests authenticated under the old owner.
+  if (
+    context.scope.apiKeyId !== undefined &&
+    !(await ApiKeyAdmissions.matches(db, {
+      id: context.scope.apiKeyId,
+      orgId: context.scope.orgId,
+      projectId: context.scope.projectId,
+    }))
+  )
+    throw new PolicyError('route_policy_changed')
+  const current = await RoutesPolicies.load(db, context.scope)
+  if (
+    JSON.stringify(current.layers.map((layer) => layer.version)) !==
+      JSON.stringify(context.versions) ||
+    JSON.stringify(current.legacy) !== JSON.stringify(context.legacy)
+  )
+    throw new PolicyError('route_policy_changed')
+}
+
+/** Emits a bounded denial metric and a customer-safe response. */
+export function policyError(c: Context<App.Environment>, cause: PolicyError) {
+  c.get('metrics')?.count('routes_policy_denial_count', 1, { reason: cause.code })
+  if (cause.code === 'route_policy_changed')
+    return Response.error(c, {
+      code: cause.code,
+      message: messages[cause.code],
+      status: 409,
+    })
+  return Response.error(c, {
+    code: cause.code,
+    message: messages[cause.code],
+    status: 403,
+  })
+}
+
+const messages = {
+  billing_past_due: 'Billing past due.',
+  billing_required:
+    'Active billing is required for enterprise-paid route subsidies. Set up billing for this organization, then retry.',
+  route_policy_changed: 'Route policy changed during creation. Retry the request.',
+  routes_not_allowed: 'This route is not permitted by your access policy.',
+  routes_subsidy_not_allowed: 'This route is not eligible for the requested subsidy.',
+  routes_subsidy_not_enabled:
+    'Route subsidies are not enabled for this request. Contact Tempo to enable them, or use an API key from an organization with subsidies enabled.',
+  routes_suspended: 'New route instructions are suspended for this organization and environment.',
+} as const
+
+/** A policy denial, distinct from provider unavailability. */
+export class PolicyError extends Error {
+  override name = 'Routes.Access.PolicyError'
+  constructor(public code: keyof typeof messages) {
+    super(messages[code])
+  }
+}

package/src/apps/routes/App.ts

@@ -4,8 +4,10 @@ import type * as App from '../../App.js'
 import type * as RoutesDepositAddress from '../../internal/routes/DepositAddress.js'
 import type * as RoutesObservability from '../../internal/routes/Observability.js'
 import type * as RoutesProvider from '../../internal/routes/Provider.js'
+import type * as RoutesSolanaTransferSubsidy from '../../internal/routes/SolanaTransferSubsidy.js'
 import type * as RoutesTransferReconciliation from '../../internal/routes/TransferReconciliation.js'
 import type * as RoutesTransferSubsidy from '../../internal/routes/TransferSubsidy.js'
+import type * as RoutesTronTransferSubsidy from '../../internal/routes/TronTransferSubsidy.js'
 import type * as Webhooks from '../../internal/Webhooks.js'
 import * as Metadata from '../metadata.js'
 import { chains } from './routes/chains.js'
@@ -35,6 +37,10 @@ export function routes(options: routes.Options = {}) {
 export declare namespace routes {
   /** Routes group configuration. */
   type Options = {
+    /** Tempo account available to settle locally subsidized deposits. */
+    depositSubsidyAccount?: string | undefined
+    /** Platform ceiling used when pinning a subsidized deposit-address commitment. */
+    depositSubsidyMaxAmount?: string | undefined
     /** Enqueues one deposit address for asynchronous reconciliation. */
     dispatchDepositReconciliation?:
       | ((message: RoutesProvider.Webhook.receive.Dispatchable) => Promise<void>)
@@ -53,6 +59,10 @@ export declare namespace routes {
       | undefined
     /** Read-only destination subsidy inventory, when settlement is configured. */
     transferSubsidy?: RoutesTransferSubsidy.Inventory | undefined
+    /** Read-only Solana destination subsidy inventory, when settlement is configured. */
+    solanaTransferSubsidy?: RoutesSolanaTransferSubsidy.Inventory | undefined
+    /** Read-only Tron destination subsidy inventory, when settlement is configured. */
+    tronTransferSubsidy?: RoutesTronTransferSubsidy.Inventory | undefined
     /** Registers a created address with a source-chain observer. */
     registerDepositAddress?: ((address: RoutesDepositAddress.Public) => Promise<void>) | undefined
   }

package/src/apps/routes/routes/chains.test.ts

@@ -209,13 +209,13 @@ describe('routes OpenAPI', () => {
           "quotes": {
             "errors": {
               "400": {
-                "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidError",
+                "$ref": "#/components/schemas/ApiKeyMalformedOrQueryInvalidOrRouteUnavailableError",
               },
               "401": {
                 "$ref": "#/components/schemas/AuthenticationError",
               },
               "403": {
-                "$ref": "#/components/schemas/ForbiddenError",
+                "$ref": "#/components/schemas/ApiKeyForbiddenOrApiKeyIpForbiddenOrForbiddenOrRoutesSuspendedError",
               },
               "429": "#/components/responses/RateLimited",
               "500": "#/components/responses/InternalError",
@@ -269,6 +269,7 @@ describe('GET /routes/chains', () => {
       'eip155:56',
       'eip155:8453',
       'eip155:137',
+      'eip155:4217',
       'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
       'tron:0x2b6653dc',
     ])