Skip to content

Merge upstream/dev: PSBT ownership scan, folded into the fork's RejectCode - #433

Merged
3rdIteration merged 15 commits into
devfrom
merge-upstream-psbt-ownership-scan
Sep 5, 2026
Merged

3rdIteration merged 15 commits into
devfrom
merge-upstream-psbt-ownership-scan

Conversation

@3rdIteration

Copy link
Copy Markdown
Owner

Brings the fork level with SeedSigner/seedsigner dev (12 commits behind, merge base d70b322f): 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 c2efb9ca (#409), so most of the work 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, card mode silently refused every psbt — it compared against the account key's own fingerprint, which no psbt ever names — and WIF mode raised AttributeError. Both fail closed, so the failure resembles a working refusal.

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 new checks are gated on the existing can_verify_derivations flag (moved up into parse(), since the scan runs before _parse_inputs).

Upstream's stricter key comparison is adopted wholesale: x-only for taproot, full SEC for ecdsa. _verify_derivation 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 routes 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 install 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, and pip demands hashes for everything in an invocation.

specter-card is a git+ URL, which pip's hash-checking mode cannot verify at all, so hash-locking is blocked on republishing it as an archive. Noted in the file. Pillow and qrcode are also deliberately kept divergent from upstream.

Behaviour change worth reviewing

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.

Running these against a reader and JavaCard exposed six defects in the fixtures, all now fixed:

  • Stale card sessions. Running a flow hands the card to init_satochip, which parks its own connector on the controller, leaving the class's cached connector holding a torn-down session. Every direct card access now starts fresh.
  • Installing over a live applet. install_capfile skips a package already on the card, so each run inherited the previous run's PIN and key state. _reinstall_blank deletes first, so install → initialise → test → uninstall means what it says.
  • Splitting provisioning from seeding. card_setup leaves its own session authenticated and accepts LOAD KEY; a connector built afterwards against the same set-up card comes back reduced and refuses it with 0x6985. Both cards now provision and seed on one session.
  • Unchecked import status word. card_bip32_import_seed reports failure in its status word rather than by raising, so an unchecked call looked like success and surfaced later as an unexplained 0x6985 on every derivation. Now checked.
  • The Keycard button was never offered. PSBTSelectSeedView gates each card on its own support setting; Satochip's defaults enabled, Keycard's does not.
  • Ordering collided across classes. pytest-order sorts globally, and each applet lifecycle is a class-scoped fixture, so sharing an order number meant one class installing and deleting its applet out from under another's tests. Each class now carries its own number, keeping its lifecycle contiguous with definition order preserved inside.

Verification

  • tests/test_flows_smartcard_hardware.py — 19/19 against a real reader and JavaCard, both card signing modes end to end alongside the pre-existing SeedKeeper save and Satochip import flows. Skips cleanly with no card present.
  • 428 desktop PSBT tests (test_psbt_parser, test_psbt_refusal_screens, test_psbt_test_suite, test_no_undefined_names) and 19 flow/card-signer tests pass.
  • Full suite: 1144 passed, 151 skipped. The one failure, test_pysatochip_contract.py::test_real_connector_has_satodime_ndef_v2, is pre-existing and environmental — the globally installed pysatochip lacks card_get_ndef_v2, while requirements.txt pins the fork archive that has it.

🤖 Generated with Claude Code

kdmukai and others added 15 commits August 22, 2026 07:11
Cover requirements.txt, tests/requirements.txt, and
requirements-raspi.txt like the l10n pins: every entry now carries the
sha256 of every published file for its release, so pip refuses any
unverified artifact.

Hash-checking mode can't verify git checkouts, so the pyzbar and
urtypes deps become commit-pinned GitHub archive tarballs. The mode
also demands pins for everything in the invocation, so pytest's
transitive deps are pinned too, and coverage is pinned as
coverage[toml]: older pips (e.g. the docker dev image's) won't accept
a plain pin as satisfying pytest-cov's extra-qualified dependency.
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>
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.
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.
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.
[security] Hash-lock the local dev pip requirements pins
…_scan

[security] Reject PSBTs that falsely claim this seed's ownership
…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 (#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>
Five defects the first run against a live reader and JavaCard exposed.

Stale card sessions. Running a flow hands the card to init_satochip, which
builds its own connector and parks it on the controller, leaving this class's
cached connector holding a session the card has already torn down. The next
direct call failed with a bare 0x6985 that named nothing about the real problem.
Every direct card access now starts a new session.

Installing over a live applet. install_capfile skips load and install for a
package already on the card, so each run inherited the previous run's PIN and
key state: provisioning short-circuited on setup_done, the expected PIN never
matched, and the seed import was refused. _reinstall_blank deletes first, so
"install, initialise, test, uninstall" means what it says.

Seeding on the provisioning session. Immediately after card_setup, the applet
accepts a LOAD KEY on the same session and reports success, but the key does not
stick -- the next status read still says no key and every later derivation fails
with 0x6985. The import now runs on a session of its own, and the status is
re-read afterwards so a silent no-op fails loudly at the fixture instead of
surfacing as seven unrelated test failures.

The Keycard button was never offered. PSBTSelectSeedView gates each card on its
own support setting; Satochip's defaults to enabled and Keycard's does not, so
the menu had no Keycard button to select.

Ordering collided across classes. pytest-order sorts globally rather than per
class, and each applet lifecycle is a class-scoped fixture, so sharing an order
number with another class meant one class installing and deleting its applet out
from under another's tests. Each class now carries its own order number, keeping
its install/initialise/test/uninstall contiguous while tests within it run in
definition order. The number lives on the concrete subclass because a marker
applied in the shared base binds at definition time and every subclass would
inherit the same value.

Satochip passes 9/9 in a full-module run against the card, PSBT signing and the
pre-existing import-seed flows alike.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Keycard applet refused every seed import with 0x6985, and the diagnosis was
wrong twice before the status word was actually read.

card_bip32_import_seed reports failure in its status word rather than by
raising, so the unchecked call looked like a success. The first guess -- that
the key "did not stick" and needed a fresh session -- had it exactly backwards:
card_setup leaves the session that ran it authenticated, card_get_status there
returns the applet's full native record, and LOAD KEY is accepted. A connector
built afterwards against the same, now set-up card comes back reduced (status
answers with a four-field fallback instead of the native record) and the applet
refuses LOAD KEY. Splitting provisioning and seeding across two connectors is
what broke it.

So provisioning and seeding are now one step, on one session, for both cards,
and the import's status word is checked rather than assumed. A refusal names
itself instead of surfacing later as an unexplained 0x6985 on every derivation.

The whole module now passes against a real reader and JavaCard: 19/19, covering
both card signing modes end to end alongside the pre-existing SeedKeeper save
and Satochip import flows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@3rdIteration
3rdIteration merged commit 01aa191 into dev Sep 5, 2026
31 checks passed
@3rdIteration
3rdIteration deleted the merge-upstream-psbt-ownership-scan branch September 5, 2026 16:52
@3rdIteration
3rdIteration restored the merge-upstream-psbt-ownership-scan branch September 5, 2026 17:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants