Hosted viewer service
The hosted viewer service gives an owner browser access to a cloud copy of My Work. It authenticates the owner at the edge, limits which worker actions can cross the public boundary, and records small viewer-use events without exposing the owner's memory or identity to the analytics system.
Service boundary
Hosted viewer replica
The hosted viewer runs one worker replica for one owner. The replica pulls the owner's synced records and serves the same work-view experience as a local worker. It does not capture new sessions or run work-view refresh jobs by default, so the owner's devices remain the source of new work data.
The gate is the only public path to the replica. It keeps the worker on loopback and forwards approved browser requests to it as local requests. This design keeps sync credentials and machine controls out of the browser.
flowchart LR
A[Owner browser] --> B[Hosted viewer gate]
B -->|approved request| C[Owner's cloud worker]
C --> D[Synced My Work records]
B --> E[Hosted viewer usage]
E --> F[PostHog]
References: services/…/index.ts• L1-21 services/…/index.ts• L41-59 services/…/index.ts• L78-93
Access control
Sign-in links and session cookies
The sign-in service creates a short-lived link token for the signed-in owner. The viewer accepts that token only once at /auth, checks that its owner matches the configured viewer owner, and exchanges it for a longer-lived HttpOnly session cookie. The browser does not keep using the link token after this exchange.
The link and session use separate token audiences. A token with the wrong audience, owner, signature, or expiry is rejected. This prevents a link from being reused as a session or used to open another owner's viewer.
References: services/…/token.ts• L1-19 services/…/token.ts• L27-44 services/…/gate.ts• L22-24 services/…/gate.ts• L124-161
Request gate
The gate requires a valid owner session before it serves the viewer or forwards an API request. A browser page without a session goes to the sign-in page; a non-HTML API request receives an unauthorized response instead.
After authentication, the gate applies a method and path policy. It permits work-view reads, blocks machine settings and maintenance paths, and permits only the My Work actions that save review, focus, rule, suggestion, completion, or usage state. Other writes stay on the owner's computer.
References: services/…/gate.ts• L25-38 services/…/gate.ts• L108-116 services/…/gate.ts• L169-207
Browser request origin
The gate protects state-changing requests from cross-site use. A write must carry the public viewer origin and must not be marked as a cross-site fetch. The gate then removes browser cookies, proxy headers, and public origin data before it sends the request to the loopback worker.
This creates two separate checks: the gate proves that the browser may act for the owner, and the worker receives a local request that cannot inherit the browser's network identity. Response cookies from the worker do not pass back to the browser.
References: services/…/gate.ts• L40-49 services/…/gate.ts• L203-243 services/…/gate.test.ts• L149-212
Hosted work-view access
Shared focus pages
The hosted viewer is the browser-facing side of a shared focus page. The local worker publishes a filtered snapshot for an eligible kept or done focus area, and a background publisher keeps that page current even when My Work is not open. The hosted service controls who can open the resulting experience and which My Work changes can be saved from it.
The page therefore shows shared work state rather than the owner's raw memory. The publisher removes owner prompts, evidence, conversations, products, and machine names before the snapshot reaches the hosted page. It sends only changed page content, and it stops a link when its area is no longer shareable. See TeamBrain and work-view for the work-view model and Work-view experience for the browser experience.
References: src/…/focus-share-publisher.ts• L1-16 src/…/focus-share-publisher.ts• L61-99 src/…/focus-share-publisher.ts• L102-161 src/…/to-shared-focus.ts• L67-112 src/…/focus-share.ts• L1-9 src/…/focus-share.ts• L72-127
Worker availability
The public health endpoint reports that the hosted service is up while separately describing whether its worker is ready, busy, or down. It does not require an owner session and does not wait for a long worker operation. If the worker is unavailable, an authenticated page request receives a short starting response while the host process restarts the worker.
References: services/…/gate.ts• L136-149 services/…/gate.ts• L219-235 services/…/index.ts• L63-73
Usage accounting
Viewer event reports
The hosted page sends a page view when the document opens, then reports the page that opens or the page that the person switches to. The report contains only a closed page name and, for a switch, the previous page name. Reopening the same page is not counted as a switch, and one document open is sent only once.
The hosted gate accepts only page view, open, and switch reports for known My Work pages. It converts them to the hosted viewer's PostHog events and answers the browser without sending them to the worker. Analytics failure does not block the work view, and the page does not retry a failed ingest.
References: src/…/usage.ts• L6-16 src/…/usage.ts• L31-62 services/…/gate.ts• L174-196 services/…/usage.ts• L55-81
Anonymous measurement
Hosted usage uses a random browser identifier stored in an HttpOnly cookie. It does not use the cmem account ID, create a person profile, run a browser analytics SDK, record sessions, or collect page content. The host marks events as hosted and includes the viewer hostname so hosted activity remains distinct from local worker telemetry.
References: services/…/usage.ts• L1-18 services/…/usage.ts• L37-41 services/…/usage.ts• L84-103 services/…/usage.test.ts• L23-39
Related systems
The hosted viewer depends on the work-view projection and the shared-page publisher, but it does not create the work data that it displays. Read TeamBrain workflows for the surrounding TeamBrain actions and Work-view experience for the local and hosted browser flows.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the link-token format and audience checks aligned with the service that mints sign-in links.
- Keep the configured owner identity aligned with the synced worker identity. A mismatch must not expose another owner's records.
- Keep the public path allowlist aligned with the My Work actions that are safe to sync back. New worker writes must not become public by default.
- Keep browser-origin checks separate from loopback worker headers. Public cookies and proxy identity must not reach the worker.
- Keep the shared-page shape aligned between the local publisher and the hosted page. A page must remain free of owner evidence and machine data.
- Keep periodic publishing aligned with share state. A stopped link must not be recreated by a late update, and an area that is no longer eligible must lose its link.
- Keep the hosted event allowlist and page-name set aligned with the viewer's usage sender.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A link token is reused or has the wrong owner | The viewer refuses the exchange and sends the person back to sign-in | Signed audience and owner checks plus one-use link tracking |
| A browser sends a state-changing request from another origin | A work-state change could be made through a cross-site request | Public-origin and cross-site checks at the gate |
| A new worker write is not added to the gate allowlist | The hosted viewer cannot save that action, or a broad policy change could expose machine state | Explicit read and write path policy |
| The worker is down or busy during a page request | The owner sees a bounded starting response instead of a hung proxy request | Separate health check and worker restart path |
| The local work view cannot be read during a share update | The hosted page keeps its last good snapshot instead of receiving a partial update | Publisher read-health check and per-area error state |
| An area is merged, dismissed, or returned to suggestions | Its old public link could remain available after the area is no longer shareable | Eligibility check plus a fresh read before stopping the link |
| A stop races with a periodic publish | A stopped link could be recreated or an old update could replace a newer share | Per-area request ordering and update-only periodic publishing |
| Hosted usage ingest fails | Viewer analytics lose that event, but the work page still loads | Best-effort ingest and a successful empty response |
Key files
| File | Why to read it |
|---|---|
| services/…/index.ts | Shows the hosted process boundary and the one-owner worker relationship. |
| services/…/gate.ts | Defines authentication, request policy, origin checks, and proxy behavior. |
| services/…/token.ts | Defines the shared link and session token contract. |
| services/…/usage.ts | Defines the hosted usage event contract and anonymous measurement. |
| src/…/focus-share-publisher.ts | Keeps eligible shared pages current and stops links that no longer match the owner's work view. |
| src/…/usage.ts | Shows which browser events the hosted page sends and when it sends them. |
| src/…/to-shared-focus.ts | Shows the safe shape of a shared focus page before hosting. |
| src/…/focus-share.ts | Shows how local work state becomes a hosted shared page and how sharing stops. |