codehost 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [0.16.0](https://github.com/snomiao/codehost/compare/v0.15.0...v0.16.0) (2026-06-10)
+
+
+### Features
+
+* **provision:** codehost init scaffolds .codehost/ (config + setup hooks) ([b1a2e9c](https://github.com/snomiao/codehost/commit/b1a2e9c23230e09dc6a291dbcab098083bb59f4d))
+* **provision:** daemon-side provision handler over the tunnel ([c297e95](https://github.com/snomiao/codehost/commit/c297e9577b3e1a65260ab105478feb63186fce46))
+* **provision:** tested security core for workspace provisioning ([ca7508c](https://github.com/snomiao/codehost/commit/ca7508c48e78eb46fbf8bf42ef398360bea38f86))
+* **web:** provisioning browser flow — run setup.sh on repo open, stream log ([9bd8742](https://github.com/snomiao/codehost/commit/9bd8742b143e84d386f8af138df73e57cac70e46))
+
 # [0.15.0](https://github.com/snomiao/codehost/compare/v0.14.0...v0.15.0) (2026-06-10)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehost",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "oxmgr": "^0.4.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
+    "yaml": "^2.9.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {

package/src/cli/commands/init.ts

@@ -0,0 +1,27 @@
+import { resolve } from "node:path";
+import type { CommandModule } from "yargs";
+import { scaffoldCodehost } from "../init";
+
+interface InitArgs {
+  dir: string;
+  force: boolean;
+}
+
+export const initCommand: CommandModule<{}, InitArgs> = {
+  command: "init [dir]",
+  describe: "Scaffold .codehost/ (config.yaml + setup.sh) so repo links auto-provision",
+  builder: (y) =>
+    y
+      .positional("dir", { describe: "Home dir to scaffold (defaults to cwd)", type: "string", default: "." })
+      .option("force", { alias: "f", describe: "Overwrite existing files", type: "boolean", default: false }) as any,
+  handler: (argv) => {
+    const dir = resolve(process.cwd(), argv.dir);
+    const written = scaffoldCodehost(dir, argv.force);
+    if (written.length === 0) {
+      console.log(`[codehost] .codehost/ already set up in ${dir} (use --force to overwrite)`);
+      return;
+    }
+    console.log(`[codehost] scaffolded:\n${written.map((p) => `  ${p}`).join("\n")}`);
+    console.log(`[codehost] edit .codehost/setup.sh, then run: codehost serve ${dir}`);
+  },
+};

package/src/cli/commands/serve.ts

@@ -2,7 +2,7 @@ import { hostname } from "node:os";
 import { resolve } from "node:path";
 import type { CommandModule } from "yargs";
 import type { PeerMeta } from "../../shared/signaling";
-import { DEFAULT_LAYOUT, toPosixPath } from "../../shared/repo";
+import { DEFAULT_LAYOUT, GITHUB_HOST, toPosixPath } from "../../shared/repo";
 import { TOKEN_REQUIREMENTS, validateToken } from "../../shared/token";
 import { launchServeDaemon } from "../daemonize";
 import { announceConnect } from "../open-url";
@@ -101,6 +101,7 @@ export const serveCommand: CommandModule<{}, ServeArgs> = {
       signal: argv.signal,
       meta,
       label: `serving workspace root ${dir}`,
+      provision: { homeDir: dir, host: GITHUB_HOST },
       launch: async (basePath) => {
         const v = await launchVscode({ dir, basePath, port: argv.port });
         return { port: v.port, stop: v.stop };

package/src/cli/index.ts

@@ -2,6 +2,7 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { setupCommand } from "./commands/setup";
+import { initCommand } from "./commands/init";
 import { serveCommand } from "./commands/serve";
 import { devCommand } from "./commands/dev";
 import { exposeCommand } from "./commands/expose";
@@ -14,6 +15,7 @@ yargs(hideBin(process.argv))
   .scriptName("codehost")
   .usage("$0 <command> [options]")
   .command(setupCommand)
+  .command(initCommand)
   .command(serveCommand)
   .command(devCommand)
   .command(exposeCommand)

package/src/cli/init.test.ts

@@ -0,0 +1,48 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { scaffoldCodehost } from "./init";
+
+const homes: string[] = [];
+afterAll(() => homes.forEach((h) => rmSync(h, { recursive: true, force: true })));
+function mkHome(): string {
+  const h = mkdtempSync(join(tmpdir(), "codehost-init-"));
+  homes.push(h);
+  return h;
+}
+
+describe("scaffoldCodehost", () => {
+  test("writes config.yaml + setup.sh + setup.ps1", () => {
+    const home = mkHome();
+    const written = scaffoldCodehost(home);
+    expect(written).toHaveLength(3);
+    expect(existsSync(join(home, ".codehost", "config.yaml"))).toBe(true);
+    expect(existsSync(join(home, ".codehost", "setup.sh"))).toBe(true);
+    expect(existsSync(join(home, ".codehost", "setup.ps1"))).toBe(true);
+  });
+
+  test("config.yaml is valid YAML with a workspace template", () => {
+    const home = mkHome();
+    scaffoldCodehost(home);
+    const cfg = parseYaml(readFileSync(join(home, ".codehost", "config.yaml"), "utf8"));
+    expect(cfg.workspace).toBe("ws/{owner}/{repo}/tree/{branch}");
+  });
+
+  test("setup.sh keeps shell vars literal (no JS interpolation leaked)", () => {
+    const home = mkHome();
+    scaffoldCodehost(home);
+    const sh = readFileSync(join(home, ".codehost", "setup.sh"), "utf8");
+    expect(sh).toContain("$CODEHOST_WS");
+    expect(sh).toContain("${ws%/tree/$CODEHOST_BRANCH}");
+    expect(sh).toContain("git -C \"$repo\" worktree add");
+  });
+
+  test("idempotent: a second run writes nothing; --force overwrites", () => {
+    const home = mkHome();
+    expect(scaffoldCodehost(home)).toHaveLength(3);
+    expect(scaffoldCodehost(home)).toHaveLength(0);
+    expect(scaffoldCodehost(home, true)).toHaveLength(3);
+  });
+});

package/src/cli/init.ts

@@ -0,0 +1,103 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Scaffolds a home's `.codehost/` config dir: an editable, idempotent setup hook
+// (run on every repo open) plus a config.yaml. Provisioning is opt-in by these
+// files existing — `codehost init` is how you opt in.
+
+const CONFIG_YAML = `# codehost workspace config — see docs/provisioning.md
+
+# Where /gh/<owner>/<repo>/tree/<branch> lands, relative to this home dir.
+# Default (if omitted): {owner}/{repo}/tree/{branch}
+workspace: "ws/{owner}/{repo}/tree/{branch}"
+
+# Optional: only these repos may auto-provision (a trailing /* is an owner
+# wildcard). Empty/absent = allow all. The room token already grants access, so
+# this is extra hardening, not the primary gate.
+# allowlist:
+#   - github.com/snomiao/*
+`;
+
+const SETUP_SH = `#!/usr/bin/env bash
+# codehost provisioning hook. Runs on every open of /gh/<owner>/<repo>/tree/<branch>
+# BEFORE the editor opens CODEHOST_WS. Keep it idempotent: clone/worktree if
+# missing, fast-skip if present. Edit freely (install deps, pull/rebase policy…).
+#
+# Env in:  CODEHOST_OWNER  CODEHOST_REPO  CODEHOST_BRANCH  CODEHOST_HOST
+#          CODEHOST_HOME (this dir)       CODEHOST_WS (the path the editor opens)
+set -euo pipefail
+
+ws="$CODEHOST_WS"
+if [ -e "$ws/.git" ]; then
+  echo "[setup] $ws already provisioned"
+  exit 0
+fi
+
+# Primary clone = the workspace path minus the /tree/<branch> tail (layout-agnostic).
+repo="\${ws%/tree/$CODEHOST_BRANCH}"
+url="https://$CODEHOST_HOST/$CODEHOST_OWNER/$CODEHOST_REPO.git"
+
+if [ ! -e "$repo/.git" ]; then
+  echo "[setup] cloning $url"
+  mkdir -p "$(dirname "$repo")"
+  git clone "$url" "$repo"
+fi
+
+echo "[setup] adding worktree $ws @ $CODEHOST_BRANCH"
+mkdir -p "$(dirname "$ws")"
+git -C "$repo" fetch --quiet origin "$CODEHOST_BRANCH" || true
+git -C "$repo" worktree add "$ws" "$CODEHOST_BRANCH" \\
+  || git -C "$repo" worktree add -b "$CODEHOST_BRANCH" "$ws" "origin/$CODEHOST_BRANCH"
+
+# Example: install deps for this worktree (uncomment / edit).
+# ( cd "$ws" && bun install )
+
+echo "[setup] ready: $ws"
+`;
+
+const SETUP_PS1 = `# codehost provisioning hook (Windows). See setup.sh for the contract.
+$ErrorActionPreference = "Stop"
+$ws = $env:CODEHOST_WS
+if (Test-Path (Join-Path $ws ".git")) { Write-Host "[setup] $ws already provisioned"; exit 0 }
+
+$repo = $ws -replace "[\\\\/]tree[\\\\/]$([regex]::Escape($env:CODEHOST_BRANCH))$", ""
+$url = "https://$($env:CODEHOST_HOST)/$($env:CODEHOST_OWNER)/$($env:CODEHOST_REPO).git"
+
+if (-not (Test-Path (Join-Path $repo ".git"))) {
+  Write-Host "[setup] cloning $url"
+  New-Item -ItemType Directory -Force -Path (Split-Path $repo) | Out-Null
+  git clone $url $repo
+}
+Write-Host "[setup] adding worktree $ws @ $($env:CODEHOST_BRANCH)"
+New-Item -ItemType Directory -Force -Path (Split-Path $ws) | Out-Null
+git -C $repo worktree add $ws $env:CODEHOST_BRANCH
+Write-Host "[setup] ready: $ws"
+`;
+
+const FILES: Array<{ rel: string; body: string; exec?: boolean }> = [
+  { rel: "config.yaml", body: CONFIG_YAML },
+  { rel: "setup.sh", body: SETUP_SH, exec: true },
+  { rel: "setup.ps1", body: SETUP_PS1 },
+];
+
+/** Write `<homeDir>/.codehost/{config.yaml,setup.sh,setup.ps1}`. Existing files
+ *  are kept unless `force`. Returns the list of files actually written. */
+export function scaffoldCodehost(homeDir: string, force = false): string[] {
+  const dir = join(homeDir, ".codehost");
+  mkdirSync(dir, { recursive: true });
+  const written: string[] = [];
+  for (const f of FILES) {
+    const path = join(dir, f.rel);
+    if (existsSync(path) && !force) continue;
+    writeFileSync(path, f.body);
+    if (f.exec) {
+      try {
+        chmodSync(path, 0o755);
+      } catch {
+        // non-POSIX fs — ignore
+      }
+    }
+    written.push(path);
+  }
+  return written;
+}

package/src/cli/provision-server.test.ts

@@ -0,0 +1,76 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { handleProvision, isProvisionPath } from "./provision-server";
+
+// A throwaway home with an optional .codehost/setup.sh.
+function makeHome(setup?: string, configYaml?: string): string {
+  const home = mkdtempSync(join(tmpdir(), "codehost-prov-"));
+  if (setup || configYaml) mkdirSync(join(home, ".codehost"), { recursive: true });
+  if (setup) writeFileSync(join(home, ".codehost", "setup.sh"), setup);
+  if (configYaml) writeFileSync(join(home, ".codehost", "config.yaml"), configYaml);
+  homes.push(home);
+  return home;
+}
+const homes: string[] = [];
+afterAll(() => homes.forEach((h) => rmSync(h, { recursive: true, force: true })));
+
+const q = (owner: string, repo: string, branch = "main") =>
+  `/__codehost/provision?owner=${owner}&repo=${repo}&branch=${branch}`;
+
+describe("isProvisionPath", () => {
+  test("matches the route, ignores query + other paths", () => {
+    expect(isProvisionPath("/__codehost/provision?owner=a")).toBe(true);
+    expect(isProvisionPath("/vs/abc/?folder=x")).toBe(false);
+  });
+});
+
+describe("handleProvision", () => {
+  test("no setup script → 200 + workspace path in header/body (today's behavior)", async () => {
+    const home = makeHome();
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/main`);
+    expect(await res.json()).toEqual({ workspace: `${home}/snomiao/codehost/tree/main` });
+  });
+
+  test("runs setup.sh, streams output + exit sentinel, env is passed", async () => {
+    const home = makeHome('echo "owner=$CODEHOST_OWNER branch=$CODEHOST_BRANCH ws=$CODEHOST_WS"\nexit 0\n');
+    const res = await handleProvision(q("snomiao", "codehost", "feat/x"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/snomiao/codehost/tree/feat/x`);
+    const body = await res.text();
+    expect(body).toContain(`owner=snomiao branch=feat/x ws=${home}/snomiao/codehost/tree/feat/x`);
+    expect(body).toContain("::codehost:exit=0");
+  });
+
+  test("propagates a non-zero exit code in the sentinel", async () => {
+    const home = makeHome('echo "boom" >&2\nexit 7\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    const body = await res.text();
+    expect(body).toContain("boom");
+    expect(body).toContain("::codehost:exit=7");
+  });
+
+  test("rejects a traversal identity with 400 (no spawn)", async () => {
+    const home = makeHome("echo SHOULD_NOT_RUN\nexit 0\n");
+    const res = await handleProvision(q("..", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.status).toBe(400);
+    expect(await res.text()).not.toContain("SHOULD_NOT_RUN");
+  });
+
+  test("enforces the config allowlist with 403", async () => {
+    const home = makeHome("echo hi\nexit 0\n", "allowlist:\n  - github.com/snomiao/*\n");
+    const ok = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(ok.status).toBe(200);
+    const denied = await handleProvision(q("evil", "repo"), { homeDir: home, host: "github.com" });
+    expect(denied.status).toBe(403);
+  });
+
+  test("config.yaml workspace template overrides the layout", async () => {
+    const home = makeHome(undefined, 'workspace: "ws/{owner}/{repo}/tree/{branch}"\n');
+    const res = await handleProvision(q("snomiao", "codehost"), { homeDir: home, host: "github.com" });
+    expect(res.headers.get("x-codehost-workspace")).toBe(`${home}/ws/snomiao/codehost/tree/main`);
+  });
+});

package/src/cli/provision-server.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { repoAllowed, resolveWorkspacePath, validateProvisionTarget, type ProvisionTarget } from "../shared/provision";
+import { fromPosixPath, repoKey, toPosixPath } from "../shared/repo";
+
+// Daemon side of provisioning. A repo open hits `GET /__codehost/provision?...`
+// over the tunnel; this validates the identity, computes the daemon-authoritative
+// workspace path, and (if `.codehost/setup.sh` exists) runs it, streaming its
+// output back as the response body. The resolved path rides in the
+// `x-codehost-workspace` header so it never depends on parsing script output.
+
+export const PROVISION_PATH = "/__codehost/provision";
+const TIMEOUT_MS = Number(process.env.CODEHOST_PROVISION_TIMEOUT_MS) || 15 * 60_000;
+
+export interface ProvisionDeps {
+  /** Real OS path of the served home root. */
+  homeDir: string;
+  /** Git host advertised by this daemon (default github.com). */
+  host: string;
+}
+
+interface CodehostConfig {
+  workspace?: string; // layout template, e.g. "ws/{owner}/{repo}/tree/{branch}"
+  allowlist?: string[];
+}
+
+/** True for the provision route (ignoring the query string). */
+export function isProvisionPath(path: string): boolean {
+  return path.split("?")[0] === PROVISION_PATH;
+}
+
+function readConfig(homeDir: string): CodehostConfig {
+  try {
+    const raw = readFileSync(join(homeDir, ".codehost", "config.yaml"), "utf8");
+    const c = (parseYaml(raw) ?? {}) as Record<string, unknown>;
+    return {
+      workspace: typeof c.workspace === "string" ? c.workspace : undefined,
+      allowlist: Array.isArray(c.allowlist)
+        ? c.allowlist.filter((x): x is string => typeof x === "string")
+        : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** Locate the host's setup script (platform-appropriate), or null if none — in
+ *  which case provisioning is a no-op and we just return the path. */
+function findSetupScript(homeDir: string): string[] | null {
+  const dir = join(homeDir, ".codehost");
+  if (process.platform === "win32") {
+    const bat = join(dir, "setup.bat");
+    if (existsSync(bat)) return ["cmd", "/c", bat];
+    const ps1 = join(dir, "setup.ps1");
+    if (existsSync(ps1)) return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ps1];
+  }
+  const sh = join(dir, "setup.sh");
+  if (existsSync(sh)) return ["bash", sh];
+  return null;
+}
+
+// Per-workspace coalescing: a concurrent open of the same target waits for the
+// running provision instead of spawning a second one.
+const inFlight = new Map<string, Promise<number>>();
+
+export async function handleProvision(rawPath: string, deps: ProvisionDeps): Promise<Response> {
+  const url = new URL(`http://x${rawPath}`);
+  const v = validateProvisionTarget(
+    url.searchParams.get("owner") ?? "",
+    url.searchParams.get("repo") ?? "",
+    url.searchParams.get("branch") ?? "",
+  );
+  if (!v.ok) return json(400, { error: v.reason });
+
+  const host = (url.searchParams.get("host") ?? deps.host).toLowerCase();
+  const cfg = readConfig(deps.homeDir);
+  const key = repoKey({ host, owner: v.target.owner, name: v.target.repo });
+  if (!repoAllowed(key, cfg.allowlist)) return json(403, { error: `repo not allowlisted: ${key}` });
+
+  const wsPosix = resolveWorkspacePath(toPosixPath(deps.homeDir), cfg.workspace ?? "", v.target);
+  const headers = { "x-codehost-workspace": wsPosix };
+
+  const cmd = findSetupScript(deps.homeDir);
+  if (!cmd) return json(200, { workspace: wsPosix }, headers); // no script: hand back the path
+
+  const lockKey = fromPosixPath(wsPosix);
+  const existing = inFlight.get(lockKey);
+  const body = existing
+    ? coalescedBody(existing) // a provision is already running for this workspace
+    : freshBody(cmd, deps, v.target, host, lockKey);
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", ...headers },
+  });
+}
+
+/** Spawn the setup script, streaming merged stdout+stderr, ending with an exit
+ *  sentinel the browser parses for success/failure. */
+function freshBody(
+  cmd: string[],
+  deps: ProvisionDeps,
+  target: ProvisionTarget,
+  host: string,
+  lockKey: string,
+): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      let resolveDone!: (code: number) => void;
+      inFlight.set(lockKey, new Promise<number>((r) => (resolveDone = r)));
+      const say = (s: string) => controller.enqueue(enc.encode(s));
+      say(`[codehost] provisioning ${host}/${target.owner}/${target.repo}@${target.branch}\n`);
+      let code = 1;
+      try {
+        const proc = Bun.spawn(cmd, {
+          cwd: deps.homeDir,
+          env: {
+            ...process.env,
+            CODEHOST_OWNER: target.owner,
+            CODEHOST_REPO: target.repo,
+            CODEHOST_BRANCH: target.branch,
+            CODEHOST_HOST: host,
+            CODEHOST_HOME: deps.homeDir,
+            CODEHOST_WS: fromPosixPath(lockKey),
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const timer = setTimeout(() => {
+          try {
+            proc.kill();
+          } catch {
+            // already gone
+          }
+        }, TIMEOUT_MS);
+        const pump = async (stream: ReadableStream<Uint8Array>) => {
+          const reader = stream.getReader();
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+        };
+        await Promise.all([pump(proc.stdout), pump(proc.stderr)]);
+        code = await proc.exited;
+        clearTimeout(timer);
+      } catch (err) {
+        say(`[codehost] provision error: ${String(err)}\n`);
+      } finally {
+        inFlight.delete(lockKey);
+        resolveDone(code);
+        say(`\n::codehost:exit=${code}\n`);
+        controller.close();
+      }
+    },
+  });
+}
+
+/** Attach to a running provision: wait for it, then emit the exit sentinel. */
+function coalescedBody(existing: Promise<number>): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      controller.enqueue(enc.encode("[codehost] provision already running for this workspace; waiting…\n"));
+      const code = await existing.catch(() => 1);
+      controller.enqueue(enc.encode(`\n::codehost:exit=${code}\n`));
+      controller.close();
+    },
+  });
+}
+
+function json(status: number, obj: unknown, extra: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store", ...extra },
+  });
+}

package/src/cli/run-server.ts

@@ -2,6 +2,7 @@ import { type PeerMeta, newPeerId } from "../shared/signaling";
 import { SignalingClient } from "../shared/signaling-client";
 import { RtcDaemon } from "./rtc-daemon";
 import { Tunnel } from "./tunnel";
+import { handleProvision, type ProvisionDeps } from "./provision-server";
 
 export interface LaunchResult {
   /** Local port to tunnel to. */
@@ -24,6 +25,9 @@ export interface RunServerOptions {
   label: string;
   /** Prepare the local target to tunnel, given the /vs/<peerId> base path. */
   launch: (basePath: string) => Promise<LaunchResult>;
+  /** Enables `/__codehost/provision` on the tunnel (serve only — runs the home's
+   *  setup.sh). Omitted by `expose`, which has no home/workspace. */
+  provision?: ProvisionDeps;
 }
 
 /**
@@ -64,7 +68,12 @@ export async function runServer(opts: RunServerOptions): Promise<never> {
     sendSignal: (to, data) => client.sendSignal(to, data),
     onChannel: (viewerId, channel) => {
       console.log(`[codehost] viewer ${viewerId.slice(0, 8)} connected; bridging to :${target.port}`);
-      new Tunnel(channel, target.port, target.stripBasePath);
+      new Tunnel(
+        channel,
+        target.port,
+        target.stripBasePath,
+        opts.provision ? (rawPath) => handleProvision(rawPath, opts.provision!) : undefined,
+      );
     },
   });
 

package/src/cli/tunnel.ts

@@ -1,4 +1,5 @@
 import type { DataChannel } from "node-datachannel";
+import { isProvisionPath } from "./provision-server";
 import {
   type HttpReqHead,
   Op,
@@ -54,6 +55,9 @@ export class Tunnel {
      * doesn't know it, so we strip `/vs/<peerId>` before proxying.
      */
     private stripPrefix?: string,
+    /** Handles `/__codehost/*` requests locally (provisioning) instead of
+     *  forwarding to the local server. Wired only for `serve` (not `expose`). */
+    private onProvision?: (rawPath: string) => Promise<Response>,
   ) {
     this.origin = `http://127.0.0.1:${vscodePort}`;
     this.wsOrigin = `ws://127.0.0.1:${vscodePort}`;
@@ -134,12 +138,15 @@ export class Tunnel {
     const body = hasBody ? concat(stream.body) : undefined;
 
     try {
-      const res = await fetch(this.origin + this.localPath(path), {
-        method,
-        headers: reqHeaders,
-        body: body as BodyInit | undefined,
-        redirect: "manual",
-      });
+      const res =
+        this.onProvision && isProvisionPath(path)
+          ? await this.onProvision(path)
+          : await fetch(this.origin + this.localPath(path), {
+              method,
+              headers: reqHeaders,
+              body: body as BodyInit | undefined,
+              redirect: "manual",
+            });
 
       const resHeaders: Record<string, string> = {};
       res.headers.forEach((v, k) => {

package/src/shared/provision.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { repoAllowed, resolveWorkspacePath, validateProvisionTarget } from "./provision";
+
+describe("validateProvisionTarget — the injection boundary", () => {
+  test("accepts normal identities", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "main");
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.target).toEqual({ owner: "snomiao", repo: "codehost", branch: "main" });
+  });
+
+  test("accepts branch with slashes and hyphens", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "feat/some-thing");
+    expect(r.ok).toBe(true);
+  });
+
+  test("empty branch defaults to main", () => {
+    const r = validateProvisionTarget("snomiao", "codehost", "");
+    expect(r.ok && r.target.branch).toBe("main");
+  });
+
+  // The whole point: these must NOT pass.
+  test("rejects path traversal in owner/repo", () => {
+    expect(validateProvisionTarget("..", "codehost", "main").ok).toBe(false);
+    expect(validateProvisionTarget(".", "codehost", "main").ok).toBe(false);
+    expect(validateProvisionTarget("snomiao", "..", "main").ok).toBe(false);
+    expect(validateProvisionTarget("a/b", "codehost", "main").ok).toBe(false); // slash
+    expect(validateProvisionTarget(".ssh", "codehost", "main").ok).toBe(false); // leading dot
+  });
+
+  test("rejects traversal / leading-dash / junk in branch", () => {
+    expect(validateProvisionTarget("o", "r", "a/../../etc").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "..").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "-x").ok).toBe(false); // option injection
+    expect(validateProvisionTarget("o", "r", "feat/-x").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "a b").ok).toBe(false); // whitespace
+    expect(validateProvisionTarget("o", "r", "a;rm -rf").ok).toBe(false); // shell meta
+    expect(validateProvisionTarget("o", "r", "a$(id)").ok).toBe(false);
+    expect(validateProvisionTarget("o", "r", "a`id`").ok).toBe(false);
+  });
+});
+
+describe("resolveWorkspacePath — daemon-authoritative, cannot escape home", () => {
+  test("fills the default layout under home", () => {
+    const t = { owner: "snomiao", repo: "codehost", branch: "main" };
+    expect(resolveWorkspacePath("/Users/sno/ws", "", t)).toBe("/Users/sno/ws/snomiao/codehost/tree/main");
+  });
+
+  test("honors a custom layout template (e.g. config.yaml ws/ home model)", () => {
+    const t = { owner: "snomiao", repo: "codehost", branch: "feat/x" };
+    expect(resolveWorkspacePath("/home/me", "ws/{owner}/{repo}/tree/{branch}", t)).toBe(
+      "/home/me/ws/snomiao/codehost/tree/feat/x",
+    );
+  });
+
+  test("a validated target can never produce a path above home", () => {
+    // Only validated targets reach here; confirm the segments are inert.
+    const v = validateProvisionTarget("snomiao", "codehost", "main");
+    expect(v.ok).toBe(true);
+    if (v.ok) {
+      const p = resolveWorkspacePath("/Users/sno/ws", "{owner}/{repo}/tree/{branch}", v.target);
+      expect(p.startsWith("/Users/sno/ws/")).toBe(true);
+      expect(p.includes("/../")).toBe(false);
+    }
+  });
+});
+
+describe("repoAllowed", () => {
+  test("empty/absent allowlist allows all", () => {
+    expect(repoAllowed("github.com/x/y", undefined)).toBe(true);
+    expect(repoAllowed("github.com/x/y", [])).toBe(true);
+  });
+
+  test("exact + owner wildcard", () => {
+    expect(repoAllowed("github.com/snomiao/codehost", ["github.com/snomiao/codehost"])).toBe(true);
+    expect(repoAllowed("github.com/snomiao/codehost", ["github.com/snomiao/*"])).toBe(true);
+    expect(repoAllowed("github.com/evil/repo", ["github.com/snomiao/*"])).toBe(false);
+    expect(repoAllowed("gitlab.com/snomiao/x", ["github.com/snomiao/*"])).toBe(false);
+  });
+});

package/src/shared/provision.ts

@@ -0,0 +1,67 @@
+// Pure provisioning helpers: the security boundary for "open a repo link runs a
+// host setup script". The room token already grants code execution (the editor
+// is a terminal), so script execution is not new trust — the only new surface is
+// a crafted/shared link auto-triggering setup.sh with attacker-chosen
+// owner/repo/branch. That surface is bounded entirely here: validate the
+// identity so it can't traverse out of the home root or inject options, and
+// compute the workspace path **daemon-authoritatively** (never from script
+// output). Kept pure + unit-tested precisely because it's the injection gate.
+
+import { DEFAULT_BRANCH, DEFAULT_LAYOUT } from "./repo";
+
+export interface ProvisionTarget {
+  owner: string;
+  repo: string;
+  branch: string;
+}
+
+export type ValidateResult = { ok: true; target: ProvisionTarget } | { ok: false; reason: string };
+
+// First char must be alphanumeric: rejects "..", ".", leading-dot tricks, and a
+// leading "-" in one stroke (a bare `[A-Za-z0-9._-]+` would match "..").
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Positive allowlist for a branch ref as a whole: safe path chars only. Excludes
+// whitespace, control chars, and shell metacharacters by construction.
+const BRANCH_CHARS = /^[A-Za-z0-9._/-]+$/;
+
+/** Validate the (owner, repo, branch) identity carried by a repo deep link before
+ *  it is used to build a filesystem path or passed to a setup script. Branch may
+ *  contain "/" (worktree refs) but no empty/`.`/`..` segment and no segment
+ *  starting with "-" (else `git checkout "$BRANCH"` eats it as an option flag —
+ *  option injection survives env-passing because the script interpolates it). An
+ *  empty branch defaults to DEFAULT_BRANCH. */
+export function validateProvisionTarget(owner: string, repo: string, branch: string): ValidateResult {
+  if (!SEGMENT.test(owner)) return { ok: false, reason: `invalid owner: ${owner}` };
+  if (!SEGMENT.test(repo)) return { ok: false, reason: `invalid repo: ${repo}` };
+  const b = (branch || DEFAULT_BRANCH).trim();
+  if (!BRANCH_CHARS.test(b)) return { ok: false, reason: `invalid branch: ${b}` };
+  const segs = b.split("/");
+  if (segs.some((s) => s === "" || s === "." || s === ".." || s.startsWith("-"))) {
+    return { ok: false, reason: `invalid branch: ${b}` };
+  }
+  return { ok: true, target: { owner, repo, branch: b } };
+}
+
+/** Fill a workspace layout template from a *validated* target. POSIX-space (the
+ *  served cwd is already `toPosixPath`'d), so the result is the `?folder=` form.
+ *  Safe against traversal only because `target` passed validateProvisionTarget. */
+export function resolveWorkspacePath(homePosix: string, layout: string, target: ProvisionTarget): string {
+  const rel = (layout || DEFAULT_LAYOUT)
+    .replace(/\{owner\}/g, target.owner)
+    .replace(/\{repo\}/g, target.repo)
+    .replace(/\{branch\}/g, target.branch);
+  return `${homePosix.replace(/\/+$/, "")}/${rel.replace(/^\/+/, "")}`;
+}
+
+/** Whether a repo may be auto-provisioned. An empty/absent allowlist allows all
+ *  (provisioning is already opt-in by the presence of setup.sh); otherwise the
+ *  repo key `<host>/<owner>/<repo>` must match an entry, where a trailing `/*`
+ *  is an owner/prefix wildcard (e.g. `github.com/snomiao/*`). */
+export function repoAllowed(repoKey: string, allowlist: string[] | undefined): boolean {
+  if (!allowlist || allowlist.length === 0) return true;
+  return allowlist.some((rule) => {
+    const r = rule.trim();
+    if (r.endsWith("/*")) return repoKey.startsWith(r.slice(0, -1));
+    return repoKey === r;
+  });
+}

package/src/shared/repo.ts

@@ -100,6 +100,16 @@ export function toPosixPath(p: string): string {
   return p.replace(/\\/g, "/");
 }
 
+/** Inverse of `toPosixPath` for the host OS: the VS Code `?folder=` form back to
+ *  a real filesystem path. `/C:/ws` -> `C:\ws` (Windows); a POSIX path is
+ *  returned unchanged (only Windows cwds carry the `/<drive>:/` shape). */
+export function fromPosixPath(p: string): string {
+  const drive = /^\/([A-Za-z]):(\/.*)?$/.exec(p);
+  if (!drive) return p;
+  const rest = (drive[2] ?? "").replace(/\//g, "\\");
+  return `${drive[1]}:${rest || "\\"}`;
+}
+
 /** Fill a layout template from a repo target (default branch -> DEFAULT_BRANCH). */
 export function fillLayout(layout: string, t: RepoTarget): string {
   return layout

package/src/web/discovery.tsx

@@ -10,6 +10,7 @@ import { connBroker } from "./conn-broker";
 import {
   DEFAULT_BRANCH,
   type DeepLink,
+  type RepoTarget,
   type RoomMatch,
   gitUrlToPath,
   parseDeepLink,
@@ -24,7 +25,7 @@ import { deriveTags, matchQuery, shortRoomLabel, tagKey } from "../shared/tags";
 
 const TOKEN_KEY = "codehost.token";
 
-type ConnState = "idle" | "connecting" | "connected" | "failed";
+type ConnState = "idle" | "connecting" | "provisioning" | "connected" | "failed";
 
 /** A server discovered in a specific room (its token routes the signaling). */
 type RoomedServer = { server: PeerInfo; room: string };
@@ -180,6 +181,8 @@ export function Discovery() {
   const [activePeerId, setActivePeerId] = useState<string | null>(null);
   const [connState, setConnState] = useState<ConnState>("idle");
   const [iframeSrc, setIframeSrc] = useState<string | null>(null);
+  // Streamed setup.sh output shown while connState === "provisioning".
+  const [provisionLog, setProvisionLog] = useState("");
 
   const rtcRef = useRef<RtcClient | null>(null);
   const activePeerRef = useRef<string | null>(null);
@@ -351,7 +354,13 @@ export function Discovery() {
     sendersRef.current.delete(t);
   }
 
-  async function connectTo(server: PeerInfo, room: string, folder?: string, fromHistory = false) {
+  async function connectTo(
+    server: PeerInfo,
+    room: string,
+    folder?: string,
+    fromHistory = false,
+    repoTarget?: RepoTarget,
+  ) {
     const send = sendersRef.current.get(room);
     if (!send) return;
     dialingRef.current = true; // synchronous gate against concurrent triggers
@@ -374,7 +383,7 @@ export function Discovery() {
       // handshake) and push a history entry, so Back returns to the list and
       // Forward returns here. When `fromHistory`, the browser already set the URL
       // (back/forward/reconnect) — don't push again, but a prior entry exists.
-      const openFolder = folder ?? server.meta?.cwd;
+      let openFolder = folder ?? server.meta?.cwd;
       if (fromHistory) {
         pushedRef.current = true;
         sharePathRef.current = window.location.pathname;
@@ -425,10 +434,23 @@ export function Discovery() {
         });
 
       await connBroker.connect(server.peerId, establish);
+
+      // For a repo deep link, ask the daemon to provision (run .codehost/setup.sh
+      // and hand back the authoritative workspace path) before opening. Streams
+      // the log under the "provisioning" state. Daemons without the route (older
+      // builds) return no path → fall back to the browser-computed folder.
+      if (repoTarget) {
+        setConnState("provisioning");
+        setProvisionLog("");
+        const ws = await runProvision(server.peerId, repoTarget);
+        if (activePeerRef.current !== server.peerId) return; // cancelled/switched mid-provision
+        if (ws) openFolder = ws;
+      }
+
       setConnState("connected");
       // The daemon no longer sets a default folder (current VS Code serve-web
       // dropped that flag), so open the served workspace from here: the
-      // deep-link folder if we have one, else the server's reported cwd.
+      // provisioned/deep-link folder if we have one, else the server's reported cwd.
       activeFolderRef.current = openFolder;
       setIframeSrc(`/vs/${server.peerId}/${folderQuery(openFolder)}`);
       setResolving(null);
@@ -446,6 +468,48 @@ export function Discovery() {
     }
   }
 
+  // Ask the daemon to provision a repo workspace over the tunnel: stream
+  // setup.sh's output into `provisionLog` and return the daemon-authoritative
+  // path (the `x-codehost-workspace` header). Returns null when the daemon has
+  // no provision route (older build) or the call fails — caller falls back.
+  async function runProvision(peerId: string, t: RepoTarget): Promise<string | null> {
+    const params = new URLSearchParams({
+      owner: t.owner,
+      repo: t.name,
+      branch: t.branch ?? DEFAULT_BRANCH,
+      host: t.host,
+    });
+    let res: Response;
+    try {
+      res = await connBroker.tunnelFor(peerId).fetch("GET", `/__codehost/provision?${params}`, {});
+    } catch {
+      return null;
+    }
+    const ws = res.headers.get("x-codehost-workspace");
+    if (!ws) {
+      await res.body?.cancel().catch(() => {});
+      return null;
+    }
+    let buf = `[codehost] provisioning ${t.owner}/${t.name}@${t.branch ?? DEFAULT_BRANCH}…\n`;
+    setProvisionLog(buf);
+    if (res.body) {
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          // Hide the internal exit sentinel from the displayed log.
+          setProvisionLog(buf.replace(/\n::codehost:exit=\d+\n?/, "\n"));
+        }
+      } catch {
+        // stream interrupted (channel closed) — return the path anyway
+      }
+    }
+    return ws;
+  }
+
   // Shareable deep-link pathname for a server+folder, with no side effects (no
   // token — Share adds that). Keeps an existing deep-link path as-is; otherwise
   // derives /gh|/git|/dev from the server's repo identity or opened folder.
@@ -493,7 +557,7 @@ export function Discovery() {
       const match = allServers.find((x) => x.server.peerId === res.peerId);
       if (!match) return;
       resolvedRef.current = true;
-      void connectTo(match.server, match.room, res.folder);
+      void connectTo(match.server, match.room, res.folder, false, dl.type === "repo" ? dl.target : undefined);
       return;
     }
     // No deep link, but a token arrived via the URL: open that room's server
@@ -563,7 +627,7 @@ export function Discovery() {
     const target = findServerForDeepLink(dl);
     if (!target) return; // its server isn't present (yet) — wait for it to appear
     if (activePeerRef.current === target.server.peerId && connStateRef.current === "connected") return;
-    void connectTo(target.server, target.room, target.folder, true);
+    void connectTo(target.server, target.room, target.folder, true, dl.type === "repo" ? dl.target : undefined);
   }
 
   function disconnect() {
@@ -630,6 +694,27 @@ export function Discovery() {
     />
   ));
 
+  // Provisioning view: the daemon's setup.sh is running; stream its log.
+  if (connState === "provisioning") {
+    return (
+      <>
+        {roomClients}
+        <div style={styles.page}>
+          <header style={styles.header}>
+            <span style={styles.brand}>codehost</span>
+            <span style={styles.dim}>·</span>
+            <span style={styles.dim}>provisioning…</span>
+            <span style={{ flex: 1 }} />
+            <button style={styles.connectBtn} onClick={disconnect}>
+              Cancel
+            </button>
+          </header>
+          <pre style={styles.provLog}>{provisionLog || "starting…"}</pre>
+        </div>
+      </>
+    );
+  }
+
   // Connected view: VS Code in an iframe, served over the tunnel.
   if (iframeSrc && connState === "connected") {
     return (
@@ -910,4 +995,5 @@ const styles: Record<string, React.CSSProperties> = {
   echo: { marginTop: 6, fontSize: 12, color: "#4ec9b0", fontFamily: "monospace" },
   connectBtn: { background: "#0e639c", border: "none", color: "#fff", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
   shareBtn: { background: "transparent", border: "1px solid #3d3d3d", color: "#ccc", padding: "6px 14px", borderRadius: 6, cursor: "pointer", fontSize: 13 },
+  provLog: { flex: 1, margin: 0, padding: "14px 18px", overflow: "auto", background: "#1e1e1e", color: "#ccc", fontFamily: "monospace", fontSize: 12.5, lineHeight: 1.5, whiteSpace: "pre-wrap" },
 };