@lightninglabs/lightning-mcp-server 0.2.0

package/skills/lib/config-gen.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Shared config generation functions for litd and lnd containers.
+#
+# These functions take a config template and produce a runtime config
+# by substituting network, debug level, node alias, UI password, and
+# appending extra arguments as config-file lines.
+#
+# Usage:
+#   source skills/lib/config-gen.sh
+#   generate_litd_config <template> <output> [network] [debug] [alias] [uipass] [extra_args]
+#   generate_lnd_config  <template> <output> [network] [debug] [extra_args]
+
+# generate_litd_config produces a litd runtime config from a template.
+#
+# It replaces the network boolean flag, debug level, node alias, and
+# UI password in-place, then appends any extra arguments as config lines.
+# Extra arguments are converted from CLI format (--lnd.flag=value) to
+# config file format (lnd.flag=value). Boolean flags without a value
+# get =true appended.
+#
+# Arguments:
+#   $1 - template  Path to the .conf.template file.
+#   $2 - output    Path to write the generated config.
+#   $3 - network   Bitcoin network (default: testnet).
+#   $4 - debug     Debug level string (default: info).
+#   $5 - alias     Node alias (default: litd-agent).
+#   $6 - uipass    litd UI password (default: empty, keeps template value).
+#   $7 - extra     Space-separated extra CLI flags to append.
+generate_litd_config() {
+    local template="$1"
+    local output="$2"
+    local network="${3:-testnet}"
+    local debug_level="${4:-info}"
+    local alias="${5:-litd-agent}"
+    local ui_password="${6:-}"
+    local extra_args="${7:-}"
+
+    cp "$template" "$output"
+
+    # Replace the litd-level network flag: network=<old> -> network=<new>.
+    # litd's global network= flag handles setting the correct lnd.bitcoin.*
+    # flag internally, avoiding the lnd default config conflict.
+    sed -i.bak -E \
+        's/^network=(testnet|mainnet|signet|regtest)/network='"$network"'/' \
+        "$output"
+    rm -f "$output.bak"
+
+    # Replace the debug level.
+    sed -i.bak 's/^lnd\.debuglevel=.*/lnd.debuglevel='"$debug_level"'/' "$output"
+    rm -f "$output.bak"
+
+    # Replace the node alias.
+    sed -i.bak 's/^lnd\.alias=.*/lnd.alias='"$alias"'/' "$output"
+    rm -f "$output.bak"
+
+    # Set UI password if provided.
+    if [ -n "$ui_password" ]; then
+        if grep -q '^uipassword=' "$output"; then
+            sed -i.bak 's/^uipassword=.*/uipassword='"$ui_password"'/' "$output"
+            rm -f "$output.bak"
+        fi
+    fi
+
+    # Append extra args as config-file lines.
+    _append_extra_args "$output" "$extra_args"
+}
+
+# generate_lnd_config produces a standalone lnd runtime config from a
+# template. Same pattern as generate_litd_config but for lnd-style
+# configs that use unprefixed keys (bitcoin.active, debuglevel, etc.).
+#
+# Arguments:
+#   $1 - template  Path to the .conf.template file.
+#   $2 - output    Path to write the generated config.
+#   $3 - network   Bitcoin network (default: testnet).
+#   $4 - debug     Debug level string (default: info).
+#   $5 - extra     Space-separated extra CLI flags to append.
+generate_lnd_config() {
+    local template="$1"
+    local output="$2"
+    local network="${3:-testnet}"
+    local debug_level="${4:-info}"
+    local extra_args="${5:-}"
+
+    cp "$template" "$output"
+
+    # Replace the network boolean: bitcoin.<old>=true -> bitcoin.<new>=true.
+    # Use -E for extended regex (portable across macOS and Linux).
+    sed -i.bak -E \
+        's/^bitcoin\.(testnet|mainnet|signet|regtest)=true/bitcoin.'"$network"'=true/' \
+        "$output"
+    rm -f "$output.bak"
+
+    # Replace the debug level.
+    sed -i.bak 's/^debuglevel=.*/debuglevel='"$debug_level"'/' "$output"
+    rm -f "$output.bak"
+
+    # Append extra args as config-file lines.
+    _append_extra_args "$output" "$extra_args"
+}
+
+# _append_extra_args converts CLI-style flags to config-file lines and
+# appends them to the output file. Each --flag=value becomes flag=value;
+# bare --flag becomes flag=true.
+_append_extra_args() {
+    local output="$1"
+    local extra_args="$2"
+
+    if [ -z "$extra_args" ]; then
+        return
+    fi
+
+    echo "" >> "$output"
+    echo "# Profile/CLI extra arguments." >> "$output"
+    for arg in $extra_args; do
+        # Strip leading dashes.
+        local line="${arg#--}"
+        line="${line#-}"
+
+        # Boolean flags without =value get =true.
+        if [[ "$line" != *=* ]]; then
+            line="${line}=true"
+        fi
+
+        echo "$line" >> "$output"
+    done
+}

package/skills/lib/rest.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Shared REST call helpers for lnd/litd scripts.
+#
+# Provides rest_call() and wait_for_rest() functions that handle both
+# native and container modes. In container mode, the host-mapped port
+# is discovered via `docker port` since container images do not include
+# curl.
+#
+# Required variables (set before sourcing):
+#   REST_HOST       - REST API host (default: localhost).
+#   REST_PORT       - REST API port (default: 8080).
+#   CONTAINER       - Docker container name (empty for native mode).
+#   CONTAINER_PORT  - Internal container port to map (default: $REST_PORT).
+#
+# Usage:
+#   source skills/lib/rest.sh
+#   rest_call GET "/v1/state"
+#   rest_call POST "/v1/initwallet" '{"wallet_password":"..."}'
+#   wait_for_rest
+
+# rest_call issues a curl request against the lnd/litd REST API.
+# In container mode, it discovers the host-mapped port via docker port.
+rest_call() {
+    local method="$1"
+    local endpoint="$2"
+    local data="${3:-}"
+
+    local host="${REST_HOST:-localhost}"
+    local port="${REST_PORT:-8080}"
+    local internal_port="${CONTAINER_PORT:-$port}"
+
+    # Container mode: discover the host-mapped port for the container's
+    # internal REST port.
+    if [ -n "${CONTAINER:-}" ]; then
+        host="localhost"
+        local mapped
+        mapped=$(docker port "$CONTAINER" "$internal_port" 2>/dev/null \
+            | head -1 | sed 's/.*://')
+        if [ -n "$mapped" ]; then
+            port="$mapped"
+        fi
+    fi
+
+    if [ "$method" = "GET" ]; then
+        curl -sk -X GET \
+            "https://$host:$port$endpoint" 2>&1
+    else
+        curl -sk -X POST \
+            "https://$host:$port$endpoint" \
+            -H "Content-Type: application/json" \
+            -d "$data" 2>&1
+    fi
+}
+
+# wait_for_rest polls the REST API until it responds or times out.
+wait_for_rest() {
+    local label="${1:-REST API}"
+    echo "Waiting for $label..."
+    for i in {1..30}; do
+        if rest_call GET "/v1/state" &>/dev/null; then
+            echo "$label is ready."
+            return 0
+        fi
+        sleep 2
+        echo "  Waiting... ($i/30)"
+    done
+    echo "Error: $label did not become available." >&2
+    return 1
+}

package/skills/lightning-security-module/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: lightning-security-module
+description: Set up an lnd remote signer container that holds private keys separately from the agent. Exports a credentials bundle (accounts JSON, TLS cert, admin macaroon) for watch-only litd nodes. Container-first with Docker, native fallback. Use when firewalling private key material from AI agents.
+---
+
+# Lightning Security Module (Remote Signer)
+
+Set up an lnd remote signer container that holds private keys on a separate,
+secured machine. The signer never routes payments or opens channels — it only
+holds keys and signs when asked by a watch-only litd node.
+
+## Architecture
+
+```
+Agent Machine                     Signer Machine (secure)
+┌─────────────────┐              ┌─────────────────────┐
+│  litd (watch-only)│◄──gRPC───►│  lnd (signer)        │
+│  - neutrino      │             │  - holds seed         │
+│  - manages chans │             │  - signs commitments  │
+│  - routes pmts   │             │  - signs on-chain txs │
+│  - NO key material│            │  - no p2p networking   │
+└─────────────────┘              └─────────────────────┘
+```
+
+The watch-only node handles all networking and channel management. The signer
+node holds the seed and performs cryptographic signing. Even if the agent machine
+is fully compromised, the attacker cannot extract private keys.
+
+See [references/architecture.md](references/architecture.md) for the full
+architecture explainer.
+
+## Quick Start (Container — Recommended)
+
+### On the Signer Machine
+
+```bash
+# 1. Install lnd signer image
+skills/lightning-security-module/scripts/install.sh
+
+# 2. Start signer container
+skills/lightning-security-module/scripts/start-signer.sh
+
+# 3. Set up signer wallet and export credentials
+skills/lightning-security-module/scripts/setup-signer.sh
+
+# 4. Copy the credentials bundle to the agent machine
+#    The setup script prints the bundle path and base64 string.
+```
+
+### On the Agent Machine
+
+```bash
+# 5. Import credentials bundle
+skills/lnd/scripts/import-credentials.sh --bundle <credentials-bundle>
+
+# 6. Start litd in watch-only mode
+skills/lnd/scripts/start-lnd.sh --watchonly
+
+# 7. Create watch-only wallet
+skills/lnd/scripts/create-wallet.sh
+
+# 8. Check status
+skills/lnd/scripts/lncli.sh getinfo
+```
+
+### Two-Container Local Setup
+
+For testing both on the same machine:
+
+```bash
+# Start litd + signer together
+skills/lnd/scripts/start-lnd.sh --watchonly
+
+# Set up signer wallet
+skills/lightning-security-module/scripts/setup-signer.sh --container litd-signer
+
+# Import credentials and create watch-only wallet
+skills/lnd/scripts/import-credentials.sh --bundle ~/.lnget/signer/credentials-bundle
+skills/lnd/scripts/create-wallet.sh --container litd
+```
+
+## Installation
+
+Default: pulls the lnd Docker image for the signer.
+
+```bash
+skills/lightning-security-module/scripts/install.sh
+```
+
+This pulls `lightninglabs/lnd:v0.20.0-beta` from Docker Hub. The signer only
+needs plain lnd (not litd) since it only holds keys and signs.
+
+### Build from Source (Fallback)
+
+```bash
+skills/lightning-security-module/scripts/install.sh --source
+```
+
+## Native Mode
+
+For running the signer without Docker:
+
+```bash
+# Set up signer natively
+skills/lightning-security-module/scripts/setup-signer.sh --native
+
+# Start signer natively
+skills/lightning-security-module/scripts/start-signer.sh --native
+
+# Stop signer natively
+skills/lightning-security-module/scripts/stop-signer.sh --native
+```
+
+## Remote Nodes
+
+Export credentials from a remote signer:
+
+```bash
+skills/lightning-security-module/scripts/export-credentials.sh \
+    --rpcserver signer-host:10012 \
+    --tlscertpath ~/signer-tls.cert \
+    --macaroonpath ~/signer-admin.macaroon
+```
+
+## Credential Bundle Format
+
+The exported bundle (`~/.lnget/signer/credentials-bundle/`) contains:
+
+| File | Purpose |
+|------|---------|
+| `accounts.json` | Account xpubs for watch-only wallet import |
+| `tls.cert` | Signer's TLS certificate for authenticated gRPC |
+| `admin.macaroon` | Signer's admin macaroon for RPC authentication |
+
+The bundle is also available as a single base64-encoded tar.gz file
+(`credentials-bundle.tar.gz.b64`) for easy copy-paste transfer between machines.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `install.sh` | Pull lnd signer image (or build from source) |
+| `docker-start.sh` | Start signer container |
+| `docker-stop.sh` | Stop signer container |
+| `setup-signer.sh` | Create signer wallet and export credentials |
+| `start-signer.sh` | Start signer (delegates to Docker by default) |
+| `stop-signer.sh` | Stop signer (delegates to Docker by default) |
+| `export-credentials.sh` | Re-export credentials from running signer |
+
+## Managing the Signer
+
+### Start
+
+```bash
+# Docker (default)
+skills/lightning-security-module/scripts/start-signer.sh
+
+# With network override
+skills/lightning-security-module/scripts/start-signer.sh --network mainnet
+```
+
+### Stop
+
+```bash
+# Docker stop (preserve data)
+skills/lightning-security-module/scripts/stop-signer.sh
+
+# Docker stop + remove volumes
+skills/lightning-security-module/scripts/stop-signer.sh --clean
+```
+
+### Re-export Credentials
+
+If TLS certificates or macaroons have been regenerated:
+
+```bash
+skills/lightning-security-module/scripts/export-credentials.sh
+```
+
+## Configuration
+
+### Container Config
+
+The signer compose template is at
+`skills/lightning-security-module/templates/docker-compose-signer.yml`. Config
+is passed via command-line arguments.
+
+### Native Config
+
+The native signer config template is at
+`skills/lightning-security-module/templates/signer-lnd.conf.template`. Key
+differences from a standard lnd node:
+
+- **No P2P listening** (`--listen=`) — signer doesn't route
+- **RPC on 0.0.0.0:10012** — accepts connections from watch-only node
+- **REST on localhost:10013** — local only, for wallet creation
+- **TLS extra IP 0.0.0.0** — watch-only on a different machine can connect
+- **No autopilot, no routing fees** — signer is signing-only
+
+## Security Model
+
+**What stays on the signer:**
+- 24-word seed mnemonic
+- All private keys (funding, revocation, HTLC)
+- Wallet database with key material
+
+**What gets exported:**
+- Account xpubs (public keys only — cannot spend)
+- TLS certificate (for authenticated connection)
+- Admin macaroon (for RPC auth — scope down for production)
+
+**Threat model:**
+- Compromised agent machine cannot sign transactions or extract keys
+- Attacker with agent access can see balances and channel state but not spend
+- Signer machine should have minimal attack surface
+
+**Production hardening:**
+- Replace admin macaroon with a signer-only macaroon (see `macaroon-bakery`)
+- Restrict signer RPC to specific IP addresses via firewall
+- Run signer on dedicated hardware or a hardened VM
+- Use Lightning Node Connect (LNC) via `mcp-lnc` for read-only agent access
+
+## Macaroon Bakery for Signer
+
+For production, bake a signing-only macaroon:
+
+```bash
+skills/macaroon-bakery/scripts/bake.sh --role signer-only \
+    --container litd-signer --rpc-port 10012
+```
+
+Then re-export the credentials bundle with the scoped macaroon.
+
+## Container & Ports
+
+| Container | Purpose | Ports |
+|-----------|---------|-------|
+| `litd-signer` | Remote signer (lnd) | 10012, 10013 |
+
+| Port  | Service | Interface | Description |
+|-------|---------|-----------|-------------|
+| 10012 | gRPC | 0.0.0.0 | Signer RPC (watch-only connects here) |
+| 10013 | REST | 0.0.0.0 | REST for wallet creation |
+
+## File Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.lnget/signer/wallet-password.txt` | Signer wallet passphrase (0600) |
+| `~/.lnget/signer/seed.txt` | Signer seed mnemonic (0600) |
+| `~/.lnget/signer/credentials-bundle/` | Exported credentials |
+| `~/.lnget/signer/signer-lnd.conf` | Signer config (native mode) |
+| `versions.env` | Pinned container image versions |

package/skills/lightning-security-module/references/architecture.md

@@ -0,0 +1,133 @@
+# Remote Signer Architecture
+
+## Overview
+
+The remote signer architecture splits an lnd Lightning node into two separate
+processes running on different machines:
+
+1. **Signer node** — holds all private key material, performs signing
+2. **Watch-only node** — handles networking, channels, routing, payments
+
+This separation ensures that even if the machine running the watch-only node
+(the "agent machine") is fully compromised, the attacker cannot extract private
+keys or sign arbitrary transactions.
+
+## Two-Node Architecture
+
+```
+┌─────────────────────────────┐     ┌─────────────────────────────┐
+│      Agent Machine          │     │      Signer Machine         │
+│                             │     │                             │
+│  ┌───────────────────────┐  │     │  ┌───────────────────────┐  │
+│  │  lnd (watch-only)     │  │     │  │  lnd (signer)         │  │
+│  │                       │  │     │  │                       │  │
+│  │  - Neutrino backend   │◄─┼─gRPC┼─►│  - Holds seed          │  │
+│  │  - Channel state      │  │     │  │  - Signs commitments   │  │
+│  │  - Routes payments    │  │     │  │  - Signs on-chain txs  │  │
+│  │  - Manages peers      │  │     │  │  - No p2p networking   │  │
+│  │  - NO private keys    │  │     │  │  - Minimal surface     │  │
+│  └───────────────────────┘  │     │  └───────────────────────┘  │
+│                             │     │                             │
+│  Imported from signer:      │     │  Never exported:            │
+│  - accounts.json (xpubs)   │     │  - Seed mnemonic            │
+│  - tls.cert                │     │  - Private keys             │
+│  - admin.macaroon          │     │  - Wallet DB key material   │
+└─────────────────────────────┘     └─────────────────────────────┘
+```
+
+## What Gets Exported
+
+The credential bundle contains three files:
+
+### accounts.json
+
+Output of `lncli wallet accounts list`. Contains extended public keys (xpubs)
+for all lnd accounts. These allow the watch-only node to:
+
+- Derive public keys and addresses
+- Track on-chain balances
+- Construct unsigned transactions
+
+They do **not** allow signing or spending.
+
+### tls.cert
+
+The signer's TLS certificate. The watch-only node uses this to establish an
+authenticated, encrypted gRPC connection to the signer. This prevents
+man-in-the-middle attacks on the signing channel.
+
+### admin.macaroon
+
+The signer's admin macaroon for RPC authentication. The watch-only node presents
+this when requesting signatures. For production, replace with a scoped macaroon
+that only allows signing operations.
+
+## What Never Leaves the Signer
+
+- **Seed mnemonic** — the 24-word BIP39 phrase from which all keys derive
+- **Private keys** — funding keys, revocation keys, HTLC keys
+- **Wallet database key material** — encrypted private key data in the wallet DB
+
+## Signing Flow
+
+When the watch-only node needs a signature (e.g., committing a channel state
+update or broadcasting an on-chain transaction):
+
+1. Watch-only node constructs the unsigned transaction
+2. Watch-only node sends a signing request to the signer via gRPC
+3. Signer validates the request and produces the signature
+4. Signer returns the signature to the watch-only node
+5. Watch-only node assembles the signed transaction and broadcasts it
+
+## Threat Model
+
+### Compromised agent machine
+
+**Impact:** Attacker can see channel states, balances, and payment history.
+Attacker can attempt to route payments through existing channels.
+
+**Cannot:** Extract private keys, sign arbitrary transactions, sweep funds to
+attacker-controlled addresses, forge channel close transactions.
+
+### Compromised signer machine
+
+**Impact:** Full compromise — attacker has seed and all keys. Can sign arbitrary
+transactions and sweep all funds.
+
+**Mitigation:** The signer should have minimal attack surface. No unnecessary
+services, no web browser, no agent software. Ideally dedicated hardware.
+
+### Network interception (gRPC channel)
+
+**Impact:** Without TLS cert validation, attacker could intercept signing
+requests.
+
+**Mitigation:** TLS with certificate pinning (the watch-only node has a copy of
+the signer's TLS cert and validates against it).
+
+## Macaroon Scoping
+
+For production deployments, the admin macaroon should be replaced with a
+custom macaroon that only grants the minimum permissions needed:
+
+```bash
+# On the signer, bake a signing-only macaroon
+lncli --rpcserver=localhost:10012 --lnddir=~/.lnd-signer \
+    bakemacaroon uri:/signrpc.Signer/SignOutputRaw \
+    uri:/signrpc.Signer/ComputeInputScript \
+    uri:/signrpc.Signer/MuSig2Sign \
+    uri:/walletrpc.WalletKit/DeriveKey \
+    uri:/walletrpc.WalletKit/DeriveNextKey \
+    --save_to=~/.lnd-signer/data/chain/bitcoin/mainnet/signer-only.macaroon
+```
+
+## Future Enhancements
+
+- **litd accounts:** Use Lightning Terminal's account system for even finer
+  access control and spending limits
+- **Hardware signing devices:** Replace the signer lnd with a hardware security
+  module (HSM) or hardware wallet for tamper-resistant key storage
+- **Multi-party signing:** Require multiple signers to approve high-value
+  transactions (threshold signatures)
+- **Macaroon rotation:** Automatically rotate macaroons on a schedule to limit
+  the window of compromise

package/skills/lightning-security-module/scripts/docker-start.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Start the remote signer container.
+#
+# Usage:
+#   docker-start.sh                          # Default (testnet, background)
+#   docker-start.sh --network mainnet        # Mainnet (real coins)
+#   docker-start.sh --foreground             # Run in foreground (show logs)
+#   docker-start.sh --build                  # Rebuild before starting
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE_DIR="$SCRIPT_DIR/../templates"
+VERSIONS_FILE="$SCRIPT_DIR/../../../versions.env"
+LIB_DIR="$SCRIPT_DIR/../../lib"
+
+DETACH=true
+BUILD=false
+CUSTOM_NETWORK=""
+
+# Source pinned versions so compose files pick them up as env vars.
+if [ -f "$VERSIONS_FILE" ]; then
+    source "$VERSIONS_FILE"
+    export LND_VERSION LND_IMAGE
+fi
+
+# Source config generation functions.
+source "$LIB_DIR/config-gen.sh"
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --network)
+            CUSTOM_NETWORK="$2"
+            shift 2
+            ;;
+        --build)
+            BUILD=true
+            shift
+            ;;
+        --foreground|-f)
+            DETACH=false
+            shift
+            ;;
+        -h|--help)
+            echo "Usage: docker-start.sh [options]"
+            echo ""
+            echo "Start the remote signer container."
+            echo ""
+            echo "Options:"
+            echo "  --network NET     Override network (testnet, mainnet, signet)"
+            echo "  --build           Rebuild images before starting"
+            echo "  --foreground, -f  Run in foreground (show logs)"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Override network if specified on command line.
+if [ -n "$CUSTOM_NETWORK" ]; then
+    NETWORK="$CUSTOM_NETWORK"
+fi
+
+# --- Generate runtime config from template ---
+
+LNGET_LND_DIR="${LNGET_LND_DIR:-$HOME/.lnget/lnd}"
+mkdir -p "$LNGET_LND_DIR"
+
+generate_lnd_config \
+    "$TEMPLATE_DIR/signer-lnd.conf.template" \
+    "$LNGET_LND_DIR/signer-lnd.conf" \
+    "${NETWORK:-testnet}" \
+    "${LND_DEBUG:-info}" \
+    ""
+
+export SIGNER_CONF_PATH="$LNGET_LND_DIR/signer-lnd.conf"
+
+# --- Start container ---
+
+cd "$TEMPLATE_DIR"
+
+echo "=== Starting signer container ==="
+echo "  Config:   $SIGNER_CONF_PATH"
+echo "  Network:  ${NETWORK:-testnet}"
+echo "  Image:    ${LND_IMAGE:-lightninglabs/lnd}:${LND_VERSION:-v0.20.0-beta}"
+echo ""
+
+# Build the docker-compose command.
+CMD="docker compose -f docker-compose-signer.yml"
+
+if [ "$BUILD" = true ]; then
+    CMD="$CMD up --build"
+else
+    CMD="$CMD up"
+fi
+
+if [ "$DETACH" = true ]; then
+    CMD="$CMD -d"
+fi
+
+echo "Running: $CMD"
+eval "$CMD"
+
+if [ "$DETACH" = true ]; then
+    echo ""
+    echo "Signer started in background."
+    echo ""
+    echo "Check logs:"
+    echo "  docker logs -f litd-signer"
+    echo ""
+    echo "Next: set up the signer wallet (if first run):"
+    echo "  skills/lightning-security-module/scripts/setup-signer.sh --container litd-signer"
+fi