@logicseek/hello-cc 0.1.8 → 1.0.0

package/docs/superpowers/specs/2026-08-03-v1-release-verification-design.md

@@ -0,0 +1,117 @@
+# hello-cc v1 Release and Verification Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Define code ownership boundaries, fatal error behavior, packaging, documentation,
+and evidence required before the remaining hardening work can be called complete.
+
+## Module Boundaries
+
+New focused modules own these policies:
+
+- process identity inspection and comparison;
+- clock observation and liveness resolution;
+- project registry locking;
+- buffer GC planning and arbitration;
+- Runtime API version negotiation;
+- secret redaction.
+
+`bin/hcc.mjs` remains the command and runtime orchestrator. It calls these
+modules but does not duplicate their decision logic. Existing repository
+patterns are retained; unrelated restructuring is out of scope.
+
+Every imported production module must be tracked and included by the package
+`files` contract. Docker test files are tracked but remain outside the npm
+package.
+
+## Fatal Error Behavior
+
+Expected poller, watcher, sibling-project, and transient runtime failures are
+caught at their ownership boundary, logged with redaction, and isolated.
+
+An uncaught exception or unhandled rejection initiates one idempotent fatal
+shutdown. Shutdown stops timers and watchers, closes sessions and sockets using
+the documented detach/exit semantics, clears only runtime pointers owned by the
+current process identity, closes the server and database resources, then exits
+nonzero. The runtime must not continue after an unknown exception.
+
+A second fatal signal during shutdown forces termination without attempting a
+second cleanup pass.
+
+## Release Contract
+
+The package version becomes `1.0.0`. Changelog, README files, bilingual command
+documentation, help output, and the defect review describe:
+
+- schema v7 and no downgrade support;
+- the pre-migration backup;
+- provider peer ID changes;
+- Runtime API v2 and session token delivery changes;
+- safe GC defaults and `--history`;
+- process-evidence-first liveness and unknown-only grace;
+- optional TLS and trusted proxy usage;
+- accepted plaintext LAN and arbitrary-root risks.
+
+The defect report uses evidence-backed status counts and the actual branch. It
+must not label accepted risks or partial controls as completely fixed.
+
+The Dockerfile uses `npm ci`, records Node and tmux versions in test output, and
+builds from the complete current source tree. `.dockerignore` excludes host
+runtime state and secrets without excluding production source.
+
+## Test Architecture
+
+Pure policies use Node's built-in test runner in focused test files. Real CLI,
+SQLite, tmux, HTTP, HTTPS, and WebSocket boundaries remain integration tests.
+Tests do not add production-only backdoors or test-only public APIs.
+
+Each behavior change follows red-green-refactor:
+
+1. add the smallest regression that demonstrates the missing invariant;
+2. run it and record the expected failure;
+3. implement the minimum production change;
+4. rerun the focused test and relevant neighboring tests;
+5. refactor only while green.
+
+Required regressions cover:
+
+- v5/v6 backup and migration failure atomicity;
+- PID reuse and platform process inspection;
+- live, dead, and unknown tmux/external peers;
+- CLI-only sleep-sized gaps and concurrent grace writers;
+- manual/automatic GC, negative retention, history opt-in, and runtime failure;
+- concurrent registry writers and same-root DB changes;
+- API v2, cookie lifecycle, action-token scope, CSP, and redaction;
+- realpath and symlink containment;
+- fatal shutdown cleanup;
+- package content and tracked-file completeness.
+
+TTL renewal tests use the renewal operation's recorded timestamp rather than
+assuming wall-clock readings in separate processes are monotonic. This retains
+strict TTL inflation checks without the observed one-second container flake.
+
+## Verification Gates
+
+Completion requires fresh evidence, in this order:
+
+1. final diff and tracked production import audit;
+2. syntax/import/package-content checks;
+3. focused unit and security regression tests;
+4. original vulnerable-path reproductions and alternate bypass inputs;
+5. preserved legitimate behavior tests;
+6. complete local regression;
+7. a freshly built Node 24/Linux image;
+8. three consecutive complete container regressions;
+9. final `origin/master..worktree` review and documentation consistency check.
+
+A failed gate blocks a completion claim. Accepted risks are reported separately
+and are not represented as test gaps or fixed findings.
+
+## Definition of Done
+
+The work is complete only when every approved non-accepted-risk requirement in
+the four v1 design specifications has a passing test or a documented reason the
+check is inapplicable, all required verification gates pass, and the final
+working tree contains no untracked production dependency.

package/docs/superpowers/specs/2026-08-03-web-api-hardening-design.md

@@ -0,0 +1,104 @@
+# Web and Runtime API v2 Hardening Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Define the v1 Web authentication, Runtime API v2, browser policy, path safety,
+and log-redaction contract while preserving two explicitly accepted risks.
+
+## Accepted Risks
+
+- The default Web listener remains `0.0.0.0` over HTTP for LAN access.
+- An authenticated administrator may select any existing server project root.
+
+These choices permit passive LAN observation of HTTP traffic and broad access
+to server project directories by anyone holding the administrator credential.
+Documentation must state these risks and must not mark transport confidentiality
+or project scoping as fully remediated.
+
+## Authentication Roles
+
+The stable runtime token is the administrator credential. An HttpOnly browser
+cookie issued after successful token login represents the same administrator
+role. Both may create, stop, attach, and inject managed sessions.
+
+A session action token is narrower. It authorizes terminal WebSocket input for
+one managed session and is delivered only in that session's terminal snapshot.
+It is never returned by the session list. Session action token comparisons use
+the shared constant-time token helper.
+
+Cookie sessions have a server-side expiry, a bounded count, explicit logout,
+and tracked WebSocket membership. Expiry, eviction, or logout closes associated
+WebSockets immediately. Cookie-authenticated mutations require a same-origin
+request.
+
+Non-loopback listeners require a non-empty administrator token. Tokenless mode
+is accepted only from a loopback socket.
+
+## Runtime API v2
+
+Runtime metadata advertises API version 2. CLI and browser HTTP requests send
+`X-HCC-API-Version: 2`. Browser WebSocket handshakes send `api_version=2` in the
+query because the WebSocket browser API cannot set an arbitrary request header.
+Protected API requests with a missing or unsupported version receive HTTP 426
+with `API_VERSION_UNSUPPORTED` and the supported version.
+
+Public login and static bootstrap routes remain reachable without the API
+version header. The v1 release notes identify removal of `action_token` from
+`GET /api/sessions` as a breaking API change.
+
+## Browser Policy
+
+HTML responses use a per-response nonce. The Content Security Policy permits
+scripts only from self and the response nonce, denies objects and framing,
+restricts base URIs, and permits only the same-origin HTTP/WebSocket connections
+needed by the console. Styles allow the current xterm and inline-style contract;
+script policy must not require `unsafe-inline`.
+
+Responses retain no-store, no-referrer, and nosniff headers. Secure requests may
+add transport-only headers without applying HSTS to accepted plaintext mode.
+
+## Path Safety
+
+Arbitrary existing roots remain supported, but lexical containment is not
+enough. The selected root is canonicalized with `realpath`. The `.hello-cc`
+directory is created with owner-only permissions when absent and canonicalized
+when present. A symlinked `.hello-cc` or DB parent that resolves outside the
+canonical state directory is rejected.
+
+The selected database must resolve to `mesh.db` or another path below the real
+`.hello-cc` directory. Pseudo-files, non-regular database targets, and symlink
+escapes are rejected before SQLite opens the target.
+
+## TLS and Proxy Modes
+
+Direct `--tls` mode validates certificate dates, SAN coverage, key pairing, file
+permissions, and generation publication before listening. CLI requests trust
+only the runtime's stored self-signed certificate.
+
+`--trust-proxy --proxy-origin https://host[:port]` accepts forwarded host/proto
+only from a loopback peer and only when both exactly match the pinned public
+origin. Either option without the other is rejected. Forwarded headers from any
+non-loopback peer are ignored. Cookie `Secure` state and origin checks consume
+the same trusted-proxy decision.
+
+## Secret Redaction
+
+All startup and error logging passes through one redactor. It removes or replaces
+values for `--token`, Authorization, cookies, session action tokens, runtime
+tokens, and URL `token` query parameters. The redactor handles both structured
+objects and command-line strings. Runtime pointer files remain owner-readable
+only because local CLI operation requires the administrator token.
+
+## Acceptance Criteria
+
+- Old or missing API versions receive 426 on protected API routes.
+- Admin token and admin cookie retain documented management behavior.
+- Session action tokens are absent from lists and required for WS input.
+- Logout and expiry close existing cookie-authenticated WebSockets.
+- CSP blocks an injected inline script without the nonce.
+- Logs contain no supplied administrator, cookie, or session token value.
+- Symlink DB escape is rejected while a normal arbitrary project root works.
+- Direct TLS, loopback trusted proxy, and accepted plaintext LAN modes pass
+  independent integration tests.