npm - @lifeaitools/clauth - Versions diffs - 0.4.0 → 0.5.0 - Mend

@lifeaitools/clauth 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/.clauth-skill/SKILL.md +184 -184
package/.clauth-skill/references/keys-guide.md +270 -270
package/.clauth-skill/references/operator-guide.md +148 -148
package/README.md +125 -125
package/cli/api.js +113 -113
package/cli/commands/install.js +291 -265
package/cli/commands/scrub.js +231 -231
package/cli/commands/serve.js +511 -1
package/cli/commands/uninstall.js +164 -164
package/cli/fingerprint.js +91 -91
package/cli/index.js +5 -1
package/install.ps1 +44 -44
package/install.sh +38 -38
package/package.json +54 -54
package/scripts/bin/bootstrap-linux +0 -0
package/scripts/bin/bootstrap-macos +0 -0
package/scripts/bootstrap.cjs +43 -43
package/scripts/build.sh +45 -45
package/supabase/functions/auth-vault/index.ts +235 -235
package/supabase/migrations/001_clauth_schema.sql +103 -103
package/supabase/migrations/002_vault_helpers.sql +90 -90
package/supabase/migrations/20260317_lockout.sql +26 -26

package/cli/commands/serve.js CHANGED Viewed

@@ -41,6 +41,15 @@ function isProcessAlive(pid) {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
+function openBrowser(url) {
+  try {
+    const cmd = os.platform() === "win32" ? `start "" "${url}"`
+      : os.platform() === "darwin" ? `open "${url}"`
+      : `xdg-open "${url}"`;
+    execSync(cmd, { stdio: "ignore" });
+  } catch {}
+}
 // ── Dashboard HTML ───────────────────────────────────────────
 function dashboardHtml(port, whitelist) {
   return `<!DOCTYPE html>
@@ -127,6 +136,23 @@ function dashboardHtml(port, whitelist) {
   @keyframes sdot-fade{to{opacity:0}} .status-dot.fading{animation:sdot-fade 1.5s forwards}
   .error-bar{background:#7f1d1d;color:#fca5a5;border:1px solid #991b1b;padding:10px 14px;border-radius:8px;margin-bottom:1rem;display:none;font-size:.85rem}
   .loading{color:#64748b;font-style:italic}
+  .tunnel-panel{background:#0f1d2d;border:1px solid #1e3a5f;border-radius:8px;padding:1rem 1.25rem;margin-bottom:1.25rem;display:flex;align-items:center;gap:12px;flex-wrap:wrap}
+  .tunnel-dot{width:10px;height:10px;border-radius:50%;flex-shrink:0}
+  .tunnel-dot.off{background:#64748b}
+  .tunnel-dot.starting{background:#f59e0b;animation:pulse 1s infinite}
+  .tunnel-dot.on{background:#22c55e;animation:pulse 2s infinite}
+  .tunnel-dot.err{background:#ef4444}
+  .tunnel-label{font-size:.85rem;color:#94a3b8;flex:1}
+  .tunnel-label strong{color:#e2e8f0}
+  .tunnel-url{font-family:'Courier New',monospace;font-size:.78rem;color:#60a5fa;word-break:break-all}
+  .tunnel-url a{color:#60a5fa;text-decoration:none}
+  .tunnel-url a:hover{text-decoration:underline}
+  .btn-claude{background:linear-gradient(135deg,#d97706,#f59e0b);color:#0a0f1a;padding:8px 18px;font-size:.85rem;border-radius:7px;border:none;cursor:pointer;font-weight:700;letter-spacing:.3px;transition:all .15s;white-space:nowrap}
+  .btn-claude:hover{filter:brightness(1.1);transform:translateY(-1px)}
+  .btn-claude:disabled{opacity:.4;cursor:not-allowed;transform:none;filter:none}
+  .btn-tunnel-stop{background:#1e293b;color:#f87171;border:1px solid #334155;padding:6px 12px;font-size:.8rem;border-radius:6px;cursor:pointer;font-weight:500}
+  .btn-tunnel-stop:hover{background:#2d1f1f;border-color:#f87171}
+  .tunnel-err{font-size:.78rem;color:#f87171;width:100%;margin-top:4px}
   .footer{margin-top:2rem;font-size:.75rem;color:#475569;text-align:center}
   .oauth-fields{display:flex;flex-direction:column;gap:8px;margin-bottom:8px}
   .oauth-field{display:flex;flex-direction:column;gap:3px}
@@ -189,6 +215,17 @@ function dashboardHtml(port, whitelist) {
     </div>
   </div>
+  <div class="tunnel-panel" id="tunnel-panel">
+    <div class="tunnel-dot off" id="tunnel-dot"></div>
+    <div class="tunnel-label" id="tunnel-label">
+      <strong>claude.ai MCP</strong> — checking tunnel…
+    </div>
+    <button class="btn-check" id="btn-tunnel-test" style="display:none;padding:6px 12px;font-size:.8rem" onclick="testTunnel()">Test</button>
+    <button class="btn-claude" id="btn-claude" disabled onclick="openClaude()">Connect claude.ai</button>
+    <button class="btn-tunnel-stop" id="btn-tunnel-toggle" style="display:none" onclick="toggleTunnel()">Stop</button>
+    <div class="tunnel-err" id="tunnel-err" style="display:none"></div>
+  </div>
   <div id="grid" class="grid"><p class="loading">Loading services…</p></div>
   <div class="footer">localhost:${port} · 127.0.0.1 only · 3-strike lockout</div>
 </div>
@@ -303,6 +340,7 @@ function showMain(ping) {
     document.getElementById("s-fails").textContent =
       ping.failures + "/" + (ping.failures + ping.failures_remaining);
   }
+  pollTunnel();
 }
 // ── Unlock ──────────────────────────────────
@@ -562,6 +600,22 @@ async function checkAll() {
     const results = r.results || {};
     for (const [name, result] of Object.entries(results)) {
+      if (name === "__tunnel__") {
+        // Update tunnel panel with health result
+        const tDot = document.getElementById("tunnel-dot");
+        const tLabel = document.getElementById("tunnel-label");
+        if (result.ok) {
+          tDot.className = "tunnel-dot on";
+          tLabel.innerHTML = '<strong>claude.ai MCP</strong> — tunnel healthy';
+        } else if (result.running) {
+          tDot.className = "tunnel-dot starting";
+          tLabel.innerHTML = '<strong>claude.ai MCP</strong> — ' + (result.reason || "starting…");
+        } else {
+          tDot.className = "tunnel-dot err";
+          tLabel.innerHTML = '<strong>claude.ai MCP</strong> — ' + (result.reason || "not running");
+        }
+        continue;
+      }
       const dot = document.getElementById("sdot-" + name);
       if (!dot) continue;
       if (result.ok) {
@@ -639,6 +693,140 @@ document.addEventListener("DOMContentLoaded", () => {
   });
 });
+// ── Tunnel management ───────────────────────
+let tunnelPollTimer = null;
+async function pollTunnel() {
+  if (tunnelPollTimer) clearInterval(tunnelPollTimer);
+  await updateTunnelUI();
+  // Poll every 3s until URL is found, then slow to 10s
+  tunnelPollTimer = setInterval(async () => {
+    const state = await updateTunnelUI();
+    if (state === "connected") {
+      clearInterval(tunnelPollTimer);
+      tunnelPollTimer = setInterval(updateTunnelUI, 10000);
+    }
+  }, 3000);
+}
+async function updateTunnelUI() {
+  const dot   = document.getElementById("tunnel-dot");
+  const label = document.getElementById("tunnel-label");
+  const btn   = document.getElementById("btn-claude");
+  const togBtn = document.getElementById("btn-tunnel-toggle");
+  const errEl = document.getElementById("tunnel-err");
+  try {
+    const t = await fetch(BASE + "/tunnel").then(r => r.json());
+    errEl.style.display = "none";
+    if (t.error) {
+      dot.className = "tunnel-dot err";
+      label.innerHTML = '<strong>claude.ai MCP</strong> — ' + t.error;
+      btn.disabled = true;
+      togBtn.style.display = "none";
+      togBtn.textContent = "Start Tunnel";
+      togBtn.onclick = () => toggleTunnel("start");
+      togBtn.style.display = "inline-block";
+      return "error";
+    }
+    if (t.running && t.url && t.url.startsWith("http")) {
+      dot.className = "tunnel-dot on";
+      label.innerHTML = '<strong>claude.ai MCP</strong> — <span class="tunnel-url"><a href="' + t.sseUrl + '" target="_blank">' + t.sseUrl + '</a></span>';
+      btn.disabled = false;
+      document.getElementById("btn-tunnel-test").style.display = "inline-block";
+      togBtn.textContent = "Stop Tunnel";
+      togBtn.onclick = () => toggleTunnel("stop");
+      togBtn.style.display = "inline-block";
+      return "connected";
+    }
+    if (t.running) {
+      dot.className = "tunnel-dot starting";
+      label.innerHTML = '<strong>claude.ai MCP</strong> — starting tunnel…';
+      btn.disabled = true;
+      togBtn.textContent = "Stop Tunnel";
+      togBtn.onclick = () => toggleTunnel("stop");
+      togBtn.style.display = "inline-block";
+      return "starting";
+    }
+    // Not running
+    dot.className = "tunnel-dot off";
+    label.innerHTML = '<strong>claude.ai MCP</strong> — tunnel not running';
+    btn.disabled = true;
+    togBtn.textContent = "Start Tunnel";
+    togBtn.onclick = () => toggleTunnel("start");
+    togBtn.style.display = "inline-block";
+    return "stopped";
+  } catch {
+    dot.className = "tunnel-dot off";
+    label.innerHTML = '<strong>claude.ai MCP</strong> — unable to reach daemon';
+    btn.disabled = true;
+    togBtn.style.display = "none";
+    return "error";
+  }
+}
+async function toggleTunnel(action) {
+  const togBtn = document.getElementById("btn-tunnel-toggle");
+  togBtn.disabled = true; togBtn.textContent = "…";
+  try {
+    await fetch(BASE + "/tunnel", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action })
+    });
+    // Wait a beat for tunnel to start/stop, then refresh
+    setTimeout(updateTunnelUI, action === "start" ? 5000 : 500);
+  } catch {} finally {
+    togBtn.disabled = false;
+  }
+}
+async function testTunnel() {
+  const btn = document.getElementById("btn-tunnel-test");
+  const dot = document.getElementById("tunnel-dot");
+  const label = document.getElementById("tunnel-label");
+  btn.disabled = true; btn.textContent = "Testing…";
+  dot.className = "tunnel-dot starting";
+  try {
+    const r = await fetch(BASE + "/tunnel/test").then(r => r.json());
+    if (r.ok) {
+      dot.className = "tunnel-dot on";
+      label.innerHTML = '<strong>claude.ai MCP</strong> — <span style="color:#4ade80">PASS</span> ' +
+        r.latencyMs + 'ms roundtrip · SSE ' + (r.sseReachable ? 'reachable' : 'unreachable') +
+        ' · <span class="tunnel-url"><a href="' + r.sseUrl + '" target="_blank">' + r.sseUrl + '</a></span>';
+    } else {
+      dot.className = "tunnel-dot err";
+      label.innerHTML = '<strong>claude.ai MCP</strong> — <span style="color:#f87171">FAIL</span> ' + (r.reason || "unknown error");
+    }
+  } catch (e) {
+    dot.className = "tunnel-dot err";
+    label.innerHTML = '<strong>claude.ai MCP</strong> — <span style="color:#f87171">FAIL</span> ' + e.message;
+  } finally {
+    btn.disabled = false; btn.textContent = "Test";
+  }
+}
+function openClaude() {
+  // Copy the SSE URL to clipboard and open claude.ai settings
+  fetch(BASE + "/tunnel").then(r => r.json()).then(t => {
+    if (t.sseUrl) {
+      navigator.clipboard.writeText(t.sseUrl).then(() => {
+        const btn = document.getElementById("btn-claude");
+        btn.textContent = "SSE URL copied!";
+        setTimeout(() => { btn.textContent = "Connect claude.ai"; }, 2000);
+      }).catch(() => {});
+      window.open("https://claude.ai/settings/integrations", "_blank");
+    }
+  });
+}
 boot();
 </script>
 </body>
@@ -657,6 +845,16 @@ function readBody(req) {
 // ── Server logic (shared by foreground + daemon) ─────────────
 function createServer(initPassword, whitelist, port) {
+  // Ensure Windows system tools are reachable (bash shells may lack these on PATH)
+  if (os.platform() === "win32") {
+    const sys32 = "C:\\Windows\\System32";
+    if (!process.env.PATH?.includes(sys32 + "\\Wbem")) {
+      process.env.PATH = (process.env.PATH || "") + ";" + sys32 + "\\Wbem";
+    }
+    if (!process.env.PATH?.includes(sys32 + ";") && !process.env.PATH?.endsWith(sys32)) {
+      process.env.PATH = (process.env.PATH || "") + ";" + sys32;
+    }
+  }
   const MAX_FAILS = 3;
   let failCount = 0;
   let password = initPassword || null;   // null = locked; set via POST /auth
@@ -668,6 +866,123 @@ function createServer(initPassword, whitelist, port) {
     "Access-Control-Allow-Headers": "Content-Type",
   };
+  // ── MCP SSE session tracking ──────────────────────────────
+  const sseSessions = new Map(); // sessionId → { res, initialized }
+  let sseCounter = 0;
+  function sseVault() {
+    return {
+      _pw: password,
+      get password() { return this._pw; },
+      set password(v) { this._pw = v; },
+      get machineHash() { return machineHash; },
+      whitelist,
+      failCount,
+      MAX_FAILS,
+    };
+  }
+  function sseSend(sessionRes, event, data) {
+    sessionRes.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  }
+  // ── Cloudflare Tunnel management ──────────────────────────
+  let tunnelProc = null;
+  let tunnelUrl = null;
+  let tunnelError = null;
+  async function startTunnel() {
+    if (tunnelProc) return; // already running
+    tunnelUrl = null;
+    tunnelError = null;
+    try {
+      // Named tunnel "clauth" — ingress configured in ~/.cloudflared/config.yml
+      // Falls back to quick tunnel if named tunnel fails
+      const tunnelName = "clauth";
+      const proc = spawnProc("cloudflared", ["tunnel", "run", tunnelName], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      tunnelProc = proc;
+      // cloudflared logs to stderr — parse for connection info
+      let stderrBuf = "";
+      proc.stderr.on("data", (chunk) => {
+        const text = chunk.toString();
+        stderrBuf += text;
+        // Detect connection registered (named tunnel is live)
+        if (!tunnelUrl && stderrBuf.includes("Registered tunnel connection")) {
+          // Named tunnel URL comes from config, not stderr.
+          // Read it from cloudflared config if available.
+          try {
+            const cfgPath = path.join(os.homedir(), ".cloudflared", "config.yml");
+            const cfgText = fs.readFileSync(cfgPath, "utf8");
+            const hostnameMatch = cfgText.match(/hostname:\s*(\S+)/);
+            if (hostnameMatch) {
+              tunnelUrl = hostnameMatch[1].startsWith("http") ? hostnameMatch[1] : `https://${hostnameMatch[1]}`;
+            }
+          } catch {}
+          if (!tunnelUrl) tunnelUrl = `(named tunnel "${tunnelName}" connected — check DNS)`;
+          const logLine = `[${new Date().toISOString()}] Tunnel started: ${tunnelUrl}\n`;
+          try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+        }
+        // Quick tunnel fallback: trycloudflare.com URL
+        if (!tunnelUrl) {
+          const quickMatch = stderrBuf.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+          if (quickMatch) {
+            tunnelUrl = quickMatch[0];
+            const logLine = `[${new Date().toISOString()}] Tunnel started: ${tunnelUrl}\n`;
+            try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+          }
+        }
+      });
+      proc.on("error", (err) => {
+        tunnelError = err.code === "ENOENT"
+          ? "cloudflared not found — install from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/"
+          : err.message;
+        tunnelProc = null;
+        const logLine = `[${new Date().toISOString()}] Tunnel error: ${tunnelError}\n`;
+        try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+      });
+      proc.on("exit", (code) => {
+        if (tunnelProc === proc) {
+          tunnelProc = null;
+          if (!tunnelError) tunnelError = `Tunnel exited with code ${code}`;
+          const logLine = `[${new Date().toISOString()}] Tunnel exited: code ${code}\n`;
+          try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+        }
+      });
+      // Give it a moment to start
+      await new Promise(r => setTimeout(r, 4000));
+    } catch (err) {
+      tunnelError = err.message;
+      tunnelProc = null;
+    }
+  }
+  function stopTunnel() {
+    if (tunnelProc) {
+      try { tunnelProc.kill(); } catch {}
+      tunnelProc = null;
+      tunnelUrl = null;
+      tunnelError = null;
+      const logLine = `[${new Date().toISOString()}] Tunnel stopped\n`;
+      try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+    }
+  }
+  // Auto-start tunnel if vault is already unlocked (--pw flag)
+  if (password) {
+    startTunnel().catch(() => {});
+  }
   function strike(res, code, message) {
     failCount++;
     const remaining = MAX_FAILS - failCount;
@@ -715,6 +1030,116 @@ function createServer(initPassword, whitelist, port) {
     const reqPath = url.pathname;
     const method = req.method;
+    // ── MCP SSE transport ─────────────────────────────────
+    // GET /sse — open SSE stream, receive endpoint event
+    if (method === "GET" && reqPath === "/sse") {
+      const sessionId = `ses_${++sseCounter}_${Date.now()}`;
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        ...CORS,
+      });
+      sseSessions.set(sessionId, { res, initialized: false });
+      // Send the endpoint URI the client should POST to
+      const endpoint = `/message?sessionId=${sessionId}`;
+      res.write(`event: endpoint\ndata: ${endpoint}\n\n`);
+      // Keepalive every 15s
+      const keepalive = setInterval(() => {
+        try { res.write(": keepalive\n\n"); } catch {}
+      }, 15_000);
+      // Cleanup on disconnect
+      req.on("close", () => {
+        clearInterval(keepalive);
+        sseSessions.delete(sessionId);
+        const logLine = `[${new Date().toISOString()}] SSE session closed: ${sessionId}\n`;
+        try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+      });
+      const logLine = `[${new Date().toISOString()}] SSE session opened: ${sessionId}\n`;
+      try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+      return;
+    }
+    // POST /message?sessionId=xxx — JSON-RPC over SSE
+    if (method === "POST" && reqPath === "/message") {
+      const sessionId = url.searchParams.get("sessionId");
+      const session = sessionId ? sseSessions.get(sessionId) : null;
+      if (!session) {
+        res.writeHead(404, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "Unknown or expired session" }));
+      }
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+      const id = body.id;
+      const rpcMethod = body.method;
+      // Acknowledge the POST immediately
+      res.writeHead(202, { "Content-Type": "application/json", ...CORS });
+      res.end(JSON.stringify({ ok: true }));
+      // Handle JSON-RPC methods
+      if (rpcMethod === "notifications/initialized" || rpcMethod === "initialized") {
+        session.initialized = true;
+        return;
+      }
+      if (rpcMethod === "initialize") {
+        sseSend(session.res, "message", {
+          jsonrpc: "2.0", id,
+          result: {
+            protocolVersion: "2024-11-05",
+            serverInfo: { name: "clauth", version: VERSION },
+            capabilities: { tools: {} }
+          }
+        });
+        return;
+      }
+      if (rpcMethod === "tools/list") {
+        sseSend(session.res, "message", {
+          jsonrpc: "2.0", id,
+          result: { tools: MCP_TOOLS }
+        });
+        return;
+      }
+      if (rpcMethod === "tools/call") {
+        const { name, arguments: args } = body.params || {};
+        const vault = sseVault();
+        try {
+          const result = await handleMcpTool(vault, name, args || {});
+          // Sync vault mutations back (e.g. unlock sets password)
+          password = vault.password;
+          sseSend(session.res, "message", { jsonrpc: "2.0", id, result });
+        } catch (err) {
+          sseSend(session.res, "message", {
+            jsonrpc: "2.0", id,
+            result: mcpError(`Internal error: ${err.message}`)
+          });
+        }
+        return;
+      }
+      // Unknown method
+      sseSend(session.res, "message", {
+        jsonrpc: "2.0", id,
+        error: { code: -32601, message: `Unknown method: ${rpcMethod}` }
+      });
+      return;
+    }
     // GET / — built-in web dashboard
     if (method === "GET" && reqPath === "/") {
       res.writeHead(200, { "Content-Type": "text/html", ...CORS });
@@ -734,8 +1159,36 @@ function createServer(initPassword, whitelist, port) {
       });
     }
+    // GET /tunnel — tunnel status (for dashboard polling)
+    if (method === "GET" && reqPath === "/tunnel") {
+      return ok(res, {
+        running: !!tunnelProc,
+        url: tunnelUrl,
+        sseUrl: tunnelUrl && tunnelUrl.startsWith("http") ? `${tunnelUrl}/sse` : null,
+        error: tunnelError,
+      });
+    }
+    // POST /tunnel — start or stop tunnel manually
+    if (method === "POST" && reqPath === "/tunnel") {
+      if (lockedGuard(res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+      if (body.action === "stop") {
+        stopTunnel();
+        return ok(res, { ok: true, running: false });
+      }
+      // start
+      await startTunnel();
+      return ok(res, { ok: true, running: !!tunnelProc, url: tunnelUrl, error: tunnelError });
+    }
     // GET /shutdown (for daemon stop)
     if (method === "GET" && reqPath === "/shutdown") {
+      stopTunnel();
       ok(res, { ok: true, message: "shutting down" });
       removePid();
       setTimeout(() => process.exit(0), 100);
@@ -811,6 +1264,8 @@ function createServer(initPassword, whitelist, port) {
         password = pw;   // unlock — store in process memory only
         const logLine = `[${new Date().toISOString()}] Vault unlocked\n`;
         try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+        // Auto-start Cloudflare Tunnel for claude.ai MCP
+        startTunnel().catch(() => {});
         return ok(res, { ok: true, locked: false });
       } catch {
         // Wrong password — not a lockout strike, just a UI auth attempt
@@ -822,6 +1277,7 @@ function createServer(initPassword, whitelist, port) {
     // POST /lock — clear password from memory
     if (method === "POST" && reqPath === "/lock") {
       password = null;
+      stopTunnel();
       const logLine = `[${new Date().toISOString()}] Vault locked\n`;
       try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
       return ok(res, { ok: true, locked: true });
@@ -879,12 +1335,62 @@ function createServer(initPassword, whitelist, port) {
             results[svc.name] = { ok: false, reason: e.message };
           }
         }
+        // Include tunnel health in check-all
+        const tunnelHealth = { running: !!tunnelProc, url: tunnelUrl, error: tunnelError };
+        if (tunnelProc && tunnelUrl && tunnelUrl.startsWith("http")) {
+          try {
+            const resp = await fetch(tunnelUrl + "/ping", { signal: AbortSignal.timeout(5000) });
+            const data = await resp.json();
+            tunnelHealth.ok = data.status === "ok";
+            tunnelHealth.latencyMs = null; // could measure but ping is fast
+          } catch (e) {
+            tunnelHealth.ok = false;
+            tunnelHealth.reason = e.message;
+          }
+        } else {
+          tunnelHealth.ok = false;
+          tunnelHealth.reason = tunnelError || (tunnelProc ? "URL not yet available" : "Not running");
+        }
+        results["__tunnel__"] = tunnelHealth;
         return ok(res, { results });
       } catch (err) {
         return strike(res, 502, err.message);
       }
     }
+    // GET /tunnel/test — end-to-end tunnel health check (hits /ping through the tunnel)
+    if (method === "GET" && reqPath === "/tunnel/test") {
+      if (lockedGuard(res)) return;
+      if (!tunnelUrl || !tunnelUrl.startsWith("http")) {
+        return ok(res, { ok: false, reason: "Tunnel not connected" });
+      }
+      const start = Date.now();
+      try {
+        // Hit /ping through the public tunnel URL — proves full roundtrip
+        const resp = await fetch(tunnelUrl + "/ping", { signal: AbortSignal.timeout(8000) });
+        const data = await resp.json();
+        const latencyMs = Date.now() - start;
+        if (data.status === "ok") {
+          // Also verify SSE endpoint is reachable
+          const sseResp = await fetch(tunnelUrl + "/sse", { signal: AbortSignal.timeout(5000) });
+          const sseOk = sseResp.headers.get("content-type")?.includes("text/event-stream");
+          sseResp.body?.cancel?.();
+          return ok(res, {
+            ok: true,
+            latencyMs,
+            tunnelUrl,
+            sseUrl: tunnelUrl + "/sse",
+            sseReachable: !!sseOk,
+            pid: data.pid,
+          });
+        }
+        return ok(res, { ok: false, reason: "Ping returned unexpected response", data });
+      } catch (e) {
+        return ok(res, { ok: false, reason: e.message, latencyMs: Date.now() - start });
+      }
+    }
     // POST /change-pw — change master password (must be unlocked)
     if (method === "POST" && reqPath === "/change-pw") {
       if (lockedGuard(res)) return;
@@ -1066,6 +1572,8 @@ async function actionStart(opts) {
       console.log(chalk.cyan(`\n  👉 Open http://127.0.0.1:${info.port} to unlock the vault`));
     }
     console.log(chalk.gray(`  Stop:     clauth serve stop\n`));
+    // Auto-open browser
+    openBrowser(`http://127.0.0.1:${info.port}`);
   } else {
     console.log(chalk.red(`\n  ❌ Failed to start daemon — check ${LOG_FILE}\n`));
     process.exit(1);
@@ -1176,6 +1684,8 @@ async function actionForeground(opts) {
     console.log(chalk.green(`  clauth serve → http://127.0.0.1:${port}`));
     if (!password) console.log(chalk.cyan(`  👉 Open http://127.0.0.1:${port} to unlock`));
     console.log(chalk.gray("  Ctrl+C to stop\n"));
+    // Auto-open browser
+    openBrowser(`http://127.0.0.1:${port}`);
   });
   server.on("error", err => {
@@ -1200,7 +1710,7 @@ async function actionForeground(opts) {
 // Secrets are delivered via temp files — never in the MCP response.
 import { createInterface } from "readline";
-import { execSync } from "child_process";
+import { execSync, spawn as spawnProc } from "child_process";
 const ENV_MAP = {
   "github":           "GITHUB_TOKEN",