ESP32_Serial_Swiss_Army_Knife/docs/roadmap.md

Implementation roadmap

This document tracks the implementation and hardware-validation plan for the ESP32 Serial Swiss Army Knife. It describes intended sequencing rather than a release schedule. A phase is complete only when its implementation, documentation, build validation, and relevant hardware tests have passed.

Status legend

• Complete — implemented and validated on the target hardware.
• In progress — implementation or validation is actively underway, but the overall phase is not complete.
• Implemented; validation pending — code is present and builds, but the current implementation still needs the listed hardware checks.
• Planned — accepted project direction, not yet implemented.
• Under evaluation — useful candidate whose feasibility, security, or resource cost must be measured before it becomes a commitment.

Project-wide design constraints

These constraints apply across all phases:

• UART0 remains the trusted physical administration and recovery console.
• UART1 and the MAX3243 provide the single physical RS-232 data port.
• All serial transports use the central session broker: one writer, multiple observers.
• A slow or failed client must not block UART reception or unrelated clients.
• Serial data paths remain binary-transparent; transports must not reserve in-band control sequences.
• Network serial access must be authenticated and encrypted. No unauthenticated plaintext TCP serial service is planned.
• Secrets must not be exposed by routine status output, command completion, or logs.
• Resource use must remain bounded and observable on the ESP32-S3 N16R8 target.
• New work must preserve USB CDC and UART0 recovery when Wi-Fi or a network service fails.
• Project code remains GPL-3.0-only; third-party license notices and compatibility must be preserved.

Phase overview

Phase	Scope	Status
0	RS-232 hardware characterization and diagnostics	Complete
1	Persistent UART1 serial-service foundation	Complete
2	Transport-neutral session broker	Complete
3	Native USB CDC-ACM serial transport	Complete
4	Wi-Fi station/AP foundation and network diagnostics	Complete
5A	Authenticated HTTPS administration foundation	Complete
5B	Offline xterm.js WebSocket serial terminal	Complete
6	Authenticated SSH serial transport	Complete
7	Local display and button interface	Complete
8	Role-based users and administrative access	Complete (8D.22 accepted 2026-09-13)
9	Security and production hardening	In progress (9A–9C implemented; combined phase validation deferred)
10	Authenticated, rollback-capable OTA	Planned
11	BLE serial transport and provisioning evaluation	Planned
12	Advanced network integration	Under evaluation
13	Optional filesystem-backed features	Under evaluation

Completed phases

Phase 0 — RS-232 hardware characterization

Implemented and hardware-validated:

• Central board pin profile for the ESP32-S3 N16R8 and MAX3243 breakout.
• MAX3243 enable, static driver, receiver, valid-voltage, and modem-signal checks.
• UART loopback across supported framing and baud-rate combinations.
• Hardware CTS transmit gating and RTS receive-backpressure tests.
• Exclusive RS-232 port ownership and fault-safe cleanup.
• RGB status indication for diagnostic state.
• Phase 0 hardware diagnostics, including signal status, are isolated under the debug CLI submenu.

Detailed procedures are in Electrical tests and Hardware wiring.

Phase 1 — Serial-service foundation

Implemented and hardware-validated:

• Persistent, versioned UART configuration with safe defaults.
• UART1 lifecycle management and exclusive ownership.
• Nonblocking RX and TX software streams.
• Baud rate, data bits, parity, stop bits, RTS/CTS, DTR policy, and RTS threshold controls.
• Runtime counters and safe restart after working-configuration changes.
• Explicit save/load/default/reset behavior; edits are not silently persisted.

Phase 2 — Session broker

Implemented and hardware-validated:

• Up to eight generation-safe broker clients.
• Exactly one writer lease with multiple observers.
• Bounded per-client output and event queues.
• Slow-observer isolation and drop accounting.
• Writer grant, release, denial, revocation, and forced administrative reassignment.
• DTR on-connect integration.
• Partial-transfer and retryable no-progress semantics for transports.
• Broker payload storage placed preferentially in PSRAM while FreeRTOS control structures remain in internal RAM.

Phase 3 — Native USB CDC-ACM

Implemented and hardware-validated:

• Native ESP32-S3 USB CDC-ACM serial transport.
• Automatic broker connection when the host opens the port with DTR asserted.
• Opportunistic writer acquisition with observer fallback.
• Binary-transparent bidirectional serial data.
• Host line-coding visibility for diagnostics; UART1 remains under explicit serial configuration control.
• Disconnect cleanup, bounded buffering, counters, and UART0 lifecycle controls.

Phase 4 — Wi-Fi foundation

Implemented and hardware-validated:

• Four persistent station profiles with priority ordering.
• WPA2/WPA3 mixed mode and WPA3-SAE-required mode.
• Explicit no-echo secret entry through UART0.
• AP policies off, fallback, and always.
• Random persistent fallback-AP password and MAC-derived default SSID.
• Bounded profile attempts, DHCP deadlines, failover, and retry backoff.
• Root and wifi aliases for ping, nslookup, and traceroute.
• Wi-Fi/lwIP payload allocation configured to prefer PSRAM with capacities pinned in sdkconfig.defaults.

Post-validation enhancements implemented; regression validation pending:

• Edits to disabled station profiles are staged without restarting the active radio; enable-state changes and edits affecting enabled radio policy apply asynchronously.
• Configurable STA-only sak-<suffix>.local mDNS hostname with an independent versioned NVS record, live hostname updates, automatic withdrawal/restoration across STA IPv4 transitions, and nonfatal failure isolation. The responder initializes at most once and keeps its task stack internal while general metadata prefers PSRAM.

A WPA3-required profile correctly rejects an AP that does not advertise the required Protected Management Frame capability; mixed mode is the compatible choice for such an AP.

Phase 5A — Authenticated HTTPS foundation

Implemented and hardware-validated:

• HTTPS-only service on TCP port 443 using ESP-IDF mbedTLS.
• Persistent random shared admin credential, later retained only as migration/recovery material by Phase 8.
• Persistent device-specific ECDSA P-256 certificate and private key.
• Physical-console credential retrieval, rotation, certificate inspection, rotation, and recovery.
• Explicit failure behavior that preserves UART0, USB, serial, and Wi-Fi recovery paths.
• Credential rotation revocation hooks shared with WebSocket and SSH sessions.

Phase 5B — Offline browser terminal

Implemented and hardware-validated:

• Vendored xterm.js and FitAddon assets; no Internet or CDN dependency.
• CSP-compatible page structure with scripts served as separate resources.
• Authenticated status and one-time WebSocket-ticket APIs.
• Binary WebSocket serial frames and broker writer/observer integration.
• Two bounded browser-terminal sessions.
• Writer request/release controls and role indication.
• Bounded TLS/socket behavior and slow-observer isolation.
• Viewport-constrained terminal fitting without recursive page growth.
• Validation with multiple clients, ANSI colors, advanced escape sequences, and full-screen terminal software.

Post-validation enhancement implemented; browser regression validation pending: the combined Connect/Disconnect control explicitly closes the terminal WebSocket and pauses automatic reconnect until Connect is selected.

Phase 6 — Authenticated SSH serial transport

Implemented and target-hardware validated:

• wolfSSH on TCP port 22 with a separate persistent ECDSA P-256 host key.
• Two bounded interactive shell/PTY sessions; no exec, file transfer, forwarding, or subsystems.
• Authenticated, binary-transparent broker forwarding with opportunistic writer acquisition and observer fallback.
• Bounded handshake attempts/deadlines, receive work, buffers, and a single wolfSSH owner task pinned to CPU 1.
• UART0 lifecycle, session, counter, and host-key administration.
• PSRAM-preferred allocations with internal fallback and internal task stacks.
• Bounded broker/WebSocket work, software mbedTLS AES, and software wolfCrypt AES/SHA to avoid the validated shared-hardware-crypto/PSRAM watchdog failure while retaining ESP-IDF SHA/MPI acceleration.
• Concurrent USB, WebSocket, and SSH operation validated with USB and SSH alternately holding the writer lease.

Phase 7 — Local display and buttons

Implemented and target-hardware validated:

• Optional 128×64 SSD1315-compatible I²C OLED on GPIO11/12 and active-low buttons on GPIO10/13/14; assignments remain centralized in board_pins.h.
• Display service with a static framebuffer, bounded dirty-page commits, and separate yellow status rows 0–15 plus blue content rows 16–63.
• Low-priority status/control task built from copied public snapshots; no service lock is held across I²C and the UI never becomes a broker client.
• Overview, RS-232, broker, and network/service pages with no credential or key material.
• Confirmation-protected local controls for service lifecycle, Wi-Fi reconnect/profile rotation, writer release, display off, and reboot; the UI cannot assign a writer or edit secrets/configuration.
• Persistent dim/off settings, bounded boot animation, consumed wake presses, stuck-button quarantine, and one-shot confirmations.
• Missing, disconnected, or unresponsive display hardware remains nonfatal and can recover through one bounded reprobe.
• Concurrent serial, UART0, USB, WebSocket, SSH, and injected display/button fault behavior validated. See Electrical tests and Hardware wiring.

Phase 8 — Role-based users and administrative access — Complete

Implemented and accepted: a bounded, persistent user system replaces the single shared network credential. Both roles can use the authenticated web serial/status interface. Over SSH, user routes to the broker-backed serial stream while admin routes exclusively to the administration shell and receives no broker client or writer lease. UART0 remains the physical recovery and bootstrap authority.

Completed implementation (8A–8C target-hardware validated; 8D explicitly accepted at 8D.22 on 2026-09-13):

1. Phase 8A — User database and UART0 administration — Complete
   • Versioned NVS database for up to eight user/admin accounts, random account IDs and authentication generations, final-admin protection, and three Ed25519/P-256 keys per account.
   • Salted PBKDF2-HMAC-SHA256 password verifiers, bounded no-echo entry, one-time generated passwords, and secret-free account/key status.
   • Historical migration/bootstrap supported the initial cutover. Current firmware instead commits missing storage empty, provisions the first admin with normal UART0 user add, and provides UART0-only unavailable-database recovery; legacy credential/bootstrap commands are removed.
   • Migration, bootstrap, CRUD, persistence, and command basics target-hardware validated; the full fault-injection matrix remains regression coverage. NVS remains unencrypted and offline guessing remains possible.
2. Phase 8B — Role-aware HTTPS and SSH authentication — Complete
   • HTTPS and SSH authenticate through the common database and copied secret-free principals; unavailable user storage fails closed. The initial HTTPS Basic path was replaced by cookie authentication in 8D.
   • One-time principal-bound WebSocket tickets and ongoing principal-currentness checks prevent stale admission or input.
   • Account mutations request targeted WebSocket/SSH revocation; authentication generations provide fail-safe invalidation while unrelated accounts remain connected.
   • Password/key login, ticket behavior, targeted revocation, recovery, and concurrent transport operation are target-hardware validated. Legacy credentials were subsequently removed without changing established TLS identity or valid users.
3. Phase 8C — SSH administrative shell — Complete
   • Authenticated admin SSH shell sessions route to a bounded administration worker and never create a broker client or acquire a serial writer lease. Normal user sessions retain the existing broker-backed serial stream.
   • UART0 and admin SSH now submit complete lines to one fixed-length request queue. A single dispatcher task is the sole caller of ESP-IDF's non-reentrant esp_console_run() and therefore executes the same registered command handlers for both entry routes. The former separately implemented reduced SSH command dispatcher has been removed.
   • The worker uses fixed per-session command/input and output buffers. Queue records contain copied secret-free principals and generation-tagged session tokens; late work is discarded after disconnect, slot reuse, role change, password/key mutation, or deletion. Task-local standard streams route canonical handler output into the applicable bounded SSH ring, and only the SSH owner task calls wolfSSH APIs.
   • Transport-neutral bounded prompts now support interactive user passwords/keys and Wi-Fi secrets over admin SSH without exposing hidden input or allowing another command while a prompt is active. Ping callbacks enqueue typed bounded events and the dispatcher alone formats their output. Four-entry per-session history and whole-line Tab completion are RAM-only and wiped on disconnect.
   • Authenticated administrators receive the operational registry, including HTTPS material rotation/reset, reboot, ping, and SSH lifecycle/session/host-key mutation. Self-terminating reboot and SSH actions are deferred until acknowledgement output drains, block further shell input, and execute through existing synchronous owner APIs from a separate bounded control task. First-admin provisioning and explicit user recover --force remain physical-UART0 operations (user bootstrap was later removed); admin SSH also rejects generating a replacement password for its own account.
   • ssh sessions and ssh counters identify broker versus admin-console routes, worker command state, queued admin output, admission failures, and input backpressure. exit and Ctrl+D on an empty command line request bounded deferred self-disconnect after best-effort application-buffer draining. Admin sessions are checked for a current admin principal before command execution and during the active-session reconciliation.
   • Keep SFTP, SCP, exec, forwarding, subsystems, and unauthenticated shells disabled.
   • Target-hardware validation passed for route separation, history/Tab editing, interactive visible/hidden prompts, output/backpressure, generated and entered user/password/key management including the longest ECDSA P-256 import, ping event routing, deferred reboot/SSH lifecycle drain behavior, bootstrap/recovery rejection, targeted self/other-user revocation during queued work, UART0/SSH administration serialization, and concurrent USB/WebSocket/user-SSH/admin-SSH operation. Stress at 460800 baud with SSH and WebSocket clients caused substantial expected packet drops and slower display controls, but did not exhaust memory or require lowering the supported baud-rate range.
4. Phase 8D — Integrated web administration — Complete
   • User explicitly signed off tested firmware at 8D.22 on 2026-09-13, superseding earlier per-slice pending acceptance/review gates. Cookie login/logout replaces Basic; bounded digest-only sessions, same-origin/CSRF checks, principal currentness and targeted revocation protect serial and admin routes.
   • Admin-only Serial/Admin selection and Settings preserve connected terminal observation and serial writer ownership. The browser shell shares the serialized UART0/admin-SSH dispatcher, with bounded output, explicit admission and retained frontend restrictions—not unrestricted shell parity.
   • Typed Serial, Accounts/password/authorized-key, Network/Wi-Fi/mDNS, Display, Broker and SSH settings; confirmed HTTPS stop/restart/reboot and HTTPS/SSH identity rotation. Canonical owners compare reserved service/identity/target generations, preserve commit/failure semantics and expose no stored secrets. Admitted work is not cancelled by later logout/timeout; uncertain mutations are never automatically replayed.
   • Accessible Serial/Wi-Fi/client/writer contextual controls reuse existing controllers. Writer transfer is explicit and generation-safe; one writer, isolated observers, binary transparency, UART0 administrative recovery and network-independent native USB UART1 remain invariants.
   • Scope removed by user: 8D.15 dedicated typed network diagnostics (shell diagnostics retained) and the unimplemented 8D.19 ordinary browser-session/native-USB controls (SSH controls retained). Browser identity reset/recovery/export is excluded; canonical recovery remains available.
   • Prior final build PASS: 100,556 B linked RAM / 1,828,573 B flash, CPU 160 MHz. Earlier combined binary WebSocket-send fix was explicitly accepted at 160 MHz / 230400 baud with full client mix including browser admin. Latest overall sign-off does not invent individual fault/soak/duration results or a latest exact zero-drop comparison.
   • Latest loaded internal/DMA minima 2,052 / 460 B remain a conservative transient-headroom follow-up, not a blocker reopening acceptance or an approved reserve. See acceptance and telemetry, current contracts, regression procedures and legacy compatibility.

Current and planned phases

Phase 8 is complete for its accepted scope. Phase 9 has started at the user's request; later work remains planned or under evaluation. Optional features must not weaken completed serial and recovery paths. General release gates below remain guidance for future work, not claims that every listed fault, soak or reserve measurement was individually performed for 8D.

Phase 9 — Security and production hardening

In progress. Harden network authentication, secret lifetimes, crash/debug exposure and operational maintenance. Secure boot and encrypted NVS are explicitly excluded by user preference. No eFuse, partition, at-rest encryption or dependency-version upgrades are part of 9A–9C; 9C adds source-pinned build-tree dependency corrections; no future flash/PSRAM encryption commitment is implied. Physical extraction and firmware replacement remain outside the threat model after Phase 9, and software debug restrictions do not imply physical JTAG fuse restrictions.

Staged work:

1. 9A — Crash/debug build policy and operational profiles — In progress; hardware pending. src/security_build_policy.c requires CONFIG_ESP_COREDUMP_ENABLE_TO_NONE=y and CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT=y; rejects core-dump enable/flash/UART, panic print/halt/GDBstub, runtime GDBstub and ESP/FreeRTOS debugger-aware options. sdkconfig.defaults makes the baseline explicit. Development/test/production use the same build baseline, not separate PlatformIO environments. Host matrix (python3 tests/security_build_policy/run.py) compiles the actual guard: 17 cases plus the generated-header check passed on 2026-09-15. pio run passed (94,196 B linked RAM / 1,828,565 B flash); target panic/recovery tests have not run. Production readiness remains pending.
2. 9B — SSH admission and credential handling — Implemented; combined target validation deferred. Boot-lifetime, owner-only token buckets independently bound handshakes, password/signed-key requests and unsigned probes; reconnect/restart/counter clearing do not replenish them. Existing per-slot attempt limits/currentness remain. Explicit keyboard-interactive rejection, pending-signature result fencing, secret-free admission counters, consumed admin-buffer wipes and fail-closed hidden-prompt overflow/unsupported-byte handling are implemented. Four focused suites (including 35 pinned-vendor control-flow cases), 11 related regressions and pio run passed on 2026-09-15: 94,340 B linked RAM / 1,829,925 B flash. Global-budget starvation remains a documented tradeoff, not a solved availability problem.
3. 9C — Library cleanup and protocol policy — Implemented; combined target validation deferred. Exact-hash build-tree overrides correct HTTPS cleanup/leaks, HTTPD scratch failure/wiping/first-read handling, bounded SSH password parsing/wiping and server-local TLS policy without modifying installed dependencies. Secure wolfSSL allocation hooks and explicit SSH policy fail closed; early web quota probing avoids receiving already-throttled bodies. TLS1.2 ECDHE-ECDSA AES-GCM and SSH GCM/modern-KEX allowlists intentionally exclude legacy-only clients; no identity migration. Bounded password/certificate/header/destructor review is documented, not exhaustive zeroization. Final build PASS 94,340 B linked RAM / 1,831,309 B flash; focused and related host/source-contract tests passed. Review and maintenance contract.
4. 9D — Maintenance and lifecycle — In progress; unresolved security and distribution questions. Security operations documents provisioning, explicit saves, rotation, recovery, reconstruction (no implemented backup/export) and approved destructive reset/decommissioning. The wolfSSL/wolfSSH implementation addendum records the implemented Xtensa small X25519/Ed25519 mitigation (CVE-2025-12888), with consistent library/consumer flags and a resolved-settings guard; small X25519 is not combined with blinding. Bounded IGNORE/service/string parsing, channel-window overflow, ECC/Ed25519 labels and exact signature framing are now corrected in the existing generated override. P-256 import and X25519 all-zero-result checks are enabled with effective PUBLIC flags confirmed; generic digest/OID API hardening and deferred parser semantics remain open. Restricted existing-profile ordering correction (CVE-2025-14942) is implemented, using audited PR793/819/840/855/921 subsets plus local gates, not a full upstream backport. X25519/P-256 only, independent SELF/PEER bits, expected-message/authentication gates and queued NEWKEYS continuation handle nonblocking writes. EXT_INFO is intentionally disabled; no server-sig-algs is advertised. Eight C overrides plus one PUBLIC forced ABI header retain hash pins/notices; joined forced-header arguments fix PlatformIO sorting/deduplication. The review's misplaced EOF guard is corrected and verified with no scoped blocker. The IDF implementation addendum records pinned DHCP (CVE-2026-45160), TLS 1.2 EMS (CVE-2026-50581) and X.509 allocation-failure (CVE-2026-34874) backports; historical research remains labeled and retained. Supplied parent build PASS: 94,340 B linked RAM / 1,768,701 B flash, unchanged RAM / −248 B flash versus 1,768,949 B. Final parent all six suites PASS: ordering --interop (8,028 checks, seven rejected mutations, 12 exact-256-KiB sessions with clean channel close/transport EOF), SDK overrides with actual --build-dir registration, auth (135), protocol, strict crypto and parser (3,124 × two modes). Interop required unsandboxed approval only for local AF_UNIX sockets; no remote network/device operation. Agent ordering evidence: 8,028 checks / seven rejected mutations. Initial interop failed a harness close race despite early PASS output; the corrected harness waits for peer close/transport EOF and independently reaps the server through an fd-passing proxy. Final agent repeated OpenSSH matrix: 36/36 sessions, each exact 256 KiB, two or ten completed key exchanges and clean client/server exits; see evidence and limits. The bounded license inventory marks modification/date notices resolved for all eight generated C files plus one header (baseline 2026-09-15 and wolfSSH ordering 2026-09-16; upstream licenses retained), with archived patch hashes/commits and patch license context recorded, but radio-blob corresponding-source/exception, source/notice delivery and packaging/provenance questions remain open. Official registry wolfSSH 1.5.0 / wolfSSL 5.9.2 queries returned 404 on 2026-09-15; upstream tags exist but managed compatibility is not established. The remaining ordering gates and immutable provenance retain target cleanup during rekey, intended-client compatibility without EXT_INFO and whole-phase resource/timing validation. Future upstream adoption still requires isolated packaging/compatibility evaluation. Upgrades/backports require coherent source/header review, override rebasing and contract tests, not blind repinning. Broader dependency advisory coverage remains unfinished. No dependency upgrade was performed. Phase 9 is not complete or production-ready; scoped mitigations do not establish full advisory closure, device validation or license/distribution clearance. OTA signing trust remains separate Phase 10 work.

At the user's request, hardware validation is deferred to Phase 9 as a whole, not required between implementation slices. Security hardening collects profiles, host evidence and the combined target checklist. Silent panic reboot removes useful crash diagnostics, not ordinary reset/boot/status information or every possible log disclosure. Raw flash/RAM/dumps remain secret-bearing, not routine diagnostic exports. Existing coredump bytes are not retroactively cleared; no secure erase is claimed. Isolated synthetic-secret debug builds require explicit reviewed source-policy changes, not a provided bypass flag.

Phase 10 — Authenticated OTA and rollback

Use the existing dual 4 MiB application slots and otadata partition to add safe firmware updates.

Planned work:

• Accept only authenticated, integrity-checked firmware images under an independently defined OTA signing-trust policy without secure boot; define trusted-key provisioning, rotation, revocation and recovery. This cannot prevent physical firmware replacement.
• Support an update path that does not expose a plaintext management endpoint.
• Stream downloads with bounded RAM use and explicit progress/error reporting.
• Preserve serial, Wi-Fi, HTTPS, and SSH configuration across successful updates.
• Mark new firmware pending until a post-boot health check succeeds.
• Roll back automatically after failed boot or health confirmation.
• Define power-loss behavior for every update stage.
• Keep UART0 recovery and wired re-flashing documented and functional.
• Add version/compatibility checks and reject accidental downgrade unless an explicit policy allows it.

OTA is complete only after successful update, interrupted-update, invalid-image, rollback, and configuration-persistence tests on hardware.

Phase 11 — BLE

Evaluate and, if resource limits permit, add BLE as another bounded transport or provisioning path.

Planned work:

• Decide whether BLE is primarily a serial transport, a provisioning interface, or both.
• Require authenticated pairing/bonding appropriate to the device threat model.
• Integrate serial access through the existing broker rather than bypassing writer ownership.
• Preserve binary transparency through explicit framing and MTU-aware partial transfers.
• Bound connections, queues, retries, and advertising behavior.
• Measure coexistence with 2.4 GHz Wi-Fi, HTTPS, WebSocket, SSH, USB CDC, and UART service.
• Define bond/provisioning secret retention under the unencrypted-storage threat model; do not assume Phase 9 provides at-rest encryption.
• Provide UART0 controls and a physical recovery path for clearing BLE state.

BLE remains subordinate to stable Wi-Fi and serial operation; it should be omitted if coexistence or memory costs cannot be bounded acceptably.

Phase 12 — Advanced network integration

These features are candidates, not current commitments:

• Additional DNS-SD service advertisement and any certificate-name integration beyond the implemented configurable STA hostname.
• Enterprise Wi-Fi support, subject to credential-storage and certificate-validation design.
• IPv6 behavior and diagnostics beyond the current basic support.
• WireGuard feasibility evaluation, including RAM, CPU, licensing, key storage, routing, and recovery impact.

The device is not intended to become a general-purpose router. Captive-portal interception, unauthenticated DNS redirection, NAPT, and a plaintext serial listener remain out of scope unless the project requirements are explicitly revised.

Phase 13 — Optional filesystem-backed features

The storage partition is reserved but not currently mounted. Possible uses must be justified individually:

• LittleFS-backed web assets to decouple large static files from the application image.
• Bounded diagnostic logs with explicit retention and secret-redaction rules.
• Import/export of non-secret configuration.
• Optional user files needed by later administration features.

Before enabling storage, define corruption recovery, wear limits, quotas, atomic update behavior, compatibility across OTA slots, and whether encryption is required. Serial operation and recovery must not depend on a mountable filesystem.

Cross-phase release gates

Every phase should satisfy the following before being marked complete:

1. A clean release build for the ESP32-S3 N16R8 target.
2. No new compiler or project diagnostics attributable to the change.
3. Focused automated tests where practical and documented hardware tests where hardware behavior is involved.
4. UART0, native USB CDC, and previously completed network transports still operate.
5. Broker writer/observer semantics and binary transparency remain intact.
6. Failure, disconnect, stop/start, reboot, and stale-session cleanup paths are exercised.
7. Runtime memory, stack, socket, and queue bounds are measured under maximum supported concurrency.
8. Secrets remain absent from ordinary status output and logs.
9. Command reference, Hardware wiring, electrical tests, and this roadmap are updated as applicable.
10. New dependencies receive security, maintenance, and GPL-3.0 compatibility review.

Explicitly deferred work

The following are not implemented merely because flash partitions or library support exist:

• Secure boot and encrypted NVS are excluded by explicit user preference, not scheduled future enablement.

• Flash/PSRAM encryption and production eFuse provisioning are outside the current scope, with no enablement commitment.

• OTA download, image confirmation, or rollback policy.

• Core-dump collection or export: the supported Phase 9A baseline disables new dumps; existing partition bytes are not cleared.

• Filesystem mounting.

• SFTP, SCP, SSH exec, forwarding, or subsystems.

• General routing, NAPT, captive-portal interception, or unauthenticated serial access.

Deferring these features is intentional: each changes the security model, recovery behavior, or bounded-resource assumptions and therefore requires its own design and validation gate.