botmux 2.75.1 → 2.76.0

package/dist/cli/dashboard-endpoint.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Loopback HMAC client for the dashboard process's `/__cli/*` endpoints, used by
+ * `botmux dashboard` (rotate) and the post-start/restart hint (current).
+ *
+ * Two subtleties this module exists to handle correctly:
+ *
+ * 1. **404 is ambiguous.** Only the dashboard's `/__cli/current` returns 404 to
+ *    mean "no token minted yet" (`{ error: 'no_active_token' }`). Any *other*
+ *    404 means the request hit a server that doesn't speak the `/__cli`
+ *    protocol — most commonly the daemon IPC server, whose unknown-route 404 is
+ *    `{ error: 'not_found', path }`. Conflating the two surfaces the infamous
+ *    misleading `Rotation failed: no-active-token` when the real problem is that
+ *    `.dashboard-port` points at the wrong service.
+ *
+ * 2. **`.dashboard-port` can go stale.** The dashboard and the daemon IPC server
+ *    both `listenWithProbe` upward from adjacent base ports (7891 vs 7892) with
+ *    heavily overlapping probe ranges, so across restarts the recorded dashboard
+ *    port can end up owned by an IPC server. When the recorded port answers as
+ *    the *wrong service*, we rediscover the real dashboard by HMAC-probing the
+ *    probe range (only the genuine dashboard can validate the signature) and
+ *    self-heal `.dashboard-port`.
+ */
+export type DashboardEndpoint = '/__cli/rotate' | '/__cli/current';
+export type DashboardFailReason = 'no-secret' | 'unreachable' | 'http-error' | 'no-active-token' | 'wrong-service';
+export type DashboardResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: DashboardFailReason;
+    detail?: string;
+};
+type FetchImpl = typeof fetch;
+/**
+ * Classify a 404 from a `/__cli/*` request. A genuine "no token yet" only comes
+ * from `/__cli/current` carrying `{ error: 'no_active_token' }`; everything else
+ * means the port is answering for some other service (daemon IPC, a stray HTTP
+ * server, …), not the dashboard rotate/current routes.
+ */
+export declare function classifyDashboard404(path: DashboardEndpoint, bodyText: string): DashboardResult;
+/** Issue a single HMAC-authed request to one candidate port. */
+export declare function requestDashboardAt(opts: {
+    host: string;
+    port: number;
+    path: DashboardEndpoint;
+    secret: string;
+    fetchImpl?: FetchImpl;
+}): Promise<DashboardResult>;
+/**
+ * Resolve the dashboard URL for `path`, trying the recorded port first and
+ * self-healing the port file when it points at the wrong service.
+ */
+export declare function callDashboard(opts: {
+    configDir: string;
+    defaultPort: number;
+    host?: string;
+    envPort?: string;
+    probeSpan?: number;
+    persistPort?: boolean;
+    path: DashboardEndpoint;
+    fetchImpl?: FetchImpl;
+}): Promise<DashboardResult>;
+export {};
+//# sourceMappingURL=dashboard-endpoint.d.ts.map

package/dist/cli/dashboard-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-endpoint.d.ts","sourceRoot":"","sources":["../../src/cli/dashboard-endpoint.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE,KAAK,SAAS,GAAG,OAAO,KAAK,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAY/F;AAED,gEAAgE;AAChE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8B3B;AAOD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4C3B"}

package/dist/cli/dashboard-endpoint.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteFileSync } from '../utils/atomic-write.js';
+import { cliAuthBind, signCliAuth } from '../dashboard/auth.js';
+/**
+ * Classify a 404 from a `/__cli/*` request. A genuine "no token yet" only comes
+ * from `/__cli/current` carrying `{ error: 'no_active_token' }`; everything else
+ * means the port is answering for some other service (daemon IPC, a stray HTTP
+ * server, …), not the dashboard rotate/current routes.
+ */
+export function classifyDashboard404(path, bodyText) {
+    let body = null;
+    try {
+        body = JSON.parse(bodyText);
+    }
+    catch { /* non-JSON body → wrong service */ }
+    const err = (body && typeof body === 'object') ? body.error : undefined;
+    if (path === '/__cli/current' && err === 'no_active_token') {
+        return { ok: false, reason: 'no-active-token' };
+    }
+    return {
+        ok: false,
+        reason: 'wrong-service',
+        detail: bodyText ? `404 ${bodyText.slice(0, 200)}` : '404',
+    };
+}
+/** Issue a single HMAC-authed request to one candidate port. */
+export async function requestDashboardAt(opts) {
+    const { host, port, path, secret } = opts;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    // Bind the credential to method + path + the port we're dialing. A malicious
+    // server handed these headers during discovery therefore can't forward them
+    // to a different `/__cli/*` route or to the real dashboard on another port —
+    // the verifier reconstructs the bind from the port IT bound, so any forward
+    // mismatches the signature (and the attacker can't re-sign without the secret).
+    const { ts, nonce, sig } = signCliAuth(secret, cliAuthBind('POST', path, port));
+    let res;
+    try {
+        res = await fetchImpl(`http://${host}:${port}${path}`, {
+            method: 'POST',
+            headers: {
+                'X-Botmux-Cli-Ts': ts,
+                'X-Botmux-Cli-Nonce': nonce,
+                'X-Botmux-Cli-Auth': sig,
+            },
+        });
+    }
+    catch {
+        return { ok: false, reason: 'unreachable' };
+    }
+    if (res.status === 404)
+        return classifyDashboard404(path, await res.text().catch(() => ''));
+    if (!res.ok) {
+        return { ok: false, reason: 'http-error', detail: `${res.status} ${await res.text().catch(() => '')}` };
+    }
+    const body = await res.json().catch(() => ({}));
+    if (!body.url)
+        return { ok: false, reason: 'http-error', detail: 'malformed response (no url)' };
+    return { ok: true, url: body.url };
+}
+/** A result that proves we actually reached the dashboard (vs. wrong port). */
+function reachedDashboard(r) {
+    return r.ok || (!r.ok && (r.reason === 'no-active-token' || r.reason === 'http-error'));
+}
+/**
+ * Resolve the dashboard URL for `path`, trying the recorded port first and
+ * self-healing the port file when it points at the wrong service.
+ */
+export async function callDashboard(opts) {
+    const host = opts.host ?? '127.0.0.1';
+    const probeSpan = opts.probeSpan ?? 20;
+    const persistPort = opts.persistPort ?? true;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const secretPath = join(opts.configDir, '.dashboard-secret');
+    if (!existsSync(secretPath))
+        return { ok: false, reason: 'no-secret' };
+    const secret = readFileSync(secretPath, 'utf8').trim();
+    const portFile = join(opts.configDir, '.dashboard-port');
+    const recorded = (existsSync(portFile) ? readFileSync(portFile, 'utf8').trim() : '')
+        || opts.envPort
+        || String(opts.defaultPort);
+    const candidate = Number(recorded);
+    // 1. Try the recorded port. A success — or any state that proves we reached
+    //    the dashboard (no-active-token / http-error) — is returned as-is.
+    const first = await requestDashboardAt({ host, port: candidate, path: opts.path, secret, fetchImpl });
+    if (reachedDashboard(first))
+        return first;
+    // 2. Only `wrong-service` warrants rediscovery: some server answered on the
+    //    recorded port but it's not the dashboard, so the port file is stale.
+    //    (`unreachable` during boot resolves by retrying the same port, not by
+    //    scanning — so we leave it to the caller's retry loop.)
+    if (first.ok || first.reason !== 'wrong-service')
+        return first;
+    const base = Number(opts.envPort || opts.defaultPort);
+    for (let p = base; p <= base + probeSpan; p++) {
+        if (p === candidate)
+            continue;
+        // Probe read-only (`/__cli/current`) so discovery never mints a token on a
+        // server we're merely identifying. Only the real dashboard can answer the
+        // HMAC-gated route as `ok` or `no-active-token`.
+        const probe = await requestDashboardAt({ host, port: p, path: '/__cli/current', secret, fetchImpl });
+        if (probe.ok || (!probe.ok && probe.reason === 'no-active-token')) {
+            if (persistPort) {
+                try {
+                    atomicWriteFileSync(portFile, String(p));
+                }
+                catch { /* best-effort self-heal */ }
+            }
+            // Found the dashboard — perform the actually-requested op on its port.
+            return requestDashboardAt({ host, port: p, path: opts.path, secret, fetchImpl });
+        }
+    }
+    // No dashboard found in the probe range; surface the original wrong-service.
+    return first;
+}
+//# sourceMappingURL=dashboard-endpoint.js.map

package/dist/cli/dashboard-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-endpoint.js","sourceRoot":"","sources":["../../src/cli/dashboard-endpoint.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAo8IA;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GACzF,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8F7B"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAk7IA;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GACzF,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8F7B"}

package/dist/cli.js

@@ -42,6 +42,7 @@ import { invalidWorkingDirs } from './utils/working-dir.js';
 import { firstPositional } from './cli/arg-utils.js';
 import { dispatchPrimaryMessage, findStdinAliasAttachment, sendFileAttachments } from './cli/send-dispatch.js';
 import { buildPm2SpawnCommand } from './cli/pm2-command.js';
+import { callDashboard } from './cli/dashboard-endpoint.js';
 import { rejectLikelyWindowsStdinMojibake } from './cli/stdin-encoding.js';
 import { formatBotInfoEntriesForCli, formatChatBotsForCli, } from './cli/bots-list-output.js';
 import { buildFooterAddressing, hasKnownBotMention, knownBotOpenIdsFromCrossRef, orderedFooterRecipients, } from './utils/bot-routing.js';
@@ -1368,47 +1369,18 @@ function cmdUpgrade() {
     }
 }
 /**
- * Call one of the dashboard's loopback HMAC `/__cli/*` endpoints.
- * - `/__cli/rotate` mints a fresh token and returns its URL, invalidating the
- *   previously-issued link.
- * - `/__cli/current` returns the existing token's URL WITHOUT rotating (404 →
- *   no token has ever been minted → `no-active-token`).
- * Returns { ok: true, url } on success, or { ok: false, reason } so callers can
- * decide how to surface the failure (hard error vs soft hint).
+ * Call one of the dashboard's loopback HMAC `/__cli/*` endpoints. Thin wrapper
+ * over {@link callDashboard}, which handles 404 disambiguation and self-heals a
+ * stale `.dashboard-port` that points at the wrong service (e.g. daemon IPC).
+ * See `src/cli/dashboard-endpoint.ts` for the why.
  */
 async function callDashboardEndpoint(path) {
-    const SECRET_PATH = join(CONFIG_DIR, '.dashboard-secret');
-    if (!existsSync(SECRET_PATH))
-        return { ok: false, reason: 'no-secret' };
-    const secret = readFileSync(SECRET_PATH, 'utf8').trim();
-    const ts = Math.floor(Date.now() / 1000).toString();
-    const nonce = randomBytes(8).toString('hex');
-    const sig = createHmac('sha256', secret).update(`${ts}:${nonce}`).digest('base64url');
-    const portFile = join(CONFIG_DIR, '.dashboard-port');
-    const port = (existsSync(portFile) ? readFileSync(portFile, 'utf8').trim() : '')
-        || process.env.BOTMUX_DASHBOARD_PORT
-        || '7891';
-    let res;
-    try {
-        res = await fetch(`http://127.0.0.1:${port}${path}`, {
-            method: 'POST',
-            headers: {
-                'X-Botmux-Cli-Ts': ts,
-                'X-Botmux-Cli-Nonce': nonce,
-                'X-Botmux-Cli-Auth': sig,
-            },
-        });
-    }
-    catch {
-        return { ok: false, reason: 'unreachable' };
-    }
-    if (res.status === 404)
-        return { ok: false, reason: 'no-active-token' };
-    if (!res.ok) {
-        return { ok: false, reason: 'http-error', detail: `${res.status} ${await res.text()}` };
-    }
-    const body = await res.json();
-    return { ok: true, url: body.url };
+    return callDashboard({
+        configDir: CONFIG_DIR,
+        defaultPort: 7891,
+        envPort: process.env.BOTMUX_DASHBOARD_PORT,
+        path,
+    });
 }
 /**
  * Best-effort dashboard hint printed after start/restart. Reads the LIVE link
@@ -1428,8 +1400,10 @@ async function printDashboardHintWithRetry() {
             return;
         }
         // Terminal states — file-backed secret/token won't appear mid-poll, unlike
-        // a not-yet-listening port. Don't spin on them.
-        if (last.reason === 'no-secret' || last.reason === 'no-active-token')
+        // a not-yet-listening port. `wrong-service` means the port file points at a
+        // non-dashboard server and discovery already failed to find it, so retrying
+        // won't help either. Don't spin on any of them.
+        if (last.reason === 'no-secret' || last.reason === 'no-active-token' || last.reason === 'wrong-service')
             break;
         await new Promise(r => setTimeout(r, stepMs));
     }
@@ -1440,6 +1414,9 @@ async function printDashboardHintWithRetry() {
     else if (last?.reason === 'no-secret') {
         console.log('   面板: dashboard 凭证未就绪，启动后可用 `botmux dashboard` 获取链接');
     }
+    else if (last?.reason === 'wrong-service') {
+        console.log('   面板: `botmux dashboard`（端口文件可能已失效，必要时 `botmux restart` 刷新）');
+    }
     else {
         console.log('   面板: `botmux dashboard`（daemon 启动中，稍后可获取链接）');
     }
@@ -1455,15 +1432,24 @@ async function cmdDashboard() {
         console.log(r.url);
         return;
     }
+    const portFile = join(CONFIG_DIR, '.dashboard-port');
+    const recordedPort = (existsSync(portFile) ? readFileSync(portFile, 'utf8').trim() : '')
+        || process.env.BOTMUX_DASHBOARD_PORT
+        || '7891';
     if (r.reason === 'no-secret') {
         console.error('Dashboard not initialised. Run `botmux restart` first.');
     }
     else if (r.reason === 'unreachable') {
-        const portFile = join(CONFIG_DIR, '.dashboard-port');
-        const port = (existsSync(portFile) ? readFileSync(portFile, 'utf8').trim() : '')
-            || process.env.BOTMUX_DASHBOARD_PORT
-            || '7891';
-        console.error(`dashboard process not reachable on 127.0.0.1:${port} — \`botmux restart\` will start it`);
+        console.error(`dashboard process not reachable on 127.0.0.1:${recordedPort} — \`botmux restart\` will start it`);
+    }
+    else if (r.reason === 'wrong-service') {
+        // 127.0.0.1:<port> answered, but it isn't the dashboard (typically the
+        // daemon IPC server holding a port the stale .dashboard-port points at),
+        // and rediscovery across the probe range found no dashboard either.
+        console.error(`127.0.0.1:${recordedPort} 上的服务不是 dashboard（端口文件 ~/.botmux/.dashboard-port 已失效，可能指向了 daemon IPC）。` +
+            '运行 `botmux restart` 重启 dashboard 并刷新端口文件。');
+        if (r.detail)
+            console.error(`  详情: ${r.detail}`);
     }
     else {
         // `no-active-token` can't occur on rotate (it always mints); fall through.