@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/relay/identity.test.js

@@ -4,52 +4,43 @@ import crypto from 'node:crypto';
 import { createRelayIdentityRuntime } from './identity.js';
 import { canonicalPublicJwkString } from './signing-key.js';
 
-// In-memory settings store standing in for the on-disk settings file.
-const makeSettingsStore = (initial = {}) => {
-  let settings = { ...initial };
+// In-memory key store standing in for the on-disk relay identity file.
+const makeKeyStore = (initial = {}) => {
+  const slots = { ...initial };
   return {
-    readSettingsFromDiskMigrated: async () => ({ ...settings }),
-    writeSettingsToDisk: async (next) => {
-      settings = { ...next };
-    },
-    peek: () => settings,
+    getOrCreate: async (slot, generate) => (slots[slot] ??= await generate()),
+    peek: () => slots,
   };
 };
 
 describe('relay identity', () => {
   it('derives a stable serverId from the signing key and persists both keypairs', async () => {
-    const store = makeSettingsStore();
-    const runtime = createRelayIdentityRuntime({ crypto, ...store });
+    const relayKeyStore = makeKeyStore();
+    const runtime = createRelayIdentityRuntime({ crypto, relayKeyStore });
     const identity = await runtime.getRelayIdentity();
 
-    const stored = store.peek();
-    expect(stored.relaySigningKey).toBeDefined();
-    expect(stored.relayEncryptionKey).toBeDefined();
+    const stored = relayKeyStore.peek();
+    expect(stored.signing).toBeDefined();
+    expect(stored.encryption).toBeDefined();
 
     const expectedServerId = crypto
       .createHash('sha256')
-      .update(canonicalPublicJwkString(stored.relaySigningKey.publicJwk))
+      .update(canonicalPublicJwkString(stored.signing.publicJwk))
       .digest('base64url');
     expect(identity.serverId).toBe(expectedServerId);
     expect(identity.hostEncPubJwk.crv).toBe('P-256');
   });
 
   it('reuses an existing signing key (serverId stays stable across installs)', async () => {
-    const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
-    void privateKey;
-    const publicJwk = publicKey.export({ format: 'jwk' });
-    const store = makeSettingsStore({
-      relaySigningKey: {
-        privateJwk: crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' }).privateKey.export({ format: 'jwk' }),
-        publicJwk,
+    const pair = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+    const relayKeyStore = makeKeyStore({
+      signing: {
+        privateJwk: pair.privateKey.export({ format: 'jwk' }),
+        publicJwk: pair.publicKey.export({ format: 'jwk' }),
       },
     });
-    // Match private to public so importing works.
-    const pair = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
-    store.peek().relaySigningKey.privateJwk = pair.privateKey.export({ format: 'jwk' });
-    store.peek().relaySigningKey.publicJwk = pair.publicKey.export({ format: 'jwk' });
 
-    const runtime = createRelayIdentityRuntime({ crypto, ...store });
+    const runtime = createRelayIdentityRuntime({ crypto, relayKeyStore });
     const identity = await runtime.getRelayIdentity();
     const expected = crypto
       .createHash('sha256')
@@ -59,8 +50,7 @@ describe('relay identity', () => {
   });
 
   it('produces a verifiable relay auth signature', async () => {
-    const store = makeSettingsStore();
-    const runtime = createRelayIdentityRuntime({ crypto, ...store });
+    const runtime = createRelayIdentityRuntime({ crypto, relayKeyStore: makeKeyStore() });
     const identity = await runtime.getRelayIdentity();
     const { ts, sig, pk } = identity.signRelayAuth('host-control', null);
 

package/server/lib/relay/key-store.js

@@ -0,0 +1,141 @@
+// Host relay identity keys (the signing and encryption keypairs, private JWKs
+// included) live in their own 0600 file, `<data-dir>/relay-identity.json`,
+// not in settings.json, so the private keys do not travel with every copy of
+// the settings file.
+//
+// Installs that predate the split keep the keys in settings.json as
+// `relaySigningKey` / `relayEncryptionKey`. The first load moves them here
+// unchanged, so serverId and the E2EE trust anchor stay the same, then strips
+// them from settings.json. An older build sharing the data dir no longer finds
+// them there and mints its own identity, which it warns about loudly.
+//
+// A key is minted only when neither file holds it. Both files are read
+// strictly: a corrupt or unreadable file throws instead of reading as "first
+// run", because a new key orphans every paired device and push binding.
+
+import { z } from 'zod';
+
+const SLOTS = Object.freeze({
+  signing: { field: 'signingKey', legacySettingsKey: 'relaySigningKey' },
+  encryption: { field: 'encryptionKey', legacySettingsKey: 'relayEncryptionKey' },
+});
+
+const jwkSchema = z.looseObject({ kty: z.string().min(1) });
+const jwkPairSchema = z.looseObject({ privateJwk: jwkSchema, publicJwk: jwkSchema });
+// Unknown fields are kept so a newer build's additions survive our rewrites.
+const storeSchema = z.looseObject({
+  signingKey: jwkPairSchema.optional(),
+  encryptionKey: jwkPairSchema.optional(),
+});
+
+/** @typedef {z.infer<typeof jwkPairSchema>} RelayJwkPair */
+/** @typedef {'signing' | 'encryption'} RelayKeySlot */
+
+const isJwkPair = (value) => jwkPairSchema.safeParse(value).success;
+
+/**
+ * @param {{
+ *   fsPromises: typeof import('node:fs/promises'),
+ *   path: typeof import('node:path'),
+ *   dataDir: string,
+ *   readSettingsFromDiskMigrated: () => Promise<object>,
+ *   readSettingsStrict: () => Promise<object>,
+ *   writeSettingsToDisk: (settings: object) => Promise<void>,
+ *   logger?: Pick<Console, 'warn'>,
+ * }} deps
+ */
+export const createRelayKeyStore = ({
+  fsPromises,
+  path,
+  dataDir,
+  readSettingsFromDiskMigrated,
+  readSettingsStrict,
+  writeSettingsToDisk,
+  logger = console,
+}) => {
+  const filePath = path.join(dataDir, 'relay-identity.json');
+  // The push relay and the private relay ask for the signing key at the same
+  // boot; serialized, the second caller reads what the first one wrote
+  // instead of minting a second key over it.
+  let queue = Promise.resolve();
+  const serialized = (task) => {
+    const run = queue.then(task, task);
+    queue = run.catch(() => {});
+    return run;
+  };
+
+  const readStore = async () => {
+    let raw;
+    try {
+      raw = await fsPromises.readFile(filePath, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return {};
+      throw error;
+    }
+    const corrupt = (cause) => new Error(`Relay identity file is corrupt: ${filePath} (fix or remove it, then retry)`, { cause });
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch (cause) {
+      throw corrupt(cause);
+    }
+    const parsed = storeSchema.safeParse(json);
+    if (!parsed.success) throw corrupt(parsed.error);
+    return parsed.data;
+  };
+
+  const writeStore = async (store) => {
+    const directory = path.dirname(filePath);
+    const created = await fsPromises.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (created && process.platform !== 'win32') await fsPromises.chmod(directory, 0o700);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+      await fsPromises.writeFile(tmp, JSON.stringify(store, null, 2), { encoding: 'utf8', mode: 0o600 });
+      if (process.platform !== 'win32') await fsPromises.chmod(tmp, 0o600);
+      await fsPromises.rename(tmp, filePath);
+    } catch (error) {
+      await fsPromises.rm(tmp, { force: true }).catch(() => {});
+      throw error;
+    }
+  };
+
+  // Drops from settings.json every legacy key this file already holds. Best
+  // effort: the identity is valid without it, and the next load retries.
+  const scrubLegacySettings = async (store) => {
+    try {
+      const raw = await readSettingsStrict();
+      const stale = Object.values(SLOTS)
+        .filter(({ field, legacySettingsKey }) => isJwkPair(store[field]) && Object.hasOwn(raw, legacySettingsKey))
+        .map(({ legacySettingsKey }) => legacySettingsKey);
+      if (stale.length === 0) return;
+      const next = { ...(await readSettingsFromDiskMigrated()), ...raw };
+      for (const key of stale) delete next[key];
+      await writeSettingsToDisk(next);
+    } catch (error) {
+      logger.warn('[relay-identity] Could not remove the moved relay keys from settings.json:', error);
+    }
+  };
+
+  /**
+   * @param {RelayKeySlot} slot
+   * @param {() => Promise<RelayJwkPair>} generate Mints a new keypair; called only when no file holds one.
+   * @returns {Promise<RelayJwkPair>}
+   */
+  const getOrCreate = (slot, generate) => serialized(async () => {
+    const { field, legacySettingsKey } = SLOTS[slot];
+    let store = await readStore();
+    if (!isJwkPair(store[field])) {
+      const legacy = (await readSettingsStrict())[legacySettingsKey];
+      // Another process may have moved or minted the key between the two reads.
+      store = await readStore();
+      if (!isJwkPair(store[field])) {
+        store = { ...store, [field]: isJwkPair(legacy) ? legacy : await generate() };
+        await writeStore(store);
+      }
+    }
+    await scrubLegacySettings(store);
+    return store[field];
+  });
+
+  return { getOrCreate };
+};

package/server/lib/relay/key-store.test.js

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { createRelayKeyStore } from './key-store.js';
+
+const makePair = () => {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+  return { privateJwk: privateKey.export({ format: 'jwk' }), publicJwk: publicKey.export({ format: 'jwk' }) };
+};
+
+let dataDir;
+beforeEach(() => {
+  dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'oc-relay-keys-'));
+});
+afterEach(() => {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+});
+
+const identityPath = () => path.join(dataDir, 'relay-identity.json');
+const settingsPath = () => path.join(dataDir, 'settings.json');
+const readJson = (filePath) => JSON.parse(fs.readFileSync(filePath, 'utf8'));
+const writeJson = (filePath, value) => fs.writeFileSync(filePath, JSON.stringify(value));
+
+// Settings accessors over a real settings.json, strict like the app's.
+const makeStore = ({ writeSettingsToDisk } = {}) => {
+  const readSettingsStrict = async () => {
+    try {
+      return JSON.parse(fs.readFileSync(settingsPath(), 'utf8'));
+    } catch (error) {
+      if (error.code === 'ENOENT') return {};
+      throw error;
+    }
+  };
+  return createRelayKeyStore({
+    fsPromises: fs.promises,
+    path,
+    dataDir,
+    readSettingsFromDiskMigrated: async () => readSettingsStrict().catch(() => ({})),
+    readSettingsStrict,
+    writeSettingsToDisk: writeSettingsToDisk ?? (async (next) => writeJson(settingsPath(), next)),
+    logger: { warn: () => {} },
+  });
+};
+
+describe('relay key store', () => {
+  it('mints a key on first run into its own owner-only file, not settings.json', async () => {
+    writeJson(settingsPath(), { theme: 'dark' });
+    const pair = makePair();
+    let generations = 0;
+    const stored = await makeStore().getOrCreate('signing', async () => {
+      generations += 1;
+      return pair;
+    });
+
+    expect(stored).toEqual(pair);
+    expect(generations).toBe(1);
+    expect(readJson(identityPath()).signingKey).toEqual(pair);
+    expect(readJson(settingsPath())).toEqual({ theme: 'dark' });
+    if (process.platform !== 'win32') {
+      expect(fs.statSync(identityPath()).mode & 0o777).toBe(0o600);
+    }
+  });
+
+  it('moves legacy keys out of settings.json unchanged and keeps the other settings', async () => {
+    const signing = makePair();
+    const encryption = makePair();
+    writeJson(settingsPath(), { theme: 'dark', relaySigningKey: signing, relayEncryptionKey: encryption });
+    const store = makeStore();
+    const mint = async () => {
+      throw new Error('must not mint a key that settings.json already holds');
+    };
+
+    expect(await store.getOrCreate('signing', mint)).toEqual(signing);
+    expect(await store.getOrCreate('encryption', mint)).toEqual(encryption);
+
+    expect(readJson(identityPath())).toEqual({ signingKey: signing, encryptionKey: encryption });
+    expect(readJson(settingsPath())).toEqual({ theme: 'dark' });
+  });
+
+  it('strips from settings.json only the keys the identity file already holds', async () => {
+    writeJson(settingsPath(), { relaySigningKey: makePair(), relayEncryptionKey: makePair() });
+    await makeStore().getOrCreate('signing', async () => makePair());
+
+    const settings = readJson(settingsPath());
+    expect(settings.relaySigningKey).toBeUndefined();
+    expect(settings.relayEncryptionKey).toBeDefined();
+  });
+
+  it('keeps the identity file authoritative over a key an older build put back into settings.json', async () => {
+    const current = makePair();
+    writeJson(identityPath(), { signingKey: current });
+    writeJson(settingsPath(), { relaySigningKey: makePair() });
+
+    expect(await makeStore().getOrCreate('signing', async () => makePair())).toEqual(current);
+    expect(readJson(settingsPath()).relaySigningKey).toBeUndefined();
+  });
+
+  it('mints one key when two callers ask at the same time', async () => {
+    const store = makeStore();
+    let generations = 0;
+    const mint = async () => {
+      generations += 1;
+      return makePair();
+    };
+    const [first, second] = await Promise.all([store.getOrCreate('signing', mint), store.getOrCreate('signing', mint)]);
+
+    expect(generations).toBe(1);
+    expect(second).toEqual(first);
+  });
+
+  it('refuses to mint over a corrupt identity file', async () => {
+    fs.writeFileSync(identityPath(), '{"signingKey": {"unfinished');
+    await expect(makeStore().getOrCreate('signing', async () => makePair())).rejects.toThrow(/corrupt/);
+    expect(fs.readFileSync(identityPath(), 'utf8')).toBe('{"signingKey": {"unfinished');
+  });
+
+  it('refuses to mint while a corrupt settings.json may still hold the legacy key', async () => {
+    fs.writeFileSync(settingsPath(), '{"relaySigningKey": {"unfinished');
+    await expect(makeStore().getOrCreate('signing', async () => makePair())).rejects.toThrow();
+    expect(fs.existsSync(identityPath())).toBe(false);
+  });
+
+  it('still returns the key when stripping settings.json fails', async () => {
+    const signing = makePair();
+    writeJson(settingsPath(), { relaySigningKey: signing });
+    const store = makeStore({
+      writeSettingsToDisk: async () => {
+        throw new Error('disk full');
+      },
+    });
+
+    expect(await store.getOrCreate('signing', async () => makePair())).toEqual(signing);
+    expect(readJson(identityPath()).signingKey).toEqual(signing);
+  });
+});

package/server/lib/relay/service.js

@@ -14,7 +14,7 @@
 import express from 'express';
 
 import { createRelayIdentityRuntime } from './identity.js';
-import { startRelayHost } from './host-client.js';
+import { describeRelayError, startRelayHost } from './host-client.js';
 import { isEnterpriseMode, readEnterprisePolicy } from '../enterprise-mode.js';
 
 export const DEFAULT_RELAY_URL = 'wss://relay.openchamber.dev/ws';
@@ -59,6 +59,7 @@ export const relayBlockedByEnterprise = () => isEnterpriseMode() && pinnedRelayU
  *   crypto: typeof import('node:crypto'),
  *   readSettingsFromDiskMigrated: () => Promise<object>,
  *   writeSettingsToDisk: (settings: object) => Promise<void>,
+ *   relayKeyStore: ReturnType<typeof import('./key-store.js').createRelayKeyStore>,
  *   getLocalPort: () => number,
  *   logger?: Pick<Console, 'warn'>,
  * }} deps
@@ -67,9 +68,8 @@ export const createRelayService = ({
   crypto,
   readSettingsFromDiskMigrated,
   writeSettingsToDisk,
-  // Strict settings reader (throws on corrupt/unreadable) gating identity
-  // regeneration — see identity.js/signing-key.js.
-  readSettingsStrict,
+  // Host relay identity keys, shared with the push relay (key-store.js).
+  relayKeyStore,
   getLocalPort,
   // Returns true when any paired device or pending pairing session uses the
   // relay transport. The relay lifecycle is driven purely by this demand.
@@ -86,7 +86,7 @@ export const createRelayService = ({
   allowPassiveHost = true,
   logger = console,
 }) => {
-  const identityRuntime = createRelayIdentityRuntime({ crypto, readSettingsFromDiskMigrated, writeSettingsToDisk, readSettingsStrict });
+  const identityRuntime = createRelayIdentityRuntime({ crypto, relayKeyStore });
 
   let hostClient = null;
   let status = { state: 'disabled', lastError: null, connectedClients: 0 };
@@ -170,7 +170,7 @@ export const createRelayService = ({
             await start(relayUrl);
           }
         } catch (error) {
-          logger.warn(`[Relay] claim watch failed: ${error?.message ?? error}`);
+          logger.warn(`[Relay] claim watch failed: ${describeRelayError(error)}`);
         }
       })();
     }, CLAIM_WATCH_INTERVAL_MS);
@@ -235,7 +235,7 @@ export const createRelayService = ({
         await start(config.relayUrl);
       }
     } catch (error) {
-      logger.warn(`[Relay] startup failed: ${error?.message ?? error}`);
+      logger.warn(`[Relay] startup failed: ${describeRelayError(error)}`);
     }
   };
 
@@ -257,7 +257,7 @@ export const createRelayService = ({
         stop();
       }
     } catch (error) {
-      logger.warn(`[Relay] reconcile failed: ${error?.message ?? error}`);
+      logger.warn(`[Relay] reconcile failed: ${describeRelayError(error)}`);
     }
   };
 

package/server/lib/relay/service.test.js

@@ -4,14 +4,19 @@ import crypto from 'node:crypto';
 import { createRelayService } from './service.js';
 
 const makeService = (options = {}) => {
-  // In-memory settings store with a pre-seeded relay identity so the service
-  // never regenerates a signing key during the test.
+  // In-memory key store with a pre-seeded signing key so the service never
+  // regenerates the serverId during the test.
   const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
-  let settings = {
-    relaySigningKey: {
+  const keySlots = {
+    signing: {
       privateJwk: privateKey.export({ format: 'jwk' }),
       publicJwk: publicKey.export({ format: 'jwk' }),
     },
+  };
+  const relayKeyStore = {
+    getOrCreate: async (slot, generate) => (keySlots[slot] ??= await generate()),
+  };
+  let settings = {
     privateRelay: { enabled: true, relayUrl: 'wss://relay.example.test/ws' },
     ...options.settings,
   };
@@ -26,7 +31,7 @@ const makeService = (options = {}) => {
     crypto,
     readSettingsFromDiskMigrated: async () => settings,
     writeSettingsToDisk: async (next) => { settings = next; },
-    readSettingsStrict: async () => settings,
+    relayKeyStore,
     getLocalPort: () => 0,
     hasRelayDemand: options.hasRelayDemand ?? (async () => true),
     hostLock,

package/server/lib/relay/signing-key.js

@@ -1,51 +1,28 @@
 // Per-server relay signing identity (ECDSA P-256), extracted from
 // lib/notifications/apns-runtime.js so both the push relay and the private
 // relay share the SAME keypair and thus the SAME serverId
-// (base64url(SHA-256(canonical public JWK))). Storage format is unchanged:
-// `settings.relaySigningKey = { privateJwk, publicJwk }` — existing installs'
-// serverId must stay stable because push token binding depends on it.
+// (base64url(SHA-256(canonical public JWK))). Stored by key-store.js; existing
+// installs' serverId must stay stable because push token binding depends on it.
 
 /**
  * @param {{
  *   crypto: typeof import('node:crypto'),
- *   readSettingsFromDiskMigrated: () => Promise<object>,
- *   writeSettingsToDisk: (settings: object) => Promise<void>,
- *   readSettingsStrict?: () => Promise<object>,
+ *   relayKeyStore: ReturnType<typeof import('./key-store.js').createRelayKeyStore>,
  * }} deps
  * @returns {Promise<{ privateKey: import('node:crypto').KeyObject, publicJwk: JsonWebKey }>}
  */
-export const getOrCreateRelaySigningKeypair = async ({ crypto, readSettingsFromDiskMigrated, writeSettingsToDisk, readSettingsStrict }) => {
-  const toKeypair = (stored) => ({
+export const getOrCreateRelaySigningKeypair = async ({ crypto, relayKeyStore }) => {
+  const stored = await relayKeyStore.getOrCreate('signing', async () => {
+    // Loud on purpose: a new signing key means a new serverId — every previously
+    // paired device and push binding is orphaned. Expected exactly once, on first run.
+    console.warn('[relay-identity] Generating NEW relay signing keypair (serverId changes; previously paired devices must re-pair)');
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
+    return { privateJwk: privateKey.export({ format: 'jwk' }), publicJwk: publicKey.export({ format: 'jwk' }) };
+  });
+  return {
     privateKey: crypto.createPrivateKey({ key: stored.privateJwk, format: 'jwk' }),
     publicJwk: stored.publicJwk,
-  });
-  const settings = await readSettingsFromDiskMigrated();
-  const existing = settings?.relaySigningKey;
-  if (existing && existing.privateJwk && existing.publicJwk) {
-    return toKeypair(existing);
-  }
-  // Regeneration gate: the lenient settings reader maps read failures to `{}`,
-  // indistinguishable from "first run". Minting a new keypair changes serverId,
-  // which orphans every paired device and push binding AND the write below would
-  // clobber the settings file with the empty spread. Re-verify with the strict
-  // reader (throws on corrupt/unreadable) before generating; if it finds the
-  // key the lenient read lost, use it and generate nothing.
-  let verifiedSettings = settings;
-  if (readSettingsStrict) {
-    verifiedSettings = await readSettingsStrict();
-    const verified = verifiedSettings?.relaySigningKey;
-    if (verified && verified.privateJwk && verified.publicJwk) {
-      return toKeypair(verified);
-    }
-  }
-  // Loud on purpose: a new signing key means a new serverId — every previously
-  // paired device and push binding is orphaned. Expected exactly once, on first run.
-  console.warn('[relay-identity] Generating NEW relay signing keypair (serverId changes; previously paired devices must re-pair)');
-  const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'P-256' });
-  const privateJwk = privateKey.export({ format: 'jwk' });
-  const publicJwk = publicKey.export({ format: 'jwk' });
-  await writeSettingsToDisk({ ...settings, ...(verifiedSettings || {}), relaySigningKey: { privateJwk, publicJwk } });
-  return { privateKey, publicJwk };
+  };
 };
 
 // Fixed key order so the hash is stable regardless of stored JSON field order.

package/server/lib/relay/tunnel-codec.js

@@ -8,16 +8,16 @@
 import { MAX_PLAINTEXT_FRAME_BYTES } from './e2ee.js';
 
 
-export const TUNNEL_FRAME_HEADER_BYTES = 5;
-export const TUNNEL_FRAGMENT_FLAG = 0x80;
+const TUNNEL_FRAME_HEADER_BYTES = 5;
+const TUNNEL_FRAGMENT_FLAG = 0x80;
 
 // Batch envelope container (mirror of protocol.ts). Only used when both peers
 // negotiated `batch`. Reserve the per-frame envelope overhead from the payload
 // budget so any single frame still fits one 64 KiB encrypted plaintext.
-export const BATCH_CONTAINER_TAG_SINGLE = 0x00;
-export const BATCH_CONTAINER_TAG_BATCH = 0x01;
-export const BATCH_FRAME_LENGTH_BYTES = 4;
-export const BATCH_ENVELOPE_RESERVED_BYTES = 1 + BATCH_FRAME_LENGTH_BYTES;
+const BATCH_CONTAINER_TAG_SINGLE = 0x00;
+const BATCH_CONTAINER_TAG_BATCH = 0x01;
+const BATCH_FRAME_LENGTH_BYTES = 4;
+const BATCH_ENVELOPE_RESERVED_BYTES = 1 + BATCH_FRAME_LENGTH_BYTES;
 export const MAX_TUNNEL_PAYLOAD_BYTES =
   MAX_PLAINTEXT_FRAME_BYTES - TUNNEL_FRAME_HEADER_BYTES - BATCH_ENVELOPE_RESERVED_BYTES;
 
@@ -40,7 +40,7 @@ export const TunnelFrameType = {
 const TUNNEL_FRAME_TYPE_VALUES = new Set(Object.values(TunnelFrameType));
 
 /** @param {number} value */
-export const isTunnelFrameType = (value) => TUNNEL_FRAME_TYPE_VALUES.has(value);
+const isTunnelFrameType = (value) => TUNNEL_FRAME_TYPE_VALUES.has(value);
 
 const MAX_STREAM_ID = 0xffffffff;
 
@@ -295,9 +295,9 @@ const BUFFERED_FRAME_TYPES = new Set([
 
 // See the TS mirror (tunnel-codec.ts) for the 150ms rationale: the chat render pipeline's
 // 100ms input throttle + ~64ms paced-reveal smoothing make a 150ms batch window invisible.
-export const DEFAULT_BATCH_WINDOW_MS = 150;
-export const DEFAULT_BATCH_MAX_BYTES = 24 * 1024;
-export const DEFAULT_BATCH_MAX_FRAMES = 32;
+const DEFAULT_BATCH_WINDOW_MS = 150;
+const DEFAULT_BATCH_MAX_BYTES = 24 * 1024;
+const DEFAULT_BATCH_MAX_FRAMES = 32;
 
 /**
  * Outbound batching buffer (mirror of tunnel-codec.ts createOutboundFrameBatcher).

package/server/lib/route-module-exports.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+describe('lazy-loaded route module exports', () => {
+  it.each([
+    ['./git/index.js', [
+      'computeIntegratePlan',
+      'createBranch',
+      'deleteProfile',
+      'getCommitSummaries',
+      'listStashes',
+    ]],
+    ['./quota/index.js', ['fetchQuotaForProvider', 'listConfiguredQuotaProviders']],
+    ['./tts/index.js', ['ttsService', 'TTS_VOICES']],
+    ['./walkthrough/index.js', ['getRepositoryRootFor']],
+  ])('%s keeps the exports its routes load dynamically', async (specifier, names) => {
+    const routeModule = await import(specifier);
+
+    for (const name of names) {
+      expect(routeModule[name], `${specifier} must export ${name}`).toBeDefined();
+    }
+  });
+});

package/server/lib/routing/DOCUMENTATION.md

@@ -39,7 +39,11 @@ Auto. There is no env gate — the feature shipped dark behind
 - `history.js` — the last three settled turns through session assist's
   `loadAssistContext` (text parts only, attached quotes included, no files or
   tool payloads), each user message cut to its head and each answer to head
-  plus tail. The new request is never cut.
+  plus tail. The new request is never cut. Also the model that wrote the last
+  settled answer and when it finished (`lastAnswer`), for `cache.js`.
+- `cache.js` — "Try to preserve cache usage": which category a send stays on
+  while the current model's prompt cache is likely warm (`cacheHoldCategory`),
+  and how long that is given OpenCode's `warming` config (`warmWindowMs`).
 - `runtime.js` — `createRoutingRuntime`: `describe`, `classifierEndpoint` (the
   endpoint a Jev request goes to now, or null; also used by
   `../session-work` and `../session-goal`), `noteModelSelection`,
@@ -91,6 +95,21 @@ Auto. There is no env gate — the feature shipped dark behind
   switch, so the reply runs on the model's default thinking instead of OpenCode
   refusing it (Settings from before #4133 saved list positions like `"2"`).
   An unreadable catalog, or one that does not know the model yet, keeps it.
+- A provider's prompt cache belongs to one model, so a model switch makes the
+  new model read the whole context uncached. With `preserveCache` on (the
+  default; a config without the key reads as on), a send Jev routes to a
+  built-in category below the one the session is on runs as that one instead,
+  while the cache is likely warm. "Below" is the built-in order trivial <
+  research < implement < hard; the session is on the highest enabled built-in
+  category whose model wrote the last settled answer. Moving up is never held,
+  and neither is a send routed to a user category, a fallback for low
+  confidence or an error, or a hold that would change the agent (another
+  agent is another system prompt, which misses the cache anyway). Warm means
+  within 5 minutes of the last answer finishing, or, when OpenCode's `warming`
+  is on for the directory, within its `duration` (30 minutes for `true`) plus
+  5 minutes. The config is read only after the first 5 minutes; an unreadable
+  one counts as warming off. The decision event names the category the send
+  ran as and carries `cacheHold.requested`, the one Jev chose.
 - Auto is offered (`autoReady`) with a usable classification provider
   (`jevAvailable`), `enabled`, a fallback model and at least two enabled
   categories.
@@ -223,9 +242,10 @@ features that need Jev.
 
 ## Tests
 
-`store.test.js` (defaults, deviation round-trip, deleted built-ins, malformed
+`store.test.js` (defaults, deviation round-trip, the cache setting's default,
+deleted built-ins, malformed
 file, token file mode, classifier pick, custom endpoint file), `runtime.test.js` (request text,
-excerpts, decisions, endpoints, custom URL normalization and setter,
+excerpts, decisions, cache holds and the warm window, endpoints, custom URL normalization and setter,
 classifier fallback, rewrite and fallback
 paths, safety net accept/hold/skip/unavailable), `routes.http.test.js`
 (sentinel dropped from a create and swallowed on the model switch, routed send