> 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/phase08-session04-war-room-and-hosted-identity-release-gate/spec.md). # Session Specification **Session ID**: `phase08-session04-war-room-and-hosted-identity-release-gate` **Phase**: 08 - Release Hardening and Legacy Decommission **Status**: Complete **Created**: 2026-05-31 **Completed**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: TypeScript protocol/Worker/web/server contracts across `packages/protocol`, `apps/warroom`, `apps/web`, `apps/server`, docs, and Phase 08 PRD artifacts *** ## 1. Session Overview This session closes the next Phase 08 release-hardening gap after local and browser erasure were implemented in Session 03. The remaining War Room gap is Durable Object room-state handling: participants, recent events, authority hashes, join-decision idempotency metadata, room revision state, and the browser hints that sit next to the Worker room. The release must either prove Worker room-state deletion with tests and docs or keep an explicit no trusted Worker-erasure claim. This plan targets a release-grade Worker room-state erasure path for the Durable Object room record while keeping the broader trusted unified erasure claim unavailable until final closeout. The session also hardens the hosted identity release gate. Phase 07 intentionally shipped hosted identity as planned or unavailable guardrails only, and Session 01 did not route active hosted auth implementation into this session. That means this session must preserve a no-hosted-identity release posture: no SSO, organization membership, account UI, production audit proof, analytics consent, public collaboration safety, or account-backed authorization claim can be made from room-local Worker authority. The work is cross-cutting. Protocol owns the request, response, claim, and no-overclaim vocabulary; the Worker owns room-boundary preview, confirmation, deletion, idempotency, partial-failure, and verification behavior; the web cockpit owns leave/reset and hosted identity copy; server and web hosted identity helpers expose release gate posture without raw values; docs record the exact claim boundary for release review. *** ## 2. Objectives 1. Add protocol-owned Worker erasure and hosted identity release gate contracts that distinguish Worker room-state deletion from full trusted unified erasure. 2. Implement a War Room Durable Object room-state erasure path with leader authority, explicit confirmation, idempotency, partial-failure handling, redacted audit output, and verification. 3. Update web and hosted identity copy so browser leave/reset and room-local authority cannot be read as hosted identity, SSO, organization membership, public collaboration safety, production audit proof, analytics consent, or trusted erasure. 4. Add focused Worker, protocol, server, and web tests plus docs that prove no-overclaim release gates for Worker erasure and hosted identity. *** ## 3. Prerequisites ### Required Sessions * [x] `phase08-session01-release-requirements-and-risk-baseline` - provides Phase 08 release claim vocabulary, risk routing, and no-overclaim standards. * [x] `phase08-session02-unified-erasure-contract-and-inventory` - provides shared erasure inventory rows, Worker boundary ids, unsupported claim vocabulary, and Worker handoff. * [x] `phase08-session03-local-erasure-runtime-and-controls` - provides local/browser erasure runtime, docs, and residual Worker/hosted limitations. * [x] `phase07-session03-hosted-identity-and-authorization-guardrails` - provides planned/unavailable hosted identity guardrail vocabulary and diagnostics. * [x] `phase06-session02-room-authority-and-participant-identity-contracts` - provides room-local authority, role, revision, and idempotency behavior that this session must enforce. ### Required Tools/Knowledge * `packages/protocol/src/warroom.ts`, `packages/protocol/src/erasure.ts`, and `packages/protocol/src/hostedIdentity.ts`. * `apps/warroom/src/index.ts`, `apps/warroom/src/authority.ts`, and `apps/warroom/src/erasureInventory.ts`. * Web War Room client, UI copy, store, and tests in `apps/web/src/lib/warRoomClient.ts`, `apps/web/src/lib/warRoomUi.ts`, `apps/web/src/store/useWarRoomStore.ts`, and `apps/web/tests`. * Hosted identity helpers in `apps/server/src/lib/hostedIdentity.ts` and `apps/web/src/lib/hostedIdentity.ts`. * Phase 08 baseline artifacts: release risk matrix, routing matrix, unified erasure inventory, release requirements risk baseline, and security-compliance findings. ### Environment Requirements * Node 20+ and npm workspaces installed. * Wrangler-compatible Worker test environment or existing fake Durable Object storage tests. * No Cloudflare, Supabase, Umami, VAPID, hosted account, provider, production credential, or real executor is required. * Tests must use synthetic Worker storage, mocked browser APIs, and sanitized fixture values only. *** ## 4. Scope ### In Scope (MVP) * Room leader can preview Worker erasure scope - Worker returns sanitized counts and statuses for Durable Object participants, recent events, authority hash metadata, join-decision idempotency metadata, room revision, and browser hint adjacency without exposing raw room payloads, authority tokens, authority hashes, participant secrets, paths, or diagnostics. * Room leader can confirm Worker room-state erasure - confirmed execution requires leader authority, expected revision, explicit confirmation phrase, and idempotency key before deleting the Durable Object room record and closing active sockets. * Worker erasure handles duplicate requests, stale authority, stale revision, missing authority, non-leader authority, room not found, already-erased rooms, and storage partial failure with explicit error mapping. * Worker erasure reports redacted audit and verification output - completed, skipped, unsupported, unavailable, and partial-failure boundaries are visible without raw values. * Hosted identity release gate records no active hosted auth - release posture proves no hosted identity, SSO, organization, account UI, production audit proof, analytics consent, public collaboration safety, or account-backed authorization claim exists. * Browser leave/reset copy distinguishes local browser context reset, Worker room-state erasure, hosted identity, and full trusted unified erasure. * Docs update War Room, hosted-services, privacy/security, release, API, deployment/environment, and runbook wording with the exact Worker erasure and hosted identity claim boundary. ### Out of Scope (Deferred) * Active Supabase auth, SSO, organization membership, hosted account UI, billing, or account-backed audit trails - *Reason: Session 01 did not route active hosted auth into this session; the release gate is no-claim.* * Hosted storage deletion, analytics deletion, public replay takedown, push subscription deletion, remote-access deletion, or hosted account deletion - *Reason: hosted surfaces remain planned, disabled, unavailable, or future-scope.* * Full trusted unified erasure release claim - *Reason: Session 08 must validate local/browser runtime plus Worker evidence and final release wording before any release-level claim changes.* * Production-hosted Worker validation - *Reason: Session 05 owns deployed Worker smoke, dashboard constraints, and sanitized production-hosted evidence.* * Mobile/accessibility certification, media release gates, and legacy decommission - *Reason: Sessions 06 and 07 own those gates.* *** ## 5. Technical Approach ### Architecture Add protocol contracts for Worker erasure preview and confirm requests, summaries, audit entries, verification results, claim labels, and no-overclaim states. Keep protocol pure and exhaustive so Worker, web, server diagnostics, and tests share the same vocabulary. Extend hosted identity release gate contracts from the existing planned/unavailable guardrail summary instead of introducing any auth runtime. Add a Worker room erasure helper that derives a sanitized preview from the existing `PersistedRoom` shape and Session 02 inventory rows. The helper should count participants, safe recent events, authority records, stale authorities, idempotency records, duplicate records, and room revision presence without returning raw participant metadata beyond bounded counts and labels. Confirmed deletion should run only after leader authority, expected revision, confirmation phrase, and idempotency key pass validation. Wire Durable Object endpoints for `/erasure/preview` and `/erasure/confirm`. The confirm endpoint should record a minimal redacted erasure receipt for duplicate handling, delete the room record, clear in-memory state, close active sockets, verify room absence, and return partial-failure output if storage deletion or verification fails. The erasure receipt must not contain authority tokens, raw authority hashes, participant names, room payloads, local paths, or hosted account identifiers. Update web and hosted identity helpers to expose the release gate clearly. Browser leave/reset remains local context cleanup. Worker erasure is room-state deletion only. Room authority remains room-local bearer proof only. Hosted identity remains no-claim unless a future scoped session ships active hosted auth evidence. ### Design Patterns * Protocol-owned release vocabulary: shared request, response, gate, no-overclaim, audit, and verification labels live in `packages/protocol`. * Boundary-nearest authorization: Worker erasure authority is enforced inside the Durable Object before storage mutation. * Explicit destructive confirmation: confirmed Worker erasure requires confirmation phrase, expected revision, and idempotency key. * Redacted audit receipts: duplicate handling can persist minimal synthetic receipt data but no room payloads, tokens, hashes, participant names, or hosted identifiers. * Partial failure over hidden failure: storage and verification failures are returned as boundary-specific partial failures. * No-overclaim copy: UI and docs distinguish browser reset, Worker room-state deletion, hosted identity, production-hosted validation, and full trusted unified erasure. ### Technology Stack * TypeScript in `packages/protocol`, `apps/warroom`, `apps/server`, and `apps/web`. * Cloudflare Worker Durable Object storage APIs through existing War Room tests and fake storage. * React 18, Zustand, Vite, and Testing Library for browser copy and state tests. * Express diagnostics helpers for local hosted identity posture. * Vitest, Biome, package-local typecheck scripts, and Markdown docs. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/warroom/src/roomErasure.ts` | Worker room erasure preview, confirmation summary, audit, verification, receipt, and redaction helper | \~260 | | `apps/warroom/tests/roomErasure.test.ts` | Unit tests for Worker erasure helper previews, receipts, redaction, verification, and partial-failure summaries | \~220 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/warroom.ts` | Add Worker erasure request/response contracts, confirmation phrase, parser helpers, status labels, and error handling | \~220 | | `packages/protocol/src/erasure.ts` | Add Worker runtime claim labels, verification/audit mapping, and unsupported claim guardrails derived from inventory | \~80 | | `packages/protocol/src/hostedIdentity.ts` | Add hosted identity release gate/no-claim summary derived from existing guardrails | \~90 | | `packages/protocol/tests/warroom.test.ts` | Add Worker erasure parser, contract, error, no-overclaim, and exhaustive enum tests | \~160 | | `packages/protocol/tests/erasure.test.ts` | Add Worker runtime claim and unsupported full-erasure contract coverage | \~80 | | `packages/protocol/tests/hostedIdentity.test.ts` | Add hosted identity release gate and unsupported claim tests | \~80 | | `apps/warroom/src/index.ts` | Wire `/erasure/preview` and `/erasure/confirm` Durable Object routes with authority, idempotency, deletion, sockets, and errors | \~240 | | `apps/warroom/src/erasureInventory.ts` | Reflect Worker room-state runtime and verification metadata without claiming full trusted unified erasure | \~80 | | `apps/warroom/tests/warroom.test.ts` | Add Durable Object route tests for erasure authority, stale revision, duplicate requests, deletion, and room absence | \~260 | | `apps/warroom/tests/worker.test.ts` | Add routed Worker tests for erasure endpoint CORS, validation, and no raw output | \~160 | | `apps/web/src/lib/warRoomClient.ts` | Add typed Worker erasure preview/confirm clients and response validation with timeout and explicit error mapping | \~180 | | `apps/web/src/lib/warRoomUi.ts` | Update leave/reset, authority, and erasure copy to distinguish browser context, Worker room-state deletion, hosted identity, and full trusted erasure | \~90 | | `apps/web/src/store/useWarRoomStore.ts` | Add optional Worker erasure state, in-flight guard, result reset, and revalidation hooks if exposed in War Room state | \~120 | | `apps/web/src/components/WarRoomPanel.tsx` | Surface no-overclaim Worker erasure and hosted identity copy without confusing leave/reset behavior | \~120 | | `apps/web/tests/warRoomClient.test.ts` | Add Worker erasure client tests for preview, confirm, timeout, malformed response, authority failure, and redaction | \~180 | | `apps/web/tests/WarRoomPanel.test.tsx` | Add no-overclaim copy tests for leave/reset, Worker erasure distinction, hosted identity, and disabled/unavailable states | \~160 | | `apps/web/tests/hostedIdentity.test.ts` | Add browser hosted identity release gate tests for no account UI, no OAuth, no SSO, no organization, and no raw authority values | \~80 | | `apps/server/src/lib/hostedIdentity.ts` | Add release gate field to diagnostics snapshot without enabling hosted account runtime | \~60 | | `apps/server/tests/hostedIdentityDiagnostics.test.ts` | Add release gate route tests for no hosted claim and no raw account/env/authority leakage | \~90 | | `docs/release.md` | Document Session 04 Worker erasure evidence, hosted identity no-claim gate, and residual full-erasure limitations | \~70 | | `docs/privacy-and-security.md` | Update security/GDPR posture for Worker room-state deletion and remaining hosted/full-erasure findings | \~70 | | `docs/api/README_api.md` | Document Worker erasure endpoints, schemas, auth boundary, errors, and redacted response limits | \~70 | | `docs/hosted-services.md` | Document hosted identity no-claim release gate and room-local authority distinction | \~50 | | `docs/environments.md` | Document that Cloudflare/hosted variables do not activate hosted identity or production validation claims | \~45 | | `docs/runbooks/war-room-operations.md` | Document Worker erasure operation, confirmation, evidence capture, and residual no-overclaim language | \~80 | | `apps/warroom/README_warroom.md` | Document Worker room-state erasure scope, endpoints, authority, idempotency, verification, and limitations | \~90 | | `apps/web/README_web.md` | Document browser leave/reset copy and Worker erasure distinction | \~45 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Worker erasure preview returns sanitized boundary summaries for participants, recent events, authority hash metadata, idempotency metadata, room revision, and browser hint adjacency without exposing raw values. * [ ] Worker erasure confirm requires room leader authority, expected revision, confirmation phrase, and idempotency key before deleting Durable Object room state. * [ ] Confirmed Worker erasure deletes the room record, clears in-memory room state, closes active sockets, verifies room absence, and returns redacted audit output. * [ ] Duplicate confirm requests with the same idempotency key return a deterministic redacted receipt without restoring or exposing room data. * [ ] Missing authority, non-leader authority, stale authority, stale revision, malformed requests, room not found, already-erased rooms, and storage partial failures return explicit mapped states. * [ ] Browser leave/reset copy remains local-only and does not imply Worker erasure, hosted identity, production-hosted validation, or full trusted unified erasure. * [ ] Hosted identity release gate reports no active hosted auth and blocks hosted identity, SSO, organization membership, public collaboration safety, analytics consent, production audit proof, and trusted erasure claims. ### Testing Requirements * [ ] Protocol Worker erasure and hosted identity release gate contract tests written and passing. * [ ] Worker helper, Durable Object route, and routed Worker tests written and passing. * [ ] Web War Room client, copy, store/component, and hosted identity tests written and passing. * [ ] Server hosted identity diagnostics release gate tests written and passing. * [ ] Manual docs/no-overclaim review completed. ### Non-Functional Requirements * [ ] Core local-first workflows still work without Cloudflare credentials, hosted credentials, Supabase, Umami, VAPID, provider keys, production hosts, or real executors. * [ ] Worker erasure outputs use boundary ids, labels, counts, booleans, docs paths, synthetic receipt ids, and status values only. * [ ] Authority tokens, authority hashes, participant secrets, room payloads, account ids, OAuth values, env values, local paths, logs, exports, replay buffers, and diagnostics payloads are not exposed. * [ ] Full trusted unified erasure remains unavailable until Session 08 validates all release-scoped boundaries and final copy. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Do not treat room-local Worker authority as hosted identity. It is bearer proof for one room only. * Worker room-state deletion is not full trusted unified erasure. Local/browser state, archives, logs, backups, exports, workspace files, hosted state, and production-hosted validation remain separate gates. * Erasure receipts must be minimal and redacted. They can support duplicate request handling but must not preserve room data. * Active sockets need explicit closure after room erasure so clients cannot keep acting on stale room state. * Browser leave/reset copy must remain distinct from Worker erasure; a user leaving a room clears local context only. ### Potential Challenges * Deleting room state while supporting duplicate confirmations: mitigate with a redacted erasure receipt keyed by an idempotency digest, not raw room data. * Partial failure in Durable Object storage: mitigate with helper-level try/catch, boundary-specific partial-failure status, and verification after deletion. * Authority race conditions: mitigate with expected revision checks and leader-authority verification inside the Durable Object before mutation. * No-overclaim drift in docs and UI: mitigate with protocol labels, focused copy tests, and a docs grep review for blocked phrases. * Fake storage parity with Cloudflare storage: mitigate by extending existing test fakes to support `delete`, failure injection, and post-delete verification. ### Relevant Considerations * \[P07] **Unified erasure deferred to Phase 08 (P07-R023)**: this session closes or gates the Worker room-state portion while full trusted unified erasure stays unavailable until final release closeout. * \[P07] **Hosted services ship as disabled-default guardrails only**: no active hosted identity claim can be made without a future scoped hosted auth implementation. * \[P06] **Room-local authority is not hosted identity**: room authority must stay separated from hosted account proof, SSO, organization membership, consent, revocation, and audit. * \[P07] **Redaction is boundary-specific**: Worker and hosted identity outputs must expose labels, counts, docs paths, booleans, and synthetic ids only. * \[P03] **Protocol leads cross-package work**: shared erasure and hosted identity release gate vocabulary belongs in protocol before app packages consume it. * \[P06] **Do not call Worker leave or reset trusted erasure**: browser leave/reset remains local context cleanup, not Worker deletion. * \[Security] **P06-S07-HOSTED-IDENTITY**: this session records no active hosted auth and blocks release overclaims. * \[Security] **P06-S07-ERASURE**: Worker room-state deletion can reduce the finding but full trusted unified erasure remains open until final release evidence. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A destructive Worker erasure request could be accepted without leader authority, fresh revision, typed confirmation, or idempotency protection. * Duplicate or replayed erasure requests could recreate, leak, or misreport erased room state. * UI, docs, diagnostics, or test fixtures could overclaim room authority as hosted identity or Worker erasure as full trusted unified erasure. * Preview, error, audit, or receipt output could leak authority tokens, authority hashes, participant names, room payloads, account ids, env values, or local paths. *** ## 9. Testing Strategy ### Unit Tests * Test protocol Worker erasure request parsing, confirmation phrase validation, idempotency key requirements, expected revision requirements, response status coverage, audit event shapes, verification methods, unsupported full-erasure labels, and no-overclaim labels. * Test hosted identity release gate summaries for no active account runtime, no OAuth, no SSO, no organization membership, no production audit proof, no analytics consent, no public collaboration safety, and no trusted erasure claim. * Test Worker erasure helper previews with present, absent, unknown, stale-authority, duplicate-idempotency, and browser-hint adjacency states. * Test Worker erasure helper receipts, redaction, completion, already-erased handling, partial failure, and verification failure. * Test web War Room client erasure calls for timeout, malformed responses, authority failures, partial failures, and no raw sensitive output. * Test web copy helpers and panel rendering for leave/reset, Worker erasure, hosted identity, disabled/unavailable states, focus behavior, and state reset on re-entry. ### Integration Tests * Run focused Vitest files for protocol, warroom, web, and server hosted identity diagnostics. * Run affected package typechecks for `packages/protocol`, `apps/warroom`, `apps/web`, and `apps/server`. * Run routed Worker tests through the existing Worker fake namespace and Durable Object fake storage. ### Manual Testing * Create a synthetic Worker room through the existing test harness or local Wrangler path, preview erasure, confirm with the expected phrase, and verify subsequent room snapshot returns room not found. * Exercise duplicate confirm with the same idempotency key and verify the redacted receipt remains deterministic without room data. * Review War Room panel leave/reset copy and hosted identity copy in local web rendering for no-overclaim wording and no layout disruption. * Review release, privacy/security, API, hosted-services, environment, and War Room runbook docs for blocked hosted identity and trusted erasure claims. ### Edge Cases * Room does not exist. * Room already erased. * Missing authority. * Expired or mismatched authority. * Non-leader authority. * Stale expected revision. * Duplicate idempotency key with matching request. * Replayed idempotency key with different request. * Durable Object storage delete throws. * Verification reads stale room state after delete. * Active sockets exist during erase. * Recent events contain blocked payload fields. * Hosted identity env vars are present but no active account runtime exists. * Browser storage contains Worker hints while Worker room state is erased. *** ## 10. Dependencies ### External Libraries * None new planned. Use existing TypeScript, Worker Durable Object APIs, React/Zustand, Express diagnostics helpers, and Vitest/Testing Library setup. ### Other Sessions * **Depends on**: `phase08-session03-local-erasure-runtime-and-controls` * **Depended by**: `phase08-session05-production-hosted-validation-and-deploy-smoke`, `phase08-session08-release-candidate-validation-and-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/phase08-session04-war-room-and-hosted-identity-release-gate/spec.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.