@routedock/routedock 0.1.0

package/dist/provider.js

@@ -0,0 +1,414 @@
+import { Keypair } from '@stellar/stellar-sdk';
+import { ExactStellarScheme } from '@x402/stellar/exact/facilitator';
+import { createEd25519Signer } from '@x402/stellar';
+import { encodePaymentRequiredHeader, decodePaymentSignatureHeader, encodePaymentResponseHeader } from '@x402/core/http';
+import { stellar } from '@stellar/mpp/charge/server';
+import { Mppx, Request } from 'mppx/server';
+import { Store, stellar as stellar$1, close } from '@stellar/mpp/channel/server';
+
+// src/types.ts
+var RouteDockError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RouteDockError";
+  }
+};
+var RouteDockManifestError = class extends RouteDockError {
+  constructor(message) {
+    super(message);
+    this.name = "RouteDockManifestError";
+  }
+};
+var RouteDockNoSupportedModeError = class extends RouteDockError {
+  constructor(message) {
+    super(message);
+    this.name = "RouteDockNoSupportedModeError";
+  }
+};
+var RouteDockSessionError = class extends RouteDockError {
+  constructor(message) {
+    super(message);
+    this.name = "RouteDockSessionError";
+  }
+};
+var RouteDockPolicyRejectedError = class extends RouteDockError {
+  reason;
+  constructor(reason) {
+    super(`Payment rejected by policy: ${reason}`);
+    this.name = "RouteDockPolicyRejectedError";
+    this.reason = reason;
+  }
+};
+var CAIP2 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+function createX402Handler(opts) {
+  const caip2 = CAIP2[opts.network];
+  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
+  const signer = createEd25519Signer(opts.payeeSecretKey, caip2);
+  const facilitatorScheme = new ExactStellarScheme([signer], {
+    areFeesSponsored: true
+  });
+  const amountInBaseUnits = String(Math.round(parseFloat(opts.amount) * 1e7));
+  const requirements = {
+    scheme: "exact",
+    network: caip2,
+    asset: opts.assetContract,
+    amount: amountInBaseUnits,
+    payTo: opts.manifest.payee,
+    maxTimeoutSeconds: 60,
+    extra: {
+      areFeesSponsored: true,
+      facilitatorAddresses: [payeeKeypair.publicKey()]
+    }
+  };
+  return async (req, res, next) => {
+    try {
+      const paymentHeader = req.headers["payment-signature"] ?? req.headers["x-payment"];
+      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,
+        requirements
+      );
+      if (!verifyResult.isValid) {
+        res.status(401).json({
+          error: "Payment verification failed",
+          reason: verifyResult.invalidReason
+        });
+        return;
+      }
+      const settleResult = await facilitatorScheme.settle(
+        payload,
+        requirements
+      );
+      const txHash = settleResult.transaction ?? null;
+      if (txHash && opts.onSettled) {
+        await opts.onSettled(txHash, opts.amount, "x402");
+      }
+      if (settleResult) {
+        res.setHeader(
+          "X-Payment-Response",
+          encodePaymentResponseHeader(
+            settleResult
+          )
+        );
+      }
+      next();
+    } catch (err) {
+      console.error("[x402] Settlement error:", err);
+      res.status(500).json({ error: "Payment settlement failed" });
+    }
+  };
+}
+var MPP_NETWORK = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+function createMppChargeHandler(opts) {
+  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, res, next) => {
+    try {
+      const fetchReq = Request.fromNodeListener(req, res);
+      const handler = mppx["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, k) => res.setHeader(k, v));
+        res.send(await challenge.text());
+        return;
+      }
+      const receipt = result.withReceipt(new Response(""));
+      receipt.headers.forEach((v, k) => res.setHeader(k, v));
+      const receiptHeader = receipt.headers.get("payment-receipt");
+      if (receiptHeader && opts.onSettled) {
+        try {
+          const parsed = JSON.parse(
+            Buffer.from(receiptHeader, "base64").toString("utf8")
+          );
+          if (parsed.reference) {
+            await opts.onSettled(parsed.reference, opts.amount, "mpp-charge");
+          }
+        } catch {
+        }
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+var MPP_NETWORK2 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+function createMppSessionHandler(opts) {
+  const networkId = MPP_NETWORK2[opts.network];
+  const rateHuman = opts.rate;
+  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
+  const cumulativeKey = `stellar:channel:cumulative:${opts.channelContract}`;
+  const innerStore = Store.memory();
+  let lastCumulativeAmount = 0n;
+  const wrappedStore = {
+    async get(key) {
+      return innerStore.get(key);
+    },
+    async put(key, value) {
+      await innerStore.put(key, value);
+      if (key === cumulativeKey && value && typeof value === "object" && "amount" in value) {
+        lastCumulativeAmount = BigInt(value.amount);
+      }
+    },
+    async delete(key) {
+      return innerStore.delete(key);
+    }
+  };
+  const mppx = Mppx.create({
+    secretKey: opts.payeeSecretKey,
+    methods: [
+      stellar$1.channel({
+        channel: opts.channelContract,
+        commitmentKey: opts.commitmentPublicKey,
+        network: networkId,
+        store: wrappedStore,
+        sourceAccount: payeeKeypair.publicKey(),
+        feePayer: { envelopeSigner: payeeKeypair }
+      })
+    ]
+  });
+  let lastSignatureHex = "";
+  return async (req, res, next) => {
+    try {
+      if (req.method === "DELETE") {
+        const body = req.body;
+        const closeAmount = body?.amount ? BigInt(body.amount) : lastCumulativeAmount;
+        const closeSig = body?.signature ?? lastSignatureHex;
+        if (closeAmount > 0n && closeSig) {
+          const closeTxHash = await close({
+            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;
+      }
+      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);
+            if (cred.payload?.signature) {
+              lastSignatureHex = cred.payload.signature;
+            }
+          }
+        } catch {
+        }
+      }
+      const fetchReq = Request.fromNodeListener(req, res);
+      const result = await mppx.channel({
+        amount: rateHuman,
+        description: opts.manifest.name
+      })(fetchReq);
+      if (result.status === 402) {
+        const challenge = result.challenge;
+        res.status(402);
+        challenge.headers.forEach((v, k) => res.setHeader(k, v));
+        const body = await challenge.text();
+        res.send(body);
+        return;
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+// src/provider/routedockMiddleware.ts
+function routedock(opts) {
+  const handlers = [];
+  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, res, next) => {
+    if (req.path === "/.well-known/routedock.json") {
+      res.json(opts.manifest);
+      return;
+    }
+    if (handlers.length === 0) {
+      next();
+      return;
+    }
+    const hasX402Header = !!(req.headers["payment-signature"] || req.headers["x-payment"]);
+    const prefersX402 = req.headers["x-preferred-mode"] === "x402";
+    let handler;
+    if (hasX402Header || prefersX402) {
+      handler = handlers[0];
+    } else {
+      handler = handlers[handlers.length - 1];
+    }
+    if (!handler) {
+      next();
+      return;
+    }
+    void Promise.resolve().then(() => new Promise((resolve, reject) => {
+      handler(req, res, (handlerErr) => {
+        if (handlerErr != null) reject(handlerErr);
+        else resolve();
+      });
+    })).then(() => next()).catch((err) => next(err));
+  };
+}
+
+// src/store/SessionStore.ts
+var SupabaseSessionStore = class {
+  constructor(supabase) {
+    this.supabase = supabase;
+  }
+  supabase;
+  async get(channelId) {
+    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,
+      payee: data.payee,
+      payer: data.payer,
+      cumulative_amount: String(data.cumulative_amount),
+      last_signature: data.last_signature,
+      status: data.status,
+      opened_at: data.opened_at,
+      updated_at: data.updated_at,
+      settlement_tx_hash: data.settlement_tx_hash
+    };
+  }
+  async upsert(channelId, state) {
+    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: (/* @__PURE__ */ new Date()).toISOString(),
+        settlement_tx_hash: state.settlement_tx_hash
+      },
+      { onConflict: "channel_id" }
+    );
+    if (error) {
+      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) {
+    const { error } = await this.supabase.from("sessions").update({ status: "closed", updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("channel_id", channelId);
+    if (error) throw new RouteDockSessionError(`SessionStore.close failed: ${error.message}`);
+  }
+};
+
+export { RouteDockError, RouteDockManifestError, RouteDockNoSupportedModeError, RouteDockPolicyRejectedError, RouteDockSessionError, SupabaseSessionStore, createMppChargeHandler, createMppSessionHandler, createX402Handler, routedock };

package/dist/routedockMiddleware-Beqan6QS.d.cts

@@ -0,0 +1,49 @@
+import { RequestHandler } from 'express';
+import { P as PaymentMode, c as RouteDockManifest } from './SessionStore-CCVO0PHM.cjs';
+
+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' },
+ *   ...
+ * }))
+ * ```
+ */
+declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
+
+export { type RouteDockMiddlewareOptions as R, routedock as r };

package/dist/routedockMiddleware-CqnyHjhO.d.ts

@@ -0,0 +1,49 @@
+import { RequestHandler } from 'express';
+import { P as PaymentMode, c as RouteDockManifest } from './SessionStore-CCVO0PHM.js';
+
+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' },
+ *   ...
+ * }))
+ * ```
+ */
+declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
+
+export { type RouteDockMiddlewareOptions as R, routedock as r };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@routedock/routedock",
+  "version": "0.1.0",
+  "description": "Unified payment execution layer for autonomous agents on Stellar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/winsznx/routedock.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "client": ["dist/client.d.ts"],
+      "provider": ["dist/provider.d.ts"]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "import": "./dist/provider.js",
+      "require": "./dist/provider.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^14.6.1",
+    "@supabase/supabase-js": "^2.47.0",
+    "@x402/core": "^2.9.0",
+    "@x402/stellar": "^2.9.0",
+    "@stellar/mpp": "^0.4.0",
+    "ajv": "^8.17.1",
+    "mppx": "^0.5.7"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.5"
+  }
+}

package/src/client/ModeRouter.ts

@@ -0,0 +1,104 @@
+import Ajv from 'ajv'
+import type { RouteDockManifest, PaymentMode } from '../types.js'
+import { RouteDockManifestError, RouteDockNoSupportedModeError } from '../types.js'
+import schema from '../schemas/routedock.schema.json' assert { type: 'json' }
+
+const ajv = new Ajv()
+const validateManifest = ajv.compile(schema)
+
+interface CacheEntry {
+  manifest: RouteDockManifest
+  fetchedAt: number
+}
+
+const CACHE_TTL_MS = 60_000
+
+/** In-memory manifest cache keyed by base URL. */
+const manifestCache = new Map<string, CacheEntry>()
+
+export interface ModeSelectOptions {
+  /** Force mpp-session if the provider supports it */
+  sustained?: boolean
+  session?: boolean
+  /**
+   * Override mode selection and use this specific mode.
+   * Throws RouteDockNoSupportedModeError if the provider does not support it.
+   */
+  forceMode?: PaymentMode
+}
+
+/** Fetch, validate, and cache a RouteDock manifest from `baseUrl`. */
+export async function fetchManifest(baseUrl: string): Promise<RouteDockManifest> {
+  const cached = manifestCache.get(baseUrl)
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.manifest
+  }
+
+  const url = baseUrl.replace(/\/$/, '') + '/.well-known/routedock.json'
+  let raw: unknown
+  try {
+    const resp = await fetch(url)
+    if (!resp.ok) {
+      throw new RouteDockManifestError(`Manifest fetch failed: HTTP ${resp.status} from ${url}`)
+    }
+    raw = await resp.json()
+  } catch (err) {
+    if (err instanceof RouteDockManifestError) throw err
+    throw new RouteDockManifestError(`Manifest fetch error: ${String(err)}`)
+  }
+
+  if (!validateManifest(raw)) {
+    const msgs = ajv.errorsText(validateManifest.errors)
+    throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`)
+  }
+
+  const manifest = raw as unknown as RouteDockManifest
+  manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now() })
+  return manifest
+}
+
+/**
+ * Deterministic mode selection per Section 6.3 of ROUTEDOCK_MASTER.md:
+ * 1. If { sustained | session } AND manifest supports mpp-session → mpp-session
+ * 2. Else if manifest supports mpp-charge AND network is Stellar → mpp-charge
+ * 3. Else if manifest supports x402 → x402
+ * 4. Else throw RouteDockNoSupportedModeError
+ */
+export function selectMode(
+  manifest: RouteDockManifest,
+  options: ModeSelectOptions = {},
+): PaymentMode {
+  const modes = manifest.modes
+
+  if (options.forceMode) {
+    if (!modes.includes(options.forceMode)) {
+      throw new RouteDockNoSupportedModeError(
+        `Provider does not support forced mode: ${options.forceMode} (available: ${modes.join(', ')})`,
+      )
+    }
+    console.log(`[RouteDock] ${manifest.name} → ${options.forceMode} (forced)`)
+    return options.forceMode
+  }
+
+  if ((options.sustained || options.session) && modes.includes('mpp-session')) {
+    const mode: PaymentMode = 'mpp-session'
+    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
+    return mode
+  }
+
+  if (modes.includes('mpp-charge')) {
+    const mode: PaymentMode = 'mpp-charge'
+    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
+    return mode
+  }
+
+  if (modes.includes('x402')) {
+    const mode: PaymentMode = 'x402'
+    console.log(`[RouteDock] ${manifest.name} → ${mode}`)
+    return mode
+  }
+
+  throw new RouteDockNoSupportedModeError(
+    `No supported payment mode found in manifest (modes: ${modes.join(', ')})`,
+  )
+}