Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(access): add private room password entry (#77)
AAAded55bcd7d2e
diff --git a/docs/adr/0002-persistent-protected-rooms.md b/docs/adr/0002-persistent-protected-rooms.mdindex 715d37f1..b0ac405c 100644--- a/docs/adr/0002-persistent-protected-rooms.md+++ b/docs/adr/0002-persistent-protected-rooms.md@@ -1,6 +1,6 @@# ADR-0002: Persistent Rooms And Scoped Viewer Access-- Status: Accepted; runtime candidate implemented, deployment pending+- Status: Accepted; grant boundary deployed, room-password extension source-only- Date: 2026-08-19## Context@@ -11,18 +11,19 @@ so the deployment owner must control Host admission. Watching should remain anormal-browser, link-first action and should not reveal the deployment's Hostpassword to every invited friend.-The superseded runtime and current production deployment use one optional-`ACCESS_PASSWORD`, one stateless cookie,-and the same WebSocket upgrade gate for both roles. A Viewer then authenticates-with only a numeric room code. This is simple but conflates deployment admission-with room privacy: sharing the site password grants broader access than a Viewer-needs, while disabling it makes a random room code the only weak capability.-Persistent sequential IDs make that problem more visible.+The superseded runtime used one optional `ACCESS_PASSWORD`, one stateless cookie,+and the same WebSocket upgrade gate for both roles. The deployed replacement now+separates Host admission from default private fragment grants and explicit+public-watch. The accepted source-only extension adds optional room-password+entry without reopening the old site-wide Viewer gate. Persistent sequential IDs+make a room-scoped boundary especially important.-Accounts, a user database, per-person ACLs, human room passwords, and a server-session table would exceed the product need. A single room-scoped bearer-capability provides the intended delegation with less user and operational-state. Media topology remains independent and is governed by ADR-0001/0005.+Accounts, a user database, per-person ACLs, password recovery, and a server+session table would exceed the product need. A room-scoped bearer capability+remains the lowest-friction invitation, while an optional low-policy room+password lets a trusted friend enter from a numeric room code without weakening+Host admission. Media topology remains independent and is governed by+ADR-0001/0005.## Decision@@ -71,6 +72,32 @@ Every room has one of two Viewer policies:central-egress limits. Sequential public room IDs deliberately provide noprivacy and must be labelled accordingly.+A private room may also have one optional Viewer password. An existing valid+fragment grant still enters directly. A code-only Viewer sees a neutral password+form and, on success, authenticates only that current Viewer session in that+room. The Host can set, replace, or remove it. The input accepts 1 through 64+visible ASCII characters without composition rules; this is a convenience+boundary for trusted friends, not an account credential or recovery system.++Plaintext room passwords exist only transiently in the current page state,+WebSocket authentication message, and KDF call memory. They never enter a URL,+cookie, browser persistent storage, log, error, or SQLite. The server uses Node's+asynchronous scrypt with fixed `N=16384,r=8,p=1`, a random 16-byte salt, a+32-byte verifier, two active KDF slots, and at most 16 waiters. A full queue fails+boundedly; a waiter rechecks its Viewer socket or Host session before starting+KDF and skips stale work. A target-machine benchmark+may tune those parameters after the feature is deployed; it does not block the+functional default. Unknown rooms, absent/wrong passwords, and a full room after+a correct password share generic rejection. Completion rechecks current room+material and socket/Host session so stale asynchronous work cannot authorize or+commit.++The wire remains `screener-v2`. Only a Web Host that advertises+`viewerPasswordSettings: true` may set/remove the password and receive+`viewer-password-updated`; Native v2 does not advertise the capability and sees+no new message type. Viewer `authenticate` may carry the current password+attempt. The generic `authenticated` message does not gain a password field.+Private invitations use `/r/{roomId}#v={grant}`. RFC 3986 separates a fragmentbefore dereference, and the WebSocket API rejects fragment-bearing URLs, so theclient never appends it to HTTP or `/signal`. On first load the client strictly@@ -99,7 +126,9 @@ every current Viewer socket. Closing signaling alone is insufficient because ahealthy P2P edge can keep playing without it. Rotation and public-to-private eachreturn one new grant. Revoke stores a fresh random locked-private digest forwhich no grant was generated and returns no grant until a later rotation.-The old grant or code-only session then cannot reconnect. A persistence failure+The old grant or code-only session then cannot reconnect; a separately configured+room password remains an available future entry after current Viewers are+disconnected. A persistence failureleaves the old digest, existing sockets, and topology unchanged. Switching fromprivate to public only broadens future Viewer admission and does not movehealthy media.@@ -111,7 +140,8 @@ healthy media.`ROOM_TTL_SECONDS`. With it, SQLite allocates persistent decimal IDs using`INTEGER PRIMARY KEY AUTOINCREMENT`.-Schema v2 keeps one `rooms` table and one additional field:+Schema v3 keeps one `rooms` table and adds one nullable password-material field+to the deployed v2 shape:```textid INTEGER PRIMARY KEY AUTOINCREMENT@@ -119,17 +149,23 @@ host_token_digest BLOB NOT NULLCHECK (length(host_token_digest) = 32)viewer_grant_digest BLOB NULLCHECK (viewer_grant_digest IS NULL OR length(viewer_grant_digest) = 32)+viewer_password_material BLOB NULL+ CHECK (viewer_password_material IS NULL OR length(viewer_password_material) = 48)```-`NULL` means public-watch; 32 bytes mean private-link. SQLite stores no raw-password, Host token, Viewer grant, cookie, display name, participant,+For the grant, `NULL` means public-watch and 32 bytes mean private-link. Password+material is either `NULL` or one 48-byte BLOB containing a 16-byte salt followed+by a 32-byte scrypt verifier, so salt/verifier cannot be half-written. SQLite+stores no raw Host-admission or room password, Host token, Viewer grant, cookie,+display name, participant,`clientId`, `peerId`, IP address, SDP, ICE candidate, media, or TURN credential.There is no user, invitation, or session table.-Schema v1 migrates inside one `BEGIN IMMEDIATE` transaction. It adds the nullable-checked `BLOB` column, assigns every existing row a fresh random 32-byte-locked-private digest for which no grant is generated, and advances-`user_version`. Existing Host+Schema v1 or v2 migrates to v3 inside one `BEGIN IMMEDIATE` transaction. V1 first+adds the nullable checked grant `BLOB` and assigns every existing row a fresh+random 32-byte locked-private digest for which no grant is generated. Both v1+and v2 then add the checked nullable password-material column, default it to+`NULL`, and advance `user_version`. Existing Hosttokens still reclaim their rooms, after which the Host rotates once to obtain anew invitation. Old code-only links fail closed. Deployment takes a v1 backup before migration; arollback to the old binary stops the service and restores that backup rather@@ -146,8 +182,8 @@ SQLite or participates in authorization, routing, or quality decisions.room-creation and Host capability.- One digest scopes leaked Viewer authority to one room and one role; rotationprovides a clear recovery operation.-- Public watching remains explicit, and persistent state grows by one nullable- digest column rather than a new subsystem.+- Public watching remains explicit. Optional password entry adds one nullable+ fixed-size material column, not an account or authentication subsystem.- A capability link is a bearer credential. Anyone who obtains it can joinbefore expiry and remain until disconnect or room-wide rotation/revoke;targeted per-person revocation is unavailable.@@ -155,7 +191,7 @@ SQLite or participates in authorization, routing, or quality decisions.Closing the only Host tab loses its raw copy; the Host must rotate to produceanother link, although room ownership remains recoverable from its Host token.- Rotation/revoke deliberately disconnects all Viewers and rebuilds their routes.-- SQLite v2 is not readable by the old runtime, so rollback requires the+- SQLite v3 is not readable by the old runtime, so rollback requires thepre-migration backup.- Public-watch consumes bounded Viewer/media capacity and offers no privacy.@@ -163,8 +199,9 @@ SQLite or participates in authorization, routing, or quality decisions.- One password for Host and Viewer: over-grants every invited Viewer and couplesdeployment abuse control to room privacy.-- Human per-room passwords: adds input, password handling, and recovery without- improving the link-sharing workflow over a high-entropy capability.+- A room password as the only private mechanism: loses the direct fragment-grant+ workflow and encourages password reuse. The password is an optional parallel+ Viewer entry, while the grant remains the default invitation.- Query/path grant: request targets are commonly logged; RFC 6750 likewise warnsagainst bearer tokens in URI queries. A fragment plus first WS message keepsit out of ordinary HTTP and proxy request logs.@@ -182,23 +219,25 @@ SQLite or participates in authorization, routing, or quality decisions.- The auth matrix proves production Host admission, Viewer-without-Host-cookie,8-byte minimum/independent secret, ingress rate limit, exact-room/role grant- scope, non-enumerating failures, and public-watch caps.+ scope, correct/wrong/replaced/removed room passwords, non-enumerating failures,+ public code-only entry, and v2 Native wire isolation.- Leak tests cover HTTP/WS targets, Referrer, browser storage, SQLite, applicationand proxy logs, and errors; fragment consumption immediately clears the URL.- Rotation/revoke/public-to-private proves commit-before-disconnect, completegrace/route cleanup, old receive/send media teardown, one-time grant semantics,old reconnect rejection, locked revoke, and no change after persistence failure.-- A production-copy v1 `STRICT` database migrates transactionally to checked,- locked-private v2; malformed non-null values fail closed, rollback restores its- backup, and v1 tabs terminate without compatibility code.+- Production-copy v1/v2 `STRICT` databases migrate transactionally to checked v3+ with locked-private v1 grants and nullable single-BLOB password material;+ malformed non-null values fail closed and rollback restores the backup.## Implementation Status-The 2026-08-20 repository candidate implements the single-version v2 runtime,-same-row SQLite migration, private/public room policy, fragment consumption,-Host admission, and commit-first generation teardown. Focused automated tests-cover protocol bounds, exact-room grants, persistent-write failure, active-peer/SFU edge retirement, old-generation socket rejection, and v1 migration-rollback. The tracked nginx limiter and backup/restore procedure are present.-Production ingress loading, browser storage/request/log leak inspection, a-production-copy migration rehearsal, and deployment remain acceptance work.+The deployed 2026-08-20 boundary implements the single-version v2 runtime,+private/public room policy, fragment consumption, Host admission, and+commit-first grant teardown on SQLite v2. The current source-only candidate adds+the optional room password, capability-isolated Web Host controls, asynchronous+session rechecks, and the v1/v2-to-v3 single-BLOB migration. Focused automated+tests cover password set/change/remove, grant continuity, public code-only entry,+Native wire isolation, protocol bounds, and both migration origins. Password+deployment, browser UX/leak inspection, production-copy migration rehearsal,+and post-feature target-machine KDF benchmarking remain acceptance work.diff --git a/docs/project-memory.md b/docs/project-memory.mdindex 31e7d7db..b22214d3 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -12,7 +12,7 @@ Last updated: 2026-08-20- Two-tree packet/layer striping may reduce endpoint upload toward one stream bitrate, but needs a bounded multi-parent, loss, sync, churn, and latency experiment; it is not in the current full-stream chains.- Direct/peer keeps per-PC stock GCC. SFU paths start at a `HIGH` ceiling and share at most one `LOW`; next test LiveKit exactly-two built-in BWE on zero-descendant leaves. If it passes, no app media selector is built. Explicit quality, manual activation, then custom/native are later fallbacks; always-on `LOW` needs resource gates.- A later explicit quality fallback evacuates children under a generation guard first. Autonomous BWE enters `suspect`; confirmation evacuates children, and no confirmed `FALLBACK` parent remains. Root-with-children impact is a default-on gate; capacity returns after longer recovery plus cooldown. Self-report alone never triggers it.-- Separate abuse control from watching: production Host admission protects room creation/Host role, while a default private capability grants Viewer access to one room; public-watch is explicit. Keep raw grants out of localStorage/cookies/query/logs/SQLite; retain no account, ACL, user, or session table.+- Separate abuse control from watching: Host admission protects creation/Host; private Viewer entry uses a room grant or optional room password, while public-watch accepts the code. Persist neither raw credential; keep accounts, ACLs, users, and session tables out.- Keep decisions, snapshots, research, code, `AGENTS.md`, and `.codex/` in Git; rewrite memory/status in place. Research current primary sources before material work and reject speculative machinery.- Migrate client, server, and deployment atomically. After a canary, delete superseded config/wire/parsers/tests; do not retain compatibility layers, dual writes, or a second architecture without a current consumer. Git history owns the old implementation.- Autonomously deploy each coherent low-risk milestone after narrow tests, independent review, one full gate, CI and rollback preflight. Keep protocol/database migrations atomic rather than folding them into routine UI/media updates.@@ -33,7 +33,7 @@ Last updated: 2026-08-20- Production reports poor film audio and self-echo when system capture includes voice software. Diagnose audio A/B/C and sync; Web cannot isolate arbitrary processes and `maxBitrate` is not quality-up. A Windows 11 native candidate defaults to game-process-tree audio and never widens silently; Windows 10 remains unresolved/unsupported. See `docs/research/browser-screen-audio-quality.md`.- Viewer-local names and the opt-in Web Host roster are deployed without media changes. Host self-name, endpoint details, and RTP loss remain pending.- Do not add scene detection, dynamic-FPS control, or forced AV1 without negotiation, encode, game, CPU/GPU, and sender evidence.-- ADR-0002 access is deployed; names/presence are session-only with no account, member, session, or roster table.+- ADR-0002 grant/public access is deployed; room-password is source-only. Names/presence remain session-only without account or roster tables.- Deferred architecture audit: `docs/maintenance.md`.## Current Implementationdiff --git a/docs/research/webrtc-p2p-screen-sharing.md b/docs/research/webrtc-p2p-screen-sharing.mdindex 62c44eaa..1e6d5722 100644--- a/docs/research/webrtc-p2p-screen-sharing.md+++ b/docs/research/webrtc-p2p-screen-sharing.md@@ -228,11 +228,11 @@ Electron 可以固定 Chromium 版本,枚举屏幕/窗口,改善选源、热### 最小访问模型-旧 production 的 `ACCESS_PASSWORD`、同一 Host/Viewer cookie gate 和 code-only Viewer 是已部署事实,不再是接受的目标;仓库 access candidate 已把“谁可以建立/发布房间”和“谁可以看这一间房”分开。production 必配的 `HOST_ADMISSION_PASSWORD` 无状态 cookie 只允许建房及尝试 Host role,房间 Host token 仍独立验证;默认 private-link 使用一个 room-scoped Viewer bearer grant,public-watch 才接受 code-only Viewer。它们不需要账号、JWT、服务端 session Map、逐人 ACL 或人类房间密码。WebSocket upgrade 不知道未来 role,因此只能保留 Origin/容量门并记录 Host cookie 状态;首条 Host 鉴权再同时要求该状态和 Host token,Viewer 只走 room policy。RFC 6455 明确允许服务端用 handshake `Origin` 作接纳判断,但这不是 Viewer 授权本身。+旧 production 的 `ACCESS_PASSWORD`、同一 Host/Viewer cookie gate 和 code-only Viewer 是已部署事实,不再是接受的目标;仓库 access candidate 已把“谁可以建立/发布房间”和“谁可以看这一间房”分开。production 必配的 `HOST_ADMISSION_PASSWORD` 无状态 cookie 只允许建房及尝试 Host role,房间 Host token 仍独立验证;默认 private-link 使用一个 room-scoped Viewer bearer grant,public-watch 才接受 code-only Viewer。原研究结论不要求人类房间密码;后续已接受的最小扩展增加可选的逐房间 Viewer 密码作为 code-only 私密入口,但仍不引入账号、JWT、服务端 session Map 或逐人 ACL。WebSocket upgrade 不知道未来 role,因此只能保留 Origin/容量门并记录 Host cookie 状态;首条 Host 鉴权再同时要求该状态和 Host token,Viewer 只走 room policy。RFC 6455 明确允许服务端用 handshake `Origin` 作接纳判断,但这不是 Viewer 授权本身。RFC 3986 的规范事实是 fragment 在 URI dereference 前由 user agent 分离;WHATWG WebSockets 进一步规定含 fragment 的 constructor URL 必须抛 `SyntaxError`。因此把 256-bit room grant 放在 `/r/{code}#v=...`,再由页面在首个 WSS application message 发送,可以使它不进入 HTTP 或 WebSocket request-target。RFC 6750 对 OAuth bearer query 的警告并不直接规定本产品,但它提供了适用的安全类比:URI query 高概率被日志记录,不应承载此 grant。W3C Referrer Policy 的算法会从 referrer URL 移除 fragment,production 的 `no-referrer` header 再禁止整个 header;这是传输边界,不是“不会泄漏”的保证。-W3C TAG 的 capability URL 指南指出 URL 仍会出现在地址栏、历史、扩展、同步服务、截图和转发路径中,建议高熵、到期与可撤销。目标因此使用 Node.js `randomBytes(32)` 的加密强随机量、完整 grant 的 SHA-256 摘要、有限期限,以及 Host rotate 或 locked revoke。浏览器首次严格解析后只写 room-scoped `sessionStorage`,立即 `history.replaceState` 到 canonical URL;刷新和页面内 WSS reconnect 可复用。HTML 标准明确新 auxiliary browsing context 可以复制同源 opener 的 session storage;这是已持有 bearer 的本地浏览器上下文转交边界,不是服务器扩大 room/role 权限,因此不增加导航状态机。独立且无 fragment/room key 的访问仍 fail closed。raw grant 不进入 `localStorage`、cookie、query、Referrer、SQLite、应用/代理日志或错误。OWASP 日志指南也明确把 access token、session identifier 和密码列为通常不应直接记录的数据。Fragment 降低服务端泄漏面,但 possession 仍等于该房间 Viewer 权限。+W3C TAG 的 capability URL 指南指出 URL 仍会出现在地址栏、历史、扩展、同步服务、截图和转发路径中,建议高熵、到期与可撤销。目标因此使用 Node.js `randomBytes(32)` 的加密强随机量、完整 grant 的 SHA-256 摘要、有限期限,以及 Host rotate 或 locked revoke。浏览器首次严格解析后只写 room-scoped `sessionStorage`,立即 `history.replaceState` 到 canonical URL;刷新和页面内 WSS reconnect 可复用。HTML 标准明确新 auxiliary browsing context 可以复制同源 opener 的 session storage;这是已持有 bearer 的本地浏览器上下文转交边界,不是服务器扩大 room/role 权限,因此不增加导航状态机。独立且无 fragment/room key 的访问只进入中性密码路径,没有正确房间密码仍 fail closed。raw grant 不进入 `localStorage`、cookie、query、Referrer、SQLite、应用/代理日志或错误。OWASP 日志指南也明确把 access token、session identifier 和密码列为通常不应直接记录的数据。Fragment 降低服务端泄漏面,但 possession 仍等于该房间 Viewer 权限。持久化只在现有 `rooms` row 增加 nullable `viewer_grant_digest`;`NULL` 表示 public-watch,非空值以 `CHECK` 约束为 32-byte BLOB。SQLite `STRICT` table 只接受规定的类型名,因此不能声明 `BLOB(32)`;括号长度也不是 SQLite 的长度约束。官方迁移指南支持在 transaction 中完成 schema/data 变更,目标用一个 `BEGIN IMMEDIATE` 给每个 schema v1 旧行写入未生成对应 grant 的 fresh random locked-private digest,再更新 `user_version`。这是项目设计推论,不是 SQLite 自动提供的权限语义。上线前备份 v1;旧 binary 回滚恢复备份,不在 runtime 保留双 schema。@@ -278,7 +278,7 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件- WebRTC 使用 DTLS-SRTP。TURN 只能看到加密后的媒体包,但仍能看到地址、房间时序和流量元数据。- P2P 会让房间内双方得知网络地址。熟人首版可以接受,陌生人房间不能默认接受。- TURN 必须使用短期凭据、速率限制、每用户/房间配额和出口告警,不能提供匿名公共 relay。-- Host admission password 只控制建房/Host role,不能作为私密观看凭据;private-link 依赖 room-scoped grant,public-watch 的 room code 则明确不提供隐私。两者都不改变媒体 fanout/egress 上限。+- Host admission password 只控制建房/Host role,不能作为私密观看凭据;private-link 接受 room-scoped grant 或可选逐房间 Viewer 密码,public-watch 的 room code 则明确不提供隐私。这些入口都不改变媒体 fanout/egress 上限。- raw Viewer grant 与 Host token 等同访问凭据:只保存摘要,禁止日志/遥测/错误/Referrer/SQLite 明文。显示名、room-scoped peer 后缀和 IP 诊断均不参与授权。- 如果未来使用 SFU 且要求服务器看不到内容,再评估 SFrame/WebRTC Encoded Transform 和群组密钥管理。diff --git a/docs/status.md b/docs/status.mdindex 6e0d88bb..7dd44efe 100644--- a/docs/status.md+++ b/docs/status.md@@ -16,8 +16,8 @@ and is not part of production.## Current Snapshot- Capture precedes room creation; source/quality changes preserve peers and pause keeps audio/connections. Quality defaults to `maintain-resolution` with balanced/fluid options.-- Production requires `HOST_ADMISSION_PASSWORD` only for creation/Host role and uses `screener-v2`, default private fragment grants, explicit public-watch, and generation-bound rotate/revoke. Viewers never need the Host secret; there is no account/session table or old parser.-- SQLite v2 keeps Host and nullable Viewer-grant digests in one checked `STRICT` row. The stopped migration retained four rooms and locked each old room private without minting a raw grant.+- Production access remains `screener-v2`: Host secret gates creation/Host; private grants and public codes authorize Viewers. The source-only, undeployed candidate adds private room-code + password entry without changing grant/public entry.+- Production SQLite v2 retains four rooms and checked grant digests. Candidate v3 atomically adds a nullable checked 48-byte salt+scrypt-verifier BLOB; never plaintext.- Source-only Native v2 uses memory-only rooms, 300s reclaim and `ROOM_TTL`; production does not run it.- PR #44's exact-room STUN-only/SFU-UDP router is enabled only for production room `1`: host/SFU roots <=2, browser relay <=1, bounded failure. HTTPS/WSS stays TLS/TCP.- Fallback prewarm is token-free and limited to room `1`; mobile/iPad viewers are leaves and healthy edges stay sticky.diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"index e6013c1a..d864b14d 100644--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"@@ -27,7 +27,7 @@| Web 客户端 | React 19、TypeScript、Vite 8 | 同一套响应式界面覆盖分享者与桌面/移动观看者;官方模板成熟 || 媒体 | 浏览器原生 WebRTC 与 Screen Capture API | 不引入 PeerJS/simple-peer,保留对 ICE、sender 参数和 stats 的直接控制 || 应用服务 | Node.js 24 LTS、TypeScript、原生 HTTP、`ws` | 服务只负责小流量控制面;前后端可共享协议类型和校验 |-| 可选房间持久化 | Node.js 内置 `node:sqlite` | 单文件、无额外依赖;只保存房间 ID、Host token 摘要与 nullable Viewer grant 摘要 |+| 可选房间持久化 | Node.js 内置 `node:sqlite` | 单文件、无额外依赖;只保存房间 ID、Host token 摘要、nullable Viewer grant 摘要与 nullable Viewer-password KDF material || 运行时校验 | Zod | WebSocket 和 HTTP 输入不可信,需要与 TypeScript 类型一致的运行时边界 || 静态文件 | `sirv` | 生产环境由同一 Node 进程提供前端构建结果,避免引入完整 Web 框架 || 地址发现/鉴权回退 | coturn 4.17.2 或更新补丁版本 | 当前 tracked template 与 production 应用只下发 STUN,但共享机保留旧 authenticated-relay daemon 配置/端口规则且不下发 credential;未来只为 controller 选中的异常 edge 签发短期 TURN,先验收 TURN REST、UDP relay range 与 quotas,不启用媒体 TCP |@@ -74,15 +74,17 @@ WebSocket upgrade 无法预知后续 role,因此不能再用 Host cookie 拒- `private-link`:服务端用 `randomBytes(32)` 生成 256-bit 随机量,并把到期信息和随机量组成严格、room-scoped 的 opaque Viewer grant;只保存完整 grant 的 SHA-256 摘要并用定长比较验证。临时房间 grant 不晚于 room TTL;持久房间 grant 固定七天。这个无配置首版边界允许熟人跨短期游戏会话复用链接,但不让可枚举持久房间产生永久邀请;只有真实使用证据才调整。到期在首次鉴权/重连时拒绝,不定时踢出已鉴权 Viewer;即时清退使用 rotate/revoke。- `public-watch`:纯 `/r/{roomId}` 或 `/join` 房间码允许 Viewer 进入,不签发 Viewer grant。这是有意公开的观看 policy,不是私密链接;它仍受房间 Viewer、全局/未鉴权连接和中央 egress/admission 上限保护,不提供房间目录。-- 人类可输入的逐房间密码、逐人邀请、账号和通用授权服务不做。Capability link 已满足可信朋友的低摩擦观看;需要隔离单个观看者时再以真实需求评估多 grant,而不是先建 ACL。+- `private-link` 另可设置一个逐房间 Viewer 密码。有效 fragment grant 保持直达;只有房间号时显示中性密码表单,正确密码仅鉴权当前 Viewer 会话。Host 可设置、改写或移除,密码接受 1 至 64 个可见 ASCII 字符且不要求组合复杂度。逐人邀请、账号、找回、ACL 和通用授权服务仍不做。-私密邀请使用 `/r/{roomId}#v={grant}`。RFC 3986 要求 fragment 在 dereference 前由 user agent 分离,因此 HTTP request-target 与反向代理 access log 看不到它;WHATWG WebSocket 还明确拒绝含 fragment 的 URL。客户端只从页面 URL 严格解析一次,把 grant 写入 `screener:viewer-grant:{roomId}` 的 `sessionStorage`,随即以 `history.replaceState` 把地址栏替换为 canonical `/r/{roomId}`;刷新和页面内 WSS 重连继续使用该页面会话的值,独立且无 fragment/room key 的页面 fail closed。Host 建房/rotate 收到的 raw grant 同样只在内存和 room-scoped `sessionStorage` 中保留,用它临时构造复制链接;写入 `localStorage` 的 room ownership 对象只能包含 canonical URL、room ID、Host token 和期限。grant 不进入 cookie、query、WebSocket URL、Referrer、日志或错误。生产继续发送 `Referrer-Policy: no-referrer`;fragment 与该 header 降低传输泄漏,但不能防止原邀请消息、浏览器扩展、截图或用户转发,UI 必须把链接称为访问凭据。+房间密码明文只短暂存在于当前 React 状态、WebSocket 鉴权消息和异步派生调用内存;不进入 URL/query/fragment、cookie、`localStorage`、`sessionStorage`、日志、错误或 SQLite。服务端使用 Node 标准异步 `scrypt` 固定 `N=16384,r=8,p=1`、16-byte 随机 salt 和 32-byte verifier;进程级 gate 最多执行 2 个、等待 16 个派生,队满即有界失败。等待任务取槽后先复核当前 Host/Viewer session,stale work 不启动 KDF;实际派生后再复核 room material 与连接代次。功能部署后的目标机 benchmark 再校准参数,不阻塞最小闭环。不存在房间、未配置密码、错误密码与正确密码后的满房都使用通用拒绝,不形成存在性 oracle。-`ROOM_DATABASE_PATH` 仍是可选 SQLite 文件路径,但必须同时配置 `HOST_ADMISSION_PASSWORD`。无数据库时房间使用随机数字 ID 和 `ROOM_TTL_SECONDS`;有数据库时 SQLite `INTEGER PRIMARY KEY AUTOINCREMENT` 从 `1` 开始分配持久 room ID。所有房间继续生成 256-bit Host token,服务端只保存 SHA-256 摘要;Host 浏览器只把 room ownership 明文留在同源 `localStorage`。SQLite schema v2 在同一个 `rooms` row 上只有 `id`、32-byte `host_token_digest` 和 nullable 32-byte `viewer_grant_digest`:`NULL` 表示 public-watch,32 bytes 表示 private-link;没有用户、成员或 session 表。+私密邀请使用 `/r/{roomId}#v={grant}`。RFC 3986 要求 fragment 在 dereference 前由 user agent 分离,因此 HTTP request-target 与反向代理 access log 看不到它;WHATWG WebSocket 还明确拒绝含 fragment 的 URL。客户端只从页面 URL 严格解析一次,把 grant 写入 `screener:viewer-grant:{roomId}` 的 `sessionStorage`,随即以 `history.replaceState` 把地址栏替换为 canonical `/r/{roomId}`;刷新和页面内 WSS 重连继续使用该页面会话的值,独立且无 fragment/room key 的页面只进入中性密码路径,没有正确房间密码仍 fail closed。Host 建房/rotate 收到的 raw grant 同样只在内存和 room-scoped `sessionStorage` 中保留,用它临时构造复制链接;写入 `localStorage` 的 room ownership 对象只能包含 canonical URL、room ID、Host token 和期限。grant 不进入 cookie、query、WebSocket URL、Referrer、日志或错误。生产继续发送 `Referrer-Policy: no-referrer`;fragment 与该 header 降低传输泄漏,但不能防止原邀请消息、浏览器扩展、截图或用户转发,UI 必须把链接称为访问凭据。-schema v1 -> v2 使用单个 `BEGIN IMMEDIATE` 事务新增 `viewer_grant_digest BLOB NULL CHECK (viewer_grant_digest IS NULL OR length(viewer_grant_digest) = 32)`,为每个旧行写入由 Node `randomBytes(32)` 产生、未生成对应 grant 的 locked digest,再更新 `user_version`。这既满足当前 `STRICT` table 的合法类型名,也让 SQLite 真实约束长度;读取畸形非空值时仍 fail closed。旧 Host token 能认领房间,但必须 rotate 才能取得新私密邀请;旧 code-only Viewer 不能 fail-open。部署前备份 v1 数据库;由于新 release 不读写双 schema,回滚旧 binary 必须停服并恢复该备份。临时内存房间随部署重启结束。+`ROOM_DATABASE_PATH` 仍是可选 SQLite 文件路径,但必须同时配置 `HOST_ADMISSION_PASSWORD`。无数据库时房间使用随机数字 ID 和 `ROOM_TTL_SECONDS`;有数据库时 SQLite `INTEGER PRIMARY KEY AUTOINCREMENT` 从 `1` 开始分配持久 room ID。所有房间继续生成 256-bit Host token,服务端只保存 SHA-256 摘要;Host 浏览器只把 room ownership 明文留在同源 `localStorage`。SQLite schema v3 在同一个 `rooms` row 上保存 `id`、32-byte `host_token_digest`、nullable 32-byte `viewer_grant_digest` 和 nullable 48-byte `viewer_password_material`;后者是 16-byte salt 与 32-byte scrypt verifier 的单一 BLOB,`CHECK` 只允许 `NULL` 或准确长度 48,避免半写状态。没有明文房间密码、用户、成员或 session 表。-rotate、revoke 或从 public-watch 切回 private-link 都是强撤销:服务端先原子提交新 digest/authorization generation;成功后清除所有 Viewer grace、连接代次与路由状态,向 Viewer 发送通用访问已撤销终态使其立即关闭接收 `RTCPeerConnection`/媒体并停止重连,同时向每个 Host/relay/SFU upstream owner 发送权威旧边移除使其关闭对应发送边,最后关闭 Viewer socket。不能只断 WSS,因为健康 P2P 可在信令断开后继续播放。rotate 与 public-to-private 都生成并仅返回一次新 grant;revoke 写入未生成对应 grant 的 fresh random locked digest,房间保持私密锁定直到下一次 rotate。数据库写失败时,内存摘要、现有 Viewer、媒体和拓扑保持不变。切到 public-watch 只放宽以后 Viewer 的 code-only 鉴权,不需要迁移健康媒体。服务端永不返回现有 grant 明文;丢失 Host 标签页中的 grant 时只能 rotate。+schema v1/v2 -> v3 使用单个 `BEGIN IMMEDIATE` 事务。v1 先新增 checked `viewer_grant_digest` 并为旧行写入没有对应 raw grant 的随机 locked digest;v1 与 v2 都新增 checked `viewer_password_material`,默认 `NULL`,最后更新 `user_version`。读取畸形非空值时 fail closed。旧 Host token 能认领房间;旧 code-only Viewer 不能 fail-open。部署前备份数据库;由于新 release 不读写双 schema,回滚旧 binary 必须停服并恢复备份。临时内存房间随部署重启结束。++rotate、revoke 或从 public-watch 切回 private-link 都是当前 Viewer 的强撤销:服务端先原子提交新 digest/authorization generation;成功后清除所有 Viewer grace、连接代次与路由状态,向 Viewer 发送通用访问已撤销终态使其立即关闭接收 `RTCPeerConnection`/媒体并停止重连,同时向每个 Host/relay/SFU upstream owner 发送权威旧边移除使其关闭对应发送边,最后关闭 Viewer socket。不能只断 WSS,因为健康 P2P 可在信令断开后继续播放。rotate 与 public-to-private 都生成并仅返回一次新 grant;revoke 写入未生成对应 grant 的 fresh random locked digest,不再允许旧 grant,但已配置的房间密码仍是独立的以后进入方式。数据库写失败时,内存摘要、现有 Viewer、媒体和拓扑保持不变。切到 public-watch 只放宽以后 Viewer 的 code-only 鉴权,不需要迁移健康媒体。服务端永不返回现有 grant 明文;丢失 Host 标签页中的 grant 时只能 rotate。房间规则:@@ -102,17 +104,18 @@ Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability;## 信令协议-WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 Host-admission cookie 是否有效;连接后五秒内第一条消息必须是 `screener-v2` 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 Host admission;Viewer 消息携带 room、role、clientId 和 private-link 时的 Viewer grant。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。+WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 Host-admission cookie 是否有效;连接后五秒内第一条消息必须是 `screener-v2` 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 Host admission;Web Host 可选发 `viewerPasswordSettings: true` capability,Native v2 不发送且不接收任何密码设置新消息。Viewer 消息携带 room、role、clientId,以及 private room 的 Viewer grant 或当前尝试的房间密码。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。主要消息:| 方向 | 消息 | 作用 || --- | --- | --- |-| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话,并可显式订阅 Web-only viewer presence;Viewer 以 public room code 或 private Viewer grant 建立仅观看会话并可附带规范化本地显示名 |+| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话,并可显式订阅 Web-only viewer presence/password settings;Viewer 以 public room code、private Viewer grant 或当前房间密码尝试建立仅观看会话并可附带规范化本地显示名 || server -> client | `authenticated` | 返回角色、peerId、可为空的房间期限、容量、host 状态、该 viewer 的历史 connectionId、host 的权威 viewer 列表和 ICE 配置 || viewer -> server | `set-display-name` | 只更新该 Viewer 当前 authenticated socket state 的规范化名称,不写房间或数据库状态 || server -> subscribed Web host | `viewer-presence` | 返回全部当前在线 Viewer 的权威 snapshot 与只读 active media topology;不触发媒体连接 || host -> server -> host | `set-viewer-access` / `viewer-access-updated` | Host 切换 public/private、rotate 或 revoke;raw grant 只在新建、rotate 或 public-to-private 成功响应中出现一次 |+| opted-in Web host -> server -> host | `set-viewer-password` / `viewer-password-updated` | 设置、替换或移除逐房间 Viewer 密码;服务端只返回 enabled snapshot,不回显密码;未声明 capability 的 v2 Host 不接收该新 type || server -> host | `peer-joined` / `peer-left` | 建立或关闭该观看者的独立连接 || host -> viewer | `offer` / `candidate` | 带 `peerId` 与 `connectionId` 的定向信令 || viewer -> host | `answer` / `candidate` | 只能回给本房间分享者 |@@ -313,10 +316,10 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)首屏就是工具,不做营销页。视觉采用中性深灰工作台,绿色表示 direct、琥珀色表示 relay/警告、红色表示失败,避免单一蓝紫色主题;浏览器 favicon 复用页头 `MonitorUp` 的深绿底、绿色显示器和上行箭头语言。-- 访问入口:未鉴权根路径和 `/join` 只显示中性的“访问验证/访问口令”,未知路径只显示“无法访问”,HTML metadata 不说明站点用途。有效 `/r/{code}#v={grant}` 或 public-watch `/r/{code}` 先完成 Viewer 鉴权,成功后才渲染房间 UI;无效、过期或满员只显示通用拒绝。Viewer 页面不显示或泄露部署访问口令。这是降低偶然访客信息量的展示边界,不把浏览器可下载的 bundle 当成秘密。+- 访问入口:未鉴权根路径和 `/join` 只显示中性的“访问验证/访问口令”,未知路径只显示“无法访问”,HTML metadata 不说明站点用途。有效 `/r/{code}#v={grant}` 或 public-watch `/r/{code}` 先完成 Viewer 鉴权并直接进入;private room 仅有房间号时在同一中性边界显示“访问密码”输入,成功后才渲染房间 UI。无效、过期、错误密码或满员只显示通用拒绝。Viewer 页面不显示或泄露部署访问口令或站点用途。这是降低偶然访客信息量的展示边界,不把浏览器可下载的 bundle 当成秘密。- 分享者根页面:顶部显示“{分享者显示名} 的房间”和房间状态,并在标题旁显示可单独复制的紧凑房间号;主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;前者直接开始现有分享流程,后者直接进入 `/join`,不增加首页、向导或拓扑选择。直播时舞台显示本地预览,底部保留停止、暂停、质量档位和复制完整邀请链接。-- `/join`:只输入正整数房间码并进入 `/r/{code}`,仅 public-watch 会通过;private-link 缺失 grant 时统一提示使用完整邀请链接。-- `/r/{code}` 观看者:主区域最大化远端视频;private-link 首次解析 fragment grant 后立即清理地址栏,public-watch 只需 code;标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制。+- `/join`:只输入正整数房间码并进入 `/r/{code}`;public-watch 直接通过,private room 缺失 grant 时显示中性房间密码表单。+- `/r/{code}` 观看者:未鉴权时不渲染产品用途;private room 首次解析 fragment grant 后立即清理地址栏并直达,仅有 code 时可用房间密码;public-watch 只需 code。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制。- 移动端:视频保持稳定宽高比,控制与状态移到视频下方,任何文字和按钮不得溢出或遮挡。两端后续默认显示紧凑在线 roster;Host 与 Viewer 均可修改本机显示名,展示为名称加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开信令、ICE/TURN、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。用户名/roster 是独立 PR,不进入 access credential 或 SQLite。@@ -330,7 +333,7 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)## 安全与故障边界- 生产仅允许 HTTPS/WSS,并校验 WebSocket `Origin` allowlist。-- Host admission 密码以定长摘要配合常量时间比较;Host-admission cookie 由服务端 HMAC 签名且不含账号或可查询 session ID。Host token 与 Viewer grant 只保存 SHA-256 摘要并以定长比较验证;Host admission 与建房 HTTP 响应设置 `Cache-Control: no-store`。+- Host admission 密码以定长摘要配合常量时间比较;Host-admission cookie 由服务端 HMAC 签名且不含账号或可查询 session ID。Host token 与 Viewer grant 只保存 SHA-256 摘要并以定长比较验证;房间密码只保存带随机 salt 的 scrypt verifier material,并对派生结果做定长比较。Host admission 与建房 HTTP 响应设置 `Cache-Control: no-store`。- Fragment 只避免其进入 HTTP/WebSocket request-target,不能把 capability 变成非敏感数据。客户端首次读取后立即清理地址栏,只在 room-scoped `sessionStorage` 留存;服务端和代理日志不得记录 WebSocket payload、Authorization、cookie、raw grant 或响应 body,异常只能记录安全路径、状态码和分类。- HTTP body、WebSocket payload、总连接数、未鉴权连接数、输出缓冲、房间总数、观看人数和 candidate 缓存都有硬上限;无法解析的 upgrade request-target 在未鉴权边界返回 HTTP 400,不允许异常逃逸到进程顶层。- 应用日志不得主动记录 IP;反向代理、STUN 和 LiveKit 为提供网络服务必然可见源地址,部署时需设置最短必要留存与访问控制。@@ -343,11 +346,11 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)- HostAdmission 的 production 必配、8 至 128 visible-ASCII bytes/独立 secret、local-dev 显式关闭、12 小时签名 cookie、过期、篡改、cookie 属性、旧 `ACCESS_PASSWORD` fail-fast 和无服务端 session 状态;- RoomStore 的随机临时房间、TTL、Host token/Viewer grant 摘要验证、private/public policy、grant 到期/跨房拒绝、rotate/revoke 强撤销、停止分享等待、Viewer 上限和超额拒绝;-- SQLite 房间库从 `1` 自增、重启恢复、v1 -> v2 单事务 locked-private 迁移、nullable 32-byte CHECK、畸形值 fail-closed、rotate/revoke 写失败原子性和数据最小化;数据库路径无 Host admission 时启动失败;+- SQLite 房间库从 `1` 自增、重启恢复、v1/v2 -> v3 单事务迁移、nullable 32-byte grant 与 48-byte password material CHECK、畸形值 fail-closed、rotate/revoke/password 写失败原子性和数据最小化;数据库路径无 Host admission 时启动失败;- STUN/TURN UDP URL 严格校验、生产 STUN 必需、selected-edge tuple 完整性/TTL/secret 独立性、issuer HMAC/expiry/opaque tag、当前 route/session/revision/old-new connection generation 与 one-use rebuild guard,以及 ordinary peer、未命中房间和 Native 的 STUN-only isolation;LiveKit `sfu-config` 保持独立边界;- 单一 `screener-v2` 信令 literal、v1 旧页面 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;- 质量协议的 host 授权、严格字段与数值范围、last-wins、当前/未来 relay、已配置 SFU 和普通 P2P wire 兼容;sender 的四字段 requested/applied 读回、拒绝与持续受限提示;-- HTTP/WS 集成:nginx per-source admission `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 无 Host cookie 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured admission 与 Host token,Viewer 只按 room policy;Host cookie 不绕过 private grant,grant 不能建房/Host/跨房。覆盖 private fragment/sessionStorage/replaceState、独立无 grant 访问、不含 query/Referrer/log、public code-only、public-to-private 一次性 grant,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;+- HTTP/WS 集成:nginx per-source admission `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 无 Host cookie 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured admission 与 Host token,Viewer 只按 room policy;Host cookie 不绕过 private grant/password,grant/password 不能建房、取得 Host 或跨房。覆盖 private fragment/sessionStorage/replaceState、房间号+正确/错误/已替换/已移除密码、不含明文于 URL/浏览器持久存储/SQLite/log、public code-only、v2 Native 无 capability 不收新 wire,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;- 客户端策略与 stats 解析:会话替换不重连,ordinary ICE、LiveKit 与 selected-edge TURN protocol 分离,远端 TURN transport 保持未知;- TypeScript 类型检查、Vite production build 和仓库 hygiene。diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"index 51b54ead..62bf1f9c 100644--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"@@ -13,7 +13,7 @@### P0 - 必须实现- [ ] 首屏双入口:分享入口通过 Host admission 后,主工作区必须同等突出“开始分享”和“加入房间”两个主要动作,并用清楚的视觉分隔表达发送与接收;观看者不需要知道 Host admission 密码。点击后直接进入现有分享或房间加入流程,不增加营销首页、模式向导或拓扑选择。浏览器标签页使用与现有 `MonitorUp` 品牌语言一致的 favicon。-- [ ] 简单房间:分享者获得纯数字房间码。房间默认是私密链接模式,邀请使用 `/r/{code}#v={grant}`;拥有该链接只可作为 Viewer 进入这一间房,不能建房、发布、冒充 Host 或跨房。Host 可显式选择 public-watch,使 `/r/{code}` 和 `/join` 的纯房间码可直接观看;当前已部署 slice 尚未实现房间密码,已接受的后续边界见 P1。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。+- [ ] 简单房间:分享者获得纯数字房间码。房间默认是私密模式,现有 `/r/{code}#v={grant}` 邀请继续直接进入;Host 也可给该房间设置低门槛观看密码,使仅有 `/r/{code}` 或 `/join` 房间码的 Viewer 在中性页面输入密码后进入。Host 可显式选择 public-watch,使纯房间码直接观看。当前源码候选已实现密码入口,但线上版本尚未部署。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。- [ ] 免安装观看:桌面和手机观看者可直接通过浏览器链接进入、授权并播放,不依赖与分享端相同的桌面客户端。- [ ] 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时暂停画面和切换分享来源。Host 本地预览必须直接使用 capture stream,不得为预览建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。- [ ] 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。@@ -29,13 +29,13 @@- [ ] 断线恢复:临时网络变化时按不同层级做一次性恢复,而不是把同一动作机械重复三次。`failed` 边先做一次 ICE restart,再重建一次同 parent 的 `RTCPeerConnection`,随后尝试一个不同的合格 peer parent;只有 peer 路径耗尽才进入 SFU。`connecting`/`checking` 先显示不改变拓扑的慢连接状态,硬超时必须由真实移动网络证据确定,不能为了更快使用服务器而过早放弃最终可成功的 P2P。任一步恢复即停止后续动作;所有异步结果受 session、route revision、assignment/connection generation 约束。active SFU 只允许一次 fresh-token 重试,再失败即有界回到 peer baseline 或明确失败,并向 Host 显示不含 URL、地址、token 或原始错误的失败阶段。- [ ] 可观测性:按目标 RTP transport 与不透明连接/ICE 代次关联 selected path、`iceGatheringState`/ICE/connection state、事件推导的建立时长、generation-baselined pair-change delta,以及 RTT、RTP 丢包率、抖动、码率、帧率、编码耗时和受限原因。候选与错误的 wire、日志和导出只使用[低服务器成本媒体路由](./research/low-server-media-routes.md)的脱敏字段和 code bucket,禁止 raw SDP、candidate、地址、URL、`errorText` 或网络标识。只有创建该 `RTCPeerConnection` 的本机可在折叠详情中显示浏览器对 selected local/remote candidate 实际暴露的地址与端口;该值不上传、不持久化、不用于地理/NAT 推断,缺失或被隐私保护时显示未知。- [ ] 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;候选路径、RTT、丢包、编解码器、编码耗时等技术详情由一个明确的“显示连接详情”开关展开。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。-- [ ] Host admission:生产部署必须配置独立的 `HOST_ADMISSION_PASSWORD` 控制建房和 Host 信令角色;只有本地开发/测试可显式关闭。它只是防止随手滥用的部署访问口令,不是账号密码;非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` Host-admission cookie。未鉴权根路径、`/join` 和未知路径只显示中性的访问验证或通用拒绝,不说明站点用途;有效 private-link grant 或 public-watch 直链仍直接进入目标房间。这只是界面最小暴露,不把可下载的前端代码误当保密边界。建房 HTTP 只认该 cookie且不提供 Bearer 旁路;Host admission endpoint 由部署层/nginx 做 per-source `limit_req`,失败只返回统一结果,不在 Node 新增 IP 身份库/LRU/session 表或持久化来源地址。WebSocket upgrade 继续校验 Origin 与全局/未鉴权容量并记录 cookie 状态,首条 Host `authenticate` 必须同时通过该状态与房间 `hostToken`。Viewer 不经过此 gate,Host cookie 也不能绕过私密房间的 Viewer grant。不引入账号、JWT、服务端 session Map 或通用 logout。-- [ ] 房间级观看授权:新房间默认生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续,独立且没有 grant 的访问必须 fail closed。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可 rotate 或 revoke;revoke 写入一个未生成对应 grant 的 locked-private digest,直到下一次 rotate 才产生新邀请。新摘要成功提交后必须清除 Viewer grace/路由、终止旧授权代次的信令和媒体并断开全部旧 Viewer,数据库写失败则不得改变连接。public-watch 是显式、可逆的 room policy,只放宽观看,不放宽建房或发布。-- [ ] 最小持久化:`ROOM_DATABASE_PATH` 可选且必须与 `HOST_ADMISSION_PASSWORD` 同时配置。两者都存在时,SQLite 只持久保存从 `1` 开始自增的房间 ID、Host token 摘要和同一 `rooms` 行上的 nullable Viewer grant 摘要;`NULL` 表示 public-watch,非空值必须由数据库 `CHECK` 约束为 32-byte BLOB,不新增用户、成员或 session 表。持久房间停止后仍显示等待状态;私密邀请按期限或 Host rotate 更新。旧 schema 行在原子迁移时必须 fail-closed 为没有可用明文 grant 的锁定私密状态,Host rotate 后才能生成新邀请。+- [ ] Host admission:生产部署必须配置独立的 `HOST_ADMISSION_PASSWORD` 控制建房和 Host 信令角色;只有本地开发/测试可显式关闭。它只是防止随手滥用的部署访问口令,不是账号密码;非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` Host-admission cookie。未鉴权根路径、`/join` 和未知路径只显示中性的访问验证或通用拒绝,不说明站点用途;有效 private-link grant 或 public-watch 直链仍直接进入目标房间,正确房间密码从中性表单进入。这只是界面最小暴露,不把可下载的前端代码误当保密边界。建房 HTTP 只认该 cookie且不提供 Bearer 旁路;Host admission endpoint 由部署层/nginx 做 per-source `limit_req`,失败只返回统一结果,不在 Node 新增 IP 身份库/LRU/session 表或持久化来源地址。WebSocket upgrade 继续校验 Origin 与全局/未鉴权容量并记录 cookie 状态,首条 Host `authenticate` 必须同时通过该状态与房间 `hostToken`。Viewer 不经过此 gate,Host cookie 也不能绕过私密房间的 Viewer grant/password。不引入账号、JWT、服务端 session Map 或通用 logout。+- [ ] 房间级观看授权:新房间默认生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。私密房间缺失 grant 时只有正确的该房间观看密码可进入;两者都没有必须 fail closed。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可 rotate 或 revoke;revoke 只锁定 grant 路径,已配置的房间密码仍是独立的后续进入方式。新 grant 摘要成功提交后必须清除 Viewer grace/路由、终止旧授权代次的信令和媒体并断开全部旧 Viewer,数据库写失败则不得改变连接。public-watch 是显式、可逆的 room policy,只放宽观看,不放宽建房或发布。+- [ ] 最小持久化:`ROOM_DATABASE_PATH` 可选且必须与 `HOST_ADMISSION_PASSWORD` 同时配置。两者都存在时,SQLite 只持久保存从 `1` 开始自增的房间 ID、Host token 摘要、nullable Viewer grant 摘要,以及 nullable 48-byte Viewer-password material(16-byte salt + 32-byte scrypt verifier);数据库 `CHECK` 约束非空 BLOB 长度,不新增用户、成员或 session 表。明文房间密码只短暂存在于当前页面和鉴权/派生调用内存,不进入 URL、cookie、浏览器持久存储、日志或 SQLite。持久房间停止后仍显示等待状态;私密邀请按期限或 Host rotate 更新。旧 schema 行在原子迁移时必须 fail-closed 为没有可用明文 grant 的锁定私密状态,Host rotate 后才能生成新邀请。### P1 - 重要功能-- [ ] 私密房间双入口:在不引入账号、密码找回或通用服务端 session 的前提下,private room 同时接受“房间号 + 该房间观看密码”和现有 `/r/{code}#v={grant}` 私密邀请;有效 grant 直接进入目标房间,没有 grant 的 `/join` 或 `/r/{code}` 只显示中性的房间密码输入。Host 可设置或轮换房间观看密码,并可选择复制仅含房间号的入口或默认附带 room-scoped access token 的完整邀请。房间密码、grant 与 verifier 的权限都只能是该房间 Viewer,不得进入 URL query、`localStorage`、日志或 SQLite 明文,也不能取得 Host admission、建房、发布或跨房权限。失败响应不区分房间不存在与密码错误,并复用有界 admission 限制;确切 verifier/KDF 参数必须在目标 1 GiB 部署机基准后选择。该项排在当前自动路由、selected-edge TURN 兜底和 Windows Native 主线之后,不得提前改写生产能力声明。+- [ ] 私密房间双入口:在不引入账号、密码找回或通用服务端 session 的前提下,private room 同时接受“房间号 + 该房间观看密码”和现有 `/r/{code}#v={grant}` 私密邀请;有效 grant 直接进入目标房间,没有 grant 的 `/join` 或 `/r/{code}` 只显示中性的房间密码输入。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符,不要求字符组合复杂度;服务端先以固定保守参数的 Node 异步 scrypt 落地,全局最多执行 2 个、等待 16 个派生,取槽后跳过 stale session,目标 1 GiB 部署机的参数 benchmark 与优化在功能部署后进行。房间密码、grant 与 verifier 的权限都只能是该房间 Viewer;明文密码不得进入 URL/query/cookie、`localStorage`、`sessionStorage`、日志或 SQLite,也不能取得 Host admission、建房、发布或跨房权限。不存在、错误密码、队满和正确密码后的满房都返回通用结果。当前源码候选已实现该最小闭环,线上仍未部署。- [ ] 实验路由按房间灰度:部署开启 `PEER_ASSISTED_MEDIA` 时必须同时提供非空、严格的房间 ID allowlist,只有指定房间进入 peer-assisted 与已配置的 SFU 路径;缺失、空值、非法或重复配置启动即失败,绝不 fail-open 为全房。未命中房间继续使用当前 ordinary P2P 拓扑及其质量拒绝、停止、重连和删除语义,并保持 STUN-only。未来 selected-edge TURN 只能复用同一 controller 的当前 assignment/session/revision/connection generation,不得借 allowlist 向普通 peer edge 预发 TURN candidates。旧 production release 与新 candidate 必须用隔离实例验证和回滚,不能在产品代码建立长期双 transport 分支。exact-room 只服务本阶段验证;验收后以独立 coherent change 退役灰度边界,不能靠清空变量暗中放量。该能力不增加 UI、用户选择、百分比发布或第二套路由器。@@ -77,7 +77,7 @@- 首版不包含远程键鼠控制、公开/大规模直播、录制、社区系统或完整语音聊天;大规模分享直接使用现有直播服务。- public-watch 中房间码本身就是有意公开的观看入口,不提供隐私保证、目录或防转发承诺;随机/自增房间码均不得被描述为私密邀请。现有每房 Viewer 上限、全局/未鉴权连接上限、房间上限和中央 egress/admission cap 仍适用,public-watch 不能创建无界服务器 fanout。-- SQLite 只用于持久房间身份与最小授权摘要:房间 ID、Host token 摘要、nullable Viewer grant 摘要。不得保存 Host admission 密码、token/grant 明文、cookie、显示名、成员、`clientId`、`peerId`、SDP、ICE candidate、IP 地址、媒体或 TURN 凭据;首版仍是单进程、单实例控制面。+- SQLite 只用于持久房间身份与最小授权材料:房间 ID、Host token 摘要、nullable Viewer grant 摘要和 nullable 48-byte Viewer-password salt+verifier。不得保存 Host admission 密码、房间观看密码、token/grant 明文、cookie、显示名、成员、`clientId`、`peerId`、SDP、ICE candidate、IP 地址、媒体或 TURN 凭据;首版仍是单进程、单实例控制面。- 当前八名观看者和 1 至 16 配置范围是接入边界;目标默认 20 也只是通过指定矩阵后的接入边界,不承诺任意机器、档位、网络或跨洲路径都稳定承载。- 浏览器规范要求每次由用户主动选择分享源,权限不能永久保存;纯网页不能保证指定游戏窗口或始终获得系统音频。- 1080p60 是能力目标,实际分辨率、帧率和硬件编码由浏览器、GPU、驱动、画面复杂度及网络共同决定。@@ -95,10 +95,11 @@- Given production Host admission secret 短于 8 bytes、长于 128 bytes 或含非可见 ASCII,When 新 release 启动,Then 必须 fail-fast。Given 同一来源连续提交错误 secret,When 超过 deployment `limit_req` 的 `5r/m`、`burst=5 nodelay` 边界,Then nginx 返回不含凭据的通用限频结果;允许请求的错误值仍使用常量时间比较和统一鉴权失败,limiter 只使用 nginx 内存且不新增 IP 持久化/日志字段。- Given `ROOM_DATABASE_PATH` 为空,When 创建房间,Then 无论是否启用 Host admission 都使用随机临时房间码并遵守 `ROOM_TTL_SECONDS`;停止分享本身不立即销毁房间。- Given 新建私密房间,When 服务端返回邀请并由 Host/Viewer 客户端读取,Then grant 含 256-bit 随机量、只授权该房间 Viewer、只在该页面会话的 room-scoped `sessionStorage` 留存,并在首次读取后从地址栏移除;HTTP request-target、WebSocket URL、Referrer、cookie、`localStorage`、SQLite 明文、日志和错误均不包含 grant。Given 独立页面既无 fragment 也无该 room key,When 尝试进入私密房间,Then 必须要求完整邀请而不是退回 code-only。-- Given Viewer 只有 Host admission cookie、另一个房间的 grant、缺失/过期 grant 或自行把 role 改为 Host,When 首条信令鉴权到达,Then 私密房间返回同一通用无效/过期邀请结果且不泄露房间存在性;不能建房、发布、跨房或绕过 Host token。-- Given Host rotate/revoke 私密邀请或把 public-watch 改为私密,When 新摘要持久化成功,Then 服务端先提交新授权代次,再清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 和 public-to-private 各返回一次新 grant,revoke 不返回 grant 且保持 locked-private,旧页面停止自动重连。Given 持久化失败,Then 旧摘要、连接和媒体保持不变。+- Given Viewer 只有 Host admission cookie、另一个房间的 grant、缺失/过期 grant 且没有正确房间密码,或自行把 role 改为 Host,When 首条信令鉴权到达,Then 私密房间返回同一通用无效结果且不泄露房间存在性;不能建房、发布、跨房或绕过 Host token。+- Given Host rotate/revoke 私密邀请或把 public-watch 改为私密,When 新摘要持久化成功,Then 服务端先提交新授权代次,再清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 和 public-to-private 各返回一次新 grant,revoke 不返回 grant 且锁定 grant 路径,已配置的房间密码仍是独立的以后进入方式。Given 持久化失败,Then 旧摘要、连接和媒体保持不变。- Given 房间处于 public-watch,When 用户只输入房间码,Then 可在现有 Viewer/连接/egress 上限内观看,但仍不能创建房间、取得 Host 角色或枚举房间目录;Host 切回私密时签发新 grant 并撤销现有 code-only Viewer。-- Given schema v1 SQLite 在备份后首次由新 release 打开,When 单事务升级到 v2,Then 只新增 `viewer_grant_digest BLOB NULL CHECK (viewer_grant_digest IS NULL OR length(viewer_grant_digest) = 32)`,旧行被置为未生成对应 grant 的锁定私密摘要;旧 Host token 仍可回收房间并 rotate,旧 Viewer 链接不能 fail-open。畸形非空值必须拒绝写入或读取时 fail closed;回滚旧 binary 必须恢复迁移前备份,不运行双 schema 代码。+- Given private room 配置了观看密码,When Viewer 仅以房间号访问,Then 未授权页面只显示中性密码表单;正确密码只鉴权当前 Viewer 会话,错误密码与不存在房间返回同一通用结果。Given Host 改密或移除,Then 旧密码的以后鉴权失败,现有 fragment grant 仍可直接进入;public-watch 纯房间码仍直接进入。+- Given schema v1 或 v2 SQLite 在备份后首次由新 release 打开,When 单事务升级到 v3,Then v1 先补 checked `viewer_grant_digest` 并 fail-closed 锁定旧行,v1/v2 都新增 `viewer_password_material BLOB NULL CHECK (viewer_password_material IS NULL OR length(viewer_password_material) = 48)`;旧 Host token 仍可回收房间,旧 Viewer 链接不能 fail-open。畸形非空值必须拒绝写入或读取时 fail closed;回滚旧 binary 必须恢复迁移前备份,不运行双 schema 代码。- Given 部署切换了不兼容的当前协议,When 仍打开的旧页面连接新服务端,Then 单一 release/protocol mismatch 边界终止该 session、停止自动重连并明确提示刷新;不得通过旧 parser、双写或双协议继续假连接。### P2P、SFU 与可选 TURN 兜底diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex 35a1ed74..b32d34df 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -3,18 +3,22 @@ import {Copy,Globe2,Hash,+ KeyRound,LockKeyhole,MonitorUp,Pause,Play,RefreshCw,Square,+ Trash2,Users,} from "lucide-react";import { useEffect, useMemo, useRef, useState } from "react";import {DEFAULT_QUALITY_SETTINGS,+ MAX_VIEWER_PASSWORD_LENGTH,VIEWER_QUALITY_EVIDENCE_EXPIRY_MS,+ viewerPasswordSchema,type CreateRoomResponse,type IceConfig,type ServerMessage,@@ -185,6 +189,9 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const [newRoomViewerPolicy, setNewRoomViewerPolicy] =useState<ViewerAccessPolicy>("private-link");const [viewerAccessUpdating, setViewerAccessUpdating] = useState(false);+ const [viewerPasswordEnabled, setViewerPasswordEnabled] = useState(false);+ const [viewerPasswordDraft, setViewerPasswordDraft] = useState("");+ const [viewerPasswordUpdating, setViewerPasswordUpdating] = useState(false);const [maxViewers, setMaxViewers] = useState<number | null>(null);const [peerSnapshots, setPeerSnapshots] = useState<Map<string, PeerSnapshot>>(() => new Map(),@@ -205,6 +212,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {const videoRef = useRef<HTMLVideoElement | null>(null);const streamRef = useRef<MediaStream | null>(null);const signalRef = useRef<SignalingClient | null>(null);+ const viewerPasswordActionRef = useRef<"set" | "remove" | null>(null);const iceConfigRef = useRef<IceConfig | null>(null);const peersRef = useRef(new Map<string, HostPeer>());const retiredConnectionsRef = useRef(new Map<string, string>());@@ -888,6 +896,19 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {);return;}+ if (message.type === "viewer-password-updated") {+ const action = viewerPasswordActionRef.current;+ viewerPasswordActionRef.current = null;+ setViewerPasswordEnabled(message.enabled);+ setViewerPasswordUpdating(false);+ setViewerPasswordDraft("");+ if (action) {+ setNotice(+ action === "remove" ? "访问密码已移除" : "访问密码已更新",+ );+ }+ return;+ }if (message.type === "viewer-presence") {setViewerPresence(message.viewers);return;@@ -975,6 +996,8 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}if (message.type === "error") {setViewerAccessUpdating(false);+ setViewerPasswordUpdating(false);+ viewerPasswordActionRef.current = null;if (["INVALID_TOKEN", "ROOM_EXPIRED"].includes(message.code)) {forgetRoom();endSharing("房间已失效,再次点击将创建新房", false);@@ -1068,6 +1091,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {clientId: getStableClientId("host", activeRoom.roomId),shareGeneration,viewerPresence: true,+ viewerPasswordSettings: true,},{onStatus: (status) => {@@ -1322,6 +1346,30 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {setNotice(null);}+ function changeViewerPassword(password: string | null): void {+ if (+ password !== null &&+ !viewerPasswordSchema.safeParse(password).success+ ) {+ setNotice(+ `访问密码只需 1-${MAX_VIEWER_PASSWORD_LENGTH} 个可见字符`,+ );+ return;+ }+ if (+ viewerPasswordUpdating ||+ phase !== "live" ||+ !signalRef.current?.send({ type: "set-viewer-password", password })+ ) {+ setNotice("开始分享并连接后才能修改访问密码");+ return;+ }+ viewerPasswordActionRef.current = password === null ? "remove" : "set";+ setViewerPasswordUpdating(true);+ setViewerPasswordDraft("");+ setNotice(null);+ }+const expirationText = room? room.expiresAt? `${new Intl.DateTimeFormat("zh-CN", {@@ -1717,6 +1765,61 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {</>)}</div>+ {room.viewerPolicy === "private-link" && (+ <form+ className="viewer-password-control"+ onSubmit={(event) => {+ event.preventDefault();+ changeViewerPassword(viewerPasswordDraft);+ }}+ >+ <label htmlFor="viewer-password">访问密码</label>+ <span className="input-with-icon">+ <KeyRound size={16} aria-hidden="true" />+ <input+ id="viewer-password"+ type="password"+ value={viewerPasswordDraft}+ maxLength={MAX_VIEWER_PASSWORD_LENGTH}+ autoComplete="new-password"+ placeholder={+ viewerPasswordEnabled ? "输入新密码" : "设置密码"+ }+ disabled={viewerPasswordUpdating || phase !== "live"}+ onChange={(event) =>+ setViewerPasswordDraft(event.target.value)+ }+ />+ </span>+ <button+ className="icon-button"+ type="submit"+ title={viewerPasswordEnabled ? "更改访问密码" : "设置访问密码"}+ aria-label={+ viewerPasswordEnabled ? "更改访问密码" : "设置访问密码"+ }+ disabled={+ viewerPasswordUpdating ||+ phase !== "live" ||+ viewerPasswordDraft.length === 0+ }+ >+ <Check size={18} />+ </button>+ {viewerPasswordEnabled && (+ <button+ className="icon-button"+ type="button"+ title="移除访问密码"+ aria-label="移除访问密码"+ disabled={viewerPasswordUpdating || phase !== "live"}+ onClick={() => changeViewerPassword(null)}+ >+ <Trash2 size={18} />+ </button>+ )}+ </form>+ )}</div>)}</section>diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsxindex bc4da12d..f3611f69 100644--- a/src/client/pages/ViewerPage.tsx+++ b/src/client/pages/ViewerPage.tsx@@ -1,4 +1,5 @@import {+ KeyRound,LoaderCircle,Maximize2,Play,@@ -11,7 +12,9 @@ import {import { useEffect, useMemo, useRef, useState } from "react";import {DEFAULT_QUALITY_SETTINGS,+ MAX_VIEWER_PASSWORD_LENGTH,VIEWER_QUALITY_EVIDENCE_EXPIRY_MS,+ viewerPasswordSchema,type IceConfig,type MediaAssignment,type ServerMessage,@@ -94,6 +97,14 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {const [displayName, setDisplayName] = useState(() => readDisplayName());const [displayNameDraft, setDisplayNameDraft] = useState(displayName);const [displayNameError, setDisplayNameError] = useState<string | null>(null);+ const [viewerPasswordDraft, setViewerPasswordDraft] = useState("");+ const [viewerPasswordError, setViewerPasswordError] = useState<string | null>(+ null,+ );+ const [viewerPasswordAttempt, setViewerPasswordAttempt] = useState<{+ password: string;+ sequence: number;+ } | null>(null);const qualityLimitation = useMemo(() =>@@ -156,6 +167,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {role: "viewer",clientId: getStableClientId("viewer", roomId),...(viewerGrant ? { viewerGrant } : {}),+ ...(!viewerGrant && viewerPasswordAttempt+ ? { viewerPassword: viewerPasswordAttempt.password }+ : {}),displayName: displayNameRef.current,},{@@ -540,6 +554,8 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {selectedEdgeTurn = null;viewerAuthenticated = true;setAccessState("ready");+ setViewerPasswordDraft("");+ setViewerPasswordError(null);clearRelayChildEvidence();currentPeerId = message.peerId;viewerAuthorizationGeneration =@@ -801,6 +817,9 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {}if (message.code === "INVALID_TOKEN") {clearViewerGrant(roomId);+ if (!viewerGrant && viewerPasswordAttempt) {+ setViewerPasswordError("访问验证失败,请重试");+ }setStatusText("邀请无效或已失效");return;}@@ -833,7 +852,7 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {viewerRelay?.dispose();viewerRelay = null;};- }, [roomId, viewerGrant]);+ }, [roomId, viewerGrant, viewerPasswordAttempt]);useEffect(() => {const video = videoRef.current;@@ -930,6 +949,22 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {signalRef.current?.setViewerDisplayName(saved);}+ function submitViewerPassword(event: React.FormEvent<HTMLFormElement>): void {+ event.preventDefault();+ if (!viewerPasswordSchema.safeParse(viewerPasswordDraft).success) {+ setViewerPasswordError(+ `请输入 1-${MAX_VIEWER_PASSWORD_LENGTH} 个可见字符`,+ );+ return;+ }+ setViewerPasswordError(null);+ setAccessState("checking");+ setViewerPasswordAttempt((current) => ({+ password: viewerPasswordDraft,+ sequence: (current?.sequence ?? 0) + 1,+ }));+ }+if (accessState !== "ready") {return (<div className="app-shell">@@ -939,10 +974,42 @@ export function ViewerPage({ roomId, viewerGrant }: ViewerPageProps) {<LoaderCircle size={20} className="spin" aria-hidden="true" />正在验证</div>- ) : (+ ) : viewerGrant ? (<section className="access-panel"><h1>无法访问</h1></section>+ ) : (+ <form className="access-panel" onSubmit={submitViewerPassword}>+ <div>+ <h1>访问验证</h1>+ <p className="section-meta">请输入访问密码</p>+ </div>+ <label className="token-field">+ <span>访问密码</span>+ <span className="input-with-icon">+ <KeyRound size={16} aria-hidden="true" />+ <input+ type="password"+ value={viewerPasswordDraft}+ maxLength={MAX_VIEWER_PASSWORD_LENGTH}+ autoComplete="current-password"+ autoFocus+ onChange={(event) => {+ setViewerPasswordDraft(event.target.value);+ setViewerPasswordError(null);+ }}+ />+ </span>+ </label>+ {viewerPasswordError && (+ <p className="access-error" role="alert">+ {viewerPasswordError}+ </p>+ )}+ <button className="button button-primary" type="submit">+ 进入+ </button>+ </form>)}</main></div>diff --git a/src/client/styles.css b/src/client/styles.cssindex 0e88ba7f..fd46ab88 100644--- a/src/client/styles.css+++ b/src/client/styles.css@@ -704,6 +704,7 @@ h3 {.invite-bar {display: flex;+ flex-wrap: wrap;min-width: 0;gap: 12px;align-items: center;@@ -725,6 +726,30 @@ h3 {gap: 6px;}+.viewer-password-control {+ display: grid;+ grid-template-columns: auto minmax(160px, 240px) 40px 40px;+ width: 100%;+ gap: 6px;+ align-items: center;+ padding-top: 10px;+ border-top: 1px solid var(--border);+}++.viewer-password-control > label {+ color: var(--muted);+ font-size: 12px;+}++.viewer-password-control .input-with-icon {+ min-width: 0;+}++.viewer-password-control input {+ min-width: 0;+ width: 100%;+}+.invite-copy .field-label {margin-bottom: 3px;}@@ -1154,6 +1179,14 @@ h3 {align-items: flex-end;}+ .viewer-password-control {+ grid-template-columns: minmax(0, 1fr) 40px 40px;+ }++ .viewer-password-control > label {+ grid-column: 1 / -1;+ }+.viewer-stats .stats-grid {grid-template-columns: repeat(2, minmax(0, 1fr));}diff --git a/src/server/room-database.ts b/src/server/room-database.tsindex fe1129c4..5b37a85f 100644--- a/src/server/room-database.ts+++ b/src/server/room-database.ts@@ -1,13 +1,14 @@import { randomBytes } from "node:crypto";import { DatabaseSync } from "node:sqlite";-const SCHEMA_VERSION = 2;+const SCHEMA_VERSION = 3;const MAX_ROOM_ID = 999_999_999_999;export interface StoredRoom {roomId: string;hostTokenDigest: Buffer;viewerGrantDigest: Buffer | null;+ viewerPasswordMaterial: Buffer | null;}export class RoomDatabase {@@ -28,7 +29,9 @@ export class RoomDatabase {loadRooms(): StoredRoom[] {const rows = this.database.prepare(- "SELECT id, host_token_digest, viewer_grant_digest FROM rooms ORDER BY id",+ `SELECT id, host_token_digest, viewer_grant_digest,+ viewer_password_material+ FROM rooms ORDER BY id`,).all();@@ -44,6 +47,11 @@ export class RoomDatabase {roomId: roomId.toString(),hostTokenDigest: Buffer.from(row.host_token_digest),viewerGrantDigest: readViewerGrantDigest(row.viewer_grant_digest),+ viewerPasswordMaterial: readNullableBytes(+ row.viewer_password_material,+ 48,+ "viewer password material",+ ),};});}@@ -79,6 +87,7 @@ export class RoomDatabase {hostTokenDigest: Buffer.from(hostTokenDigest),viewerGrantDigest:viewerGrantDigest === null ? null : Buffer.from(viewerGrantDigest),+ viewerPasswordMaterial: null,};} catch (error) {if (this.database.isTransaction) {@@ -104,6 +113,26 @@ export class RoomDatabase {}}+ updateViewerPassword(+ roomId: string,+ material: Buffer | null,+ ): void {+ const numericRoomId = parseRoomId(roomId);+ if (material) {+ assertBytes(material, 48, "Viewer password material");+ }+ const changes = this.database+ .prepare(+ `UPDATE rooms+ SET viewer_password_material = ?+ WHERE id = ?`,+ )+ .run(material, numericRoomId).changes;+ if (changes !== 1) {+ throw new Error("Persistent room is missing from the room database");+ }+ }+deleteRoom(roomId: string): boolean {const numericRoomId = parseRoomId(roomId);return (@@ -124,6 +153,10 @@ export class RoomDatabase {if (version === SCHEMA_VERSION) {return;}+ if (version === 2) {+ this.migrateV2();+ return;+ }if (version === 1) {this.migrateV1();return;@@ -144,6 +177,11 @@ export class RoomDatabase {CHECK (viewer_grant_digest IS NULL ORlength(viewer_grant_digest) = 32+ ),+ viewer_password_material BLOB NULL+ CHECK (+ viewer_password_material IS NULL OR+ length(viewer_password_material) = 48)) STRICT;PRAGMA user_version = ${SCHEMA_VERSION};@@ -166,6 +204,11 @@ export class RoomDatabase {viewer_grant_digest IS NULL ORlength(viewer_grant_digest) = 32);+ ALTER TABLE rooms ADD COLUMN viewer_password_material BLOB NULL+ CHECK (+ viewer_password_material IS NULL OR+ length(viewer_password_material) = 48+ );`);const roomIds = this.database.prepare("SELECT id FROM rooms ORDER BY id").all();const lockRoom = this.database.prepare(@@ -187,6 +230,26 @@ export class RoomDatabase {throw error;}}++ private migrateV2(): void {+ this.database.exec("BEGIN IMMEDIATE");+ try {+ this.database.exec(`+ ALTER TABLE rooms ADD COLUMN viewer_password_material BLOB NULL+ CHECK (+ viewer_password_material IS NULL OR+ length(viewer_password_material) = 48+ );+ PRAGMA user_version = ${SCHEMA_VERSION};+ COMMIT;+ `);+ } catch (error) {+ if (this.database.isTransaction) {+ this.database.exec("ROLLBACK");+ }+ throw error;+ }+ }}function assertDigest(value: Buffer, name: string): void {@@ -195,6 +258,26 @@ function assertDigest(value: Buffer, name: string): void {}}+function assertBytes(value: Buffer, length: number, name: string): void {+ if (value.byteLength !== length) {+ throw new Error(`${name} must contain ${length} bytes`);+ }+}++function readNullableBytes(+ value: unknown,+ length: number,+ name: string,+): Buffer | null {+ if (value === null) {+ return null;+ }+ if (!(value instanceof Uint8Array) || value.byteLength !== length) {+ throw new Error(`Room database contains an invalid ${name}`);+ }+ return Buffer.from(value);+}+function readViewerGrantDigest(value: unknown): Buffer | null {if (value === null) {return null;diff --git a/src/server/room-store.ts b/src/server/room-store.tsindex 4afe8de8..62c177be 100644--- a/src/server/room-store.ts+++ b/src/server/room-store.ts@@ -1,10 +1,16 @@-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";+import {+ createHash,+ randomBytes,+ scrypt,+ timingSafeEqual,+} from "node:crypto";import {MAX_HOST_CLAIM_TTL_SECONDS,MAX_VIEWERS_PER_ROOM_LIMIT,ROOM_CODE_LENGTH,viewerGrantSchema,+ viewerPasswordSchema,type Role,type ViewerAccessPolicy,} from "../shared/protocol.js";@@ -18,6 +24,21 @@ export type RoomStoreErrorCode =| "ROOM_LIMIT";const PERSISTENT_VIEWER_GRANT_TTL_MS = 7 * 24 * 60 * 60 * 1_000;+const VIEWER_PASSWORD_SALT_BYTES = 16;+const VIEWER_PASSWORD_VERIFIER_BYTES = 32;+const VIEWER_PASSWORD_MATERIAL_BYTES =+ VIEWER_PASSWORD_SALT_BYTES + VIEWER_PASSWORD_VERIFIER_BYTES;+const VIEWER_PASSWORD_KDF_CONCURRENCY = 2;+const VIEWER_PASSWORD_KDF_PENDING_LIMIT = 16;+const VIEWER_PASSWORD_SCRYPT_OPTIONS = {+ N: 16_384,+ r: 8,+ p: 1,+ maxmem: 32 * 1024 * 1024,+} as const;+const DUMMY_VIEWER_PASSWORD_MATERIAL = Buffer.alloc(+ VIEWER_PASSWORD_MATERIAL_BYTES,+);export class RoomStoreError extends Error {constructor(public readonly code: RoomStoreErrorCode) {@@ -36,6 +57,7 @@ interface Room {roomId: string;hostTokenDigest: Buffer;viewerGrantDigest: Buffer | null;+ viewerPasswordMaterial: Buffer | null;viewerAuthorizationGeneration: string;expiresAtMs: number | null;provisionalHostExpiresAtMs: number | null;@@ -68,6 +90,13 @@ export type ConnectParticipantInput =sessionId: string;};+export interface ConnectViewerWithPasswordInput {+ roomId: string;+ password: string;+ clientId: string;+ sessionId: string;+}+export interface ConnectedParticipant {roomId: string;role: Role;@@ -77,6 +106,7 @@ export interface ConnectedParticipant {replacedSessionId?: string;viewerPeerIds: readonly string[];viewerPolicy: ViewerAccessPolicy;+ viewerPasswordEnabled: boolean;viewerAuthorizationGeneration: string;}@@ -157,6 +187,10 @@ export class RoomStore {storedRoom.viewerGrantDigest === null? null: Buffer.from(storedRoom.viewerGrantDigest),+ viewerPasswordMaterial:+ storedRoom.viewerPasswordMaterial === null+ ? null+ : Buffer.from(storedRoom.viewerPasswordMaterial),viewerAuthorizationGeneration: this.newAuthorizationGeneration(),expiresAtMs: null,provisionalHostExpiresAtMs: null,@@ -238,6 +272,7 @@ export class RoomStore {roomId,hostTokenDigest,viewerGrantDigest,+ viewerPasswordMaterial: null,viewerAuthorizationGeneration,expiresAtMs,provisionalHostExpiresAtMs,@@ -277,6 +312,129 @@ export class RoomStore {return this.connectViewer(room, input);}+ async connectViewerWithPassword(+ input: ConnectViewerWithPasswordInput,+ mayConnect: () => boolean = () => true,+ ): Promise<ConnectedParticipant> {+ if (!viewerPasswordSchema.safeParse(input.password).success) {+ throw new RoomStoreError("INVALID_TOKEN");+ }++ let room: Room | undefined;+ try {+ room = this.getAvailableRoom(input.roomId);+ } catch (error) {+ if (!(error instanceof RoomStoreError)) {+ throw error;+ }+ }+ if (room?.viewerGrantDigest === null) {+ if (!mayConnect()) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ return this.connectViewer(room, { ...input, role: "viewer" });+ }++ const expectedMaterial = Buffer.from(+ room?.viewerPasswordMaterial ?? DUMMY_VIEWER_PASSWORD_MATERIAL,+ );+ const expectedSalt = expectedMaterial.subarray(+ 0,+ VIEWER_PASSWORD_SALT_BYTES,+ );+ const expectedVerifier = expectedMaterial.subarray(+ VIEWER_PASSWORD_SALT_BYTES,+ );+ const derived = await deriveViewerPassword(+ input.password,+ expectedSalt,+ mayConnect,+ );+ if (derived === null) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ const matches = timingSafeEqual(derived, expectedVerifier);++ let currentRoom: Room;+ try {+ currentRoom = this.getAvailableRoom(input.roomId);+ } catch (error) {+ if (error instanceof RoomStoreError) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ throw error;+ }+ if (currentRoom.viewerGrantDigest === null) {+ if (!mayConnect()) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ return this.connectViewer(currentRoom, { ...input, role: "viewer" });+ }+ if (+ !room ||+ currentRoom !== room ||+ !matches ||+ !sameBytes(currentRoom.viewerPasswordMaterial, expectedMaterial) ||+ !mayConnect()+ ) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ try {+ return this.connectViewer(currentRoom, { ...input, role: "viewer" });+ } catch (error) {+ if (error instanceof RoomStoreError && error.code === "ROOM_FULL") {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ throw error;+ }+ }++ async setViewerPassword(+ roomId: string,+ password: string | null,+ hostSessionId: string,+ ): Promise<boolean> {+ const room = this.getAvailableRoom(roomId);+ if (room.host?.sessionId !== hostSessionId) {+ throw new RoomStoreError("INVALID_TOKEN");+ }++ let nextPasswordMaterial: Buffer | null = null;+ if (password !== null) {+ if (!viewerPasswordSchema.safeParse(password).success) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ const salt = this.random(VIEWER_PASSWORD_SALT_BYTES);+ if (salt.byteLength !== VIEWER_PASSWORD_SALT_BYTES) {+ throw new Error("Viewer password salt source must return 16 bytes");+ }+ const verifier = await deriveViewerPassword(password, salt, () => {+ const currentRoom = this.rooms.get(roomId);+ return (+ currentRoom === room &&+ currentRoom.host?.sessionId === hostSessionId+ );+ });+ if (verifier === null) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ nextPasswordMaterial = Buffer.concat([salt, verifier]);+ }++ const currentRoom = this.getAvailableRoom(roomId);+ if (+ currentRoom !== room ||+ currentRoom.host?.sessionId !== hostSessionId+ ) {+ throw new RoomStoreError("INVALID_TOKEN");+ }+ if (currentRoom.expiresAtMs === null) {+ this.options.database?.updateViewerPassword(roomId, nextPasswordMaterial);+ }+ currentRoom.viewerPasswordMaterial = nextPasswordMaterial;+ return nextPasswordMaterial !== null;+ }+setViewerAccess(roomId: string,action: "public-watch" | "rotate" | "revoke",@@ -483,6 +641,7 @@ export class RoomStore {// Disconnected viewers remain room members until their grace period ends.viewerPeerIds: [...room.viewers.values()].map((viewer) => viewer.peerId),viewerPolicy: viewerPolicy(room),+ viewerPasswordEnabled: room.viewerPasswordMaterial !== null,viewerAuthorizationGeneration: room.viewerAuthorizationGeneration,};}@@ -516,6 +675,7 @@ export class RoomStore {replacedSessionId === input.sessionId ? undefined : replacedSessionId,viewerPeerIds: [],viewerPolicy: viewerPolicy(room),+ viewerPasswordEnabled: room.viewerPasswordMaterial !== null,viewerAuthorizationGeneration: room.viewerAuthorizationGeneration,};}@@ -658,6 +818,81 @@ function verifyDigest(value: string, expectedDigest: Buffer): boolean {return timingSafeEqual(digest(value), expectedDigest);}+function sameBytes(value: Buffer | null, expected: Buffer): boolean {+ return value !== null && timingSafeEqual(value, expected);+}++function deriveViewerPassword(+ password: string,+ salt: Buffer,+ mayStart: () => boolean = () => true,+): Promise<Buffer | null> {+ return viewerPasswordKdfGate.run(+ () =>+ new Promise<Buffer>((resolve, reject) => {+ scrypt(+ password,+ salt,+ VIEWER_PASSWORD_VERIFIER_BYTES,+ VIEWER_PASSWORD_SCRYPT_OPTIONS,+ (error, derivedKey) => (error ? reject(error) : resolve(derivedKey)),+ );+ }),+ mayStart,+ );+}++class AsyncGate {+ private active = 0;+ private readonly waiters: Array<() => void> = [];++ constructor(+ private readonly limit: number,+ private readonly pendingLimit: number,+ ) {}++ async run<T>(+ task: () => Promise<T>,+ mayStart: () => boolean,+ ): Promise<T | null> {+ if (!(await this.acquire())) {+ return null;+ }+ try {+ return mayStart() ? await task() : null;+ } finally {+ this.release();+ }+ }++ private acquire(): Promise<boolean> {+ if (this.active >= this.limit) {+ if (this.waiters.length >= this.pendingLimit) {+ return Promise.resolve(false);+ }+ return new Promise<boolean>((resolve) =>+ this.waiters.push(() => resolve(true)),+ );+ }+ this.active += 1;+ return Promise.resolve(true);+ }++ private release(): void {+ const next = this.waiters.shift();+ if (next) {+ next();+ return;+ }+ this.active -= 1;+ }+}++const viewerPasswordKdfGate = new AsyncGate(+ VIEWER_PASSWORD_KDF_CONCURRENCY,+ VIEWER_PASSWORD_KDF_PENDING_LIMIT,+);+function viewerPolicy(room: Room): ViewerAccessPolicy {return room.viewerGrantDigest === null ? "public-watch" : "private-link";}diff --git a/src/server/signaling.ts b/src/server/signaling.tsindex 94601f77..975cdf03 100644--- a/src/server/signaling.ts+++ b/src/server/signaling.ts@@ -46,6 +46,7 @@ interface AuthenticatedSession {shareGeneration: string | null;displayName: string | null;viewerPresence: boolean;+ viewerPasswordSettings: boolean;}interface SocketState {@@ -54,6 +55,8 @@ interface SocketState {authenticationTimer: NodeJS.Timeout;hostAdmissionAuthenticated: boolean;revoked?: boolean;+ authenticating?: boolean;+ viewerPasswordUpdatePending?: boolean;authenticated?: AuthenticatedSession;}@@ -315,7 +318,16 @@ export class SignalingServer {socket.close(4001, "Authentication required");return;}- this.authenticate(socket, state, message);+ if (state.authenticating) {+ this.rejectInvalidMessage(socket);+ return;+ }+ state.authenticating = true;+ void this.authenticate(socket, state, message).finally(() => {+ if (this.socketStates.get(socket) === state) {+ state.authenticating = false;+ }+ });return;}if (message.type === "authenticate") {@@ -338,11 +350,11 @@ export class SignalingServer {this.handleAuthenticatedMessage(socket, state.authenticated, message);}- private authenticate(+ private async authenticate(socket: WebSocket,state: SocketState,message: Extract<ClientMessage, { type: "authenticate" }>,- ): void {+ ): Promise<void> {if (message.role === "host" && !state.hostAdmissionAuthenticated) {this.sendError(socket, "AUTH_REQUIRED", "Host admission is required");socket.close(4003, "Authentication failed");@@ -351,26 +363,49 @@ export class SignalingServer {let participant;try {- participant = this.options.roomStore.connectParticipant(- message.role === "host"- ? {- roomId: message.roomId,- role: "host",- token: message.token,- clientId: message.clientId,- sessionId: state.sessionId,- }- : {- roomId: message.roomId,- role: "viewer",- ...(message.viewerGrant- ? { viewerGrant: message.viewerGrant }- : {}),- clientId: message.clientId,- sessionId: state.sessionId,- },- );+ if (+ message.role === "viewer" &&+ !message.viewerGrant &&+ message.viewerPassword !== undefined+ ) {+ participant = await this.options.roomStore.connectViewerWithPassword(+ {+ roomId: message.roomId,+ password: message.viewerPassword,+ clientId: message.clientId,+ sessionId: state.sessionId,+ },+ () =>+ this.socketStates.get(socket) === state &&+ !state.revoked &&+ !state.authenticated &&+ socket.readyState === WebSocket.OPEN,+ );+ } else {+ participant = this.options.roomStore.connectParticipant(+ message.role === "host"+ ? {+ roomId: message.roomId,+ role: "host",+ token: message.token,+ clientId: message.clientId,+ sessionId: state.sessionId,+ }+ : {+ roomId: message.roomId,+ role: "viewer",+ ...(message.viewerGrant+ ? { viewerGrant: message.viewerGrant }+ : {}),+ clientId: message.clientId,+ sessionId: state.sessionId,+ },+ );+ }} catch (error) {+ if (this.socketStates.get(socket) !== state || state.revoked) {+ return;+ }if (!(error instanceof RoomStoreError)) {console.error("Signaling authentication failed unexpectedly");}@@ -414,6 +449,7 @@ export class SignalingServer {? (message.displayName ?? DEFAULT_VIEWER_DISPLAY_NAME): null,viewerPresence: false,+ viewerPasswordSettings: false,};if (participant.role === "viewer") {this.viewerQualityEvidenceGates.delete(@@ -483,6 +519,14 @@ export class SignalingServer {}state.authenticated.viewerPresence =message.role === "host" && message.viewerPresence === true;+ state.authenticated.viewerPasswordSettings =+ message.role === "host" && message.viewerPasswordSettings === true;+ if (state.authenticated.viewerPasswordSettings) {+ this.send(socket, {+ type: "viewer-password-updated",+ enabled: participant.viewerPasswordEnabled,+ });+ }if (participant.replacedSessionId) {const replaced = this.socketsBySessionId.get(participant.replacedSessionId);@@ -668,6 +712,36 @@ export class SignalingServer {}this.updateViewerAccess(socket, authenticated, message.action);return;+ case "set-viewer-password": {+ if (+ authenticated.role !== "host" ||+ !authenticated.viewerPasswordSettings+ ) {+ this.sendError(+ socket,+ "FORBIDDEN",+ "Viewer password settings are unavailable",+ );+ return;+ }+ const socketState = this.socketStates.get(socket);+ if (!socketState || socketState.viewerPasswordUpdatePending) {+ this.sendError(socket, "FORBIDDEN", "Viewer password update is busy");+ return;+ }+ socketState.viewerPasswordUpdatePending = true;+ void this.updateViewerPassword(+ socket,+ authenticated,+ socketState,+ message.password,+ ).finally(() => {+ if (this.socketStates.get(socket) === socketState) {+ socketState.viewerPasswordUpdatePending = false;+ }+ });+ return;+ }case "stop-sharing":if (authenticated.role !== "host") {this.sendError(socket, "FORBIDDEN", "Only the host may stop sharing");@@ -787,6 +861,42 @@ export class SignalingServer {});}+ private async updateViewerPassword(+ hostSocket: WebSocket,+ authenticated: AuthenticatedSession,+ state: SocketState,+ password: string | null,+ ): Promise<void> {+ try {+ const enabled = await this.options.roomStore.setViewerPassword(+ authenticated.roomId,+ password,+ state.sessionId,+ );+ if (+ this.socketStates.get(hostSocket) !== state ||+ state.authenticated !== authenticated ||+ state.revoked+ ) {+ return;+ }+ this.send(hostSocket, { type: "viewer-password-updated", enabled });+ } catch {+ if (+ this.socketStates.get(hostSocket) === state &&+ state.authenticated === authenticated &&+ !state.revoked+ ) {+ console.error("Viewer password update failed");+ this.sendError(+ hostSocket,+ "SERVER_ERROR",+ "Viewer password could not be updated",+ );+ }+ }+ }+private handleViewerQualityEvidence(socket: WebSocket,source: AuthenticatedSession,diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex ab0c57ae..61c513c8 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -16,6 +16,8 @@ export const VIEWER_QUALITY_EVIDENCE_INTERVAL_MS = 2_000;export const VIEWER_QUALITY_EVIDENCE_EXPIRY_MS = 5_000;export const MAX_DISPLAY_NAME_CODE_POINTS = 24;export const DEFAULT_VIEWER_DISPLAY_NAME = "访客";+export const MIN_VIEWER_PASSWORD_LENGTH = 1;+export const MAX_VIEWER_PASSWORD_LENGTH = 64;const FORBIDDEN_DISPLAY_NAME_CHARACTERS =/[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff]/u;@@ -82,6 +84,13 @@ export const viewerGrantSchema = z.max(96).regex(/^g1\.[1-9]\d{0,11}\.[1-9]\d{0,12}\.[A-Za-z0-9_-]{43}$/);+export const viewerPasswordSchema = z+ .string()+ .min(MIN_VIEWER_PASSWORD_LENGTH)+ .max(MAX_VIEWER_PASSWORD_LENGTH)+ .regex(/^[\x21-\x7e]+$/);+export type ViewerPassword = z.infer<typeof viewerPasswordSchema>;+export const viewerAccessPolicySchema = z.enum(["private-link","public-watch",@@ -466,6 +475,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [clientId: opaqueIdSchema,shareGeneration: opaqueIdSchema.optional(),viewerPresence: z.literal(true).optional(),+ viewerPasswordSettings: z.literal(true).optional(),}).strict(),z@@ -476,6 +486,7 @@ const authenticateMessageSchema = z.discriminatedUnion("role", [role: z.literal("viewer"),clientId: opaqueIdSchema,viewerGrant: viewerGrantSchema.optional(),+ viewerPassword: viewerPasswordSchema.optional(),displayName: displayNameSchema.optional(),}).strict(),@@ -545,6 +556,12 @@ export const clientMessageSchema = z.union([action: z.enum(["public-watch", "rotate", "revoke"]),}).strict(),+ z+ .object({+ type: z.literal("set-viewer-password"),+ password: viewerPasswordSchema.nullable(),+ })+ .strict(),z.object({type: z.literal("stop-sharing"),@@ -721,6 +738,12 @@ export const serverMessageSchema = z.union([viewerAuthorizationGeneration: opaqueIdSchema,}).strict(),+ z+ .object({+ type: z.literal("viewer-password-updated"),+ enabled: z.boolean(),+ })+ .strict(),z.object({ type: z.literal("sharing-stopped") }).strict(),z.object({diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex 8e93c931..2c1c5b83 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -8,6 +8,7 @@ import {MAX_PARENT_EDGE_QUALITY_EVIDENCE_BYTES,MAX_SFU_TOKEN_LENGTH,MAX_VIEWER_QUALITY_EVIDENCE_BYTES,+ MAX_VIEWER_PASSWORD_LENGTH,MAX_VIEWERS_PER_ROOM_LIMIT,SIGNALING_PROTOCOL,clientMessageSchema,@@ -16,6 +17,7 @@ import {normalizeDisplayName,participantRouteAssignmentSchema,serverMessageSchema,+ viewerPasswordSchema,} from "../src/shared/protocol.js";const token = "a".repeat(43);@@ -224,6 +226,53 @@ describe("client signaling protocol", () => {).toBe(false);});+ it("accepts simple bounded Viewer passwords and the Web Host capability", () => {+ expect(viewerPasswordSchema.safeParse("x").success).toBe(true);+ expect(viewerPasswordSchema.safeParse("simple-password").success).toBe(true);+ for (const invalid of [+ "",+ "contains space",+ "line\nbreak",+ "x".repeat(MAX_VIEWER_PASSWORD_LENGTH + 1),+ ]) {+ expect(viewerPasswordSchema.safeParse(invalid).success).toBe(false);+ }++ expect(+ clientMessageSchema.safeParse({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId,+ role: "viewer",+ clientId: "client_12345678",+ viewerPassword: "easy-password",+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId,+ role: "host",+ token,+ clientId: "client_12345678",+ viewerPasswordSettings: true,+ }).success,+ ).toBe(true);+ expect(+ clientMessageSchema.safeParse({+ type: "set-viewer-password",+ password: null,+ }).success,+ ).toBe(true);+ expect(+ serverMessageSchema.safeParse({+ type: "viewer-password-updated",+ enabled: true,+ }).success,+ ).toBe(true);+ });+it("rejects unknown fields and malformed tokens", () => {const result = clientMessageSchema.safeParse({type: "authenticate",diff --git a/tests/room-store.test.ts b/tests/room-store.test.tsindex d8745ebc..0554933b 100644--- a/tests/room-store.test.ts+++ b/tests/room-store.test.ts@@ -22,6 +22,13 @@ function expectRoomError(action: () => unknown, code: RoomStoreError["code"]): v}}+async function expectRoomErrorAsync(+ action: () => Promise<unknown>,+ code: RoomStoreError["code"],+): Promise<void> {+ await expect(action()).rejects.toMatchObject({ code });+}+function viewerGrant(room: { viewerGrant: string | null }): string {if (!room.viewerGrant) {throw new Error("Expected a private room Viewer grant");@@ -499,6 +506,210 @@ describe("RoomStore", () => {).toMatchObject({ viewerPolicy: "public-watch" });});+ it("accepts, changes, and removes a private room password", async () => {+ const store = new RoomStore({+ ttlMs: 10_000,+ maxRooms: 10,+ maxViewersPerRoom: 5,+ });+ const room = store.createRoom();+ const host = store.connectParticipant({+ roomId: room.roomId,+ role: "host",+ token: room.hostToken,+ clientId: "password-host",+ sessionId: "password-host-session",+ });+ expect(host.viewerPasswordEnabled).toBe(false);++ await expect(+ store.setViewerPassword(+ room.roomId,+ "easy-password",+ "password-host-session",+ ),+ ).resolves.toBe(true);+ await expect(+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "easy-password",+ clientId: "password-viewer-1",+ sessionId: "password-viewer-session-1",+ }),+ ).resolves.toMatchObject({ role: "viewer", viewerPasswordEnabled: true });+ await expectRoomErrorAsync(+ () =>+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "wrong-password",+ clientId: "wrong-password-viewer",+ sessionId: "wrong-password-session",+ }),+ "INVALID_TOKEN",+ );++ await store.setViewerPassword(+ room.roomId,+ "new-password",+ "password-host-session",+ );+ await expectRoomErrorAsync(+ () =>+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "easy-password",+ clientId: "old-password-viewer",+ sessionId: "old-password-session",+ }),+ "INVALID_TOKEN",+ );+ await expect(+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "new-password",+ clientId: "password-viewer-2",+ sessionId: "password-viewer-session-2",+ }),+ ).resolves.toMatchObject({ role: "viewer" });++ await expect(+ store.setViewerPassword(room.roomId, null, "password-host-session"),+ ).resolves.toBe(false);+ await expectRoomErrorAsync(+ () =>+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "new-password",+ clientId: "removed-password-viewer",+ sessionId: "removed-password-session",+ }),+ "INVALID_TOKEN",+ );+ expect(+ store.connectParticipant({+ roomId: room.roomId,+ role: "viewer",+ viewerGrant: viewerGrant(room),+ clientId: "grant-still-works",+ sessionId: "grant-still-works-session",+ }).role,+ ).toBe("viewer");+ });++ it("bounds pending password derivations and skips stale waiters", async () => {+ const store = new RoomStore({+ ttlMs: 10_000,+ maxRooms: 10,+ maxViewersPerRoom: 3,+ });+ let mayStartCalls = 0;+ const attempts = Array.from({ length: 40 }, (_, index) =>+ store.connectViewerWithPassword(+ {+ roomId: "999999",+ password: "bounded-password",+ clientId: `bounded-client-${index}`,+ sessionId: `bounded-session-${index}`,+ },+ () => {+ mayStartCalls += 1;+ return index < 2;+ },+ ),+ );++ const results = await Promise.allSettled(attempts);+ expect(mayStartCalls).toBe(18);+ expect(+ results.every(+ (result) =>+ result.status === "rejected" &&+ result.reason instanceof RoomStoreError &&+ result.reason.code === "INVALID_TOKEN",+ ),+ ).toBe(true);+ });++ it("does not reveal a full private room after a correct password", async () => {+ const store = new RoomStore({+ ttlMs: 10_000,+ maxRooms: 10,+ maxViewersPerRoom: 1,+ });+ const room = store.createRoom();+ store.connectParticipant({+ roomId: room.roomId,+ role: "host",+ token: room.hostToken,+ clientId: "full-password-host",+ sessionId: "full-password-host-session",+ });+ await store.setViewerPassword(+ room.roomId,+ "full-password",+ "full-password-host-session",+ );+ store.connectParticipant({+ roomId: room.roomId,+ role: "viewer",+ viewerGrant: viewerGrant(room),+ clientId: "full-room-viewer",+ sessionId: "full-room-viewer-session",+ });++ await expectRoomErrorAsync(+ () =>+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "full-password",+ clientId: "full-password-viewer",+ sessionId: "full-password-viewer-session",+ }),+ "INVALID_TOKEN",+ );+ });++ it("does not commit a password after the Host session is replaced", async () => {+ const store = new RoomStore({+ ttlMs: 10_000,+ maxRooms: 10,+ maxViewersPerRoom: 3,+ });+ const room = store.createRoom();+ store.connectParticipant({+ roomId: room.roomId,+ role: "host",+ token: room.hostToken,+ clientId: "same-host",+ sessionId: "old-host-session",+ });++ const pending = store.setViewerPassword(+ room.roomId,+ "stale-password",+ "old-host-session",+ );+ store.connectParticipant({+ roomId: room.roomId,+ role: "host",+ token: room.hostToken,+ clientId: "same-host",+ sessionId: "new-host-session",+ });++ await expect(pending).rejects.toMatchObject({ code: "INVALID_TOKEN" });+ await expectRoomErrorAsync(+ () =>+ store.connectViewerWithPassword({+ roomId: room.roomId,+ password: "stale-password",+ clientId: "stale-password-viewer",+ sessionId: "stale-password-viewer-session",+ }),+ "INVALID_TOKEN",+ );+ });+it("treats public-to-private as a strong Viewer authorization rotation", () => {const store = new RoomStore({ttlMs: 10_000,@@ -726,6 +937,31 @@ describe("RoomStore", () => {true,);expect(rooms[0].viewerGrantDigest).not.toEqual(rooms[1].viewerGrantDigest);+ expect(rooms.every((room) => room.viewerPasswordMaterial === null)).toBe(+ true,+ );+ database.close();+ } finally {+ rmSync(directory, { recursive: true, force: true });+ }+ });++ it("migrates v2 rooms to a nullable checked password material column", () => {+ const directory = mkdtempSync(join(tmpdir(), "screener-room-v2-migration-"));+ const databasePath = join(directory, "rooms.sqlite");+ try {+ createV2Database(databasePath);+ const database = new RoomDatabase(databasePath);+ expect(database.loadRooms()).toMatchObject([+ { roomId: "1", viewerPasswordMaterial: null },+ ]);+ database.updateViewerPassword("1", Buffer.alloc(48, 7));+ expect(database.loadRooms()[0].viewerPasswordMaterial).toEqual(+ Buffer.alloc(48, 7),+ );+ expect(() =>+ database.updateViewerPassword("1", Buffer.alloc(47)),+ ).toThrow("Viewer password material must contain 48 bytes");database.close();} finally {rmSync(directory, { recursive: true, force: true });@@ -799,3 +1035,22 @@ function createV1Database(path: string, roomCount: number): void {}database.close();}++function createV2Database(path: string): void {+ const database = new DatabaseSync(path);+ database.exec(`+ CREATE TABLE rooms (+ id INTEGER PRIMARY KEY AUTOINCREMENT,+ host_token_digest BLOB NOT NULL CHECK (length(host_token_digest) = 32),+ viewer_grant_digest BLOB NULL+ CHECK (viewer_grant_digest IS NULL OR length(viewer_grant_digest) = 32)+ ) STRICT;+ PRAGMA user_version = 2;+ `);+ database+ .prepare(+ "INSERT INTO rooms (host_token_digest, viewer_grant_digest) VALUES (?, ?)",+ )+ .run(Buffer.alloc(32, 1), Buffer.alloc(32, 2));+ database.close();+}diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 8bd122da..58294364 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -443,7 +443,12 @@ async function authenticate(clientId: string,relayCapacity: 0 | 1 | null = 1,shareGeneration?: string,- presence: { displayName?: string; viewerPresence?: true } = {},+ presence: {+ displayName?: string;+ viewerPresence?: true;+ viewerPasswordSettings?: true;+ viewerPassword?: string;+ } = {},) {client.socket.send(JSON.stringify(@@ -457,6 +462,9 @@ async function authenticate(clientId,...(shareGeneration ? { shareGeneration } : {}),...(presence.viewerPresence ? { viewerPresence: true } : {}),+ ...(presence.viewerPasswordSettings+ ? { viewerPasswordSettings: true }+ : {}),}: {type: "authenticate",@@ -464,7 +472,11 @@ async function authenticate(roomId: room.roomId,role,clientId,- ...(room.viewerGrant ? { viewerGrant: room.viewerGrant } : {}),+ ...(presence.viewerPassword+ ? { viewerPassword: presence.viewerPassword }+ : room.viewerGrant+ ? { viewerGrant: room.viewerGrant }+ : {}),...(presence.displayName? { displayName: presence.displayName }: {}),@@ -808,6 +820,107 @@ describe("WebSocket signaling", () => {await host.inbox.next("peer-joined");await host.inbox.expectNone(40);++ host.socket.send(+ JSON.stringify({ type: "set-viewer-password", password: "unused" }),+ );+ expect(await host.inbox.next("error")).toMatchObject({+ code: "FORBIDDEN",+ });+ await host.inbox.expectNone(40);+ });++ it("lets an opted-in Web Host set and remove room password access", async () => {+ const harness = await startHarness();+ const host = await openClient(harness.webSocketUrl);+ const hostAuth = await authenticate(+ host,+ harness.room,+ "host",+ "password-settings-host",+ 1,+ undefined,+ { viewerPasswordSettings: true },+ );+ expect("viewerPasswordEnabled" in hostAuth).toBe(false);+ expect(await host.inbox.next("viewer-password-updated")).toEqual({+ type: "viewer-password-updated",+ enabled: false,+ });++ host.socket.send(+ JSON.stringify({+ type: "set-viewer-password",+ password: "easy-password",+ }),+ );+ expect(await host.inbox.next("viewer-password-updated")).toEqual({+ type: "viewer-password-updated",+ enabled: true,+ });++ const wrongViewer = await openClient(harness.webSocketUrl);+ wrongViewer.socket.send(+ JSON.stringify({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId: harness.room.roomId,+ role: "viewer",+ clientId: "wrong-password-viewer",+ viewerPassword: "wrong-password",+ }),+ );+ expect(await wrongViewer.inbox.next("error")).toMatchObject({+ code: "INVALID_TOKEN",+ });++ const passwordViewer = await openClient(harness.webSocketUrl);+ await expect(+ authenticate(+ passwordViewer,+ harness.room,+ "viewer",+ "password-viewer",+ 1,+ undefined,+ { viewerPassword: "easy-password" },+ ),+ ).resolves.toMatchObject({ role: "viewer" });+ await host.inbox.next("peer-joined");++ host.socket.send(+ JSON.stringify({ type: "set-viewer-password", password: null }),+ );+ expect(await host.inbox.next("viewer-password-updated")).toEqual({+ type: "viewer-password-updated",+ enabled: false,+ });++ const grantViewer = await openClient(harness.webSocketUrl);+ await expect(+ authenticate(+ grantViewer,+ harness.room,+ "viewer",+ "grant-after-password-removal",+ ),+ ).resolves.toMatchObject({ role: "viewer" });+ await host.inbox.next("peer-joined");++ const removedPasswordViewer = await openClient(harness.webSocketUrl);+ removedPasswordViewer.socket.send(+ JSON.stringify({+ type: "authenticate",+ protocol: SIGNALING_PROTOCOL,+ roomId: harness.room.roomId,+ role: "viewer",+ clientId: "removed-password-viewer",+ viewerPassword: "easy-password",+ }),+ );+ expect(await removedPasswordViewer.inbox.next("error")).toMatchObject({+ code: "INVALID_TOKEN",+ });});it("reports every online Viewer without expanding the Host media fanout", async () => {