Collab Phase 1: Websocket Server Skeleton, Auth, and Presence Rooms

[cubap]

Summary

Add websocket infrastructure to TPEN-services for authenticated collaboration sessions and presence events.

Scope

• Initialize websocket server alongside HTTP server startup.
• Validate bearer tokens during websocket handshake.
• Authorize room joins by project permission.
• Support rooms: project:{projectId} and project:{projectId}:page:{pageId}.
• Emit and relay presence events: join, leave, cursor, selection.
• Feature flag websocket collaboration.

Acceptance Criteria

• Authenticated users can connect and join allowed rooms.
• Unauthorized joins are rejected.
• Presence fanout works for at least 2 concurrent users in same page room.
• Feature flag fully disables websocket endpoints.

Notes

Contract baseline: docs/collaboration/websocket-collaboration-contract.md

[cubap]

Dependency map for execution planning:

Depends on:

• Collaboration Contract v1.0 Ratification for Services, Interfaces, and RERUM #512

Blocks:

• Collab Phase 2: Realtime Client and Presence UI (No Save Behavior Change Yet) TPEN-interfaces#555
• Collab Phase 3: Draft Buffer API and Operation Intake for Deferred Persistence #510

Related to:

• Collab Phase 5: Durable Flush Worker from Drafts to RERUM with Conflict Acks #511

[cubap]

Phase Documentation Addendum

• This phase defines websocket transport/auth/room semantics and must follow Contract sections 3, 4, 5, and presence events in section 6.
• Required validation: auth handshake, permission-gated joins, presence fanout under at least two active collaborators.
• Exit artifacts: event samples, connection failure matrix, and feature-flag off behavior proof.

[cubap]

Phase Documentation Addendum

• This phase defines websocket transport/auth/room semantics and must follow Contract sections 3, 4, 5, and presence events in section 6.
• Required validation: auth handshake, permission-gated joins, presence fanout under at least two active collaborators.
• Exit artifacts: event samples, connection failure matrix, and feature-flag off behavior proof.