@armory-sh/base 0.2.28 → 0.2.29

package/src/utils/routes.ts

@@ -0,0 +1,240 @@
+export type RoutePattern = string;
+export type RouteMatcher = (path: string) => boolean;
+
+export interface RouteConfig<T = unknown> {
+  pattern: RoutePattern;
+  config: T;
+}
+
+export interface ParsedPattern {
+  segments: string[];
+  isWildcard: boolean;
+  isParametrized: boolean;
+  paramNames: string[];
+  priority: number;
+}
+
+const PRIORITY_EXACT = 3;
+const PRIORITY_PARAMETRIZED = 2;
+const PRIORITY_WILDCARD = 1;
+
+export function parseRoutePattern(pattern: string): ParsedPattern {
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+  const segments = normalizedPattern.split("/").filter(Boolean);
+
+  let isWildcard = false;
+  let isParametrized = false;
+  const paramNames: string[] = [];
+  const seenParamNames = new Set<string>();
+  const recordParamName = (name: string) => {
+    if (!name) {
+      return;
+    }
+    if (seenParamNames.has(name)) {
+      return;
+    }
+    seenParamNames.add(name);
+    paramNames.push(name);
+  };
+
+  for (const segment of segments) {
+    if (segment === "*") {
+      isWildcard = true;
+      continue;
+    }
+
+    const hasWildcardToken = segment.includes("*");
+
+    if (segment.startsWith(":")) {
+      isParametrized = true;
+      const paramName = segment.replace(/\*+$/, "").slice(1);
+      recordParamName(paramName);
+      if (hasWildcardToken) {
+        isWildcard = true;
+      }
+      continue;
+    }
+
+    if (hasWildcardToken) {
+      const parts = segment.split("*");
+      for (const part of parts) {
+        if (part.startsWith(":")) {
+          isParametrized = true;
+          recordParamName(part.slice(1));
+        }
+      }
+      isWildcard = true;
+    }
+  }
+
+  let priority = PRIORITY_WILDCARD;
+  if (!isWildcard && !isParametrized) {
+    priority = PRIORITY_EXACT;
+  } else if (isParametrized && !isWildcard) {
+    priority = PRIORITY_PARAMETRIZED;
+  } else if (isParametrized && isWildcard) {
+    priority = PRIORITY_PARAMETRIZED;
+  }
+
+  return { segments, isWildcard, isParametrized, paramNames, priority };
+}
+
+function matchSegment(patternSegment: string, pathSegment: string): boolean {
+  if (patternSegment === "*") {
+    return true;
+  }
+
+  if (patternSegment.startsWith(":")) {
+    return true;
+  }
+
+  if (patternSegment.includes("*")) {
+    const regex = new RegExp(
+      `^${patternSegment.replace(/\*/g, ".*").replace(/:/g, "")}$`,
+    );
+    return regex.test(pathSegment);
+  }
+
+  return patternSegment === pathSegment;
+}
+
+function matchWildcardPattern(
+  patternSegments: string[],
+  pathSegments: string[],
+): boolean {
+  const requiredSegments = patternSegments.filter((s) => s !== "*");
+
+  if (requiredSegments.length > pathSegments.length) {
+    return false;
+  }
+
+  for (let i = 0; i < requiredSegments.length; i++) {
+    const patternIndex = patternSegments.indexOf(requiredSegments[i]);
+    if (pathSegments[patternIndex] !== requiredSegments[i].replace(/^:/, "")) {
+      if (!requiredSegments[i].startsWith(":") && requiredSegments[i] !== "*") {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+export function matchRoute(pattern: string, path: string): boolean {
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+
+  if (normalizedPattern === normalizedPath) {
+    return true;
+  }
+
+  const parsed = parseRoutePattern(normalizedPattern);
+  const patternSegments = parsed.segments;
+  const pathSegments = normalizedPath.split("/").filter(Boolean);
+
+  if (!parsed.isWildcard && patternSegments.length !== pathSegments.length) {
+    return false;
+  }
+
+  if (parsed.isWildcard && patternSegments.length > pathSegments.length + 1) {
+    return false;
+  }
+
+  if (parsed.isWildcard) {
+    return matchWildcardPattern(patternSegments, pathSegments);
+  }
+
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!matchSegment(patternSegments[i], pathSegments[i])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function findMatchingRoute<T>(
+  routes: RouteConfig<T>[],
+  path: string,
+): RouteConfig<T> | null {
+  const matchingRoutes: Array<{
+    route: RouteConfig<T>;
+    parsed: ParsedPattern;
+  }> = [];
+
+  for (const route of routes) {
+    if (matchRoute(route.pattern, path)) {
+      const parsed = parseRoutePattern(route.pattern);
+      matchingRoutes.push({ route, parsed });
+    }
+  }
+
+  if (matchingRoutes.length === 0) {
+    return null;
+  }
+
+  matchingRoutes.sort((a, b) => {
+    if (b.parsed.priority !== a.parsed.priority) {
+      return b.parsed.priority - a.parsed.priority;
+    }
+    if (b.parsed.segments.length !== a.parsed.segments.length) {
+      return b.parsed.segments.length - a.parsed.segments.length;
+    }
+    return b.route.pattern.length - a.route.pattern.length;
+  });
+
+  return matchingRoutes[0].route;
+}
+
+export interface RouteInputConfig {
+  route?: string;
+  routes?: string[];
+}
+
+export interface RouteValidationError {
+  code: string;
+  message: string;
+  path?: string;
+  value?: unknown;
+  validOptions?: string[];
+}
+
+function containsWildcard(pattern: string): boolean {
+  return pattern.includes("*");
+}
+
+export function validateRouteConfig(
+  config: RouteInputConfig,
+): RouteValidationError | null {
+  const { route, routes } = config;
+
+  if (!route && !routes) {
+    return null;
+  }
+
+  if (route && routes) {
+    return {
+      code: "INVALID_ROUTE_CONFIG",
+      message:
+        "Cannot specify both 'route' and 'routes'. Use 'route' for a single exact path or 'routes' for multiple paths.",
+      path: "route",
+      value: { route, routes },
+    };
+  }
+
+  if (route && containsWildcard(route)) {
+    return {
+      code: "INVALID_ROUTE_PATTERN",
+      message:
+        "Wildcard routes must use the routes array, not 'route'. Use 'routes: [\"/api/*\"]' instead of 'route: \"/api/*\"'.",
+      path: "route",
+      value: route,
+      validOptions: [
+        'routes: ["/api/*"]',
+        'routes: ["/api/users", "/api/posts"]',
+      ],
+    };
+  }
+
+  return null;
+}

package/src/utils/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Test Utilities Index
+ *
+ * Re-exports commonly used test utilities
+ */
+
+export * from "./mock-facilitator";

package/src/utils/utils/mock-facilitator.ts

@@ -0,0 +1,184 @@
+/**
+ * Mock Facilitator for Testing
+ */
+
+/// <reference types="bun-types" />
+
+import type { PaymentPayload } from "@armory-sh/base";
+import { serve } from "bun";
+
+export interface FacilitatorVerifyRequest {
+  payload: PaymentPayload;
+  requirements: Record<string, unknown>;
+  options?: Record<string, unknown>;
+}
+
+export interface FacilitatorVerifyResponse {
+  success: boolean;
+  payerAddress?: string;
+  balance?: string;
+  requiredAmount?: string;
+  error?: string;
+}
+
+export interface FacilitatorSettleRequest {
+  payload: PaymentPayload;
+  requirements: Record<string, unknown>;
+}
+
+export interface FacilitatorSettleResponse {
+  success: boolean;
+  txHash?: string;
+  error?: string;
+}
+
+export type AnyFacilitatorRequest =
+  | FacilitatorVerifyRequest
+  | FacilitatorSettleRequest;
+export type AnyFacilitatorResponse =
+  | FacilitatorVerifyResponse
+  | FacilitatorSettleResponse;
+
+export interface MockFacilitatorOptions {
+  port?: number;
+  alwaysVerify?: boolean;
+  alwaysSettle?: boolean;
+  verifyDelay?: number;
+  settleDelay?: number;
+}
+
+let nextPort = 9100;
+
+export const createMockFacilitator = async (
+  options: MockFacilitatorOptions = {},
+): Promise<{ url: string; close: () => Promise<void> }> => {
+  const {
+    port = nextPort++,
+    alwaysVerify = true,
+    alwaysSettle = true,
+    verifyDelay = 0,
+    settleDelay = 0,
+  } = options;
+
+  const server = serve({
+    port,
+    hostname: "127.0.0.1",
+    async fetch(req: Request) {
+      const url = new URL(req.url);
+      const path = url.pathname;
+
+      const corsHeaders = {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type",
+      };
+
+      if (req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers: corsHeaders });
+      }
+
+      if (req.method !== "POST") {
+        return Response.json(
+          { error: "Method not allowed" },
+          { status: 405, headers: corsHeaders },
+        );
+      }
+
+      if (path === "/verify") {
+        const body = (await req.json()) as FacilitatorVerifyRequest;
+
+        if (verifyDelay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, verifyDelay));
+        }
+
+        const result: FacilitatorVerifyResponse = alwaysVerify
+          ? {
+              success: true,
+              payerAddress: extractPayerAddress(body.payload),
+              balance: "10000000",
+              requiredAmount: "1000000",
+            }
+          : {
+              success: false,
+              error: "Verification failed (mock error)",
+            };
+
+        return Response.json(result, { headers: corsHeaders });
+      }
+
+      if (path === "/settle") {
+        const body = (await req.json()) as FacilitatorSettleRequest;
+
+        if (settleDelay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, settleDelay));
+        }
+
+        const result: FacilitatorSettleResponse = alwaysSettle
+          ? {
+              success: true,
+              txHash: `0x${"a".repeat(64)}`,
+            }
+          : {
+              success: false,
+              error: "Settlement failed (mock error)",
+            };
+
+        return Response.json(result, { headers: corsHeaders });
+      }
+
+      return Response.json(
+        { error: "Not found" },
+        { status: 404, headers: corsHeaders },
+      );
+    },
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: async () => {
+      server.stop();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    },
+  };
+};
+
+function extractPayerAddress(payload: PaymentPayload | unknown): string {
+  if (typeof payload === "string") {
+    try {
+      payload = JSON.parse(payload);
+    } catch {
+      return "0x0000000000000000000000000000000000000000000000";
+    }
+  }
+
+  if (
+    typeof payload === "object" &&
+    payload !== null &&
+    "x402Version" in payload
+  ) {
+    const p = payload as Record<string, unknown>;
+    if ("payload" in p && typeof p.payload === "object" && p.payload !== null) {
+      const schemePayload = p.payload as Record<string, unknown>;
+      if (
+        "authorization" in schemePayload &&
+        typeof schemePayload.authorization === "object"
+      ) {
+        const auth = schemePayload.authorization as Record<string, unknown>;
+        if ("from" in auth && typeof auth.from === "string") {
+          return auth.from;
+        }
+      }
+    }
+  }
+
+  if (typeof payload === "object" && payload !== null && "from" in payload) {
+    const p = payload as Record<string, unknown>;
+    if (typeof p.from === "string") {
+      return p.from;
+    }
+  }
+
+  return "0x0000000000000000000000000000000000000000000000";
+}

package/src/utils/x402.ts

@@ -0,0 +1,147 @@
+/**
+ * X402 Protocol Utilities - Coinbase Compatible
+ *
+ * Helper functions for nonce generation, amount conversion, and other utilities.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { Address, Hex } from "../types/x402";
+
+/**
+ * Generate a random 32-byte nonce as hex string
+ * Matches Coinbase SDK format: "0x" + 64 hex characters
+ */
+export function createNonce(): Hex {
+  const bytes = randomBytes(32);
+  return `0x${bytes.toString("hex")}` as Hex;
+}
+
+/**
+ * Convert human-readable amount to atomic units
+ * e.g., "1.5" USDC -> "1500000" (6 decimals)
+ */
+export function toAtomicUnits(amount: string, decimals: number = 6): string {
+  const parts = amount.split(".");
+  const whole = parts[0];
+  const fractional = parts[1] || "";
+  const paddedFractional = fractional.padEnd(decimals, "0").slice(0, decimals);
+  return `${whole}${paddedFractional}`;
+}
+
+/**
+ * Convert atomic units to human-readable amount
+ * e.g., "1500000" -> "1.5" USDC (6 decimals)
+ */
+export function fromAtomicUnits(amount: string, decimals: number = 6): string {
+  const value = BigInt(amount);
+  const divisor = BigInt(10 ** decimals);
+  const whole = (value / divisor).toString();
+  const fractional = (value % divisor)
+    .toString()
+    .padStart(decimals, "0")
+    .replace(/0+$/, "");
+
+  if (fractional.length === 0) {
+    return whole;
+  }
+  return `${whole}.${fractional}`;
+}
+
+/**
+ * Parse signature from hex string to components
+ * Returns { r, s, v } where v is 27 or 28
+ */
+export function parseSignature(signature: Hex): { r: Hex; s: Hex; v: number } {
+  const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
+  const r = `0x${hex.slice(0, 64)}` as Hex;
+  const s = `0x${hex.slice(64, 128)}` as Hex;
+  const v = parseInt(hex.slice(128, 130) || "1c", 16);
+  return { r, s, v };
+}
+
+/**
+ * Combine signature components into hex string
+ */
+export function combineSignature(r: Hex, s: Hex, v: number): Hex {
+  const rHex = r.startsWith("0x") ? r.slice(2) : r;
+  const sHex = s.startsWith("0x") ? s.slice(2) : s;
+  const vHex = v.toString(16).padStart(2, "0");
+  return `0x${rHex}${sHex}${vHex}` as Hex;
+}
+
+/**
+ * Convert CAIP-2 chain ID to network name
+ * e.g., "eip155:8453" -> "base"
+ */
+export function caip2ToNetwork(caip2Id: string): string {
+  const match = caip2Id.match(/^eip155:(\d+)$/);
+  if (!match) {
+    return caip2Id;
+  }
+
+  const chainId = parseInt(match[1], 10);
+  const chainIdToNetwork: Record<number, string> = {
+    1: "ethereum",
+    8453: "base",
+    84532: "base-sepolia",
+    137: "polygon",
+    42161: "arbitrum",
+    421614: "arbitrum-sepolia",
+    10: "optimism",
+    11155420: "optimism-sepolia",
+    11155111: "ethereum-sepolia",
+  };
+
+  return chainIdToNetwork[chainId] || caip2Id;
+}
+
+/**
+ * Convert network name to CAIP-2 chain ID
+ * e.g., "base" -> "eip155:8453"
+ */
+export function networkToCaip2(network: string): string {
+  const networkToChainId: Record<string, number> = {
+    ethereum: 1,
+    base: 8453,
+    "base-sepolia": 84532,
+    polygon: 137,
+    arbitrum: 42161,
+    "arbitrum-sepolia": 421614,
+    optimism: 10,
+    "optimism-sepolia": 11155420,
+    "ethereum-sepolia": 11155111,
+  };
+
+  const chainId = networkToChainId[network];
+  if (chainId) {
+    return `eip155:${chainId}`;
+  }
+
+  // If already in CAIP-2 format, return as-is
+  if (network.startsWith("eip155:")) {
+    return network;
+  }
+
+  return `eip155:0`;
+}
+
+/**
+ * Get current Unix timestamp in seconds
+ */
+export function getCurrentTimestamp(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+/**
+ * Validate Ethereum address
+ */
+export function isValidAddress(address: string): address is Address {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+/**
+ * Normalize address to checksum format (basic lowercase)
+ */
+export function normalizeAddress(address: string): Address {
+  return address.toLowerCase() as Address;
+}