Files
giza-kmp/docs/lightning/first-commitment-policy.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

226 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# The first commitment must pass the co-signer policy
A remediation plan for finding 3 of the security review: the first remote
commitment a device signs for a channel skips every value rule in
`CoSignerPolicy`. It interacts with [group-lightning-wallet.md](../group-lightning-wallet.md)
Phase 9, check 5, and with the floor-starting deviation at its line 80
("a floor that starts at the first commitment less the fee allowance").
## The finding
`GroupLightningCoSigner.checkRemote` runs its checks in this order
(`composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/managers/GroupLightningCoSigner.kt`):
1. the mainnet channel cap, `:374-377`, which runs for every remote commitment,
first or not;
2. the rebuild: `Commitments.makeRemoteTxs` from the request's `SigningContext`,
byte-equality with the transaction asked to sign, `:384-395`;
3. then `:399`:
```kotlin
if (pinned == null) return null
```
The first commitment this device signs for a channel is approved there. Rule 2
(every newly offered HTLC sits in an open FROST-signed authorisation with
budget left, `CoSignerPolicy.kt:89-101`), the in-flight cap
(`CoSignerPolicy.kt:105-106`, the statement's `inFlightCapSat`, default
200,000 sats) and the floor (`CoSignerPolicy.kt:108-130`) are all behind that
return — they are only reached through `checkRemoteCommitment` at `:402`, which
needs the previous ledger `pinned` holds.
The write path is symmetric. `commitLedger` folds what was approved into the
device's channel ledger, and its `pinned == null` branch (`:430-431`) calls
`CoSignerPolicy.open` (`CoSignerPolicy.kt:58-62`), which builds the starting
ledger from whatever commitment 0 holds — offered HTLCs included — with no
authorisation read and nothing consumed. The floor starts at
`ours + offered − feeAllowance` (`:61`), so an unauthorised offered HTLC in
commitment 0 is not just signed, it is *banked* as the group's baseline.
**The attack, step by step.** It needs a hostile operator *and* the LSP the
statement names, colluding. It cannot work against an honest LSP: check 4 pins
`params.remoteParams.nodeId == statement.lspNodeId` (`:307`), on-the-fly funding
makes commitment 0 carry only the incoming HTLC, and the LSP validates its own
commitment before the channel is live. The review (co-signer report, finding C;
operator-wiring report, gap 1) could not construct an operator-only variant.
1. A payer pays the group — say 500,000 sats — which under on-the-fly funding is
what opens the channel.
2. The operator's node and the colluding LSP negotiate the channel so that the
LSP's first commitment (the one the group signs) carries, beside the incoming
HTLC, an *offered* HTLC of 400,000 sats to a payment hash whose preimage the
LSP holds.
3. Every co-signer runs `checkRemote`: the funding output is the group key with
the LSP's (`:294-316`), the capacity is under `MAINNET_CHANNEL_CAP`
(1,000,000 sats, `GroupLightningRollout.kt:38`), the transaction rebuilds
from its context because the operator built a real one, and `pinned == null`
approves it. No authorisation is ever consulted, because none exists.
4. Every co-signer echoes, `n − t + 1` echoes collect, and the group signs.
`commitLedger` starts the floor at 100,000 + 400,000 − allowance.
5. The LSP fulfils the HTLC with its preimage. Of the 500,000 the group was
paid, it keeps 100,000. The policy's own arithmetic now *defends* this
outcome: the floor says the group is owed only what the attack left it.
The bound is the incoming amount itself, up to the channel cap — the in-flight
cap does not apply either, so this is larger than the exposure the statement's
cap exists to bound (the design doc's "the cap is the most the node seed can
ever be worth" assumes it does).
## Root cause
`open` was written as a pure ledger constructor — its doc comment is "whatever
it holds is where the floor starts" (`CoSignerPolicy.kt:57`) — and `checkRemote`
treats the first commitment as the definition of the floor rather than as a
commitment. The three value rules were placed inside `checkRemoteCommitment`,
which needs a previous ledger, so a commitment with no predecessor gets none of
them. But only rule 3's fall-versus-floor reasoning genuinely needs a
predecessor. Rule 2 and the cap degenerate cleanly: with `previous.offered`
empty, *every* offered HTLC is "added", and both checks are fully computable on
commitment 0. The exemption was never a structural necessity; it is a missing
branch.
## The fix, in phases
### Phase 1 — `open` runs rule 2 and the cap
**About a day. App only: no schema, no wire kind, no fork change.**
`CoSignerPolicy.open` (`CoSignerPolicy.kt:58-62`) gains the three arguments
`checkRemoteCommitment` already takes — `budgets: Map<String, Long>`,
`closed: Set<String>`, `inFlightCapMsat: Long` — and returns a `Verdict` instead
of a bare `Ledger`:
- **Rule 2 at open.** Every offered HTLC in commitment 0 is checked the way
`checkRemoteCommitment` checks an added one (`:96-101`): its hash must have a
budget (open authorisations, `GroupLightningAuthorisations.budgets`), must not
be expired (`closed`), and its amount must fit what is left. `remaining`
starts from `budgets` itself, since nothing is in flight from earlier
commitments. The per-hash accumulation is the same loop; factor the
added-HTLC block out of `checkRemoteCommitment` so open and later commitments
share it verbatim, rather than copying it.
- **The cap at open.** All offered HTLCs are new at commitment 0, so the
`added.isNotEmpty()` guard (`:106`) is always true and the check is simply
`offered.sum > inFlightCapMsat` → refuse.
- **The floor still starts where the first commitment puts it.** The
`Verdict.Sign` ledger keeps `floorMsat = ours + offered − feeAllowance` as at
`:61` today, and `consumed` is empty: nothing can settle at commitment 0, so
no budget is spent by opening. What changes is only that offered HTLCs in the
baseline are now authorised ones.
| | decision | why |
|---|---|---|
| an *authorised* offered HTLC in commitment 0 signs | rule 2 already expresses "the group agreed"; refusing offered HTLCs at open outright would hardcode today's on-the-fly-only world into the policy | a group-funded or spliced-in channel (the splice-out follow-up in Phase 13 of the design doc) would carry one legitimately, and a policy that cannot express it will be worked around |
| the floor-starting behaviour is kept | a co-signer's first commitment is its only truth about the channel; any other starting floor (zero, capacity) refuses every real open | the review found no fault in the floor itself, only in what gets into it |
| the checks live in `CoSignerPolicy`, not in `checkRemote` | the policy is pure and unit-tested in `CoSignerPolicyTest.kt`; logic in the co-signer is reachable only through the four-device harness | the same shape as every other value rule |
**Tests, in `CoSignerPolicyTest.kt`:** one new test beside the existing eight:
- `the first commitment answers to the authorisations too` — `open` with an
offered HTLC and empty budgets refuses; with a budget for its hash it signs
and the floor starts at value − allowance; with the hash in `closed` it
refuses; with two offered HTLCs against one budget it applies the same
budget-left arithmetic as `one authorisation cannot be offered twice over`;
with offered HTLCs over `inFlightCapMsat` it refuses; and the honest shape —
an incoming-only on-the-fly commitment with empty budgets — signs.
### Phase 2 — the two call sites, and the four-device tests
**About a day.**
`GroupLightningCoSigner.kt`:
- **`checkRemote` (`:399-405`).** The early return goes. Budgets, the expired
set and the cap are fetched for the open case as they already are for the
pinned one (`:400-402`), and the branch becomes
`pinned == null → CoSignerPolicy.open(commitIndex, txid, spec, budgets, closed, cap)`
with `Refuse` mapped to its reason exactly as the `checkRemoteCommitment`
branch does. The mainnet cap check at `:374-377` and the rebuild at `:384-395`
keep running first, unchanged.
- **`commitLedger` (`:430-438`).** The `null` branch takes the same new
signature and handles `Verdict.Refuse` by returning, as the `else` branch
already does at `:433`. The two sites must change together: `commitLedger`
runs only after `check` passed (`:193-208`), so a disagreement would mean a
commitment refused at check time is still written into the channel ledger at
echo time, floor and all.
**Tests, in `GroupLightningCoSigningJvmTest.kt`** (which
`GroupLightningCoSigningMainnetJvmTest` re-runs on mainnet parameters), beside
`an outgoing payment the group did not authorise is refused` (`:251`), which
does the same at commitment 1:
- `the first commitment carrying an offered HTLC is refused without an authorisation` —
`channel.commitment(0, spec with an IncomingHtlc)` never gets a signature
(`IcebergSigningTimeout`), and no device's `IcebergChannelLedger` row exists
for the channel afterwards.
- `the first commitment carrying an authorised HTLC is signed` — the group signs
a `pay` authorisation for the hash first (`fixture.sign` with
`GroupLightningAuthorisationEvent.template`, as the force-close test at
`:200-202` does), then commitment 0 with the HTLC is signed and
`correctlySpends` passes.
- `the first commitment over the in-flight cap is refused` — an authorised HTLC
whose amount exceeds the statement's `inFlightCapSat` never gets a signature.
**The regtest happy path must not move.** `GroupLightningRegtestJvmTest.kt`'s
`receive(all, 100_000)` (`:268`) is the on-the-fly open whose commitment 0
carries only the incoming HTLC; it exercises the new `open` branch with empty
budgets and must pass unchanged. That is the regression proof that the honest
path is unaffected.
### Phase 3 — rollout, and the design doc
**About half a day.**
This is a co-signer behaviour change in app code only: schema 32 is untouched
(`StoredLedger`'s JSON shape does not change), no kind moves, the fork gets no
commit. But as with the kinds in the design doc's Phase 15, **the rule a group
relies on is the rule its worst co-signer runs**: signing needs `n − t + 1`
echoes, and devices on an old build will still echo a poisoned first commitment,
so the finding is closed for a group only once every participant's device runs
the new build. A mixed group fails safe, not silent — new-build devices refuse,
so a malicious open stalls rather than signing — and the honest on-the-fly open
is byte-for-byte the path it was, so upgrading cannot wedge a working channel.
The wallet screen's existing per-member bookkeeping is the place to note who has
not upgraded, as Phase 15 already does for unanswered ceremony proposals.
The design doc's deviation table then gets a line: the floor "starts at the
first commitment less the fee allowance" gains *"and the first commitment
answers to the authorisations and the cap like any other"*.
## What this does not fix
- **A restored device re-opens the channel.** A co-signer whose database was
restored has `pinned == null` for a channel mid-life and will treat its next
remote commitment as a first one: rule 2 and the cap now run, but the floor
restarts at whatever that commitment holds, so a drained state becomes the new
baseline. That is the unbuilt high-water-mark collection (design doc line 83),
covered by [restored-device-marks.md](./restored-device-marks.md); this fix
narrows what a restored device can be fed but does not replace the marks.
- **The liquidity fee on the open is still the operator's word.**
`maxLiquidityFeeSat` is enforced by the operator node's liquidity policy only;
no co-signer reads it (the review's doc-overclaim note beside this finding).
With the colluding-LSP threat model of this finding, the fee bound rests on
the LSP's honesty regardless of this fix.
- **Incoming HTLCs at open stay unchecked by design** — an HTLC offered *to*
the group is the counterparty's to add (`CoSignerPolicy.kt:103-104`), and what
the seed can take from them is
[node-seed-in-flight-exposure.md](./node-seed-in-flight-exposure.md)'s subject.
- **The ledger is still committed at echo time,** so a refused-then-retried open
interacts with the echo-time budget burn and channel-wedge surface in
[griefing-surface.md](./griefing-surface.md); this fix adds one more refusal
reason before the ledger write, which is the safe direction, but does not
reorder anything.
- Independent of the open path: the force-close fence's one-behind hole
([force-close-revoked-commitment.md](./force-close-revoked-commitment.md)) and
the mutual-close amount anchored to the operator's spec
([mutual-close-amount.md](./mutual-close-amount.md)).
## Risks and open questions
| risk or question | why it matters | what to do |
|---|---|---|
| a legitimate first commitment with an offered HTLC never occurs today | on-the-fly funding is the only open flow, and its commitment 0 is incoming-only; the authorised-HTLC-at-open branch will be dead code until group-funded channels exist | keep it anyway (the decision table above), with the Phase 2 test as its only exercise; a splice-in flow that needs it must re-read this note |
| mixed-build groups | old-build co-signers still echo a poisoned open, so the fix is per-device, not per-group | say so on the wallet screen until every participant is upgraded; the failure mode is a stalled malicious open, never a signed one |
| the factored added-HTLC loop must not drift from `checkRemoteCommitment`'s | two copies of rule 2 would re-create this finding in miniature the next time one is edited | share one private function; the existing `CoSignerPolicyTest` suite plus the new open tests pin both paths |
| does `open` need the repeat-commitment branch? | `checkRemoteCommitment` allows re-signing the same txid at the same index (`:79-81`) for retransmission; at open there is no previous row, so a retransmitted commitment 0 arrives while `pinned` is still null on devices that never echoed it — already handled, since `open` is deterministic over the same spec | no special case; a device that already echoed commitment 0 has a ledger row and takes the `checkRemoteCommitment` repeat branch |
| interaction with the first-commitment trust in `signedOursMsat` | the wallet screen's "matches the last commitment you signed" reads the ledger this fix now guards more strictly | nothing to do; the figure can only improve |