@routedock/routedock 0.1.0

package/src/client/MppChargeClient.ts

@@ -0,0 +1,44 @@
+import { Keypair } from '@stellar/stellar-sdk'
+import { stellar } from '@stellar/mpp/charge/client'
+import { Mppx } from 'mppx/client'
+import type { RouteDockManifest, PaymentResult } from '../types.js'
+import { RouteDockManifestError } from '../types.js'
+
+export class MppChargeClient {
+  constructor(
+    private readonly keypair: Keypair,
+    private readonly network: 'testnet' | 'mainnet',
+  ) {}
+
+  async pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult> {
+    const pricing = manifest.pricing['mpp-charge']
+    if (!pricing) {
+      throw new RouteDockManifestError('manifest.pricing.mpp-charge missing')
+    }
+
+    let txHash: string | null = null
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        stellar.charge({
+          keypair: this.keypair,
+          mode: 'pull',
+          onProgress(event) {
+            if (event.type === 'paid') {
+              txHash = event.hash
+            }
+          },
+        }),
+      ],
+    })
+
+    const response = await mppx.fetch(url)
+    if (!response.ok) {
+      throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`)
+    }
+
+    const data = await response.json()
+    return { data, txHash, mode: 'mpp-charge', amount: pricing.amount, timestamp: Date.now() }
+  }
+}

package/src/client/MppSessionClient.ts

@@ -0,0 +1,144 @@
+/**
+ * MppSessionClient — uses @stellar/mpp channel/client for off-chain
+ * cumulative commitments against a pre-deployed one-way-channel contract.
+ *
+ * The channel is deployed and funded before the agent runs. The client
+ * signs ed25519 commitments per the one-way-channel protocol — the
+ * @stellar/mpp library handles the 402 challenge-response cycle.
+ */
+import { Keypair } from '@stellar/stellar-sdk'
+import { stellar } from '@stellar/mpp/channel/client'
+import { Mppx } from 'mppx/client'
+import type {
+  RouteDockManifest,
+  SessionHandle,
+  SessionCloseResult,
+} from '../types.js'
+import {
+  RouteDockManifestError,
+  RouteDockSessionError,
+} from '../types.js'
+
+const MIN_REFUND_WAITING_PERIOD = 17_280
+
+export class MppSessionClient {
+  constructor(
+    private readonly keypair: Keypair,
+    private readonly network: 'testnet' | 'mainnet',
+  ) {}
+
+  async openSession(
+    url: string,
+    manifest: RouteDockManifest,
+    commitmentSecret: string,
+  ): Promise<SessionHandle> {
+    const pricing = manifest.pricing['mpp-session']
+    if (!pricing) {
+      throw new RouteDockManifestError('manifest.pricing.mpp-session missing')
+    }
+
+    const refundPeriod = pricing.refund_waiting_period_ledgers
+    if (refundPeriod < MIN_REFUND_WAITING_PERIOD) {
+      throw new RouteDockManifestError(
+        `refund_waiting_period_ledgers ${refundPeriod} < minimum ${MIN_REFUND_WAITING_PERIOD}`,
+      )
+    }
+
+    const commitmentKey = Keypair.fromSecret(commitmentSecret)
+    const channelContract = pricing.channel_contract
+    const agentPublicKey = this.keypair.publicKey()
+
+    let currentCumulative = 0n
+    let vouchersIssued = 0
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        stellar.channel({
+          commitmentKey,
+          sourceAccount: this.keypair.publicKey(),
+          onProgress(event) {
+            if (event.type === 'signed') {
+              currentCumulative = BigInt(event.cumulativeAmount)
+            }
+          },
+        }),
+      ],
+    })
+
+    const openTxHash = channelContract
+
+    const handle: SessionHandle = {
+      channelId: channelContract,
+      openTxHash,
+
+      async *stream(): AsyncIterable<unknown> {
+        while (true) {
+          let resp: globalThis.Response | null = null
+          for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+              resp = await mppx.fetch(url)
+              if (resp.ok) break
+              resp = null
+            } catch {
+              if (attempt === 2) throw new RouteDockSessionError('Voucher request failed after 3 retries')
+              await new Promise(r => setTimeout(r, 1000 * (attempt + 1)))
+            }
+          }
+          if (!resp || !resp.ok) {
+            throw new RouteDockSessionError(`Voucher request failed: HTTP ${resp?.status ?? 'unknown'}`)
+          }
+          vouchersIssued++
+          yield await resp.json()
+        }
+      },
+
+      async close(): Promise<SessionCloseResult> {
+        const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk')
+        const rpcUrl = 'https://soroban-testnet.stellar.org'
+        const server = new rpcMod.Server(rpcUrl)
+        const contract = new Contract(channelContract)
+        const passphrase = 'Test SDF Network ; September 2015'
+
+        const account = await server.getAccount(agentPublicKey)
+        const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase })
+          .addOperation(contract.call('prepare_commitment', nativeToScVal(currentCumulative, { type: 'i128' })))
+          .setTimeout(30)
+          .build()
+        const simResult = await server.simulateTransaction(simTx)
+        if (rpcMod.Api.isSimulationError(simResult)) {
+          throw new RouteDockSessionError(`prepare_commitment simulation failed: ${simResult.error}`)
+        }
+        const commitmentBytes = (simResult as { result?: { retval?: { bytes: () => Buffer } } }).result?.retval?.bytes()
+        if (!commitmentBytes) throw new RouteDockSessionError('prepare_commitment returned no bytes')
+
+        const signature = commitmentKey.sign(Buffer.from(commitmentBytes))
+
+        const closeResp = await fetch(url, {
+          method: 'DELETE',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            amount: currentCumulative.toString(),
+            signature: Buffer.from(signature).toString('hex'),
+          }),
+        })
+
+        if (!closeResp.ok) {
+          throw new RouteDockSessionError(`Channel close failed: HTTP ${closeResp.status}`)
+        }
+
+        const closeData = (await closeResp.json()) as { closeTxHash?: string }
+        const closeTxHash = closeData.closeTxHash ?? null
+
+        if (!closeTxHash) {
+          throw new RouteDockSessionError('Channel close response missing closeTxHash')
+        }
+
+        const totalPaid = (Number(currentCumulative) / 1e7).toFixed(7)
+        return { closeTxHash, totalPaid, vouchersIssued }
+      },
+    }
+
+    return handle
+  }
+}

package/src/client/RouteDockClient.ts

@@ -0,0 +1,124 @@
+import { Keypair } from '@stellar/stellar-sdk'
+import { fetchManifest, selectMode, type ModeSelectOptions } from './ModeRouter.js'
+import { X402Client } from './x402Client.js'
+import { MppChargeClient } from './MppChargeClient.js'
+import { MppSessionClient } from './MppSessionClient.js'
+import type { PaymentResult, SessionHandle } from '../types.js'
+import {
+  RouteDockManifestError,
+  RouteDockPolicyRejectedError,
+} from '../types.js'
+
+export interface SpendCap {
+  /** Maximum total USDC spend per day (decimal string, e.g. "1.00") */
+  daily: string
+  asset: 'USDC'
+}
+
+export interface RouteDockClientConfig {
+  /** Stellar keypair or raw secret key (S...) */
+  wallet: Keypair | string
+  network: 'testnet' | 'mainnet'
+  /** Optional local daily spend cap — checked before every payment */
+  spendCap?: SpendCap
+  /** Ed25519 secret key (S...) for signing channel commitments. Required for mpp-session. */
+  commitmentSecret?: string | undefined
+}
+
+export class RouteDockClient {
+  private readonly keypair: Keypair
+  private readonly network: 'testnet' | 'mainnet'
+  private readonly spendCap: SpendCap | undefined
+  private readonly commitmentSecret: string | undefined
+
+  /** Local daily accumulator keyed by YYYY-MM-DD */
+  private dailySpend: { date: string; total: number } = { date: '', total: 0 }
+
+  private readonly x402: X402Client
+  private readonly charge: MppChargeClient
+  private readonly session: MppSessionClient
+
+  constructor(config: RouteDockClientConfig) {
+    this.keypair =
+      typeof config.wallet === 'string' ? Keypair.fromSecret(config.wallet) : config.wallet
+    this.network = config.network
+    this.spendCap = config.spendCap
+    this.commitmentSecret = config.commitmentSecret
+
+    const secretKey = this.keypair.secret()
+    this.x402 = new X402Client(secretKey, this.network)
+    this.charge = new MppChargeClient(this.keypair, this.network)
+    this.session = new MppSessionClient(this.keypair, this.network)
+  }
+
+  /**
+   * Pay for one request at `url`. Fetches manifest, selects payment mode,
+   * checks local spend cap, executes payment, returns result.
+   */
+  async pay(url: string, options?: ModeSelectOptions): Promise<PaymentResult> {
+    const baseUrl = new URL(url).origin
+    const manifest = await fetchManifest(baseUrl)
+    const mode = selectMode(manifest, options)
+
+    let result: PaymentResult
+
+    switch (mode) {
+      case 'x402':
+        result = await this.x402.pay(url, manifest)
+        break
+      case 'mpp-charge':
+        result = await this.charge.pay(url, manifest)
+        break
+      case 'mpp-session':
+        throw new RouteDockManifestError(
+          'Use client.openSession() for mpp-session mode — client.pay() only handles discrete payments',
+        )
+      default:
+        throw new RouteDockManifestError(`Unknown payment mode: ${mode as string}`)
+    }
+
+    this._checkAndRecordSpend(result.amount)
+    return result
+  }
+
+  /**
+   * Open a sustained MPP session at `url`. Verifies mpp-session is supported
+   * before opening a channel. Returns a SessionHandle for streaming + closing.
+   */
+  async openSession(url: string): Promise<SessionHandle> {
+    const baseUrl = new URL(url).origin
+    const manifest = await fetchManifest(baseUrl)
+
+    if (!manifest.modes.includes('mpp-session')) {
+      throw new RouteDockManifestError(
+        `Provider at ${baseUrl} does not support mpp-session mode`,
+      )
+    }
+
+    if (!this.commitmentSecret) {
+      throw new RouteDockManifestError(
+        'commitmentSecret is required in RouteDockClientConfig for mpp-session mode',
+      )
+    }
+
+    return this.session.openSession(url, manifest, this.commitmentSecret)
+  }
+
+  /** Check local daily cap and record the spend. Throws if cap exceeded. */
+  private _checkAndRecordSpend(amount: string): void {
+    if (!this.spendCap) return
+
+    const today = new Date().toISOString().slice(0, 10)
+    if (this.dailySpend.date !== today) {
+      this.dailySpend = { date: today, total: 0 }
+    }
+
+    const amountNum = parseFloat(amount)
+    const capNum = parseFloat(this.spendCap.daily)
+    if (this.dailySpend.total + amountNum > capNum) {
+      throw new RouteDockPolicyRejectedError('local_daily_cap_exceeded')
+    }
+
+    this.dailySpend.total += amountNum
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,8 @@
+// Client-only exports (no provider/Express)
+export * from '../types.js'
+export * from './RouteDockClient.js'
+export * from './ModeRouter.js'
+export * from './x402Client.js'
+export * from './MppChargeClient.js'
+export * from './MppSessionClient.js'
+export * from '../store/SessionStore.js'

package/src/client/x402Client.ts

@@ -0,0 +1,84 @@
+import { createEd25519Signer } from '@x402/stellar'
+import { ExactStellarScheme } from '@x402/stellar/exact/client'
+import { x402Client, x402HTTPClient } from '@x402/core/client'
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentResponseHeader,
+  encodePaymentSignatureHeader,
+} from '@x402/core/http'
+import type { Network as X402Network } from '@x402/core/types'
+import type { RouteDockManifest, PaymentResult } from '../types.js'
+import { RouteDockManifestError } from '../types.js'
+
+type Network = 'testnet' | 'mainnet'
+
+const CAIP2: Record<Network, X402Network> = {
+  testnet: 'stellar:testnet',
+  mainnet: 'stellar:pubnet',
+}
+
+export class X402Client {
+  private readonly httpClient: x402HTTPClient
+
+  constructor(
+    private readonly secretKey: string,
+    private readonly network: Network,
+  ) {
+    const caip2 = CAIP2[network]
+    const signer = createEd25519Signer(secretKey, caip2)
+    const scheme = new ExactStellarScheme(signer)
+    const core = new x402Client()
+    core.register(caip2, scheme)
+    this.httpClient = new x402HTTPClient(core)
+  }
+
+  async pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult> {
+    const pricing = manifest.pricing.x402
+    if (!pricing) {
+      throw new RouteDockManifestError('manifest.pricing.x402 missing')
+    }
+    if (!pricing.facilitator) {
+      throw new RouteDockManifestError('manifest.pricing.x402.facilitator missing')
+    }
+
+    // Initial request — expect 402. Include mode hint so middleware routes correctly.
+    const init = await fetch(url, { headers: { 'X-Preferred-Mode': 'x402' } })
+    if (init.status !== 402) {
+      const data = await init.json()
+      return { data, txHash: null, mode: 'x402', amount: pricing.amount, timestamp: Date.now() }
+    }
+
+    // Parse payment requirements from header
+    const reqHeader = init.headers.get('X-Payment-Requirements')
+    if (!reqHeader) {
+      throw new RouteDockManifestError('402 response missing X-Payment-Requirements header')
+    }
+
+    const paymentRequired = decodePaymentRequiredHeader(reqHeader)
+
+    // Build signed payment payload
+    const paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired)
+    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload)
+
+    // Re-request with payment
+    const settled = await fetch(url, { headers: paymentHeaders })
+    if (!settled.ok) {
+      throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`)
+    }
+
+    // Extract settlement tx hash from response header
+    let txHash: string | null = null
+    const responseHeader = settled.headers.get('X-Payment-Response')
+    if (responseHeader) {
+      try {
+        const settleResponse = decodePaymentResponseHeader(responseHeader)
+        txHash = (settleResponse as { transaction?: string }).transaction ?? null
+      } catch {
+        // non-fatal — some facilitators may omit the response header
+      }
+    }
+
+    const data = await settled.json()
+    return { data, txHash, mode: 'x402', amount: pricing.amount, timestamp: Date.now() }
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// Full SDK — types, client, provider, store
+export * from './types.js'
+export * from './client/RouteDockClient.js'
+export * from './client/ModeRouter.js'
+export * from './client/x402Client.js'
+export * from './client/MppChargeClient.js'
+export * from './client/MppSessionClient.js'
+export * from './store/SessionStore.js'
+export * from './provider/routedockMiddleware.js'

package/src/provider/MppChargeHandler.ts

@@ -0,0 +1,90 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express'
+import { stellar } from '@stellar/mpp/charge/server'
+import { Mppx, Request as MppxRequest } from 'mppx/server'
+import type { RouteDockManifest } from '../types.js'
+import type { SessionStore } from '../store/SessionStore.js'
+
+type Network = 'testnet' | 'mainnet'
+
+const MPP_NETWORK: Record<Network, 'stellar:testnet' | 'stellar:pubnet'> = {
+  testnet: 'stellar:testnet',
+  mainnet: 'stellar:pubnet',
+}
+
+export interface MppChargeHandlerOptions {
+  payeeSecretKey: string
+  network: Network
+  amount: string
+  assetContract: string
+  manifest: RouteDockManifest
+  store?: SessionStore
+  onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>
+}
+
+export function createMppChargeHandler(opts: MppChargeHandlerOptions): RequestHandler {
+  const networkId = MPP_NETWORK[opts.network]
+  const amountHumanReadable = opts.amount
+
+  const mppx = Mppx.create({
+    secretKey: opts.payeeSecretKey,
+    methods: [
+      stellar.charge({
+        recipient: opts.manifest.payee,
+        currency: opts.assetContract,
+        network: networkId,
+        feePayer: { envelopeSigner: opts.payeeSecretKey },
+      }),
+    ],
+  })
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      const fetchReq = MppxRequest.fromNodeListener(req, res)
+      // `mppx['stellar/charge']` — method key is `name/intent`
+      const handler = (
+        mppx as unknown as {
+          'stellar/charge': (
+            opts: { amount: string; currency: string; recipient: string; description?: string },
+          ) => (input: globalThis.Request) => Promise<{ status: 402 | 200; challenge?: globalThis.Response; withReceipt?: (r: globalThis.Response) => globalThis.Response }>
+        }
+      )['stellar/charge']
+      const result = await handler({
+        amount: amountHumanReadable,
+        currency: opts.assetContract,
+        recipient: opts.manifest.payee,
+        description: opts.manifest.name,
+      })(fetchReq)
+
+      if (result.status === 402) {
+        const challenge = result.challenge!
+        res.status(402)
+        challenge.headers.forEach((v: string, k: string) => res.setHeader(k, v))
+        res.send(await challenge.text())
+        return
+      }
+
+      // status 200 — payment verified
+      const receipt = result.withReceipt!(new Response(''))
+      receipt.headers.forEach((v: string, k: string) => res.setHeader(k, v))
+
+      // Extract tx hash from receipt headers if available
+      const receiptHeader = receipt.headers.get('payment-receipt')
+      if (receiptHeader && opts.onSettled) {
+        try {
+          const parsed = JSON.parse(
+            Buffer.from(receiptHeader, 'base64').toString('utf8'),
+          ) as { reference?: string }
+          if (parsed.reference) {
+            await opts.onSettled(parsed.reference, opts.amount, 'mpp-charge')
+          }
+        } catch {
+          // non-fatal
+        }
+      }
+
+      next()
+    } catch (err) {
+      next(err)
+    }
+  }
+}

package/src/provider/MppSessionHandler.ts

@@ -0,0 +1,136 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express'
+import { Keypair } from '@stellar/stellar-sdk'
+import { stellar, close as channelClose, Store } from '@stellar/mpp/channel/server'
+import { Mppx, Request as MppxRequest } from 'mppx/server'
+import type { RouteDockManifest } from '../types.js'
+
+type Network = 'testnet' | 'mainnet'
+
+const MPP_NETWORK: Record<Network, 'stellar:testnet' | 'stellar:pubnet'> = {
+  testnet: 'stellar:testnet',
+  mainnet: 'stellar:pubnet',
+}
+
+export interface MppSessionHandlerOptions {
+  payeeSecretKey: string
+  network: Network
+  channelContract: string
+  rate: string
+  assetContract: string
+  manifest: RouteDockManifest
+  commitmentPublicKey: string
+  onSettled?: (txHash: string, totalPaid: string, mode: string) => Promise<void>
+}
+
+export function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler {
+  const networkId = MPP_NETWORK[opts.network]
+  const rateHuman = opts.rate
+  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey)
+  const cumulativeKey = `stellar:channel:cumulative:${opts.channelContract}`
+
+  const innerStore = Store.memory()
+
+  // Wrap the store to intercept cumulative amount writes
+  let lastCumulativeAmount = 0n
+  const wrappedStore: ReturnType<typeof Store.memory> = {
+    async get(key: string) { return innerStore.get(key) },
+    async put(key: string, value: unknown) {
+      await innerStore.put(key, value)
+      if (key === cumulativeKey && value && typeof value === 'object' && 'amount' in (value as Record<string, unknown>)) {
+        lastCumulativeAmount = BigInt((value as { amount: string }).amount)
+      }
+    },
+    async delete(key: string) { return innerStore.delete(key) },
+  }
+
+  const mppx = Mppx.create({
+    secretKey: opts.payeeSecretKey,
+    methods: [
+      stellar.channel({
+        channel: opts.channelContract,
+        commitmentKey: opts.commitmentPublicKey,
+        network: networkId,
+        store: wrappedStore,
+        sourceAccount: payeeKeypair.publicKey(),
+        feePayer: { envelopeSigner: payeeKeypair },
+      }),
+    ],
+  })
+
+  // Track the last signature from the authorization header
+  let lastSignatureHex = ''
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      if (req.method === 'DELETE') {
+        const body = req.body as { amount?: string; signature?: string } | undefined
+        const closeAmount = body?.amount ? BigInt(body.amount) : lastCumulativeAmount
+        const closeSig = body?.signature ?? lastSignatureHex
+
+        if (closeAmount > 0n && closeSig) {
+          const closeTxHash = await channelClose({
+            channel: opts.channelContract,
+            amount: closeAmount,
+            signature: Buffer.from(closeSig, 'hex'),
+            feePayer: { envelopeSigner: payeeKeypair },
+            network: networkId,
+          })
+
+          if (opts.onSettled) {
+            const totalPaid = (Number(lastCumulativeAmount) / 1e7).toFixed(7)
+            await opts.onSettled(closeTxHash, totalPaid, 'mpp-session')
+          }
+
+          res.json({ closeTxHash })
+        } else {
+          res.json({ closeTxHash: null, message: 'no vouchers received' })
+        }
+        return
+      }
+
+      // Extract the signature from the authorization header before passing to mppx
+      const authHeader = req.headers['authorization']
+      if (typeof authHeader === 'string' && authHeader.startsWith('Payment ')) {
+        try {
+          const credB64 = authHeader.replace(/^Payment\s+/, '').split(',').find(p => p.trim().startsWith('credential='))
+          if (credB64) {
+            const credJson = Buffer.from(credB64.split('=').slice(1).join('=').replace(/^"|"$/g, ''), 'base64').toString('utf8')
+            const cred = JSON.parse(credJson) as { payload?: { signature?: string } }
+            if (cred.payload?.signature) {
+              lastSignatureHex = cred.payload.signature
+            }
+          }
+        } catch {
+          // non-fatal — signature extraction is best-effort
+        }
+      }
+
+      const fetchReq = MppxRequest.fromNodeListener(req, res)
+
+      const result = await (mppx as unknown as {
+        channel: (o: { amount: string; description?: string }) =>
+          (r: globalThis.Request) => Promise<{
+            status: number
+            challenge?: globalThis.Response
+            withReceipt?: (r: globalThis.Response) => globalThis.Response
+          }>
+      }).channel({
+        amount: rateHuman,
+        description: opts.manifest.name,
+      })(fetchReq)
+
+      if (result.status === 402) {
+        const challenge = result.challenge!
+        res.status(402)
+        challenge.headers.forEach((v: string, k: string) => res.setHeader(k, v))
+        const body = await challenge.text()
+        res.send(body)
+        return
+      }
+
+      next()
+    } catch (err) {
+      next(err)
+    }
+  }
+}

package/src/provider/index.ts

@@ -0,0 +1,7 @@
+// Provider-only exports (Express middleware + handlers)
+export * from '../types.js'
+export * from './routedockMiddleware.js'
+export * from './x402Handler.js'
+export * from './MppChargeHandler.js'
+export * from './MppSessionHandler.js'
+export * from '../store/SessionStore.js'