Skip to content

[security] Reject PSBTs that falsely claim this seed's ownership - #1013

Merged
newtonick merged 9 commits into
SeedSigner:devfrom
kdmukai:psbt_parser_ownership_scan
Aug 29, 2026
Merged

newtonick merged 9 commits into
SeedSigner:devfrom
kdmukai:psbt_parser_ownership_scan

Conversation

@kdmukai

@kdmukai kdmukai commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Depends on #1005

It builds directly on #1005's claimed_/verified_ naming. This is the PR that starts
filling the verified_ side.

Description by Claude, reviewed and edited by Keith:


The problem

A psbt's derivation metadata (fingerprints and paths in each input/output scope) is
written by the coordinator and was never verified against actual key material. Any
software that can send us a psbt can label any key with our fingerprint and nothing
checked the claim. A forged derivation entry on an output is exactly how fake change is
dressed up: the display counts the output as "back to your wallet" while the funds go to
the attacker.

What this PR does

parse() gains an ownership scan that runs before any transaction detail is computed: every
derivation entry naming the signing seed's fingerprint is re-derived from the seed and
compared against real key material. The scan records its results in
verified_input_derivation_paths / verified_output_derivation_paths, one entry per
scope. The entry is the derivation path the scan proved the seed owns, or None when the
seed owns nothing in that scope.

A claim that does not hold up aborts the parse and routes to a new screen:

  • False claim on an output → dire warning ("Suspicious Transaction / Likely an
    Attack!"). This is the fake-change scenario.
  • False claim on an input → plain warning ("Transaction Problem"). Inconsistent
    data rather than an attack; an input claim gains the attacker nothing. embit
    refuses to sign the same condition, so tolerating it would only defer the failure.
    Outputs are scanned first so the attack classification wins when a psbt carries both.
  • Seed owns no input at all → informational "Seed Can't Sign" screen routing back
    to seed selection (wrong seed, not an attack).

The scan's re-derivations use the parse-wide derivation cache from #1002. A test case
verifies that the whole parse derives each unique path level exactly once, so the scan
adds no meaningful cost.


Deliberate decisions, for review

  • ecdsa ownership comparison is full-key — stricter than embit. embit's sign_with
    compares x-only even for ecdsa; we compare the full serialized key. The
    parity-flipped twin of our key is not a key this seed derives, and a signature
    produced under it is unusable by any standard finalizer, so the extra strictness
    only rejects transactions that could never complete. Taproot claims compare x-only,
    as they must.
  • Fingerprint collisions are rejected like forgeries. An honest party whose master
    fingerprint collides with ours (1 in 2^32) produces a scope that is byte-for-byte
    identical to a forgery, and embit's sign_with already refuses this.
    Skip-rather-than-raise would belong upstream in embit first. The test fixture is a real
    colliding pair (two random-entropy mnemonics sharing fingerprint 11fed83f).
  • A bare master key directly in a script is deliberately unsupported. No coordinator
    produces such a psbt and the per-script-type inspection code it would require isn't
    worth the audit surface. The signability gate keys on derivation paths only.
  • Two dead inner is_change checks removed from the output loop. Inside
    if out_policy == self.policy:, the pkh and p2tr branches each ended with the same
    script comparison the outer check performs immediately afterward for every policy
    type, with nothing modifying the compared values in between. The inner copies could
    not change the result. I also verified locally, against a matrix of 112 psbt
    scenarios across all supported script types, that parse output is byte-identical
    for every accepted psbt.

Scope and follow-ups

This PR establishes ownership, nothing else. Two planned follow-ups will use this
information.

Tests

New parser suite covering the scan (forged claims on inputs/outputs, taproot and
multisig scopes, collision, collaborative-spend inputs, cache accounting) plus
flow-level routing tests for all three rejection screens; screenshot generator
includes the three new screens.


Screenshots

Information, but not a warning.
PSBTSeedCannotSignView

Input ownership claim failed. Odd / malformed psbt but not an attack.
PSBTInputOwnershipClaimFailedView

Output ownership claim failed. Fake change attack.
PSBTOutputOwnershipClaimFailedView


Additional Information

Issue identified via internal scans as well as responsibly disclosed by the Red Team 🟥.


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.

Nothing in a psbt proves the fingerprints and derivation paths it
carries, but change_data's fingerprint and derivation_path keys read
like facts -- the change details view splits one into a wallet path and
hands it straight to get_xpub. Renaming them to claimed_fingerprint and
claimed_derivation_path, along with the locals that carry them, puts the
trust boundary in the data itself rather than in the logic around it.

The class docstring now states the convention behind the prefix:
claimed_ for coordinator-supplied metadata, verified_ for what this
device proved by re-deriving from the signing seed, and the invariant
that no verified_ value comes from a claimed_ one without a derivation
in between. It also records that change_data covers self-transfers, not
just change-branch outputs. No logic changes; the two dict keys are the
only behavioral difference.
Comment thread src/seedsigner/views/psbt_views.py Resolved
Comment on lines +638 to +640
if is_taproot:
# Taproot keys are x-only
return derived_public_key.xonly() == public_key.xonly()

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.

This compares x-only for taproot, which is right. But two other places (missing fingerprint fallback) still do their own comparison with full SEC, and both feed taproot keys through it:

embit normalizes taproot keys to an even prefix when it parses them, while the BIP-32 derived key carries its real parity. Full-SEC therefore fails whenever the derived parity is odd (~50%).

No effect wherever the fingerprint is present, but on the zero-fingerprint path the fill silently doesn't happen, the scope never matches our fingerprint, and _reject_if_seed_cannot_sign reports that none of the inputs are controlled by this seed, which isn't true. This is pre-existing, but this PR is what turns it into a confident wrong statement on a new screen.

test_missing_fingerprint_handling does exercise this, it zeroes taproot_bip32_derivations across ALL_INPUTS but there's only one taproot input in the fixtures and it's at m/86h/1h/0h/0/0, which happens to derive even. Point it at /0/1 and it fails.

Threading is_taproot into _get_updated_fingerprint and delegating to seed_owns_pubkey fixes it; I tried it locally and the odd-parity case goes from PSBTSeedCannotSignError to 1 sig.

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 c9fda64

@kdmukai

kdmukai commented Aug 22, 2026

Copy link
Copy Markdown
Contributor Author

To aid on-device testing, I've updated my testqrs.com site to add psbts that exercise these new checks.

https://testqrs.com/?tx=test-fake-change-p2wpkh

To access them:

Screenshot 2026-08-22 at 8 04 59 AM
Screenshot 2026-08-22 at 8 05 30 AM

kdmukai and others added 5 commits August 22, 2026 10:15
claimed_fingerprints and claimed_derivation_paths each hold a list
(one entry per cosigner), so the singular key names misread at their
call sites. Also drop a commented-out debugging print.
Every derivation entry naming the signing seed's fingerprint is now
verified during parse() by re-deriving the key from the seed itself.
A claim that does not hold up aborts the parse before any transaction
detail is shown: a false claim on an output is classified as an attack
(fake change) and routed to a dire warning, while a false claim on an
input is reported as inconsistent data with a plain warning. A psbt
whose inputs this seed cannot sign at all is turned away to seed
selection.

The per-scope verification results are recorded in
verified_input_derivation_paths / verified_output_derivation_paths,
the ownership record later stages consume.
Co-authored-by: Chaitanya-Keyal <chaitanyakeyal@gmail.com>
@kdmukai
kdmukai force-pushed the psbt_parser_ownership_scan branch from 4dfa7ba to 5e53bdb Compare August 22, 2026 18:12
@kdmukai

kdmukai commented Aug 22, 2026

Copy link
Copy Markdown
Contributor Author

Rebased to match changes up to c7eacfb in #1005.

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

🟡 Changes recommended

Verified derivation metadata is treated as scope ownership without proving the key participates in the scope’s spending script.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds PSBT ownership verification before transaction details are calculated.

Changes:

  • Verifies claimed derivation paths against seed-derived keys.
  • Adds dedicated rejection screens and routing.
  • Expands parser, flow, and screenshot tests.
File summaries
File Description
src/seedsigner/models/psbt_parser.py Implements ownership scanning and verification errors.
src/seedsigner/views/psbt_views.py Routes failures to new informational/warning screens.
tests/test_psbt_parser.py Tests ownership verification scenarios.
tests/test_flows_psbt.py Tests failure-screen routing.
tests/psbt_testing_util.py Adds ownership-test helpers and fixtures.
tests/screenshot_generator/generator.py Registers the new screens.
Review details
  • Files reviewed: 6/6 changed files
  • Comments generated: 1
  • Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +698 to +700
# Store only the first verified path
if verified_derivation_path is None:
verified_derivation_path = derivation_path_obj.derivation

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.

Response by Claude, reviewed by me:

Confirmed the mechanics described here: the scan proves key ownership and deliberately does not check script participation, and for ECDSA inputs embit's sign_with will add a partial signature for a derivation-map entry whose key is not in the input's script (its taproot signing does check membership, so those inputs get no signature). But that signature satisfies no script, so it cannot move funds. And nothing in this PR treats a scope as the seed's on the strength of a verified path alone: change classification still requires the script rebuilt from the derived key to match the committed scriptPubKey in _parse_outputs, and the verified output paths have no other consumer in this PR. Worth noting too that this psbt shape behaves identically without this PR: embit adds the same unusable signature and the finalize flow reports the same success. The scan narrows what was already accepted; it does not create the acceptance.

Verifying script membership in the scan was considered and rejected. It would reintroduce per-script-type inspection (p2pkh, p2sh, p2wpkh, p2wsh, taproot key path plus leaves) whose only purpose is to mirror the signer, which is exactly the dense, hard-to-audit branching this parser is trying to shed. If that check is ever added, it belongs in _reject_if_seed_cannot_sign, where signability is decided, not in the scan.

What this comment did surface is that the method's name and docstrings claimed more than the code establishes. Fixed in ee1a9f5: _scan_seed_ownership is now _verify_claimed_derivation_paths, its docstring states that a verified path means the seed provably owns the named key and nothing more, and _reject_if_seed_cannot_sign now notes the deliberately omitted input-script check and why it is harmless.

A psbt carries taproot keys as bare x coordinates and embit rebuilds
them assuming even parity, so the full-key comparisons in the two
zero-fingerprint fallbacks failed whenever the seed's real key derives
with odd parity. A taproot psbt from an xpub-only coordinator was then
wrongly rejected with PSBTSeedCannotSignError about half the time.

Both fallbacks now delegate to seed_owns_pubkey, which already compares
taproot keys by their x-only representation. The regression test re-keys
the taproot fixture to an odd-parity path; the existing fixture at
m/86h/1h/0h/0/0 happens to derive even and passed by luck.

@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. My previous comments are addressed, and I've also tested this PR hands-on using testqrs.com (extremely useful btw!).

fwiw I looked a bit into copilot's finding and it's technically accurate, but it's pre-existing embit behavior, not a regression, and there's no fund-loss path as far as I can tell.

@newtonick

Copy link
Copy Markdown
Collaborator

@kdmukai #1005 has been merged, is this PR ready for review (move out of draft)?

The old name read as if the scan established ownership of the scope
itself. What it proves is narrower: the seed derives the key a scope
names at the claimed path, nothing about that key's role in the scope's
script. The new name states exactly that, and the docstrings around it
are tightened to match.

Also note on _reject_if_seed_cannot_sign that we deliberately skip
verifying that a key appears in its input's script: a key absent from
the script cannot spend the input, so nothing of this seed's is at
risk.
@kdmukai
kdmukai marked this pull request as ready for review August 24, 2026 14:13
@kdmukai

kdmukai commented Aug 24, 2026

Copy link
Copy Markdown
Contributor Author

With the slight changes in ee1a9f5 (just renaming _scan_seed_ownership to the more precise _verify_claimed_derivation_paths) I've now addressed all the review comments thus far.

I have flipped this PR to Ready for review.

@jdlcdl

jdlcdl commented Aug 24, 2026 •

Copy link
Copy Markdown

tACK at ee1a9f5 w/ latest seedsigner-os 'main'

New warning screens are very nice, as well "cannot sign" with ability to load/select another seed.
and testqrs is a gift.

The three REASON__ constants and the `reason` parameter were fixed up
front to settle a shared vocabulary before any consumer existed, on the
reasoning that one contributor owned all three prospective call sites.

No caller ever passed a reason. Routing each rejection by exception type
sends it to its own view, which leaves PSBTAddressVerificationFailedView
with two outcomes already decided by is_multisig. Later work should
introduce whatever distinctions its own copy needs rather than inherit
three unused constants.
@kdmukai

kdmukai commented Aug 25, 2026

Copy link
Copy Markdown
Contributor Author

Sorry, one more tweak.

The REASON__* constants that were added in this PR (but not yet used) anticipated work being done in upcoming stages. But right now it looks like they will be unnecessary.

So rather than add them here and then possibly / probably remove them later, better to just omit them from this PR altogether in 6d58d0a.

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

Re-ACK at 6d58d0a.

@newtonick

Copy link
Copy Markdown
Collaborator

ACK and reviewed

@newtonick
newtonick merged commit e4af6a7 into SeedSigner:dev Aug 29, 2026
2 checks passed
@newtonick newtonick moved this from 0.8.8 Needs Review to 0.8.8 Merged in @SeedSigner Development Board Aug 29, 2026
SovereignGG added a commit to SovereignGG/seedsigner that referenced this pull request Sep 3, 2026
Rebasing onto SeedSigner#1013 brought a canonical ownership check, so establish
ownership through that rather than deriving and comparing keys by hand.

Also records why this check stays necessary now that
_reject_if_seed_cannot_sign() exists: that guarantees the seed can sign
some input, which is not the same as the signing pass having added a
signature, so "already signed" is still worth asking directly rather than
inferring from the absence of a rejection.
renatoslopes pushed a commit to GRIFORTIS/3rdIteration-seedsigner that referenced this pull request Oct 9, 2026
…tCode

Brings in the 12 commits the fork was behind: kdmukai/psbt_parser_ownership_scan
(SeedSigner#1013) and kdmukai/hash_lock_dev_deps (SeedSigner#1018). The first lands directly on the
malicious-PSBT hardening merged as c2efb9c (3rdIteration#409), so most of the work here is
reconciling two overlapping sets of checks rather than resolving text.

Ownership verification, made root-mode aware
--------------------------------------------
Upstream's new scan re-derives every key whose derivation claims the signing
seed's fingerprint, and refuses the psbt when a claim does not hold up. It
assumes `self.root` is a master HDKey. This fork has three root modes: a seed's
master key, a Satochip/SeedKeeper *account-level* xpub (with root_path and
master_fingerprint alongside), and a bare WIF/BIP38 private key with no BIP32
tree at all.

Taken as merged, the card mode silently refused every psbt -- it compared
against the account key's own fingerprint, which no psbt ever names -- and the
WIF mode raised AttributeError. seed_owns_pubkey now takes a root_path offset,
_get_seed_derivation_path takes the fingerprint to match rather than reading it
off the root, and both the scan and the cannot-sign check are gated on the
existing can_verify_derivations flag (moved up into parse(), since the scan runs
before _parse_inputs). All three modes verified against a live parse.

Upstream's stricter key comparison is adopted wholesale: x-only for taproot,
full SEC for ecdsa. _verify_derivation now routes through seed_owns_pubkey and
keeps this fork's _input_commits_to_key check on top. The two are complementary
-- upstream proves the seed derives the key, the fork proves the utxo commits
to it.

One rejection taxonomy, upstream's screens
------------------------------------------
Upstream added PSBTVerificationError and three subclasses beside this fork's
InvalidPSBTError/RejectCode. Rather than carry two mechanisms, the three
exceptions become three RejectCodes (FORGED_OUTPUT_OWNERSHIP,
FORGED_INPUT_OWNERSHIP, SEED_CANNOT_SIGN), keeping upstream's reasoning as
comments on each.

Upstream's *routing* is the better half and is generalized instead: refusals now
redirect to a View rather than rendering inline in PSBTOverviewView, driven by a
REJECT_PRESENTATION table keyed on RejectCode. Existing codes keep today's
generic "Invalid PSBT" screen by default; the three new ones get upstream's
severity, prose, and exit routes verbatim, including SEED_CANNOT_SIGN's unique
disposition of keeping the psbt and returning to seed selection. Upstream's
three View names survive as thin subclasses, so its flow tests and screenshot
configs work unchanged. Card signing is routed through the same table.

Requirements: hash-locking deferred
-----------------------------------
requirements.txt and tests/requirements.txt keep the fork's pins, and the CI
workflow keeps its split pip invocations (upstream's single-invocation line
auto-merged silently and would have failed on the first run, since this fork's
l10n requirements are hash-locked while requirements.txt is not). specter-card
is a git+ URL, which pip's hash-checking mode cannot verify at all; hash-locking
is blocked on republishing it as an archive. Noted in the file.

Behaviour change worth flagging
-------------------------------
The ownership scan runs before _parse_inputs, so a psbt with no seed-owned input
derivation now reports SEED_CANNOT_SIGN rather than a downstream code. One suite
vector moved: test_withholding_input_derivations_is_rejected expected
UNREACHABLE_CHANGE_PATH and now gets SEED_CANNOT_SIGN. The invariant it protects
is unchanged (the psbt is refused, never displayed) and the new diagnosis is the
more accurate of the two.

Two upstream test fixtures rewrote witness_utxo.script_pubkey while leaving
non_witness_utxo describing the original script -- the BIP-143 amount-binding
shape this fork refuses. Both now drop non_witness_utxo, which is what the
payjoin and taproot inputs they model actually look like.

Hardware coverage
-----------------
tests/test_flows_smartcard_hardware.py gains TestSatochipPSBTSigningFlows and
TestKeycardPSBTSigningFlows: seven tests per card covering the account-xpub root
mode end to end, from "the parser is genuinely in card mode" through the forged
input and output claims to a signature produced by the real applet and verified
against the key the parser said the card owns. The account-xpub mode's failure
mode is to refuse everything, which resembles a working refusal -- only a real
card separates the two.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@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.

5 participants