Files
alkane-os/code-review-report.md
T
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

6.6 KiB

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.