@gotcos/glasses-server 6.41.0 → 6.42.1

package/.env.example

@@ -14,9 +14,27 @@ BIND_HOST=0.0.0.0
 # PORT=3141
 
 # ── AUTH ────────────────────────────────────────────────────────────────
-# A token is REQUIRED on every /api call. Leave UNSET and the server prints an
-# auto-generated one at boot — paste it into the phone app. Set a fixed value
-# here for a stable token across restarts.
+# A token is required on every /api call EXCEPT six paths. Four are public because
+# a client needs them BEFORE it holds a usable token; two are capability URLs
+# because the browser API that fetches them cannot send a header at all:
+#
+#   GET  /api/health          server availability and capability advertisement
+#   GET  /api/diag/health     recovery diagnostics
+#   POST /api/diag/client     client-side crash/diagnostic upload
+#   GET  /api/display-stream  the glasses display bus. EventSource cannot set
+#                             headers, so this returns 200 to anyone — but a
+#                             subscriber without a token gets a live transport and
+#                             lifecycle markers ONLY, never transcripts or answers.
+#   GET  /api/display-stream/<expiry>.<hmac>   short-lived capability URLs, each
+#   GET  /api/tts/play/<uuid>                  minted by an AUTHENTICATED call, for
+#                             EventSource and for native audio players respectively
+#                             — neither can send a header. On the display stream the
+#                             X-Cos-Token header is accepted as an equivalent, so any
+#                             caller that CAN send one should; the TTS UUID also names
+#                             which audio to play, so it is not interchangeable.
+#
+# Leave UNSET and the server prints an auto-generated token at boot — paste it into
+# the phone app. Set a fixed value here for a stable token across restarts.
 # COS_API_TOKEN=pick-any-long-random-string
 
 # Optional durable image-store location. Defaults to

package/CHANGELOG.md

@@ -1,3 +1,121 @@
+## 6.42.1
+
+Hardening of the 6.42.0 display-stream ticket, from a four-validator QA pass
+that tested the FIX rather than the original finding. Nothing here changes the
+wire contract; every 6.42.0 client keeps working unchanged.
+
+- **A refused ticket now says why.** `explainDisplayTicket` returns
+  `expired | bad-signature | malformed`, and the throttled summary line counts
+  each. Before this the server could not tell "a client needs to re-mint"
+  (expired — expected after every native EventSource retry on a stale URL) from
+  "someone holds a ticket this token never signed". The author's own log had
+  seven unexplained rejections in three windows.
+- **The allowlist uses `Object.hasOwn`.** The projection map is an object
+  literal and inherited `Object.prototype`; a type of `constructor` would have
+  resolved to a truthy identity and passed the event through whole. Unreachable
+  via the typed union; the allowlist must not depend on that.
+- **Ticketless connects no longer materialise the replay buffer.** Gap detection
+  still runs; the up-to-200-event filter does not. A stale install retrying
+  every 3s was doing that filter and discarding it each time.
+- **`?probe=1` skips the replay write.** The client's connection probe is
+  authorized (it sends the token) and was handed the whole buffer on every
+  reconnect, then aborted the socket — 1,164 "Replayed 200" lines in one day.
+  A 6.42.0 server ignores the flag (verified live), so a new client against an
+  old server loses nothing.
+- **Comments corrected.** `api-auth.ts` no longer claims a path segment avoids
+  URL logs (it does not; the TTL is what bounds a leaked URL). `index.ts` names
+  both capability URLs. `health.ts` states plainly that authorization is decided
+  once per socket and that a per-event re-check would be a breaking change.
+- **The 6.42.0 note "6.8.441 restores full content delivery" was too broad.**
+  It is true for the phone companion. The lens entrypoint was untouched in
+  6.8.441 and connects bare; app 6.9.442 ports the ticket to it.
+- Tests: the adversarial event list is now derived from a `Record` keyed on the
+  union, so a twelfth event type is a compile error rather than a silent gap; a
+  projection that throws is proven not to reach the emitter; the probe is proven
+  to receive no replay; every verdict is exercised.
+- **The probe no longer BUILDS the replay buffer either.** The first cut of this
+  release skipped only the write for `?probe=1`; `materialize` was still keyed
+  on authorization, so an authorized probe filtered up to 200 events and dropped
+  them. One term, matched to the write guard, closes it.
+- **Two guards gained the tests that prove them.** A mutation run during
+  `/validate-plan` (2026-09-01) found the `Object.hasOwn` allowlist guard and
+  the per-reason counter both survived mutation with the suite green.
+  `display-ticketless.test.ts` now emits prototype-keyed event types
+  (`constructor`, `toString`, …) and asserts exact per-reason counts.
+- `SECURITY.md` and a `bugs` field. Two security releases in a row, and there
+  was nowhere to report the next one.
+
+## 6.42.0
+
+The display stream stops broadcasting your meetings to the local network.
+
+`GET /api/display-stream` has been public since it was written, because
+EventSource cannot attach an `X-Cos-Token` header. That is still true, so the
+route is still public and still returns 200 to everyone — but what it SENDS is
+now decided per event. A subscriber that proves it holds the pairing token gets
+the whole bus. A subscriber that does not gets a live transport, the handshake,
+the keepalive, replay-gap notices, and one projected lifecycle marker. It never
+receives a transcript, an answer, a coaching cue, a tool status or an error.
+
+**COS Glasses app 6.8.441 restores full content delivery to the PHONE COMPANION (`index.html`).** It does not touch the lens entrypoint (`glasses.html` / `glasses-entry.ts`), which still connects bare and, wherever it can reach the server at all, now receives lifecycle events only. Whether that entrypoint reaches the server is unproven either way; 6.9.442 ports the ticket to it regardless. Older
+builds keep working — that is the entire reason the connection is not rejected —
+but they connect without a capability, so they will see the content-suppressed
+stream: no live transcript on the lens and no streamed answers, while meeting
+capture, saving, and offline sync continue normally. 6.8.441 is the first app
+build that fetches a ticket and reconnects on `contentAuthorized: false`. Nothing
+else states this, so state it here: update the app with the server.
+
+Two ways to prove you hold the token:
+
+- `X-Cos-Token` on the request, for every fetch-based consumer (COS Control, the
+  companion's own connection probe, curl). Preferred wherever it is possible.
+- `GET /api/display-stream/<expiry>.<hmac>` for EventSource, which cannot send a
+  header. The ticket is an HMAC over its own expiry keyed on the pairing token,
+  so it is stateless, unforgeable without the key, and invalidated the instant
+  the token rotates. `GET /api/models` mints one; `GET /api/health` advertises the
+  capability so a client can detect an older server by its absence.
+
+An invalid or expired ticket is never rejected. It degrades to the ticketless
+stream, so a client whose ticket died mid-reconnect keeps its transport instead
+of entering a retry loop — and the `ready` frame now carries
+`contentAuthorized: <boolean>` so it can tell the difference and re-mint. Without
+that field a degraded stream is indistinguishable from a healthy one.
+
+The ticket TTL is 15 minutes, chosen by the platform rather than by taste: a
+backgrounded Even Hub WebView is suspended and cannot re-mint, and the Even Hub
+review loop locks the phone for five minutes. A 2-minute TTL was guaranteed to
+be dead on the reviewer's exact path. Minting requires the pairing token, so the
+TTL only bounds the value of a ticket that leaks out of a URL.
+
+Also in this release:
+
+- `recording_stop` reaches ticketless subscribers as a PROJECTION carrying only
+  `sessionId`. The production payload also carries `filename`, which embeds the
+  transcript-derived meeting title (`..._Q3_Budget_Cuts_Layoffs_....md`), plus
+  duration and business domain. An allowlist of event TYPES passed the whole
+  event through and would have broadcast the title of every meeting.
+- `replay_gap` reaches ticketless subscribers too. It carries only a reason, the
+  cursor the client itself sent, the watermark already in `ready`, and a buffer
+  boundary, and withholding it strands a client on a dead cursor after a server
+  restart. The buffer it describes is still never served without a ticket.
+- The ticketed path is exempt from the recovery lease classifier. It matched by
+  exact string, so the new path segment classified as a leased request — and an
+  SSE lease never settles, so a connected lens would have held the recovery gate
+  open and 409'd every COS Control server restart. (In this build the admission
+  middleware is exported but not mounted, so that was latent, not live; the
+  classification is a contract a build that mounts it would inherit.) Lease kinds
+  are also redacted now, so `GET /api/recovery/status` can never republish a live
+  display ticket or TTS capability as plain text.
+- `mintDisplayTicket` throws on an empty token instead of returning a ticket that
+  can never verify, and `/api/models` omits the field rather than advertising a
+  dead capability.
+- Ticketless connects are summarized once a minute with a count instead of logged
+  per connect. `retry: 3000` means one stale client would otherwise write ~1,200
+  lines an hour into the launchd log.
+- `.env.example` said a token is required on every `/api` call. It is not, and it
+  never was: four paths are public and two are capability URLs. That file ships in
+  the npm tarball.
+
 ## 6.41.0
 
 Allowlist mode can finally read the workspace it was pointed at.

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security
+
+COS Glasses server runs on your own machine and holds your meeting transcripts,
+so a flaw here is a flaw in your privacy, not ours. Reports are welcome and
+taken seriously.
+
+## Reporting
+
+Open an issue at <https://github.com/ukaoma/cos-glasses-server/issues> titled
+`security` with **no details in the body**. A maintainer will reply with a
+private channel within two business days. Do not post the finding publicly
+until a fixed version is on npm.
+
+Please include the server version (`/api/health` → `server_version`), the
+client (COS Glasses EHPK version or COS Control version), and the smallest
+reproduction you have. Do not include real transcripts.
+
+## What to expect
+
+- Acknowledgement within two business days.
+- A fix released as a patch version, with the finding described in
+  `CHANGELOG.md` once a fixed version is on npm.
+- Credit in the changelog if you want it. TJ's 2026-08 report on the display
+  stream (fixed in 6.42.0 and hardened in 6.42.1) is the model.
+
+## Scope notes
+
+- The pairing token (`X-Cos-Token`) is the only credential. Rotating it
+  invalidates every display-stream ticket; there is no server-side ticket store.
+- `GET /api/display-stream` is public by design and returns lifecycle events
+  only. Content requires a ticket or the token header. See
+  `server/routes/display.ts` for the allowlist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.41.0",
+  "version": "6.42.1",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {
@@ -40,7 +40,8 @@
     ".cos-profile.example.json",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "author": "COS Contributors",
   "license": "MIT",
@@ -49,6 +50,7 @@
     "url": "git+https://github.com/ukaoma/cos-glasses-server.git"
   },
   "homepage": "https://www.gotcos.com",
+  "bugs": { "url": "https://github.com/ukaoma/cos-glasses-server/issues" },
   "publishConfig": {
     "access": "public"
   },

package/server/index.ts

@@ -181,9 +181,10 @@ app.use(cors({
 }))
 // Auth middleware — always active (token is auto-generated if not set).
 // Mounted before body parsers so rejected uploads cannot consume parse memory.
-// The only capability-URL exception is a canonical /tts/play/<UUID> GET/HEAD;
-// authenticated /tts/prepare mints it for native audio players that cannot set
-// X-Cos-Token headers.
+// Two capability-URL exceptions: a canonical /tts/play/<UUID> GET/HEAD (minted by
+// authenticated /tts/prepare for native audio players) and
+// /display-stream/<exp>.<hmac> GET/HEAD (minted on authenticated /api/models for
+// EventSource, which cannot set X-Cos-Token either). See api-auth.ts.
 app.use('/api', requireApiToken(API_TOKEN))
 
 // Fail-closed catch-all for mutation routes that do not own a more specific

package/server/lib/api-auth.ts

@@ -13,13 +13,32 @@ const PUBLIC_API_PATHS = new Set([
 // Native HTML audio requests cannot attach X-Cos-Token. The UUID minted by
 // authenticated POST /tts/prepare is therefore a short-lived bearer
 // capability. Keep this exception exact: GET/HEAD only, one canonical v4 UUID
-// path segment, and no query-token fallback that could leak into URL logs.
+// path segment, and no query-token fallback. (A path segment reaches access and
+// proxy logs exactly as a query string does — the TTL is what bounds a leaked
+// URL; the point of refusing a query form is that it is trivially added back by
+// accident and routinely forwarded.)
 const TTS_PLAYBACK_CAPABILITY_PATH = /^\/tts\/play\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 
+// EventSource has the identical constraint, so the display stream reuses the same
+// shape: `/display-stream/<expUnixSeconds>.<hex hmac>`, GET/HEAD only, path segment,
+// no query-token fallback (same reasoning as above — this is not log hygiene). Admission here is SHAPE ONLY — the signature is verified
+// in the route, which is the only place that holds the API token.
+//
+// `/display-stream` itself STAYS PUBLIC, deliberately. Removing it would make a
+// ticketless connect fall through to the token check and 401, and neither EventSource
+// in the client can send a header — every installed build would enter a permanent
+// reconnect loop and, because `displayBusConnected` would never turn true, would also
+// stop syncing already-recorded offline meetings. Confidentiality is enforced by
+// withholding CONTENT in the route, not by rejecting the connection. The route also
+// accepts a valid X-Cos-Token header as equivalent authorization, for the fetch-based
+// callers that can send one; the ticket exists only for the ones that cannot.
+const DISPLAY_STREAM_CAPABILITY_PATH = /^\/display-stream\/\d{1,15}\.[0-9a-f]{64}$/
+
 export function isPublicApiRequest(method: string, path: string): boolean {
   if (PUBLIC_API_PATHS.has(path)) return true
-  return (method === 'GET' || method === 'HEAD')
-    && TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+  if (method !== 'GET' && method !== 'HEAD') return false
+  return TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+    || DISPLAY_STREAM_CAPABILITY_PATH.test(path)
 }
 
 /** Global /api authentication boundary. Mount before all body parsers. */

package/server/lib/display-bus.ts

@@ -52,7 +52,12 @@ export function getDisplayWatermark(): { bootId: string; eventId: number } {
   return { bootId: serverMetrics.bootId, eventId }
 }
 
-export function replayDisplayEvents(bootId: string | null, afterEventId: number): DisplayReplayResult {
+export function replayDisplayEvents(
+  bootId: string | null,
+  afterEventId: number,
+  opts: { materialize?: boolean } = {},
+): DisplayReplayResult {
+  const materialize = opts.materialize !== false
   const oldestEventId = replayBuffer[0]?.eventId ?? eventId + 1
   const latestEventId = eventId
   if (bootId && bootId !== serverMetrics.bootId) {
@@ -65,7 +70,7 @@ export function replayDisplayEvents(bootId: string | null, afterEventId: number)
     return { events: [], gap: true, reason: 'buffer_overflow', oldestEventId, latestEventId }
   }
   return {
-    events: replayBuffer.filter(item => item.eventId > afterEventId),
+    events: materialize ? replayBuffer.filter(item => item.eventId > afterEventId) : [],
     gap: false,
     oldestEventId,
     latestEventId,

package/server/lib/display-ticket.ts

@@ -0,0 +1,119 @@
+import { createHmac } from 'node:crypto'
+import { timingSafeTokenEqual } from './token-auth.js'
+
+/**
+ * Short-lived capability for GET /api/display-stream.
+ *
+ * WHY A CAPABILITY AT ALL. `EventSource` cannot attach `X-Cos-Token` — the same
+ * constraint native HTML audio has, which is why `api-auth.ts` already carries a
+ * TTS playback capability. This reuses that reviewed shape rather than inventing
+ * a second one: **a path segment, GET/HEAD only, and no query-token fallback that
+ * could leak into URL logs.**
+ *
+ * WHY STATELESS. An HMAC over the expiry needs no store, so there is no eviction
+ * policy to get wrong, no unbounded Map, and no timer to leak. It also invalidates
+ * every outstanding ticket the moment the pairing token rotates, which a UUID store
+ * would not. The TTS capability needs a store because its UUID carries no claims;
+ * this one carries its own expiry.
+ *
+ * WHY REPLAY WITHIN THE TTL IS FINE. Minting requires the pairing token, so an
+ * attacker who could mint already has full API access. The TTL bounds the value of
+ * a ticket that leaks out of a URL, which is the actual threat. Single-use would be
+ * strictly worse: the server sends `retry: 3000`, so a browser-initiated reconnect
+ * replays the same URL, and a consumed ticket would turn every transport blip into a
+ * hard failure.
+ */
+
+/**
+ * 15 minutes, set by the PLATFORM, not by taste.
+ *
+ * The first draft used 120s, which is exactly the Even Hub reviewer's boundary: the
+ * review rubric checks a two-minute idle, and the pre-submission loop locks the phone
+ * for five. A backgrounded Even Hub WebView is SUSPENDED — no timer, no fetch, no
+ * re-mint — so a 120s ticket is guaranteed to be dead on the exact path a reviewer
+ * exercises, and the app would come back to a content-suppressed stream.
+ *
+ * The TTL is not what protects the stream. MINTING requires the pairing token, so
+ * anyone who can mint already has full API access; the TTL only bounds the value of
+ * a ticket that leaks out of a URL (proxy log, screen share, shoulder surf). 15
+ * minutes keeps that window small while surviving every suspension a phone actually
+ * imposes.
+ */
+export const DISPLAY_TICKET_TTL_SECONDS = 900
+
+/** Domain separation. Without a purpose string, any future feature that HMACs an
+ *  integer under the same key would mint cross-usable display tickets. */
+const TICKET_PURPOSE = 'display-stream'
+
+function signature(apiToken: string, expSeconds: number): string {
+  return createHmac('sha256', apiToken)
+    .update(`${TICKET_PURPOSE}:${expSeconds}`)
+    .digest('hex')
+}
+
+/**
+ * `<expUnixSeconds>.<hex sha256 hmac>` — safe in a path segment, no encoding needed.
+ *
+ * THROWS on an empty token rather than returning a ticket. An HMAC keyed on '' is a
+ * well-formed string that `verifyDisplayTicket` rejects unconditionally (it fails
+ * closed on `!apiToken`), so a silent mint would publish a capability that can never
+ * be redeemed — the caller would advertise `ticketSupported` and hand out a value
+ * that is dead on arrival. Callers must decide what to do without a token; they may
+ * not be handed a placeholder.
+ */
+export function mintDisplayTicket(
+  apiToken: string,
+  nowMs: number = Date.now(),
+): string {
+  if (!apiToken) {
+    throw new Error('mintDisplayTicket requires a non-empty API token — a ticket minted without one can never verify')
+  }
+  const exp = Math.floor(nowMs / 1000) + DISPLAY_TICKET_TTL_SECONDS
+  return `${exp}.${signature(apiToken, exp)}`
+}
+
+/**
+ * True only for a well-formed, unexpired, correctly-signed ticket.
+ *
+ * Fails CLOSED on every malformed input. The expiry is parsed from the ticket
+ * itself, so a forged expiry changes the signed message and fails the HMAC — the
+ * claim cannot be edited without the key.
+ */
+/**
+ * Why a ticket was refused. `verifyDisplayTicket` collapsed every refusal to
+ * `false`, so the server's only signal was "N rejected" with no way to tell an
+ * EXPIRED ticket (a client that needs to re-mint — expected on every native
+ * EventSource retry after a WebView suspension) from a BAD SIGNATURE (a rotated
+ * token, or a forgery). QA on 2026-09-01 found >=7 rejections in three
+ * consecutive windows on the author's own device and could not say which.
+ */
+export type DisplayTicketVerdict = 'ok' | 'malformed' | 'expired' | 'bad-signature'
+
+export function explainDisplayTicket(
+  apiToken: string,
+  ticket: unknown,
+  nowMs: number = Date.now(),
+): DisplayTicketVerdict {
+  if (typeof ticket !== 'string' || !apiToken) return 'malformed'
+  const separator = ticket.indexOf('.')
+  if (separator <= 0) return 'malformed'
+  const expRaw = ticket.slice(0, separator)
+  const provided = ticket.slice(separator + 1)
+  if (!/^\d{1,15}$/.test(expRaw) || !/^[0-9a-f]{64}$/.test(provided)) return 'malformed'
+  const exp = Number(expRaw)
+  // Unreachable while the regex caps exp at 15 digits (MAX_SAFE_INTEGER has 16);
+  // kept as the belt for a widened regex. A mutation test proved it dead.
+  if (!Number.isSafeInteger(exp)) return 'malformed'
+  // Expiry is checked BEFORE the compare so a stale ticket cannot be probed for
+  // signature validity, and so the common rejection costs no hashing.
+  if (Math.floor(nowMs / 1000) >= exp) return 'expired'
+  return timingSafeTokenEqual(provided, signature(apiToken, exp)) ? 'ok' : 'bad-signature'
+}
+
+export function verifyDisplayTicket(
+  apiToken: string,
+  ticket: unknown,
+  nowMs: number = Date.now(),
+): boolean {
+  return explainDisplayTicket(apiToken, ticket, nowMs) === 'ok'
+}

package/server/lib/recovery-activity.ts

@@ -29,6 +29,40 @@ const EXEMPT_EXACT = new Set([
   'POST /api/recovery/server/restart',
 ])
 
+/**
+ * Exempt by PREFIX, because the display stream grew a path segment.
+ *
+ * EXEMPT_EXACT matches whole strings, so `GET /api/display-stream/<exp>.<hmac>`
+ * (6.42.0's ticketed form) fell through to 'request' and would take a lease. An SSE
+ * connection has no `finish`, and `close` only converts the lease to a 120s grace
+ * window that a live socket never reaches — so one connected lens would hold the
+ * recovery gate open indefinitely and 409 every COS Control server restart. A
+ * long-lived stream is the exact shape that must never take a lease.
+ *
+ * SCOPE, stated honestly: in THIS build `recoveryAdmissionMiddleware` is exported
+ * but never mounted (`grep -rn "recovery-activity" server` shows routes/recovery.ts
+ * importing only acquireMaintenance and getRecoveryActivityStatus), so no lease is
+ * taken for any route and the 409 above is latent rather than live. The
+ * classification is still a published contract that a build mounting the middleware
+ * would inherit, so it is fixed here rather than left as a trap.
+ */
+const EXEMPT_GET_PREFIXES = ['/api/display-stream/']
+
+/**
+ * A capability URL is a live bearer credential. GET /api/recovery/status publishes
+ * every lease `kind` verbatim, and that route is reachable by anyone who can already
+ * read status — so a kind built from the raw path would republish a working display
+ * ticket (or a TTS playback capability) as plain text in a diagnostic response.
+ *
+ * Redaction happens where the kind is BUILT, not where it is read, so no future
+ * reader of `active` can reintroduce the leak.
+ */
+export function redactCapabilityPath(path: string): string {
+  return path
+    .replace(/^(\/api\/display-stream)\/[^/]+$/, '$1/<ticket>')
+    .replace(/^(\/api\/tts\/play)\/[^/]+$/, '$1/<capability>')
+}
+
 const OPERATION_GET_PREFIXES = [
   '/api/models',
   '/v1/models',
@@ -53,6 +87,10 @@ export function classifyRecoveryRoute(method: string, path: string): RecoveryRou
   const verb = method.toUpperCase()
   const normalized = path.split('?')[0]
   if (EXEMPT_EXACT.has(`${verb} ${normalized}`)) return 'exempt'
+  if ((verb === 'GET' || verb === 'HEAD')
+    && EXEMPT_GET_PREFIXES.some(prefix => normalized.startsWith(prefix))) {
+    return 'exempt'
+  }
   if (!normalized.startsWith('/api/') && !normalized.startsWith('/v1/')) return 'exempt'
   if (verb !== 'GET' && verb !== 'HEAD') return 'operation'
   if (OPERATION_GET_PREFIXES.some(prefix => normalized === prefix || normalized.startsWith(prefix))) {
@@ -144,7 +182,10 @@ export function recoveryAdmissionMiddleware(req: Request, res: Response, next: N
   }
 
   const id = `${routeClass}:${++sequence}`
-  const release = createLease(`${req.method} ${(req.originalUrl || req.path).split('?')[0]}`, id)
+  const release = createLease(
+    `${req.method} ${redactCapabilityPath((req.originalUrl || req.path).split('?')[0])}`,
+    id,
+  )
   res.once('finish', release)
   res.once('close', () => {
     const lease = active.get(id)

package/server/routes/display.ts

@@ -2,30 +2,199 @@
 // Any connected glasses client receives real-time query responses
 // regardless of which interface submitted the query
 
-import { Router, type Response } from 'express'
+import { Router, type Request, type Response } from 'express'
 import {
   emitDisplay,
   getDisplayWatermark,
   onDisplay,
   replayDisplayEvents,
+  type DisplayEvent,
   type PublishedDisplayEvent,
 } from '../lib/display-bus.js'
+import { type DisplayTicketVerdict, explainDisplayTicket } from '../lib/display-ticket.js'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
 
 export const displayRouter = Router()
 
+/**
+ * What a TICKETLESS subscriber may receive, as a per-type PROJECTION.
+ *
+ * ALLOWLIST, NEVER A DENYLIST. A new member of the DisplayEvent union is withheld
+ * by default, so adding an event type can never silently widen the unauthenticated
+ * surface.
+ *
+ * A projection, not a pass-through, because an allowlisted TYPE can still carry
+ * content in its payload — which is exactly the bug the first cut of this shipped.
+ * The projection is the contract: whatever the emitter grows later, only the fields
+ * named here can ever leave.
+ *
+ * The other ten members of the union all carry user content: `transcript_chunk` and
+ * `prompt_transcript` carry meeting speech with speaker labels, `chunk`/`done` carry
+ * answer text, `session_restore` carries conversation state, `coaching_nudge` carries
+ * derived guidance, `start` carries session metadata, `tool_status` carries a message,
+ * `error` carries error text, and `recording_start` is covered by its own note below.
+ *
+ * NOT ROUTED THROUGH HERE: `keepalive` is an SSE comment (`: keepalive`), not an
+ * event. `ready` and `replay_gap` are written directly by the handler below — both
+ * are transport metadata with no user content, and `replay_gap` is deliberately
+ * ticketless-visible (see the handler).
+ */
+const TICKETLESS_PROJECTIONS: {
+  readonly [K in DisplayEvent['type']]?: (data: Record<string, unknown>) => Record<string, unknown>
+} = {
+  /**
+   * `recording_stop` is a lifecycle marker: the lens uses it to clear a stale
+   * "recording" indicator that would otherwise persist forever.
+   *
+   * BUT THE PRODUCTION PAYLOAD IS NOT BARE. Both emitters (routes/meeting.ts, the
+   * durable save path and the orphan-recovery path) send
+   * `{ sessionId, filename, durationMin, domain }`, and `filename` is built by
+   * meeting-store.ts `filenameStem()` from the transcript-derived meeting TITLE —
+   * `2026-08-31_Q3_Budget_Cuts_Layoffs_1a2b3c4d.md`. Passing the event through whole
+   * broadcast the meeting title, its duration and its business domain to every
+   * unauthenticated listener on the LAN, which is precisely what a ticket exists to
+   * withhold.
+   *
+   * Only `sessionId` survives. It is the id the CLIENT supplied when it started the
+   * capture (meeting-store `normalizeSessionId` constrains it to
+   * `[A-Za-z0-9:_-]{3,96}` and the server never derives it from the transcript), so
+   * it is the one field the subscriber already holds and the one the lens needs to
+   * match the marker to its own indicator.
+   */
+  // `durationMin` rides along because the lens renders `Meeting saved — ${n}m`
+  // straight from this frame (glasses-entry.ts). Projecting it away left a valid
+  // JSON payload — so the client's catch never fired — and painted
+  // "Meeting saved — undefinedm". A duration is a scalar with no transcript in it;
+  // `filename` stays stripped precisely because it embeds the meeting TITLE.
+  recording_stop: data => ({ sessionId: data.sessionId, durationMin: data.durationMin }),
+
+  /**
+   * `recording_start` is NOT here, as a DECISION rather than an omission.
+   *
+   * Three reasons, in order of weight:
+   *  1. The failure modes are asymmetric. A missing `stop` leaves the lens asserting
+   *     something FALSE — a recording indicator burning with no recording behind it.
+   *     A missing `start` leaves it showing nothing, which is exactly what the
+   *     ticketless contract promises anyway. Only the wrong state needs repairing.
+   *  2. `start` is a live presence signal. "A meeting is beginning on this machine,
+   *     right now" is occupancy intelligence for any listener on the network; `stop`
+   *     is the erasure of a signal already shown.
+   *  3. Nothing in this server emits it. `grep -rn "type: 'recording_start'" server`
+   *     returns no emitter as of 6.42.0 — it exists in the union for client-side
+   *     use — so allowlisting it would advertise a path that never runs.
+   *
+   * If a server-side emitter is ever added, revisit this WITH a projection; do not
+   * simply add the key.
+   */
+}
+
+/**
+ * The event a ticketless subscriber may receive, or null when it may receive none.
+ * Never returns the input event unchanged — the projection is always applied.
+ */
+function projectForTicketless(event: PublishedDisplayEvent): PublishedDisplayEvent | null {
+  // hasOwn, not a bare index: the map is an object literal and inherits
+  // Object.prototype, so a type of "constructor" would resolve to `Object` — a
+  // truthy identity function — and pass the event through whole. Unreachable via
+  // the typed union today; the allowlist must not depend on that staying true.
+  const project = Object.hasOwn(TICKETLESS_PROJECTIONS, event.type)
+    ? TICKETLESS_PROJECTIONS[event.type]
+    : undefined
+  if (!project) return null
+  return { ...event, data: project(event.data) }
+}
+
 function writeEvent(res: Response, event: PublishedDisplayEvent): void {
   const data = JSON.stringify({
     ...event.data,
+    // NESTED, and it must stay nested. Every shipped client reads
+    // `parsed._cosDisplayCursor` and RETURNS EARLY when it is absent
+    // (Main.ts, identically in 6.8.353 and 6.8.441), so flattening these three
+    // fields to the top level silently freezes the client cursor at its
+    // connect-time watermark: `rememberCursor` never fires, and every reconnect
+    // then re-replays and re-processes everything since the connect (duplicate
+    // `done` renders), or trips a spurious buffer_overflow replay_gap past 200
+    // events. 6.42.0 briefly shipped the flattened shape in development; it was
+    // caught pre-release. A test that only asserts `"eventId":1` cannot see the
+    // difference, because that substring is present in BOTH shapes.
     _cosDisplayCursor: {
       bootId: event.bootId,
       eventId: event.eventId,
       publishedAt: event.publishedAt,
     },
   })
+  // SSE `id:` is the reconnect cursor EventSource echoes back as Last-Event-ID.
+  // Namespaced by bootId so a restarted server cannot look like a resumable gap.
   res.write(`id: ${event.bootId}:${event.eventId}\nevent: ${event.type}\ndata: ${data}\n\n`)
 }
 
-displayRouter.get('/display-stream', (req, res) => {
+/**
+ * Ticketless-connect accounting, summarized rather than logged per connect.
+ *
+ * The server sends `retry: 3000`, so ONE client that cannot mint reconnects every
+ * three seconds — 1,200 lines an hour into the launchd log, forever, from a single
+ * stale install. The counter is the point (adoption is measured, not guessed); the
+ * per-line volume is not.
+ */
+const TICKETLESS_LOG_INTERVAL_MS = 60_000
+let ticketlessConnects = 0
+let ticketlessRejectedTickets = 0
+let ticketlessLoggedAt = 0
+// Per-reason so the log can tell "a client needs to re-mint" (expired — expected
+// after every native EventSource retry on a stale URL) from "someone is holding
+// a ticket this token never signed" (bad-signature — a rotation, or a probe).
+const ticketlessByReason: Record<Exclude<DisplayTicketVerdict, 'ok'> | 'none', number> = {
+  none: 0, malformed: 0, expired: 0, 'bad-signature': 0,
+}
+
+function noteTicketlessConnect(reason: Exclude<DisplayTicketVerdict, 'ok'> | 'none'): void {
+  ticketlessConnects++
+  if (reason !== 'none') ticketlessRejectedTickets++
+  ticketlessByReason[reason]++
+  const now = Date.now()
+  if (ticketlessLoggedAt !== 0 && now - ticketlessLoggedAt < TICKETLESS_LOG_INTERVAL_MS) return
+  ticketlessLoggedAt = now
+  const { expired, 'bad-signature': bad, malformed, none } = ticketlessByReason
+  console.warn(
+    `[display-bus] ${ticketlessConnects} ticketless subscriber(s)`
+    + ` (${ticketlessRejectedTickets} with a rejected ticket:`
+    + ` ${expired} expired, ${bad} bad-signature, ${malformed} malformed; ${none} bare)`
+    + ` — content withheld, lifecycle only`,
+  )
+  ticketlessConnects = 0
+  ticketlessRejectedTickets = 0
+  for (const k of Object.keys(ticketlessByReason) as Array<keyof typeof ticketlessByReason>) ticketlessByReason[k] = 0
+}
+
+export function __resetDisplayStreamLogForTests(): void {
+  ticketlessConnects = 0
+  ticketlessRejectedTickets = 0
+  ticketlessLoggedAt = 0
+  for (const k of Object.keys(ticketlessByReason) as Array<keyof typeof ticketlessByReason>) ticketlessByReason[k] = 0
+}
+
+/**
+ * A valid `X-Cos-Token` header is equivalent authorization to a ticket.
+ *
+ * The ticket exists only because EventSource cannot set headers. Every fetch-based
+ * consumer can — including the client's own `probeConnectionTarget`, COS Control, and
+ * curl — so requiring those to mint first would suppress content for callers that are
+ * already fully authenticated, and would permanently pollute the ticketless adoption
+ * counter with connections that were never the problem.
+ */
+function headerAuthorized(req: Request): boolean {
+  return timingSafeTokenEqual(req.headers['x-cos-token'], process.env.COS_API_TOKEN ?? '')
+}
+
+/**
+ * Shared handler for both registrations.
+ *
+ * `authorized` decides CONTENT, never admission. A ticketless subscriber still gets
+ * 200, `ready`, the keepalive, lifecycle markers, and replay-gap notices, so every
+ * already-installed client keeps a live transport, keeps `displayBusConnected` true,
+ * and keeps syncing offline meetings. It simply never receives transcripts or answers.
+ */
+function serveDisplayStream(req: Request, res: Response, authorized: boolean): void {
   res.writeHead(200, {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
@@ -38,26 +207,62 @@ displayRouter.get('/display-stream', (req, res) => {
   // Tell EventSource to retry quickly on disconnect (3s instead of browser default ~5-10s)
   res.write('retry: 3000\n\n')
 
+  // DO NOT move this inside an `if (authorized)`. It looks unused on the ticketless
+  // path and is not: a ticketless subscriber never receives buffered events, but it
+  // MUST still be told when its cursor is unresumable (see replay_gap below), and
+  // that verdict is a function of the cursor. Hiding the cursor behind the
+  // authorization check would silently delete ticketless gap reporting.
   const headerCursor = String(req.headers['last-event-id'] ?? '')
   const [headerBootId, headerEventId] = headerCursor.includes(':')
     ? headerCursor.split(':', 2)
     : ['', headerCursor]
   const cursorBootId = String(req.query.bootId ?? headerBootId ?? '') || null
   const cursorEventId = Number(req.query.eventId ?? headerEventId ?? 0)
-  const replay = replayDisplayEvents(cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0)
 
   // Ready is a transport handshake, not proof that replay was consumed. It
   // must precede application events so build 188 can finish admission first.
+  //
+  // `contentAuthorized` is what makes a degraded stream DETECTABLE. Without it the
+  // two handshakes are byte-identical, so a client whose ticket expired sets
+  // `displayBusConnected = true`, sees a healthy socket, and never re-mints — the
+  // stream stays silent forever with nothing anywhere reporting a fault. Old clients
+  // JSON.parse this frame and read only bootId/eventId, so the extra key is inert
+  // for them.
   const watermark = getDisplayWatermark()
-  res.write(`event: ready\ndata: ${JSON.stringify(watermark)}\n\n`)
+  res.write(`event: ready\ndata: ${JSON.stringify({ ...watermark, contentAuthorized: authorized })}\n\n`)
+
+  // Gap detection is needed for every subscriber; MATERIALISING the up-to-200
+  // event buffer is only needed for one we will actually write it to. A stale
+  // ticketless install retrying every 3s was filtering the whole buffer each
+  // time and discarding it — and so was every authorized `probe=1` connect,
+  // whose write is skipped below. The term here must match that `else if`.
+  const materialize = authorized && req.query.probe !== '1'
+  const replay = replayDisplayEvents(
+    cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0, { materialize },
+  )
   if (replay.gap) {
+    // Ticketless-VISIBLE on purpose. The payload is transport metadata only —
+    // reason, the cursor the client itself sent, the watermark already in `ready`,
+    // and a buffer boundary — so it discloses nothing. Withholding it silently
+    // breaks the client's replay-reconciliation branch after a server restart: the
+    // client would sit on a dead cursor waiting for a resume that cannot come.
     res.write(`event: replay_gap\ndata: ${JSON.stringify({
       reason: replay.reason,
       requested: { bootId: cursorBootId, eventId: cursorEventId },
       watermark,
       oldestEventId: replay.oldestEventId,
     })}\n\n`)
-  } else {
+  } else if (authorized && req.query.probe !== '1') {
+    // The replay buffer holds up to REPLAY_BUFFER_SIZE past events, so serving it
+    // to a ticketless subscriber would be a retroactive transcript dump — a larger
+    // disclosure than the live subscription. Skipped entirely rather than filtered,
+    // so no future event type can leak through a per-item test here.
+    //
+    // `probe=1` is the client's connection probe: it opens this stream ONLY to read
+    // the `ready` watermark and then aborts. It sends the token, so it is
+    // authorized — and was being handed the full buffer on every reconnect and
+    // throwing it away (1,164 "Replayed 200" lines in one day's log). A probe is
+    // never a consumer; it gets the handshake and nothing else.
     for (const event of replay.events) writeEvent(res, event)
     if (replay.events.length > 0) {
       console.log(`[display-bus] Replayed ${replay.events.length} publish-owned events after ${cursorEventId}`)
@@ -70,13 +275,43 @@ displayRouter.get('/display-stream', (req, res) => {
   }, 15_000)
 
   const unsub = onDisplay((event) => {
-    try { writeEvent(res, event) } catch { /* client gone */ }
+    // The projection runs INSIDE the try, not above it. This is a synchronous
+    // EventEmitter listener, so anything that throws here propagates back out
+    // through `bus.emit()` into whoever called `emitDisplay` — and one of those
+    // callers is the meeting-save path. A malformed event must never be able to
+    // reach a recording. 6.41.0 guarded the whole listener body; keep that.
+    try {
+      const outgoing = authorized ? event : projectForTicketless(event)
+      if (!outgoing) return
+      writeEvent(res, outgoing)
+    } catch { /* client gone, or an event this subscriber simply cannot render */ }
   })
 
   req.on('close', () => {
     clearInterval(ping)
     unsub()
   })
+}
+
+// Ticketless path. Stays public so installed clients keep a live transport; content
+// is withheld above unless the caller sent a valid token header.
+displayRouter.get('/display-stream', (req, res) => {
+  const authorized = headerAuthorized(req)
+  if (!authorized) noteTicketlessConnect('none')
+  serveDisplayStream(req, res, authorized)
+})
+
+// Ticketed path. `api-auth` admits it on SHAPE alone; the signature is verified
+// here, where the API token lives. A bad or expired ticket is not rejected — it
+// degrades to exactly the ticketless stream, so a client whose ticket expired
+// mid-reconnect keeps its transport instead of entering a retry loop. It learns it
+// is degraded from `contentAuthorized:false` in the `ready` frame, and re-mints.
+displayRouter.get('/display-stream/:ticket', (req, res) => {
+  const apiToken = process.env.COS_API_TOKEN ?? ''
+  const verdict = explainDisplayTicket(apiToken, req.params.ticket)
+  const authorized = verdict === 'ok' || headerAuthorized(req)
+  if (!authorized) noteTicketlessConnect(verdict)
+  serveDisplayStream(req, res, authorized)
 })
 
 // POST /api/display-session — broadcast session restore to glasses (cross-surface sync)

package/server/routes/health.ts

@@ -10,6 +10,7 @@ import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contra
 import { isSileroAvailable } from '../lib/vad-silero.js'
 import { profileProvenanceSummary, speakerModelState, speakerReadiness } from '../lib/speaker-embeddings.js'
 import { chunkEmbeddingStoreStats } from '../lib/chunk-embedding-store.js'
+import { mintDisplayTicket, DISPLAY_TICKET_TTL_SECONDS } from '../lib/display-ticket.js'
 import { correctionStoreStats } from '../lib/meeting-corrections.js'
 import { meetingAudioStats } from '../lib/meeting-audio-archive.js'
 import { adaptivePlaybackStatus } from '../lib/adaptive-playback-audio.js'
@@ -353,6 +354,14 @@ healthRouter.get('/health', async (_req, res) => {
     review_audio: reviewAudio,
     ...(voiceProvenance ? { voice_provenance: voiceProvenance } : {}),
     capabilities: {
+      // Advertised on the PUBLIC health route on purpose: a client deciding whether
+      // to request a display ticket may not hold a usable token yet, and an old
+      // server simply omits this key, which is how a new client detects it.
+      displayStream: {
+        ticketSupported: true,
+        ticketTtlSeconds: DISPLAY_TICKET_TTL_SECONDS,
+        contentRequiresTicket: true,
+      },
       transcription: {
         ...transcription,
         live: transcriptionLive,
@@ -429,6 +438,9 @@ healthRouter.get('/models', async (req, res) => {
   // THIS surface and Main.ts states outright that /api/health alone is not used,
   // so a capability published only there is invisible to the phone.
   const threadAttach = threadAttachCapability()
+  // mintDisplayTicket refuses an empty key, because a ticket signed with '' can
+  // never verify. Omit the field rather than publish a dead capability.
+  const apiToken = process.env.COS_API_TOKEN ?? ''
   res.json({
     ...catalog,
     ...threadAttachHealthFields(threadAttach),
@@ -447,6 +459,42 @@ healthRouter.get('/models', async (req, res) => {
     },
     ollamaReady: isOllamaProviderReady(),
     serverInstanceId: getServerInstanceId(),
+    // Minted here rather than on a route of its own: this response is already
+    // authenticated, and the mint is stateless, so it costs nothing and stores
+    // nothing.
+    //
+    // TWO THINGS THIS ROUTE IS NOT, both of which the client must plan around:
+    //
+    // 1. It IS fetched before every connect in the 6.8.441 client — every retry
+    //    calls connectDisplayBus() with no argument, which re-runs
+    //    probeConnectionTarget, which fetches this route. Do not assume that of
+    //    any OTHER client: nothing in the protocol requires it, and a client that
+    //    minted once at pairing would go content-free one TTL later.
+    // 2. Its drain behaviour is NOT what classifyRecoveryRoute implies. That
+    //    classifier puts /api/models in OPERATION_GET_PREFIXES, but its only
+    //    consumer — recoveryAdmissionMiddleware — is never mounted in this build,
+    //    and the gate that IS mounted (server/index.ts) returns next() for every
+    //    GET/HEAD/OPTIONS on its first line. So this route answers 200 during a
+    //    COS Control drain today. Treat the classifier's verdict as the contract a
+    //    build that mounts that middleware would enforce, not as current behaviour.
+    //    (The ticketed display-stream path is exempt either way, so an already-held
+    //    ticket keeps working through a drain — which is still why the TTL has to
+    //    outlive one.)
+    //
+    // So the CLIENT carries the re-mint obligation: fetch /api/models and reconnect
+    // when a display-stream `ready` frame reports `contentAuthorized: false`,
+    // retrying if the fetch 503s. Nothing on the server can re-mint on the
+    // client's behalf.
+    //
+    // AUTHORIZATION IS DECIDED ONCE PER SOCKET, at connect. A ticket that was
+    // valid when the EventSource opened keeps that socket authorized for its whole
+    // life — QA on 2026-09-01 held an 8-second ticket open for 32s and content
+    // kept flowing. That is deliberate: the shipped client re-mints only on
+    // RECONNECT, never on a timer, so a per-event re-check would blank every
+    // 6.8.441 lens fifteen minutes into a meeting. The TTL therefore bounds how
+    // long a LEAKED URL can open a new socket, not how long an open socket lives.
+    // Changing that is a breaking change that needs a client version gate first.
+    ...(apiToken ? { displayStreamTicket: mintDisplayTicket(apiToken) } : {}),
     capabilities: {
       durableQueryJobs: {
         enabled: durableJobs.enabled,

package/server/routes/query.ts

@@ -161,9 +161,13 @@ queryRouter.post('/query', async (req, res) => {
           emitDisplay({ type: 'tool_status', data: { message } })
         }
       },
-      // Activity lines stay on this authenticated request stream. The global
-      // display stream is intentionally unauthenticated for Even Hub recovery,
-      // so observable command/output text must never be broadcast there.
+      // Activity lines stay on this authenticated request stream. The guard is
+      // unchanged; the reason has moved. Since 6.42.0 the global display stream is
+      // not "unauthenticated" — it ADMITS ticketless subscribers (200 for everyone,
+      // so an installed client keeps a live transport) and withholds CONTENT per
+      // event instead. Broadcasting observable command/output text onto that bus
+      // would leave it one allowlist entry away from an unauthenticated listener,
+      // so it is never emitted there at all.
       ...(activityToolMode === 'preview' ? {
         onActivityLine: (line: { kind: 'input' | 'output'; text: string }) => {
           if (!done) {