@deepsql/mcp 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",

package/src/api/client.js

@@ -32,7 +32,7 @@ function resolveUrl(baseUrl, path) {
   return new URL(withApi, normalizeBaseUrl(baseUrl)).toString();
 }
 
-async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, token, timeoutMs = 120000, query } = {}) {
+async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, token, timeoutMs = 120000, query, returnHeaders = false } = {}) {
   let url;
   if (typeof pathOrUrl === "string" && /^https?:\/\//i.test(pathOrUrl)) {
     url = pathOrUrl;
@@ -87,7 +87,31 @@ async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, toke
     const message = (body && typeof body === "object" && (body.message || body.error)) || `HTTP ${response.status}`;
     throw new ApiError(message, { status: response.status, body });
   }
+  if (returnHeaders) {
+    // Node's fetch exposes Set-Cookie via getSetCookie() (Node 20+); the
+    // password-login flow needs the auth_token cookie value to mint a long-
+    // lived MCP token afterwards.
+    const setCookies = typeof response.headers.getSetCookie === "function"
+      ? response.headers.getSetCookie()
+      : [];
+    return { body, status: response.status, setCookies };
+  }
   return body;
 }
 
-module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl };
+/**
+ * Extract a single cookie value from an array of Set-Cookie header values.
+ *
+ *   parseCookieValue(["auth_token=abc.def; Path=/; HttpOnly", "refresh_token=…"], "auth_token")
+ *     => "abc.def"
+ */
+function parseCookieValue(setCookies, name) {
+  if (!Array.isArray(setCookies)) return null;
+  for (const raw of setCookies) {
+    const match = raw && raw.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+    if (match) return decodeURIComponent(match[1]);
+  }
+  return null;
+}
+
+module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl, parseCookieValue };

package/src/auth/password-flow.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * Direct username/password login — for headless boxes where neither a browser
+ * nor copy-paste of a device code is convenient (e.g. provisioning a fresh
+ * self-host VM via Ansible/cloud-init, or a CI runner that needs to mint a
+ * service-account token from a stored secret).
+ *
+ * Flow:
+ *   1. Prompt for email + password (or accept --email and --password-stdin).
+ *   2. POST /auth/login. The backend either:
+ *        a) succeeds and sets the auth_token cookie containing a session JWT, or
+ *        b) returns { challengeId, message } indicating an email-OTP step.
+ *   3. If a challenge is required, kick off /auth/email/start, prompt for the
+ *      OTP, then POST /auth/email/verify. Same auth_token cookie is set on
+ *      success.
+ *   4. With the JWT in hand, POST /auth/mcp-tokens to mint a long-lived MCP
+ *      token. The session cookie is short-lived (minutes); the MCP token lives
+ *      until revoked, which is what we want to persist to ~/.config/deepsql.
+ *
+ * Security notes:
+ *   - We never persist the raw password. It's read from a TTY (echo off) or
+ *     from stdin and then dropped after the login POST.
+ *   - The session JWT is held only in memory between login and the
+ *     mcp-tokens POST.
+ *   - For CI-style use, callers should pipe the password via stdin
+ *     (`--password-stdin`) rather than passing it as an argv flag, since argv
+ *     shows up in `ps`.
+ */
+
+const os = require("node:os");
+
+const { ApiError, parseCookieValue, request } = require("../api/client");
+const { prompt, promptPassword, readSingleLineFromStdin } = require("./prompt");
+
+async function runPasswordFlow({ baseUrl, email, passwordStdin, hostname, clientLabel, log = () => {} }) {
+  const resolvedEmail = email && email.trim() ? email.trim() : await prompt("Email: ");
+  if (!resolvedEmail) throw new Error("Email is required.");
+
+  const password = passwordStdin
+    ? await readSingleLineFromStdin()
+    : await promptPassword("Password: ");
+  if (!password) throw new Error("Password is required.");
+
+  log(`Authenticating ${resolvedEmail} against ${baseUrl}…`);
+  let jwt = await postLoginAndExtractJwt(baseUrl, resolvedEmail, password);
+
+  if (!jwt) {
+    // Server returned a challenge — currently the only kind we handle is
+    // email OTP. Other challenges (e.g. authenticator-app MFA) should fall
+    // back to the browser flow with a clear error.
+    log("Server requires email verification. Sending OTP…");
+    jwt = await runEmailOtpChallenge(baseUrl, resolvedEmail);
+  }
+
+  log("Minting long-lived CLI token…");
+  const tokenName = buildTokenName(clientLabel, hostname);
+  const created = await request(baseUrl, "/auth/mcp-tokens", {
+    method: "POST",
+    token: jwt,
+    json: { name: tokenName },
+  });
+
+  return {
+    token: created.token,
+    token_id: created.id,
+    username: extractUsername(created, resolvedEmail),
+    expires_at: created.expiresAt || null,
+  };
+}
+
+async function postLoginAndExtractJwt(baseUrl, email, password) {
+  let result;
+  try {
+    result = await request(baseUrl, "/auth/login", {
+      method: "POST",
+      json: { email, password },
+      returnHeaders: true,
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status >= 400 && err.status < 500) {
+      const detail = err.body && typeof err.body === "object" ? err.body.message : null;
+      throw new Error(detail || "Invalid email or password.");
+    }
+    throw err;
+  }
+
+  const jwt = parseCookieValue(result.setCookies, "auth_token");
+  if (jwt) return jwt;
+
+  // No cookie on the response — must be a challenge handoff. Body shape is
+  // { challengeId, message }.
+  if (result.body && result.body.challengeId) return null;
+
+  throw new Error(
+    "Login succeeded but no session token was issued — your DeepSQL instance may use SSO that the CLI can't drive. Use `deepsql login` (browser flow) instead.",
+  );
+}
+
+async function runEmailOtpChallenge(baseUrl, email) {
+  // Fresh challenge so /email/start has something to act on. The login call
+  // above already created a challenge but didn't expose its id; calling
+  // /email/start without a prior challenge id is supported and starts a new
+  // one for the same user.
+  let started;
+  try {
+    started = await request(baseUrl, "/auth/email/start", {
+      method: "POST",
+      json: { email },
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not start email verification: ${err.message}. Use \`deepsql login\` (browser flow) if your account requires SSO or authenticator MFA.`,
+    );
+  }
+
+  const otp = await prompt(`Email OTP (sent to ${email}): `);
+  if (!otp) throw new Error("OTP is required.");
+
+  const result = await request(baseUrl, "/auth/email/verify", {
+    method: "POST",
+    json: { challengeId: started.challengeId, otp },
+    returnHeaders: true,
+  });
+  const jwt = parseCookieValue(result.setCookies, "auth_token");
+  if (!jwt) {
+    throw new Error("Email verification did not return a session token. Aborting.");
+  }
+  return jwt;
+}
+
+function extractUsername(createdTokenResponse, fallbackEmail) {
+  if (createdTokenResponse && typeof createdTokenResponse === "object") {
+    if (createdTokenResponse.username) return createdTokenResponse.username;
+    if (createdTokenResponse.userId) return String(createdTokenResponse.userId);
+  }
+  return fallbackEmail;
+}
+
+function buildTokenName(clientLabel, hostname) {
+  const parts = ["CLI"];
+  parts.push(clientLabel && clientLabel.trim() ? clientLabel.trim() : "deepsql");
+  if (hostname && hostname.trim()) parts.push(`@ ${hostname.trim()}`);
+  parts.push("(password)");
+  const name = parts.join(" ");
+  return name.length > 120 ? name.slice(0, 120) : name;
+}
+
+module.exports = { runPasswordFlow };

package/src/auth/prompt.js

@@ -0,0 +1,96 @@
+"use strict";
+
+/**
+ * Tiny interactive prompt helpers — no dependency on a TTY library.
+ *
+ * For passwords we mute the terminal echo so the value does not show on screen
+ * or get captured by ttyrec / screen-recording. If stdin is not a TTY (piped
+ * input), we read a single line as-is.
+ */
+
+const readline = require("node:readline");
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function promptPassword(question) {
+  if (!process.stdin.isTTY) {
+    return readSingleLineFromStdin();
+  }
+  return new Promise((resolve, reject) => {
+    process.stderr.write(question);
+    const stdin = process.stdin;
+    const previousRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    const ETX = "\u0003"; // Ctrl-C
+    const EOT = "\u0004"; // Ctrl-D
+    const BS  = "\u0008"; // ASCII backspace
+    const DEL = "\u007f"; // most modern terminals send this on backspace
+
+    let buffer = "";
+    const onData = (char) => {
+      switch (char) {
+        case "\r":
+        case "\n":
+        case EOT:
+          finish();
+          return;
+        case ETX:
+          cleanup();
+          process.stderr.write("\n");
+          reject(new Error("Cancelled"));
+          return;
+        case BS:
+        case DEL:
+          buffer = buffer.slice(0, -1);
+          return;
+        default:
+          // Accept printable chars only; ignore other ANSI control sequences.
+          if (char.charCodeAt(0) >= 32) buffer += char;
+      }
+    };
+
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      try {
+        stdin.setRawMode(previousRaw);
+      } catch {}
+      stdin.pause();
+    };
+
+    const finish = () => {
+      cleanup();
+      process.stderr.write("\n");
+      resolve(buffer);
+    };
+
+    stdin.on("data", onData);
+  });
+}
+
+function readSingleLineFromStdin() {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      // Strip a single trailing newline if the caller did echo \$PWD | …
+      resolve(buffer.replace(/\r?\n$/, ""));
+    });
+    process.stdin.on("error", reject);
+  });
+}
+
+module.exports = { prompt, promptPassword, readSingleLineFromStdin };

package/src/cli.js

@@ -31,8 +31,14 @@ Usage:
   deepsql <command> [options]
 
 Commands:
-  login [--url <url>] [--device|--browser] [--no-browser] [--label <name>]
+  login [--url <url>] [--device|--browser|--password] [--no-browser] [--label <name>]
+        [--email <email>] [--password-stdin]
                                   Authorize this CLI with a DeepSQL instance.
+                                  Default: browser callback (PKCE), or device-code
+                                  on headless boxes. Use --password for direct
+                                  email+password login on a fresh self-host VM
+                                  with no browser; pipe the password via stdin
+                                  with --password-stdin for non-interactive use.
   logout [--url <url>]            Revoke and forget the saved token.
   whoami                          Show the user behind the saved token.
   config show                     List saved profiles.
@@ -107,6 +113,9 @@ function buildOpts(parsed) {
     device: !!f.device,
     browser: !!f.browser,
     noBrowser: !!f.noBrowser,
+    password: !!f.password,
+    passwordStdin: !!f.passwordStdin,
+    email: f.email || null,
     label: f.label || null,
     connection: f.connection || f.c || null,
     chat: f.chat || null,

package/src/commands/login.js

@@ -3,6 +3,7 @@
 const os = require("node:os");
 const { runBrowserFlow } = require("../auth/browser-flow");
 const { runDeviceFlow } = require("../auth/device-flow");
+const { runPasswordFlow } = require("../auth/password-flow");
 const store = require("../auth/store");
 const { ApiError } = require("../api/client");
 
@@ -10,13 +11,15 @@ function defaultClientLabel() {
   return `deepsql-cli@${process.versions.node}`;
 }
 
-function shouldUseDevice(opts) {
-  if (opts.device) return true;
-  if (opts.browser) return false;
-  // Heuristic: assume browser unless we detect a headless env.
-  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT) return true;
-  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
-  return false;
+function pickFlow(opts) {
+  // Explicit user choice wins.
+  if (opts.password) return "password";
+  if (opts.device) return "device";
+  if (opts.browser) return "browser";
+  // Heuristic: prefer browser; fall back to device-code in headless envs.
+  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT) return "device";
+  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return "device";
+  return "browser";
 }
 
 async function run(opts, { stderr = process.stderr, stdout = process.stdout } = {}) {
@@ -28,14 +31,24 @@ async function run(opts, { stderr = process.stderr, stdout = process.stdout } =
   }
   const hostname = os.hostname();
   const label = opts.label || defaultClientLabel();
-  const useDevice = shouldUseDevice(opts);
+  const flow = pickFlow(opts);
   const log = (msg) => stderr.write(`[deepsql] ${msg}\n`);
 
   let issued;
   try {
-    if (useDevice) {
+    if (flow === "device") {
       log(`Starting device-code login against ${baseUrl}…`);
       issued = await runDeviceFlow({ baseUrl, hostname, clientLabel: label, log });
+    } else if (flow === "password") {
+      log(`Starting password login against ${baseUrl}…`);
+      issued = await runPasswordFlow({
+        baseUrl,
+        email: opts.email,
+        passwordStdin: !!opts.passwordStdin,
+        hostname,
+        clientLabel: label,
+        log,
+      });
     } else {
       log(`Starting browser login against ${baseUrl}…`);
       issued = await runBrowserFlow({