86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# Rooms And Access
|
|
|
|
This file owns the current room, admission, invitation, and persistence
|
|
contract. [ADR-0002](../adr/0002-memory-resident-protected-rooms.md) explains
|
|
the storage decision; implementation detail belongs in code and tests.
|
|
|
|
## Room Authority
|
|
|
|
- A room has one Host and at most 20 authenticated Viewers.
|
|
- Room codes are random free four-digit values from `1000..9999`. A code locates
|
|
a room; it is not a secret or permanent identity.
|
|
- Every room has a 256-bit Host token. The server stores only its digest; the
|
|
owning Browser keeps the raw token locally.
|
|
- Dormant rooms have a configurable lease, default 24 hours. An authenticated
|
|
online Host clears the lease deadline whether or not it is currently sharing;
|
|
Host absence starts the dormant lease. The exact Host token resumes an
|
|
unexpired room; Viewer activity never renews it.
|
|
- The Host may replace its room code. Replacement atomically creates a different
|
|
room and invalidates the old ownership, invitations, password, sessions,
|
|
routes, and media resources. It ends an active share and stops its capture
|
|
tracks; it does not migrate or automatically restart capture.
|
|
- A locally remembered preferred code is only a request. The server remains the
|
|
authority and allocates another code when that code is unavailable or expired.
|
|
|
|
## Admission Paths
|
|
|
|
Three independent authorities exist:
|
|
|
|
1. **Site access.** Production requires an independent
|
|
`SITE_ACCESS_PASSWORD`. Successful entry creates a stateless, HttpOnly,
|
|
`SameSite=Strict` cookie with a 24-hour rolling idle lifetime. An already
|
|
authorized page renews it through the site-access check while it remains
|
|
active. It authorizes room creation, Host role, and code-only Viewer
|
|
attempts; it is not a room credential, and Viewer-grant admission cannot
|
|
create or renew it.
|
|
2. **Host ownership.** The exact Host token authorizes that room's Host and
|
|
access-management operations. It cannot authorize another room.
|
|
3. **Viewer invitation.** Every room creates a 128-bit, 22-character base64url
|
|
Viewer grant. It authorizes only the Viewer role for that exact room
|
|
incarnation and bypasses site access and code-entry policy.
|
|
|
|
The invitation grant is carried in the URL fragment, removed from the address
|
|
bar on first read, and retained only in room-scoped `sessionStorage`. Refreshing
|
|
the same tab preserves it. It is not intentionally persisted across independent
|
|
tabs or Browser sessions; tab duplication and opener initialization remain
|
|
Browser behavior. The grant has no independent TTL and ends with the room or
|
|
when the Host rotates or revokes it.
|
|
|
|
Code-only admission is independent of invitations:
|
|
|
|
- `open` admits a site-authorized Viewer by room code;
|
|
- `private` without a password is invitation-only;
|
|
- `private` with a password additionally admits a site-authorized matching
|
|
code-and-password attempt.
|
|
|
|
An unknown, reclaimed, or expired code returns `ROOM_NOT_FOUND`. A current room
|
|
that refuses a code-only attempt returns the generic `ROOM_ACCESS_DENIED` result
|
|
without exposing its exact policy. Invalid grants and Host ownership failures
|
|
remain separate.
|
|
|
|
Rotating or revoking the Viewer grant is a strong authorization change. The new
|
|
generation is committed before old Viewers, signaling grace, routes, and sender
|
|
edges are closed. An affected SFU Viewer is removed by its exact LiveKit
|
|
identity and confirmed absent. This does not revoke an already issued
|
|
self-hosted LiveKit token: its subscription stays charged until that publication
|
|
generation drains. Changing code-entry policy or password affects later
|
|
code-only attempts and does not silently revoke invitations.
|
|
|
|
## Persistence Modes
|
|
|
|
- **Lightweight mode:** without `ROOM_DATABASE_PATH`, room authority is process
|
|
memory and all rooms disappear on restart.
|
|
- **Stable mode:** with an explicit SQLite path, one exact-schema owner persists
|
|
room authority across application restart.
|
|
|
|
Stable mode does not persist participants, signaling sessions, sharing state,
|
|
routes, codec decisions, quality evidence, or SFU state. After restart, clients
|
|
reauthenticate and rebuild media; a room that was active becomes dormant with a
|
|
fresh lease. [Status](../status.md) owns the selected deployment mode and
|
|
ADR-0002 owns storage validation.
|
|
|
|
The Host Browser may persist its creation preferences, including policy and an
|
|
optional room password. Raw Viewer grants never enter `localStorage`, cookies,
|
|
queries, server logs, or SQLite. Credentials, passwords, and invitation URLs are
|
|
never committed to the repository.
|