@routedock/routedock 0.1.2 → 0.2.0

package/src/provider/routedockMiddleware.ts

@@ -1,154 +0,0 @@
-import type { Request, Response, NextFunction, RequestHandler } from 'express'
-import { createX402Handler } from './x402Handler.js'
-import { createMppChargeHandler } from './MppChargeHandler.js'
-import { createMppSessionHandler } from './MppSessionHandler.js'
-import type { RouteDockManifest, PaymentMode } from '../types.js'
-
-export interface RouteDockMiddlewareOptions {
-  modes: PaymentMode[]
-  pricing: {
-    x402?: string
-    'mpp-charge'?: string
-    'mpp-session'?: { rate: string; channelContract: string }
-  }
-  asset: string
-  /** Stellar Asset Contract address for the payment asset */
-  assetContract: string
-  payee: string
-  network: 'testnet' | 'mainnet'
-  /** Private key (S...) of the server/payee account */
-  payeeSecretKey: string
-  /** Required for x402 mode */
-  facilitatorApiKey?: string
-  /** Required for mpp-session mode — ed25519 public key (G...) for verifying commitments */
-  commitmentPublicKey?: string
-  /** Full RouteDock manifest — served at /.well-known/routedock.json */
-  manifest: RouteDockManifest
-  /** Called after each successful on-chain settlement */
-  onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>
-  /** Called when a new mpp-session is opened (first voucher received) */
-  onSessionOpen?: (channelId: string) => Promise<void>
-  /** Called after each verified voucher in an mpp-session */
-  onVoucher?: (voucherIndex: number, cumulativeAmount: string) => Promise<void>
-}
-
-/**
- * Express middleware factory for RouteDock provider endpoints.
- *
- * Automatically serves /.well-known/routedock.json and enforces payment
- * verification for all three modes (x402, mpp-charge, mpp-session).
- *
- * @example
- * ```ts
- * import { routedock } from '@routedock/sdk/provider'
- *
- * app.use('/price', routedock({
- *   modes: ['x402', 'mpp-charge'],
- *   pricing: { x402: '0.001', 'mpp-charge': '0.0008' },
- *   ...
- * }))
- * ```
- */
-export function routedock(opts: RouteDockMiddlewareOptions): RequestHandler {
-  const handlers: RequestHandler[] = []
-
-  if (opts.modes.includes('x402')) {
-    const x402Price = opts.pricing.x402
-    if (x402Price) {
-      handlers.push(
-        createX402Handler({
-          payeeSecretKey: opts.payeeSecretKey,
-          network: opts.network,
-          amount: x402Price,
-          assetContract: opts.assetContract,
-          ...(opts.facilitatorApiKey ? { facilitatorApiKey: opts.facilitatorApiKey } : {}),
-          manifest: opts.manifest,
-          ...(opts.onSettled ? { onSettled: opts.onSettled } : {}),
-        }),
-      )
-    }
-  }
-
-  if (opts.modes.includes('mpp-charge')) {
-    const chargePrice = opts.pricing['mpp-charge']
-    if (chargePrice) {
-      handlers.push(
-        createMppChargeHandler({
-          payeeSecretKey: opts.payeeSecretKey,
-          network: opts.network,
-          amount: chargePrice,
-          assetContract: opts.assetContract,
-          manifest: opts.manifest,
-          ...(opts.onSettled ? { onSettled: opts.onSettled } : {}),
-        }),
-      )
-    }
-  }
-
-  if (opts.modes.includes('mpp-session')) {
-    const sessionPricing = opts.pricing['mpp-session']
-    if (sessionPricing) {
-      if (!opts.commitmentPublicKey) {
-        throw new Error('routedock: mpp-session mode requires commitmentPublicKey')
-      }
-      handlers.push(
-        createMppSessionHandler({
-          payeeSecretKey: opts.payeeSecretKey,
-          network: opts.network,
-          channelContract: sessionPricing.channelContract,
-          rate: sessionPricing.rate,
-          assetContract: opts.assetContract,
-          manifest: opts.manifest,
-          commitmentPublicKey: opts.commitmentPublicKey,
-          ...(opts.onSettled ? { onSettled: opts.onSettled } : {}),
-          ...(opts.onSessionOpen ? { onSessionOpen: opts.onSessionOpen } : {}),
-          ...(opts.onVoucher ? { onVoucher: opts.onVoucher } : {}),
-        }),
-      )
-    }
-  }
-
-  return (req: Request, res: Response, next: NextFunction): void => {
-    // Serve manifest at /.well-known/routedock.json
-    if (req.path === '/.well-known/routedock.json') {
-      res.json(opts.manifest)
-      return
-    }
-
-    // No handlers — pass through
-    if (handlers.length === 0) {
-      next()
-      return
-    }
-
-    // Route to the correct handler based on request headers.
-    // x402 clients send `payment-signature` or `x-payment` headers.
-    // mppx clients send `authorization` with the mppx bearer scheme.
-    // On initial request (no payment), use the last handler (mppx returns
-    // WWW-Authenticate which x402 clients ignore; x402 only runs when its
-    // header is explicitly present).
-    const hasX402Header = !!(req.headers['payment-signature'] || req.headers['x-payment'])
-    const prefersX402 = req.headers['x-preferred-mode'] === 'x402'
-
-    let handler: RequestHandler | undefined
-    if (hasX402Header || prefersX402) {
-      handler = handlers[0]
-    } else {
-      handler = handlers[handlers.length - 1]
-    }
-
-    if (!handler) {
-      next()
-      return
-    }
-    void Promise.resolve()
-      .then(() => new Promise<void>((resolve, reject) => {
-        handler!(req, res, (handlerErr?: unknown) => {
-          if (handlerErr != null) reject(handlerErr)
-          else resolve()
-        })
-      }))
-      .then(() => next())
-      .catch((err) => next(err))
-  }
-}

package/src/provider/x402Handler.ts

@@ -1,164 +0,0 @@
-import type { Request, Response, NextFunction, RequestHandler } from 'express'
-import { Keypair } from '@stellar/stellar-sdk'
-import { ExactStellarScheme as ExactStellarFacilitatorScheme } from '@x402/stellar/exact/facilitator'
-import { ExactStellarScheme as ExactStellarServerScheme } from '@x402/stellar/exact/server'
-import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server'
-import { createEd25519Signer } from '@x402/stellar'
-import {
-  decodePaymentSignatureHeader,
-  encodePaymentRequiredHeader,
-  encodePaymentResponseHeader,
-} from '@x402/core/http'
-import type { Network as X402Network } from '@x402/core/types'
-import type { RouteDockManifest } from '../types.js'
-
-type Network = 'testnet' | 'mainnet'
-
-const CAIP2: Record<Network, X402Network> = {
-  testnet: 'stellar:testnet',
-  mainnet: 'stellar:pubnet',
-}
-
-const OZ_FACILITATOR_URL = 'https://channels.openzeppelin.com/x402'
-
-export interface X402HandlerOptions {
-  payeeSecretKey: string
-  network: Network
-  amount: string
-  assetContract: string
-  facilitatorApiKey?: string
-  manifest: RouteDockManifest
-  onSettled?: (txHash: string, amount: string, mode: string) => Promise<void>
-}
-
-export function createX402Handler(opts: X402HandlerOptions): RequestHandler {
-  const caip2 = CAIP2[opts.network]
-  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey)
-  const signer = createEd25519Signer(opts.payeeSecretKey, caip2)
-
-  const useOzFacilitator = opts.network === 'mainnet' && opts.facilitatorApiKey
-
-  // Mainnet: OZ hosted facilitator via x402ResourceServer
-  // Testnet: local ExactStellarFacilitatorScheme (OZ facilitator does not serve testnet)
-  const localFacilitator = new ExactStellarFacilitatorScheme([signer], {
-    areFeesSponsored: true,
-  })
-
-  let ozServer: x402ResourceServer | null = null
-  if (useOzFacilitator) {
-    const apiKey = opts.facilitatorApiKey!
-    const facilitator = new HTTPFacilitatorClient({
-      url: OZ_FACILITATOR_URL,
-      createAuthHeaders: async () => ({
-        verify: { Authorization: `Bearer ${apiKey}` },
-        settle: { Authorization: `Bearer ${apiKey}` },
-        supported: { Authorization: `Bearer ${apiKey}` },
-      }),
-    })
-    ozServer = new x402ResourceServer(facilitator)
-    ozServer.register(caip2, new ExactStellarServerScheme())
-  }
-
-  const amountInBaseUnits = String(Math.round(parseFloat(opts.amount) * 1e7))
-  const requirements = {
-    scheme: 'exact' as const,
-    network: caip2,
-    asset: opts.assetContract,
-    amount: amountInBaseUnits,
-    payTo: opts.manifest.payee,
-    maxTimeoutSeconds: 60,
-    extra: {
-      areFeesSponsored: true,
-      ...(useOzFacilitator ? {} : { facilitatorAddresses: [payeeKeypair.publicKey()] }),
-    },
-  }
-
-  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
-    try {
-      const paymentHeader = (req.headers['payment-signature'] ?? req.headers['x-payment']) as string | undefined
-
-      if (!paymentHeader) {
-        if (ozServer) {
-          const resourceInfo = {
-            url: `${req.protocol}://${req.get('host') ?? ''}${req.originalUrl}`,
-            description: opts.manifest.name,
-          }
-          const paymentRequired = await ozServer.createPaymentRequiredResponse(
-            [requirements],
-            resourceInfo,
-          )
-          res
-            .status(402)
-            .setHeader('Content-Type', 'application/json')
-            .setHeader('X-Payment-Requirements', encodePaymentRequiredHeader(paymentRequired))
-            .json({ error: 'Payment Required' })
-        } else {
-          const x402Response = {
-            x402Version: 2,
-            resource: {
-              url: `${req.protocol}://${req.get('host') ?? ''}${req.originalUrl}`,
-              description: opts.manifest.name,
-            },
-            accepts: [requirements],
-          }
-          res
-            .status(402)
-            .setHeader('Content-Type', 'application/json')
-            .setHeader('X-Payment-Requirements', encodePaymentRequiredHeader(x402Response))
-            .json({ error: 'Payment Required' })
-        }
-        return
-      }
-
-      const payload = decodePaymentSignatureHeader(paymentHeader)
-      let txHash: string | null = null
-
-      if (ozServer) {
-        const settleResult = await ozServer.settlePayment(payload, requirements)
-        txHash = (settleResult as { transaction?: string }).transaction ?? null
-        if (settleResult) {
-          res.setHeader(
-            'X-Payment-Response',
-            encodePaymentResponseHeader(
-              settleResult as Parameters<typeof encodePaymentResponseHeader>[0],
-            ),
-          )
-        }
-      } else {
-        const verifyResult = await localFacilitator.verify(
-          payload as Parameters<typeof localFacilitator.verify>[0],
-          requirements,
-        )
-        if (!verifyResult.isValid) {
-          res.status(401).json({
-            error: 'Payment verification failed',
-            reason: (verifyResult as { invalidReason?: string }).invalidReason,
-          })
-          return
-        }
-        const settleResult = await localFacilitator.settle(
-          payload as Parameters<typeof localFacilitator.settle>[0],
-          requirements,
-        )
-        txHash = (settleResult as { transaction?: string }).transaction ?? null
-        if (settleResult) {
-          res.setHeader(
-            'X-Payment-Response',
-            encodePaymentResponseHeader(
-              settleResult as Parameters<typeof encodePaymentResponseHeader>[0],
-            ),
-          )
-        }
-      }
-
-      if (txHash && opts.onSettled) {
-        await opts.onSettled(txHash, opts.amount, 'x402')
-      }
-
-      next()
-    } catch (err) {
-      console.error('[x402] Settlement error:', err)
-      res.status(500).json({ error: 'Payment settlement failed' })
-    }
-  }
-}

package/src/schemas/routedock.schema.json

@@ -1,159 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://routedock.dev/schemas/routedock.schema.json",
-  "title": "RouteDock Manifest",
-  "description": "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
-  "type": "object",
-  "required": [
-    "routedock",
-    "name",
-    "description",
-    "modes",
-    "network",
-    "asset",
-    "asset_contract",
-    "payee",
-    "pricing",
-    "endpoints",
-    "tags"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "routedock": {
-      "type": "string",
-      "const": "1.0",
-      "description": "Manifest schema version. Always '1.0' for this version."
-    },
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 120,
-      "description": "Human-readable provider name"
-    },
-    "description": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 500,
-      "description": "Human-readable description of the provider's data or service"
-    },
-    "modes": {
-      "type": "array",
-      "minItems": 1,
-      "uniqueItems": true,
-      "items": {
-        "$ref": "#/definitions/PaymentMode"
-      },
-      "description": "Payment modes supported by this provider"
-    },
-    "network": {
-      "type": "string",
-      "enum": ["testnet", "mainnet"],
-      "description": "Stellar network this provider operates on"
-    },
-    "asset": {
-      "type": "string",
-      "description": "Asset ticker symbol (e.g. 'USDC')"
-    },
-    "asset_contract": {
-      "type": "string",
-      "description": "Stellar Asset Contract (SAC) address for the payment asset"
-    },
-    "payee": {
-      "type": "string",
-      "description": "Stellar address (G...) that receives payments"
-    },
-    "pricing": {
-      "type": "object",
-      "description": "Pricing configuration per supported payment mode",
-      "additionalProperties": false,
-      "properties": {
-        "x402": {
-          "$ref": "#/definitions/PricingConfig"
-        },
-        "mpp-charge": {
-          "$ref": "#/definitions/PricingConfig"
-        },
-        "mpp-session": {
-          "$ref": "#/definitions/SessionPricingConfig"
-        }
-      },
-      "minProperties": 1
-    },
-    "endpoints": {
-      "type": "object",
-      "description": "Map of endpoint name to HTTP method + path (e.g. { 'price': 'GET /price' })",
-      "additionalProperties": {
-        "type": "string"
-      },
-      "minProperties": 1
-    },
-    "tags": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1,
-        "maxLength": 64
-      },
-      "uniqueItems": true,
-      "description": "Capability tags indexed with trigram search in the provider registry"
-    }
-  },
-  "definitions": {
-    "PaymentMode": {
-      "type": "string",
-      "enum": ["x402", "mpp-charge", "mpp-session"],
-      "description": "A supported RouteDock payment mode"
-    },
-    "PricingConfig": {
-      "type": "object",
-      "description": "Per-request pricing for x402 or mpp-charge modes",
-      "required": ["amount", "per"],
-      "additionalProperties": false,
-      "properties": {
-        "amount": {
-          "type": "string",
-          "description": "Cost per request in the payment asset (decimal string, e.g. '0.001')"
-        },
-        "per": {
-          "type": "string",
-          "const": "request",
-          "description": "Billing unit — always 'request' for non-session modes"
-        },
-        "facilitator": {
-          "type": "string",
-          "description": "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
-        }
-      }
-    },
-    "SessionPricingConfig": {
-      "type": "object",
-      "description": "Per-voucher pricing for mpp-session (one-way-channel) mode",
-      "required": ["rate", "per", "channel_contract", "min_deposit", "refund_waiting_period_ledgers"],
-      "additionalProperties": false,
-      "properties": {
-        "rate": {
-          "type": "string",
-          "description": "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
-        },
-        "per": {
-          "type": "string",
-          "const": "voucher",
-          "description": "Billing unit — always 'voucher' for session mode"
-        },
-        "channel_contract": {
-          "type": "string",
-          "description": "Soroban contract address (C...) for the one-way-channel contract"
-        },
-        "min_deposit": {
-          "type": "string",
-          "description": "Minimum initial deposit to open a channel (decimal string)"
-        },
-        "refund_waiting_period_ledgers": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
-        }
-      }
-    }
-  }
-}

package/src/store/SessionStore.ts

@@ -1,90 +0,0 @@
-import type { SupabaseClient } from '@supabase/supabase-js'
-import type { SessionState } from '../types.js'
-import { RouteDockSessionError } from '../types.js'
-
-// ── Interface ──────────────────────────────────────────────────────────────────
-
-export interface SessionStore {
-  get(channelId: string): Promise<SessionState | null>
-  /** Enforce monotonic invariant at application level before writing */
-  upsert(channelId: string, state: SessionState): Promise<void>
-  close(channelId: string): Promise<void>
-}
-
-// ── Supabase implementation ────────────────────────────────────────────────────
-
-export class SupabaseSessionStore implements SessionStore {
-  constructor(private readonly supabase: SupabaseClient) {}
-
-  async get(channelId: string): Promise<SessionState | null> {
-    const { data, error } = await this.supabase
-      .from('sessions')
-      .select('*')
-      .eq('channel_id', channelId)
-      .maybeSingle()
-
-    if (error) throw new RouteDockSessionError(`SessionStore.get failed: ${error.message}`)
-    if (!data) return null
-
-    return {
-      channel_id: data.channel_id as string,
-      payee: data.payee as string,
-      payer: data.payer as string,
-      cumulative_amount: String(data.cumulative_amount),
-      last_signature: data.last_signature as string,
-      status: data.status as SessionState['status'],
-      opened_at: data.opened_at as string,
-      updated_at: data.updated_at as string,
-      settlement_tx_hash: data.settlement_tx_hash as string | null,
-    }
-  }
-
-  async upsert(channelId: string, state: SessionState): Promise<void> {
-    // Application-level monotonic invariant check — catches non-increasing
-    // amounts before hitting the DB trigger, giving a typed error.
-    const existing = await this.get(channelId)
-    if (existing) {
-      const prev = parseFloat(existing.cumulative_amount)
-      const next = parseFloat(state.cumulative_amount)
-      if (next <= prev) {
-        throw new RouteDockSessionError(
-          `cumulative_amount must be strictly increasing: ${next} <= ${prev}`,
-        )
-      }
-    }
-
-    const { error } = await this.supabase.from('sessions').upsert(
-      {
-        channel_id: state.channel_id,
-        payee: state.payee,
-        payer: state.payer,
-        cumulative_amount: state.cumulative_amount,
-        last_signature: state.last_signature,
-        status: state.status,
-        opened_at: state.opened_at,
-        updated_at: new Date().toISOString(),
-        settlement_tx_hash: state.settlement_tx_hash,
-      },
-      { onConflict: 'channel_id' },
-    )
-
-    if (error) {
-      // DB trigger will raise 'cumulative_amount must be strictly increasing'
-      if (error.message.includes('strictly increasing')) {
-        throw new RouteDockSessionError(
-          `cumulative_amount must be strictly increasing (DB): ${error.message}`,
-        )
-      }
-      throw new RouteDockSessionError(`SessionStore.upsert failed: ${error.message}`)
-    }
-  }
-
-  async close(channelId: string): Promise<void> {
-    const { error } = await this.supabase
-      .from('sessions')
-      .update({ status: 'closed', updated_at: new Date().toISOString() })
-      .eq('channel_id', channelId)
-
-    if (error) throw new RouteDockSessionError(`SessionStore.close failed: ${error.message}`)
-  }
-}