Merge pull request #739 from Foundation-Devices/sft-8559-psbt-file-errors
What changed, and why it matters
This update fixes a bug where the Passport hardware wallet could freeze (hang) when reading a malformed or unreadable PSBT transaction file from a microSD card. Now the device reports a clear error instead of getting stuck, so users know something went wrong and can try again.
Treat as a low-severity reliability/DoS fix. Review whether any other async tasks that wait on on_done() have similar unhandled-exception hang paths. No immediate incident response required.
Security signals we found
Denial-of-service / UI hang on malformed input now returns an error
Unhandled exception path now caught and reported instead of leaving task unresolved
Missing microSD card case explicitly reported
Unrecognized PSBT encoding now explicitly rejected with PSBT_INVALID
Evidence from the diff
The commit refactors copy_psbt_file_to_external_flash_task() so that all outcomes of copy_psbt_file() are funneled through a single on_done() callback. Previously, malformed PSBT files (unrecognized encoding, bad hex/base64, empty files, etc.) or unexpected exceptions could leave the caller’s spinner waiting forever because on_done() was not always reached. The patch adds a top-level try/except that maps CardMissingError to Error.MICROSD_CARD_MISSING and any other exception to Error.PSBT_INVALID, and adds an else branch that returns Error.PSBT_INVALID when the file’s encoding cannot be determined. A host-side test file is added to exercise these paths.
Changed components
ports/stm32/boards/Passport/modules/tasks/copy_psbt_file_to_external_flash_task.pyPSBT file import flow from microSD cardInspect captured patch +144 / −6
### ports/stm32/boards/Passport/modules/tasks/copy_psbt_file_to_external_flash_task.py
@@ -13,8 +13,23 @@
async def copy_psbt_file_to_external_flash_task(on_done, on_progress, filename, offset):
+ from errors import Error
+ from files import CardMissingError
+
+ # Report exactly once, whatever the file holds: the caller waits on a
+ # spinner until on_done() is called.
+ try:
+ result = await copy_psbt_file(filename, offset)
+ except CardMissingError:
+ result = (0, None, Error.MICROSD_CARD_MISSING)
+ except Exception:
+ result = (0, None, Error.PSBT_INVALID)
+
+ await on_done(*result)
+
+
+async def copy_psbt_file(filename, offset):
# sign a PSBT file found on a microSD card
- from passport import mem
from sffile import SFFile
from errors import Error
from files import CardSlot
@@ -35,8 +50,7 @@ async def copy_psbt_file_to_external_flash_task(on_done, on_progress, filename,
fd.seek(0)
if psbt_len > MAX_TXN_LEN:
- await on_done(0, None, Error.PSBT_TOO_LARGE)
- return
+ return (0, None, Error.PSBT_TOO_LARGE)
# determine encoding used, although we prefer binary
taste = fd.read(10)
@@ -55,6 +69,8 @@ def output_encoder(x):
decoder = Base64Streamer()
output_encoder = Base64Writer
psbt_len = (psbt_len * 3 // 4) + 10
+ else:
+ return (0, None, Error.PSBT_INVALID)
total = 0
with SFFile(offset, max_size=psbt_len) as out:
@@ -84,7 +100,6 @@ def output_encoder(x):
# Might have been whitespace inflating initial estimate of PSBT size
if total > psbt_len:
- await on_done(0, output_encoder, Error.PSBT_INVALID)
- return
+ return (0, output_encoder, Error.PSBT_INVALID)
- await on_done(psbt_len, output_encoder, None)
+ return (psbt_len, output_encoder, None)
### ports/stm32/boards/Passport/modules/tests/host/test_psbt_file_copy.py
@@ -0,0 +1,123 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Host tests: copying a PSBT file from microSD always reports a result."""
+
+import asyncio
+import runpy
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+
+MODULES = Path(__file__).resolve().parents[2]
+PSBT = b'psbt\xff' + bytes(range(40))
+
+
+class CardMissingError(RuntimeError):
+ pass
+
+
+class Error:
+ PSBT_TOO_LARGE = 'too large'
+ PSBT_INVALID = 'invalid'
+ MICROSD_CARD_MISSING = 'card missing'
+
+
+class BadDecoder:
+ def more(self, data):
+ raise ValueError('bad encoding')
+
+
+@pytest.fixture
+def task(monkeypatch):
+ written = bytearray()
+ card = {'missing': False}
+
+ class CardSlot:
+ def __enter__(self):
+ if card['missing']:
+ raise CardMissingError()
+ return self
+
+ def __exit__(self, *args):
+ return False
+
+ class SFFile:
+ def __init__(self, offset, max_size):
+ pass
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *args):
+ return False
+
+ async def erase(self):
+ pass
+
+ def write(self, data):
+ written.extend(data)
+
+ stubs = {
+ 'public_constants': types.SimpleNamespace(MAX_TXN_LEN=1024),
+ 'errors': types.SimpleNamespace(Error=Error),
+ 'files': types.SimpleNamespace(CardSlot=CardSlot, CardMissingError=CardMissingError),
+ 'sffile': types.SimpleNamespace(SFFile=SFFile),
+ 'utils': types.SimpleNamespace(HexStreamer=BadDecoder, Base64Streamer=BadDecoder,
+ HexWriter='hex', Base64Writer='base64'),
+ }
+ for name, stub in stubs.items():
+ monkeypatch.setitem(sys.modules, name, stub)
+
+ copy = runpy.run_path(str(MODULES / 'tasks/copy_psbt_file_to_external_flash_task.py'))[
+ 'copy_psbt_file_to_external_flash_task']
+
+ def run(path):
+ results = []
+
+ async def on_done(*result):
+ results.append(result)
+
+ asyncio.run(copy(on_done, None, str(path), 0))
+ return results
+
+ return types.SimpleNamespace(run=run, written=written, card=card)
+
+
+@pytest.mark.parametrize('contents', [
+ b'', # empty file
+ b'\xef\xbb\xbf' + PSBT, # leading BOM
+ b' ' + PSBT, # leading whitespace
+ b'not a psbt at all',
+ b'70736274ff' + b'zz' * 20, # hex prefix, then bad hex
+ b'cHNidP' + b'!' * 20, # base64 prefix, then bad base64
+])
+def test_unreadable_file_is_reported_invalid(task, tmp_path, contents):
+ path = tmp_path / 'tx.psbt'
+ path.write_bytes(contents)
+ assert task.run(path) == [(0, None, Error.PSBT_INVALID)]
+
+
+def test_missing_card_is_reported(task, tmp_path):
+ path = tmp_path / 'tx.psbt'
+ path.write_bytes(PSBT)
+ task.card['missing'] = True
+ assert task.run(path) == [(0, None, Error.MICROSD_CARD_MISSING)]
+
+
+def test_oversized_file_is_reported(task, tmp_path):
+ path = tmp_path / 'tx.psbt'
+ path.write_bytes(PSBT + bytes(2048))
+ assert task.run(path) == [(0, None, Error.PSBT_TOO_LARGE)]
+
+
+def test_binary_psbt_is_copied(task, tmp_path):
+ path = tmp_path / 'tx.psbt'
+ path.write_bytes(PSBT)
+ [(length, encoder, error)] = task.run(path)
+ assert (length, error) == (len(PSBT), None)
+ assert encoder(b'x') == b'x'
+ assert bytes(task.written) == PSBTWhy this scored 48/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.