@vantran-se/openchamber-web 1.23.1 → 1.24.4

package/server/lib/terminal/runtime.test.js

@@ -134,6 +134,7 @@ function createRuntime(server, overrides = {}) {
     isExecutable: () => false,
     isRequestOriginAllowed: async () => true,
     rejectWebSocketUpgrade() {},
+    shutdownProcesses: async terminals => { for (const terminal of terminals) terminal.process.kill('SIGKILL'); },
     TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS: 30_000,
     TERMINAL_INPUT_WS_REBIND_WINDOW_MS: 1_000,
     TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW: 3,
@@ -210,6 +211,72 @@ describe('terminal runtime', () => {
     } finally { await harness.runtime.shutdown(); }
   });
 
+  it('reaps a pending create during shutdown and rejects later creates', async () => {
+    const gate = deferred();
+    const harness = createHarness({ spawnDeferred: gate });
+    const create = harness.routes.post.get('/api/terminal/create');
+    const response = createResponse();
+    const creation = create({ body: { sessionId: 'pending', cwd: '/repo' } }, response);
+    const closing = harness.runtime.shutdown();
+    gate.resolve();
+    await Promise.all([creation, closing]);
+    expect(harness.processes).toHaveLength(1);
+    expect(harness.processes[0].killed).toBe(true);
+    expect(response.statusCode).toBe(400);
+    const later = createResponse();
+    await create({ body: { sessionId: 'later', cwd: '/repo' } }, later);
+    expect(later.statusCode).toBe(400);
+    expect(harness.processes).toHaveLength(1);
+    await harness.runtime.shutdown();
+  });
+
+  it('joins terminal cleanup and retires sessions before waiting for shutdown', async () => {
+    const gate = deferred();
+    let terminals;
+    const harness = createHarness({ shutdownProcesses: async current => { terminals = current; await gate.promise; } });
+    await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'running', cwd: '/repo' } }, createResponse());
+    let done = false;
+    const closing = harness.runtime.shutdown();
+    expect(harness.runtime.shutdown()).toBe(closing);
+    closing.then(() => { done = true; });
+    await new Promise(resolve => setImmediate(resolve));
+    expect(terminals).toHaveLength(1);
+    expect(terminals[0].process).toBe(harness.processes[0]);
+    expect(done).toBe(false);
+    const later = createResponse();
+    await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'later', cwd: '/repo' } }, later);
+    expect(later.statusCode).toBe(400);
+    gate.resolve();
+    await closing;
+    expect(done).toBe(true);
+  });
+
+  for (const removal of ['close', 'force-kill']) {
+    it(`reaps a replacement PTY when ${removal} wins a pending restart`, async () => {
+      const gate = { promise: Promise.resolve() };
+      const harness = createHarness({ spawnDeferred: gate });
+      try {
+        await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'terminal', cwd: '/repo' } }, createResponse());
+        const replacement = deferred();
+        gate.promise = replacement.promise;
+        const response = createResponse();
+        const restarting = harness.routes.post.get('/api/terminal/:sessionId/restart')({ params: { sessionId: 'terminal' }, body: {} }, response);
+        await new Promise((resolve) => setImmediate(resolve));
+        const removed = createResponse();
+        if (removal === 'close') {
+          await harness.routes.delete.get('/api/terminal/:sessionId')({ params: { sessionId: 'terminal' } }, removed);
+        } else {
+          harness.routes.post.get('/api/terminal/force-kill')({ body: { sessionId: 'terminal' } }, removed);
+        }
+        replacement.resolve();
+        await restarting;
+        expect(harness.processes).toHaveLength(2);
+        expect(harness.processes.every((child) => child.killed)).toBe(true);
+        expect(response.statusCode).toBe(400);
+      } finally { await harness.runtime.shutdown(); }
+    });
+  }
+
   it('retains completed output when the replacement command fails to start', async () => {
     let available = true;
     const harness = createHarness({ fs: { promises: { stat: async () => ({ isDirectory: () => available }) } } });

package/server/lib/terminal/shutdown.js

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const SHUTDOWN_GRACE_MS = 20_000;
+
+// Job-control shells give foreground/background jobs their own process groups.
+// Killing only -pty.pid misses those jobs; closing the PTY first sends SIGHUP.
+const readProcesses = async () => {
+  // Minimal server/container installations need not ship procps.
+  if (process.platform === 'linux') {
+    const processes = new Map();
+    for (const entry of await fs.readdir('/proc')) {
+      if (!/^\d+$/.test(entry)) continue;
+      let stat;
+      try { stat = await fs.readFile(`/proc/${entry}/stat`, 'utf8'); }
+      catch (error) { if (error.code === 'ENOENT' || error.code === 'ESRCH') continue; throw error; }
+      const end = stat.lastIndexOf(')');
+      const fields = stat.slice(end + 2).trim().split(/\s+/);
+      const pid = Number(entry);
+      processes.set(pid, { pid, parent: Number(fields[1]), group: Number(fields[2]), zombie: fields[0] === 'Z', started: fields[19], command: stat.slice(stat.indexOf('(') + 1, end) });
+    }
+    return processes;
+  }
+  const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,ppid=,pgid=,stat=,lstart=,comm='], { timeout: 1000, maxBuffer: 4 * 1024 * 1024 });
+  return new Map(stdout.trim().split('\n').map(line => {
+    const fields = line.trim().split(/\s+/);
+    return [Number(fields[0]), { pid: Number(fields[0]), parent: Number(fields[1]), group: Number(fields[2]), zombie: fields[3].startsWith('Z'), started: fields.slice(4, 9).join(' '), command: fields.slice(9).join(' ') }];
+  }));
+};
+
+const signal = (pid, name) => {
+  try { process.kill(pid, name); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+};
+
+export async function shutdownTerminalProcesses(terminals, { graceMs = SHUTDOWN_GRACE_MS } = {}) {
+  if (!terminals.length) return;
+  // ConPTY has no POSIX signal protocol. Its backend owns tree teardown.
+  if (process.platform === 'win32') {
+    for (const { process: pty } of terminals) {
+      try { pty.kill(); } catch { /* already gone; other terminals still need cleanup */ }
+    }
+    return;
+  }
+
+  const deadline = Date.now() + graceMs;
+  const owned = new Map();
+  const shells = new Map();
+  try {
+    let snapshot = await readProcesses();
+    for (const terminal of terminals) {
+      const current = snapshot.get(terminal.process.pid);
+      if (!current || current.zombie) continue;
+      owned.set(current.pid, { ...current, terminal: current.pid });
+      // An exec'ed server occupies the shell PID, but must get the same grace
+      // as a child. Only an actual shell is held open until its jobs finish.
+      if (path.basename(current.command) === path.basename(terminal.shellExecutable)) shells.set(current.pid, terminal.process);
+    }
+    const signalled = new Set();
+    while (owned.size) {
+      for (const [pid, previous] of owned) {
+        const current = snapshot.get(pid);
+        if (!current || current.zombie || current.started !== previous.started) { owned.delete(pid); shells.delete(pid); }
+        else if (current.command !== previous.command) shells.delete(pid);
+      }
+      // Retain descendants before signalling anything, including separate job
+      // groups and children still cleaning up after their parent has exited.
+      let added;
+      do {
+        added = false;
+        for (const current of snapshot.values()) {
+          if (!current.zombie && !owned.has(current.pid) && owned.has(current.parent)) {
+            owned.set(current.pid, { ...current, terminal: owned.get(current.parent).terminal });
+            added = true;
+          }
+        }
+      } while (added);
+      for (const pid of owned.keys()) {
+        if (!shells.has(pid) && !signalled.has(pid)) { signal(pid, 'SIGTERM'); signalled.add(pid); }
+      }
+      for (const [pid, pty] of shells) {
+        const hasJobs = [...owned.values()].some(current => current.terminal === pid && current.pid !== pid);
+        if (!hasJobs && !signalled.has(pid)) { pty.kill('SIGHUP'); signalled.add(pid); }
+      }
+      if (!owned.size) return;
+      if (Date.now() >= deadline) {
+        for (const current of owned.values()) {
+          if (current.group === current.pid) signal(-current.group, 'SIGKILL');
+          signal(current.pid, 'SIGKILL');
+        }
+        return;
+      }
+      await new Promise(resolve => setTimeout(resolve, 250));
+      snapshot = await readProcesses();
+    }
+  } catch (error) {
+    // A failed process-table read is not evidence that the jobs exited.
+    console.warn('Terminal graceful shutdown failed; forcing owned PTYs closed:', error.message);
+    for (const pid of owned.keys()) { try { signal(pid, 'SIGKILL'); } catch { /* best effort */ } }
+    for (const { process: pty } of terminals) {
+      try { pty.kill('SIGKILL'); } catch { /* continue with the remaining PTYs */ }
+    }
+  }
+}

package/server/lib/terminal/shutdown.test.js

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import { shutdownTerminalProcesses } from './shutdown.js';
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const script = `
+const fs = require('node:fs');
+const [file, mode] = process.argv.slice(1);
+const record = event => fs.appendFileSync(file, JSON.stringify({ pid: process.pid, event }) + '\\n');
+process.on('SIGHUP', () => record('SIGHUP'));
+process.on('SIGTERM', () => {
+  record('SIGTERM');
+  if (mode === 'ignore') return;
+  if (mode === 'parent') return process.exit(0);
+  setTimeout(() => { record('complete'); process.exit(0); }, 250);
+});
+record('ready');
+setInterval(() => {}, 1000);
+`;
+
+async function fixture(t, mode) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'terminal-shutdown-'));
+  const file = path.join(dir, 'events.jsonl');
+  const source = script + (mode === 'parent' ? `require('node:child_process').spawn(process.execPath, ['-e', ${JSON.stringify(script)}, file, 'worker'], { detached: true, stdio: 'ignore' }).unref();` : '');
+  const child = spawn(process.execPath, ['-e', source, file, mode], { detached: true, stdio: 'ignore' });
+  const exit = new Promise(resolve => child.once('exit', (code, signal) => resolve({ code, signal })));
+  const events = async () => { try { return (await fs.readFile(file, 'utf8')).trim().split('\n').map(line => JSON.parse(line)); } catch (error) { if (error.code === 'ENOENT') return []; throw error; } };
+  t.onTestFinished(async () => {
+    for (const pid of new Set([child.pid, ...(await events()).map(event => event.pid)])) {
+      try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+    }
+    await exit;
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+  const count = mode === 'parent' ? 2 : 1;
+  for (let i = 0; i < 100 && (await events()).filter(event => event.event === 'ready').length < count; i++) await delay(20);
+  assert.equal((await events()).filter(event => event.event === 'ready').length, count);
+  return { terminal: { process: { pid: child.pid, kill: signal => child.kill(signal) }, shellExecutable: '/bin/sh' }, events, exit };
+}
+
+test('graceful shutdown lets concurrent exec workloads finish without SIGHUP or SIGKILL', { skip: process.platform === 'win32' }, async t => {
+  const first = await fixture(t, 'worker');
+  const second = await fixture(t, 'worker');
+  await shutdownTerminalProcesses([first.terminal, second.terminal], { graceMs: 1500 });
+  for (const run of [first, second]) {
+    assert.deepEqual((await run.events()).map(event => event.event), ['ready', 'SIGTERM', 'complete']);
+    assert.deepEqual(await run.exit, { code: 0, signal: null });
+  }
+});
+
+test('waits for a separate process group after its parent exits', { skip: process.platform === 'win32' }, async t => {
+  const run = await fixture(t, 'parent');
+  await shutdownTerminalProcesses([run.terminal], { graceMs: 1500 });
+  const events = await run.events();
+  assert.equal(events.filter(event => event.event === 'SIGTERM').length, 2);
+  assert.equal(events.filter(event => event.event === 'complete').length, 1);
+  assert.deepEqual(await run.exit, { code: 0, signal: null });
+});
+
+test('escalates a noncooperative workload only after the shared deadline', { skip: process.platform === 'win32' }, async t => {
+  const run = await fixture(t, 'ignore');
+  const start = Date.now();
+  await shutdownTerminalProcesses([run.terminal], { graceMs: 350 });
+  assert.ok(Date.now() - start >= 350);
+  assert.deepEqual((await run.events()).map(event => event.event), ['ready', 'SIGTERM']);
+  assert.deepEqual(await run.exit, { code: null, signal: 'SIGKILL' });
+});
+
+test('an idle shell closes promptly and shutdown waits for its exit', { skip: process.platform === 'win32' }, async t => {
+  const child = spawn('/bin/sh', ['-i'], { detached: true, stdio: 'pipe' });
+  child.stdout.resume();
+  child.stderr.resume();
+  const exit = new Promise(resolve => child.once('exit', (code, signal) => resolve({ code, signal })));
+  t.onTestFinished(async () => { child.kill('SIGKILL'); await exit; });
+  await delay(100);
+  const start = Date.now();
+  await shutdownTerminalProcesses([{ process: { pid: child.pid, kill: signal => child.kill(signal) }, shellExecutable: '/bin/sh' }]);
+  assert.ok(Date.now() - start < 3000);
+  assert.equal((await exit).signal, 'SIGHUP');
+});

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

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { createServer } from 'node:http';
+import { once } from 'node:events';
+import { TTSService } from './service.js';
+import { transcribeAudio } from './stt.js';
+
+describe('OpenAI audio SDK compatibility', () => {
+  let server;
+
+  afterEach(async () => {
+    if (server) {
+      await new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+        server.closeAllConnections();
+      });
+      server = undefined;
+    }
+  });
+
+  const listen = async (handler) => {
+    server = createServer(handler);
+    server.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    return `http://127.0.0.1:${server.address().port}/v1`;
+  };
+
+  it('sends custom speech options and returns the audio bytes', async () => {
+    const audio = Buffer.from('speech-response');
+    let received;
+    const baseURL = await listen(async (request, response) => {
+      const chunks = [];
+      for await (const chunk of request) chunks.push(chunk);
+      received = { url: request.url, method: request.method, body: JSON.parse(Buffer.concat(chunks).toString()) };
+      response.writeHead(200, { 'Content-Type': 'audio/mpeg' });
+      response.end(audio);
+    });
+
+    const result = await new TTSService().generateSpeechStream({
+      text: 'Hello', model: 'custom-tts', voice: 'coral', speed: 1.2, baseURL,
+    });
+
+    expect(received).toEqual({
+      url: '/v1/audio/speech', method: 'POST',
+      body: { input: 'Hello', model: 'custom-tts', voice: 'coral', speed: 1.2 },
+    });
+    expect(result).toEqual({ buffer: audio, contentType: 'audio/mpeg' });
+  });
+
+  it('uploads transcription audio as multipart data and reads the text', async () => {
+    const audio = Buffer.from('transcription-input');
+    let received;
+    const baseURL = await listen(async (request, response) => {
+      const chunks = [];
+      for await (const chunk of request) chunks.push(chunk);
+      const form = await new Response(Buffer.concat(chunks), {
+        headers: { 'Content-Type': request.headers['content-type'] },
+      }).formData();
+      const file = form.get('file');
+      received = {
+        url: request.url, method: request.method,
+        model: form.get('model'), language: form.get('language'), format: form.get('response_format'),
+        filename: file.name, audio: Buffer.from(await file.arrayBuffer()),
+      };
+      response.writeHead(200, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ text: 'Hello from transcription' }));
+    });
+
+    const result = await transcribeAudio({
+      audioBuffer: audio, mimeType: 'audio/webm', model: 'whisper-1', language: 'en', baseURL,
+    });
+
+    expect(received).toEqual({
+      url: '/v1/audio/transcriptions', method: 'POST', model: 'whisper-1', language: 'en',
+      format: 'json', filename: 'audio.webm', audio,
+    });
+    expect(result).toBe('Hello from transcription');
+  });
+});

package/server/lib/ui-auth/DOCUMENTATION.md

@@ -10,9 +10,17 @@ Pairing v2 is implemented by `packages/web/server/lib/client-auth/pairing.js`. I
 ## Entrypoints and structure
 - `packages/web/server/lib/ui-auth/ui-auth.js`: UI auth controller runtime, cookie/session issuance, rate limiting, and auth route handlers.
 - `packages/web/server/lib/ui-auth/ui-passkeys.js`: passkey store and WebAuthn registration/authentication verification helpers.
+- `packages/web/server/lib/ui-auth/session-cookie.js`: resolves the session cookie name from a request's `Host` port; shared by session issuance and validation in `ui-auth.js` and notification/session identity extraction in `packages/web/server/lib/security/request-security.js`.
 - `packages/web/server/lib/client-auth/remote-clients.js`: trusted-device client token storage, bearer authentication, last-used tracking, and revocation.
 - `packages/web/server/lib/client-auth/pairing.js`: short-lived Pairing v2 sessions and one-time secret redemption into trusted-device client tokens.
 
+## Session cookie scoping
+Browsers key a cookie jar on the host only, never the port (RFC 6265). Two OpenChamber instances reached through the same hostname on different ports therefore shared a single `oc_ui_session` cookie. Logging into the second overwrote the first instance's session cookie (issue #2377). This affects LAN and loopback hosts alike.
+
+`sessionCookieNameForRequest(req, base)` folds the request `Host` port into the cookie name: `oc_ui_session_<port>` when the host carries an explicit port (including a port from `x-forwarded-host`), or the bare `oc_ui_session` when it does not. `localhost:3000` and `localhost:3001` use separate names, just like two ports on one LAN address. Password and browser passkey login both call `issueSession` and receive this cookie. Session validation, clearing, and notification identity extraction use the same resolver; identity extraction does not provide a CSRF token. Bearer-token validation is unchanged.
+
+Compatibility: upgrading renames the cookie for any explicit-port host, so already-signed-in browser sessions must log in once again. No on-disk format changes.
+
 ## Public exports (ui-auth.js)
 - `createUiAuth({ password, cookieName, sessionTtlMs, readSettingsFromDiskMigrated })`: creates UI auth controller with methods:
   - `enabled`

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

@@ -0,0 +1,51 @@
+/**
+ * Session cookie naming that is stable per host:port.
+ *
+ * Browsers do not isolate cookies by port (RFC 6265). Instances on the same
+ * hostname overwrite one another's session cookies without distinct names.
+ * This applies to LAN addresses and same-host loopback instances alike.
+ *
+ * We fold the request port into the cookie name so each port owns its own
+ * cookie. Password/passkey session issuance and validation (`ui-auth.js`) and
+ * notification identity extraction (`request-security.js`) share this resolver.
+ * A host with no explicit port keeps the bare `oc_ui_session` name.
+ */
+export const SESSION_COOKIE_BASE = 'oc_ui_session';
+
+const forwardedHost = (headers) => {
+  const forwarded = headers?.['x-forwarded-host'];
+  if (typeof forwarded === 'string' && forwarded.trim().length > 0) {
+    return forwarded.split(',')[0].trim();
+  }
+  const host = headers?.host;
+  return typeof host === 'string' ? host.trim() : '';
+};
+
+/**
+ * Extract the trailing port from a Host authority, or null when there is none.
+ * Handles bracketed IPv6 (`[::1]:3000`, `[::1]`) and plain host names.
+ */
+const hostPort = (host) => {
+  if (host.startsWith('[')) {
+    const end = host.indexOf(']');
+    if (end === -1) return null;
+    const rest = host.slice(end + 1);
+    if (!rest.startsWith(':')) return null;
+    return /^\d+$/.test(rest.slice(1)) ? rest.slice(1) : null;
+  }
+  const matches = host.match(/:(\d+)$/);
+  return matches ? matches[1] : null;
+};
+
+/**
+ * Resolve the session cookie name for a request. Returns the bare base name
+ * when the host carries no explicit port, otherwise `<base>_<port>`.
+ */
+export const sessionCookieNameForRequest = (req, base = SESSION_COOKIE_BASE) => {
+  const host = forwardedHost(req?.headers || {});
+  const port = host ? hostPort(host) : null;
+  if (!port) return base;
+  const portNumber = Number.parseInt(port, 10);
+  if (!Number.isFinite(portNumber) || portNumber <= 0) return base;
+  return `${base}_${port}`;
+};

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

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  SESSION_COOKIE_BASE,
+  sessionCookieNameForRequest,
+} from './session-cookie.js';
+
+const req = (host, forwarded) => ({
+  headers: {
+    ...(host ? { host } : {}),
+    ...(forwarded ? { 'x-forwarded-host': forwarded } : {}),
+  },
+});
+
+describe('sessionCookieNameForRequest', () => {
+  test('keeps the bare base name when the host has no explicit port', () => {
+    expect(sessionCookieNameForRequest(req('192.168.0.1'))).toBe(SESSION_COOKIE_BASE);
+    expect(sessionCookieNameForRequest(req('example.com'))).toBe(SESSION_COOKIE_BASE);
+    expect(sessionCookieNameForRequest(req(''))).toBe(SESSION_COOKIE_BASE);
+    expect(sessionCookieNameForRequest(undefined)).toBe(SESSION_COOKIE_BASE);
+  });
+
+  test('folds the port into the name so LAN instances on one IP are isolated', () => {
+    expect(sessionCookieNameForRequest(req('192.168.0.1:3000'))).toBe('oc_ui_session_3000');
+    expect(sessionCookieNameForRequest(req('192.168.0.1:3001'))).toBe('oc_ui_session_3001');
+    expect(sessionCookieNameForRequest(req('192.168.0.1:8080'))).toBe('oc_ui_session_8080');
+  });
+
+  test('handles IPv6 authorities', () => {
+    expect(sessionCookieNameForRequest(req('[::1]:3000'))).toBe('oc_ui_session_3000');
+    expect(sessionCookieNameForRequest(req('[::1]'))).toBe(SESSION_COOKIE_BASE);
+  });
+
+  test('prefers the forwarded host port over the direct host', () => {
+    expect(sessionCookieNameForRequest(req('127.0.0.1:3902', '203.0.113.9:8443')))
+      .toBe('oc_ui_session_8443');
+  });
+
+  test('ignores malformed or non-numeric ports', () => {
+    expect(sessionCookieNameForRequest(req('192.168.0.1:notaport'))).toBe(SESSION_COOKIE_BASE);
+  });
+
+  test('honours a custom base name', () => {
+    expect(sessionCookieNameForRequest(req('127.0.0.1:3000'), 'my_app')).toBe('my_app_3000');
+    expect(sessionCookieNameForRequest(req('127.0.0.1'), 'my_app')).toBe('my_app');
+  });
+});

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

@@ -4,6 +4,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { createUiPasskeys } from './ui-passkeys.js';
+import { sessionCookieNameForRequest } from './session-cookie.js';
 
 const SESSION_COOKIE_NAME = 'oc_ui_session';
 const SESSION_TTL_MS = 12 * 60 * 60 * 1000;
@@ -291,6 +292,25 @@ const isWebSocketUpgrade = (req) => {
   return String(upgradeValue || '').toLowerCase() === 'websocket';
 };
 
+const GUEST_URL_AUTH_SCOPE = /^guest:([a-z][a-z0-9-]*)$/;
+
+/**
+ * A URL token scope narrows where the token is accepted. `guest:<id>` is
+ * minted for a guest iframe and only opens that guest's own package files:
+ * the iframe URL is readable by the guest's script, so the token must be
+ * worthless anywhere else.
+ * @returns {{ kind: 'guest', id: string } | null | undefined} `undefined` when the value is not a scope
+ */
+const parseUrlAuthScope = (value) => {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw !== 'string') return undefined;
+  const match = raw.trim().match(GUEST_URL_AUTH_SCOPE);
+  return match ? { kind: 'guest', id: match[1] } : undefined;
+};
+
+const isGuestScopedPath = (pathname, guestId) => pathname.startsWith(`/api/guests/${guestId}/`);
+
 const isUrlAuthReadableHttpPath = (pathname) => {
   return pathname === '/api/event'
     || pathname === '/api/global/event'
@@ -301,7 +321,9 @@ const isUrlAuthReadableHttpPath = (pathname) => {
     || pathname === '/api/fs/serve'
     || pathname.startsWith('/api/fs/serve/')
     || pathname.startsWith('/api/preview/proxy/')
-    || /^\/api\/projects\/[^/]+\/icon$/.test(pathname);
+    || /^\/api\/projects\/[^/]+\/icon$/.test(pathname)
+    || pathname === '/api/guests'
+    || /^\/api\/guests\/[a-z][a-z0-9-]*\//.test(pathname);
 };
 
 const isUrlAuthWebSocketPath = (pathname) => {
@@ -314,9 +336,12 @@ const isUrlAuthWebSocketPath = (pathname) => {
     || pathname.startsWith('/api/preview/proxy/');
 };
 
-const canUseUrlAuthTokenForRequest = (req) => {
+const canUseUrlAuthTokenForRequest = (req, scope = null) => {
   const method = typeof req?.method === 'string' ? req.method.toUpperCase() : 'GET';
   const pathname = getRequestPathname(req);
+  if (scope?.kind === 'guest') {
+    return !isWebSocketUpgrade(req) && method === 'GET' && isGuestScopedPath(pathname, scope.id);
+  }
   if (isWebSocketUpgrade(req)) {
     return isUrlAuthWebSocketPath(pathname);
   }
@@ -425,16 +450,15 @@ export const createUiAuth = ({
     }
   };
 
-  const issueUrlAuthTokenForSession = (sessionToken) => {
+  const issueUrlAuthTokenForSession = (sessionToken, scope = null) => {
     sweepUrlAuthTokens();
     const token = `${URL_AUTH_TOKEN_PREFIX}${crypto.randomBytes(24).toString('base64url')}`;
     const expiresAt = Date.now() + URL_AUTH_TOKEN_TTL_MS;
-    urlAuthTokens.set(token, { sessionToken, expiresAt });
+    urlAuthTokens.set(token, { sessionToken, expiresAt, scope });
     return { token, expiresAt };
   };
 
   const authenticateUrlAuthToken = (req) => {
-    if (!canUseUrlAuthTokenForRequest(req)) return null;
     const token = getUrlAuthTokenFromRequest(req);
     if (!token || !token.startsWith(URL_AUTH_TOKEN_PREFIX)) return null;
     const entry = urlAuthTokens.get(token);
@@ -442,9 +466,13 @@ export const createUiAuth = ({
       urlAuthTokens.delete(token);
       return null;
     }
+    if (!canUseUrlAuthTokenForRequest(req, entry.scope)) return null;
     return { ok: true, sessionToken: entry.sessionToken || 'url:authenticated' };
   };
 
+  /** Scope requested on `POST /auth/url-token`: `?scope=guest:<id>` or `{ scope }` in the body. */
+  const readRequestedUrlAuthScope = (req) => parseUrlAuthScope(req?.body?.scope ?? req?.query?.scope);
+
   const authenticateClientRequest = async (req, { allowUrlToken = true } = {}) => {
     if (allowUrlToken) {
       const urlAuth = authenticateUrlAuthToken(req);
@@ -489,7 +517,7 @@ export const createUiAuth = ({
       const secure = isSecureRequest(req);
       const maxAgeSeconds = Math.floor(ttlMs / 1000);
       const header = buildCookie({
-        name: cookieName,
+        name: sessionCookieNameForRequest(req, cookieName),
         value: encodeURIComponent(token),
         maxAge: maxAgeSeconds,
         secure,
@@ -499,8 +527,9 @@ export const createUiAuth = ({
 
     const ensureSessionToken = async (req, res) => {
       const cookies = parseCookies(req.headers.cookie);
-      if (cookies[cookieName]) {
-        return cookies[cookieName];
+      const name = sessionCookieNameForRequest(req, cookieName);
+      if (cookies[name]) {
+        return cookies[name];
       }
       const token = crypto.randomBytes(32).toString('base64url');
       setSessionCookie(req, res, token, sessionTtlMs);
@@ -533,8 +562,9 @@ export const createUiAuth = ({
 
     const resolveAuthContext = async (req, res, { allowClientAuth = true, allowUrlToken = true } = {}) => {
       const cookies = parseCookies(req.headers.cookie);
-      if (cookies[cookieName]) {
-        return { type: 'session', token: cookies[cookieName] };
+      const name = sessionCookieNameForRequest(req, cookieName);
+      if (cookies[name]) {
+        return { type: 'session', token: cookies[name] };
       }
       if (allowClientAuth) {
         const clientAuth = await authenticateClientRequest(req, { allowUrlToken });
@@ -566,17 +596,21 @@ export const createUiAuth = ({
         res.status(400).json({ error: 'UI password not configured' });
       },
       handleUrlAuthToken: async (req, res) => {
+        const scope = readRequestedUrlAuthScope(req);
+        if (scope === undefined) {
+          return res.status(400).json({ error: 'Unknown URL token scope' });
+        }
         const clientAuth = await authenticateClientRequest(req, { allowUrlToken: false });
         if (clientAuth) {
           res.setHeader('Cache-Control', 'no-store');
-          return res.json(issueUrlAuthTokenForSession(clientSessionToken(clientAuth)));
+          return res.json(issueUrlAuthTokenForSession(clientSessionToken(clientAuth), scope));
         }
         if (requireClientAuth) {
           return res.status(401).json({ error: 'Client authentication required', locked: true, clientAuthRequired: true });
         }
         const sessionToken = await ensureSessionToken(req, res);
         res.setHeader('Cache-Control', 'no-store');
-        return res.json(issueUrlAuthTokenForSession(sessionToken));
+        return res.json(issueUrlAuthTokenForSession(sessionToken, scope));
       },
       handlePasskeyStatus: (_req, res) => {
         res.json({ enabled: false, hasPasskeys: false, passkeyCount: 0, rpID: null });
@@ -641,8 +675,9 @@ export const createUiAuth = ({
 
   const getTokenFromRequest = (req) => {
     const cookies = parseCookies(req.headers.cookie);
-    if (cookies[cookieName]) {
-      return cookies[cookieName];
+    const name = sessionCookieNameForRequest(req, cookieName);
+    if (cookies[name]) {
+      return cookies[name];
     }
     return null;
   };
@@ -651,7 +686,7 @@ export const createUiAuth = ({
     const secure = isSecureRequest(req);
     const maxAgeSeconds = Math.floor(ttlMs / 1000);
     const header = buildCookie({
-      name: cookieName,
+      name: sessionCookieNameForRequest(req, cookieName),
       value: encodeURIComponent(token),
       maxAge: maxAgeSeconds,
       secure,
@@ -662,7 +697,7 @@ export const createUiAuth = ({
   const clearSessionCookie = (req, res) => {
     const secure = isSecureRequest(req);
     const header = buildCookie({
-      name: cookieName,
+      name: sessionCookieNameForRequest(req, cookieName),
       value: '',
       maxAge: 0,
       secure,
@@ -799,13 +834,17 @@ export const createUiAuth = ({
   };
 
   const handleUrlAuthToken = async (req, res) => {
+    const scope = readRequestedUrlAuthScope(req);
+    if (scope === undefined) {
+      return res.status(400).json({ error: 'Unknown URL token scope' });
+    }
     const sessionToken = await resolveAuthenticatedSessionToken(req, { allowUrlToken: false });
     if (!sessionToken) {
       clearSessionCookie(req, res);
       return respondUnauthorized(req, res);
     }
     res.setHeader('Cache-Control', 'no-store');
-    return res.json(issueUrlAuthTokenForSession(sessionToken));
+    return res.json(issueUrlAuthTokenForSession(sessionToken, scope));
   };
 
   const handleSessionCreate = async (req, res) => {