Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

docs(truth): checkpoint route and room state

AAA24ce10d5a11d
diff --git a/docs/README.md b/docs/README.md
index ef3ea6cc..452fbdfb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,10 +1,11 @@
# Project Documentation
- [需求理解](./需求理解.md): current product scope, priorities, constraints, and acceptance criteria.
-- [方案设计](./方案设计.md): accepted implementation design; runtime migration and validation are tracked in the current TODO ledger.
+- [方案设计](./方案设计.md): accepted implementation design; unfinished production release and validation are tracked in the current TODO ledger.
- [Project memory](./project-memory.md): durable current product and source snapshot to read at the start of future work.
- [Current status](./status.md): bounded current/index snapshot of production, active milestones, decisions, blockers, and links to detail.
- [Verification status](./verification-status.md): demand-loaded ledger of current cross-cutting evidence, open proof boundaries, and expensive-test applicability.
+- [Session handoff](./session-handoff.md): temporary bootstrap prompt that points a new session back to the canonical truth owners.
- [Current TODO](./todo.md): unresolved work, active truth holds, and decisions that still require user confirmation.
- [Deployment](./deployment.md): exact current/rollback production configuration, release operations, and transport evidence boundaries.
- [Maintenance guide](./maintenance.md): Git workflow, context hygiene, document lifecycle, research policy, and automation.
@@ -21,9 +22,9 @@
- [Display name and presence boundaries](./research/display-name-presence.md): browser-local storage failure behavior, Unicode normalization, control-character policy, and the Web-only presence capability boundary.
- [Agent context governance research](./research/agent-context-governance.md): official Codex, Claude Code, Hermes Agent, and GitHub practices adopted by this repository.
- [ADR-0001](./adr/0001-p2p-first-media-topology.md): historical P2P-first baseline; later access and automatic-routing decisions supersede its stale current-state details.
-- [ADR-0002](./adr/0002-persistent-protected-rooms.md): site access, room-scoped private Viewer grants, explicit public-watch, rotation, and minimal SQLite persistence.
+- [ADR-0002](./adr/0002-memory-resident-protected-rooms.md): four-digit leased in-memory rooms, local Host defaults, scoped Viewer grants, and orthogonal code entry.
- [ADR-0004](./adr/0004-peer-assisted-media-experiment.md): historical standard-WebRTC peer-assisted experiment and reusable evidence.
-- [ADR-0005](./adr/0005-automatic-hybrid-media-routing.md): accepted automatic P2P-first single-reconcile route model, capacity/accounting, fallback roles, and exact first-frame transaction; runtime migration remains in the current TODO.
+- [ADR-0005](./adr/0005-automatic-hybrid-media-routing.md): accepted and source-implemented automatic P2P-first single-reconcile route model, capacity/accounting, fallback roles, and exact first-frame transaction; production release and validation remain in the current TODO.
- [ADR-0006](./adr/0006-fixed-high-native-sender-canary.md): proposed fixed-`HIGH` native canary, current no-go result, and staged revalidation boundary.
- [ADR-0007](./adr/0007-demand-driven-dual-representation-quality.md): accepted path-isolated `HIGH + at most one LOW` policy, optional idle-layer stop, evidence contract, and SVC boundary.
- [ADR-0008](./adr/0008-window-scoped-audio-capture.md): browser window-audio hint and the Windows WASAPI process-loopback boundary.
diff --git a/docs/adr/0001-p2p-first-media-topology.md b/docs/adr/0001-p2p-first-media-topology.md
index 95dd4153..ef0075c9 100644
--- a/docs/adr/0001-p2p-first-media-topology.md
+++ b/docs/adr/0001-p2p-first-media-topology.md
@@ -31,10 +31,10 @@ contradict the private-room cost model or duplicate mature WebRTC capabilities.
## Current Ownership
[ADR-0005](./0005-automatic-hybrid-media-routing.md) owns current routing
-invariants and assisted-route roles; runtime migration and validation remain
-in the current TODO. [ADR-0004](./0004-peer-assisted-media-experiment.md)
+invariants and assisted-route roles; Browser source migration is complete while
+production release and validation remain in the current TODO. [ADR-0004](./0004-peer-assisted-media-experiment.md)
owns only historical peer-assisted evidence. Access and room lifetime are owned
-by [ADR-0002](./0002-persistent-protected-rooms.md).
+by [ADR-0002](./0002-memory-resident-protected-rooms.md).
This historical record does not authorize a capacity, SFU/TURN order, topology,
runtime migration, or release gate.
diff --git a/docs/adr/0002-memory-resident-protected-rooms.md b/docs/adr/0002-memory-resident-protected-rooms.md
new file mode 100644
index 00000000..4c8b638b
--- /dev/null
+++ b/docs/adr/0002-memory-resident-protected-rooms.md
@@ -0,0 +1,149 @@
+# ADR-0002: Memory-Resident Rooms And Scoped Viewer Access
+
+- Status: Accepted; implementation pending
+- Date: 2026-08-23
+
+## Context
+
+Screener serves one Host and at most 20 trusted Viewers. The media plane stays
+distributed and P2P-first, while the application server owns the small room,
+authorization, signaling, and route-control state. An application restart already
+ends every active media session. Removing durable room storage additionally loses
+the current code, invitation, and dormant lease, while same-browser creation
+preferences can still be replayed locally. For this private, bounded product that
+is a small and accepted recovery cost.
+
+SQLite would preserve those identifiers across restart, but it also keeps a
+schema, migrations, path and writable-directory configuration, backup/restore
+operations, persistence tests, and cross-restart state semantics. That ongoing
+surface is not justified by the limited recovery benefit and works against the
+small, ephemeral control plane. The product therefore accepts restart-wide room
+loss and does not include cross-restart room recovery in its current contract.
+
+The room experience needs a memorable code, a direct invitation, optional
+code-entry protection, and short-term reuse by the same browser. It does not need
+accounts, browser fingerprinting, a user database, permanent room ownership,
+schema migration, or high-availability coordination.
+
+## Decision
+
+### One Memory-Resident Room Model
+
+All room state lives in the authoritative application process:
+
+- a random four-digit room code from `1000` through `9999`;
+- the room lease and current Host/Viewer membership;
+- SHA-256 digests of the Host token and current Viewer grant;
+- the current code-entry policy and, when enabled, a salted room-password
+ verifier;
+- authorization generations and the existing signaling/route state.
+
+The free-code pool contains every currently unallocated four-digit code. Room
+creation selects uniformly from that pool, and room release returns the code to
+it. `MAX_ROOMS` must not exceed the 9,000-code space; its product default remains
+1,000. A room code is a locator, not a secret or permanent identity.
+
+`ROOM_LEASE_SECONDS` is the single room-lifetime setting and defaults to 86,400
+seconds. An authenticated, actively sharing Host prevents expiry. When sharing
+stops or the Host is no longer connected, the room remains dormant until the
+lease deadline. The same Host token may resume sharing before that deadline and
+renew the lease. Viewer presence never renews ownership. Expiry closes the room,
+invalidates its credentials, and releases its code.
+
+Process restart deliberately clears every room, lease, credential digest,
+password verifier, and participant. Old Host records and invitations then fail
+closed, and the next Host share creates a new room. There is no room database,
+`ROOM_DATABASE_PATH`, persistent-room mode, schema migration, or compatibility
+reader. The site-access secret remains deployment configuration rather than room
+state.
+
+### Ownership And Local Host Defaults
+
+Room ownership uses the existing random Host bearer token, not an IP address,
+user agent, hardware property, or browser fingerprint. The Host browser keeps the
+raw token in same-origin `localStorage`; the server keeps only its digest in the
+current room. Clearing local data or changing browser/device loses ownership.
+
+The Host browser also keeps one local creation profile containing its display
+name, code-entry policy, and optional room password. When an old room no longer
+exists, the next explicit share creates a new room and atomically reapplies that
+profile, so the same browser retains its preferences but receives a new code,
+Host token, and Viewer grant. The site-access password is never part of this
+profile. A Host room password may be stored locally as a convenience for this
+private product; the server receives it only over the authenticated creation or
+update path, derives the verifier, and never stores or logs the plaintext.
+
+### Orthogonal Viewer Access
+
+Every room has an expiring, room-scoped Viewer grant independent of code entry.
+The primary share action copies `/r/{code}#v={grant}`. A valid grant directly
+authorizes only the Viewer role in that room. The browser consumes it into
+room-scoped `sessionStorage`, immediately clears the fragment with
+`history.replaceState`, and never places it in a cookie, query, log, error, or
+`localStorage`.
+
+Code entry is a separate three-state policy:
+
+- `open` is the default: after site access, the four-digit code admits a Viewer
+ without a room password;
+- `password`: after site access, the code also requires the room password;
+- `disabled`: code-only admission is rejected and the grant remains the entry
+ path.
+
+The Host may rotate or revoke the grant without changing code-entry policy, and
+may change code-entry policy without changing a healthy media route. Strong
+grant revocation advances the authorization generation, clears Viewer grace and
+route state, closes the old receive and send edges, and disconnects the affected
+Viewers before they can reconnect with the old grant.
+
+`SITE_ACCESS_PASSWORD` continues to protect room creation, Host admission, and
+all code-only Viewer attempts. A valid room grant may bypass that site gate only
+for the exact Viewer role and room. Neither a code, room password, nor Viewer
+grant can create a room or become Host authority.
+
+## Consequences
+
+- Normal operation and the 24-hour renewable-room experience require only one
+ bounded in-memory room map and no writable database directory.
+- The central control plane stays small and ephemeral; media distribution and
+ bandwidth remain governed by the P2P-first route model rather than moved to the
+ application server.
+- A deployment, crash, or restart invalidates 100 percent of current rooms and
+ invitations. Active media already disconnects at that boundary; the additional
+ cost is a new room code and invitation. Same-browser Host preferences are
+ reapplied automatically on the next explicit share.
+- A room unused beyond the lease is released. With a 24-hour value, any dormant
+ interval longer than 24 hours produces a new code.
+- Recycled code-only bookmarks may eventually identify a different room. A stale
+ grant remains unusable because the new room has a different digest.
+- Multi-process room coordination, seamless restart, and horizontal scaling are
+ outside the current contract. They require a new accepted storage decision if
+ they become real requirements.
+
+## Acceptance Gates
+
+- Allocation uses only `1000` through `9999`, never duplicates an active code,
+ respects `MAX_ROOMS`, and returns released codes to the free pool.
+- An active Host is not expired. Stop/disconnect starts the configured dormant
+ lease; the exact Host token resumes before expiry; Viewer activity does not.
+- Expiry and process restart reject the old Host token, Viewer grant, room
+ password, and code-bound room state. Reusing a released code never accepts the
+ old grant.
+- Default creation atomically produces `open` code entry with no room password
+ and an independent token-bearing invitation. `open`, `password`, and
+ `disabled` code entry are covered independently from grant rotate/revoke.
+- Same-browser recreation reapplies the Host profile; another browser or cleared
+ storage does not. No fingerprint or server user record participates.
+- Raw site passwords, Host tokens, Viewer grants, and room passwords remain out
+ of application/proxy logs and server durable storage.
+
+## Implementation Status
+
+This ADR is the accepted target, not a claim about current source or production.
+Current source still has `private-link | public-watch`, random 12-digit temporary
+rooms, optional SQLite persistent rooms, `ROOM_TTL_SECONDS`, and the v3 migration
+surface. Production still runs that SQLite-backed release. The implementation
+must replace those surfaces atomically, delete the database code and old
+configuration rather than preserve compatibility, update deployment guidance,
+and pass the gates above before status reports this decision as source-complete
+or deployed.
diff --git a/docs/adr/0002-persistent-protected-rooms.md b/docs/adr/0002-persistent-protected-rooms.md
deleted file mode 100644
index db6cbc65..00000000
--- a/docs/adr/0002-persistent-protected-rooms.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# ADR-0002: Persistent Rooms And Scoped Viewer Access
-
-- Status: Accepted; access boundary deployed, local privacy gate source-only
-- Date: 2026-08-19
-
-## Context
-
-The trusted-friends workflow uses a site-access boundary and a room-access
-boundary. Creating or publishing and navigating by room code require site
-access. A room-scoped fragment grant remains the link-first path and does not
-require sharing the site password with invited friends.
-
-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 site access 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, 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
-site access. Media topology remains independent and is governed by
-ADR-0001/0005.
-
-## Decision
-
-Keep site access and room authorization as two ordered checks:
-
-- Replace `ACCESS_PASSWORD` with `SITE_ACCESS_PASSWORD`. Production startup
- requires it; local development and tests may explicitly disable it. It accepts
- 8 through 128 visible ASCII bytes, must be independent from other deployment
- secrets, and issues a 12-hour stateless
- HMAC `HttpOnly`, `SameSite=Strict`, `Path=/` cookie (`Secure` and `__Host-` in
- HTTPS production). It authorizes room creation and an attempted Host role,
- and permits code-only Viewer attempts. The room's independent Host token is
- still required to publish.
-- The atomic deployment change applies nginx per-source `limit_req` at `5r/m`,
- `burst=5 nodelay` to `/api/site-access`. It uses nginx shared memory and
- introduces no IP persistence/log field. Throttling returns generic 429;
- allowed failures use constant-time comparison and generic 401. Node gains no
- IP-keyed identity/LRU/session store; existing connection caps remain.
-- Remove the old environment variable, `/api/session`, old cookie name, and old
- client gate in the same release. Supplying `ACCESS_PASSWORD` is a startup
- error. The replacement endpoint is `/api/site-access`; `POST /api/rooms`
- accepts only its cookie, not a Bearer shortcut.
-- A WebSocket upgrade cannot know the future role. `/signal` therefore admits a
- browser without a site-access cookie after the existing exact Origin, empty-query,
- total-capacity, and unauthenticated-capacity checks. The server records whether
- the upgrade carried a valid site-access cookie. The first Host
- `authenticate` must pass both that recorded state and the room Host token. A
- Viewer may bypass site access only with a valid, unexpired grant for that
- exact room; otherwise site access is required before any room lookup policy
- or password verification can authorize it.
-- At this ADR's release boundary, move the single wire literal from
- `screener-v1` to `screener-v2`. That migration had no negotiation, v1 parser,
- dual write, or translator. A v1 first message received the universal fatal
- refresh outcome before room lookup and did not reconnect. Later atomic
- migrations advanced the source wire to `screener-v6`.
-
-Every room has one of two Viewer policies:
-
-- `private-link` is the default. The server creates a grant containing a
- 256-bit random value and bounded expiry, stores only SHA-256 of the canonical
- full grant, and accepts it only for the Viewer role in that exact room. A
- temporary-room grant cannot outlive the room; a persistent-room grant lasts
- seven days unless rotated earlier. Expiry rejects later authentication and
- reconnects; it does not schedule a mid-session disconnect. Rotate/revoke is
- the immediate removal operation. Seven days is a configuration-free first
- release bound: reusable across short friend sessions, but not a permanent
- capability attached to a persistent sequential room.
-- `public-watch` is an explicit Host choice. Site access plus a room code can
- acquire only the Viewer role. It creates no room directory and remains bounded by existing
- per-room Viewer, global connection, unauthenticated connection, route, and
- central-egress limits. Sequential public room IDs deliberately provide no
- privacy 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 passes neutral site
-access before seeing the neutral room-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.
-
-At this ADR's implementation checkpoint, the wire remained `screener-v2`.
-Current source has since migrated atomically to `screener-v6`, while production
-remains on `screener-v5`; the paragraph below records the v2 compatibility
-boundary rather than the current source wire. 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 fragment
-before dereference, and the WebSocket API rejects fragment-bearing URLs, so the
-client never appends it to HTTP or `/signal`. On first load the client strictly
-parses the grant into room-scoped `sessionStorage` and immediately calls
-`history.replaceState` with canonical `/r/{roomId}`. Refresh and in-page
-reconnect use that page session's value; an independent page without a fragment
-or room key fails closed. The raw grant is never put in `localStorage`, a
-cookie, query, Referrer, log, or error. Host creation and
-rotation keep the returned raw grant only in memory and room-scoped
-`sessionStorage` while constructing a copyable link. The persistent Host-room
-object keeps the room ID, canonical URL, Host token, and room expiry, not the
-Viewer grant.
-
-The fragment and production `Referrer-Policy: no-referrer` prevent ordinary
-request/referrer logging, but do not make the invitation harmless. The original
-message, a browser extension, a screenshot, or deliberate forwarding can still
-disclose it. The UI treats it as an access credential and provides Host
-rotation/revoke.
-
-Rotation, explicit revoke, and public-to-private changes are strong revocation
-operations. The server first commits the new digest and authorization generation.
-Only after a successful commit does it clear Viewer grace, connection
-generations, and route state, tell Viewers to close receive PCs/media, tell every
-Host/relay/SFU upstream owner to close the old-generation send edge, and close
-every current Viewer socket. Closing signaling alone is insufficient because a
-healthy P2P edge can keep playing without it. Rotation and public-to-private each
-return one new grant. Revoke stores a fresh random locked-private digest for
-which no grant was generated and returns no grant until a later rotation.
-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 failure
-leaves the old digest, existing sockets, and topology unchanged. Switching from
-private to public only broadens future Viewer admission and does not move
-healthy media.
-
-## Persistence And Migration
-
-`ROOM_DATABASE_PATH` remains optional and now requires
-`SITE_ACCESS_PASSWORD`. Without it, rooms use random numeric IDs and
-`ROOM_TTL_SECONDS`. With it, SQLite allocates persistent decimal IDs using
-`INTEGER PRIMARY KEY AUTOINCREMENT`.
-
-Schema v3 keeps one `rooms` table and adds one nullable password-material field
-to the deployed v2 shape:
-
-```text
-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)
-viewer_password_material BLOB NULL
- CHECK (viewer_password_material IS NULL OR length(viewer_password_material) = 48)
-```
-
-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 site-access 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 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 Host
-tokens still reclaim their rooms, after which the Host rotates once to obtain a
-new invitation. Old code-only links fail closed. Deployment takes a v1 backup before migration; a
-rollback to the old binary stops the service and restores that backup rather
-than retaining dual-schema runtime code.
-
-Display names and roster presentation remain a separate change: browser
-`localStorage` plus current-room memory only. A unique display name is shown
-without an identifier; duplicate names append the shortest room-scoped
-`peerId` suffix (at least six characters, extended only when needed). Neither
-the name nor suffix enters SQLite or participates in authorization, routing, or
-quality decisions.
-
-## Consequences
-
-- Friends can watch a private room without learning the password that grants
- room-creation and Host capability.
-- One digest scopes leaked Viewer authority to one room and one role; rotation
- provides a clear recovery operation.
-- 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 join
- before expiry and remain until disconnect or room-wide rotation/revoke;
- targeted per-person revocation is unavailable.
-- Clearing the fragment sacrifices bookmark/copy-from-address-bar behavior.
- Closing the only Host tab loses its raw copy; the Host must rotate to produce
- another link, although room ownership remains recoverable from its Host token.
-- Rotation/revoke deliberately disconnects all Viewers and rebuilds their routes.
-- SQLite v3 is not readable by the old runtime, so rollback requires the
- pre-migration backup.
-- Public-watch consumes bounded Viewer/media capacity and offers no privacy.
-
-## Rejected Alternatives
-
-- One password for Host and Viewer: over-grants every invited Viewer and couples
- deployment abuse control to room privacy.
-- 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 warns
- against bearer tokens in URI queries. A fragment plus first WS message keeps
- it out of ordinary HTTP and proxy request logs.
-- Viewer cookie or `localStorage`: broadens retention and ambient authority.
- Room-scoped `sessionStorage` is enough for the required refresh/reconnect.
-- Plaintext SQLite grants, per-Viewer grants, ACLs, accounts, JWTs, or a session
- table: unnecessary credential exposure/state without a current consumer.
-- Letting a site-access cookie satisfy private Viewer admission: collapses the
- two authorization scopes. It permits the room attempt but never replaces a
- private room grant or password.
-- Keeping v1 compatibility: risks ambiguous old-tab behavior and leaves a
- second security model in product code; Git history and database backup own
- rollback.
-
-## Acceptance Gates
-
-- The auth matrix proves production site access, grant-without-site-cookie,
- 8-byte minimum/independent secret, ingress rate limit, exact-room/role grant
- scope, correct/wrong/replaced/removed room passwords, non-enumerating failures,
- public code-only rejection before site access, public entry after site access,
- and v2 Native wire isolation.
-- Leak tests cover HTTP/WS targets, Referrer, browser storage, SQLite, application
- and proxy logs, and errors; fragment consumption immediately clears the URL.
-- Rotation/revoke/public-to-private proves commit-before-disconnect, complete
- grace/route cleanup, old receive/send media teardown, one-time grant semantics,
- old reconnect rejection, locked revoke, and no change after persistence failure.
-- 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 deployed boundary implements the single-version v2 runtime, ordered site
-access for code-only Viewers, private/public room policy, fragment consumption,
-room passwords, and commit-first grant teardown on SQLite v3.
-
-The source-only `npm run gate:access-privacy` gate builds the current Web client,
-uses an ephemeral real-Chrome context against a loopback persistent room, and
-reports only fixed booleans and counts. It proves that the fragment is consumed
-through `replaceState` before `DOMContentLoaded`, the grant appears only under
-that room's `sessionStorage` key, and the run's site password plus grant do not
-appear in observed request/referrer records, the tracked nginx combined-log
-model, or captured application diagnostics. None of those values or the room
-password appears raw in temporary SQLite files. The room password enters at the
-RoomStore boundary, so this gate makes no claim about its browser/WebSocket/log
-ingress. It also runs the complete signaling test file containing the strong
-rotate/revoke media-edge teardown case.
-
-This local headless gate neither reads production credentials nor inspects a
-production request log, nginx log, service journal, database, or headful browser.
-Those exact-environment checks and a production rotation/revoke remain separate
-acceptance work.
diff --git a/docs/adr/0004-peer-assisted-media-experiment.md b/docs/adr/0004-peer-assisted-media-experiment.md
index e71f2d8d..e2846187 100644
--- a/docs/adr/0004-peer-assisted-media-experiment.md
+++ b/docs/adr/0004-peer-assisted-media-experiment.md
@@ -87,8 +87,9 @@ ADR-0005's current invariants rather than carried forward wholesale.
The current accepted endpoint rule is one server-authoritative downstream
capacity for every non-server endpoint, default `2` and statically configurable
as `1`, `2`, or `3`; upstream receive is free and role or user agent does not
-create an exception. The separate SFU/TURN publication, subscription, transport,
-server-resource, and migration-overlap model is still pending.
+create an exception. ADR-0005 owns the implemented Browser source for SFU/TURN
+publication, subscription, transport, server admission, and migration overlap;
+its production release and real-network validation remain pending.
## Consequences
diff --git a/docs/adr/0005-automatic-hybrid-media-routing.md b/docs/adr/0005-automatic-hybrid-media-routing.md
index c91b8459..addf599f 100644
--- a/docs/adr/0005-automatic-hybrid-media-routing.md
+++ b/docs/adr/0005-automatic-hybrid-media-routing.md
@@ -39,11 +39,11 @@ capacity:
The server returns the final deployment value as
`authenticated.endpointMediaCopyCapacity` on every successful signaling
-authentication. Web and Native clients validate `1..3`; a Native Host uses that
-same value for ordinary Viewer admission, authoritative peer-assisted child
-assignments, and physical sender slots. Room `maxViewers` is a separate
-participant-admission limit and never supplies a sender budget. A missing or
-invalid capacity fails before route authority is accepted.
+authentication. Browser Host and Viewer clients validate `1..3` and use the
+same value for authoritative child assignments and physical sender slots. Room
+`maxViewers` is a separate participant-admission limit and never supplies a
+sender budget. A missing or invalid capacity, old wire, or executable sender
+fails before route authority is accepted.
Without the peer-assisted controller, signaling still admits at most that many
active Host children per room. Excess admitted Viewers wait without an
@@ -355,7 +355,7 @@ Route and signaling authority is room-, role-, session-, share-, revision-, and
connection-bound. LiveKit media credentials are short-lived and bound to the
room, role, share, and publication generation so healthy media may survive a
signaling reconnect. Server-assisted credentials remain memory-only and never
-appear in application page URLs, browser persistence, or SQLite. LiveKit places
+appear in application page URLs, browser persistence, or durable server storage. LiveKit places
its short-lived JWT in the WebSocket transport request target, which must not be
logged; no credential may enter application or proxy logs.
Ordinary SFU transport terminates DTLS-SRTP at the SFU; the product must not
diff --git a/docs/adr/0006-fixed-high-native-sender-canary.md b/docs/adr/0006-fixed-high-native-sender-canary.md
index 7c55b073..28971002 100644
--- a/docs/adr/0006-fixed-high-native-sender-canary.md
+++ b/docs/adr/0006-fixed-high-native-sender-canary.md
@@ -39,9 +39,9 @@ merged as product code from this state.
## 2026-08-20 Historical Wire Checkpoint
This checkpoint targeted the then-current `screener-v2` wire and SQLite schema
-v2. Current Web and source-only Native use `screener-v6`, production remains on
-`screener-v5`, and current room persistence is SQLite schema v3. The dated
-behavior below remains experiment provenance, not a current integration contract.
+v2. It is experiment provenance, not a current integration contract; current
+source and production boundaries are owned by [status](../status.md), and
+executable senders remain outside the current release.
A clean local delivery candidate now targets only `screener-v2`: it exchanges
`SITE_ACCESS_PASSWORD` for the bounded HttpOnly site-access cookie, uses
diff --git a/docs/deployment.md b/docs/deployment.md
index 6b076ffe..a6f1d960 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -210,7 +210,7 @@ SITE_ACCESS_PASSWORD=<INDEPENDENT_8_TO_128_BYTE_ACCESS_KEY>
ROOM_DATABASE_PATH=/var/lib/screener/rooms.sqlite
ROOM_TTL_SECONDS=14400
MAX_ROOMS=1000
-MAX_VIEWERS_PER_ROOM=8
+MAX_VIEWERS_PER_ROOM=20
ENDPOINT_MEDIA_COPY_CAPACITY=2
STUN_URLS=stun:stun.example.com:3478
@@ -288,11 +288,10 @@ key, even blank, fails startup.
`ROOM_DATABASE_PATH` is optional but requires `SITE_ACCESS_PASSWORD`.
Omit the database path to keep random temporary rooms; `ROOM_TTL_SECONDS`
applies only to those rooms.
-`MAX_VIEWERS_PER_ROOM` defaults to 8 and accepts 1 through 16. It is an admission
-limit in the deployed release, not current product policy or evidence that the
-publisher can sustain that many streams. The accepted source target is 20
-Viewers; deployment default promotion follows the route release's 20-Viewer
-smoke.
+Production `9461e20` defaults `MAX_VIEWERS_PER_ROOM` to 8 and accepts 1 through
+16. Current source accepts 1 through 20, and the next-release baseline above
+explicitly selects 20 after the route-release smoke passes. It is an admission
+limit, not evidence that the publisher can sustain that many streams.
`ENDPOINT_MEDIA_COPY_CAPACITY` defaults to 2 and accepts only 1, 2, or 3. It is
the single server-authoritative steady outbound media-copy cap for Host and
Viewer endpoints; role, browser, UA, and visibility do not create another tier.
@@ -307,9 +306,11 @@ Supplying the removed `MAX_PEER_RELAY_DOWNSTREAM_EDGES`, even blank, fails
startup.
Production release `9461e20` still runs the legacy Host-2/Browser-1 policy on
-wire `screener-v5`. Deploy the current source server, Web assets, and Native
-sender atomically on `screener-v6`; restore the exact prior environment and
-release together when rolling back.
+wire `screener-v5`. Deploy the current source server and Browser assets
+atomically on `screener-v7`; stale Browser and executable-sender wires must fail
+before room authority. Native senders and helpers are outside this release.
+Restore the exact prior environment, server, and Web assets together when
+rolling back.
The four `LIVEKIT_*` values must either all be absent or all be present, and a
complete tuple requires `PEER_ASSISTED_MEDIA=true` plus explicit positive
diff --git a/docs/maintenance.md b/docs/maintenance.md
index 3249fad6..1a39c1fb 100644
--- a/docs/maintenance.md
+++ b/docs/maintenance.md
@@ -39,6 +39,12 @@
语义仍未决定时,在 TODO 记录 hold,只冻结依赖项。接受的真相先进入 canonical `main`;保留候选再从该精确提交 rebase 或重建一次,只移植获批的 scoped code、tests 和 new facts。旧分支的 truth 文档不得覆盖当前 owner。具体 Git 和 worktree 操作遵循 `CONTRIBUTING.md`。
+## 机制减负审查
+
+设计或扩展机制前,先确认它服务哪个用户行为,量化删除后真正损失的功能和体验,再把这份收益与新增的代码、配置、迁移、测试、运行时状态、部署和故障面比较。已有需求或消费者不自动证明机制值得保留;还要问当前规模和使用方式是否真的需要它,现有标准、框架行为或更小的状态是否已经够用。若退让有界且 owner 接受,先更新产品合同,再整体删除失去必要性的组件、开关和分支;若退让不可接受,则保留合同并寻找更小实现。减负审查先做只读清点,不以行数为目标,也不演变成无边界重构。
+
+内存房间决定是基准案例:先衡量删除 SQLite 的真实退让。应用重启本来就会中断全部活动媒体,额外损失只是当前房间号、邀请和休眠租约;同一浏览器还能重放本地创建偏好。对当前私用、最多 20 名 Viewer、允许重启清空的产品,这点体验回退很小。相较之下,SQLite 会持续引入 schema、迁移、路径配置、可写目录、备份、测试分支和跨重启状态语义。产品因此主动接受这份有界回退并更新合同,随后才选择进程内模型和整体删除持久层。结论不是“小项目不应使用 SQLite”,而是不要为价值很小的能力长期维护一整套机制。
+
## 检查点与恢复
在需求或优先级被接受、设计或研究结论改变、实质阶段切换、分支/PR/agent 交接、可能 compaction 或长暂停前更新事实 owner。不要为每个函数、工具调用或未形成结论的探索建立检查点。
diff --git a/docs/project-memory.md b/docs/project-memory.md
index e79c0da8..4161f25f 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -7,6 +7,8 @@ Last updated: 2026-08-23
- Build private, low-latency game screen sharing for one broadcaster and a small group of trusted friends. Public or large broadcasts belong on OBS/Twitch-class services.
- A room supports one Host and up to `20` authenticated Viewers. Admission is independent of endpoint fanout and SFU/TURN capacity; the event-driven route controller must remain efficient at that bound without all-pairs probing.
- Authenticated Hosts and shipped clients are trusted media participants in these private rooms; route authority, generation fencing, and server admission remain fail-closed.
+- Rooms use one bounded, process-memory model: a random free code from `1000..9999`, default 24-hour configurable dormant lease, and no database or cross-restart recovery. Active sharing never expires; stop/disconnect starts the lease, the exact Host token may resume before expiry, Viewer activity does not renew it, and expiry releases the code. Process restart invalidates every room, token, invitation, password verifier, and participant.
+- Viewer grants and code entry are orthogonal. Every room has an expiring token-bearing invitation; code-only entry is `open | password | disabled` and defaults to `open` with no room password after site access. The Host browser locally retains its display name, code-entry policy, optional room password, and raw Host ownership token; the server keeps only current-process digests/verifiers and never uses IP, UA, device properties, or a fingerprint as identity. Recreating after restart reapplies local preferences but produces a new code, Host token, and grant.
- Web is the current delivery target. The route release covers Browser Host, Viewer, and relay endpoints; packaged/native senders, capture helpers, shared-encode executables, and their acceptance runs are lowest-priority later work outside this milestone.
- Keep routing automatic and media distributed. Direct/peer UDP is preferred; centralized media is fallback infrastructure, not the default topology.
- Every non-server endpoint uses one server-authoritative steady outbound media-copy capacity: default `2`, statically configurable as `1`, `2`, or `3`. A peer child or the Host publication consumes one slot; upstream receive is free, selected TURN replaces the same copy's transport, and SFU subscriber egress is accounted at the server. Browser role/UA/visibility does not create a separate tier, and clients cannot raise the deployment value.
@@ -15,7 +17,7 @@ Last updated: 2026-08-23
- One Host publication may serve all SFU subscriptions. Its exact generation owns one ingress handle and exact Viewer subscription handles own egress; later SFU children reuse the publication, while reserved, committed, and draining handles remain charged until the managed room is deleted and proven absent. Actual SFU/TURN usage release wakes only rooms that previously lost a candidate to global admission. SFU-fed and peer-fed endpoints use the same provisional-child transaction, and selected TURN changes only the transport of an authorized logical edge. Parent choice hard-filters authority, reachability, cycles, effective capacity, and producer transition, then orders by shallowest result, remaining steady sender capacity, stable join order, and peer identity; server admission is checked at the current cursor. Acyclicity and room admission bound maximum depth; depth is observed but has no separate hard cap. Raw IP, claimed NAT type, UA, geography, all-pairs probes, weighted scores, and periodic room rebalancing are not route inputs.
- Ordinary peer ICE is STUN-only. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped.
- Browser peers use existing periodic WebRTC/LiveKit stats to maintain one exact-route decoded-progress timestamp. New frames or route/connection changes reset it; a non-paused deadline reports the edge once. Track availability, bitrate, FPS, blur, sender stats, and SFU layer remain framework or diagnostic inputs.
-- Screen audio offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.
+- Browser capture already requests available share audio by default on initial capture and source switch, with an explicit video-only warning when no audio track is returned. Screen audio offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.
- Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused; unpaused hot switching is later reuse of that transaction, not an independent mechanism.
- Two distribution artifacts are accepted only after the current feature, NAT, and real-network ledger is complete. A public-server one-click deployment package installs the current application plus STUN/SFU/TURN and proxy components on a user-owned server. A Windows/macOS/Linux local package runs the Host, application server, and local state on the broadcaster's machine without source, Node, or any external Screener/network service; it keeps workable direct P2P but reports the reachability loss imposed by public ingress, TLS, gateway, NAT, or firewall limits rather than promising universal connectivity.
- Current UI, presence, route labels, and diagnostics describe observed state only; they do not create route authority.
@@ -24,8 +26,9 @@ Last updated: 2026-08-23
## Current Source And Production
-- Canonical source is the clean `main` branch. New branches and worktrees start from its exact current commit after accepted truth is merged.
+- Canonical source is the root `main` branch. Audit/integration boundaries require it to be clean, and new branches/worktrees start from its exact commit only after accepted truth is merged.
- Current source admits up to `20` Viewers and implements the uniform `1/2/3` endpoint cap, single Browser `screener-v7` wire, exact prepare candidate, first-decoded-frame commit, strict rollback revision, decoded-progress stall, and one event-driven room controller. Older Browser and executable-sender wires fail before room authority. SFU admission uses exact publication and Viewer-subscription handles with explicit no-default ingress/egress capacities and a listener-fenced dedicated LiveKit owner. Selected TURN uses its own explicit no-default deployment capacity and exact logical-allocation ledger shared by independent peer edges and Host-SFU ingress.
+- The accepted room model is not implemented on current source. Source still exposes mutually exclusive `private-link | public-watch`, random 12-digit temporary rooms, optional SQLite persistent rooms, and `ROOM_TTL_SECONDS`; production also remains SQLite-backed. Do not report four-digit leases, orthogonal code/grant access, local preference replay, or SQLite removal as shipped until that scoped implementation is validated and deployed.
- Production runs exact `9461e207af62b4f38f6b7a8aa16f8beb49e0e4ee`, release `9461e20`, wire `screener-v5`; `21d5cd9f7139` is the rollback release.
- Production still enforces Host downstream `2`, ordinary Browser downstream `1`, deployment values `1/2`, a fixed SFU-root limit of `2`, and legacy publication/selected accounting. This is a dated implementation divergence, not current product policy.
- Production has automatic routing, bad-relay corroboration, peer-quality make-before-break with Viewer and Host provisional parents, selected-edge transport, stable route/connection details, 64/128/256 audio choices, access controls, self-check, diagnostic export, and signaling watchdog behavior.
@@ -35,7 +38,7 @@ Last updated: 2026-08-23
## Current Priority
1. Keep this truth set and [the TODO ledger](./todo.md) concise and internally consistent.
-2. Release the converged Browser route source first. Then release live audio and paused video-codec switching, follow with evidence-led H.264 diagnosis, the strict-NAT emulator gate, connection feedback, and the remaining functional roadmap. Distribution packaging starts only after those TODOs are complete. Parallel branches may finish earlier but do not change this merge/deployment order.
+2. Release the converged Browser route source first. Then release live audio and paused video-codec switching, follow with evidence-led H.264 diagnosis, the strict-NAT emulator gate, connection feedback, the accepted memory-resident room/access slice, and the remaining functional roadmap. Distribution packaging starts only after those TODOs are complete. Parallel branches may finish earlier but do not change this merge/deployment order.
## Working Rules
diff --git a/docs/research/built-in-peer-ice-turn.md b/docs/research/built-in-peer-ice-turn.md
index 3c53d97e..c2631d16 100644
--- a/docs/research/built-in-peer-ice-turn.md
+++ b/docs/research/built-in-peer-ice-turn.md
@@ -27,7 +27,10 @@ The current source no longer contains the rejected participant-wide config,
issuer, authentication capability, refresh wire, or client propagation. Supplying any
stale `PEER_ICE_TURN_*` key, even blank, fails startup. The replacement
selected-edge config, wire, and rebuild now exist and are configured in
-production. They remain controller-selected and lack real relay-media evidence.
+production. They remain controller-selected. An isolated Host-SFU ingress canary
+proved selected TURN/UDP media; ordinary peer-selected media, deployment
+capacity, expiry, heterogeneous networks, and production-route behavior remain
+open.
## Production Canary
diff --git a/docs/research/display-name-presence.md b/docs/research/display-name-presence.md
index 3a2d7659..37e8667e 100644
--- a/docs/research/display-name-presence.md
+++ b/docs/research/display-name-presence.md
@@ -10,7 +10,7 @@ Accessed 2026-08-20. This note records only the browser and Unicode facts that c
## Retained design
-The browser is the only durable owner of a display-name preference. The signaling server retains the canonical value only on the authenticated socket state and derives an authoritative online snapshot from current connected sessions. Presence is display-only: it neither authorizes nor changes media routing. For Web display, an SFU Viewer entry carries `sfuMediaReady: true` only after first media is bound to its current session, active route revision, and publication generation; absence stays neutral, while track, route, or session loss removes the proof. Web Hosts and Viewers explicitly opt in to the shared participant snapshot; a Native sender does not, so its exact parser receives no new server message or field. Host defaults may be derived from the room-scoped stable client ID, but the value is still local/socket-only.
+The browser is the only durable owner of a display-name preference. The signaling server retains the canonical value only on the authenticated socket state and derives an authoritative online snapshot from current connected sessions. Presence is display-only: it neither authorizes nor changes media routing. For Web display, an SFU Viewer entry carries `sfuMediaReady: true` only after first media is bound to its current session, active route revision, and publication generation; absence stays neutral, while track, route, or session loss removes the proof. Browser Hosts and Viewers explicitly opt in to the shared participant snapshot; executable senders are outside the current Browser contract. Host defaults may be derived from the room-scoped stable client ID, but the value is still local/socket-only.
## Current roster presentation
diff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.md
index d88b2ef3..90616758 100644
--- a/docs/research/low-server-media-routes.md
+++ b/docs/research/low-server-media-routes.md
@@ -5,7 +5,8 @@
low latency, and bounded host media fanout
- Status: research and dated route evidence. Current invariants and assisted
transport roles are in [ADR-0005](../adr/0005-automatic-hybrid-media-routing.md);
- runtime migration and validation are in [the TODO ledger](../todo.md).
+ Browser source migration is complete, while production release and validation
+ remain in [the TODO ledger](../todo.md).
## Historical Candidate Route Ladder
@@ -591,10 +592,10 @@ contract and is outside this wave.
| Route | Where copies are emitted | Endpoint cost | Evidence status |
| --- | --- | --- | --- |
| Direct host P2P | Host emits one copy per Viewer | Host upload and sender pipelines grow with Viewers | Baseline evidence; current capacity is owned by the product contract |
-| Bounded browser relay DAG | Host and each Web relay emit at most the configured endpoint cap | Ordinary browser, but every relay decodes and re-encodes and adds a hop | Admission defaults to eight and permits 1-16; representative resource/quality gate remains eight viewers |
+| Bounded browser relay DAG | Host and each Web relay emit at most the configured endpoint cap | Ordinary browser, but every relay decodes and re-encodes and adds a hop | Current source admits up to 20; production remains default eight/maximum 16 until the 20-Viewer release smoke passes |
| Native shared-encode host | Host targets one encode for standard WebRTC edges | libwebrtc public-API proxy risk spike, with Pion as fallback | Research evidence; still pays per-edge upload |
| Native volunteer encoded-RTP relay | Each volunteer forwards one encoded copy | Native install, RTP/RTCP forwarding, packaging, and opt-in relay policy | Research only; no current product authorization |
-| SFU service | SFU emits authorized subscription copies | Service pays measured egress; an authoritative Host publisher supplies media | Functional evidence exists; accepted topology/admission still needs runtime validation |
+| SFU service | SFU emits authorized subscription copies | Service pays measured egress; an authoritative Host publisher supplies media | Functional evidence and source topology/admission exist; production release and real-network validation remain open |
| Additional server-assisted paths | SFU/TURN emits authorized copies | Additional central ingress, egress, or allocation cost | Accepted resource-admission input; validate each bounded path at release |
| SVC plus multiple trees | Peers emit striped layer copies across several trees | Layer scheduling, reassembly, redundancy, and more churn state | Separate conditional spike; target endpoint upload near `B` |
| Network coding | Peers or servers emit coded blocks | Generations, buffering, decoding, integrity, and a custom media plane | Trace/FEC spike only; optimize loss recovery, not clean bandwidth |
diff --git a/docs/research/native-shared-encode-sender.md b/docs/research/native-shared-encode-sender.md
index 190a3007..809d9348 100644
--- a/docs/research/native-shared-encode-sender.md
+++ b/docs/research/native-shared-encode-sender.md
@@ -165,10 +165,9 @@ generation-matched disconnect resets the five-minute window, the ordinary
transient room TTL still caps the room, and restart drops it. A pre-auth
connection or authentication failure gets one same-room/token/client-generation
retry without a second room POST. SQLite remained v2 and ordinary Web creation
-was unchanged. Current Web and source-only Native have since moved to
-`screener-v6`, production remains on `screener-v5`, and current room persistence
-is SQLite schema v3. Retaining this paragraph records the dated candidate
-boundary; it does not authorize new work against v2.
+was unchanged. This paragraph records only the dated candidate boundary; current
+source and production are owned by [status](../status.md), executable senders are
+outside the current release, and no new work is authorized against v2.
Android stop/capture-failure cleanup keeps the established signaling socket until
its single-thread teardown sends `abandon-room` and then performs a normal close;
pending-work cancellation only blocks callbacks and cancels active HTTP. No ACK
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.md
index 7f5823ad..2ca95469 100644
--- a/docs/research/peer-assisted-media.md
+++ b/docs/research/peer-assisted-media.md
@@ -520,16 +520,11 @@ event arrives later. The application therefore needs a small text-message
challenge rather than waiting for either protocol Ping/Pong or the old socket's
close event.
-The retained compatibility seam is response-only opt-in under `screener-v6`:
-the Web client sends `signaling-challenge { sequence }`, and the server sends
-the exact `signaling-challenge-response { sequence }` only to that requesting
-socket. The Native sender's strict decoder rejects unknown server message
-types, so the server must never send this response unsolicited. Existing Web
-clients and Native senders do not opt in and therefore never receive the new
-message. A new server remains compatible with those old clients, but new Web
-assets and the signaling server still need an ordered, atomic deployment
-because an old server rejects the new client message. Supporting that reverse
-version skew would require explicit capability negotiation or a protocol bump.
+Under the current `screener-v7` Browser wire, the Web client sends
+`signaling-challenge { sequence }`, and the server sends the exact
+`signaling-challenge-response { sequence }` only to that requesting socket.
+Server and Browser assets deploy atomically; stale Browser and executable-sender
+wires fail before room authority, with no compatibility parser or response seam.
The Web watchdog is eligible only while the current socket is authenticated,
the share is online, and the endpoint has an active authoritative route (the
diff --git a/docs/research/webrtc-p2p-screen-sharing.md b/docs/research/webrtc-p2p-screen-sharing.md
index c9df8fae..3ea3ed6f 100644
--- a/docs/research/webrtc-p2p-screen-sharing.md
+++ b/docs/research/webrtc-p2p-screen-sharing.md
@@ -22,13 +22,13 @@
+---- logical edge: direct/STUN -> exact selected TURN transport
+---- source/ingress fallback: one Host publication -> SFU subscriptions
-当前自动模型由 ADR-0005 持有:健康 direct/peer 边保持 sticky;selected TURN 只替换 exact logical edge 的 transport;需要 server-fed ingress 时由一份 Host publication 服务精确授权的 SFU subscriptions。每条路径受端点发送容量、独立 server admission、generation 和 bounded failure 共同约束。room `1` 只是首个 bounded production smoke,retained-media 验收仍未完成。
+当前自动模型由 ADR-0005 持有:健康 direct/peer 边保持 sticky;selected TURN 只替换 exact logical edge 的 transport;需要 server-fed ingress 时由一份 Host publication 服务精确授权的 SFU subscriptions。每条路径受端点发送容量、独立 server admission、generation 和 bounded failure 共同约束。Browser source 已实现该模型;production release 与真实网络验收边界由 current status、TODO 和 verification ledger 持有。
系统必须无感完成拓扑分配、恢复和必要迁移;大规模公开分享仍直接使用现有直播服务。
```
“让画面跑起来”难度不高;“像 Discord/TeamSpeak 一样在不同 GPU、浏览器、NAT、运营商和弱网中都保持清晰、60 fps、低延迟”难度高。建议把产品分层:
-- 原型:Web、P2P、STUN、TURN,验证小范围多观看者;当前默认接入上限为八、可配置 1 至 16,但真实 1:8 仍待验证。
+- 原型:Web、P2P、STUN、TURN,验证小范围多观看者;当前产品接入上限为 20,发布前仍需完成 20-Viewer Browser smoke。
- 可用 MVP:房间鉴权、短期 TURN 凭据、质量降档、ICE restart、统计与 30 分钟稳定性测试。
- 产品化:Electron 分享端、Web/移动观看端、Windows 应用音频、硬件编码诊断和区域化 TURN。
- Discord 级:原生捕获/编码引擎、多个捕获后端、GPU 零复制、进程树音频、广泛兼容与持续遥测,属于长期工程。
@@ -116,15 +116,15 @@ IETF 对 mesh/SFU 的拓扑说明见 [RFC 7667](https://www.rfc-editor.org/rfc/r
## 推荐的拓扑策略
-当前生产基线:
+当前 source 与 production 边界:
- 生产已移除 exact-room allowlist,所有房间由 bounded peer-assisted/SFU controller 自动路由;ordinary peer 仍使用 STUN-only ICE。
-- 当前 PoC 默认允许八名观看者,部署者可配置 1 至 16,超额连接会被明确拒绝。该数值只控制接入,不代表 1:8 已通过性能验收;必须收集可用上行、实际发送码率、`qualityLimitationReason`、编码耗时和发送队列来确定真实可持续人数。
+- Production `9461e20` 默认允许八名观看者且只接受 1 至 16;当前 source 接受最多 20。该数值只控制接入,不代表 1:20 已通过性能验收;route release 仍需记录实际 sender、应用 CPU/内存与 SFU/TURN 用量。
- 每条 ordinary peer 链路独立使用 STUN-only ICE;只有控制器选中的 exact logical edge 或 Host-SFU ingress 才会获得短期 TURN credential。
-- Exact release `9461e20` 的所有房间在 peer recovery 与 alternate parent 耗尽后可准备最多两个 SFU/UDP roots;这是已部署事实,不是未来固定 root 数的授权。首次 room `1` smoke 已观察到 participant entry,但 retained media 尚未验收。
+- Exact release `9461e20` 的所有房间在 peer recovery 与 alternate parent 耗尽后可准备最多两个 SFU/UDP roots;这是已部署事实,不是当前 source 的固定 root 数。当前 source 使用一份 Host publication 和精确 Viewer subscriptions,尚未发布。
- 桌面和手机观看者使用同一个 Web 播放端;分享者不要求朋友安装完整客户端。
-当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 viewer 可由客户端转发;ADR-0005 定义一份 Host publication、逐 Viewer SFU subscription、exact selected TURN edge transport 与独立 server admission,automatic controller 最初在 room `1` 受限部署,现已覆盖所有房间。retained SFU media、移动端矩阵和 broad rollout 仍未通过门槛;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:
+当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 Viewer 可由客户端转发;ADR-0005 定义一份 Host publication、逐 Viewer SFU subscription、exact selected TURN edge transport 与独立 server admission,当前 Browser source 已收敛为一个自动 controller。生产发布、真实 SFU/TURN、移动端和异构网络验收仍未完成;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:
- 正常工作负载持续超过实测可承载的 P2P 人数。
- 当前 logical edge 的 direct/STUN transport 失败;controller 可为同一 edge 选择 selected TURN,或在 logical ingress 需要 server-fed source 时选择当前 Host publication 的 SFU subscription。
@@ -284,15 +284,13 @@ Electron 可以固定 Chromium 版本,枚举屏幕/窗口,改善选源、热
### 最小访问模型
-当前 access boundary 使用 production 必配的 `SITE_ACCESS_PASSWORD` 无状态 cookie 保护建房、Host role 和所有 code-only Viewer 入口;合法未过期的 exact-room fragment grant 可直接观看。没有 grant 时,服务端先要求 site access,再检查 public-watch 或 private room password;房间码只定位,cookie 也不替代私密房间授权。WebSocket upgrade 仍只做 Origin/容量检查并记录 cookie 状态,首条 `authenticate` 完成上述 role/room 授权。该边界不引入账号、JWT、服务端 session Map 或逐人 ACL。
+接受的 access boundary 使用 production 必配的 `SITE_ACCESS_PASSWORD` 无状态 cookie 保护建房、Host role 和所有 code-only Viewer 入口;合法未过期的 exact-room fragment grant 可直接观看。没有 grant 时,服务端先要求 site access,再检查 `open | password | disabled` code-only policy;房间码只定位,cookie 也不替代房间密码。WebSocket upgrade 仍只做 Origin/容量检查并记录 cookie 状态,首条 `authenticate` 完成上述 role/room 授权。该边界不引入账号、JWT、服务端 session Map 或逐人 ACL。
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 权限,因此不增加导航状态机。raw grant 不进入 `localStorage`、cookie、query、Referrer、服务端持久存储、应用/代理日志或错误。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。
-
-来源(访问于 2026-08-19):[RFC 3986 section 3.5](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5)、[WHATWG WebSockets](https://websockets.spec.whatwg.org/#the-websocket-interface)、[RFC 6455](https://www.rfc-editor.org/rfc/rfc6455.html)、[RFC 6750 section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3)、[W3C Referrer Policy](https://www.w3.org/TR/referrer-policy/)、[W3C TAG Capability URLs](https://www.w3.org/TR/capability-urls/)、[HTML Web Storage](https://html.spec.whatwg.org/multipage/webstorage.html)、[Web Cryptography Level 2](https://www.w3.org/TR/WebCryptoAPI/)、[Node.js Crypto](https://nodejs.org/api/crypto.html)、[SQLite STRICT Tables](https://www.sqlite.org/stricttables.html)、[SQLite ALTER TABLE](https://www.sqlite.org/lang_altertable.html) 与 [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)。
+来源(访问于 2026-08-19):[RFC 3986 section 3.5](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5)、[WHATWG WebSockets](https://websockets.spec.whatwg.org/#the-websocket-interface)、[RFC 6455](https://www.rfc-editor.org/rfc/rfc6455.html)、[RFC 6750 section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3)、[W3C Referrer Policy](https://www.w3.org/TR/referrer-policy/)、[W3C TAG Capability URLs](https://www.w3.org/TR/capability-urls/)、[HTML Web Storage](https://html.spec.whatwg.org/multipage/webstorage.html)、[Web Cryptography Level 2](https://www.w3.org/TR/WebCryptoAPI/)、[Node.js Crypto](https://nodejs.org/api/crypto.html) 与 [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)。
WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组可信好友看到彼此网络地址。若房间政策要求完全隐藏 endpoint IP,ordinary direct/peer 不能满足,应使用明确的中央媒体路径或拒绝该连接;selected TURN 只隐藏获授权 edge 的 direct candidate,不是全房隐私开关。
@@ -334,8 +332,8 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件
- WebRTC 使用 DTLS-SRTP。TURN 只能看到加密后的媒体包,但仍能看到地址、房间时序和流量元数据。
- P2P 会让房间内双方得知网络地址。熟人首版可以接受,陌生人房间不能默认接受。
- TURN 必须使用短期凭据、速率限制、每用户/房间配额和出口告警,不能提供匿名公共 relay。
-- site access 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 诊断均不参与授权。
+- site access password 控制建房/Host role 和 code-only 尝试,不能替代 room-scoped grant 或可选逐房间 Viewer 密码;`open` room code 明确不提供隐私。这些入口都不改变媒体 fanout/egress 上限。
+- raw Viewer grant 与 Host token 等同访问凭据:服务器当前进程只保存摘要,禁止日志/遥测/错误/Referrer/持久存储明文。显示名、room-scoped peer 后缀和 IP 诊断均不参与授权。
- 如果未来使用 SFU 且要求服务器看不到内容,再评估 SFrame/WebRTC Encoded Transform 和群组密钥管理。
## 参考代码优先级
@@ -398,7 +396,7 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件
## 最终建议
-1. 首版坚持 P2P-first,但明确只服务小房间;默认接入上限为八名、可配置 1 至 16,真实 1:8 测量完成前不把它写成性能承诺。
+1. 首版坚持 P2P-first,但明确只服务一名 Host 加最多 20 名 Viewer;20-Viewer smoke 只验证 admission、控制面和资源上界,不把它写成任意公网画质或持续性能承诺。
2. Web 先行,目标 Windows Chrome/Edge;把 1080p60 写成 best effort,同时提供降档。
3. 保留 ordinary STUN-only 配置。Controller 对 exact logical edge 先验证 direct/STUN,再按 ADR-0005 选择短期 authenticated selected TURN;需要 server-fed ingress 时复用唯一 Host publication 和精确 SFU subscription,Host-SFU ingress 本身也可经 selected TURN。coturn 只验证 credential 与 expiry,room/edge/revision 必须由应用重验。
4. 观看端优先做成免安装响应式 Web;分享端先 Web 验证,再按捕获/音频实测升级 Electron。
diff --git a/docs/session-handoff.md b/docs/session-handoff.md
new file mode 100644
index 00000000..c48968e5
--- /dev/null
+++ b/docs/session-handoff.md
@@ -0,0 +1,58 @@
+# Session Handoff
+
+Last updated: 2026-08-23
+
+This file is a bootstrap prompt, not a product-truth owner. The linked documents
+replace any duplicated or conflicting statement here. Update or remove this file
+after the handoff boundary changes.
+
+## Prompt
+
+```text
+Continue the Screener project from the canonical repository root:
+C:\Users\TNTcraft\Documents\GitHub\Screener
+
+Before changing code, deployment, branches, worktrees, or TODO state:
+
+1. Read the root AGENTS.md instructions supplied for this repository, then read
+ CONTRIBUTING.md, docs/project-memory.md, docs/status.md, docs/todo.md,
+ docs/需求理解.md, docs/方案设计.md, docs/maintenance.md, and the relevant
+ ADR/research owner.
+2. Inspect git status, current branch/HEAD, worktree list, and the diff. Preserve
+ every pre-existing edit. The canonical root/main owns truth; auxiliary
+ worktrees, branches, agent memories, chat summaries, and old TODOs do not.
+3. Distinguish accepted product truth, current source, and current production.
+ Do not report an accepted design as implemented or deployed.
+4. Resolve meaning and update all affected truth owners before implementation.
+ Keep the model simple, use existing framework behavior, avoid case-by-case
+ patches, and do not add compatibility for unpublished internal releases.
+
+Current high-signal boundary:
+
+- docs/status.md owns the exact source/production/hold state.
+- docs/todo.md is the only executable work ledger and owns ordering.
+- ADR-0005 owns the accepted automatic route model. The Browser route source is
+ implemented on main but production remains on the older release; do not rerun
+ broad or executable/native test suites unless the current acceptance boundary
+ specifically requires them.
+- ADR-0002 owns the newly accepted room model: one process-memory RoomStore,
+ random free four-digit codes, configurable 24-hour dormant leases, restart
+ loss, local Host preference replay, an independent expiring Viewer grant, and
+ open/password/disabled code entry. SQLite removal and the new access/UI model
+ are documented but not implemented or deployed.
+- docs/maintenance.md owns the reusable mechanism-simplification review. SQLite
+ is its reference case because the bounded restart-experience loss did not
+ justify the persistence surface; accepting that tradeoff changed the contract,
+ rather than a prior contract change causing the removal. The later repository
+ audit in TODO is not permission for broad cleanup during this handoff.
+- The canonical root/main checkpoint reconciles the route truth audit with this
+ room decision. Use that coherent truth as the base; do not replace it with
+ older documents from another worktree.
+- Existing auxiliary worktrees and branches are retained candidates or audit
+ material. Do not merge or delete them until their unique changes, references,
+ and reparse/junction safety are checked against current main.
+
+First report back with: current branch/HEAD, dirty-file scope, accepted versus
+implemented versus deployed room/route state, and the next authorized TODO. Then
+follow the latest owner instruction without reviving stale agent or branch facts.
+```
diff --git a/docs/status.md b/docs/status.md
index 436aca14..15723685 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -13,7 +13,7 @@ This is the current execution index. Git history owns completed timelines; [veri
## Current Source
-- Canonical source is the clean `main` branch; auxiliary branches and worktrees do not own current truth.
+- Canonical source is the root `main` branch; auxiliary branches and worktrees do not own current truth. The documentation-only route/room truth and handoff checkpoint is part of this canonical state; start dependent work only from that exact root `main` commit.
- Current source implements one steady outbound media-copy cap for every non-server endpoint: default `2`, static `1/2/3`, a peer child or Host publication consumes one slot, upstream receive is free, a committed selected TURN transport replaces the same copy while hidden carry consumes another, and no Browser/UA/visibility tier exists. One shared guard owns the accounting and transition work is bounded by `min(C + 1, 3)`.
- Current source and accepted room admission support one Host plus up to `20` Viewers. Focused controller coverage includes `C=1/2/3` and a 20-Viewer graph; real Browser resource and media measurements remain release evidence.
- The single Browser `screener-v7` boundary rejects stale Browser and executable-sender wires before room authority and carries the exact deployment cap plus exact prepare candidate in the authenticated route contract.
@@ -21,14 +21,16 @@ This is the current execution index. Git history owns completed timelines; [veri
- Current source implements automatic P2P-first routing with one active upstream, an acyclic source-reachable graph, exact Browser v7 prepare tuple, first-decoded-frame make-before-break, strict rollback revision, and bounded wait or failure.
- One event-driven controller owns the committed graph and at most one room-serial child operation. The operation owns one deterministic tuple list/cursor, one current candidate and reservations, fact version, and one total deadline. Failed tuples are operation-local; exhaustion retires invalid/overflow edges but retains healthy bootstrap media. Bounded-gap preflights resources, replans the remaining suffix, and restores a healthy retired edge through one final ordinary candidate. Admission commits synchronously before graph promotion; release uses the resource-set difference and room disposal returns all resources. One Host publication serves exact Viewer subscription handles, selected TURN changes only transport, and actual global resource release wakes registered waiting rooms.
- Parent selection is deterministic rather than random or score-based: hard eligibility filters, then shallowest result, remaining sender capacity, stable join order, and peer identity. The exact candidate child's first new decoded frame is the only application media-ready event. Moderate bitrate, FPS, or visual degradation remains with stock WebRTC/LiveKit adaptation and diagnostics; only hard connection failure or a non-paused decoded-frame stall invalidates a route edge. Viewer connection feedback and the strict-NAT emulator gate are accepted follow-up work, not deployed behavior.
+- Browser initial capture and source switching already request available share audio through one shared capture boundary and visibly retain video-only sharing when no audio track is returned.
- Live 64/128/256 audio-ceiling mutation and paused-share video codec switching are accepted but not yet implemented on canonical `main`. H.264 startup blur/low-FPS reports remain an evidence-led diagnosis, not a presumed codec defect. Public-server and fully local distribution packages are later work after the functional, NAT, and real-network ledger is complete.
+- The accepted room target is one process-memory RoomStore with random four-digit codes, a default 24-hour dormant lease, local Host preference replay, independent token invitations and `open | password | disabled` code entry, and no SQLite. Current source and production still use the old 12-digit/SQLite and `private-link | public-watch` surfaces; the target is documented and queued, not implemented or deployed.
## Current Milestone
1. Release the implemented generic route loop on the single Browser `screener-v7` wire after its remaining production acceptance boundary.
2. Release live audio-ceiling mutation and paused-share codec switching on the resulting generation/transition boundary.
3. Reproduce the H.264 startup report before any codec-specific repair, and build the strict-NAT emulator gate before any manually approved canary in an operator-owned test room.
-4. Add first-frame-driven Viewer connection stages and finish the remaining accepted functional and real-network work.
+4. Add first-frame-driven Viewer connection stages, then implement the accepted memory-resident room/access slice and finish the remaining accepted functional and real-network work.
5. Validate and deploy each coherent slice in this order with its focused browser/network/resource and rollback gates; distribution packaging remains outside this milestone.
## Active Boundaries
@@ -36,10 +38,15 @@ This is the current execution index. Git history owns completed timelines; [veri
- `fix/configurable-relay-cap` is an old, incomplete draft and must not be merged as-is.
- Open PR #192 and the Native stack are evidence/research, not pending product releases. Native senders, capture helpers, shared-encode executables, and their test binaries are outside the current route release and are not built or run in this milestone.
- Deployed surfaces and retained candidates that still need product decisions are indexed only in [the TODO ledger](./todo.md); do not extend or roll them back automatically.
+- Room entry, sharing controls, ID lifetime, and storage semantics are settled in the owning requirements/design/ADR and queued after the route boundary. Current source remains divergent until that complete slice replaces the old access and persistence model atomically.
- Real SFU/TURN recovery, heterogeneous networks, mobile lifecycle, audio/A-V device behavior, and endurance/resource measurements remain external acceptance evidence, not blockers for unrelated reversible work.
-## Next Stop
+## Current Hold
-Complete the route production boundary without repeating the full local suite: one resource-limited
-20-Viewer Browser smoke, production preflight, deploy, postflight, and rollback verification. The
-dedicated LiveKit instance and measured SFU/TURN capacities remain required deployment inputs.
+The route model and Browser source are complete and merged. Work is intentionally paused before
+production release or any later TODO until the owner chooses the next action. Production therefore
+remains on `9461e20` / `screener-v5`; source completion must not be reported as deployment.
+
+If the owner resumes the route release, do not repeat the full local suite. Run one resource-limited
+20-Viewer Browser smoke, then production preflight, deploy, postflight, and rollback verification.
+The dedicated LiveKit instance and measured SFU/TURN capacities remain required deployment inputs.
diff --git a/docs/todo.md b/docs/todo.md
index 114f0d5e..647b504a 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -6,7 +6,7 @@ Only items in **Now** are executable after their stated decision gate. A branch
## Now
-1. **Release the converged Browser route.** The one-controller `screener-v7` source is implemented, merged, typechecked, and focused-review clean. Do not repeat the full local suite. Run one resource-limited 20-Viewer Browser smoke that records route convergence, first-frame or bounded failure, endpoint sender counts, application CPU/memory, and SFU/TURN usage, then run production preflight, deploy, postflight, and rollback verification. Do not build or run Native, helper, shared-encode, Go test, or hardware executable artifacts.
+1. **Release the converged Browser route (held pending owner direction).** The one-controller `screener-v7` source is implemented, merged, typechecked, and focused-review clean. Start no release action until the owner resumes this item. Then run one resource-limited 20-Viewer Browser smoke that records route convergence, first-frame or bounded failure, endpoint sender counts, application CPU/memory, and SFU/TURN usage, followed by production preflight, deploy, postflight, and rollback verification. The existing Chrome attempt never reached a Browser/media run and must not be counted or retried unchanged; [verification status](./verification-status.md) owns that boundary. Do not repeat the full local suite or build/run Native, helper, shared-encode, Go test, or hardware executable artifacts.
2. **Switch screen-audio ceilings live.** Keep Opus fixed and serialize 64/128/256 kbps desired profile updates across every current Host, relay, and SFU audio sender. Each endpoint uses fresh `getParameters()`/`setParameters()` readback, ignores stale completions, retains media plus its prior applied value on failure, and applies the latest desired value to future edges. Do not add a remote applied-ack protocol or claim room-wide atomic convergence in this slice.
3. **Switch video codec while paused.** After the route/media-generation boundary is available, serialize the change with route mutation, freeze exact current route/media bindings, hold new joins, renegotiate P2P/relay and republish SFU while paused, then verify actual codec plus decoded frames on resume. A binding invalidated by leave or hard route failure exits this proof set and waits for routing to rebuild from the final committed preference after the bounded codec transaction settles. On failure pause again and perform bounded rollback; rollback proves the prior preference was reapplied plus a newly negotiated actual codec and decoded progress, not literal equality with the old actual codec. Zero targets update only the future-edge preference. Reset `automatic` with empty codec preferences. This is a paused bounded-gap transaction; unpaused make-before-break is a later extension.
4. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against current `main` on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.
@@ -15,8 +15,7 @@ Only items in **Now** are executable after their stated decision gate. A branch
## Queued After Route
-1. **Default room entry and sharing controls.** Make new rooms default to room-code entry without a password. Before implementation, settle one meaning for a token-bearing share link when code entry is already open, then make room code, invite link, and password commands visually distinct with direct labels and familiar icons.
-2. **Default Web share audio request.** For every Browser capture surface that can expose share audio, request audio by default and keep an explicit, truthful no-audio fallback when the browser, operating system, selected surface, or user choice does not provide it. Do not add a native helper or executable for this item.
+1. **Implement memory-resident rooms and clear sharing controls.** Replace the two current room modes with one in-memory model: uniformly random free codes from `1000..9999`, `ROOM_LEASE_SECONDS=86400` by default, no expiry while Host sharing, dormant renewal only by the exact Host token, release after expiry, and total loss on process restart. Remove SQLite, `ROOM_DATABASE_PATH`, `ROOM_TTL_SECONDS`, schema/migration code, and compatibility surfaces atomically. Make Viewer grant independent of `open | password | disabled` code entry; default to `open` with no room password while the primary share action copies the token-bearing invitation. Persist the Host's display name, code-entry policy, and optional room password as a same-origin local creation profile and atomically reapply it to a newly created room after expiry/restart. Give room code, invitation link, grant rotation/revocation, and code/password policy distinct direct labels and familiar icons. Current source still implements the old model; do not report this item complete until source, tests, deployment guidance, and browser behavior agree.
## Accepted Later Roadmap
@@ -25,10 +24,11 @@ These items are real product work, ordered after the current release boundary; t
1. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari device matrices for autoplay gesture, foreground/background audio, foreground video recovery, lock/page reclamation, rotation, Wi-Fi/cellular migration, and an assigned relay's outbound-media survival or controller failover across those transitions. Preserve the same media element and current reconnect path; do not promise background video composition, background relay continuity, or unsupported lock-screen behavior.
2. **Real network acceptance.** Measure standard ICE/STUN, IPv4/IPv6, independent STUN destinations, selected TURN, SFU ingress, and bounded failure across representative NATs and mobile networks. Browser port prediction remains experiment-only until its emulator and allowlisted-canary gates pass; raw-IP ranking and a room-wide quality score remain out of scope. Parent choice uses exact edge evidence and the accepted route controller.
3. **Platform output only when real.** Revisit AirPlay/Cast only when a target browser and physical receiver prove the live `MediaStream` contract. System mirroring remains external; no placeholder button, custom receiver, or server transcode is scheduled.
-4. **Public-server one-click deployment package.** After every current functional and real-network item is settled, package the exact application, STUN/SFU/TURN, reverse proxy, storage, secrets, health checks, backup and rollback flow for a user-owned public server. Require real domain/TLS/firewall/capacity inputs and never ship credentials or call a partial deployment ready.
+4. **Public-server one-click deployment package.** After every current functional and real-network item is settled, package the exact application, STUN/SFU/TURN, reverse proxy, secrets, health checks and rollback flow for a user-owned public server. Require real domain/TLS/firewall/capacity inputs and never ship credentials or call a partial deployment ready.
5. **Fully local one-click Host-server package.** Package Windows/macOS/Linux Host capture, the exact application server and local state without requiring source, Node or any external Screener/STUN/SFU/TURN/tunnel/relay service. Preserve usable direct P2P and use the completed NAT/network evidence to maximize reachability, while reporting public-origin, gateway, NAT and firewall limits truthfully; loopback/LAN success is not universal Internet success.
6. **Native Host capture backend.** At lowest priority, productize a proven Windows native capture path before expanding capture/audio backends to macOS and Linux. Its capture, hardware encode, audio, identity and lifecycle evidence becomes an input to later packages; a source checkout, helper executable, or evaluation ZIP is not a distributable product.
7. **Native shared encode, Windows first.** At lowest priority, prove one hardware encoder output can serve two independent Viewer transports and the Host-SFU publication while each connection retains its own RTP/RTCP, pacing, encryption, feedback, and upload accounting. Productize only after actual access-unit identity, Viewer2/FIFO, heterogeneous feedback, game-resource, browser/hardware, A/V, packaging, and licensing gates pass. Web Host/relay remains standard per-`RTCPeerConnection` encoding because no portable shared-encoder contract exists.
+8. **Repository simplification audit.** After the current route and room checkpoints and their scoped implementation work settle, inventory components, configuration, migrations, gates, timers, compatibility paths, and tests using the [maintenance review](./maintenance.md#机制减负审查). Begin read-only: identify the user behavior each mechanism preserves, quantify the impact of removing it, and compare that value with its whole-system cost. Any accepted feature tradeoff updates its owning contract before complete unused surfaces are removed. This later audit must not become a broad refactor or block current product work.
## Product Decisions Needed
@@ -50,6 +50,6 @@ These decisions are not permission to continue old branches, and current deploym
## Candidate Handling
-- Preserve `fix/configurable-relay-cap`, but do not commit or merge it. Its relevant intent must be rebuilt after route truth is accepted.
+- Preserve the dirty `fix/configurable-relay-cap` worktree only for user-change audit. Current `main` already implements the accepted uniform `1/2/3` endpoint cap; do not merge the worktree's old route implementation or treat it as unfinished cap work.
- Preserve dirty or unique worktrees and open stacked branches until reviewed. Never resolve their conflicts by importing old truth into `main`.
- Sample worktree, branch, PR, artifact, and reparse-point state immediately before cleanup; do not maintain a permanent workspace inventory here.
diff --git a/docs/verification-status.md b/docs/verification-status.md
index fdd5e1a2..f2ffb7dc 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -23,6 +23,7 @@ Capacity and routing entries below describe the exact tested source or release o
- Exact source `31e323e2754fcfde15f7b4d69e925ec71e2795cb` passed repository hygiene, TypeScript typecheck, client/server builds, all 660 Web tests, all Native Go packages, `go vet`, and two independent P0/P1 reviews. The tests cover strict v6 endpoint-cap authentication, ordinary active/waiting authorization and grace promotion, Native cap propagation and admission, and peer-assisted cap rejection. This is local state-machine/build evidence, not a complete Native physical-slot matrix or production, browser-quality, or heterogeneous-network acceptance.
- Exact Wave B implementation source `815c6174d411c55648daf5cd6ac4c42f64effff9`, based on `d1ba2e52919225e67ad0c8dd2b660f333fbc88fd`, passed its 372-test SFU-admission gate, all 690 Web tests, TypeScript typecheck, and client/server builds. Focused tests cover reserved/committed/draining accounting, reserve-before-token enforcement, explicit room lifecycle, listener-owner startup fencing, restart cleanup, stale-token replay boundaries, Host-offline reclamation, shutdown races, and two-room global admission. This is fake-control-plane and local state-machine evidence, not a real LiveKit process/JWT replay, packet-flow, multi-process, deployment-capacity, or production proof.
- Exact route source `4e0a922` passed repository hygiene, TypeScript typecheck, and 84 focused controller, runtime, protocol, transition, decoded-stall, and SFU-admission tests. During the same convergence, the full 557-test Web suite and client/server builds passed before the final no-consumer cleanup. The two independent route audits' model and wire findings are incorporated, and final static review found no remaining P0/P1. No Browser, Native, Go, helper, hardware, or executable test ran in the final pass; this is source and state-machine evidence, not production or heterogeneous-network proof.
+- A 2026-08-23 attempt to start the required one-Host/20-Viewer Browser smoke produced `RunCount=0`: the Windows Chrome launcher exited before its CDP endpoint was ready, so no room, route, media, or resource measurement ran. This is harness infrastructure evidence, neither a route pass nor a route failure; do not retry the unchanged launcher.
- Current source TURN-admission unit and signaling tests cover independent peer and Host-SFU logical edges, shared capacity exhaustion, exact reserve/commit/drain/release identity, current-share cleanup, and graceful shutdown. This is local authorization evidence, not real coturn, network-media, or production-capacity proof.
- Chrome 151 synthetic `1/3/5/8` and 720p30 runs preserved bounded fanout and decoding. A `9461e20`-era three-Viewer rerun kept Host2/Browser Viewer1, decoded every Viewer, and recovered a hard first-level relay departure in 5,380 ms; it did not exercise quality-triggered MBB. Sixteen-Viewer cap2/cap3 loopbacks decoded all Viewers and a ten-second follow-up recorded guarded sender and aggregate Chromium CPU evidence, but resolution/FPS remained low and the ordinary-PC data cannot rank caps, select product policy, or prove sustainable heterogeneous-network quality. See [peer-assisted media](./research/peer-assisted-media.md).
- Chrome 151 with local LiveKit 1.13.5/client 2.22.0 proved one SFU/UDP root after `q,f` -> `q,h`: decoded frames advanced 3 -> 23, rendered frames reached 26, Host used one edge, leaves were clean, and TURN was absent. This is functional evidence only. See [low-server media routes](./research/low-server-media-routes.md).
@@ -30,7 +31,7 @@ Capacity and routing entries below describe the exact tested source or release o
- The built-in peer TURN canary was rejected after allocation passed but the direct Host/Pion Viewer path failed before forced relay. Full rollback restored STUN-only client ICE and zero allocations. See [built-in peer ICE TURN](./research/built-in-peer-ice-turn.md).
- Chrome H.264 loopback proves negotiation and decode interoperability, not encoder performance or hardware attribution. Native WGC/MF has a one-Viewer Windows proof with 203 rendered 1280x720 frames, 500 Opus packets, and nonzero process/LUID-correlated `VideoEncode`. See [Native H.264](./research/native-h264-hardware-decision.md) and [Native shared encode](./research/native-shared-encode-sender.md).
- Native Windows 11 process audio is source-only and default-off. A retained run isolated the target by about 4018x and delivered 495 Opus packets to one Viewer; package download, game sync, Windows 10, and other routes remain open. See [ADR-0008](./adr/0008-window-scoped-audio-capture.md).
-- The local access gate proves pre-DOM fragment clearing, room-scoped session isolation, no site/grant transport-log hits, no raw room-password SQLite sentinel, and rotate/revoke behavior. It is headless loopback evidence only. See [ADR-0002](./adr/0002-persistent-protected-rooms.md).
+- The local access gate proves the current source's pre-DOM fragment clearing, room-scoped session isolation, no site/grant transport-log hits, no raw room-password SQLite sentinel, and rotate/revoke behavior. It predates the accepted in-memory room replacement and is headless loopback evidence only. See [ADR-0002](./adr/0002-memory-resident-protected-rooms.md).
## Open Proof Boundaries
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 292d524e..b641ad6b 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"
@@ -11,14 +11,14 @@
本阶段必须形成完整的最小纵向链路:
- 分享者主动选择屏幕、窗口或标签页,并请求可用音频;
-- 创建数字房间;production site access 密码严格控制建房/发布,默认 room-scoped capability link 让 Viewer 免站点密码观看,部署可选择最小 SQLite 持久化;
+- 创建四位随机数字房间;production site access 密码严格控制建房/发布和 code-only 观看,默认 room-scoped capability link 让受邀 Viewer 直接观看,房间控制状态只驻留当前进程内存;
- 每名观看者拥有独立的 `RTCPeerConnection`;
- 当前 production 要求 STUN,普通 peer ICE 只发 STUN servers;SFU 只开放 LiveKit ICE/UDP;
- 展示连接状态、direct/relay、RTT、实际码率、帧率和丢包等数据;
- 超过部署配置上限的观看者被明确拒绝,不静默超载;
- 在代码、测试和真实浏览器验证完成前,不宣称达到延迟或画质目标。
-首个基线不实现账号数据库、通用业务数据库、Redis、simulcast/SVC、语音聊天、Electron、原生捕获、PWA、录制、遥测平台或多地区调度。唯一持久化例外是可选的 `node:sqlite` 房间身份表。后来接受的 peer-assisted/SFU candidate 只通过 ADR-0004/0005 的现有窄 owner 扩展,不引入第二套路由器或通用优化框架。
+首个基线不实现账号数据库、通用业务数据库、房间数据库、Redis、语音聊天、Electron、原生捕获、PWA、录制、遥测平台或多地区调度。房间控制状态只驻留当前应用进程;peer-assisted/SFU candidate 只通过 ADR-0004/0005 的现有窄 owner 扩展,不引入第二套路由器或通用优化框架。
## 技术栈决策
@@ -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 摘要与 nullable Viewer-password KDF material |
+| 房间状态 | 进程内 `RoomStore` | 重启本已中断媒体;新增房间号和邀请的有界回退不值得持续承担数据库、迁移和恢复分支 |
| 运行时校验 | Zod | WebSocket 和 HTTP 输入不可信,需要与 TypeScript 类型一致的运行时边界 |
| 静态文件 | `sirv` | 生产环境由同一 Node 进程提供前端构建结果,避免引入完整 Web 框架 |
| 地址发现/可选兼容传输 | coturn 4.17.2 或更新补丁版本 | 普通 peer 只下发 STUN;TURN 仅可服务整体路由模型明确授权的短期 edge,并受 UDP relay range、credential、quota 和真实媒体门禁约束 |
@@ -36,7 +36,7 @@
不选 Go 的原因是 Node 不承载正常情况下的媒体流量,换语言不会减少分享者上行或 TURN 中继成本。不选 C++ 的原因是浏览器能力尚未被实测证明不足;只有捕获、应用音频或硬件编码出现明确瓶颈时才增加原生 helper。
-最终分发有两个独立产物。公网服务器一键部署包面向用户自有服务器,编排同一版本的 Web/信令应用、持久状态、STUN/SFU/TURN 和反向代理,不建立第二套应用;域名、TLS、secret、端口、容量、备份、健康检查和回滚继续 fail closed。它不提供托管基础设施,也不把占位配置写成可用服务。
+最终分发有两个独立产物。公网服务器一键部署包面向用户自有服务器,编排同一版本的 Web/信令应用、易失房间状态、STUN/SFU/TURN 和反向代理,不建立第二套应用;域名、TLS、secret、端口、容量、健康检查和回滚继续 fail closed。它不提供托管基础设施,也不把占位配置写成可用服务。
本地自包含一键包在分享者电脑上同时承载 Host、当前 Web/信令应用服务器与本地状态,Viewer 仍使用普通浏览器。它不调用任何外部 Screener、STUN、SFU、TURN、隧道或 relay 服务,并复用唯一协议、房间、鉴权和路由实现;公网覆盖取决于本机入口、可信 origin、网关映射和 NAT 条件,direct P2P 可用时保留,受限时明确失败。具体 runtime、进程边界、签名、更新、证书、网关与 NAT 方案等当前功能和真实网络 TODO 完成后再由证据确定,不得先用某个打包器或自动映射技巧反向定义产品。
@@ -72,35 +72,33 @@ tests/ RoomStore、ICE 配置、协议和 WebSocket 集成测试
`SITE_ACCESS_PASSWORD` 是简单的部署访问口令,不是 Viewer 密码或账号凭据。production 启动时必须配置;本地开发/测试可显式关闭。非空值必须包含 8 至 128 个可见 ASCII bytes(`0x21` 至 `0x7e`),并作为不复用 TURN、LiveKit、TLS 或其他凭据的独立 secret。`POST /api/site-access` 只在严格允许的 Origin 下接收 `Authorization: Bearer`,成功后签发 12 小时的无状态 site-access cookie:值只包含版本、到期时间和 HMAC-SHA256 签名,不创建账号、JWT 或服务端 session Map。cookie 使用 `HttpOnly`、`SameSite=Strict`、`Path=/`、有限 `Max-Age`;HTTPS 生产环境使用 `Secure` 和 `__Host-` 前缀。`POST /api/rooms` 只认该 cookie,不接受同一 Bearer 旁路。原子 deployment change 在 nginx 为该 admission endpoint 配置 per-source `limit_req`,初始边界为 `5r/m`、`burst=5 nodelay`;超限返回通用 429,允许到达 Node 的错误 secret 使用常量时间比较和统一 401。limiter 只使用 nginx shared memory,不新增 IP 持久化/日志字段;Node 不建立 IP key/LRU/session table,并保留现有全局/未鉴权连接上限。删除旧 `ACCESS_PASSWORD`、`/api/session` 与旧 cookie;旧环境变量出现时 fail-fast。
-WebSocket upgrade 无法预知后续 role,因此仍允许没有 site-access cookie 的合法 grant Viewer 完成握手;握手前严格校验 `/signal` 无 query、Origin allowlist、总连接数和未鉴权连接数,并把当次 cookie 校验结果保存到 socket state。五秒内的第一条 `authenticate` 完成授权:Host 必须同时拥有 upgrade 时有效的 site-access 状态和当前房间 `hostToken`;Viewer 必须拥有目标房间合法未过期 grant,或者先通过 site access 再按 public/private policy 校验。site-access cookie 只允许尝试私密房间密码,不能替代 grant/password;Viewer grant 也不能用于 HTTP 建房、Host role、其他房间或其他操作。
+WebSocket upgrade 无法预知后续 role,因此仍允许没有 site-access cookie 的合法 grant Viewer 完成握手;握手前严格校验 `/signal` 无 query、Origin allowlist、总连接数和未鉴权连接数,并把当次 cookie 校验结果保存到 socket state。五秒内的第一条 `authenticate` 完成授权:Host 必须同时拥有 upgrade 时有效的 site-access 状态和当前房间 `hostToken`;Viewer 必须拥有目标房间合法未过期 grant,或者先通过 site access 再按 `open | password | disabled` code-only policy 校验。site-access cookie 只允许进行 code-only 尝试,不能替代 grant/房间密码;Viewer grant 也不能用于 HTTP 建房、Host role、其他房间或其他操作。
-新房间默认 `private-link`,也允许 Host 显式选择 `public-watch`:
+Viewer grant 与 code-only 入口是两个正交维度。每个房间都用 `randomBytes(32)` 生成含 256-bit 随机量和到期时间的 room-scoped opaque grant,服务端只在内存保存完整 grant 的 SHA-256 摘要并用定长比较验证。Host 的主分享动作始终复制 token-bearing invitation;到期在以后鉴权/重连时拒绝,即时清退使用 rotate/revoke。
-- `private-link`:服务端用 `randomBytes(32)` 生成 256-bit 随机量,并把到期信息和随机量组成严格、room-scoped 的 opaque Viewer grant;只保存完整 grant 的 SHA-256 摘要并用定长比较验证。临时房间 grant 不晚于 room TTL;持久房间 grant 固定七天。这个无配置首版边界允许熟人跨短期游戏会话复用链接,但不让可枚举持久房间产生永久邀请;只有真实使用证据才调整。到期在首次鉴权/重连时拒绝,不定时踢出已鉴权 Viewer;即时清退使用 rotate/revoke。
-- `public-watch`:通过 site access 后,`/r/{roomId}` 或 `/join` 房间码允许 Viewer 进入,不签发 Viewer grant。房间码只定位;该 policy 仍受房间 Viewer、全局/未鉴权连接和中央 egress/admission 上限保护,不提供房间目录。
-- `private-link` 另可设置一个逐房间 Viewer 密码。有效 fragment grant 保持直达;只有房间号时显示中性密码表单,正确密码仅鉴权当前 Viewer 会话。Host 可设置、改写或移除,密码接受 1 至 64 个可见 ASCII 字符且不要求组合复杂度。逐人邀请、账号、找回、ACL 和通用授权服务仍不做。
+code-only policy 使用单一 `open | password | disabled` 状态:`open` 是无房间密码的默认值;`password` 要求已通过 site access 的 Viewer 再输入该房间密码;`disabled` 中性拒绝 code-only 尝试。它们都不改变有效 grant 的 exact-room Viewer authority,也不建立目录、账号、ACL 或额外媒体容量。Host 可独立改变 code-only policy、设置/替换/移除密码,以及 rotate/revoke grant。
-房间密码明文只短暂存在于当前 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。
+Host 的同源 `localStorage` creation profile 保存显示名、code-only policy 和可选房间密码,使进程重启或租约过期后的下一次显式分享可原子应用同一偏好。该密码只保存在 Host 浏览器;不保存在 Viewer 浏览器、URL/query/fragment、cookie、日志、错误或服务器持久存储。建房/更新请求通过 HTTPS/WSS 把明文短暂交给服务端,服务端使用 Node 标准异步 `scrypt` 固定 `N=16384,r=8,p=1`、16-byte 随机 salt 和 32-byte verifier,只在当前房间内存保存 48-byte material。进程级 gate 最多执行 2 个、等待 16 个派生,队满即有界失败;任务开始和提交前都复核当前 Host/Viewer session 与 room material。不存在房间、未配置/错误密码和正确密码后的满房都使用通用拒绝。
-私密邀请使用 `/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 必须把链接称为访问凭据。
+邀请使用 `/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 重连继续使用该页面会话的值。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 必须把链接称为访问凭据。
-`ROOM_DATABASE_PATH` 仍是可选 SQLite 文件路径,但必须同时配置 `SITE_ACCESS_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 表。
+房间只有一种易失模型。进程启动时建立 `1000..9999` 的空闲码池;创建房间时用加密随机索引从当前空闲集合取出一个号码并以 swap-remove 删除,释放时放回。这样在 9000 个号码内没有碰撞重试、递增身份或数据库序列。`MAX_ROOMS` 默认 1000 且不得超过 9000。
-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 必须停服并恢复备份。临时内存房间随部署重启结束。
+`ROOM_LEASE_SECONDS` 默认 86400。RoomStore 对连接中的 Host 不执行到期;Host 明确停止或连接消失时将 `expiresAt` 设为 `now + lease`,同一 Host token 在期限内重新鉴权并分享时续租,Viewer 活动不修改期限。清理循环删除 dormant expired room、关闭其 session/route/resource 并把号码归还空闲池。应用进程重启直接清空全部房间;配置不再包含 `ROOM_DATABASE_PATH`、`ROOM_TTL_SECONDS` 或任何 schema/migration。所有房间继续生成 256-bit Host token,Host 浏览器保存 raw token,服务器当前进程只保存摘要;不使用 IP、UA、设备信息或浏览器指纹认领。
-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 只放宽已通过 site access 的房间级鉴权,不需要迁移健康媒体。服务端永不返回现有 grant 明文;丢失 Host 标签页中的 grant 时只能 rotate。
+rotate/revoke 是 grant 路径的强撤销:服务端先同步提交新 digest/authorization generation,再清除 Viewer grace、连接代次与路由状态,向 Viewer 发送通用访问已撤销终态使其立即关闭接收 `RTCPeerConnection`/媒体并停止重连,同时让每个 Host/relay/SFU upstream owner 关闭旧代次发送边,最后关闭 Viewer socket。不能只断 WSS,因为健康 P2P 可在信令断开后继续播放。rotate 生成并仅返回一次新 grant;revoke 写入没有对应 raw grant 的 fresh random locked digest。code-only policy 和密码保持独立;其变更只影响以后 code-only admission,除非 Host 明确执行强撤销。服务端永不返回现有 grant 明文;丢失 Host 标签页中的 grant 时只能 rotate。
房间规则:
-- 一名在线分享者、最多 `20` 名 authenticated Viewer;房间 admission 与 endpoint/SFU/TURN capacity 分离,当前 production 默认八名且 source 只接受 1 至 16 是待本轮发布替换的部署事实;
-- 分享者明确停止或捕获轨结束时只停止当前发布并通知观看者进入等待,不删除房间或使链接失效;host 信令短断仅更新在线状态并触发恢复,不能主动关闭仍健康的 P2P 媒体;
-- 临时房间到达 TTL 后才拒绝新连接、通知现有参与者并从内存清理;持久房间没有 TTL,进程启动时从 SQLite 恢复房间身份;
-- 设置全局房间上限防止内存耗尽;持久房间没有自动删除策略,运维方必须保护和备份数据库文件;
-- 运行时仍只在内存保存当前 host/viewer 连接与信令状态,任何模式都不记录 SDP、ICE candidate、IP 地址、媒体或 TURN 密钥。
+- 一名在线分享者、最多 `20` 名 authenticated Viewer;房间 admission 与 endpoint/SFU/TURN capacity 分离。Production `9461e20` 默认八名且只接受 1 至 16;当前 source 已接受 1 至 20,生产值在 20-Viewer smoke 通过后随 route release 提升;
+- 分享者明确停止或捕获轨结束时停止当前发布、通知观看者进入等待并开始 dormant lease,不立即删除房间;host 信令短断先交给既有恢复,在租期内仍可用同一 Host token 续租;
+- 活动分享不因租期到达而删除;dormant 房间过期后拒绝新连接、通知现有参与者、清理 route/resource 并释放号码;
+- 设置不超过四位号码池的全局房间上限;进程重启清空全部房间,不恢复任何 ownership、grant 或密码状态;
+- 单个服务器内存控制面保存当前 room/participant/authorization/signaling 状态,但不记录 SDP、ICE candidate、IP 地址、媒体或 TURN 密钥;媒体面继续按 P2P-first 图分布,不把媒体压力移到应用服务器。
客户端用 `sessionStorage` 保存随机的 128-bit `clientId`,作为当前标签页内稳定的参与者 key。同一 role/clientId 的新 WebSocket 会原子替换旧 socket;观看者断线后保留五秒 grace,期间不发送 `peer-left` 且 `peerId` 不变,重新鉴权时重发幂等的 `peer-joined`,超时才释放名额。host 鉴权或重连后,`authenticated` 携带包含 grace 成员的权威 viewer ID 列表供客户端删除已离开的 peer,服务端再重放当前在线观看者的 `peer-joined`,因此观看者可以先于 host 打开邀请,host 离线期间的离开也不会遗留幽灵连接。
-显示名是独立的本地偏好:同源 `localStorage` 只保存浏览器输入,存储不可用时静默退回内存 fallback;服务端只把参与者的规范化名称挂在当前 authenticated socket state,断线即丢弃,不进入 RoomStore、SQLite 或日志。shared schema 先做 NFC、合并 Unicode space separators、去除边缘空格,再限制为 1 至 24 个 Unicode code points,并拒绝控制字符、行/段分隔符、BOM、双向控制符和孤立 surrogate;未设置时 Viewer 使用通用“访客”,Web Host 可由 room-scoped stable client ID 生成本地 fallback。普通多语言文本、组合字符和 emoji 仍可用。
+显示名是独立的本地偏好:同源 `localStorage` 只保存浏览器输入,存储不可用时静默退回内存 fallback;服务端只把参与者的规范化名称挂在当前 authenticated socket state,断线即丢弃,不进入 RoomStore durable state 或日志。shared schema 先做 NFC、合并 Unicode space separators、去除边缘空格,再限制为 1 至 24 个 Unicode code points,并拒绝控制字符、行/段分隔符、BOM、双向控制符和孤立 surrogate;未设置时 Viewer 使用通用“访客”,Web Host 可由 room-scoped stable client ID 生成本地 fallback。普通多语言文本、组合字符和 emoji 仍可用。
Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,Viewer 也可显式订阅同一 participant snapshot;Native sender 不发送,因此继续只收到原有 exact server wire。两端可在 `authenticate.displayName` 发送名称,并以 `set-display-name` 更新当前会话。服务端只向已订阅的 Web participant 发送完整 `viewer-presence` snapshot,列表严格来自当前带 sessionId 的在线参与者,不含五秒媒体恢复 grace 成员;条目用 `role` discriminator 区分 Host/Viewer。加入、离线、会话替换、改名和 active route 改变都会重发快照;该只读广播不调用 connect/reconcile,也不建立任何媒体边。Host 的“在线”Viewer 总数只取 Viewer 条目数;最多两条本机媒体快照只补充当前以 Host 为 active upstream 的连接指标。
@@ -108,18 +106,17 @@ Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,
## 信令协议
-WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是 `screener-v7` 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access;Web Host 可选发 `viewerPasswordSettings: true` capability。Viewer 消息携带 room、role、clientId,以及 private room 的 Viewer grant 或当前尝试的房间密码。成功的 `authenticated` 快照始终携带部署最终值 `endpointMediaCopyCapacity: 1|2|3`;普通模式的服务端 admission 只向 Host 激活稳定加入顺序中的至多该数量 Viewer,并在离开后提升等待者,双方信令只允许 active child。Browser Host 与 Viewer 严格校验该值,房间 `maxViewers` 只约束观看者总 admission。Native/executable sender 停留在旧 wire 并在 authority 前拒绝。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。
+WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是当前单一 wire 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access。Viewer 消息携带 room、role、clientId,以及 exact-room Viewer grant 或当前 code-only password attempt。成功的 `authenticated` 快照始终携带部署最终值 `endpointMediaCopyCapacity: 1|2|3`;普通模式的服务端 admission 只向 Host 激活稳定加入顺序中的至多该数量 Viewer,并在离开后提升等待者,双方信令只允许 active child。Browser Host 与 Viewer 严格校验该值,房间 `maxViewers` 只约束观看者总 admission。Native/executable sender 停留在旧 wire 并在 authority 前拒绝。服务端设置 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/password settings;Viewer 以 public room code、private Viewer grant 或当前房间密码尝试建立仅观看会话并可附带规范化本地显示名 |
+| client -> server | `authenticate` | Host 以 upgrade 时的 admission 状态加 room-scoped Host token 建立会话并可订阅 Web-only presence/settings;Viewer 以 exact-room Viewer grant,或 site access 加当前 `open/password` code-only policy 建立仅观看会话,并可附带规范化本地显示名 |
| 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 upstream;不触发媒体连接 |
-| 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 |
+| host -> server -> host | room-access update | 独立设置 `open/password/disabled`、设置/移除 password,或 rotate/revoke grant;raw grant 只在新建或 rotate 成功响应中出现一次,服务端不回显密码 |
| server -> host | `peer-joined` / `peer-left` | 建立或关闭该观看者的独立连接 |
| host -> viewer | `offer` / `candidate` | 带 `peerId` 与 `connectionId` 的定向信令 |
| viewer -> host | `answer` / `candidate` | 只能回给本房间分享者 |
@@ -135,7 +132,7 @@ Zod 在服务边界拒绝未知类型、超长字符串、非法 SDP/candidate
分享者是唯一 offerer。每名观看者对应一个 `RTCPeerConnection`,以独立 `connectionId` 区分重建代次:
1. 分享者在开始按钮的同一用户手势内先成功调用 `getDisplayMedia()`。
-2. 只有捕获 track 已存在时才请求创建房间、连接 host WebSocket 并显示邀请;若用户在建房响应返回前取消,迟到结果不得覆盖后续分享会话。尚未被客户端认领的迟到结果通过内部 `abandon-room` 清理;已经认领的房间不因正常停止捕获而删除。持久模式使用 `AUTOINCREMENT`,被清理的编号不会复用。
+2. 只有捕获 track 已存在时才请求创建或续租房间、连接 Host WebSocket 并显示邀请。新建请求携带本地 creation profile,使 code-only policy 与可选密码 verifier 在房间可见前原子生效;若用户在响应返回前取消,迟到结果不得覆盖后续分享会话,尚未认领的房间通过内部 `abandon-room` 立即释放号码。已经认领的房间在停止捕获后进入 dormant lease,过期才释放。
3. 观看者认证后,服务端向在线分享者发送 `peer-joined`;host 晚上线或重连时收到完整观看者快照。
4. 分享者创建连接、加入当前视频 track,并以现有音轨或空 sender 预留 audio transceiver,设置 sender 参数,然后创建 offer。
5. 观看者收到 offer 后创建连接、设置 remote description、创建 answer。
@@ -262,7 +259,7 @@ publication。端点容量、SFU/TURN ingress/egress、临时 overlap、server a
和 bounded failure 在同一 reserve/first-frame/commit-or-abort 事务中记账。
短期 server-assisted credential 必须严格绑定当前 route identity、只存内存、受 TTL
-与 quota 限界,并且不进入 URL、日志、browser storage、room row 或 SQLite。Coturn
+与 quota 限界,并且不进入 URL、日志、browser storage 或任何持久存储。Coturn
只能验证 bearer 的 HMAC 与 expiry,应用仍需逐次重验 room/edge/generation。普通
SFU 终止 DTLS-SRTP;没有应用层 E2EE 时 operator 可接触媒体,产品必须如实说明。
所有物理 hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)逐项计量。
@@ -295,14 +292,14 @@ Host 与 relay Viewer 复用同一个纯 presentation reducer 保存远端 `View
首屏就是工具,不做营销页。视觉采用中性深灰工作台,绿色表示 direct、琥珀色表示 relay/警告、红色表示失败,避免单一蓝紫色主题;浏览器 favicon 复用页头 `MonitorUp` 的深绿底、绿色显示器和上行箭头语言。
-- 访问入口:未鉴权根路径、`/join` 和 code-only `/r/{code}` 显示“站点访问”与“站点口令”,未知路径只显示“无法访问”。有效 `/r/{code}#v={grant}` 直接进入;其余 Viewer 通过 site access 后,public-watch 进入房间,private room 显示“加入房间”与“房间密码”。已有有效 site-access cookie 不重复显示整站验证;站点口令和房间密码不共享输入值或授权状态。无效、过期、错误密码或满员只显示通用拒绝,不泄露房间存在性或 policy。
-- 分享者根页面:顶部显示“{分享者显示名} 的屏幕”和房间状态,并在标题旁显示可单独复制的紧凑房间号;Viewer 同一位置显示权威 Host 名称,不再在标题下重复。主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;前者直接开始现有分享流程,后者作为 disclosure 在当前舞台内、紧邻触发按钮就地展开共享的房间码表单,提交后才导航到 `/r/{code}`。按钮同步 `aria-expanded`/`aria-controls`,展开后输入获得焦点,DOM 与焦点顺序保持触发器后接表单;窄屏允许表单换到动作行下方,不产生横向滚动。不增加首页、向导或拓扑选择。直播时舞台显示本地预览及独立全屏图标,底部保留停止、同步暂停音视频、质量档位和复制完整邀请链接;页面失焦仅暂停本地 video element,并在舞台提示“本地预览已暂停,分享仍在继续”;媒体暂停则禁用 capture stream 轨道,两者都保留现有连接。
-- `/join`:保留为可直接访问的回退入口,并复用同一个房间码表单;通过 site access 后只输入正整数房间码并进入 `/r/{code}`。public-watch 直接通过,private room 缺失 grant 时显示当前房间的密码表单。
-- `/r/{code}` 观看者:private room 首次解析合法 fragment grant 后立即清理地址栏并直达;仅有 code 时先通过 site access,再按 public/private policy 进入。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制;Host 主动暂停时复用视频舞台遮罩显示“分享者已暂停”,恢复后立即移除。视频舞台用单一派生 presentation reducer 合成 access、Host presence、route prepare/active、peer/SFU connection、remote track、首个 composited frame、autoplay rejection 和 bounded failure。支持时用 `requestVideoFrameCallback()` 确认第一帧已提交,旧浏览器回退到当前代 decoded-frame delta 与 video readiness;`playing`、track object 或 ICE `connected` 单独都不足以结束占位层。连接阶段占用固定布局且不显示虚假百分比,播放按钮只处理实际 autoplay rejection,失败重试只调用现有有界 controller 入口。
+- 访问入口:未鉴权根路径、`/join` 和 code-only `/r/{code}` 显示“站点访问”与“站点口令”,未知路径只显示“无法访问”。有效 `/r/{code}#v={grant}` 直接进入;其余 Viewer 通过 site access 后按 `open/password/disabled` 直接进入、看到“加入房间 / 房间密码”或得到中性拒绝。已有有效 site-access cookie 不重复显示整站验证;站点口令和房间密码不共享输入值或授权状态。无效、过期、错误密码或满员只显示通用拒绝,不泄露房间存在性或 policy。
+- 分享者根页面:顶部显示“{分享者显示名} 的屏幕”和房间状态,并在标题旁显示可单独复制的紧凑四位房间号;Viewer 同一位置显示权威 Host 名称,不再在标题下重复。主区域保持稳定的 16:9 舞台。未发布、已停止或可恢复错误状态时,舞台内以同等尺寸和权重显示“开始分享”和“加入房间”,中间只用“或”与分隔线表达发送/接收;前者直接开始现有分享流程,后者作为 disclosure 在当前舞台内、紧邻触发按钮就地展开共享的房间码表单,提交后才导航到 `/r/{code}`。按钮同步 `aria-expanded`/`aria-controls`,展开后输入获得焦点,DOM 与焦点顺序保持触发器后接表单;窄屏允许表单换到动作行下方,不产生横向滚动。不增加首页、向导或拓扑选择。直播时舞台显示本地预览及独立全屏图标,底部保留停止、同步暂停音视频、质量档位,以及职责分离的“复制邀请链接”“复制房间号”“房间号加入:开放/密码/关闭”“更新邀请”“撤销邀请”控制;熟悉动作使用 lucide 图标、直接标签和 tooltip,不用一个含糊的“分享”菜单混装。主分享动作始终复制含 grant 的邀请链接。页面失焦仅暂停本地 video element,并在舞台提示“本地预览已暂停,分享仍在继续”;媒体暂停则禁用 capture stream 轨道,两者都保留现有连接。
+- `/join`:保留为可直接访问的回退入口,并复用同一个四位房间码表单;通过 site access 后输入 `1000..9999` 并进入 `/r/{code}`,后续行为由房间 code-only policy 决定。
+- `/r/{code}` 观看者:首次解析合法 fragment grant 后立即清理地址栏并直达;仅有 code 时先通过 site access,再按 `open/password/disabled` policy 进入。鉴权后主区域最大化远端视频,标题旁显示可复制的紧凑房间号,顶部保留连接状态,并提供本地音量、静音、全屏和重试控制;Host 主动暂停时复用视频舞台遮罩显示“分享者已暂停”,恢复后立即移除。视频舞台用单一派生 presentation reducer 合成 access、Host presence、route prepare/active、peer/SFU connection、remote track、首个 composited frame、autoplay rejection 和 bounded failure。支持时用 `requestVideoFrameCallback()` 确认第一帧已提交,旧浏览器回退到当前代 decoded-frame delta 与 video readiness;`playing`、track object 或 ICE `connected` 单独都不足以结束占位层。连接阶段占用固定布局且不显示虚假百分比,播放按钮只处理实际 autoplay rejection,失败重试只调用现有有界 controller 入口。
- 首帧观察绑定当前 assignment/connection/media-binding generation 以及适用的 publication generation;`srcObject` 或 route identity 变化立即使旧回调和旧 decoded baseline 失效,迟到回调不能把新路线标成已播放。
- 移动端:视频保持稳定宽高比,控制与状态移到视频下方,任何文字和按钮不得溢出或遮挡。
-两端默认显示紧凑在线 roster;Viewer 端复用同一权威 participant snapshot,只列出当前 Viewer(含本机)并在新 snapshot 到达时整体替换,停止分享仅移除已离线 Host,鉴权失效、房间关闭或页面卸载则清空。Host 与 Viewer 的本机显示名在界面中统一标为“昵称”,默认只读,铅笔按钮紧贴昵称并只切换当前控件的输入、保存和取消,唯一名称仅显示名称,重名时才追加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开媒体方式、传输协议、候选路径、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;地址与端口只从当前页面 `RTCPeerConnection.getStats()` 精确关联的 selected pair 读取,浏览器隐藏或缺失任一字段就不显示,且不进入质量证据、信令、服务端、日志或持久化。真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。显示名/roster 不进入 access credential 或 SQLite。
+两端默认显示紧凑在线 roster;Viewer 端复用同一权威 participant snapshot,只列出当前 Viewer(含本机)并在新 snapshot 到达时整体替换,停止分享仅移除已离线 Host,鉴权失效、房间关闭或页面卸载则清空。Host 与 Viewer 的本机显示名在界面中统一标为“昵称”,默认只读,铅笔按钮紧贴昵称并只切换当前控件的输入、保存和取消,唯一名称仅显示名称,重名时才追加 room-scoped `peerId` 短后缀。一个不持久化的“显示连接详情”复选框按页展开媒体方式、传输协议、候选路径、浏览器实际暴露的本地/远端候选地址、codec、RTT、RTP 丢包率、编解码耗时及逐边统计;地址与端口只从当前页面 `RTCPeerConnection.getStats()` 精确关联的 selected pair 读取,浏览器隐藏或缺失任一字段就不显示,且不进入质量证据、信令、服务端、日志或持久化。真实连接失败、音频缺失、持续画质受限和需要用户动作的告警始终可见。显示名/roster 不进入 access credential 或服务器持久状态。
用户可见的非直播状态使用稳定、真实的阶段词:分享端使用“已停止分享”;观看端使用“等待开始分享”“正在分配线路”“正在建立 P2P”“正在连接备用线路”“正在接收画面”“需要点击播放”“正在恢复连接”或明确失败。阶段只描述当前用户可感知动作,不暴露房间寿命、媒体代次、parent identity 或内部迁移步骤。`room-closed` 显示“房间已关闭”或“房间已过期”,不得误写成“分享已结束”。
@@ -310,7 +307,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
按钮使用 `lucide-react` 图标并提供可访问名称和 tooltip。动态状态区域固定最小尺寸,避免连接状态变化导致布局跳动。320、375 与 390 CSS px 下两个首屏动作仍须同排等宽、文字不溢出且触控高度至少 44 px;展开详情不遮挡视频或引入横向滚动。
-观看端使用原生 `range` 展示 `0%` 至 `100%`,并把归一化值直接写入当前 `<video>.volume`;它不进入 WebRTC sender、信令、房间状态、SQLite 或 `localStorage`。React 页面状态跨 `srcObject` 替换、换父和 ICE 恢复保留;页面刷新后恢复默认值。静音按钮只切换本地 `muted`,并保留上次非零音量;拖到零自动静音,从零调高或直接取消静音时恢复可听状态。该控件不作为音频码率、声道、采样率或来源隔离设置。
+观看端使用原生 `range` 展示 `0%` 至 `100%`,并把归一化值直接写入当前 `<video>.volume`;它不进入 WebRTC sender、信令、房间状态或 `localStorage`。React 页面状态跨 `srcObject` 替换、换父和 ICE 恢复保留;页面刷新后恢复默认值。静音按钮只切换本地 `muted`,并保留上次非零音量;拖到零自动静音,从零调高或直接取消静音时恢复可听状态。该控件不作为音频码率、声道、采样率或来源隔离设置。
## 安全与故障边界
@@ -327,12 +324,12 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
自动测试:
- SiteAccess 的 production 必配、8 至 128 visible-ASCII bytes/独立 secret、local-dev 显式关闭、12 小时签名 cookie、过期、篡改、cookie 属性、已移除 access key fail-fast 和无服务端 session 状态;
-- RoomStore 的随机临时房间、TTL、Host token/Viewer grant 摘要验证、private/public policy、grant 到期/跨房拒绝、rotate/revoke 强撤销、停止分享等待、Viewer 上限和超额拒绝;
-- SQLite 房间库从 `1` 自增、重启恢复、v1/v2 -> v3 单事务迁移、nullable 32-byte grant 与 48-byte password material CHECK、畸形值 fail-closed、rotate/revoke/password 写失败原子性和数据最小化;数据库路径无 site access 时启动失败;
+- RoomStore 的四位空闲码随机分配/释放、活动分享免过期、dormant lease/续租、Host token/Viewer grant 摘要验证、`open/password/disabled` 正交 policy、grant 到期/跨房拒绝、rotate/revoke 强撤销、Viewer 上限和超额拒绝;
+- 进程重启后 room state 全空、旧 Host/grant/password fail closed、释放号码复用时旧 grant 仍失败;`ROOM_LEASE_SECONDS` 的默认/边界与 `MAX_ROOMS <= 9000` 校验,已删除的 `ROOM_DATABASE_PATH`/`ROOM_TTL_SECONDS` fail-fast;
- STUN/TURN UDP URL 严格校验、生产 STUN 必需、server-assisted tuple 完整性/TTL/secret 独立性、issuer HMAC/expiry/opaque tag、当前 route/session/revision/connection generation guard,以及 ordinary peer、未授权房间和 Native 的 STUN-only isolation;LiveKit `sfu-config` 保持独立边界;
- 单一 `screener-v7` 信令 literal、任意旧客户端 mismatch 的一次性刷新终态,以及协议非法 JSON、未知消息、错误方向、跨房间目标和 payload 限制;
- 质量协议的 host 授权、严格字段与数值范围、last-wins、当前/未来 relay、已配置 SFU 和普通 P2P wire 兼容;sender 的四字段 requested/applied 读回、拒绝与持续受限提示;screen audio SDP helper 覆盖 CRLF、existing/missing fmtp、unknown key preservation、幂等、payload number、rejected/non-audio,以及 empty/no-Opus/ambiguous/parser 异常原对象 fallback,`ViewerPeer` 覆盖 initial/restart/rebuild 时同一结果的 local/signaling 一致性,SFU publisher 精确断言 high-quality stereo/forceStereo/DTX 且不覆盖 RED;
-- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 room policy;site-access cookie 不绕过 private grant/password,grant/password 不能建房、取得 Host 或跨房。覆盖 fragment/sessionStorage/replaceState、无 site access 的 public/password code-only 统一拒绝、通过 site access 后的 public/password 进入、不含明文于 URL/浏览器持久存储/SQLite/log、Native capability isolation,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;
+- HTTP/WS 集成:nginx per-source site-access `limit_req` 与统一错误不泄露 secret,应用不建立 IP limiter 状态;Viewer 可在 Origin/容量门下 upgrade;Host 首条鉴权同时要求 upgrade-captured site access 与 Host token,Viewer 要么持 exact-room grant,要么先有 site access 再按 `open/password/disabled`。覆盖原子创建 profile、同浏览器重建偏好、fragment/sessionStorage/replaceState、无 site access 的 code-only 统一拒绝、通过 site access 后的 open/password/disabled 行为、raw grant/密码不进入 URL/日志/服务端持久状态,以及 rotate/revoke 后 grace/route 清理、旧 Viewer/上游媒体边关闭和 reconnect 拒绝;
- 客户端策略与 stats 解析:会话替换不重连,ordinary ICE、LiveKit 与 selected-edge TURN protocol 分离,远端 TURN transport 保持未知;
- route planner property tests:候选输入乱序仍产生相同 list,健康边 sticky,硬过滤拒绝 stale/cycle/effective-capacity/unadmitted parent,优先结果深度和剩余容量并稳定打破平局;失败候选清理后 cursor 前进且总 deadline 不重置;
- Viewer stage reducer:peer/SFU prepare、remote track 无首帧、首个 composited frame、autoplay rejection、恢复和 bounded failure 不互相冒充,动态状态不改变布局或 route authority;
@@ -359,7 +356,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
4. 完成连接恢复和 stats 面板;随后以 STUN-only snapshot 替换旧全房 TURN credential/refresh wire。
5. 在已合入的 endpoint cap/accounting、SFU lifecycle 与 TURN allocation admission 边界上,以单一 `screener-v7` wire 完成 route controller convergence:一个 event-driven reconcile 和一个 room-serial candidate 统一处理 deterministic allocation、child reparent 和 relay drain;该 wave 独立可回滚。
6. 路由边界合入后依次落 live screen-audio ceiling 和 paused video-codec transaction;随后做 H.264 根因诊断与 strict-NAT emulator gate,门禁通过才允许 allowlisted canary。
-7. 加入 first-frame-driven Viewer connection stages。Site access、room-scoped Viewer grant、路由与 SQLite v3 合同保持唯一。
+7. 加入 first-frame-driven Viewer connection stages;随后把房间收敛为四位随机码、易失租约、正交 code/grant access 和本地 Host creation profile,并原子删除 SQLite 双模式。
8. 当前发布只验收 Web Host、Viewer 和 browser relay。Native sender、capture helper 与 shared-encode executable 排在整体 roadmap 最后,不参与当前构建、路由验收或发布。
9. 当前功能、NAT 与真实网络 TODO 完成后,再分别设计和交付公网服务器一键部署包与完全不依赖外部服务的本地 Host-server 包。
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 fb4657d1..9a8f3b6f 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"
@@ -17,37 +17,38 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
### P0 - 必须实现
- 首屏双入口:分享入口通过站点访问后,主工作区必须同等突出“开始分享”和“加入房间”两个主要动作,并用清楚的视觉分隔表达发送与接收;持合法房间 grant 的观看者不需要知道站点访问密码。“加入房间”在当前舞台内就地展开房间码输入并提交,不先跳转到独立页面;直接访问 `/join` 仍提供同一输入能力。不增加营销首页、模式向导或拓扑选择。浏览器标签页使用与现有 `MonitorUp` 品牌语言一致的 favicon。
-- 简单房间:分享者获得纯数字房间码,但房间码只负责定位。现有 `/r/{code}#v={grant}` 合法未过期邀请继续直接进入;仅有 `/r/{code}` 或 `/join` 房间码的 Viewer 必须先通过站点访问验证,再按房间 policy 进入:public-watch 接受房间码,private room 还需正确观看密码。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作,Host 保留复制完整邀请链接;持久房间码从 `1` 开始自增,其他模式继续使用随机临时房间码。
+- 简单房间:分享者从当前空闲池随机获得一个 `1000` 至 `9999` 的四位房间码,房间码只负责定位,不是秘密或永久身份。Host 与 Viewer 标题附近都紧凑、显眼地显示房间号并提供只复制房间号的动作;Host 的主分享动作复制含独立 Viewer grant 的完整邀请链接。新房默认允许已通过站点访问的 Viewer 直接用房间号加入且不设房间密码;Host 可把 code-only 入口改为需要房间密码或完全关闭,不影响 grant 邀请。所有入口只授予该房间 Viewer,不能建房、发布、冒充 Host 或跨房。
- 免安装观看:桌面和手机观看者可直接通过浏览器链接进入、授权并播放,不依赖与分享端相同的桌面客户端。
- 屏幕采集:分享者可主动选择显示器或应用窗口,开始、停止、临时同步暂停音视频和切换分享来源;暂停保留现有连接并禁用当前 capture stream 的全部媒体轨道。服务端按当前分享代次同步这一主动暂停状态,观看端在视频舞台显示“分享者已暂停”,不得从黑帧、track mute 或网络状态推断暂停;晚加入和信令重连使用权威快照,恢复、停止、新分享或会话替换清除旧提示。Host 本地预览必须直接使用 capture stream,支持独立全屏;页面失焦或隐藏时只暂停本地 video element,并明确提示“本地预览已暂停,分享仍在继续”,恢复焦点后继续预览,不得停止 capture、编码或上行。预览不得建立 viewer/媒体边或消耗 TURN、SFU、应用服务器 media egress;预览仍可能产生本地合成、缩放和 GPU 显示成本,不能把隐藏预览称为停止采集或编码。
-- 游戏声音:Windows Chrome/Edge 目标环境可请求系统音频;没有返回音轨时必须明确提示,而不是静默无声。
+- 游戏声音:Windows Chrome/Edge 的初次分享和切换来源都默认请求可用的标签页、窗口或系统音频;浏览器、系统、所选来源或用户没有返回音轨时必须明确提示,而不是静默无声或阻止 video-only 分享。
- 观看端本地音量:播放控制栏提供 `0%` 至 `100%` 音量条和静音按钮,只改变当前浏览器的媒体元素,不修改 Host 音轨、编码、房间状态或其他观看者。切流、换父和 ICE 恢复保留当前页面内的值;刷新后不持久化。静音保留上次非零音量,拖动到非零值自动取消静音。
-- 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 使用同一版本化鉴权 wire,但不发送 presence capability,也不接收 Web roster。
+- 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写服务端持久存储或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native/executable sender 不在当前发布面,也不接收 Web roster。
- 一对多观看:每个房间允许一名 Host 和最多 `20` 名 authenticated Viewer;房间 admission 与端点下游容量、SFU/TURN admission 分别配置,超额加入必须明确拒绝。Production 当前默认 8、显式接受 1 至 16 是部署事实;本轮 route release 把 source hard limit 提升到 20,并以一个 20-Viewer smoke 验收,不从 endpoint cap 推导房间人数。
- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,committed selected TURN 只替换同一份 logical edge 的 transport。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Browser Host 与 Viewer 严格校验该值并用它约束稳态 assignment;并行产生媒体的 candidate 必须持有唯一 `TransitionOverlapSlot`,active+pending 物理 copy 只可达到 `min(C + 1, 3)` 并在 commit/abort 后释放。`C=3` 满载时必须先收到 active bounded-gap retirement 再 prepare,绝不产生第四份 copy。SFU subscriber egress 与 TURN allocation 由独立 server admission 记账。该不兼容能力以 `screener-v7` 原子升级;缺失/非法 cap、旧 wire 与 executable sender都在取得room/route authority前fail closed。
- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。Host 已满且首次需要 SFU 时,同一 reconcile 将 affected Host direct child(若无则稳定顺序中最新的 connected Host direct child)作为本次 child operation,创建唯一 Host publication 并把该 child 变为首个 SFU subscriber,subtree 不动;publication 取代释放的 Host peer slot,下一次扫描再处理原受限 Viewer,不建立 bootstrap 状态机。
-- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入应用页面 URL、日志、浏览器持久化或 SQLite;TURN 凭据和 Screener route grant 不进入任何 URL,LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target。HTTPS/WSS 继续独立使用 TLS/TCP。
+- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入应用页面 URL、日志或服务端持久存储;TURN 凭据和 Screener route grant 不进入任何 URL,LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target。HTTPS/WSS 继续独立使用 TLS/TCP。
- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先使用 pinned LiveKit 的标准两层 screen-share simulcast,让内建 per-subscriber BWE 独立降层和恢复,Screener 不实现媒体层 selector。应用只诊断实际接收层、硬件编码、游戏性能、资源和上传;SFU 自动降层不改变拓扑。`LOW` 停编只是资源优化,active representation/layer 硬上限为二且不随 viewer 增长。当前 Web P2P simulcast 与 Web/LiveKit SVC 不能证明跨 direct/peer 共享编码或可移植硬件路径;全部标准路径失败后才考虑 custom/native dual encode。
- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时现有 periodic stats 在统一 deadline 内没有新 decoded frame 时,使自己的 exact edge 失效并唤醒同一个 reconcile。decoded progress 只保存 route-keyed `lastDecodedAt`,route/connection变化或新帧重置、暂停抑制,同一 edge只报告一次,不增加轮询器。该 operation 把失败的 `parent + transport` tuple 在当前 fact version 直接视为已尝试,先选择其他 direct parent;同一 parent 只有换用另一 transport 时才可在本次继续,新的外部事实才允许原 tuple 重新进入。Track availability、低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer只用于stock WebRTC/LiveKit恢复和诊断。relay自身ingress失效时,它作为child换父并保留subtree;disconnect或effective downstream capacity降低只让direct/overflow children逐个走同一事务。
- 断线恢复:临时网络变化先交给 WebRTC/LiveKit 的 ICE、consent、重连和流状态。Direct edge 可在 exact current parent/child sessions 内采用 framework rebuild 的新 connection ID而不改变topology;selected transport随session变化统一retire。应用只在上述exact edge失效后运行一次有界reconcile;任一步成功即停止。候选耗尽时hard-invalid、confirmed-departed或overflow edge被退休并进入明确waiting,healthy bootstrap edge保留。所有异步结果受authenticated session、share generation、base/pending route revision与candidate connection identity约束,未受影响分支保持sticky。权威暂停abort未提交candidate、保留active graph、抑制stall,并在resume后重新reconcile。
- 可观测性:按目标 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 推断,缺失或被隐私保护时显示未知。
- 渐进式诊断:分享者和观看者默认只看到房间、画面、核心状态和常用控制;Host 的 Viewer 卡片只把本机连接或当前接收证据称为“已连接”,其余状态保持中性的“线路分配中”或具体连接状态,不把 active assignment 当作连接成功。展开连接详情也只在当前媒体证据成立后显示媒体方式:`P2P` 使用绿色与直观图标,`SFU` 使用黄色的 `SFU fallback`;实际 relay 时另标 `TURN`,只有本地 relay protocol 可见时才附加 `/UDP` 等实际值。尚未连接时不预告 P2P、SFU 或未知 ICE,只保留中性状态。Host/Peer 上下游仍只在独立的权威拓扑视图中展示。传输协议、候选路径、RTT、视频/音频 RTP 区间丢包率、实际编解码器、音频区间码率/jitter 和视频编码耗时等技术详情由一个明确的“显示连接详情”开关展开。远端 Viewer evidence 的详情 shell 在同一 viewer/parent/connection/route identity 内保持稳定;非空字段从各自最后一次实际观测起精确保留五秒,`connecting`/`disconnected` 只降为非 fresh,`failed`/`closed`、identity/session/share/route 变化或非单调 sequence 则清空/换代。非 fresh evidence 不得继续证明“已连接”或被其他 current-state 消费者使用。音频 codec MIME、RTP clock、channels 与 fmtp 只能来自当前 RTP 对象引用的 `RTCCodecStats`,缺失即未知;`opus/48000/2` 不得写成 48 kHz 音源或实际立体声。隐藏诊断不能隐藏失败原因、音频缺失、持续画质受限或需要用户操作的告警。
-- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}`、`/join` 和 public-watch 必须先持有效站点 cookie,之后才检查房间 public/private policy 和房间密码。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、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` 可选且必须与 `SITE_ACCESS_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 后才能生成新邀请。
+- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}` 和 `/join` 必须先持有效站点 cookie,之后才检查 `open | password | disabled` code-only policy。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。
+- 房间级观看授权:新房间总是生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端内存只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。code-only 入口独立采用 `open | password | disabled`,默认 `open` 且无房间密码;所有 code-only 尝试先通过站点访问。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可独立 rotate/revoke grant 或改变 code-only policy;授权变化必须先提交新的内存代次,再清除 Viewer grace/路由、终止旧代次信令和媒体并断开受影响 Viewer。
+- 易失房间状态:服务器只在一个有界内存 RoomStore 中保存房间码、租期、Host token/Viewer grant 摘要、code-only policy、可选 48-byte 房间密码校验材料、参与者和控制状态。`ROOM_LEASE_SECONDS` 默认 `86400`;Host 正在分享时不回收,停止分享或 Host 断开后开始 dormant lease,同一 Host token 在期限内重新分享即续租,Viewer 活动不续租,过期后释放号码。应用进程重启时全部房间、租约、邀请和密码状态直接失效;不使用 SQLite、`ROOM_DATABASE_PATH`、schema migration、账号、用户表或服务器 session 表。
+- 本地 Host 偏好:房间所有权继续使用随机 Host token,不使用 IP、UA、硬件信息或浏览器指纹。Host 浏览器在同源 `localStorage` 保存 raw Host token,以及昵称、code-only policy 和可选房间密码组成的创建偏好;服务器只在当前进程内保存 token 摘要和密码 verifier。旧房间不存在时,下一次显式分享创建新房间并原子应用本地偏好,同时生成新的四位房间号、Host token 和 Viewer grant。换设备、换浏览器或清理站点数据即不恢复。
### P1 - 重要功能
-- 公网服务器一键部署包:在用户自有的公网服务器上一键部署当前 Web/信令应用、持久状态和所需 STUN/SFU/TURN/反向代理组件,复用唯一配置、secret、路由、健康检查和回滚合同。它不是托管服务,不能内置真实凭据或跳过域名、TLS、防火墙、端口、容量和备份预检。
+- 公网服务器一键部署包:在用户自有的公网服务器上一键部署当前 Web/信令应用、易失房间状态和所需 STUN/SFU/TURN/反向代理组件,复用唯一配置、secret、路由、健康检查和回滚合同。它不是托管服务,不能内置真实凭据或跳过域名、TLS、防火墙、端口、容量和回滚预检。
- 本地自包含一键包:提供 Windows、macOS 和 Linux 可分发的桌面包,在分享者电脑上同时运行 Host、当前 Web/信令应用服务器和本地状态,朋友继续通过普通浏览器邀请观看。安装后启动不要求源码 checkout、Node 或任何外部 Screener、STUN、SFU、TURN、隧道或 relay 服务;它尽力使用本机可达入口和 direct P2P,但必须明确报告公网入口、可信 HTTPS/WSS、网关映射或 NAT 路径缺失,不能承诺任意 CGNAT/严格防火墙必通。两种分发包都排在当前功能、路由、NAT 和真实网络 TODO 完成之后。
-- 私密房间双入口:private room 接受现有 `/r/{code}#v={grant}` 合法邀请直接进入,或“站点访问 + 房间号 + 该房间观看密码”。没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,通过后才显示明确标为“加入房间”的当前房间密码输入;有效 site-access cookie 直接跳过第一步,但两类密码不得复用、代填或互相替代。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符;异步 scrypt 全局最多执行 2 个、等待 16 个派生。站点口令和房间密码都不得进入 URL/query/storage/log/SQLite;不存在、错误密码、队满和正确密码后的满房都返回通用结果。
+- 独立房间入口:合法 `/r/{code}#v={grant}` 邀请直接进入对应房间;没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,再按房间 `open | password | disabled` policy 直接进入、要求房间密码或中性拒绝。有效 site-access cookie 只跳过第一步,两类密码不得复用或互相替代。Host 可设置、轮换或移除房间观看密码;密码接受 1 至 64 个可见 ASCII 字符,异步 scrypt 全局最多执行 2 个、等待 16 个派生。Host 可把房间密码保存在同源本地创建偏好中;它不得进入 URL、cookie、日志或服务端持久存储。不存在、错误密码、队满和正确密码后的满房都返回通用结果。
- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,每个房间使用一个服务端 route controller,独占 committed graph、一个 pending child operation 和 event-driven reconcile。运行时只增加一个串行pump、一个operation deadline timer与typed resource lifecycle task,不维护另一份graph。operation持有candidate tuple list/cursor、一个current candidate/资源预留、fact version和一个总deadline。committed graph必须无环、source-reachable,且每名Viewer同时至多一个active upstream。加入、容量变化、节点离开、exact edge `failed/closed`,以及非暂停decoded-frame stall都只唤醒同一个reconcile;其余健康分支保持sticky。候选按当前身份、source reachability、无环、effective capacity与sender transition硬过滤,再按结果深度、剩余sender slots、稳定加入顺序和peer identity排序;server admission在执行当前cursor时独立reserve。candidate child首帧ready触发`settleReady(commitAdmissionSync)`,成功prepare `P`提交active `P`;失败释放资源并用同一monotonic allocator广播`R>P` rollback,cursor推进但总deadline不重置。bounded-gap先preflight server resource,再retire producer、按新graph重算未尝试suffix,并在切断healthy edge时追加一个普通restore candidate。relay自身ingress失效时作为child换父并保留subtree;relay disconnect/cap降低让overflow children逐个走同一事务,childless后删除。房间admission和无环约束最大深度,不设独立hard cap。普通peer始终STUN-only,SFU/TURN使用独立admission。
- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。
- 质量控制扩展:推荐档位仍是默认入口;“分享高级设置”只允许 720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位和音频档位在直播中显式应用;音频变更只更新固定 Opus 路径的 sender ceiling,不是 codec 切换。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 都读取最新 desired 档位,并各自在 fresh sender parameters 上应用和读回 endpoint-local applied 值;实际码率仍由浏览器拥塞控制和 stats 决定。Peer 只在唯一明确的 active Opus audio 上做结构化、幂等的 Viewer answer `stereo=1;maxaveragebitrate=256000` 变换,使同一接收上限覆盖三档;非目标形态或 parser/writer 异常必须原样保留浏览器 answer,不得阻断可继续的 mono/video edge。不得用宽泛字符串/正则改 SDP,也不得改写浏览器协商的 FEC。SFU 将三档映射到 pinned SDK 的 music stereo preset 或显式 256 kbps ceiling,统一保留 `forceStereo = true`、`dtx = false` 与 pinned room default `red = true`。不得暴露任意码率、声道、采样率、audio codec、stereo、DTX、RED 或 FEC 控件;256 kbps 只是显式较高上限,不是无损、高保真或最低码率保证。实际质量持续低于所选上限时必须显示可解释的限制原因;在真实拥塞、编码器和接收端证据完成前,不把任一组合称为“完美平衡”。未来 microphone voice 若进入范围,必须是独立 track/处理链,不能把 AEC/降噪/DTX 套到电影或游戏音频。
- SFU 质量设置生命周期:直播中修改档位时,浏览器 sender 的 applied readback、LiveKit `LocalVideoTrack` 保存的 degradation preference、track restart options 与 `LocalTrackPublication` 的 republish options 必须作为同一次串行操作更新;任一步失败恢复旧 sender 与旧 SDK 保存态,旧 publication generation 不得回写当前状态。LiveKit full reconnect/republish 不得恢复初次发布的旧偏好。该修复不改变 codec、码率上限、层数或路由,也不能单独解释即时低帧。
- 本地预览性能候选:在相同动态场景中 A/B 测量 Host 动态预览开/关的 CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不受影响时,才允许直播开始后默认显示静止缩略图或隐藏动态预览并提供按需展开;未测前不宣称收益。
-- Peer-assisted 媒体路径:所有非服务器 endpoint 都受同一个服务端权威稳态 outbound media-copy capacity 约束,默认 `2` 且可静态配置为 `1`、`2` 或 `3`;peer child 与 Host publication 都按实际发送副本计数。每名 Viewer 任一时刻只有一个 active upstream,活动媒体图保持无环;只在离散事件中做有界分配或换父。浏览器把收到的标准 remote track 加入独立下游 `RTCPeerConnection` 时会逐跳解码并分别重编码,必须测量而不能称为 shared encode。服务端只在有界房间内存中保存严格校验的质量设置,不写入 SQLite。
+- Peer-assisted 媒体路径:所有非服务器 endpoint 都受同一个服务端权威稳态 outbound media-copy capacity 约束,默认 `2` 且可静态配置为 `1`、`2` 或 `3`;peer child 与 Host publication 都按实际发送副本计数。每名 Viewer 任一时刻只有一个 active upstream,活动媒体图保持无环;只在离散事件中做有界分配或换父。浏览器把收到的标准 remote track 加入独立下游 `RTCPeerConnection` 时会逐跳解码并分别重编码,必须测量而不能称为 shared encode。服务端只在有界房间内存中保存严格校验的质量设置,不写入持久存储。
- 原生 shared encode 分享端:后续独立的 Electron/原生分享端必须让每个 active representation 只产生一份兼容编码结果,并在 direct、peer 与 SFU transport 间复用;健康路径选择共享 `HIGH`,最多另有一份弱路径共用的 `LOW`,是否常驻由硬件、游戏和上传门槛决定。每条连接仍保留独立 WebRTC packetization、SSRC、pacing、加密和反馈,且各自消耗上传带宽。浏览器不保证跨 `RTCPeerConnection` 复用编码器,因此当前 Web spike 不能宣称满足该保证。
- 原生 shared encode relay:具备原生 relay 能力的非服务器端点同样受统一服务端权威下游容量约束,并应复用兼容编码输出而不再次编码。当前普通浏览器 relay 使用逐边重编码的标准 WebRTC 路径,不伪称 shared encode。
- SVC 重开条件:当前标准 Web/LiveKit SVC 已静态拒绝为 `no-go-web-svc-cross-path-hardware-contract`。sender `scalabilityMode` 没有 direct/peer receiver 对应的按层选择或跨 PeerConnection shared-encode 契约;requested/applied mode、Media Capabilities `powerEfficient` 和 RTCStats encoder 字段也不能证明没有静默软件 fallback。Pinned client 2.22.0 还会把 screen-share SVC 覆盖为三层 temporal-only `L1T3`,不满足低分辨率 base 与最多两层。只有未来 native sender 能明确选择硬件编码器、最多发布两层、将同一编码输出复用于 direct/peer/SFU、保持每条路径独立选择并通过真实游戏和亚秒延迟门槛时,才可用新的 capability decision 重开 SVC;不能把浏览器 API 支持或 UA 推断当成采用理由。
@@ -55,7 +56,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- SFU/TURN 中央兜底:产品部署可以提供有界 SFU 与可选 TURN 资源,但不要求用户选模式,也不得默认变成整房 always-SFU。只有 Host 拥有一个 authoritative publication;SFU-fed 与 peer-fed endpoint 使用同一个 provisional-child first-frame transaction,严格受限 endpoint 在没有成功 child candidate 时自然保持 leaf。TURN 是某条授权 logical edge 或 Host-SFU ingress 的 selected transport,不是拓扑节点。启用 LiveKit fallback 时必须使用专用且关闭 `room.auto_create` 的实例,并显式提供私有 `LIVEKIT_API_URL`、无默认值的正整数 `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`。单进程全局账本按 exact room/share/publication 保存一份 Host publication ingress,并在该 generation 下按 exact Viewer 保存 subscription egress;当前 publication 被后续 SFU Viewer 复用,每个 child candidate 只 reserve/commit 自己的 subscription。一份 publication 占一个 ingress,每份 reserved、committed 或 draining subscription 占一个 egress;离开 route 的 subscription 在整个 publication room 删除并确认 absent 前仍作为 draining 计费,同一 Viewer handle 再次启用不重复计数。新 generation 在发 token 前 reserve publication 与首个 subscription,并先通过 RoomService 创建对应 room;first-frame ready同步commit admission后才promote graph。publication replacement、abort、timeout、disconnect、share rollover、room stop/delete按资源差集或controller `dispose()`进入draining,只有DeleteRoom成功和absent readback才释放该generation的ingress/egress。启动时必须先拒绝外来room、清除全部遗留Screener room并确认namespace为空;Host信令离线但LiveKit participant仍存在时继续保留和计费,participant消失后有界回收。实际因deployment-wide admission失败的房间只进入一个waiter Set;TURN usage释放或LiveKit drain完成时一次性touch这些controller的external fact并走普通reconcile,不轮询。固定root数和普通endpoint child数不能代替准入;资源耗尽进入下一candidate、明确waiting或failure。多应用进程部署必须先引入共享原子owner。
- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。
- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。
-- 受限网络增强:短期鉴权 TURN 只有在完整、默认关闭的部署配置和当前 route controller 明确授权时可用;普通 peer PC 从创建起保持 STUN-only,不得向整个 participant、房间或所有 peer connections 预发 TURN candidates。凭据必须绑定 exact room/share/session/route/connection generation,短期有效、内存态、受配额约束且不进入 URL、日志、浏览器持久化或 SQLite。TURN 只替换授权 edge 的 transport;Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。TURN 不得被描述为更高清的传输方式。
+- 受限网络增强:短期鉴权 TURN 只有在完整、默认关闭的部署配置和当前 route controller 明确授权时可用;普通 peer PC 从创建起保持 STUN-only,不得向整个 participant、房间或所有 peer connections 预发 TURN candidates。凭据必须绑定 exact room/share/session/route/connection generation,短期有效、内存态、受配额约束且不进入 URL、日志、浏览器持久化或服务端持久存储。TURN 只替换授权 edge 的 transport;Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。TURN 不得被描述为更高清的传输方式。
- Web 编码选择:分享高级设置提供 `自动 | H.264 | VP8`,默认自动使用浏览器/LiveKit 协商;首次分享前直接应用,分享中只在 Host 已显式暂停后允许切换。暂停切换与 route mutation 串行,使用 generation-fenced P2P/relay 重协商和 SFU republish;恢复播放后才以实际 codec 与 decoded-frame progress 验证,失败重新暂停并有界回滚。P2P/浏览器 relay 保留完整 repair 与其他 codec 回退列表,SFU 保持 `backupCodec = false`,不维护第二套应用编码链。实际 codec/profile、encoder implementation 与 stats 是结果真相;H.264 可选不等于浏览器必走硬编,AV1 仍不得仅凭压缩率推断默认启用。
### P2 - 可选功能
@@ -71,7 +72,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 启播:观看者请求观看后,除用户授权耗时外,3 秒内出现首帧;从请求开始到首帧期间持续显示真实、稳定且可访问的连接阶段,不用黑屏、`playing` 事件或 ICE `connected` 冒充已播放。
- 流畅性:选择 60 fps 档位时,不能在没有降档或提示的情况下连续 5 秒低于 50 个解码帧每秒。
- 成本:direct/peer UDP 不经过应用服务器。SFU/TURN 的 ingress、egress、allocation 和并发上限由整体路由模型明确配置;验收逐 hop 记录 Host、peer、SFU、TURN 和供应商计费的真实 bytes,不得用普通端点 child 数或有效载荷近似代替中央资源准入。
-- 安全:应用控制面全程 HTTPS/WSS;site access、Host token 与 room-scoped Viewer grant 权限正交,任何一个 Viewer grant 只授予一个房间的观看角色。P2P/TURN 边在 WebRTC 端点间使用 DTLS-SRTP,普通 SFU 是逐跳 DTLS-SRTP;只有另行实现并验收应用层 E2EE 才能对 SFU operator 保持媒体端到端机密。仓库、数据库、日志和错误不得包含明文密码或 grant。已鉴权 Host 与 shipped clients 是当前私密房间中的可信媒体参与者;越权房间、角色和未授权 subscription 必须拒绝。旧 generation 不得重新取得 route authority,并在有界 drain 后由 exact-room 删除阻止再次加入。
+- 安全:应用控制面全程 HTTPS/WSS;site access、Host token 与 room-scoped Viewer grant 权限正交,任何一个 Viewer grant 只授予一个房间的观看角色。P2P/TURN 边在 WebRTC 端点间使用 DTLS-SRTP,普通 SFU 是逐跳 DTLS-SRTP;只有另行实现并验收应用层 E2EE 才能对 SFU operator 保持媒体端到端机密。仓库、服务端持久存储、日志和错误不得包含明文密码或 grant。已鉴权 Host 与 shipped clients 是当前私密房间中的可信媒体参与者;越权房间、角色和未授权 subscription 必须拒绝。旧 generation 不得重新取得 route authority,并在有界 drain 后由 exact-room 删除阻止再次加入。
- 隐私:P2P 会向房间内好友暴露网络地址,首版威胁模型仅覆盖可信熟人;若要求隐藏 IP,必须切换为服务器转发。
- 可维护性:代码、需求、调研、项目记忆、`AGENTS.md` 和 `.codex/` 均在 Git 中跟踪;开发配置不得依赖单一操作系统的绝对路径。
- 迁移完整性:项目拥有者明确宣布公开发布前,只维护当前内部产品合同,不承担 backward/forward compatibility。客户端、服务端和部署配置按同一 release 原子迁移;旧客户端在 authority 前拒绝,替代后立即删除旧配置、wire、parser、双写、translator、deprecated alias、migration shim 与仅服务旧版本的测试,不保留第二套架构。Git 历史承担旧实现追溯;公开发布后才按明确的新要求重新评估兼容策略。
@@ -81,8 +82,8 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
## 边界与约束
- 首版不包含远程键鼠控制、公开/大规模直播、录制、社区系统或完整语音聊天;大规模分享直接使用现有直播服务。
-- public-watch 只省略房间级 grant/password,不省略站点访问;房间码只定位,不提供隐私保证、目录或防转发承诺。现有每房 Viewer 上限、全局/未鉴权连接上限、房间上限和中央 egress/admission cap 仍适用,public-watch 不能创建无界服务器 fanout。
-- SQLite 只用于持久房间身份与最小授权材料:房间 ID、Host token 摘要、nullable Viewer grant 摘要和 nullable 48-byte Viewer-password salt+verifier。不得保存 site access 密码、房间观看密码、token/grant 明文、cookie、显示名、成员、`clientId`、`peerId`、SDP、ICE candidate、IP 地址、媒体或 TURN 凭据;首版仍是单进程、单实例控制面。
+- `open` code-only 入口只省略房间密码,不省略站点访问;四位房间码只定位,不提供隐私保证、目录或防转发承诺。现有每房 Viewer 上限、全局/未鉴权连接上限、房间上限和中央 egress/admission cap 仍适用,任何访问方式都不能创建无界服务器 fanout。
+- 房间控制面是单进程、单实例、易失内存状态;不得持久保存房间身份、租约、Host/Viewer credential、房间密码 verifier、成员、`clientId`、`peerId`、SDP、ICE candidate、IP 地址、媒体或 TURN 凭据。进程重启是明确的全部房间失效边界,而不是恢复或迁移事件。
- 20-Viewer admission 是产品边界,不承诺任意机器、档位、网络或跨洲路径都达到相同画质;endpoint cap、SFU/TURN admission 和明确 wait/failure 继续保护资源。
- 浏览器规范要求每次由用户主动选择分享源,权限不能永久保存;纯网页不能保证指定游戏窗口或始终获得系统音频。
- 1080p60 是能力目标,实际分辨率、帧率和硬件编码由浏览器、GPU、驱动、画面复杂度及网络共同决定。
@@ -93,18 +94,17 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
### 房间模式与生命周期
-- Given `SITE_ACCESS_PASSWORD` 和 `ROOM_DATABASE_PATH` 都已配置,When 连续创建房间并重启应用,Then 房间码从 `1` 开始单调递增,Host ownership 可恢复,且 SQLite 的应用数据只包含房间 ID、Host token 摘要、nullable Viewer grant 摘要和 nullable Viewer password verifier material。
-- Given 持久房间正在分享,When 分享者明确停止或捕获轨结束,Then 房间和链接保持有效,分享端显示“已停止分享”,观看者显示“等待开始分享”;分享者重新发布后可继续在同一房间观看。
+- Given 当前空闲房间码池,When 连续创建房间,Then 每间房从 `1000..9999` 的未占用集合随机取得一个四位码,不重复活动号码,`MAX_ROOMS` 不超过 9000 且默认 1000;释放房间后号码返回同一空闲池。
+- Given Host 正在分享,When `ROOM_LEASE_SECONDS` 到达,Then 活动房间不被回收。Given 分享者明确停止、捕获轨结束或 Host 断开,When 同一 Host token 在默认 86400 秒内重新分享,Then 同一进程内恢复原房间并重新续租;超过期限则关闭房间、释放号码并拒绝旧 Host token、grant 和房间密码。
- Given 分享期间只有 host 信令短暂断开,When 现有 P2P 媒体仍健康,Then 客户端继续播放媒体并恢复信令,而不是错误显示“已停止分享”。
-- Given 应用以 production 模式启动但 `SITE_ACCESS_PASSWORD` 缺失、`ROOM_DATABASE_PATH` 已配置但该密码为空,或原子迁移后的配置仍提供已删除的 `ACCESS_PASSWORD`,When 应用启动,Then 配置校验明确失败,而不是兼容旧 gate 或公开建房。
+- Given 应用以 production 模式启动但 `SITE_ACCESS_PASSWORD` 缺失,或配置仍提供已删除的 `ACCESS_PASSWORD`、`ROOM_DATABASE_PATH`、`ROOM_TTL_SECONDS`,When 应用启动,Then 配置校验明确失败,而不是兼容旧 gate、旧持久化模式或公开建房。
- Given production site access 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 无论是否启用 site access 都使用随机临时房间码并遵守 `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 只有 site access 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 切回私密时签发新 grant 并撤销现有 code-only Viewer。
-- Given private room 配置了观看密码,When Viewer 仅以房间号访问,Then 先显示“站点访问 / 站点口令”,通过后才显示“加入房间 / 房间密码”;已有有效 site-access cookie 不重复提示站点口令,正确房间密码只鉴权当前 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 服务端返回邀请并由 Host/Viewer 客户端读取,Then grant 含 256-bit 随机量、只授权该房间 Viewer、只在该页面会话的 room-scoped `sessionStorage` 留存,并在首次读取后从地址栏移除;HTTP request-target、WebSocket URL、Referrer、cookie、`localStorage`、服务端持久存储、日志和错误均不包含 grant。
+- Given 默认新房,When 已通过站点访问的 Viewer 只输入四位房间码,Then 无房间密码即可在现有 Viewer/连接/egress 上限内加入,同时 Host 的主分享动作仍复制独立的 token-bearing link。Given code-only policy 为 `password` 或 `disabled`,Then 分别要求正确房间密码或中性拒绝;grant 路径保持独立。
+- Given Viewer 只有 site access cookie、另一个房间的 grant、缺失/过期 grant 且 code-only policy 不允许,或自行把 role 改为 Host,When 首条信令鉴权到达,Then 返回同一通用无效结果且不泄露房间存在性;不能建房、发布、跨房或绕过 Host token。
+- Given Host rotate/revoke Viewer grant,When 新内存摘要和 authorization generation 提交,Then 服务端清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 返回一次新 grant,revoke 锁定 grant 路径,code-only policy 保持独立。
+- Given Host 同源本地偏好保存了 `open | password | disabled` 和可选房间密码,When 服务器重启后该 Host 下一次显式开始分享,Then 客户端清除失效 ownership、创建新四位房间并原子重放偏好;新的 Host token 和 grant 替换旧值。Given 换浏览器、换设备或清理站点数据,Then 不恢复这些偏好或所有权。
+- Given 应用进程重启,When 旧 Host、Viewer 或 code-only 链接再次访问,Then 所有旧房间、租约、摘要、密码 verifier 和参与者均已丢弃并 fail closed;运行时不读取数据库、迁移旧 schema 或恢复旧号码。
- Given 部署切换了不兼容的当前协议,When 仍打开的旧页面连接新服务端,Then 单一 release/protocol mismatch 边界终止该 session、停止自动重连并明确提示刷新;不得通过旧 parser、双写或双协议继续假连接。
### P2P、SFU 与可选 TURN 兜底
@@ -125,14 +125,14 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- Given 用户在普通手机浏览器尝试成为 Host,When `navigator.mediaDevices.getDisplayMedia` 缺失,Then 页面在创建发布路径前明确显示该浏览器不支持移动端屏幕分享,并保留加入房间入口。Given API 存在但真实调用失败,When 失败原因是拒绝/取消或其他 capture error,Then 分别显示对应状态而不是一律重标为不支持;判断使用运行时能力/结果而不是 UA、平台或设备型号,也不能把移动 Viewer 支持宣传成移动 Web Host 支持。
- Given 观看者调节音量或静音,When 媒体切流、换父或恢复连接,Then 当前页面的本地播放音量保持不变,其他观看者和发送端不受影响;刷新页面后恢复默认音量,不产生信令、持久化或媒体重协商。
- Given Viewer 已通过浏览器要求的用户手势开始可听播放,When 页面切到后台且浏览器仍保留该页面,Then 同一个媒体元素、信令和 WebRTC 连接继续承载音频,返回前台后沿当前直播恢复画面而无需重新加入;后台视频合成或逐帧回调增长不作为连续播放承诺。Given iOS 锁屏、系统回收页面或后台期间产生新的媒体连接,Then 以当前真机行为为准,恢复时继续使用已有重连和显式播放入口。
-- Given 用户查看本机身份,When 尚未进入编辑状态,Then 界面显示“昵称”、当前昵称和紧贴其后的铅笔按钮,不显示默认可编辑输入框。Given 用户修改昵称后以 Host 或 Viewer 加入房间,Then 所有在线参与者看到同一份服务端权威 roster、对应房间标题;唯一名称只显示名称,重名项追加当前房间 `peerId` 短后缀。刷新后本机名称仍在,清除站点数据后恢复未命名默认值,数据库中不存在显示名或成员记录,展示身份不参与授权或路由。
+- Given 用户查看本机身份,When 尚未进入编辑状态,Then 界面显示“昵称”、当前昵称和紧贴其后的铅笔按钮,不显示默认可编辑输入框。Given 用户修改昵称后以 Host 或 Viewer 加入房间,Then 所有在线参与者看到同一份服务端权威 roster、对应房间标题;唯一名称只显示名称,重名项追加当前房间 `peerId` 短后缀。刷新后本机名称仍在,清除站点数据后恢复未命名默认值,服务器不存在显示名或成员的持久记录,展示身份不参与授权或路由。
- Given 手机从 Wi-Fi 切换到蜂窝网络或页面从后台恢复,When 原候选对失效,Then 客户端执行 ICE restart 或重建连接,并显示恢复进度而不是永久黑屏。
- Given Viewer 已鉴权但尚未提交首帧,When route 从 peer prepare 进入 SFU fallback 或等待媒体,Then 固定舞台依次显示当前真实阶段且不跳动、不显示虚假百分比;只有当前代 video frame 被 compositor 接收后才显示正在播放。Given `video.play()` 仅因 autoplay policy 被拒绝,Then 稳定显示一个播放动作;连接尚未完成时不显示忽隐忽现的播放按钮。Given 旧媒体仍可见且正在 MBB 恢复,Then 保留旧画面并叠加恢复状态。
- Given Viewer 尝试把直播输出到电视,When 浏览器/系统提供已验证的 Remote Playback、AirPlay 或屏幕镜像能力,Then 该动作只改变本机输出设备,现有 upstream PeerConnection、TURN/SFU/peer route 和其他参与者保持不变。Given live `srcObject` 未经目标设备证明或 API 缺失,Then 产品不显示伪可用 Cast/AirPlay 按钮,也不创建自有 receiver 或转码服务器。
### 一对多与带宽保护
-- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Host 或任一 Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,committed selected TURN 不重复计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,Native Host 不用 `maxViewers` 或本地常量代替它,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。When 此能力合同上线,Then client/server/native wire 同一 release 原子升级,缺失或越界的 `C` 与旧 wire 都在房间授权前得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token/grant 前明确等待或失败。
+- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Browser Host 或任一 Browser Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,committed selected TURN 不重复计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。When 此能力合同上线,Then server 与 Browser assets 在同一 `screener-v7` release 原子升级,缺失或越界的 `C`、旧 wire 与 executable sender 都在房间授权前得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token/grant 前明确等待或失败。
- Given peer-assisted 路径分别运行 1、5、10、20 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。
- Given 一名分享者和 20 名观看者,When 运行 bounded browser smoke,Then 全部 Viewer 取得明确媒体或 bounded wait/failure,非服务器端点不超过 `C`,并记录 route depth、首帧时间、实际 sender 数、应用服务器 CPU/内存以及 SFU/TURN 用量。该 smoke 验证 admission、控制面效能和资源上界,不单独证明任意公网画质或 30 分钟 endurance。
- Given candidate 改变房间 admission 默认值或上限,When 在目标数量与代表性路径上运行规定时长并注入 relay departure、重连和一个弱路径,Then 每名观看者持续解码、每个非服务器端点不超过配置容量、深度与故障半径有界、未受影响 subtree 不迁移,并记录端点与中央服务的 CPU、GPU、内存、上行、出口、帧率、丢包率、冻结和恢复;任一门槛失败时不得切换默认值。