Files
giza-kmp/docs/lightning/node-seed-in-flight-exposure.md
T
Kgothatso Ngako 1f9c9ef131 docs: the group Lightning wallet's review findings, as seven phased plans
The review asked whether the wallet's operator can spend lightning funds
without t-1 other share holders. The core claim holds; the seven exceptions
each get a phased plan under docs/lightning/, with an index giving the
severity table and the build order.
2026-10-27 09:21:36 +02:00

23 KiB

The node seed's real worth: in-flight incoming HTLCs

The design doc says the statement's in-flight cap "is the most the node seed can ever be worth" (docs/group-lightning-wallet.md:333-337). That is wrong by the whole incoming side of the channel: HTLCs the counterparty offers the group are claimable from the counterparty's commitment by anyone holding the node seed, to an address of the claimant's choosing, and no policy caps them. This plan corrects the claim, makes the exposure visible, bounds it, and sets up the decision on eliminating it. Phases 1 and 2 are the work; Phase 3 is a spike with an explicit go/no-go, because the honest answer may be that elimination costs more than the exposure does.

The finding

In a force close that publishes the counterparty's commitment, two transaction types spend its HTLC outputs, and both sign with commitKeys.ourHtlcKey — a per-commitment tweak of the HTLC basepoint, which withGroupBasepoints leaves derived from the node seed (KeyManager.kt:227-228,241,264; only the payment and delayed-payment basepoints are group keys, KeyManager.kt:207,215):

  • ClaimHtlcSuccessTx, an incoming HTLC claimed with its preimage (Transactions.kt:592-620; the signature is at :615). Its output pays localFinalScriptPubKey, a free parameter of createUnsignedTx (:639,:652), and its fee is baked into the output amount (:648).
  • ClaimHtlcTimeoutTx, an offered HTLC refunded after its CLTV (Transactions.kt:664-690; signature at :686, free final script at :710,:722).

The shipped, honest node passes the group's onchain wallet address as that final script (Helpers.kt:835,:886, with GroupNodeKeyManager.kt:25 overriding defaultFinalScriptPubKey). Nothing in the protocol requires it: the output script is committed only by the claim's own signature, which the seed's key alone produces. A modified operator node — or a hand-built transaction from any seed holder — pays any address.

The statement's cap never covered this. CoSignerPolicy.checkRemoteCommitment caps only the HTLCs the group offers (CoSignerPolicy.kt:105-106), and the code comment says why incoming HTLCs are exempt (:103-104): "an HTLC offered to it is the counterparty's to add, and refusing to sign over one would stall the channel rather than protect anything". The doc says the same (docs/group-lightning-wallet.md:105). The real bound on the incoming side is the channel's capacity, which every co-signer holds to MAINNET_CHANNEL_CAP = 1,000,000 sats (GroupLightningRollout.kt:38, enforced at GroupLightningCoSigner.kt:374-377).

The attack, step by step.

  1. The group has a channel with the LSP. Someone pays a group invoice for, say, 600,000 sats. The LSP adds the HTLC to its commitment; the co-signers sign it — correctly, since incoming HTLCs are uncapped and the group's balance has not moved.
  2. The attacker sends the LSP an error naming the channel. Impersonating the node takes only the seed, which every participant holds (D4), including removed members (docs/group-lightning-wallet.md:329). No group signature is involved.
  3. The LSP force-closes, publishing its commitment — the one carrying the incoming HTLC as an offered output.
  4. The attacker builds ClaimHtlcSuccessTx by hand: input the HTLC output, witness the preimage and the seed-derived HTLC key's signature, output to the attacker's own address.
  5. This races the honest node's claim to the group's address (Helpers.kt:829-841). Both spends are valid; the claim tx has no anchor (taproot channels publish none, per the doc's table), so the race is first-seen plus RBF fee, and the attacker can spend up to the whole output on fees. The attacker has the edge whenever the honest operator is offline — and is not racing anyone when the attacker is the operator.
  6. The payer sees their preimage revealed and counts the payment settled. The group never receives the balance. Repeat per in-flight incoming HTLC; the take is bounded only by the channel cap.

Who can actually run it — narrower than "any seed holder", and worth stating precisely. Claiming needs the preimage, and the preimage of a group invoice is generated by the node that created the invoice (GroupLightningNode.kt:567-568, peer.createInvoice(Lightning.randomBytes32(), …)) and lives in that device's payments database. So the realistic attackers are: the current operator, who holds every current invoice's preimage; and past operators and removed members, who keep the seed and the preimages of any still-unpaid invoices from their term. A seed holder who never operated has no preimages for in-flight HTLCs, and cannot get a new incoming HTLC into a signed commitment without being the current operator (co-signer check 1, GroupLightningCoSigner.kt:183-187). That is a narrower set than the finding states — but it includes every ex-operator and every removed member forever, which is bad enough.

The doc repeats the false bound in three places: the trust-table afterword (docs/group-lightning-wallet.md:333-337), the risks table ("a removed member keeps the seed — griefing, plus in-flight HTLCs up to the cap", :1041), and the Policy docstring ("inFlightCapSat is the most that can be in HTLCs at once, which is the most the node seed is ever worth", GroupLightningWalletStatementEvent.kt:34-36).

Root cause

D5 group-keyed the payment and delayed-payment basepoints and deliberately left the HTLC basepoint on the seed, because claiming on chain is time-critical and a FROST session "is the wrong tool for it" (docs/group-lightning-wallet.md:333-335; the deviation table's HtlcDelayedTx row, :61, says the same). That choice was then justified post hoc by the in-flight cap — but the cap was designed against the offered side (Phase 12's send path), and the incoming side was exempted on the reasoning that refusing to sign over a counterparty-added HTLC "stalls the channel without protecting anything" (CoSignerPolicy.kt:103-104). That reasoning was written when the exposure was believed capped, and was never revisited: under this finding the exemption is the exposure, and a refusal protects exactly the stealable excess, because an HTLC in no signed commitment can never be claimed on chain. Two doc sentences then promoted the design choice into a false security bound.

One mitigating fact the review surfaced: NodeParams.maxHtlcValueInFlightMsat exists upstream as a protocol-level bound on what the counterparty may offer us (NodeParams.kt:136,167), enforced when the peer's update_add_htlc would exceed it (Commitments.kt:542-544) and advertised to the LSP in accept_channel (WaitForOpenChannel.kt:65), which BOLT 2 binds the LSP to respect. The group node never sets it: GroupLightningNode.lightningKmpPeers copies only zeroConfPeers and liquidityPolicy (GroupLightningNode.kt:479-493), so it sits at lightning-kmp's default of 20,000,000,000 msat = 20M sats (NodeParams.kt:246) — twenty times the channel cap, inert.

The fix, in phases

Phase 1 — correct the documents, and show the group its exposure

About 2 days. No schema, no wire-kind, no fork changes; an additive snapshot field.

Goal: nobody downstream of the doc's sentence trusts the cap as the seed's worth, and every member can see the live number at risk.

  • The design doc. Rewrite the trust-table afterword (docs/group-lightning-wallet.md:333-337): the cap bounds only what the group offers; the seed is additionally worth all in-flight incoming HTLC value on the counterparty's commitment, up to the channel cap, claimable by the operator, any past operator, and any removed member, to any address. Fix the risks-table row at :1041 the same way.
  • The code docstrings that repeat the claim: GroupLightningWalletStatementEvent.kt:34-36 (the Policy KDoc) and the cap's rationale comment at CoSignerPolicy.kt:103-104, which stays true for offered HTLCs but must stop implying incoming value is safe.
  • The snapshot carries it. WalletWire.ChannelView gains incomingInFlightMsat: Long? = null and offeredInFlightMsat: Long? = null, summed from localCommit.spec.htlcs in PeerHandle.channels() (GroupLightningNode.kt:552-565: IncomingHtlc amounts are on their way to the group). Nullable with a null default, so an old snapshot and an old build both read as not reported rather than zero — CommonJson has ignoreUnknownKeys (CommonJson.kt:7), so the field is backward compatible in both directions and no schema migration is needed (the snapshot row stores the JSON blob).
  • The cross-check comes free. Every co-signer's ledger already records incoming HTLCs by id with amounts (CoSignerPolicy.Ledger.incoming, CoSignerPolicy.kt:39). Add a DAO read beside GroupLightningCoSigner.signedOursMsat and extend GroupLightningReports.ChannelCheck (GroupLightningReports.kt:36-39,104-108) so the snapshot's incoming figure is checked against what this device last signed, exactly the pattern the balance check already uses. A mismatch means the operator is lying or stale — the screen already has the vocabulary for that.
  • The screen. On GroupLightningWalletScreen.kt (balance at :352, channel rows at :382): under the balance, a line in the style of the existing mismatch copy — N sats on their way in — until they settle, anyone holding the node seed could take them — shown only while the figure is non-zero, with amounts as format arguments per CLAUDE.md. The opening screen's unreviewed-scheme sentence (GroupLightningRollout.kt:24-28 lists the stated bounds) names this exposure beside the cap.

Tests (existing suites, no new harness):

  • GroupLightningReportsJvmTest.kt: a snapshot with the new fields round-trips; an old snapshot without them reads as not reported; a ChannelCheck whose snapshot incoming figure differs from the device's ledger flags a mismatch.
  • GroupLightningNodeJvmTest.kt: channels() sums incoming and offered in-flight from a fake peer's spec.
  • GroupLightningCoSigningJvmTest.kt already populates ledgers with incoming HTLCs; add a case asserting the ledger's incoming sum the screen will read.

Deployment realism: visibility is per-device; a member on an old build sees the old screen and loses nothing. The doc corrections are what the group's understanding relies on, so the release notes say the old sentence was wrong.

Phase 2 — bound the incoming side to the statement's cap

About 4 days. App only: no wire-kind, schema, or fork changes — deliberately, see the table. A co-signer behaviour change, so the rollout rule below applies.

Goal: the seed's worth is bounded by a number the group signed, on both directions of in-flight value, enforced even against a modified operator node.

decision why
where the bound lives both the node's NodeParams.maxHtlcValueInFlightMsat and a co-signer check the node param fails a too-big receive cleanly at update_add_htlc and binds an honest LSP over the wire, but it is operator-local and a modified node ignores it; the co-signer check survives a hostile operator but its failure mode is a refused commitment. Neither alone is enough
which value the statement's existing inFlightCapSat, applied to incoming totals too a fourth value in the policy tag is silently ignored by old builds — read accepts any tag of size ≥ 4 and reads only p[1..3] (GroupLightningWalletStatementEvent.kt:89-91) — so the group would believe in a bound that un-upgraded co-signers do not enforce. Reusing the existing field changes no wire format. A dedicated incoming cap waits for the statement's next change, with the deployment rule below
what a refusal costs a wedge, then either recovery or an LSP force close — accepted a refused commitment means the oversized HTLC never enters any signed commitment and can never be claimed on chain. The recovery path exists: a later commitment with the HTLC failed back passes the policy (incoming shrank, nothing else moved), so an honest operator unwedges the channel. A hostile operator can choose the force close instead — which it could have caused anyway, and D5 still sends the proceeds to the group. The doc's "stalls without protecting anything" is wrong under this finding: the refusal protects exactly the stealable excess

Changes, by file and function:

  • GroupLightningNode.lightningKmpPeers (GroupLightningNode.kt:479-493): the copied NodeParams sets maxHtlcValueInFlightMsat = statement.policy.inFlightCapSat * 1000. This is advertised in accept_channel (WaitForOpenChannel.kt:65) and enforced on receipt (Commitments.kt:542-544), so with an honest operator a too-big incoming payment fails back to the payer instead of wedging anything. (maxAcceptedHtlcs, 19 at NodeParams.kt:247, bounds count, not value; leave it.)
  • CoSignerPolicy.checkRemoteCommitment (CoSignerPolicy.kt:70-106): after the offered-side cap check, mirror it for the incoming side — refuse when incoming HTLCs were added and their new total exceeds inFlightCapMsat. The added.isNotEmpty() guard matters: a commitment that merely carries an already-in-flight HTLC forward must not be refused, or a group that raises the policy later would wedge every live channel.
  • The first commitment is a hole here. checkRemote returns early on pinned == null (GroupLightningCoSigner.kt:399), and on-the-fly funding puts the channel's first incoming HTLC in exactly that commitment. So the incoming cap must also run in CoSignerPolicy.open (CoSignerPolicy.kt:58-62), or in checkRemote before the early return. This is the same exemption first-commitment-policy.md removes wholesale; if that plan lands first, this phase adds one line to its fixed path. Either way, do not ship this phase with the exemption intact — the biggest single receive a channel ever sees is its first one.
  • The receive screen says the most one payment can be (the cap), and any-amount invoice requests and offer payments that would exceed it are refused by the node before the invoice is created — the honest path never reaches the co-signer refusal.

Tests:

  • CoSignerPolicyTest.kt: incoming added over the cap is refused; at the cap it signs; incoming carried forward unchanged past a lowered cap signs; the cap holds in open.
  • GroupLightningCoSigningJvmTest.kt (four devices): a remote commitment carrying an oversized incoming HTLC is refused by every member; the follow-up commitment with the HTLC failed back is signed (the recovery path). GroupLightningCoSigningMainnetJvmTest.kt re-runs both.
  • GroupLightningNodeJvmTest.kt: the built NodeParams carries the statement's cap, not lightning-kmp's 20M-sat default.

Deployment realism: this is a co-signer behaviour change with no format change, so old builds still sign — and any quorum drawn entirely from old-build devices signs an over-cap commitment. For 2-of-4, that is any three un-upgraded devices (the echo gate is n-t+1). The bound holds as a group property only once every participant's device runs the new build — the doc's own Phase 15 rule (docs/group-lightning-wallet.md:977-981) — and the proposal screen should say so when a wallet's members run mixed builds, as the ceremony screen already does for unanswered devices.

Phase 3 — elimination: a spike with an explicit go/no-go

About 3 days of research and a regtest measurement; the fix itself, if go, is an estimated 2-3 weeks across the fork and the sweep machinery. No code in this phase beyond the spike.

Goal: decide, with numbers, whether the HTLC basepoint moves to a group key — the only real elimination — or the group lives with Phase 2's bound.

Pre-signing claims at commitment-signing time: evaluated and rejected. A ClaimHtlcSuccessTx commits to its output amount, which is the input minus a feerate-baked fee (Transactions.kt:648), to a locktime (0 for success, the HTLC's CLTV for timeout, :723), and to the input outpoint — the counterparty commitment's output, which changes with every commitment. So pre-signed claims die with each new commitment, the feerate is right only by luck at claim time (days later), and the claim tx has no anchor to bump it — RBF means a new signature, i.e. the quorum again, at the worst moment. Pre-signing at a spread of feerates multiplies Iceberg sessions per HTLC per commitment for a transaction that will likely never be used. This is not the way; the spike should not reopen it.

A group-keyed HTLC basepoint: the real candidate. The doc rejected it for time-criticality (docs/group-lightning-wallet.md:333-335), but the numbers have changed since that sentence was written: the sweep machinery it would have needed did not exist then and does now (Phase 13), and the deadline is not minutes — it is the HTLC's CLTV, at minimum minFinalCltvExpiryDelta = 144 blocks ≈ a day (NodeParams.kt:252), with lightning-kmp starting its claims fulfillSafetyBeforeTimeoutBlocks = 12 blocks early (:253). A FROST session inside a day-long window is the same shape as the CSV-delayed sweeps the app already does. And the failure mode flips the right way: if the group cannot convene in the window, the LSP times the HTLC out and takes it back — the group loses a payment it was owed, which is a liveness failure, where today's equivalent failure is theft. What it costs:

  • Fork: withGroupBasepoints gains the HTLC basepoint, htlcBaseSecret becomes a poison pill and per-commitment ourHtlcKey nullable (KeyManager.kt:227-228,241,252,264), and the four claim/HTLC constructors guard on null exactly as the existing four group-output guards do (Helpers.kt:531,697,787,1011). HtlcSuccessTx/HtlcTimeoutTx from our own commitment become group-keyed too (Transactions.kt:436,485), so every force close with in-flight HTLCs — not just attack scenarios — needs per-HTLC FROST sessions inside the CLTV window. The claims are built and signed at claim time, so the feerate is fresh; each pays the group's onchain wallet.
  • App: GroupLightningDerivation gains child index 2 beside PAYMENT/DELAYED_PAYMENT (GroupLightningDerivation.kt:50-51,80-87); the sweep machinery (GroupSweep, the FROST SWEEP subject) gains the offered/received HTLC leaves, rebuilt by each member from its own basepoints with the tweak carried in the proposal, as the existing leaves are; the preimage travels with the claim proposal — it is revealed on chain anyway.
  • Deployment: a channel's basepoints are fixed in open_channel, so this applies only to channels opened after the change. Existing channels keep the exposure until closed; the natural vehicle is the next wallet rotation (docs/group-lightning-wallet.md, Phase 14), and every device needs the new build before the group opens the new channel — the Phase 15 rule again.

Go/no-go. Go requires all of: (1) a regtest run with an HTLC in flight at a force close — the current run has none (docs/group-lightning-wallet.md:190-191) — showing the group claim completing well inside the 144-block window; (2) measured FROST session latency from the sweep path, showing 2t-1 devices convene in hours, not days, for realistic groups; (3) a fork diff that stays behind the basepoints seam, per the parity plan's rule for surviving upstream bumps. No-go leaves Phase 2's bound as the standing mitigation and records the decision in the design doc's appendix. Recommendation: run the spike only after Phases 1-2 have shipped and the bound has been lived with; the exposure is then capped at a group-signed number, and elimination is a liveness-versus-theft trade that a real group should make with measurements in hand.

What this does not fix

  • Phase 2 bounds the exposure at the statement's cap; it does not remove it. Until Phase 3 lands a go, a current or past operator can still take up to that much of in-flight incoming value. signer-hygiene.md is the plan for the seed's handling at rest.
  • The griefing that triggers the attack — sending error to force the LSP to close — is unchanged; it is griefing-surface.md's subject. This plan only caps what the close pays the attacker.
  • ClaimHtlcTimeoutTx (refunds of offered HTLCs) shares the free-final-script mechanism (Transactions.kt:722); those amounts are already inside the statement cap, and Phase 3 would cover them incidentally.
  • The adjacent review findings are their own plans: the force-close fence signing a revoked commitment (force-close-revoked-commitment.md), the first-commitment policy exemption this phase depends on (first-commitment-policy.md), the mutual-close amount anchored to the operator's claim (mutual-close-amount.md), and the restored device's empty ledger — which also empties the incoming map Phase 1's cross-check reads (restored-device-marks.md).
  • A successful theft is detected only after the fact: Phase 1's screen shows the exposure, and the payments list would show a settled payment whose balance never arrived. Nothing here raises an alarm in time to stop it; the bound is the mitigation, not detection.

Risks and open questions

risk why it matters what to do
mixed-build groups during Phase 2 any echo quorum drawn from old builds still signs over-cap commitments; for 2-of-4 that is any three devices the proposal screen names un-upgraded members, as the ceremony screen names non-answerers; the group treats the bound as real only once every device is upgraded
reusing inFlightCapSat couples send and receive a group that wants a 600,000-sat receive must raise the cap, raising the offered-side bound with it stated on the proposal screen; a dedicated incoming cap is the follow-up when the statement's format next changes, deployed with the Phase 15 rule
any-amount invoices and offer payments over the cap fail a receive the group wanted dies at update_add_htlc, looking like an LSP error the receive screen shows the cap before the invoice, as it already shows the liquidity fee
a co-signer refusal wedges the channel if the operator is hostile the unwedge needs the operator to ask for the failing commitment; a hostile one can prefer the force close accepted: the force close pays the group under D5, and the refusal is what kept the excess out of every signed commitment
Phase 3 trades theft for a liveness requirement a group that cannot convene 2t-1 devices inside the CLTV window after a force close loses incoming payments it was owed the go/no-go measurements; the honest failure mode is still better than today's, but it is new, and the doc's time-criticality sentence was written about exactly this
an ex-operator's old unpaid invoices their preimages outlive their term, so the exposure survives handovers until the invoices expire invoices have an expiry (NodeParams.kt:174-175); the residual window is the invoice lifetime, and Phase 14's re-key with a new seed closes it at rotation
two devices running one node id the impersonation step of the attack may interact with the LSP's peer storage and data-loss protection in ways not yet traced open question, recorded for the Phase 3 spike; out of scope here because the claim path needs no channel state at all