Skip to content

[security] Verify that change outputs actually pay this seed - #1032

Merged
newtonick merged 6 commits into
SeedSigner:devfrom
kdmukai:psbt_output_ownership
Sep 19, 2026
Merged

newtonick merged 6 commits into
SeedSigner:devfrom
kdmukai:psbt_output_ownership

Conversation

@kdmukai

@kdmukai kdmukai commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

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_outputs that describes the new, more thorough vetting of change outputs.

Copied verbatim here:

"""********************* How output ownership is determined *********************
Many outputs are obviously NOT ours. An output is only considered possible
change if its policy matches the inputs' policy "shape" (script type, plus m-of-n
for multisig; see parse()); anything else is recorded as an external spend.

The psbt will usually annotate which key(s) a change output pays (see embit's
bip32_derivations and taproot_bip32_derivations), but this is just a claim
supplied by the coordinator. These annotations are not authoritative. But such
claims are significant; if our checks prove that the claim is false, we consider
the deception an attack.

-- Proving the claim --
The output's scriptPubKey determines where the value ACTUALLY goes. But the
scriptPubKey only contains a hash of the spending conditions (note: taproot uses a
tweaked key instead), so we can't simply inspect the scriptPubKey to determine if
the output is ours.

We must build our own version of the scriptPubKey via:
  * single sig: derive a key from our seed using the claimed derivation path.
  * multisig: hash the claimed witness_script or redeem_script, then check that a
    key derived from our seed is among that script's keys.

That leaves us holding two independent answers about the same output: which key it
commits to (our rebuild, matched against the scriptPubKey), and which key the psbt
says it commits to (the claim). We evaluate the output on those two facts:

                             | claims this seed     | doesn't claim this seed
    -------------------------+----------------------+-------------------------
    commits to our key       | presumed change      | contradiction
    commits to another key   | contradiction        | presumed external spend

If our two answers contradict each other, the psbt has been caught in a deception.
We raise an exception and reject the psbt.

Multisig change can't be fully verified until later in the process, so we use
"presumed" to avoid conveying a false impression of certainty. Single sig carries
its own note later in this function about its guarantees.

(note one exception: no taproot mismatch is rejected. A script tree tweaks our
internal key, so an honest taproot change output fails to match too, and we cannot
yet tell that apart from an output that claims our key but pays someone else. All
taproot mismatches pass as EXTERNAL spends and are never considered "change".)
******************************************************************************"""

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:

Screenshot 2026-08-22 at 8 04 59 AM Screenshot 2026-09-04 at 11 01 40 PM

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

PSBTSurplusDerivationPathsView PSBTMixedDerivationPathTypesView PSBTOutputOwnershipContradictionView

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 was
confirmed 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:

psbt supplies old parse this PR
global xpubs spend 10,000 refused
no global xpubs change 10,000 refused

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_script hashes to the scriptPubKey exactly as it should, and the
output 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:

psbt supplies old parse this PR
global xpubs for all four keys spend 10,000 spend 10,000
no global xpubs presumed change 10,000 presumed change 10,000

Why the first row is a spend. With an xpub for every key, _get_cosigners
resolves 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. PSBTChangeDetailsView offers
"Verify multisig change" (load the descriptor) or "Skip verification". With the
descriptor loaded, verify_multisig_output runs descriptor.owns(output), which
fails 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 scriptPubKey is the authority, not one of the things checked. It comes from the
unsigned 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 PSBTOutputOwnershipContradictionError
raise sites:

  • commits to our key, doesn't claim this seed: single sig, where the output pays us at a
    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.
  • commits to another key, claims this seed: the general mismatch; and the multisig case
    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_matches compares script
type plus m-of-n, and nothing else. Shape comes from the scriptPubKey and the supplied
script, 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
RuntimeError naming it. embit reports a script it does not recognize as None, so
previously a psbt whose inputs and outputs were both unrecognized passed the gate
(None == None) and died in a substring test with a bare TypeError. Both land on the
unhandled-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 scriptPubKey from the key at the claimed derivation path, so a match proves the
output 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_change because
the 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_data carries a verified derivation path. It replaces the
claimed_fingerprints and claimed_derivation_paths lists, so the views no longer
re-derive trust from strings the parse has already settled. PSBTChangeDetailsView reads
the 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_TREE unparsed, and
that 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 xpubs
resolve, 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:

  • Other: security

Checklist

I ran pytest locally

  • All tests passed before submitting the PR

I included screenshots of any new or modified screens

Should be part of the PR description above.

  • Yes

I added or updated tests

Any new or altered functionality should be covered in a unit test. Any new or updated sequences require FlowTests.

  • Yes

I tested this PR hands-on on the following platform(s):

  • SeedSigner OS on a Pi0/Pi0W board; tested via extra psbt scenarios in testqrs.com

I have reviewed these notes:

  • Keep your changes limited in scope.
  • If you uncover other issues or improvements along the way, ideally submit those as a separate PR.
  • The more complicated the PR, the harder it is to review, test, and merge.
  • We appreciate your efforts, but we're a small team of volunteers so PR review can be a very slow process.
  • Please only "@" mention a contributor if their input is truly needed to enable further progress.
  • I understand

Thank you! Please join our Devs' Telegram group to get more involved.

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.
Comment on lines +677 to +681
for field in ("type", "m", "n"):
if policy_a.get(field) != policy_b.get(field):
return False

return True

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify to:

return all(policy_a.get(field) == policy_b.get(field) for field in ("type", "m", "n"))

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/seedsigner/models/psbt_parser.py Outdated

# single-sig: p2pkh, p2sh-p2wpkh, and p2wpkh; taproot handled separately
# below.
elif "pkh" in self.policy["type"]:

@oren-z0 oren-z0 Sep 7, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be safer to check for exact strings:

elif self.policy["type"] in ("p2pkh", "p2sh-p2wpkh", "p2wpkh"):

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +429 to +433
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:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
    ...

Comment thread src/seedsigner/models/psbt_parser.py Outdated
# output is actually committing to.

# Remember that "change" is ANY output coming back to our seed
is_change = True

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of enumerate(self.psbt.outputs) could we use zip(self.psbt.outputs, vout, self.verified_output_derivation_paths)?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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")

@oren-z0 oren-z0 Sep 7, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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")

@oren-z0 oren-z0 Sep 7, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. 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.

  2. In _get_cosigners, match keys to xpubs by derivation rather than by the claimed fingerprint, i.e. drop the origin_der.fingerprint == der.fingerprint precondition. 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.

@kdmukai kdmukai Sep 16, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

45a5eab implements @Chaitanya-Keyal's item 1.) and 2.).

Comment on lines +363 to +366
| claims this seed | doesn't claim this seed
-------------------------+----------------------+-------------------------
commits to our key | confirmed: is change | contradiction
commits to another key | contradiction | presumed external spend

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 oren-z0 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 oren-z0 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quick review. My main worry is about multisig change outputs: https://github.com/SeedSigner/seedsigner/pull/1032/changes#r3952753297

@oren-z0

oren-z0 commented Sep 8, 2026

Copy link
Copy Markdown

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.
Declaring an address as a change address is extremely dangerous because it hides the fact that a huge amount can be sent there.
An address should be considered a change address only if it could be found in the Receive Addresses list after scanning a wallet descriptor.
The PSBT's output derivation paths are hints that can be used to find the addresses instead of iterating one by one. The process should take the full multisig wallet descriptor and the PSBT's output derivation path, calculate the address and compare the result to the output's address.
If the address is different - it's an attack.
If something is missing for the calculation - show the full address. Maybe if we have some data in the PSBT that indicates this this could be a change address (i.e. it's enriched with the full script of the output which contains our key), there should be a warning below the address "This address could be a change address, but SeedSigner was unable to verify it".

@kdmukai

kdmukai commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

here should be a warning below the address "This address could be a change address, but SeedSigner was unable to verify it".

I think it's worth revisiting how we present multisig change before the descriptor is loaded.

PSBTChangeDetailsView_multisig_unverified (2)

BUT... that's out of scope for this PR.

This PR is just focused on tightening the sanity checks during the initial psbt parse().

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.
@newtonick

Copy link
Copy Markdown
Collaborator

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.

@newtonick

Copy link
Copy Markdown
Collaborator

I've completed hands on testing and believe this PR is ready for merge.

@jdlcdl

jdlcdl commented Sep 14, 2026 •

Copy link
Copy Markdown

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
My focus is searching for discrepancies against display of the same PSBTs on two projects that have had changes in psbt parsing recently. I found no un-expected discrepancies along the way, and no failures from
either signer.

Using testqrs site, Tested that normal PSBTs are not failing, are displaying accurately:
* single-sig p2pkh
* single-sig p2wpkh
* single-sig p2sh-p2wpkh
* single-sig p2tr
* multisig p2sh
* multisig p2sh-p2wsh
* multisig-p2wsh

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.

@knorrium

Copy link
Copy Markdown

@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:

 1. Multisig foreign quorum is still shown as change

  src/seedsigner/models/psbt_parser.py:553-573

  A malicious output can be a different 2-of-3 wallet containing this seed’s key. If global xpubs are omitted—or the foreign cosigner cannot be resolved—the parser leaves
  is_presumed_change = True.

  The user can then choose “Skip verification” in PSBTChangeDetailsView and approve the transaction.

  I reproduced this with the branch’s own quorum fixture:

  global xpubs: input wallet only
  output quorum: this seed + one input cosigner + foreign cosigner
  result: change_amount=10000, spend_amount=0

  This is exactly the concern raised in the PR comments, and the current head does not resolve it. The test test__parse__counts_a_different_quorum_as_change_if_no_global_xpubs
  explicitly locks in the unsafe behavior.

  Recommendation: unresolved multisig outputs must not be categorized as wallet change. Treat them as external/unverified, or require descriptor verification before displaying them
  as change. “Skip verification” should not permit approval of an unresolved multisig output.

  2. _get_cosigners() still trusts the claimed fingerprint as a matching key

  src/seedsigner/models/psbt_parser.py:879-884

  The code requires:

  origin_der.fingerprint == der.fingerprint

  The fingerprint is coordinator-provided metadata. A malformed or deliberately relabeled derivation causes the output cosigners to become unresolved. Combined with the previous
  issue, that can turn a foreign quorum into presumed change.

  The unresolved-output logic should distinguish:

  • no global xpubs at all: unknown;
  • input cosigners successfully resolved, but output keys cannot resolve against them: mismatch.

  Cosigner resolution should compare derived key material, not require the untrusted fingerprint label to match first.

  Medium findings:

  3. Nonzero OP_RETURN outputs are omitted from recipient accounting

  src/seedsigner/models/psbt_parser.py:597-621

  OP_RETURN outputs are excluded from destination_amounts and spend_amount. Their value is instead reflected only in the calculated fee.

  I reproduced this with a 500,000-sat OP_RETURN output:

  input_amount = 100000000
  change_amount = 1000
  spend_amount = 0
  fee_amount = 99499000
  op_return_data = b'bc'

  The UI therefore presents a value-burning output as an enormous fee and never shows its amount beside the OP_RETURN output.

  Recommendation: reject nonzero OP_RETURN values or display each OP_RETURN output and amount explicitly.

  4. Empty derivation paths can crash the review flow

  src/seedsigner/models/psbt_parser.py:1024-1027
  src/seedsigner/views/psbt_views.py:363-368

  The parser accepts an output derivation path of [] if the key genuinely derives from the seed. It then stores that output as change. PSBTChangeDetailsView unconditionally
  evaluates:

  verified_derivation_path[-1]

  A crafted PSBT reaches IndexError instead of a controlled transaction warning.

  The parser should reject paths that cannot contain branch/index components, or the view should handle malformed paths safely.

  5. Missing UTXO data can produce an uncaught exception

  src/seedsigner/models/psbt_parser.py:312-320

  If an input claims the selected seed but contains neither witness_utxo nor non_witness_utxo, script_pubkey is never assigned. Parsing raises:

  UnboundLocalError: cannot access local variable 'script_pubkey'

  This should become a dedicated malformed-PSBT error handled by PSBTOverviewView.

  6. Unsupported and malformed scripts bypass the new warning screens

  src/seedsigner/models/psbt_parser.py:480-484, 747-766
  src/seedsigner/views/psbt_views.py:101-139

  Unsupported script types and malformed multisig scripts raise RuntimeError/ValueError, but the view catches only the custom verification exceptions. A user can therefore encounter
  an uncaught error screen rather than a controlled discard flow.

  The existing test suite currently expects an uncaught RuntimeError for unsupported scripts, which confirms this gap.

  Low/medium findings:

  7. OP_RETURN decoding assumes one encoding and retains only the last output

  src/seedsigner/models/psbt_parser.py:597-599

  The parser assumes a fixed OP_RETURN OP_PUSHDATA1 length payload layout. For a normal direct push such as OP_RETURN 03 "abc", it reports b"bc".

  Multiple OP_RETURN outputs overwrite self.op_return_data; in my test, one and two resulted in only b"wo" being retained.

  8. Fee/value conservation is not validated

  src/seedsigner/models/psbt_parser.py:621

  The parser does not reject negative fees or output totals exceeding input totals. Such a PSBT can reach the review/signing flow with misleading arithmetic, even though it will
  generally fail broadcast.

  Recommendation: reject negative fees and validate:

  inputs = outputs + fee
  fee >= 0

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.
@kdmukai

kdmukai commented Sep 16, 2026

Copy link
Copy Markdown
Contributor Author

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 parse() can only rule out outputs that are self-evidently not our change. Note the comment here as is_presumed_change is set to True: https://github.com/kdmukai/seedsigner/blob/45a5eabb9d3bb8afc496d219168642845c4cc8a1/src/seedsigner/models/psbt_parser.py#L553-L559

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.


  1. _get_cosigners() still trusts the claimed fingerprint as a matching key:

Same issue that @Chaitanya-Keyal identified in his #1032 (comment) part 2.). Resolved in 45a5eab.


  1. through 7.:

Already tracked in internal TODO docs, some planned for upcoming PRs.


  1. Fee/value conservation is not validated:

New issue not previously identified. Added to internal TODO docs, not yet prioritized.

@kdmukai
kdmukai force-pushed the psbt_output_ownership branch from fa326fd to 45a5eab Compare September 16, 2026 15:31

@Chaitanya-Keyal Chaitanya-Keyal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

3rdIteration added a commit to 3rdIteration/seedsigner that referenced this pull request Sep 18, 2026
…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>
3rdIteration added a commit to 3rdIteration/seedsigner that referenced this pull request Sep 18, 2026
* 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>
@newtonick
newtonick merged commit b225ae7 into SeedSigner:dev Sep 19, 2026
2 of 4 checks passed
@newtonick newtonick moved this from 0.8.8 Needs Review to 0.8.8 Merged in @SeedSigner Development Board Sep 19, 2026
@newtonick newtonick added this to the 0.8.8 milestone Sep 19, 2026
Chaitanya-Keyal pushed a commit to Chaitanya-Keyal/seedsigner that referenced this pull request Sep 20, 2026
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.
Chaitanya-Keyal added a commit to Chaitanya-Keyal/seedsigner that referenced this pull request Sep 20, 2026
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.
3rdIteration added a commit to 3rdIteration/seedsigner that referenced this pull request Sep 21, 2026
…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>
3rdIteration added a commit to 3rdIteration/seedsigner that referenced this pull request Sep 23, 2026
kkdao pushed a commit to kkdao/seedsigner that referenced this pull request Sep 25, 2026
…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>
kdmukai added a commit to kdmukai/seedsigner that referenced this pull request Sep 30, 2026
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.
@jdlcdl

jdlcdl commented Nov 5, 2026

Copy link
Copy Markdown

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: 0.8.8 Merged

Development

Successfully merging this pull request may close these issues.

6 participants