@railbridgeai/merchant-sdk 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @railbridgeai/merchant-sdk
+
+Merchant-first server SDK for RailBridge.
+
+Goal:
+1. Protect paid routes with one middleware.
+2. Keep merchant business logic unchanged.
+3. Verify webhook signatures with one helper.
+
+## Install
+
+```bash
+npm install @railbridgeai/merchant-sdk
+```
+
+Repo contributor note:
+1. In this repository, `facilitator` consumes the SDK through a local `file:` dependency.
+2. Running `npm --prefix facilitator install` also creates `packages/node_modules -> facilitator/node_modules` for local dependency resolution.
+3. Use the facilitator npm scripts for local smoke tests; you do not need a separate `npm install` inside `packages/server-sdk` for the linked-package path.
+
+Release workflow:
+1. Bump the version in `packages/server-sdk/package.json`.
+2. Push a tag like `sdk-v0.1.0-beta.1`.
+3. GitHub Actions publishes the package to the npm registry as `public`.
+
+## Quick Start (Express)
+
+```ts
+import express from "express";
+import { createRailbridgeFromEnv } from "@railbridgeai/merchant-sdk";
+
+const app = express();
+const rb = createRailbridgeFromEnv(process.env);
+
+const start = async () => {
+  await rb.protectExpress(
+    app,
+    {
+      apiId: "premium_api",
+      method: "GET",
+      path: "/api/premium",
+    },
+    async (req, res) => {
+      // Keep business logic here.
+      const payload = await buildPremiumPayload(req.user);
+      res.json(payload);
+    },
+  );
+
+  app.listen(4021);
+};
+
+start().catch(console.error);
+```
+
+Alternative env-first bootstrap:
+
+```ts
+import { createRailbridge } from "@railbridgeai/merchant-sdk";
+
+const rb = createRailbridge({
+  apiKey: process.env.RB_API_KEY,
+  environment: "testnet",
+});
+```
+
+In the normal hosted RailBridge flow, merchants should only need:
+1. `RB_API_KEY`
+2. `RB_ENV` (`local`, `testnet`, or `live`)
+
+The SDK chooses RailBridge-managed URLs automatically from the environment.
+
+## Webhook Verification
+
+```ts
+import express from "express";
+import { createRailbridgeFromEnv } from "@railbridgeai/merchant-sdk";
+
+const app = express();
+const rb = createRailbridgeFromEnv(process.env);
+
+// Keep raw payload for signature verification.
+app.use("/webhooks/railbridge", express.text({ type: "application/json" }));
+
+app.post(
+  "/webhooks/railbridge",
+  rb.webhooks.express({
+    secret: process.env.RB_WEBHOOK_SECRET,
+    onEvent: async (event) => {
+      // idempotent async processing
+      console.log("railbridge webhook", event.type, event.id);
+    },
+  }),
+);
+```
+
+## Merchant Env Vars
+
+```env
+RB_API_KEY=rb_...
+RB_WEBHOOK_SECRET=whsec_...
+RB_ENV=testnet
+```
+
+Advanced overrides:
+
+```env
+RB_MERCHANT_OS_URL=https://api.testnet.railbridge.ai
+RB_FACILITATOR_URL=https://facilitator.testnet.railbridge.ai
+```
+
+Only use these overrides if:
+1. you are developing against local/self-hosted RailBridge services
+2. RailBridge support asked you to target a non-standard endpoint
+
+## API Summary
+
+1. `createRailbridge(config)`
+2. `createRailbridgeFromEnv(process.env)`
+3. `client.protect(routeConfig)` -> Express middleware
+4. `client.protectExpress(app, routeConfig, handler)` -> lowest-friction Express helper
+5. `client.resolveRequirements(...)`
+6. `client.webhooks.verify(...)`
+7. `client.webhooks.express(...)`
+
+## Notes
+
+1. This SDK abstracts payment requirement resolution and verify/settle wiring.
+2. Merchant handlers should only contain business logic.
+3. Do not call RailBridge internal endpoints (`/v1/internal/*`) from merchant apps.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@railbridgeai/merchant-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "RailBridge SDK for merchant API protection and webhook verification",
+  "scripts": {
+    "check": "node --check src/index.js && node --check src/paymentGuard.js && node --check src/webhooks.js",
+    "test": "node --test \"tests/**/*.test.js\"",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:public:dry-run": "npm publish --access public --dry-run"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarcoBrian/RailBridge.git",
+    "directory": "packages/server-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/MarcoBrian/RailBridge/issues"
+  },
+  "homepage": "https://github.com/MarcoBrian/RailBridge/tree/testnet/packages/server-sdk",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@x402/core": "^2.12.0",
+    "@x402/evm": "^2.12.0",
+    "@x402/express": "^2.12.0",
+    "@x402/paywall": "^2.12.0"
+  },
+  "keywords": [
+    "railbridge",
+    "x402",
+    "merchant",
+    "sdk"
+  ],
+  "license": "MIT"
+}

package/src/crossChain.js

@@ -0,0 +1,32 @@
+export const CROSS_CHAIN = "cross-chain";
+
+export const declareCrossChainExtension = ({
+  destinationNetwork,
+  destinationAsset,
+  destinationPayTo,
+}) => ({
+  info: {
+    destinationNetwork,
+    destinationAsset,
+    destinationPayTo,
+  },
+  schema: {
+    type: "object",
+    properties: {
+      destinationNetwork: {
+        type: "string",
+        pattern: "^eip155:\\d+$",
+      },
+      destinationAsset: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{40}$",
+      },
+      destinationPayTo: {
+        type: "string",
+        pattern: "^0x[a-fA-F0-9]{40}$",
+      },
+    },
+    required: ["destinationNetwork", "destinationAsset", "destinationPayTo"],
+    additionalProperties: false,
+  },
+});

package/src/index.d.ts

@@ -0,0 +1,110 @@
+type RequestHandler = (...args: any[]) => any;
+type ExpressLikeApp = Record<string, any>;
+
+export type RailbridgeEnvironment = "local" | "testnet" | "live" | "mainnet" | "production" | "prod";
+export type RailbridgeLogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
+export type RailbridgeLogger = {
+  debug?: (...args: any[]) => void;
+  info?: (...args: any[]) => void;
+  warn?: (...args: any[]) => void;
+  error?: (...args: any[]) => void;
+};
+
+export type RailbridgeAdvancedConfig = {
+  merchantOsUrl?: string;
+  facilitatorUrl?: string;
+  paywallTestnet?: boolean;
+  sourceNetworkFilter?: "all" | "testnet_only" | "mainnet_only";
+  maxRequirementOptions?: number;
+  autoRefreshMs?: number;
+  logPrefix?: string;
+  paywallAppName?: string;
+  supportedSourceNetworks?: string[];
+  logger?: RailbridgeLogger;
+  logLevel?: RailbridgeLogLevel;
+};
+
+export type RailbridgeBaseConfig = {
+  apiKey: string;
+  environment?: RailbridgeEnvironment;
+  advanced?: RailbridgeAdvancedConfig;
+} & Partial<RailbridgeAdvancedConfig>;
+
+export type RailbridgeFromEnvOverrides = Partial<RailbridgeBaseConfig>;
+
+export type RailbridgeProtectConfig = {
+  method?: string;
+  path: string;
+  apiId?: string;
+  apiProductId?: string;
+  settlementModeOverride?: "same_chain" | "cross_chain";
+  advanced?: RailbridgeAdvancedConfig;
+} & Partial<RailbridgeAdvancedConfig>;
+
+export type RailbridgeGuardMiddleware = RequestHandler & {
+  routeMethod?: string;
+  routePath?: string;
+  refreshRequirements?: () => Promise<unknown>;
+  getCurrentRouteInfo?: () => unknown;
+  startAutoRefresh?: () => void;
+  stopAutoRefresh?: () => void;
+};
+
+export type ResolveRequirementsInput = {
+  apiId?: string;
+  apiProductId?: string;
+  method?: string;
+  path: string;
+  settlementModeOverride?: "same_chain" | "cross_chain";
+};
+
+export type GetOnboardingStatusInput = {
+  merchantOsUrl?: string;
+  token: string;
+};
+
+export type WebhookVerifyInput = {
+  secret: string;
+  timestamp: string;
+  payload: string | Record<string, unknown>;
+  signature: string;
+};
+
+export type ExpressWebhookHandlerInput = {
+  secret?: string;
+  requireSignature?: boolean;
+  onEvent?: (event: any, context: { headers: Record<string, unknown>; eventType: string | null; eventId: string | null }) => Promise<void> | void;
+};
+
+export type RailbridgeClient = {
+  environment: "local" | "testnet" | "live";
+  merchantOsUrl: string;
+  facilitatorUrl: string;
+  resolveRequirements: (input: ResolveRequirementsInput) => Promise<any>;
+  getOnboardingStatus: (input: GetOnboardingStatusInput) => Promise<any>;
+  protect: (routeConfig: RailbridgeProtectConfig) => Promise<RailbridgeGuardMiddleware>;
+  protectExpress: (
+    app: ExpressLikeApp,
+    routeConfig: RailbridgeProtectConfig,
+    ...handlers: RequestHandler[]
+  ) => Promise<RailbridgeGuardMiddleware>;
+  webhooks: {
+    verify: (input: WebhookVerifyInput) => boolean;
+    express: (input?: ExpressWebhookHandlerInput) => RequestHandler;
+  };
+};
+
+export function createRailbridge(config: RailbridgeBaseConfig): RailbridgeClient;
+export function createRailbridgeFromEnv(
+  env?: Record<string, string | undefined>,
+  overrides?: RailbridgeFromEnvOverrides,
+): RailbridgeClient;
+export function getOnboardingStatus(input: {
+  merchantOsUrl: string;
+  token: string;
+}): Promise<any>;
+
+export function createRailbridgePaymentGuard(config: any): Promise<any>;
+export function createExpressWebhookHandler(input?: ExpressWebhookHandlerInput): RequestHandler;
+export function verifyWebhook(input: WebhookVerifyInput): boolean;

package/src/index.js

@@ -0,0 +1,370 @@
+import { createExpressWebhookHandler, verifyWebhook } from "./webhooks.js";
+
+const ENVIRONMENT_DEFAULTS = {
+  local: {
+    merchantOsUrl: "http://localhost:4030",
+    facilitatorUrl: "http://localhost:4022",
+    paywallTestnet: true,
+    sourceNetworkFilter: "all",
+  },
+  testnet: {
+    merchantOsUrl: "https://api.testnet.railbridge.ai",
+    facilitatorUrl: "https://facilitator.testnet.railbridge.ai",
+    paywallTestnet: true,
+    sourceNetworkFilter: "testnet_only",
+  },
+  live: {
+    merchantOsUrl: "https://api.railbridge.xyz",
+    facilitatorUrl: "https://facilitator.railbridge.xyz",
+    paywallTestnet: false,
+    sourceNetworkFilter: "all",
+  },
+};
+
+const normalizeEnvironment = (value) => {
+  const normalized = String(value || "testnet").trim().toLowerCase();
+  if (normalized === "mainnet" || normalized === "production" || normalized === "prod") {
+    return "live";
+  }
+  if (normalized === "dev") {
+    return "local";
+  }
+  if (!["local", "testnet", "live"].includes(normalized)) {
+    throw new Error("environment must be one of: local, testnet, live");
+  }
+  return normalized;
+};
+
+const normalizeMethod = (method) => {
+  const value = String(method || "").trim().toUpperCase();
+  return value || "GET";
+};
+
+const normalizePath = (path, fieldName = "path") => {
+  const value = String(path || "").trim();
+  if (!value) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return value.startsWith("/") ? value : `/${value}`;
+};
+
+const ensureNonEmpty = (value, fieldName) => {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return text;
+};
+
+const parseBoolean = (value, fieldName) => {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "y", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "n", "off"].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`${fieldName} must be a boolean-like value`);
+};
+
+const parseOptionalFiniteNumber = (value, fieldName) => {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${fieldName} must be a finite number`);
+  }
+  return parsed;
+};
+
+const resolveEnvironmentInput = (value, fieldName = "environment") => {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return normalizeEnvironment(text);
+};
+
+const readAdvanced = (config = {}) => {
+  if (!config.advanced || typeof config.advanced !== "object") {
+    return {};
+  }
+  return config.advanced;
+};
+
+const mergeDefaults = (config = {}) => {
+  const advanced = readAdvanced(config);
+  const environment = normalizeEnvironment(config.environment || "testnet");
+  const defaults = ENVIRONMENT_DEFAULTS[environment];
+
+  return {
+    environment,
+    apiKey: ensureNonEmpty(config.apiKey, "apiKey"),
+    merchantOsUrl: String(
+      advanced.merchantOsUrl || config.merchantOsUrl || defaults.merchantOsUrl,
+    ).trim(),
+    facilitatorUrl: String(
+      advanced.facilitatorUrl || config.facilitatorUrl || defaults.facilitatorUrl,
+    ).trim(),
+    paywallTestnet:
+      typeof advanced.paywallTestnet === "boolean"
+        ? advanced.paywallTestnet
+        : typeof config.paywallTestnet === "boolean"
+          ? config.paywallTestnet
+        : defaults.paywallTestnet,
+    sourceNetworkFilter:
+      advanced.sourceNetworkFilter || config.sourceNetworkFilter || defaults.sourceNetworkFilter,
+    maxRequirementOptions: advanced.maxRequirementOptions ?? config.maxRequirementOptions,
+    autoRefreshMs: advanced.autoRefreshMs ?? config.autoRefreshMs,
+    logPrefix: advanced.logPrefix || config.logPrefix || "[railbridge-sdk]",
+    paywallAppName:
+      advanced.paywallAppName || config.paywallAppName || "RailBridge Merchant Integration",
+    supportedSourceNetworks: advanced.supportedSourceNetworks || config.supportedSourceNetworks,
+    logger: advanced.logger || config.logger || console,
+    logLevel: advanced.logLevel || config.logLevel || "warn",
+  };
+};
+
+const mountProtectedRoute = (app, method, path, middleware, handlers) => {
+  if (!app || (typeof app !== "object" && typeof app !== "function")) {
+    throw new Error("protectExpress(...) requires an Express app instance");
+  }
+
+  const normalizedMethod = String(method || "GET").trim().toLowerCase();
+  const normalizedPath = normalizePath(path, "routeConfig.path");
+  const normalizedHandlers = handlers.filter(Boolean);
+
+  if (!normalizedHandlers.length) {
+    throw new Error("protectExpress(...) requires at least one route handler");
+  }
+
+  if (typeof app[normalizedMethod] === "function") {
+    app[normalizedMethod](normalizedPath, middleware, ...normalizedHandlers);
+    return;
+  }
+
+  if (typeof app.all === "function") {
+    app.all(normalizedPath, middleware, ...normalizedHandlers);
+    return;
+  }
+
+  throw new Error(`protectExpress(...) could not find app.${normalizedMethod}(...) or app.all(...)`);
+};
+
+const resolveOnboardingStatus = async ({ merchantOsUrl, token }) => {
+  const response = await fetch(`${merchantOsUrl.replace(/\/$/, "")}/v1/onboarding/checklist`, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${token}`,
+    },
+  });
+
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(payload.error || `onboarding status failed (${response.status})`);
+  }
+  return payload;
+};
+
+const resolveRequirements = async ({
+  merchantOsUrl,
+  apiKey,
+  apiId,
+  apiProductId,
+  method = "GET",
+  path,
+  settlementModeOverride,
+}) => {
+  const response = await fetch(`${merchantOsUrl.replace(/\/$/, "")}/v1/sdk/requirements/resolve`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-railbridge-api-key": apiKey,
+    },
+    body: JSON.stringify({
+      apiId,
+      apiProductId,
+      method: String(method || "GET").trim().toUpperCase(),
+      path,
+      settlementModeOverride,
+    }),
+  });
+
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(payload.error || `resolve requirements failed (${response.status})`);
+  }
+  return payload;
+};
+
+export const createRailbridge = (config = {}) => {
+  const base = mergeDefaults(config);
+  const client = {
+    environment: base.environment,
+    merchantOsUrl: base.merchantOsUrl,
+    facilitatorUrl: base.facilitatorUrl,
+
+    async resolveRequirements(input = {}) {
+      const method = input.method || "GET";
+      const path = String(input.path || "").trim();
+      if (!path) {
+        throw new Error("path is required");
+      }
+
+      return resolveRequirements({
+        merchantOsUrl: base.merchantOsUrl,
+        apiKey: base.apiKey,
+        apiId: input.apiId,
+        apiProductId: input.apiProductId,
+        method,
+        path,
+        settlementModeOverride: input.settlementModeOverride,
+      });
+    },
+
+    async getOnboardingStatus(input = {}) {
+      const token = ensureNonEmpty(input.token, "token");
+      const merchantOsUrl = String(input.merchantOsUrl || base.merchantOsUrl).trim();
+      return resolveOnboardingStatus({ merchantOsUrl, token });
+    },
+
+    async protect(routeConfig = {}) {
+      const advanced = readAdvanced(routeConfig);
+      const method = normalizeMethod(routeConfig.method || "GET");
+      const path = normalizePath(routeConfig.path, "routeConfig.path");
+
+      const guard = await createRailbridgePaymentGuard({
+        facilitatorUrl: base.facilitatorUrl,
+        merchantOsApiUrl: base.merchantOsUrl,
+        merchantApiKey: base.apiKey,
+        route: {
+          method,
+          path,
+        },
+        apiId: routeConfig.apiId,
+        apiProductId: routeConfig.apiProductId,
+        settlementModeOverride: routeConfig.settlementModeOverride,
+        paywallAppName: advanced.paywallAppName || routeConfig.paywallAppName || base.paywallAppName,
+        paywallTestnet:
+          typeof advanced.paywallTestnet === "boolean"
+            ? advanced.paywallTestnet
+            : typeof routeConfig.paywallTestnet === "boolean"
+              ? routeConfig.paywallTestnet
+            : base.paywallTestnet,
+        autoRefreshMs:
+          Number.isFinite(advanced.autoRefreshMs)
+            ? advanced.autoRefreshMs
+            : Number.isFinite(routeConfig.autoRefreshMs)
+              ? routeConfig.autoRefreshMs
+              : base.autoRefreshMs,
+        supportedSourceNetworks:
+          advanced.supportedSourceNetworks ||
+          routeConfig.supportedSourceNetworks ||
+          base.supportedSourceNetworks,
+        sourceNetworkFilter:
+          advanced.sourceNetworkFilter ||
+          routeConfig.sourceNetworkFilter ||
+          base.sourceNetworkFilter,
+        maxRequirementOptions:
+          Number.isFinite(advanced.maxRequirementOptions)
+            ? advanced.maxRequirementOptions
+            : Number.isFinite(routeConfig.maxRequirementOptions)
+              ? routeConfig.maxRequirementOptions
+            : base.maxRequirementOptions,
+        logPrefix: advanced.logPrefix || routeConfig.logPrefix || base.logPrefix,
+        logger: advanced.logger || routeConfig.logger || base.logger,
+        logLevel: advanced.logLevel || routeConfig.logLevel || base.logLevel,
+      });
+
+      const middleware = guard.middleware;
+      middleware.routeMethod = guard.routeMethod;
+      middleware.routePath = guard.routePath;
+      middleware.refreshRequirements = guard.refreshRequirements;
+      middleware.getCurrentRouteInfo = guard.getCurrentRouteInfo;
+      middleware.startAutoRefresh = guard.startAutoRefresh;
+      middleware.stopAutoRefresh = guard.stopAutoRefresh;
+
+      return middleware;
+    },
+
+    async protectExpress(app, routeConfig = {}, ...handlers) {
+      const middleware = await client.protect(routeConfig);
+      const method = middleware.routeMethod || normalizeMethod(routeConfig.method || "GET");
+      const path = middleware.routePath || normalizePath(routeConfig.path, "routeConfig.path");
+      mountProtectedRoute(app, method, path, middleware, handlers);
+      return middleware;
+    },
+
+    webhooks: {
+      verify: verifyWebhook,
+      express: createExpressWebhookHandler,
+    },
+  };
+
+  return client;
+};
+
+export const createRailbridgeFromEnv = (env = process.env, overrides = {}) => {
+  if (!env || typeof env !== "object") {
+    throw new Error("env must be an object");
+  }
+
+  const environment = resolveEnvironmentInput(
+    overrides.environment ?? env.RB_ENV ?? env.RAILBRIDGE_ENV,
+    "RB_ENV or RAILBRIDGE_ENV",
+  );
+
+  return createRailbridge({
+    ...overrides,
+    apiKey: overrides.apiKey ?? env.RB_API_KEY,
+    environment,
+    advanced: {
+      ...(overrides.advanced || {}),
+      merchantOsUrl: overrides.advanced?.merchantOsUrl ?? overrides.merchantOsUrl ?? env.RB_MERCHANT_OS_URL,
+      facilitatorUrl:
+        overrides.advanced?.facilitatorUrl ?? overrides.facilitatorUrl ?? env.RB_FACILITATOR_URL,
+      paywallTestnet:
+        overrides.advanced?.paywallTestnet ??
+        overrides.paywallTestnet ??
+        parseBoolean(env.RB_PAYWALL_TESTNET, "RB_PAYWALL_TESTNET"),
+      sourceNetworkFilter:
+        overrides.advanced?.sourceNetworkFilter ??
+        overrides.sourceNetworkFilter ??
+        env.RB_SOURCE_NETWORK_FILTER,
+      maxRequirementOptions:
+        overrides.advanced?.maxRequirementOptions ??
+        overrides.maxRequirementOptions ??
+        parseOptionalFiniteNumber(env.RB_MAX_REQUIREMENT_OPTIONS, "RB_MAX_REQUIREMENT_OPTIONS"),
+      autoRefreshMs:
+        overrides.advanced?.autoRefreshMs ??
+        overrides.autoRefreshMs ??
+        parseOptionalFiniteNumber(env.RB_AUTO_REFRESH_MS, "RB_AUTO_REFRESH_MS"),
+      logPrefix: overrides.advanced?.logPrefix ?? overrides.logPrefix ?? env.RB_LOG_PREFIX,
+      paywallAppName:
+        overrides.advanced?.paywallAppName ?? overrides.paywallAppName ?? env.RB_PAYWALL_APP_NAME,
+      logLevel: overrides.advanced?.logLevel ?? overrides.logLevel ?? env.RB_LOG_LEVEL,
+      logger: overrides.advanced?.logger ?? overrides.logger,
+    },
+  });
+};
+
+export const getOnboardingStatus = async ({ merchantOsUrl, token }) => {
+  return resolveOnboardingStatus({
+    merchantOsUrl: ensureNonEmpty(merchantOsUrl, "merchantOsUrl"),
+    token: ensureNonEmpty(token, "token"),
+  });
+};
+
+export const createRailbridgePaymentGuard = async (config) => {
+  const module = await import("./paymentGuard.js");
+  return module.createRailbridgePaymentGuard(config);
+};
+
+export { createExpressWebhookHandler, verifyWebhook };

package/src/paymentGuard.js

@@ -0,0 +1,558 @@
+import { paymentMiddleware } from "@x402/express";
+import { x402ResourceServer } from "@x402/core/server";
+import { HTTPFacilitatorClient } from "@x402/core/http";
+import { registerExactEvmScheme } from "@x402/evm/exact/server";
+import { createPaywall } from "@x402/paywall";
+import { evmPaywall } from "@x402/paywall/evm";
+import { CROSS_CHAIN, declareCrossChainExtension } from "./crossChain.js";
+
+const DEFAULT_SUPPORTED_NETWORKS = [
+  "eip155:421614",
+  "eip155:5042002",
+  "eip155:84532",
+  "eip155:11155111",
+  "eip155:8453",
+  "eip155:137",
+  "eip155:1",
+];
+
+const DEFAULT_MAX_REQUIREMENT_OPTIONS = 8;
+const LOG_LEVEL_PRIORITY = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+const PREFERRED_REQUIREMENT_NETWORKS = [
+  "eip155:84532",
+  "eip155:421614",
+  "eip155:11155111",
+  "eip155:5042002",
+  "eip155:8453",
+  "eip155:42161",
+  "eip155:10",
+  "eip155:1",
+  "eip155:137",
+];
+
+const SUPPORTED_SETTLEMENT_MODES = new Set(["same_chain", "cross_chain"]);
+const FACILITATOR_SUPPORTED_ENDPOINT = "/supported";
+const FACILITATOR_CHAINS_ENDPOINT = "/chains";
+const DEFAULT_FETCH_TIMEOUT_MS = 8000;
+
+const isValidPayTo = (value) =>
+  typeof value === "string" && /^0x[a-fA-F0-9]{40}$/.test(value.trim());
+
+const isValidNetwork = (value) =>
+  typeof value === "string" && /^[a-z0-9]+:[a-zA-Z0-9]+$/.test(value.trim());
+
+const isValidPrice = (value) => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  if (typeof value.asset !== "string" || !value.asset.trim()) {
+    return false;
+  }
+  if (typeof value.amount !== "string" || !/^\d+(\.\d+)?$/.test(value.amount.trim())) {
+    return false;
+  }
+  return Number(value.amount) > 0;
+};
+
+const isValidRequirement = (value) =>
+  value?.scheme === "exact" &&
+  isValidNetwork(value.network) &&
+  isValidPayTo(value.payTo) &&
+  isValidPrice(value.price);
+
+class LoggingFacilitatorClient extends HTTPFacilitatorClient {
+  constructor({ url, sdkLogger }) {
+    super({ url });
+    this.sdkLogger = sdkLogger;
+  }
+
+  async settle(paymentPayload, paymentRequirements) {
+    this.sdkLogger.debug("settle", {
+      network: paymentRequirements.network,
+      scheme: paymentRequirements.scheme,
+    });
+    return super.settle(paymentPayload, paymentRequirements);
+  }
+
+  async verify(paymentPayload, paymentRequirements) {
+    this.sdkLogger.debug("verify", {
+      network: paymentRequirements.network,
+      scheme: paymentRequirements.scheme,
+    });
+    return super.verify(paymentPayload, paymentRequirements);
+  }
+}
+
+const normalizeMethod = (method) => {
+  const value = String(method || "").trim().toUpperCase();
+  return value || "GET";
+};
+
+const normalizePath = (path) => {
+  const value = String(path || "").trim();
+  if (!value) {
+    throw new Error("route.path is required");
+  }
+  return value.startsWith("/") ? value : `/${value}`;
+};
+
+const normalizeRequestPath = (path) => {
+  const value = String(path || "").trim();
+  if (!value) {
+    return "/";
+  }
+  const withoutQuery = value.split("?")[0] || "/";
+  return withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
+};
+
+const normalizeSettlementMode = (mode) => {
+  const value = String(mode || "").trim().toLowerCase();
+  if (!SUPPORTED_SETTLEMENT_MODES.has(value)) {
+    throw new Error("settlementModeOverride must be either 'same_chain' or 'cross_chain'");
+  }
+  return value;
+};
+
+const ensureRequired = (value, fieldName) => {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) {
+    throw new Error(`${fieldName} is required`);
+  }
+  return trimmed;
+};
+
+const createSdkLogger = ({ logger = console, logLevel = "warn", logPrefix = "[railbridge-sdk]" }) => {
+  const threshold = LOG_LEVEL_PRIORITY[logLevel] ?? LOG_LEVEL_PRIORITY.warn;
+  const resolveMethod = (level) => {
+    const fn = logger?.[level];
+    return typeof fn === "function" ? fn.bind(logger) : null;
+  };
+
+  const emit = (level, message, metadata) => {
+    if ((LOG_LEVEL_PRIORITY[level] ?? LOG_LEVEL_PRIORITY.info) > threshold) {
+      return;
+    }
+
+    const fn = resolveMethod(level);
+    if (!fn) {
+      return;
+    }
+
+    if (metadata === undefined) {
+      fn(`${logPrefix} ${message}`);
+      return;
+    }
+
+    fn(`${logPrefix} ${message}`, metadata);
+  };
+
+  return {
+    debug(message, metadata) {
+      emit("debug", message, metadata);
+    },
+    info(message, metadata) {
+      emit("info", message, metadata);
+    },
+    warn(message, metadata) {
+      emit("warn", message, metadata);
+    },
+    error(message, metadata) {
+      emit("error", message, metadata);
+    },
+  };
+};
+
+const fetchWithTimeout = async (url, init = {}, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1000, timeoutMs));
+  try {
+    return await fetch(url, {
+      ...init,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const fetchFacilitatorSupportedNetworks = async (facilitatorUrl) => {
+  try {
+    const response = await fetchWithTimeout(`${facilitatorUrl}${FACILITATOR_SUPPORTED_ENDPOINT}`);
+    if (!response.ok) {
+      return [...DEFAULT_SUPPORTED_NETWORKS];
+    }
+
+    const body = await response.json().catch(() => ({}));
+    const networks = Array.isArray(body.kinds)
+      ? body.kinds
+          .filter((kind) => Boolean(kind?.network && kind?.scheme))
+          .filter((kind) => kind.scheme === "exact")
+          .map((kind) => kind.network)
+      : [];
+
+    if (!networks.length) {
+      return [...DEFAULT_SUPPORTED_NETWORKS];
+    }
+
+    return Array.from(new Set(networks));
+  } catch {
+    return [...DEFAULT_SUPPORTED_NETWORKS];
+  }
+};
+
+const fetchFacilitatorChains = async (facilitatorUrl) => {
+  try {
+    const response = await fetchWithTimeout(`${facilitatorUrl}${FACILITATOR_CHAINS_ENDPOINT}`);
+    if (!response.ok) {
+      return [];
+    }
+    const body = await response.json().catch(() => ({}));
+    if (!Array.isArray(body.items)) {
+      return [];
+    }
+
+    return body.items
+      .filter((item) => typeof item?.network === "string" && item.network.includes(":"))
+      .filter((item) => String(item.status || "active").toLowerCase() !== "paused")
+      .map((item) => ({
+        network: item.network,
+        isTestnet: Boolean(item.isTestnet),
+      }));
+  } catch {
+    return [];
+  }
+};
+
+const clampMaxRequirementOptions = (value) => {
+  if (!Number.isFinite(value)) {
+    return DEFAULT_MAX_REQUIREMENT_OPTIONS;
+  }
+  const normalized = Math.floor(Number(value));
+  if (normalized <= 0) {
+    return 1;
+  }
+  return normalized;
+};
+
+const sortRequirementOptions = (options) => {
+  const weightByNetwork = new Map(
+    PREFERRED_REQUIREMENT_NETWORKS.map((network, index) => [network, index]),
+  );
+
+  return [...options].sort((left, right) => {
+    const leftWeight = weightByNetwork.get(left.network);
+    const rightWeight = weightByNetwork.get(right.network);
+
+    if (leftWeight !== undefined && rightWeight !== undefined) {
+      return leftWeight - rightWeight;
+    }
+    if (leftWeight !== undefined) {
+      return -1;
+    }
+    if (rightWeight !== undefined) {
+      return 1;
+    }
+    return left.network.localeCompare(right.network);
+  });
+};
+
+export const createRailbridgePaymentGuard = async (config) => {
+  const facilitatorUrl = ensureRequired(config.facilitatorUrl, "facilitatorUrl");
+  const merchantOsApiUrl = ensureRequired(config.merchantOsApiUrl, "merchantOsApiUrl");
+  const merchantApiKey = ensureRequired(config.merchantApiKey, "merchantApiKey");
+  const routeMethod = normalizeMethod(config.route?.method || "GET");
+  const routePath = normalizePath(config.route?.path || "");
+  const apiId = String(config.apiId || "").trim();
+  const apiProductId = String(config.apiProductId || "").trim();
+  const settlementMode = config.settlementModeOverride
+    ? normalizeSettlementMode(config.settlementModeOverride)
+    : null;
+
+  const logPrefix = config.logPrefix || "[railbridge-sdk]";
+  const maxRequirementOptions = clampMaxRequirementOptions(config.maxRequirementOptions);
+  const sourceNetworkFilter = config.sourceNetworkFilter || "all";
+  const sdkLogger = createSdkLogger({
+    logger: config.logger,
+    logLevel: config.logLevel,
+    logPrefix,
+  });
+
+  const routes = {};
+  let currentRouteInfo = null;
+  let refreshInFlight = null;
+  let refreshTimer = null;
+  let lastResolvedSignature = "";
+
+  const fetchedSupportedNetworks =
+    Array.isArray(config.supportedSourceNetworks) && config.supportedSourceNetworks.length
+      ? config.supportedSourceNetworks
+      : await fetchFacilitatorSupportedNetworks(facilitatorUrl);
+
+  const facilitatorChains = await fetchFacilitatorChains(facilitatorUrl);
+  const filteredSourceNetworkSet =
+    sourceNetworkFilter === "all"
+      ? null
+      : new Set(
+          facilitatorChains
+            .filter((chain) =>
+              sourceNetworkFilter === "testnet_only" ? chain.isTestnet : !chain.isTestnet,
+            )
+            .map((chain) => chain.network),
+        );
+
+  const supportedSourceNetworks =
+    filteredSourceNetworkSet && filteredSourceNetworkSet.size
+      ? fetchedSupportedNetworks.filter((network) => filteredSourceNetworkSet.has(network))
+      : fetchedSupportedNetworks;
+
+  if (filteredSourceNetworkSet && !filteredSourceNetworkSet.size) {
+    throw new Error(
+      `${logPrefix} unable to enforce source network filter: facilitator /chains metadata unavailable`,
+    );
+  }
+
+  if (!supportedSourceNetworks.length) {
+    throw new Error(`${logPrefix} no supported source networks available after initialization`);
+  }
+
+  const supportedSourceNetworkSet = new Set(supportedSourceNetworks);
+  const facilitatorClient = new LoggingFacilitatorClient({
+    url: facilitatorUrl,
+    sdkLogger,
+  });
+
+  const resourceServer = new x402ResourceServer(facilitatorClient);
+  registerExactEvmScheme(resourceServer, {
+    networks: supportedSourceNetworks,
+  });
+
+  const paywall = createPaywall()
+    .withNetwork(evmPaywall)
+    .withConfig({
+      appName: config.paywallAppName || "RailBridge Merchant Integration",
+      testnet: config.paywallTestnet ?? true,
+    })
+    .build();
+
+  const routeKey = `${routeMethod} ${routePath}`;
+
+  const fetchResolvedRequirement = async () => {
+    const response = await fetchWithTimeout(
+      `${merchantOsApiUrl.replace(/\/$/, "")}/v1/sdk/requirements/resolve`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-railbridge-api-key": merchantApiKey,
+        },
+        body: JSON.stringify({
+          apiId: apiId || undefined,
+          apiProductId: apiProductId || undefined,
+          method: routeMethod,
+          path: routePath,
+          settlementModeOverride: settlementMode || undefined,
+        }),
+      },
+      DEFAULT_FETCH_TIMEOUT_MS,
+    );
+
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new Error(
+        `Merchant OS requirement resolve failed (${response.status}): ${body.error || body.message || "unknown error"}`,
+      );
+    }
+
+    return body;
+  };
+
+  const refreshRequirementsInternal = async ({ reason = "manual", continueOnError = false } = {}) => {
+    try {
+      const resolved = await fetchResolvedRequirement();
+      const requirementOptions =
+        Array.isArray(resolved.requirements) && resolved.requirements.length
+          ? resolved.requirements
+          : [resolved.requirement];
+
+      const invalidRequirement = requirementOptions.find((requirement) => !isValidRequirement(requirement));
+      if (invalidRequirement) {
+        throw new Error("Merchant OS returned invalid requirement payload");
+      }
+
+      const supportedRequirements = requirementOptions.filter((requirement) =>
+        supportedSourceNetworkSet.has(requirement.network),
+      );
+
+      if (!supportedRequirements.length) {
+        const requestedNetworks = Array.from(new Set(requirementOptions.map((r) => r.network)));
+        throw new Error(
+          `No supported source networks after filtering. Requested=${requestedNetworks.join(",")} Supported=${Array.from(
+            supportedSourceNetworkSet,
+          ).join(",")}`,
+        );
+      }
+
+      const prioritizedRequirements = sortRequirementOptions(supportedRequirements);
+      const truncatedRequirements = prioritizedRequirements.slice(0, maxRequirementOptions);
+
+      const nextRoute = {
+        accepts: truncatedRequirements.map((requirement) => ({
+          scheme: requirement.scheme,
+          network: requirement.network,
+          price: requirement.price,
+          payTo: requirement.payTo,
+          merchantId: resolved.merchantId,
+          accountId: resolved.accountId,
+          extra: requirement.extra,
+        })),
+        description:
+          resolved.requirement?.extra?.description ||
+          resolved.apiProduct?.description ||
+          resolved.apiProduct?.apiName ||
+          "RailBridge protected endpoint",
+        mimeType: "application/json",
+      };
+
+      if (resolved.crossChain) {
+        nextRoute.extensions = {
+          [CROSS_CHAIN]: declareCrossChainExtension({
+            destinationNetwork: resolved.crossChain.destinationNetwork,
+            destinationAsset: resolved.crossChain.destinationAsset,
+            destinationPayTo: resolved.crossChain.destinationPayTo,
+          }),
+        };
+      }
+
+      routes[routeKey] = nextRoute;
+
+      currentRouteInfo = {
+        routeKey,
+        payTo: resolved.requirement.payTo,
+        sourceNetworks: truncatedRequirements.map((requirement) => requirement.network),
+        crossChain: Boolean(resolved.crossChain),
+        settlementMode: resolved.settlementMode || settlementMode || "auto",
+      };
+
+      const nextSignature = JSON.stringify({
+        payTo: currentRouteInfo.payTo,
+        sourceNetworks: currentRouteInfo.sourceNetworks,
+        crossChain: currentRouteInfo.crossChain,
+        settlementMode: currentRouteInfo.settlementMode,
+        accepts: truncatedRequirements.map((requirement) => ({
+          scheme: requirement.scheme,
+          network: requirement.network,
+          payTo: requirement.payTo,
+          asset: requirement.price.asset,
+          amount: requirement.price.amount,
+        })),
+        extension: resolved.crossChain || null,
+      });
+
+      if (nextSignature !== lastResolvedSignature) {
+        lastResolvedSignature = nextSignature;
+        sdkLogger.info("route requirements refreshed", {
+          ...currentRouteInfo,
+          reason,
+        });
+      }
+
+      return currentRouteInfo;
+    } catch (error) {
+      if (continueOnError && currentRouteInfo) {
+        sdkLogger.warn("route refresh failed, continuing with cached requirements", {
+          reason,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return currentRouteInfo;
+      }
+      throw error;
+    }
+  };
+
+  const refreshRequirements = () => {
+    if (!refreshInFlight) {
+      refreshInFlight = refreshRequirementsInternal({ reason: "manual" }).finally(() => {
+        refreshInFlight = null;
+      });
+    }
+    return refreshInFlight;
+  };
+
+  const refreshForProtectedRequest = () => {
+    if (!refreshInFlight) {
+      refreshInFlight = refreshRequirementsInternal({
+        reason: "request",
+        continueOnError: false,
+      }).finally(() => {
+        refreshInFlight = null;
+      });
+    }
+    return refreshInFlight;
+  };
+
+  await refreshRequirementsInternal({ reason: "startup" });
+
+  const baseMiddleware = paymentMiddleware(routes, resourceServer, undefined, paywall, true);
+
+  const shouldRefreshForRequest = (req) =>
+    normalizeMethod(req.method || "GET") === routeMethod &&
+    normalizeRequestPath(req.path || req.originalUrl || req.url || "") === routePath;
+
+  const middleware = (req, res, next) => {
+    if (!shouldRefreshForRequest(req)) {
+      return baseMiddleware(req, res, next);
+    }
+
+    void refreshForProtectedRequest()
+      .then(() => {
+        baseMiddleware(req, res, next);
+      })
+      .catch((error) => {
+        next(error);
+      });
+  };
+
+  const startAutoRefresh = () => {
+    if (refreshTimer) {
+      return;
+    }
+    const everyMs = Math.max(10_000, Number(config.autoRefreshMs || 30_000));
+    refreshTimer = setInterval(() => {
+      if (!refreshInFlight) {
+        refreshInFlight = refreshRequirementsInternal({
+          reason: "interval",
+          continueOnError: true,
+        }).finally(() => {
+          refreshInFlight = null;
+        });
+      }
+    }, everyMs);
+
+    if (typeof refreshTimer.unref === "function") {
+      refreshTimer.unref();
+    }
+  };
+
+  const stopAutoRefresh = () => {
+    if (refreshTimer) {
+      clearInterval(refreshTimer);
+      refreshTimer = null;
+    }
+  };
+
+  return {
+    middleware,
+    routeMethod,
+    routePath,
+    refreshRequirements,
+    getCurrentRouteInfo: () => currentRouteInfo,
+    startAutoRefresh,
+    stopAutoRefresh,
+  };
+};

package/src/webhooks.js

@@ -0,0 +1,75 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const normalizePayload = (payload) =>
+  typeof payload === "string" ? payload : JSON.stringify(payload ?? {});
+
+const normalizeSignature = (signature) => String(signature || "").trim().toLowerCase();
+
+const secureHexEqual = (leftHex, rightHex) => {
+  const left = Buffer.from(leftHex, "hex");
+  const right = Buffer.from(rightHex, "hex");
+  if (left.length !== right.length) {
+    return false;
+  }
+  return timingSafeEqual(left, right);
+};
+
+export const verifyWebhook = ({ secret, timestamp, payload, signature }) => {
+  if (!secret || !timestamp || !signature) {
+    return false;
+  }
+
+  const body = normalizePayload(payload);
+  const signedPayload = `${String(timestamp)}.${body}`;
+  const expected = createHmac("sha256", String(secret)).update(signedPayload).digest("hex");
+  const actual = normalizeSignature(signature);
+
+  if (!/^[a-f0-9]+$/.test(actual) || actual.length !== expected.length) {
+    return false;
+  }
+
+  return secureHexEqual(expected, actual);
+};
+
+export const createExpressWebhookHandler = ({
+  secret,
+  requireSignature = true,
+  onEvent,
+} = {}) => {
+  const handler = async (req, res) => {
+    const signature = req.header("x-railbridge-signature");
+    const timestamp = req.header("x-railbridge-timestamp");
+    const rawBody = typeof req.body === "string" ? req.body : JSON.stringify(req.body ?? {});
+
+    if (requireSignature) {
+      const ok = verifyWebhook({
+        secret,
+        timestamp,
+        payload: rawBody,
+        signature,
+      });
+      if (!ok) {
+        return res.status(401).json({ error: "invalid signature" });
+      }
+    }
+
+    let event;
+    try {
+      event = JSON.parse(rawBody);
+    } catch {
+      return res.status(400).json({ error: "invalid JSON payload" });
+    }
+
+    if (typeof onEvent === "function") {
+      await onEvent(event, {
+        headers: req.headers,
+        eventType: req.header("x-railbridge-event") || null,
+        eventId: req.header("x-railbridge-event-id") || null,
+      });
+    }
+
+    return res.status(200).json({ ok: true });
+  };
+
+  return handler;
+};