Repository navigation
[security] Verify that change outputs actually pay this seed - #1032
Conversation
An output counted as change when its policy matched the inputs' and its rebuilt scriptPubKey matched what the output committed to. Neither step established that the key involved was ours. The policy comparison included cosigners resolved from the coordinator's own global xpubs, so one misannotated fingerprint made an output stop matching and skip verification altogether, and multisig never checked our key against the committed script at all. Outputs now compare on script shape alone, and every candidate proves ownership: single sig by rebuilding from the claimed derivation path, multisig by finding this seed's key in the committed script. Where the psbt's account of an output contradicts what the output commits to, the parse refuses rather than quietly reclassifying. A claim set too malformed to answer that question, one populating both derivation path maps or claiming more keys than its script uses, is refused as well. change_data now carries the verified derivation path in place of the coordinator's claimed fingerprints and paths, so the views no longer re-derive trust from strings the parse has already settled. Taproot mismatches stay exempt. A script tree tweaks the internal key, so honest taproot change fails the rebuild too, and embit leaves PSBT_OUT_TAP_TREE unparsed, which is what would tell the two apart.
| for field in ("type", "m", "n"): | ||
| if policy_a.get(field) != policy_b.get(field): | ||
| return False | ||
|
|
||
| return True |
There was a problem hiding this comment.
Simplify to:
return all(policy_a.get(field) == policy_b.get(field) for field in ("type", "m", "n"))
There was a problem hiding this comment.
Claude originally implemented it with the comprehension but I explicitly refactored that out.
I prefer the readability of the simple for loop and find that comprehensions (somewhat ironically) are harder to understand. Also note that I don't think we use any() or all() type keywords at all in the current code, aside from some instances in a few tests.
|
|
||
| # single-sig: p2pkh, p2sh-p2wpkh, and p2wpkh; taproot handled separately | ||
| # below. | ||
| elif "pkh" in self.policy["type"]: |
There was a problem hiding this comment.
Would be safer to check for exact strings:
elif self.policy["type"] in ("p2pkh", "p2sh-p2wpkh", "p2wpkh"):
There was a problem hiding this comment.
Updated in a929b8b.
A few other similar checks were updated.
And more importantly, the catch-all else deep within the change verification was pulled up to a more sensible location to catch an unsupported policy type.
A test case was added for the catch-all.
| if len(out.bip32_derivations) > 1: | ||
| raise PSBTSurplusDerivationPathsError("Single-key output claims more than one derivation path") | ||
|
|
||
| # Rebuild the scriptPubKey from the key at the claimed derivation path | ||
| if len(out.bip32_derivations.values()) == 1: |
There was a problem hiding this comment.
out.bip32_derivations is an OrderedDict.
len(out.bip32_derivations) is the same as len(out.bip32_derivations.values()).
Just save it once in a bip32_derivations_len = len(out.bip32_derivations), and then check:
if bip32_derivations_len > 1:
...
elif bip32_derivations_len == 1:
...
else: # bip32_derivations_len == 0
...
| # output is actually committing to. | ||
|
|
||
| # Remember that "change" is ANY output coming back to our seed | ||
| is_change = True |
There was a problem hiding this comment.
Instead of setting is_change to True here, and then revert it back to False in some of the flows - let's just change it to True in the flows where it should stay True.
There was a problem hiding this comment.
Updated in 12c7239.
The reasoning for the refactor is sound: the more conservative stance is to keep is_change as False until we've explicitly gone through every check.
More importantly, this refactor provided a natural place to explain what we are or are not sure of at that point for the single sig vs multisig branches.
I also moved the reminder note about what "change" means in this function (i.e. could be a true change output OR a self-transfer / receive output) to where it's actually assigned to the internal change_data info.
| @@ -283,88 +389,192 @@ def _parse_outputs(self, child_key_derivation_cache: dict): | |||
| out_policy = PSBTParser._get_policy(out, vout[i].script_pubkey, self.psbt.xpubs, child_key_derivation_cache) | |||
There was a problem hiding this comment.
Instead of enumerate(self.psbt.outputs) could we use zip(self.psbt.outputs, vout, self.verified_output_derivation_paths)?
There was a problem hiding this comment.
I find zip to be just barely over my "it's magic" threshold and for me it impairs readability. Constant theme with me: I prefer simpler and more straightforward approaches. There's almost never anything that's particularly clever or elegant about my code.
Plus we need the i index anyway.
| # The output pays a multisig this seed is part | ||
| # of, but the psbt did not claim our key there. | ||
| # We treat this deception as an attack. | ||
| raise PSBTOutputOwnershipContradictionError(f"Output's committed script holds this seed's key at {bip32.path_to_str(derivation_path_obj.derivation)} but the psbt claims another fingerprint and/or public key there") |
There was a problem hiding this comment.
Are we sure this is an attack?
I can imagine a system that manages multiple multisig wallets, where one seed is used in many wallets - and the PSBTs' outputs are enriched with all the derivation paths known by the system.
Why not just keep is_change false in this case? Or maybe I'm just confused?
There was a problem hiding this comment.
This path would only be reached if the psbt didn't claim our fingerprint at all in the output's derivation paths.
If our key was referenced along with a bunch of extra unrelated derivation paths, the psbt would raise PSBTSurplusDerivationPathsError in a different if/else branch and hard stop regardless.
| if len(out.bip32_derivations) > self.policy["n"]: | ||
| # We don't try to decide if this is an attack or a | ||
| # mistake. We just abort the parse. | ||
| raise PSBTSurplusDerivationPathsError("Multisig output claims more derivation paths than its script has keys") |
There was a problem hiding this comment.
Suppose we have a PSBT of a 2-of-3 multisig wallet where the output comes with a 2-of-3 multisig script that happens to contain our key - but belongs to a different multisig wallet from the input.
i.e. the input is spent by 2 keys out of p1, p2, p3, and the output can be spent by 2 keys out of p1, p2, p4. And suppose self.root refers to p1.
Will that output be considered a change-output? If so, I think this is very dangerous.
There was a problem hiding this comment.
I agree this is a regression even if an edge case. A Multisig wallet sharing the same "shape" and one or more cosigners (the active seed) would show as change incorrectly.
There was a problem hiding this comment.
Yes, such an output would be considered change here.
A planned follow-up will compare the cosigners resolved for the inputs against the ones resolved for the output. But it only works when the psbt supplies the global xpubs and those xpubs are themselves just coordinator claims. An attacker simply omits the xpubs.
So it will still just be a modest sanity check, similar to other checks in this PR. It can disprove but cannot prove.
The overall thing to keep in mind is that these parse()-time checks can only catch obvious forgeries and malformed psbts. No real guarantee exists until the user loads their "known-good" descriptor.
So an is_change determination at this stage can only ever be considered preliminary as far as multisig is concerned.
There was a problem hiding this comment.
The more I think about this, if the PSBT omits the global xpubs on a multisig transaction, it would be a reasonable UX choice to never show an output to the user as change. In fact, I believe the currently released psbt_parser does exactly that. Requiring the global xpubs as a precondition before even proposing an output as change for the user to validate seems like reasonable UX.
This PR changes that behavior, and it may require the follow-up PR to be public before this one can be adequately reviewed.
There was a problem hiding this comment.
Matching cosigner check added back in ff13396, but at the END of the is_presumed_change checks rather than as part of the initial gate.
A couple of reasons for this:
We want to be able to detect -- and warn users -- about malicious deceptions in the psbt; the original gate would simply bail out of the is_change path if the cosigners didn't match. Deceptions in the psbt would go unnoticed (raising an exception to abort a malicious psbt is better than silently categorizing a suspicious output as an external spend).
The check itself doesn't end up adding any likely enhancement to real-world assurances. The cosigner mismatch check depends on global xpubs being provided (they are optional by the BIP-174 spec) and for the output's extra xpubs to be included. If they are provided, then we'd also need the output to be fully annotated (bip32_derivations) which are also optional.
Providing all this optional info gives the parser more verifiable information about the output, allowing us to prove to ourselves: nope, this is NOT our wallet's change (even though our key is part of the output's multisig).
The attack version of this output would REDUCE the info provided (as allowed by the spec) to make it impossible for us to do that verification.
And no known coordinator provides this combination of info (global xpubs + annotated output for a different wallet).
So this check was probably always a big nothing.
Having this check included in the original code's initial is_change gate felt like a commonsense reassurance. But the really complex nuances underlying where the cosigners info comes from in the first place make a mess of being able to really understand the scenarios. Note that in this commit I also added a large docstring explanation to _get_cosigners() since I was also struggling to keep all this straight.
There was a problem hiding this comment.
if the PSBT omits the global xpubs on a multisig transaction, it would be a reasonable UX choice to never show an output to the user as change. In fact, I believe the currently released psbt_parser does exactly that.
That's incorrect for v0.8.7 and prior: When the global xpubs are omitted, cosigners becomes None for both the inputs and the outputs (see _get_cosigners()). So the v0.8.7 policy gate WOULD consider an output to a different multisig as potential change (provided that its m-of-n and script type still matched).
Requiring the global xpubs as a precondition before even proposing an output as change for the user to validate seems like reasonable UX.
Since the global xpubs are optional, unfortunately Keeper and BlueWallet both omit them. My guess is that it's to keep the animated psbt QR shorter (I think it's something like 40% fewer frames that way).
So if we applied that rule, we would never properly display the user's expected change for psbts from those wallets.
There was a problem hiding this comment.
I ran this case ({p1,p2,p3} -> 2-of-3(p1,p2,p4)) against ff13396, with only the spending wallet's three xpubs in the global map, which is what Sparrow actually writes. Was reviewing this on my own before posting (had Claude help me poke at it).
It's still counted as change. dev shows the same psbt as a spend. Loading the real descriptor does trigger the dire warning, so that part still works.
I think the issue is the assumption that the check needs "the output's extra xpubs to be included." dev's check never needed p4's xpub. It only had the wallet's three, tried to resolve the output's keys against them, and p4 didn't resolve. dev treated that as the answer: not our quorum, so a spend. ff13396 treats the same thing as "unknown" and skips (output_cosigners is None). That's why it only fires when p4's xpub is also in the global map, which is the shape you noted no coordinator produces.
Two small changes:
-
Once the inputs' cosigners resolved, treat an output whose cosigners don't resolve as a mismatch, not as unknown. If the wallet's xpubs are there, genuine change always resolves against them, so an output that can't has a key that isn't this wallet's. This is gated on
input_cosigners is not None, so Keeper/BlueWallet (no global xpubs) keep the current behaviour. -
In
_get_cosigners, match keys to xpubs by derivation rather than by the claimed fingerprint, i.e. drop theorigin_der.fingerprint == der.fingerprintprecondition. The fingerprint is a label the coordinator wrote; the derivation is the proof. Without this, (1) on its own reintroduces the escape from the description: mislabel one cosigner's fingerprint on the real change output and it stops resolving, so it gets shown as a spend. With (2), a mislabelled genuine cosigner still derives from its xpub and resolves, while an attacker's key still derives from nothing.
Results on this head, xpubs present, inputs spend from our 2-of-3 (p1 = us, p2, p3). Global xpubs are the wallet's three.
| output | dev | ff13396 | (1) only | (1)+(2) |
|---|---|---|---|---|
| 2-of-3 of us, p2, stranger, labelled honestly | spend | change | spend | spend |
| 2-of-3 of us + 2 attacker keys, labelled honestly | spend | change | spend | spend |
| same, but attacker keys labelled as p2 and p3 | spend | change | spend | spend |
| our real change, but p3's fingerprint mislabelled | spend | change | spend | change |
| 2-of-3 of three strangers, with an entry claiming our key | spend | refused | refused | refused |
| our real change, with our entry deleted | spend | refused | refused | refused |
Row 1 is oren's example. Rows 2-3 are the attack. Row 4 is the trade-off (why (2) is needed). Rows 5-6 are the PR's own cases, unchanged.
There was a problem hiding this comment.
45a5eab implements @Chaitanya-Keyal's item 1.) and 2.).
| | claims this seed | doesn't claim this seed | ||
| -------------------------+----------------------+------------------------- | ||
| commits to our key | confirmed: is change | contradiction | ||
| commits to another key | contradiction | presumed external spend |
There was a problem hiding this comment.
I'm still not sure what the top-left case means for multisig wallets.
The fact that our key happens to be in the multisig script doesn't mean this is a change address.
See: https://github.com/SeedSigner/seedsigner/pull/1032/changes#r3952753297
There was a problem hiding this comment.
Somewhat improved in 321bf14.
This entire function suffers a bit from single sig and multisig both using the same is_change bool. That var and the description here project accurate confidence for single sig but don't do justice to the remaining doubts for multisig.
So instead the attitude is now flipped: "presumed" language now predominates and single sig is left to add its own note that says, "No, actually we ARE sure now."
oren-z0
left a comment
There was a problem hiding this comment.
Quick review - my main worry is about claiming that an output is change only because our key participates in the multisig. But maybe I'm just confused.
oren-z0
left a comment
There was a problem hiding this comment.
Quick review. My main worry is about multisig change outputs: https://github.com/SeedSigner/seedsigner/pull/1032/changes#r3952753297
|
Maybe I'm just confused, but my main problem with the PR's multisig cases is that they have heuristics that look on the output's script to decide whether it's a change address. |
In _parse_outputs the flag was set True as soon as the rebuilt scriptPubKey matched, and two multisig branches then turned it back off. That made "change" the default inside the matched arm, so a branch that forgot the flag would record change with nothing verified behind it. Now each branch sets the flag only once its own checks have passed, and an output that satisfies none of them stays an external spend. The two sites where the flag is set split by signature type, and each carries the certainty it actually has: single sig is settled, because our own key rebuilt the scriptPubKey; multisig is a presumption, because our key in the committed script does not say which wallet that script belongs to, and only the user's descriptor can. The reminder that "change" means any output coming back to our seed moves to the line where change_data is built, which is where the word takes that meaning. No behavior change: the same outputs land in the same lists on every fixture shape, and the suite is unchanged.
The rebuild chain in _parse_outputs matched single sig and taproot by
substring ("pkh" in type, "p2tr" in type) and had no else. embit reports
a script type it does not recognize as None, and _get_policy passes that
through, so a psbt whose inputs and outputs were both unrecognized passed
the shape gate and died in the substring test with a bare TypeError. The
guard meant for an unhandled type sat inside the scriptPubKey match,
where an empty rebuild cannot arrive.
The arms now name their types exactly, matching _build_singlesig_script,
and the chain ends in a catch-all else that raises RuntimeError with the
unsupported type in the message. The unreachable inner guard is removed.
A test drives a p2pk psbt into the catch-all.
The flag in _parse_outputs is set for two different strengths of finding. For single sig our own key rebuilt the scriptPubKey, so the output is provably ours. For multisig we have only shown that our key sits in the committed script, and which wallet that script belongs to is settled later, by the user's descriptor. Calling both "is_change" gave the multisig case a certainty it does not have. The process docstring is held to the same standard: it describes how ownership is determined rather than how outputs are verified as change, the verdict table reads "presumed change", and the multisig rebuild bullet names the key-in-script step that the table row depends on. No behavior change.
A multisig output whose committed script holds this seed's key can
still belong to a different wallet: a 2-of-3 over {p1,p2,p4} when the
inputs spend {p1,p2,p3}. When the psbt supplies global xpubs and fully
annotates the output, _get_cosigners resolves a cosigner list for the
inputs and one for the output, and lists that differ mean the output
pays a quorum other than the one being spent from. That output is now
counted as an external spend. It stays presumed change when the lists
match or when either side's cosigners are unresolved.
This is hygiene, not a security control. The global xpubs are optional
and unauthenticated, so a coordinator that omits them skips the check,
and a mismatch demotes rather than raises because a transfer into a
second multisig this seed belongs to is legitimate. No surveyed
coordinator produces the shape the check fires on: every one except
Bitcoin Core annotates only its own wallet's outputs, and Core, which
annotates any output a descriptor in its wallet file can solve, writes
no global xpubs at all. Settling which wallet a multisig output pays
still needs the user's own descriptor.
The comparison sits after the ownership checks rather than at the
policy shape gate, so a psbt whose output cosigners fail to resolve
still faces every ownership check.
_get_cosigners' sorted() is what makes the two lists comparable: two of
the three multisig fixtures order the same wallet's keys differently on
the input and on its change output. Its docstring now separates what
is claim from what is checked and what the result does and does not
establish, its loop carries the procedure inline, and two early-outs
name the omitted-xpubs and omitted-derivations cases before the loop
(behaviour-neutral: both already raised from inside it). Tests pin the
sort, the different-quorum spend, and the no-xpubs presumed-change
fallback.
|
ACK and reviewed. I want to do some hands on testing before merge. I'd also like to see some more feedback ideally from contributors before merging if possible. |
|
I've completed hands on testing and believe this PR is ready for merge. |
|
I've been reviewing this pr with many interruptions in-between. partial LGTM at ff13396: I've focused testing between this PR branch and yet-to-be-Krux-v26.09.0 which uses embit 0.8.2 Using testqrs site, Tested that normal PSBTs are not failing, are displaying accurately: Also, specifically for this pr where suspect PSBTs fail early, all of the "testqrs dot com attack scenario" PSBTs were tested on both devices (for pr1013 and pr1032) and seedsigner behaved w/ expected exception screens for this pr. I'm comfortable with changes in the psbt_parser, but still have more review in views and tests. |
|
@kdmukai I did an extensive adversarial review with 3 different models and they all had similar feedback. Here's the summary using 5.6 Luna, which considered 1 and 2 as critical to fix (1 was already raised by previous reviewers) and found some interesting unhandled exceptions that I would recommend fixing: |
The cosigner comparison skipped any output whose cosigners failed to resolve, so the different-quorum case it exists for never fired on a real psbt: coordinators write only the spending wallet's xpubs, and a foreign cosigner's key then resolves against nothing. Once the inputs' cosigners resolve, an output that differs or fails to resolve is counted as a spend. Keys now match xpubs by derivation alone rather than requiring the claimed fingerprint to match first. The fingerprint is a label the coordinator wrote; requiring it let one mislabeled cosigner turn genuine change into a spend, and a key an xpub really derives is proof enough on its own. The different-quorum test now uses the wallet's own xpubs, the shape every xpub-writing coordinator produces, and a second test keeps the four-xpub variant.
|
Thank you for the review, @knorrium! 1.a. Multisig foreign quorum is still shown as change (the foreign cosigner cannot be resolved): Same issue that @Chaitanya-Keyal identified in his #1032 (comment) part 1.). Resolved in 45a5eab 1.b. Multisig foreign quorum is still shown as change (global xpubs omitted): Wallets like Keeper and BlueWallet always omit the global xpubs for QR-based signers, so a blanket rule in that scenario would guarantee an initial misrepresentation in the UI (e.g. the total spend amounts would be too high when there is legitimate change). The initial As a stateless signer, we just can't provide guarantees until a trusted descriptor is provided. I think this future TODO is the better route; it would be a bad UX tradeoff to create a hard-stop requirement to load the descriptor (imagine an emergency spend scenario but the descriptor isn't nearby), but instead we could try to improve how we communicate the "we can't be sure" reality to the user.
Same issue that @Chaitanya-Keyal identified in his #1032 (comment) part 2.). Resolved in 45a5eab.
Already tracked in internal TODO docs, some planned for upcoming PRs.
New issue not previously identified. Added to internal TODO docs, not yet prioritized. |
fa326fd to
45a5eab
Compare
Chaitanya-Keyal
left a comment
There was a problem hiding this comment.
ACK at 45a5eab. Re-reviewed, my previous comment is now resolved, and the rest of the changes look good. I've also run this locally against several scenarios and the outcomes look correct.
…ia descriptor From a review of open upstream SeedSigner PRs and their discussions: - Previous-tx proof (upstream SeedSigner#995/SeedSigner#977): a non_witness_utxo must hash to the txid its input spends (UTXO_MISMATCH), and a legacy p2sh input may not rely on a witness_utxo alone (INVALID_WITNESS_UTXO). Legacy signatures commit to no amount, so either lie hides fee in a single signing. - Multisig change without global xpubs (review thread on upstream SeedSigner#1032): a change-shaped m-of-n containing our key is not provably this wallet's. It is now a payment unless a loaded descriptor identifies it; the new PSBTIdentifyChangeView offers "Load descriptor to identify change", and returning with a descriptor re-reads the psbt. verify_multisig_output's per-entry check is shared as _descriptor_owns_output. - OP_RETURN payload read from its push opcode (SeedSigner#965/SeedSigner#1003): direct pushes lost their first byte on screen. - INCONSISTENT_FINGERPRINTS (SeedSigner#1040): a global xpub whose fingerprint disagrees with the keys it derives. - Untrusted-QR crashes (SeedSigner#967/SeedSigner#968/SeedSigner#970/SeedSigner#971): SeedQR checksum and whole-payload detection, signmessage bounds, parse_derivation_path on short/48h paths, and a UR2 seq_len bound. New psbt_faker vectors cover each (PREV_TX_TXID_MISMATCH, LEGACY_P2SH_WITNESS_ONLY, OP_RETURN_DIRECT_PUSH, TX-24.xpub_fingerprint_mismatch, TX-21.ms_foreign_quorum*, TX-21.ms_honest_change_no_xpubs). TX-20 and XTRAS.MIXED_INPUT_TYPES are re-vendored after generator fixes; TX-20 is no longer vacuous. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test+fix: resync psbt_faker corpus and close the gaps it exposes Re-vendor the regenerated psbt_faker corpus (97 vectors, fixed BIP-371 taproot encoding) and cover every vector in psbt_suite_util. Parser fixes for vectors that previously parsed: - FORGED_OUTPUT_OWNERSHIP also when a genuine key of ours annotates an output whose script does not pay it (TX-21.claims_us_pays_other, TX-21.ms_repointed_*, TX-22.ms_decoy_*). - MISLABELED_OUTPUT_OWNERSHIP: an output paying our key but attributed to a foreign fingerprint (TX-21.pays_us_claims_other, taproot_claims_other, ms_fp_relabeled). - SURPLUS_DERIVATIONS / MIXED_DERIVATION_MAPS for contradictory claims (TX-22.surplus_paths, taproot_surplus_internal_key, mixed_path_maps*). - SCRIPT_TIMELOCK warning for CLTV/CSV in an output's committed script (TX-20.cltv_time). - verify_multisig_output checks every derivation entry instead of embit's first-match Descriptor.owns (decoy-last used to verify as ours). TX-20.cltv_height/csv_relative are vacuous upstream (scriptPubKey is still p2wpkh) and marked so. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test: stop flow tests hanging when collected after the refusal-screen tests tests/test_psbt_refusal_screens.py imported the GUI before tests/base.py installed its renderer and hardware-button doubles. Any flow test collected after it then ran against the real, never-configured Renderer (every View and the error View raise, so the Controller loops forever) or against real buttons (real-screen flows wait for a key press forever). The full suite only passed because alphabetical order puts the flow tests first. The refusal-screen test now imports base first, and base.py also rebinds seedsigner.gui.Renderer when the package was already imported by some other module collected earlier. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix: port upstream PSBT/QR hardening; identify multisig change only via descriptor From a review of open upstream SeedSigner PRs and their discussions: - Previous-tx proof (upstream SeedSigner#995/SeedSigner#977): a non_witness_utxo must hash to the txid its input spends (UTXO_MISMATCH), and a legacy p2sh input may not rely on a witness_utxo alone (INVALID_WITNESS_UTXO). Legacy signatures commit to no amount, so either lie hides fee in a single signing. - Multisig change without global xpubs (review thread on upstream SeedSigner#1032): a change-shaped m-of-n containing our key is not provably this wallet's. It is now a payment unless a loaded descriptor identifies it; the new PSBTIdentifyChangeView offers "Load descriptor to identify change", and returning with a descriptor re-reads the psbt. verify_multisig_output's per-entry check is shared as _descriptor_owns_output. - OP_RETURN payload read from its push opcode (SeedSigner#965/SeedSigner#1003): direct pushes lost their first byte on screen. - INCONSISTENT_FINGERPRINTS (SeedSigner#1040): a global xpub whose fingerprint disagrees with the keys it derives. - Untrusted-QR crashes (SeedSigner#967/SeedSigner#968/SeedSigner#970/SeedSigner#971): SeedQR checksum and whole-payload detection, signmessage bounds, parse_derivation_path on short/48h paths, and a UR2 seq_len bound. New psbt_faker vectors cover each (PREV_TX_TXID_MISMATCH, LEGACY_P2SH_WITNESS_ONLY, OP_RETURN_DIRECT_PUSH, TX-24.xpub_fingerprint_mismatch, TX-21.ms_foreign_quorum*, TX-21.ms_honest_change_no_xpubs). TX-20 and XTRAS.MIXED_INPUT_TYPES are re-vendored after generator fixes; TX-20 is no longer vacuous. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(screenshots): give the multisig PSBT global xpubs; add PSBTIdentifyChangeView The screenshot generator's multisig PSBT carries no PSBT_GLOBAL_XPUB, so since multisig change is only identified through global xpubs or a loaded descriptor, it had no change output and the PSBTChangeDetailsView_multisig_* screenshots crashed (get_change_data returned None), failing CI's "Generate screenshots". - The multisig screenshots now use a copy of that PSBT with global xpubs taken from its own wallet descriptor, like a coordinator that includes them. - The parser is built with the loaded descriptor, and the descriptor is loaded before the PSBT, so the "verified" screenshot parses the way the device would. - New screenshots for PSBTIdentifyChangeView (no descriptor / descriptor loaded), from the original xpub-less PSBT. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
SeedSigner#1032 replaced change_data's claimed_derivation_paths list of strings with a single verified_derivation_path (a list of ints the parse proved this seed owns). get_total_output_value still read the old key, so the high-fee check raised KeyError on every psbt once rebased onto it. Use PSBTParser.is_change_branch on the verified path instead, and update the test fixtures to the new shape.
SeedSigner#1032 replaced change_data's claimed_derivation_paths list of strings with a single verified_derivation_path (a list of ints the parse proved this seed owns). get_total_output_value still read the old key, so the high-fee check raised KeyError on every psbt once rebased onto it. Use PSBTParser.is_change_branch on the verified path instead, and update the test fixtures to the new shape.
…ork hardening preserved (#453) * Clarify psbt_parser.py docstrings and comments No behavior change. Corrects prose that had drifted from what the code does, and addresses two local names for the same reason. Docstrings and comments: - The two ownership-claim exceptions state the condition each signals, without speculating about how it arises. - _get_seed_derivation_path drops the output-versus-input severity split, which _verify_claimed_derivation_paths already states. - The verified_*_derivation_paths comment says what an entry holds, and no longer explains the None the positive statement already implies. - parse() steps 1 and 2 name the per-key condition instead of "scopes". - _parse_inputs gains a docstring covering the amount total and the one-shared-policy requirement. - The single-sig branch comment names the script types it covers. Naming: - _parse_multisig's `sc` parameter becomes `multisig_script`. - A TODO marks _get_policy's local `script`, which shadows the embit module imported at the top of the file. * Drop "scope" from the two ownership-claim summary lines "An output scope claims..." reads no better than "An output claims...". The word is doing no work in a sentence about what the output says, and the psbt-scope sense it borrows is not the one the reader needs there. * Verify that change outputs actually pay this seed An output counted as change when its policy matched the inputs' and its rebuilt scriptPubKey matched what the output committed to. Neither step established that the key involved was ours. The policy comparison included cosigners resolved from the coordinator's own global xpubs, so one misannotated fingerprint made an output stop matching and skip verification altogether, and multisig never checked our key against the committed script at all. Outputs now compare on script shape alone, and every candidate proves ownership: single sig by rebuilding from the claimed derivation path, multisig by finding this seed's key in the committed script. Where the psbt's account of an output contradicts what the output commits to, the parse refuses rather than quietly reclassifying. A claim set too malformed to answer that question, one populating both derivation path maps or claiming more keys than its script uses, is refused as well. change_data now carries the verified derivation path in place of the coordinator's claimed fingerprints and paths, so the views no longer re-derive trust from strings the parse has already settled. Taproot mismatches stay exempt. A script tree tweaks the internal key, so honest taproot change fails the rebuild too, and embit leaves PSBT_OUT_TAP_TREE unparsed, which is what would tell the two apart. * Set is_change only after each branch's own checks In _parse_outputs the flag was set True as soon as the rebuilt scriptPubKey matched, and two multisig branches then turned it back off. That made "change" the default inside the matched arm, so a branch that forgot the flag would record change with nothing verified behind it. Now each branch sets the flag only once its own checks have passed, and an output that satisfies none of them stays an external spend. The two sites where the flag is set split by signature type, and each carries the certainty it actually has: single sig is settled, because our own key rebuilt the scriptPubKey; multisig is a presumption, because our key in the committed script does not say which wallet that script belongs to, and only the user's descriptor can. The reminder that "change" means any output coming back to our seed moves to the line where change_data is built, which is where the word takes that meaning. No behavior change: the same outputs land in the same lists on every fixture shape, and the suite is unchanged. * Match policy types exactly and refuse an unsupported one The rebuild chain in _parse_outputs matched single sig and taproot by substring ("pkh" in type, "p2tr" in type) and had no else. embit reports a script type it does not recognize as None, and _get_policy passes that through, so a psbt whose inputs and outputs were both unrecognized passed the shape gate and died in the substring test with a bare TypeError. The guard meant for an unhandled type sat inside the scriptPubKey match, where an empty rebuild cannot arrive. The arms now name their types exactly, matching _build_singlesig_script, and the chain ends in a catch-all else that raises RuntimeError with the unsupported type in the message. The unreachable inner guard is removed. A test drives a p2pk psbt into the catch-all. * Rename is_change to is_presumed_change The flag in _parse_outputs is set for two different strengths of finding. For single sig our own key rebuilt the scriptPubKey, so the output is provably ours. For multisig we have only shown that our key sits in the committed script, and which wallet that script belongs to is settled later, by the user's descriptor. Calling both "is_change" gave the multisig case a certainty it does not have. The process docstring is held to the same standard: it describes how ownership is determined rather than how outputs are verified as change, the verdict table reads "presumed change", and the multisig rebuild bullet names the key-in-script step that the table row depends on. No behavior change. * Compare cosigners before presuming multisig change A multisig output whose committed script holds this seed's key can still belong to a different wallet: a 2-of-3 over {p1,p2,p4} when the inputs spend {p1,p2,p3}. When the psbt supplies global xpubs and fully annotates the output, _get_cosigners resolves a cosigner list for the inputs and one for the output, and lists that differ mean the output pays a quorum other than the one being spent from. That output is now counted as an external spend. It stays presumed change when the lists match or when either side's cosigners are unresolved. This is hygiene, not a security control. The global xpubs are optional and unauthenticated, so a coordinator that omits them skips the check, and a mismatch demotes rather than raises because a transfer into a second multisig this seed belongs to is legitimate. No surveyed coordinator produces the shape the check fires on: every one except Bitcoin Core annotates only its own wallet's outputs, and Core, which annotates any output a descriptor in its wallet file can solve, writes no global xpubs at all. Settling which wallet a multisig output pays still needs the user's own descriptor. The comparison sits after the ownership checks rather than at the policy shape gate, so a psbt whose output cosigners fail to resolve still faces every ownership check. _get_cosigners' sorted() is what makes the two lists comparable: two of the three multisig fixtures order the same wallet's keys differently on the input and on its change output. Its docstring now separates what is claim from what is checked and what the result does and does not establish, its loop carries the procedure inline, and two early-outs name the omitted-xpubs and omitted-derivations cases before the loop (behaviour-neutral: both already raised from inside it). Tests pin the sort, the different-quorum spend, and the no-xpubs presumed-change fallback. * Count an unresolved output cosigner set as a mismatch The cosigner comparison skipped any output whose cosigners failed to resolve, so the different-quorum case it exists for never fired on a real psbt: coordinators write only the spending wallet's xpubs, and a foreign cosigner's key then resolves against nothing. Once the inputs' cosigners resolve, an output that differs or fails to resolve is counted as a spend. Keys now match xpubs by derivation alone rather than requiring the claimed fingerprint to match first. The fingerprint is a label the coordinator wrote; requiring it let one mislabeled cosigner turn genuine change into a spend, and a key an xpub really derives is proof enough on its own. The different-quorum test now uses the wallet's own xpubs, the shape every xpub-writing coordinator produces, and a second test keeps the four-xpub variant. --------- Co-authored-by: kdmukai <934746+kdmukai@users.noreply.github.com> Co-authored-by: Nick Klockenga <nick@klockenga.net>
…cestry Record upstream SeedSigner#1032 ancestry after squash of #453
…squash 3rdIteration#453) 3rdIteration#453 was squash-merged, so dev has the content of upstream PR SeedSigner#1032 but not its commits. This merge changes no files; it only records the PR head (84c84c3, which contains upstream/dev b225ae7) as an ancestor so future upstream merges don't replay SeedSigner#1032. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Renaming _policy_shape_matches to _is_change_candidate dropped the reason the candidacy test compares shape alone. Without it, adding the cosigners to the comparison reads as a harmless tightening. The old wording named a misannotated fingerprint as what breaks an output's cosigner resolution. Since SeedSigner#1032, _get_cosigners matches each key to a global xpub by derivation path alone and never reads the fingerprint, so the restored note names a misannotated derivation path instead.
|
Regarding proposed embit pr152 I have tested seedsigner as of Nov 1 (last merge pr1047), using pr152 atop embit 0.8.2, instead of embit 0.8.0. All tests for this pr at testqrs dot com still behave exactly as expected. |

Description
This PR is focused on hardening the PSBTParser against psbts that are either malformed or may be deliberately lying about aspects of the change outputs.
EXTENSIVE effort was invested to provide descriptive comments throughout that are much more detailed than usual. The goal was to try to help people who are not yet experts in psbts to level up their knowledge and still follow what this revised change output verification process is doing.
Changes written by Claude Opus 4.x/5 and Keith, with multiple critical full review passes by Fable 5 and 5.1.
How to tackle this PR
Step 1:
This is a large PR with some complicated subtleties, but the best starting point is the long docstring in
PSBTParser._parse_outputsthat describes the new, more thorough vetting of change outputs.Copied verbatim here:
Step 2:
Next I'd recommend that you read through the docstrings of the new tests in
test_psbt_parser.py. I wouldn't go through the actual test code yet. Just make sure that the overall picture provided above is clear and that the various subtle deceptions or malformed psbt fields described in the new tests more or less make sense.Step 3:
Then I'd step through the changes in
psbt_parser.py. You'll find more descriptive comments throughout.Step 4:
At this point I think reviewing the code in the new tests will be more straightforward. A fresh readthrough of the new tests docstrings should also help reinforce everything absorbed in the above steps.
Step 5:
Compare a SeedSigner OS build for this PR vs the v0.8.7 release against the test psbts for this PR on testqrs.com:
To run your own copy of the testqrs.com source, see: kdmukAI-bot/btc-datagen@1b87df8
Step 6:
The remaining misc changes are minor (e.g. catching the new exceptions and showing the new warning screens).
Screenshots
Background and rationale by Claude
(note from Keith: This is pasted here as-is for later reference. But I think it'll be easier to go through the above steps to understand the full process first, then come back here so you can more fully appreciate what was insufficient in the original code. I also think Claude's writing is just harder to understand in general, but this supplementary info section would take too long for me to completely rewrite. Perhaps its primary value is to provide context for other AI scans of these changes)
What this section is for
The steps above are the way in. This is the background they assume: what the old code
actually did, why the new gate looks the way it does, and the judgment calls that a diff
does not show.
What the old code did
An output became a change candidate when
out_policy == self.policy, and a candidate wasconfirmed as change when the script we rebuilt for it hashed to its
scriptPubKey.Neither step established that a key of ours was involved, and the two failed in different
directions depending on what the psbt supplied.
Take a 2-of-3 native segwit psbt whose change output has been repointed at a stranger's
2-of-3, with the derivation path entries left untouched so the psbt still claims our seed
owns it:
Why the first row is a spend. A policy can carry the cosigners resolved from the
coordinator's own global xpubs. The attacker's script resolves no cosigners, so its policy
degrades to script type plus m-of-n while the inputs' policy stays fully resolved, the two
stop comparing equal, and the output leaves the change branch before anything is checked.
The amount displayed is correct and no alarm is raised. But cosigner resolution turns on
the fingerprints the psbt itself supplies, so that exit is available on demand: one
misannotated fingerprint takes any output out of verification.
Why the second row is change. With no global xpubs to resolve, both policies degrade
to script type plus m-of-n, so they compare equal, the output enters the change branch, the
attacker's
witness_scripthashes to thescriptPubKeyexactly as it should, and theoutput is counted as change. The user is shown 10,000 sats coming back to them while the
money leaves for someone else.
The gate change and the ownership proof each close a different row.
A quorum that includes our key
The table above is a stranger's script that claims our seed. The other shape is a
2-of-3 that genuinely holds our key but belongs to a different wallet: the inputs
spend {p1,p2,p3}, the output pays {p1,p2,p4}, and the psbt annotates our key
truthfully. Every ownership check passes, because the claim is true. What separates
the two quorums is the global xpubs, and only when the psbt supplies them for every
key in the output:
Why the first row is a spend. With an xpub for every key,
_get_cosignersresolves the inputs' cosigners and the output's cosigners, and the two lists differ.
The old parse got there through full-dict equality on the policy. This PR compares
the two lists explicitly, after the ownership checks, so an output whose cosigners
fail to resolve still faces every ownership check. (The shape-gate commit had dropped
the comparison; the last commit restores it.)
Why the second row is presumed change, in both versions. Without xpubs the parser
has nothing that distinguishes {p1,p2,p3} from {p1,p2,p4}: both are 2-of-3 of the
same script type, and our key is in both. The global xpubs are an optional field the
coordinator fills in (BIP 174), and honest coordinators do omit them, so their absence
cannot be treated as an attack, and an attacker omits them at will. The cosigner
comparison is therefore hygiene against a coordinator bug, not a defense: it never
runs on a psbt whose author chose not to supply the evidence.
What settles this row is the user's own descriptor.
PSBTChangeDetailsViewoffers"Verify multisig change" (load the descriptor) or "Skip verification". With the
descriptor loaded,
verify_multisig_outputrunsdescriptor.owns(output), whichfails for {p1,p2,p4} and aborts the psbt. Without it, the output is shown as presumed
change. Making that verification mandatory is outside this PR.
What decides the question
The
scriptPubKeyis the authority, not one of the things checked. It comes from theunsigned transaction, so it is what actually decides where the money goes. Nothing verifies
it. Everything else is checked against it.
The derivation path is consumed, not verified. It is an input to a derivation we
perform ourselves, never a claim we test: any path that derives from the seed will pass.
Whether it is a path the user's wallet would ever look at is a separate question, and this
PR does not answer it.
So the list of things checked against that authority is short: the supplied script
(multisig, by hashing it), and the supplied fingerprint (only when it claims this seed).
This PR adds the one that was missing, that this seed's key is actually in what the output
commits to.
From the table to the four raise sites
The table in Step 1 has two disagreement cells, and each has a single sig and a multisig
expression. That is why there are exactly four
PSBTOutputOwnershipContradictionErrorraise sites:
path the psbt annotated with someone else's fingerprint; and multisig, where the
committed script holds our key while the psbt puts another cosigner in our place.
where the supplied script hashes correctly but holds no key of ours.
Read the four error messages in that order and they are the table spelled out.
The changes
Change candidacy compares script shape alone.
_policy_shape_matchescompares scripttype plus m-of-n, and nothing else. Shape comes from the
scriptPubKeyand the suppliedscript, neither of which the psbt can edit without changing what it is asking us to sign.
The script types are matched exactly, and a type outside the supported list raises
RuntimeErrornaming it. embit reports a script it does not recognize asNone, sopreviously a psbt whose inputs and outputs were both unrecognized passed the gate
(
None == None) and died in a substring test with a bareTypeError. Both land on theunhandled-exception screen, so this is a cleaner failure rather than a new rejection.
Every candidate proves participation before anything is presumed. Single sig rebuilds
the
scriptPubKeyfrom the key at the claimed derivation path, so a match proves theoutput is ours. Multisig looks for this seed's key in the script the output commits to,
via
_multisig_script_contains_key; a match proves our key is in the script and no more.Nothing is recorded as change by default: each branch sets the flag only once its own
checks pass, and an output that satisfies none of them stays an external spend.
Multisig change is presumed, not confirmed. The flag is
is_presumed_changebecausethe two branches carry different certainty: single sig is settled, multisig has shown
participation and not which wallet the script belongs to. That is settled by the user's
descriptor later in the flow (see "A quorum that includes our key"). One thing the parse
can rule out on its own: when the psbt's global xpubs resolve the cosigners of both the
inputs and the output, and the two lists differ, the output is demoted to a spend. That
comparison runs after the ownership checks and never raises.
Participation is checked even when nothing claims us. When no entry carries this seed's
fingerprint, each supplied derivation path is still derived and the resulting key tested
against the committed script, so an output that pays a multisig we are in cannot be
disowned by relabeling a fingerprint. The loop reads only the path and derives the key
itself, never the coordinator's listed public key, so neither field can switch the check
off.
The claim set has to be answerable. A scope populating both the ecdsa and the taproot
derivation path maps is refused, as is an output claiming more keys than its script uses.
Neither is forbidden by BIP 174 or BIP 371 and embit will parse and sign both, so refusing
them is an opinionated choice rather than a spec requirement.
change_datacarries a verified derivation path. It replaces theclaimed_fingerprintsandclaimed_derivation_pathslists, so the views no longerre-derive trust from strings the parse has already settled.
PSBTChangeDetailsViewreadsthe verified path directly instead of matching a fingerprint and parsing the path back out
of a string.
Two judgment calls
Only the contradiction is graded as an attack. It gets the Dire Warning. The other two
refusals get the plain Warning: an output claiming more keys than its script uses, or a
scope populating both derivation path maps, could be deception or could be a buggy
coordinator, and the parse does not try to tell those apart. All three are terminal, so the
user is stopped either way; the grading only decides how loudly.
Taproot mismatches are exempt, and that is a real gap. The Step 1 docstring says why.
What it does not say is what would close it: embit leaves
PSBT_OUT_TAP_TREEunparsed, andthat field's merkle root is what separates a script tree that legitimately tweaks our
internal key from an output that claims our key and pays someone else. There is a
TODO:at the raise site. The exemption fails in the conservative direction, since an unverifiable
taproot output is shown as an ordinary destination with its amount rather than as change,
but the alarm is genuinely lost until the tree can be parsed.
Testing
254 passing. The new coverage is the multisig participation check across all three multisig
script types, the fingerprint-independent path that catches an output disowned by a
relabeled fingerprint, refusal of a decoy entry in either position, the surplus and
mixed-map refusals, a p2pk psbt driven into the unsupported-type catch-all, the sort on
_get_cosigners' result, a different-quorum output counted as a spend when its xpubsresolve, and the same output presumed change when the psbt omits its xpubs.
Additional Information
The issues this PR resolves were identified via our own internal scans and later also responsibly disclosed by the Red Team 🟥.
This pull request is categorized as a:
Checklist
I ran
pytestlocallyI included screenshots of any new or modified screens
Should be part of the PR description above.
I added or updated tests
Any new or altered functionality should be covered in a unit test. Any new or updated sequences require FlowTests.
I tested this PR hands-on on the following platform(s):
I have reviewed these notes:
Thank you! Please join our Devs' Telegram group to get more involved.