@akanjs/devkit 3.1.1 → 3.1.2-rc.0

package/codeAgent/tools/mcpServerConfig.test.ts

@@ -1,8 +1,19 @@
 import { afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  truncateSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { akanCodePaths } from "../agent/akanCodePaths";
+import { WorkspaceTrust } from "../agent/WorkspaceTrust";
 import { McpServerConfig, type McpServerScope } from "./McpServerConfig";
 
 const roots: string[] = [];
@@ -210,3 +221,121 @@ describe("MCP server config", () => {
     expect(McpServerConfig.targetOf({ name: "a", transport: "http", url: "https://x" })).toBe("https://x");
   });
 });
+
+describe("workspace trust", () => {
+  const extension = (root: string, name: string, body: string) => {
+    const file = path.join(akanCodePaths.extensionsDir(root), name);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, body);
+  };
+
+  afterEach(() => {
+    rmSync(akanCodePaths.trustFile(), { force: true });
+  });
+
+  test("a repo with no servers or extensions of its own needs no approval", () => {
+    const root = workspace();
+    McpServerConfig.add(root, "home", ["https://home.example/mcp"], "global");
+    expect(WorkspaceTrust.pending(root)).toEqual([]);
+    expect(WorkspaceTrust.isTrusted(root, "mcp")).toBe(true);
+  });
+
+  test("the repo's servers and extensions wait for approval, and a remembered one stays approved", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node", args: ["x.js"] } } }));
+    extension(root, "hello.ts", "export default () => {};");
+    expect(WorkspaceTrust.pending(root).map((item) => item.kind)).toEqual(["mcp", "extensions"]);
+    expect(WorkspaceTrust.pending(root)[0]?.lines).toEqual(["tool: node x.js"]);
+    WorkspaceTrust.approve(root, WorkspaceTrust.pending(root), true);
+    expect(WorkspaceTrust.pending(root)).toEqual([]);
+    expect(Object.keys(JSON.parse(readFileSync(akanCodePaths.trustFile(), "utf8")).workspaces)).toHaveLength(1);
+  });
+
+  test.skipIf(process.platform === "win32")("the trust file is readable only by its owner", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node" } } }));
+    WorkspaceTrust.approve(root, WorkspaceTrust.pending(root), true);
+    expect(statSync(akanCodePaths.trustFile()).mode & 0o777).toBe(0o600);
+  });
+
+  test("a change to what was approved is asked about again", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node", args: ["x.js"] } } }));
+    extension(root, "hello.ts", "export default () => {};");
+    WorkspaceTrust.approve(root, WorkspaceTrust.pending(root), true);
+    writeFileSync(
+      McpServerConfig.file(root),
+      JSON.stringify({ mcpServers: { tool: { command: "node", args: ["y.js"] } } }),
+    );
+    extension(root, "nested/more.ts", "export default () => {};");
+    expect(WorkspaceTrust.pending(root).map((item) => item.kind)).toEqual(["mcp", "extensions"]);
+    expect(WorkspaceTrust.isTrusted(root, "mcp")).toBe(false);
+  });
+
+  test("an approval that is not remembered lasts only for this process", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node" } } }));
+    WorkspaceTrust.approve(root, WorkspaceTrust.pending(root), false);
+    expect(WorkspaceTrust.isTrusted(root, "mcp")).toBe(true);
+    expect(existsSync(akanCodePaths.trustFile())).toBe(false);
+  });
+
+  test("an edit made through akan code keeps the approval the content had", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node" } } }));
+    WorkspaceTrust.approve(root, WorkspaceTrust.pending(root), true);
+    WorkspaceTrust.carry(root, "mcp", () =>
+      McpServerConfig.add(root, "more", ["https://more.example/mcp"], "workspace"),
+    );
+    expect(WorkspaceTrust.isTrusted(root, "mcp")).toBe(true);
+    const untrusted = workspace(JSON.stringify({ mcpServers: { tool: { command: "node" } } }));
+    WorkspaceTrust.carry(untrusted, "mcp", () => McpServerConfig.add(untrusted, "more", ["x"], "workspace"));
+    expect(WorkspaceTrust.isTrusted(untrusted, "mcp")).toBe(false);
+  });
+
+  test("a link that stays in the extensions folder is followed and checked", () => {
+    const root = workspace();
+    extension(root, "real/index.ts", "export default () => {};");
+    symlinkSync(
+      path.join(akanCodePaths.extensionsDir(root), "real"),
+      path.join(akanCodePaths.extensionsDir(root), "alias"),
+    );
+    const [item] = WorkspaceTrust.pending(root);
+    expect(item?.lines).toEqual(["alias/index.ts"]);
+    expect(item?.hash).not.toBe("");
+    WorkspaceTrust.approve(root, [item as NonNullable<typeof item>], true);
+    extension(root, "real/index.ts", "export default () => 1;");
+    expect(WorkspaceTrust.isTrusted(root, "extensions")).toBe(false);
+  });
+
+  test("a link out of the extensions folder is not followed, and an approval of that folder is never remembered", () => {
+    const root = workspace();
+    const outside = workspace();
+    writeFileSync(path.join(outside, "secret-notes.ts"), "export default () => {};");
+    extension(root, "hello.ts", "export default () => {};");
+    symlinkSync(outside, path.join(akanCodePaths.extensionsDir(root), "linked"));
+    const [item] = WorkspaceTrust.pending(root);
+    expect(item?.hash).toBe("");
+    expect(item?.lines[0]).toContain("linked links out of the folder");
+    expect(item?.lines.join("\n")).not.toContain("secret-notes");
+    WorkspaceTrust.approve(root, [item as NonNullable<typeof item>], true);
+    expect(existsSync(akanCodePaths.trustFile())).toBe(false);
+  });
+
+  test("an extensions folder past the file or byte cap is not checked, and its approval is never remembered", () => {
+    const many = workspace();
+    const modules = path.join(akanCodePaths.extensionsDir(many), "node_modules", "dep");
+    mkdirSync(modules, { recursive: true });
+    for (let index = 0; index <= 10_000; index++) writeFileSync(path.join(modules, `f${index}.js`), "");
+    const large = workspace();
+    extension(large, "big.js", "");
+    truncateSync(path.join(akanCodePaths.extensionsDir(large), "big.js"), 64 * 1024 * 1024 + 1);
+    for (const root of [many, large]) {
+      const [item] = WorkspaceTrust.pending(root);
+      expect(item?.hash).toBe("");
+      expect(item?.lines[0]).toContain("too many to check");
+      WorkspaceTrust.approve(root, [item as NonNullable<typeof item>], true);
+    }
+    expect(existsSync(akanCodePaths.trustFile())).toBe(false);
+  });
+
+  test("a disabled server needs no approval", () => {
+    const root = workspace(JSON.stringify({ mcpServers: { tool: { command: "node", disabled: true } } }));
+    expect(WorkspaceTrust.pending(root)).toEqual([]);
+  });
+});

package/commandDecorators/command.ts

@@ -436,7 +436,10 @@ export const runCommands = async (...commands: CommandCls[]) => {
           reportFailure = async (failure) =>
             await onFailure?.(failure, { usage: false, given: givenOptionsOf(allArgMetas, opt) });
           const commandArgs = [] as unknown[];
-          if (targetMeta.targetOption.runsOnWorkspaceRoot) await assertCurrentDirectoryIsWorkspaceRoot();
+          if (targetMeta.targetOption.runsOnWorkspaceRoot) {
+            await assertCurrentDirectoryIsWorkspaceRoot();
+            WorkspaceExecutor.defaultCloneToLocalEnv(process.cwd());
+          }
           const workspace = WorkspaceExecutor.fromRoot();
           const commandContext: CommandContext = { values: {} };
           for (const argMeta of allArgMetas) {

package/createTunnel.test.ts

@@ -1,8 +1,76 @@
-import { describe, expect, spyOn, test } from "bun:test";
-import { Client } from "ssh2";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import type { AddressInfo } from "node:net";
+import path from "node:path";
+import { Client, type Connection, Server, utils } from "ssh2";
 import { createTunnel } from "./createTunnel";
+import { SshHostKeys } from "./sshHostKeys";
 import { createTempApp, isolateEnv, tempRoots } from "./testHelpers";
 
+const freePort = () => {
+  const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+  const { port } = listener;
+  listener.stop(true);
+  return port;
+};
+
+const publicBlobOf = (publicKey: string) => {
+  const parsed = utils.parseKey(publicKey);
+  if (parsed instanceof Error) throw parsed;
+  return parsed.getPublicSSH();
+};
+
+const sshServers: { server: Server; clients: Set<Connection> }[] = [];
+
+const startSshServer = async () => {
+  const hostKey = utils.generateKeyPairSync("ed25519");
+  const methods: string[] = [];
+  const clients = new Set<Connection>();
+  const server = new Server({ hostKeys: [hostKey.private] }, (client) => {
+    clients.add(client);
+    client.on("error", () => clients.delete(client));
+    client.on("authentication", (context) => {
+      methods.push(context.method);
+      if (context.method === "password" || context.method === "publickey") context.accept();
+      else context.reject(["publickey", "password"]);
+    });
+    client.on("ready", () => {
+      client.on("tcpip", (accept) => {
+        const channel = accept();
+        channel.on("data", (chunk: Buffer) => channel.write(chunk));
+      });
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()));
+  sshServers.push({ server, clients });
+  const { port } = server.address() as AddressInfo;
+  return { port, methods, fingerprint: SshHostKeys.fingerprintOf(publicBlobOf(hostKey.public)) };
+};
+
+const echoThrough = async (port: number) =>
+  await new Promise<string>((resolve, reject) => {
+    void Bun.connect({
+      hostname: "127.0.0.1",
+      port,
+      socket: {
+        open: (socket) => void socket.write("ping"),
+        data: (socket, chunk) => {
+          resolve(Buffer.from(chunk).toString());
+          socket.end();
+        },
+        error: (_socket, error) => reject(error),
+        connectError: (_socket, error) => reject(error),
+      },
+    });
+  });
+
+afterEach(() => {
+  for (const { server, clients } of sshServers.splice(0)) {
+    for (const client of clients) client.end();
+    server.close();
+  }
+});
+
 describe("createTunnel", () => {
   isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "testing" });
   const track = tempRoots();
@@ -62,4 +130,134 @@ describe("createTunnel", () => {
       connect.mockRestore();
     }
   });
+
+  test("forwards on loopback, signs in with the configured key and keeps the host key it first sees", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const keyPath = path.join(root, "id_tunnel");
+    await writeFile(keyPath, utils.generateKeyPairSync("ed25519").private);
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PRIVATE_KEY_PATH: keyPath,
+    });
+    const localPort = freePort();
+    const listen = spyOn(Bun, "listen");
+    try {
+      expect(await createTunnel("redis", { app, environment: "testing", port: localPort })).toBe(
+        `localhost:${localPort}`,
+      );
+      expect(listen.mock.calls[0]?.[0]).toMatchObject({ hostname: "127.0.0.1", port: localPort });
+    } finally {
+      listen.mockRestore();
+    }
+
+    expect(await echoThrough(localPort)).toBe("ping");
+    expect(ssh.methods).toContain("publickey");
+    expect(ssh.methods).not.toContain("password");
+    expect(JSON.parse(await readFile(knownHosts, "utf8"))).toEqual({ [`localhost:${ssh.port}`]: ssh.fingerprint });
+    if (process.platform !== "win32") expect((await stat(knownHosts)).mode & 0o777).toBe(0o600);
+  });
+
+  test("refuses a host whose key differs from the kept or the pinned one", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const other = `SHA256:${Buffer.alloc(32, 1).toString("base64").replace(/=+$/, "")}`;
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PASSWORD: "test-password",
+    });
+    const open = async () => await createTunnel("redis", { app, environment: "testing", port: freePort() });
+
+    await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: other }));
+    await expect(open()).rejects.toThrow(`differs from the one ${knownHosts} keeps`);
+    expect(JSON.parse(await readFile(knownHosts, "utf8"))).toEqual({ [`localhost:${ssh.port}`]: other });
+
+    process.env.SSH_TUNNEL_HOST_FINGERPRINT = other;
+    await expect(open()).rejects.toThrow("is not one SSH_TUNNEL_HOST_FINGERPRINT pins");
+    process.env.SSH_TUNNEL_HOST_FINGERPRINT = ssh.fingerprint;
+    await expect(open()).resolves.toStartWith("localhost:");
+    expect(ssh.methods.filter((method) => method !== "none")).toEqual(["password"]);
+  });
+
+  test("warns when it signs in with the default shared credential", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: path.join(root, "known_hosts.json"),
+    });
+    //? `akan test` runs from the workspace root, whose dotenv may name a password; this case is the one with none.
+    delete process.env.SSH_TUNNEL_PASSWORD;
+    delete process.env.SSH_TUNNEL_PRIVATE_KEY_PATH;
+    const warn = spyOn(app.logger, "warn");
+
+    await createTunnel("redis", { app, environment: "testing", port: freePort() });
+
+    expect(warn.mock.calls.map(([message]) => String(message)).join("\n")).toContain(
+      "uses the default shared credential",
+    );
+  });
+
+  test("listens where SSH_TUNNEL_BIND_HOST says and warns when that is not loopback", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: path.join(root, "known_hosts.json"),
+      SSH_TUNNEL_PASSWORD: "test-password",
+      SSH_TUNNEL_BIND_HOST: "0.0.0.0",
+    });
+    const warn = spyOn(app.logger, "warn");
+    const localPort = freePort();
+    const listen = spyOn(Bun, "listen");
+    try {
+      await createTunnel("redis", { app, environment: "testing", port: localPort });
+      expect(listen.mock.calls[0]?.[0]).toMatchObject({ hostname: "0.0.0.0", port: localPort });
+    } finally {
+      listen.mockRestore();
+    }
+
+    expect(warn.mock.calls.map(([message]) => String(message)).join("\n")).toContain(
+      "The redis tunnel listens on 0.0.0.0 (SSH_TUNNEL_BIND_HOST)",
+    );
+  });
+
+  test("takes no host check or listener the repo's dotenv file names, and says it ignored them", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const ssh = await startSshServer();
+    const knownHosts = path.join(root, "known_hosts.json");
+    const other = `SHA256:${Buffer.alloc(32, 1).toString("base64").replace(/=+$/, "")}`;
+    await writeFile(path.join(root, ".env"), "SSH_TUNNEL_HOST_FINGERPRINT=*\nexport SSH_TUNNEL_BIND_HOST=0.0.0.0\n");
+    Object.assign(process.env, {
+      SSH_TUNNEL_PORT: String(ssh.port),
+      SSH_TUNNEL_KNOWN_HOSTS: knownHosts,
+      SSH_TUNNEL_PASSWORD: "test-password",
+      SSH_TUNNEL_HOST_FINGERPRINT: "*",
+      SSH_TUNNEL_BIND_HOST: "0.0.0.0",
+    });
+    const warn = spyOn(app.logger, "warn");
+    const listen = spyOn(Bun, "listen");
+    const cwd = process.cwd();
+    process.chdir(root);
+    try {
+      const open = async () => await createTunnel("redis", { app, environment: "testing", port: freePort() });
+      await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: other }));
+      await expect(open()).rejects.toThrow(`differs from the one ${knownHosts} keeps`);
+      await writeFile(knownHosts, JSON.stringify({ [`localhost:${ssh.port}`]: ssh.fingerprint }));
+      await expect(open()).resolves.toStartWith("localhost:");
+      expect(listen.mock.calls.at(-1)?.[0]).toMatchObject({ hostname: "127.0.0.1" });
+    } finally {
+      process.chdir(cwd);
+      listen.mockRestore();
+    }
+
+    const warnings = warn.mock.calls.map(([message]) => String(message)).join("\n");
+    expect(warnings).toContain("SSH_TUNNEL_HOST_FINGERPRINT is set in .env, which the repository controls");
+    expect(warnings).toContain("SSH_TUNNEL_BIND_HOST is set in .env");
+    expect(warnings).not.toContain("accepts any host key");
+  });
 });

package/createTunnel.ts

@@ -1,36 +1,110 @@
+import { readFileSync } from "node:fs";
+import type { ConnectConfig } from "ssh2";
 import { type AppExecutor, WorkspaceExecutor } from "./executors";
+import { ShellOnlyEnv } from "./shellOnlyEnv";
+import { SshHostKeys } from "./sshHostKeys";
 import { createSshTunnel } from "./sshTunnel";
 
+//? Loosening the host check or the listener, or picking a key, is the person's call; a repo's dotenv cannot set it.
+const tunnelEnv = new ShellOnlyEnv([
+  "SSH_TUNNEL_PRIVATE_KEY_PATH",
+  "SSH_TUNNEL_PASSPHRASE",
+  "SSH_TUNNEL_HOST_FINGERPRINT",
+  "SSH_TUNNEL_KNOWN_HOSTS",
+  "SSH_TUNNEL_BIND_HOST",
+]);
+
 interface TunnelOption {
   app: AppExecutor;
   environment: string;
   port?: number;
 }
+
+const tunnelAuth = (
+  app: AppExecutor,
+  repoName: string,
+): Pick<ConnectConfig, "privateKey" | "passphrase" | "password"> => {
+  const keyPath = tunnelEnv.get("SSH_TUNNEL_PRIVATE_KEY_PATH");
+  const passphrase = tunnelEnv.get("SSH_TUNNEL_PASSPHRASE");
+  if (keyPath) return { privateKey: readFileSync(keyPath), ...(passphrase ? { passphrase } : {}) };
+  if (process.env.SSH_TUNNEL_PASSWORD) return { password: process.env.SSH_TUNNEL_PASSWORD };
+  app.logger.warn(
+    "The SSH tunnel uses the default shared credential. " +
+      "Set SSH_TUNNEL_PRIVATE_KEY_PATH to a key (or SSH_TUNNEL_PASSWORD) once the cluster's tunnel endpoint accepts it.",
+  );
+  return { password: repoName };
+};
+
+const tunnelHostVerifier = (app: AppExecutor, hostId: string, onRefusal: (reason: string) => void) => {
+  const pinned = SshHostKeys.parsePinned(tunnelEnv.get("SSH_TUNNEL_HOST_FINGERPRINT"));
+  const hostKeys = new SshHostKeys(tunnelEnv.get("SSH_TUNNEL_KNOWN_HOSTS") || undefined);
+  return (key: Buffer, verify: (valid: boolean) => void) => {
+    if (pinned.includes("SHA256:*")) {
+      app.logger.warn(`SSH_TUNNEL_HOST_FINGERPRINT=* accepts any host key ${hostId} shows.`);
+      verify(true);
+      return;
+    }
+    hostKeys.verify(hostId, key, pinned).then(
+      ({ trusted, firstUse, fingerprint }) => {
+        if (firstUse)
+          app.logger.warn(
+            `Trusting the SSH host key ${fingerprint} of ${hostId} on first use; kept in ${hostKeys.filePath}.`,
+          );
+        if (!trusted)
+          onRefusal(
+            pinned.length
+              ? `the host key ${fingerprint} of ${hostId} is not one SSH_TUNNEL_HOST_FINGERPRINT pins`
+              : `the host key ${fingerprint} of ${hostId} differs from the one ${hostKeys.filePath} keeps; if the host was rebuilt, remove its entry or pin the new key with SSH_TUNNEL_HOST_FINGERPRINT`,
+          );
+        verify(trusted);
+      },
+      (error: unknown) => {
+        onRefusal(
+          `the host key store ${hostKeys.filePath} could not be read (${error instanceof Error ? error.message : String(error)})`,
+        );
+        verify(false);
+      },
+    );
+  };
+};
+
 export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
   const baseDevEnv = WorkspaceExecutor.getBaseDevEnv();
   WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, `The ${service} tunnel`);
+  for (const line of tunnelEnv.ignored()) app.logger.warn(line);
   const { serveDomain, repoName } = baseDevEnv;
   const host = `${app.name}-${environment}.${serveDomain}`;
+  //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
+  const sshHost = host.endsWith(".localhost") ? "localhost" : host;
   const sshPort = process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767;
   const dstHost = `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`;
   const dstPort = service === "postgres" ? 5432 : 6379;
+  //? The forward reaches a cluster database, so it listens on loopback unless SSH_TUNNEL_BIND_HOST widens it.
+  const bindHost = tunnelEnv.get("SSH_TUNNEL_BIND_HOST") || "127.0.0.1";
+  if (!["127.0.0.1", "localhost", "::1"].includes(bindHost))
+    app.logger.warn(
+      `The ${service} tunnel listens on ${bindHost} (SSH_TUNNEL_BIND_HOST), so other machines that reach it reach ${dstHost}.`,
+    );
+  let refusal: string | null = null;
   try {
     await createSshTunnel({
-      localHost: "0.0.0.0",
+      localHost: bindHost,
       localPort: port,
-      srcHost: "0.0.0.0",
+      srcHost: "127.0.0.1",
       srcPort: port,
       dstHost,
       dstPort,
       sshOptions: {
-        //? RFC 6761 makes *.localhost loopback, but only macOS resolves it; glibc without systemd-resolved and Windows answer ENOTFOUND
-        host: host.endsWith(".localhost") ? "localhost" : host,
+        host: sshHost,
         port: sshPort,
         username: process.env.SSH_TUNNEL_USERNAME ?? "root",
-        password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
+        ...tunnelAuth(app, repoName),
+        hostVerifier: tunnelHostVerifier(app, `${sshHost}:${sshPort}`, (reason) => {
+          refusal = reason;
+        }),
       },
     });
   } catch (error) {
@@ -41,7 +115,7 @@ export const createTunnel = async (
           ? error.message
           : String(error);
     throw new Error(
-      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${reasons})`,
+      `Could not open the ${service} tunnel for ${app.name}-${environment}: SSH ${host}:${sshPort} -> ${dstHost}:${dstPort} failed (${refusal ?? reasons})`,
       { cause: error },
     );
   }

package/envSeed.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { EnvSeed } from "./envSeed";
+import { tempDirs, writeText } from "./testHelpers";
+
+const makeEnvDir = tempDirs("akan-env-seed-");
+const templates = path.resolve(import.meta.dir, "../cli/templates");
+const template = async (file: string) => await readFile(path.join(templates, file), "utf8");
+
+const selector = (side: "server" | "client", names: string[]) =>
+  `${names.map((name) => `import { env as ${name} } from "./env.${side}.${name}";`).join("\n")}\n\nexport const env = { ${names.join(", ")} };\n`;
+
+const seededIn = async (envDir: string) =>
+  Object.fromEntries((await new EnvSeed(envDir).missing()).map(({ fileName, content }) => [fileName, content]));
+
+describe("EnvSeed", () => {
+  test("names each environment file the selectors import and the testing one, of those missing", async () => {
+    const envDir = await makeEnvDir();
+    await writeText(path.join(envDir, "env.server.ts"), selector("server", ["debug", "local"]));
+    await writeText(path.join(envDir, "env.client.ts"), selector("client", ["local", "staging"]));
+    await writeText(path.join(envDir, "env.server.debug.ts"), "export const env = { kept: true };\n");
+
+    expect(Object.keys(await seededIn(envDir))).toEqual([
+      "env.client.local.ts",
+      "env.client.staging.ts",
+      "env.server.local.ts",
+      "env.server.testing.ts",
+    ]);
+  });
+
+  test("passes over the generated type, the tracked example and a build profile", async () => {
+    const envDir = await makeEnvDir();
+    await writeText(
+      path.join(envDir, "env.server.ts"),
+      [
+        'import { libEnv } from "./env.server.type";',
+        'import { env as example } from "./env.server.example";',
+        'import { env as desktop } from "./env.server.debug.desktop";',
+        "",
+        "export const env = { ...libEnv, ...example, ...desktop };",
+        "",
+      ].join("\n"),
+    );
+
+    expect(Object.keys(await seededIn(envDir))).toEqual(["env.server.testing.ts"]);
+  });
+
+  test("writes what the app scaffold writes when the folder has no example", async () => {
+    const envDir = await makeEnvDir();
+    await writeText(path.join(envDir, "env.server.ts"), selector("server", ["local", "testing"]));
+    await writeText(path.join(envDir, "env.client.ts"), selector("client", ["local"]));
+    await writeText(path.join(envDir, "env.client.type.ts"), "export type AppClientEnv = Record<never, never>;\n");
+
+    expect(await seededIn(envDir)).toEqual({
+      "env.client.local.ts": await template("app/env/env.client.local.ts.template"),
+      "env.server.local.ts": await template("app/env/env.server.local.ts.template"),
+      "env.server.testing.ts": await template("app/env/env.server.testing.ts.template"),
+    });
+  });
+
+  test("copies the side's tracked example into each of its files", async () => {
+    const envDir = await makeEnvDir();
+    const example =
+      'import type { ModulesOptions } from "../lib/option";\n\nexport const env: ModulesOptions = { port: 1 };\n';
+    await writeText(path.join(envDir, "env.server.ts"), selector("server", ["local"]));
+    await writeText(path.join(envDir, "env.server.example.ts"), example);
+
+    expect(await seededIn(envDir)).toEqual({ "env.server.local.ts": example, "env.server.testing.ts": example });
+  });
+
+  test("leaves a client env untyped when the folder has no env.client.type.ts to type it", async () => {
+    const envDir = await makeEnvDir();
+    await writeText(path.join(envDir, "env.client.ts"), selector("client", ["local"]));
+
+    expect((await seededIn(envDir))["env.client.local.ts"]).toBe("export const env = {};\n");
+  });
+
+  test("gives a lib its testing env from the example the lib scaffold tracks", async () => {
+    const envDir = await makeEnvDir();
+    await writeText(
+      path.join(envDir, "env.server.example.ts"),
+      await template("libRoot/env/env.server.example.ts.template"),
+    );
+
+    expect(await seededIn(envDir)).toEqual({
+      "env.server.testing.ts": await template("libRoot/env/env.server.testing.ts.template"),
+    });
+  });
+});

package/envSeed.ts

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { FileSys } from "./fileSys";
+
+export interface EnvSeedFile {
+  fileName: string;
+  content: string;
+}
+
+//? These files are gitignored for the secrets they hold, so a fresh clone has none of them.
+export class EnvSeed {
+  static readonly #server = `import type { ModulesOptions } from "../lib/option";
+
+export const env: ModulesOptions = {};
+`;
+  static readonly #testingServer = `import type { ModulesOptions } from "../lib/option";
+import { libEnv } from "./env.server.type";
+
+export const env: ModulesOptions = {
+  ...libEnv,
+};
+`;
+  static readonly #client = `import type { AppClientEnv } from "./env.client.type";
+
+export const env: AppClientEnv = {};
+`;
+  static readonly #untypedClient = "export const env = {};\n";
+  static readonly #selectors = ["env.server.ts", "env.client.ts"];
+  //? `type` is generated and `example` tracked; a dotted name (`debug.desktop`) is a build profile no selector imports.
+  static readonly #selectedPattern = /^\.\/(env\.(?:server|client)\.(?!(?:type|example)$)[\w-]+)$/;
+  //? A lib's server.ts and the signal test runtime import it by name, whatever the selector imports.
+  static readonly #testing = "env.server.testing.ts";
+
+  readonly #envDir: string;
+  constructor(envDir: string) {
+    this.#envDir = envDir;
+  }
+
+  async missing(): Promise<EnvSeedFile[]> {
+    const wanted = [...new Set([EnvSeed.#testing, ...(await this.#selected())])].sort();
+    const exists = await Promise.all(wanted.map((fileName) => FileSys.fileExists(path.join(this.#envDir, fileName))));
+    const missing = wanted.filter((_, idx) => !exists[idx]);
+    return await Promise.all(missing.map(async (fileName) => ({ fileName, content: await this.#contentOf(fileName) })));
+  }
+
+  async #selected() {
+    const transpiler = new Bun.Transpiler({ loader: "ts" });
+    const selected = await Promise.all(
+      EnvSeed.#selectors.map(async (selector) => {
+        const file = path.join(this.#envDir, selector);
+        if (!(await FileSys.fileExists(file))) return [];
+        return transpiler
+          .scan(await FileSys.readText(file))
+          .imports.flatMap(({ path: specifier }) => specifier.match(EnvSeed.#selectedPattern)?.[1] ?? [])
+          .map((name) => `${name}.ts`);
+      }),
+    );
+    return selected.flat();
+  }
+
+  async #contentOf(fileName: string) {
+    const side = fileName.startsWith("env.client.") ? "client" : "server";
+    const example = path.join(this.#envDir, `env.${side}.example.ts`);
+    if (await FileSys.fileExists(example)) return await FileSys.readText(example);
+    if (side === "server") return fileName === EnvSeed.#testing ? EnvSeed.#testingServer : EnvSeed.#server;
+    const typed = await FileSys.fileExists(path.join(this.#envDir, "env.client.type.ts"));
+    return typed ? EnvSeed.#client : EnvSeed.#untypedClient;
+  }
+}