create-mantle-facilitator 0.3.5 → 0.4.1

package/README.md

@@ -37,6 +37,7 @@ After creation, edit the `.env` file:
 # Required
 FACILITATOR_PRIVATE_KEY=0x...   # Wallet that pays gas fees
 RPC_URL=https://rpc.mantle.xyz  # Mantle RPC endpoint
+FACILITATOR_SECRET=fac_xxx...   # Auto-generated security secret
 
 # Optional
 USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
@@ -51,8 +52,28 @@ TELEMETRY_PROJECT_KEY=pk_xxx    # Get from dashboard
 ### Important Notes
 
 - **FACILITATOR_PRIVATE_KEY**: This wallet will pay gas fees for all settlements. Make sure it has MNT for gas.
+- **FACILITATOR_SECRET**: Auto-generated during setup. **Copy this to your backend's environment variables** to enable secure authentication.
 - **Security**: Never commit `.env` to version control. The generated `.gitignore` already excludes it.
 
+### Connecting to Your Backend
+
+Add `FACILITATOR_SECRET` to your backend and configure the SDK:
+
+```typescript
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
+
+// Self-hosted facilitator (requires facilitatorUrl + facilitatorSecret)
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWallet',
+  facilitatorUrl: 'https://your-facilitator.com', // Required for self-hosted
+  facilitatorSecret: process.env.FACILITATOR_SECRET!, // Required for self-hosted
+  // projectKey: process.env.PROJECT_KEY, // Optional: for analytics
+});
+```
+
+**Note:** When using `facilitatorSecret` (self-hosted mode), `facilitatorUrl` is required. The URL is automatically passed to clients via 402 responses, so frontend code doesn't need to configure it.
+
 ## Running Locally
 
 ```bash
@@ -221,7 +242,7 @@ curl -X POST http://localhost:8080/verify \
 
 ### POST /settle
 
-Executes the USDC transfer on-chain.
+Executes the USDC transfer on-chain. Requires a valid `settleToken` for authentication.
 
 ```bash
 curl -X POST http://localhost:8080/settle \
@@ -229,7 +250,8 @@ curl -X POST http://localhost:8080/settle \
   -d '{
     "x402Version": 1,
     "paymentHeader": "base64...",
-    "paymentRequirements": {...}
+    "paymentRequirements": {...},
+    "settleToken": "base64..."
   }'
 ```
 
@@ -240,6 +262,8 @@ curl -X POST http://localhost:8080/settle \
 }
 ```
 
+**Note:** The `settleToken` is automatically generated by the SDK when `facilitatorSecret` is configured, and passed through the client to authenticate with your facilitator.
+
 ---
 
 ## How It Works
@@ -298,17 +322,23 @@ Telemetry errors never affect payment processing — if analytics backend is dow
 
 ## Security Considerations
 
-1. **Private Key Security**
+1. **Facilitator Secret (REQUIRED)**
+   - `FACILITATOR_SECRET` prevents unauthorized usage of your facilitator
+   - Without it, anyone could use your facilitator URL to settle their payments and drain your gas wallet
+   - The secret creates a secure token flow: Backend → Client → Facilitator
+   - Always set `facilitatorSecret` in your backend SDK configuration
+
+2. **Private Key Security**
    - Never commit `.env` to git
    - Use secret management in production (Railway secrets, Fly secrets, etc.)
    - Consider using hardware wallets for high-value facilitators
 
-2. **Gas Management**
+3. **Gas Management**
    - Monitor MNT balance regularly
    - Set up alerts for low balance
    - Facilitator needs ~0.001 MNT per settlement
 
-3. **Network Security**
+4. **Network Security**
    - Use HTTPS in production
    - Consider rate limiting
    - Monitor for unusual patterns

package/dist/index.mjs

@@ -3,9 +3,13 @@
 // src/index.ts
 import path from "path";
 import fs from "fs";
+import crypto from "crypto";
 import { fileURLToPath } from "url";
 import fse from "fs-extra";
 import prompts from "prompts";
+function generateFacilitatorSecret() {
+  return "fac_" + crypto.randomBytes(32).toString("hex");
+}
 function getAsciiArt() {
   const asciiArtPath = path.join(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -94,6 +98,7 @@ async function promptSetup() {
   });
 }
 function generateEnvFile(answers) {
+  const facilitatorSecret = generateFacilitatorSecret();
   const env = [
     `# Server Configuration`,
     `PORT=8080`,
@@ -110,6 +115,10 @@ function generateEnvFile(answers) {
     `# Facilitator Wallet (keeps private key safe)`,
     answers.privateKey ? `FACILITATOR_PRIVATE_KEY=${answers.privateKey}` : `# FACILITATOR_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE`,
     ``,
+    `# Security: Shared secret between your backend and this facilitator`,
+    `# IMPORTANT: Copy this value to your backend's facilitatorSecret config`,
+    `FACILITATOR_SECRET=${facilitatorSecret}`,
+    ``,
     `# Logging`,
     `LOG_LEVEL=info`,
     ``
@@ -167,6 +176,7 @@ Creating facilitator in ${targetDir}...`);
   if (!answers.privateKey) {
     reminders.push("IMPORTANT: Set FACILITATOR_PRIVATE_KEY in .env before starting");
   }
+  reminders.push("IMPORTANT: Copy FACILITATOR_SECRET from .env to your backend configuration");
   if (answers.enableTelemetry && !answers.telemetryKey) {
     reminders.push("Telemetry enabled: Get PROJECT_KEY from https://x402mantlesdk.xyz/dashboard");
   }
@@ -210,6 +220,7 @@ async function createProjectNonInteractive(projectName) {
   await fse.writeFile(path.join(targetDir, ".env"), envContent);
   console.log("\n\u2713 Done!\n");
   console.log("IMPORTANT: Edit .env file and set FACILITATOR_PRIVATE_KEY");
+  console.log("IMPORTANT: Copy FACILITATOR_SECRET from .env to your backend configuration");
   console.log(`Then run: cd ${projectName} && npm install && npm run dev`);
 }
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mantle-facilitator",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "bin": {

package/template/README.md

@@ -24,6 +24,7 @@ Edit `.env` file:
 # Required
 FACILITATOR_PRIVATE_KEY=0x...   # Wallet that pays gas
 RPC_URL=https://rpc.mantle.xyz
+FACILITATOR_SECRET=fac_xxx...   # Auto-generated, share with your backend
 
 # Optional
 PORT=8080
@@ -33,7 +34,36 @@ USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9
 TELEMETRY_PROJECT_KEY=pk_xxx    # Get from https://x402mantlesdk.xyz/dashboard
 ```
 
-**Important:** The facilitator wallet needs MNT for gas fees. Check balance at `/health`.
+**Important:**
+- The facilitator wallet needs MNT for gas fees. Check balance at `/health`.
+- Copy `FACILITATOR_SECRET` to your backend's environment variables.
+
+## Security
+
+The `FACILITATOR_SECRET` protects your facilitator from unauthorized usage:
+
+1. Your backend generates a `settleToken` using this secret when returning 402 responses
+2. The client passes this token to your facilitator's `/settle` endpoint
+3. The facilitator verifies the token matches before executing the transaction
+
+This prevents third parties from using your facilitator to settle their payments and drain your gas wallet.
+
+**Backend configuration:**
+
+```typescript
+import { mantlePaywall } from '@puga-labs/x402-mantle-sdk/server/express';
+
+// Self-hosted facilitator (requires facilitatorUrl + facilitatorSecret)
+const pay = mantlePaywall({
+  priceUsd: 0.01,
+  payTo: '0xYourWallet',
+  facilitatorUrl: 'https://your-facilitator.com', // Required for self-hosted
+  facilitatorSecret: process.env.FACILITATOR_SECRET!, // Required for self-hosted
+  // projectKey: process.env.PROJECT_KEY, // Optional: for analytics
+});
+```
+
+**Note:** When using `facilitatorSecret`, `facilitatorUrl` is required. The URL is automatically passed to clients via 402 responses.
 
 ## Endpoints
 

package/template/src/config.ts

@@ -1,24 +1,136 @@
 // src/config.ts
 import "dotenv/config";
+import { ethers } from "ethers";
 import { DEFAULT_TELEMETRY_ENDPOINT } from "./constants";
 
-function required(name: string): string {
-  const v = process.env[name];
-  if (!v) throw new Error(`Missing env var: ${name}`);
-  return v;
+// ============================================
+// Validation types and helpers
+// ============================================
+
+interface ConfigError {
+  field: string;
+  message: string;
+  howToFix: string[];
+}
+
+function validateConfig(): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // Required: FACILITATOR_PRIVATE_KEY
+  const privateKey = process.env.FACILITATOR_PRIVATE_KEY;
+  if (!privateKey) {
+    errors.push({
+      field: "FACILITATOR_PRIVATE_KEY",
+      message: "This is the wallet that will pay gas fees for settlements.",
+      howToFix: [
+        "Open .env file",
+        "Set FACILITATOR_PRIVATE_KEY=0xYourPrivateKey",
+        "Need a wallet? Create one at https://metamask.io",
+        "Make sure it has MNT for gas fees.",
+      ],
+    });
+  } else if (!privateKey.startsWith("0x") || privateKey.length !== 66) {
+    errors.push({
+      field: "FACILITATOR_PRIVATE_KEY",
+      message: "Invalid private key format.",
+      howToFix: [
+        "Private key must start with 0x",
+        "Private key must be 66 characters (0x + 64 hex digits)",
+        `Current length: ${privateKey.length} characters`,
+      ],
+    });
+  }
+
+  // Required: FACILITATOR_SECRET
+  const secret = process.env.FACILITATOR_SECRET;
+  if (!secret) {
+    errors.push({
+      field: "FACILITATOR_SECRET",
+      message: "This secret authenticates your backend with the facilitator.",
+      howToFix: [
+        "Open .env file",
+        "Set FACILITATOR_SECRET=fac_YOUR_SECRET_HERE",
+        "Then copy this value to your backend's facilitatorSecret config",
+      ],
+    });
+  }
+
+  // Required: RPC_URL
+  if (!process.env.RPC_URL) {
+    errors.push({
+      field: "RPC_URL",
+      message: "RPC URL for connecting to Mantle network.",
+      howToFix: [
+        "Open .env file",
+        "Set RPC_URL=https://rpc.mantle.xyz",
+      ],
+    });
+  }
+
+  // Required: USDC_ADDRESS
+  if (!process.env.USDC_ADDRESS) {
+    errors.push({
+      field: "USDC_ADDRESS",
+      message: "USDC contract address on Mantle.",
+      howToFix: [
+        "Open .env file",
+        "Set USDC_ADDRESS=0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9",
+      ],
+    });
+  }
+
+  return errors;
+}
+
+function printConfigErrors(errors: ConfigError[]): void {
+  console.error("");
+  console.error("CONFIGURATION ERROR");
+  console.error("=".repeat(50));
+
+  for (const error of errors) {
+    console.error("");
+    console.error(`Missing: ${error.field}`);
+    console.error(`${error.message}`);
+    console.error("");
+    console.error("To fix:");
+    error.howToFix.forEach((step, i) => {
+      console.error(`  ${i + 1}. ${step}`);
+    });
+  }
+
+  console.error("");
+  console.error("=".repeat(50));
+  console.error("");
+}
+
+// ============================================
+// Run validation at startup
+// ============================================
+
+const configErrors = validateConfig();
+if (configErrors.length > 0) {
+  printConfigErrors(configErrors);
+  process.exit(1);
 }
 
+// ============================================
+// Build config (all required fields are validated)
+// ============================================
+
 export const CONFIG = {
   port: Number(process.env.PORT ?? 8080),
 
   networkId: process.env.NETWORK_ID ?? "mantle-mainnet",
   chainId: Number(process.env.CHAIN_ID ?? 5000),
-  rpcUrl: required("RPC_URL"),
+  rpcUrl: process.env.RPC_URL!,
 
-  usdcAddress: required("USDC_ADDRESS"),
+  usdcAddress: process.env.USDC_ADDRESS!,
   usdcDecimals: Number(process.env.USDC_DECIMALS ?? 6),
 
-  facilitatorPrivateKey: required("FACILITATOR_PRIVATE_KEY"),
+  facilitatorPrivateKey: process.env.FACILITATOR_PRIVATE_KEY!,
+
+  // Secret for settle token verification (required for security)
+  facilitatorSecret: process.env.FACILITATOR_SECRET!,
 
   logLevel: process.env.LOG_LEVEL ?? "info",
 
@@ -30,3 +142,12 @@ export const CONFIG = {
       }
     : undefined,
 } as const;
+
+// ============================================
+// Derive facilitator address from private key
+// ============================================
+
+export function getFacilitatorAddress(): string {
+  const wallet = new ethers.Wallet(CONFIG.facilitatorPrivateKey);
+  return wallet.address;
+}

package/template/src/index.ts

@@ -1,7 +1,7 @@
 // src/index.ts
 import express from "express";
 import cors from "cors";
-import { CONFIG } from "./config";
+import { CONFIG, getFacilitatorAddress } from "./config";
 
 import { healthRoute } from "./routes/health";
 import { supportedRoute } from "./routes/supported";
@@ -25,7 +25,36 @@ app.get("/supported", supportedRoute);
 app.post("/verify", verifyRoute);
 app.post("/settle", settleRoute);
 
+// ============================================
+// Startup banner
+// ============================================
+
+function printStartupBanner(): void {
+  const address = getFacilitatorAddress();
+  const shortAddress = `${address.slice(0, 6)}...${address.slice(-4)}`;
+  const telemetryStatus = CONFIG.telemetry ? "enabled" : "disabled";
+
+  console.log("");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log("|  Mantle x402 Facilitator".padEnd(50) + "|");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log(`|  Network:     ${CONFIG.networkId} (${CONFIG.chainId})`.padEnd(50) + "|");
+  console.log(`|  Address:     ${shortAddress}`.padEnd(50) + "|");
+  console.log(`|  Port:        ${CONFIG.port}`.padEnd(50) + "|");
+  console.log(`|  Telemetry:   ${telemetryStatus}`.padEnd(50) + "|");
+  console.log("+".padEnd(50, "-") + "+");
+  console.log("");
+
+  // Telemetry warning
+  if (!CONFIG.telemetry) {
+    console.log("Note: Telemetry is disabled.");
+    console.log("  To enable analytics, set TELEMETRY_PROJECT_KEY in .env");
+    console.log("  Get your key at https://x402mantlesdk.xyz/dashboard");
+    console.log("");
+  }
+}
+
 app.listen(CONFIG.port, () => {
-  console.log(`Facilitator server listening on http://localhost:${CONFIG.port}`);
-  console.log(`Network: ${CONFIG.networkId} (chainId=${CONFIG.chainId})`);
+  printStartupBanner();
+  console.log(`Server listening on http://localhost:${CONFIG.port}`);
 });

package/template/src/routes/settle.ts

@@ -4,6 +4,7 @@ import { ethers } from "ethers";
 import { decodePaymentHeader, verifyPayment, type PaymentRequirements } from "../x402";
 import { getFacilitatorSigner, getUsdcContract } from "../blockchain";
 import { CONFIG } from "../config";
+import { verifySettleToken } from "../security";
 
 function signatureToVRS(signature: string) {
   const sig = ethers.Signature.from(signature);
@@ -15,10 +16,11 @@ export async function settleRoute(req: Request, res: Response) {
   const raw = req.body ?? {};
 
   try {
-    const { x402Version, paymentHeader, paymentRequirements } = raw as {
+    const { x402Version, paymentHeader, paymentRequirements, settleToken } = raw as {
       x402Version?: number;
       paymentHeader?: string;
       paymentRequirements?: PaymentRequirements;
+      settleToken?: string;
     };
     const projectKey = req.header("X-Project-Key"); // Optional: for hosted facilitator billing
 
@@ -47,6 +49,18 @@ export async function settleRoute(req: Request, res: Response) {
       return;
     }
 
+    // Verify settle token (required for self-hosted facilitator security)
+    const tokenVerification = verifySettleToken(settleToken, paymentRequirements, CONFIG.facilitatorSecret);
+    if (!tokenVerification.valid) {
+      res.status(401).json({
+        success: false,
+        error: tokenVerification.error || "Invalid settle token",
+        txHash: null,
+        networkId: paymentRequirements.network,
+      });
+      return;
+    }
+
     const headerObj = decodePaymentHeader(paymentHeader);
     const verify = verifyPayment(headerObj, paymentRequirements);
 

package/template/src/security.ts

@@ -0,0 +1,126 @@
+// src/security.ts
+import crypto from "crypto";
+
+export interface PaymentRequirementsForToken {
+  payTo: string;
+  maxAmountRequired: string;
+  asset: string;
+  network: string;
+}
+
+interface SettleTokenPayload {
+  payTo: string;
+  amount: string;
+  asset: string;
+  network: string;
+  timestamp: number;
+  expires: number;
+}
+
+interface DecodedSettleToken {
+  payload: SettleTokenPayload;
+  signature: string;
+}
+
+/**
+ * Creates a settle token that authorizes a specific payment.
+ * The token is signed with HMAC-SHA256 and includes expiration.
+ *
+ * @param paymentRequirements - The payment requirements to authorize
+ * @param secret - The FACILITATOR_SECRET
+ * @param expiresInSeconds - Token validity period (default: 600 seconds = 10 minutes)
+ * @returns Base64-encoded settle token
+ */
+export function createSettleToken(
+  paymentRequirements: PaymentRequirementsForToken,
+  secret: string,
+  expiresInSeconds: number = 600
+): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  const payload: SettleTokenPayload = {
+    payTo: paymentRequirements.payTo.toLowerCase(),
+    amount: paymentRequirements.maxAmountRequired,
+    asset: paymentRequirements.asset.toLowerCase(),
+    network: paymentRequirements.network,
+    timestamp,
+    expires: timestamp + expiresInSeconds,
+  };
+
+  const data = JSON.stringify(payload);
+  const signature = crypto.createHmac("sha256", secret).update(data).digest("hex");
+
+  return Buffer.from(JSON.stringify({ payload, signature })).toString("base64");
+}
+
+/**
+ * Verifies a settle token against payment requirements.
+ * Checks signature, expiration, and that the token matches the requirements.
+ *
+ * @param token - Base64-encoded settle token
+ * @param paymentRequirements - The payment requirements to verify against
+ * @param secret - The FACILITATOR_SECRET
+ * @returns true if token is valid, false otherwise
+ */
+export function verifySettleToken(
+  token: string | undefined,
+  paymentRequirements: PaymentRequirementsForToken,
+  secret: string
+): { valid: boolean; error?: string } {
+  if (!token) {
+    return { valid: false, error: "Missing settle token" };
+  }
+
+  try {
+    const decoded: DecodedSettleToken = JSON.parse(
+      Buffer.from(token, "base64").toString("utf-8")
+    );
+    const { payload, signature } = decoded;
+
+    // Check expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.expires < now) {
+      return { valid: false, error: "Settle token expired" };
+    }
+
+    // Check that token matches payment requirements (case-insensitive for addresses)
+    if (payload.payTo.toLowerCase() !== paymentRequirements.payTo.toLowerCase()) {
+      return { valid: false, error: "PayTo address mismatch" };
+    }
+
+    if (payload.amount !== paymentRequirements.maxAmountRequired) {
+      return { valid: false, error: "Amount mismatch" };
+    }
+
+    if (payload.asset.toLowerCase() !== paymentRequirements.asset.toLowerCase()) {
+      return { valid: false, error: "Asset mismatch" };
+    }
+
+    if (payload.network !== paymentRequirements.network) {
+      return { valid: false, error: "Network mismatch" };
+    }
+
+    // Verify signature
+    const data = JSON.stringify(payload);
+    const expectedSignature = crypto
+      .createHmac("sha256", secret)
+      .update(data)
+      .digest("hex");
+
+    if (signature !== expectedSignature) {
+      return { valid: false, error: "Invalid signature" };
+    }
+
+    return { valid: true };
+  } catch (err) {
+    return { valid: false, error: "Invalid token format" };
+  }
+}
+
+/**
+ * Generates a random secret for FACILITATOR_SECRET.
+ * Format: fac_<64 hex characters>
+ */
+export function generateFacilitatorSecret(): string {
+  return "fac_" + crypto.randomBytes(32).toString("hex");
+}