@x402sentinel/test 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# sentinel-test
+
+Test any x402 payment endpoint from your terminal. Like Postman for x402.
+
+## Quick Start
+
+```bash
+npx sentinel-test https://api.example.com/endpoint
+```
+
+## What It Tests
+
+1. **Reachability** — endpoint responds with HTTP 402
+2. **Payment Schema** — valid amount, currency, network, receiver address
+3. **Facilitator** — facilitator URL is reachable (if provided)
+4. **Response Quality** — response time, CORS headers, HTTPS
+5. **Sentinel Integration** — checks for Sentinel audit trail headers
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--network <name>` | Expected network (base, solana, etc) |
+| `--verbose` | Show full response details |
+| `--json` | Output results as JSON |
+| `--timeout <ms>` | Request timeout (default: 10000) |
+
+## Score
+
+Each endpoint gets a score from 0-10:
+- Failed critical checks: -3 each
+- Failed warning checks: -1 each
+- Exit code 0 if score >= 5, exit code 1 otherwise
+
+## Links
+
+- [Sentinel Dashboard](https://sentinel.valeocash.com)
+- [Sentinel CLI](https://npmjs.com/package/create-sentinel)
+- [x402 SDK](https://npmjs.com/package/@x402sentinel/x402)

package/dist/display.d.ts

@@ -0,0 +1,5 @@
+import type { TestResult } from "./tester.js";
+export interface DisplayOptions {
+    verbose?: boolean;
+}
+export declare function displayResults(result: TestResult, options?: DisplayOptions): void;

package/dist/display.js

@@ -0,0 +1,73 @@
+import chalk from "chalk";
+export function displayResults(result, options = {}) {
+    console.log();
+    // Score header
+    const scoreColor = result.score >= 8 ? chalk.green : result.score >= 5 ? chalk.yellow : chalk.red;
+    console.log(chalk.bold("  URL:   ") + chalk.cyan(result.url));
+    console.log(chalk.bold("  Score: ") + scoreColor.bold(`${result.score}/10`) +
+        chalk.dim(`  (${result.totalTime}ms)`));
+    console.log();
+    // Checks
+    const passed = result.checks.filter((c) => c.passed);
+    const failed = result.checks.filter((c) => !c.passed);
+    if (failed.length > 0) {
+        console.log(chalk.bold.red("  ISSUES"));
+        console.log();
+        for (const check of failed) {
+            printCheck(check);
+        }
+        console.log();
+    }
+    if (passed.length > 0) {
+        console.log(chalk.bold.green("  PASSED"));
+        console.log();
+        for (const check of passed) {
+            printCheck(check);
+        }
+        console.log();
+    }
+    // Payment details
+    if (result.paymentDetails) {
+        const pd = result.paymentDetails;
+        console.log(chalk.bold("  PAYMENT DETAILS"));
+        console.log();
+        console.log(`    Amount:       ${chalk.white.bold(pd.amount)} ${chalk.dim(pd.currency)}`);
+        console.log(`    Network:      ${chalk.white(pd.network)}`);
+        console.log(`    Receiver:     ${chalk.dim(pd.receiver)}`);
+        if (pd.facilitator) {
+            console.log(`    Facilitator:  ${chalk.dim(pd.facilitator)}`);
+        }
+        console.log();
+    }
+    // Summary line
+    const critFail = result.checks.filter((c) => !c.passed && c.severity === "critical").length;
+    const warnFail = result.checks.filter((c) => !c.passed && c.severity === "warning").length;
+    const parts = [
+        chalk.green(`${passed.length} passed`),
+    ];
+    if (critFail > 0)
+        parts.push(chalk.red(`${critFail} critical`));
+    if (warnFail > 0)
+        parts.push(chalk.yellow(`${warnFail} warnings`));
+    console.log(`  ${parts.join(chalk.dim("  ·  "))}`);
+    console.log();
+}
+function printCheck(check) {
+    const icon = check.passed ? chalk.green("✓") : check.severity === "critical" ? chalk.red("✗") : chalk.yellow("!");
+    const label = check.passed ? chalk.white(check.name) : severityColor(check)(check.name);
+    let line = `    ${icon}  ${label}`;
+    if (check.value) {
+        line += chalk.dim(`  →  ${check.value}`);
+    }
+    if (!check.passed && check.expected) {
+        line += chalk.dim(`  (expected: ${check.expected})`);
+    }
+    console.log(line);
+}
+function severityColor(check) {
+    if (check.severity === "critical")
+        return chalk.red;
+    if (check.severity === "warning")
+        return chalk.yellow;
+    return chalk.dim;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import { testEndpoint } from "./tester.js";
+import { displayResults } from "./display.js";
+const banner = `
+${chalk.bold.cyan("  🛡  Sentinel x402 Endpoint Tester")}
+${chalk.dim("  Test any x402 payment endpoint")}
+`;
+const program = new Command();
+program
+    .name("sentinel-test")
+    .description("Test any x402 payment endpoint")
+    .version("0.1.0")
+    .argument("<url>", "URL of the x402 endpoint to test")
+    .option("--network <network>", "Expected network (base, solana, etc)")
+    .option("--verbose", "Show full response details")
+    .option("--json", "Output results as JSON")
+    .option("--timeout <ms>", "Request timeout in ms", "10000")
+    .action(async (url, opts) => {
+    if (!opts.json) {
+        console.log(banner);
+    }
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+        url = `https://${url}`;
+    }
+    const result = await testEndpoint(url, {
+        network: opts.network,
+        verbose: !!opts.verbose,
+        timeout: Number(opts.timeout) || 10000,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        displayResults(result, { verbose: !!opts.verbose });
+    }
+    process.exit(result.score >= 5 ? 0 : 1);
+});
+program.parse();

package/dist/tester.d.ts

@@ -0,0 +1,27 @@
+export interface TestCheck {
+    name: string;
+    passed: boolean;
+    value?: string;
+    expected?: string;
+    severity: "critical" | "warning" | "info";
+}
+export interface PaymentDetails {
+    amount: string;
+    currency: string;
+    network: string;
+    receiver: string;
+    facilitator?: string;
+}
+export interface TestResult {
+    url: string;
+    checks: TestCheck[];
+    score: number;
+    totalTime: number;
+    paymentDetails?: PaymentDetails;
+}
+export interface TestOptions {
+    network?: string;
+    verbose?: boolean;
+    timeout?: number;
+}
+export declare function testEndpoint(url: string, options?: TestOptions): Promise<TestResult>;

package/dist/tester.js

@@ -0,0 +1,329 @@
+const RECOGNIZED_CURRENCIES = ["USDC", "USDT", "DAI", "WETH", "ETH", "SOL"];
+const RECOGNIZED_NETWORKS = [
+    "base", "base-sepolia",
+    "ethereum", "sepolia",
+    "polygon", "arbitrum", "optimism",
+    "solana", "solana-devnet",
+];
+function isEvmAddress(s) {
+    return /^0x[a-fA-F0-9]{40}$/.test(s);
+}
+function isSolanaAddress(s) {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(s);
+}
+export async function testEndpoint(url, options = {}) {
+    const checks = [];
+    let paymentDetails;
+    const timeout = options.timeout ?? 10000;
+    const start = Date.now();
+    let response = null;
+    let body = null;
+    // --- Step 1: Reachability ---
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        response = await fetch(url, {
+            method: "GET",
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        clearTimeout(timer);
+        body = await response.text();
+        checks.push({
+            name: "Endpoint reachable",
+            passed: true,
+            value: `HTTP ${response.status}`,
+            severity: "critical",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isTimeout = message.includes("abort");
+        checks.push({
+            name: "Endpoint reachable",
+            passed: false,
+            value: isTimeout ? `Timed out after ${timeout}ms` : message,
+            severity: "critical",
+        });
+        const totalTime = Date.now() - start;
+        return { url, checks, score: calcScore(checks), totalTime };
+    }
+    const totalTime = Date.now() - start;
+    // Check for 402
+    if (response.status === 402) {
+        checks.push({
+            name: "Returns HTTP 402",
+            passed: true,
+            value: "Payment Required",
+            severity: "critical",
+        });
+    }
+    else if (response.status === 200) {
+        checks.push({
+            name: "Returns HTTP 402",
+            passed: false,
+            value: "Endpoint doesn't require payment (returned 200)",
+            expected: "402",
+            severity: "critical",
+        });
+        return { url, checks, score: calcScore(checks), totalTime };
+    }
+    else {
+        checks.push({
+            name: "Returns HTTP 402",
+            passed: false,
+            value: `Endpoint returned ${response.status}`,
+            expected: "402",
+            severity: "critical",
+        });
+        return { url, checks, score: calcScore(checks), totalTime };
+    }
+    // --- Step 2: Parse 402 body ---
+    let parsed = null;
+    try {
+        parsed = JSON.parse(body);
+        checks.push({
+            name: "Response body is valid JSON",
+            passed: true,
+            severity: "critical",
+        });
+    }
+    catch {
+        checks.push({
+            name: "Response body is valid JSON",
+            passed: false,
+            value: "Body is not valid JSON",
+            severity: "critical",
+        });
+        return { url, checks, score: calcScore(checks), totalTime };
+    }
+    const payReq = extractPaymentRequirements(parsed);
+    // Amount
+    const amount = payReq.amount;
+    if (amount && !isNaN(Number(amount)) && Number(amount) > 0) {
+        checks.push({
+            name: "Valid payment amount",
+            passed: true,
+            value: amount,
+            severity: "critical",
+        });
+    }
+    else {
+        checks.push({
+            name: "Valid payment amount",
+            passed: false,
+            value: amount ?? "missing",
+            expected: "Number > 0",
+            severity: "critical",
+        });
+    }
+    // Currency
+    const currency = payReq.currency?.toUpperCase();
+    if (currency && RECOGNIZED_CURRENCIES.includes(currency)) {
+        checks.push({
+            name: "Recognized currency",
+            passed: true,
+            value: currency,
+            severity: "warning",
+        });
+    }
+    else {
+        checks.push({
+            name: "Recognized currency",
+            passed: !currency,
+            value: currency ?? "not specified",
+            expected: RECOGNIZED_CURRENCIES.join(", "),
+            severity: "warning",
+        });
+    }
+    // Network
+    const network = payReq.network?.toLowerCase();
+    if (network && RECOGNIZED_NETWORKS.includes(network)) {
+        checks.push({
+            name: "Recognized network",
+            passed: true,
+            value: network,
+            severity: "warning",
+        });
+    }
+    else {
+        checks.push({
+            name: "Recognized network",
+            passed: false,
+            value: network ?? "not specified",
+            expected: "base, ethereum, solana, ...",
+            severity: "warning",
+        });
+    }
+    if (options.network && network && network !== options.network.toLowerCase()) {
+        checks.push({
+            name: "Network matches expected",
+            passed: false,
+            value: network,
+            expected: options.network,
+            severity: "warning",
+        });
+    }
+    // Receiver address
+    const receiver = payReq.receiver;
+    if (receiver) {
+        const isSolana = network?.startsWith("solana");
+        const valid = isSolana ? isSolanaAddress(receiver) : isEvmAddress(receiver);
+        checks.push({
+            name: "Valid receiver address",
+            passed: valid,
+            value: receiver.length > 20 ? `${receiver.slice(0, 10)}...${receiver.slice(-6)}` : receiver,
+            expected: isSolana ? "Base58 (32-44 chars)" : "0x... (42 chars)",
+            severity: "critical",
+        });
+    }
+    else {
+        checks.push({
+            name: "Valid receiver address",
+            passed: false,
+            value: "missing",
+            severity: "critical",
+        });
+    }
+    // Facilitator
+    const facilitator = payReq.facilitator;
+    paymentDetails = {
+        amount: amount ?? "unknown",
+        currency: currency ?? "unknown",
+        network: network ?? "unknown",
+        receiver: receiver ?? "unknown",
+        facilitator: facilitator ?? undefined,
+    };
+    // --- Step 3: Schema & facilitator ---
+    checks.push({
+        name: "Payment schema present",
+        passed: !!(amount && receiver),
+        value: amount && receiver ? "amount + receiver found" : "incomplete schema",
+        severity: "critical",
+    });
+    if (facilitator) {
+        try {
+            const fc = new AbortController();
+            const ft = setTimeout(() => fc.abort(), 5000);
+            const fRes = await fetch(facilitator, { method: "HEAD", signal: fc.signal });
+            clearTimeout(ft);
+            checks.push({
+                name: "Facilitator reachable",
+                passed: fRes.ok || fRes.status === 405,
+                value: `HTTP ${fRes.status}`,
+                severity: "warning",
+            });
+        }
+        catch {
+            checks.push({
+                name: "Facilitator reachable",
+                passed: false,
+                value: "Connection failed",
+                severity: "warning",
+            });
+        }
+    }
+    // --- Step 4: Response quality ---
+    if (totalTime < 500) {
+        checks.push({
+            name: "Response time",
+            passed: true,
+            value: `${totalTime}ms (fast)`,
+            severity: "info",
+        });
+    }
+    else if (totalTime < 2000) {
+        checks.push({
+            name: "Response time",
+            passed: true,
+            value: `${totalTime}ms`,
+            severity: "info",
+        });
+    }
+    else {
+        checks.push({
+            name: "Response time",
+            passed: false,
+            value: `${totalTime}ms (slow)`,
+            expected: "< 2000ms",
+            severity: "warning",
+        });
+    }
+    const corsHeader = response.headers.get("access-control-allow-origin");
+    checks.push({
+        name: "CORS headers present",
+        passed: !!corsHeader,
+        value: corsHeader ?? "missing",
+        severity: "warning",
+    });
+    const isHttps = url.startsWith("https://");
+    checks.push({
+        name: "Uses HTTPS",
+        passed: isHttps,
+        value: isHttps ? "yes" : "no — insecure",
+        severity: "critical",
+    });
+    // --- Step 5: Sentinel integration ---
+    const sentinelHeader = response.headers.get("x-sentinel-receipt") ||
+        response.headers.get("x-sentinel-agent");
+    checks.push({
+        name: "Sentinel integration",
+        passed: !!sentinelHeader,
+        value: sentinelHeader
+            ? "This endpoint uses Sentinel for audit tracking"
+            : "Tip: Add Sentinel for payment audit trails → npmjs.com/package/@x402sentinel/x402",
+        severity: "info",
+    });
+    return {
+        url,
+        checks,
+        score: calcScore(checks),
+        totalTime,
+        paymentDetails,
+    };
+}
+function calcScore(checks) {
+    let score = 10;
+    for (const c of checks) {
+        if (c.passed)
+            continue;
+        if (c.severity === "critical")
+            score -= 3;
+        if (c.severity === "warning")
+            score -= 1;
+    }
+    return Math.max(0, score);
+}
+function extractPaymentRequirements(body) {
+    // x402 can nest payment info at top level or under "payment" / "paymentRequirements"
+    const sources = [
+        body,
+        body.payment,
+        body.paymentRequirements,
+        // Handle array format: paymentRequirements: [{ ... }]
+        ...(Array.isArray(body.paymentRequirements) ? body.paymentRequirements : []),
+    ].filter(Boolean);
+    let amount;
+    let currency;
+    let network;
+    let receiver;
+    let facilitator;
+    for (const src of sources) {
+        if (!amount)
+            amount = str(src.amount ?? src.maxAmountRequired);
+        if (!currency)
+            currency = str(src.currency ?? src.asset ?? src.token);
+        if (!network)
+            network = str(src.network ?? src.chain ?? src.chainId);
+        if (!receiver)
+            receiver = str(src.receiver ?? src.payTo ?? src.address ?? src.recipient);
+        if (!facilitator)
+            facilitator = str(src.facilitator ?? src.facilitatorUrl ?? src.facilitatorAddress);
+    }
+    return { amount, currency, network, receiver, facilitator };
+}
+function str(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    return String(v);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@x402sentinel/test",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Test any x402 payment endpoint",
+  "bin": {
+    "sentinel-test": "dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": ["x402", "sentinel", "test", "payments", "402"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valeo-cash/Sentinel.git"
+  },
+  "homepage": "https://sentinel.valeocash.com"
+}