@gotcos/glasses-server 6.42.0 → 6.42.1

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## 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.
@@ -10,7 +57,7 @@ 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 is required to restore full content delivery.** Older
+**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

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.42.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,12 +13,15 @@ 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. Admission here is SHAPE ONLY — the signature is verified
+// 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

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

@@ -79,21 +79,41 @@ export function mintDisplayTicket(
  * itself, so a forged expiry changes the signed message and fails the HMAC — the
  * claim cannot be edited without the key.
  */
-export function verifyDisplayTicket(
+/**
+ * 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(),
-): boolean {
-  if (typeof ticket !== 'string' || !apiToken) return false
+): DisplayTicketVerdict {
+  if (typeof ticket !== 'string' || !apiToken) return 'malformed'
   const separator = ticket.indexOf('.')
-  if (separator <= 0) return false
+  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 false
+  if (!/^\d{1,15}$/.test(expRaw) || !/^[0-9a-f]{64}$/.test(provided)) return 'malformed'
   const exp = Number(expRaw)
-  if (!Number.isSafeInteger(exp)) return false
+  // 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 false
-  return timingSafeTokenEqual(provided, signature(apiToken, exp))
+  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/routes/display.ts

@@ -11,7 +11,7 @@ import {
   type DisplayEvent,
   type PublishedDisplayEvent,
 } from '../lib/display-bus.js'
-import { verifyDisplayTicket } from '../lib/display-ticket.js'
+import { type DisplayTicketVerdict, explainDisplayTicket } from '../lib/display-ticket.js'
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
 
 export const displayRouter = Router()
@@ -93,7 +93,13 @@ const TICKETLESS_PROJECTIONS: {
  * Never returns the input event unchanged — the projection is always applied.
  */
 function projectForTicketless(event: PublishedDisplayEvent): PublishedDisplayEvent | null {
-  const project = TICKETLESS_PROJECTIONS[event.type]
+  // 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) }
 }
@@ -134,25 +140,37 @@ 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(rejectedTicket: boolean): void {
+function noteTicketlessConnect(reason: Exclude<DisplayTicketVerdict, 'ok'> | 'none'): void {
   ticketlessConnects++
-  if (rejectedTicket) ticketlessRejectedTickets++
+  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) — content withheld, lifecycle only`,
+    + ` (${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
 }
 
 /**
@@ -213,7 +231,15 @@ function serveDisplayStream(req: Request, res: Response, authorized: boolean): v
   const watermark = getDisplayWatermark()
   res.write(`event: ready\ndata: ${JSON.stringify({ ...watermark, contentAuthorized: authorized })}\n\n`)
 
-  const replay = replayDisplayEvents(cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0)
+  // 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`,
@@ -226,11 +252,17 @@ function serveDisplayStream(req: Request, res: Response, authorized: boolean): v
       watermark,
       oldestEventId: replay.oldestEventId,
     })}\n\n`)
-  } else if (authorized) {
+  } 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}`)
@@ -265,7 +297,7 @@ function serveDisplayStream(req: Request, res: Response, authorized: boolean): v
 // is withheld above unless the caller sent a valid token header.
 displayRouter.get('/display-stream', (req, res) => {
   const authorized = headerAuthorized(req)
-  if (!authorized) noteTicketlessConnect(false)
+  if (!authorized) noteTicketlessConnect('none')
   serveDisplayStream(req, res, authorized)
 })
 
@@ -276,9 +308,9 @@ displayRouter.get('/display-stream', (req, res) => {
 // 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 ticketOk = verifyDisplayTicket(apiToken, req.params.ticket)
-  const authorized = ticketOk || headerAuthorized(req)
-  if (!authorized) noteTicketlessConnect(true)
+  const verdict = explainDisplayTicket(apiToken, req.params.ticket)
+  const authorized = verdict === 'ok' || headerAuthorized(req)
+  if (!authorized) noteTicketlessConnect(verdict)
   serveDisplayStream(req, res, authorized)
 })
 

package/server/routes/health.ts

@@ -482,9 +482,18 @@ healthRouter.get('/models', async (req, res) => {
     //    outlive one.)
     //
     // So the CLIENT carries the re-mint obligation: fetch /api/models and reconnect
-    // when a display-stream `ready` frame reports `contentAuthorized: false`, or
-    // when DISPLAY_TICKET_TTL_SECONDS has elapsed since the last mint — retrying if
-    // the fetch 503s. Nothing on the server can re-mint on the client's behalf.
+    // 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: {