feat: compose session source backup io

Author: VincenzoImp

README.md

@@ -128,8 +128,11 @@ hardware readiness can differ, final vault behavior must converge.
   `nsec`-equivalent sources in the same RAM-only import/review/keyring
   boundary. Host-core now also models the separate danger-zone backup review
   that can reveal BIP-39 words/SeedQR or NIP-19 `nsec` recovery payloads only
-  after final-page local approval. Hardware RNG wiring, physical backup
-  display/output acceptance, and physical acceptance remain pending.
+  after final-page local approval. A host-core backup/output harness displays
+  bounded danger-zone frames before local button reads and emits the recovery
+  payload to an injected output sink only after final-page approval. Hardware
+  RNG wiring, physical backup display/output acceptance, and physical
+  acceptance remain pending.
 - Host-core QR response-envelope encoding for already-produced response JSON.
   Static `nsealr1:` and animated `nsealr1a:` output match the shared signed
   response vector. A host-core response-display harness now chooses static

docs/architecture.md

@@ -161,6 +161,11 @@ The first firmware foundation is host-buildable C++ under
   RAM-only QR-vault source and reveals BIP-39 words/SeedQR or NIP-19 `nsec`
   payloads only after final-page local approval. It is a recovery ceremony,
   not import approval, not signing approval, and not persistent storage.
+  `run_session_source_backup_io_flow` is the future adapter-facing boundary:
+  it renders bounded backup review frames before every local button read and
+  emits the recovery payload to an injected output sink only after final-page
+  approval. Rejection, early approval, and bounded non-terminal button streams
+  emit nothing.
 - `session_source_qr`: normalizes decoded QR session-source inputs for future
   camera adapters. It maps canonical NIP-19 `nsec`, plain BIP-39 English
   mnemonic QR text, SeedSigner Standard SeedQR digit streams, and CompactSeedQR

docs/roadmap.md

@@ -719,6 +719,14 @@ reaches the final page and is approved. Hardware RNG wiring, physical backup
 display/output acceptance, response QR output, reset-loss evidence, and real
 signing remain pending.
 
+Status note, 2026-05-20: the same backup/export ceremony now has a host-core
+display/button/output harness for future ESP32 QR vault adapters. It renders
+bounded danger-zone review frames before each local button read and emits the
+recovery payload to an injected output sink only after final-page approval.
+Rejection, early approval, and bounded non-terminal button streams emit
+nothing. This is not physical display/output acceptance, persistence, policy
+automation, or signing.
+
 Status note, 2026-05-19: host-core now has a decoded session-source QR parser
 for future ESP32 QR vault camera adapters. Canonical NIP-19 `nsec`, plain
 BIP-39 English mnemonic QR text, SeedSigner Standard SeedQR digit streams, and

docs/testing.md

@@ -132,6 +132,11 @@ tests with strict C++ warnings.
   SeedQR, and CompactSeedQR inputs load the RAM-only keyring only after local
   import-review final-page approval, while rejection and invalid decoded QR
   inputs leave the keyring empty.
+- Host-core session-source backup/output tests prove bounded danger-zone
+  review frames are displayed before local button reads, approved flows emit
+  the BIP-39/SeedQR or NIP-19 `nsec` recovery payload only after final-page
+  approval, and rejection, early approval, or bounded non-terminal button
+  streams emit nothing.
 - Host-core session-account selection tests prove an ESP32 QR vault account
   descriptor binds a RAM-only BIP-39 or standalone `nsec` source to a public
   signer identity used by trusted review, while rejecting wrong routes,

firmware/host_core/include/nsealr/session_source_backup.hpp

@@ -6,6 +6,7 @@
 #include <string>
 #include <vector>
 
+#include "nsealr/review_display.hpp"
 #include "nsealr/review_controls.hpp"
 #include "nsealr/session_keyring.hpp"
 #include "nsealr/trusted_review.hpp"
@@ -46,11 +47,25 @@ struct SessionSourceBackupFlowResult {
     std::vector<SessionSourceBackupTranscriptStep> transcript;
 };
 
+class SessionSourceBackupIo {
+public:
+    virtual ~SessionSourceBackupIo() = default;
+
+    virtual void show_backup_review_frame(const ReviewDisplayFrame& frame) = 0;
+    virtual ReviewButton read_backup_review_button() = 0;
+    virtual void emit_backup_payload(const SessionSourceBackupPayload& payload) = 0;
+};
+
 [[nodiscard]] SessionSourceBackupPayload session_source_backup_payload(const SessionKeySource& source);
 [[nodiscard]] SessionSourceBackupReview build_session_source_backup_review(const SessionKeySource& source);
 [[nodiscard]] SessionSourceBackupFlowResult run_session_source_backup_flow(
     const SessionKeySource& source,
     const std::vector<ReviewButton>& buttons,
     std::size_t max_button_steps = 32U);
+[[nodiscard]] SessionSourceBackupFlowResult run_session_source_backup_io_flow(
+    const SessionKeySource& source,
+    SessionSourceBackupIo& io,
+    ReviewDisplayLimits limits = {},
+    std::size_t max_button_steps = 32U);
 
 }  // namespace nsealr

firmware/host_core/src/session_source_backup.cpp

@@ -2,6 +2,8 @@
 
 #include <iomanip>
 #include <sstream>
+#include <string_view>
+#include <utility>
 
 #include "nsealr/bip39_english.hpp"
 #include "nsealr/nip19_nsec.hpp"
@@ -75,6 +77,21 @@ std::string backup_approval_digest(
     return sha256_hex(material);
 }
 
+ReviewPage backup_review_page_for_display(const TrustedReviewPage& page) {
+    std::vector<std::string_view> lines;
+    lines.reserve(page.lines.size());
+    for (const std::string& line : page.lines) {
+        lines.push_back(line);
+    }
+    return ReviewPage{
+        page.title,
+        std::move(lines),
+        page.action,
+        page.page_indicator,
+        page.body_line_styles,
+    };
+}
+
 }  // namespace
 
 SessionSourceBackupPayload session_source_backup_payload(const SessionKeySource& source) {
@@ -180,4 +197,46 @@ SessionSourceBackupFlowResult run_session_source_backup_flow(
     throw SessionSourceBackupError("session source backup review did not reach approval or rejection");
 }
 
+SessionSourceBackupFlowResult run_session_source_backup_io_flow(
+    const SessionKeySource& source,
+    SessionSourceBackupIo& io,
+    ReviewDisplayLimits limits,
+    std::size_t max_button_steps) {
+    if (max_button_steps == 0U) {
+        throw SessionSourceBackupError("session source backup flow max button steps must be positive");
+    }
+
+    SessionSourceBackupFlowResult result;
+    result.review = build_session_source_backup_review(source);
+    ReviewControlSession controls(result.review.pages.size());
+
+    for (std::size_t step_count = 0; step_count < max_button_steps; ++step_count) {
+        const std::size_t page_index = controls.current_page_index();
+        const ReviewPage page = backup_review_page_for_display(result.review.pages.at(page_index));
+        io.show_backup_review_frame(render_review_page(page, page_index, result.review.pages.size(), limits));
+
+        const ReviewButton button = io.read_backup_review_button();
+        const std::optional<bool> decision = controls.handle_button(button);
+        const bool revealed = decision.has_value() && *decision;
+        result.transcript.push_back(SessionSourceBackupTranscriptStep{
+            page_index,
+            button,
+            decision,
+            revealed,
+        });
+
+        if (decision.has_value()) {
+            result.approved = *decision;
+            result.revealed = revealed;
+            if (revealed) {
+                result.backup_payload = session_source_backup_payload(source);
+                io.emit_backup_payload(*result.backup_payload);
+            }
+            return result;
+        }
+    }
+
+    throw SessionSourceBackupError("session source backup review exceeded max button steps");
+}
+
 }  // namespace nsealr

firmware/host_core/tests/test_host_core.cpp

@@ -316,6 +316,37 @@ class RecordingQrResponseDisplayIo : public nsealr::QrResponseDisplayIo {
     std::vector<nsealr::QrResponseDisplayFrame> frames;
 };
 
+class RecordingSessionSourceBackupIo : public nsealr::SessionSourceBackupIo {
+public:
+    explicit RecordingSessionSourceBackupIo(std::vector<nsealr::ReviewButton> buttons)
+        : buttons_(std::move(buttons)) {}
+
+    void show_backup_review_frame(const nsealr::ReviewDisplayFrame& frame) override {
+        frames.push_back(frame);
+        events.push_back("frame:" + frame.title);
+    }
+
+    nsealr::ReviewButton read_backup_review_button() override {
+        assert(!buttons_.empty());
+        const nsealr::ReviewButton button = buttons_.front();
+        buttons_.erase(buttons_.begin());
+        events.push_back("button");
+        return button;
+    }
+
+    void emit_backup_payload(const nsealr::SessionSourceBackupPayload& payload) override {
+        payloads.push_back(payload);
+        events.push_back("payload");
+    }
+
+    std::vector<nsealr::ReviewDisplayFrame> frames;
+    std::vector<nsealr::SessionSourceBackupPayload> payloads;
+    std::vector<std::string> events;
+
+private:
+    std::vector<nsealr::ReviewButton> buttons_;
+};
+
 class NextOnlyQrReviewIo : public nsealr::QrReviewIo {
 public:
     std::string scan_request_qr() override {
@@ -1081,6 +1112,65 @@ void test_session_source_backup_flow_reveals_only_after_local_approval() {
     });
 }
 
+void test_session_source_backup_io_reveals_only_after_displayed_approval() {
+    nsealr::StatelessSessionKeyring keyring;
+    keyring.add_nsec("nsec test vector", nsealr::decode_nsec_secret_key(nsealr::test_vectors::kNip19NsecTestKey1));
+    RecordingSessionSourceBackupIo io{{nsealr::ReviewButton::Next, nsealr::ReviewButton::Approve}};
+
+    const nsealr::SessionSourceBackupFlowResult result =
+        nsealr::run_session_source_backup_io_flow(keyring.source_at(0), io);
+
+    assert(result.approved);
+    assert(result.revealed);
+    assert(result.backup_payload.has_value());
+    assert(result.backup_payload->nsec == std::string(nsealr::test_vectors::kNip19NsecTestKey1));
+    assert(io.payloads.size() == 1U);
+    assert(io.payloads[0].nsec == std::string(nsealr::test_vectors::kNip19NsecTestKey1));
+    assert(io.frames.size() == 2U);
+    assert(io.frames[0].title == "Backup source");
+    assert(io.frames[0].page_indicator == "Page 1/2");
+    assert(lines_contain(io.frames[0].body_lines, "Danger: secret export"));
+    assert(!lines_contain(io.frames[0].body_lines, nsealr::test_vectors::kNip19NsecTestKey1));
+    assert(!lines_contain(io.frames[0].body_lines, nsealr::test_vectors::kNip19NsecTestKey1SecretKey));
+    assert(io.frames[1].title == "Show secret?");
+    assert(io.frames[1].page_indicator == "Page 2/2");
+    assert((io.events == std::vector<std::string>{
+        "frame:Backup source",
+        "button",
+        "frame:Show secret?",
+        "button",
+        "payload",
+    }));
+}
+
+void test_session_source_backup_io_rejection_or_timeout_does_not_emit_payload() {
+    nsealr::StatelessSessionKeyring keyring;
+    keyring.add_nsec("nsec test vector", nsealr::decode_nsec_secret_key(nsealr::test_vectors::kNip19NsecTestKey1));
+
+    RecordingSessionSourceBackupIo rejected_io{{nsealr::ReviewButton::Reject}};
+    const nsealr::SessionSourceBackupFlowResult rejected =
+        nsealr::run_session_source_backup_io_flow(keyring.source_at(0), rejected_io);
+    assert(!rejected.approved);
+    assert(!rejected.revealed);
+    assert(!rejected.backup_payload.has_value());
+    assert(rejected_io.payloads.empty());
+    assert(rejected_io.frames.size() == 1U);
+
+    RecordingSessionSourceBackupIo timeout_io{{nsealr::ReviewButton::Next, nsealr::ReviewButton::Back}};
+    expect_throw("max button steps", [&] {
+        (void)nsealr::run_session_source_backup_io_flow(keyring.source_at(0), timeout_io, {}, 1U);
+    });
+    assert(timeout_io.payloads.empty());
+    assert(timeout_io.frames.size() == 1U);
+
+    RecordingSessionSourceBackupIo early_approval_io{{nsealr::ReviewButton::Approve}};
+    expect_throw("approval requires viewing every review page", [&] {
+        (void)nsealr::run_session_source_backup_io_flow(keyring.source_at(0), early_approval_io);
+    });
+    assert(early_approval_io.payloads.empty());
+    assert(early_approval_io.frames.size() == 1U);
+}
+
 void test_policy_change_review_matches_shared_vector() {
     const nsealr::test_vectors::PolicyChangeReviewVector vector =
         policy_change_review_vector_by_name("esp32-usb-enable-kind-1-automation");
@@ -3319,6 +3409,8 @@ int main() {
     test_session_source_backup_review_matches_shared_danger_zone_vectors();
     test_session_source_backup_payload_matches_shared_secret_payloads();
     test_session_source_backup_flow_reveals_only_after_local_approval();
+    test_session_source_backup_io_reveals_only_after_displayed_approval();
+    test_session_source_backup_io_rejection_or_timeout_does_not_emit_payload();
     test_policy_change_review_matches_shared_vector();
     test_policy_change_review_flow_requires_device_approval();
     test_policy_change_review_rejects_companion_authority_or_secret_material();