@routedock/routedock 0.1.0

package/src/provider/routedockMiddleware.ts

@@ -0,0 +1,148 @@
+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>
+}
+
+/**
+ * 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 } : {}),
+        }),
+      )
+    }
+  }
+
+  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

@@ -0,0 +1,112 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express'
+import { Keypair } from '@stellar/stellar-sdk'
+import { ExactStellarScheme as ExactStellarFacilitatorScheme } from '@x402/stellar/exact/facilitator'
+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',
+}
+
+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 facilitatorScheme = new ExactStellarFacilitatorScheme([signer], {
+    areFeesSponsored: true,
+  })
+
+  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,
+      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) {
+        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)
+      const verifyResult = await facilitatorScheme.verify(
+        payload as Parameters<typeof facilitatorScheme.verify>[0],
+        requirements,
+      )
+
+      if (!verifyResult.isValid) {
+        res.status(401).json({
+          error: 'Payment verification failed',
+          reason: (verifyResult as { invalidReason?: string }).invalidReason,
+        })
+        return
+      }
+
+      const settleResult = await facilitatorScheme.settle(
+        payload as Parameters<typeof facilitatorScheme.settle>[0],
+        requirements,
+      )
+
+      const txHash = (settleResult as { transaction?: string }).transaction ?? null
+      if (txHash && opts.onSettled) {
+        await opts.onSettled(txHash, opts.amount, 'x402')
+      }
+
+      if (settleResult) {
+        res.setHeader(
+          'X-Payment-Response',
+          encodePaymentResponseHeader(
+            settleResult as Parameters<typeof encodePaymentResponseHeader>[0],
+          ),
+        )
+      }
+      next()
+    } catch (err) {
+      console.error('[x402] Settlement error:', err)
+      res.status(500).json({ error: 'Payment settlement failed' })
+    }
+  }
+}

package/src/schemas/routedock.schema.json

@@ -0,0 +1,159 @@
+{
+  "$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

@@ -0,0 +1,90 @@
+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}`)
+  }
+}