@vantran-se/openchamber-web 1.23.1 → 1.24.3

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

@@ -0,0 +1,390 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { guestAssetContentType, inspectGuestPackage, listInstalledGuests, resolveGuestAssetPath, resolveGuestServedFile, toPublicGuest } from './catalog.js';
+import { setCapabilityGrants, writeExtensionPaths } from './persist.js';
+
+const writeBuiltGuest = async (root) => {
+  await fs.mkdir(path.join(root, 'panel'), { recursive: true });
+  await fs.writeFile(path.join(root, 'panel', 'index.html'), '<script src="./main.js"></script>');
+  await fs.writeFile(path.join(root, 'panel', 'main.js'), 'console.log("hello")');
+  await fs.writeFile(path.join(root, 'package.json'), JSON.stringify({
+    name: '@openchamber/hello',
+    openchamber: {
+      apiVersion: 1,
+      contributes: {
+        panel: { id: 'hello', name: 'Hello', icon: 'window', entry: 'panel/index.html' },
+        attach: 'dialog',
+      },
+    },
+  }));
+};
+
+describe('resolveGuestAssetPath', () => {
+  test('stays inside the package and rejects escapes', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    await fs.writeFile(path.join(root, 'index.html'), '<html></html>');
+    await fs.mkdir(path.join(root, 'panel'));
+    await fs.writeFile(path.join(root, 'panel', 'index.html'), '<html></html>');
+
+    expect(await resolveGuestAssetPath(root, 'index.html')).toBe(await fs.realpath(path.join(root, 'index.html')));
+    expect(await resolveGuestAssetPath(root, 'panel/index.html')).toBe(await fs.realpath(path.join(root, 'panel', 'index.html')));
+    expect(await resolveGuestAssetPath(root, '../secret.html')).toBeNull();
+    expect(await resolveGuestAssetPath(root, '/etc/passwd')).toBeNull();
+    expect(await resolveGuestAssetPath(root, 'missing.html')).toBeNull();
+
+    await fs.rm(root, { recursive: true, force: true });
+  });
+});
+
+describe('guestAssetContentType', () => {
+  test('refuses unknown extensions', () => {
+    expect(guestAssetContentType('panel/index.html')).toContain('text/html');
+    expect(guestAssetContentType('icon.svg')).toBe('image/svg+xml');
+    expect(guestAssetContentType('notes.md')).toBeNull();
+  });
+});
+
+describe('listInstalledGuests', () => {
+  test('does not auto-install the repo sample', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    expect(await listInstalledGuests({ persistPath })).toEqual([]);
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('serves a path-installed guest', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const guestRoot = path.join(dir, 'hello');
+    await writeBuiltGuest(guestRoot);
+    await writeExtensionPaths([guestRoot], persistPath);
+
+    const guests = await listInstalledGuests({ persistPath });
+    const hello = guests.find((guest) => guest.id === 'hello');
+    expect(hello?.name).toBe('Hello');
+    expect(hello?.source).toBe('path');
+    expect(hello?.attach).toBe('dialog');
+    expect(hello).toBeTruthy();
+    if (!hello) {
+      await fs.rm(dir, { recursive: true, force: true });
+      return;
+    }
+    expect(toPublicGuest(hello)).toEqual({
+      id: 'hello',
+      name: 'Hello',
+      icon: 'window',
+      entry: 'panel/index.html',
+      source: 'path',
+      path: hello.path,
+      attach: 'dialog',
+      enabled: true,
+      capabilities: { requested: [], granted: [] },
+    });
+    expect(toPublicGuest({
+      ...hello,
+      integration: {
+        name: 'ClickUp',
+        description: 'Tasks',
+        oauth: {
+          authorizeUrl: 'https://app.clickup.com/api',
+          tokenUrl: 'https://api.clickup.com/api/v2/oauth/token',
+          apiOrigin: 'https://api.clickup.com',
+        },
+        settings: [{ id: 'list-id', label: 'List ID' }],
+      },
+    })).toEqual({
+      id: 'hello',
+      name: 'Hello',
+      icon: 'window',
+      entry: 'panel/index.html',
+      source: 'path',
+      path: hello.path,
+      attach: 'dialog',
+      enabled: true,
+      capabilities: { requested: ['network'], granted: [] },
+      integration: {
+        name: 'ClickUp',
+        description: 'Tasks',
+        apiOrigin: 'https://api.clickup.com',
+        auth: 'oauth',
+        settings: [{ id: 'list-id', label: 'List ID' }],
+      },
+    });
+    const served = await resolveGuestServedFile(hello.packageRoot, 'panel/main.js');
+    expect(served?.contentType).toContain('javascript');
+    expect(await resolveGuestServedFile(hello.packageRoot, 'panel/main.ts')).toBeNull();
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('skips a missing folder and keeps the rest', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const guestRoot = path.join(dir, 'clone');
+    await fs.mkdir(path.join(guestRoot, 'panel'), { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'panel', 'index.html'), '<html></html>');
+    await fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/clone-hello',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'clone-hello', name: 'Clone', icon: 'window', entry: 'panel/index.html' },
+        },
+      },
+    }));
+    await writeExtensionPaths([path.join(dir, 'gone'), guestRoot], persistPath);
+
+    const guests = await listInstalledGuests({ persistPath });
+    expect(guests.some((guest) => guest.id === 'clone-hello' && guest.source === 'path')).toBe(true);
+    expect(guests.some((guest) => guest.path === path.join(dir, 'gone'))).toBe(false);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('skips a package whose entry script was never built', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const guestRoot = path.join(dir, 'source-only');
+    await fs.mkdir(path.join(guestRoot, 'panel'), { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'panel', 'index.html'), '<script src="./main.js"></script>');
+    await fs.writeFile(path.join(guestRoot, 'panel', 'main.ts'), 'console.log(1)');
+    await fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/source-only',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'source-only', name: 'Source', icon: 'window', entry: 'panel/index.html' },
+        },
+      },
+    }));
+    await writeExtensionPaths([guestRoot], persistPath);
+
+    expect(await listInstalledGuests({ persistPath })).toEqual([]);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('checks a declared dialog entry like panel.entry and exposes it on the public row', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const guestRoot = path.join(dir, 'tasks');
+    const writeManifest = async () => fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/tasks',
+      version: '1.0.0',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'tasks', name: 'Tasks', icon: 'window', entry: 'panel/index.html' },
+          attach: { mode: 'dialog', entry: 'panel/attach.html' },
+        },
+      },
+    }));
+    await fs.mkdir(path.join(guestRoot, 'panel'), { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'panel', 'index.html'), '<script src="./main.js"></script>');
+    await fs.writeFile(path.join(guestRoot, 'panel', 'main.js'), 'console.log("main")');
+    await writeManifest();
+
+    expect(await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' })).toEqual({ ok: false, code: 'invalid-manifest' });
+
+    await fs.writeFile(path.join(guestRoot, 'panel', 'attach.html'), '<script src="./attach.js"></script>');
+    expect(await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' })).toEqual({ ok: false, code: 'missing-build' });
+
+    await fs.writeFile(path.join(guestRoot, 'panel', 'attach.js'), 'console.log("attach")');
+    const inspected = await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' });
+    expect(inspected.ok).toBe(true);
+    if (inspected.ok) {
+      expect(inspected.guest.attach).toBe('dialog');
+      expect(inspected.guest.attachEntry).toBe('panel/attach.html');
+      expect(toPublicGuest({ ...inspected.guest, source: 'path', path: guestRoot })).toMatchObject({
+        attach: 'dialog',
+        attachEntry: 'panel/attach.html',
+      });
+    }
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('page-less packages', () => {
+  test('validates full-screen HTML and built scripts and publishes its title', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-page-'));
+    try {
+      await fs.mkdir(path.join(dir, 'panel'));
+      await fs.writeFile(path.join(dir, 'panel/index.html'), '<p>Panel</p>');
+      await fs.writeFile(path.join(dir, 'package.json'), JSON.stringify({ version: '1.0.0', openchamber: {
+        apiVersion: 1, contributes: { panel: { id: 'board', name: 'Board', icon: 'window', entry: 'panel/index.html' }, page: { entry: 'panel/page.html', title: 'Tasks' } },
+      } }));
+      expect(await inspectGuestPackage(dir)).toMatchObject({ ok: false, code: 'invalid-manifest' });
+      await fs.writeFile(path.join(dir, 'panel/page.html'), '<script src="page.js"></script>');
+      expect(await inspectGuestPackage(dir)).toMatchObject({ ok: false, code: 'missing-build' });
+      await fs.writeFile(path.join(dir, 'panel/page.js'), 'console.log("page")');
+      const inspected = await inspectGuestPackage(dir);
+      expect(inspected.ok).toBe(true);
+      expect(toPublicGuest(inspected.guest)).toMatchObject({ pageEntry: 'panel/page.html', pageTitle: 'Tasks' });
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  });
+  test('installs a tools-only package without entry, omits entry from the row, and never serves it a frame', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const guestRoot = path.join(dir, 'tools-only');
+    await fs.mkdir(path.join(guestRoot, 'icons'), { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'icons', 'tool.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>');
+    await fs.writeFile(path.join(guestRoot, 'stray.html'), '<script src="./stray.js"></script>');
+    await fs.writeFile(path.join(guestRoot, 'stray.js'), 'console.log(1)');
+    await fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/tools-only',
+      version: '1.0.0',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'tools-only', name: 'Tools Only', icon: 'tools' },
+          tools: [{ match: 'mcp.*', icon: 'icons/tool.svg', output: 'json' }],
+        },
+      },
+    }));
+
+    const inspected = await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' });
+    expect(inspected).toEqual({
+      ok: true,
+      guest: {
+        id: 'tools-only',
+        name: 'Tools Only',
+        icon: 'tools',
+        packageRoot: guestRoot,
+        version: '1.0.0',
+        tools: [{ match: 'mcp.*', icon: 'icons/tool.svg', output: 'json' }],
+      },
+    });
+    if (!inspected.ok) {
+      await fs.rm(dir, { recursive: true, force: true });
+      return;
+    }
+    const row = toPublicGuest({ ...inspected.guest, source: 'path', path: guestRoot });
+    expect(row).not.toHaveProperty('entry');
+    expect(row.tools).toEqual([{ match: 'mcp.*', icon: 'icons/tool.svg', output: 'json' }]);
+
+    const hasRuntime = false;
+    expect((await resolveGuestServedFile(guestRoot, 'icons/tool.svg', { hasRuntime }))?.contentType).toBe('image/svg+xml');
+    expect(await resolveGuestServedFile(guestRoot, 'stray.html', { hasRuntime })).toBeNull();
+    expect(await resolveGuestServedFile(guestRoot, 'stray.js', { hasRuntime })).toBeNull();
+    expect((await resolveGuestServedFile(guestRoot, 'stray.html', { hasRuntime: true }))?.contentType).toContain('html');
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('refuses a page-less package that declares a page-only contribution', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const guestRoot = path.join(dir, 'no-entry');
+    await fs.mkdir(guestRoot, { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/no-entry',
+      version: '1.0.0',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'no-entry', name: 'No Entry', icon: 'tools' },
+          attach: 'dialog',
+        },
+      },
+    }));
+    expect(await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' })).toEqual({ ok: false, code: 'invalid-manifest' });
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('actions and commands on the public row', () => {
+  test('copies declared actions and commands and asks for conversation when a session action wants messages', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    await writeBuiltGuest(root);
+    const pkg = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+    pkg.version = '1.0.0';
+    pkg.openchamber.contributes.actions = [
+      { id: 'create-task', label: 'Create task', where: 'message', roles: ['assistant'] },
+      { id: 'summarize', label: 'Summarize', where: 'session', payload: ['messages'] },
+    ];
+    pkg.openchamber.contributes.commands = [{ name: 'task', description: 'Attach a task' }];
+    pkg.openchamber.contributes.tools = [
+      { match: 'mcp.tasks.*', name: 'Tasks', icon: 'checkbox-circle', title: '{input.id}', output: 'table', columns: ['id', 'title'] },
+    ];
+    await fs.writeFile(path.join(root, 'package.json'), JSON.stringify(pkg));
+
+    const inspected = await inspectGuestPackage(root);
+    expect(inspected.ok).toBe(true);
+    if (inspected.ok) {
+      const row = toPublicGuest({ ...inspected.guest, source: 'path', path: root, capabilityGrants: [] });
+      expect(row.actions).toEqual(pkg.openchamber.contributes.actions);
+      expect(row.commands).toEqual(pkg.openchamber.contributes.commands);
+      expect(row.tools).toEqual(pkg.openchamber.contributes.tools);
+      expect(row.capabilities).toEqual({ requested: ['conversation'], granted: [] });
+    }
+
+    pkg.openchamber.contributes.actions = [{ id: 'x', label: 'X', where: 'message', payload: ['messages'] }];
+    await fs.writeFile(path.join(root, 'package.json'), JSON.stringify(pkg));
+    expect(await inspectGuestPackage(root)).toMatchObject({ ok: false, code: 'invalid-manifest' });
+
+    await fs.rm(root, { recursive: true, force: true });
+  });
+});
+
+describe('grant scopes', () => {
+  const writeScopedGuest = async (root, filesystem) => {
+    await fs.mkdir(path.join(root, 'panel'), { recursive: true });
+    await fs.writeFile(path.join(root, 'panel', 'index.html'), '<script src="./main.js"></script>');
+    await fs.writeFile(path.join(root, 'panel', 'main.js'), 'console.log("hello")');
+    await fs.writeFile(path.join(root, 'package.json'), JSON.stringify({
+      name: '@openchamber/scoped',
+      version: '1.0.0',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'scoped', name: 'Scoped', icon: 'window', entry: 'panel/index.html' },
+          capabilities: ['prompt'],
+          filesystem,
+        },
+      },
+    }));
+  };
+
+  test('a widened filesystem list drops that grant until the user approves again', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const root = path.join(dir, 'scoped');
+    try {
+      await writeScopedGuest(root, ['~/notes/**']);
+      await writeExtensionPaths([root], persistPath);
+      await setCapabilityGrants('scoped', persistPath, ['prompt', 'filesystem'], { filesystem: ['~/notes/**'] });
+      const [approved] = await listInstalledGuests({ persistPath });
+      expect(approved.capabilityGrants).toEqual(['prompt', 'filesystem']);
+
+      await writeScopedGuest(root, ['~/**']);
+      // Any store write drops the 5s catalog cache, as an update or a reinstall would.
+      await writeExtensionPaths([root], persistPath);
+      const [widened] = await listInstalledGuests({ persistPath });
+      expect(widened.capabilityGrants).toEqual(['prompt']);
+      expect(toPublicGuest(widened).capabilities).toEqual({ requested: ['prompt', 'filesystem'], granted: ['prompt'] });
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('catalog cache under a store write', () => {
+  test('a listing that started before a withdrawal is not cached as current', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const root = path.join(dir, 'hello');
+    try {
+      await writeBuiltGuest(root);
+      await writeExtensionPaths([root], persistPath);
+      await setCapabilityGrants('hello', persistPath, ['prompt'], null);
+      // Start a listing (it reads the old file) and withdraw while it runs.
+      const early = listInstalledGuests({ persistPath });
+      await setCapabilityGrants('hello', persistPath, [], null);
+      await early;
+      const [after] = await listInstalledGuests({ persistPath });
+      expect(after.capabilityGrants).toEqual([]);
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/server/lib/guests/clone.js

@@ -0,0 +1,297 @@
+import { spawn } from 'node:child_process';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const CLONE_TIMEOUT_MS = 60_000;
+
+const PRIVATE_IPV4 = [
+  /^127\./, /^10\./, /^192\.168\./, /^169\.254\./, /^0\./,
+  /^172\.(1[6-9]|2\d|3[01])\./, /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+
+/**
+ * An install URL must name a public host. The server fetches it itself, so a
+ * loopback or LAN address would turn "install from URL" into a request against
+ * OpenChamber's own machine or network.
+ */
+export const isPublicHostname = (hostname) => {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!host || host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal')) {
+    return false;
+  }
+  const version = net.isIP(host);
+  if (version === 4) {
+    return !PRIVATE_IPV4.some((pattern) => pattern.test(host));
+  }
+  if (version === 6) {
+    return !(host === '::1' || host === '::' || host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd') || host.startsWith('::ffff:'));
+  }
+  return host.includes('.');
+};
+
+/**
+ * A public-looking hostname can still resolve to a private address (a DNS
+ * record the link's author controls). Every address it resolves to must be
+ * public; a name that does not resolve is refused too.
+ * @param {string} hostname
+ * @param {(hostname: string, options: { all: true }) => Promise<Array<{ address: string }>>} [lookup]
+ */
+/**
+ * The addresses a public hostname resolves to, or `null` when the name is
+ * not public, does not resolve, or any answer is private. Callers connect to
+ * exactly these addresses, so a second lookup by the HTTP client or by git
+ * cannot answer differently.
+ * @param {string} hostname
+ * @param {(hostname: string, options: { all: true }) => Promise<Array<{ address: string, family?: number }>>} [lookup]
+ * @returns {Promise<Array<{ address: string, family: 4 | 6 }> | null>}
+ */
+export const publicAddressesOf = async (hostname, lookup = (name, options) => dns.lookup(name, options)) => {
+  const host = hostname.replace(/^\[|\]$/g, '');
+  if (!isPublicHostname(host)) {
+    return null;
+  }
+  const literal = net.isIP(host);
+  if (literal) {
+    return [{ address: host, family: literal === 6 ? 6 : 4 }];
+  }
+  try {
+    const addresses = await lookup(host, { all: true });
+    if (addresses.length === 0 || !addresses.every((entry) => isPublicHostname(entry.address))) {
+      return null;
+    }
+    return addresses.map((entry) => ({ address: entry.address, family: net.isIP(entry.address) === 6 ? 6 : 4 }));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * `-c` options that keep a git network operation on the checked host: no
+ * redirects, and the connection pinned to the addresses just resolved
+ * (`http.curloptResolve`, git 2.30+; older builds ignore the key and keep
+ * the redirect rule). `null` when the URL is https but not public.
+ * @param {string} url
+ * @param {Parameters<typeof publicAddressesOf>[1]} [lookup]
+ * @returns {Promise<string[] | null>}
+ */
+export const gitNetworkArgs = async (url, lookup) => {
+  const hostname = httpsHostname(url);
+  if (hostname === null) {
+    return [];
+  }
+  const addresses = await publicAddressesOf(hostname, lookup);
+  if (!addresses) {
+    return null;
+  }
+  const port = new URL(url).port || '443';
+  return [
+    '-c', 'http.followRedirects=false',
+    '-c', `http.curloptResolve=${hostname}:${port}:${addresses.map((entry) => entry.address).join(',')}`,
+  ];
+};
+
+const isHttpsGitUrl = (value) => {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'https:' && parsed.username === '' && parsed.password === '' && isPublicHostname(parsed.hostname);
+  } catch {
+    return false;
+  }
+};
+
+/** SSH URLs and scp-style addresses, with no shell syntax in their components. */
+const parseSshGitUrl = (value) => {
+  if (/[\s\\\0]/.test(value)) return null;
+  let hostname;
+  let username;
+  let repository;
+  let port;
+  if (value.slice(0, 6).toLowerCase() === 'ssh://') {
+    try {
+      const url = new URL(value);
+      if (url.password || url.search || url.hash) return null;
+      hostname = url.hostname;
+      username = url.username;
+      repository = url.pathname;
+      port = url.port;
+      if (port && (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535)) return null;
+    } catch { return null; }
+  } else {
+    const match = /^(?:([A-Za-z0-9_][A-Za-z0-9_.-]*)@)?([A-Za-z0-9][A-Za-z0-9.-]*):(.+)$/.exec(value);
+    if (!match) return null;
+    [, username = '', hostname, repository] = match;
+  }
+  if (!/^[A-Za-z0-9.-]+$/.test(hostname) && !net.isIP(hostname.replace(/^\[|\]$/g, ''))) return null;
+  if (!isPublicHostname(hostname) || (username && !/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(username))) return null;
+  if (!/^\/?[A-Za-z0-9_.~][A-Za-z0-9_./~-]*$/.test(repository) || repository.split('/').includes('..')) return null;
+  return port ? { hostname, port } : { hostname };
+};
+
+export const isHttpsZipUrl = (value) => {
+  if (!isHttpsGitUrl(value)) {
+    return false;
+  }
+  try {
+    return new URL(value).pathname.toLowerCase().endsWith('.zip');
+  } catch {
+    return false;
+  }
+};
+
+// A branch or tag name git will take after `--branch`. No option-looking
+// names, no `..`, and nothing git refuses in a ref.
+const GIT_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/;
+
+/** @param {string} value */
+export const isGitRef = (value) => (
+  GIT_REF_PATTERN.test(value)
+  && !value.includes('..')
+  && !value.endsWith('/')
+  && !value.endsWith('.lock')
+  && !value.includes('//')
+);
+
+/**
+ * `https://host/org/panel.git#v1.2.0` → `{ url, ref }`. The fragment pins a
+ * branch or tag; without it the clone follows the remote default branch. A
+ * fragment that is not a usable ref, or a URL that is not public HTTPS/SSH, is
+ * `null` (the install route answers `invalid-url`).
+ * @param {string} value
+ */
+export const parseGitInstallUrl = (value) => {
+  const hashAt = value.indexOf('#');
+  const rawUrl = hashAt === -1 ? value : value.slice(0, hashAt);
+  const url = rawUrl.replace(/^ssh:\/\//i, 'ssh://');
+  const ref = hashAt === -1 ? '' : value.slice(hashAt + 1);
+  if (!isHttpsGitUrl(url) && !parseSshGitUrl(url)) {
+    return null;
+  }
+  if (hashAt !== -1 && !isGitRef(ref)) {
+    return null;
+  }
+  return ref ? { url, ref } : { url };
+};
+
+/**
+ * Run one git command without a terminal. Resolves `{ ok: true, stdout }` on
+ * exit 0 and `{ ok: false }` on a non-zero exit, a spawn error, or the
+ * timeout (the child is killed). Never rejects. `stdout` is captured only
+ * when `capture` is set so a clone's progress is not buffered.
+ */
+export const runGit = (args, { gitBinary = 'git', cwd, timeoutMs = CLONE_TIMEOUT_MS, capture = false, env = {} } = {}) => (
+  new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(
+        gitBinary,
+        args,
+        {
+          cwd,
+          windowsHide: true,
+          env: {
+            ...process.env,
+            ...env,
+            GIT_TERMINAL_PROMPT: '0',
+            GIT_ASKPASS: 'echo',
+          },
+          stdio: ['ignore', capture ? 'pipe' : 'ignore', 'pipe'],
+        },
+      );
+    } catch {
+      resolve({ ok: false });
+      return;
+    }
+    /** @type {Buffer[]} */
+    const chunks = [];
+    if (capture && child.stdout) {
+      child.stdout.on('data', (chunk) => chunks.push(chunk));
+    }
+    let settled = false;
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish({ ok: false });
+    }, timeoutMs);
+    child.on('error', () => {
+      clearTimeout(timer);
+      finish({ ok: false });
+    });
+    child.on('close', (exit) => {
+      clearTimeout(timer);
+      finish(exit === 0 ? { ok: true, stdout: Buffer.concat(chunks).toString('utf8') } : { ok: false });
+    });
+  })
+);
+
+/**
+ * Clone `source` into `dest`. Production uses HTTPS/SSH; tests may use a local repo path.
+ * `gitBinary` comes from the host's git resolver: on Windows and in the packaged desktop app a bare
+ * `git` is often not on PATH. `ref` pins a branch or tag (`--branch`); a shallow clone of a tag
+ * works the same way as of a branch.
+ */
+/** @returns {string | null} the hostname when `value` is an https URL */
+const httpsHostname = (value) => {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'https:' ? parsed.hostname : null;
+  } catch {
+    return null;
+  }
+};
+
+const quoteSshPath = (value) => {
+  const expanded = value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : value;
+  const normalized = process.platform === 'win32' ? expanded.replace(/\\/g, '/') : expanded;
+  return `'${normalized.replace(/'/g, "'\\''")}'`;
+};
+
+/** Resolve identity on the server for every clone/fetch, so key rotation takes effect. */
+export const prepareGuestGitNetwork = async (source, { gitIdentityId, lookup } = {}) => {
+  let sshCommand = process.env.GIT_SSH_COMMAND?.trim() || '';
+  if (gitIdentityId && gitIdentityId !== 'global') {
+    const { getProfile } = await import('../git/identity-storage.js');
+    const profile = getProfile(gitIdentityId);
+    if (!profile) return null;
+    if (profile.sshKey) sshCommand = `ssh -i ${quoteSshPath(profile.sshKey)} -o IdentitiesOnly=yes`;
+  }
+  const ssh = parseSshGitUrl(source);
+  if (ssh) {
+    const addresses = await publicAddressesOf(ssh.hostname, lookup);
+    if (!addresses) return null;
+    if (!sshCommand) {
+      const { getGlobalIdentity } = await import('../git/index.js');
+      const globalIdentity = await getGlobalIdentity();
+      sshCommand = globalIdentity.sshCommand || (process.env.GIT_SSH ? quoteSshPath(process.env.GIT_SSH) : 'ssh');
+    }
+    sshCommand += ` -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o Hostname=${addresses[0].address} -o HostKeyAlias=${ssh.hostname.replace(/^\[|\]$/g, '')} -o ProxyCommand=none -o ProxyJump=none`;
+    return { args: [], env: { GIT_SSH_COMMAND: sshCommand, GIT_SSH_VARIANT: 'ssh' } };
+  }
+  const args = await gitNetworkArgs(source, lookup);
+  if (!args) return null;
+  return sshCommand ? { args, env: { GIT_SSH_COMMAND: sshCommand } } : { args };
+};
+
+export const cloneGitRepository = async (source, dest, { gitBinary = 'git', timeoutMs = CLONE_TIMEOUT_MS, ref, lookup, gitIdentityId } = {}) => {
+  if (ref !== undefined && !isGitRef(ref)) {
+    return { ok: false, code: 'clone-failed' };
+  }
+  const network = await prepareGuestGitNetwork(source, { lookup, gitIdentityId }).catch(() => null);
+  if (!network) {
+    return { ok: false, code: 'clone-failed' };
+  }
+  const args = [...network.args, 'clone', '--depth', '1'];
+  if (ref) {
+    args.push('--branch', ref);
+  }
+  args.push('--', source, dest);
+  const result = await runGit(args, { gitBinary, timeoutMs, env: network.env });
+  return result.ok ? { ok: true } : { ok: false, code: 'clone-failed' };
+};