Fix USB radio stalls and add durable replay timestamp recovery

This commit is contained in:
mikecarper committed 2026-09-03 23:58:32 -07:00
1 parent f2c15225cc
commit a8cf4fd12f
44 files changed
+4339 -148

No files matched your search

+67
View File
@@ -2605,6 +2605,73 @@ eviction like administrators.
---
#### Recover a repeater's future-dated replay timestamp
This is an explicit recovery operation after correcting a bad clock, not a
contact deletion. It lowers selected replay timestamps to the repeater's
current UTC epoch only when they are later than that epoch. Earlier values,
public keys, permissions, stored paths, and historical identity records remain.
The replay file is committed before the live table changes. No extra 60-second
login reservation is added by this command.
First set/synchronize and verify the repeater's clock (`clock`); a build-default
clock without a manual or observed synchronization is not accepted. Also fix
the companion's clock before its next login.
USB console:
```text
replay reset <full-64-hex-public-key>
replay reset all CONFIRM
```
Authenticated LoRa admin, including a resumed admin session:
```text
replay reset <full-64-hex-public-key>
```
The reply shows `now=<epoch>`, `ttl=<remaining-seconds>s`, and a confirmation command containing the same
full key and a one-use 32-hex-character token. Verify the displayed time and send
that command before the original 300-second deadline. During the first 120
seconds, repeated requests for the same key by the same admin return the same
token without restarting either timer. From 120 through 300 seconds, the token
is retained for confirmation only: requests do not resend or replace it. This
leaves at least 180 seconds to deliver a confirmation after the last permitted
token response is generated (radio transit time still counts toward expiry).
At 300 seconds it expires and a new request can receive a new token. Confirmation
can succeed immediately; there is no requirement to wait for the resend window
to close. The displayed TTL decreases on retries and is measured when the reply
is generated, not when it reaches the companion.
It can target the caller's own key or another
exact key; prefixes, `self`, wildcards, and `all` are not allowed over LoRa.
Tokens are bound to both the requesting admin and target, expire on reboot,
and are invalid after use or a clock correction outside the five-second
confirmation tolerance. A failed write requires a new confirmation. Challenge
requests consult live token state instead of replaying cached challenge text;
completed confirmation results remain cacheable without executing the reset
again. Normal packet freshness checks still apply to retries.
Only the physical serial console grants `all` access. Ethernet, browser and
internal command callbacks do not count as USB. Guest, read-only, region-manager
and filter-manager roles cannot reset replay state. This command is implemented
in repeater firmware; room-server and sensor CLI are unchanged.
Normal login and command admission checks remain in force: a fully locked-out
caller that cannot send an accepted admin command needs another working admin
or USB access. A corrupt/unreadable replay file fails closed and is not erased
or formatted by this operation. Unknown keys do not create records.
Security trade-off: lowering a replay boundary can admit previously captured
future-dated login/command packets above the new boundary, including packets
that could raise it again. The one-use token prevents the recovery command
itself from being repeatedly executed; it does not replace the protocol's
timestamp-based replay protection. Use recovery only after verifying clocks.
Setting a clock alone never automatically resets this table.
---
#### View or change this room server's 'read-only' flag
**Usage:**
- `get allow.read.only`
+63
View File
@@ -0,0 +1,63 @@
# SPIFFS regular-file reads and login replay state
Arduino-ESP32 SPIFFS can return a truthy directory handle from a read-open of a
nonexistent filename. `File::operator bool()` alone does not prove that a
regular file exists. A directory's `size()` and `read()` are zero.
The first privileged login on an upgraded G2 encountered this in
`ClientACL::writeClientLoginReplayCeiling()`: opening the not-yet-created
`/s_login_replay` appeared successful, then subtracting the eight-byte trailer
from size zero underflowed. Copying the supposed records failed and login was
rejected. Waiting or changing the repeater clock cannot fix that file-open bug.
## Fix
Use `mesh::openFileRead()` for regular-file reads. It checks existence and
rejects directory handles, while preserving real empty files. Replay record
counts also validate the minimum trailer size, record alignment, and maximum
count before subtraction. An existing replay file that becomes unreadable is
not treated as a new store.
No replay records are cleared and authentication is not weakened. Invalid or
unwritable replay state still fails closed. The first successful privileged
login creates a 44-byte file: one 36-byte identity/ceiling record plus its
eight-byte integrity trailer.
Setting the repeater clock must not clear this file. Admission compares the
sender's timestamp with that sender's saved boundary, not with the repeater's
current time. Clearing the boundary could make captured requests reusable. A
sender clock rollback is a separate condition and remains subject to the saved
boundary after this fix.
Companion directory enumeration uses the separate `openDirectory()` API,
which deliberately permits SPIFFS virtual directories. Regular-file reads are
also enforced for companion data, repeater/room logs, flood-rule verification,
and HTTP packet-log downloads (missing logs return 404; real empty logs 200).
## Audit boundary
The audit covered file opens and size arithmetic in `src` and `examples`.
Identity, region, clock, and common preference loaders already gate reads with
filesystem existence checks; SPIFFS's `exists()` explicitly excludes directory
handles. Relevant MQTT length subtraction follows validated headers and exact
reads. ESP32 OTA staging uses partition APIs, not these SPIFFS file handles.
Intentional directory enumeration must not be changed to a regular-file read.
## Regression checks
- `test/test_client_acl_spiffs.py` compiles the actual `ClientACL.cpp` against
a filesystem that reproduces the misleading missing-file directory handle.
It covers first creation, fresh/stale login, reboot ceilings, corrupt and
unreadable state, short writes, failed publication, and truncated sources.
- `test/test_regular_file_reads.py` executes production companion readers,
flood-file verification, and HTTP log delivery with the same filesystem
behavior, including platform-specific file API differences.
- `test/test_esp32_tinyusb_cooperative_output.py` exercises both real role log
pumps, including missing logs and bounded output.
- Native ACL transaction, login persistence, and client-path persistence suites
retain the existing security and recovery coverage.
The pre-fix actual ACL code was reproduced as `first_login=rejected`, one
missing read-open, and no replay file. The fixed code accepted that identical
scenario without a missing read-open and created the valid 44-byte record.
Host simulations do not replace a post-flash LoRa login test on the G2.
+74
View File
@@ -0,0 +1,74 @@
# Native USB backpressure and radio liveness
ESP32-S2/S3 builds using native TinyUSB CDC (`ARDUINO_USB_MODE=0` and
CDC-on-boot) must not wait for a computer to read USB output. In the bundled
Arduino-ESP32 2.0.17 core, `USBCDC::write()` can wait indefinitely for transmit
space; its configured timeout bounds a mutex, not that wait. This can stop the
same loop that services LoRa, even while the USB connection still appears open.
## Firmware behavior
- Native CDC output uses a single FIFO attempt, not Arduino's wait-for-space
write or flush. TinyUSB's internal short mutex operations still apply; this
is a no-host-progress-wait guarantee, not a lock-free driver replacement.
- Functional text and diagnostics share one ordered 4 KiB queue. Diagnostics
leave 3 KiB reserved for commands. A diagnostic backlog alone does not prevent
command input. A stalled host may lose diagnostic records; radio work continues.
- A connected terminal that exceeds its bounded output capacity gets an explicit
dropped-byte notice when transmission resumes. Large local file dumps and
recent-repeater listings advance between radio service passes instead.
- File dumps stop at their initial file size and emit `-> EOF` only after the
final accepted record. Corrupt stored lines exceeding 640 bytes are omitted
with a visible notice. Recent-repeater output is a live, bounded-cursor view;
incoming packets can change its ordering while it is being printed.
- Disconnects discard pending old-session text and reset the role's partial
command/listing state. Binary/mOTA transitions suppress pending text notices.
Bytes already transmitted cannot be recalled.
- Companion frames retain and retry short writes. An mOTA request is admitted
only when its complete, at-most-11-byte record fits.
- nRF52, UART, and USB-Serial-JTAG behavior is not changed by this native-CDC path.
Host software must also keep reading independently of command writes. A serial
relay should start its reader before the first command, use finite write and
response deadlines, avoid discarding received packet logs, and cancel I/O during
shutdown. A response timeout must not allow a late reply to satisfy another
command: the CLI has no transaction identifiers. Updating firmware alone does
not correct an indefinite host-side serial write.
## Regression checks
Run only one PlatformIO process in the checkout at a time.
```sh
python test/test_esp32_tinyusb_nonblocking.py
python test/test_esp32_tinyusb_role_hygiene.py
python test/test_esp32_tinyusb_cooperative_output.py
python test/test_esp32_usb_serial_hygiene.py
python test/test_nrf52_usb_logging_contract.py
pio test -e native -f test_nrf52_debug_output -f test_serial_packet_log -f test_serial_mode_switch -f test_mesh_tables
```
The first test compiles the real USB facade against a simulated 64-byte FIFO,
including stopped readers, reconnects, protocol transitions, and other-platform
fallbacks. Host simulations cannot establish that every real USB driver or
endpoint failure has recovered.
A Full Station G2 validation build with USA Cascadia radio settings and the Cascade
profile can be made using the normal build entry point. The portable `standard`
recipe preserves the deployed partition layout but omits LoRa OTA; it still has
the browser firmware uploader. The `auto`/`full` recipe instead enables the
expanded feature set and partition layout: its merged image is **not** an
app-only update for a device with the legacy layout.
```sh
MESHDEBUG_OVERRIDE=on PACKET_LOGGING_OVERRIDE=on \
bash build.sh build-firmware Station_G2_repeater --build-profile full \
--radio-preset usa-cascadia --profile cascade
```
Before installing on hardware, preserve the device identity, preferences, and
existing partition layout. Then verify USB command responses and repeated LoRa
logins with the relay running, paused, and stopped, including a host that leaves
USB open without reading. Check LoRa recovery separately from USB OUT recovery;
fixing transmit backpressure does not prove an unrelated OUT endpoint fault is
resolved. Do not erase or repartition the radio as part of this test.