docs/scripts/giza-rename.sh, run over the moves of Phase 3a:
- com.machankura.bennu.{compose,android,desktop} -> mobi.giza.{...}, in
package lines, imports, fully qualified references, the manifest, mainClass,
the Android namespace (one value with applicationId again), the m3Audit
source path, the six docs/scripts tools, and the source links in docs/;
- Res moves from bennu.composeapp.generated.resources to
mobi.giza.compose.resources, now pinned with packageOfResClass so a later
rename of the root project leaves the imports alone;
- BennuDatabase, BennuTheme and the other eleven Bennu identifiers are Giza*.
The script's search is now the same pattern as its sed expressions, so on a
renamed tree it finds nothing and changes nothing.
Checked against the Phase 0 baseline: jvmTest 1643 run (1642 + AppDirJvmTest),
0 failed, 2 skipped; compileDebugKotlinAndroid passes; m3-audit prints the
baseline report line for line. iOS is not compiled on this Linux host.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
The mutual-close amount check trusts the operator's spec, not the co-signer's own ledger
Finding 4 of the security review. The fix keeps checkClosing's shape — output-by-output,
no rebuild — but anchors what the group must be paid to the channel ledger the device
already keeps, instead of to a number the operator supplies. About five days, all in the
app; no schema, wire-kind or fork change.
The finding
GroupLightningCoSigner.checkClosing (composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt:408-417)
is the whole of Phase 9's check 7 ("its amount is our balance minus a capped fee",
docs/group-lightning-wallet.md:799-800). It reads:
val ours = context.spec.toLocalMsat / 1000 // :413
val paid = tx.txOut.filter { it.publicKeyScript == local }.sumOf { it.amount.sat }
val allowance = statement.policy.commitmentFeeAllowanceSat
return if (ours > allowance && paid < ours - allowance) "…" else null // :416
ours is context.spec.toLocalMsat — a field of the SigningContext.Closing the
operator's node attached to the request and serialised over the wire
(CoSigningWire.kt:200). Every other context type is checked against the device's own
records: remote commitments answer to CoSignerPolicy.checkRemoteCommitment over the
pinned channel ledger (GroupLightningCoSigner.kt:399-405), and both commitment paths are
rebuilt from the context and compared byte-for-byte (:348-359, :384-395). The closing
path alone takes the operator's word for the group's balance. The pinned ledger is in
scope at the call site (:313, :320) and is never handed in.
Worse, the guard ours > allowance means a spec with toLocal = 0 switches the amount
check off entirely.
The attack, step by step:
- The operator runs modified node code, and the LSP colludes (or is itself modified).
A stock LSP rebuilds the closer's closing transaction from its own commitment state
and refuses one whose amounts differ (
Helpers.kt:366-410in the fork, matching itsclosingTxs.localAndRemoteagainst the offered signature), so a dishonest close needs the LSP in on it. The design doc's whole premise is that the co-signers, not the counterparty, are the group's defence ("a co-signer signs any mutual close that passes check 7",docs/group-lightning-wallet.md:108). - The LSP initiates a mutual close. No
closeauthorisation is needed on the co-signer side — by design, so an honest LSP-initiated close is never refused (doc line 108). - The operator relays a signing request carrying a closing transaction that pays, say,
5,000 sats to the group's onchain address and the remaining 895,000 to the LSP's
script, with a context whose spec says
toLocal = 0. - Every co-signer's
checkClosingpasses: the local script is the wallet's own derived address (:411), every output pays one of the two named scripts (:412), and withours = 0the amount check is skipped. Each co-signer recomputes the sighash over the given transaction (messageOf,:269-273), so the signature it produces is valid for the cheating transaction. The echo rule sees one honest hash per label and signs. - The LSP aggregates and broadcasts. The group loses everything above 5,000 sats, up to the 1,000,000-sat channel cap — with every co-signer having "checked" the close.
There is also no rebuild of the closing transaction — both commitment paths got one and
this path did not — and no test of a close to a wrong address or a short amount: the
co-signing suite's five refusals (GroupLightningCoSigningJvmTest.kt:226-319) never build
a closing transaction.
Root cause
Check 7 was implemented as an internal consistency check — the transaction must match
the context it arrives with — on the one path where consistency is not enough, because
both halves of the comparison come from the operator. The device holds the truth the check
needs: CoSignerPolicy.Ledger (composeApp/src/commonMain/kotlin/mobi/giza/compose/wallet/lightning/CoSignerPolicy.kt:32-43)
tracks exactly what the group can claim (oursMsat plus offered HTLCs, valueMsat)
against a floor that only authorised payments lower, and it is persisted per channel in
IcebergChannelLedger and loadable with load(pinned.ledger). The closing path was never
wired to it.
Two real complications explain why it was not, and any fix has to answer both:
- The ledger is the LSP's view; the close's spec is the node's.
commitLedgerrecords the last remote commitment this device signed (GroupLightningCoSigner.kt:422), whileSigningContext.Closingcarriescommitment.localCommit.spec— the node's local commitment (forkHelpers.kt:333,:398). The two move one index apart while an update is in flight — the same snapshot mismatch the design doc explains at line 97. A naivepaid >= ledger.valueMsat - allowancewould refuse an honest close requested mid-dance. - The closing fee is not the commitment fee. When the group's node is the closer, the
fee comes out of the group's side (
Transactions.kt:1324,ClosingTxFee.PaidByUs), and at a high feerate it can exceed the 5,000-satcommitmentFeeAllowanceSatdefault (GroupLightningWalletStatementEvent.kt:41). Anchoring to the ledger with only that allowance would fail honest closes exactly when fees spike.
The fix, in phases
Phase 1 — a closing rule in CoSignerPolicy
Goal: the amount a close must pay is derived from the ledger by a pure, unit-tested function, with the in-flight gap and the closing fee handled explicitly. About two days.
CoSignerPolicy.kt, new function beside checkRemoteCommitment:
fun checkClosing(previous: Ledger, closeSpec: CommitmentSpec, feeSat: Long, budgets: Map<String, Long>, closed: Set<String>): Verdict
closeSpec is the context's spec in the node's local view: toLocal is ours, and an
HTLC we offered arrives as OutgoingHtlc. The rule:
- Flip the view (
toLocal↔toRemote,OutgoingHtlc↔IncomingHtlc) so the spec is comparable with the ledger, then decide which state the close is from:- Same state as the ledger. The flipped spec's value (
toRemoteplus offered HTLCs) equalsprevious.valueMsat. This is the normal case: the channel went quiet before closing (Transactions.makeClosingTxsrequiresspec.htlcs.isEmpty(), forkTransactions.kt:1317, and negotiation only signs once both sides converge). - One state ahead. Treat the flipped spec as the next remote commitment and run it
through
checkRemoteCommitment(previous, previous.commitIndex + 1, …)with the live budgets. A Sign verdict means the local commitment legitimately settled a payment the ledger has not seen — the mid-dance gap, passed without trusting the operator. - Anything else: refuse. The policy's existing rules do the work — an understated
toLocaleats the fee allowance and then the floor refuses it; an HTLC that "settled" without an authorisation has no budget to consume.
- Same state as the ledger. The flipped spec's value (
- Return the validated value (the flipped spec's value from whichever branch
matched). From here on
closeSpecis no longer operator data: it has been forced to agree with the device's own ledger within the policy's own tolerances. - The fee is measured, not assumed. The caller passes
feeSat = input amount − Σ outputsof the actual transaction. The close must pay the group at leastvalidated − feeAllowance − feeSatwhen the group is the fee-payer, andvalidated − feeAllowancewhen it is not — andfeeSatitself is capped at a new constantMAX_CLOSING_FEE_SAT(start at 50,000: beyond any sane negotiated fee, below a theft worth having). A close whose fee exceeds the cap is refused as greedy, the same ruleGroupSweep.checkalready applies to sweep feerates.
| decision | why | |
|---|---|---|
| two accepted states (same, or one ahead via the existing policy) rather than a wider tolerance on amounts | a tolerance re-introduces "the operator picks the number"; replaying the policy means the only slack is the fee allowance the group already signed | |
the fee read off the transaction and capped, not folded into commitmentFeeAllowanceSat |
a mainnet fee spike can legitimately exceed 5,000 sats; refusing those closes would push the group into a force close at a higher fee. The cap is a constant for now; a statement policy field is the cleaner form and is a statement-version change, left as a follow-up | |
| the dust exemption stays: a validated value at or under the allowance keeps the current skip | a channel whose remainder is dust has nothing checkable to pay; refusing its close would strand it |
Tests, in CoSignerPolicyTest.kt beside the existing floor and budget cases:
- a close at the ledger's value, no HTLCs, passes in the same state;
- a close one state ahead where the difference is exactly an authorised payment settling passes, and consumes budget;
- a close one state ahead whose extra fall has no authorisation is refused;
- a close two states away, or with a value that fits neither state, is refused;
- the fee cap: at the cap passes, over it refused.
Phase 2 — wire it into checkClosing
Goal: the co-signer refuses a close its own ledger cannot explain, including every close on a channel it has no ledger for. About two days, tests included.
GroupLightningCoSigner.kt:
checkClosinggainspinned: IcebergChannelLedger?,budgetsandclosed— all already computed or one call away at the call site (:308-321). The script checks at:411-412are unchanged.pinned == nullrefuses the close. A device that never signed a remote commitment for the channel — new, or restored from a stale backup with an empty ledger — has no floor and cannot check anything; it abstains. This is the close-path twin of the first-commitment exemption that first-commitment-policy.md removes for commitments, and it leans on restored-device-marks.md: until high-water-mark collection lands, a restored device abstains from closes for good, which costs the groupn-t+1quorum slack but never money.- The amount line becomes: load the ledger, run
CoSignerPolicy.checkClosing, and on Sign requirepaid >= validated − feeAllowance − (feeSat if the group pays the fee), withfeeSatmeasured from the transaction and capped. The refusal message says what the ledger believes the group holds. - No rebuild. Both commitment paths are rebuilt with
Commitments.makeRemoteTxs/makeLocalTxsbecause a commitment's outputs are derived — per-commitment tweaks, HTLC leaves, key bases — and the only way to enumerate them is to build the transaction. A closing transaction has no derived structure: two outputs to two scripts the context names and the device independently pins, an input already pinned by check 3, and amounts Phase 1 validates against the ledger.Transactions.makeClosingTxsexists and is pure (forkTransactions.kt:1316), but a byte-for-byte rebuild would need the negotiatedfeeandlockTimeon the wire — neither is inCoSigningWire.Contexttoday, so a rebuild is a wire change that buys nothing over the output-by-output check once the amounts are anchored. The sighash the co-signer recomputes covers the whole transaction, so what it checks is what it signs.
| decision | why | |
|---|---|---|
| output-by-output checks with a ledger-anchored amount, not a rebuild | the closing transaction has no derived parts to mistrust; a rebuild adds a wire-field change (fee, lockTime) and a second code path for no extra assurance | |
pinned == null refuses rather than trusts the spec |
trusting the spec with no ledger is the finding, verbatim. The cost is abstention by devices that cannot check, and the echo rule tolerates up to t-1 of those |
|
no close authorisation required on the co-signer, unchanged |
doc line 108: refusing an LSP-initiated close only makes the LSP force-close at the group's cost. The ledger anchor is what makes that safe to keep |
Tests, in GroupLightningCoSigningJvmTest.kt (and therefore in
GroupLightningCoSigningMainnetJvmTest.kt, which re-runs the suite on mainnet
parameters), with a Channel.close(spec, fee) helper beside Channel.commitment that
builds the transaction with Transactions.makeClosingTxs and the context as
FundingSigner.SigningContext.Closing:
a mutual close that pays a script that is not the group's is refused— today untested;a mutual close that pays the group short is refused— the honest spec, a light transaction;a mutual close with an understated spec is refused— the finding itself: the transaction matches the lying context, the ledger disagrees;an honest close is still signed, including one requested one state behind the ledger (a payment settled in the local commitment the device has not signed the remote twin of), and the LSP-initiated shape of it;a device that never signed for the channel abstains from its close— sign commitments with three devices, then ask all four for the close, and assert the fourth never echoes.
Phase 3 — rollout and the design doc
About a day.
- No schema change (the ledger already carries everything Phase 1 reads), no wire-kind change (the context carries everything Phase 2 needs), no fork change. The new rule is co-signer-side only.
- Deployment realism, as the design doc puts it for the kinds: a co-signer on an old
build still echoes a cheating close. The attack needs
n - t + 1devices to echo the same hash, so the group is safe once fewer thann - t + 1devices run the old build — but every participant should upgrade before the group treats the rule as in force, the same way Phase 15 treats the kinds (docs/group-lightning-wallet.md:977-981). For 2-of-4 that means at least two devices on the new build. - The design doc gains a deviation row: check 7's "its amount is our balance minus a capped fee" now says whose balance — the device's own ledger, with the one-state gap and the measured, capped closing fee — and line 108's rationale is kept and now safe.
What this does not fix
- A colluding operator and LSP can still grief. They can refuse to close honestly, force-close at the group's fee cost, or stall. D5 (group basepoints) is what sends a force close's proceeds to the group's keys; this plan is about the mutual-close path only.
- The force-close fence off-by-one — signing local commitment
lastRemote − 1, which may already be revoked — is force-close-revoked-commitment.md's. Both plans read the sameLedger.commitIndex; whichever lands second must rebase its fence arithmetic on the other's. - An overstated ledger blocks honest closes.
commitLedgerruns at echo time, before the signature completes, so a burned commitment can advance the ledger past the channel's real state — and Phase 1's anchor would then refuse the honest close that follows. That is griefing-surface.md's echo-time-commit finding made visible on the close path; the failure is a refusal (liveness), never a theft, but the two plans should land together. - In-flight HTLCs at a force close stay claimable by a node-seed holder: node-seed-in-flight-exposure.md. A mutual close requires empty HTLCs, so this plan never sees them.
- A restored device abstains from closes until restored-device-marks.md rebuilds its ledger. If the whole group restored from stale backups, the wallet cannot mutual-close at all and must force-close under D5.
Risks and open questions
| risk | why it matters | what to do |
|---|---|---|
| the one-state gap is wider than one state | commitLedger at echo time can advance the ledger over commitments that were never completed, so the close's spec can be several states behind the ledger with honest balances |
griefing-surface.md's fix (commit at signing, not echoing) removes most of it; until then the refusal is safe-direction and the group can still force-close |
| the closing-fee cap is a guess | too low and honest mainnet closes at fee spikes are refused; too high and it is the new allowance | 50,000 sats is a starting constant, pinned by a test; the real fix is a policy field on the wallet statement, which is a statement-version change and a follow-up |
pinned == null abstention shrinks the quorum |
a group with several new or restored devices may fall under n - t + 1 echoing devices and be unable to close |
acceptable: force-close under D5 remains, and restored-device-marks.md is the real fix. The ceremony and restore flows should say so |
| the LSP's closee path signs before the group's | in signClosingTx the group's signature answers the LSP's chosen transaction (fork Helpers.kt:357-410); a colluding LSP picks which of the variants to offer |
harmless once the amount is anchored: every variant must pay the validated value to the pinned script |
the ledger's valueMsat includes offered HTLCs that a close spec can never carry |
a close with HTLCs outstanding is not signable (Transactions.kt:1317 requires them empty), but the ledger may still list offered HTLCs that failed back without a settling commitment reaching this device |
the one-ahead policy run explains exactly those deltas through budgets; a delta with no budget refuses. If that bites in practice, the answer is high-water-mark exchange, not a wider tolerance |