@echomem/mcp 1.4.20 → 1.4.21

package/dist/setup.js

@@ -2,15 +2,15 @@
  * `echomem-mcp init | setup | login | unlock | status | logout` — onboarding for the local bridge (spec §8).
  *
  * Design goals from the spec:
- *   - One command → one browser approval → one reload.
+ *   - One command → one local browser setup → one reload.
  *   - Both secrets (API token + encryption key) ride a single browser flow and land in the local
  *     keystore — never in the client's MCP config, never in the agent's chat context.
  *   - Re-unlock after the key's TTL is one step, not a re-setup.
  *
- * The browser flow posts `{ token, key? }` to a localhost callback this process opens. The
- * "connect device" web page that drives it is the one piece that lives in the web app (not here);
- * until it ships, the same flow is fully usable via the manual flags (`--token`, `--key`,
- * `--passphrase`), which is also the documented headless/SSH path (spec §8).
+ * The browser flow stays on a localhost setup page. That local page collects email OTP consent and
+ * an encryption passphrase, while this process asks the hosted API to send/verify OTP and mint a
+ * device token. Secrets land in the local keystore — never in the client's MCP config, never in
+ * the agent's chat context.
  */
 import http from "node:http";
 import { randomUUID } from "node:crypto";
@@ -23,7 +23,7 @@ import readline from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import axios from "axios";
 import { KeyStore } from "./keystore.js";
-import { fetchEncryptionConfig, deriveAndVerifyKey, verifyKeyB64 } from "./encryption.js";
+import { fetchEncryptionConfig, deriveAndVerifyKey, setupNewEncryptionKey, verifyKeyB64 } from "./encryption.js";
 import { collect, runReport, buildStatsPayload } from "./report.js";
 import { cmdMigrate, applyAccountImportStatus, applyFastAccountImportStatus, discoverMigratableFastDiscovery, discoverMigratableSessions, discoverPendingSessionsTargeted, estimateMigrationEta, fetchProcessedImportKeys, isImportStatusUnsupported, markAccountImportStatusFailed, markAccountImportStatusUnavailable, markFastAccountImportStatusUnavailable, startMigration, summarizeFastMigratableDiscovery, MIGRATE_CONCURRENCY, } from "./migrate.js";
 import { syncCodexUsage } from "./codex-sync.js";
@@ -33,10 +33,8 @@ import { repoLabel, validateForensicReportForSetup } from "./forensics.js";
 import { installHooks } from "./hud/hooks.js";
 import { MCP_PACKAGE_LABEL, MCP_PACKAGE_NAME, MCP_PACKAGE_VERSION, MCP_UPDATE_ALL_COMMAND, MCP_UPDATE_COMMAND } from "./package-metadata.js";
 import { checkLatestUpdateStatus, compareSemver, readCachedUpdateStatus } from "./update-check.js";
-// The hosted connect-device page is now only the account-auth/token courier. The dashboard itself is
-// served by this localhost bridge, where local logs and processed/unprocessed counts never leave the
-// device unless the user explicitly starts migration. Override the hosted auth origin with ECHO_WEB_URL.
-const WEB_URL = (process.env.ECHO_WEB_URL || "https://yeahecho.com").replace(/\/$/, "");
+// The setup dashboard, account login, and encryption passphrase entry are all served by this
+// localhost bridge. The hosted API only sends OTP email, verifies the code, and mints a device token.
 const API_BASE_URL = (process.env.ECHO_API_BASE_URL || "https://echo-mem-chrome.vercel.app").replace(/\/$/, "");
 const PRICING_URL = (process.env.ECHO_PRICING_URL || "https://echoknows.com/pricing").replace(/\/$/, "");
 const CODEX_SKILL_NAMES = [
@@ -1191,9 +1189,9 @@ function publicRunningForensicProgress(value) {
     };
 }
 /**
- * Start the persistent localhost bridge used by the connect-device page. It accepts the token,
- * serves local Wrapped stats, and holds the /migrate response until cmdLogin has created a cloud
- * import session.
+ * Start the persistent localhost bridge used by the setup page. It sends/verifies OTP through the
+ * hosted API, accepts the local passphrase, serves local Wrapped stats, and holds the /migrate
+ * response until cmdLogin has created a cloud import session.
  */
 export function startCallbackServer(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 15 * 60_000;
@@ -1211,6 +1209,7 @@ export function startCallbackServer(opts = {}) {
         let authUrl = "";
         let switchAccountUrl = "";
         let connected = false;
+        let pendingLocalAuth = null;
         let reportConsentGranted = opts.requireReportConsent !== true;
         let progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
         let migrateStarted = false;
@@ -1227,6 +1226,26 @@ export function startCallbackServer(opts = {}) {
         const checkNonce = (nonce) => !expectedNonce || nonce === expectedNonce;
         const text = (res, status, body = "") => res.writeHead(status, { "Content-Type": "text/plain" }).end(body);
         const json = (res, status, body) => res.writeHead(status, { "Content-Type": "application/json" }).end(JSON.stringify(body));
+        const revokeDeviceToken = async (token) => {
+            try {
+                await authedAxios(token).post("/api/extension/mcp/local-auth/revoke-device", {}, { timeout: 10_000 });
+                return true;
+            }
+            catch (error) {
+                console.error(`Could not revoke incomplete local login: ${error instanceof Error ? error.message : String(error)}`);
+                return false;
+            }
+        };
+        const revokePendingLocalAuth = async () => {
+            const pending = pendingLocalAuth;
+            pendingLocalAuth = null;
+            if (!pending)
+                return false;
+            return revokeDeviceToken(pending.token);
+        };
+        const completeDeviceLogin = async (token) => {
+            await authedAxios(token).post("/api/extension/mcp/local-auth/complete-device", {}, { timeout: 10_000 });
+        };
         const close = () => {
             if (timer)
                 clearTimeout(timer);
@@ -1234,6 +1253,7 @@ export function startCallbackServer(opts = {}) {
             if (closed)
                 return;
             closed = true;
+            void revokePendingLocalAuth();
             server.close();
             for (const socket of sockets)
                 socket.destroy();
@@ -1245,7 +1265,7 @@ export function startCallbackServer(opts = {}) {
             const waitMs = onToken.settled() ? dashboardTimeoutMs : timeoutMs;
             timer = setTimeout(() => {
                 if (!onToken.settled()) {
-                    onToken.reject(new Error(`browser approval did not finish in ${approvalTimeoutLabel}`));
+                    onToken.reject(new Error(`local setup did not finish in ${approvalTimeoutLabel}`));
                 }
                 else if (!decision.settled()) {
                     decision.resolve("timeout");
@@ -1265,7 +1285,7 @@ export function startCallbackServer(opts = {}) {
             }
             if (!token)
                 return void text(res, 400, "missing token");
-            console.log(`[${new Date().toISOString()}] Browser approval callback received.`);
+            console.log(`[${new Date().toISOString()}] Device token callback received.`);
             const firstToken = !onToken.settled();
             connected = true;
             const setupPath = `/setup?nonce=${encodeURIComponent(nonce || "")}&connected=1`;
@@ -1281,12 +1301,172 @@ export function startCallbackServer(opts = {}) {
             }
             armTimeout();
         };
+        const rejectIfLocalAuthBlocked = (res, nonce) => {
+            if (!checkNonce(nonce)) {
+                text(res, 403, "bad nonce");
+                return true;
+            }
+            if (opts.requireReportConsent === true && !reportConsentGranted) {
+                json(res, 403, {
+                    error: "LOCAL_HISTORY_CONSENT_REQUIRED",
+                    message: "Allow local history access in the setup page before connecting EchoMem.",
+                });
+                return true;
+            }
+            return false;
+        };
+        const resolveLocalToken = (token, key) => {
+            const firstToken = !onToken.settled();
+            connected = true;
+            pendingLocalAuth = null;
+            const callbackToken = { token, key };
+            if (firstToken) {
+                onToken.resolve(callbackToken);
+            }
+            else if (tokenRefreshHandler) {
+                Promise.resolve(tokenRefreshHandler(callbackToken)).catch((e) => {
+                    console.error(`Could not refresh local login: ${e instanceof Error ? e.message : String(e)}`);
+                });
+            }
+            armTimeout();
+        };
+        const handleLocalSendOtp = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const email = normalizeEmail(body.email);
+            if (!validEmail(email))
+                return void json(res, 400, { ok: false, error: "Invalid email address" });
+            if (!acceptedLocalTerms(body)) {
+                return void json(res, 400, {
+                    ok: false,
+                    error: "Confirm your age and accept Echo's terms before continuing.",
+                });
+            }
+            try {
+                const response = await apiAxios().post("/api/extension/mcp/local-auth/send-otp", {
+                    email,
+                    acceptedTerms: true,
+                    ageConfirmed: true,
+                }, { timeout: 10_000 });
+                json(res, 200, { ok: true, email: asString(response.data?.email) || email });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to send verification code");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
+        const handleLocalVerifyOtp = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const email = normalizeEmail(body.email);
+            const otp = asString(body.otp)?.trim() || "";
+            if (!validEmail(email))
+                return void json(res, 400, { ok: false, error: "Invalid email address" });
+            if (!/^\d{6}$/.test(otp)) {
+                return void json(res, 400, { ok: false, error: "Enter the 6-digit verification code." });
+            }
+            if (!acceptedLocalTerms(body)) {
+                return void json(res, 400, {
+                    ok: false,
+                    error: "Confirm your age and accept Echo's terms before continuing.",
+                });
+            }
+            try {
+                const response = await apiAxios().post("/api/extension/mcp/local-auth/verify-otp", {
+                    email,
+                    otp,
+                    acceptedTerms: true,
+                    ageConfirmed: true,
+                }, { timeout: 15_000 });
+                const token = asString(response.data?.api_key);
+                const userId = asString(response.data?.user_id);
+                if (!token || !userId) {
+                    return void json(res, 502, { ok: false, error: "The EchoMem API did not return a device token." });
+                }
+                let config;
+                try {
+                    config = await fetchEncryptionConfig(authedAxios(token));
+                }
+                catch (error) {
+                    await revokeDeviceToken(token);
+                    throw error;
+                }
+                await revokePendingLocalAuth();
+                pendingLocalAuth = {
+                    token,
+                    userId,
+                    email: asString(response.data?.email) || email,
+                    mode: config.enabled ? "unlock" : "setup",
+                    config: config.enabled ? config : undefined,
+                    expiresAtMs: Date.now() + 10 * 60_000,
+                };
+                json(res, 200, {
+                    ok: true,
+                    stage: "passphrase",
+                    mode: pendingLocalAuth.mode,
+                    email: pendingLocalAuth.email,
+                });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to verify code");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
+        const handleLocalPassphrase = async (res, body) => {
+            if (rejectIfLocalAuthBlocked(res, asString(body.nonce)))
+                return;
+            const passphrase = typeof body.passphrase === "string" ? body.passphrase : "";
+            if (passphrase.length < 4) {
+                return void json(res, 400, { ok: false, error: "Enter an encryption passphrase with at least 4 characters." });
+            }
+            if (!pendingLocalAuth || pendingLocalAuth.expiresAtMs <= Date.now()) {
+                await revokePendingLocalAuth();
+                return void json(res, 409, {
+                    ok: false,
+                    error: "This local login expired. Send a new verification code.",
+                    reset: true,
+                });
+            }
+            try {
+                if (pendingLocalAuth.mode === "unlock") {
+                    const key = pendingLocalAuth.config
+                        ? await deriveAndVerifyKey(passphrase, pendingLocalAuth.config)
+                        : null;
+                    if (!key)
+                        return void json(res, 400, { ok: false, error: "Incorrect encryption passphrase." });
+                    await completeDeviceLogin(pendingLocalAuth.token);
+                    resolveLocalToken(pendingLocalAuth.token, key);
+                    return void json(res, 200, { ok: true, connected: true });
+                }
+                const setup = await setupNewEncryptionKey(passphrase);
+                await authedAxios(pendingLocalAuth.token).post("/api/extension/account/encryption", {
+                    salt: setup.saltBase64,
+                    verification: setup.verification,
+                    iterations: setup.iterations,
+                }, {
+                    timeout: 10_000,
+                    headers: { "X-Encryption-Key": setup.keyBase64 },
+                });
+                pendingLocalAuth.mode = "unlock";
+                pendingLocalAuth.config = {
+                    enabled: true,
+                    salt: setup.saltBase64,
+                    verification: setup.verification,
+                    iterations: setup.iterations,
+                };
+                await completeDeviceLogin(pendingLocalAuth.token);
+                resolveLocalToken(pendingLocalAuth.token, setup.keyBase64);
+                json(res, 200, { ok: true, connected: true });
+            }
+            catch (error) {
+                const detail = publicAxiosError(error, "Failed to unlock encrypted memory");
+                json(res, detail.status, { ok: false, error: detail.message });
+            }
+        };
         server = http.createServer((req, res) => {
             res.setHeader("Access-Control-Allow-Origin", "*");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type");
             res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-            // Let the HTTPS connect-device page reach this localhost server (Chrome Private Network Access).
-            res.setHeader("Access-Control-Allow-Private-Network", "true");
             if (req.method === "OPTIONS")
                 return void res.writeHead(204).end();
             const url = new URL(req.url || "/", "http://127.0.0.1");
@@ -1330,6 +1510,7 @@ export function startCallbackServer(opts = {}) {
                         authUrl,
                         switchAccountUrl: switchAccountUrl || authUrl,
                         localOnly: true,
+                        localAuth: true,
                         workspacePath: process.cwd(),
                         consentRequired: opts.requireReportConsent === true,
                         consentGranted: reportConsentGranted,
@@ -1385,6 +1566,42 @@ export function startCallbackServer(opts = {}) {
                     handleCallback(res, asString(body.token), asString(body.key), asString(body.nonce));
                     return;
                 }
+                if (route === "/local-auth/send-otp" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalSendOtp(res, body);
+                    return;
+                }
+                if (route === "/local-auth/verify-otp" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalVerifyOtp(res, body);
+                    return;
+                }
+                if (route === "/local-auth/passphrase" && req.method === "POST") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        text(res, 400, "bad json");
+                        return;
+                    }
+                    await handleLocalPassphrase(res, body);
+                    return;
+                }
                 if (route === "/stats" && req.method === "GET") {
                     if (!checkNonce(url.searchParams.get("nonce") || undefined))
                         return void text(res, 403, "bad nonce");
@@ -1599,10 +1816,17 @@ export function startCallbackServer(opts = {}) {
                         /* already logged out locally */
                     }
                     connected = false;
+                    const revokedPendingCredential = await revokePendingLocalAuth();
                     stats = null;
                     migrateStarted = false;
                     progress = { status: "idle", total: 0, completed: 0, running: 0, queued: 0, failed: 0, extracted: 0 };
-                    json(res, 200, { ok: true, authUrl, switchAccountUrl: switchAccountUrl || authUrl, localOnly: true });
+                    json(res, 200, {
+                        ok: true,
+                        authUrl,
+                        switchAccountUrl: switchAccountUrl || authUrl,
+                        localOnly: true,
+                        revokedPendingCredential,
+                    });
                     Promise.resolve()
                         .then(() => logoutHandler?.())
                         .catch((e) => {
@@ -1726,6 +1950,34 @@ function authedAxios(token) {
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
     });
 }
+function apiAxios() {
+    return axios.create({
+        baseURL: API_BASE_URL,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function normalizeEmail(value) {
+    return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function validEmail(value) {
+    return value.length > 0 && value.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+function acceptedLocalTerms(body) {
+    return body.acceptedTerms === true && body.ageConfirmed === true;
+}
+function publicAxiosError(error, fallback) {
+    if (axios.isAxiosError(error)) {
+        const data = error.response?.data;
+        const status = typeof error.response?.status === "number" ? error.response.status : 500;
+        const message = typeof data?.error === "string"
+            ? data.error
+            : typeof data?.message === "string"
+                ? data.message
+                : fallback;
+        return { message, status };
+    }
+    return { message: error instanceof Error ? error.message : fallback, status: 500 };
+}
 function formatVerificationError(error) {
     if (axios.isAxiosError(error)) {
         const status = typeof error.response?.status === "number" ? error.response.status : null;
@@ -2039,9 +2291,9 @@ async function cmdLogin(flags) {
             process.exitCode = 1;
         return ok;
     }
-    // Browser path: open a localhost dashboard. It briefly leaves for hosted auth, then returns here
-    // after the web page has delivered the token+key to the callback. The nonce gates every local route.
-    console.log("Opening your browser to approve this device…");
+    // Browser path: open a localhost dashboard. Login, legal confirmation, and encryption
+    // passphrase entry all happen through this local bridge. The nonce gates every local route.
+    console.log("Opening your browser to connect this device locally…");
     const devPortRaw = typeof flags["dev-port"] === "string" ? Number(flags["dev-port"]) : undefined;
     if (devPortRaw !== undefined && (!Number.isInteger(devPortRaw) || devPortRaw < 1024 || devPortRaw > 65535)) {
         throw new Error("--dev-port must be an integer between 1024 and 65535");
@@ -2113,18 +2365,10 @@ async function cmdLogin(flags) {
             startForensicScan();
         },
     });
-    const callbackUrl = `http://127.0.0.1:${srv.port}/callback`;
     const localSetupUrl = `http://127.0.0.1:${srv.port}/setup?nonce=${nonce}`;
-    const connectUrl = `${WEB_URL}/connect-device?callback=${encodeURIComponent(callbackUrl)}&nonce=${nonce}&return_to=${encodeURIComponent(localSetupUrl)}`;
-    const switchAccountUrl = new URL(connectUrl);
-    // The hosted connect-device page should clear its own Supabase/browser session before minting
-    // the localhost token when this hint is present. Localhost cannot safely clear yeahecho.com auth.
-    switchAccountUrl.searchParams.set("force_signout", "1");
-    switchAccountUrl.searchParams.set("prompt", "login");
-    srv.setAuthUrl(connectUrl, switchAccountUrl.toString());
     openBrowser(localSetupUrl);
     console.log(`If it didn't open, visit:\n  ${localSetupUrl}\n`);
-    console.log("Waiting for browser approval for up to 15 minutes…");
+    console.log("Waiting for local setup for up to 15 minutes…");
     const startForensicScan = () => {
         if (forensicScanStarted || forensicConsent !== "allowed")
             return;
@@ -2880,7 +3124,7 @@ Usage:
   echomem-mcp update --all          Repoint detected clients to this installed bridge; no login/browser
   echomem-mcp update --client X     Repoint one MCP client; no login/browser
   echomem-mcp setup --with-hud      Configure MCP, then launch the EchoMem context HUD
-  echomem-mcp login                 Approve this device in the browser (or --token/--passphrase)
+  echomem-mcp login                 Connect this device in the local browser page (or --token/--passphrase)
   echomem-mcp unlock                Privately unlock the vault on this trusted device
   echomem-mcp lock                  Remove the local vault key while keeping the device login
   echomem-mcp status                Show token/key/clients

package/dist/v1-contract.js

@@ -117,7 +117,7 @@ export function listToolSpecs(opts = {}) {
     return [
         {
             name: canonicalToolNames.search,
-            description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled. ${recallPlanNote} ${searchBillingReplyInstruction}${mapSection}\nReturns the ranked memories; set includeAnswer=true only if you need the legacy synthesized answer. Current time: ${currentTime}.${updateSection}`),
+            description: withMcpVersion(`Recall the user's prior decisions, preferences, and project context from EchoMem — their long-term memory across ALL their AI tools, not just this session. Use it instead of re-deriving or re-asking what the user already settled. ${recallPlanNote} ${searchBillingReplyInstruction}${mapSection}\nReturns ranked memories only; the MCP host model writes the final answer. Current time: ${currentTime}.${updateSection}`),
             inputSchema: {
                 type: "object",
                 properties: {
@@ -125,11 +125,6 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
-                    includeAnswer: {
-                        type: "boolean",
-                        default: false,
-                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
-                    },
                     triggerMessage: {
                         type: "string",
                         description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",
@@ -148,11 +143,6 @@ export function listToolSpecs(opts = {}) {
                     limit: { type: "number", default: 10 },
                     threshold: { type: "number", default: 0.1 },
                     timeFrameDays: { type: "number" },
-                    includeAnswer: {
-                        type: "boolean",
-                        default: false,
-                        description: "Default false: return only retrieved memories and skip answer generation. Set true for the legacy synthesized recall answer.",
-                    },
                     triggerMessage: {
                         type: "string",
                         description: "Optional: the user's message that caused this recall. EchoMem stores only a redacted analytics preview and hash.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echomem/mcp",
-  "version": "1.4.20",
+  "version": "1.4.21",
   "description": "EchoMem MCP bridge: cloud-first memory tools, local context HUD, and the Agent Doctor workspace forensics report (cost ledger + 3D repo city)",
   "main": "dist/index.js",
   "type": "module",
@@ -22,7 +22,11 @@
     "dev": "node dist/index.js",
     "smoke": "node smoke.mjs",
     "preview:extraction": "npm run build && node scripts/preview-extraction.mjs",
-    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/hud.test.mjs",
+    "test:artifact": "npm run build && node test/package-artifact.test.mjs",
+    "test:registry": "node test/registry-artifact.test.mjs",
+    "test:registry-ui": "npm run build && node test/registry-ui.test.mjs",
+    "test:ui": "npm run build && node test/setup-ui.test.mjs",
+    "test": "npm run build && node test/local-data-paths.test.mjs && node test/crypto.test.mjs && node test/integration.test.mjs && node test/local-auth.test.mjs && node test/retrieval-only.test.mjs && node test/no-restart.test.mjs && node test/report.test.mjs && node test/forensics.test.mjs && node test/canonical-golden.test.mjs && node test/tools.test.mjs && node test/update-check.test.mjs && node test/delete.test.mjs && node test/low-touch-tools.test.mjs && node test/migrate.test.mjs && node test/restart-recovery.test.mjs && node test/hud.test.mjs",
     "prepack": "npm run build && node scripts/bundle-city.mjs"
   },
   "dependencies": {