virlow-mcp 3.17.1 → 3.19.0

package/README.md

@@ -35,13 +35,13 @@ offers a **hosted connector** — the same 19 tools, served from Virlow's own se
 client can connect by URL with nothing installed. It is a genuinely different trust model,
 and the sentence "the key never leaves it" is the part that stops being true:
 
-| | this local server | the hosted connector |
-| --- | --- | --- |
-| where the key is derived | this process, on your machine | Virlow's API process |
-| who can read a decrypted note | this process | this process, and Virlow's server |
-| what an unlock sends | nothing; the password stays local | your master password, over HTTPS |
-| what it takes to run | Node on your machine | nothing |
-| session lifetime | 4 hours idle | 30 minutes idle |
+| | this local server | the desktop app | the hosted connector |
+| --- | --- | --- | --- |
+| where the key is derived | this process, on your machine | the Virlow app, on your machine | Virlow's API process |
+| who can read a decrypted note | this process | the app's process | this process, and Virlow's server |
+| what an unlock sends | nothing; the password stays local | nothing; the password stays local | your master password, over HTTPS |
+| what it takes to run | Node on your machine | the installed app | nothing |
+| session lifetime | 4 hours idle | follows the app's vault lock | 30 minutes idle |
 
 The hosted connector is **off by default** on every account and has to be switched on in
 Virlow's settings. If you are reading this page, you are looking at the option that keeps
@@ -122,6 +122,27 @@ Claude Desktop / Cursor:
 }
 ```
 
+### Connecting through the Virlow desktop app
+
+If you run the [Virlow desktop app](../desktop/README.md), it already hosts this server
+on your machine and unlocks with the app. Clients that can send a header connect to it
+directly; the app shows the exact snippet under Settings, This computer. Clients that can
+only spawn a command use this package as a pipe:
+
+```json
+{
+  "mcpServers": {
+    "virlow": {
+      "command": "npx",
+      "args": ["-y", "virlow-mcp", "--connect", "http://127.0.0.1:47821/mcp",
+               "--token-file", "<path the app shows you>"]
+    }
+  }
+}
+```
+
+In this mode nothing is decrypted in this process. It forwards to the app and back.
+
 ## First use
 
 1. Ask your AI client to run the **`unlock`** tool. This opens a browser window pointed

package/dist/cli.js

@@ -3,11 +3,12 @@
 // src/cli.ts
 import * as os2 from "node:os";
 import * as path4 from "node:path";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFile as readFile3 } from "node:fs/promises";
+import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
 import os from "node:os";
-import path2 from "node:path";
+import path3 from "node:path";
 
 // ../../packages/mcp-core/dist/api.js
 var ApiError = class extends Error {
@@ -50,12 +51,29 @@ var VirlowApi = class {
   tokens = null;
   refreshInFlight = null;
   onTokensRotated;
+  /** Fired when a refresh is refused outright and the session is gone. */
+  onTokensCleared;
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
   }
   setTokens(tokens) {
     this.tokens = tokens;
   }
+  getTokens() {
+    return this.tokens;
+  }
+  /**
+   * Rotate the refresh token exactly once no matter how many callers arrive
+   * while a rotation is pending. The API revokes the whole token family when a
+   * replaced refresh token is presented again, so two concurrent refreshes are
+   * not a race, they are a forced sign-out.
+   */
+  refreshSession() {
+    this.refreshInFlight ??= this.doRefresh().finally(() => {
+      this.refreshInFlight = null;
+    });
+    return this.refreshInFlight;
+  }
   async request(method, path5, body, opts = {}) {
     const { auth = true, retryOn401 = true } = opts;
     const headers = { "content-type": "application/json" };
@@ -79,17 +97,24 @@ var VirlowApi = class {
     return data;
   }
   refresh() {
-    this.refreshInFlight ??= this.doRefresh().finally(() => {
-      this.refreshInFlight = null;
-    });
-    return this.refreshInFlight;
+    return this.refreshSession().then(() => void 0);
   }
   async doRefresh() {
     if (!this.tokens)
       throw new ApiError(401, "Not authenticated");
-    const rotated = await this.request("POST", "/api/auth/refresh", { refreshToken: this.tokens.refreshToken }, { auth: false, retryOn401: false });
+    let rotated;
+    try {
+      rotated = await this.request("POST", "/api/auth/refresh", { refreshToken: this.tokens.refreshToken }, { auth: false, retryOn401: false });
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 401) {
+        this.tokens = null;
+        this.onTokensCleared?.();
+      }
+      throw err;
+    }
     this.tokens = { accessToken: rotated.accessToken, refreshToken: rotated.refreshToken };
     this.onTokensRotated?.(this.tokens);
+    return { user: rotated.user, accessToken: rotated.accessToken };
   }
   login(email, password) {
     return this.request("POST", "/api/auth/login", { email, password }, { auth: false });
@@ -1411,7 +1436,7 @@ function formatMeta(meta) {
 }
 var truncate = (text, max = 120) => text.length > max ? `${text.slice(0, max)}\u2026` : text;
 function createServices(opts) {
-  const api = new VirlowApi(opts.apiUrl);
+  const api = opts.api ?? new VirlowApi(opts.apiUrl);
   const vault = new Vault(opts.autoLockMs);
   let embedderPromise = null;
   const getRealEmbedder = () => {
@@ -1684,21 +1709,30 @@ ${note.content}`);
 }
 
 // src/unlock.ts
-import { randomBytes } from "node:crypto";
+import { randomBytes as randomBytes2 } from "node:crypto";
 import { spawn } from "node:child_process";
 import * as http from "node:http";
 
-// src/local-origin.ts
+// ../../packages/mcp-core/dist/http/server.js
+import { createServer } from "node:http";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import path2 from "node:path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// ../../packages/mcp-core/dist/http/local-origin.js
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
 function withoutPort(host) {
   return host.replace(/:\d+$/, "").toLowerCase();
 }
 function isLoopbackHost(hostHeader) {
-  if (hostHeader === void 0 || hostHeader === "") return false;
+  if (hostHeader === void 0 || hostHeader === "")
+    return false;
   return LOOPBACK_HOSTS.has(withoutPort(hostHeader.trim()));
 }
 function isAllowedOrigin(originHeader) {
-  if (originHeader === void 0 || originHeader === "") return true;
+  if (originHeader === void 0 || originHeader === "")
+    return true;
   try {
     return LOOPBACK_HOSTS.has(new URL(originHeader).hostname.toLowerCase());
   } catch {
@@ -1706,9 +1740,12 @@ function isAllowedOrigin(originHeader) {
   }
 }
 function rejectReason(headers, enforce) {
-  if (!enforce) return null;
-  if (!isLoopbackHost(headers.host)) return "non-loopback Host";
-  if (!isAllowedOrigin(headers.origin)) return "cross-site Origin";
+  if (!enforce)
+    return null;
+  if (!isLoopbackHost(headers.host))
+    return "non-loopback Host";
+  if (!isAllowedOrigin(headers.origin))
+    return "cross-site Origin";
   return null;
 }
 var SECURITY_HEADERS = Object.freeze({
@@ -1719,6 +1756,99 @@ var SECURITY_HEADERS = Object.freeze({
   "cache-control": "no-store"
 });
 
+// ../../packages/mcp-core/dist/http/server.js
+function defaultTokenPath(homeDir) {
+  return path2.join(homeDir, ".virlow-mcp", "http-token");
+}
+async function loadOrCreateToken(tokenPath) {
+  try {
+    const existing = (await readFile2(tokenPath, "utf8")).trim();
+    if (existing.length > 0)
+      return existing;
+  } catch {
+  }
+  const token = randomBytes(32).toString("base64url");
+  await mkdir2(path2.dirname(tokenPath), { recursive: true, mode: 448 });
+  await writeFile2(tokenPath, `${token}
+`, { mode: 384 });
+  return token;
+}
+function tokenMatches(provided, expected) {
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) {
+    timingSafeEqual(b, b);
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+function bearerFrom(header) {
+  if (!header)
+    return null;
+  const match = /^Bearer[ ]+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+async function handleWithFreshTransport(server, req, res) {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: void 0
+  });
+  res.on("close", () => {
+    void transport.close();
+    void server.close();
+  });
+  await server.connect(transport);
+  await transport.handleRequest(req, res);
+}
+async function startHttpServer(opts) {
+  const host = opts.host ?? "127.0.0.1";
+  const mcpPath = opts.path ?? "/mcp";
+  const enforceLocal = host === "127.0.0.1" || host === "::1" || host === "localhost";
+  const httpServer = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", `http://${host}`);
+    if (rejectReason(req.headers, enforceLocal) !== null) {
+      res.writeHead(403, { ...SECURITY_HEADERS, "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "forbidden" }));
+      return;
+    }
+    if (url.pathname === "/health") {
+      res.writeHead(200, { ...SECURITY_HEADERS, "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+    if (url.pathname !== mcpPath) {
+      res.writeHead(404, SECURITY_HEADERS).end();
+      return;
+    }
+    const provided = bearerFrom(req.headers.authorization);
+    if (provided === null || opts.authorize(provided) === null) {
+      res.writeHead(401, {
+        ...SECURITY_HEADERS,
+        "content-type": "application/json",
+        "www-authenticate": "Bearer"
+      });
+      res.end(JSON.stringify({ error: "unauthorized" }));
+      return;
+    }
+    void handleWithFreshTransport(opts.makeServer(), req, res);
+  });
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(opts.port ?? 0, host, () => {
+      httpServer.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const address = httpServer.address();
+  const port = typeof address === "object" && address !== null ? address.port : 0;
+  return {
+    port,
+    host,
+    close: () => new Promise((resolve) => {
+      httpServer.close(() => resolve());
+    })
+  };
+}
+
 // src/unlock.ts
 var UNLOCK_TIMEOUT_MS = 5 * 60 * 1e3;
 var MAX_BAD_NONCE_ATTEMPTS = 3;
@@ -1859,7 +1989,7 @@ function openInBrowser(url) {
 function startUnlockServer(api, vault, opts = {}) {
   const openBrowser = opts.openBrowser ?? true;
   return new Promise((resolveStart, rejectStart) => {
-    const nonce = randomBytes(32).toString("hex");
+    const nonce = randomBytes2(32).toString("hex");
     let badNonceAttempts = 0;
     let settled = false;
     let timeoutHandle;
@@ -1984,11 +2114,11 @@ function startUnlockServer(api, vault, opts = {}) {
 }
 
 // src/version.ts
-var VERSION = true ? "3.17.1" : "dev";
+var VERSION = true ? "3.19.0" : "dev";
 
 // src/server.ts
 function defaultEmbeddingCacheDir() {
-  return path2.join(os.homedir(), ".virlow-mcp", "cache");
+  return path3.join(os.homedir(), ".virlow-mcp", "cache");
 }
 var localBrowserUnlock = {
   description: "Open a local browser window where the USER signs in and enters their Virlow master password. This tool returns immediately once the browser is opened \u2014 it does NOT wait for the user to finish. Call the status tool afterward to confirm the vault unlocked. Never ask the user for their password or account credentials yourself, and never relay a password through this tool or any other \u2014 credentials are entered only in the browser form and never seen by any AI model.",
@@ -2017,99 +2147,53 @@ function buildServer2(opts) {
   return buildServer({ ...withLocalDefaults(opts), services: opts.services });
 }
 
-// src/http.ts
-import { createServer as createServer2 } from "node:http";
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { randomBytes as randomBytes2, timingSafeEqual } from "node:crypto";
-import path3 from "node:path";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-function defaultTokenPath(homeDir) {
-  return path3.join(homeDir, ".virlow-mcp", "http-token");
-}
-async function loadOrCreateToken(tokenPath) {
-  try {
-    const existing = (await readFile2(tokenPath, "utf8")).trim();
-    if (existing.length > 0) return existing;
-  } catch {
-  }
-  const token = randomBytes2(32).toString("base64url");
-  await mkdir2(path3.dirname(tokenPath), { recursive: true, mode: 448 });
-  await writeFile2(tokenPath, `${token}
-`, { mode: 384 });
-  return token;
-}
-function tokenMatches(provided, expected) {
-  const a = Buffer.from(provided);
-  const b = Buffer.from(expected);
-  if (a.length !== b.length) {
-    timingSafeEqual(b, b);
-    return false;
-  }
-  return timingSafeEqual(a, b);
-}
-function bearerFrom(header) {
-  if (!header) return null;
-  const match = /^Bearer[ ]+(.+)$/i.exec(header.trim());
-  return match ? match[1].trim() : null;
-}
-async function handleWithFreshTransport(server, req, res) {
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: void 0
-  });
-  res.on("close", () => {
-    void transport.close();
-    void server.close();
-  });
-  await server.connect(transport);
-  await transport.handleRequest(req, res);
-}
-async function startHttpServer(opts) {
-  const host = opts.host ?? "127.0.0.1";
-  const mcpPath = opts.path ?? "/mcp";
-  const enforceLocal = host === "127.0.0.1" || host === "::1" || host === "localhost";
-  const httpServer = createServer2((req, res) => {
-    const url = new URL(req.url ?? "/", `http://${host}`);
-    if (rejectReason(req.headers, enforceLocal) !== null) {
-      res.writeHead(403, { ...SECURITY_HEADERS, "content-type": "application/json" });
-      res.end(JSON.stringify({ error: "forbidden" }));
-      return;
-    }
-    if (url.pathname === "/health") {
-      res.writeHead(200, { ...SECURITY_HEADERS, "content-type": "application/json" });
-      res.end(JSON.stringify({ ok: true }));
-      return;
-    }
-    if (url.pathname !== mcpPath) {
-      res.writeHead(404, SECURITY_HEADERS).end();
-      return;
-    }
-    const provided = bearerFrom(req.headers.authorization);
-    if (provided === null || !tokenMatches(provided, opts.token)) {
-      res.writeHead(401, {
-        ...SECURITY_HEADERS,
-        "content-type": "application/json",
-        "www-authenticate": "Bearer"
-      });
-      res.end(JSON.stringify({ error: "unauthorized" }));
-      return;
-    }
-    void handleWithFreshTransport(opts.makeServer(), req, res);
+// src/connect.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+async function runConnectBridge(opts) {
+  const report = opts.onError ?? ((m) => process.stderr.write(`virlow-mcp: ${m}
+`));
+  let closing = false;
+  const local = new StdioServerTransport(
+    opts.stdin,
+    opts.stdout
+  );
+  const remote = new StreamableHTTPClientTransport(new URL(opts.url), {
+    requestInit: { headers: { authorization: `Bearer ${opts.token}` } }
   });
-  await new Promise((resolve, reject) => {
-    httpServer.once("error", reject);
-    httpServer.listen(opts.port ?? 0, host, () => {
-      httpServer.removeListener("error", reject);
-      resolve();
+  local.onmessage = (message) => {
+    remote.send(message).catch((err) => {
+      const text = err instanceof Error ? err.message : String(err);
+      if (!closing) report(`could not reach the desktop app at ${opts.url}: ${text}`);
+      if ("id" in message && message.id !== void 0 && "method" in message) {
+        void local.send({
+          jsonrpc: "2.0",
+          id: message.id,
+          error: { code: -32e3, message: `Virlow desktop app unreachable: ${text}` }
+        });
+      }
     });
-  });
-  const address = httpServer.address();
-  const port = typeof address === "object" && address !== null ? address.port : 0;
+  };
+  remote.onmessage = (message) => {
+    local.send(message).catch((err) => {
+      report(`stdio write failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  };
+  local.onclose = () => {
+    closing = true;
+    void remote.close();
+  };
+  remote.onerror = (err) => {
+    if (!closing) report(err.message);
+  };
+  await remote.start();
+  await local.start();
   return {
-    port,
-    host,
-    close: () => new Promise((resolve) => {
-      httpServer.close(() => resolve());
-    })
+    close: async () => {
+      closing = true;
+      await remote.close();
+      await local.close();
+    }
   };
 }
 
@@ -2127,6 +2211,17 @@ async function main() {
 `);
     return;
   }
+  const connectUrl = flagValue("connect");
+  if (connectUrl !== void 0) {
+    const tokenFile = flagValue("token-file");
+    if (!tokenFile) {
+      throw new Error("--connect needs --token-file <path> (the Virlow app writes this file for you)");
+    }
+    const token = (await readFile3(tokenFile, "utf8")).trim();
+    if (!token) throw new Error(`token file is empty: ${tokenFile}`);
+    await runConnectBridge({ url: connectUrl, token });
+    return;
+  }
   const apiUrl = process.env.VIRLOW_API_URL ?? "https://api.virlow.com";
   const modelCacheDir = path4.join(os2.homedir(), ".virlow-mcp", "models");
   const embeddingCacheDir = path4.join(os2.homedir(), ".virlow-mcp", "cache");
@@ -2142,7 +2237,7 @@ async function main() {
     const host = flagValue("host") ?? "127.0.0.1";
     const running = await startHttpServer({
       makeServer: () => buildServer2({ ...serverOpts, services }).server,
-      token,
+      authorize: (bearer) => tokenMatches(bearer, token) ? { clientId: "cli" } : null,
       host,
       ...portFlag !== void 0 ? { port: Number(portFlag) } : {}
     });
@@ -2161,7 +2256,7 @@ async function main() {
     );
     return;
   }
-  const transport = new StdioServerTransport();
+  const transport = new StdioServerTransport2();
   await server.connect(transport);
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virlow-mcp",
-  "version": "3.17.1",
+  "version": "3.19.0",
   "description": "Local MCP server for Virlow Secure Notes: end-to-end-encrypted AI memories and notes for Cursor, Claude, Codex, and any MCP client.",
   "license": "MIT",
   "type": "module",
@@ -34,9 +34,9 @@
     "esbuild": "^0.25.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0",
-    "@batalabs/virlow-crypto": "3.17.1",
-    "@batalabs/virlow-memory": "3.17.1",
-    "@batalabs/virlow-mcp-core": "3.17.1"
+    "@batalabs/virlow-crypto": "3.19.0",
+    "@batalabs/virlow-memory": "3.19.0",
+    "@batalabs/virlow-mcp-core": "3.19.0"
   },
   "scripts": {
     "build": "node build.mjs",