refactor(split): decouple app from website in preparation for the repo split

Phase 0 of the OpenSquawk repo separation. Everything happens inside the
monorepo so that the split itself becomes a mechanical path filter — filtering
first and repairing afterwards would leave two broken repos at once.

AUTH_MODE (0.1)
  New server/utils/authMode.ts, session.ts and jwt.ts (the latter extracted
  from auth.ts). requireUserSession now resolves in three steps: the app's own
  session cookie, an app-minted bearer token, then the website access token.
  Only the last one is transitional; it is marked PHASE 1 and disappears with
  the User collection. The app's session is its own JWT in a host-only cookie
  plus a short-lived bearer, so the existing Authorization call sites are
  unchanged.

  AUTH_MODE defaults to 'sso', not 'open' as the plan proposed: while the admin
  and editor surface still lives here, an unset variable would otherwise serve
  it to everyone as a local admin. requireAdmin additionally refuses in open
  mode. Both are one-line removals in Phase 1 and marked as such.

SSO handoff (0.2)
  Issuer: /api/service/auth/sso/{authorize,exchange}. Codes are stored as
  SHA-256 hashes with a TTL index and claimed by a single atomic update, so
  concurrent redemption cannot succeed twice. redirect_uri is matched against
  SSO_REDIRECT_ORIGINS by exact origin — a prefix check would accept
  app.opensquawk.de.evil.tld. There is no default and no wildcard: an empty
  allowlist disables the handoff rather than opening a redirector.
  Consumer: /api/auth/sso/callback plus app/pages/auth/callback.vue. The
  browser only ever carries the code; it is redeemed server-to-server.

Hardcoded values and leaks (0.3)
  Hotjar ID, the dome-light webhook URL and the bug-report recipient were
  compiled in. All three are env-gated and off by default now, so a foreign
  instance cannot ship analytics, cockpit telemetry or its users' bug reports
  to us. Setting HOTJAR_ID, DOME_LIGHT_WEBHOOK_URL and BUG_REPORT_NOTIFY_EMAIL
  restores the current behaviour on opensquawk.de.

Two databases, no shared Mongo (0.6)
  AppUser mirrors an identity locally. Its _id is deliberately the SSO subject,
  i.e. the website's User._id, so every existing LearnProfile, PilotProfile and
  BridgeToken reference keeps resolving without a migration.
  telemetry.ts mirrors records to the hosted service only when TELEMETRY_URL
  and SERVICE_SECRET are both set — the self-host default is that nothing ever
  leaves the instance. It writes locally first, buffers with a bound, drops on
  overflow and never blocks the request path.
  /api/service/user-deleted purges the app's half on account deletion. Unlike
  telemetry this is deliberately loud: the admin delete aborts with the user
  intact if the purge fails, because their id is the only handle for retrying.
  ?force=true overrides it and says so in the response.

Also here
  /api/service/analytics/product-session was an unauthenticated public write
  endpoint; it moves to /api/analytics/product-session behind the auth guard.
  The bridge no longer populates against User but resolves through the mirror,
  backfilling missing rows so live bridges never have to re-pair.
  .claude/worktrees was tracked and would have reached the public repo.

scripts/split-paths.txt carries the filter list, verified by
scripts/verify-split-paths.mjs: every path exists, nothing website-only is
kept, and no kept file imports a dropped one. That check found real gaps —
tests/ cannot be taken wholesale, and two shared modules were missing. Ten
remaining edges are allowlisted, each annotated PHASE 1 in the code.

Open item, flagged and not resolved: flightlabTelemetryStore is an in-process
singleton written by the bridge (app) and read by FlightLab (website). Two
repos means two processes, so that read breaks regardless of which side it
lands on. FlightLab needs an HTTP path in Phase 2/3.

Verified: 609 tests pass, vue-tsc clean. Ran against two throwaway local
MongoDBs: open mode reaches /classroom and /live-atc with no login and
persists progress; the full SSO loop works and the mirror _id matches the
website User._id; lookalike origins, code reuse, forged codes and wrong
service secrets are all rejected; ingest is idempotent on bug-report code;
deletion purges all five collections; and with the app unreachable the admin
delete fails 502 with the user still present.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

server/utils/auth.ts

@@ -1,9 +1,13 @@
 import { createError, getHeader, H3Event, setCookie, deleteCookie } from 'h3'
 import { useRuntimeConfig } from '#imports'
-import { createHmac, randomBytes, timingSafeEqual, scrypt as _scrypt } from 'node:crypto'
+import { randomBytes, timingSafeEqual, scrypt as _scrypt } from 'node:crypto'
 import { promisify } from 'node:util'
 import type { UserDocument } from '../models/User'
 import { User } from '../models/User'
+import { AppUser } from '../models/AppUser'
+import { createJwtToken, verifyJwtToken } from './jwt'
+import { getAuthMode, getLocalAppUser, mirrorAppUser } from './authMode'
+import { readAppSession, verifyAppAccessToken } from './session'
 
 const scrypt = promisify(_scrypt) as (password: string | Buffer, salt: string | Buffer, keylen: number) => Promise<Buffer>
 
@@ -24,49 +28,6 @@ function getSecrets() {
   }
 }
 
-function base64url(buffer: Buffer) {
-  return buffer.toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
-}
-
-function fromBase64url(input: string) {
-  let sanitized = input.replace(/-/g, '+').replace(/_/g, '/')
-  const pad = sanitized.length % 4
-  if (pad === 2) sanitized += '=='
-  else if (pad === 3) sanitized += '='
-  else if (pad !== 0) sanitized += '===' 
-  return Buffer.from(sanitized, 'base64')
-}
-
-function createJwtToken(payload: Record<string, any>, secret: string, ttlSeconds: number) {
-  const header = { alg: 'HS256', typ: 'JWT' }
-  const now = Math.floor(Date.now() / 1000)
-  const body = { ...payload, iat: now, exp: now + ttlSeconds }
-  const encodedHeader = base64url(Buffer.from(JSON.stringify(header)))
-  const encodedPayload = base64url(Buffer.from(JSON.stringify(body)))
-  const data = `${encodedHeader}.${encodedPayload}`
-  const signature = createHmac('sha256', secret).update(data).digest()
-  return `${data}.${base64url(signature)}`
-}
-
-function verifyJwtToken(token: string, secret: string) {
-  const parts = token.split('.')
-  if (parts.length !== 3) throw new Error('Malformed token')
-  const [encodedHeader, encodedPayload, signature] = parts
-  const data = `${encodedHeader}.${encodedPayload}`
-  const expectedSignature = createHmac('sha256', secret).update(data).digest()
-  const receivedSignature = fromBase64url(signature)
-  if (receivedSignature.length !== expectedSignature.length || !timingSafeEqual(receivedSignature, expectedSignature)) {
-    throw new Error('Invalid signature')
-  }
-  const header = JSON.parse(fromBase64url(encodedHeader).toString('utf8'))
-  if (header.alg !== 'HS256') throw new Error('Unsupported algorithm')
-  const payload = JSON.parse(fromBase64url(encodedPayload).toString('utf8'))
-  if (payload.exp && Math.floor(Date.now() / 1000) > payload.exp) {
-    throw new Error('Token expired')
-  }
-  return payload as Record<string, any>
-}
-
 export async function hashPassword(password: string) {
   const salt = randomBytes(PASSWORD_SALT_BYTES)
   const derived = await scrypt(password, salt, PASSWORD_KEYLEN)
@@ -155,21 +116,61 @@ export function getDevBypassUser(): UserDocument {
   } as unknown as UserDocument
 }
 
+/** Resolve an identity from the app's own mirror — no `User` lookup involved. */
+async function resolveAppUser(sub: string) {
+  const appUser = await AppUser.findById(sub)
+  if (!appUser) return null
+  return appUser as unknown as UserDocument
+}
+
 export async function resolveUserFromToken(event: H3Event) {
+  // 1. The app's own session cookie — the only path that survives the split.
+  const session = readAppSession(event)
+  if (session) {
+    const appUser = await resolveAppUser(session.sub)
+    if (appUser) return appUser
+  }
+
   const token = parseAuthorizationHeader(event)
   if (!token) return null
+
+  // 2. An app-minted bearer token (same session, carried in the header).
+  const appToken = verifyAppAccessToken(token)
+  if (appToken) {
+    return await resolveAppUser(appToken.sub)
+  }
+
+  // 3. PHASE 1 (app repo): everything below goes away together with the `User`
+  // collection. While website and app share one deployment, a website access
+  // token is still a valid way in — it is how every existing user is logged in
+  // today. Each such request also refreshes the AppUser mirror (rate-limited
+  // internally), so app-side data is already keyed correctly when the split
+  // happens.
   try {
     const { accessSecret } = getSecrets()
     const payload = verifyJwtToken(token, accessSecret)
     if (!payload?.sub) return null
     if (payload.sub === DEV_BYPASS_USER_ID && process.env.NODE_ENV !== 'production') {
-      return getDevBypassUser()
+      const devUser = getDevBypassUser()
+      await mirrorAppUser({
+        subject: DEV_BYPASS_USER_ID,
+        email: devUser.email,
+        name: devUser.name,
+        role: 'user',
+      }).catch(() => null)
+      return devUser
     }
     const user = await User.findById(payload.sub)
     if (!user) return null
     if (typeof payload.version === 'number' && payload.version !== user.tokenVersion) {
       return null
     }
+    await mirrorAppUser({
+      subject: String(user._id),
+      email: user.email,
+      name: user.name,
+      role: user.role,
+    }).catch(() => null)
     return user
   } catch {
     return null
@@ -180,6 +181,15 @@ export async function requireUserSession(event: H3Event) {
   if (event.context?.user) {
     return event.context.user as UserDocument
   }
+
+  // AUTH_MODE=open: a self-hosted instance has no login. Every request is the
+  // one local identity, resolved without ever touching the `User` collection.
+  if (getAuthMode() === 'open') {
+    const localUser = await getLocalAppUser() as unknown as UserDocument
+    event.context.user = localUser
+    return localUser
+  }
+
   const user = await resolveUserFromToken(event)
   if (!user) {
     throw createError({ statusCode: 401, statusMessage: 'Authentication required' })
@@ -190,6 +200,11 @@ export async function requireUserSession(event: H3Event) {
 
 export async function getUserFromEvent(event: H3Event) {
   if (event.context?.user) return event.context.user as UserDocument
+  if (getAuthMode() === 'open') {
+    const localUser = await getLocalAppUser() as unknown as UserDocument
+    event.context.user = localUser
+    return localUser
+  }
   const user = await resolveUserFromToken(event)
   if (user) {
     event.context.user = user
@@ -202,6 +217,13 @@ export function hasAdminRole(user: UserDocument | null | undefined) {
 }
 
 export async function requireAdmin(event: H3Event) {
+  // PHASE 1 (app repo): delete this guard together with the admin surface.
+  // The local AUTH_MODE=open identity is an admin *of its own instance*, which
+  // is correct once /api/admin/** no longer lives here. For as long as it does,
+  // an unauthenticated open-mode request must never reach it.
+  if (getAuthMode() === 'open') {
+    throw createError({ statusCode: 404, statusMessage: 'Not found' })
+  }
   const user = await requireUserSession(event)
   if (!hasAdminRole(user)) {
     throw createError({ statusCode: 403, statusMessage: 'Administratorrechte erforderlich' })

server/utils/authMode.ts

@@ -0,0 +1,135 @@
+import mongoose from 'mongoose'
+import { AppUser, type AppUserDocument, type AppUserRole } from '../models/AppUser'
+
+export type AuthMode = 'open' | 'sso'
+
+/**
+ * How this deployment obtains an identity.
+ *
+ * - `open` — self-hosted, no login at all. Every request is the one local user.
+ * - `sso`  — identity is handed over from the issuer (opensquawk.de) via a
+ *            one-time code; the app then mints and verifies its own session.
+ *
+ * There is deliberately no third mode: the app never owns passwords, invites or
+ * password resets. Entitlement/feature-gating must NOT be mixed in here —
+ * AUTH_MODE is an *identity* concept (see Phase 5.2 of the split plan).
+ */
+
+// The single local identity used in AUTH_MODE=open. Fixed so that profiles,
+// bridge tokens and progress survive restarts. Distinct from DEV_BYPASS_USER_ID
+// in server/utils/auth.ts, which is a separate local-dev-only bypass.
+export const LOCAL_USER_ID = '000000000000000000000010'
+export const LOCAL_USER_SUBJECT = 'local'
+const LOCAL_USER_EMAIL = 'local@opensquawk.invalid'
+const LOCAL_USER_NAME = 'Local User'
+
+export function getAuthMode(): AuthMode {
+  // PHASE 1 (app repo): flip this default to 'open' and delete the note below.
+  //
+  // The default is 'sso' for as long as the website surface (/api/admin/**,
+  // /api/editor/**, invitations, waitlist) still lives in this repo. Defaulting
+  // to 'open' here would mean that any deployment which simply forgets to set
+  // AUTH_MODE serves those endpoints to everyone as the local admin user.
+  // In the app repo that surface is gone and 'open' is the correct default.
+  const raw = (process.env.AUTH_MODE || 'sso').trim().toLowerCase()
+  return raw === 'open' ? 'open' : 'sso'
+}
+
+export function isOpenAuthMode() {
+  return getAuthMode() === 'open'
+}
+
+/**
+ * Where an unauthenticated user is sent in AUTH_MODE=sso. Empty in `open`.
+ */
+export function getAuthIssuer(): string {
+  return (process.env.NUXT_PUBLIC_AUTH_ISSUER || '').trim().replace(/\/+$/, '')
+}
+
+let localUserPromise: Promise<AppUserDocument> | null = null
+
+/**
+ * The one identity of an AUTH_MODE=open instance. Persisted (rather than kept
+ * in memory) because BridgeToken/LearnProfile/PilotProfile reference it.
+ */
+export function getLocalAppUser(): Promise<AppUserDocument> {
+  if (!localUserPromise) {
+    localUserPromise = AppUser.findOneAndUpdate(
+      { _id: LOCAL_USER_ID },
+      {
+        // _id is seeded from the filter's equality condition on insert.
+        $setOnInsert: {
+          ssoSubject: LOCAL_USER_SUBJECT,
+          email: LOCAL_USER_EMAIL,
+          name: LOCAL_USER_NAME,
+          role: 'admin',
+        },
+      },
+      { upsert: true, new: true, setDefaultsOnInsert: true },
+    ).exec().catch((err) => {
+      // Never cache a failed lookup — a transient DB outage must not disable
+      // the instance for the rest of the process lifetime.
+      localUserPromise = null
+      throw err
+    }) as Promise<AppUserDocument>
+  }
+  return localUserPromise
+}
+
+// Re-upserting the mirror on every single request would add a write to every
+// authenticated call. Subjects seen recently are skipped.
+const MIRROR_TTL_MS = 5 * 60 * 1000
+const mirroredAt = new Map<string, number>()
+
+export interface MirrorInput {
+  subject: string
+  email: string
+  name?: string
+  role?: AppUserRole
+}
+
+/**
+ * Write/refresh the local mirror of an SSO identity.
+ *
+ * When the subject is a valid ObjectId — which it is for every identity issued
+ * by opensquawk.de, where the subject *is* `User._id` — it is reused verbatim
+ * as the mirror's `_id`, so pre-existing `LearnProfile.user` / `PilotProfile.user`
+ * / `BridgeToken.user` references keep resolving without a migration
+ * (see server/models/AppUser.ts). A non-ObjectId subject from some future
+ * issuer simply gets a generated `_id` and is matched on `ssoSubject`.
+ */
+export async function mirrorAppUser(input: MirrorInput, options: { force?: boolean } = {}) {
+  const subject = String(input.subject || '').trim()
+  if (!subject) return null
+
+  const last = mirroredAt.get(subject)
+  if (!options.force && last && Date.now() - last < MIRROR_TTL_MS) {
+    return null
+  }
+
+  const update: Record<string, unknown> = {
+    ssoSubject: subject,
+    email: input.email,
+    role: input.role || 'user',
+  }
+  if (input.name !== undefined) update.name = input.name
+
+  // On insert, MongoDB seeds the document from the filter's equality
+  // conditions — so matching on _id is what carries the subject into _id.
+  const filter = mongoose.isValidObjectId(subject) ? { _id: subject } : { ssoSubject: subject }
+
+  const doc = await AppUser.findOneAndUpdate(
+    filter,
+    { $set: update },
+    { upsert: true, new: true, setDefaultsOnInsert: true },
+  ).exec()
+
+  mirroredAt.set(subject, Date.now())
+  return doc
+}
+
+/** Test seam — the mirror cache is process-local and otherwise unreachable. */
+export function resetAuthModeCaches() {
+  localUserPromise = null
+  mirroredAt.clear()
+}

server/utils/bridge.ts

@@ -1,4 +1,7 @@
 import { getHeader, type H3Event } from 'h3'
+import mongoose from 'mongoose'
+import { AppUser, type AppUserDocument } from '../models/AppUser'
+import { mirrorAppUser } from './authMode'
 
 export function normalizeBridgeToken(input: unknown) {
   if (typeof input !== 'string') {
@@ -17,3 +20,43 @@ export function normalizeBridgeToken(input: unknown) {
 export function getBridgeTokenFromHeader(event: H3Event) {
   return normalizeBridgeToken(getHeader(event, 'x-bridge-token'))
 }
+
+/**
+ * The identity behind a bridge token, from the app's own mirror.
+ *
+ * Bridge endpoints are called by the desktop app with only a token, so there is
+ * no session to resolve and no chance to refresh the mirror first. A token
+ * paired before the mirror existed would otherwise report "not connected" and
+ * push the user through pairing again, so a missing mirror row is backfilled
+ * from the website's User here rather than treated as "unknown user".
+ *
+ * PHASE 1 (app repo): drop the backfill — by then every token predates nothing
+ * and there is no User collection to read.
+ */
+export async function resolveBridgeUser(
+  user: unknown,
+): Promise<AppUserDocument | null> {
+  if (!user) return null
+
+  // Already populated by the caller's .populate('user', ...).
+  if (typeof user === 'object' && 'email' in (user as Record<string, unknown>)) {
+    return user as AppUserDocument
+  }
+
+  const userId = String((user as { _id?: unknown })?._id ?? user)
+  if (!mongoose.isValidObjectId(userId)) return null
+
+  const mirrored = await AppUser.findById(userId)
+  if (mirrored) return mirrored
+
+  const { User } = await import('../models/User')
+  const websiteUser = await User.findById(userId)
+  if (!websiteUser) return null
+
+  return await mirrorAppUser({
+    subject: String(websiteUser._id),
+    email: websiteUser.email,
+    name: websiteUser.name,
+    role: websiteUser.role,
+  }, { force: true })
+}

server/utils/jwt.ts

@@ -0,0 +1,53 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+/**
+ * Minimal HS256 JWT helpers.
+ *
+ * Extracted from server/utils/auth.ts so that the app's own session
+ * (server/utils/session.ts) can mint and verify tokens without dragging in the
+ * website-only parts of auth.ts (scrypt passwords, invite codes, password
+ * reset). Both files ship with the app repo; auth.ts's website half does not.
+ */
+
+export function base64url(buffer: Buffer) {
+  return buffer.toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
+}
+
+export function fromBase64url(input: string) {
+  let sanitized = input.replace(/-/g, '+').replace(/_/g, '/')
+  const pad = sanitized.length % 4
+  if (pad === 2) sanitized += '=='
+  else if (pad === 3) sanitized += '='
+  else if (pad !== 0) sanitized += '==='
+  return Buffer.from(sanitized, 'base64')
+}
+
+export function createJwtToken(payload: Record<string, any>, secret: string, ttlSeconds: number) {
+  const header = { alg: 'HS256', typ: 'JWT' }
+  const now = Math.floor(Date.now() / 1000)
+  const body = { ...payload, iat: now, exp: now + ttlSeconds }
+  const encodedHeader = base64url(Buffer.from(JSON.stringify(header)))
+  const encodedPayload = base64url(Buffer.from(JSON.stringify(body)))
+  const data = `${encodedHeader}.${encodedPayload}`
+  const signature = createHmac('sha256', secret).update(data).digest()
+  return `${data}.${base64url(signature)}`
+}
+
+export function verifyJwtToken(token: string, secret: string) {
+  const parts = token.split('.')
+  if (parts.length !== 3) throw new Error('Malformed token')
+  const [encodedHeader, encodedPayload, signature] = parts
+  const data = `${encodedHeader}.${encodedPayload}`
+  const expectedSignature = createHmac('sha256', secret).update(data).digest()
+  const receivedSignature = fromBase64url(signature)
+  if (receivedSignature.length !== expectedSignature.length || !timingSafeEqual(receivedSignature, expectedSignature)) {
+    throw new Error('Invalid signature')
+  }
+  const header = JSON.parse(fromBase64url(encodedHeader).toString('utf8'))
+  if (header.alg !== 'HS256') throw new Error('Unsupported algorithm')
+  const payload = JSON.parse(fromBase64url(encodedPayload).toString('utf8'))
+  if (payload.exp && Math.floor(Date.now() / 1000) > payload.exp) {
+    throw new Error('Token expired')
+  }
+  return payload as Record<string, any>
+}

server/utils/session.ts

@@ -0,0 +1,108 @@
+import { deleteCookie, getCookie, setCookie, type H3Event } from 'h3'
+import { createJwtToken, verifyJwtToken } from './jwt'
+import type { AppUserDocument } from '../models/AppUser'
+
+/**
+ * The app's *own* session — deliberately independent of the issuer.
+ *
+ * Once an identity has arrived (via the SSO exchange, or trivially in
+ * AUTH_MODE=open), the app mints a session signed with its own secret and
+ * stored in a host-only cookie on its own origin. No cross-domain cookie, no
+ * CORS, no shared secret with the website beyond the one-time exchange. After
+ * this point the app can serve every request without the issuer being reachable
+ * at all — which is the whole point: a self-hosted instance must not depend on
+ * opensquawk.de.
+ */
+
+const APP_SESSION_COOKIE = 'os_app_session'
+const APP_SESSION_TTL_SECONDS = 60 * 60 * 24 * 30
+const APP_ACCESS_TOKEN_TTL_SECONDS = 60 * 60 * 24
+
+// Marks a bearer token as minted by the app rather than by the website's
+// login. Both are HS256 and — in the monorepo, where APP_JWT_SECRET is usually
+// unset — signed with the same secret, so the payload is what tells them apart:
+// an app token resolves against AppUser, a website token against User.
+const APP_TOKEN_TYPE = 'app'
+
+export interface AppSessionPayload {
+  sub: string
+  sso: string
+  email: string
+  role: string
+}
+
+function getAppSessionSecret() {
+  // APP_JWT_SECRET lets the app run on a secret of its own; JWT_SECRET is the
+  // fallback so the monorepo keeps working with a single configured secret.
+  const secret = (process.env.APP_JWT_SECRET || process.env.JWT_SECRET || '').trim()
+  if (!secret) {
+    throw new Error('App session secret missing – bitte APP_JWT_SECRET (oder JWT_SECRET) in .env setzen')
+  }
+  return secret
+}
+
+function sessionClaims(user: AppUserDocument) {
+  return {
+    sub: String(user._id),
+    sso: user.ssoSubject,
+    email: user.email,
+    role: user.role,
+    typ: APP_TOKEN_TYPE,
+  }
+}
+
+/**
+ * Short-lived bearer token for the browser. The durable session lives in the
+ * httpOnly cookie; this is what the client puts in the Authorization header,
+ * exactly as the website's access token does today, so no call site has to
+ * change shape.
+ */
+export function createAppAccessToken(user: AppUserDocument) {
+  return createJwtToken(sessionClaims(user), getAppSessionSecret(), APP_ACCESS_TOKEN_TTL_SECONDS)
+}
+
+/**
+ * Returns the payload if `token` is an app-minted bearer token, else null —
+ * including for a well-formed website token, which must fall through to the
+ * website resolution path.
+ */
+export function verifyAppAccessToken(token: string): AppSessionPayload | null {
+  try {
+    const payload = verifyJwtToken(token, getAppSessionSecret())
+    if (payload?.typ !== APP_TOKEN_TYPE || !payload?.sub) return null
+    return {
+      sub: String(payload.sub),
+      sso: String(payload.sso || payload.sub),
+      email: String(payload.email || ''),
+      role: String(payload.role || 'user'),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function issueAppSession(event: H3Event, user: AppUserDocument) {
+  const token = createJwtToken(sessionClaims(user), getAppSessionSecret(), APP_SESSION_TTL_SECONDS)
+
+  setCookie(event, APP_SESSION_COOKIE, token, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: APP_SESSION_TTL_SECONDS,
+    // Host-only on purpose: no `domain`, so the cookie never leaks to the
+    // issuer's origin and self-hosted instances behave identically.
+    secure: process.env.NODE_ENV === 'production',
+  })
+
+  return token
+}
+
+export function readAppSession(event: H3Event): AppSessionPayload | null {
+  const token = getCookie(event, APP_SESSION_COOKIE)
+  if (!token) return null
+  return verifyAppAccessToken(token)
+}
+
+export function clearAppSession(event: H3Event) {
+  deleteCookie(event, APP_SESSION_COOKIE, { path: '/' })
+}

server/utils/telemetry.ts

@@ -0,0 +1,145 @@
+/**
+ * Outbound telemetry mirror.
+ *
+ * The app always writes to its **own** database first — that is its data, and
+ * this channel must never be a dependency of anything. Only if both
+ * TELEMETRY_URL and SERVICE_SECRET are set is a copy additionally mirrored to
+ * the hosted service's ingest endpoint.
+ *
+ * Self-host default: both unset → nothing ever leaves the instance. That is the
+ * point, not a fallback.
+ *
+ * Design constraints, all of them deliberate:
+ *  - fire-and-forget: emit() never awaits the network and never throws
+ *  - bounded buffer: on overflow the oldest entries are dropped, so a dead sink
+ *    can cost memory neither indefinitely nor unboundedly
+ *  - no retries beyond the current batch: /api/atc/say must return 200 whether
+ *    or not a log sink exists
+ *
+ * The wire contract below — {kind, payload} — is the interface between the two
+ * repos. Neither side shares a Mongoose schema with the other; each owns its
+ * own. That is what makes two independent databases possible.
+ */
+
+export type TelemetryKind =
+  | 'transmission-log'
+  | 'bug-report'
+  | 'llm-routing-decision'
+  | 'product-usage-session'
+
+export interface TelemetryEnvelope {
+  kind: TelemetryKind
+  payload: Record<string, unknown>
+  emittedAt: string
+}
+
+const MAX_BUFFERED = 500
+const MAX_BATCH = 50
+const FLUSH_DELAY_MS = 2_000
+const REQUEST_TIMEOUT_MS = 5_000
+
+const buffer: TelemetryEnvelope[] = []
+let flushTimer: ReturnType<typeof setTimeout> | null = null
+let flushing = false
+let droppedSinceLastWarning = 0
+let warnedMissingConfig = false
+
+interface TelemetryConfig {
+  url: string
+  secret: string
+}
+
+function getTelemetryConfig(): TelemetryConfig | null {
+  const url = (process.env.TELEMETRY_URL || '').trim()
+  const secret = (process.env.SERVICE_SECRET || '').trim()
+  if (!url || !secret) {
+    if (url && !secret && !warnedMissingConfig) {
+      console.warn('[telemetry] TELEMETRY_URL is set but SERVICE_SECRET is not — mirroring stays off.')
+      warnedMissingConfig = true
+    }
+    return null
+  }
+  return { url, secret }
+}
+
+export function isTelemetryEnabled() {
+  return getTelemetryConfig() !== null
+}
+
+/**
+ * Queue one record for mirroring. Returns immediately; callers do not await and
+ * do not handle errors, because a telemetry failure is not their problem.
+ */
+export function emit(kind: TelemetryKind, payload: Record<string, unknown>) {
+  if (!isTelemetryEnabled()) return
+
+  if (buffer.length >= MAX_BUFFERED) {
+    // Drop the oldest: a stalled sink must not push out fresh data forever.
+    buffer.shift()
+    droppedSinceLastWarning += 1
+  }
+
+  buffer.push({ kind, payload, emittedAt: new Date().toISOString() })
+  scheduleFlush()
+}
+
+function scheduleFlush() {
+  if (flushTimer || flushing) return
+  flushTimer = setTimeout(() => {
+    flushTimer = null
+    void flush()
+  }, FLUSH_DELAY_MS)
+  // Never hold the process open for a telemetry batch.
+  if (typeof flushTimer === 'object' && flushTimer && 'unref' in flushTimer) {
+    ;(flushTimer as unknown as { unref: () => void }).unref()
+  }
+}
+
+export async function flush() {
+  const config = getTelemetryConfig()
+  if (!config || flushing || !buffer.length) return
+
+  flushing = true
+  try {
+    if (droppedSinceLastWarning > 0) {
+      console.warn(`[telemetry] dropped ${droppedSinceLastWarning} record(s): buffer full`)
+      droppedSinceLastWarning = 0
+    }
+
+    while (buffer.length) {
+      const batch = buffer.splice(0, MAX_BATCH)
+      try {
+        await $fetch(config.url, {
+          method: 'POST',
+          headers: { 'x-service-secret': config.secret },
+          body: { records: batch },
+          timeout: REQUEST_TIMEOUT_MS,
+        })
+      } catch (error: any) {
+        // The batch is gone. Re-queueing it would let an unreachable sink build
+        // an unbounded backlog, which is exactly what this must not do.
+        console.warn(`[telemetry] mirroring ${batch.length} record(s) failed:`, error?.message || error)
+        break
+      }
+    }
+  } finally {
+    flushing = false
+    if (buffer.length) scheduleFlush()
+  }
+}
+
+/** Test seam — the buffer is module-local and otherwise unreachable. */
+export function __resetTelemetryBufferForTests() {
+  buffer.length = 0
+  droppedSinceLastWarning = 0
+  warnedMissingConfig = false
+  if (flushTimer) {
+    clearTimeout(flushTimer)
+    flushTimer = null
+  }
+}
+
+/** Test seam — inspect what is queued without flushing. */
+export function __peekTelemetryBufferForTests(): readonly TelemetryEnvelope[] {
+  return buffer
+}