> 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/phase06-session02-room-authority-and-participant-identity-contracts/spec.md).

# Session Specification

**Session ID**: `phase06-session02-room-authority-and-participant-identity-contracts` **Phase**: 06 - Collaboration, Isolation, and Mobile **Status**: Completed **Created**: 2026-05-30 **Package**: Cross-package (`packages/protocol`, `apps/warroom`, `apps/web`) **Package Stack**: TypeScript, Cloudflare Workers, Durable Objects, React 18, Vite, Zustand, Vitest

***

## 1. Session Overview

This session strengthens the optional War Room authority model so room, leader, participant, approval, reconnect, and duplicate-action behavior no longer depends only on caller-supplied browser metadata. The work remains non-hosted: there is no account lifecycle, OAuth, SSO, organization membership, hosted storage, analytics, public replay hosting, remote execution, or trusted erasure claim.

Protocol contracts lead the change. Shared authority, revision, expiration, idempotency, and deterministic error shapes should be added in `packages/protocol`, then consumed by the Cloudflare Worker in `apps/warroom` and the browser state/client surface in `apps/web`.

The result should preserve Phase 05 behavior for local-only fallback, leader-only approval, compact diagnostics, sender-excluded redacted federation, and bounded reconnect catch-up while making stale, duplicate, expired, malformed, mismatched, and replayed authority inputs produce explicit outcomes.

***

## 2. Objectives

1. Define shared room and participant authority contracts with revision, expiration, idempotency, role, and deterministic error metadata.
2. Enforce authority in Worker create, join, approve, reject, snapshot, socket, reconnect, disconnect, and leave-adjacent browser flows without adding hosted accounts.
3. Update the web client and store to preserve local-only fallback, separate display hints from authority state, and surface bounded authority failures.
4. Add focused protocol, Worker, and web coverage for success, duplicate, stale, expired, malformed, mismatched, replayed, reconnect, and unavailable flows.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase05-session07-war-room-validation-and-documentation-closeout` - Provides the shipped optional Worker lifecycle, diagnostics, approval, presence, reconnect, catch-up, sender-excluded federation, and local browser evidence baseline.
* [x] `phase06-session01-collaboration-requirements-and-safety-baseline` - Provides the Phase 06 safety baseline, routing matrix, mobile checklist, and authority requirements.

### Required Tools/Knowledge

* Node 20+ and npm workspaces.
* TypeScript 5.9, Vitest, React Testing Library, and package-local typecheck commands.
* Cloudflare Worker and Durable Object request, storage, and WebSocket behavior.
* Existing War Room contracts in `packages/protocol/src/warroom.ts`.
* Existing Worker tests in `apps/warroom/tests/warroom.test.ts`.
* Existing web client/store/component tests in `apps/web/tests/`.

### Environment Requirements

* Cloudflare credentials are optional and must not be required for focused tests.
* No checked-in authority secrets, signing keys, account ids, tokens, or hosted identity fixtures.
* Local and mocked Worker paths must remain sufficient for implementation and validation.

***

## 4. Scope

### In Scope (MVP)

* Protocol consumers can use deterministic authority contracts for room, leader, participant, requester, approver, role, approval state, expected revision, expiration, and idempotency - Add shared types, validators, error codes, and test coverage before Worker/web wiring.
* Worker participants can rely on Worker-issued room-local authority instead of browser id hints alone - Issue, verify, expire, rotate, and reject authority metadata inside the room boundary without hosted accounts.
* Leaders can approve and reject pending joins deterministically - Enforce leader authority, expected revision, duplicate decision handling, and stale or replayed decision errors.
* Approved participants can reconnect safely - Require participant authority for socket setup and refresh or clear stale state when authority no longer matches the room snapshot.
* Browser users can understand authority status and failures - Show bounded copy for expired, mismatched, replayed, stale, non-leader, rejected, forbidden, unavailable, and rate-limited flows without implying hosted identity.
* Documentation readers can see the limits of the non-hosted authority model - Update package READMEs and stable docs with proof limits and Phase 07/08 deferrals.

### Out of Scope (Deferred)

* Hosted account lifecycle, OAuth, Supabase, SSO, organization membership, billing, account recovery, or account-backed identity - Reason: Phase 07 or later hosted-service work owns account lifecycle.
* Hosted storage, public replay hosting, analytics dashboards, push notifications, or production-hosted validation - Reason: Phase 07/08 owns hosted and release validation guardrails.
* Real command execution, remote control, inbound chat commands, Docker isolation, or hosted queues - Reason: Session 05 owns isolation posture and later threat models before execution.
* Trusted unified erasure for Worker storage, browser hints, logs, archives, exports, replay buffers, backups, or future hosted data - Reason: Phase 08 owns erasure design.

***

## 5. Technical Approach

### Architecture

`packages/protocol` remains the source of truth for shared War Room authority contracts. Add role, revision, expiration, idempotency, authority envelope, and error vocabulary there first so Worker and web code do not redefine shapes.

`apps/warroom` should keep authority room-local and non-hosted. A Worker-issued authority token or opaque proof can be stored and verified inside the Durable Object room boundary, scoped to a participant, role, room code, room revision, and expiration. This is stronger than hint-only browser metadata but is not an account-backed identity proof.

`apps/web` should treat authority metadata as room state, not account state. Display names, colors, roles, and online flags remain browser hints. The store should clear or revalidate stale authority on Worker URL changes, storage hydration, reconnect, join decisions, leave, and reset. UI copy must remain bounded and must not show raw tokens or imply hosted identity or trusted erasure.

### Design Patterns

* Protocol-first contracts: Shared request, response, socket, and error shapes are added before Worker and web consumers.
* Fail-closed validation: Unknown fields, malformed authority, expired authority, mismatched participants, stale revisions, and replayed decisions return compact deterministic envelopes.
* Room-local bearer limits: Authority can prove possession of a Worker-issued room token, not a hosted account or real-world identity.
* Idempotent mutation paths: Duplicate create, join, approve, reject, connect, disconnect, leave, and retry triggers are guarded in browser state and deterministic in Worker responses.
* Visible failure mapping: Web copy maps authority failures to short user-safe messages without echoing payloads, tokens, URLs, paths, or request bodies.

### Technology Stack

* TypeScript 5.9 shared contracts and tests in `packages/protocol`.
* Cloudflare Workers, Durable Objects, WebSocket, and Wrangler 4.x in `apps/warroom`.
* React 18.3, Vite 6.4, Zustand 4.5, browser fetch/WebSocket/localStorage APIs, and React Testing Library in `apps/web`.
* Vitest 4.1 for focused protocol, Worker, and web tests.
* Biome and package-local `tsc` typechecking for quality gates.

***

## 6. Deliverables

### Files to Create

| File                                                                                                             | Purpose                                                                                         | Est. Lines |
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- |
| `apps/warroom/src/authority.ts`                                                                                  | Room-local authority issue, verify, expiration, rotation, and replay/idempotency helper         | \~220      |
| `apps/warroom/tests/authority.test.ts`                                                                           | Focused helper tests for valid, expired, mismatched, replayed, duplicate, and rotated authority | \~180      |
| `.spec_system/specs/phase06-session02-room-authority-and-participant-identity-contracts/implementation-notes.md` | Implementation evidence, command results, and decisions                                         | \~120      |

### Files to Modify

| File                                       | Changes                                                                                                   | Est. Lines |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/warroom.ts`         | Add authority, revision, expiration, idempotency, and error contracts plus validators                     | \~180      |
| `packages/protocol/tests/warroom.test.ts`  | Add protocol authority contract and validator coverage                                                    | \~160      |
| `apps/warroom/src/index.ts`                | Enforce authority for create, join, approve, reject, snapshot, socket, reconnect, and duplicate decisions | \~260      |
| `apps/warroom/tests/warroom.test.ts`       | Extend Worker lifecycle and socket tests for authority failure paths                                      | \~260      |
| `apps/web/src/lib/warRoomClient.ts`        | Add authority-aware REST and socket client handling and failure mapping                                   | \~180      |
| `apps/web/src/lib/warRoomIdentity.ts`      | Keep display hints separate from authority and clear stale room authority                                 | \~80       |
| `apps/web/src/store/useWarRoomStore.ts`    | Track authority status, revision, expiration, duplicate guards, and revalidation behavior                 | \~240      |
| `apps/web/src/lib/warRoomUi.ts`            | Add bounded authority copy and error labels                                                               | \~80       |
| `apps/web/src/components/WarRoomPanel.tsx` | Display authority status and failure feedback accessibly                                                  | \~120      |
| `apps/web/tests/warRoomClient.test.ts`     | Add client authority success and error mapping tests                                                      | \~160      |
| `apps/web/tests/warRoomStore.test.ts`      | Add store authority, stale hydration, duplicate, reconnect, and failure tests                             | \~220      |
| `apps/web/tests/WarRoomPanel.test.tsx`     | Add accessible visible authority state and failure tests                                                  | \~160      |
| `packages/protocol/README_protocol.md`     | Document protocol authority ownership and proof limits                                                    | \~40       |
| `apps/warroom/README_warroom.md`           | Document Worker authority behavior and non-hosted identity limits                                         | \~60       |
| `apps/web/README_web.md`                   | Document browser authority state, local-only fallback, and stale-state behavior                           | \~60       |
| `docs/api/README_api.md`                   | Document authority-aware Worker API shapes and compact errors                                             | \~80       |
| `docs/privacy-and-security.md`             | Update data inventory and transfer boundary for authority metadata                                        | \~80       |
| `docs/runbooks/war-room-operations.md`     | Update operational notes for authority failures and non-erasure limits                                    | \~60       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Room and participant authority is stronger than hint-only browser metadata without requiring hosted accounts.
* [ ] Stale, duplicate, expired, malformed, mismatched, and replayed authority inputs produce deterministic Worker and web outcomes.
* [ ] Leader-only approval and rejection enforce leader authority and expected room revision.
* [ ] Socket setup and reconnect require valid approved participant authority.
* [ ] Browser state clears or revalidates stale authority on Worker URL changes, storage hydration, reconnect, leave, and reset.
* [ ] UI copy does not imply hosted identity, account proof, trusted erasure, public collaboration safety, or remote execution.

### Testing Requirements

* [ ] Protocol authority validators and type contracts are covered.
* [ ] Worker authority helper and lifecycle routes are covered.
* [ ] Web client, store, and panel authority behavior is covered.
* [ ] Focused package typechecks pass for protocol, Worker, and web packages.
* [ ] Manual implementation notes record command results and residual risks.

### Non-Functional Requirements

* [ ] Authority payloads remain compact and bounded.
* [ ] Error envelopes do not echo raw request bodies, tokens, URLs, paths, prompts, command output, diagnostics, logs, exports, or replay buffers.
* [ ] No checked-in secrets, signing keys, account ids, or hosted identity fixtures are introduced.
* [ ] Local-only cockpit workflows remain usable when Worker URL, Cloudflare credentials, hosted services, analytics, and public replay hosting are absent.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `npm --workspace packages/protocol run typecheck` passes.
* [ ] `npm --workspace @factionos/warroom run typecheck` passes.
* [ ] `npm --workspace @factionos/web run typecheck` passes.
* [ ] Focused War Room-related Vitest coverage passes.

***

## 8. Implementation Notes

### Key Considerations

* Treat participant names, colors, roles, online flags, and local participant hints as display metadata, not account proof.
* Keep authority tokens or opaque proofs out of visible copy, logs, diagnostics, socket federation frames, replay, export, settings, and docs examples.
* Avoid designs that require Cloudflare secrets or hosted auth to run local tests.
* Document proof limits directly: room-local Worker authority reduces spoofing and stale decisions, but it is not hosted identity.

### Potential Challenges

* Token storage risk: Keep authority scoped, bounded, expiring, and absent from shared collaboration payloads.
* Durable Object replay behavior: Store only compact idempotency and authority metadata needed to reject duplicate or stale actions deterministically.
* Browser hydration drift: Clear or revalidate stale room authority whenever Worker URL, room code, participant id, room revision, or role no longer matches the latest safe snapshot.
* Compatibility with Phase 05 tests: Preserve current local-only fallback, leader approval, reconnect, catch-up, and redacted federation behavior while adding authority requirements.

### Relevant Considerations

* \[P05] **Unified erasure still missing**: Leave, reset, disconnect, and local storage cleanup must not claim trusted deletion for Worker state, browser hints, archives, logs, exports, replay buffers, backups, or future hosted data.
* \[P05-apps/warroom+apps/web] **War Room federation is optional and redacted**: Authority work must not turn optional Worker transfer into hosted auth, hosted storage, analytics, public replay hosting, or remote execution.
* \[P05] **Redaction is boundary-specific**: Authority metadata safe for a room control request is not automatically safe for logs, diagnostics, replay, export, adapter, backup, or docs output.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Shared authority contracts start in `packages/protocol` before Worker or web code depends on them.
* \[P03] **Local-first boundary is architectural**: The browser and local cockpit must continue to degrade cleanly when Cloudflare, hosted services, public tokens, provider credentials, and analytics are absent.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Expired or replayed authority could be accepted after stale local storage, duplicate joins, duplicate decisions, or socket reconnect.
* UI copy could accidentally imply hosted identity, account-backed proof, public collaboration safety, remote execution, or trusted erasure.
* Worker and browser state could diverge if approvals, rejects, reconnects, disconnects, Worker URL changes, or room revisions are not revalidated.

***

## 9. Testing Strategy

### Unit Tests

* Protocol parser tests for authority envelopes, expected revision, expiration, idempotency keys, new error codes, role coverage, and unknown-field rejection.
* Worker authority helper tests for issue, verify, expiration, mismatch, rotation, replay, and duplicate idempotency behavior.
* Web client tests for authority-aware request bodies, socket URL handling, and compact error mapping.
* Web helper tests for bounded authority copy and no raw token display.

### Integration Tests

* Worker route tests for create, join, approve, reject, snapshot, socket, reconnect, duplicate decisions, stale decisions, expired authority, mismatched participant, and forbidden participant outcomes.
* Web store tests for create, join, approve, reject, connect, retry, leave, reset, Worker URL change, storage hydration, stale state, and unavailable Worker flows.
* Component tests for visible authority state, pending/approved/rejected states, non-leader decisions, duplicate-action disabled states, accessible labels, and bounded failure messages.

### Manual Testing

* Review the War Room panel in local-only, approved, pending, rejected, expired, reconnecting, unavailable, and left states.
* Confirm no visible copy exposes raw tokens, room authority values, request bodies, private URLs, paths, prompts, command output, diagnostics, logs, or hosted identity claims.
* Confirm docs describe non-hosted authority limits and Phase 07/08 deferrals.

### Edge Cases

* Duplicate join with the same participant id before and after room-full checks.
* Duplicate approve/reject with same and conflicting idempotency keys.
* Non-leader decision attempts with otherwise valid-looking authority.
* Expired or mismatched leader authority.
* Approved participant reconnect after room revision change.
* Pending participant socket setup.
* Worker URL changed while authority-bearing state is still present.
* Malformed authority objects and unknown request fields.
* Storage hydration with stale participant id, role, room code, or authority.

***

## 10. Dependencies

### External Libraries

* No new runtime library is expected.
* Existing dependencies: TypeScript 5.9, Vitest 4.1, React 18.3, Zustand 4.5, Vite 6.4, Wrangler 4.x.

### Other Sessions

* **Depends on**: `phase05-session07-war-room-validation-and-documentation-closeout`, `phase06-session01-collaboration-requirements-and-safety-baseline`
* **Depended by**: `phase06-session03-shared-collaboration-event-contracts`, `phase06-session04-collaborative-cockpit-ux-and-remote-context`, `phase06-session07-collaboration-isolation-and-mobile-validation-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/phase06-session02-room-authority-and-participant-identity-contracts/spec.md?ask=<question>&goal=<endgoal>
```

`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.