> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md). # Implementation Notes **Session ID**: `phase01-session05-websocket-hydration-and-archive-export-privacy` **Package**: Cross-package (`apps/server`, `apps/web`, `packages/protocol`) **Started**: 2026-05-29 05:06 **Last Updated**: 2026-05-29 06:03 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 24 / 24 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Session Source Map ### Session 04 Baseline * `phase01-session04-server-routes-and-authorization-boundaries/validation.md` passed with 21/21 tasks complete, 1730 passing tests, route auth boundaries, compact `invalid_request` errors, deterministic 501 fallbacks, ASCII/LF checks, Biome, typecheck, and `npm test`. * `apps/server/src/lib/requestValidation.ts` owns the current route-boundary pattern: validate `unknown` bodies into compact field-level errors without echoing raw request data. * Stable docs currently mark export redaction, archive retention, and LLM provider-transfer privacy as Phase 01 hardening work. ### WebSocket Expectations * Current server connection hydration order is `connected`, `roster_update`, `notice_board_hydrate`, `scroll_state`, then `achievement_state`. * Current client message vocabulary is `hello`, `ping`, `permission_response`, `plan_approval`, `post_notice`, `collect_scroll`, and `hero_state_override`. * Historical WebSocket findings list many more event literals, but current source and stable docs remain authoritative. This session must harden only the shipped local WebSocket subset. ### Export, Archive, and Replay Expectations * `POST /export/session` must preserve JSON schema version, JSON top-level fields, CSV labels, CSV headers, and the `X-FactionOS-Export-Schema` response header. * Redaction must avoid prompt, path, command, token, secret, and URL leakage without removing useful IDs, timestamps, states, counts, or metrics. * Local archives remain audit artifacts under `~/.factionos/sessions`; redaction must be deterministic, or retained local-only risk must be explicit in code, tests, and docs. * Replay/shared payload decoding must stay bounded, version-aware, and tolerant of malformed historical entries. ## Focused Verification Commands * `npx vitest run packages/protocol/tests/events.test.ts apps/server/tests/websocket.test.ts apps/server/tests/exportSession.test.ts apps/server/tests/exportRoute.test.ts apps/web/tests/wsClientPrivacy.test.ts apps/web/tests/exportSession.test.ts apps/web/tests/replayLink.test.ts` * `npm --workspace @factionos/protocol run typecheck` * `npm --workspace @factionos/server run typecheck` * `npm --workspace @factionos/web run typecheck` * `npx biome check packages/protocol/src/events.ts packages/protocol/tests/events.test.ts packages/protocol/README_protocol.md apps/server/src/ws/clientMessageValidation.ts apps/server/src/ws/handlers.ts apps/server/src/ws/broadcaster.ts apps/server/src/lib/sessionPrivacy.ts apps/server/src/lib/sessionArchive.ts apps/server/src/lib/exportSession.ts apps/server/src/routes/export.ts apps/server/tests/websocket.test.ts apps/server/tests/exportSession.test.ts apps/server/tests/exportRoute.test.ts apps/web/src/store/useWsClient.ts apps/web/src/lib/exportSession.ts apps/web/src/lib/replayLink.ts apps/web/tests/wsClientPrivacy.test.ts apps/web/tests/exportSession.test.ts apps/web/tests/replayLink.test.ts docs/api/README_api.md docs/api/event-api-hook-contracts.md docs/privacy-and-security.md apps/server/README_server.md` * `git diff --check` * ASCII/LF validation over touched files using `file`, `grep`, or `perl` checks recorded in T024. *** ## Task Log ### 2026-05-29 - Session Start **Environment verified**: * [x] Prerequisites confirmed with `check-prereqs.sh --json --env` * [x] Directory structure ready * [x] `node`, `npm`, `vitest`, and `biome` available through workspace tooling and `npx` * [x] No database layer applies to this session ### Task T001 - Verify Session 04 prerequisites, WebSocket docs, and current route validation baseline **Started**: 2026-05-29 05:05 **Completed**: 2026-05-29 05:06 **Duration**: 1 minute **Notes**: * Confirmed active session from deterministic project analysis: `phase01-session05-websocket-hydration-and-archive-export-privacy`. * Confirmed Session 04 validation result is PASS and route validation baseline exists in `RequestValidator`. * Confirmed docs describe current WebSocket hydration order, client message types, and the export/archive privacy gap this session must close. **Files Changed**: * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md` - created baseline implementation log. **BQC Fixes**: * N/A - context and documentation baseline only. ### Task T002 - Map WebSocket, export, and archive expectations from session sources into implementation notes **Started**: 2026-05-29 05:06 **Completed**: 2026-05-29 05:07 **Duration**: 1 minute **Notes**: * Mapped current WebSocket hydration order and supported client-message vocabulary from stable API docs. * Mapped historical WebSocket findings as traceability only, without promoting typed-only or historical event names to shipped behavior. * Captured export, archive, and replay privacy expectations for later code and documentation tasks. **Files Changed**: * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md` - added session source map. **BQC Fixes**: * N/A - context and documentation mapping only. ### Task T003 - Identify focused server, web, and protocol verification commands before code changes **Started**: 2026-05-29 05:07 **Completed**: 2026-05-29 05:08 **Duration**: 1 minute **Notes**: * Confirmed `vitest` and `biome` are available via local workspace dev dependencies and `npx`. * Recorded focused Vitest, typecheck, Biome, diff, ASCII, and LF validation commands before code changes. **Files Changed**: * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md` - added focused verification command list. **BQC Fixes**: * N/A - verification planning only. ### Task T004 - Create WebSocket client-message validator with schema-validated input and explicit error mapping **Started**: 2026-05-29 05:08 **Completed**: 2026-05-29 05:16 **Duration**: 8 minutes **Notes**: * Added a pure validator that parses raw WebSocket text as `unknown`, rejects invalid JSON and non-object payloads, and narrows all supported client message shapes. * Bounded message size, IDs, notice body, targets, client IDs, severities, hero states, and preferred factions. * Invalid messages map to compact `server_toast` warnings without echoing raw payloads. * Server typecheck passed after adding the validator. **Files Changed**: * `apps/server/src/ws/clientMessageValidation.ts` - created schema validation and compact invalid-message response helper. **BQC Fixes**: * Trust boundary enforcement: all client WebSocket messages now have explicit type and bounds checks before use. * Failure path completeness: malformed messages produce a stable warning event and never throw from parsing. * Error information boundaries: invalid-message responses do not echo raw socket payloads. ### Task T005 - Create session privacy helper for prompt, path, command, token, and URL redaction **Started**: 2026-05-29 05:08 **Completed**: 2026-05-29 05:17 **Duration**: 9 minutes **Notes**: * Added deterministic placeholders for prompt, path, command, token, URL, terminal, and transcript fields. * Added redaction helpers for export heroes, export missions, tool-use metadata, arbitrary text, and archived server events. * Server typecheck passed after adding the privacy helper. **Files Changed**: * `apps/server/src/lib/sessionPrivacy.ts` - created deterministic redaction helpers for export and archive boundaries. **BQC Fixes**: * Error information boundaries: redaction removes secrets, bearer tokens, URLs, commands, prompts, paths, and terminal identifiers from sensitive output surfaces. * Contract alignment: export helpers preserve object shape and field names by replacing values with stable placeholders. ### Task T006 - Wire archive privacy boundary into session archive without crashing on filesystem or serialization failures **Started**: 2026-05-29 05:17 **Completed**: 2026-05-29 05:19 **Duration**: 2 minutes **Notes**: * Session archive now serializes the redacted event copy instead of raw server events. * Filesystem, directory creation, and serialization failures remain non-fatal and emit one-time compact warnings. * Server typecheck passed after archive changes. **Files Changed**: * `apps/server/src/lib/sessionArchive.ts` - applied archive redaction boundary and one-time warning paths. * `apps/server/src/lib/sessionPrivacy.ts` - used by archive redaction. **BQC Fixes**: * Failure path completeness: archive write and serialization failures no longer disappear silently. * Error information boundaries: archive warning messages do not echo local paths or raw payload content. ### Task T007 - Lock client-message and hydration contract expectations in protocol tests **Started**: 2026-05-29 05:19 **Completed**: 2026-05-29 05:20 **Duration**: 1 minute **Notes**: * Added protocol tests for the shipped hydration frame order and complete client-message vocabulary. * Focused protocol event tests passed: 12 tests. **Files Changed**: * `packages/protocol/tests/events.test.ts` - added hydration order and client-message union coverage. **BQC Fixes**: * Contract alignment: protocol tests now pin the server/web WebSocket contract before wiring changes. ### Task T008 - Document protocol ownership of client-message and hydration event shapes **Started**: 2026-05-29 05:20 **Completed**: 2026-05-29 05:21 **Duration**: 1 minute **Notes**: * Added protocol README ownership notes for hydration frame order and supported client message types. **Files Changed**: * `packages/protocol/README_protocol.md` - documented WebSocket protocol ownership. **BQC Fixes**: * Contract alignment: documentation now points future WebSocket changes back to protocol first. ### Task T009 - Define replay-link privacy and malformed-entry guards for bounded shared payloads **Started**: 2026-05-29 05:21 **Completed**: 2026-05-29 05:24 **Duration**: 3 minutes **Notes**: * Replay-link encoding now filters malformed entries, redacts sensitive event fields, and drops oversized single events before token creation. * Replay decoding now reuses the same event-shape and privacy guard before dispatching decoded entries. * Web typecheck passed after replay-link changes. **Files Changed**: * `apps/web/src/lib/replayLink.ts` - added replay event guard, share redaction, per-event byte cap, and decode-time sanitization. **BQC Fixes**: * Trust boundary enforcement: decoded replay events must be objects with a non-empty string `type`. * Error information boundaries: generated and decoded replay shares redact prompts, paths, commands, tokens, URLs, terminal IDs, and transcript text. * Failure path completeness: malformed and oversized replay entries are dropped instead of throwing. ### Task T010 - Validate raw WebSocket message JSON before dispatch with malformed-message no-crash behavior **Started**: 2026-05-29 05:24 **Completed**: 2026-05-29 05:27 **Duration**: 3 minutes **Notes**: * `registerWsHandlers` now routes raw socket text through `validateClientMessageText` before dispatch. * Invalid JSON, non-object payloads, oversized frames, unknown types, and field errors send compact warning frames and return without manager mutation. * Server typecheck passed after handler wiring. **Files Changed**: * `apps/server/src/ws/handlers.ts` - wired raw message validation and invalid-message response path. * `apps/server/src/ws/clientMessageValidation.ts` - provides the validator used by handlers. **BQC Fixes**: * Trust boundary enforcement: socket payloads cross the boundary as `unknown` and must validate before dispatch. * Failure path completeness: malformed input has a caller-visible warning path and does not crash the process. * Error information boundaries: warning frames do not echo raw payloads. ### Task T011 - Harden permission\_response and plan\_approval socket messages with duplicate-trigger prevention while in-flight **Started**: 2026-05-29 05:24 **Completed**: 2026-05-29 05:28 **Duration**: 4 minutes **Notes**: * Added per-socket client action claims for `permission_response` and `plan_approval` IDs. * Duplicate messages with the same request or plan ID return before resolver calls or broadcast emission. **Files Changed**: * `apps/server/src/ws/handlers.ts` - added duplicate response claim guard. **BQC Fixes**: * Duplicate action prevention: rapid duplicate approval sends cannot resolve or emit the same socket action twice for one connection. ### Task T012 - Harden post\_notice socket messages with bounded body, validated severity, and target array limits **Started**: 2026-05-29 05:24 **Completed**: 2026-05-29 05:29 **Duration**: 5 minutes **Notes**: * `post_notice` messages now reach the notice manager only after body, severity, target count, and target ID length validation. * Existing route limits are mirrored for the WebSocket boundary: 2000-character body, 50 targets, and 120-character target IDs. **Files Changed**: * `apps/server/src/ws/clientMessageValidation.ts` - added `post_notice` field validation. * `apps/server/src/ws/handlers.ts` - dispatches only parsed `post_notice` messages. **BQC Fixes**: * Trust boundary enforcement: user-authored notice fields are bounded and enum-checked before state mutation. * Contract alignment: WebSocket notice validation now matches the route validation limits. ### Task T013 - Harden collect\_scroll and hero\_state\_override socket messages with validated IDs and state enums **Started**: 2026-05-29 05:24 **Completed**: 2026-05-29 05:30 **Duration**: 6 minutes **Notes**: * `collect_scroll` now validates scroll IDs and optional hero IDs before manager calls. * `hero_state_override` now validates hero IDs and known hero state enum values before roster updates. **Files Changed**: * `apps/server/src/ws/clientMessageValidation.ts` - added scroll collection and hero state override validation. * `apps/server/src/ws/handlers.ts` - dispatches only parsed scroll and hero-state messages. **BQC Fixes**: * Trust boundary enforcement: ID and state enum checks happen before scroll or roster mutation. * Contract alignment: WebSocket state override values match the protocol `HeroState` union. ### Task T014 - Apply session privacy redaction to CSV export columns while preserving deterministic headers **Started**: 2026-05-29 05:30 **Completed**: 2026-05-29 05:32 **Duration**: 2 minutes **Notes**: * CSV export helpers now render redacted hero and mission copies before formatting rows. * Existing column headers remain unchanged while sensitive cells use deterministic placeholders. * Server typecheck passed after export helper changes. **Files Changed**: * `apps/server/src/lib/exportSession.ts` - applied CSV redaction for hero and mission rows. * `apps/server/src/lib/sessionPrivacy.ts` - provides export redaction helpers. **BQC Fixes**: * Error information boundaries: CSV output no longer exposes prompts, paths, terminal IDs, or sensitive text patterns in exported cells. * Contract alignment: CSV headers and section structure remain stable. ### Task T015 - Apply session privacy redaction to JSON export payloads while preserving top-level schema version and counts **Started**: 2026-05-29 05:30 **Completed**: 2026-05-29 05:33 **Duration**: 3 minutes **Notes**: * JSON export now preserves `exportedAt`, `schemaVersion`, `counts`, `heroes`, and `missions` while redacting nested sensitive hero, mission, and tool-use fields. * Counts continue to derive from the redacted arrays so shape and totals remain aligned. **Files Changed**: * `apps/server/src/lib/exportSession.ts` - applied JSON redaction for exported heroes and missions. * `apps/server/src/lib/sessionPrivacy.ts` - provides export redaction helpers. **BQC Fixes**: * Error information boundaries: JSON output no longer exposes prompt, transcript, path, command, token, URL, or terminal-sensitive values in redacted fields. * Contract alignment: JSON top-level schema version and counts remain stable. ### Task T016 - Validate export route options through shared request validation without echoing raw invalid payloads **Started**: 2026-05-29 05:33 **Completed**: 2026-05-29 05:36 **Duration**: 3 minutes **Notes**: * `/export/session` now validates JSON body options with `RequestValidator` and query format with the shared `invalid_request` response helper. * Invalid format responses no longer include the raw invalid value. * Added `X-FactionOS-Export-Privacy: redacted-local` and `Cache-Control: no-store` headers. * Server typecheck passed after route changes. **Files Changed**: * `apps/server/src/routes/export.ts` - added shared validation envelope, no-echo invalid responses, privacy header, and cache prevention header. **BQC Fixes**: * Trust boundary enforcement: export body and query options validate before export generation. * Error information boundaries: invalid export responses report field names and allowed values without raw input echo. * Failure path completeness: invalid body shape and format errors use explicit 400 JSON responses. ### Task T017 - Ensure broadcaster archive writes use the local archive boundary with cleanup on scope exit for acquired socket resources **Started**: 2026-05-29 05:36 **Completed**: 2026-05-29 05:38 **Duration**: 2 minutes **Notes**: * Broadcaster archive writes continue to route through `archive(event)`, which now performs redaction before persistence. * Socket attachment now registers one-shot close/error cleanup and removes its cleanup listeners when invoked. * Server typecheck passed after broadcaster cleanup changes. **Files Changed**: * `apps/server/src/ws/broadcaster.ts` - added one-shot socket cleanup with listener removal. * `apps/server/src/lib/sessionArchive.ts` - provides the redacted archive boundary used by broadcaster. **BQC Fixes**: * Resource cleanup: WebSocket clients are removed and cleanup listeners are detached on close or error. * Error information boundaries: archived broadcaster events pass through the local redaction boundary before persistence. ### Task T018 - Drop malformed incoming WebSocket frames before applying store reducers with explicit closed/offline fallback behavior **Started**: 2026-05-29 05:38 **Completed**: 2026-05-29 05:40 **Duration**: 2 minutes **Notes**: * WebSocket messages now parse through `parseServerEventFrame` and reach reducers only if they are objects with a non-empty string `type`. * Constructor failures now mark status `closed` before scheduling reconnect. * Reconnect timers are cleared when rescheduled or when the hook unmounts. * Web typecheck passed after WebSocket client changes. **Files Changed**: * `apps/web/src/store/useWsClient.ts` - added frame parser, malformed-frame drop path, closed fallback, and timer cleanup. **BQC Fixes**: * Trust boundary enforcement: incoming socket frames validate shape before store application. * Resource cleanup: reconnect timeout is cleared on unmount and before replacement. * Failure path completeness: offline constructor failures set closed status and retry instead of leaving the UI in connecting state. ### Task T019 - Preserve export download behavior while reading privacy/schema headers and reporting failure paths through toasts **Started**: 2026-05-29 05:40 **Completed**: 2026-05-29 05:43 **Duration**: 3 minutes **Notes**: * Export success results now include schema and privacy headers when present. * Success toasts include bytes, schema, privacy mode, and format without changing the download flow. * Download Blob URLs are revoked and anchors removed through a `finally` path even when click handling fails. * Error handling now converts JSON error envelopes to bounded messages before toast display. * Web typecheck passed after export helper changes. **Files Changed**: * `apps/web/src/lib/exportSession.ts` - added schema/privacy header reads, bounded error messages, and stronger download cleanup. **BQC Fixes**: * Resource cleanup: Blob URLs are revoked and temporary anchors are removed through failure and success paths. * Failure path completeness: HTTP, network, blob-read, and download errors all return explicit `ExportFailure` values for toasts. * Error information boundaries: error toasts use bounded response summaries. ### Task T020 - Add WebSocket hydration, valid client-message, malformed-message, duplicate-response, and disconnect tests **Started**: 2026-05-29 05:43 **Completed**: 2026-05-29 05:46 **Duration**: 3 minutes **Notes**: * Added real ephemeral-server WebSocket integration tests with a buffering client harness. * Covered hydration order, valid client messages, malformed input, duplicate permission responses, and socket disconnect cleanup. * Focused WebSocket test passed: 5 tests. **Files Changed**: * `apps/server/tests/websocket.test.ts` - created focused WebSocket integration test suite. **BQC Fixes**: * Contract alignment: tests lock hydration order and supported client message behavior. * Duplicate action prevention: tests confirm duplicate approval messages from one socket do not emit twice. * Resource cleanup: tests confirm client disconnects close cleanly before server shutdown. ### Task T021 - Extend export helper and route tests for redaction, schema stability, invalid options, and no raw input echo **Started**: 2026-05-29 05:46 **Completed**: 2026-05-29 05:50 **Duration**: 4 minutes **Notes**: * Added helper tests for path, terminal, prompt, URL, token, and summary redaction. * Updated route tests for shared validation envelopes, no raw invalid format echo, redacted CSV/JSON output, privacy headers, cache prevention, and malformed body validation. * Focused export tests passed: 31 tests. **Files Changed**: * `apps/server/tests/exportSession.test.ts` - extended redaction and schema stability coverage. * `apps/server/tests/exportRoute.test.ts` - extended route validation, header, and redacted response coverage. **BQC Fixes**: * Error information boundaries: tests assert raw prompts, local paths, and invalid format values do not appear in outputs. * Contract alignment: tests preserve headers, schema version, counts, and route envelope shape. ### Task T022 - Add web tests for malformed frame drops, replay privacy boundaries, and export header/error behavior **Started**: 2026-05-29 05:50 **Completed**: 2026-05-29 05:53 **Duration**: 3 minutes **Notes**: * Added focused web privacy tests for incoming WebSocket frame filtering, replay-share redaction, malformed replay entries, export schema/privacy headers, and export error toasts. * Focused web privacy/export/replay tests passed: 65 tests. **Files Changed**: * `apps/web/tests/wsClientPrivacy.test.ts` - created focused web privacy boundary test suite. * `apps/web/src/lib/replayLink.ts` - adjusted replay `inputPreview` redaction to preserve URL placeholder coverage while still redacting sensitive text. **BQC Fixes**: * Trust boundary enforcement: tests assert malformed socket frames are dropped before reducers. * Error information boundaries: tests assert replay shares remove raw prompt, path, URL, and token values. * Failure path completeness: tests assert export error envelopes surface as bounded toast bodies. ### Task T023 - Update API, contract, privacy, and server docs for WebSocket, archive, replay, and export privacy status **Started**: 2026-05-29 05:53 **Completed**: 2026-05-29 05:57 **Duration**: 4 minutes **Notes**: * Updated concise API docs, detailed event/API contract, privacy posture, and server README for WebSocket validation, redacted exports, redacted archives, replay-share redaction, and retained local-only boundaries. * Docs avoid describing exports, archives, or replay links as hosted-safe or share-safe. * Touched docs are ASCII-only after updates. **Files Changed**: * `docs/api/README_api.md` - updated WebSocket and export privacy summary. * `docs/api/event-api-hook-contracts.md` - updated detailed WebSocket, export, archive, and replay contract status. * `docs/privacy-and-security.md` - updated data inventory, controls, and remaining risks. * `apps/server/README_server.md` - updated server export, archive, and WebSocket behavior. **BQC Fixes**: * Contract alignment: stable docs now match implemented validation, redaction, and header behavior. * Error information boundaries: docs call out local-only retained risk instead of overstating share safety. ### Task T024 - Run focused server/web/protocol tests, typechecks, Biome checks, ASCII validation, LF validation, and record results **Started**: 2026-05-29 05:57 **Completed**: 2026-05-29 06:02 **Duration**: 5 minutes **Notes**: * Focused Vitest passed: 7 files, 113 tests. * Protocol typecheck passed. * Server typecheck passed. * Web typecheck passed. * Biome check passed for touched TypeScript and supported docs files. * `git diff --check` passed. * ASCII validation passed for touched files, including spec-system artifacts. * LF validation passed for touched files, including spec-system artifacts. **Files Changed**: * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md` - recorded final verification results. * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/tasks.md` - marked verification and completion checklist complete. * `.spec_system/specs/phase01-session05-websocket-hydration-and-archive-export-privacy/IMPLEMENTATION_SUMMARY.md` - added session closure summary. **BQC Fixes**: * Contract alignment: final test, typecheck, Biome, ASCII, LF, and whitespace gates all passed for the implemented behavior. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase01-session05-websocket-hydration-and-archive-export-privacy/implementation-notes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.