planche 0.1.0 → 0.2.0

package/README.md

@@ -39,8 +39,6 @@ npx planche [options]
   -p, --port <n>       Port to listen on (default: 8888)
       --addr <host>    Address to bind (default: 127.0.0.1)
       --token <str>    Auth token (default: random on each start)
-      --app <url>      Web app to open (default: https://planche.dev)
-      --origin <url>   Extra browser origin allowed to use the agent (repeatable)
       --no-open        Print the pairing link without opening a browser
       --verbose        Log every request
   -h, --help           Show help
@@ -53,10 +51,9 @@ Every option can also be set through an environment variable:
 | `PLANCHE_PORT`            | `--port`   |                                                     |
 | `PLANCHE_ADDR`            | `--addr`   |                                                     |
 | `PLANCHE_AUTH_TOKEN`      | `--token`  | Fixed token; the pairing link stays valid across restarts |
-| `PLANCHE_APP_URL`         | `--app`    | Use a self-hosted build of the app                  |
-| `PLANCHE_ALLOWED_ORIGINS` | `--origin` | Comma-separated list                                |
 | `PLANCHE_BODY_LIMIT`      |            | Max request body, default `50mb` (large SQL scripts) |
 | `PLANCHE_SQLITE_DIR`      |            | Only SQLite files inside this directory may be opened |
+| `PLANCHE_SSH_CONFIG`      | `~/.ssh/config` | SSH client config used to resolve jump-host aliases; `none` disables reading it and `~/.ssh/id_*` |
 
 ### Examples
 
@@ -72,12 +69,6 @@ Run on another port and print the link only:
 npx planche --port 9000 --no-open
 ```
 
-Use with the app served from your own host:
-
-```bash
-npx planche --app https://planche.example.com
-```
-
 Restrict SQLite access to one folder:
 
 ```bash
@@ -99,19 +90,35 @@ database connections open and forwards queries with the matching driver
 - **SQLite** — opens a file on your disk by path. Set `PLANCHE_SQLITE_DIR` to
   limit which files can be opened. (Small SQLite files can also be opened
   directly in the browser without the agent.)
+- **SSH tunnel** — MySQL and PostgreSQL profiles can go through an SSH jump
+  host (password, private key, or the local `ssh-agent`). The agent opens the
+  tunnel with `ssh2` on a loopback port and points the driver at it. The host
+  may be a `Host` alias from `~/.ssh/config`: `HostName`, `Port`, `User` and
+  `IdentityFile` are applied like the `ssh` command does (`ProxyJump` is not
+  supported), and with no key given `~/.ssh/id_*` are tried. Unknown
+  host keys are trusted on first use and recorded in `~/.planche/known_hosts`
+  (entries in `~/.ssh/known_hosts` are honoured too); a changed key refuses the
+  connection until the stale entry is removed.
 
 ## Security
 
 - Every request except `GET /health` requires the bearer token.
-- Browser requests are accepted only from the Planche app origin and local
-  dev servers. Any other `Origin` is refused with `403`, even with a valid
-  token. Add your own with `--origin`.
+- Browser requests are accepted only from the Planche app origin
+  (`https://planche.dev`). Any other `Origin` is refused with `403`, even
+  with a valid token.
 - The agent binds to `127.0.0.1` by default, so only the browser on the same
   machine can reach it. Binding to another address (`--addr 0.0.0.0`) exposes
   your databases to the network — only do that behind a tunnel or firewall you
   trust.
 - The agent never stores credentials. They are passed per connection by the
-  app and live in memory only while the connection is open.
+  app (including SSH passwords and private key contents) and live in memory
+  only while the connection is open. The only thing written to disk is the
+  SSH host key list in `~/.planche/known_hosts`.
+- For SSH tunnels the agent reads `~/.ssh/config` and, when the profile has no
+  key, the `IdentityFile` it names or `~/.ssh/id_*` — exactly what the `ssh`
+  command would do, and the key never leaves the agent. Set
+  `PLANCHE_SSH_CONFIG=none` if you would rather the agent only used what the
+  app sends.
 
 ## Troubleshooting
 
@@ -120,8 +127,8 @@ database connections open and forwards queries with the matching driver
   browser extensions that block `localhost` requests can also cause this.
 - **"Agent restarted, re-pair"** — the agent generated a new token. Open the
   new link it printed, or start it with a fixed `--token`.
-- **`403 Forbidden`** — the request came from an origin that is not
-  allow-listed. Pass `--origin https://your-app-host`.
+- **`403 Forbidden`** — the request did not come from `https://planche.dev`.
+  Open the app from the pairing link the agent printed.
 - **Wrong Node version** — the SQLite driver ships prebuilt binaries for
   Node 22+. Check with `node -v`, or run with `npx -p node@22 planche`.
 

package/dist/index.js

@@ -466,6 +466,347 @@ var sqliteDriverFactory = {
   }
 };
 
+// src/ssh-tunnel.ts
+import { createServer } from "net";
+import { mkdir, readFile as readFile2, appendFile } from "fs/promises";
+import { createHash } from "crypto";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { Client } from "ssh2";
+
+// src/ssh-config.ts
+import { readFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, isAbsolute as isAbsolute2, join } from "path";
+var SSH_CONFIG_DISABLED = process.env.PLANCHE_SSH_CONFIG === "none";
+var DEFAULT_SSH_CONFIG = SSH_CONFIG_DISABLED ? "" : process.env.PLANCHE_SSH_CONFIG || join(homedir(), ".ssh", "config");
+var DEFAULT_IDENTITY_FILES = ["id_ed25519", "id_ecdsa", "id_rsa", "id_ed25519_sk", "id_ecdsa_sk"].map(
+  (f) => join(homedir(), ".ssh", f)
+);
+function expandHome(path) {
+  return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+}
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function hostPatternMatches(patterns, host) {
+  let matched = false;
+  for (const raw of patterns) {
+    const negated = raw.startsWith("!");
+    const pattern = negated ? raw.slice(1) : raw;
+    if (!globToRegExp(pattern).test(host)) continue;
+    if (negated) return false;
+    matched = true;
+  }
+  return matched;
+}
+function tokenize(line) {
+  const tokens = [];
+  const re = /"([^"]*)"|(\S+)/g;
+  let m;
+  while (m = re.exec(line)) tokens.push(m[1] ?? m[2]);
+  return tokens;
+}
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return void 0;
+  const eq = trimmed.match(/^([A-Za-z]+)\s*=\s*(.*)$/);
+  const [keyword, rest] = eq ? [eq[1], eq[2]] : [trimmed.split(/\s+/, 1)[0], trimmed.slice(trimmed.split(/\s+/, 1)[0].length)];
+  return { keyword: keyword.toLowerCase(), args: tokenize(rest) };
+}
+async function loadLines(file, seen) {
+  if (seen.has(file)) return [];
+  seen.add(file);
+  try {
+    return (await readFile(file, "utf8")).split(/\r?\n/);
+  } catch {
+    return [];
+  }
+}
+async function resolveSshHost(host, file = DEFAULT_SSH_CONFIG) {
+  const result = { identityFiles: [] };
+  if (!file) return result;
+  const seen = /* @__PURE__ */ new Set();
+  async function walk(path, active) {
+    let blockActive = active;
+    for (const line of await loadLines(path, seen)) {
+      const d = parseLine(line);
+      if (!d) continue;
+      switch (d.keyword) {
+        case "host":
+          blockActive = hostPatternMatches(d.args, host);
+          continue;
+        case "match":
+          blockActive = d.args.length === 1 && d.args[0].toLowerCase() === "all";
+          continue;
+        case "include":
+          for (const inc of d.args) {
+            const target = expandHome(inc);
+            await walk(isAbsolute2(target) ? target : join(dirname(file), target), blockActive);
+          }
+          continue;
+      }
+      if (!blockActive) continue;
+      const value = d.args[0];
+      if (value === void 0) continue;
+      switch (d.keyword) {
+        case "hostname":
+          result.hostName ??= value.replace(/%h/g, host);
+          break;
+        case "port":
+          result.port ??= Number(value) || void 0;
+          break;
+        case "user":
+          result.user ??= value;
+          break;
+        case "identityfile":
+          for (const f of d.args) result.identityFiles.push(expandHome(f.replace(/%d/g, homedir()).replace(/%h/g, host)));
+          break;
+        case "identityagent":
+          result.identityAgent ??= value === "none" ? void 0 : expandHome(value.replace(/%d/g, homedir()));
+          break;
+        case "proxyjump":
+          result.proxyJump ??= value;
+          break;
+      }
+    }
+  }
+  await walk(file, true);
+  return result;
+}
+
+// src/ssh-tunnel.ts
+var TunnelError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "TunnelError";
+  }
+  status;
+};
+var CONNECT_TIMEOUT_MS = 2e4;
+var PLANCHE_DIR = join2(homedir2(), ".planche");
+var PLANCHE_KNOWN_HOSTS = join2(PLANCHE_DIR, "known_hosts");
+var OPENSSH_KNOWN_HOSTS = join2(homedir2(), ".ssh", "known_hosts");
+function parseSshConfig(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "object") throw new TunnelError("ssh must be an object", 400);
+  const body = value;
+  const host = typeof body.host === "string" ? body.host.trim() : "";
+  const user = typeof body.user === "string" ? body.user.trim() : "";
+  const auth = body.auth;
+  if (!host) throw new TunnelError("ssh.host is required", 400);
+  if (auth !== "password" && auth !== "key" && auth !== "agent") {
+    throw new TunnelError("ssh.auth must be one of password, key, agent", 400);
+  }
+  const str = (v) => typeof v === "string" && v ? v : void 0;
+  const config = {
+    host,
+    port: Number(body.port) || 22,
+    user,
+    auth,
+    password: auth === "password" ? str(body.password) ?? "" : void 0,
+    privateKey: auth === "key" ? str(body.privateKey) : void 0,
+    passphrase: auth === "key" ? str(body.passphrase) : void 0
+  };
+  return config;
+}
+function keyType(blob) {
+  const len = blob.readUInt32BE(0);
+  return blob.subarray(4, 4 + len).toString("ascii");
+}
+function hostPatterns(host, port) {
+  const h = host.toLowerCase();
+  return port === 22 ? [h, `[${h}]:22`] : [`[${h}]:${port}`];
+}
+async function readKnownHosts(file) {
+  try {
+    return (await readFile2(file, "utf8")).split(/\r?\n/);
+  } catch {
+    return [];
+  }
+}
+async function lookupHostKey(host, port, blob) {
+  const patterns = hostPatterns(host, port);
+  const type = keyType(blob);
+  const encoded = blob.toString("base64");
+  let sawType = false;
+  const lines = [...await readKnownHosts(OPENSSH_KNOWN_HOSTS), ...await readKnownHosts(PLANCHE_KNOWN_HOSTS)];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("@") || line.startsWith("|")) continue;
+    const [hosts, lineType, lineKey] = line.split(/\s+/);
+    if (!hosts || !lineType || !lineKey) continue;
+    if (!hosts.toLowerCase().split(",").some((h) => patterns.includes(h))) continue;
+    if (lineType !== type) continue;
+    if (lineKey === encoded) return "match";
+    sawType = true;
+  }
+  return sawType ? "mismatch" : "unknown";
+}
+async function rememberHostKey(host, port, blob) {
+  await mkdir(PLANCHE_DIR, { recursive: true, mode: 448 });
+  const name = port === 22 ? host.toLowerCase() : `[${host.toLowerCase()}]:${port}`;
+  await appendFile(PLANCHE_KNOWN_HOSTS, `${name} ${keyType(blob)} ${blob.toString("base64")}
+`, { mode: 384 });
+}
+function fingerprint(blob) {
+  return "SHA256:" + createHash("sha256").update(blob).digest("base64").replace(/=+$/, "");
+}
+async function resolveConfig(ssh) {
+  const cfg = await resolveSshHost(ssh.host);
+  if (cfg.proxyJump) {
+    throw new TunnelError(`ProxyJump (${cfg.proxyJump}) configured for ${ssh.host} in ~/.ssh/config is not supported`, 400);
+  }
+  const resolved = {
+    ...ssh,
+    host: cfg.hostName ?? ssh.host,
+    port: ssh.port === 22 && cfg.port ? cfg.port : ssh.port,
+    user: ssh.user || cfg.user || ""
+  };
+  if (!resolved.user) {
+    throw new TunnelError(
+      SSH_CONFIG_DISABLED ? "ssh.user is required" : `ssh.user is required (no User for ${ssh.host} in ~/.ssh/config)`,
+      400
+    );
+  }
+  if (resolved.auth === "key" && !resolved.privateKey) {
+    if (SSH_CONFIG_DISABLED) {
+      throw new TunnelError("ssh.privateKey is required (the agent runs with PLANCHE_SSH_CONFIG=none)", 400);
+    }
+    const candidates = cfg.identityFiles.length ? cfg.identityFiles : DEFAULT_IDENTITY_FILES;
+    for (const file of candidates) {
+      try {
+        resolved.privateKey = await readFile2(file, "utf8");
+        console.log(`[ssh] Using identity file ${file} for ${ssh.host}`);
+        break;
+      } catch {
+      }
+    }
+    if (!resolved.privateKey) {
+      throw new TunnelError(
+        `No private key given and none readable for ${ssh.host} (tried ${candidates.join(", ")})`,
+        400
+      );
+    }
+  }
+  if (resolved.auth === "agent" && cfg.identityAgent && !process.env.SSH_AUTH_SOCK) {
+    process.env.SSH_AUTH_SOCK = cfg.identityAgent;
+  }
+  return resolved;
+}
+function toConnectConfig(ssh) {
+  const base = {
+    host: ssh.host,
+    port: ssh.port,
+    username: ssh.user,
+    readyTimeout: CONNECT_TIMEOUT_MS,
+    keepaliveInterval: 3e4
+  };
+  switch (ssh.auth) {
+    case "password":
+      return { ...base, password: ssh.password ?? "", tryKeyboard: true };
+    case "key":
+      return { ...base, privateKey: ssh.privateKey, passphrase: ssh.passphrase };
+    case "agent": {
+      const agent = process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "pageant" : void 0);
+      if (!agent) throw new TunnelError("No ssh-agent found (SSH_AUTH_SOCK is not set)", 400);
+      return { ...base, agent };
+    }
+  }
+}
+function describeSshError(err, ssh) {
+  const target = `${ssh.user}@${ssh.host}:${ssh.port}`;
+  if (err instanceof TunnelError) return err;
+  switch (err.level) {
+    case "client-authentication":
+      return new TunnelError(`SSH authentication failed for ${target}`, 401);
+    case "client-timeout":
+      return new TunnelError(`SSH connection to ${target} timed out`, 400);
+    default:
+      return new TunnelError(`SSH connection to ${target} failed: ${err.message}`, 400);
+  }
+}
+async function openSshTunnel(requested, target) {
+  const ssh = await resolveConfig(requested);
+  const client = new Client();
+  const connectConfig = toConnectConfig(ssh);
+  let verifyError;
+  connectConfig.hostVerifier = (key, verified) => {
+    void lookupHostKey(ssh.host, ssh.port, key).then(async (result) => {
+      if (result === "mismatch") {
+        verifyError = new TunnelError(
+          `Host key for ${ssh.host}:${ssh.port} has changed (${fingerprint(key)}). Remove the old entry from ~/.ssh/known_hosts or ${PLANCHE_KNOWN_HOSTS} if this is expected.`,
+          400
+        );
+        verified(false);
+        return;
+      }
+      if (result === "unknown") {
+        console.log(`[ssh] Trusting new host key for ${ssh.host}:${ssh.port} (${fingerprint(key)}), saved to ${PLANCHE_KNOWN_HOSTS}`);
+        await rememberHostKey(ssh.host, ssh.port, key).catch((e) => console.warn(`[ssh] Could not save host key: ${e.message}`));
+      }
+      verified(true);
+    });
+  };
+  await new Promise((resolve2, reject) => {
+    client.once("ready", resolve2);
+    client.once("error", (err) => reject(verifyError ?? describeSshError(err, ssh)));
+    try {
+      client.connect(connectConfig);
+    } catch (err) {
+      reject(describeSshError(err, ssh));
+    }
+  });
+  const sockets = /* @__PURE__ */ new Set();
+  let forwardError;
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+    client.forwardOut(socket.localAddress ?? "127.0.0.1", socket.localPort ?? 0, target.host, target.port, (err, stream) => {
+      if (err) {
+        const local = /^(localhost|127\.0\.0\.1|::1)$/i.test(target.host);
+        const hint = local ? `"${target.host}" is resolved on the jump host itself; use the database's real address (e.g. the RDS endpoint) as the database host` : "is the database reachable from the jump host, and does it allow TCP forwarding?";
+        forwardError = `SSH port forwarding to ${target.host}:${target.port} failed: ${err.message} (${hint})`;
+        console.error(`[ssh] ${forwardError}`);
+        socket.destroy();
+        return;
+      }
+      socket.pipe(stream).pipe(socket);
+      stream.once("close", () => socket.destroy());
+      socket.once("close", () => stream.destroy());
+    });
+  });
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve2());
+  }).catch((err) => {
+    client.end();
+    throw new TunnelError(`Could not open local tunnel port: ${err.message}`, 400);
+  });
+  const { port } = server.address();
+  let closed = false;
+  const close = () => new Promise((resolve2) => {
+    if (closed) return resolve2();
+    closed = true;
+    for (const s of sockets) s.destroy();
+    server.close(() => {
+      client.end();
+      resolve2();
+    });
+  });
+  client.once("close", () => void close());
+  return {
+    host: "127.0.0.1",
+    port,
+    get forwardError() {
+      return forwardError;
+    },
+    close
+  };
+}
+
 // src/drivers/index.ts
 var factories = {
   mysql: mysqlDriverFactory,
@@ -480,9 +821,53 @@ function parseDriverConfig(body) {
   if (!isDriverType(driver)) {
     throw new Error(`Unsupported driver: ${String(driver)}`);
   }
-  return factories[driver].parseConfig(body);
+  const config = factories[driver].parseConfig(body);
+  if (config.driver === "sqlite") return config;
+  const ssh = parseSshConfig(body.ssh);
+  return ssh ? { ...config, ssh } : config;
+}
+async function withTunnel(config, run) {
+  if (config.driver === "sqlite" || !config.ssh) return run(config, void 0);
+  const tunnel = await openSshTunnel(config.ssh, { host: config.host, port: config.port });
+  try {
+    return await run({ ...config, host: tunnel.host, port: tunnel.port, ssh: void 0 }, tunnel);
+  } catch (err) {
+    await tunnel.close();
+    throw tunnel.forwardError ? new TunnelError(tunnel.forwardError, 400) : err;
+  }
+}
+function tunneled(driver, tunnel, label) {
+  return {
+    type: driver.type,
+    label,
+    query: (sql, database) => driver.query(sql, database),
+    async close() {
+      try {
+        await driver.close();
+      } finally {
+        await tunnel.close();
+      }
+    }
+  };
 }
 function openDriver(config) {
+  return withTunnel(config, async (direct, tunnel) => {
+    const driver = await openDirect(direct);
+    if (!tunnel || config.driver === "sqlite" || !config.ssh) return driver;
+    const label = `${config.user}@${config.host}:${config.port} via ssh ${config.ssh.user}@${config.ssh.host}:${config.ssh.port}`;
+    return tunneled(driver, tunnel, label);
+  });
+}
+function testDriver(config) {
+  return withTunnel(config, async (direct, tunnel) => {
+    try {
+      await testDirect(direct);
+    } finally {
+      await tunnel?.close();
+    }
+  });
+}
+function openDirect(config) {
   switch (config.driver) {
     case "mysql":
       return factories.mysql.open(config);
@@ -492,7 +877,7 @@ function openDriver(config) {
       return factories.sqlite.open(config);
   }
 }
-function testDriver(config) {
+function testDirect(config) {
   switch (config.driver) {
     case "mysql":
       return factories.mysql.test(config);
@@ -594,6 +979,10 @@ var ConnectionManager = class {
 };
 
 // src/server.ts
+function errorStatus(err) {
+  const status = err?.status;
+  return typeof status === "number" && status >= 400 && status < 600 ? status : 400;
+}
 function fail(res, status, message) {
   res.status(status).json({ success: false, message });
 }
@@ -679,7 +1068,7 @@ function createAgent(options) {
     } catch (err) {
       const message = errorMessage(err);
       console.error("[connect] Error:", message);
-      fail(res, 400, message);
+      fail(res, errorStatus(err), message);
     }
   });
   app.post("/query", async (req, res) => {
@@ -737,7 +1126,7 @@ function createAgent(options) {
     } catch (err) {
       const message = errorMessage(err);
       console.error("[test-connection] Error:", message);
-      fail(res, 400, message);
+      fail(res, errorStatus(err), message);
     }
   });
   return { app, manager };
@@ -788,6 +1177,12 @@ function openInBrowser(url) {
   }
 }
 function main() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 22) {
+    console.error(`planche needs Node.js 22 or newer (you are running ${process.version}).`);
+    console.error("Try `nvm use 22` or `npx -p node@22 planche`.");
+    process.exit(1);
+  }
   let values;
   try {
     values = parseArgs({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planche",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local agent for Planche — lets the browser-based Planche SQL client reach MySQL/MariaDB/PostgreSQL/SQLite databases from your machine.",
   "license": "MIT",
   "homepage": "https://planche.dev",
@@ -43,13 +43,15 @@
     "better-sqlite3": "^12.11.1",
     "express": "^5.1.0",
     "mysql2": "^3.14.1",
-    "pg": "^8.23.0"
+    "pg": "^8.23.0",
+    "ssh2": "^1.17.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.23.1",
+    "@types/ssh2": "^1.15.5",
     "tsup": "^8.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.9.0"