@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/spaces/tools-pack.test.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { packLocalTools } from './tools-pack.js';
+
+const CHECKOUT = path.resolve('/checkout');
+const OUT = path.resolve('/out');
+
+/** A stand-in for bun. `pack` is what `bun pm pack --quiet` prints for a package. */
+const fakeBun = ({ pack = (name) => `${path.join(OUT, `openchamber-${name}-1.24.2.tgz`)}\n`, failAt = () => false } = {}) => {
+  const calls = [];
+  const runCommand = async (file, args, options) => {
+    calls.push({ file, args, cwd: options.cwd, timeoutMs: options.timeoutMs });
+    if (failAt(args, options.cwd)) return { code: 1, stdout: '', stderr: 'error: Script not found "build"\n' };
+    return { code: 0, stdout: args[0] === 'pm' ? pack(path.basename(options.cwd)) : '', stderr: '' };
+  };
+  return { runCommand, calls };
+};
+
+describe('packLocalTools', () => {
+  it('builds the sdk, then packs the sdk and web from their own directories', async () => {
+    const bun = fakeBun();
+    const result = await packLocalTools({ runCommand: bun.runCommand, bunPath: '/opt/bun', checkoutRoot: CHECKOUT, outputDirectory: OUT });
+
+    expect(result).toEqual({
+      sdkTarballPath: path.join(OUT, 'openchamber-sdk-1.24.2.tgz'),
+      webTarballPath: path.join(OUT, 'openchamber-web-1.24.2.tgz'),
+    });
+    expect(bun.calls.map((call) => [call.file, call.args.join(' '), call.cwd])).toEqual([
+      ['/opt/bun', 'run build', path.join(CHECKOUT, 'packages', 'sdk')],
+      ['/opt/bun', `pm pack --destination ${OUT} --quiet`, path.join(CHECKOUT, 'packages', 'sdk')],
+      ['/opt/bun', `pm pack --destination ${OUT} --quiet`, path.join(CHECKOUT, 'packages', 'web')],
+    ]);
+    for (const call of bun.calls) expect(call.timeoutMs).toBeGreaterThan(0);
+  });
+
+  it('takes the last line as the tarball, because the prepack script prints before it', async () => {
+    const bun = fakeBun({ pack: (name) => `Built 0 built-in extension(s).\n${path.join(OUT, `openchamber-${name}-1.24.2.tgz`)}\n\n` });
+    const result = await packLocalTools({ runCommand: bun.runCommand, checkoutRoot: CHECKOUT, outputDirectory: OUT });
+    expect(result.webTarballPath).toBe(path.join(OUT, 'openchamber-web-1.24.2.tgz'));
+  });
+
+  it('says which step failed and what to do', async () => {
+    const bun = fakeBun({ failAt: (args) => args[0] === 'run' });
+    await expect(packLocalTools({ runCommand: bun.runCommand, checkoutRoot: CHECKOUT, outputDirectory: OUT })).rejects.toMatchObject({
+      code: 'tools_pack_failed',
+      message: expect.stringMatching(/build the sdk package.*Script not found.*bun install/s),
+    });
+    expect(bun.calls).toHaveLength(1);
+  });
+
+  it('rejects when bun does not name a tarball', async () => {
+    const bun = fakeBun({ pack: () => 'Done\n' });
+    await expect(packLocalTools({ runCommand: bun.runCommand, checkoutRoot: CHECKOUT, outputDirectory: OUT })).rejects.toMatchObject({ code: 'tools_pack_failed' });
+  });
+});

package/server/lib/spaces/tools.js

@@ -0,0 +1,138 @@
+// Tools sources: what goes into a tools volume. A source is plain data, made once.
+//
+//   registry  exact published versions, for a released host
+//   packed    local tarballs of `web` and `sdk`, for a development build, whose
+//             packages differ from the published ones with the same version number
+//
+// Deciding which one a host needs is wiring and belongs to a later stage.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+import { SpaceError } from './errors.js';
+import { FILLER_PROGRAM } from './tools-filler.js';
+
+// Where the filler puts the tarballs of a packed source. It is a tmpfs, so they vanish with the filler.
+export const TOOLS_STAGING_PATH = '/tmp/openchamber-fill';
+
+const WEB_PACKAGE_NAME = '@vantran-se/openchamber-web';
+const WEB_TARBALL_NAME = 'openchamber-web.tgz';
+const SDK_TARBALL_NAME = 'openchamber-sdk.tgz';
+
+// Exact versions for the three packages this module names, never a range or a URL.
+// That pins those three only. Their own dependencies are still ranges, and no lock file travels
+// with the source, so two fills of one key can differ in a transitive package. A known limit.
+const EXACT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+const requireVersion = (value, what) => {
+  if (!EXACT_VERSION_PATTERN.test(value ?? '')) {
+    throw new SpaceError('invalid_tools_version', `${what} needs an exact version such as 1.2.3, got '${value}'`);
+  }
+  return value;
+};
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+const packageJsonText = (fields) => JSON.stringify({ name: 'openchamber-space-tools', private: true, ...fields });
+
+// Every source made here. The Docker place accepts no other object as a source.
+const madeHere = new WeakSet();
+
+const finishSource = (source) => {
+  madeHere.add(Object.freeze(source));
+  return source;
+};
+
+// A revision changes the key and nothing else: the same packages, filled again into a new volume.
+const REVISION_PATTERN = /^[A-Za-z0-9._-]{0,64}$/;
+
+const requireRevision = (value) => {
+  if (!REVISION_PATTERN.test(value)) {
+    throw new SpaceError('invalid_tools_revision', 'A tools revision may hold only letters, digits, dots, dashes and underscores, 64 at most');
+  }
+  return value;
+};
+
+/** OpenCode and its plugin always share one version. */
+const openCodePackages = (version) => ({ '@opencode/cli': version, '@opencode/plugin': version });
+
+/**
+ * The versions a released host installs: its own web package, and OpenCode at the
+ * version of the `@opencode/client` this server was built against.
+ */
+export function readHostToolVersions(packageJsonUrl = new URL('../../../package.json', import.meta.url)) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(packageJsonUrl, 'utf8'));
+  } catch (error) {
+    throw new SpaceError('tools_versions_unreadable', `Could not read the package.json of the OpenChamber server: ${error.message}`);
+  }
+  return {
+    webVersion: requireVersion(manifest.version, WEB_PACKAGE_NAME),
+    openCodeVersion: requireVersion(manifest.dependencies?.['@opencode/client'], 'OpenCode'),
+  };
+}
+
+export function createRegistryToolsSource({ webVersion, openCodeVersion, revision = '' }) {
+  const packages = {
+    [WEB_PACKAGE_NAME]: requireVersion(webVersion, WEB_PACKAGE_NAME),
+    ...openCodePackages(requireVersion(openCodeVersion, 'OpenCode')),
+  };
+  return finishSource({
+    kind: 'registry',
+    description: `web ${webVersion}, opencode ${openCodeVersion}`,
+    canonical: { kind: 'registry', packages, revision: requireRevision(revision) },
+    packageJson: packageJsonText({ dependencies: packages }),
+    files: [],
+  });
+}
+
+/**
+ * A development build. The two tarballs are read and hashed here, once.
+ * The override makes every `@openchamber/sdk` in the tree the local tarball, also the one
+ * that `web` asks for by version number.
+ */
+export function createPackedToolsSource({ webTarballPath, sdkTarballPath, openCodeVersion, revision = '' }) {
+  const read = (filePath, what) => {
+    try {
+      return fs.readFileSync(filePath);
+    } catch (error) {
+      throw new SpaceError('tools_tarball_unreadable', `Could not read the packed ${what} package at ${filePath}: ${error.message}`);
+    }
+  };
+  const files = [
+    { name: WEB_TARBALL_NAME, bytes: read(webTarballPath, 'web') },
+    { name: SDK_TARBALL_NAME, bytes: read(sdkTarballPath, 'sdk') },
+  ];
+  const packages = openCodePackages(requireVersion(openCodeVersion, 'OpenCode'));
+  return finishSource({
+    kind: 'packed',
+    description: 'development build',
+    canonical: { kind: 'packed', tarballs: files.map((file) => ({ name: file.name, sha256: sha256(file.bytes) })), packages, revision: requireRevision(revision) },
+    packageJson: packageJsonText({
+      dependencies: {
+        '@openchamber/web': `file:${TOOLS_STAGING_PATH}/${WEB_TARBALL_NAME}`,
+        '@openchamber/sdk': `file:${TOOLS_STAGING_PATH}/${SDK_TARBALL_NAME}`,
+        ...packages,
+      },
+      overrides: { '@openchamber/sdk': '$@openchamber/sdk' },
+    }),
+    files,
+  });
+}
+
+export function requireToolsSource(source) {
+  if (!madeHere.has(source)) {
+    throw new SpaceError('invalid_tools_source', 'The Docker place needs a tools source from createRegistryToolsSource or createPackedToolsSource');
+  }
+  return source;
+}
+
+/**
+ * First 16 hex characters of a sha256 over everything that decides the content of a tools
+ * volume: the source, the base image the filler runs in, and the filler program itself.
+ */
+export function toolsContentKey(source, image) {
+  const description = JSON.stringify({ source: requireToolsSource(source).canonical, image, filler: sha256(FILLER_PROGRAM) });
+  return sha256(description).slice(0, 16);
+}

package/server/lib/spaces/tools.test.js

@@ -0,0 +1,153 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createPackedToolsSource, createRegistryToolsSource, readHostToolVersions, requireToolsSource, toolsContentKey } from './tools.js';
+
+const IMAGE = 'node@sha256:aaaa';
+const VERSIONS = { webVersion: '1.24.2', openCodeVersion: '1.18.31' };
+
+let directory;
+const tarball = (name, content) => {
+  const filePath = path.join(directory, name);
+  fs.writeFileSync(filePath, content);
+  return filePath;
+};
+
+beforeAll(() => {
+  directory = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-tools-test-'));
+});
+
+afterAll(() => {
+  fs.rmSync(directory, { recursive: true, force: true });
+});
+
+describe('readHostToolVersions', () => {
+  it('reads the version of this server and the OpenCode version it was built against', () => {
+    const versions = readHostToolVersions();
+    expect(versions.webVersion).toMatch(/^\d+\.\d+\.\d+/);
+    expect(versions.openCodeVersion).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it('rejects a manifest whose OpenCode dependency is a range', () => {
+    const manifest = tarball('range.json', JSON.stringify({ version: '1.0.0', dependencies: { '@opencode/client': '^1.18.0' } }));
+    expect(() => readHostToolVersions(pathToFileURL(manifest))).toThrow(expect.objectContaining({ code: 'invalid_tools_version' }));
+  });
+
+  it('says when the manifest cannot be read', () => {
+    expect(() => readHostToolVersions(pathToFileURL(path.join(directory, 'missing.json')))).toThrow(expect.objectContaining({ code: 'tools_versions_unreadable' }));
+  });
+});
+
+describe('createRegistryToolsSource', () => {
+  it('asks for the fork package at the exact host version', () => {
+    const source = createRegistryToolsSource(VERSIONS);
+
+    expect(source.description).toBe('web 1.24.2, opencode 1.18.31');
+    expect(source.files).toEqual([]);
+    expect(JSON.parse(source.packageJson)).toEqual({
+      name: 'openchamber-space-tools',
+      private: true,
+      dependencies: { '@vantran-se/openchamber-web': '1.24.2', '@opencode/cli': '1.18.31', '@opencode/plugin': '1.18.31' },
+    });
+  });
+
+  it.each(['^1.24.2', 'latest', '1.24', '', undefined, 'https://example.com/x.tgz', '1.24.2 || 2'])('rejects the version %j', (version) => {
+    expect(() => createRegistryToolsSource({ ...VERSIONS, webVersion: version })).toThrow(expect.objectContaining({ code: 'invalid_tools_version' }));
+    expect(() => createRegistryToolsSource({ ...VERSIONS, openCodeVersion: version })).toThrow(expect.objectContaining({ code: 'invalid_tools_version' }));
+  });
+
+  it('accepts a prerelease version', () => {
+    expect(createRegistryToolsSource({ ...VERSIONS, webVersion: '1.25.0-beta.1' }).description).toContain('1.25.0-beta.1');
+  });
+});
+
+describe('createPackedToolsSource', () => {
+  it('installs both tarballs by path and makes every sdk in the tree the local one', () => {
+    const source = createPackedToolsSource({ webTarballPath: tarball('web.tgz', 'web bytes'), sdkTarballPath: tarball('sdk.tgz', 'sdk bytes'), openCodeVersion: '1.18.31' });
+
+    expect(source.description).toBe('development build');
+    expect(source.files).toEqual([
+      { name: 'openchamber-web.tgz', bytes: Buffer.from('web bytes') },
+      { name: 'openchamber-sdk.tgz', bytes: Buffer.from('sdk bytes') },
+    ]);
+    expect(JSON.parse(source.packageJson)).toEqual({
+      name: 'openchamber-space-tools',
+      private: true,
+      dependencies: {
+        '@openchamber/web': 'file:/tmp/openchamber-fill/openchamber-web.tgz',
+        '@openchamber/sdk': 'file:/tmp/openchamber-fill/openchamber-sdk.tgz',
+        '@opencode/cli': '1.18.31',
+        '@opencode/plugin': '1.18.31',
+      },
+      overrides: { '@openchamber/sdk': '$@openchamber/sdk' },
+    });
+  });
+
+  it('hashes the tarballs once, when the source is made', () => {
+    const webTarballPath = tarball('web-once.tgz', 'first');
+    const source = createPackedToolsSource({ webTarballPath, sdkTarballPath: tarball('sdk-once.tgz', 'sdk'), openCodeVersion: '1.18.31' });
+    const key = toolsContentKey(source, IMAGE);
+
+    fs.writeFileSync(webTarballPath, 'changed later');
+    expect(toolsContentKey(source, IMAGE)).toBe(key);
+    expect(source.canonical.tarballs[0].sha256).toBe(crypto.createHash('sha256').update('first').digest('hex'));
+  });
+
+  it('says which tarball it could not read', () => {
+    const missing = path.join(directory, 'nowhere.tgz');
+    expect(() => createPackedToolsSource({ webTarballPath: missing, sdkTarballPath: missing, openCodeVersion: '1.18.31' }))
+      .toThrow(expect.objectContaining({ code: 'tools_tarball_unreadable', message: expect.stringContaining('web') }));
+  });
+});
+
+describe('toolsContentKey', () => {
+  const packed = (webContent) => createPackedToolsSource({ webTarballPath: tarball(`web-${webContent}.tgz`, webContent), sdkTarballPath: tarball('sdk-key.tgz', 'sdk'), openCodeVersion: '1.18.31' });
+
+  it('is 16 hex characters and the same for the same content', () => {
+    const key = toolsContentKey(createRegistryToolsSource(VERSIONS), IMAGE);
+    expect(key).toMatch(/^[0-9a-f]{16}$/);
+    expect(toolsContentKey(createRegistryToolsSource(VERSIONS), IMAGE)).toBe(key);
+  });
+
+  it('changes with a version, with the base image, with a tarball byte, and between the two kinds', () => {
+    const keys = [
+      toolsContentKey(createRegistryToolsSource(VERSIONS), IMAGE),
+      toolsContentKey(createRegistryToolsSource({ ...VERSIONS, webVersion: '1.24.3' }), IMAGE),
+      toolsContentKey(createRegistryToolsSource({ ...VERSIONS, openCodeVersion: '1.18.32' }), IMAGE),
+      toolsContentKey(createRegistryToolsSource(VERSIONS), 'node@sha256:bbbb'),
+      toolsContentKey(packed('a'), IMAGE),
+      toolsContentKey(packed('b'), IMAGE),
+      toolsContentKey(createRegistryToolsSource({ ...VERSIONS, revision: 'refill-1' }), IMAGE),
+    ];
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+});
+
+describe('revision', () => {
+  it('changes the key and nothing that gets installed', () => {
+    const plain = createRegistryToolsSource(VERSIONS);
+    const revised = createRegistryToolsSource({ ...VERSIONS, revision: 'refill-1' });
+    expect(revised.packageJson).toBe(plain.packageJson);
+    expect(revised.description).toBe(plain.description);
+  });
+
+  it.each(['two words', 'a/b', 'x'.repeat(65)])('rejects %j', (revision) => {
+    expect(() => createRegistryToolsSource({ ...VERSIONS, revision })).toThrow(expect.objectContaining({ code: 'invalid_tools_revision' }));
+  });
+});
+
+describe('requireToolsSource', () => {
+  it.each([undefined, null, 'registry', {}, { ...createRegistryToolsSource(VERSIONS) }])('rejects %j, which no factory here made', (source) => {
+    expect(() => requireToolsSource(source)).toThrow(expect.objectContaining({ code: 'invalid_tools_source' }));
+  });
+
+  it('accepts a source from either factory', () => {
+    const source = createRegistryToolsSource(VERSIONS);
+    expect(requireToolsSource(source)).toBe(source);
+  });
+});

package/server/lib/tts/openai-sdk.js

@@ -0,0 +1,11 @@
+/**
+ * The OpenAI SDK is ~200 modules and only speech and transcription use it, so
+ * it is loaded on the first call rather than with the server.
+ */
+
+let pending;
+
+export const loadOpenAI = () => {
+  pending ??= import('openai').then((module) => module.default);
+  return pending;
+};

package/server/lib/tts/service.js

@@ -5,8 +5,8 @@
  * This bypasses mobile Safari's audio context restrictions.
  */
 
-import OpenAI from 'openai';
 import { readAuthFile } from '../opencode/auth.js';
+import { loadOpenAI } from './openai-sdk.js';
 import { normalizeCustomOpenAIBaseURL } from './base-url.js';
 
 // Voice options from OpenAI
@@ -53,11 +53,12 @@ class TTSService {
     this._lastApiKey = null;
   }
 
-  _getClient() {
+  async _getClient() {
     const apiKey = getOpenAIApiKey();
 
     // If API key changed or client doesn't exist, create new client
     if (apiKey && (!this._client || this._lastApiKey !== apiKey)) {
+      const OpenAI = await loadOpenAI();
       this._client = new OpenAI({ apiKey });
       this._lastApiKey = apiKey;
     }
@@ -66,7 +67,7 @@ class TTSService {
   }
 
   isAvailable() {
-    return this._getClient() !== null;
+    return Boolean(getOpenAIApiKey());
   }
 
   /**
@@ -96,9 +97,10 @@ class TTSService {
       if (apiKey) clientOpts.apiKey = apiKey;
       if (!apiKey) clientOpts.apiKey = 'not-required';
       if (normalizedBaseURL) clientOpts.baseURL = normalizedBaseURL;
+      const OpenAI = await loadOpenAI();
       client = new OpenAI(clientOpts);
     } else {
-      client = this._getClient();
+      client = await this._getClient();
     }
 
     if (!client) {
@@ -141,7 +143,7 @@ class TTSService {
    * Generate speech and return as a buffer (for caching)
    */
   async generateSpeechBuffer(options) {
-    const client = this._getClient();
+    const client = await this._getClient();
     if (!client) {
       throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY environment variable or configure OpenAI in OpenCode.');
     }

package/server/lib/tts/stt.js

@@ -5,7 +5,7 @@
  * (e.g. faster-whisper, whisper.cpp) using the OpenAI Node SDK.
  */
 
-import OpenAI, { toFile } from 'openai';
+import { loadOpenAI } from './openai-sdk.js';
 import { normalizeCustomOpenAIBaseURL } from './base-url.js';
 
 /**
@@ -36,6 +36,7 @@ export async function transcribeAudio({ audioBuffer, mimeType, model, baseURL, a
   };
   clientOpts.baseURL = normalizedBaseURL;
 
+  const OpenAI = await loadOpenAI();
   const client = new OpenAI(clientOpts);
 
   // Derive a sensible filename extension from the MIME type so the server
@@ -43,7 +44,7 @@ export async function transcribeAudio({ audioBuffer, mimeType, model, baseURL, a
   const ext = mimeTypeToExt(mimeType);
   const filename = `audio.${ext}`;
 
-  const file = await toFile(audioBuffer, filename, { type: mimeType });
+  const file = await OpenAI.toFile(audioBuffer, filename, { type: mimeType });
 
   const result = await client.audio.transcriptions.create({
     file,

package/server/lib/tunnels/DOCUMENTATION.md

@@ -3,6 +3,8 @@
 ## Purpose
 This module contains tunnel provider orchestration for OpenChamber, including provider registry/service wiring, managed remote token config lifecycle, and tunnel HTTP route registration.
 
+Public tunnels require a UI password on the running server. The shared tunnel start operation enforces this for startup tunnels and HTTP requests; the HTTP route rejects passwordless starts before touching an existing tunnel.
+
 ## Entrypoints and structure
 - `packages/web/server/lib/tunnels/index.js`: tunnel service orchestration.
 - `packages/web/server/lib/tunnels/executable-search.js`: cross-platform executable discovery, including Windows Store app aliases.

package/server/lib/tunnels/routes.js

@@ -5,6 +5,7 @@ export const createTunnelRoutesRuntime = (dependencies) => {
     tunnelService,
     tunnelProviderRegistry,
     tunnelAuthController,
+    hasUiPassword,
     readSettingsFromDiskMigrated,
     readManagedRemoteTunnelConfigFromDisk,
     normalizeTunnelProvider,
@@ -74,6 +75,9 @@ export const createTunnelRoutesRuntime = (dependencies) => {
     selectedPresetId,
     selectedPresetName,
   }) => {
+    if (!hasUiPassword) {
+      throw new Error('A UI password is required before starting a public tunnel. Restart OpenChamber with --ui-password.');
+    }
     if (provider === TUNNEL_PROVIDER_CLOUDFLARE && mode === TUNNEL_MODE_MANAGED_REMOTE) {
       setRuntimeManagedRemoteTunnelHostname(hostname);
       setRuntimeManagedRemoteTunnelToken(token);
@@ -445,6 +449,9 @@ export const createTunnelRoutesRuntime = (dependencies) => {
     });
 
     app.post('/api/openchamber/tunnel/start', async (_req, res) => {
+      if (!hasUiPassword) {
+        return res.status(403).json({ ok: false, code: 'ui_password_required', error: 'A UI password is required before starting a public tunnel. Restart OpenChamber with --ui-password.' });
+      }
       try {
         const settings = await readSettingsFromDiskMigrated();
         if (typeof _req?.body?.provider === 'string' && _req.body.provider.trim().length > 0) {

package/server/lib/tunnels/routes.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'bun:test';
+import { createTunnelRoutesRuntime } from './routes.js';
+
+describe('public tunnel password requirement', () => {
+  const createRuntime = (hasUiPassword) => {
+    let starts = 0;
+    const runtime = createTunnelRoutesRuntime({
+      hasUiPassword,
+      tunnelService: {
+        start: async () => {
+          starts += 1;
+          return { provider: 'cloudflare', publicUrl: 'https://example.com', activeMode: 'quick' };
+        },
+      },
+      TUNNEL_PROVIDER_CLOUDFLARE: 'cloudflare',
+      TUNNEL_MODE_MANAGED_REMOTE: 'managed-remote',
+    });
+    return { runtime, getStarts: () => starts };
+  };
+
+  it('rejects an unauthenticated runtime before starting any provider', async () => {
+    const { runtime, getStarts } = createRuntime(false);
+    await expect(runtime.startTunnelWithNormalizedRequest({ provider: 'cloudflare', mode: 'quick' }))
+      .rejects.toThrow('A UI password is required');
+    expect(getStarts()).toBe(0);
+  });
+
+  it('rejects the HTTP start route without disturbing an existing tunnel', async () => {
+    const { runtime, getStarts } = createRuntime(false);
+    const routes = new Map();
+    const app = {
+      get: (path, handler) => routes.set(`GET ${path}`, handler),
+      post: (path, handler) => routes.set(`POST ${path}`, handler),
+      put: (path, handler) => routes.set(`PUT ${path}`, handler),
+    };
+    runtime.registerRoutes(app);
+    let status = 200;
+    let body;
+    const response = {
+      status(code) { status = code; return this; },
+      json(payload) { body = payload; return this; },
+    };
+    await routes.get('POST /api/openchamber/tunnel/start')({ body: {} }, response);
+    expect(status).toBe(403);
+    expect(body.code).toBe('ui_password_required');
+    expect(getStarts()).toBe(0);
+  });
+
+  it('allows a password-protected runtime to start a tunnel', async () => {
+    const { runtime, getStarts } = createRuntime(true);
+    const result = await runtime.startTunnelWithNormalizedRequest({ provider: 'cloudflare', mode: 'quick' });
+    expect(result.publicUrl).toBe('https://example.com');
+    expect(getStarts()).toBe(1);
+  });
+});

package/server/lib/ui-auth/ui-auth.js

@@ -1,5 +1,11 @@
 import crypto from 'crypto';
-import { SignJWT, jwtVerify } from 'jose';
+
+// jose is loaded on the first session check, not with the server.
+let josePending;
+const loadJose = () => {
+  josePending ??= import('jose');
+  return josePending;
+};
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -267,7 +273,34 @@ const getUrlAuthTokenFromRequest = (req) => {
       token = undefined;
     }
   }
-  return typeof token === 'string' && token.trim() ? token.trim() : null;
+  if (typeof token === 'string' && token.trim()) return token.trim();
+  return getServedPageSubresourceToken(req);
+};
+
+/**
+ * An HTML file shown through `/api/fs/serve/` loads its own images, styles
+ * and scripts with plain relative URLs, which carry no token: only the page's
+ * URL has one. The browser sends that page URL as the Referer of every
+ * same-origin subresource request, so the page's token is taken from there,
+ * and only when both the page and the subresource live under `/api/fs/serve/`.
+ * Nothing else about the token changes: it is still checked for validity,
+ * expiry and scope like a query token.
+ */
+const SERVED_PAGE_PREFIX = '/api/fs/serve/';
+
+const getServedPageSubresourceToken = (req) => {
+  if (!getRequestPathname(req).startsWith(SERVED_PAGE_PREFIX)) return null;
+  const referer = req?.headers?.referer;
+  const value = Array.isArray(referer) ? referer[0] : referer;
+  if (typeof value !== 'string' || !value) return null;
+  try {
+    const url = new URL(value);
+    if (!url.pathname.startsWith(SERVED_PAGE_PREFIX)) return null;
+    const token = url.searchParams.get('oc_url_token');
+    return token && token.trim() ? token.trim() : null;
+  } catch {
+    return null;
+  }
 };
 
 const getRequestPathname = (req) => {
@@ -333,6 +366,7 @@ const isUrlAuthWebSocketPath = (pathname) => {
     || pathname === '/api/terminal/ws'
     || pathname === '/api/dictation/ws'
     || pathname === '/api/dev-tunnel'
+    || /^\/api\/guests\/[a-z][a-z0-9-]*\/surface\/ws$/.test(pathname)
     || pathname.startsWith('/api/preview/proxy/');
 };
 
@@ -726,6 +760,7 @@ export const createUiAuth = ({
       return false;
     }
     try {
+      const { jwtVerify } = await loadJose();
       await jwtVerify(token, jwtSecret);
       return true;
     } catch {
@@ -735,6 +770,7 @@ export const createUiAuth = ({
 
   const issueSession = async (req, res, { trustDevice = false } = {}) => {
     const ttlMs = resolveSessionTtlMs(trustDevice);
+    const { SignJWT } = await loadJose();
     const token = await new SignJWT({ type: 'ui-session' })
       .setProtectedHeader({ alg: 'HS256' })
       .setIssuedAt()

package/server/lib/ui-auth/ui-auth.test.js

@@ -190,6 +190,32 @@ describe('ui auth client credential seam', () => {
     });
     expect(serveCalled).toBe(true);
 
+    // A served page's own images carry no token; the page URL in the Referer
+    // stands in, but only between two paths under /api/fs/serve/.
+    const pageUrl = `http://127.0.0.1:3001/api/fs/serve/tmp/index.html?oc_url_token=${encodeURIComponent(urlToken)}`;
+    const subresourceReq = { method: 'GET', path: '/api/fs/serve/tmp/images/photo.png', url: '/api/fs/serve/tmp/images/photo.png', headers: { referer: pageUrl } };
+    const subresourceRes = createResponse();
+    let subresourceCalled = false;
+    await auth.requireAuth(subresourceReq, subresourceRes, () => {
+      subresourceCalled = true;
+    });
+    expect(subresourceCalled).toBe(true);
+
+    for (const denied of [
+      // The same referer must not open anything outside the served tree.
+      { method: 'GET', path: '/api/fs/raw', url: '/api/fs/raw?path=%2Ftmp%2Fsecret.png', headers: { referer: pageUrl } },
+      // A referer that is not a served page opens nothing.
+      { method: 'GET', path: '/api/fs/serve/tmp/images/photo.png', url: '/api/fs/serve/tmp/images/photo.png', headers: { referer: `http://127.0.0.1:3001/?oc_url_token=${encodeURIComponent(urlToken)}` } },
+    ]) {
+      const deniedRes = createResponse();
+      let deniedCalled = false;
+      await auth.requireAuth(denied, deniedRes, () => {
+        deniedCalled = true;
+      });
+      expect(deniedCalled).toBe(false);
+      expect(deniedRes.statusCode).toBe(401);
+    }
+
     const absoluteServeReq = { method: 'GET', path: '/api/fs/serve/Users/test/project/preview-test.html', url: `/api/fs/serve/Users/test/project/preview-test.html?oc_url_token=${encodeURIComponent(urlToken)}`, headers: {} };
     const absoluteServeRes = createResponse();
     let absoluteServeCalled = false;
@@ -261,6 +287,22 @@ describe('ui auth client credential seam', () => {
     };
     expect(await auth.ensureSessionToken(dictationWsReq, null)).toBe('client:device-1');
 
+    // An extension surface socket takes the session-wide URL token, never a
+    // guest-scoped one: it carries the user's pointer and keyboard.
+    const surfaceWsReq = {
+      method: 'GET',
+      path: '/api/guests/server-chrome/surface/ws',
+      url: `/api/guests/server-chrome/surface/ws?oc_url_token=${encodeURIComponent(urlToken)}`,
+      headers: { upgrade: 'websocket' },
+    };
+    expect(await auth.ensureSessionToken(surfaceWsReq, null)).toBe('client:device-1');
+    expect(await auth.ensureSessionToken({ ...surfaceWsReq, url: `/api/guests/server-chrome/surface/ws?oc_url_token=${encodeURIComponent(guestToken)}` }, null)).toBe(null);
+    expect(await auth.ensureSessionToken({
+      ...surfaceWsReq,
+      path: '/api/guests/server-chrome/surface/ws/extra',
+      url: `/api/guests/server-chrome/surface/ws/extra?oc_url_token=${encodeURIComponent(urlToken)}`,
+    }, null)).toBe(null);
+
     const devTunnelWsReq = {
       method: 'GET',
       path: '/api/dev-tunnel',