@remitmd/sdk 0.1.0

package/src/provider.ts

@@ -0,0 +1,281 @@
+/**
+ * x402 service provider middleware for gating HTTP endpoints behind payments.
+ *
+ * Providers use this module to:
+ * - Return HTTP 402 responses with properly formatted `PAYMENT-REQUIRED` headers
+ * - Verify incoming `PAYMENT-SIGNATURE` headers against the remit.md facilitator
+ *
+ * Usage (Hono / Cloudflare Workers / any fetch-based framework):
+ * ```typescript
+ * import { X402Paywall } from "@remitmd/sdk/provider";
+ *
+ * const paywall = new X402Paywall({
+ *   walletAddress: "0xYourProviderWallet",
+ *   amountUsdc: 0.001,
+ *   network: "eip155:84532",
+ *   asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+ *   facilitatorToken: "your-bearer-jwt",
+ *   resource: "/v1/data",
+ *   description: "Realtime market data feed",
+ *   mimeType: "application/json",
+ * });
+ *
+ * // Returns a 402 Response if payment is absent/invalid, null if payment ok.
+ * const block = await paywall.handle(request);
+ * if (block) return block;
+ * return new Response("here is your data");
+ * ```
+ *
+ * Usage (Hono):
+ * ```typescript
+ * app.use("/v1/*", paywall.honoMiddleware());
+ * ```
+ *
+ * Usage (Express-style):
+ * ```typescript
+ * app.get("/v1/data", paywall.expressMiddleware(), (req, res) => {
+ *   res.json({ data: "..." });
+ * });
+ * ```
+ */
+
+/** Configuration for {@link X402Paywall}. */
+export interface PaywallOptions {
+  /** Provider's checksummed Ethereum address (the `payTo` field). */
+  walletAddress: string;
+  /** Price per request in USDC (e.g. `0.001`). */
+  amountUsdc: number;
+  /** CAIP-2 network string (e.g. `"eip155:84532"` for Base Sepolia). */
+  network: string;
+  /** USDC contract address on the target network. */
+  asset: string;
+  /** Base URL of the remit.md facilitator (default: `"https://remit.md"`). */
+  facilitatorUrl?: string;
+  /** Bearer JWT for authenticating calls to `/api/v0/x402/verify`. */
+  facilitatorToken?: string;
+  /** How long the payment authorization remains valid in seconds (default: 60). */
+  maxTimeoutSeconds?: number;
+  /** V2 — URL or path of the resource being protected (e.g. `"/v1/data"`). */
+  resource?: string;
+  /** V2 — Human-readable description of what the payment is for. */
+  description?: string;
+  /** V2 — MIME type of the resource (e.g. `"application/json"`). */
+  mimeType?: string;
+}
+
+/** Result of {@link X402Paywall.check}. */
+export interface CheckResult {
+  isValid: boolean;
+  /** Populated when `isValid` is false and the signature was present. */
+  invalidReason?: string;
+}
+
+/** x402 paywall for service providers. */
+export class X402Paywall {
+  readonly #walletAddress: string;
+  readonly #amountBaseUnits: string;
+  readonly #network: string;
+  readonly #asset: string;
+  readonly #facilitatorUrl: string;
+  readonly #facilitatorToken: string;
+  readonly #maxTimeoutSeconds: number;
+  readonly #resource: string | undefined;
+  readonly #description: string | undefined;
+  readonly #mimeType: string | undefined;
+
+  constructor({
+    walletAddress,
+    amountUsdc,
+    network,
+    asset,
+    facilitatorUrl = "https://remit.md",
+    facilitatorToken = "",
+    maxTimeoutSeconds = 60,
+    resource,
+    description,
+    mimeType,
+  }: PaywallOptions) {
+    this.#walletAddress = walletAddress;
+    this.#amountBaseUnits = String(Math.round(amountUsdc * 1_000_000));
+    this.#network = network;
+    this.#asset = asset;
+    this.#facilitatorUrl = facilitatorUrl.replace(/\/$/, "");
+    this.#facilitatorToken = facilitatorToken;
+    this.#maxTimeoutSeconds = maxTimeoutSeconds;
+    this.#resource = resource;
+    this.#description = description;
+    this.#mimeType = mimeType;
+  }
+
+  /** Return the base64-encoded JSON `PAYMENT-REQUIRED` header value. */
+  paymentRequiredHeader(): string {
+    const payload: Record<string, unknown> = {
+      scheme: "exact",
+      network: this.#network,
+      amount: this.#amountBaseUnits,
+      asset: this.#asset,
+      payTo: this.#walletAddress,
+      maxTimeoutSeconds: this.#maxTimeoutSeconds,
+    };
+    if (this.#resource !== undefined) payload["resource"] = this.#resource;
+    if (this.#description !== undefined) payload["description"] = this.#description;
+    if (this.#mimeType !== undefined) payload["mimeType"] = this.#mimeType;
+    return Buffer.from(JSON.stringify(payload)).toString("base64");
+  }
+
+  #paymentRequiredObject() {
+    return {
+      scheme: "exact",
+      network: this.#network,
+      amount: this.#amountBaseUnits,
+      asset: this.#asset,
+      payTo: this.#walletAddress,
+      maxTimeoutSeconds: this.#maxTimeoutSeconds,
+    };
+  }
+
+  /**
+   * Check whether a `PAYMENT-SIGNATURE` header represents a valid payment.
+   *
+   * Calls the remit.md facilitator's `/api/v0/x402/verify` endpoint.
+   *
+   * @param paymentSig The raw header value (base64 JSON), or null if absent.
+   * @returns `{ isValid: true }` or `{ isValid: false, invalidReason }`.
+   */
+  async check(paymentSig: string | null): Promise<CheckResult> {
+    if (!paymentSig) {
+      return { isValid: false };
+    }
+
+    let paymentPayload: unknown;
+    try {
+      paymentPayload = JSON.parse(Buffer.from(paymentSig, "base64").toString("utf8"));
+    } catch {
+      return { isValid: false, invalidReason: "INVALID_PAYLOAD" };
+    }
+
+    const body = {
+      paymentPayload,
+      paymentRequired: this.#paymentRequiredObject(),
+    };
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.#facilitatorToken) {
+      headers["Authorization"] = `Bearer ${this.#facilitatorToken}`;
+    }
+
+    let data: { isValid?: boolean; invalidReason?: string };
+    try {
+      const resp = await globalThis.fetch(`${this.#facilitatorUrl}/api/v0/x402/verify`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+      });
+      if (!resp.ok) {
+        return { isValid: false, invalidReason: "FACILITATOR_ERROR" };
+      }
+      data = (await resp.json()) as { isValid?: boolean; invalidReason?: string };
+    } catch {
+      return { isValid: false, invalidReason: "FACILITATOR_ERROR" };
+    }
+
+    return {
+      isValid: data.isValid === true,
+      invalidReason: data.invalidReason,
+    };
+  }
+
+  /**
+   * Web-standard (fetch API) middleware compatible with Hono, Cloudflare Workers, etc.
+   *
+   * Returns a 402 `Response` if payment is absent or invalid, or `null` to allow
+   * the request to proceed.
+   *
+   * @param request Incoming `Request` object.
+   */
+  async handle(request: Request): Promise<Response | null> {
+    const paymentSig = request.headers.get("payment-signature");
+    const result = await this.check(paymentSig);
+    if (!result.isValid) {
+      return new Response(JSON.stringify({ error: "Payment required", invalidReason: result.invalidReason }), {
+        status: 402,
+        headers: {
+          "Content-Type": "application/json",
+          "PAYMENT-REQUIRED": this.paymentRequiredHeader(),
+        },
+      });
+    }
+    return null;
+  }
+
+  /**
+   * Express-style middleware factory.
+   *
+   * @example
+   * ```typescript
+   * app.get("/v1/data", paywall.expressMiddleware(), (req, res) => {
+   *   res.json({ data: "..." });
+   * });
+   * ```
+   */
+  expressMiddleware(): (
+    req: { headers: Record<string, string | string[] | undefined> },
+    res: {
+      status(code: number): { set(headers: Record<string, string>): { json(body: unknown): void } };
+    },
+    next: () => void,
+  ) => Promise<void> {
+    return async (req, res, next) => {
+      const raw = req.headers["payment-signature"];
+      const paymentSig = Array.isArray(raw) ? raw[0] ?? null : (raw ?? null);
+      const result = await this.check(paymentSig);
+      if (!result.isValid) {
+        res
+          .status(402)
+          .set({ "PAYMENT-REQUIRED": this.paymentRequiredHeader(), "Content-Type": "application/json" })
+          .json({ error: "Payment required", invalidReason: result.invalidReason });
+        return;
+      }
+      next();
+    };
+  }
+
+  /**
+   * Hono middleware factory.
+   *
+   * Compatible with Hono v3/v4 and any framework that uses the same
+   * `(c, next) => Promise<void>` middleware signature.
+   *
+   * @example
+   * ```typescript
+   * import { Hono } from "hono";
+   * app.use("/v1/*", paywall.honoMiddleware());
+   * ```
+   */
+  honoMiddleware(): (
+    c: {
+      req: { raw: Request };
+      header(name: string, value: string): void;
+      body(content: string, status?: number): Response;
+    },
+    next: () => Promise<void>,
+  ) => Promise<Response | void> {
+    return async (c, next) => {
+      const paymentSig = c.req.raw.headers.get("payment-signature");
+      const result = await this.check(paymentSig);
+      if (!result.isValid) {
+        c.header("PAYMENT-REQUIRED", this.paymentRequiredHeader());
+        c.header("Content-Type", "application/json");
+        return c.body(JSON.stringify({ error: "Payment required", invalidReason: result.invalidReason }), 402);
+      }
+      await next();
+    };
+  }
+
+  /** Prevent sensitive config leakage. */
+  toJSON(): Record<string, string> {
+    return { walletAddress: this.#walletAddress, network: this.#network };
+  }
+}

package/src/signer.ts

@@ -0,0 +1,70 @@
+import { privateKeyToAccount } from "viem/accounts";
+import type { PrivateKeyAccount, SignTypedDataParameters } from "viem/accounts";
+
+/** EIP-712 typed data domain. */
+export interface TypedDataDomain {
+  name: string;
+  version: string;
+  chainId?: number;
+  verifyingContract?: string;
+}
+
+/** EIP-712 type definitions. */
+export type TypedDataTypes = Record<string, Array<{ name: string; type: string }>>;
+
+/** Pluggable signing interface. Implementations must isolate key material. */
+export interface Signer {
+  /** Sign EIP-712 typed data and return hex signature. */
+  signTypedData(
+    domain: TypedDataDomain,
+    types: TypedDataTypes,
+    value: Record<string, unknown>,
+  ): Promise<string>;
+
+  /** Return the checksummed public address. */
+  getAddress(): string;
+}
+
+/** Default signer: raw private key via viem. Key is held in closure, never exposed. */
+export class PrivateKeySigner implements Signer {
+  readonly #account: PrivateKeyAccount;
+
+  constructor(privateKey: string) {
+    // Normalise: ensure 0x prefix
+    const hex = (privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`) as `0x${string}`;
+    this.#account = privateKeyToAccount(hex);
+  }
+
+  /** Create from hex private key string. */
+  static fromHex(privateKey: string): PrivateKeySigner {
+    return new PrivateKeySigner(privateKey);
+  }
+
+  async signTypedData(
+    domain: TypedDataDomain,
+    types: TypedDataTypes,
+    value: Record<string, unknown>,
+  ): Promise<string> {
+    const primaryType = Object.keys(types).filter((k) => k !== "EIP712Domain")[0] ?? "Request";
+    // Cast through unknown to satisfy viem's highly-parameterized overloads
+    return this.#account.signTypedData({
+      domain,
+      types,
+      primaryType,
+      message: value,
+    } as unknown as SignTypedDataParameters);
+  }
+
+  getAddress(): string {
+    return this.#account.address;
+  }
+
+  /** Prevent key leakage in serialization. */
+  toJSON(): Record<string, string> {
+    return { address: this.#account.address };
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return `PrivateKeySigner { address: '${this.#account.address}' }`;
+  }
+}

package/src/testing/local.ts

@@ -0,0 +1,118 @@
+/**
+ * LocalChain — wraps a local Anvil instance for integration testing.
+ * Real EVM, <100ms per operation (requires Anvil in PATH).
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { MockWallet, MockRemit } from "./mock.js";
+
+/** Anvil default pre-funded accounts (well-known test keys). */
+const ANVIL_KEYS: string[] = [
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+  "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a",
+  "0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6",
+  "0x47e179ec197488593b187f80a00eb0da91f1b9d0b13f8733639f19c30a34926b",
+];
+
+export interface LocalChainOptions {
+  port?: number;
+  blockTime?: number; // seconds; 0 = instant mining
+}
+
+export class LocalChain {
+  readonly #port: number;
+  readonly #mock: MockRemit;
+  #process: ChildProcess | null = null;
+
+  private constructor(port: number) {
+    this.#port = port;
+    this.#mock = new MockRemit();
+  }
+
+  /**
+   * Start Anvil, wait for it to be ready, and return a LocalChain instance.
+   * Throws if Anvil is not in PATH.
+   */
+  static async start(options: LocalChainOptions = {}): Promise<LocalChain> {
+    const port = options.port ?? 8545;
+    const chain = new LocalChain(port);
+    await chain.#spawn(options.blockTime ?? 0);
+    return chain;
+  }
+
+  async #spawn(blockTime: number): Promise<void> {
+    const args = ["--port", String(this.#port)];
+    if (blockTime > 0) args.push("--block-time", String(blockTime));
+
+    this.#process = spawn("anvil", args, { stdio: "pipe" });
+
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("Anvil did not start within 5s")), 5000);
+
+      this.#process!.stdout?.on("data", (data: Buffer) => {
+        if (data.toString().includes("Listening on")) {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+
+      this.#process!.on("error", (err) => {
+        clearTimeout(timeout);
+        reject(new Error(`Failed to start Anvil: ${err.message}. Is foundry installed?`));
+      });
+    });
+  }
+
+  /** Get a pre-funded wallet by index (0-4). Uses Anvil's default accounts. */
+  getWallet(index = 0): MockWallet {
+    const key = ANVIL_KEYS[index];
+    if (!key) throw new Error(`Wallet index ${index} out of range (0-${ANVIL_KEYS.length - 1})`);
+    const wallet = new MockWallet(key, this.#mock);
+    this.#mock["_getState"](wallet.address).balance = 10000;
+    return wallet;
+  }
+
+  /** Advance chain time by `seconds`. */
+  async advanceTime(seconds: number): Promise<void> {
+    this.#mock.advanceTime(seconds);
+    // Also call evm_increaseTime + evm_mine on Anvil
+    await this.#rpc("evm_increaseTime", [seconds]);
+    await this.#rpc("evm_mine", []);
+  }
+
+  /** Mine additional blocks. */
+  async mine(blocks = 1): Promise<void> {
+    for (let i = 0; i < blocks; i++) {
+      await this.#rpc("evm_mine", []);
+    }
+  }
+
+  /** Save a snapshot. Returns snapshot ID. */
+  async snapshot(): Promise<string> {
+    const result = await this.#rpc("evm_snapshot", []);
+    return result as string;
+  }
+
+  /** Revert to a saved snapshot. */
+  async revert(snapshotId: string): Promise<void> {
+    await this.#rpc("evm_revert", [snapshotId]);
+  }
+
+  /** Stop Anvil. */
+  stop(): void {
+    this.#process?.kill();
+    this.#process = null;
+  }
+
+  async #rpc(method: string, params: unknown[]): Promise<unknown> {
+    const response = await fetch(`http://127.0.0.1:${this.#port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    const data = (await response.json()) as { result?: unknown; error?: { message: string } };
+    if (data.error) throw new Error(`RPC error: ${data.error.message}`);
+    return data.result;
+  }
+}