@routedock/routedock 0.1.1 → 0.2.0

package/dist/provider.js

@@ -1,46 +1,178 @@
-import { Keypair } from '@stellar/stellar-sdk';
+import { Keypair, StrKey, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } from '@stellar/stellar-sdk';
 import { ExactStellarScheme } from '@x402/stellar/exact/facilitator';
 import { ExactStellarScheme as ExactStellarScheme$1 } from '@x402/stellar/exact/server';
 import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
 import { createEd25519Signer } from '@x402/stellar';
 import { encodePaymentRequiredHeader, decodePaymentSignatureHeader, encodePaymentResponseHeader } from '@x402/core/http';
+import { usdcToStroops } from '@routedock/nulth-sdk';
 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';
+import { Errors } from 'mppx';
+import { createHash } from 'crypto';
 
-// src/types.ts
+// src/errors.ts
 var RouteDockError = class extends Error {
-  constructor(message) {
-    super(message);
+  code;
+  retryable;
+  retryAfterMs;
+  constructor(message, code, retryable, options = {}) {
+    super(message, { cause: options.cause });
     this.name = "RouteDockError";
+    this.code = code;
+    this.retryable = retryable;
+    if (options.retryAfterMs !== void 0) {
+      this.retryAfterMs = options.retryAfterMs;
+    }
   }
 };
 var RouteDockManifestError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "MANIFEST", false, options);
     this.name = "RouteDockManifestError";
   }
 };
 var RouteDockNoSupportedModeError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "NO_SUPPORTED_MODE", false, options);
     this.name = "RouteDockNoSupportedModeError";
   }
 };
-var RouteDockSessionError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
-    this.name = "RouteDockSessionError";
+var RouteDockClientVersionError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CLIENT_VERSION_TOO_OLD", false, options);
+    this.name = "RouteDockClientVersionError";
+  }
+};
+var RouteDockTrustlineError = class extends RouteDockError {
+  asset;
+  issuer;
+  remediation;
+  constructor(asset, issuer, remediation, options = {}) {
+    super(
+      `Missing trustline for ${asset} (issuer: ${issuer}). ${remediation}`,
+      "TRUSTLINE",
+      false,
+      options
+    );
+    this.name = "RouteDockTrustlineError";
+    this.asset = asset;
+    this.issuer = issuer;
+    this.remediation = remediation;
+  }
+};
+var RouteDockFacilitatorError = class extends RouteDockError {
+  status;
+  constructor(message, status, options = {}) {
+    super(message, "FACILITATOR", true, options);
+    this.name = "RouteDockFacilitatorError";
+    this.status = status;
+  }
+};
+var RouteDockNetworkError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "NETWORK", true, options);
+    this.name = "RouteDockNetworkError";
+  }
+};
+var RouteDockSignatureError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "SIGNATURE", false, options);
+    this.name = "RouteDockSignatureError";
+  }
+};
+var RouteDockVoucherMonotonicityError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "VOUCHER_MONOTONICITY", false, options);
+    this.name = "RouteDockVoucherMonotonicityError";
   }
 };
-var RouteDockPolicyRejectedError = class extends RouteDockError {
+var RouteDockPolicyRejectError = class extends RouteDockError {
   reason;
-  constructor(reason) {
-    super(`Payment rejected by policy: ${reason}`);
-    this.name = "RouteDockPolicyRejectedError";
+  constructor(reason, options = {}) {
+    super(`Payment rejected by policy: ${reason}`, "POLICY_REJECT", false, options);
+    this.name = "RouteDockPolicyRejectError";
     this.reason = reason;
   }
 };
+var RouteDockChannelStateError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CHANNEL_STATE", false, options);
+    this.name = "RouteDockChannelStateError";
+  }
+};
+var RouteDockDisputeError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "DISPUTE", false, options);
+    this.name = "RouteDockDisputeError";
+  }
+};
+var RouteDockRefundWindowError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "REFUND_WINDOW", false, options);
+    this.name = "RouteDockRefundWindowError";
+  }
+};
+var RouteDockPolicyRejectedError = RouteDockPolicyRejectError;
+var RouteDockSessionError = RouteDockVoucherMonotonicityError;
+
+// src/types.ts
+var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
+
+// src/provider/payee.ts
+function resolvePayee(manifest, mode) {
+  const override = manifest.pricing[mode]?.payee;
+  return override ?? manifest.payee;
+}
+var usdcToUnits = usdcToStroops;
+function extractPayerAddress(key) {
+  if (typeof key !== "string") return null;
+  return StrKey.isValidEd25519PublicKey(key) || StrKey.isValidMed25519PublicKey(key) ? key : null;
+}
+
+// src/provider/SeenTxStore.ts
+var InMemorySeenTxStore = class {
+  map = /* @__PURE__ */ new Map();
+  order = [];
+  constructor(maxEntriesOrOptions = 1e4) {
+    const options = typeof maxEntriesOrOptions === "number" ? { maxEntries: maxEntriesOrOptions } : maxEntriesOrOptions;
+    this.maxEntries = options.maxEntries ?? 1e4;
+    if (options.warn !== false) {
+      const isServerless = typeof globalThis.navigator !== "undefined" && globalThis.navigator.userAgent === "Cloudflare-Workers";
+      if (isServerless) {
+        console.warn(
+          "[RouteDock] Using in-memory SeenTxStore: settlement deduplication is NOT durable and resets on every isolate restart. Supply a SupabaseSeenTxStore (or other durable SeenTxStore) for production safety."
+        );
+      }
+    }
+  }
+  maxEntries;
+  get(key) {
+    return this.map.get(key);
+  }
+  set(key, record) {
+    if (!this.map.has(key)) {
+      this.order.push(key);
+      if (this.order.length > this.maxEntries) {
+        const evicted = this.order.shift();
+        if (evicted !== void 0) this.map.delete(evicted);
+      }
+    }
+    this.map.set(key, record);
+  }
+};
+async function sha256Hex(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function paymentIdempotencyKey(getHeader) {
+  const material = getHeader("payment-signature") ?? getHeader("x-payment") ?? getHeader("authorization");
+  if (!material) return null;
+  return sha256Hex(material);
+}
+
+// src/provider/x402Handler.ts
 var CAIP2 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -50,6 +182,7 @@ function createX402Handler(opts) {
   const caip2 = CAIP2[opts.network];
   const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
   const signer = createEd25519Signer(opts.payeeSecretKey, caip2);
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore();
   const useOzFacilitator = opts.network === "mainnet" && opts.facilitatorApiKey;
   const localFacilitator = new ExactStellarScheme([signer], {
     areFeesSponsored: true
@@ -68,13 +201,14 @@ function createX402Handler(opts) {
     ozServer = new x402ResourceServer(facilitator);
     ozServer.register(caip2, new ExactStellarScheme$1());
   }
-  const amountInBaseUnits = String(Math.round(parseFloat(opts.amount) * 1e7));
+  const amountInBaseUnits = String(usdcToUnits(opts.amount));
+  const payTo = resolvePayee(opts.manifest, "x402");
   const requirements = {
     scheme: "exact",
     network: caip2,
     asset: opts.assetContract,
     amount: amountInBaseUnits,
-    payTo: opts.manifest.payee,
+    payTo,
     maxTimeoutSeconds: 60,
     extra: {
       areFeesSponsored: true,
@@ -108,8 +242,31 @@ function createX402Handler(opts) {
         }
         return;
       }
+      const idempotencyKey = await paymentIdempotencyKey((name) => {
+        const v = req.headers[name.toLowerCase()];
+        return Array.isArray(v) ? v[0] : v;
+      });
+      if (idempotencyKey) {
+        const cached = await seenTxStore.get(idempotencyKey);
+        if (cached) {
+          if (cached.headers) {
+            for (const [k, val] of Object.entries(cached.headers)) {
+              res.setHeader(k, val);
+            }
+          }
+          next();
+          return;
+        }
+      }
       const payload = decodePaymentSignatureHeader(paymentHeader);
       let txHash = null;
+      let payerAddress = null;
+      try {
+        const creds = payload.authorization?.credentials;
+        const key = Array.isArray(creds) ? creds[0]?.publicKey : void 0;
+        payerAddress = extractPayerAddress(key);
+      } catch {
+      }
       if (ozServer) {
         const settleResult = await ozServer.settlePayment(payload, requirements);
         txHash = settleResult.transaction ?? null;
@@ -147,8 +304,19 @@ function createX402Handler(opts) {
           );
         }
       }
+      if (idempotencyKey) {
+        const headers = {};
+        const paymentResponse = res.getHeader("X-Payment-Response");
+        if (typeof paymentResponse === "string") {
+          headers["X-Payment-Response"] = paymentResponse;
+        }
+        await seenTxStore.set(idempotencyKey, { txHash, headers });
+      }
       if (txHash && opts.onSettled) {
-        await opts.onSettled(txHash, opts.amount, "x402");
+        Promise.resolve().then(() => opts.onSettled(txHash, opts.amount, "x402", payerAddress)).catch((err) => {
+          console.error("[x402] onSettled callback error:", err);
+          opts.onCallbackError?.(err, "onSettled");
+        });
       }
       next();
     } catch (err) {
@@ -164,11 +332,13 @@ var MPP_NETWORK = {
 function createMppChargeHandler(opts) {
   const networkId = MPP_NETWORK[opts.network];
   const amountHumanReadable = opts.amount;
+  const recipient = resolvePayee(opts.manifest, "mpp-charge");
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore();
   const mppx = Mppx.create({
     secretKey: opts.payeeSecretKey,
     methods: [
       stellar.charge({
-        recipient: opts.manifest.payee,
+        recipient,
         currency: opts.assetContract,
         network: networkId,
         feePayer: { envelopeSigner: opts.payeeSecretKey }
@@ -177,12 +347,43 @@ function createMppChargeHandler(opts) {
   });
   return async (req, res, next) => {
     try {
+      let payerAddress = null;
+      try {
+        const authHeader = req.headers["authorization"];
+        if (typeof authHeader === "string" && authHeader.startsWith("Payment ")) {
+          const credPart = authHeader.replace(/^Payment\s+/, "").split(",").find((p) => p.trim().startsWith("credential="));
+          if (credPart) {
+            const b64 = credPart.split("=").slice(1).join("=").replace(/^"|"$/g, "");
+            const credJson = Buffer.from(b64, "base64").toString("utf8");
+            const cred = JSON.parse(credJson);
+            const key = cred.sender ?? cred.payload?.sender ?? cred.payload?.from;
+            payerAddress = extractPayerAddress(key);
+          }
+        }
+      } catch {
+      }
+      const idempotencyKey = await paymentIdempotencyKey((name) => {
+        const v = req.headers[name.toLowerCase()];
+        return Array.isArray(v) ? v[0] : v;
+      });
+      if (idempotencyKey) {
+        const cached = await seenTxStore.get(idempotencyKey);
+        if (cached) {
+          if (cached.headers) {
+            for (const [k, val] of Object.entries(cached.headers)) {
+              res.setHeader(k, val);
+            }
+          }
+          next();
+          return;
+        }
+      }
       const fetchReq = Request.fromNodeListener(req, res);
       const handler = mppx["stellar/charge"];
       const result = await handler({
         amount: amountHumanReadable,
         currency: opts.assetContract,
-        recipient: opts.manifest.payee,
+        recipient,
         description: opts.manifest.name
       })(fetchReq);
       if (result.status === 402) {
@@ -193,25 +394,130 @@ function createMppChargeHandler(opts) {
         return;
       }
       const receipt = result.withReceipt(new Response(""));
-      receipt.headers.forEach((v, k) => res.setHeader(k, v));
+      const receiptHeaders = {};
+      receipt.headers.forEach((v, k) => {
+        res.setHeader(k, v);
+        receiptHeaders[k] = v;
+      });
       const receiptHeader = receipt.headers.get("payment-receipt");
-      if (receiptHeader && opts.onSettled) {
+      let reference;
+      if (receiptHeader) {
         try {
           const parsed = JSON.parse(
             Buffer.from(receiptHeader, "base64").toString("utf8")
           );
-          if (parsed.reference) {
-            await opts.onSettled(parsed.reference, opts.amount, "mpp-charge");
-          }
+          reference = parsed.reference;
         } catch {
         }
       }
+      if (idempotencyKey) {
+        await seenTxStore.set(idempotencyKey, {
+          txHash: reference ?? null,
+          headers: receiptHeaders
+        });
+      }
+      if (reference && opts.onSettled) {
+        Promise.resolve().then(() => opts.onSettled(reference, opts.amount, "mpp-charge", payerAddress)).catch((err) => {
+          console.error("[mpp-charge] onSettled callback error:", err);
+          opts.onCallbackError?.(err, "onSettled");
+        });
+      }
       next();
     } catch (err) {
       next(err);
     }
   };
 }
+function resolveVaultSettlementAddresses(payer, payee) {
+  if (!payer) return null;
+  return { payer, payee };
+}
+function buildSessionSettlementTransaction(source, vaultContractId, channelId, addresses, amount, voucherCount, networkPassphrase) {
+  const vault = new Contract(vaultContractId);
+  const op = vault.call(
+    "record_session_settlement",
+    nativeToScVal(channelId, { type: "address" }),
+    nativeToScVal(addresses.payer, { type: "address" }),
+    nativeToScVal(addresses.payee, { type: "address" }),
+    nativeToScVal(amount, { type: "i128" }),
+    nativeToScVal(voucherCount, { type: "u32" })
+  );
+  return new TransactionBuilder(source, {
+    fee: BASE_FEE,
+    networkPassphrase
+  }).addOperation(op).setTimeout(30).build();
+}
+function channelAuthorizer(envelopeSigner) {
+  return { envelopeSigner };
+}
+function formatMppError(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    const serialized = JSON.stringify(error);
+    return serialized === void 0 ? String(error) : serialized;
+  } catch {
+    return String(error);
+  }
+}
+function withTypedChannelErrors(method) {
+  return {
+    ...method,
+    async verify(parameters) {
+      try {
+        return await method.verify(parameters);
+      } catch (error) {
+        throw mapChannelError(error);
+      }
+    }
+  };
+}
+function onVerifiedCredential(method, commit) {
+  return {
+    ...method,
+    async verify(parameters) {
+      const receipt = await method.verify(parameters);
+      await commit(parameters.credential);
+      return receipt;
+    }
+  };
+}
+function mapChannelError(error) {
+  const message = formatMppError(error);
+  const details = error && typeof error === "object" && "details" in error ? error.details : void 0;
+  const reason = details && Object.keys(details).length > 0 ? `${message} (${JSON.stringify(details)})` : message;
+  if (/signer mismatch|authori[sz]er|unauthori[sz]ed/i.test(message)) {
+    return new Errors.SignerMismatchError({ reason });
+  }
+  if (/already used|replay|challenge/i.test(message)) {
+    return new Errors.InvalidChallengeError({ reason });
+  }
+  if (/channel has been closed|channel is closed|finalized/i.test(message)) {
+    return new Errors.ChannelClosedError({ reason });
+  }
+  if (/exceeds channel balance|exceeds.*deposit/i.test(message)) {
+    return new Errors.AmountExceedsDepositError({ reason });
+  }
+  if (/channel not found|no channel/i.test(message)) {
+    return new Errors.ChannelNotFoundError({ reason });
+  }
+  if (/must be greater|does not cover|below.*minimum/i.test(message)) {
+    return new Errors.DeltaTooSmallError({ reason });
+  }
+  if (/signature/i.test(message)) {
+    return new Errors.InvalidSignatureError({ reason });
+  }
+  return new Errors.VerificationFailedError({ reason });
+}
+
+// src/provider/MppSessionHandler.ts
+function isVoucherStoreValue(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.amount === "string" && /^\d+$/.test(candidate.amount);
+}
 var MPP_NETWORK2 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -220,67 +526,202 @@ 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 voucherRecordKey = `routedock:session:voucher:${opts.channelFactory}`;
   const innerStore = Store.memory();
-  let lastCumulativeAmount = 0n;
+  let record = null;
   let voucherCount = 0;
   let sessionOpened = false;
+  let idleTimer = null;
+  let settledCleanly = false;
+  let closeListenerArmed = false;
+  function clearIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+  function armIdleTimer() {
+    if (!opts.idleTimeoutMs) return;
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      void flagOrphan("idle-timeout");
+    }, opts.idleTimeoutMs);
+    if (typeof idleTimer.unref === "function") idleTimer.unref();
+  }
+  async function loadPersistedRecord() {
+    if (record) return record;
+    try {
+      const stored = await innerStore.get(voucherRecordKey);
+      if (!stored || typeof stored.amount !== "string" || typeof stored.signature !== "string") {
+        return null;
+      }
+      record = { amount: BigInt(stored.amount), signature: stored.signature, payer: stored.payer ?? null };
+    } catch {
+      return null;
+    }
+    return record;
+  }
+  async function flagOrphan(reason) {
+    await loadPersistedRecord();
+    if (!sessionOpened || settledCleanly) return;
+    sessionOpened = false;
+    closeListenerArmed = false;
+    clearIdleTimer();
+    const cumulativeAmount = record ? (Number(record.amount) / 1e7).toFixed(7) : "0.0000000";
+    if (opts.onOrphaned) {
+      try {
+        await opts.onOrphaned(opts.channelFactory, {
+          cumulativeAmount,
+          lastSignature: record?.signature ?? "",
+          voucherCount,
+          reason
+        });
+      } catch (err) {
+        console.error("[mpp-session] onOrphaned handler failed:", err);
+      }
+    }
+  }
   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);
-        voucherCount++;
-        if (!sessionOpened) {
-          sessionOpened = true;
-          if (opts.onSessionOpen) {
-            await opts.onSessionOpen(opts.channelContract);
-          }
-        }
-        if (opts.onVoucher) {
-          const humanAmount = (Number(lastCumulativeAmount) / 1e7).toFixed(7);
-          await opts.onVoucher(voucherCount, humanAmount);
-        }
-      }
+      return innerStore.put(key, value);
     },
     async delete(key) {
       return innerStore.delete(key);
+    },
+    async update(key, fn) {
+      const storeWithUpdate = innerStore;
+      if (typeof storeWithUpdate.update === "function") {
+        return storeWithUpdate.update(key, fn);
+      }
+      throw new Error("Store does not support atomic update operations");
     }
   };
+  async function commit(credential) {
+    await loadPersistedRecord();
+    const payload = credential.payload;
+    if (typeof payload?.amount !== "string" || typeof payload.signature !== "string") return;
+    let amount;
+    try {
+      amount = BigInt(payload.amount);
+    } catch {
+      return;
+    }
+    if (record && amount < record.amount) return;
+    const payer = record?.payer ?? extractPayerAddress(credential.source);
+    record = { amount, signature: payload.signature, payer };
+    await innerStore.put(voucherRecordKey, {
+      amount: record.amount.toString(),
+      signature: record.signature,
+      payer: record.payer
+    });
+    voucherCount++;
+    settledCleanly = false;
+    armIdleTimer();
+    if (!sessionOpened) {
+      sessionOpened = true;
+      if (opts.onSessionOpen) {
+        Promise.resolve().then(() => opts.onSessionOpen(opts.channelFactory, record.payer)).catch((err) => {
+          console.error("[mpp-session] onSessionOpen callback error:", err);
+          opts.onCallbackError?.(err, "onSessionOpen");
+        });
+      }
+    }
+    if (opts.onVoucher) {
+      const humanAmount = (Number(record.amount) / 1e7).toFixed(7);
+      Promise.resolve().then(() => opts.onVoucher(opts.channelFactory, voucherCount, humanAmount, record.signature)).catch((err) => {
+        console.error("[mpp-session] onVoucher callback error:", err);
+        opts.onCallbackError?.(err, "onVoucher");
+      });
+    }
+  }
   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 }
-      })
+      withTypedChannelErrors(
+        onVerifiedCredential(
+          stellar$1.channel({
+            channel: opts.channelFactory,
+            commitmentKey: opts.commitmentPublicKey,
+            network: networkId,
+            store: wrappedStore,
+            sourceAccount: payeeKeypair.publicKey(),
+            feePayer: channelAuthorizer(payeeKeypair)
+          }),
+          commit
+        )
+      )
     ]
   });
-  let lastSignatureHex = "";
   return async (req, res, next) => {
     try {
       if (req.method === "DELETE") {
+        await loadPersistedRecord();
         const body = req.body;
-        const closeAmount = body?.amount ? BigInt(body.amount) : lastCumulativeAmount;
-        const closeSig = body?.signature ?? lastSignatureHex;
+        const bodyAmount = body?.amount ? BigInt(body.amount) : 0n;
+        const recordAmount = record?.amount ?? 0n;
+        let closeAmount;
+        let closeSig;
+        if (bodyAmount > recordAmount) {
+          closeAmount = bodyAmount;
+          closeSig = body?.signature ?? record?.signature ?? "";
+        } else {
+          closeAmount = recordAmount;
+          closeSig = record?.signature ?? "";
+        }
         if (closeAmount > 0n && closeSig) {
+          const closePayer = record?.payer ?? null;
           const closeTxHash = await close({
-            channel: opts.channelContract,
+            channel: opts.channelFactory,
             amount: closeAmount,
             signature: Buffer.from(closeSig, "hex"),
-            feePayer: { envelopeSigner: payeeKeypair },
+            feePayer: channelAuthorizer(payeeKeypair),
             network: networkId
           });
+          settledCleanly = true;
+          clearIdleTimer();
           if (opts.onSettled) {
-            const totalPaid = (Number(lastCumulativeAmount) / 1e7).toFixed(7);
-            await opts.onSettled(closeTxHash, totalPaid, "mpp-session");
+            const totalPaid = (Number(closeAmount) / 1e7).toFixed(7);
+            Promise.resolve().then(() => opts.onSettled(closeTxHash, totalPaid, "mpp-session", closePayer)).catch((err) => {
+              console.error("[mpp-session] onSettled callback error:", err);
+              opts.onCallbackError?.(err, "onSettled");
+            });
+          }
+          const vaultContract = process.env.AGENT_VAULT_CONTRACT;
+          if (vaultContract) {
+            const settlementAddresses = resolveVaultSettlementAddresses(
+              closePayer,
+              payeeKeypair.publicKey()
+            );
+            if (!settlementAddresses) {
+              console.error("[mpp-session] skipped session_settled vault record: payer address unavailable");
+            } else {
+              try {
+                const { Networks } = await import('@stellar/stellar-sdk');
+                const { Server } = await import('@stellar/stellar-sdk/rpc');
+                const networkPassphrase = opts.network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
+                const rpcUrl = opts.network === "mainnet" ? "https://mainnet.sorobanrpc.com" : "https://soroban-testnet.stellar.org";
+                const server = new Server(rpcUrl);
+                const payeePublicKey = payeeKeypair.publicKey();
+                const sourceAccount = await server.getAccount(payeePublicKey);
+                const tx = buildSessionSettlementTransaction(
+                  sourceAccount,
+                  vaultContract,
+                  opts.channelFactory,
+                  settlementAddresses,
+                  closeAmount,
+                  voucherCount,
+                  networkPassphrase
+                );
+                const preparedTx = await server.prepareTransaction(tx);
+                preparedTx.sign(payeeKeypair);
+                await server.sendTransaction(preparedTx);
+              } catch (recordErr) {
+                console.error("[mpp-session] failed to record session_settled on vault:", recordErr);
+              }
+            }
           }
           res.json({ closeTxHash });
         } else {
@@ -288,23 +729,12 @@ function createMppSessionHandler(opts) {
         }
         sessionOpened = false;
         voucherCount = 0;
-        lastCumulativeAmount = 0n;
+        record = null;
+        await innerStore.delete(voucherRecordKey);
+        closeListenerArmed = false;
+        clearIdleTimer();
         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,
@@ -318,28 +748,100 @@ function createMppSessionHandler(opts) {
         res.send(body);
         return;
       }
+      if (!closeListenerArmed) {
+        closeListenerArmed = true;
+        req.on("close", () => {
+          void flagOrphan("connection-closed");
+        });
+      }
       next();
     } catch (err) {
       next(err);
     }
   };
 }
+var MANIFEST_SIGNATURE_VERSION = "2";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
+    );
+  }
+  return value;
+}
+function manifestDigest(manifest) {
+  const { signature: _omit, ...rest } = manifest;
+  const canonical = JSON.stringify(canonicalize(rest));
+  return createHash("sha256").update(canonical, "utf8").digest();
+}
+function signManifest(manifest, payeeSecretKey) {
+  const keypair = Keypair.fromSecret(payeeSecretKey);
+  const versionedManifest = {
+    ...manifest,
+    signature_version: MANIFEST_SIGNATURE_VERSION
+  };
+  const digest = manifestDigest(versionedManifest);
+  const sig = keypair.sign(digest);
+  return { ...versionedManifest, signature: Buffer.from(sig).toString("base64") };
+}
+function verifyManifestSignature(manifest, expectedPayee) {
+  if (!manifest.signature) {
+    throw new RouteDockSignatureError(
+      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
+    );
+  }
+  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
+    throw new RouteDockSignatureError(
+      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
+    );
+  }
+  const keypair = Keypair.fromPublicKey(manifest.payee);
+  const digest = manifestDigest(manifest);
+  let sigBytes;
+  try {
+    sigBytes = Buffer.from(manifest.signature, "base64");
+  } catch {
+    throw new RouteDockSignatureError("Manifest signature is not valid base64");
+  }
+  let valid = false;
+  try {
+    valid = keypair.verify(digest, sigBytes);
+  } catch {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+  if (!valid) {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+}
 
 // src/provider/routedockMiddleware.ts
+var MPP_MODES = ["mpp-session", "mpp-charge"];
 function routedock(opts) {
-  const handlers = [];
+  const startTime = Date.now();
+  const signedManifest = signManifest(opts.manifest, opts.payeeSecretKey);
+  const handlerMap = /* @__PURE__ */ new Map();
   if (opts.modes.includes("x402")) {
     const x402Price = opts.pricing.x402;
     if (x402Price) {
-      handlers.push(
+      handlerMap.set(
+        "x402",
         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 } : {}
+          manifest: signedManifest,
+          ...opts.onSettled ? { onSettled: opts.onSettled } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {}
         })
       );
     }
@@ -347,14 +849,17 @@ function routedock(opts) {
   if (opts.modes.includes("mpp-charge")) {
     const chargePrice = opts.pricing["mpp-charge"];
     if (chargePrice) {
-      handlers.push(
+      handlerMap.set(
+        "mpp-charge",
         createMppChargeHandler({
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
           amount: chargePrice,
           assetContract: opts.assetContract,
-          manifest: opts.manifest,
-          ...opts.onSettled ? { onSettled: opts.onSettled } : {}
+          manifest: signedManifest,
+          ...opts.onSettled ? { onSettled: opts.onSettled } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {}
         })
       );
     }
@@ -365,39 +870,52 @@ function routedock(opts) {
       if (!opts.commitmentPublicKey) {
         throw new Error("routedock: mpp-session mode requires commitmentPublicKey");
       }
-      handlers.push(
+      handlerMap.set(
+        "mpp-session",
         createMppSessionHandler({
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
-          channelContract: sessionPricing.channelContract,
+          channelFactory: sessionPricing.channelFactory,
           rate: sessionPricing.rate,
           assetContract: opts.assetContract,
-          manifest: opts.manifest,
+          manifest: signedManifest,
           commitmentPublicKey: opts.commitmentPublicKey,
           ...opts.onSettled ? { onSettled: opts.onSettled } : {},
           ...opts.onSessionOpen ? { onSessionOpen: opts.onSessionOpen } : {},
-          ...opts.onVoucher ? { onVoucher: opts.onVoucher } : {}
+          ...opts.onVoucher ? { onVoucher: opts.onVoucher } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.onOrphaned ? { onOrphaned: opts.onOrphaned } : {},
+          ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {}
         })
       );
     }
   }
+  const defaultMode = MPP_MODES.find((mode) => handlerMap.has(mode)) ?? (handlerMap.has("x402") ? "x402" : void 0);
   return (req, res, next) => {
     if (req.path === "/.well-known/routedock.json") {
-      res.json(opts.manifest);
+      res.json(signedManifest);
+      return;
+    }
+    if (req.path === "/health") {
+      res.json({
+        status: "ok",
+        routedock: opts.manifest.routedock,
+        network: opts.network,
+        payee: opts.payee,
+        modesActive: opts.modes,
+        uptime: Math.floor((Date.now() - startTime) / 1e3)
+      });
       return;
     }
-    if (handlers.length === 0) {
+    if (handlerMap.size === 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];
-    }
+    const x402Handler = handlerMap.get("x402");
+    const defaultHandler = defaultMode ? handlerMap.get(defaultMode) : void 0;
+    const handler = hasX402Header || prefersX402 ? x402Handler ?? defaultHandler : defaultHandler;
     if (!handler) {
       next();
       return;
@@ -410,6 +928,148 @@ function routedock(opts) {
     })).then(() => next()).catch((err) => next(err));
   };
 }
+var MPP_NETWORK3 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+function decimalToStroops(amountStr) {
+  return usdcToStroops(amountStr);
+}
+async function reconcileAbandonedSessions(opts) {
+  const stats = {
+    orphanedCount: 0,
+    recoveredCount: 0,
+    skippedCount: 0,
+    failedCount: 0,
+    errors: []
+  };
+  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
+  const networkId = MPP_NETWORK3[opts.network];
+  try {
+    const { data: closingSessions, error } = await opts.supabase.from("sessions").select("channel_id, channel_contract, cumulative_amount, last_signature, settlement_tx_hash").eq("status", "closing").eq("network", opts.network).eq("payee", payeeKeypair.publicKey()).is("settlement_tx_hash", null).not("last_signature", "is", null).order("updated_at", { ascending: true }).limit(100);
+    if (error) {
+      throw new Error(`Failed to query sessions: ${error.message}`);
+    }
+    stats.orphanedCount = closingSessions?.length ?? 0;
+    if (!closingSessions || closingSessions.length === 0) {
+      return stats;
+    }
+    for (const session of closingSessions) {
+      try {
+        const {
+          channel_id: sessionId,
+          channel_contract: channelContract,
+          cumulative_amount,
+          last_signature
+        } = session;
+        const channelId = channelContract || sessionId;
+        if (!channelId || !cumulative_amount || !last_signature) {
+          stats.skippedCount++;
+          continue;
+        }
+        const closeAmount = decimalToStroops(cumulative_amount);
+        const closeSig = Buffer.from(last_signature, "hex");
+        const closeFn = opts.channelClose ?? (await import('@stellar/mpp/channel/server')).close;
+        const closeTxHash = await closeFn({
+          channel: channelId,
+          amount: closeAmount,
+          signature: closeSig,
+          feePayer: channelAuthorizer(payeeKeypair),
+          network: networkId
+        });
+        const totalPaid = (Number(closeAmount) / 1e7).toFixed(7);
+        const { error: updateError } = await opts.supabase.from("sessions").update({
+          status: "closed",
+          settlement_tx_hash: closeTxHash,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        }).eq("channel_id", sessionId);
+        if (updateError) {
+          throw new Error(`Failed to update session: ${updateError.message}`);
+        }
+        stats.recoveredCount++;
+        if (opts.onRecovered) {
+          await opts.onRecovered(channelId, closeTxHash, totalPaid);
+        }
+      } catch (err) {
+        stats.failedCount++;
+        stats.errors.push({
+          channelId: session.channel_id,
+          reason: formatMppError(err)
+        });
+      }
+    }
+    return stats;
+  } catch (err) {
+    throw new Error(
+      `Session reconciliation failed: ${formatMppError(err)}`
+    );
+  }
+}
+async function runStartupReconciliation(opts, logger) {
+  const log = logger || console.log;
+  log("[SessionReconciler] Running startup reconciliation...");
+  try {
+    const stats = await reconcileAbandonedSessions(opts);
+    if (stats.orphanedCount === 0) {
+      log("[SessionReconciler] No orphaned sessions found");
+      return;
+    }
+    log(
+      `[SessionReconciler] Found ${stats.orphanedCount} orphaned session(s). Recovered: ${stats.recoveredCount}, Skipped: ${stats.skippedCount}, Failed: ${stats.failedCount}`
+    );
+    if (stats.errors.length > 0) {
+      log("[SessionReconciler] Reconciliation errors:");
+      for (const err of stats.errors) {
+        log(`  - ${err.channelId}: ${err.reason}`);
+      }
+    }
+  } catch (err) {
+    log(`[SessionReconciler] Startup reconciliation failed: ${formatMppError(err)}`);
+  }
+}
+
+// src/provider/registerProvider.ts
+async function registerProvider(optionsOrSupabase, manifestArg, baseUrlArg, verifiedArg) {
+  let supabase;
+  let manifest;
+  let baseUrl;
+  let verified;
+  if ("supabase" in optionsOrSupabase) {
+    supabase = optionsOrSupabase.supabase;
+    manifest = optionsOrSupabase.manifest;
+    baseUrl = optionsOrSupabase.baseUrl;
+    verified = optionsOrSupabase.verified ?? true;
+  } else {
+    supabase = optionsOrSupabase;
+    if (!manifestArg || !baseUrlArg) {
+      throw new RouteDockManifestError("manifest and baseUrl are required for registerProvider");
+    }
+    manifest = manifestArg;
+    baseUrl = baseUrlArg;
+    verified = verifiedArg ?? true;
+  }
+  verifyManifestSignature(manifest);
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+  const { error } = await supabase.from("providers").upsert(
+    {
+      name: manifest.name,
+      description: manifest.description ?? null,
+      base_url: normalizedBaseUrl,
+      modes: manifest.modes,
+      tags: manifest.tags ?? [],
+      categories: manifest.categories ?? [],
+      network: manifest.network,
+      payee: manifest.payee,
+      manifest,
+      verified,
+      registered_at: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    { onConflict: "base_url" }
+  );
+  if (error) {
+    throw new Error(`Failed to register provider in Supabase: ${error.message}`);
+  }
+}
 
 // src/store/SessionStore.ts
 var SupabaseSessionStore = class {
@@ -419,12 +1079,16 @@ var SupabaseSessionStore = class {
   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 (error) {
+      throw new RouteDockNetworkError(`SessionStore.get failed: ${error.message}`);
+    }
     if (!data) return null;
     return {
       channel_id: data.channel_id,
       payee: data.payee,
       payer: data.payer,
+      channel_contract: data.channel_contract,
+      network: data.network,
       cumulative_amount: String(data.cumulative_amount),
       last_signature: data.last_signature,
       status: data.status,
@@ -439,7 +1103,7 @@ var SupabaseSessionStore = class {
       const prev = parseFloat(existing.cumulative_amount);
       const next = parseFloat(state.cumulative_amount);
       if (next <= prev) {
-        throw new RouteDockSessionError(
+        throw new RouteDockVoucherMonotonicityError(
           `cumulative_amount must be strictly increasing: ${next} <= ${prev}`
         );
       }
@@ -449,6 +1113,8 @@ var SupabaseSessionStore = class {
         channel_id: state.channel_id,
         payee: state.payee,
         payer: state.payer,
+        channel_contract: state.channel_contract,
+        network: state.network,
         cumulative_amount: state.cumulative_amount,
         last_signature: state.last_signature,
         status: state.status,
@@ -460,17 +1126,62 @@ var SupabaseSessionStore = class {
     );
     if (error) {
       if (error.message.includes("strictly increasing")) {
-        throw new RouteDockSessionError(
+        throw new RouteDockVoucherMonotonicityError(
           `cumulative_amount must be strictly increasing (DB): ${error.message}`
         );
       }
-      throw new RouteDockSessionError(`SessionStore.upsert failed: ${error.message}`);
+      throw new RouteDockNetworkError(`SessionStore.upsert failed: ${error.message}`);
+    }
+  }
+  async setStatus(channelId, status, settlementTxHash) {
+    const payload = {
+      status,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (settlementTxHash !== void 0) {
+      payload.settlement_tx_hash = settlementTxHash;
+    }
+    const { error } = await this.supabase.from("sessions").update(payload).eq("channel_id", channelId);
+    if (error) {
+      throw new RouteDockNetworkError(`SessionStore.setStatus 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}`);
+    await this.setStatus(channelId, "closed");
+  }
+};
+
+// src/store/SupabaseSeenTxStore.ts
+var SupabaseSeenTxStore = class {
+  constructor(supabase) {
+    this.supabase = supabase;
+  }
+  supabase;
+  async get(key) {
+    const { data, error } = await this.supabase.from("settlements").select("tx_hash, headers").eq("key", key).maybeSingle();
+    if (error) {
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.get failed: ${error.message}`);
+    }
+    if (!data) return void 0;
+    const headers = data.headers;
+    return {
+      txHash: data.tx_hash ?? null,
+      ...headers ? { headers } : {}
+    };
+  }
+  async set(key, record) {
+    const { error } = await this.supabase.from("settlements").upsert(
+      {
+        key,
+        tx_hash: record.txHash,
+        headers: record.headers ?? null
+      },
+      { onConflict: "key" }
+    );
+    if (error) {
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.set failed: ${error.message}`);
+    }
   }
 };
 
-export { RouteDockError, RouteDockManifestError, RouteDockNoSupportedModeError, RouteDockPolicyRejectedError, RouteDockSessionError, SupabaseSessionStore, createMppChargeHandler, createMppSessionHandler, createX402Handler, routedock };
+export { DEFAULT_MAX_SESSION_DURATION_MS, InMemorySeenTxStore, RouteDockChannelStateError, RouteDockClientVersionError, RouteDockDisputeError, RouteDockError, RouteDockFacilitatorError, RouteDockManifestError, RouteDockNetworkError, RouteDockNoSupportedModeError, RouteDockPolicyRejectError, RouteDockPolicyRejectedError, RouteDockRefundWindowError, RouteDockSessionError, RouteDockSignatureError, RouteDockTrustlineError, RouteDockVoucherMonotonicityError, SupabaseSeenTxStore, SupabaseSessionStore, createMppChargeHandler, createMppSessionHandler, createX402Handler, decimalToStroops, isVoucherStoreValue, paymentIdempotencyKey, reconcileAbandonedSessions, registerProvider, routedock, runStartupReconciliation };