@bankofai/x402-gateway 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -17,18 +17,43 @@ npm install
 npm run build
 ```
 
+After installing the npm package globally, use the binary directly:
+
+```bash
+npm install -g @bankofai/x402-gateway
+x402-gateway --help
+```
+
 ## Run
 
 Start from a single provider file:
 
 ```bash
-node dist/cli.js --provider examples/provider.yml --host 127.0.0.1 --port 4020
+x402-gateway --provider examples/provider.yml --host 127.0.0.1 --port 4020
 ```
 
 Start from a providers directory:
 
 ```bash
-node dist/cli.js --providers providers --host 0.0.0.0 --port 4020
+x402-gateway --providers providers --host 127.0.0.1 --port 4020
+```
+
+Validate provider files without starting the server:
+
+```bash
+x402-gateway check --providers providers
+x402-gateway check --provider examples/provider.yml --json
+```
+
+`check` validates provider YAML syntax, required fields, environment expansion,
+network aliases, endpoint shape, and duplicate provider names. It does not call
+upstream APIs, facilitator services, RPC endpoints, recipient addresses, or the
+full payment path.
+
+Run from source during development:
+
+```bash
+npm run dev -- --providers providers --host 127.0.0.1 --port 4020
 ```
 
 Health check:
@@ -48,6 +73,45 @@ If the endpoint has metering, the gateway returns `402 Payment Required` with a
 the gateway verifies and settles with the facilitator, then forwards to the
 configured upstream.
 
+## CLI
+
+```text
+x402-gateway start --providers <dir> [options]
+x402-gateway --providers <dir> [options]
+x402-gateway check --providers <dir>
+x402-gateway check --provider <file>
+```
+
+Options:
+
+- `--provider <file>`: load one provider YAML file.
+- `--providers <dir>`: recursively load `provider.yml` / `provider.yaml`.
+  `--provider` and `--providers` are mutually exclusive.
+- `--host <host>`: bind host. The CLI default is `127.0.0.1`; Docker passes `0.0.0.0`.
+- `--port <port>`: bind port, default `8080`.
+- `--json`: machine-readable startup/check/error output.
+- `--quiet`: suppress startup, shutdown, and successful `check` output.
+- `--debug`: include stack traces for startup errors.
+- `--help`, `--version`: inspect usage and installed version.
+
+Startup prints human-readable URLs by default:
+
+```text
+x402-gateway listening on http://127.0.0.1:4020
+providers: 14 loaded
+health: http://127.0.0.1:4020/__402/health
+ready: http://127.0.0.1:4020/__402/ready
+```
+
+With `--json`, startup output includes `source`, `host`, `port`, `count`,
+`providers`, `health`, and `ready` for deployment scripts. CLI errors also
+honor `--json`, including argument parsing errors such as unknown options.
+
+Admin endpoints such as `/__402/providers`, `/__402/endpoints`, and `/metrics`
+are protected by default. Set `X402_GATEWAY_ADMIN_TOKEN` in deployed
+environments and call them with `Authorization: Bearer <token>`. For a
+deliberately public test deployment, set `X402_GATEWAY_ADMIN_ALLOW_PUBLIC=true`.
+
 ## Provider Config
 
 Provider files stay in YAML:
@@ -99,9 +163,32 @@ Network aliases accepted:
 ## Environment
 
 ```bash
-X402_FACILITATOR_URL=https://facilitator.bankofai.io
-X402_FACILITATOR_API_KEY=<optional-facilitator-api-key>
+X402_GATEWAY_PROVIDERS_DIR=providers
+X402_GATEWAY_HOST=127.0.0.1
+PORT=8080
+X402_GATEWAY_ADMIN_TOKEN=<admin-token>
+X402_FACILITATOR_URL=https://facilitator-v2.bankofai.io
+X402_FACILITATOR_API_KEY=<facilitator-api-key>
 X402_PROVIDER_FORWARD_URL=<upstream-base-url>
 X402_PROVIDER_RECIPIENT_TRON=<recipient-T-address>
 X402_PROVIDER_API_TOKEN=<upstream-token>
 ```
+
+Provider YAML may also use `operator.facilitator_api_key_env:
+X402_FACILITATOR_API_KEY` so deployments can inject the facilitator API key via
+environment variable without storing it in the mounted provider file.
+
+## Docker
+
+The container runs the same CLI binary:
+
+```bash
+docker run --rm -p 4020:8080 \
+  -v "$PWD/providers:/app/providers:ro" \
+  -e X402_GATEWAY_ADMIN_TOKEN=<admin-token> \
+  -e X402_FACILITATOR_API_KEY=<facilitator-api-key> \
+  bankofai/x402-gateway:<tag>
+```
+
+The Docker command binds `0.0.0.0:8080` explicitly; local CLI runs default to
+`127.0.0.1` unless `--host` or `X402_GATEWAY_HOST` is set.

package/dist/cli.js

@@ -1,33 +1,263 @@
 #!/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;
+        }
+        if (item === "-v" || item === "-V") {
+            options.version = true;
             continue;
-        const key = item.slice(2);
-        const next = argv[i + 1];
-        if (!next || next.startsWith("--"))
+        }
+        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 rawHasFlag(argv, name, short) {
+    return argv.some(item => item === `--${name}` || item.startsWith(`--${name}=`) || (short ? item === short : false));
+}
+function readVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        const version = JSON.parse(fs.readFileSync(url, "utf8")).version;
+        return typeof version === "string" && version ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function help() {
+    return `x402-gateway ${readVersion() ?? "unknown"}
+
+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) {
+    if (opt(options, "provider") && opt(options, "providers")) {
+        throw new CliError("Options --provider and --providers are mutually exclusive.");
+    }
+    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 parseHost(value) {
+    const host = value ?? process.env.X402_GATEWAY_HOST ?? "127.0.0.1";
+    if (!host.trim())
+        throw new CliError("Invalid --host; expected a non-empty host.");
+    return host;
+}
+function listenErrorMessage(error, host, port) {
+    const err = error;
+    if (err?.code === "EADDRINUSE")
+        return `Port ${port} is already in use on ${host}. Choose another --port or stop the existing process.`;
+    if (err?.code === "EADDRNOTAVAIL")
+        return `Host ${host} is not available on this machine. Use --host 127.0.0.1 for local runs or --host 0.0.0.0 in containers.`;
+    return error instanceof Error ? error.message : String(error);
+}
+function publicHost(host) {
+    return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+function localUrls(host, port) {
+    const base = `http://${publicHost(host)}:${port}`;
+    return {
+        base,
+        health: `${base}/__402/health`,
+        ready: `${base}/__402/ready`,
+    };
+}
+function printStartup(options, source, host, port, providers) {
+    if (flag(options, "quiet"))
+        return;
+    const urls = localUrls(host, port);
+    if (flag(options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: true, source, host, port, count: providers.length, providers, health: urls.health, ready: urls.ready }, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write(`x402-gateway listening on ${urls.base}\n`);
+    process.stdout.write(`providers: ${providers.length} loaded\n`);
+    process.stdout.write(`health: ${urls.health}\n`);
+    process.stdout.write(`ready: ${urls.ready}\n`);
+}
+function loadProvidersForCli(action, source) {
+    try {
+        return loadProviders(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to load providers from ${source} for ${action}: ${message}`);
+    }
+}
+function check(options) {
+    const source = providerPath(options);
+    const providers = loadProvidersForCli("check", 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;
+    }
+    if (flag(options, "quiet"))
+        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 = parseHost(opt(options, "host"));
+    const port = parsePort(opt(options, "port"));
+    const providers = loadProvidersForCli("start", source);
+    const server = createGatewayServer(providers);
+    await new Promise((resolve, reject) => {
+        server.once("error", error => reject(new Error(listenErrorMessage(error, host, port))));
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            printStartup(options, source, host, port, [...providers.keys()]);
+            resolve();
+        });
+    });
+    const shutdown = (signal) => {
+        if (!flag(options, "quiet") && !flag(options, "json"))
+            process.stderr.write(`received ${signal}, shutting down...\n`);
+        const timeout = setTimeout(() => {
+            if (!flag(options, "quiet") && !flag(options, "json"))
+                process.stderr.write("server close timed out; exiting\n");
+            process.exit(1);
+        }, 10_000);
+        timeout.unref();
+        server.close(() => {
+            clearTimeout(timeout);
+            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")) {
+        const version = readVersion();
+        if (!version)
+            throw new Error("Unable to read package version.");
+        process.stdout.write(`${version}\n`);
+        return;
+    }
+    if (parsed.command === "check")
+        check(parsed.options);
+    else
+        await start(parsed.options);
+}
+main().catch(error => {
+    const argv = process.argv.slice(2);
+    const json = rawHasFlag(argv, "json");
+    const debug = rawHasFlag(argv, "debug");
+    const message = error instanceof Error ? error.message : String(error);
+    if (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 (debug && error instanceof Error && error.stack) {
+            process.stderr.write(`${error.stack}\n`);
+        }
+    }
+    process.exit(error instanceof CliError ? error.exitCode : 1);
 });

package/dist/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-gateway",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "private": false,
   "type": "module",
   "files": [
@@ -10,10 +10,11 @@
     "LICENSE"
   ],
   "bin": {
-    "x402-gateway": "./dist/cli.js"
+    "x402-gateway": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts"
   },