Merge pull request #740 from Foundation-Devices/sft-4482-update-card-missing
What changed, and why it matters
This commit fixes a user-experience bug in the Passport hardware wallet's firmware update flow. Previously, if the user removed the microSD card while the device was reading a firmware update file, the process would crash with an unhandled error. Now the device detects the missing card, prompts the user to reinsert it, and only gives up if the user declines. It also adds a friendly error message if the file becomes unreadable for other reasons. There is no direct evidence this was exploitable to install malicious firmware or steal funds.
Treat as a routine reliability/UX fix. Review whether the original unhandled exception could have left the firmware update UI in an inconsistent state, but the patch itself is defensive and does not weaken verification. No immediate security response required.
Security signals we found
Adds exception handling for a removable-media failure during a privileged operation (firmware update)
Prevents unhandled CardMissingError from aborting the update flow abruptly
Does not alter firmware signature, timestamp, or header validation logic
Includes regression tests for missing-card and unreadable-file scenarios
Evidence from the diff
The change wraps the existing firmware-file read logic in update_firmware_flow.py with a try/except for CardMissingError and OSError. On CardMissingError it shows InsertMicroSDPage and either retries or goes back; on OSError it shows ‘Could not read firmware file’ and aborts the flow. The actual signature/timestamp/header verification logic is moved into a new check_firmware_file() method and is unchanged. New host-side unit tests verify the retry/back/error behavior. A related timestamp test is updated to target the renamed method.
Changed components
ports/stm32/boards/Passport/modules/flows/update_firmware_flow.pyports/stm32/boards/Passport/modules/tests/host/test_update_firmware_card.pyports/stm32/boards/Passport/modules/tests/test_firmware_timestamp.pyInspect captured patch +109 / −2
### ports/stm32/boards/Passport/modules/flows/update_firmware_flow.py
@@ -49,6 +49,19 @@ async def choose_file(self):
self.goto(self.show_firmware_details)
async def show_firmware_details(self):
+ from files import CardMissingError
+
+ try:
+ await self.check_firmware_file()
+ except CardMissingError:
+ # Retry this step once a card is inserted, or go back to the picker.
+ if not await InsertMicroSDPage().show():
+ self.back()
+ except OSError:
+ await ErrorPage(text='Could not read firmware file').show()
+ self.set_result(False)
+
+ async def check_firmware_file(self):
import common
with CardSlot() as card:
with open(self.update_file_path, 'rb') as fp:
### ports/stm32/boards/Passport/modules/tests/host/test_update_firmware_card.py
@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: © 2026 Foundation Devices, Inc. <hello@foundation.xyz>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Host tests: a missing card or unreadable file while showing update details."""
+
+import asyncio
+import runpy
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+
+MODULES = Path(__file__).resolve().parents[2]
+
+
+class CardMissingError(RuntimeError):
+ pass
+
+
+@pytest.fixture
+def flow(monkeypatch):
+ events = []
+ card = {'missing': True, 'insert': False}
+
+ class CardSlot:
+ def __enter__(self):
+ if card['missing']:
+ raise CardMissingError()
+ return self
+
+ def __exit__(self, *args):
+ return False
+
+ class Page:
+ def __init__(self, *args, text=None, **kwargs):
+ self.text = text if text is not None else (args[0] if args else None)
+
+ async def show(self):
+ events.append((type(self).__name__, self.text))
+ return card['insert']
+
+ pages = types.SimpleNamespace(**{name: type(name, (Page,), {}) for name in (
+ 'ErrorPage', 'ProgressPage', 'QuestionPage', 'SuccessPage', 'InsertMicroSDPage', 'InfoPage')})
+
+ class Flow:
+ def __init__(self, **kwargs):
+ pass
+
+ stubs = {
+ 'lvgl': types.SimpleNamespace(),
+ 'machine': types.SimpleNamespace(),
+ 'files': types.SimpleNamespace(CardSlot=CardSlot, CardMissingError=CardMissingError),
+ 'constants': types.SimpleNamespace(FW_HEADER_SIZE=2048, FW_MAX_SIZE=2000000),
+ 'pages': pages,
+ 'tasks': types.SimpleNamespace(verify_firmware_signature_task=None, copy_firmware_to_spi_flash_task=None),
+ 'flows': types.SimpleNamespace(Flow=Flow, FilePickerFlow=None),
+ 'utils': types.SimpleNamespace(read_user_firmware_pubkey=None, is_all_zero=None, start_task=None),
+ 'errors': types.SimpleNamespace(Error=None),
+ 'passport': types.SimpleNamespace(),
+ 'common': types.SimpleNamespace(),
+ }
+ for name, stub in stubs.items():
+ monkeypatch.setitem(sys.modules, name, stub)
+
+ flow_class = runpy.run_path(str(MODULES / 'flows/update_firmware_flow.py'))['UpdateFirmwareFlow']
+ instance = flow_class(reset_after=False)
+ instance.update_file_path = 'missing-passport.bin'
+ instance.back = lambda: events.append(('back', None))
+ instance.set_result = lambda result: events.append(('result', result))
+ instance.goto = lambda state, save_curr=True: events.append(('goto', state.__name__))
+
+ def show():
+ asyncio.run(instance.show_firmware_details())
+ return events
+
+ return types.SimpleNamespace(show=show, card=card)
+
+
+def test_missing_card_offers_insert_then_goes_back(flow):
+ assert flow.show() == [('InsertMicroSDPage', None), ('back', None)]
+
+
+def test_missing_card_retries_once_inserted(flow):
+ # Returning without a transition runs this step again.
+ flow.card['insert'] = True
+ assert flow.show() == [('InsertMicroSDPage', None)]
+
+
+def test_unreadable_file_reports_an_error(flow):
+ flow.card['missing'] = False
+ assert flow.show() == [('ErrorPage', 'Could not read firmware file'), ('result', False)]
### ports/stm32/boards/Passport/modules/tests/test_firmware_timestamp.py
@@ -218,7 +218,8 @@ def test_update_timestamp_failure_handling(tmp_path, production):
def test_header_state_failure_is_recoverable(tmp_path, monkeypatch):
source = ast.parse((BOARD / 'modules/flows/update_firmware_flow.py').read_text())
flow_class = next(node for node in source.body if isinstance(node, ast.ClassDef))
- method = next(node for node in flow_class.body if node.name == 'show_firmware_details')
+ # show_firmware_details() only adds card handling around this step.
+ method = next(node for node in flow_class.body if node.name == 'check_firmware_file')
messages, results = [], []
class ErrorPage:
@@ -245,7 +246,7 @@ def verify_header(_):
}
isolated = ast.Module(body=[method], type_ignores=[])
exec(compile(isolated, 'update_firmware_flow.py', 'exec'), namespace)
- asyncio.run(namespace['show_firmware_details'](flow))
+ asyncio.run(namespace['check_firmware_file'](flow))
assert results == [False]
assert messages == ['Firmware update cannot continue.\n\nUnable to read firmware timestamp.']
assert not hasattr(flow, 'update_header')Why this scored 34/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.