tapimo 0.15.1 → 0.18.1

package/src/apps/relay/Sponsorships.ts

@@ -53,7 +53,9 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
     // here only the TTL can settle them.
     if (row.transactionHash === null) {
       if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
-        await SponsoredTransactions.fail(db, row.id, now().toISOString())
+        await SponsoredTransactions.fail(db, row.id, now().toISOString(), {
+          transactionHash: row.transactionHash,
+        })
         result.failed++
       } else result.pending++
       continue
@@ -70,7 +72,9 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
       else {
         result.errors++
         if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
-          await SponsoredTransactions.fail(db, row.id, now().toISOString())
+          await SponsoredTransactions.fail(db, row.id, now().toISOString(), {
+            transactionHash: row.transactionHash,
+          })
           result.failed++
         } else result.pending++
         continue
@@ -83,10 +87,13 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
       await SponsoredTransactions.finalize(db, row.id, {
         feeAmount: feeAmount.toString(),
         finalizedAt: now().toISOString(),
+        transactionHash: row.transactionHash,
       })
       result.finalized++
     } else if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
-      await SponsoredTransactions.fail(db, row.id, now().toISOString())
+      await SponsoredTransactions.fail(db, row.id, now().toISOString(), {
+        transactionHash: row.transactionHash,
+      })
       result.failed++
     } else result.pending++
   }
@@ -123,11 +130,9 @@ export declare namespace finalize {
 }
 
 /**
- * Runs one reconciliation pass over pending fill intents (rows with no
- * transaction hash): fetches the fee payer's recent on-chain transactions
- * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
- * matching intents' hashes so the receipt pass can finalize them. Query or
- * candidate errors leave intents for the next pass.
+ * Reconciles pending fill intents and recently failed sponsorships against
+ * on-chain fee-payer sign payloads. Matches update their transaction hashes;
+ * errors leave sponsorships for the next pass.
  *
  * @param db - The database holding `sponsored_transactions`.
  * @param options - Reconciliation options.
@@ -147,74 +152,80 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
   const failedSince = new Date(Date.now() - failedIntentTtlMs).toISOString()
   // Old failed intents must not move the active scan behind its candidate cap.
   const [intents, recoveryWindows] = await Promise.all([
-    SponsoredTransactions.listIntents(db, { limit: batchSize }),
+    SponsoredTransactions.listReconciliationCandidates(db, { limit: batchSize }),
     SponsoredTransactions.listRecoveryWindows(db, { failedSince }),
   ])
   const result = { errors: 0, matched: 0, scanned: 0 }
   if (intents.length === 0 && recoveryWindows.length === 0) return result
 
-  const groups = new Map<number, SponsoredTransactions.Record[]>()
-  for (const intent of intents)
-    groups.set(intent.chainId, [...(groups.get(intent.chainId) ?? []), intent])
+  const groups = [
+    new Map<number, SponsoredTransactions.Record[]>(),
+    new Map<number, SponsoredTransactions.Record[]>(),
+  ]
+  for (const intent of intents) {
+    const group = groups[intent.transactionHash === null ? 0 : 1]!
+    group.set(intent.chainId, [...(group.get(intent.chainId) ?? []), intent])
+  }
 
-  for (const [chainId, rows] of groups) {
-    if (candidateCap <= 0) continue
-    const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]))
-    const since = formatTidxTimestamp(
-      Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs,
-    )
+  for (const group of groups)
+    for (const [chainId, rows] of group) {
+      if (candidateCap <= 0) continue
+      const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]))
+      const since = formatTidxTimestamp(
+        Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs,
+      )
 
-    let candidates: readonly globalThis.Record<string, unknown>[]
-    try {
-      // Dynamic filter values; the tidx client's query type wants literals.
-      const fetched = await getTidx(chainId).fetch({
-        chainId,
-        query:
-          `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}` as string,
-      })
-      candidates = fetched.rows
-    } catch {
-      // Indexer outage must not fail intents; retry on the next pass.
-      result.errors++
-      continue
-    }
-
-    for (const candidate of candidates) {
-      if (bySignPayload.size === 0) break
-      const hash = candidate['hash'] as Hex.Hex | undefined
-      const sender = candidate['from'] as Address | undefined
-      if (!hash || !sender) continue
-      result.scanned++
+      let candidates: readonly globalThis.Record<string, unknown>[]
       try {
-        const serialized = await getRawTransaction(getClient(chainId), hash)
-        if (!serialized) {
-          result.errors++
-          continue
+        // Dynamic filter values; the tidx client's query type wants literals.
+        const fetched = await getTidx(chainId).fetch({
+          chainId,
+          query:
+            `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}` as string,
+        })
+        candidates = fetched.rows
+      } catch {
+        // Indexer outage must not fail sponsorships; retry on the next pass.
+        result.errors++
+        continue
+      }
+
+      for (const candidate of candidates) {
+        if (bySignPayload.size === 0) break
+        const hash = candidate['hash'] as Hex.Hex | undefined
+        const sender = candidate['from'] as Address | undefined
+        if (!hash || !sender) continue
+        result.scanned++
+        try {
+          const serialized = await getRawTransaction(getClient(chainId), hash)
+          if (!serialized) {
+            result.errors++
+            continue
+          }
+          if (!serialized.startsWith(TxEnvelopeTempo.serializedType)) continue
+          const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(
+            TxEnvelopeTempo.deserialize(serialized as TxEnvelopeTempo.Serialized),
+            { sender },
+          )
+          const intent = bySignPayload.get(signPayload)
+          if (!intent) continue
+          await SponsoredTransactions.assignTransactionHash(
+            db,
+            intent.id,
+            hash,
+            await options.limitFor?.(intent),
+          )
+          bySignPayload.delete(signPayload)
+          result.matched++
+        } catch (error) {
+          // Spend-limit enforcement is an expected policy refusal; dependency,
+          // lookup, and malformed-envelope failures remain operational errors.
+          if (!(error instanceof SponsoredTransactions.PeriodSpendLimitError)) result.errors++
         }
-        if (!serialized.startsWith(TxEnvelopeTempo.serializedType)) continue
-        const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(
-          TxEnvelopeTempo.deserialize(serialized as TxEnvelopeTempo.Serialized),
-          { sender },
-        )
-        const intent = bySignPayload.get(signPayload)
-        if (!intent) continue
-        await SponsoredTransactions.assignTransactionHash(
-          db,
-          intent.id,
-          hash,
-          await options.limitFor?.(intent),
-        )
-        bySignPayload.delete(signPayload)
-        result.matched++
-      } catch (error) {
-        // Spend-limit enforcement is an expected policy refusal; dependency,
-        // lookup, and malformed-envelope failures remain operational errors.
-        if (!(error instanceof SponsoredTransactions.PeriodSpendLimitError)) result.errors++
       }
+      // A truncated active scan cannot prove that the remaining sponsorships were never mined.
+      if (candidates.length === candidateCap && bySignPayload.size > 0) result.errors++
     }
-    // A truncated active scan cannot prove that the remaining intents were never mined.
-    if (candidates.length === candidateCap && bySignPayload.size > 0) result.errors++
-  }
 
   const feePayer_lower = feePayer.toLowerCase() as Address
   for (const window of recoveryWindows) {
@@ -353,7 +364,7 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
 export declare namespace reconcile {
   /** Options for {@link reconcile}. */
   type Options = {
-    /** Maximum active intents considered per pass. @default 100 */
+    /** Maximum pending sponsorships per transaction-hash state considered per pass. @default 100 */
     batchSize?: number | undefined
     /** Maximum candidates per chain in each active or recovery scan. @default 500 */
     candidateCap?: number | undefined

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])
+  }
+}