Files
alkane-os/code-review-report.md
noahandClaude Opus 4.8 2c5eccae55 os: apply code-review-harness fixes (security/reliability/correctness)
Four-dimension review (correctness/security/reliability/maintainability) of today's
console/bus/login/dashboard/image work found no Critical/High; the HTTP parser,
login gate (un-bypassable), bus semantics and the HMAC/PBKDF2/SHA-256 math were
verified correct. The Medium findings are fixed here.

Security:
- Token-gate /api/files and /api/file (were session-only despite the docs/Security
  page claiming token-gated - arbitrary root-readable file exfiltration).
- Neutralize settings-redirect header-splitting: __section/__tab are constrained to
  safe slugs before going into the Location header (CRLF no longer injects).
- One token source (auth::rand_hex): fail loud + non-constant fallback instead of the
  published "dev-csrf-token" / second-granular wsid when /dev/urandom is unreadable.
- Constant-time UI-token compare (auth::ct_eq); write auth.json 0600, dir 0700.
- Cap concurrent connections (64, 503 beyond) + 10s head-read deadline, bounding the
  thread-per-connection flood on the open :80.

Reliability/correctness:
- Settings persistence now propagates its write error (was swallowed and reported as
  success with a misleading comment) and writes atomically (temp+rename); deck save
  atomic too. Auth::login returns None if the session insert failed.
- TuningLoop::set_target resets the PID accumulator on a mode change (the old target's
  integral is in the old units) while keeping the operating point.
- Editable-deck JS: monotonic new-block ids (no collision after remove+add), default
  source frequency (was power_w, not in the live map), symmetric drag-drop placement,
  re-render after save. Drivers "stopped" shows the bare reason, not JSON-quoted.

Maintainability:
- New `form` module consolidates the three divergent percent_decode/field copies
  (web/service/dashboard). Added a test asserting published state topics match the
  registry contract.

Report in code-review-report.md (verdict, accepted-by-design posture incl. the
no-TLS / factory-creds residual risk, and a deferred list: ui.rs dead code, deck
assets extraction, target_label dedup). 206 lib tests + integration pass, clippy
-D warnings clean, no emojis. Image rebuilt with the fixed binary.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 21:41:59 -06:00

111 lines
6.6 KiB
Markdown

# Code review report - alkane-os console/bus/login/dashboard/image
Scope: today's work on `feature/afw-os-bundle` (bus, registry, service, web, console,
app, main, control, runtime, tuning, auth, dashboard, schema menus, image tooling).
Method: code-review-harness, 4 parallel reviewers (correctness, security, reliability,
maintainability) at high reasoning effort over the branch diff, then fixes applied and
re-verified. Installation-from-stock / restore-to-stock method tooling was out of scope
(DeepSeek Harness's domain; not in this repo).
## Verdict: READY TO SHIP (software checkpoint)
No Critical or High findings. The HTTP parser, login/session gate, bus semantics, and the
crypto (HMAC-SHA256 / PBKDF2 / SHA-256 against RFC 4231 / RFC 7914 vectors) were verified
correct; the session gate cannot be bypassed. Every Medium finding has been fixed and
re-verified. Remaining items are Low / maintainability and are listed as deferred.
External tooling: `cargo clippy --all-targets -- -D warnings` clean; 206 lib tests + all
integration tests pass; no emojis.
## Fixed in this pass
Security
- `/api/files` and `/api/file` were reachable with a session but no token, contradicting
the module docs and the Security page (arbitrary root-readable file exfiltration). Now
token-gated via `authorised()`, matching the advertised control. (web.rs)
- Response/header-splitting: `__section`/`__tab` from the settings form were interpolated
into the `Location:` header; `%0d%0a` decoded to CRLF. Now constrained to safe slugs
(`safe_slug`) before the redirect. (web.rs)
- RNG degradation: an unreadable `/dev/urandom` substituted the published constant
`"dev-csrf-token"` and second-granular, guessable session ids. Now a single token source
(`auth::rand_hex`) that warns loudly and falls back to a per-call, non-constant mix; the
CSRF generator delegates to it. (auth.rs, web.rs)
- The UI token was compared with `==` (timing oracle). Now `auth::ct_eq` (constant time).
(web.rs)
- `auth.json` (password hash) was written umask-default (world-readable). Now created 0600
with the parent dir 0700. (auth.rs)
- Unbounded thread-per-connection + no absolute read deadline (flood DoS on the open :80).
Now a 64-connection cap (503 beyond it) and a 10 s head-read deadline, on top of the
per-read timeout. (web.rs)
Reliability / correctness
- Settings persistence swallowed its write error and reported success with a misleading
comment. Now the error propagates (surfaced as the form's rejection) and the write is
atomic (temp + rename). Deck save is atomic too. (dashboard.rs, service.rs)
- `Auth::login` returned a cookie even if the session insert failed (redirect loop). Now
returns `None` on a poisoned lock. (auth.rs)
- `TuningLoop::set_target` carried the PID integral across modes whose error is in
different units (watts vs millidegrees vs TH/s), injecting a stale push on a mode switch.
Now the accumulator resets on a target change while the operating point is kept. (tuning.rs)
- Editable-deck JS: new-block ids collided after remove-then-add (duplicate ids, both
deleted on remove); the default new-block source `power_w` wasn't in the live-value map
(rendered n/a); drag-drop placement was asymmetric; save didn't re-render the normalized
doc. All fixed. (console.rs)
- Drivers page showed `"temperature"` with JSON quotes for the stopped reason. Now the bare
string. (web.rs)
Maintainability
- `percent_decode` / form-field parsing existed in three divergent copies; consolidated into
one `form` module used by web, service and dashboard. The CSPRNG-to-hex helper is now one
function (`auth::rand_hex`).
- Added a test asserting the published state topics match the registry contract (the
"single source of truth" claim for topics was previously unenforced).
## Deferred (reported, not blocking)
- `ui.rs` is now largely dead: only `validate_deck` / `default_deck` (+ two consts) are used
(by `service.rs`); the legacy console (`page`, `dashboard_page`, `sidebar`, `NAV`, the CSS/JS
consts, `icon`/`group_icon_svg` which `Box::leak`) has no callers. Recommend moving the two
deck helpers to a `deck` module and deleting the rest. (~34 KB)
- `control::target_label` vs `app::target_label` are two implementations of the same mapping;
recommend one canonical (e.g. in `tuning`).
- `DECK_CSS` / `DECK_JS` / `TERMINAL_JS` are large inline strings; recommend moving to
`assets/*.js|css`, `include_str!`, and serving under `/assets` like the stylesheets, so they
can be linted.
- `web.rs` still owns host-fact gatherers (`system_rows`, ...) that `console.rs` consumes;
recommend a `hostfacts` module both depend on.
- `route()` is long; the `/api/*` arm could be an `api_route()`.
- `Dashboard::page()` is now test-only (console renders pages); remove or mark reference-only.
- serve_sim's control loop spins silently if the in-process HAL thread dies; recommend
surfacing the fault and dropping `running` (the real-hardware `boot_hal` loop already exits
on a HAL write error, so this is dev-path only).
- `make-zynq-afw.sh` usage comment omits `--sdk-dir` (doc drift).
- No change-password route exists though the login page tells the operator to change
admin/admin; wire one or soften the text.
## Accepted-by-design posture (stated, not defects)
The box is SSH-guarded and the console is defense-in-depth on a shared network:
- No TLS: the console is HTTP on `0.0.0.0:80`, so a passive sniffer can capture the password
and session cookie. This is the dominant residual risk and should be made explicit to the
operator. A TLS front (or binding the console to a management interface / WireGuard) is the
real mitigation.
- Factory `admin`/`admin` with nothing forcing a change; the login page prints it.
- `/api/terminal` is a gated (session + token) root `/bin/sh` - an accepted diagnostic on an
already-root-reachable box. Note the shipped terminal UI does not send the token, so it is
fail-closed/unusable until a token is supplied.
- The web process runs as root (binds 80); consider a post-bind privilege drop.
- `/api/hardware|summary|control` are intentionally open (interface of record, mirror of the
cgminer socket).
- PBKDF2 at 50k iterations - low by modern standards, accepted behind SSH; matters only if the
hash leaks (now 0600).
- `make-zynq-afw.sh` always passes `--allow-unsigned` (bench-only helper; do not reuse on a
release path).
## Verification after fixes
Live `--serve-sim`: unauthenticated GET / serves the login page; admin/admin issues a session
and the console renders; `/api/files` returns 403 without a token; a CRLF-injected `__section`
is neutralized (303, no header split); the editable deck saves and reloads. clippy -D warnings
clean; 206 lib tests + integration pass.