Lightning Security Module

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.

Security Scan

The skill's purpose (a remote lnd signer) is plausible and the scripts largely match that goal, but there are mismatches and risky defaults (undeclared binary/environment requirements, sourcing missing shared libs, and exporting an admin macaroon in the bundle) that merit caution before installing.

Purpose & Capability

The name/description (remote lnd signer) match the provided scripts and templates. However the registry metadata declares no required binaries or env vars while the scripts clearly require Docker/docker-compose, lnd/lncli, jq, openssl, curl, tar/base64, and (for --source) git and Go. That discrepancy (metadata says 'none' but scripts need many tools) is an incoherence the user should be aware of.

Instruction Scope

The runtime instructions and scripts create and store sensitive material on the signer host (seed mnemonic, wallet passphrase, TLS cert, admin macaroon), copy files into containers, and produce a base64-encoded credentials bundle intended for transfer to the agent. Exporting the admin macaroon by default (admin.macaroon) grants full RPC privileges and is a risky default. Scripts also source helper scripts from ../lib (e.g., lib/rest.sh, lib/config-gen.sh) that are not included in the manifest — sourcing external shell code is a notable point of trust and potential supply-chain concern.

Install Mechanism

There is no formal install spec (instruction-only), which is lower-risk in the sense nothing is automatically downloaded by the platform. The scripts do pull the public Docker image lightninglabs/lnd:v0.20.0-beta (a known public repo) and optionally clone/build from GitHub — these are expected for this purpose. No arbitrary/personal download URLs or obfuscated fetches were found.

Credentials

The skill declares no required env vars or credentials, yet the scripts read and respect several environment variables (LNGET_SIGNER_DIR, LND_SIGNER_DIR, LND_IMAGE, LND_VERSION, etc.) and require access to Docker/socket and filesystem paths in the user's home. The skill will create and store secret material (seed, wallet-password.txt) under ~/.lnget/signer. It also exports an admin macaroon into the bundle; asking for or producing an admin macaroon without declaring/justifying privileged access is disproportionate.

Persistence & Privilege

always:false (good), and there is no installation step that permanently modifies other skills. However the scripts will write secrets and configs to disk (~/.lnget/signer, ~/.lnd-signer), create Docker containers/volumes, and copy sensitive files into containers. Combined with autonomous invocation being allowed by default, the skill could be used to create/export credentials bundles programmatically — a capability with high blast radius if invoked on an untrusted agent or if output is exfiltrated.

What to consider before installing

This skill appears to implement the claimed remote-signer architecture, but several things to check before installing: - Required tools: the manifest lists no required binaries, but the scripts need Docker/docker-compose, lnd/lncli, jq, curl, openssl, tar/base64 (and git/Go if building from source). Make sure those are installed and that you trust them. - Sensitive outputs: the setup and export scripts write the seed mnemonic and wallet passphrase to disk (~/.lnget/signer) and export an admin macaroon in the credentials bundle by default. An admin macaroon grants full RPC rights — for production you should bake a signing-only macaroon as recommended in the docs instead of exporting admin.macaroon. - Missing sourced libs: several scripts source ../lib/*.sh (rest.sh, config-gen.sh). Those files are not in the manifest you provided; verify they exist in the environment and review them before running. Sourcing external shell code can execute arbitrary commands. - Image provenance: the script pulls lightninglabs/lnd from Docker Hub. If you proceed, prefer pinned versions, verify image digests/signatures, or build from source in a controlled environment. - Transfer risk: the credentials bundle is intentionally packaged as a base64 tarball for easy copy-paste — that convenience makes accidental or malicious exfiltration easier. Transfer bundles only over trusted channels and consider encrypting them in transit. - Operational advice: run the signer on a dedicated, well-hardened machine (air-gapped or firewall-restricted), use a scoped/signing-only macaroon in production, rotate macaroons, protect filesystem permissions, and audit any helper scripts that are sourced. Given the above mismatches and risky defaults, treat this skill as suspicious until you verify the missing helper scripts, confirm runtime dependencies, and change the default export to a least-privilege macaroon and an operationally secure transfer method.

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 for the full architecture explainer.

Quick Start (Container — Recommended)

On the Signer Machine

# 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

# 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:

# 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.

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)

skills/lightning-security-module/scripts/install.sh --source

Native Mode

For running the signer without Docker:

# 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:

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

# Docker (default)
skills/lightning-security-module/scripts/start-signer.sh

# With network override
skills/lightning-security-module/scripts/start-signer.sh --network mainnet

Stop

# 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:

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 lightning-mcp-server for read-only agent access

Macaroon Bakery for Signer

For production, bake a signing-only macaroon:

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