From d4991658b1173425ab9d5eb0e635c2c05bea2084 Mon Sep 17 00:00:00 2001 From: Commander1024 Date: Sat, 5 Sep 2026 16:11:23 +0200 Subject: [PATCH] Phase 8D validation completed --- docs/agent/current-state.md | 14 +++++++++----- docs/phase8d_baseline.md | 10 ++++++++-- docs/phase8d_plan.md | 10 ++++++---- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/docs/agent/current-state.md b/docs/agent/current-state.md index f71a6fb..d55bc07 100644 --- a/docs/agent/current-state.md +++ b/docs/agent/current-state.md @@ -4,12 +4,14 @@ This file is working memory. Update it during active work and before handoff; do ## Development state +- **8D.0 sign-off (2026-09-05):** User marked the baseline validated and identified tested source as latest checked-in revision `d8999cd4a96e477fabd392ced02d810c3cd22d0f`. Current samples and authoritative sign-off are in `docs/phase8d_baseline.md`; they supersede older baseline measurements/provenance notes below. User attributes SSH I/O errors to out-of-spec **460400-baud** testing, distinct from transcript UART configuration **460800**. Numeric reserve approval and 8D.1 post-change target validation remain pending; do not reopen 8D.0 solely for unrecorded checklist details or claim those checks were executed. + Based on checked-in source plus `README.md` and `docs/roadmap.md`: - Hardware characterization, serial service, session broker, USB CDC, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and local display/control are implemented and documented as target-hardware validated. - Phase 8A role-based user storage/UART0 administration and Phase 8B role-aware HTTPS/SSH authentication and targeted revocation are documented as target-hardware validated. - Phase 8C admin SSH is implemented in source, uses the shared `esp_console` registry, and has passed target-hardware validation. -- Phase 8D integrated web administration is planned, not implemented. Follow `docs/phase8d_plan.md`: one numbered chunk per request, with baseline/resource budgeting first, target-validated login/logout (M1) before the browser admin shell (M2), then one typed-settings/control domain at a time (M3). Changing terminal modes must preserve the browser serial broker client and any writer lease. The roadmap retains the full end-state requirements. +- Phase 8D.1 internal session primitives are implemented, host-tested and build-verified, not target-verified; browser login/logout and integrated web administration remain planned. Follow `docs/phase8d_plan.md`: one numbered chunk per request, with baseline/resource budgeting first, target-validated login/logout (M1) before the browser admin shell (M2), then one typed-settings/control domain at a time (M3). Changing terminal modes must preserve the browser serial broker client and any writer lease. The roadmap retains the full end-state requirements. - Security/production hardening, OTA, BLE evaluation, advanced networking, and optional filesystem features remain future roadmap work. - Reserved OTA, coredump, NVS-key, and storage partitions do not imply those runtime features are implemented. @@ -44,15 +46,17 @@ These observations should be checked when touching the relevant area; they are n - Confirm task-local Newlib standard-stream behavior if ESP-IDF/Newlib configuration changes; admin SSH command output relies on dispatcher-task stream redirection. - If HTTPD concurrency configuration changes, add locking around the boot-local Basic-authentication cache. -## Active task — Phase 8D.0 baseline and browser contract +## Active task — Phase 8D.1 internal session primitives -- **Objective:** Documentation and measurement only, following `docs/phase8d_plan.md`; no authentication implementation or continuation to 8D.1. +- **Objective:** Phase 8D.1 only. User explicitly requested continuation with remaining reserve/validation gates pending, then supplied a second pre-change full-client-mix sample. No browser auth cutover or continuation to 8D.2. - **Context:** The user reports that the earlier experimental implementation was moved to a separate branch and `devel` rolled back after repeated agent interruptions, a roughly +10k/-1k-line diff, broken browser login, and severe memory pressure. These symptoms have not been independently diagnosed. Do not import that branch wholesale. -- **Changes completed:** Added `docs/phase8d_baseline.md`: exact baseline revision/configuration hashes, build results, source-derived resource/socket inventory, minimal M1 routes/session/CSRF/origin/lifecycle/error contract, pending budget table and exact target checklist. Linked progress from the execution plan. Firmware, generated assets, and durable implementation architecture are unchanged. +- **Changes completed:** Added `src/web_session_store.{h,c}`, CMake registration and small admitted-HTTPS-start/stop hooks in `web_server.c`. Four static digest-only sessions, copied principals, separate CSRF/origin state, absolute expiry, generation-safe IDs/epochs, invalidation/prune and count-only snapshot APIs. Database/crypto outside portMUX, post-call revalidation. No issuing HTTP callers, ticket/socket/revocation binding, new routes/tasks, UI change or regenerated assets. Added focused `tests/web_session_store/` runner and updated baseline/plan/architecture/code map. - **Baseline:** Clean `devel` at `af89dd1bd96cdd97d8d57eee7a29f68e3874506b`, PlatformIO espressif32 6.12.0 / IDF 5.5.0, N16R8 release. `pio run` passed in 36.08 seconds: 94,532 B linked RAM and 1,599,973 B flash (historical RAM unchanged, flash +208 B, cause not diagnosed). `pio device list` returned no ports. No agent upload or target/browser test was performed. The user subsequently supplied a runtime heap baseline; stack measurements remain pending. - **User-provided runtime memory baseline (2026-09-05):** Administrative SSH transcript with one browser serial writer (broker 8), one public-key user SSH observer (broker 9), and one public-key admin SSH session; web 1/2, SSH 2/2, zero tickets, no USB broker client listed. Heap bytes in free/minimum-free/largest-block order: internal 8-bit **39,668 / 13,876 / 18,432**; internal DMA **31,912 / 6,120 / 18,432**; PSRAM **8,138,380 / 8,107,324 / 7,995,392**. Accepted as the runtime baseline, not reserve floors or full-workload validation. Flashed revision, baud, duration, traffic and stack margins were not supplied. See `docs/phase8d_baseline.md` for provenance and remaining checks. +- **Follow-up pre-change full-client-mix sample:** Two web sessions (broker 8 writer, 10 observer), USB broker 11 observer, user SSH broker 9 observer and admin SSH; four broker clients, SSH 2/2, web 2/2, no tickets. Internal 8-bit **41,868 / 13,876 / 18,432 B**; DMA **34,112 / 6,120 / 18,432 B**; PSRAM **8,162,784 / 8,107,324 / 7,995,392 B** (free/minimum/largest). Cumulative web/SSH traffic with no reported transport I/O/protocol/queue failures; one web auth failure and two rejected SSH RX bytes retained without diagnosis. This is not timed-soak or byte-integrity evidence; see baseline record. +- **8D.1 validation/accounting:** Started at clean `02fdeee3453654680c11096c9a6224c26233eced`. `python3 tests/web_session_store/run.py` passes with OpenSSL SHA-256, deterministic dependency doubles and injected callback races; no hardware or real multicore scheduling claim. Final `pio run` passed in 8.90 seconds: **95,204 B RAM (+672 B)**, **1,600,505 B flash (+532 B)**. Target object/DWARF: record 152 B × four, state 656 B + lock 8 B = **664 B**, no module heap/new task/socket/route cost, Basic cache retained. Only init/stop currently survive firmware linker GC; full primitive flash/stack costs become relevant when future callers are added. Independent review found/fixed store reinit by rejected concurrent start. Post-change target run pending. - **Planned contract decisions:** Four one-hour absolute sessions without idle/sliding renewal, four 120-second pre-login CSRF challenges, four 30-second serial tickets, no live-record eviction and no Basic compatibility after cutover. Strict same-origin mutation/upgrade checks, session-specific logout versus account-wide revocation, bounded global login throttle. These are functional choices, not measured memory budgets or implemented behavior. -- **Next:** Finish 8D.0 target checklist and measured reserve/incremental budgets in the baseline record. Five routine cycles per role, 15-minute 115200-baud concurrent soak and separate five-minute 460800-baud stress are specified but not executed. Do not start 8D.1 with the runtime gate pending without an explicit user decision; M1/M2 target pauses remain. +- **Next:** Stop at 8D.1. Obtain post-change Basic browser/serial/USB/user+admin SSH/UART0 regression and comparable `memory`/counters/`ssh status` evidence; five serial disconnect/reconnect cycles per role and HTTPS stop/start checks. Timed soak/cleanup and reserve floors remain pending. Next implementation is 8D.2 session-specific ticket/socket binding, only after checkpoint or explicit user decision; M1/M2 pauses remain. Host tests cover dormant primitives, not browser logout/currentness integration. ID/epoch exhaustion, collision rejection and private memory wiping are source-reviewed only. - **Risks / things to remember:** Six HTTPD client slots include WebSockets; HTTPD infrastructure plus HTTPS and SSH can consume twelve of sixteen descriptors before other services/transients. Existing LRU purge is enabled and must not evict retained serial to admit M2 admin sockets. Nine current route slots have no spare capacity; the proposed M1 contract adds five. Cookie sessions, tickets, sockets and request scratch are separate costs. Only SSH exposes stack margin today. Numeric runtime floors and per-chunk/cumulative budgets remain pending, not guessed. ## Previous task — mDNS (target checks still pending) diff --git a/docs/phase8d_baseline.md b/docs/phase8d_baseline.md index 8a30c66..41afa1a 100644 --- a/docs/phase8d_baseline.md +++ b/docs/phase8d_baseline.md @@ -1,6 +1,12 @@ # Phase 8D.0 — Baseline and M1 browser contract -Status: **documentation/source audit, baseline build and user-provided runtime memory baseline recorded; remaining target validation and numeric runtime budgets pending.** The M1 browser contract below remains planned, not implemented authentication. The user explicitly requested 8D.1 with remaining reserve gates pending; its internal-primitives results are recorded below. See [execution plan](phase8d_plan.md) and [acceptance matrix](user_administration_tests.md#planned-phase-8d-integrated-web-administration). +Status: **8D.0 validated by user sign-off on 2026-09-05.** Documentation/source audit, baseline build and target runtime samples are recorded. Numeric reserve floors and future incremental budgets remain open engineering gates, not blockers to this user-approved baseline closure. The M1 browser contract below remains planned, not implemented authentication; 8D.1 target validation remains separate. See [execution plan](phase8d_plan.md) and [acceptance matrix](user_administration_tests.md#planned-phase-8d-integrated-web-administration). + +## Validation sign-off + +- The user explicitly marked **8D.0 validated** and identified the tested firmware with the latest checked-in project state, resolved at sign-off to Git revision **`d8999cd4a96e477fabd392ced02d810c3cd22d0f`**. This is user-confirmed source provenance, not an independently read-back device binary hash. The earlier reproducible build revision and SHA-256 table remain historical build evidence, not newly generated hashes for this revision. +- The user attributes the SSH I/O errors to testing at **out-of-spec 460400 baud**. Preserve that exact reported rate separately from the transcripts' **460800-baud UART configuration**; the differing rate may describe the test setup, and no firmware baud-support change or independently reproduced diagnosis is implied. The session-revocation counter remains recorded without a separately supplied causal explanation. +- This sign-off closes 8D.0 using the supplied evidence. Per-sample missing-provenance and unverified-check notes below describe the evidence available when collected; source-revision uncertainty is superseded by this sign-off. Unrecorded detailed checks remain regression coverage, not claims that the agent executed them or outstanding blockers to 8D.0 closure. Numeric memory/stack reserve approval and post-change 8D.1 validation are not implied. ## Reproducible build baseline @@ -238,7 +244,7 @@ Resource gates: | 8D.0 firmware allocation/route/task/socket change | **0**; documentation only | | Baseline internal free/minimum/largest-block reserve floors | **Pending reserve analysis and remaining workload measurements**; the recorded sample is not a safety floor | | PSRAM reserve and largest-block floor | **Pending**, including TLS/SSH connection and handshake peaks | -| Stack reserve floors | **Pending** SSH measurement and missing owner-task telemetry | +| Stack reserve floors | **Pending** reserve analysis; SSH measurements recorded, other owner-task telemetry missing | | 8D.1 incremental budget | **Actual static delta +672 B**, including 664 B store/lock symbols; no module heap allocation, task, route or socket increase. Basic cache retained. Runtime reserve acceptance still pending; see implementation record below. | | 8D.2 incremental budget | **Pending** exact generation/session bindings added to four tickets/two slots and cleanup integration | | 8D.3 incremental and cumulative M1 budget | **Pending** four challenge records, throttle, five handlers, parser/CSRF scratch, minus removed Basic cache/key; no new task/socket allowance | diff --git a/docs/phase8d_plan.md b/docs/phase8d_plan.md index 0032192..976cd74 100644 --- a/docs/phase8d_plan.md +++ b/docs/phase8d_plan.md @@ -1,6 +1,6 @@ # Phase 8D — Incremental web administration plan -Status: **8D.0 documentation/source audit and baseline build and user-provided runtime memory baseline recorded; remaining target evidence and runtime budgets pending. 8D.1–8D.22 remain planned.** See the [8D.0 baseline and M1 contract](phase8d_baseline.md); no authentication implementation is claimed. +Status: **8D.0 validated by user sign-off on 2026-09-05; 8D.1 internal session primitives implemented, host-tested and build-verified, with target validation pending. Reserve budgets remain pending. 8D.2–8D.22 remain planned.** See the [8D.0 baseline and M1 contract](phase8d_baseline.md); no authentication implementation is claimed. This is the execution plan for [roadmap Phase 8D](roadmap.md#phase-8--role-based-users-and-administrative-access). The roadmap retains the feature/security requirements; this document defines small work units, dependencies, and release gates. The [administration test matrix](user_administration_tests.md#planned-phase-8d-integrated-web-administration) remains the final acceptance checklist. @@ -58,7 +58,7 @@ After each runtime-changing chunk: build; boot and read UART0 status/`memory`; l **Gate:** Existing admin and user browser login, serial data, USB, and SSH work; baseline `pio run` and target memory evidence are recorded. If the rolled-back baseline already fails login, diagnose that in a separate task before changing authentication. If target evidence is unavailable, the budget and runtime gate remain pending. -**Record:** [8D.0 baseline, browser contract, resource inventory and target checklist](phase8d_baseline.md). The baseline build passed at 94,532 B linked RAM / 1,599,973 B flash; no device ports were available. A user-provided runtime memory baseline is now recorded for one web serial writer plus user/admin SSH sessions. Other workload measurements, reserve floors and incremental budgets remain pending. Do not treat the documented contract as implemented behavior. +**Record:** [8D.0 baseline, browser contract, resource inventory and target checklist](phase8d_baseline.md). **Validated by user sign-off on 2026-09-05**, with tested source identified as `d8999cd4a96e477fabd392ced02d810c3cd22d0f`. Historical baseline build: 94,532 B linked RAM / 1,599,973 B flash. User-provided boot, browser, lifecycle, mixed-client and 15-minute soak/60-second cleanup samples include heap and SSH stack measurements. The user attributes SSH I/O errors to out-of-spec 460400-baud testing; see sign-off for distinction from reported UART configuration. Numeric reserve floors and incremental budgets remain open, without blocking user-approved 8D.0 closure. Do not treat the documented contract as implemented behavior. ### 8D.1 — Bounded server-side session primitives, not yet browser-facing @@ -68,6 +68,8 @@ After each runtime-changing chunk: build; boot and read UART0 status/`memory`; l **Gate:** Focused local/component checks for lifecycle, capacity, slot reuse, stale principals, and failed initialization; bounded storage accounting and build. Existing Basic-auth behavior remains unchanged. If no executable harness is practical, distinguish code review from target execution and carry the missing checks into 8D.3; do not claim unused code was exercised by a boot test. +**Record:** Implemented `web_session_store` plus admitted-start/stop lifecycle hooks; no route uses it yet. `python3 tests/web_session_store/run.py` and `pio run` pass. Linked RAM **95,204 B (+672 B)**, flash **1,600,505 B (+532 B)** versus 8D.0; static store/lock symbols total 664 B, no module heap allocation/new task/routes/sockets. Only init/stop are currently retained in the firmware link; host tests exercise the full production module. See the [8D.1 implementation record](phase8d_baseline.md#8d1-implementation-and-validation-record) for exact accounting, review limits and post-change target checklist. User explicitly requested this chunk with reserve gates pending; post-change device regression remains pending. Stop before 8D.2. + ### 8D.2 — Bind existing serial tickets and sockets to a web-session identity **Start in:** `src/web_serial_transport.{c,h}`, `src/web_server.{c,h}`, the session module from 8D.1, and the existing revocation call sites in `src/user_console.c`. @@ -155,11 +157,11 @@ Update the roadmap and user/command documentation to distinguish completed featu ## Progress and next-request template -Progress: **8D.0 documentation/source audit and build complete; target validation and numeric runtime budgets pending. 8D.1–8D.22 planned.** Record incremental results in `docs/agent/current-state.md`, retaining the [baseline](phase8d_baseline.md) and cumulative resource measurements as work proceeds. User-provided web/SSH status and memory evidence is recorded in the baseline; the full target/browser acceptance checklist remains unverified. +Progress: **8D.0 validated by user sign-off; 8D.1 implemented / host-tested / build-verified, not target-verified. Reserve gates pending. 8D.2–8D.22 planned.** Record incremental results in `docs/agent/current-state.md`, retaining the [baseline](phase8d_baseline.md) and cumulative resource measurements as work proceeds. The baseline records user-provided evidence and sign-off; this does not imply completion of later browser-authentication acceptance checks. Suggested next request: -> Work on Phase 8D.0 only, following `docs/phase8d_plan.md`. Establish the rolled-back baseline, the minimal M1 authentication/browser contract, and the resource budget. Do not implement authentication, import the experimental branch, or proceed to 8D.1. Report missing hardware evidence as pending and stop with the exact validation checklist. +> Validate the Phase 8D.1 target regression checklist in `docs/phase8d_baseline.md` and record post-change memory alongside the two pre-change samples. Then work on 8D.2 only when that checkpoint is satisfied, or explicitly decide to proceed with it pending. Do not cut over browser authentication or continue to 8D.3. For later chunks: