@logicseek/hello-cc 1.0.0 → 1.0.1

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

@@ -1,117 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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.