lightning-wallet-mcp 1.4.1 → 1.5.0

package/README.md

@@ -505,6 +505,74 @@ def verify_webhook(payload, signature, secret):
 
 Check the `X-Webhook-Signature` header against the payload.
 
+## Pre-Payment Policy Hook
+
+An optional, vendor-neutral hook lets an external policy endpoint **allow or deny a payment before it executes**. It is off by default — when `PRE_PAYMENT_HOOK_URL` is unset, behaviour is exactly as before. When set, every outgoing payment (`pay_l402_api`, `pay_invoice`, `keysend`, `pay_lightning_address`) is checked against your endpoint first; a denial aborts the payment before any funds move.
+
+This is useful for spending policies, approval workflows, compliance checks, or any external authorization layer. The hook protocol is generic, so any service implementing the request/response contract below can be wired in by configuration alone.
+
+### Configuration
+
+| Env var | Default | Description |
+|---|---|---|
+| `PRE_PAYMENT_HOOK_URL` | _(unset)_ | Policy endpoint to POST each payment proposal to. Unset disables the hook entirely. |
+| `PRE_PAYMENT_HOOK_TIMEOUT_MS` | `3000` | Per-request timeout in milliseconds. |
+| `PRE_PAYMENT_HOOK_FAIL_MODE` | `closed` | `closed` denies a payment if the hook errors or times out; `open` lets it proceed. Default is fail-closed. |
+
+```jsonc
+{
+  "mcpServers": {
+    "lightning-wallet": {
+      "command": "npx",
+      "args": ["lightning-wallet-mcp"],
+      "env": {
+        "LIGHTNING_WALLET_API_KEY": "your-api-key",
+        "PRE_PAYMENT_HOOK_URL": "https://your-policy-endpoint.example/hook"
+      }
+    }
+  }
+}
+```
+
+### Hook request (POST from the client)
+
+The proposal describes only the proposed payment — **it never includes your wallet API key**.
+
+```json
+{
+  "proposal_id": "f7e1…",
+  "agent_id": 42,
+  "protocol": "l402",
+  "destination_or_url": "https://api.example/paid-endpoint",
+  "amount_sats": null,
+  "max_payment_sats": 1000,
+  "method": "GET",
+  "ts": "2026-06-06T18:00:00.000Z"
+}
+```
+
+`protocol` is one of `l402`, `x402`, `bolt11`, `keysend`, `lnaddress`. `amount_sats` is the exact amount when it is known at hook time: for `keysend` and `lnaddress` it is the requested amount, and for `bolt11` it is decoded locally from the invoice (no extra API call). For `l402`/`x402` it is `null` because the amount is set by the payment challenge at execution time — there the hook enforces `max_payment_sats` (the agent-authorised ceiling) up front, and the exact settled amount is available afterward via [webhooks](#webhooks). `max_payment_sats` is the agent-authorised ceiling when applicable.
+
+**Exactly what leaves the wallet.** Only the eight fields above are sent to your hook endpoint: `proposal_id`, `agent_id`, `protocol`, `destination_or_url`, `amount_sats`, `max_payment_sats`, `method`, `ts`. The wallet API key and any other credentials are **never** included.
+
+**Coverage.** The hook gates every agent-initiated spend: `pay_l402_api`, `pay_invoice`, `keysend`, `pay_lightning_address`, and Nostr zaps. Operator-scoped fund management (withdrawals, agent funding, agent-to-agent transfers) is intentionally **not** gated — those are operator actions, not agent spends.
+
+### Hook response (your endpoint returns)
+
+```json
+{ "decision": "allow" }
+```
+
+```json
+{ "decision": "deny", "reason": { "code": "over_limit", "message": "Exceeds per-transaction limit" } }
+```
+
+- `allow` → the payment proceeds.
+- `deny` → the payment is aborted and the tool returns a `PolicyDenied` error surfacing `reason.message`.
+- An optional `attestation` field (any JSON) is treated as opaque by the client — it is logged to stderr and otherwise ignored, so a policy service can return a signed decision for downstream auditing.
+
+On a hook error, timeout, or unrecognized response, the `PRE_PAYMENT_HOOK_FAIL_MODE` applies (deny by default).
+
 ## Pricing
 
 Lightning Faucet charges a 2% platform fee (min 1 sat) on outgoing payments:

package/dist/bolt11.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal, dependency-free BOLT11 amount decoder.
+ *
+ * Reads only the amount from the invoice's human-readable prefix (HRP). It does
+ * NOT bech32-decode the data part and makes no network call. Returns the amount
+ * in sats, or null when the invoice is amountless or cannot be confidently
+ * parsed — callers treat null as "amount unknown" and degrade gracefully.
+ */
+export declare function bolt11AmountSats(invoice: string): number | null;

package/dist/bolt11.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Minimal, dependency-free BOLT11 amount decoder.
+ *
+ * Reads only the amount from the invoice's human-readable prefix (HRP). It does
+ * NOT bech32-decode the data part and makes no network call. Returns the amount
+ * in sats, or null when the invoice is amountless or cannot be confidently
+ * parsed — callers treat null as "amount unknown" and degrade gracefully.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bolt11AmountSats = bolt11AmountSats;
+// msats per 1 unit of each multiplier (1 BTC = 1e11 msat).
+const MSAT_PER_UNIT = {
+    m: 1e8, // milli  (1e-3 BTC)
+    u: 1e5, // micro  (1e-6 BTC)
+    n: 1e2, // nano   (1e-9 BTC)
+    p: 1e-1, // pico  (1e-12 BTC)
+};
+function bolt11AmountSats(invoice) {
+    try {
+        const lower = invoice.trim().toLowerCase();
+        if (!lower.startsWith('ln'))
+            return null;
+        // The bech32 data part never contains '1', so the LAST '1' is the separator
+        // between the human-readable prefix and the data.
+        const sep = lower.lastIndexOf('1');
+        if (sep < 1)
+            return null;
+        const hrp = lower.slice(0, sep);
+        // hrp = 'ln' + currency-prefix + <digits><multiplier?>. Amountless invoices
+        // (no digits) and unknown currency prefixes do not match → null.
+        const match = hrp.match(/^ln(?:bcrt|bc|tb|sb)(\d+)([munp])?$/);
+        if (!match)
+            return null;
+        const digits = match[1];
+        const multiplier = match[2];
+        let msat;
+        if (multiplier) {
+            const factor = MSAT_PER_UNIT[multiplier];
+            if (factor === undefined)
+                return null;
+            msat = Number(digits) * factor;
+        }
+        else {
+            msat = Number(digits) * 1e11; // whole BTC
+        }
+        if (!Number.isFinite(msat) || msat < 0)
+            return null;
+        return Math.round(msat / 1000);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lightning-faucet.d.ts

@@ -118,7 +118,24 @@ interface WhoamiResponse extends ApiResponse {
 }
 export declare class LightningFaucetClient {
     private apiKey;
+    private agentIdCache;
     constructor(apiKey: string);
+    /**
+     * Resolve the current agent id for hook proposals (best-effort, cached).
+     * Returns null if it cannot be determined; a payment is never blocked solely
+     * because identity resolution failed — that decision is left to the policy hook.
+     */
+    private resolveAgentId;
+    /**
+     * Run the optional pre-payment policy hook before executing a payment.
+     *
+     * No-op when `PRE_PAYMENT_HOOK_URL` is unset (behaviour is unchanged). When a
+     * hook is configured this POSTs a vendor-neutral proposal and throws
+     * `PolicyDenied` if the hook — or fail-closed handling of a hook error —
+     * denies the payment. Only the four explicit payment methods call this; it is
+     * invoked before any funds-moving request is sent.
+     */
+    private enforcePrePaymentPolicy;
     /**
      * Make an API request to Lightning Faucet
      */

package/dist/lightning-faucet.js

@@ -8,15 +8,75 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LightningFaucetClient = void 0;
 exports.registerOperator = registerOperator;
 exports.getPublicInfo = getPublicInfo;
+const pre_payment_hook_js_1 = require("./pre-payment-hook.js");
+const bolt11_js_1 = require("./bolt11.js");
 const API_BASE_URL = process.env.LIGHTNING_WALLET_API_URL || 'https://lightningfaucet.com/ai-agents/api';
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
 class LightningFaucetClient {
     apiKey;
+    agentIdCache;
     constructor(apiKey) {
         if (!apiKey) {
             throw new Error('API key is required');
         }
         this.apiKey = apiKey;
     }
+    /**
+     * Resolve the current agent id for hook proposals (best-effort, cached).
+     * Returns null if it cannot be determined; a payment is never blocked solely
+     * because identity resolution failed — that decision is left to the policy hook.
+     */
+    async resolveAgentId() {
+        if (this.agentIdCache !== undefined) {
+            return this.agentIdCache;
+        }
+        try {
+            const who = await this.whoami();
+            this.agentIdCache = who.id || null;
+        }
+        catch {
+            this.agentIdCache = null;
+        }
+        return this.agentIdCache;
+    }
+    /**
+     * Run the optional pre-payment policy hook before executing a payment.
+     *
+     * No-op when `PRE_PAYMENT_HOOK_URL` is unset (behaviour is unchanged). When a
+     * hook is configured this POSTs a vendor-neutral proposal and throws
+     * `PolicyDenied` if the hook — or fail-closed handling of a hook error —
+     * denies the payment. Only the four explicit payment methods call this; it is
+     * invoked before any funds-moving request is sent.
+     */
+    async enforcePrePaymentPolicy(params) {
+        const config = (0, pre_payment_hook_js_1.getPrePaymentHookConfig)();
+        if (!config) {
+            return;
+        }
+        const agentId = await this.resolveAgentId();
+        const proposal = {
+            proposal_id: globalThis.crypto.randomUUID(),
+            agent_id: agentId,
+            protocol: params.protocol,
+            destination_or_url: params.destinationOrUrl,
+            amount_sats: params.amountSats,
+            max_payment_sats: params.maxPaymentSats,
+            method: params.method ?? null,
+            ts: new Date().toISOString(),
+        };
+        const { attestation } = await (0, pre_payment_hook_js_1.runPrePaymentHook)(proposal, config);
+        if (attestation !== undefined) {
+            // Opaque to this client — logged on stderr to avoid corrupting MCP stdio.
+            console.error(`[pre-payment-hook] payment allowed with attestation: ${safeStringify(attestation)}`);
+        }
+    }
     /**
      * Make an API request to Lightning Faucet
      */
@@ -57,6 +117,15 @@ class LightningFaucetClient {
      * Pay an L402-protected API endpoint
      */
     async l402Pay(url, method = 'GET', body, maxPaymentSats = 1000) {
+        // L402 vs X402 is auto-detected server-side; the actual amount is set by the
+        // challenge, so only the agent-authorised ceiling is known at hook time.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'l402',
+            destinationOrUrl: url,
+            amountSats: null,
+            maxPaymentSats,
+            method: method.toUpperCase(),
+        });
         const requestData = {
             url,
             method: method.toUpperCase(),
@@ -93,6 +162,15 @@ class LightningFaucetClient {
      * Pay a BOLT11 Lightning invoice
      */
     async payInvoice(bolt11, maxFeeSats) {
+        // Decode the amount from the invoice locally (no extra API call) so the hook
+        // receives the exact amount; null only if the invoice is amountless/unparseable.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'bolt11',
+            destinationOrUrl: bolt11,
+            amountSats: (0, bolt11_js_1.bolt11AmountSats)(bolt11),
+            maxPaymentSats: null,
+            method: null,
+        });
         const data = {
             invoice: bolt11,
         };
@@ -573,6 +651,13 @@ class LightningFaucetClient {
      * Pay to a Lightning address
      */
     async payLightningAddress(address, amountSats, comment) {
+        await this.enforcePrePaymentPolicy({
+            protocol: 'lnaddress',
+            destinationOrUrl: address,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             address,
             amount_sats: amountSats,
@@ -663,6 +748,13 @@ class LightningFaucetClient {
      * Send keysend payment
      */
     async keysend(destination, amountSats, message) {
+        await this.enforcePrePaymentPolicy({
+            protocol: 'keysend',
+            destinationOrUrl: destination,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             destination,
             amount_sats: amountSats,
@@ -714,6 +806,15 @@ class LightningFaucetClient {
      * Falls back to regular Lightning address payment if recipient doesn't support NIP-57
      */
     async nostrZap(address, amountSats, recipientPubkey, content, eventId, relays) {
+        // A Nostr zap settles as a Lightning-address payment, so it is an agent spend
+        // and must pass the policy hook like any other.
+        await this.enforcePrePaymentPolicy({
+            protocol: 'lnaddress',
+            destinationOrUrl: address,
+            amountSats,
+            maxPaymentSats: amountSats,
+            method: null,
+        });
         const data = {
             address,
             amount_sats: amountSats,

package/dist/pre-payment-hook.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pre-Payment Policy Hook
+ *
+ * An optional, vendor-neutral hook that lets an external policy endpoint allow
+ * or deny a payment *before* it executes. When `PRE_PAYMENT_HOOK_URL` is unset
+ * the hook is inert and payment behaviour is identical to having no hook at all.
+ *
+ * This module contains no vendor-specific logic. It POSTs a generic payment
+ * proposal and interprets a generic decision, so any policy service that speaks
+ * the documented request/response contract can be wired in by configuration
+ * alone. The proposal deliberately carries NO wallet credentials.
+ */
+export type PaymentProtocol = 'l402' | 'x402' | 'bolt11' | 'keysend' | 'lnaddress';
+export type HookFailMode = 'closed' | 'open';
+export interface PrePaymentProposal {
+    /** Unique id for this proposal (one per payment attempt). */
+    proposal_id: string;
+    /** The paying agent's id, when resolvable; null otherwise. */
+    agent_id: number | null;
+    /** Payment protocol being attempted. */
+    protocol: PaymentProtocol;
+    /** Destination address, node pubkey, lightning address, invoice, or target URL. */
+    destination_or_url: string;
+    /** Exact amount when known at hook time; null when the protocol determines it later. */
+    amount_sats: number | null;
+    /** Upper bound the agent authorised, when applicable; null otherwise. */
+    max_payment_sats: number | null;
+    /** HTTP method for L402/X402 URL payments; null for direct Lightning payments. */
+    method: string | null;
+    /** ISO-8601 timestamp of the proposal. */
+    ts: string;
+}
+export interface HookDecisionReason {
+    code?: string;
+    message?: string;
+}
+export interface HookDecision {
+    decision: 'allow' | 'deny';
+    reason?: HookDecisionReason;
+    /** Opaque to this client; forwarded/logged only. */
+    attestation?: unknown;
+}
+export interface PrePaymentHookConfig {
+    url: string;
+    timeoutMs: number;
+    failMode: HookFailMode;
+}
+/**
+ * Read hook configuration from the environment. Returns null when no hook URL is
+ * configured, in which case callers MUST behave exactly as before.
+ *
+ * - `PRE_PAYMENT_HOOK_URL` — when set, enables the hook.
+ * - `PRE_PAYMENT_HOOK_TIMEOUT_MS` — request timeout; defaults to 3000.
+ * - `PRE_PAYMENT_HOOK_FAIL_MODE` — `closed` (default) denies on hook error/timeout;
+ *   `open` proceeds on hook error/timeout.
+ */
+export declare function getPrePaymentHookConfig(env?: Record<string, string | undefined>): PrePaymentHookConfig | null;
+/**
+ * Error thrown when a payment is denied — either explicitly by the hook
+ * (`decision: "deny"`) or implicitly by a hook error under fail-closed mode.
+ */
+export declare class PolicyDenied extends Error {
+    readonly code: string;
+    readonly reason?: HookDecisionReason;
+    constructor(message: string, code?: string, reason?: HookDecisionReason);
+}
+export interface RunHookDeps {
+    /** Injectable fetch, primarily for tests. Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Run the pre-payment hook for a proposal.
+ *
+ * - decision `allow`: resolves with the (opaque) attestation, if any.
+ * - decision `deny`: throws {@link PolicyDenied} carrying the structured reason.
+ * - transport error / timeout / non-2xx / malformed response: applies failMode —
+ *   `closed` throws {@link PolicyDenied}; `open` resolves (payment proceeds) after
+ *   logging the failure to stderr.
+ */
+export declare function runPrePaymentHook(proposal: PrePaymentProposal, config: PrePaymentHookConfig, deps?: RunHookDeps): Promise<{
+    attestation?: unknown;
+}>;

package/dist/pre-payment-hook.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Pre-Payment Policy Hook
+ *
+ * An optional, vendor-neutral hook that lets an external policy endpoint allow
+ * or deny a payment *before* it executes. When `PRE_PAYMENT_HOOK_URL` is unset
+ * the hook is inert and payment behaviour is identical to having no hook at all.
+ *
+ * This module contains no vendor-specific logic. It POSTs a generic payment
+ * proposal and interprets a generic decision, so any policy service that speaks
+ * the documented request/response contract can be wired in by configuration
+ * alone. The proposal deliberately carries NO wallet credentials.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyDenied = void 0;
+exports.getPrePaymentHookConfig = getPrePaymentHookConfig;
+exports.runPrePaymentHook = runPrePaymentHook;
+const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * Read hook configuration from the environment. Returns null when no hook URL is
+ * configured, in which case callers MUST behave exactly as before.
+ *
+ * - `PRE_PAYMENT_HOOK_URL` — when set, enables the hook.
+ * - `PRE_PAYMENT_HOOK_TIMEOUT_MS` — request timeout; defaults to 3000.
+ * - `PRE_PAYMENT_HOOK_FAIL_MODE` — `closed` (default) denies on hook error/timeout;
+ *   `open` proceeds on hook error/timeout.
+ */
+function getPrePaymentHookConfig(env = process.env) {
+    const url = env.PRE_PAYMENT_HOOK_URL?.trim();
+    if (!url) {
+        return null;
+    }
+    const timeoutRaw = env.PRE_PAYMENT_HOOK_TIMEOUT_MS?.trim();
+    const parsedTimeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : NaN;
+    const timeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : DEFAULT_TIMEOUT_MS;
+    // Default fail-closed: when a hook is configured, a hook error denies the payment.
+    const failMode = env.PRE_PAYMENT_HOOK_FAIL_MODE?.trim().toLowerCase() === 'open' ? 'open' : 'closed';
+    return { url, timeoutMs, failMode };
+}
+/**
+ * Error thrown when a payment is denied — either explicitly by the hook
+ * (`decision: "deny"`) or implicitly by a hook error under fail-closed mode.
+ */
+class PolicyDenied extends Error {
+    code;
+    reason;
+    constructor(message, code = 'policy_denied', reason) {
+        super(message);
+        this.name = 'PolicyDenied';
+        this.code = code;
+        this.reason = reason;
+    }
+}
+exports.PolicyDenied = PolicyDenied;
+/**
+ * Run the pre-payment hook for a proposal.
+ *
+ * - decision `allow`: resolves with the (opaque) attestation, if any.
+ * - decision `deny`: throws {@link PolicyDenied} carrying the structured reason.
+ * - transport error / timeout / non-2xx / malformed response: applies failMode —
+ *   `closed` throws {@link PolicyDenied}; `open` resolves (payment proceeds) after
+ *   logging the failure to stderr.
+ */
+async function runPrePaymentHook(proposal, config, deps = {}) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    // The timer lives in a try/finally with NO catch: a fail-closed PolicyDenied
+    // (from applyFailMode or the deny branch) propagates straight out, clearing
+    // the timer, and is never caught and re-wrapped. Only the fetch and the body
+    // read are wrapped in their own try/catch, so their failures map to fail-mode
+    // exactly once with the right detail.
+    try {
+        let response;
+        try {
+            response = await doFetch(config.url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(proposal),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            return applyFailMode(config, transportDetail(err, config));
+        }
+        // Non-2xx is handled OUTSIDE the fetch try/catch so the status detail is
+        // preserved and fail-mode runs once.
+        if (!response.ok) {
+            return applyFailMode(config, `policy hook returned HTTP ${response.status}`);
+        }
+        let decision;
+        try {
+            decision = (await response.json());
+        }
+        catch (err) {
+            return applyFailMode(config, transportDetail(err, config, 'policy hook returned an unparseable body'));
+        }
+        if (decision?.decision === 'allow') {
+            return { attestation: decision.attestation };
+        }
+        if (decision?.decision === 'deny') {
+            const reason = decision.reason;
+            const detail = reason?.message || 'payment denied by policy';
+            throw new PolicyDenied(`Payment blocked by pre-payment policy hook: ${detail}`, reason?.code || 'policy_denied', reason);
+        }
+        // Malformed/unknown decision — treat as a hook error and apply the fail mode.
+        return applyFailMode(config, 'policy hook returned an unrecognized decision');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function transportDetail(err, config, fallback = 'policy hook request failed') {
+    return err instanceof Error && err.name === 'AbortError'
+        ? `policy hook timed out after ${config.timeoutMs}ms`
+        : fallback;
+}
+function applyFailMode(config, detail) {
+    if (config.failMode === 'open') {
+        // Fail-open: allow the payment, but record the hook failure on stderr.
+        console.error(`[pre-payment-hook] fail-open: proceeding despite ${detail}`);
+        return {};
+    }
+    throw new PolicyDenied(`Payment blocked by pre-payment policy hook (fail-closed): ${detail}`, 'policy_hook_unavailable');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-wallet-mcp",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "mcpName": "io.github.lightningfaucet/lightning-wallet-mcp",
   "description": "Lightning wallet for AI agents. MCP server + CLI. Works with Claude Code, OpenClaw, Cursor, and any agent framework.",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "start": "node dist/index.js",
+    "test": "npm run build && node --test test/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [