@vantran-se/openchamber-web 1.23.1 → 1.24.3

package/server/lib/guests/files.test.js

@@ -0,0 +1,262 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { GUEST_FILE_CONTENT_MAX, GUEST_FILE_LIST_MAX } from '@openchamber/sdk';
+
+import {
+  expandHome,
+  globToRegExp,
+  matchesFilesystemPattern,
+  resolveGuestFilePath,
+  runGuestFileOperation,
+} from './files.js';
+
+const tempDirs = [];
+
+const makeTemp = async (prefix) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  const real = await fs.realpath(dir);
+  tempDirs.push(real);
+  return real;
+};
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe('expandHome and globToRegExp', () => {
+  test('expands ~ and ~/ against the home directory', () => {
+    expect(expandHome('~/.config/x', '/home/ada')).toBe('/home/ada/.config/x');
+    expect(expandHome('~/.config/x', '/home/ada/')).toBe('/home/ada/.config/x');
+    expect(expandHome('~', '/home/ada')).toBe('/home/ada');
+    expect(expandHome('/etc/x', '/home/ada')).toBe('/etc/x');
+  });
+
+  test('** spans directories, * and ? stay inside one segment', () => {
+    expect(globToRegExp('/a/**/c.txt').test('/a/c.txt')).toBe(true);
+    expect(globToRegExp('/a/**/c.txt').test('/a/b/x/c.txt')).toBe(true);
+    expect(globToRegExp('/a/*.txt').test('/a/c.txt')).toBe(true);
+    expect(globToRegExp('/a/*.txt').test('/a/b/c.txt')).toBe(false);
+    expect(globToRegExp('/a/?.txt').test('/a/c.txt')).toBe(true);
+    expect(globToRegExp('/a/?.txt').test('/a/cc.txt')).toBe(false);
+    expect(globToRegExp('/a/b.txt').test('/a/bxtxt')).toBe(false);
+  });
+
+  test('a directory pattern matches the directory and everything below', () => {
+    const pattern = globToRegExp('/tmp/probe/**');
+    expect(pattern.test('/tmp/probe')).toBe(true);
+    expect(pattern.test('/tmp/probe/a')).toBe(true);
+    expect(pattern.test('/tmp/probe/a/b/c')).toBe(true);
+    expect(pattern.test('/tmp/probes')).toBe(false);
+    expect(pattern.test('/tmp')).toBe(false);
+  });
+});
+
+describe('matchesFilesystemPattern', () => {
+  test('matches on the expanded home pattern only', () => {
+    const patterns = ['~/.config/opencode/opencode.json', '/tmp/probe/**'];
+    expect(matchesFilesystemPattern('/home/ada/.config/opencode/opencode.json', patterns, '/home/ada')).toBe(true);
+    expect(matchesFilesystemPattern('/home/ada/.config/opencode/other.json', patterns, '/home/ada')).toBe(false);
+    expect(matchesFilesystemPattern('/tmp/probe/deep/file', patterns, '/home/ada')).toBe(true);
+    expect(matchesFilesystemPattern('/etc/hosts', patterns, '/home/ada')).toBe(false);
+    expect(matchesFilesystemPattern('/etc/hosts', [], '/home/ada')).toBe(false);
+  });
+});
+
+describe('resolveGuestFilePath', () => {
+  test('accepts a relative path inside the project and refuses .. anywhere', async () => {
+    const project = await makeTemp('oc-files-project-');
+    await fs.writeFile(path.join(project, 'README.md'), '# hi');
+    const inside = await resolveGuestFilePath({ path: 'README.md', projectDirectory: project, patterns: [], homeDir: os.homedir() });
+    expect(inside).toEqual({ ok: true, scope: 'project', absolute: path.join(project, 'README.md') });
+    const dot = await resolveGuestFilePath({ path: '.', projectDirectory: project, patterns: [], homeDir: os.homedir() });
+    expect(dot).toEqual({ ok: true, scope: 'project', absolute: project });
+    for (const bad of ['../etc/passwd', 'src/../../x', '~/../x', '/tmp/../etc', 'a\\b', 'a\0b', '']) {
+      const result = await resolveGuestFilePath({ path: bad, projectDirectory: project, patterns: ['/**'], homeDir: os.homedir() });
+      expect(result).toMatchObject({ ok: false, code: 'BAD_PATH' });
+    }
+  });
+
+  test('is NO_DIRECTORY for a relative path without a project', async () => {
+    const result = await resolveGuestFilePath({ path: 'README.md', projectDirectory: null, patterns: [], homeDir: os.homedir() });
+    expect(result).toMatchObject({ ok: false, code: 'NO_DIRECTORY' });
+  });
+
+  test('refuses a symlink that escapes the project', async () => {
+    const project = await makeTemp('oc-files-project-');
+    const outside = await makeTemp('oc-files-outside-');
+    await fs.writeFile(path.join(outside, 'secret.txt'), 'nope');
+    await fs.symlink(outside, path.join(project, 'link'));
+    const viaLink = await resolveGuestFilePath({ path: 'link/secret.txt', projectDirectory: project, patterns: [], homeDir: os.homedir() });
+    expect(viaLink).toMatchObject({ ok: false, code: 'BAD_PATH' });
+    // A file that does not exist yet under the escaping link is still outside.
+    const newViaLink = await resolveGuestFilePath({ path: 'link/new.txt', projectDirectory: project, patterns: [], homeDir: os.homedir() });
+    expect(newViaLink).toMatchObject({ ok: false, code: 'BAD_PATH' });
+  });
+
+  test('accepts an outside path only when a declared pattern covers its canonical form', async () => {
+    const home = await makeTemp('oc-files-home-');
+    const probe = await makeTemp('oc-files-probe-');
+    await fs.mkdir(path.join(home, '.config', 'opencode'), { recursive: true });
+    const declared = await resolveGuestFilePath({
+      path: '~/.config/opencode/opencode.json',
+      projectDirectory: null,
+      patterns: ['~/.config/opencode/opencode.json', `${probe}/**`],
+      homeDir: home,
+    });
+    expect(declared).toEqual({ ok: true, scope: 'filesystem', absolute: path.join(home, '.config', 'opencode', 'opencode.json') });
+    const below = await resolveGuestFilePath({ path: `${probe}/a/b.txt`, projectDirectory: null, patterns: [`${probe}/**`], homeDir: home });
+    expect(below).toEqual({ ok: true, scope: 'filesystem', absolute: path.join(probe, 'a', 'b.txt') });
+    const undeclared = await resolveGuestFilePath({ path: '/etc/hosts', projectDirectory: null, patterns: ['~/.config/opencode/opencode.json'], homeDir: home });
+    expect(undeclared).toMatchObject({ ok: false, code: 'BAD_PATH' });
+    const none = await resolveGuestFilePath({ path: `${probe}/a`, projectDirectory: null, patterns: [], homeDir: home });
+    expect(none).toMatchObject({ ok: false, code: 'BAD_PATH' });
+  });
+
+  test('matches through a symlinked pattern prefix and refuses a symlink out of the granted tree', async () => {
+    const real = await makeTemp('oc-files-real-');
+    const holder = await makeTemp('oc-files-holder-');
+    const outside = await makeTemp('oc-files-outside-');
+    const link = path.join(holder, 'link');
+    await fs.symlink(real, link);
+    // Pattern names the symlink; the candidate canonicalizes to the real dir.
+    const viaLinkPattern = await resolveGuestFilePath({ path: `${link}/x.txt`, projectDirectory: null, patterns: [`${link}/**`], homeDir: holder });
+    expect(viaLinkPattern).toEqual({ ok: true, scope: 'filesystem', absolute: path.join(real, 'x.txt') });
+    // A symlink inside the granted tree pointing elsewhere is refused.
+    await fs.symlink(outside, path.join(real, 'escape'));
+    const escape = await resolveGuestFilePath({ path: `${real}/escape/y.txt`, projectDirectory: null, patterns: [`${real}/**`], homeDir: holder });
+    expect(escape).toMatchObject({ ok: false, code: 'BAD_PATH' });
+  });
+});
+
+describe('runGuestFileOperation', () => {
+  const base = async () => {
+    const project = await makeTemp('oc-files-project-');
+    const probe = await makeTemp('oc-files-probe-');
+    return {
+      project,
+      probe,
+      run: (overrides) => runGuestFileOperation({
+        projectDirectory: project,
+        patterns: [`${probe}/**`],
+        grants: ['files', 'filesystem'],
+        homeDir: os.homedir(),
+        ...overrides,
+      }),
+    };
+  };
+
+  test('needs files for the project and filesystem for outside', async () => {
+    const { probe, run } = await base();
+    expect(await run({ op: 'stat', path: 'README.md', grants: ['filesystem'] })).toMatchObject({ ok: false, code: 'NOT_GRANTED' });
+    expect(await run({ op: 'stat', path: `${probe}/x`, grants: ['files'] })).toMatchObject({ ok: false, code: 'NOT_GRANTED' });
+    expect(await run({ op: 'stat', path: 'README.md', grants: [] })).toMatchObject({ ok: false, code: 'NOT_GRANTED' });
+    expect(await run({ op: 'stat', path: 'README.md' })).toEqual({ ok: true, result: { kind: 'missing', size: 0, mtime: 0 } });
+  });
+
+  test('reads, stats, and reports a missing file as NOT_FOUND', async () => {
+    const { project, run } = await base();
+    await fs.writeFile(path.join(project, 'README.md'), '# hi');
+    expect(await run({ op: 'read', path: 'README.md' })).toEqual({ ok: true, result: { content: '# hi' } });
+    expect(await run({ op: 'read', path: 'missing.md' })).toMatchObject({ ok: false, code: 'NOT_FOUND' });
+    expect(await run({ op: 'read', path: '.' })).toMatchObject({ ok: false, code: 'BAD_PATH' });
+    const stat = await run({ op: 'stat', path: 'README.md' });
+    expect(stat).toMatchObject({ ok: true, result: { kind: 'file', size: 4 } });
+    expect(stat.result.mtime).toBeGreaterThan(0);
+    expect(await run({ op: 'stat', path: '.' })).toMatchObject({ ok: true, result: { kind: 'directory' } });
+  });
+
+  test('refuses to read a file over the content cap', async () => {
+    const { project, run } = await base();
+    const fsPromises = {
+      ...fs,
+      stat: async (target) => ({
+        ...(await fs.stat(project)),
+        isDirectory: () => false,
+        isFile: () => true,
+        size: GUEST_FILE_CONTENT_MAX + 1,
+        target,
+      }),
+      realpath: fs.realpath.bind(fs),
+      readFile: async () => {
+        throw new Error('should not read');
+      },
+    };
+    expect(await run({ op: 'read', path: 'big.txt', fsPromises })).toMatchObject({ ok: false, code: 'FILE_TOO_LARGE' });
+  });
+
+  test('writes atomically, creating parents, and refuses oversized content', async () => {
+    const { probe, run } = await base();
+    const target = path.join(probe, 'nested', 'deep', 'config.json');
+    const renames = [];
+    const fsPromises = {
+      ...fs,
+      realpath: fs.realpath.bind(fs),
+      rename: async (from, to) => {
+        // The target must not exist (or be complete) before the rename lands.
+        const before = await fs.readFile(to, 'utf8').catch(() => null);
+        renames.push({ from, to, before });
+        return fs.rename(from, to);
+      },
+    };
+    expect(await run({ op: 'write', path: target, content: '{"a":1}', fsPromises })).toEqual({ ok: true, result: { written: true } });
+    expect(await fs.readFile(target, 'utf8')).toBe('{"a":1}');
+    expect(renames).toHaveLength(1);
+    expect(renames[0].to).toBe(target);
+    expect(renames[0].from).not.toBe(target);
+    expect(renames[0].before).toBeNull();
+    // Overwrite: the previous content stays whole until the rename.
+    expect(await run({ op: 'write', path: target, content: '{"a":2}', fsPromises })).toEqual({ ok: true, result: { written: true } });
+    expect(renames[1].before).toBe('{"a":1}');
+    expect(await fs.readFile(target, 'utf8')).toBe('{"a":2}');
+    expect(await fs.readdir(path.dirname(target))).toEqual(['config.json']);
+    expect(await run({ op: 'write', path: target, content: 'x'.repeat(GUEST_FILE_CONTENT_MAX + 1) })).toMatchObject({ ok: false, code: 'FILE_TOO_LARGE' });
+    expect(await fs.readFile(target, 'utf8')).toBe('{"a":2}');
+  });
+
+  test('lists sorted entries with kinds and caps the list', async () => {
+    const { project, run } = await base();
+    await fs.mkdir(path.join(project, 'src'));
+    await fs.writeFile(path.join(project, 'b.txt'), '');
+    await fs.writeFile(path.join(project, 'a.txt'), '');
+    await fs.symlink(path.join(project, 'a.txt'), path.join(project, 'link'));
+    expect(await run({ op: 'list', path: '.' })).toEqual({
+      ok: true,
+      result: {
+        entries: [
+          { name: 'a.txt', kind: 'file' },
+          { name: 'b.txt', kind: 'file' },
+          { name: 'link', kind: 'other' },
+          { name: 'src', kind: 'directory' },
+        ],
+      },
+    });
+    expect(await run({ op: 'list', path: 'a.txt' })).toMatchObject({ ok: false, code: 'BAD_PATH' });
+    expect(await run({ op: 'list', path: 'nope' })).toMatchObject({ ok: false, code: 'NOT_FOUND' });
+    const many = await makeTemp('oc-files-many-');
+    await Promise.all(Array.from({ length: GUEST_FILE_LIST_MAX + 5 }, (_, index) => (
+      fs.writeFile(path.join(many, `f${String(index).padStart(5, '0')}`), '')
+    )));
+    const capped = await run({ op: 'list', path: many, patterns: [`${many}/**`] });
+    expect(capped.ok).toBe(true);
+    expect(capped.result.entries).toHaveLength(GUEST_FILE_LIST_MAX);
+    expect(capped.result.entries[0].name).toBe('f00000');
+  });
+
+  test('maps an OS permission error to DENIED', async () => {
+    const { project, run } = await base();
+    await fs.writeFile(path.join(project, 'README.md'), '# hi');
+    const fsPromises = {
+      ...fs,
+      realpath: fs.realpath.bind(fs),
+      readFile: async () => {
+        const error = new Error('EACCES');
+        error.code = 'EACCES';
+        throw error;
+      },
+    };
+    expect(await run({ op: 'read', path: 'README.md', fsPromises })).toMatchObject({ ok: false, code: 'DENIED' });
+  });
+});

package/server/lib/guests/grant-scope.js

@@ -0,0 +1,81 @@
+import { resolveIntegrationApi } from '@openchamber/sdk';
+
+// What a grant covered when the user approved it. `filesystem` is the
+// declared pattern list, `network` the API origin, `service` the exec names
+// and socket ids the dialog showed. A newer package that changes any of
+// these has not been approved for that capability, whatever the stored
+// grant list says, so the card asks again and the proxies refuse meanwhile.
+
+const sortedUnique = (values) => [...new Set(values)].sort();
+
+/**
+ * @param {{ filesystem?: string[], integration?: object, service?: { permissions?: { exec?: string[], sockets?: Array<{ id: string }> } } }} guest
+ * @returns {{ filesystem?: string[], apiOrigin?: string, service?: { exec: string[], sockets: string[] } }}
+ */
+export const guestGrantScope = (guest) => {
+  const scope = {};
+  if (Array.isArray(guest.filesystem) && guest.filesystem.length > 0) {
+    scope.filesystem = sortedUnique(guest.filesystem);
+  }
+  if (guest.integration) {
+    const api = resolveIntegrationApi(guest.integration);
+    if (api?.apiOrigin) {
+      scope.apiOrigin = api.apiOrigin;
+    }
+    // The stored refresh token and client secret travel to these two URLs;
+    // a package that moves either one has not been approved for them.
+    if (guest.integration.oauth) {
+      scope.oauth = {
+        authorizeUrl: guest.integration.oauth.authorizeUrl,
+        tokenUrl: guest.integration.oauth.tokenUrl,
+      };
+    }
+  }
+  if (guest.service) {
+    scope.service = {
+      exec: sortedUnique(guest.service.permissions?.exec ?? []),
+      sockets: sortedUnique((guest.service.permissions?.sockets ?? []).map((binding) => binding.id)),
+    };
+  }
+  return scope;
+};
+
+const sameOauth = (a, b) => (
+  (!a && !b) || Boolean(a && b && a.authorizeUrl === b.authorizeUrl && a.tokenUrl === b.tokenUrl)
+);
+
+/**
+ * Whether the credentials pasted or minted for one integration may still be
+ * used with the package as it is now: same API origin and same OAuth
+ * endpoints. Otherwise the tokens are dropped at re-approval.
+ */
+export const sameCredentialTarget = (stored, current) => (
+  Boolean(stored?.apiOrigin) && stored.apiOrigin === current.apiOrigin && sameOauth(stored.oauth, current.oauth)
+);
+
+const sameList = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+
+/**
+ * The grants that still hold for the package as it is now. A scoped
+ * capability (`filesystem`, `network`, `service`) only counts when the stored
+ * scope equals the current one; without a stored scope it never counts.
+ * @param {string[]} granted
+ * @param {ReturnType<typeof guestGrantScope> | undefined} stored
+ * @param {ReturnType<typeof guestGrantScope>} current
+ */
+export const effectiveGrants = (granted, stored, current) => granted.filter((capability) => {
+  if (capability === 'filesystem') {
+    return Boolean(stored?.filesystem) && sameList(stored.filesystem, current.filesystem ?? []);
+  }
+  if (capability === 'network') {
+    return Boolean(stored?.apiOrigin)
+      && stored.apiOrigin === current.apiOrigin
+      && sameOauth(stored.oauth, current.oauth);
+  }
+  if (capability === 'service') {
+    return Boolean(stored?.service)
+      && sameList(stored.service.exec, current.service?.exec ?? [])
+      && sameList(stored.service.sockets, current.service?.sockets ?? []);
+  }
+  return true;
+});

package/server/lib/guests/grant-scope.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+
+import { effectiveGrants, guestGrantScope, sameCredentialTarget } from './grant-scope.js';
+
+const guest = {
+  filesystem: ['~/notes/**', '~/.config/opencode/opencode.json'],
+  integration: {
+    name: 'Acme',
+    description: 'Tasks',
+    token: { apiOrigin: 'https://api.acme.example' },
+  },
+  service: {
+    entry: 'service/main.js',
+    runtime: 'host',
+    permissions: { exec: ['docker'], sockets: [{ id: 'docker', candidatesByPlatform: {} }] },
+  },
+};
+
+describe('guestGrantScope', () => {
+  test('captures sorted patterns, the API origin, and service permissions', () => {
+    expect(guestGrantScope(guest)).toEqual({
+      filesystem: ['~/.config/opencode/opencode.json', '~/notes/**'],
+      apiOrigin: 'https://api.acme.example',
+      service: { exec: ['docker'], sockets: ['docker'] },
+    });
+    expect(guestGrantScope({})).toEqual({});
+    expect(guestGrantScope({ integration: { name: 'L', description: 'x', host: { provider: 'linear' } } }))
+      .toEqual({ apiOrigin: 'https://api.linear.app' });
+  });
+});
+
+describe('effectiveGrants', () => {
+  const granted = ['prompt', 'filesystem', 'network', 'service'];
+
+  test('keeps every grant while the scope is what the user approved', () => {
+    const scope = guestGrantScope(guest);
+    expect(effectiveGrants(granted, scope, scope)).toEqual(granted);
+  });
+
+  test('drops a scoped grant when the package widened it', () => {
+    const approved = guestGrantScope(guest);
+    const wider = guestGrantScope({ ...guest, filesystem: ['~/**'] });
+    expect(effectiveGrants(granted, approved, wider)).toEqual(['prompt', 'network', 'service']);
+    const moved = guestGrantScope({ ...guest, integration: { ...guest.integration, token: { apiOrigin: 'https://evil.example' } } });
+    expect(effectiveGrants(granted, approved, moved)).toEqual(['prompt', 'filesystem', 'service']);
+    const moreExec = guestGrantScope({ ...guest, service: { ...guest.service, permissions: { exec: ['docker', 'kubectl'], sockets: guest.service.permissions.sockets } } });
+    expect(effectiveGrants(granted, approved, moreExec)).toEqual(['prompt', 'filesystem', 'network']);
+  });
+
+  test('never counts a scoped grant without a recorded scope', () => {
+    expect(effectiveGrants(granted, undefined, guestGrantScope(guest))).toEqual(['prompt']);
+  });
+});
+
+describe('oauth endpoints', () => {
+  const oauthGuest = {
+    integration: {
+      name: 'Acme',
+      description: 'Tasks',
+      oauth: { authorizeUrl: 'https://acme.example/authorize', tokenUrl: 'https://acme.example/token', apiOrigin: 'https://api.acme.example' },
+    },
+  };
+
+  test('a moved token endpoint drops the network grant and the credentials', () => {
+    const approved = guestGrantScope(oauthGuest);
+    expect(approved).toEqual({
+      apiOrigin: 'https://api.acme.example',
+      oauth: { authorizeUrl: 'https://acme.example/authorize', tokenUrl: 'https://acme.example/token' },
+    });
+    const moved = guestGrantScope({ integration: { ...oauthGuest.integration, oauth: { ...oauthGuest.integration.oauth, tokenUrl: 'https://evil.example/token' } } });
+    expect(effectiveGrants(['network'], approved, moved)).toEqual([]);
+    expect(sameCredentialTarget(approved, moved)).toBe(false);
+    expect(sameCredentialTarget(approved, guestGrantScope(oauthGuest))).toBe(true);
+  });
+});

package/server/lib/guests/host-session.js

@@ -0,0 +1,73 @@
+import { resolveIntegrationAuth } from '@openchamber/sdk';
+
+import { readTrimmedString } from '../linear/parse.js';
+import { GuestOAuthError, toPublicGuestAuth } from './oauth.js';
+
+const isHostLinear = (integration) => (
+  resolveIntegrationAuth(integration ?? {}) === 'host'
+  && integration?.host?.provider === 'linear'
+);
+
+const linearAccountLabel = (auth) => (
+  readTrimmedString(auth?.user?.displayName)
+  || readTrimmedString(auth?.user?.name)
+  || readTrimmedString(auth?.organization?.name)
+);
+
+export const toGuestAuthResponse = async (integration, stored) => {
+  const published = toPublicGuestAuth(stored, integration);
+  if (!isHostLinear(integration)) {
+    return published;
+  }
+  const { getLinearAuth } = await import('../linear/index.js');
+  const auth = getLinearAuth();
+  return {
+    ...published,
+    connected: Boolean(auth?.accessToken),
+    account: linearAccountLabel(auth),
+    hasClient: true,
+  };
+};
+
+export const startHostGuestAuthorization = async (integration) => {
+  if (!isHostLinear(integration)) {
+    return null;
+  }
+  try {
+    const { startAuthorization } = await import('../linear/index.js');
+    return await startAuthorization({ origin: 'web' });
+  } catch (error) {
+    if (error instanceof GuestOAuthError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : 'Could not start Linear.';
+    throw new GuestOAuthError(message, 'HOST_AUTH_FAILED');
+  }
+};
+
+export const disconnectHostGuest = async (integration) => {
+  if (!isHostLinear(integration)) {
+    return false;
+  }
+  const { getLinearAuth, clearLinearAuth, revokeToken } = await import('../linear/index.js');
+  const auth = getLinearAuth();
+  if (auth?.refreshToken) {
+    await revokeToken(auth.refreshToken, 'refresh_token').catch(() => undefined);
+  } else if (auth?.accessToken) {
+    await revokeToken(auth.accessToken, 'access_token').catch(() => undefined);
+  }
+  clearLinearAuth(auth?.workspaceId);
+  return true;
+};
+
+export const resolveHostAccessToken = async (integration) => {
+  if (!isHostLinear(integration)) {
+    return null;
+  }
+  try {
+    const { getValidLinearAccessToken } = await import('../linear/index.js');
+    return await getValidLinearAccessToken();
+  } catch {
+    return null;
+  }
+};

package/server/lib/guests/host-session.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+
+import { toGuestAuthResponse } from './host-session.js';
+
+describe('toGuestAuthResponse', () => {
+  test('leaves an oauth guest on the stored public slice', async () => {
+    const published = await toGuestAuthResponse({
+      name: 'GitLab',
+      description: 'Issues',
+      oauth: {
+        authorizeUrl: 'https://gitlab.com/oauth/authorize',
+        tokenUrl: 'https://gitlab.com/oauth/token',
+        apiOrigin: 'https://gitlab.com',
+      },
+    }, {
+      accessToken: 'tok',
+      account: 'ada',
+      clientId: 'app-1',
+      // Entered for these endpoints, so the card still counts it as a client.
+      clientTarget: { apiOrigin: 'https://gitlab.com', authorizeUrl: 'https://gitlab.com/oauth/authorize', tokenUrl: 'https://gitlab.com/oauth/token' },
+      settings: { 'project-path': 'group/project' },
+    });
+    expect(published).toEqual({
+      connected: true,
+      account: 'ada',
+      hasClient: true,
+      settings: { 'project-path': 'group/project' },
+    });
+  });
+});

package/server/lib/guests/html-styles.js

@@ -0,0 +1,6 @@
+import { GUEST_SCROLLBAR_CSS } from '@openchamber/sdk';
+
+/** Append instead of matching tags inside untrusted comments, scripts, or templates.
+ * Browsers accept the style after the document; its doctype and authored CSP stay intact.
+ */
+export const injectGuestDocumentStyles = (html) => `${html}\n<style data-openchamber-guest-styles>${GUEST_SCROLLBAR_CSS}</style>`;

package/server/lib/guests/html-styles.test.js

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import request from 'supertest';
+import { GUEST_SCROLLBAR_CSS } from '@openchamber/sdk';
+import { injectGuestDocumentStyles } from './html-styles.js';
+import { registerGuestRoutes } from './routes.js';
+import { writeExtensionStore } from './persist.js';
+
+const roots = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+
+describe('guest document styles', () => {
+  test('preserves doctypes, CSP, and tag-like text inside authored scripts', () => {
+    const html = '<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="style-src \'self\'"><script>const text = "</head><head>";</script></head><body>Guest</body></html>';
+    const decorated = injectGuestDocumentStyles(html);
+    expect(decorated.startsWith(html)).toBe(true);
+    expect(decorated).toContain(GUEST_SCROLLBAR_CSS);
+    expect(decorated).toContain('data-openchamber-guest-styles');
+  });
+
+  test('serves scrollbar defaults to existing guests with or without an asset token', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-styles-')); roots.push(root);
+    const packageRoot = path.join(root, 'guest'); await fs.mkdir(packageRoot);
+    const html = '<!doctype html><html><head></head><body><script src="main.js"></script></body></html>';
+    const script = 'console.log("existing bundle");';
+    await fs.writeFile(path.join(packageRoot, 'index.html'), html);
+    await fs.writeFile(path.join(packageRoot, 'main.js'), script);
+    await fs.writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({ name: 'guest', version: '1.0.0', openchamber: { apiVersion: 1, contributes: { panel: { id: 'old-guest', name: 'Old guest', icon: 'apps', entry: 'index.html' } } } }));
+    await writeExtensionStore(path.join(root, 'extensions.json'), { paths: [packageRoot], sources: { [packageRoot]: 'path' } });
+    const app = express(); registerGuestRoutes(app, { openchamberDataDir: root });
+    for (const suffix of ['', '?oc_url_token=fixture-scope']) {
+      const response = await request(app).get(`/api/guests/old-guest/index.html${suffix}`).expect(200);
+      expect(response.headers['content-security-policy']).toBe('sandbox allow-scripts');
+      expect(response.headers['cache-control']).toBe('no-store');
+      expect(response.text).toContain(GUEST_SCROLLBAR_CSS);
+      expect(response.text.startsWith('<!doctype html>')).toBe(true);
+      expect(response.text).toContain(suffix ? 'main.js?oc_url_token=fixture-scope' : 'src="main.js"');
+    }
+    expect((await request(app).get('/api/guests/old-guest/main.js').expect(200)).text).toBe(script);
+    expect(await fs.readFile(path.join(packageRoot, 'index.html'), 'utf8')).toBe(html);
+  });
+});

package/server/lib/guests/html-tokens.js

@@ -0,0 +1,73 @@
+const RELATIVE_ASSET = /(<(?:script|link|img)\b[^>]*?\s(?:src|href)=)(["'])(?!https?:|\/\/|data:|#)([^"']+)\2/gi;
+
+const withToken = (url, token) => {
+  if (url.includes('oc_url_token=')) {
+    return url;
+  }
+  const joiner = url.includes('?') ? '&' : '?';
+  return `${url}${joiner}oc_url_token=${encodeURIComponent(token)}`;
+};
+
+const firstQueryValue = (value) => (Array.isArray(value) ? value[0] : value);
+
+/** Query `oc_url_token` for guest HTML. Empty when the query is missing or not a token. */
+export const parseGuestUrlToken = (value) => {
+  const first = firstQueryValue(value);
+  if (first == null || first === '') {
+    return '';
+  }
+  return `${first}`;
+};
+
+const SCRIPT_SRC = /<script\b[^>]*?\ssrc=(["'])(?!https?:|\/\/|data:|#)([^"']+)\1/gi;
+
+/** Relative `script src` values. Absolute, protocol-relative, data, and hash URLs are skipped. */
+export const listRelativeGuestScriptHrefs = (html) => {
+  if (html === '') {
+    return [];
+  }
+  const hrefs = [];
+  SCRIPT_SRC.lastIndex = 0;
+  let match = SCRIPT_SRC.exec(html);
+  while (match) {
+    hrefs.push(match[2]);
+    match = SCRIPT_SRC.exec(html);
+  }
+  return hrefs;
+};
+
+/** Resolve a relative href against the entry HTML path. Stays inside the package. */
+export const resolveGuestHtmlRelativePath = (entry, href) => {
+  const withoutHash = href.split('#')[0] ?? '';
+  const raw = withoutHash.split('?')[0];
+  if (raw === '' || raw.includes('\0') || raw.includes('\\')) {
+    return null;
+  }
+  const entryDir = entry.includes('/') ? entry.slice(0, entry.lastIndexOf('/')) : '';
+  const combined = entryDir === '' ? raw : `${entryDir}/${raw}`;
+  const segments = [];
+  for (const part of combined.split('/')) {
+    if (part === '' || part === '.') {
+      continue;
+    }
+    if (part === '..') {
+      if (segments.length === 0) {
+        return null;
+      }
+      segments.pop();
+      continue;
+    }
+    segments.push(part);
+  }
+  return segments.join('/');
+};
+
+/** Copy the iframe URL token onto relative script/link/img URLs in guest HTML. */
+export const injectGuestAssetTokens = (html, token) => {
+  if (!token) {
+    return html;
+  }
+  return html.replace(RELATIVE_ASSET, (_match, prefix, quote, url) => {
+    return `${prefix}${quote}${withToken(url, token)}${quote}`;
+  });
+};