tapimo 0.7.1 → 0.7.2

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

@@ -0,0 +1,98 @@
+import type { LocalAccount } from 'viem/accounts'
+
+import type * as Auth from '../../../internal/Auth.js'
+import type * as Db from '../../../db/Db.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as Billing from '../../management/Billing.js'
+import type * as Mpp from '../Mpp.js'
+
+/** Resolves the chain declared by a Tempo charge challenge. */
+export function chainId(input: Mpp.RelayInput): number | undefined {
+  const request = input.challenge.request
+  const details = record(request['methodDetails'])
+  return number(details?.['chainId']) ?? number(request['chainId'])
+}
+
+/** Whether a Tempo charge credential requests platform fee sponsorship. */
+export function requiresFeePayer(input: Mpp.RelayInput) {
+  const request = input.challenge.request
+  return record(request['methodDetails'])?.['feePayer'] === true && request['feePayer'] !== false
+}
+
+/** Refuses credentials outside the chains served by this API deployment. */
+export function assertSupportedChain(options: assertSupportedChain.Options) {
+  const { chainId, supportedChainIds } = options
+  if (!supportedChainIds.has(chainId)) throw new UnsupportedChainError(chainId)
+}
+
+export declare namespace assertSupportedChain {
+  /** Chain-selection inputs. */
+  type Options = {
+    /** Resolved credential chain. */
+    chainId: number
+    /** Chains served by this API deployment. */
+    supportedChainIds: ReadonlySet<number>
+  }
+}
+
+/** Authorizes managed fee sponsorship for one broadcast request. */
+export async function authorizeFeePayer(
+  options: authorizeFeePayer.Options,
+): Promise<LocalAccount | undefined> {
+  const { chainId, db, feePayer, input, principal } = options
+  if (!feePayer || !requiresFeePayer(input)) return feePayer
+  if (principal?.type !== 'api_key')
+    throw new PolicyDeniedError('Fee sponsorship requires an API key.')
+  if (!Viem.isMainnet(chainId)) return feePayer
+  if (principal.environment !== 'production')
+    throw new PolicyDeniedError('Mainnet fee sponsorship requires a production API key.')
+
+  const status = await Billing.status(db, principal.orgId)
+  if (status !== 'active')
+    throw new PolicyDeniedError(
+      status === 'past_due'
+        ? 'Billing is past due.'
+        : 'Active billing is required for mainnet fee sponsorship.',
+    )
+  return feePayer
+}
+
+export declare namespace authorizeFeePayer {
+  /** Dependencies used to authorize managed fee sponsorship. */
+  type Options = {
+    /** Credential chain. */
+    chainId: number
+    /** Primary database for authoritative billing enforcement. */
+    db: Db.Db
+    /** Managed fee-payer account, when configured. */
+    feePayer?: LocalAccount | undefined
+    /** MPP credential being broadcast. */
+    input: Mpp.RelayInput
+    /** Authenticated request principal. */
+    principal?: Auth.Principal | undefined
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function number(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined
+}
+
+/** Raised when an MPP credential selects a chain this deployment does not serve. */
+export class UnsupportedChainError extends Error {
+  override name = 'Mpp.Policy.UnsupportedChainError'
+
+  constructor(chainId: number) {
+    super(`Unsupported chain id ${chainId}.`)
+  }
+}
+
+/** Raised when a caller is not eligible for managed fee sponsorship. */
+export class PolicyDeniedError extends Error {
+  override name = 'Mpp.Policy.PolicyDeniedError'
+}

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

@@ -0,0 +1,68 @@
+import * as Store from '../../../internal/Store.js'
+import * as ScreenManager from './ScreenManager.js'
+
+describe('create', () => {
+  test('screens participants concurrently and reuses cached results', async () => {
+    const calls: string[] = []
+    let active = 0
+    let maxActive = 0
+    const manager = ScreenManager.create({
+      chainId: 4217,
+      provider: {
+        async screen({ address }) {
+          active++
+          maxActive = Math.max(maxActive, active)
+          calls.push(address)
+          await Promise.resolve()
+          active--
+          return { allowed: true }
+        },
+      },
+      store: Store.memory(),
+    })
+    const addresses = [`0x${'aa'.repeat(20)}`, `0x${'bb'.repeat(20)}`]
+
+    await manager.screen(addresses)
+    await manager.screen(addresses)
+
+    expect(calls).toEqual(addresses)
+    expect(maxActive).toBe(2)
+  })
+
+  test('rejects a payment when any participant fails screening', async () => {
+    const manager = ScreenManager.create({
+      chainId: 4217,
+      provider: {
+        async screen() {
+          return { allowed: false }
+        },
+      },
+      store: Store.memory(),
+    })
+
+    await expect(manager.screen([`0x${'aa'.repeat(20)}`])).rejects.toThrow(
+      ScreenManager.RejectedError,
+    )
+  })
+
+  test('uses the configured cache lifetime', async () => {
+    let calls = 0
+    const manager = ScreenManager.create({
+      chainId: 4217,
+      provider: {
+        async screen() {
+          calls++
+          return { allowed: true }
+        },
+      },
+      store: Store.memory(),
+      ttl: 0,
+    })
+    const addresses = [`0x${'aa'.repeat(20)}`]
+
+    await manager.screen(addresses)
+    await manager.screen(addresses)
+
+    expect(calls).toBe(2)
+  })
+})

package/src/apps/mpp/internal/ScreenManager.ts

@@ -0,0 +1,41 @@
+import * as Store from '../../../internal/Store.js'
+import * as Screening from './Screening.js'
+
+/** Coordinates concurrent cached screening before credential processing. */
+export type Manager = {
+  /** Rejects when any payment participant fails screening. */
+  screen(addresses: readonly string[]): Promise<void>
+}
+
+/** Creates a cached address-screening manager. */
+export function create(options: create.Options): Manager {
+  const { chainId, provider = Screening.allowAll, store, ttl = Screening.defaultTtl } = options
+
+  return {
+    async screen(addresses) {
+      const results = await Promise.all(
+        addresses.map((address) => Screening.screen({ address, chainId, provider, store, ttl })),
+      )
+      if (results.some((result) => !result.allowed)) throw new RejectedError()
+    },
+  }
+}
+
+export declare namespace create {
+  /** Dependencies for cached address screening. */
+  type Options = {
+    /** Tempo chain that owns the screened addresses. */
+    chainId: number
+    /** Address-screening provider. */
+    provider?: Screening.Provider | undefined
+    /** Cache used for screening results. */
+    store: Store.Store
+    /** Cache duration. @default `Ttl.days(1)` */
+    ttl?: number | undefined
+  }
+}
+
+/** Indicates that an address-screening provider rejected a participant. */
+export class RejectedError extends Error {
+  override name = 'Mpp.ScreenManager.RejectedError'
+}

package/src/apps/mpp/internal/Screening.ts

@@ -1,10 +1,47 @@
-/** Future address-screening result. */
+import * as Store from '../../../internal/Store.js'
+import * as Ttl from '../../../internal/Ttl.js'
+
+/** Address-screening result. */
 export type Result = { allowed: boolean }
 
-/** Future address-screening provider. */
+/** Address-screening provider. */
 export type Provider = {
   /** Screens one normalized account address on a Tempo chain. */
   screen(options: { address: string; chainId: number }): Promise<Result>
 }
 
-// TODO(mppx#597): add concurrent cached Chainalysis screening behind this provider.
+/** Allows every address while the external screening provider is unconfigured. */
+export const allowAll: Provider = {
+  async screen() {
+    return { allowed: true }
+  },
+}
+
+/** Screens one address, caching the provider result by chain and normalized address. */
+export async function screen(options: screen.Options): Promise<Result> {
+  const { address, chainId, provider, store, ttl = defaultTtl } = options
+  return Store.memoize(() => provider.screen({ address, chainId }), {
+    key: `mpp:screen:v1:${chainId}:${address.toLowerCase()}`,
+    store,
+    ttl,
+  })
+}
+
+export declare namespace screen {
+  /** Dependencies used to screen an address. */
+  type Options = {
+    /** Normalized account address. */
+    address: string
+    /** Tempo chain identifier. */
+    chainId: number
+    /** Address-screening provider. */
+    provider: Provider
+    /** Cache used for provider results. */
+    store: Store.Store
+    /** Cache duration. @default `Ttl.days(1)` */
+    ttl?: number | undefined
+  }
+}
+
+/** Default address-screening cache lifetime (24 hours). */
+export const defaultTtl = Ttl.days(1)

package/src/apps/mpp/internal/Sponsorship.ts

@@ -0,0 +1,144 @@
+import { Hash } from 'ox'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import type { LocalAccount } from 'viem/accounts'
+import { TokenId, Transaction } from 'viem/tempo'
+
+import type * as Auth from '../../../internal/Auth.js'
+import * as BillingSettings from '../../../db/tables/billingSettings.js'
+import type * as Db from '../../../db/Db.js'
+import * as SponsoredTransactions from '../../../db/tables/sponsoredTransactions.js'
+import * as Fees from '../../../internal/Fees.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as Billing from '../../management/Billing.js'
+import * as Policy from './Policy.js'
+
+/** Wraps a managed fee payer to record its signed transaction before broadcast. */
+export function decorate(options: decorate.Options): LocalAccount {
+  const { account, onSigned } = options
+  const signTransaction = account.signTransaction.bind(account)
+
+  return new Proxy(account, {
+    get(target, property, receiver) {
+      if (property !== 'signTransaction') return Reflect.get(target, property, receiver)
+      return async (...parameters: Parameters<LocalAccount['signTransaction']>) => {
+        const serializedTransaction = await signTransaction(...parameters)
+        await onSigned({ serializedTransaction })
+        return serializedTransaction
+      }
+    },
+  }) as LocalAccount
+}
+
+export declare namespace decorate {
+  /** Dependencies used to record one MPP-sponsored transaction. */
+  type Options = {
+    /** Account that MPPX uses to add the fee-payer signature. */
+    account: LocalAccount
+    /** Records the signed transaction before it can reach the network. */
+    onSigned: (options: { serializedTransaction: `0x${string}` }) => Promise<void>
+  }
+}
+
+type SponsoredTransaction = {
+  chainId?: unknown
+  feeToken?: unknown
+  from?: `0x${string}` | undefined
+  gas?: unknown
+  maxFeePerGas?: unknown
+}
+
+/** Records a sponsorship and atomically enforces its billing limits. */
+export async function record(options: record.Options): Promise<void> {
+  const { db, dbCached, principal, serializedTransaction, txFeeLimit } = options
+  const transaction = Transaction.deserialize(serializedTransaction) as SponsoredTransaction
+  if (!transaction.from)
+    throw new Policy.PolicyDeniedError('Fee-sponsored transaction must declare a sender.')
+  if (typeof transaction.chainId !== 'number')
+    throw new Policy.PolicyDeniedError('Fee-sponsored transaction must declare a chain id.')
+  const chainId = transaction.chainId
+  const feeMax = Fees.maxOf(transaction)
+  if (feeMax === undefined)
+    throw new Policy.PolicyDeniedError('Fee-sponsored transaction must declare a fee limit.')
+
+  const feeToken = (() => {
+    try {
+      return transaction.feeToken === undefined
+        ? undefined
+        : TokenId.toAddress(transaction.feeToken as never)
+    } catch {
+      throw new Policy.PolicyDeniedError('Fee-sponsored transaction uses an invalid fee token.')
+    }
+  })()
+  const mainnet = Viem.isMainnet(chainId)
+  const settings = mainnet ? await BillingSettings.get(db, principal.orgId) : undefined
+
+  let currency: string | undefined
+  if (mainnet) {
+    const verified = feeToken
+      ? (await VerifiedTokens.read(dbCached, chainId))?.byAddress.get(feeToken.toLowerCase())
+      : undefined
+    if (
+      !verified ||
+      verified.currency.toLowerCase() !== 'usd' ||
+      verified.decimals !== Fees.tokenDecimals
+    )
+      throw new Policy.PolicyDeniedError('Fee-sponsored transaction uses an unsupported fee token.')
+    currency = verified.currency.toLowerCase()
+
+    const cap = (() => {
+      if (settings?.txFeeLimit == null) return txFeeLimit
+      const org = Billing.toBaseUnits(settings.txFeeLimit)
+      return org < txFeeLimit ? org : txFeeLimit
+    })()
+    if (feeMax > cap) throw new Policy.PolicyDeniedError('Transaction fee limit exceeded.')
+  }
+
+  const envelope = TxEnvelopeTempo.deserialize(serializedTransaction as TxEnvelopeTempo.Serialized)
+  const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(envelope, { sender: transaction.from })
+  const input = {
+    apiKeyId: principal.id,
+    billable: mainnet && principal.environment === 'production',
+    chainId,
+    ...(currency ? { currency } : {}),
+    environment: principal.environment,
+    feeMax: feeMax.toString(),
+    ...(feeToken ? { feeToken } : {}),
+    orgId: principal.orgId,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+    signPayload,
+    transaction: serializedTransaction,
+    transactionHash: Hash.keccak256(serializedTransaction),
+  }
+  if (settings?.spendLimit == null) {
+    await SponsoredTransactions.upsert(db, input)
+    return
+  }
+  try {
+    await SponsoredTransactions.reserve(db, input, {
+      chainIds: [Viem.chainId.mainnet],
+      max: Billing.toBaseUnits(settings.spendLimit),
+      since: Billing.periodStart(settings.period),
+    })
+  } catch (cause) {
+    if (cause instanceof SponsoredTransactions.PeriodSpendLimitError)
+      throw new Policy.PolicyDeniedError('Spend limit exceeded.')
+    throw cause
+  }
+}
+
+export declare namespace record {
+  /** Dependencies used to persist one MPP sponsorship. */
+  type Options = {
+    /** Primary database for billing enforcement and sponsorship state. */
+    db: Db.Db
+    /** Cached database used for verified-token reads. */
+    dbCached: Db.Db
+    /** API key that requested sponsorship. */
+    principal: Extract<Auth.Principal, { type: 'api_key' }>
+    /** Final fee-payer-signed transaction, before broadcast. */
+    serializedTransaction: `0x${string}`
+    /** Platform per-transaction cap in fee-token base units. */
+    txFeeLimit: bigint
+  }
+}

package/src/apps/mpp/internal/Utils.ts

@@ -0,0 +1,30 @@
+import * as Mppx from 'mppx'
+
+import * as Store from '../../../internal/Store.js'
+
+/** Returns the normalized Tempo sender and recipients in a validated credential. */
+export function addresses(result: Awaited<ReturnType<typeof Mppx.Method.validateCredential>>) {
+  const details = result.details as {
+    sender?: string
+    transfers?: readonly { recipient: string }[]
+  }
+  return [details.sender, ...(details.transfers?.map(({ recipient }) => recipient) ?? [])]
+    .filter((address): address is string => address !== undefined)
+    .map((address) => address.toLowerCase())
+    .filter((address, index, values) => values.indexOf(address) === index)
+}
+
+/** Adapts Tempo API durable state to MPPX's atomic Cloudflare store contract. */
+export function mppxStore(state: Store.State): Mppx.Store.AtomicStore {
+  return Mppx.Store.cloudflare({
+    delete: (key) => state.delete(key),
+    get: (key) => state.get(key),
+    put: (key, value) => state.put(key, value),
+    update: (key, change) =>
+      Store.change(state, key, (current) => {
+        const next = change(current)
+        // MPPX's Cloudflare adapter represents a missing value with JSON null.
+        return next.op === 'delete' ? { ...next, op: 'set', value: 'null' as const } : next
+      }),
+  })
+}