@vantran-se/openchamber-web 1.23.1 → 1.24.4

package/server/lib/guests/ssh-install.test.js

@@ -0,0 +1,188 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { resolveBunExecutable } from '../../../../../scripts/lib/bun-executable.mjs';
+
+import { cloneGitRepository, parseGitInstallUrl, prepareGuestGitNetwork } from './clone.js';
+import { installGuestFromGitSource, parseInstallRequest } from './install.js';
+import { listInstalledGuests } from './catalog.js';
+import { readExtensionStore } from './persist.js';
+import { checkGuestUpdate, updateGuest } from './updates.js';
+
+const lookup = async () => [{ address: '93.184.216.34', family: 4 }];
+const source = 'git@github.com:acme/fixture.git';
+const testPath = fileURLToPath(import.meta.url);
+const bunExecutable = resolveBunExecutable();
+const savedEnv = new Map();
+let root;
+let repo;
+let profilesPath;
+let logPath;
+let globalKey;
+let workKey;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], {
+  cwd: root,
+  env: { ...process.env, HOME: root, GIT_CONFIG_GLOBAL: path.join(root, '.gitconfig'), GIT_CONFIG_NOSYSTEM: '1' },
+  stdio: 'pipe',
+});
+const setEnv = (key, value) => {
+  savedEnv.set(key, process.env[key]);
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+};
+const writeProfiles = (key) => fs.writeFile(profilesPath, JSON.stringify({ profiles: key ? [{ id: 'work', name: 'Work', userName: 'Fixture', userEmail: 'fixture@example.com', sshKey: key }] : [] }));
+const publishVersion = async (version) => {
+  await fs.writeFile(path.join(repo, 'package.json'), JSON.stringify({ name: 'fixture', version,
+    openchamber: { apiVersion: 1, contributes: { panel: { id: 'ssh-fixture', name: 'Fixture', icon: 'window', entry: 'panel/index.html' } } } }));
+  git('add', '.');
+  git('commit', '-m', `fixture ${version}`);
+};
+const sshCalls = async () => (await fs.readFile(logPath, 'utf8')).trim().split('\n').map((line) => JSON.parse(line));
+
+if (!process.env.GUEST_SSH_TEST_HOME) {
+  test('SSH integration suite uses an isolated server home', async () => {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), 'guest-ssh-test-'));
+    const protectedPaths = [path.join(os.homedir(), '.gitconfig'), path.resolve(path.dirname(testPath), '../../../../../.git/config')];
+    const readProtected = async (file) => {
+      try { return await fs.readFile(file); }
+      catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+        throw error;
+      }
+    };
+    const before = await Promise.all(protectedPaths.map(readProtected));
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) if (key.startsWith('GIT_')) delete env[key];
+    Object.assign(env, {
+      HOME: home,
+      USERPROFILE: home,
+      XDG_CONFIG_HOME: path.join(home, '.config'),
+      GIT_CONFIG_GLOBAL: path.join(home, '.gitconfig'),
+      GIT_CONFIG_NOSYSTEM: '1',
+      GIT_CEILING_DIRECTORIES: path.dirname(home),
+      GUEST_SSH_TEST_HOME: home,
+    });
+    try {
+      const refused = spawnSync(bunExecutable, ['test', testPath], {
+        env, cwd: path.dirname(home), stdio: 'pipe', timeout: 60_000,
+      });
+      expect(refused.status).not.toBe(0);
+      expect(refused.stderr.toString()).toContain('SSH fixture refused to run without an isolated home');
+      // Bun's default child-process environment can ignore late process.env
+      // edits. Establish isolation at process startup and always pass env/cwd.
+      execFileSync(bunExecutable, ['test', testPath], {
+        env, cwd: home, stdio: 'pipe', timeout: 60_000,
+      });
+    } finally {
+      const after = await Promise.all(protectedPaths.map(readProtected));
+      await fs.rm(home, { recursive: true, force: true });
+      // Compare bytes without printing configuration contents on a failure.
+      for (let index = 0; index < before.length; index++) {
+        const unchanged = before[index] === null ? after[index] === null : after[index] !== null && before[index].equals(after[index]);
+        expect(unchanged).toBe(true);
+      }
+    }
+  });
+} else {
+beforeAll(async () => {
+  root = process.env.GUEST_SSH_TEST_HOME;
+  const realRoot = await fs.realpath(root);
+  if (path.dirname(realRoot) !== await fs.realpath(os.tmpdir())
+    || !path.basename(realRoot).startsWith('guest-ssh-test-')
+    || await fs.realpath(os.homedir()) !== realRoot
+    || await fs.realpath(process.cwd()) !== realRoot
+    || process.env.GIT_CONFIG_GLOBAL !== path.join(root, '.gitconfig')) {
+    throw new Error('SSH fixture refused to run without an isolated home, cwd, and Git config');
+  }
+  repo = path.join(root, 'repository');
+  const bin = path.join(root, 'bin');
+  profilesPath = path.join(root, '.config/openchamber/git-identities.json');
+  logPath = path.join(root, 'ssh-calls.jsonl');
+  globalKey = path.join(root, 'global key');
+  workKey = path.join(root, 'work key');
+  await fs.mkdir(path.dirname(profilesPath), { recursive: true });
+  await fs.mkdir(bin);
+  await fs.mkdir(path.join(repo, 'panel'), { recursive: true });
+  setEnv('HOME', root);
+  setEnv('GIT_CONFIG_GLOBAL', path.join(root, '.gitconfig'));
+  setEnv('GIT_CONFIG_NOSYSTEM', '1');
+  setEnv('GIT_SSH_COMMAND', undefined);
+  setEnv('GIT_SSH', undefined);
+  setEnv('SSH_AUTH_SOCK', path.join(root, 'fixture-agent.sock'));
+  setEnv('PATH', `${bin}${path.delimiter}${process.env.PATH}`);
+  setEnv('GUEST_TEST_REPO', repo);
+  setEnv('GUEST_TEST_SSH_LOG', logPath);
+  // Real Git protocol over a local test transport: no server key or network is used.
+  await fs.writeFile(path.join(bin, 'ssh'), `#!${process.execPath}\nimport { appendFileSync } from 'node:fs';\nimport { spawnSync } from 'node:child_process';\nappendFileSync(process.env.GUEST_TEST_SSH_LOG, JSON.stringify({ args: process.argv.slice(2), agent: process.env.SSH_AUTH_SOCK }) + '\\n');\nconst result = spawnSync('git', ['upload-pack', process.env.GUEST_TEST_REPO], { stdio: 'inherit' });\nprocess.exit(result.status ?? 1);\n`, { mode: 0o755 });
+  // Seed only this explicit fixture file. Never run `git config --global` here.
+  await fs.writeFile(path.join(root, '.gitconfig'), `[user]\n  name = Fixture\n  email = fixture@example.com\n[core]\n  sshCommand = ${JSON.stringify(`ssh -i '${globalKey}'`)}\n`);
+  git('init', '--initial-branch=main');
+  await fs.writeFile(path.join(repo, 'panel/index.html'), '<script src="main.js"></script>');
+  await fs.writeFile(path.join(repo, 'panel/main.js'), 'console.log("fixture");');
+  await writeProfiles(workKey);
+  await publishVersion('1.0.0');
+});
+
+afterAll(async () => {
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe('SSH extension installs', () => {
+  test('accepts SSH and scp URLs with refs, but rejects credentials, private targets and shell syntax', () => {
+    expect(parseGitInstallUrl(`${source}#main`)).toEqual({ url: source, ref: 'main' });
+    expect(parseGitInstallUrl('ssh://git@github.com:2222/acme/fixture.git')).toEqual({ url: 'ssh://git@github.com:2222/acme/fixture.git' });
+    expect(parseGitInstallUrl('SSH://git@github.com/acme/fixture.git')).toEqual({ url: 'ssh://git@github.com/acme/fixture.git' });
+    for (const url of ['ssh://git:password@github.com/acme/repo', 'ssh://git@127.0.0.1/repo', 'git@localhost:repo', 'ssh://git@github.com:99999/repo', 'git@github.com:repo;id', 'ssh://git@github.com/repo?command=id', 'ssh://git@bad\'host.com/repo', `${source}\n`]) {
+      expect(parseGitInstallUrl(url)).toBeNull();
+    }
+    expect(parseInstallRequest({ url: source, gitIdentityId: 'work' })).toEqual({ url: source, gitIdentityId: 'work' });
+    expect(parseInstallRequest({ url: source, gitIdentityId: {} })).toBeNull();
+  });
+
+  test('global identity uses host SSH configuration and inherits its agent', async () => {
+    expect(await cloneGitRepository(source, path.join(root, 'global-clone'), { lookup })).toEqual({ ok: true });
+    const call = (await sshCalls()).at(-1);
+    expect(call.args).toContain(globalKey);
+    expect(call.agent).toBe(process.env.SSH_AUTH_SOCK);
+    expect(call.args).toContain('BatchMode=yes');
+    expect(call.args).toContain('Hostname=93.184.216.34');
+    expect(call.args).toContain('HostKeyAlias=github.com');
+    expect(await cloneGitRepository('ssh://git@github.com:2222/acme/fixture.git', path.join(root, 'port-clone'), { lookup })).toEqual({ ok: true });
+    expect((await sshCalls()).at(-1).args).toContain('2222');
+  });
+
+  test('rejects DNS answers into private networks', async () => {
+    expect(await prepareGuestGitNetwork(source, { lookup: async () => [{ address: '10.0.0.1', family: 4 }] })).toBeNull();
+  });
+
+  test('persists the selected identity and re-resolves it for update checks and replacement clones', async () => {
+    const persistPath = path.join(root, 'extensions.json');
+    const result = await installGuestFromGitSource(source, persistPath, { gitIdentityId: 'work', ref: 'main', lookup });
+    expect(result.ok).toBe(true);
+    const [guest] = await listInstalledGuests({ persistPath });
+    expect(guest.gitOrigin).toEqual({ url: source, ref: 'main', gitIdentityId: 'work' });
+    expect((await sshCalls()).at(-1).args).toContain(workKey);
+    expect(JSON.stringify(await readExtensionStore(persistPath))).not.toContain(workKey);
+
+    const rotatedKey = path.join(root, 'rotated key');
+    await writeProfiles(rotatedKey);
+    await publishVersion('1.1.0');
+    expect(await checkGuestUpdate({ guest, origin: guest.gitOrigin, lookup })).toMatchObject({ available: true, version: '1.1.0' });
+    expect((await sshCalls()).at(-1).args).toContain(rotatedKey);
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, lookup })).toMatchObject({ ok: true });
+    expect((await sshCalls()).at(-1).args).toContain(rotatedKey);
+
+    await writeProfiles(null);
+    expect(await checkGuestUpdate({ guest, origin: guest.gitOrigin, lookup })).toMatchObject({ available: false, error: 'fetch-failed' });
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, lookup })).toMatchObject({ ok: false, code: 'clone-failed' });
+    const [preserved] = await listInstalledGuests({ persistPath });
+    expect(preserved.version).toBe('1.1.0');
+  });
+});
+}

package/server/lib/guests/storage.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_TOTAL_BYTES, GUEST_STORAGE_VALUE_BYTES } from '@openchamber/sdk';
+
+const stores = new Map();
+const documentSchema = z.record(z.string().min(1).max(GUEST_STORAGE_KEY_MAX), z.json());
+const storagePath = (persistPath, id) => {
+  if (!/^[a-z][a-z0-9-]*$/.test(id)) throw new Error('Invalid extension identity');
+  return path.join(path.dirname(persistPath), 'guest-storage', `${id}.json`);
+};
+
+const withStorageLock = async (file, operation) => {
+  const previous = stores.get(file) ?? Promise.resolve();
+  const pending = previous.catch(() => {}).then(operation);
+  stores.set(file, pending);
+  try {
+    return await pending;
+  } finally {
+    if (stores.get(file) === pending) stores.delete(file);
+  }
+};
+
+export const removeGuestStorage = (persistPath, id) => {
+  const file = storagePath(persistPath, id);
+  return withStorageLock(file, () => fs.rm(file, { force: true }));
+};
+
+/** Authorization is rechecked inside the same lock that serializes removal. */
+export const runGuestStorage = (persistPath, id, request, authorize) => {
+  const file = storagePath(persistPath, id);
+  return withStorageLock(file, async () => {
+    await authorize();
+    let entries = new Map();
+    try {
+      const stat = await fs.stat(file);
+      if (stat.size > GUEST_STORAGE_TOTAL_BYTES) throw new Error('Storage exceeds its size limit');
+      const parsed = documentSchema.parse(JSON.parse(await fs.readFile(file, 'utf8')));
+      entries = new Map(Object.entries(parsed));
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    if (request.op === 'get') {
+      return entries.has(request.key)
+        ? { storage: true, op: 'get', found: true, value: entries.get(request.key) }
+        : { storage: true, op: 'get', found: false };
+    }
+    if (request.op === 'keys') return { storage: true, op: 'keys', keys: [...entries.keys()].sort() };
+    if (request.op === 'set') {
+      if (Buffer.byteLength(JSON.stringify(request.value)) > GUEST_STORAGE_VALUE_BYTES) throw new Error('Storage value exceeds 64 KiB');
+      entries.set(request.key, request.value);
+    } else {
+      entries.delete(request.key);
+    }
+    const data = JSON.stringify(Object.fromEntries(entries));
+    if (entries.size > GUEST_STORAGE_KEYS_MAX || Buffer.byteLength(data) > GUEST_STORAGE_TOTAL_BYTES) throw new Error('Extension storage is full');
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      await fs.writeFile(temporary, data, { mode: 0o600, flag: 'wx' });
+      await fs.rename(temporary, file);
+    } finally {
+      await fs.rm(temporary, { force: true });
+    }
+    return { storage: true, op: request.op };
+  });
+};

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

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runGuestStorage, removeGuestStorage } from './storage.js';
+
+const roots = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+const fixture = async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-storage-'));
+  roots.push(root);
+  const persistPath = path.join(root, 'extensions.json');
+  return { root, persistPath, run: (request, id = 'board') => runGuestStorage(persistPath, id, request, async () => {}) };
+};
+describe('extension storage', () => {
+  test('concurrent keys survive, namespaces are isolated, and null is present', async () => {
+    const { run, persistPath } = await fixture();
+    await Promise.all(Array.from({ length: 30 }, (_, index) => run({ op: 'set', key: `key-${index}`, value: index })));
+    expect((await run({ op: 'keys' })).keys).toHaveLength(30);
+    expect(await run({ op: 'get', key: 'key-1' }, 'other')).toMatchObject({ found: false });
+    await run({ op: 'set', key: 'null', value: null });
+    expect(await run({ op: 'get', key: 'null' })).toMatchObject({ found: true, value: null });
+    await removeGuestStorage(persistPath, 'board');
+    expect(await run({ op: 'keys' })).toMatchObject({ keys: [] });
+  });
+  test('limits and malformed reads preserve prior bytes', async () => {
+    const { run, root } = await fixture();
+    await run({ op: 'set', key: 'board', value: { columns: ['Todo'] } });
+    await expect(run({ op: 'set', key: 'board', value: 'x'.repeat(65_536) })).rejects.toThrow();
+    expect(await run({ op: 'get', key: 'board' })).toMatchObject({ value: { columns: ['Todo'] } });
+    const file = path.join(root, 'guest-storage', 'board.json');
+    await fs.writeFile(file, '{broken');
+    await expect(run({ op: 'set', key: 'other', value: 1 })).rejects.toThrow();
+    expect(await fs.readFile(file, 'utf8')).toBe('{broken');
+  });
+  test('authorization runs after earlier writes and refusal performs no write', async () => {
+    const { run, persistPath } = await fixture();
+    await run({ op: 'set', key: 'kept', value: 1 });
+    await expect(runGuestStorage(persistPath, 'board', { op: 'set', key: 'kept', value: 2 }, async () => { throw new Error('Removed'); })).rejects.toThrow('Removed');
+    expect(await run({ op: 'get', key: 'kept' })).toMatchObject({ value: 1 });
+  });
+  test('a failed atomic rename leaves the old value and does not poison subsequent writes', async () => {
+    const { run } = await fixture();
+    await run({ op: 'set', key: 'kept', value: 1 });
+    const rename = vi.spyOn(fs, 'rename').mockRejectedValueOnce(new Error('Disk failure'));
+    try {
+      await expect(run({ op: 'set', key: 'kept', value: 2 })).rejects.toThrow('Disk failure');
+    } finally { rename.mockRestore(); }
+    expect(await run({ op: 'get', key: 'kept' })).toMatchObject({ value: 1 });
+    await run({ op: 'set', key: 'kept', value: 3 });
+    expect(await run({ op: 'get', key: 'kept' })).toMatchObject({ value: 3 });
+  });
+  test('the total byte limit retains keys written before the overflowing request', async () => {
+    const { run } = await fixture();
+    const results = await Promise.allSettled(Array.from({ length: 35 }, (_, index) => run({ op: 'set', key: `key-${index}`, value: 'x'.repeat(60_000) })));
+    expect(results.filter((result) => result.status === 'rejected')).toHaveLength(1);
+    expect((await run({ op: 'keys' })).keys).toHaveLength(34);
+  });
+});

package/server/lib/guests/updates.js

@@ -0,0 +1,294 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { parseManifestJson } from '@openchamber/sdk/schemas';
+import { requestedGuestCapabilities } from '@openchamber/sdk';
+
+import { inspectGuestPackage, invalidateGuestCatalog, listInstalledGuests } from './catalog.js';
+import { cloneGitRepository, prepareGuestGitNetwork, runGit } from './clone.js';
+import { unwrapGuestRoot } from './extract-zip.js';
+import { guestCopiesDir, isCopiedGuestRoot } from './persist.js';
+import { stopGuestService } from './service.js';
+
+/** A remote check runs at most this often per guest unless the user forces it. */
+export const UPDATE_CHECK_TTL_MS = 60 * 60 * 1000;
+const CHECK_TIMEOUT_MS = 20_000;
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/**
+ * @param {string} value
+ * @returns {{ core: number[], pre: string[] | null } | null}
+ */
+const parseSemver = (value) => {
+  const match = SEMVER.exec(value.trim());
+  if (!match) {
+    return null;
+  }
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] ? match[4].split('.') : null,
+  };
+};
+
+const compareIdentifier = (a, b) => {
+  const aNumeric = /^\d+$/.test(a);
+  const bNumeric = /^\d+$/.test(b);
+  if (aNumeric && bNumeric) {
+    return Math.sign(Number(a) - Number(b));
+  }
+  if (aNumeric) return -1;
+  if (bNumeric) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
+/**
+ * Semver order: `-1` when `a < b`, `1` when `a > b`, `0` when equal. A
+ * prerelease sorts below its release (`1.1.0-beta.1 < 1.1.0`). Build metadata
+ * is ignored. Either side not being semver is `null`.
+ */
+export const compareSemver = (a, b) => {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  if (!left || !right) {
+    return null;
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (left.core[index] !== right.core[index]) {
+      return left.core[index] < right.core[index] ? -1 : 1;
+    }
+  }
+  if (!left.pre && !right.pre) return 0;
+  if (!left.pre) return 1;
+  if (!right.pre) return -1;
+  const length = Math.min(left.pre.length, right.pre.length);
+  for (let index = 0; index < length; index += 1) {
+    const order = compareIdentifier(left.pre[index], right.pre[index]);
+    if (order !== 0) {
+      return order;
+    }
+  }
+  return Math.sign(left.pre.length - right.pre.length);
+};
+
+/**
+ * Ask the installed clone's remote for its current `package.json` and compare
+ * the version with what is on disk. Runs inside the installed copy so the
+ * clone's own credentials-free remote is used; nothing is written. Every
+ * failure is `{ available: false, error }`; nothing throws to the route.
+ *
+ * @param {{ guest: { version?: string, packageRoot: string }, origin: { url: string, ref?: string, gitIdentityId?: string }, gitBinary?: string, timeoutMs?: number, lookup?: Parameters<typeof import('./clone.js').publicAddressesOf>[1] }} input
+ * @returns {Promise<{ available: true, version: string, requested: string[] } | { available: false, version?: string, error?: string }>}
+ */
+export const checkGuestUpdate = async ({ guest, origin, gitBinary, timeoutMs = CHECK_TIMEOUT_MS, lookup }) => {
+  if (!origin?.url) {
+    return { available: false, error: 'not-git' };
+  }
+  if (!guest.version) {
+    return { available: false, error: 'invalid-manifest' };
+  }
+  const cwd = guest.packageRoot;
+  // The fetch is a network operation like the clone: no redirects, and the
+  // connection pinned to the addresses the public hostname resolves to now.
+  const network = await prepareGuestGitNetwork(origin.url, { gitIdentityId: origin.gitIdentityId, lookup }).catch(() => null);
+  if (!network) {
+    return { available: false, error: 'fetch-failed' };
+  }
+  const fetched = await runGit(
+    [...network.args, 'fetch', '--depth', '1', '--', 'origin', origin.ref ?? 'HEAD'],
+    { gitBinary, cwd, timeoutMs, env: network.env },
+  );
+  if (!fetched.ok) {
+    return { available: false, error: 'fetch-failed' };
+  }
+  const shown = await runGit(['show', 'FETCH_HEAD:package.json'], { gitBinary, cwd, timeoutMs, capture: true });
+  if (!shown.ok) {
+    return { available: false, error: 'invalid-manifest' };
+  }
+  const parsed = parseManifestJson(shown.stdout ?? '');
+  if (!parsed.ok || !parsed.version) {
+    return { available: false, error: 'invalid-manifest' };
+  }
+  const order = compareSemver(guest.version, parsed.version);
+  if (order === null) {
+    return { available: false, error: 'invalid-manifest' };
+  }
+  if (order >= 0) {
+    return { available: false, version: parsed.version };
+  }
+  return {
+    available: true,
+    version: parsed.version,
+    requested: requestedGuestCapabilities(parsed.manifest.contributes),
+  };
+};
+
+/**
+ * Check results per store file, then per guest id. This is memory only and
+ * separate from the catalog cache, so a store write (enable, approve) does
+ * not throw away an hour-old answer from the network.
+ * @type {Map<string, Map<string, { checkedAt: number, result: Awaited<ReturnType<typeof checkGuestUpdate>> }>>}
+ */
+const updateCache = new Map();
+
+const cacheFor = (persistPath) => {
+  let byGuest = updateCache.get(persistPath);
+  if (!byGuest) {
+    byGuest = new Map();
+    updateCache.set(persistPath, byGuest);
+  }
+  return byGuest;
+};
+
+export const clearGuestUpdateCache = (persistPath, guestId) => {
+  if (!persistPath) {
+    updateCache.clear();
+    return;
+  }
+  if (guestId === undefined) {
+    updateCache.delete(persistPath);
+    return;
+  }
+  updateCache.get(persistPath)?.delete(guestId);
+};
+
+/** The cached `{ version }` for a guest with a pending update, else `null`. */
+export const getCachedGuestUpdate = (persistPath, guestId) => {
+  const entry = updateCache.get(persistPath)?.get(guestId);
+  return entry?.result.available ? { version: entry.result.version } : null;
+};
+
+/** The catalog row plus `update` when the last check found a newer version. */
+export const withGuestUpdate = (guest, persistPath) => {
+  const update = getCachedGuestUpdate(persistPath, guest.id);
+  return update ? { ...guest, update } : guest;
+};
+
+/**
+ * Check every git install. A guest checked within `UPDATE_CHECK_TTL_MS`
+ * answers from the cache unless `force`. Checks run in parallel; one guest's
+ * failure never hides another's update.
+ *
+ * @returns {Promise<Record<string, { version: string }>>} guests with an update
+ */
+export const checkAllGuestUpdates = async ({ persistPath, force = false, gitBinary, now = Date.now() }) => {
+  const guests = await listInstalledGuests({ persistPath });
+  const byGuest = cacheFor(persistPath);
+  await Promise.all(guests.map(async (guest) => {
+    if (guest.source !== 'git' || !guest.gitOrigin) {
+      byGuest.delete(guest.id);
+      return;
+    }
+    const cached = byGuest.get(guest.id);
+    if (!force && cached && now - cached.checkedAt < UPDATE_CHECK_TTL_MS) {
+      return;
+    }
+    const result = await checkGuestUpdate({ guest, origin: guest.gitOrigin, gitBinary });
+    byGuest.set(guest.id, { checkedAt: now, result });
+  }));
+  /** @type {Record<string, { version: string }>} */
+  const updates = {};
+  for (const guest of guests) {
+    const update = getCachedGuestUpdate(persistPath, guest.id);
+    if (update) {
+      updates[guest.id] = update;
+    }
+  }
+  return updates;
+};
+
+const removeDir = async (dir) => {
+  await fs.rm(dir, { recursive: true, force: true });
+};
+
+const exists = async (target) => {
+  try {
+    await fs.lstat(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Replace the installed git copy with a fresh clone of its origin.
+ *
+ * The new clone lands in a sibling temp dir and is inspected exactly like an
+ * install (manifest, built scripts, engines). Only then is the live folder
+ * swapped: current → `.old-<id>`, temp → final, then `.old-<id>` is deleted.
+ * A failure before the swap removes the temp dir and leaves the install as
+ * it was. A failed second rename moves the old folder back. Grants, tokens,
+ * settings, and the paused flag are keyed by guest id, so they survive
+ * unchanged; the catalog row for the id is re-read from disk.
+ *
+ * @returns {Promise<{ ok: true, id: string } | { ok: false, code: string, required?: string }>}
+ */
+export const updateGuest = async ({ guest, origin, persistPath, openchamberVersion, gitBinary, lookup }) => {
+  if (guest.source !== 'git' || !origin?.url || !isCopiedGuestRoot(guest.packageRoot, persistPath)) {
+    return { ok: false, code: 'not-git' };
+  }
+  const copies = guestCopiesDir(persistPath);
+  await fs.mkdir(copies, { recursive: true });
+  const staging = path.join(copies, `.tmp-${guest.id}-${crypto.randomBytes(6).toString('hex')}`);
+  let packageRoot;
+  try {
+    const cloned = await cloneGitRepository(origin.url, staging, { gitBinary, ref: origin.ref, gitIdentityId: origin.gitIdentityId, lookup });
+    if (!cloned.ok) {
+      await removeDir(staging);
+      return cloned;
+    }
+    packageRoot = await unwrapGuestRoot(staging);
+    const inspected = await inspectGuestPackage(packageRoot, { openchamberVersion });
+    if (!inspected.ok) {
+      await removeDir(staging);
+      return inspected;
+    }
+    // A repo that now declares a different panel id is not an update of this
+    // extension; installing it would orphan grants and tokens under the old id.
+    if (inspected.guest.id !== guest.id) {
+      await removeDir(staging);
+      return { ok: false, code: 'invalid-manifest' };
+    }
+  } catch {
+    await removeDir(staging);
+    return { ok: false, code: 'clone-failed' };
+  }
+
+  // The service (if running) holds files from the old copy; on Windows that
+  // blocks the rename. It restarts on the next call from the new code.
+  await stopGuestService(guest.id);
+
+  const dest = guest.packageRoot;
+  const old = path.join(copies, `.old-${guest.id}`);
+  try {
+    await removeDir(old);
+    await fs.rename(dest, old);
+  } catch {
+    await removeDir(staging);
+    return { ok: false, code: 'swap-failed' };
+  }
+  try {
+    await fs.rename(packageRoot, dest);
+  } catch {
+    // Put the previous copy back so the user keeps a working extension.
+    try {
+      if (!await exists(dest)) {
+        await fs.rename(old, dest);
+      }
+    } catch {
+      // Nothing more can be done; the next catalog read omits this guest and
+      // the user can reinstall from the same URL.
+    }
+    await removeDir(staging);
+    invalidateGuestCatalog(persistPath);
+    return { ok: false, code: 'swap-failed' };
+  }
+  await removeDir(old);
+  if (packageRoot !== staging) {
+    await removeDir(staging);
+  }
+  invalidateGuestCatalog(persistPath);
+  clearGuestUpdateCache(persistPath, guest.id);
+  return { ok: true, id: guest.id };
+};