Authentication and Connection

Strata v0 uses one shared secret. The application sends the secret as a token when it opens a WebSocket connection. The server checks the token before it accepts the connection. Authentication is not a WebSocket frame.

Endpoint and token

WebSocket endpoint

ws://<host>:8000/socket/websocket?token=<STRATA_TOKEN>

• The server reads the shared secret from STRATA_TOKEN. If the variable is unset, the server uses dev-strata-token. Use this default only for local development.
• The server returns HTTP 403 for a missing or incorrect token. It compares the values in constant time.
• All connections that use the token have access to all documents and admin data. The current server is single-tenant. Client-side user checks and document ID prefixes cannot restrict a token holder's access.

For groups that must not share access, use separate Strata deployments with separate tokens and storage directories. The session_id in welcome identifies a socket connection, not an authenticated user or tenant.

The server does not verify JWT signatures, expiry, or tenant claims. Putting a JWT in ?token= does not enable JWT authentication; the server still compares the whole value with the configured shared secret.

See Security Model before you expose Strata outside a local development environment.

Connection flow

1. Open the WebSocket with the token in the URL.
2. Receive a welcome frame carrying your session_id.
3. Send a join frame for each document that the application must open.
4. Receive a snapshot for each joined document, then a stream of delta, presence_state, and presence_diff frames.
5. Send ping messages if the connection must remain active when there is no other traffic. The server answers with pong.

presence_state contains the full presence state for the document. presence_diff contains the changes after that state.

Reconnect

A disconnect removes every document join and presence entry for that connection. The bundled examples reconnect with strata_client:

1. After the connection closes, wait 2 seconds and open a new connection.
2. Call strata_client.frames_for_resume to get the join frames for every previous document.
3. Send the returned join frames.
4. Send presence_set for each document.
5. Merge each incoming snapshot into the local CRDT state.

Do not replace the local CRDT state after a reconnect. Replacement can remove local changes that the application made while it was offline.

See strata_client for the connection logic and examples/kanban for a working implementation.

The examples use a fixed two-second retry delay. A deployed application should use exponential backoff with jitter. It should also stop after a suitable limit or show a manual retry control.

Roadmap

Issue #3 tracks JWT and multi-tenant authentication. The proposal keeps the current ?token= URL shape.