@gotcos/glasses-server 6.42.0 → 6.43.0

package/CHANGELOG.md

@@ -1,3 +1,119 @@
+## 6.43.0
+
+The brief is waiting before you ask for it.
+
+A start-of-day brief now runs on a schedule inside the server and lands in
+the inbox as an ordinary numbered reply — no prompt, no "run the good-morning
+skill", no phone awake at 07:00. Jun Kiat Lee's first-week note said it
+plainly: he deployed COS to his G2 expecting a push at the start of the day and
+nothing came, because until now the only thing that could start a brief was a
+person typing. The server is the one process awake at that hour, so it owns
+the schedule.
+
+What you get, by default: weekdays at 07:00 in the Mac's own timezone, four
+sections any COS brain can fill — Calendar, From recent meetings (decisions,
+deadlines, owed items), Due (tasks inside a seven-day horizon), and Waiting on
+you (unanswered mentions and asks across whatever channels the brain can
+read). Everything else in the catalog — Knowledge graph, Reflection, Health,
+an Opening reading, a Metrics pulse, a workspace skill, a custom section — is
+off until you turn it on. The brief is composed from the sources you choose,
+in the order you choose, with the windows you choose, so it is yours rather
+than a template with your name on it.
+
+How it works, so the cost is legible:
+
+- One durable query job per local calendar day, submitted to the same
+  coordinator every phone prompt uses. It survives the phone being asleep and
+  is projected into the conversation store with a reserved message number when
+  it completes, so the companion's history hydration surfaces it like any
+  reply.
+- The fire is remembered in a ledger written BEFORE admission. A crash between
+  that write and the 202 is resumed by a per-day client identity, never re-run.
+  A failed admission (store degraded, server draining) retries at most three
+  times, two minutes apart, then gives the day up.
+- A Mac asleep through the slot still fires inside a catch-up window (three
+  hours by default, up to twelve). Past that, the day is skipped rather than
+  delivered at lunch.
+- "Run now" is capped at five a day and refused while a brief is live.
+- The whole thing is inert when COS Control's "Background jobs" switch is off
+  or maintenance admissions are closed. The prompt is read-only by contract:
+  it forbids sending, creating, or editing anything.
+
+The prompt itself carries the evidence discipline the good-morning routine
+learned the hard way: a source that cannot be read produces one honest
+"unavailable" line; nothing is invented; only items with a hard edge (a
+decision, a date, a dollar figure, an owner) make the cut; the scribe's
+extracted action-item list is never pasted verbatim. Enable the "Workspace
+skill" source with `/good-morning` and that skill's output IS the brief —
+which is how Miles's own routine rides this without being rewritten.
+
+Surface:
+
+- `GET /api/morning-brief` — config, the source catalog (labels, descriptions,
+  option schemas a settings screen can render), status with `nextRunAt`, and
+  recent runs with live job status and the message number each produced.
+- `PUT /api/morning-brief` — patch any field; a bad time, zone, model, or
+  skill name is a 400 with a named code, never a silent keep.
+- `POST /api/morning-brief/run` — fire one now (202; 409 while one runs; 429
+  past the daily cap).
+- `GET /api/morning-brief/preview` — the exact prompt today's brief would send.
+- `/api/health` advertises `features.morningBrief` and
+  `capabilities.morningBrief` (`enabled`, `time`, `timezone`, `nextRunAt`,
+  `lastRunAt`, `lastRunStatus`, `gate`) — times and gate only, no prompt, no
+  ids.
+
+Config lives at `~/.cos-glasses/data/morning-brief/config.json` (0600), the
+ledger beside it. `COS_MORNING_BRIEF_DIR` relocates both. Schedule arithmetic
+uses Node's Intl in the configured IANA zone, and is covered across both US DST
+transitions and a zone east of UTC.
+
+## 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 +126,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/README.md

@@ -208,6 +208,29 @@ Telegram activity export is disabled by default even when a private COS
 pipeline contains `.telegram_config.json`; enable it only with the explicit
 `COS_TELEGRAM_NOTIFICATIONS=1` opt-in.
 
+## Morning brief (6.43.0)
+
+A start-of-day brief runs on a schedule inside the server and waits in the
+inbox as a numbered reply. Default: weekdays at 07:00 in the Mac's timezone,
+with Calendar, recent-meeting decisions, tasks due this week, and what is
+waiting on you. Turn on more sources (knowledge graph, reflection, health, an
+opening reading, a metrics pulse, one of your own skills such as
+`/good-morning`, a custom section), reorder them, and set their windows from
+COS Control or the companion, or directly:
+
+```bash
+curl -H "X-COS-Token: $COS_TOKEN" http://127.0.0.1:3141/api/morning-brief
+curl -H "X-COS-Token: $COS_TOKEN" -X PUT -H 'Content-Type: application/json' \
+  -d '{"time":"06:30","sources":[{"id":"skill","enabled":true,"options":{"name":"/good-morning"}}]}' \
+  http://127.0.0.1:3141/api/morning-brief
+curl -H "X-COS-Token: $COS_TOKEN" -X POST http://127.0.0.1:3141/api/morning-brief/run
+```
+
+One provider run per local day, remembered in a ledger so a restart never
+doubles it; a Mac asleep at the slot still fires inside a three-hour catch-up
+window; "Run now" is capped at five a day. Off entirely when Background jobs
+are off. The brief is read-only by contract.
+
 ## Speaker diarization (opt-in)
 
 Without a voiceprint model this server does not classify speakers at all — it

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.43.0",
   "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

@@ -83,6 +83,8 @@ import { initializeServerInstanceId } from './lib/server-instance-id.js'
 import { appendPrivateEnvBlock, UnsafeUserConfigPathError } from './lib/secure-user-config.js'
 import { getTranscriptionProfileStatus } from './lib/profile.js'
 import { createQueryJobsRouter } from './routes/query-jobs.js'
+import { createMorningBriefRouter } from './routes/morning-brief.js'
+import { getMorningBriefScheduler, startMorningBriefScheduler, stopMorningBriefScheduler } from './lib/morning-brief-runtime.js'
 import {
   initQueryJobRuntime,
   preparePublicDurableQueryAdmission,
@@ -181,9 +183,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
@@ -487,6 +490,9 @@ app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
   prepareAdmission: preparePublicDurableQueryAdmission,
 }))
 app.use('/api', queryRouter)
+// The scheduled start-of-day brief: settings, status, run-now. Same auth as
+// every other settings route; the brief itself is an ordinary durable job.
+app.use('/api', createMorningBriefRouter(getMorningBriefScheduler))
 app.use('/api', providerProofRouter)
 app.use('/api', transcribeRouter)
 // Ported from cos-glasses-app in 6.24.0. The companion's Sessions tab has been
@@ -712,6 +718,7 @@ async function gracefulShutdown(): Promise<void> {
   gracefulShutdownStarted = true
   const forceExit = setTimeout(() => process.exit(1), 8_000)
   forceExit.unref?.()
+  stopMorningBriefScheduler()
   try {
     await shutdownQueryJobRuntime('server_shutdown')
   } catch (error) {
@@ -908,6 +915,10 @@ listenRequiredServers(listeners).then(() => {
       } else {
         console.log('[COS API] Durable query jobs: disabled by COS_DURABLE_QUERY_JOBS=0')
       }
+      // The morning brief rides the durable coordinator, so it starts only once
+      // that store is ready. Its own tick checks the durable-jobs switch and the
+      // maintenance gate, so starting it here is safe when either is off.
+      startMorningBriefScheduler()
     }).catch(error => {
       // The store remains degraded and rejects admission. Legacy /api/query is
       // still mounted, so the kill switch is an immediate rollback.

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'
 }