@bankofai/x402-cli 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/cli.js

@@ -8,9 +8,9 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
-import { createPaymentPayload, decodeRequired, decodeResponse, encodeRequired, encodeResponse, encodeSignature, headers } from "./x402.js";
-import { findTokenByAddress, getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
-const BOOLEAN_FLAGS = new Set(["daemon", "dry-run", "help", "human", "include-blocked", "json", "version"]);
+import { createPaymentPayload, decodeRequired, decodeResponse, decodeSignature, encodeRequired, encodeResponse, encodeSignature, headers } from "./x402.js";
+import { assertRawAmount, findTokenByAddress, getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
+const BOOLEAN_FLAGS = new Set(["daemon", "dry-run", "force", "help", "human", "include-blocked", "json", "version"]);
 const require = createRequire(import.meta.url);
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
@@ -55,7 +55,7 @@ function parseArgs(argv) {
         else if (BOOLEAN_FLAGS.has(key)) {
             options[key] = true;
         }
-        else if (!next || next.startsWith("-")) {
+        else if (!next || next.startsWith("--")) {
             options[key] = true;
         }
         else {
@@ -344,7 +344,11 @@ function readYaml(file) {
     return YAML.parse(fs.readFileSync(file, "utf8"));
 }
 function expandEnv(value) {
-    return value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+    return value.replace(/\$\{([^}]+)\}/g, (_, name) => {
+        if (!(name in process.env))
+            throw new Error(`environment variable \${${name}} is not set`);
+        return process.env[name] ?? "";
+    });
 }
 function expandDeep(value) {
     if (typeof value === "string")
@@ -386,6 +390,14 @@ function validateProvider(provider, file = "provider.yml") {
         if (typeof value !== "string" || !value.trim())
             throw new Error(`${file}: ${name} is required`);
     }
+    try {
+        const url = new URL(provider.forward_url);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("unsupported protocol");
+    }
+    catch {
+        throw new Error(`${file}: forward_url must be a valid http(s) URL`);
+    }
     if (!Array.isArray(provider.endpoints) || !provider.endpoints.length) {
         throw new Error(`${file}: endpoints must contain at least one endpoint`);
     }
@@ -394,6 +406,12 @@ function validateProvider(provider, file = "provider.yml") {
         if (typeof endpoint.method !== "string" || typeof endpoint.path !== "string") {
             throw new Error(`${file}: each endpoint needs method and path`);
         }
+        if (!endpoint.method.trim() || !endpoint.path.trim() || !endpoint.path.startsWith("/")) {
+            throw new Error(`${file}: endpoint method/path must be non-empty and path must start with /`);
+        }
+        const price = providerPrice(endpoint);
+        if (!Number.isFinite(price) || price < 0)
+            throw new Error(`${file}: endpoint price_usd must be a finite number >= 0`);
         const key = `${endpoint.method.toUpperCase()} ${endpoint.path}`;
         if (seen.has(key))
             throw new Error(`${file}: duplicate endpoint ${key}`);
@@ -568,11 +586,42 @@ function cachedCatalogPath() {
 function providerFilename(fqn) {
     return `${fqn.replace(/\//g, "__")}.json`;
 }
+function sanitizeProviderName(name) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,127}$/.test(name) || name.includes("..")) {
+        throw new Error("provider name must be a safe FQN using letters, numbers, dots, underscores, dashes, or slashes");
+    }
+    return name;
+}
+function safeOutputPath(baseDir, ...parts) {
+    const root = path.resolve(baseDir);
+    const target = path.resolve(root, ...parts);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`refusing to write outside output directory: ${target}`);
+    }
+    return target;
+}
+function ensureWritable(file, options) {
+    if (fs.existsSync(file) && !hasFlag(options, "force")) {
+        throw new Error(`${file} already exists; pass --force to overwrite`);
+    }
+}
 function defaultCatalogSource() {
+    const envSource = process.env.X402_CATALOG || process.env.X402_GATEWAY_CATALOG;
+    if (envSource)
+        return envSource;
     return fs.existsSync(cachedCatalogPath())
         ? cachedCatalogPath()
         : "https://x402-catalog.bankofai.io/api/catalog.json";
 }
+function positiveIntegerOption(options, key, fallback) {
+    const value = opt(options, key, String(fallback));
+    if (!/^\d+$/.test(value))
+        throw new Error(`--${key} must be a positive integer`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`--${key} must be a positive integer`);
+    return parsed;
+}
 function remoteBaseFromCatalogPayload(payload) {
     const base = payload.base_url ?? payload.baseUrl;
     return typeof base === "string" && /^https?:\/\//.test(base) ? `${base.replace(/\/+$/, "")}/` : undefined;
@@ -599,7 +648,7 @@ function catalogDetailSource(source, section, name) {
             : base.pathname.endsWith("/")
                 ? base.pathname
                 : `${base.pathname}/`;
-        base.pathname = `${pathname}${section}/${name}.json`;
+        base.pathname = `${pathname}${section}/${providerFilename(name)}`;
         base.search = "";
         base.hash = "";
         return base.toString();
@@ -616,8 +665,6 @@ async function readCatalogProvider(source, name) {
     const summary = providers.find((item) => item.name === name || item.fqn === name);
     if (!summary)
         throw new Error(`provider not found: ${name}`);
-    if (Array.isArray(summary.endpoints) && summary.endpoints.length)
-        return summary;
     const fqn = summary.fqn ?? summary.name ?? name;
     try {
         return await readJson(catalogDetailSource(source, "providers", fqn));
@@ -764,12 +811,18 @@ async function catalogExportGateway(gatewayUrl, options) {
     const providerFqn = opt(options, "provider");
     if (!providerFqn)
         throw new Error("--provider is required");
+    sanitizeProviderName(providerFqn);
     const base = gatewayUrl.replace(/\/+$/, "");
-    const detail = await readJson(`${base}/__402/catalog/providers/${providerFqn}.json`);
-    const target = opt(options, "output-dir", path.join("providers", providerFqn));
+    const detail = await readJson(`${base}/__402/catalog/providers/${providerFilename(providerFqn)}`);
+    const outputRoot = opt(options, "output-dir", "providers");
+    const target = opt(options, "output-dir")
+        ? path.resolve(outputRoot)
+        : safeOutputPath("providers", providerFilename(providerFqn).replace(/\.json$/, ""));
     fs.mkdirSync(target, { recursive: true });
     const catalogPath = path.join(target, "catalog.json");
     const payMdPath = path.join(target, "pay.md");
+    ensureWritable(catalogPath, options);
+    ensureWritable(payMdPath, options);
     writeJson(catalogPath, submissionCatalog(detail));
     fs.writeFileSync(payMdPath, payMarkdownFromDetail(detail));
     emit({ command: "catalog export-gateway", mode: outputMode(options), result: { provider: providerFqn, catalog: catalogPath, payMd: payMdPath } });
@@ -790,7 +843,11 @@ function buildRequirement(options) {
     const decimals = decimalsOption !== undefined ? Number(decimalsOption) : registryToken.decimals;
     if (!Number.isInteger(decimals) || decimals < 0)
         throw new Error("--decimals must be a non-negative integer");
-    const amount = opt(options, "rawAmount") ?? toSmallestUnit(opt(options, "amount", "0.0001"), decimals);
+    const rawAmount = opt(options, "rawAmount") ?? opt(options, "raw-amount");
+    const humanAmount = opt(options, "amount");
+    if (rawAmount && humanAmount)
+        throw new Error("--amount and --rawAmount are mutually exclusive");
+    const amount = rawAmount ? assertRawAmount(rawAmount, "--rawAmount") : toSmallestUnit(humanAmount ?? "0.0001", decimals);
     const assetAddress = explicitAsset ?? registryToken.address;
     const assetTransferMethod = registryToken?.assetTransferMethod ?? "permit2";
     return {
@@ -829,6 +886,9 @@ function stripFlag(argv, flag) {
     return argv.filter(item => item !== flag);
 }
 function serveDaemon(argv, options) {
+    const requirement = buildRequirement(options);
+    if (!requirement.payTo)
+        throw new Error("--pay-to is required");
     const daemonArgs = stripFlag(stripFlag(argv, "--daemon"), "-d");
     const script = fileURLToPath(import.meta.url);
     const child = spawn(process.execPath, [script, ...daemonArgs], {
@@ -843,7 +903,7 @@ function serveDaemon(argv, options) {
     emit({
         command: "server",
         mode: outputMode(options),
-        network: normalizeNetwork(opt(options, "network", "tron:nile")),
+        network: requirement.network,
         scheme: "exact",
         result: {
             pid: child.pid,
@@ -856,7 +916,7 @@ function serveDaemon(argv, options) {
 function validateAmountLimits(selected, options) {
     const maxRaw = opt(options, "max-rawAmount") ?? opt(options, "max-raw-amount");
     const maxAmount = opt(options, "max-amount");
-    if (maxRaw && BigInt(selected.amount) > BigInt(maxRaw)) {
+    if (maxRaw && BigInt(selected.amount) > BigInt(assertRawAmount(maxRaw, "--max-rawAmount"))) {
         throw new Error(`payment raw amount ${selected.amount} exceeds --max-rawAmount ${maxRaw}`);
     }
     if (maxAmount) {
@@ -889,17 +949,18 @@ async function serve(options) {
     };
     const server = http.createServer(async (request, response) => {
         try {
-            if (request.url?.startsWith("/health")) {
+            const pathname = new URL(request.url ?? "/", `http://${host}:${port}`).pathname;
+            if (pathname === "/health") {
                 response.writeHead(200, { "content-type": "application/json" });
                 response.end(JSON.stringify({ ok: true }));
                 return;
             }
-            if (request.url?.startsWith("/.well-known/x402")) {
+            if (pathname === "/.well-known/x402") {
                 response.writeHead(200, { "content-type": "application/json" });
-                response.end(JSON.stringify({ network: requirement.network, scheme: "exact", asset: requirement.asset, amount: requirement.amount, payTo: requirement.payTo, pay_url: resourceUrl }));
+                response.end(JSON.stringify({ network: requirement.network, scheme: "exact", asset: requirement.asset, rawAmount: requirement.amount, amount: requirement.amount, payTo: requirement.payTo, pay_url: resourceUrl }));
                 return;
             }
-            if (!request.url?.startsWith("/pay")) {
+            if (pathname !== "/pay") {
                 response.writeHead(404).end("not found");
                 return;
             }
@@ -912,22 +973,33 @@ async function serve(options) {
                 response.end(JSON.stringify(challenge));
                 return;
             }
-            const payload = Buffer.from(signature, "base64").toString("utf8").startsWith("{")
-                ? JSON.parse(Buffer.from(signature, "base64").toString("utf8"))
-                : signature;
+            let payload;
+            try {
+                payload = decodeSignature(signature);
+            }
+            catch {
+                response.writeHead(400, { "content-type": "application/json" });
+                response.end(JSON.stringify({ error: "invalid payment signature" }));
+                return;
+            }
             const verify = await facilitatorPost(facilitatorUrl, "/verify", {
                 paymentPayload: payload,
                 paymentRequirements: requirement,
             });
-            if (verify?.valid === false || verify?.isValid === false) {
+            if (!(verify?.valid === true || verify?.isValid === true)) {
                 response.writeHead(400, { "content-type": "application/json" });
-                response.end(JSON.stringify({ error: "payment verification failed", verify }));
+                response.end(JSON.stringify({ error: "payment verification failed" }));
                 return;
             }
             const settle = await facilitatorPost(facilitatorUrl, "/settle", {
                 paymentPayload: payload,
                 paymentRequirements: requirement,
             });
+            if (!(settle?.success === true || settle?.settled === true || typeof settle?.transaction === "string" || typeof settle?.txHash === "string")) {
+                response.writeHead(502, { "content-type": "application/json" });
+                response.end(JSON.stringify({ error: "settlement failed" }));
+                return;
+            }
             response.writeHead(200, {
                 "content-type": "application/json",
                 [headers.response]: encodeResponse(settle),
@@ -939,13 +1011,18 @@ async function serve(options) {
             response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
         }
     });
-    server.listen(port, host, () => {
-        emit({
-            command: "server",
-            network: requirement.network,
-            scheme: "exact",
-            mode: outputMode(options),
-            result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo },
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            emit({
+                command: "server",
+                network: requirement.network,
+                scheme: "exact",
+                mode: outputMode(options),
+                result: { pay_url: resourceUrl, token: opt(options, "token", "USDT"), rawAmount: requirement.amount, pay_to: requirement.payTo },
+            });
+            resolve();
         });
     });
 }
@@ -1025,7 +1102,7 @@ async function pay(url, options) {
     const paid = await fetch(url, {
         method,
         headers: retryHeaders,
-        body: opt(options, "body"),
+        body: ["GET", "HEAD"].includes(method.toUpperCase()) ? undefined : opt(options, "body"),
     });
     const body = await responsePayload(paid);
     const paymentResponse = paid.headers.get(headers.response);
@@ -1281,7 +1358,7 @@ async function searchCatalog(source, query, options) {
     }
     return hits
         .sort((a, b) => b.score - a.score || a.fqn.localeCompare(b.fqn))
-        .slice(0, Number(opt(options, "limit", "10")));
+        .slice(0, positiveIntegerOption(options, "limit", 10));
 }
 function searchHitToJson(hit) {
     return {

package/dist/gateway/cli.js

@@ -1,33 +1,218 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import { loadProviders } from "./config.js";
 import { createGatewayServer } from "./server.js";
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+const VALUE_OPTIONS = new Set(["provider", "providers", "host", "port"]);
+const BOOLEAN_OPTIONS = new Set(["debug", "help", "json", "quiet", "version"]);
+const ALL_OPTIONS = new Set([...VALUE_OPTIONS, ...BOOLEAN_OPTIONS]);
 function parseArgs(argv) {
+    const explicitCommand = Boolean(argv[0] && !argv[0].startsWith("-"));
+    const command = explicitCommand ? argv[0] : "start";
+    const rest = explicitCommand ? argv.slice(1) : argv;
     const options = {};
-    for (let i = 0; i < argv.length; i += 1) {
-        const item = argv[i];
-        if (!item.startsWith("--"))
+    if (command !== "start" && command !== "check") {
+        throw new CliError(`Unknown command: ${command}`);
+    }
+    for (let i = 0; i < rest.length; i += 1) {
+        const item = rest[i];
+        if (item === "-h") {
+            options.help = true;
             continue;
-        const key = item.slice(2);
-        const next = argv[i + 1];
-        if (!next || next.startsWith("--"))
+        }
+        if (item === "-v" || item === "-V") {
+            options.version = true;
+            continue;
+        }
+        if (!item.startsWith("--"))
+            throw new CliError(`Unexpected argument: ${item}`);
+        const eq = item.indexOf("=");
+        const key = eq > 2 ? item.slice(2, eq) : item.slice(2);
+        if (!ALL_OPTIONS.has(key))
+            throw new CliError(`Unknown option: --${key}`);
+        if (BOOLEAN_OPTIONS.has(key)) {
+            if (eq > 2)
+                throw new CliError(`Option --${key} does not take a value`);
             options[key] = true;
+            continue;
+        }
+        const inline = eq > 2 ? item.slice(eq + 1) : undefined;
+        const next = rest[i + 1];
+        if (inline !== undefined) {
+            if (!inline)
+                throw new CliError(`Option --${key} requires a value`);
+            options[key] = inline;
+        }
         else {
+            if (!next || next.startsWith("--"))
+                throw new CliError(`Option --${key} requires a value`);
             options[key] = next;
             i += 1;
         }
     }
-    return options;
+    return { command, options };
 }
 function opt(options, key, fallback) {
     const value = options[key];
     return typeof value === "string" ? value : fallback;
 }
-const options = parseArgs(process.argv.slice(2));
-const providersPath = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR || "/app/providers"));
-const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "0.0.0.0");
-const port = Number(opt(options, "port", process.env.PORT || "8080"));
-const providers = loadProviders(providersPath);
-const server = createGatewayServer(providers);
-server.listen(port, host, () => {
-    process.stdout.write(JSON.stringify({ ok: true, host, port, providers: [...providers.keys()] }, null, 2) + "\n");
+function flag(options, key) {
+    return options[key] === true;
+}
+function version() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        return String(JSON.parse(fs.readFileSync(url, "utf8")).version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function help() {
+    return `x402-gateway ${version()}
+
+Usage:
+  x402-gateway start --providers <dir> [options]
+  x402-gateway --providers <dir> [options]
+  x402-gateway check --providers <dir>
+  x402-gateway check --provider <file>
+
+Commands:
+  start                  Start the x402 gateway server (default)
+  check                  Validate provider YAML and print a summary
+
+Options:
+  --provider <file>      Load one provider YAML file
+  --providers <dir>      Load provider.yml/provider.yaml files from a directory
+  --host <host>          Bind host (default: 127.0.0.1)
+  --port <port>          Bind port (default: 8080)
+  --json                 Print machine-readable JSON
+  --quiet                Suppress startup/shutdown messages
+  --debug                Print stack traces for startup errors
+  -h, --help             Show help
+  -v, -V, --version      Show version
+
+Examples:
+  x402-gateway --provider examples/provider.yml --host 127.0.0.1 --port 4020
+  x402-gateway start --providers providers --port 4020
+  x402-gateway check --providers providers --json
+`;
+}
+function providerPath(options) {
+    const source = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR));
+    if (!source)
+        throw new CliError("No provider source configured. Use --provider <file> or --providers <dir>.");
+    return source;
+}
+function parsePort(value) {
+    const raw = value ?? process.env.PORT ?? "8080";
+    if (!/^\d+$/.test(raw))
+        throw new CliError(`Invalid --port ${raw}; expected an integer between 1 and 65535`);
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new CliError(`Invalid --port ${raw}; expected an integer between 1 and 65535`);
+    }
+    return port;
+}
+function publicHost(host) {
+    return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+function printStartup(options, host, port, providers) {
+    if (flag(options, "quiet"))
+        return;
+    if (flag(options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: true, host, port, providers }, null, 2) + "\n");
+        return;
+    }
+    const base = `http://${publicHost(host)}:${port}`;
+    process.stdout.write(`x402-gateway listening on ${base}\n`);
+    process.stdout.write(`providers: ${providers.length} loaded\n`);
+    process.stdout.write(`health: ${base}/__402/health\n`);
+    process.stdout.write(`ready: ${base}/__402/ready\n`);
+}
+function check(options) {
+    const source = providerPath(options);
+    const providers = loadProviders(source);
+    const summary = [...providers.values()].map(entry => ({
+        name: entry.config.name,
+        network: entry.config.operator.network,
+        endpoints: entry.config.endpoints?.length ?? 0,
+    }));
+    if (flag(options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: true, source, count: summary.length, providers: summary }, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write(`ok: ${summary.length} provider${summary.length === 1 ? "" : "s"} loaded from ${source}\n`);
+    for (const item of summary) {
+        process.stdout.write(`  ${item.name} (${item.network}) endpoints=${item.endpoints}\n`);
+    }
+}
+async function start(options) {
+    const source = providerPath(options);
+    const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "127.0.0.1");
+    const port = parsePort(opt(options, "port"));
+    const providers = loadProviders(source);
+    const server = createGatewayServer(providers);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            printStartup(options, host, port, [...providers.keys()]);
+            resolve();
+        });
+    });
+    const shutdown = (signal) => {
+        if (!flag(options, "quiet") && !flag(options, "json"))
+            process.stderr.write(`received ${signal}, shutting down...\n`);
+        server.close(() => {
+            if (!flag(options, "quiet") && !flag(options, "json"))
+                process.stderr.write("server closed\n");
+            process.exit(0);
+        });
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (flag(parsed.options, "help")) {
+        process.stdout.write(help());
+        return;
+    }
+    if (flag(parsed.options, "version")) {
+        process.stdout.write(`${version()}\n`);
+        return;
+    }
+    if (parsed.command === "check")
+        check(parsed.options);
+    else
+        await start(parsed.options);
+}
+main().catch(error => {
+    const parsed = (() => {
+        try {
+            return parseArgs(process.argv.slice(2));
+        }
+        catch {
+            return { options: {} };
+        }
+    })();
+    const message = error instanceof Error ? error.message : String(error);
+    if (flag(parsed.options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: false, error: { message } }, null, 2) + "\n");
+    }
+    else {
+        process.stderr.write(`x402-gateway: ${message}\n`);
+        process.stderr.write("Run `x402-gateway --help` for usage.\n");
+        if (flag(parsed.options, "debug") && error instanceof Error && error.stack) {
+            process.stderr.write(`${error.stack}\n`);
+        }
+    }
+    process.exit(error instanceof CliError ? error.exitCode : 1);
 });

package/dist/gateway/config.js

@@ -3,7 +3,11 @@ import path from "node:path";
 import YAML from "yaml";
 import { getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
 function expandEnv(value) {
-    return value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+    return value.replace(/\$\{([^}]+)\}/g, (_, name) => {
+        if (!(name in process.env))
+            throw new Error(`environment variable \${${name}} is not set`);
+        return process.env[name] ?? "";
+    });
 }
 function expandDeep(value) {
     if (typeof value === "string")
@@ -19,11 +23,63 @@ function assertString(value, name) {
     if (typeof value !== "string" || !value.trim())
         throw new Error(`${name} is required`);
 }
+function assertHttpUrl(value, name) {
+    if (!value)
+        return;
+    try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("unsupported protocol");
+    }
+    catch {
+        throw new Error(`${name} must be a valid http(s) URL`);
+    }
+}
+function validateTiers(tiers, file, path) {
+    if (!Array.isArray(tiers) || !tiers.length)
+        throw new Error(`${file}: ${path}.tiers must contain at least one tier`);
+    for (const [tierIndex, tier] of tiers.entries()) {
+        const price = tier?.price_usd;
+        if (typeof price !== "number" || !Number.isFinite(price) || price < 0) {
+            throw new Error(`${file}: ${path}.tiers[${tierIndex}].price_usd must be a finite number >= 0`);
+        }
+    }
+}
+function validateDimensions(dimensions, file, path) {
+    if (!Array.isArray(dimensions) || !dimensions.length) {
+        throw new Error(`${file}: ${path}.dimensions must contain at least one dimension`);
+    }
+    if (dimensions.length !== 1)
+        throw new Error(`${file}: ${path}.dimensions currently supports exactly one dimension`);
+    for (const [dimensionIndex, dimension] of dimensions.entries()) {
+        validateTiers(dimension?.tiers, file, `${path}.dimensions[${dimensionIndex}]`);
+    }
+}
+function validateMetering(endpoint, file, path) {
+    if (!endpoint.metering)
+        return;
+    validateDimensions(endpoint.metering.dimensions, file, `${path}.metering`);
+    for (const [variantIndex, variant] of (endpoint.metering.variants ?? []).entries()) {
+        assertString(variant.param, `${file}: ${path}.metering.variants[${variantIndex}].param`);
+        assertString(variant.value, `${file}: ${path}.metering.variants[${variantIndex}].value`);
+        validateDimensions(variant.dimensions, file, `${path}.metering.variants[${variantIndex}]`);
+    }
+}
 function validateProvider(config, file) {
     assertString(config.name, `${file}: name`);
     assertString(config.forward_url, `${file}: forward_url`);
     assertString(config.operator?.network, `${file}: operator.network`);
     assertString(config.operator?.recipient, `${file}: operator.recipient`);
+    assertHttpUrl(config.forward_url, `${file}: forward_url`);
+    assertHttpUrl(config.operator?.facilitator_url, `${file}: operator.facilitator_url`);
+    if (config.operator?.valid_for_seconds !== undefined &&
+        (!Number.isFinite(config.operator.valid_for_seconds) || config.operator.valid_for_seconds <= 0)) {
+        throw new Error(`${file}: operator.valid_for_seconds must be > 0`);
+    }
+    const authMethod = config.routing?.auth?.method;
+    if (authMethod && !["header", "query_param", "access_token", "oauth2"].includes(authMethod)) {
+        throw new Error(`${file}: unsupported routing.auth.method ${authMethod}`);
+    }
     if (!config.endpoints?.length)
         throw new Error(`${file}: endpoints must contain at least one endpoint`);
     const seen = new Set();
@@ -40,11 +96,7 @@ function validateProvider(config, file) {
         if (seen.has(key))
             throw new Error(`${file}: duplicate endpoint ${key}`);
         seen.add(key);
-        for (const [tierIndex, tier] of (endpoint.metering?.dimensions?.[0]?.tiers ?? []).entries()) {
-            if (typeof tier.price_usd !== "number" || tier.price_usd < 0) {
-                throw new Error(`${file}: endpoints[${index}].metering tier ${tierIndex} price_usd must be >= 0`);
-            }
-        }
+        validateMetering(endpoint, file, `endpoints[${index}]`);
     }
 }
 export function loadProvider(file) {
@@ -111,8 +163,14 @@ function pathMatches(template, routePath) {
     });
 }
 export function priceUsd(endpoint, params = {}) {
+    if (!endpoint?.metering)
+        return 0;
     const variant = endpoint?.metering?.variants?.find(item => params[item.param] === item.value);
-    return (variant?.dimensions ?? endpoint?.metering?.dimensions)?.[0]?.tiers?.[0]?.price_usd ?? 0;
+    const price = (variant?.dimensions ?? endpoint.metering.dimensions)?.[0]?.tiers?.[0]?.price_usd;
+    if (typeof price !== "number" || !Number.isFinite(price) || price < 0) {
+        throw new Error(`invalid metering price for ${endpoint.method} ${endpoint.path}`);
+    }
+    return price;
 }
 export function paymentRequirements(provider, price) {
     if (price <= 0)
@@ -123,10 +181,13 @@ export function paymentRequirements(provider, price) {
     return symbols.map(symbol => {
         const token = getToken(network, symbol);
         const transferMethod = provider.operator.assetTransferMethod || provider.operator.asset_transfer_method || token.assetTransferMethod;
+        const amount = toSmallestUnit(price, token.decimals);
+        if (amount === "0")
+            throw new Error(`positive price produced zero amount for ${symbol} on ${network}`);
         return {
             scheme: "exact",
             network,
-            amount: toSmallestUnit(price, token.decimals),
+            amount,
             asset: token.address,
             payTo,
             maxTimeoutSeconds: provider.operator.valid_for_seconds ?? 300,

package/dist/gateway/server.js

@@ -2,37 +2,106 @@ import http from "node:http";
 import { URL } from "node:url";
 import { endpointFor, paymentRequirements, priceUsd } from "./config.js";
 import { decodeSignature, encodeRequired, encodeResponse, headers, matchRequirement } from "./x402.js";
+class HttpError extends Error {
+    status;
+    publicMessage;
+    constructor(status, publicMessage, message = publicMessage) {
+        super(message);
+        this.status = status;
+        this.publicMessage = publicMessage;
+    }
+}
+class RequestTooLargeError extends HttpError {
+    constructor() {
+        super(413, "request body too large");
+    }
+}
+const MAX_BODY_BYTES = Number(process.env.X402_GATEWAY_MAX_BODY_BYTES ?? 1_000_000);
+const FACILITATOR_TIMEOUT_MS = Number(process.env.X402_GATEWAY_FACILITATOR_TIMEOUT_MS ?? 10_000);
+const UPSTREAM_TIMEOUT_MS = Number(process.env.X402_GATEWAY_UPSTREAM_TIMEOUT_MS ?? 30_000);
+const STRIP_REQUEST_HEADERS = new Set([
+    "host",
+    "connection",
+    "transfer-encoding",
+    "content-length",
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-access-token",
+    "x-payment",
+    "payment-signature",
+    "payment-required",
+    "x-payment-required",
+    "accept-encoding",
+]);
+const STRIP_RESPONSE_HEADERS = new Set([
+    "connection",
+    "transfer-encoding",
+    "content-encoding",
+    "content-length",
+    "authorization",
+    "proxy-authorization",
+    "set-cookie",
+]);
 const metrics = {
     requests: 0,
     paidRequests: 0,
     verifyFailures: 0,
     settleFailures: 0,
+    feeQuoteFailures: 0,
     upstreamFailures: 0,
 };
 async function readBody(request) {
     const chunks = [];
-    for await (const chunk of request)
-        chunks.push(Buffer.from(chunk));
+    let total = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.from(chunk);
+        total += buffer.length;
+        if (total > MAX_BODY_BYTES)
+            throw new RequestTooLargeError();
+        chunks.push(buffer);
+    }
     return Buffer.concat(chunks);
 }
 function json(response, status, body, extraHeaders = {}) {
     response.writeHead(status, { "content-type": "application/json", ...extraHeaders });
     response.end(JSON.stringify(body));
 }
+async function fetchWithTimeout(url, init, timeoutMs, label = "upstream") {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error?.name === "AbortError")
+            throw new HttpError(504, `${label} request timed out`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function facilitatorPost(entry, path, body) {
     const headers = { "content-type": "application/json" };
     if (entry.facilitatorApiKey) {
         headers.authorization = `Bearer ${entry.facilitatorApiKey}`;
     }
-    const response = await fetch(new URL(path, entry.facilitatorUrl), {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-    });
+    const response = await fetchWithTimeout(new URL(path, entry.facilitatorUrl), { method: "POST", headers, body: JSON.stringify(body) }, FACILITATOR_TIMEOUT_MS, "facilitator");
     const text = await response.text();
-    const data = text ? JSON.parse(text) : {};
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new HttpError(502, "facilitator returned invalid response");
+    }
     if (!response.ok)
-        throw new Error(`facilitator ${path} failed: ${response.status} ${text}`);
+        throw new HttpError(502, "facilitator request failed", `facilitator ${path} failed: ${response.status} ${text}`);
     return data;
 }
 async function attachFeeQuotes(entry, requirements, context) {
@@ -49,14 +118,25 @@ async function attachFeeQuotes(entry, requirements, context) {
             return quote?.fee ? { ...requirement, extra: { ...requirement.extra, fee: quote.fee } } : requirement;
         });
     }
-    catch {
+    catch (error) {
+        metrics.feeQuoteFailures += 1;
+        console.warn("fee quote failed", error);
         return requirements;
     }
 }
+function isVerifySuccess(verify) {
+    return verify?.valid === true || verify?.isValid === true;
+}
+function isSettleSuccess(settle) {
+    return (settle?.success === true ||
+        settle?.settled === true ||
+        (typeof settle?.transaction === "string" && settle.transaction.length > 0) ||
+        (typeof settle?.txHash === "string" && settle.txHash.length > 0));
+}
 function isAdminAllowed(request) {
     const token = process.env.X402_GATEWAY_ADMIN_TOKEN;
     if (!token)
-        return true;
+        return process.env.X402_GATEWAY_ADMIN_ALLOW_PUBLIC === "true";
     const auth = request.headers.authorization ?? "";
     return auth === `Bearer ${token}`;
 }
@@ -89,7 +169,7 @@ function upstreamHeaders(request, entry) {
         if (!value)
             continue;
         const lower = key.toLowerCase();
-        if (["host", "connection", "content-length", "authorization", "payment-signature"].includes(lower))
+        if (STRIP_REQUEST_HEADERS.has(lower))
             continue;
         headersOut.set(key, Array.isArray(value) ? value.join(",") : value);
     }
@@ -114,14 +194,23 @@ function upstreamUrl(entry, request, routePath) {
 }
 async function forward(entry, request, response, routePath, body, paymentResponse) {
     const upstream = upstreamUrl(entry, request, routePath);
-    const upstreamResponse = await fetch(upstream, {
-        method: request.method,
-        headers: upstreamHeaders(request, entry),
-        body: ["GET", "HEAD"].includes(request.method ?? "GET") ? undefined : new Uint8Array(body),
-    });
+    let upstreamResponse;
+    try {
+        upstreamResponse = await fetchWithTimeout(upstream, {
+            method: request.method,
+            headers: upstreamHeaders(request, entry),
+            body: ["GET", "HEAD"].includes(request.method ?? "GET") ? undefined : new Uint8Array(body),
+        }, UPSTREAM_TIMEOUT_MS);
+    }
+    catch (error) {
+        metrics.upstreamFailures += 1;
+        if (error instanceof HttpError)
+            throw error;
+        throw new HttpError(502, "upstream request failed");
+    }
     const responseHeaders = {};
     upstreamResponse.headers.forEach((value, key) => {
-        if (!["connection", "transfer-encoding", "content-encoding", "content-length"].includes(key.toLowerCase())) {
+        if (!STRIP_RESPONSE_HEADERS.has(key.toLowerCase())) {
             responseHeaders[key] = value;
         }
     });
@@ -140,7 +229,7 @@ export function createGatewayServer(providers) {
                 return;
             }
             if (url.pathname === "/__402/ready") {
-                json(response, 200, { ok: true, providers: providers.size });
+                json(response, providers.size ? 200 : 503, { ok: providers.size > 0, providers: providers.size });
                 return;
             }
             if (url.pathname === "/__402/providers") {
@@ -168,12 +257,15 @@ export function createGatewayServer(providers) {
                 return;
             }
             if (url.pathname === "/metrics") {
+                if (!isAdminAllowed(request))
+                    return json(response, 401, { error: "unauthorized" });
                 response.writeHead(200, { "content-type": "text/plain; version=0.0.4" });
                 response.end([
                     `x402_gateway_requests_total ${metrics.requests}`,
                     `x402_gateway_paid_requests_total ${metrics.paidRequests}`,
                     `x402_gateway_verify_failures_total ${metrics.verifyFailures}`,
                     `x402_gateway_settle_failures_total ${metrics.settleFailures}`,
+                    `x402_gateway_fee_quote_failures_total ${metrics.feeQuoteFailures}`,
                     `x402_gateway_upstream_failures_total ${metrics.upstreamFailures}`,
                     "",
                 ].join("\n"));
@@ -213,7 +305,14 @@ export function createGatewayServer(providers) {
                 json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
                 return;
             }
-            const payload = decodeSignature(paymentHeader);
+            let payload;
+            try {
+                payload = decodeSignature(paymentHeader);
+            }
+            catch {
+                json(response, 400, { error: "invalid payment signature" });
+                return;
+            }
             const requirement = requirements.find(item => matchRequirement(payload, item));
             if (!requirement) {
                 json(response, 400, { error: "payment does not match any requirement" });
@@ -223,9 +322,9 @@ export function createGatewayServer(providers) {
                 paymentPayload: payload,
                 paymentRequirements: requirement,
             });
-            if (verify?.valid === false || verify?.isValid === false) {
+            if (!isVerifySuccess(verify)) {
                 metrics.verifyFailures += 1;
-                json(response, 400, { error: "payment verification failed", verify });
+                json(response, 400, { error: "payment verification failed" });
                 return;
             }
             let settle;
@@ -239,11 +338,21 @@ export function createGatewayServer(providers) {
                 metrics.settleFailures += 1;
                 throw error;
             }
+            if (!isSettleSuccess(settle)) {
+                metrics.settleFailures += 1;
+                json(response, 502, { error: "settlement failed" });
+                return;
+            }
             metrics.paidRequests += 1;
             await forward(entry, request, response, routePath, body, settle);
         }
         catch (error) {
-            json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+            if (error instanceof HttpError) {
+                json(response, error.status, { error: error.publicMessage });
+                return;
+            }
+            console.error(error);
+            json(response, 500, { error: "internal server error" });
         }
     });
 }

package/dist/gateway/tokens.js

@@ -31,8 +31,37 @@ export function getToken(network, symbol) {
         throw new Error(`unknown token ${symbol} on ${network}`);
     return token;
 }
+function numberToDecimalString(amount) {
+    const value = amount.toString();
+    const match = value.match(/^(\d+(?:\.\d+)?)[eE]([+-]?\d+)$/);
+    if (!match)
+        return value;
+    const [, coefficient, exponentText] = match;
+    const exponent = Number(exponentText);
+    const [whole, fraction = ""] = coefficient.split(".");
+    const digits = whole + fraction;
+    const decimalIndex = whole.length + exponent;
+    if (decimalIndex <= 0)
+        return `0.${"0".repeat(Math.abs(decimalIndex))}${digits}`.replace(/0+$/, "");
+    if (decimalIndex >= digits.length)
+        return `${digits}${"0".repeat(decimalIndex - digits.length)}`;
+    return `${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`.replace(/0+$/, "").replace(/\.$/, "");
+}
 export function toSmallestUnit(amount, decimals) {
-    const [whole, fraction = ""] = String(amount).split(".");
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new Error(`invalid token decimals ${decimals}`);
+    const numeric = typeof amount === "number" ? amount : Number(amount);
+    if (!Number.isFinite(numeric) || numeric < 0)
+        throw new Error(`invalid amount ${amount}`);
+    const value = typeof amount === "number" ? numberToDecimalString(amount) : String(amount);
+    if (!/^\d+(\.\d+)?$/.test(value))
+        throw new Error(`invalid decimal amount ${amount}`);
+    const [whole, fraction = ""] = value.split(".");
     const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);
-    return (BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+    let units = BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0");
+    if (fraction.length > decimals && /[1-9]/.test(fraction.slice(decimals)))
+        units += 1n;
+    if (numeric > 0 && units === 0n)
+        units = 1n;
+    return units.toString();
 }

package/dist/tokens.js

@@ -92,8 +92,19 @@ export function findTokenByAddress(network, address) {
     const lower = address.toLowerCase();
     return Object.values(TOKENS[normalizeNetwork(network)] ?? {}).find(token => token.address.toLowerCase() === lower);
 }
+export function assertRawAmount(value, name = "raw amount") {
+    if (!/^\d+$/.test(value))
+        throw new Error(`${name} must be a non-negative integer string`);
+    return value.replace(/^0+(?=\d)/, "");
+}
 export function toSmallestUnit(amount, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new Error("token decimals must be a non-negative integer");
+    if (!/^\d+(\.\d+)?$/.test(amount))
+        throw new Error("amount must be a non-negative decimal string");
     const [whole, fraction = ""] = amount.split(".");
+    if (fraction.length > decimals)
+        throw new Error(`amount has more than ${decimals} decimal places`);
     const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);
-    return (BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+    return assertRawAmount((BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "type": "module",
   "files": [
     "dist"
@@ -22,9 +22,10 @@
   "dependencies": {
     "@bankofai/x402-core": "1.0.0",
     "@bankofai/x402-evm": "1.0.0",
+    "@bankofai/x402-gateway": "^1.0.0-beta.1",
     "@bankofai/x402-tron": "1.0.0",
-    "tronweb": "^6.0.4",
-    "viem": "^2.40.3",
+    "tronweb": "6.4.0",
+    "viem": "^2.55.0",
     "yaml": "^2.8.2"
   },
   "devDependencies": {