Skip to content

[security] Check input claims against the input's committed script - #1060

Merged
newtonick merged 5 commits into
SeedSigner:devfrom
kdmukai:2026-10_psbt_input_claims
Nov 7, 2026
Merged

newtonick merged 5 commits into
SeedSigner:devfrom
kdmukai:2026-10_psbt_input_claims

Conversation

@kdmukai

@kdmukai kdmukai commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

The problem:

  • A psbt tells the signer which of its keys control each input. Currently we confirm that our seed really derives each claimed key, but not that the input's script uses that key.
  • Anyone holding the account xpub can derive our keys. So a coordinator can attach one of our real keys to someone else's input, or add a decoy key of ours to our own multisig input.
  • No funds are at risk: embit would just add a signature that could never spend that utxo. But we would accept a claim that the input itself contradicts, and which inputs are ours needs to be certain: the wrong-seed check reads it, and [security] Check change derivation paths against the inputs #1073's change path rules build on it.
  • Separately, a mild finding that might be an honest bug (a false input claim, an extra derivation path entry) currently stops the parse before the outputs are checked. Adding one to a psbt with a fake change output swaps "Likely an Attack!" for the milder "Transaction Problem". The psbt is refused either way, but with the wrong warning.

The solution:

  • Every claim of ours on an input must also be a key that the input's committed script uses. If not: "Likely an Attack!". The exception is a taproot claim we can't check yet (a key in a script tree leaf, or a psbt that leaves out the merkle root), which is set aside instead.
  • Milder findings wait until the outputs have been read, so an attack found there is the one reported.
  • Two small gaps get their own up-front refusal: a taproot input this seed could only sign through a script path (not supported yet; currently signing fails after the user reviews it), and a claim at the master key or at a one-level input path (no wallet uses these).

More precise description below by Claude, primarily intended to be consumed by other AIs


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

Psbt Without this PR With this PR
A milder finding (a false input claim, both derivation path maps, or a surplus output entry), plus a change output paying a stranger That finding's "Transaction Problem" "Likely an Attack!" for the change output
A true key of ours on an input whose script does not use it: planted on another party's input, a decoy on the user's own multisig input, or a taproot internal key that the supplied merkle root contradicts Parses PSBTInputOwnershipContradictionError
A taproot input whose only key of ours is in a script tree leaf Parses PSBTUnsupportedScriptPathError
A taproot input whose psbt leaves out the merkle root its address is built with (the only input) Parses "Seed Can't Sign" (our claim on it is set aside)
An input or change output claimed at the master key m, or an input at the one-level path m/5 Parses PSBTUnsupportedDerivationPathError
Wrong seed, plus a bad input script, a contradicted amount, or no utxo "Seed Can't Sign" That problem's own error

For the psbts that parse without this PR, embit's sign_with with the user's seed adds:

  • Planted and decoy keys: a useless signature. It is correct, but by a key the input's script does not use, so it can never help spend the utxo.
  • The contradicted internal key, the leaf-only input, and the missing merkle root: no signature, so signing fails after the user has reviewed the transaction.
  • The master key and m/5 inputs: a usable signature for a utxo that key really controls.

So no psbt in the table can move funds the user did not approve. With this PR, each is refused before review.

The wrong-seed row is a behavior change. The wrong-seed check reads which inputs are ours, which _parse_inputs now decides after #995's amount checks and #1047's script checks have run. So a wrong-seed psbt with one of those problems reports the problem: a bad script or a contradicted amount as "Likely an Attack!", and a missing utxo as "Transaction Problem".


Not covered

  • An input falsely described as controlled by one of our keys. The script check reads the input's scriptPubKey from the psbt's own utxo fields. Nothing in the parse authenticates it. [security] Verify PSBT input amounts before displaying the fee #995's txid check ties a previous transaction only to the txid that the psbt itself names. Measured at this PR's head: a made-up input paying one of our keys, with a true claim on it, parses and counts as ours, both with a witness_utxo alone and with a made-up previous transaction plus a rewritten txid.

    • The input can also be the coordinator's own real utxo, with its witness_utxo rewritten to pay one of our keys. On segwit v0 that transaction can still confirm because BIP-143 leaves the user's signature on their real input unchanged (measured: the same sighash either way). Taproot signatures commit every input's scriptPubKey and amount. A legacy input's previous transaction has to match its real txid. So neither is exposed.
    • In this PR, only the wrong-seed check reads which inputs are ours, so counting such an input as ours affects that check alone. The change path rules in [security] Check change derivation paths against the inputs #1073 also read it; that PR covers how they handle such an input.
  • Change at a one-level path. The one-level refusal covers inputs only. Change at m/5 that really pays that key parses as change (measured). Where change may go is left to [security] Check change derivation paths against the inputs #1073.


Screenshots

Three new screens. Each ends the flow with "Discard transaction".

PSBTInputOwnershipContradictionView (Dire Warning)

PSBTInputOwnershipContradictionView

PSBTUnsupportedDerivationPathView (Warning)

PSBTUnsupportedDerivationPathView

PSBTUnsupportedScriptPathView (Warning, titled with the existing translated string "Not Yet Implemented")

PSBTUnsupportedScriptPathView

Testing

  • pytest: 347 pass, with 12 new parser tests and 3 new flow tests. One existing test changes its expectation: test_a_psbt_with_no_utxos_is_rejected_rather_than_crashing keeps the inputs' claims and now expects PSBTMissingInputUtxoError instead of PSBTSeedCannotSignError (the wrong-seed behavior change above).
  • The screenshot generator passes in all 22 locales.
  • Tested on hardware with the testqrs.com tests for this PR.

Mutations: 32 deliberate breaks of the new code, each run against the full suite. 29 make at least one test fail. The three that pass, with their measured effect:

Mutation Effect
Apply the one-level refusal to outputs too Change at m/5 is refused instead of parsing. Left unpinned: change paths belong to the follow-up PR.
Let a held output still be a change candidate None: the held finding is raised either way (measured on six held-output psbts)
Let a multisig output with a surplus entry still be presumed change None, for the same reason

Other Notes

  • Deletes get_input_fingerprints, which had no callers.

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.

@kdmukai

kdmukai commented Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

testqrs.com now updated with tests for this PR.

@kdmukai
kdmukai marked this pull request as ready for review October 30, 2026 12:02
A false input claim, entries in both derivation path maps, and surplus
output entries might each be an honest bug. They are now held in one
list instead of raised where found. parse() raises the first one after
_parse_outputs, so an output contradiction found later is still the one
reported. A held input is set aside (its verified list emptied). A held
output counts as a spend without its claims being evaluated.

Input claim verification moves into _parse_inputs. The wrong-seed check
moves after it and stands aside while a finding is held. Deletes
get_input_fingerprints, which had no callers.
Re-deriving a claimed key proves our seed owns it, not that the input
spends with it. Each verified entry must now be a key the input's
committed script uses. Only the entries that pass are kept in
verified_input_derivation_paths. An entry that fails raises
PSBTInputOwnershipContradictionError.

Taproot rebuilds the address with the input's merkle root, the same
tweak embit signs with. A failing internal key claim raises the same
error when the input supplies its merkle root. It is dropped when a
taproot input omits the merkle root. A failing leaf key claim is
dropped. An input this seed can sign only through a script path holds
PSBTUnsupportedScriptPathError.
A claim of ours at the empty path (the master key), on an input or an
output, or at a one-level path on an input, is held as
PSBTUnsupportedDerivationPathError. No wallet writes an entry at these
paths, though embit would sign an input built on the master key. The
check runs after the claim loops, so a forged claim in the same input
or output is still the one reported.
@kdmukai
kdmukai force-pushed the 2026-10_psbt_input_claims branch from 04c58f6 to 865f249 Compare October 30, 2026 13:17
@kdmukai

kdmukai commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

Rebased to latest dev.

parse()'s docstring listed every held finding, far from the code that
holds each one. Each step that holds findings now ends its docstring
with a Holds: list, and parse() keeps only the principle: a milder
finding is held aside while the remaining checks run and is raised only
if they find nothing more serious.

Holding is a side effect a caller cannot see, which is why it gets a
list and the raises do not.

Drops the "see parse()" pointers to the held findings. An input whose
claims are set aside is now described as left with no verified
derivation paths rather than as "not ours".
Twelve places in the tests changed an input's scriptPubKey and then
dropped its non_witness_utxo, each with its own comment on why. The
previous transaction still pays the old scriptPubKey, and editing it to
match would change its txid, so the drop is required.
set_input_locking_script does both and explains it once.

The bare multisig test keeps its own edit: that input is not segwit, so
the helper's witness-only reasoning does not hold there.
@newtonick

Copy link
Copy Markdown
Collaborator

ACK and reviewed as of b297c86. Tested on device with testqrs.com. There was a lot more to this PR than I initially anticipated.

@kdmukai

kdmukai commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Description updated (no code changes in this PR):

  • "Not covered": the sub-bullet about the follow-up's change path rules said they can only narrow where change may go. That overstated it: an input falsely counted as ours can also add a base path that change may go to. [security] Check change derivation paths against the inputs #1073 handles that case and explains how, so the sentence now defers to it.

@newtonick
newtonick merged commit 995ce5c into SeedSigner:dev Nov 7, 2026
2 checks passed
@newtonick newtonick moved this from 0.8.8 Needs Review to 0.8.8 Merged in @SeedSigner Development Board Nov 7, 2026
@jdlcdl

jdlcdl commented Nov 14, 2026

Copy link
Copy Markdown

post-merge ACK, great additions.

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.

3 participants