z-zero-mcp-server 1.0.7 → 1.1.0

package/dist/lib/extract-total-price.js

@@ -0,0 +1,127 @@
+"use strict";
+// extract-total-price.ts
+// Phase 2: Smart Routing - DOM Price Extractor
+// Scans a checkout page via Playwright and returns the cart total in USD.
+// Returns null if no price can be confidently found.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTotalPrice = extractTotalPrice;
+/**
+ * Multi-strategy total price extractor.
+ * Strategy order (most reliable → least reliable):
+ *   1. Known CSS selectors for major platforms (Shopify, Stripe, Woo)
+ *   2. Aria / data-testid patterns
+ *   3. Text heuristic: find largest $ amount near keywords "total", "amount due"
+ */
+async function extractTotalPrice(page) {
+    // ─── Strategy 1: Well-known selector list ────────────────────────────────
+    const knownSelectors = [
+        // Shopify
+        '[data-checkout-payment-amount]',
+        '.payment-due__price',
+        // Stripe Checkout
+        '[data-testid="total-amount"]',
+        '.OrderAmountRow--total .OrderAmountRow-amount',
+        // Woocommerce
+        '.order-total .amount',
+        '.woocommerce-Price-amount.amount',
+        // Generic
+        '[data-testid*="total" i]',
+        '[class*="order-total" i]',
+        '[class*="total-price" i]',
+        '[class*="grand-total" i]',
+        '[id*="order-total" i]',
+        '[id*="grand-total" i]',
+        'span[class*="total"]',
+        'td[class*="total"]',
+    ];
+    for (const selector of knownSelectors) {
+        try {
+            const el = await page.$(selector);
+            if (!el)
+                continue;
+            const text = await el.innerText();
+            const parsed = parseMoneyString(text);
+            if (parsed !== null && parsed > 0) {
+                console.error(`[PRICE] ✅ Strategy 1 found via selector "${selector}": $${parsed}`);
+                return parsed;
+            }
+        }
+        catch {
+            // element may have been removed from DOM — continue
+        }
+    }
+    // ─── Strategy 2: Scan all visible text near "total" keyword ──────────────
+    try {
+        const amount = await page.evaluate(() => {
+            const allText = Array.from(document.querySelectorAll('*'))
+                .filter((el) => {
+                if (!(el instanceof HTMLElement))
+                    return false;
+                const style = window.getComputedStyle(el);
+                return style.display !== 'none' && style.visibility !== 'hidden';
+            })
+                .filter(el => {
+                const text = el.innerText?.toLowerCase() ?? '';
+                return ((text.includes('total') || text.includes('amount due') || text.includes('you pay')) &&
+                    el.children.length < 5 // narrow to leaf-ish nodes
+                );
+            })
+                .map(el => el.innerText ?? '');
+            // Find first valid $ pattern in those elements
+            const priceRegex = /\$\s*([\d,]+(?:\.\d{1,2})?)/;
+            for (const text of allText) {
+                const match = text.match(priceRegex);
+                if (match) {
+                    const value = parseFloat(match[1].replace(/,/g, ''));
+                    if (value > 0 && value < 10000)
+                        return value; // sanity bound
+                }
+            }
+            return null;
+        });
+        if (amount !== null && amount > 0) {
+            console.error(`[PRICE] ✅ Strategy 2 (text heuristic) found: $${amount}`);
+            return amount;
+        }
+    }
+    catch (e) {
+        console.error(`[PRICE] Strategy 2 failed: ${e}`);
+    }
+    // ─── Strategy 3: Last resort — biggest dollar amount visible on page ─────
+    try {
+        const amount = await page.evaluate(() => {
+            const regex = /\$\s*([\d,]+(?:\.\d{1,2})?)/g;
+            const bodyText = document.body.innerText ?? '';
+            const values = [];
+            let m;
+            while ((m = regex.exec(bodyText)) !== null) {
+                const v = parseFloat(m[1].replace(/,/g, ''));
+                if (v >= 0.5 && v < 10000)
+                    values.push(v);
+            }
+            if (values.length === 0)
+                return null;
+            return Math.max(...values);
+        });
+        if (amount !== null && amount > 0) {
+            console.error(`[PRICE] ⚠️  Strategy 3 (largest $ on page): $${amount}. Low confidence.`);
+            return amount;
+        }
+    }
+    catch (e) {
+        console.error(`[PRICE] Strategy 3 failed: ${e}`);
+    }
+    console.error('[PRICE] ❌ Could not detect total price on this page.');
+    return null;
+}
+// ─── Utility ─────────────────────────────────────────────────────────────────
+function parseMoneyString(text) {
+    // Handles: "$49.99", "USD 49.99", "49,99 $", "49.99 USD"
+    const match = text.match(/[\d,]+(?:\.\d{1,2})?/);
+    if (!match)
+        return null;
+    const value = parseFloat(match[0].replace(/,/g, ''));
+    if (isNaN(value) || value <= 0)
+        return null;
+    return value;
+}

package/dist/lib/key-store.d.ts

@@ -0,0 +1,13 @@
+/** Read the current active Passport Key. */
+export declare function getPassportKey(): string;
+/**
+ * Replace the active Passport Key in memory (no restart needed).
+ * @param newKey - must start with "zk_live_" or "zk_test_"
+ * @returns true if the key looks valid, false if rejected
+ */
+export declare function setPassportKey(newKey: string): {
+    ok: boolean;
+    message: string;
+};
+/** Check if a key is currently configured. */
+export declare function hasPassportKey(): boolean;

package/dist/lib/key-store.js

@@ -0,0 +1,38 @@
+"use strict";
+// key-store.ts
+// Shared, mutable in-memory store for the Passport Key (Z_ZERO_API_KEY).
+// All API backends (custodial + WDK) import getPassportKey() from here
+// so a single set_api_key MCP tool updates the key for ALL backends at once.
+//
+// Thread-safety: Node.js is single-threaded. Module-level `let` is safe.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPassportKey = getPassportKey;
+exports.setPassportKey = setPassportKey;
+exports.hasPassportKey = hasPassportKey;
+let _passportKey = process.env.Z_ZERO_API_KEY || "";
+/** Read the current active Passport Key. */
+function getPassportKey() {
+    return _passportKey;
+}
+/**
+ * Replace the active Passport Key in memory (no restart needed).
+ * @param newKey - must start with "zk_live_" or "zk_test_"
+ * @returns true if the key looks valid, false if rejected
+ */
+function setPassportKey(newKey) {
+    const trimmed = newKey.trim();
+    if (!trimmed) {
+        return { ok: false, message: "Key cannot be empty." };
+    }
+    if (!trimmed.startsWith("zk_live_") && !trimmed.startsWith("zk_test_")) {
+        return { ok: false, message: `Invalid key format — must start with "zk_live_" or "zk_test_". Got: "${trimmed.slice(0, 12)}..."` };
+    }
+    const previous = _passportKey;
+    _passportKey = trimmed;
+    console.error(`[KEY-STORE] ✅ Passport Key updated: ${previous.slice(0, 10)}... → ${trimmed.slice(0, 10)}...`);
+    return { ok: true, message: `Passport Key updated successfully. Active key prefix: ${trimmed.slice(0, 10)}...` };
+}
+/** Check if a key is currently configured. */
+function hasPassportKey() {
+    return _passportKey.length > 0;
+}

package/dist/lib/web3-detector.d.ts

@@ -0,0 +1,20 @@
+export interface Web3TxParams {
+    to: string;
+    value?: string;
+    data?: string;
+    chainId?: number;
+    eip681_amount?: number;
+}
+export interface Web3DetectionResult {
+    detected: boolean;
+    method: "eth_sendTransaction" | "EIP-681" | null;
+    params: Web3TxParams | null;
+    message: string;
+}
+/**
+ * Opens the checkout URL in a headless browser.
+ * Injects a mock window.ethereum (MetaMask emulation).
+ * Scans for EIP-681 links.
+ * Returns the tx params if Web3 payment is detected, else null.
+ */
+export declare function detectWeb3Payment(checkoutUrl: string): Promise<Web3DetectionResult>;

package/dist/lib/web3-detector.js

@@ -0,0 +1,182 @@
+"use strict";
+// web3-detector.ts
+// Phase 2: Smart Routing — Web3 Payment Detector
+// Injects a mock window.ethereum into a checkout page, waits for Web3 tx request.
+// If the page calls eth_sendTransaction → capture params and return them.
+// If page is not Web3-aware → return null (caller falls back to Fiat JIT card).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectWeb3Payment = detectWeb3Payment;
+const playwright_1 = require("playwright");
+const WEB3_DETECT_TIMEOUT_MS = 12_000; // 12s max to detect Web3 button click
+/**
+ * Opens the checkout URL in a headless browser.
+ * Injects a mock window.ethereum (MetaMask emulation).
+ * Scans for EIP-681 links.
+ * Returns the tx params if Web3 payment is detected, else null.
+ */
+async function detectWeb3Payment(checkoutUrl) {
+    const browser = await playwright_1.chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    try {
+        // ─── Inject mock window.ethereum BEFORE page loads ───────────────────
+        // This ensures the page's `if (typeof window.ethereum !== 'undefined')` check passes.
+        await page.addInitScript(() => {
+            const mockEthereum = {
+                isMetaMask: true,
+                selectedAddress: "0x0000000000000000000000000000000000000001",
+                chainId: "0x89",
+                networkVersion: "137",
+                request: async ({ method, params }) => {
+                    if (method === "eth_requestAccounts" || method === "eth_accounts") {
+                        return ["0x0000000000000000000000000000000000000001"];
+                    }
+                    if (method === "eth_chainId")
+                        return "0x89";
+                    if (method === "net_version")
+                        return "137";
+                    if (method === "eth_sendTransaction") {
+                        const tx = params?.[0];
+                        window["__wdkCapturedTx"] = tx;
+                        return "0xdeadbeef00000000000000000000000000000000000000000000000000000001";
+                    }
+                    if (method === "wallet_switchEthereumChain")
+                        return null;
+                    if (method === "eth_getBalance")
+                        return "0x0";
+                    // C3 FIX: Log unrecognized methods for debugging DApp compatibility
+                    window["__wdkUnknownMethod_" + method] = true;
+                    return null;
+                },
+                on: (event, handler) => {
+                    if (event === "connect")
+                        setTimeout(() => handler({ chainId: "0x89" }), 100);
+                    if (event === "accountsChanged")
+                        setTimeout(() => handler(["0x0000000000000000000000000000000000000001"]), 200);
+                },
+                removeListener: () => { },
+                removeAllListeners: () => { },
+                isConnected: () => true,
+            };
+            Object.defineProperty(window, "ethereum", {
+                value: mockEthereum,
+                writable: false,
+                configurable: true,
+            });
+        });
+        // ─── Navigate to page ─────────────────────────────────────────────────
+        await page.goto(checkoutUrl, { waitUntil: "domcontentloaded", timeout: 20_000 });
+        // ─── Strategy A: Scan for EIP-681 links ──────────────────────────────
+        // Look for links like: ethereum:0xabc...@137/transfer?address=0xabc&uint256=10000000
+        const eip681Result = await page.evaluate(() => {
+            const links = Array.from(document.querySelectorAll("a[href]"))
+                .map(a => a.href)
+                .filter(href => href.startsWith("ethereum:"));
+            const texts = [document.body.innerText ?? ""];
+            const allText = texts.join(" ");
+            const inlineMatch = allText.match(/ethereum:0x[0-9a-fA-F]{40}[^\s]*/);
+            const href = links[0] ?? inlineMatch?.[0] ?? null;
+            if (!href)
+                return null;
+            // Parse: ethereum:0xCONTRACT@137/transfer?address=0xRECIPIENT&uint256=10000000
+            const contractMatch = href.match(/ethereum:(0x[0-9a-fA-F]{40})/);
+            const chainMatch = href.match(/@(\d+)/);
+            const uint256Match = href.match(/uint256=(\d+)/);
+            // ✅ BUG 6 FIX: Parse recipient from 'address=' query param (not the contract address)
+            const recipientMatch = href.match(/[?&]address=(0x[0-9a-fA-F]{40})/);
+            return {
+                // Prefer recipient address from query param; fall back to contract only as last resort
+                to: recipientMatch?.[1] ?? contractMatch?.[1] ?? null,
+                contract: contractMatch?.[1] ?? null, // USDT contract (kept for logging)
+                chainId: chainMatch ? parseInt(chainMatch[1]) : 137,
+                uint256: uint256Match?.[1] ?? null,
+                raw: href,
+            };
+        });
+        if (eip681Result?.to) {
+            const usdtAmount = eip681Result.uint256
+                ? parseInt(eip681Result.uint256) / 1_000_000 // USDT has 6 decimals
+                : null;
+            console.error(`[WEB3] ✅ EIP-681 detected: recipient=${eip681Result.to}, contract=${eip681Result.contract}, amount=${usdtAmount} USDT`);
+            return {
+                detected: true,
+                method: "EIP-681",
+                params: {
+                    to: eip681Result.to,
+                    chainId: eip681Result.chainId,
+                    eip681_amount: usdtAmount ?? undefined,
+                },
+                message: `EIP-681 payment link found. Merchant: ${eip681Result.to}, amount: ${usdtAmount} USDT.`,
+            };
+        }
+        // ─── Strategy B: Wait for eth_sendTransaction after clicking "Pay" ────
+        // ✅ BUG 5 FIX: Auto-click common Web3 pay buttons so DApp triggers eth_sendTransaction
+        const web3ButtonSelectors = [
+            'button:has-text("MetaMask")', 'button:has-text("Pay with Crypto")',
+            'button:has-text("Connect Wallet")', 'button:has-text("Pay with Web3")',
+            'button:has-text("Pay with Wallet")', '#pay-metamask-btn',
+            '[class*="web3"] button', '[class*="metamask"] button',
+        ];
+        for (const sel of web3ButtonSelectors) {
+            try {
+                const btn = await page.$(sel);
+                if (btn && await btn.isVisible()) {
+                    console.error(`[WEB3] Clicking Web3 pay button: ${sel}`);
+                    await btn.click();
+                    break;
+                }
+            }
+            catch { /* selector may not exist — continue */ }
+        }
+        // Poll for captured tx (window.ethereum.request intercepted by mock)
+        const capturedTx = await Promise.race([
+            // Poll for captured tx
+            (async () => {
+                const start = Date.now();
+                while (Date.now() - start < WEB3_DETECT_TIMEOUT_MS) {
+                    const tx = await page.evaluate(() => {
+                        return window["__wdkCapturedTx"] ?? null;
+                    });
+                    if (tx)
+                        return tx;
+                    await page.waitForTimeout(500);
+                }
+                return null;
+            })(),
+        ]);
+        if (capturedTx) {
+            console.error(`[WEB3] ✅ eth_sendTransaction captured: to=${capturedTx["to"]}`);
+            return {
+                detected: true,
+                method: "eth_sendTransaction",
+                params: {
+                    to: capturedTx["to"],
+                    value: capturedTx["value"],
+                    data: capturedTx["data"],
+                    chainId: 137,
+                },
+                message: `Web3 payment detected via eth_sendTransaction. Recipient: ${capturedTx["to"]}`,
+            };
+        }
+        console.error("[WEB3] ❌ No Web3 payment detected on this page. Fallback to Fiat.");
+        return {
+            detected: false,
+            method: null,
+            params: null,
+            message: "No Web3 payment gateway detected. Will proceed with JIT Visa Card (Fiat) route.",
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[WEB3] Error during detection: ${msg}`);
+        return {
+            detected: false,
+            method: null,
+            params: null,
+            message: `Detection failed: ${msg}. Defaulting to Fiat route.`,
+        };
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}

package/dist/lib/with-timeout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * lib/with-timeout.ts
+ * Generic async timeout wrapper for MCP operations.
+ *
+ * Extensible usage:
+ *   await withTimeout(fillCheckoutForm(url, card), 60_000, 'Checkout')
+ *   await withTimeout(burnTokenRemote(token), 10_000, 'Burn')
+ *   await withTimeout(resolveTokenRemote(token), 8_000, 'Resolve')
+ *   await withTimeout(anyAsyncFn(), 5_000, 'MyOperation')
+ */
+export declare class TimeoutError extends Error {
+    constructor(operationName: string, ms: number);
+}
+/**
+ * Race an async operation against a hard deadline.
+ * @param promise   The async operation to run
+ * @param ms        Timeout in milliseconds
+ * @param name      Human-readable name for error messages (default: 'Operation')
+ * @param onTimeout Optional cleanup callback called on timeout
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, name?: string, onTimeout?: () => void | Promise<void>): Promise<T>;

package/dist/lib/with-timeout.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * lib/with-timeout.ts
+ * Generic async timeout wrapper for MCP operations.
+ *
+ * Extensible usage:
+ *   await withTimeout(fillCheckoutForm(url, card), 60_000, 'Checkout')
+ *   await withTimeout(burnTokenRemote(token), 10_000, 'Burn')
+ *   await withTimeout(resolveTokenRemote(token), 8_000, 'Resolve')
+ *   await withTimeout(anyAsyncFn(), 5_000, 'MyOperation')
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = void 0;
+exports.withTimeout = withTimeout;
+class TimeoutError extends Error {
+    constructor(operationName, ms) {
+        super(`[TIMEOUT] ${operationName} exceeded ${ms}ms hard cap`);
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Race an async operation against a hard deadline.
+ * @param promise   The async operation to run
+ * @param ms        Timeout in milliseconds
+ * @param name      Human-readable name for error messages (default: 'Operation')
+ * @param onTimeout Optional cleanup callback called on timeout
+ */
+function withTimeout(promise, ms, name = 'Operation', onTimeout) {
+    const timeoutPromise = new Promise((_, reject) => {
+        const timer = setTimeout(async () => {
+            if (onTimeout) {
+                try {
+                    await onTimeout();
+                }
+                catch { /* ignore cleanup errors */ }
+            }
+            reject(new TimeoutError(name, ms));
+        }, ms);
+        // Allow Node.js to exit even if timer is pending
+        if (timer.unref)
+            timer.unref();
+    });
+    return Promise.race([promise, timeoutPromise]);
+}

package/dist/playwright_bridge.d.ts

@@ -2,5 +2,6 @@ import type { CardData, PaymentResult } from "./types.js";
 /**
  * Detects and fills credit card form fields on a checkout page.
  * Card data exists ONLY in RAM and is wiped after injection.
+ * Hard timeout of 60s prevents merchant page from hanging indefinitely.
  */
 export declare function fillCheckoutForm(checkoutUrl: string, cardData: CardData): Promise<PaymentResult>;

package/dist/playwright_bridge.js

@@ -4,16 +4,48 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fillCheckoutForm = fillCheckoutForm;
 const playwright_1 = require("playwright");
+const with_timeout_js_1 = require("./lib/with-timeout.js");
+const CHECKOUT_HARD_TIMEOUT_MS = 60_000; // 60s absolute cap — prevents slow-loris attacks
 /**
  * Detects and fills credit card form fields on a checkout page.
  * Card data exists ONLY in RAM and is wiped after injection.
+ * Hard timeout of 60s prevents merchant page from hanging indefinitely.
  */
 async function fillCheckoutForm(checkoutUrl, cardData) {
     const browser = await playwright_1.chromium.launch({ headless: true });
     const context = await browser.newContext();
     const page = await context.newPage();
+    // 🔒 Wrap entire checkout flow in 60s hard timeout
+    // onTimeout: force-close browser to free memory
     try {
-        await page.goto(checkoutUrl, { waitUntil: "domcontentloaded", timeout: 30000 });
+        return await (0, with_timeout_js_1.withTimeout)(_fillCheckoutFormInner(page, checkoutUrl, cardData), // ✅ BUG 8 FIX: pass URL
+        CHECKOUT_HARD_TIMEOUT_MS, 'fillCheckoutForm', async () => {
+            console.error('[PLAYWRIGHT] ⚠️ Hard timeout hit — force-closing browser');
+            await browser.close().catch(() => { });
+        });
+    }
+    catch (err) {
+        if (err instanceof with_timeout_js_1.TimeoutError) {
+            return {
+                success: false,
+                message: `Checkout timed out after ${CHECKOUT_HARD_TIMEOUT_MS / 1000}s. The merchant page may be too slow or blocking automation.`,
+            };
+        }
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return { success: false, message: `Payment failed: ${errMsg}` };
+    }
+    finally {
+        // RAM wipe happens inside _fillCheckoutFormInner's finally block
+        // Ensure browser is closed even if timeout cleanup failed
+        await browser.close().catch(() => { });
+    }
+}
+/** Internal implementation — called by fillCheckoutForm inside a timeout wrapper */
+async function _fillCheckoutFormInner(page, checkoutUrl, // ✅ BUG 8 FIX: need URL to navigate to
+cardData) {
+    try {
+        // ✅ BUG 8 FIX: Navigate to the checkout page (was missing — page was blank!)
+        await page.goto(checkoutUrl, { waitUntil: "domcontentloaded", timeout: 20_000 });
         // ============================================================
         // STRATEGY 1: Standard HTML form fields
         // ============================================================
@@ -199,6 +231,6 @@ async function fillCheckoutForm(checkoutUrl, cardData) {
         cardData.exp_month = "00";
         cardData.exp_year = "0000";
         cardData.name = "";
-        await browser.close();
+        // Note: browser.close() is handled by fillCheckoutForm's outer finally block
     }
 }

package/dist/types.d.ts

@@ -27,6 +27,7 @@ export interface CardData {
     exp_year: string;
     cvv: string;
     name: string;
+    authorized_amount?: number;
     error?: string;
     message?: string;
 }

package/dist/wdk_backend.d.ts

@@ -0,0 +1,9 @@
+import type { CardData } from "./types.js";
+export declare function listCardsRemote(): Promise<any>;
+export declare function getBalanceRemote(cardAlias: string): Promise<any>;
+export declare function getDepositAddressesRemote(): Promise<any>;
+export declare function issueTokenRemote(cardAlias: string, amount: number, merchant: string): Promise<any | null>;
+export declare function resolveTokenRemote(token: string): Promise<CardData | null>;
+export declare function burnTokenRemote(token: string, receipt_id?: string): Promise<boolean>;
+export declare function cancelTokenRemote(token: string): Promise<any>;
+export declare function refundUnderspendRemote(token: string, actualSpent: number): Promise<void>;