Skip to content

[security] Check change derivation paths against the inputs - #1073

Merged
newtonick merged 6 commits into
SeedSigner:devfrom
kdmukai:2026-10_psbt_change_path_rules
Nov 13, 2026
Merged

newtonick merged 6 commits into
SeedSigner:devfrom
kdmukai:2026-10_psbt_change_path_rules

Conversation

@kdmukai

@kdmukai kdmukai commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Description by Claude:


The problem

  • Currently a coordinator can send the user's change to a derivation path their wallet never looks at. The user signs as usual, the transaction confirms, and the sats vanish from their balance. Nobody else can spend them, so this is leverage rather than theft: getting them back means learning the path from whoever chose it.
  • The parse currently proves that the user's seed controls the change output but accepts whatever derivation path the psbt names for it. Anyone holding the account xpub can derive the user's addresses at any non-hardened path past it.

The solution

  • Change must come back to the base path (every level before the branch and address index) of one of the inputs this seed signs, on the receive or change branch, at a non-hardened address index. Anything else is refused as an attack: "Suspicious Transaction", "Unsafe Derivation Path", with the path shown. Single sig and multisig alike.
  • An address index more than 10,000 past the smallest index the inputs spend from at that base path gets a "Distant Address" warning instead. An offline device cannot know how far the wallet has handed out addresses, so the user decides.
  • On single sig segwit v0 (p2wpkh, p2sh-p2wpkh) the inputs this seed signs must all be at one base path, unless each supplies a non_witness_utxo (the full previous transaction). A psbt that breaks this rule is refused with "Transaction Problem", and the user can only discard it. A segwit v0 input can falsely claim the user's key at a base path the coordinator chose, and the first rule would accept change there. The _evaluate_input_base_paths docstring explains why only segwit v0 is exposed and why inputs at more than one base path are allowed when each has a non_witness_utxo.

Measured at #1060's head and at this PR's head

Psbt Without this PR With this PR
Change at an extra level under the input's base path (m/84h/1h/0h/7/1/0 for p2wpkh): single sig (four script types) and multisig with the global xpubs removed (three) Parses as change PSBTChangeDerivationPathError
Input at index 3; change at 20,000 Parses, no warning "Distant Address", then "Your Change" marked "Distant index #20000"; signing allowed. 10,003 passes, 10,004 is flagged, and a second input at index 50,000 changes neither
Single sig segwit v0: an extra witness-only input claiming our key at m/84h/1h/0h/7/0/0; change at m/84h/1h/0h/7/1/0 Parses as change, no warning. Our signature on the genuine input is identical whether the extra utxo claims our key or pays the coordinator (measured sighash) PSBTUnverifiableMixedInputBasePathsError

Not covered

The change checks narrow the ways a psbt can send the user's change where their wallet never looks, but a few elaborate routes remain.

  • A real utxo paying our key at a base path the coordinator chose still gets through. The coordinator first sends a small utxo to our key at, say, m/84h/1h/0h/7/0/0, then adds it as an extra input. The change path rules then accept change at m/84h/1h/0h/7/1/0, a path the user's wallet never scans. Tested on all four single sig script types; on single sig segwit v0 the input has to come with a non_witness_utxo. The coordinator still cannot spend the change, and the overview shows one more input than the user expects. A warning listing the base paths is a possible later change.
  • Multisig is exempt from the mixed base path check (the docstring gives the reason). Its change is checked against the wallet's cosigners, which come from the psbt's global xpubs or a loaded wallet descriptor. When the user taps "Skip verification" on a psbt that leaves out its global xpubs, the change path rules are the only check, and they rest on what the inputs claim.
  • Honest single sig segwit v0 psbts spending from two of the seed's accounts are refused when any input is witness-only (measured: p2wpkh inputs at m/84h/1h/0h/0/3 and m/84h/1h/1h/0/2; with a non_witness_utxo on both, it parses). As of v32.1, Bitcoin Core attaches the previous transaction to every input its wallet holds and keeps them whenever any input is segwit v0, so a Core wallet holding several of the seed's accounts passes. As of 4.8.4, Electrum also attaches them, but its "Show as QR code" export strips them to keep the QR small. An Electrum wallet spends from one account, so its own psbts pass. A psbt joined from two of the seed's Electrum wallets ("Join inputs/outputs") and shown as a QR code is refused.
  • An annotated transfer into another of the seed's accounts is refused (measured: input at m/84h/1h/0h, output claimed at m/84h/1h/1h/0/0).

Design consideration: order of the checks

The parse reports the most serious problem it finds. Milder findings are held aside so that later checks can still find something more serious. But a held finding is raised before any check that relies on the data it has shown to be untrustworthy, and the psbt is refused with the finding's Warning-grade "Transaction Problem" screen.


Screenshots

PSBTUnexpectedChangeDerivationPathView (Dire Warning) and PSBTUnverifiableMixedInputBasePathsView (Warning), both "Discard transaction" only.

PSBTUnexpectedChangeDerivationPathView PSBTUnverifiableMixedInputBasePathsView

The distant address warning and PSBTChangeDetailsView with the distant index marked.

PSBTWarningView_distant_address PSBTChangeDetailsView_single_sig_change_distant_index

Testing

  • testqrs.com updated with scenarios for this PR: https://testqrs.com/?tx=test-1073-change-extra-level
  • pytest: 375 pass (347 at [security] Check input claims against the input's committed script #1060's head): 21 new parser tests (one more renamed) and 7 new flow tests. Screenshot generator passes in all 22 locales.
  • Several rounds of critical review by Claude (Fable model) before opening.
  • Mutations: 37 deliberate breaks of the new code, each monkeypatched and run against the full suite; 33 fail at least one test. The four that pass: the two refusal Views' clear_history flags (the Controller wipes the back stack on every route home anyway), the change details Screen ignoring the distant index flag (the warning still shows), and the wrong-seed check ignoring held output findings ("Seed Can't Sign" in place of the finding; nothing is signed either way). Every base path comparison goes through _get_base_path. Making it keep one level too many fails 61 tests; making it drop one level too many fails 7.

This pull request is categorized as a:

  • Other: Security hardening

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


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.

The high fee and no change warnings each had a View of their own, and
the routing between them was spread across the overview and the high
fee View, which had to know that the no change warning comes next. The
parse now records its non-fatal findings in self.warnings, most serious
first, and PSBTWarningView shows them one at a time, by index, before
the transaction details. A new warning is then a constant and a branch
in that View.

Drops PSBTUnsupportedScriptTypeWarningView. It was reached only when
the parse left no policy, and a successful parse always sets one from
its first input.
An output is shown as change once our key is proven in its script, but
its derivation path is still the psbt's claim. Change at a path the
user's wallet never scans is ours yet lost to the coordinator. Change
must now come back to the base path of one of our verified inputs, on
the receive or change branch, at a non-hardened address index, with
the path long enough to hold both. Other change raises
PSBTChangeDerivationPathError, graded an attack. The same rules cover
multisig outputs counted as spends because their cosigners differ from
the inputs' or fail to resolve.

An address index more than CHANGE_ADDRESS_INDEX_WINDOW past the largest
index our inputs spend from at that base path is flagged, not refused,
since an active wallet can trip it. The change details screen marks the
output and PSBTWarningView shows one distant address warning.

Held input findings are now raised before these rules and held output
findings after them. An input set aside by a held finding leaves its
base path out of the rules, while a held output is already a spend.
The base path rule compares base paths for equality. Its test covered
only a base path that differs from the input's in its last level, so a
prefix comparison would still pass it while accepting change at an
extra level under the input's base path. A coordinator holding the
account xpub can build that change. The test now covers both variants,
on every supported script type.
The address index window was measured from the largest non-hardened
address index among our inputs at the change's base path. An extra
input at a far index, which a coordinator can add, then widened the
window for every change output at that base path. Measured from the
smallest index, an added input can only narrow it. When every matching
input is at a hardened address index, the window is measured from 0.

An honest wallet spending an old utxo at a low index, with change far
past it, now gets the distant address warning. The user can still
continue.
Change may come back to the base path of any of our inputs, so each
input's base path has to be genuine. A segwit v0 signature (BIP-143)
commits to its own input's script and amount, not to the other
inputs'. A coordinator can add a real utxo of its own whose
witness_utxo falsely claims our key at a base path it chooses. Our
signature on the genuine input is unchanged, the transaction still
confirms, and the added input anchors change at a path the user's
wallet never scans.

On p2wpkh and p2sh-p2wpkh, the inputs this seed signs must now share
one base path unless each supplies a non_witness_utxo, which is checked
against its txid. Otherwise the parse raises
PSBTUnverifiableMixedInputBasePathsError, a Warning-grade refusal.
Taproot signatures commit to every input's script and amount, and a
legacy input must supply its previous transaction. Multisig change is
checked against the full set of cosigners. The tests that spent from
two base paths on p2wpkh now use the other script types.

Every base path comparison now goes through PSBTParser._get_base_path.
A one-level slip in one of the separate slices it replaces passed the
whole suite.

Held input findings are raised before this check too, since it reads
the same input claims. parse()'s docstring now says a held finding
waits only until a later check would rely on what it set aside.

Also rewords a few docstrings from this branch's earlier commits.
Wording only, no behavior change. The script path error, its Holds:
entry, and its View now make the input the subject: an input only lets
this seed sign through a script path spend. set_input_locking_script
and three test docstrings use plainer phrasing for our keys, inputs,
and utxos.
@newtonick

Copy link
Copy Markdown
Collaborator

Reviewed and tested on device. 081b1f4. Lots of tiny opinionated choices in this PR I agree with to help protect users. The difference between a "valid" transaction and a "safe" transaction are walked in this PR. Appreciate the work.

@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 081b1f4. Tested with testqrs.com on device.

The PSBTWarningView simplification in this PR is really neat. When I get to rebasing and addressing the review comments on #1043, I'll move the OP_RETURN burn warning onto this list as well.

Just curious if anything in particular led to 10,000 as the index window? Wallets typically scan with a gap limit of around 20, so 10000 feels a bit large lol. But I agree it's a guess either way, and the change screen shows the index regardless.

@newtonick

Copy link
Copy Markdown
Collaborator

Just curious if anything in particular led to 10,000 as the index window?

I’m curious to hear Keith’s answer as well.

When I was thinking of an index window before this PR I was thinking 100k or 1M as a hard cap. I like this solution better.

For a legitimate case, I think of a busy watch only BTCPay server that can have very large gaps. In theory the owner of a store could pull an address from BTCPay to consolidate funds.

@newtonick
newtonick merged commit 5f32176 into SeedSigner:dev Nov 13, 2026
2 checks passed
@Chaitanya-Keyal Chaitanya-Keyal moved this from 0.8.8 Needs Review to 0.8.8 Merged in @SeedSigner Development Board Nov 13, 2026
@kdmukai

kdmukai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

I’m curious to hear Keith’s answer as well.

When I was thinking of an index window before this PR I was thinking 100k or 1M as a hard cap. I like this solution better.

Notes compiled by Claude:


10,000 is a judgment call. Any fixed size is too tight for some wallets and too loose for others.

  • Public Electrum servers limit how far an ordinary wallet can rescan. Electrum-protocol wallets such as Sparrow and Electrum subscribe to one script hash per address. Fulcrum refuses subscriptions past 75,000 per IP by default, and ElectrumX throttles a session as its subscriptions grow. A gap limit of 10,000 on each branch is about 20,000 subscriptions, so change within 10,000 stays within reach of an ordinary wallet.
  • Past that, recovery takes a full node. Deriving a million scripts takes about a minute on one desktop core (measured: 66 s on a Ryzen 5 5600X, embit with libsecp256k1). Bitcoin Core's scantxoutset accepts up to 1,000,000 indices per descriptor range and checks them in one pass over the UTXO set, which its help text says "may take several minutes".

@kdmukai

kdmukai commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

(most of the above is ex post facto justification. Really 10k was picked just on gut instinct)

@jdlcdl

jdlcdl commented Nov 14, 2026 •

Copy link
Copy Markdown

post merge ACK. great additions.

btw: maybe 20k is a big gap, that the change address index is always printed on screen is very nice, I will start looking out for it.

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.

4 participants