Zappit

Zappit includes both the Chrome dashboard and an early keyboard-first terminal liquidity cockpit. See packages/tui/README.md for TUI setup, controls, and the optional rebalance and cln-history plugins required for the full feature set.

Zappit is a Chromium-first browser extension for controlling multiple Core Lightning nodes over Commando through Zaptunnel. Node profiles, stable browser peer keys, and runes are encrypted locally behind one passphrase. Zaptunnel forwards an end-to-end encrypted BOLT-8 connection and does not receive the runes or RPC plaintext.

The project is an early security-focused scaffold. Use regtest or testnet credentials until payment flows and the Commando connection have been exercised against your environment.

Development

All project commands run inside the Nix development shell:

nix develop
pnpm install
pnpm check
pnpm test
pnpm build

For the browser-preview development server:

nix develop -c pnpm dev

To load the extension in Chromium:

1. Run nix develop -c pnpm build.
2. Open chrome://extensions.
3. Enable Developer mode.
4. Choose Load unpacked and select the generated dist directory.

Creating a new vault opens the Core Lightning node setup immediately; no mock account is installed by default. Zappit verifies the node with getinfo before saving it and uses the returned alias as its account name. Choose Use dev mode from that setup screen only when you want a simulated regtest dashboard without a Zaptunnel connection or real payment capability.

Rebuild before reloading the extension. No secrets should be added to source files, environment files, fixtures, or test commands.

Current architecture

• Svelte 5 and TypeScript UI
• Chromium Manifest V3 service worker
• Argon2id (64 MiB, three iterations) passphrase derivation
• AES-256-GCM authenticated vault encryption
• Multiple encrypted node profiles
• End-to-end encrypted Lightning Noise and Commando transport through @zaptunnel/sdk 0.4
• Local observer zappit-mcp stdio server with a separate restricted rune, BOLT-8 identity, liquidity reporting, and node-enforced dry-run-only splice planning
• One least-privilege rune per new node, built from explicit overview, receive, sign, spend, channel-management, and splice capability selections
• Opt-in WebLN and Zappit website providers for node-identity login and origin-bound BOLT11 payment approval
• Runtime-granted, origin-specific HTTPS access plus a relay-pinned WebSocket CSP
• Mock regtest node for UI development

The extension holds decrypted runes only while its dashboard or a user-approved signing window is unlocked. Locking removes active vault sessions and closes approval requests. Zappit never needs hsm_secret or an unrestricted rune.

See docs/node-setup.md for node preparation.

The MCP server is an optional workspace package and does not read the extension vault. See packages/mcp/README.md for its current tool surface, dedicated credential setup, and Codex configuration.

It is also exposed as a Nix app. Run it directly with nix run .#zappit-mcp -- help, or install the command persistently with nix profile install .#zappit-mcp.

CLN compatibility

The initial target is Core Lightning v26.06.6. Payments use xpay; the deprecated pay method is intentionally absent from the allowlist. Zappit accepts fixed and amountless BOLT11 invoices, BOLT12 invoices, reusable and recurring BOLT12 offers, BIP 353 addresses, conventional LNURL Lightning Addresses, Cash App $cashtag shorthand, and LNURL-auth requests. LNURL-auth uses CLN signmessage following LUD-13 to derive a private, stable identity for each service domain; it never shares the node public key. A cashtag is normalized to cashtag@cash.app and enters the LNURL flow directly because its syntax explicitly selects Cash App; Chromium still prompts for host permission and Zappit still verifies the returned invoice. BIP 353 is attempted first for ambiguous user@domain inputs; LNURL-pay requires an explicit HTTPS fallback. Every resulting invoice is reviewed before it is passed to xpay.

Status

Implemented:

• Nix development environment and reproducible dependency lock
• encrypted vault creation and unlocking
• five-minute inactivity lock
• account switching and encrypted account import
• live Lightning channel and on-chain balances from bookkeeper, with listfunds as a compatibility fallback during transient refreshes
• setup-time least-privilege rune command builder
• in-place per-node rune replacement in Settings with identity, network, and read-access verification
• bookkeeper-backed 30-day money-movement chart, channel routing chord, routing and lease revenue, channel APY, and current ledger balances
• optional cln-history v2 detection, bounded pagination, per-node/range caching, collector health, time-weighted channel balances and uptime, interval utilization, liquidity return, HTLC pressure, PPM-filtered forwarding paths, and history-aware rebalance budgets
• BOLT12 offer inventory with per-offer settled payment counts and total receipts
• native fixed or amountless BOLT11 invoice creation and fixed, amountless, single-use, or recurring BOLT12 offer creation
• budgeted NWC wallet creation, inventory, receive-only conversion, renewal editing, and revocation through cln-nip47
• encrypted recurring BOLT12 subscription tracking with pay-window status, explicit per-period review, and restart-safe generic browser reminders
• issued-offer enable and disable controls
• current channel status, local/receivable balances, and guarded routing-policy editing
• passphrase-guarded peer connection, channel funding, cooperative close requests, and liquidity-ad policy management
• cross-channel liquidity composer backed by one dev-splice script, mandatory node dry run, preview invalidation, and passphrase re-authentication before execution
• guarded BOLT11/BOLT12 payment review with explicit fee, per-payment, and rolling daily limits
• verified CLN payment preimages retained as outgoing proofs of payment
• payer-entered amounts for amountless BOLT11 invoices
• safe BOLT12 offer resolution for fixed, payer-specified, quantity, and recurring payments
• DNSSEC-verified BIP 353 address resolution through CLN
• LUD-06/LUD-12/LUD-16 Lightning Address payments with bounded HTTPS responses and invoice metadata binding
• Cash App $cashtag normalization to cashtag@cash.app
• encrypted per-node received-payment history with offline catch-up and live invoice tracking
• encrypted per-node outgoing attempt history for native and WebLN payments, including resolution failures, cancellations, pending, complete, and unknown outcomes
• 100-event Activity window with bounded, incremental CLN invoice and payment pagination
• per-node Activity reload for rebuilding cached history and re-parsing NIP-57 zap metadata
• unified, filterable Activity for payments, rebalances, archived forwarding buckets, and channel lifecycle events
• pending and confirmed on-chain operations reconciled from listtransactions and bookkeeper, with direct transaction links
• live pending-HTLC monitoring by channel, including value, direction, expiry proximity, and slot pressure
• verified NIP-57 zap cards with signed messages and Primal profile/post links
• opt-in Chromium notifications for newly received payments
• per-site WebLN activation with explicit approval for every identity, signing, or payment request
• window.webln.sendPayment() backed by guarded one-shot CLN xpay, including verified payment preimages
• window.webln.signMessage() and window.zappit.signMessage() backed by CLN signmessage
• passphrase-confirmed dashboard message signing with portable and raw signature output
• passphrase re-authentication for payments above a configurable threshold
• duplicate-payment checks and conservative no-retry handling for uncertain results
• Commando connection adapter
• typed RPC capability boundary
• responsive dashboard and extension popup
• unit tests for vault encryption and RPC denial

Next:

• exercise Zaptunnel admission and the BOLT-8 handshake against a real CLN v26.06 node
• deploy cln-history on a real node and validate its forward-only collection and Commando rune flow
• expand channel lifecycle views and validate history analytics against a long-running node archive
• dashboard message-signature verification
• persistent subscription reminders and fiat-denominated BOLT12 offers
• richer closed-channel and pending on-chain operation timelines

See docs/web-signing.md for the website API, security boundary, and local test flow.