@gotcos/glasses-server 6.79.2 → 6.80.0

package/server/routes/key-lanes.ts

@@ -0,0 +1,442 @@
+// Key lanes (K1, plan v4 section 3.1): `/api/key-lanes/*`.
+//
+// While keyLanesEnabled() is false, every path here falls through to the server's existing 404,
+// byte for byte, with ONE deliberate exception agreed for K1: `POST /api/key-lanes/enable`, so COS
+// Control can turn lanes on from its own Settings row without an env edit. That door answers only
+// an authenticated (X-Cos-Token, checked here as well as by the global gate), loopback,
+// non-browser request, and never while COS_KEY_LANES=0. It is the only call that creates
+// key-lanes.json. Everything else (wrong method, wrong path, phone, browser, missing token) gets
+// today's 404.
+//
+// While enabled: the exposure list in plan 3.1, nothing else. Writes are Mac only (loopback, no
+// browser Origin), so a G2 or phone request cannot add, change or remove a key. No route ever
+// returns a secret: keys go out as PublicKeyRecord (ref, kind, last 4, cap). No route logs a body.
+import express, { Router, type ErrorRequestHandler, type Request, type RequestHandler } from 'express'
+import { copyFileSync, existsSync, mkdirSync, rmSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { dataPath } from '../lib/data-dir.js'
+import {
+  keyLanesActive,
+  keyLanesEnabled,
+  keyLanesEnvSwitch,
+  keyLanesStatusProvider,
+  runKeyLanesInactiveHooks,
+  setKeyLanesEnabled,
+} from '../lib/key-lanes.js'
+import { deleteProfile, deleteProfilesFile, getProfile, listProfiles, upsertProfile, validateProfileInput } from '../lib/key-profiles.js'
+import type { BreakerState, KeyKind, KeyLanesStatusBody } from '../lib/key-relay-contract.js'
+import { KEY_REF_RE } from '../lib/key-relay-contract.js'
+import {
+  deleteKey,
+  deleteKeyStore,
+  getPublicKey,
+  isKeyKind,
+  keyShapeProblem,
+  listPublicKeys,
+  normalizeCapUsd,
+  normalizeCompatibleBaseUrl,
+  saveKey,
+  updateKeyCap,
+} from '../lib/key-store.js'
+import { isLoopbackSocket } from '../lib/network-policy.js'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
+import { curatedKeyModels, downselectKeyCatalog, getKeyCatalog, KEY_CATALOG_CURATED, type KeyCatalogModel } from '../lib/key-catalog.js'
+import { keyNoticeError } from '../lib/key-notices.js'
+import { getSharedKeyMeter } from '../lib/key-relay-meter.js'
+import { existingKeyRelay, installKeyRelaySeams } from '../lib/key-relay.js'
+
+export const KEY_LANES_ENABLE_PATH = '/api/key-lanes/enable'
+export const KEY_LEDGER_FILE = 'key-ledger.jsonl'
+export const CODEX_HOMES_DIR = 'codex-homes'
+const VALIDATE_TIMEOUT_MS = 10_000
+
+export type KeyValidation =
+  | { ok: true; limitRemainingUsd?: number; isFreeTier?: boolean }
+  | { ok: false; error: string; message: string }
+
+export interface CatalogModel {
+  id: string
+  name: string
+  inUsdPerM: number
+  outUsdPerM: number
+}
+
+export interface KeyLanesRouteDeps {
+  /** The pairing token. The door checks it itself so it never relies on mount order alone. */
+  apiToken?: () => string
+  /** Plan 10.3 provider check. Tests inject a fake; the default calls the provider once. */
+  validateKey?: (kind: KeyKind, secret: string, baseUrl?: string) => Promise<KeyValidation>
+  /** Public OpenRouter catalog (no key). Called only by GET /key-lanes/catalog. */
+  fetchCatalog?: () => Promise<CatalogModel[]>
+  downloadsDir?: () => string
+  now?: () => Date
+}
+
+// ── Who may write ────────────────────────────────────────────────────────────
+
+export type MacOnlyRefusal = 'not_loopback' | 'browser'
+
+/**
+ * Null for a request from a native client on this Mac (COS Control). A phone or G2 companion
+ * arrives on a LAN or Tailscale socket; a WebView or browser sends Origin (the companion's is
+ * `null`). An agent child on loopback with the token cannot be told apart in
+ * K1; it can still never read a secret back.
+ */
+export function macOnlyRefusal(req: Pick<Request, 'socket' | 'headers'>): MacOnlyRefusal | null {
+  if (!isLoopbackSocket(req)) return 'not_loopback'
+  // Browsers send Origin on every POST and DELETE (Fetch Metadata alone is not a tell: Node's
+  // fetch sends sec-fetch-mode too).
+  if (req.headers.origin !== undefined) return 'browser'
+  return null
+}
+
+function requestPath(req: Request): string {
+  return (req.originalUrl || req.url).split('?')[0]
+}
+
+/** The one door that answers while lanes are off. Everything it does not admit is today's 404. */
+export function enableDoorOpen(req: Request, apiToken: () => string): boolean {
+  return req.method === 'POST'
+    && requestPath(req) === KEY_LANES_ENABLE_PATH
+    && keyLanesEnvSwitch() !== 'off'
+    && timingSafeTokenEqual(req.headers['x-cos-token'], apiToken())
+    && macOnlyRefusal(req) === null
+}
+
+function admitted(req: Request, apiToken: () => string): boolean {
+  return keyLanesEnabled() || enableDoorOpen(req, apiToken)
+}
+
+const defaultApiToken = () => process.env.COS_API_TOKEN ?? ''
+
+/**
+ * Mounted at `/api/key-lanes` BEFORE the global 10 MB JSON parser. A request it does not admit
+ * passes through untouched, so the global parser and the 404 behave exactly as before. An admitted
+ * one is parsed here at 32 KB, and a malformed body is refused without echoing a byte of it (Node's
+ * JSON errors quote the input, which could be a key).
+ */
+export function createKeyLanesBodyParser(deps: Pick<KeyLanesRouteDeps, 'apiToken'> = {}): RequestHandler[] {
+  const apiToken = deps.apiToken ?? defaultApiToken
+  const parse = express.json({ limit: '32kb' })
+  const gate: RequestHandler = (req, res, next) => {
+    if (!admitted(req, apiToken)) return next()
+    parse(req, res, next)
+  }
+  const refuse: ErrorRequestHandler = (_err, req, res, next) => {
+    if (!admitted(req, apiToken)) return next(_err)
+    res.status(400).json({ error: 'bad_json', message: 'The request body is not valid JSON.' })
+  }
+  return [gate, refuse as unknown as RequestHandler]
+}
+
+// ── Provider checks (plan 10.3) ──────────────────────────────────────────────
+
+const PROVIDER_NAME: Record<KeyKind, string> = {
+  openrouter: 'OpenRouter',
+  anthropic: 'Anthropic',
+  openai: 'OpenAI',
+  'openai-compatible': 'The endpoint',
+}
+
+/** One GET per save. Never logs, never puts the key in a URL, never returns it. */
+export async function defaultValidateKey(kind: KeyKind, secret: string, baseUrl?: string): Promise<KeyValidation> {
+  const name = PROVIDER_NAME[kind]
+  const target = kind === 'openrouter' ? 'https://openrouter.ai/api/v1/key'
+    : kind === 'anthropic' ? 'https://api.anthropic.com/v1/models'
+    : kind === 'openai' ? 'https://api.openai.com/v1/models'
+    : `${baseUrl ?? ''}/models`
+  const headers: Record<string, string> = kind === 'anthropic'
+    ? { 'x-api-key': secret, 'anthropic-version': '2023-06-01' }
+    : { authorization: `Bearer ${secret}` }
+  let response: Response
+  try {
+    response = await fetch(target, { headers, signal: AbortSignal.timeout(VALIDATE_TIMEOUT_MS), redirect: 'error' })
+  } catch {
+    return { ok: false, error: 'validation_unreachable', message: `Could not reach ${name} to check the key. Try again.` }
+  }
+  if (response.status === 401 || response.status === 403) {
+    return { ok: false, error: 'key_rejected', message: `${name} rejected this key. Check it and paste it again.` }
+  }
+  if (!response.ok) return { ok: false, error: 'validation_failed', message: `${name} could not check the key (HTTP ${response.status}). Try again.` }
+  if (kind !== 'openrouter') return { ok: true }
+  let data: { limit?: unknown; limit_remaining?: unknown; is_free_tier?: unknown } | undefined
+  try { data = ((await response.json()) as { data?: typeof data }).data } catch { data = undefined }
+  if (!data) return { ok: false, error: 'validation_failed', message: 'OpenRouter sent an answer COS could not read. Try again.' }
+  if (data.limit === null || data.limit === undefined) {
+    return { ok: false, error: 'no_credit_limit', message: keyNoticeError('no_credit_limit') }
+  }
+  if (typeof data.limit_remaining === 'number' && data.limit_remaining <= 0) {
+    return { ok: false, error: 'out_of_credit', message: 'This OpenRouter key has no credit left.' }
+  }
+  return {
+    ok: true,
+    ...(typeof data.limit_remaining === 'number' ? { limitRemainingUsd: data.limit_remaining } : {}),
+    ...(typeof data.is_free_tier === 'boolean' ? { isFreeTier: data.is_free_tier } : {}),
+  }
+}
+
+// ── Catalog (plan 10.4) ──────────────────────────────────────────────────────
+
+/** The curated two (D10), from P5's key-catalog.ts, in the shape this route has always served. */
+export const CURATED_KEY_MODELS = KEY_CATALOG_CURATED.map(({ id, name, inUsdPerM, outUsdPerM, role }) => ({ id, name, inUsdPerM, outUsdPerM, role }))
+
+/** P11: the shared 24 h public catalog (key-catalog.ts). Throws when only the built-in list is known. */
+export async function defaultFetchCatalog(): Promise<CatalogModel[]> {
+  const snapshot = await getKeyCatalog().get()
+  if (snapshot.from !== 'openrouter') throw new Error('catalog unavailable')
+  return snapshot.models
+}
+
+/** The next UTC midnight: when every key's daily cap resets (plan 4.5, OpenRouter usage_daily). */
+export function keyCapResetsAt(now: Date): string {
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1)).toISOString()
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+
+const CLOSED_BREAKER: BreakerState = { open: false, failures: 0 }
+
+function statusBody(now: Date): KeyLanesStatusBody & { resetsAt: string } {
+  const provider = keyLanesStatusProvider()
+  return {
+    enabled: keyLanesEnabled(),
+    active: keyLanesActive(),
+    keys: listPublicKeys().map(k => ({
+      ref: k.ref,
+      kind: k.kind,
+      last4: k.last4,
+      capUsd: k.capUsd,
+      spentTodayUsd: provider.spentTodayUsd?.(k.ref) ?? 0,
+      breaker: provider.breaker?.(k.ref) ?? CLOSED_BREAKER,
+    })),
+    profiles: listProfiles(),
+    keyedSessionIds: provider.keyedSessionIds?.() ?? [],
+    // P11: the phone shows when today's caps reset. Never a secret: keys go out as ref and last 4.
+    resetsAt: keyCapResetsAt(now),
+  }
+}
+
+function ledgerExportName(dir: string, now: Date): string {
+  const stem = `cos-key-ledger-${now.toISOString().slice(0, 10)}`
+  let candidate = join(dir, `${stem}.jsonl`)
+  for (let n = 2; existsSync(candidate) && n < 100; n++) candidate = join(dir, `${stem}-${n}.jsonl`)
+  return candidate
+}
+
+export function createKeyLanesRouter(deps: KeyLanesRouteDeps = {}): Router {
+  const apiToken = deps.apiToken ?? defaultApiToken
+  const validateKey = deps.validateKey ?? defaultValidateKey
+  const fetchCatalog = deps.fetchCatalog ?? defaultFetchCatalog
+  const downloadsDir = deps.downloadsDir ?? (() => join(homedir(), 'Downloads'))
+  const now = deps.now ?? (() => new Date())
+
+  const router = Router()
+
+  // Off: the door or today's 404. `next('router')` leaves this router untouched.
+  router.use('/key-lanes', (req, _res, next) => {
+    if (admitted(req, apiToken)) return next()
+    return next('router')
+  })
+
+  const macOnly: RequestHandler = (req, res, next) => {
+    const refusal = macOnlyRefusal(req)
+    if (!refusal) return next()
+    return res.status(403).json({ error: 'mac_only', reason: refusal, message: 'Keys are managed in COS Control on this Mac.' })
+  }
+
+  /** After a write that may have ended the last enabled profile. */
+  const settle = async (wasActive: boolean, reason: 'disabled' | 'no_enabled_profile') => {
+    if (wasActive && !keyLanesActive()) await runKeyLanesInactiveHooks(reason)
+  }
+
+  router.post('/key-lanes/enable', macOnly, (_req, res) => {
+    setKeyLanesEnabled(true, now)
+    // P11: lanes turned on without a restart get the relay's status answers at once (map writes only).
+    installKeyRelaySeams()
+    res.json({ enabled: keyLanesEnabled(), active: keyLanesActive() })
+  })
+
+  router.post('/key-lanes/disable', macOnly, async (_req, res) => {
+    const wasActive = keyLanesActive()
+    setKeyLanesEnabled(false, now)
+    await settle(wasActive, 'disabled')
+    const forcedOn = keyLanesEnvSwitch() === 'on'
+    res.json({ enabled: keyLanesEnabled(), active: keyLanesActive(), ...(forcedOn ? { forcedOnBy: 'COS_KEY_LANES' } : {}) })
+  })
+
+  router.get('/key-lanes/status', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    res.json(statusBody(now()))
+  })
+
+  router.post('/key-lanes/keys', macOnly, async (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const body = (req.body ?? {}) as { kind?: unknown; key?: unknown; ref?: unknown; capUsd?: unknown; baseUrl?: unknown }
+    // Cap change on a saved key: no secret in the body.
+    if (body.key === undefined && typeof body.ref === 'string') {
+      const cap = normalizeCapUsd(body.capUsd)
+      if (body.capUsd === undefined || cap === null) return res.status(400).json({ error: 'invalid_cap', message: 'A daily cap is between $0.01 and $1000.' })
+      const updated = updateKeyCap(body.ref, cap)
+      if (!updated) return res.status(404).json({ error: 'unknown_key', message: 'That key is not saved on this Mac.' })
+      // P11 (plan 4.5): the relay meters against the cap Control saved, not a later file edit.
+      getSharedKeyMeter().noteSavedCap(updated.ref, updated.capUsd)
+      return res.json({ key: updated })
+    }
+    if (!isKeyKind(body.kind)) return res.status(400).json({ error: 'invalid_kind', message: 'Pick OpenRouter, Anthropic, OpenAI or a custom endpoint.' })
+    const kind = body.kind
+    const shape = keyShapeProblem(kind, body.key)
+    if (shape) return res.status(400).json({ error: 'invalid_key', message: shape })
+    const cap = normalizeCapUsd(body.capUsd)
+    if (cap === null) return res.status(400).json({ error: 'invalid_cap', message: 'A daily cap is between $0.01 and $1000.' })
+    let baseUrl: string | undefined
+    if (kind === 'openai-compatible') {
+      baseUrl = normalizeCompatibleBaseUrl(body.baseUrl) ?? undefined
+      if (!baseUrl) return res.status(400).json({ error: 'invalid_base_url', message: 'Give the endpoint URL, starting with https://.' })
+    }
+    const secret = (body.key as string).trim()
+    let check: KeyValidation
+    try {
+      check = await validateKey(kind, secret, baseUrl)
+    } catch {
+      check = { ok: false, error: 'validation_failed', message: 'COS could not check the key. Try again.' }
+    }
+    if (!check.ok) return res.status(422).json({ error: check.error, message: check.message })
+    const saved = saveKey({ kind, secret, capUsd: cap, validatedAt: now().toISOString(), ...(baseUrl ? { baseUrl } : {}) }, now)
+    getSharedKeyMeter().noteSavedCap(saved.ref, saved.capUsd)
+    return res.json({
+      key: saved,
+      ...(check.limitRemainingUsd !== undefined || check.isFreeTier !== undefined
+        ? { credit: { ...(check.limitRemainingUsd !== undefined ? { remainingUsd: check.limitRemainingUsd } : {}), ...(check.isFreeTier !== undefined ? { freeTier: check.isFreeTier } : {}) } }
+        : {}),
+    })
+  })
+
+  // Remove one key (plan 17 item 3). Refused while an enabled profile uses it, unless ?force=1,
+  // which turns those profiles off first so no turn can pick a key that is gone.
+  router.delete('/key-lanes/keys/:ref', macOnly, async (req, res) => {
+    const ref = typeof req.params.ref === 'string' ? req.params.ref : ''
+    if (!KEY_REF_RE.test(ref)) return res.status(400).json({ error: 'invalid_key_ref', message: 'Unknown key.' })
+    if (!getPublicKey(ref)) return res.status(404).json({ error: 'unknown_key', message: 'That key is not saved on this Mac.' })
+    const force = req.query.force === '1'
+    const users = listProfiles().filter(p => p.keyRef === ref && p.enabled)
+    if (users.length && !force) {
+      return res.status(409).json({
+        error: 'key_in_use',
+        message: `Turn off the profiles that use this key first: ${users.map(p => p.label).join(', ')}.`,
+        profiles: users.map(p => p.id),
+      })
+    }
+    const wasActive = keyLanesActive()
+    for (const p of users) upsertProfile({ ...p, enabled: false, updatedAt: now().toISOString() })
+    for (const p of users) existingKeyRelay()?.revokeProfile(p.id)
+    deleteKey(ref)
+    await settle(wasActive, 'no_enabled_profile')
+    return res.json({ removed: true, disabledProfiles: users.map(p => p.id), active: keyLanesActive() })
+  })
+
+  // QA U6 / C8: Control's "Reset" for a key paused after three failures (plan 4.6).
+  router.post('/key-lanes/breaker/reset', macOnly, (req, res) => {
+    const ref = (req.body as { ref?: unknown } | undefined)?.ref
+    if (typeof ref !== 'string' || !KEY_REF_RE.test(ref)) return res.status(400).json({ error: 'invalid_key_ref', message: 'Unknown key.' })
+    if (!getPublicKey(ref)) return res.status(404).json({ error: 'unknown_key', message: 'That key is not saved on this Mac.' })
+    const relay = existingKeyRelay()
+    relay?.resetBreaker('key', ref)
+    return res.json({ reset: true, breaker: relay?.breakerState('key', ref) ?? CLOSED_BREAKER })
+  })
+
+  router.post('/key-lanes/profiles', macOnly, async (req, res) => {
+    const wasActive = keyLanesActive()
+    const result = validateProfileInput((req.body ?? {}) as Record<string, unknown>, ref => getPublicKey(ref)?.kind, now)
+    if (!result.ok) return res.status(400).json({ error: result.error, message: result.message })
+    const before = getProfile(result.profile.id)
+    const write = upsertProfile(result.profile)
+    if (!write.ok) return res.status(409).json({ error: write.error, message: 'That is the most key profiles COS keeps. Remove one first.' })
+    const p = result.profile
+    if (before) {
+      const relay = existingKeyRelay()
+      // QA W5: a profile turned off or pointed elsewhere stops its live turns now.
+      if (!p.enabled || before.keyRef !== p.keyRef || before.model !== p.model || before.engine !== p.engine) relay?.revokeProfile(p.id)
+      // QA U6: a new model or key is a fresh start for the profile's breaker.
+      if (before.keyRef !== p.keyRef || before.model !== p.model) relay?.resetBreaker('profile', p.id)
+    }
+    await settle(wasActive, 'no_enabled_profile')
+    return res.json({ profile: result.profile, active: keyLanesActive() })
+  })
+
+  router.delete('/key-lanes/profiles/:id', macOnly, async (req, res) => {
+    if (!isKeyProfileId(req.params.id)) return res.status(400).json({ error: 'invalid_profile', message: 'Unknown profile id.' })
+    const wasActive = keyLanesActive()
+    const removed = deleteProfile(req.params.id)
+    if (!removed) return res.status(404).json({ error: 'unknown_profile', message: 'No profile with that id.' })
+    existingKeyRelay()?.revokeProfile(req.params.id)
+    await settle(wasActive, 'no_enabled_profile')
+    return res.json({ removed: true, active: keyLanesActive() })
+  })
+
+  router.post('/key-lanes/remove-all', macOnly, async (req, res) => {
+    const body = (req.body ?? {}) as { exportLedger?: unknown }
+    if (body.exportLedger !== undefined && typeof body.exportLedger !== 'boolean') {
+      return res.status(400).json({ error: 'invalid_request', message: 'exportLedger is true or false.' })
+    }
+    const ledger = dataPath(KEY_LEDGER_FILE)
+    let ledgerExportedTo: string | undefined
+    if (body.exportLedger === true && existsSync(ledger)) {
+      // Export first: if it fails, nothing has been removed yet.
+      try {
+        const dir = downloadsDir()
+        mkdirSync(dir, { recursive: true })
+        ledgerExportedTo = ledgerExportName(dir, now())
+        copyFileSync(ledger, ledgerExportedTo)
+      } catch {
+        return res.status(500).json({ error: 'export_failed', message: 'Could not save the spend ledger to Downloads. Nothing was removed.' })
+      }
+    }
+    // Revoke nonces and close the relay (P2), clear session bindings (P6) before the files go.
+    const hookFailures = await runKeyLanesInactiveHooks('remove_all')
+    const removed: string[] = []
+    if (deleteKeyStore()) removed.push('keys')
+    if (deleteProfilesFile()) removed.push('profiles')
+    const homes = dataPath(CODEX_HOMES_DIR)
+    if (existsSync(homes)) { rmSync(homes, { recursive: true, force: true }); removed.push('codexHomes') }
+    if (existsSync(ledger)) { unlinkSync(ledger); removed.push('ledger') }
+    setKeyLanesEnabled(false, now)
+    return res.json({
+      removed,
+      enabled: keyLanesEnabled(),
+      active: keyLanesActive(),
+      ...(ledgerExportedTo ? { ledgerExportedTo } : {}),
+      ...(hookFailures.length ? { hookFailures } : {}),
+    })
+  })
+
+  router.get('/key-lanes/catalog', async (req, res) => {
+    const q = typeof req.query.q === 'string' ? req.query.q.trim().toLowerCase().slice(0, 40) : ''
+    // QA G5: one 24 h cache (key-catalog.ts), not a second one here.
+    let models: CatalogModel[] | null
+    try {
+      models = await fetchCatalog()
+    } catch {
+      models = null
+    }
+    // P11: curated prices and lanes from P5's key-catalog.ts, the one catalog module.
+    const curated = curatedKeyModels(models as KeyCatalogModel[] | null)
+      .map(({ id, name, inUsdPerM, outUsdPerM, role }) => ({ id, name, inUsdPerM, outUsdPerM, role }))
+    // Lane B takes only anthropic/ and openai/ slugs; every other model is direct only (plan 4.4).
+    // QA G5: P5's downselect (20 rows, one 64-character lens row each, unsafe glyphs cleaned),
+    // reporting only the rows that match the search.
+    let search: Array<CatalogModel & { lanes: string[]; label: string }> | undefined
+    if (q && models) {
+      const byId = new Map(models.map(m => [m.id, m]))
+      search = downselectKeyCatalog(models as KeyCatalogModel[], { query: q })
+        .flatMap(r => {
+          const m = byId.get(r.id)
+          return m && (m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q)) ? [{ ...m, lanes: r.lanes, label: r.label }] : []
+        })
+    }
+    res.json({ curated, pricesFrom: models ? 'openrouter' : 'built-in', ...(search ? { search } : {}) })
+  })
+
+  return router
+}

package/server/routes/openai-compat.ts

@@ -13,6 +13,10 @@ import {
 } from '../lib/codex-model-catalog.js'
 import { resolveCursorPreferenceForModelId } from '../lib/cursor-model-catalog.js'
 import { tryInstantResponse } from '../lib/response-cache.js'
+import { keyLanesActive } from '../lib/key-lanes.js'
+import { KEY_PROFILE_V1_NOT_OFFERED, v1OfferedProfile, v1OfferedProfiles } from '../lib/key-profile-routing.js'
+import type { SessionModelBinding } from '../lib/conversation.js'
+import { parseV1KeyModelName, profilePreference, v1KeyModelName } from '../../shared/key-preference.js'
 
 import crypto from 'node:crypto'
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
@@ -188,10 +192,22 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
     model,
     typeof req.query.model === 'string' ? req.query.model : undefined,
   )
-  const resolvedModel = resolveModel(selectedModel, query)
+  // Key lanes K1 (plan 9.4): `cos-key-<id>` is handled BEFORE resolveModel, which stays closed.
+  // Only an active profile with "Offer on /v1" on runs; any other `cos-key-<id>` is refused, never
+  // answered on the subscription. Every other model name takes the 6.79.0 path unchanged.
+  const keyProfileId = parseV1KeyModelName(selectedModel)
+  if (keyProfileId !== undefined && !v1OfferedProfile(keyProfileId)) {
+    maintenanceLease.release()
+    return res.status(400).json({
+      error: { message: KEY_PROFILE_V1_NOT_OFFERED, type: 'invalid_request_error', code: 'model_not_offered' },
+    })
+  }
+  const resolvedModel: SessionModelBinding = keyProfileId !== undefined
+    ? profilePreference(keyProfileId) as SessionModelBinding
+    : resolveModel(selectedModel, query)
   const completionId = `chatcmpl-${crypto.randomUUID().slice(0, 12)}`
   const timestamp = Math.floor(Date.now() / 1000)
-  const responseModel = MODEL_NAMES[resolvedModel]
+  const responseModel = keyProfileId !== undefined ? v1KeyModelName(keyProfileId) : MODEL_NAMES[resolvedModel as ModelPreference]
 
   // ── Predictive response cache — bypass Claude for common queries ──
   const cached = tryInstantResponse(query)
@@ -557,7 +573,10 @@ openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
 })
 
 // GET /v1/models — required by some clients for model discovery
-openaiCompatRouter.get('/v1/models', async (_req, res) => {
+// Key lanes K1 (plan 9.4, D8): open and byte-identical until a key lane is active; then it asks
+// for the chat Bearer and lists `cos-key-<id>` for each profile offered on /v1.
+openaiCompatRouter.get('/v1/models', async (req, res) => {
+  if (keyLanesActive() && !validateAuth(req, res)) return
   const catalog = await getCodexModelCatalog()
   res.json({
     object: 'list',
@@ -574,6 +593,12 @@ openaiCompatRouter.get('/v1/models', async (_req, res) => {
 	        created: 1709251200,
 	        owned_by: 'openai',
 	      })),
+	      ...v1OfferedProfiles().map(profile => ({
+	        id: v1KeyModelName(profile.id),
+	        object: 'model',
+	        created: 1709251200,
+	        owned_by: 'cos-key',
+	      })),
 	    ],
 	  })
 	})

package/server/routes/query.ts

@@ -8,8 +8,9 @@ import { errMsg } from '../lib/utils.js'
 import {
   isCursorModel,
   normalizeEffortPreference,
-  normalizeModelPreference,
 } from '../../shared/model-preference.js'
+import { parsePreference } from '../../shared/key-preference.js'
+import type { KeyProfileTurn } from '../lib/key-profile-routing.js'
 import { QueryAttachmentError, resolveQueryAttachments } from '../lib/query-attachments.js'
 import { getMediaStore } from '../lib/media-store.js'
 import { mergeMediaAttachmentRefs } from '../../shared/media-attachment.js'
@@ -19,6 +20,8 @@ import {
   maintenanceErrorPayload,
 } from '../lib/maintenance-lifecycle.js'
 import { currentMessageEra, LEGACY_MESSAGE_ERA } from '../lib/message-era.js'
+import { keyAnswerDoneFields } from '../lib/key-answer-fields.js'
+import { isProfilePreference } from '../../shared/key-preference.js'
 
 const TOOL_STATUS_MESSAGES: Record<string, string> = {
   WebSearch: 'Searching web...',
@@ -92,8 +95,11 @@ queryRouter.post('/query', async (req, res) => {
     return res.status(400).json({ error: 'query string or attachment required' })
   }
 
-  // Validate model if provided
-  const validModel = normalizeModelPreference(model)
+  // Validate model if provided. Key lanes K1 (plan 5.2): Accept. A `profile:<id>` is passed to
+  // model-router as is (it runs on the profile or is refused there); every family guard below
+  // reads the closed slot, so a model slot behaves exactly as before.
+  const requestedBinding = parsePreference(model)
+  const validModel = requestedBinding?.kind === 'model' ? requestedBinding.value : undefined
   const validEffort = normalizeEffortPreference(effort)
 
   // Validate globalMsgNum if provided
@@ -136,12 +142,17 @@ queryRouter.post('/query', async (req, res) => {
     done = true
   })
 
+  // Set only by model-router's onKeyProfileTurn: the binding is the turn's model on the stream.
+  let keyTurn: KeyProfileTurn | undefined
   try {
     const sid = await callModelStreaming(resolvedQuery || '', sessionId, {
+      ...(requestedBinding?.kind === 'model' ? {} : {
+        onKeyProfileTurn: (turn: KeyProfileTurn) => { keyTurn = turn },
+      }),
       onStart: (model, sid, cliSessionId, metadata) => {
         streamSessionId = sid
         if (!done) {
-          const payload = { model, sessionId: sid, cliSessionId, ...metadata }
+          const payload = { model: keyTurn ? keyTurn.binding : model, sessionId: sid, cliSessionId, ...metadata }
           res.write(`event: start\ndata: ${JSON.stringify(payload)}\n\n`)
           emitDisplay({ type: 'start', data: payload })
         }
@@ -192,7 +203,8 @@ queryRouter.post('/query', async (req, res) => {
             const attachments = mergeMediaAttachmentRefs(attachmentRefs, metadata?.outputAttachments)
             const { outputAttachments: _outputAttachments, ...runMetadata } = metadata ?? {}
             const payload = {
-              text: fullText, sessionId: streamSessionId, model, cliSessionId, ...runMetadata,
+              text: fullText, sessionId: streamSessionId, model: keyTurn ? keyTurn.binding : model, cliSessionId, ...runMetadata,
+              ...keyAnswerDoneFields(runMetadata),
               ...(attachments.length > 0 ? { attachments } : {}),
             }
             res.write(`event: done\ndata: ${JSON.stringify(payload)}\n\n`)
@@ -215,7 +227,7 @@ queryRouter.post('/query', async (req, res) => {
           maintenanceLease.release()
         }
       },
-    }, validModel, imageInputs,
+    }, requestedBinding?.kind === 'profile' ? model as KeyProfileTurn['binding'] : validModel, imageInputs,
       // Pass reference if provided (for "recall message N" feature)
       reference && typeof reference === 'object' && reference.query && reference.response
         ? { query: String(reference.query), response: String(reference.response) }
@@ -228,6 +240,8 @@ queryRouter.post('/query', async (req, res) => {
         requestAttachments: attachmentRefs,
         attachmentPromptBlock: resolvedAttachments.promptBlock,
         ...(validModel && isCursorModel(validModel) ? { cursorExecutionMode } : {}),
+        // QA U9: the one-turn plan-limit offer runs on the key without binding the session.
+        ...(req.body.keyTurnOnly === true && isProfilePreference(model) ? { keyTurnOnly: true } : {}),
       },
     )
   } catch (err: unknown) {

package/shared/key-preference.ts

@@ -0,0 +1,57 @@
+// Key lanes (K1, plan v4 section 5.1): the ONE parser that may read a key profile out of a model
+// preference. `isModelPreference` and `normalizeModelPreference` (model-preference.ts) stay
+// closed and unchanged, so every site that does not call parsePreference keeps refusing a
+// profile exactly as 6.79.0 does. Call this only at the sites plan 5.2 marks Accept.
+//
+// Encoding: a profile-bound preference is `profile:<id>`. The prefix keeps a profile id from ever
+// colliding with a model slot name (`opus` is a valid id shape). On `/v1` a profile is offered as
+// `cos-key-<id>` (plan 9.4), handled before `resolveModel` and only for profiles that opt in.
+import { normalizeModelPreference, type ModelPreference } from './model-preference.js'
+
+export const KEY_PROFILE_ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/
+export const KEY_PROFILE_PREFERENCE_PREFIX = 'profile:'
+export const V1_KEY_MODEL_PREFIX = 'cos-key-'
+
+export type ParsedPreference =
+  | { kind: 'model'; value: ModelPreference }
+  | { kind: 'profile'; id: string }
+
+export function isKeyProfileId(value: unknown): value is string {
+  return typeof value === 'string' && KEY_PROFILE_ID_RE.test(value)
+}
+
+/** `profile:<id>`, or throws on a malformed id (a caller bug, never user input). */
+export function profilePreference(id: string): string {
+  if (!isKeyProfileId(id)) throw new Error('invalid key profile id')
+  return KEY_PROFILE_PREFERENCE_PREFIX + id
+}
+
+/**
+ * A model slot (normalized exactly as normalizeModelPreference does, so `codex-high` still
+ * migrates), a `profile:<id>`, or undefined for anything else. Never throws.
+ */
+export function parsePreference(value: unknown): ParsedPreference | undefined {
+  const model = normalizeModelPreference(value)
+  if (model) return { kind: 'model', value: model }
+  if (typeof value !== 'string' || !value.startsWith(KEY_PROFILE_PREFERENCE_PREFIX)) return undefined
+  const id = value.slice(KEY_PROFILE_PREFERENCE_PREFIX.length)
+  return isKeyProfileId(id) ? { kind: 'profile', id } : undefined
+}
+
+/** True only for a well-formed `profile:<id>`. A model slot is false. */
+export function isProfilePreference(value: unknown): boolean {
+  return parsePreference(value)?.kind === 'profile'
+}
+
+/** `/v1` model name for a profile (plan 9.4). */
+export function v1KeyModelName(id: string): string {
+  if (!isKeyProfileId(id)) throw new Error('invalid key profile id')
+  return V1_KEY_MODEL_PREFIX + id
+}
+
+/** The profile id in a `cos-key-<id>` `/v1` model name, or undefined. */
+export function parseV1KeyModelName(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value.startsWith(V1_KEY_MODEL_PREFIX)) return undefined
+  const id = value.slice(V1_KEY_MODEL_PREFIX.length)
+  return isKeyProfileId(id) ? id : undefined
+}