onbuzz 4.6.4 → 4.7.0

package/bin/cli.js

@@ -17,10 +17,18 @@ import { dirname, join } from 'path';
 import { spawn } from 'child_process';
 import { readFileSync } from 'fs';
 import http from 'http';
+import { runUpdateCheck } from '../src/utilities/updateNotifier.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Fire the update-notifier check as soon as the process starts. The
+// helper is non-blocking (it schedules a background fetch and reads
+// from a tiny on-disk cache for the next run) and silently skips
+// every failure mode — missing dep, no network, kill-switch env,
+// not-globally-installed. Worst case: the banner just doesn't appear.
+runUpdateCheck().catch(() => { /* never propagate */ });
+
 // Default configuration
 const DEFAULT_PORT = 8080;
 // Use 127.0.0.1 instead of 'localhost' to avoid IPv6 issues in WSL2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.6.4",
+  "version": "4.7.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/src/__tests__/autoUpdateConfig.test.js

@@ -0,0 +1,44 @@
+/**
+ * Tripwire for the auto-update configuration in package.json.
+ *
+ * Catches the class of regression where someone bumps deps or
+ * re-formats the build block and accidentally drops:
+ *   - the `update-notifier` runtime dep (CLI banner stops working)
+ *   - the `electron-updater` optional dep (Electron updates stop)
+ *   - the `build.publish` block (electron-builder stops generating
+ *     latest.yml + electron-updater has nothing to read)
+ *
+ * If you intentionally remove any of these, update this test in the
+ * SAME commit and explain in the test diff why.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8'));
+
+describe('package.json — auto-update presence', () => {
+  test('update-notifier is in dependencies (CLI banner)', () => {
+    expect(pkg.dependencies).toBeDefined();
+    expect(pkg.dependencies['update-notifier']).toBeTruthy();
+  });
+
+  test('electron-updater is in optionalDependencies (Electron build only)', () => {
+    expect(pkg.optionalDependencies?.['electron-updater']).toBeTruthy();
+  });
+
+  test('electron-builder has a publish provider configured', () => {
+    expect(pkg.build).toBeDefined();
+    expect(Array.isArray(pkg.build.publish) || typeof pkg.build.publish === 'object').toBe(true);
+    const entries = Array.isArray(pkg.build.publish) ? pkg.build.publish : [pkg.build.publish];
+    expect(entries.length).toBeGreaterThan(0);
+    // electron-updater requires a `provider` field on each publish entry.
+    for (const entry of entries) {
+      expect(entry.provider).toBeTruthy();
+    }
+  });
+});

package/src/__tests__/releaseWorkflow.test.js

@@ -0,0 +1,72 @@
+/**
+ * Tripwire: the npm-publish workflow must NOT re-introduce
+ * `javascript-obfuscator` or any other source-modifying step that
+ * would defeat the explicit decision in commit removing obfuscation.
+ *
+ * If you genuinely want to bring obfuscation back, change this test
+ * AND record the rationale in the workflow's leading comment block.
+ * Don't just delete the test.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+const WORKFLOWS_DIR = join(REPO_ROOT, '.github', 'workflows');
+
+const FORBIDDEN_IN_PUBLISH = [
+  'javascript-obfuscator',
+  'javascript_obfuscator',
+];
+
+describe('release workflows — obfuscation absence', () => {
+  test('publish-npm-trusted.yml contains no obfuscator install or invocation', () => {
+    const yaml = readFileSync(join(WORKFLOWS_DIR, 'publish-npm-trusted.yml'), 'utf8');
+    for (const needle of FORBIDDEN_IN_PUBLISH) {
+      // Tolerate the literal mention inside a comment block that
+      // documents the removal — but not in any other context.
+      const lines = yaml.split('\n');
+      const offending = lines
+        .map((line, idx) => ({ line, idx }))
+        .filter(({ line }) => line.includes(needle))
+        .filter(({ line }) => !/^\s*#/.test(line) && !/^\s*\/\//.test(line));
+      expect(offending).toEqual([]);
+    }
+  });
+
+  test('workflow YAML is syntactically valid (no orphaned steps)', () => {
+    const yaml = readFileSync(join(WORKFLOWS_DIR, 'publish-npm-trusted.yml'), 'utf8');
+    // We don't bundle a YAML parser into the CLI repo; a structural
+    // smoke test is enough to catch the most common form of breakage
+    // (deleting a step without removing the leading `- name:`).
+    const stepCount = (yaml.match(/^\s{4,6}- name:/gm) || []).length;
+    expect(stepCount).toBeGreaterThan(5);
+    // Each top-level step name should be followed by either `run:` or `uses:`
+    const lines = yaml.split('\n');
+    let pendingStepLine = null;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^\s{4,6}- name:/.test(lines[i])) {
+        pendingStepLine = i;
+      } else if (pendingStepLine != null && /^\s{6,8}(run|uses):/.test(lines[i])) {
+        pendingStepLine = null;
+      } else if (pendingStepLine != null && /^\s{4,6}- /.test(lines[i])) {
+        throw new Error(`step at line ${pendingStepLine + 1} has no run/uses`);
+      }
+    }
+  });
+
+  test('every yml file in .github/workflows parses (basic balance check)', () => {
+    const files = readdirSync(WORKFLOWS_DIR).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const f of files) {
+      const yaml = readFileSync(join(WORKFLOWS_DIR, f), 'utf8');
+      // Naive but useful: every workflow should have `jobs:` and at
+      // least one step.
+      expect(yaml).toMatch(/^jobs:/m);
+      expect(yaml).toMatch(/^\s+steps:/m);
+    }
+  });
+});

package/src/interfaces/__tests__/accountRoutes.test.js

@@ -0,0 +1,429 @@
+/**
+ * Tests for the account-proxy router on the local CLI server.
+ *
+ * These tests cover three categories of behavior:
+ *
+ *   1. Auth gating — every route MUST return 401 + `not_signed_in`
+ *      when there's no JWT, never silently fall through to the
+ *      backend with no auth.
+ *
+ *   2. JWT forwarding + envelope normalisation — when a JWT is
+ *      present, the backend is called with a Bearer header, and
+ *      every response (200, 404, 503, JSON-shape variations) lands
+ *      in our standard `{ success, error?, code? }` envelope.
+ *
+ *   3. Handoff URL building — the FE never gets to pick which
+ *      portal we redirect to, and the handoff is only ever the
+ *      short-lived token, never the long-lived JWT.
+ *
+ * The router is constructed with injected `getJwt`, `getBrand`, and
+ * `fetchImpl` — no real HTTP, no real `lastAuthResult` plumbing.
+ */
+
+import { describe, test, expect, jest } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { createAccountRouter, ERROR_CODES, __test__ } from '../accountRoutes.js';
+
+const SAMPLE_JWT = 'eyJ.sample.jwt';
+const BACKEND_URL = 'https://backend.test';
+
+async function startApp(handler) {
+  const app = express();
+  app.use(express.json());
+  handler(app);
+  const server = createServer(app);
+  await new Promise(r => server.listen(0, r));
+  return { server, baseUrl: `http://127.0.0.1:${server.address().port}` };
+}
+
+async function stop(server) { if (server) await new Promise(r => server.close(r)); }
+
+function mountRouter({ jwt = SAMPLE_JWT, brand = 'autopilot', fetchImpl, logger = { warn: () => {} } } = {}) {
+  const router = createAccountRouter({
+    getJwt: () => jwt,
+    getBrand: () => brand,
+    backendBaseUrl: BACKEND_URL,
+    fetchImpl,
+    logger,
+  });
+  return async () => {
+    return startApp(app => app.use('/api/account', router));
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Constructor guards
+// ────────────────────────────────────────────────────────────────────
+describe('createAccountRouter — constructor', () => {
+  test('throws when getJwt is missing', () => {
+    expect(() => createAccountRouter({ getBrand: () => 'autopilot' })).toThrow(/getJwt/);
+  });
+  test('throws when getBrand is missing', () => {
+    expect(() => createAccountRouter({ getJwt: () => null })).toThrow(/getBrand/);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Auth gating
+// ────────────────────────────────────────────────────────────────────
+describe('account routes — auth gating', () => {
+  test.each([
+    ['GET',    '/api/account/profile', undefined],
+    ['GET',    '/api/account/balance', undefined],
+    ['GET',    '/api/account/keys',    undefined],
+    ['POST',   '/api/account/keys',    { name: 'CI key' }],
+    ['DELETE', '/api/account/keys/some-id', undefined],
+    ['POST',   '/api/account/handoff', {}],
+  ])('%s %s returns 401 not_signed_in when JWT is absent', async (method, path, body) => {
+    const startServer = mountRouter({ jwt: null, fetchImpl: jest.fn() });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+      expect(r.status).toBe(401);
+      const json = await r.json();
+      expect(json.success).toBe(false);
+      expect(json.code).toBe(ERROR_CODES.NOT_SIGNED_IN);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('backend is never called when JWT is absent', async () => {
+    const fetchImpl = jest.fn();
+    const startServer = mountRouter({ jwt: null, fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      await fetch(`${baseUrl}/api/account/profile`);
+      expect(fetchImpl).not.toHaveBeenCalled();
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Profile + balance + keys list
+// ────────────────────────────────────────────────────────────────────
+describe('GET /api/account/profile', () => {
+  test('forwards JWT and returns normalized { user } even when backend returns flat user object', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ id: 'u-1', email: 'a@b.com' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/profile`);
+      expect(r.status).toBe(200);
+      const json = await r.json();
+      expect(json).toEqual({ success: true, user: { id: 'u-1', email: 'a@b.com' } });
+      expect(fetchImpl).toHaveBeenCalledTimes(1);
+      const [url, opts] = fetchImpl.mock.calls[0];
+      expect(url).toBe(`${BACKEND_URL}/auth/me`);
+      expect(opts.headers.Authorization).toBe(`Bearer ${SAMPLE_JWT}`);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('passes nested { user } through unchanged', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ user: { id: 'u-2', email: 'c@d.com' } }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const json = await (await fetch(`${baseUrl}/api/account/profile`)).json();
+      expect(json.user).toEqual({ id: 'u-2', email: 'c@d.com' });
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+describe('GET /api/account/balance', () => {
+  test('proxies to /account/profile and returns the body verbatim', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ balance: 12.34, plan: 'pro' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/balance`);
+      const json = await r.json();
+      expect(json).toEqual({ balance: 12.34, plan: 'pro' });
+      expect(fetchImpl.mock.calls[0][0]).toBe(`${BACKEND_URL}/account/profile`);
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+describe('GET /api/account/keys', () => {
+  test('returns the backend response verbatim', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ apiKeys: [{ id: 'k1', name: 'CI', status: 'active' }] }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys`);
+      const json = await r.json();
+      expect(json.apiKeys).toHaveLength(1);
+      expect(fetchImpl.mock.calls[0][0]).toBe(`${BACKEND_URL}/auth/apikeys`);
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Key create — input validation + one-time-reveal pass-through
+// ────────────────────────────────────────────────────────────────────
+describe('POST /api/account/keys', () => {
+  test('400 + bad_request when name is missing', async () => {
+    const fetchImpl = jest.fn();
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      });
+      expect(r.status).toBe(400);
+      const json = await r.json();
+      expect(json.code).toBe(ERROR_CODES.BAD_REQUEST);
+      expect(fetchImpl).not.toHaveBeenCalled();
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('400 + bad_request when name is whitespace-only', async () => {
+    const startServer = mountRouter({ fetchImpl: jest.fn() });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: '   ' }),
+      });
+      expect(r.status).toBe(400);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('forwards trimmed name + optional expiresIn, returns one-time key', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 201,
+      text: async () => JSON.stringify({
+        message: 'API key generated successfully',
+        apiKey: { id: 'k-new', name: 'mykey', key: 'lx_secretvalue', createdAt: '2026-05-11', expiresAt: null },
+      }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: '  mykey  ', expiresIn: 30 }),
+      });
+      expect(r.status).toBe(201);
+      const json = await r.json();
+      expect(json.apiKey.key).toBe('lx_secretvalue');
+      const sentBody = JSON.parse(fetchImpl.mock.calls[0][1].body);
+      expect(sentBody.name).toBe('mykey');
+      expect(sentBody.expiresIn).toBe(30);
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Key revoke
+// ────────────────────────────────────────────────────────────────────
+describe('DELETE /api/account/keys/:id', () => {
+  test('rejects an id with unsafe characters before hitting the backend', async () => {
+    const fetchImpl = jest.fn();
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      // Express routes won't let `..` through directly, but
+      // `<script>` would. Either way, our regex blocks it.
+      const r = await fetch(`${baseUrl}/api/account/keys/bad%20id%21`, { method: 'DELETE' });
+      expect(r.status).toBe(400);
+      expect(fetchImpl).not.toHaveBeenCalled();
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('happy path proxies the revoke', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ message: 'API key revoked successfully' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys/abc-123_XYZ`, { method: 'DELETE' });
+      expect(r.status).toBe(200);
+      const [url, opts] = fetchImpl.mock.calls[0];
+      expect(url).toBe(`${BACKEND_URL}/auth/apikey/abc-123_XYZ`);
+      expect(opts.method).toBe('DELETE');
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Handoff URL
+// ────────────────────────────────────────────────────────────────────
+describe('POST /api/account/handoff', () => {
+  test('mints token via backend and returns autopilot portal URL with handoff query', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ handoff: 'handoff-token-xyz' }),
+    });
+    const startServer = mountRouter({ brand: 'autopilot', fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/handoff`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ destination: 'payment' }),
+      });
+      expect(r.status).toBe(200);
+      const json = await r.json();
+      expect(json.url).toBe('https://autopilot.loxia.ai/payment?handoff=handoff-token-xyz');
+      const fetchOpts = fetchImpl.mock.calls[0][1];
+      expect(fetchOpts.method).toBe('POST');
+      expect(JSON.parse(fetchOpts.body).purpose).toBe('portal-payment');
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('switches portal host for OnBuzz brand', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ handoff: 'tok' }),
+    });
+    const startServer = mountRouter({ brand: 'onbuzz', fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const json = await (await fetch(`${baseUrl}/api/account/handoff`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
+      })).json();
+      expect(json.url.startsWith(__test__.PORTAL_URLS_BY_BRAND.onbuzz)).toBe(true);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('falls back to "payment" when destination is unknown (closed allowlist)', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200,
+      text: async () => JSON.stringify({ handoff: 'tok' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const json = await (await fetch(`${baseUrl}/api/account/handoff`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ destination: '../evil' }),
+      })).json();
+      // Unknown destination falls back to /payment, NOT echoed as /../evil
+      expect(json.url).toContain('/payment?handoff=');
+      expect(json.url).not.toContain('evil');
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('502 when backend response lacks handoff field', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: true, status: 200, text: async () => JSON.stringify({ something_else: 'x' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/handoff`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
+      });
+      expect(r.status).toBe(502);
+    } finally {
+      await stop(server);
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Backend error translation
+// ────────────────────────────────────────────────────────────────────
+describe('proxy error envelopes', () => {
+  test('non-OK response is converted to { success:false, code:backend_error }', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: false, status: 500,
+      text: async () => JSON.stringify({ error: 'something broke' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/profile`);
+      expect(r.status).toBe(500);
+      const json = await r.json();
+      expect(json).toEqual({
+        success: false,
+        error: 'something broke',
+        code: ERROR_CODES.BACKEND_ERROR,
+      });
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('404 maps to code:not_found', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: false, status: 404,
+      text: async () => JSON.stringify({ error: 'nope' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/keys`);
+      expect(r.status).toBe(404);
+      const json = await r.json();
+      expect(json.code).toBe(ERROR_CODES.NOT_FOUND);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('network failure becomes 503 + code:network_error', async () => {
+    const fetchImpl = jest.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/profile`);
+      expect(r.status).toBe(503);
+      const json = await r.json();
+      expect(json.code).toBe(ERROR_CODES.NETWORK_ERROR);
+    } finally {
+      await stop(server);
+    }
+  });
+});

package/src/interfaces/__tests__/apiKeyManagerContract.test.js

@@ -0,0 +1,39 @@
+/**
+ * Contract test: methods that `webServer.js` calls on `ApiKeyManager`
+ * MUST exist on the real class.
+ *
+ * Bug history this guards against:
+ *   - 2026-05: webServer's /api/auth/signout called
+ *     `apiKeyManager.removeKeys(null)` but the real method is
+ *     `removeSessionKeys`. Sign-out 500'd at runtime. The existing
+ *     `authRoutes.test.js` happened to pass because it built its own
+ *     mock `apiKeyManager` with the wrong method names — the mock and
+ *     the production caller agreed with each other, but neither agreed
+ *     with the real class. Same drift hit /auth/callback's `setKeys`
+ *     call, which silently failed to persist API keys from OAuth.
+ *
+ * This file imports the REAL ApiKeyManager and asserts each method
+ * webServer.js calls is a function on it. Cheap to maintain — when
+ * webServer starts calling a new method, add it here.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import ApiKeyManager from '../../services/apiKeyManager.js';
+
+/**
+ * Every ApiKeyManager method invoked from webServer.js production paths.
+ * Update this list when webServer.js starts using a new method.
+ */
+const REQUIRED_METHODS = Object.freeze([
+  'setSessionKeys',     // /auth/callback, remote-session bootstrap
+  'removeSessionKeys',  // /api/auth/signout
+  'getKeysForRequest',  // /api/auth/status, /api/auth/resolve, every AI call
+]);
+
+describe('ApiKeyManager contract (methods called by webServer.js)', () => {
+  const instance = new ApiKeyManager(/* logger */ null);
+
+  test.each(REQUIRED_METHODS)('exposes %s as a function', (methodName) => {
+    expect(typeof instance[methodName]).toBe('function');
+  });
+});

package/src/interfaces/__tests__/authRoutes.test.js

@@ -53,7 +53,7 @@ function buildAuthApp({ apiKeyManager, broadcastToSession, config, logger, fetch
       }
 
       if (apiKey && apiKeyManager) {
-        await apiKeyManager.setKeys(null, { loxiaApiKey: apiKey });
+        await apiKeyManager.setSessionKeys(null, { loxiaApiKey: apiKey });
       }
 
       ctx.lastAuthResult = {
@@ -137,7 +137,7 @@ function buildAuthApp({ apiKeyManager, broadcastToSession, config, logger, fetch
   app.post('/api/auth/signout', async (req, res) => {
     try {
       if (apiKeyManager) {
-        await apiKeyManager.removeKeys(null);
+        await apiKeyManager.removeSessionKeys(null);
       }
       ctx.lastAuthResult = null;
       broadcastToSession(null, {
@@ -177,8 +177,8 @@ function buildAuthApp({ apiKeyManager, broadcastToSession, config, logger, fetch
 function makeApiKeyManager(initialKey = null) {
   let storedKey = initialKey;
   return {
-    setKeys: jest.fn(async (sessionId, keys) => { storedKey = keys.loxiaApiKey; }),
-    removeKeys: jest.fn(async () => { storedKey = null; }),
+    setSessionKeys: jest.fn(async (sessionId, keys) => { storedKey = keys.loxiaApiKey; }),
+    removeSessionKeys: jest.fn(async () => { storedKey = null; }),
     getKeysForRequest: jest.fn(() => storedKey ? { loxiaApiKey: storedKey } : {}),
     _peek: () => storedKey
   };
@@ -254,7 +254,7 @@ describe('Auth Routes (webServer.js)', () => {
       expect(await res.text()).toContain('Authenticated!');
 
       // Verify API key was stored
-      expect(apiKeyManager.setKeys).toHaveBeenCalledWith(null, { loxiaApiKey: 'lx_generated_key_123' });
+      expect(apiKeyManager.setSessionKeys).toHaveBeenCalledWith(null, { loxiaApiKey: 'lx_generated_key_123' });
 
       // Verify broadcast
       const broadcast = broadcasts[0];
@@ -438,14 +438,14 @@ describe('Auth Routes (webServer.js)', () => {
 
       const body = await (await fetch(`${baseUrl}/api/auth/signout`, { method: 'POST' })).json();
       expect(body.success).toBe(true);
-      expect(apiKeyManager.removeKeys).toHaveBeenCalledWith(null);
+      expect(apiKeyManager.removeSessionKeys).toHaveBeenCalledWith(null);
       expect(apiKeyManager._peek()).toBeNull();
       expect(ctx.lastAuthResult).toBeNull();
       expect(broadcasts[0].msg.type).toBe('auth_signout');
     });
 
-    it('returns 500 when removeKeys throws', async () => {
-      const apiKeyManager = { removeKeys: jest.fn().mockRejectedValue(new Error('vault locked')) };
+    it('returns 500 when removeSessionKeys throws', async () => {
+      const apiKeyManager = { removeSessionKeys: jest.fn().mockRejectedValue(new Error('vault locked')) };
       const app = buildAuthApp({ apiKeyManager, broadcastToSession, config: {}, logger, fetchImpl: mockFetch, ctx });
       const { server: s, baseUrl } = await startServer(app);
       server = s;