@deepsql/mcp 0.8.0 → 0.10.1

package/src/commands/whoami.js

@@ -1,6 +1,5 @@
 "use strict";
 
-const store = require("../auth/store");
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
 
@@ -8,10 +7,17 @@ async function run(opts, { stdout = process.stdout } = {}) {
   const session = resolveSession(opts);
   try {
     const me = await request(session.baseUrl, "/auth/me", { token: session.token });
-    stdout.write(`Username: ${me.username || me.email || session.profile?.username || "(unknown)"}\n`);
-    if (me.role) stdout.write(`Role:     ${me.role}\n`);
-    stdout.write(`URL:      ${session.baseUrl}\n`);
-    if (session.profile?.tokenId) stdout.write(`Token id: ${session.profile.tokenId}\n`);
+    stdout.write(`Username:   ${me.username || me.email || session.profile?.username || "(unknown)"}\n`);
+    if (me.role) stdout.write(`Role:       ${me.role}\n`);
+    stdout.write(`URL:        ${session.baseUrl}\n`);
+    if (session.profile?.tokenId) stdout.write(`Token id:   ${session.profile.tokenId}\n`);
+    stdout.write(
+      `Connection: ${
+        session.defaultConnection
+          ? session.defaultConnection
+          : "(none — pin one with `deepsql connections use <name>`)"
+      }\n`,
+    );
   } catch (err) {
     if (err.status === 401 || err.status === 403) {
       throw new Error("Saved token is no longer valid. Run `deepsql login` again.");

package/src/connections/schema.js

@@ -0,0 +1,213 @@
+"use strict";
+
+/**
+ * JSON Schema (Draft 2020-12) for the `deepsql connections add --from-file`
+ * input. Mirrors the backend's ConnectionRequest DTO field-for-field so an
+ * AI agent can use this as the canonical contract.
+ *
+ * Field definitions are kept in one place so it's hard for the JSON Schema
+ * and the CLI's interactive prompts to drift apart. We also use this for
+ * `connections show` masking and for `connections add` validation.
+ */
+
+const SECRET_FIELDS = [
+  "password",
+  "sshPassword",
+  "sshPrivateKey",
+  "sshPassphrase",
+  "sslCaCertificate",
+  "sslClientCertificate",
+  "sslClientKey",
+  "sslClientKeyPassphrase",
+];
+
+const SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://deepsql.ai/schemas/connection-request.json",
+  title: "DeepSQL Connection",
+  description:
+    "Input for `deepsql connections add --from-file`. Mirrors the backend's ConnectionRequest DTO. Secret fields support $VAR_NAME (env var) and @file:<path> (file ref) — see `deepsql connections schema` for details.",
+  type: "object",
+  required: ["connectionName", "dbType", "host", "port", "database", "username"],
+  additionalProperties: false,
+  properties: {
+    connectionName: {
+      type: "string",
+      minLength: 1,
+      description: "Display name. Pass this to `--connection` everywhere else.",
+    },
+    dbType: {
+      type: "string",
+      enum: ["postgres", "mysql"],
+      description: "Database engine. Aliases (postgresql, aurora-postgres, etc.) are normalized server-side.",
+    },
+    host: { type: "string", minLength: 1, description: "Database hostname or IP. If sshEnabled=true, this is reached *through* the bastion." },
+    port: { type: "integer", minimum: 1, maximum: 65535 },
+    database: { type: "string", minLength: 1 },
+    username: { type: "string", minLength: 1 },
+    password: {
+      type: "string",
+      description: "DB password. Required on create; on update, omit to keep existing. Accepts $VAR / @file: refs.",
+    },
+
+    // Legacy SSL boolean (back-compat — prefer sslMode).
+    ssl: { type: "boolean", description: "Legacy: use sslMode instead. true = server-only TLS." },
+
+    // SSL fields
+    sslMode: {
+      type: "string",
+      enum: ["none", "server-only", "server-client"],
+      description: "TLS mode. server-client requires the three sslClient* fields.",
+    },
+    sslCaCertificate: { type: "string", description: "PEM-encoded CA cert. Accepts @file:." },
+    sslClientCertificate: { type: "string", description: "PEM-encoded client cert (sslMode=server-client only). Accepts @file:." },
+    sslClientKey: { type: "string", description: "PEM-encoded client key (sslMode=server-client only). Accepts @file:." },
+    sslClientKeyPassphrase: { type: "string", description: "Passphrase for an encrypted client key. Accepts $VAR / @file:." },
+
+    // SSH tunnel fields
+    sshEnabled: { type: "boolean", default: false, description: "Connect via an SSH bastion." },
+    sshAuthType: {
+      type: "string",
+      enum: ["PASSWORD", "PRIVATE_KEY"],
+      default: "PASSWORD",
+      description: "PASSWORD requires sshPassword; PRIVATE_KEY requires sshPrivateKey (and optionally sshPassphrase).",
+    },
+    sshHost: { type: "string", description: "Bastion hostname. Required when sshEnabled=true." },
+    sshPort: { type: "integer", default: 22, minimum: 1, maximum: 65535 },
+    sshUsername: { type: "string", description: "Bastion login. Required when sshEnabled=true." },
+    sshPassword: { type: "string", description: "Bastion password (sshAuthType=PASSWORD). Accepts $VAR." },
+    sshPrivateKey: { type: "string", description: "PEM-encoded SSH private key (sshAuthType=PRIVATE_KEY). Accepts @file:." },
+    sshPassphrase: { type: "string", description: "Passphrase for an encrypted SSH key. Accepts $VAR / @file:." },
+
+    // Cloud / instance metadata (informational; used for performance tuning calculations)
+    cloudProvider: { type: "string", enum: ["aws", "azure", "gcp", "self-hosted"], description: "Used for feature gating + tuning hints." },
+    managedService: { type: "string", enum: ["rds", "aurora", "cloud-sql", "azure-flexible", "azure-single"] },
+    instanceClass: { type: "string", description: "e.g. db.r6g.xlarge, db-n1-standard-4." },
+    instanceVcpus: { type: "integer", minimum: 1 },
+    instanceMemoryGb: { type: "number", minimum: 0 },
+    storageType: { type: "string", description: "e.g. gp3, io1, premium-ssd, pd-ssd." },
+    storageMaxIops: { type: "integer", minimum: 0 },
+
+    enableDataSampling: {
+      type: "boolean",
+      description: "Default true. Disables column-value sampling that DeepSQL uses for entity disambiguation.",
+    },
+
+    // Allow id on update flow (ignored on create).
+    id: { type: "string", description: "Set by the server; ignored on create." },
+  },
+  // Conditional "if SSH enabled, host+username required" — JSON Schema 2020-12.
+  allOf: [
+    {
+      if: { properties: { sshEnabled: { const: true } }, required: ["sshEnabled"] },
+      then: { required: ["sshHost", "sshUsername"] },
+    },
+    {
+      if: {
+        properties: {
+          sshEnabled: { const: true },
+          sshAuthType: { const: "PASSWORD" },
+        },
+        required: ["sshEnabled", "sshAuthType"],
+      },
+      then: { required: ["sshPassword"] },
+    },
+    {
+      if: {
+        properties: {
+          sshEnabled: { const: true },
+          sshAuthType: { const: "PRIVATE_KEY" },
+        },
+        required: ["sshEnabled", "sshAuthType"],
+      },
+      then: { required: ["sshPrivateKey"] },
+    },
+    {
+      if: { properties: { sslMode: { const: "server-client" } }, required: ["sslMode"] },
+      then: { required: ["sslClientCertificate", "sslClientKey"] },
+    },
+  ],
+};
+
+/**
+ * Lightweight validator. We don't pull in ajv to keep the package small —
+ * this checks the things we care about: required fields (incl. conditional),
+ * enum values, simple types, and minLength on strings.
+ *
+ * Returns { ok: true } or { ok: false, errors: [{ path, message }] }.
+ */
+function validate(input) {
+  if (input == null || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, errors: [{ path: "$", message: "Input must be a JSON object." }] };
+  }
+  const errors = [];
+
+  for (const [key, schema] of Object.entries(SCHEMA.properties)) {
+    const value = input[key];
+    if (value === undefined) continue;
+    const typeError = checkType(key, value, schema);
+    if (typeError) errors.push(typeError);
+  }
+
+  for (const required of SCHEMA.required) {
+    if (input[required] === undefined || input[required] === null || input[required] === "") {
+      errors.push({ path: required, message: `is required` });
+    }
+  }
+
+  // Conditional rules
+  if (input.sshEnabled === true) {
+    if (!input.sshHost) errors.push({ path: "sshHost", message: "is required when sshEnabled=true" });
+    if (!input.sshUsername) errors.push({ path: "sshUsername", message: "is required when sshEnabled=true" });
+    const auth = input.sshAuthType || "PASSWORD";
+    if (auth === "PASSWORD" && !input.sshPassword) {
+      errors.push({ path: "sshPassword", message: "is required when sshEnabled=true and sshAuthType=PASSWORD" });
+    }
+    if (auth === "PRIVATE_KEY" && !input.sshPrivateKey) {
+      errors.push({ path: "sshPrivateKey", message: "is required when sshEnabled=true and sshAuthType=PRIVATE_KEY" });
+    }
+  }
+  if (input.sslMode === "server-client") {
+    if (!input.sslClientCertificate) errors.push({ path: "sslClientCertificate", message: "is required when sslMode=server-client" });
+    if (!input.sslClientKey) errors.push({ path: "sslClientKey", message: "is required when sslMode=server-client" });
+  }
+
+  // Forbid unknown fields (additionalProperties: false in the schema).
+  for (const key of Object.keys(input)) {
+    if (!(key in SCHEMA.properties)) {
+      errors.push({ path: key, message: "is not a recognized field" });
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+function checkType(path, value, schema) {
+  if (schema.enum && !schema.enum.includes(value)) {
+    return { path, message: `must be one of: ${schema.enum.join(", ")}` };
+  }
+  if (schema.type === "string" && typeof value !== "string") {
+    return { path, message: `must be a string` };
+  }
+  if (schema.type === "integer" && (!Number.isInteger(value))) {
+    return { path, message: `must be an integer` };
+  }
+  if (schema.type === "number" && typeof value !== "number") {
+    return { path, message: `must be a number` };
+  }
+  if (schema.type === "boolean" && typeof value !== "boolean") {
+    return { path, message: `must be true or false` };
+  }
+  if (schema.minLength != null && typeof value === "string" && value.length < schema.minLength) {
+    return { path, message: `must be at least ${schema.minLength} character(s)` };
+  }
+  if (schema.minimum != null && typeof value === "number" && value < schema.minimum) {
+    return { path, message: `must be ≥ ${schema.minimum}` };
+  }
+  if (schema.maximum != null && typeof value === "number" && value > schema.maximum) {
+    return { path, message: `must be ≤ ${schema.maximum}` };
+  }
+  return null;
+}
+
+module.exports = { SCHEMA, SECRET_FIELDS, validate };

package/src/connections/secrets.js

@@ -0,0 +1,167 @@
+"use strict";
+
+/**
+ * Secret resolution for connection-config JSON inputs.
+ *
+ * Three accepted forms for any string field:
+ *
+ *   "plain string"        — used as-is. If the source file lives in a git
+ *                           tree we warn (suppressible with
+ *                           `--allow-plaintext-secrets`).
+ *   "$VAR_NAME"           — substitute from process.env at CLI runtime. The
+ *                           variable name appears in logs; the value never
+ *                           does.
+ *   "@file:/path/to/key"  — read file contents at CLI runtime. `~/` is
+ *                           expanded. File mode 0600 is enforced unless
+ *                           DEEPSQL_INSECURE_AUTH=1 is set (matching the
+ *                           existing auth-store convention).
+ *
+ * The list of fields treated as secrets is small and fixed — they're the
+ * fields where leaking the value would let an attacker connect to a database.
+ * Non-secret fields (host, port, etc.) pass through untouched.
+ */
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+
+const SECRET_FIELDS = new Set([
+  "password",
+  "sshPassword",
+  "sshPrivateKey",
+  "sshPassphrase",
+  "sslCaCertificate",
+  "sslClientCertificate",
+  "sslClientKey",
+  "sslClientKeyPassphrase",
+]);
+
+const ENV_REF = /^\$([A-Z_][A-Z0-9_]*)$/;
+const FILE_REF = /^@file:(.+)$/;
+
+/**
+ * Resolve all secret references in a parsed connection-config object,
+ * mutating-by-replacement (returns a new object). Throws on missing env vars
+ * or unreadable files.
+ *
+ *   resolveSecrets(cfg, { sourcePath, allowPlaintextSecrets, log })
+ *
+ *   sourcePath           — original JSON file path (for plaintext warnings)
+ *   allowPlaintextSecrets — true to suppress git-tree warnings
+ *   log                   — function for emitting warnings to stderr
+ */
+function resolveSecrets(cfg, opts = {}) {
+  const { sourcePath = null, allowPlaintextSecrets = false, log = () => {} } = opts;
+  if (cfg == null || typeof cfg !== "object") return cfg;
+
+  const inGitTree = sourcePath ? isInsideGitTree(sourcePath) : false;
+  const out = { ...cfg };
+
+  for (const key of Object.keys(out)) {
+    const value = out[key];
+    if (typeof value !== "string") continue;
+
+    const envMatch = value.match(ENV_REF);
+    if (envMatch) {
+      const varName = envMatch[1];
+      if (!(varName in process.env)) {
+        throw new Error(
+          `Field "${key}" references env var ${varName}, but it is not set.`,
+        );
+      }
+      out[key] = process.env[varName];
+      continue;
+    }
+
+    const fileMatch = value.match(FILE_REF);
+    if (fileMatch) {
+      const resolvedPath = expandHome(fileMatch[1].trim());
+      assertSafeMode(resolvedPath, key);
+      try {
+        out[key] = fs.readFileSync(resolvedPath, "utf8");
+      } catch (err) {
+        throw new Error(
+          `Field "${key}" references @file:${resolvedPath}, but the file could not be read: ${err.message}`,
+        );
+      }
+      continue;
+    }
+
+    // Plaintext — warn if it's a non-empty secret in a git-tracked file.
+    if (
+      SECRET_FIELDS.has(key) &&
+      value.length > 0 &&
+      inGitTree &&
+      !allowPlaintextSecrets
+    ) {
+      log(
+        `[deepsql] Warning: field "${key}" contains a plaintext secret and ${sourcePath} is inside a git working tree. ` +
+          `Move the value to an env var ($VAR) or a 0600 file (@file:path), or pass --allow-plaintext-secrets.`,
+      );
+    }
+  }
+  return out;
+}
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function assertSafeMode(filePath, fieldName) {
+  if (process.platform === "win32") return;
+  if (process.env.DEEPSQL_INSECURE_AUTH === "1") return;
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch (err) {
+    throw new Error(
+      `Cannot read ${filePath} for field "${fieldName}": ${err.message}`,
+    );
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    throw new Error(
+      `${filePath} (referenced by "${fieldName}") has insecure permissions ${(stat.mode & 0o777).toString(8)}. ` +
+        `Run \`chmod 600 ${filePath}\` or set DEEPSQL_INSECURE_AUTH=1.`,
+    );
+  }
+}
+
+function isInsideGitTree(filePath) {
+  try {
+    const dir = path.dirname(path.resolve(filePath));
+    execFileSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mask secret values in a config for display. Useful before logging the
+ * resolved object for debugging.
+ */
+function maskSecrets(cfg) {
+  if (cfg == null || typeof cfg !== "object") return cfg;
+  const out = { ...cfg };
+  for (const key of Object.keys(out)) {
+    if (SECRET_FIELDS.has(key) && out[key]) {
+      out[key] = typeof out[key] === "string" && out[key].length > 0 ? "(set)" : out[key];
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  SECRET_FIELDS,
+  resolveSecrets,
+  maskSecrets,
+  // exported for testing
+  _isInsideGitTree: isInsideGitTree,
+  _expandHome: expandHome,
+};

package/src/connections/secrets.test.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { resolveSecrets, maskSecrets, SECRET_FIELDS } = require("./secrets");
+
+function tempfile(content, mode = 0o600) {
+  const file = path.join(os.tmpdir(), `deepsql-secrets-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+  fs.writeFileSync(file, content, { mode });
+  return file;
+}
+
+test("plaintext non-secret fields pass through unchanged", () => {
+  const out = resolveSecrets({ host: "db.x", port: 5432, dbType: "postgres" });
+  assert.deepEqual(out, { host: "db.x", port: 5432, dbType: "postgres" });
+});
+
+test("$VAR substitution pulls from process.env", () => {
+  process.env.DEEPSQL_TEST_PWD = "s3cret";
+  try {
+    const out = resolveSecrets({ password: "$DEEPSQL_TEST_PWD", host: "x" });
+    assert.equal(out.password, "s3cret");
+    assert.equal(out.host, "x");
+  } finally {
+    delete process.env.DEEPSQL_TEST_PWD;
+  }
+});
+
+test("$VAR throws when the env var is missing", () => {
+  delete process.env.DEEPSQL_TEST_MISSING_PWD;
+  assert.throws(
+    () => resolveSecrets({ password: "$DEEPSQL_TEST_MISSING_PWD" }),
+    /references env var DEEPSQL_TEST_MISSING_PWD, but it is not set/,
+  );
+});
+
+test("@file: reads file contents at runtime", () => {
+  const file = tempfile("-----BEGIN CERT-----\nblob\n-----END CERT-----\n");
+  try {
+    const out = resolveSecrets({ sslCaCertificate: `@file:${file}` });
+    assert.match(out.sslCaCertificate, /BEGIN CERT/);
+  } finally {
+    fs.unlinkSync(file);
+  }
+});
+
+test("@file: rejects insecure permissions unless DEEPSQL_INSECURE_AUTH=1", { skip: process.platform === "win32" }, () => {
+  const file = tempfile("body", 0o644);
+  try {
+    assert.throws(
+      () => resolveSecrets({ sshPrivateKey: `@file:${file}` }),
+      /insecure permissions/,
+    );
+    process.env.DEEPSQL_INSECURE_AUTH = "1";
+    try {
+      const out = resolveSecrets({ sshPrivateKey: `@file:${file}` });
+      assert.equal(out.sshPrivateKey, "body");
+    } finally {
+      delete process.env.DEEPSQL_INSECURE_AUTH;
+    }
+  } finally {
+    fs.unlinkSync(file);
+  }
+});
+
+test("@file: expands ~/ to homedir", () => {
+  // Write a real file under homedir to confirm expansion works end-to-end.
+  const dir = fs.mkdtempSync(path.join(os.homedir(), ".deepsql-test-"));
+  const filename = path.join(dir, "secret.pem");
+  fs.writeFileSync(filename, "homedir-secret", { mode: 0o600 });
+  const relative = `~/${path.relative(os.homedir(), filename)}`;
+  try {
+    const out = resolveSecrets({ sshPrivateKey: `@file:${relative}` });
+    assert.equal(out.sshPrivateKey, "homedir-secret");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("plaintext secrets warn only when sourcePath is inside a git tree (best-effort)", () => {
+  const warnings = [];
+  resolveSecrets(
+    { password: "plain-text-password" },
+    {
+      sourcePath: __filename, // this file is in our git tree
+      log: (msg) => warnings.push(msg),
+    },
+  );
+  assert.ok(
+    warnings.some((m) => m.includes("plaintext secret")),
+    `expected a plaintext-secret warning, got: ${warnings.join(" / ") || "(none)"}`,
+  );
+});
+
+test("plaintext secrets do NOT warn when --allow-plaintext-secrets is set", () => {
+  const warnings = [];
+  resolveSecrets(
+    { password: "plain-text-password" },
+    {
+      sourcePath: __filename,
+      allowPlaintextSecrets: true,
+      log: (msg) => warnings.push(msg),
+    },
+  );
+  assert.equal(warnings.length, 0);
+});
+
+test("plaintext non-secret fields don't trigger warnings even in a git tree", () => {
+  const warnings = [];
+  resolveSecrets(
+    { host: "plain-host" },
+    {
+      sourcePath: __filename,
+      log: (msg) => warnings.push(msg),
+    },
+  );
+  assert.equal(warnings.length, 0);
+});
+
+test("maskSecrets replaces non-empty secret fields with '(set)'", () => {
+  const cfg = {
+    host: "db.x",
+    password: "abc",
+    sshPrivateKey: "",
+    sshPassphrase: "phrase",
+  };
+  const masked = maskSecrets(cfg);
+  assert.equal(masked.host, "db.x");
+  assert.equal(masked.password, "(set)");
+  assert.equal(masked.sshPrivateKey, "");
+  assert.equal(masked.sshPassphrase, "(set)");
+});
+
+test("SECRET_FIELDS export covers the canonical list", () => {
+  for (const f of [
+    "password",
+    "sshPassword",
+    "sshPrivateKey",
+    "sshPassphrase",
+    "sslCaCertificate",
+    "sslClientCertificate",
+    "sslClientKey",
+    "sslClientKeyPassphrase",
+  ]) {
+    assert.ok(SECRET_FIELDS.has(f), `${f} should be in SECRET_FIELDS`);
+  }
+});