> 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/phases/phase_05/war_room_requirements_trust_baseline.md). # War Room Requirements And Trust Baseline **Phase**: 05 - War Room Worker Integration **Session**: 01 - War Room Requirements and Trust Baseline **Status**: Baseline for later implementation sessions **Last Updated**: 2026-05-29 *** ## Purpose This document is the source-backed Phase 05 contract for War Room room lifecycle, participant trust, authority, approval, reconnect, catch-up, unavailable states, and Worker transfer boundaries. It reconciles the current Cloudflare Worker backend, web cockpit stub, protocol types, local server stub, tests, stable docs, ADR, deployment posture, and Phase 05 PRD stubs before Worker/client implementation begins. This session does not ship web-to-Worker federation. The Worker backend exists today, the web panel is still a disabled stub, and the local server exposes only a compatibility/status stub at `/warroom`. ## Source Inventory | Source | Current evidence | Baseline implication | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `apps/warroom/src/index.ts` | Worker handles `/`, `/health`, `POST /rooms`, `GET /rooms/:code`, `POST /rooms/:code/join`, `POST /rooms/:code/approve`, and `WS /rooms/:code/socket?participant=:id`. | Worker is the only current room relay. Later sessions harden schemas, errors, signatures, and redaction before web use. | | `apps/warroom/src/index.ts` | Durable Object stores one room per code, leader id, participants, online flags, and a recent-event ring buffer. | Room state is isolated by room code and bounded, but current event payloads remain schema-loose. | | `apps/warroom/tests/warroom.test.ts` | Covers init, info, join pending, full room, approve, non-leader reject, socket guards, catch-up, sender exclusion, ring cap, persistence, and disconnect behavior. | These behaviors are current evidence for later Worker contract hardening. | | `apps/warroom/tests/worker.test.ts` | Covers landing page, health, CORS, room creation, snapshot reads, code regex, malformed codes, DO isolation, and delegated join. | Browser access, deployment health, room code shape, and CORS behavior are current source facts. | | `apps/web/src/components/WarRoomPanel.tsx` | Renders a disabled War Room panel with read-only room code and disabled action. | Web cockpit must continue to be honest until create/join/connect controls are implemented. | | `apps/web/src/lib/cockpitShell.ts` | Marks War Room as `deferred` and describes it as a separate Worker surface. | Shell metadata must keep stub, unavailable, and local-only states visible. | | `packages/protocol/src/warroom.ts` | Defines `WarRoomRole`, `Participant`, and `WarRoomState`. | Protocol owns shared room shapes before Worker and web consumers diverge. | | `packages/protocol/src/events.ts` | Defines War Room event scaffolding including joined, reconnecting, participant change, join request, join decision, and catch-up event names. | Event vocabulary exists but needs shared schema hardening before broad federation. | | `packages/protocol/src/rest.ts` | Defines `warroom-local`, `warroom-worker`, `stubbed`, `typed-only`, and `separate-surface` route statuses. | Stable docs can distinguish local stub routes from Worker routes. | | `apps/server/src/routes/heroes.ts` | `GET /warroom` returns local compatibility metadata, null room state, and Worker separate-surface metadata. | Local server remains a status stub and must not proxy room traffic in Phase 05. | | `apps/server/src/lib/unsupportedRoutes.ts` | `/rooms` and `/warroom/*` classify as `warroom-worker` separate-surface on the local server. | Unsupported local room routes must stay deterministic, not accidental 404 or partial proxy behavior. | | `docs/adr/0002-cloudflare-worker-war-room.md` | Accepts Cloudflare Worker plus Durable Object as the room relay, optional for local development. | Local server relay was rejected; web wiring is Phase 05 work. | | `docs/api/event-api-hook-contracts.md` | Documents `/warroom` as stubbed and Worker room routes as separate surface. | API docs must keep shipped local server behavior separate from Worker behavior. | | `docs/privacy-and-security.md` | Lists Worker room participants and relayed events as Cloudflare transfer when deployed and used. | Federation is optional external transfer and must be minimized. | | `docs/deployment.md` | Documents Worker custom domain, workers.dev URL, health checks, deploy workflow, rate limit, and WAF posture. | Cloudflare deployment is operable but not required for core local workflows. | | `docs/hosted-services.md` | Keeps Cloudflare Worker optional and separate from hosted auth, storage, analytics, and public replay. | Phase 05 must not imply broader hosted product surfaces are shipped. | ## Current Shipped And Planned Boundary | Surface | Current status | Phase 05 boundary | | --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Worker backend | Shipped separate surface with tests. | Session 02 hardens schemas, deterministic errors, client contracts, and redaction gates. | | Durable Object room storage | Stores participant metadata and recent room events. | Keep room state bounded; do not store sensitive local developer payloads. | | Web War Room panel | Disabled stub. | Session 03 replaces it with local-first create, join, connect, disconnect, and fallback state. | | Approval and presence UX | Worker primitives exist; cockpit UX is not wired. | Session 04 implements accessible leader approval, pending, presence, reconnect, and catch-up UX. | | Federation payloads | Worker currently accepts unknown socket event payloads. | Session 05 implements allowlisted redacted cockpit events only. | | Local server `/warroom` | Stubbed compatibility/status metadata. | Must remain a local status stub, not a Worker proxy. | | Protocol contracts | Typed scaffolding only for several War Room events. | Protocol changes lead Worker and web changes. | | Deployment diagnostics | Worker deployment and health docs exist. | Session 06 owns environment configuration, diagnostics, and runbook detail. | ## Room Lifecycle Vocabulary | State | Trigger | Required behavior | Owner | | -------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `local-only` | Worker URL is missing, disabled, or not configured. | Core cockpit remains usable; War Room controls show local-only copy and no external transfer. | Session 03 | | `unavailable` | Worker health, room fetch, create, join, approve, or socket fails; Cloudflare is down; request is rate-limited. | Surface explicit failure, retry or local-only affordance, and no blank panel. Do not discard local cockpit state. | Sessions 03, 04, 06 | | `create` | Leader starts a new room through `POST /rooms`. | Worker returns a short room code and leader participant. The local server is not involved. | Session 02 | | `connected` | Approved participant opens a Worker socket successfully. | Client receives `warroom_joined`, roster state, and future allowed frames. | Sessions 02, 03 | | `join` | Participant submits a valid room code and local display identity. | Worker creates or returns a participant record and normally enters pending state. | Sessions 02, 03 | | `pending` | Join request awaits leader approval. | Pending participant cannot open the room socket. Leader sees an approval request. | Sessions 02, 04 | | `approved` | Leader approves a pending participant. | Pending role becomes member, participants update, and socket access becomes allowed. | Sessions 02, 04 | | `rejected` | Leader rejects a pending participant or future policy denies the request. | Participant sees rejected copy and cannot connect. Current Worker needs the deterministic route and event contract. | Sessions 02, 04 | | `reconnecting` | Existing socket closes or browser detects transport loss. | Client preserves room context, disables duplicate connect actions, and retries within bounded policy. | Sessions 03, 04 | | `caught-up` | Reconnecting client receives bounded recent-event replay. | Client applies only allowlisted redacted frames and reports catch-up completion or failure. | Sessions 04, 05 | | `disconnected` | Participant socket closes or the browser intentionally disconnects. | Participant is offline, local cockpit remains usable, and reconnect or leave options are visible. | Sessions 03, 04 | | `left` | Participant intentionally exits a room. | Local room state clears or returns to local-only. Current Worker needs explicit leave semantics if persistent removal is required. | Sessions 02, 04 | The UI may present user-friendly copy, but implementation and tests should use these canonical state names where practical. ## Participant Trust Model ### Identities * Current participant ids and display names are caller-provided. Treat them as untrusted hints until Session 02 adds stronger room/client contracts. * Participant ids must be bounded, non-empty, and generated locally when not supplied. They must not encode local usernames, home directories, workspace paths, tokens, or transcript paths. * Display names are presentation metadata only. They do not prove authority. * Colors are local presentation hints and must not carry semantic authority. ### Roles | Role | Meaning | Current support | | ------------ | ------------------------------------------------------------ | --------------------------------------------------------------------- | | `leader` | Room creator with authority to approve pending participants. | Current Worker stores `leaderId` and checks approver id for approve. | | `member` | Approved participant allowed to connect to the socket. | Current Worker sets member on approval. | | `observer` | Non-mutating viewer role for later UX or policy. | Protocol role exists; Worker route behavior is not yet defined. | | `pending` | Participant waiting for leader approval. | Current Worker creates pending participants and blocks socket access. | | `rejected` | Not a protocol role today; a decision state. | Later sessions need deterministic reject contract and UX. | | `local-user` | Browser user outside a Worker room or in local-only mode. | Web stub exists; Session 03 owns local state. | ### Authority And Approval * Only the leader may approve pending participants. * Approval must reference the pending participant id and the leader authority token or equivalent future proof, not display name. * Non-leader approval attempts must fail with deterministic 403-style errors. * Missing pending participants must fail with deterministic not-found or stale approval errors. * Duplicate approve, reject, join, connect, disconnect, reconnect, and leave actions must be guarded in the web UI while in flight and must be safe on the Worker side. * A participant in `pending` or `rejected` state must not open a room socket. * Room-full behavior must stay explicit. Current cap is 16 participants. ### Stale And Duplicate Handling * Duplicate `/init` should not clobber an existing room. Current tests cover idempotent init. * Duplicate `/join` with the same participant id returns the existing participant. Later sessions should preserve idempotency and clarify whether stale pending timestamps refresh. * Approval after rejection, approval after prior approval, approval after participant leave, and approval after room disposal must return deterministic stale or conflict errors. * Reconnect must revalidate participant state before accepting a socket. ### Spoofing Constraints * The Worker must not trust browser-supplied participant ids, approver ids, display names, event `from` fields, or role fields without server-side authorization. * The browser must not treat a participant row as trusted identity, account identity, hosted auth, or collaboration account state. * Future signed room, leader, or participant tokens are Session 02 scope. * Local server bearer tokens are for loopback server access and must not be reused as Worker authority. ## Worker Federation Boundary War Room federation is optional external transfer. A user entering or creating a room may send data to Cloudflare Durable Objects when the Worker is deployed and used. The transfer baseline is: * Allow compact room and participant metadata only. * Allow only protocol-defined, schema-validated, redacted collaboration events. * Reject or drop unknown event types before persistence, catch-up, logging, or browser consumption. * Keep catch-up bounded to the recent-event cap and the same payload allowlist. * Do not relay prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, media drafts, or scan payloads. * Do not claim trusted deletion for room data, browser hints, logs, archives, exports, backups, or future hosted records. Phase 08 owns unified erasure. Detailed payload rules live in `.spec_system/archive/phases/phase_05/war_room_payload_redaction_baseline.md`. ## Local-First Requirements * Core cockpit behavior must work without Cloudflare credentials, Worker deployment, hosted auth, hosted storage, analytics, public replay hosting, media provider keys, or any external transfer. * Worker failures must not break local mission, hero, replay, export, scan, orchestration, media, or settings workflows. * Local `/warroom` must remain compatibility/status metadata unless a future PRD adds a separate local relay threat model. * Stable docs and UI copy must distinguish: * shipped Worker backend, * current web stub, * local server status stub, * optional Cloudflare deployment, * planned web federation, * deferred hosted surfaces. ## Later-Session Handoff * Session 02 owns Worker schema hardening, deterministic errors, shared client contracts, stronger participant authority, and focused Worker tests. * Session 03 owns browser room lifecycle state, create/join/connect/disconnect controls, local-only fallback, and Worker-unavailable presentation. * Session 04 owns leader approval, rejected and pending UX, presence, reconnect, catch-up, leave behavior, and accessibility tests. * Session 05 owns redacted federation event allowlist, sender-excluded cockpit updates, replay/export/log adjacency, and payload tests. * Session 06 owns Worker URL configuration, environment diagnostics, health, rate-limit, deployment, and runbook details. * Session 07 owns end-to-end validation, documentation closeout, security review, and phase handoff. --- # 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/phases/phase_05/war_room_requirements_trust_baseline.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.