botmux 3.14.0 → 3.16.0

package/dist/dashboard/preview-interaction.js

@@ -0,0 +1,198 @@
+import { controlAuditRecord, } from './control-audit.js';
+/** Product contract: interaction always relocks after fifteen idle minutes. */
+export const PREVIEW_INTERACTION_IDLE_MS = 15 * 60_000;
+export const PREVIEW_DEFAULT_MODE_LABEL = '预览模式（默认）';
+export const PREVIEW_INTERACTIVE_MODE_LABEL = '交互模式';
+export const PREVIEW_OVERLAY_SECURITY_NOTICE = '交互蒙层仅用于防止误触，不是应用级强只读安全边界。';
+function leaseKey(authSessionId, sessionId) {
+    return `${authSessionId}\0${sessionId}`;
+}
+/**
+ * Server-owned preview interaction state. Unlock and activity are explicit;
+ * both the scheduled timer and lazy reads enforce the exact idle deadline.
+ * This state drives a browser overlay only—it does not claim to neutralize
+ * scripts or network side effects inside the proxied application.
+ */
+export class PreviewInteractionManager {
+    leases = new Map();
+    audit;
+    now;
+    schedule;
+    cancel;
+    generation = 0;
+    constructor(opts) {
+        this.audit = opts.audit;
+        this.now = opts.now ?? Date.now;
+        this.schedule = opts.setTimer ?? setTimeout;
+        this.cancel = opts.clearTimer ?? clearTimeout;
+    }
+    state(actor, sessionId) {
+        const lease = this.liveLease(actor, sessionId);
+        return lease ? this.interactiveState(lease) : this.previewState();
+    }
+    unlock(actor, sessionId) {
+        const now = this.now();
+        const key = leaseKey(actor.authSessionId, sessionId);
+        const previous = this.leases.get(key);
+        if (previous?.timer)
+            this.cancel(previous.timer);
+        this.audit.append(controlAuditRecord(actor.userId, sessionId, 'preview.unlock', { now: new Date(now) }));
+        const lease = {
+            authSessionId: actor.authSessionId,
+            userId: actor.userId,
+            sessionId,
+            unlockedAt: now,
+            lastActivityAt: now,
+            idleExpiresAt: now + PREVIEW_INTERACTION_IDLE_MS,
+            generation: ++this.generation,
+        };
+        this.arm(key, lease);
+        this.leases.set(key, lease);
+        return this.interactiveState(lease);
+    }
+    activity(actor, sessionId) {
+        const lease = this.liveLease(actor, sessionId);
+        if (!lease)
+            return this.previewState();
+        const now = this.now();
+        this.audit.append(controlAuditRecord(actor.userId, sessionId, 'preview.activity', { now: new Date(now) }));
+        lease.lastActivityAt = now;
+        lease.idleExpiresAt = now + PREVIEW_INTERACTION_IDLE_MS;
+        lease.generation = ++this.generation;
+        const key = leaseKey(actor.authSessionId, sessionId);
+        if (lease.timer)
+            this.cancel(lease.timer);
+        this.arm(key, lease);
+        return this.interactiveState(lease);
+    }
+    lock(actor, sessionId) {
+        const key = leaseKey(actor.authSessionId, sessionId);
+        const lease = this.leases.get(key);
+        if (!lease)
+            return this.previewState();
+        this.remove(key, lease);
+        try {
+            this.audit.append(controlAuditRecord(actor.userId, sessionId, 'preview.lock', { now: new Date(this.now()) }));
+        }
+        catch {
+            // Relocking is the boundary. Audit storage failure must not turn the
+            // already-removed interaction lease back on or fail the browser closed.
+        }
+        return this.previewState();
+    }
+    /**
+     * P1-13：把某个**业务会话**上的交互授权全部收回，不论持有者是谁。
+     *
+     * 交互解锁是「我确认要操作**这个**预览目标」的授权，绑定的是当时那一代 worker 起
+     * 的那个 Web 服务。worker 换代、切 CLI、会话 close→resume、端口易主之后，目标已经
+     * 是另一个进程，旧租约不能顺延：否则 resume 出来的新一代 CLI（或抢到同一端口的别的
+     * 进程）一上来就落在「交互模式」里，用户从未对它点过解锁。收回后回到默认预览模式，
+     * 需要重新显式解锁。
+     */
+    relockSession(sessionId) {
+        let count = 0;
+        for (const [key, lease] of [...this.leases]) {
+            if (lease.sessionId !== sessionId)
+                continue;
+            this.remove(key, lease);
+            try {
+                this.audit.append(controlAuditRecord(lease.userId, lease.sessionId, 'preview.target_relock', { now: new Date(this.now()) }));
+            }
+            catch {
+                // 继续撤销这个会话上剩下的租约。
+            }
+            count++;
+        }
+        return count;
+    }
+    relockAuthSession(authSessionId) {
+        let count = 0;
+        for (const [key, lease] of [...this.leases]) {
+            if (lease.authSessionId !== authSessionId)
+                continue;
+            this.remove(key, lease);
+            try {
+                this.audit.append(controlAuditRecord(lease.userId, lease.sessionId, 'preview.session_relock', { now: new Date(this.now()) }));
+            }
+            catch {
+                // Continue revoking the remaining leases for this auth session.
+            }
+            count++;
+        }
+        return count;
+    }
+    expireDue() {
+        const now = this.now();
+        let count = 0;
+        for (const [key, lease] of [...this.leases]) {
+            if (now < lease.idleExpiresAt)
+                continue;
+            this.expire(key, lease, now);
+            count++;
+        }
+        return count;
+    }
+    liveLease(actor, sessionId) {
+        const key = leaseKey(actor.authSessionId, sessionId);
+        const lease = this.leases.get(key);
+        if (!lease || lease.userId !== actor.userId)
+            return undefined;
+        const now = this.now();
+        if (now >= lease.idleExpiresAt || now >= actor.expiresAt) {
+            this.expire(key, lease, now);
+            return undefined;
+        }
+        return lease;
+    }
+    arm(key, lease) {
+        const generation = lease.generation;
+        lease.timer = this.schedule(() => {
+            const current = this.leases.get(key);
+            if (!current || current !== lease || current.generation !== generation)
+                return;
+            const now = this.now();
+            if (now < current.idleExpiresAt) {
+                this.arm(key, current);
+                return;
+            }
+            this.expire(key, current, now);
+        }, Math.max(0, lease.idleExpiresAt - this.now()));
+        lease.timer.unref?.();
+    }
+    expire(key, lease, now) {
+        if (this.leases.get(key) !== lease)
+            return;
+        this.remove(key, lease);
+        try {
+            this.audit.append(controlAuditRecord(lease.userId, lease.sessionId, 'preview.idle_relock', {
+                now: new Date(now),
+            }));
+        }
+        catch {
+            // The timer must never crash the Dashboard after it safely relocked.
+        }
+    }
+    remove(key, lease) {
+        if (this.leases.get(key) !== lease)
+            return;
+        this.leases.delete(key);
+        if (lease.timer)
+            this.cancel(lease.timer);
+    }
+    previewState() {
+        return {
+            mode: 'preview',
+            label: PREVIEW_DEFAULT_MODE_LABEL,
+            securityNotice: PREVIEW_OVERLAY_SECURITY_NOTICE,
+        };
+    }
+    interactiveState(lease) {
+        return {
+            mode: 'interactive',
+            label: PREVIEW_INTERACTIVE_MODE_LABEL,
+            securityNotice: PREVIEW_OVERLAY_SECURITY_NOTICE,
+            idleExpiresAt: lease.idleExpiresAt,
+        };
+    }
+}
+//# sourceMappingURL=preview-interaction.js.map

package/dist/dashboard/preview-interaction.js.map

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

package/dist/dashboard/preview-proxy.d.ts

@@ -0,0 +1,113 @@
+import { type IncomingHttpHeaders, type IncomingMessage, type OutgoingHttpHeaders, type ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type SessionPreviewTarget } from '../core/session-preview.js';
+import type { SessionPreviewResolution } from './preview-contract.js';
+/** Dev servers commonly cold-compile their first response for 3–30 seconds.
+ * This bounds only the pre-header phase and is cleared once headers arrive. */
+export declare const PREVIEW_UPSTREAM_RESPONSE_TIMEOUT_MS = 45000;
+/**
+ * P1-2：一个 upgrade 请求收到非 101 回应时，那是一次**拒绝**，不是长连接。
+ *
+ * 代理把这段 body 攒完才写回浏览器（只有 `end` 才落笔），所以一个永不结束的
+ * 「拒绝」会同时钉死上游 socket 和浏览器 socket，而浏览器一个字节都收不到。
+ * 因此这条路必须两道时限都有：读完整段拒绝的**总时限**，以及静默多久算死的
+ * **idle 时限**——只有 idle 时限时，上游每 N 秒滴一个字节就能永久续命。
+ */
+export declare const PREVIEW_UPGRADE_REJECTION_TIMEOUT_MS = 15000;
+export declare const PREVIEW_UPGRADE_REJECTION_IDLE_TIMEOUT_MS = 10000;
+/**
+ * Sandbox flags forced onto every proxied preview document.
+ *
+ * `allow-same-origin` is deliberately absent: without it the document is an
+ * opaque origin, which is the whole point. It cannot read the dashboard DOM,
+ * cannot attach dashboard cookies to any request (an opaque origin has a null
+ * site-for-cookies, so even SameSite=Lax credentials stay home), and cannot
+ * touch same-origin storage. The same list is applied twice on purpose:
+ *
+ *   • as the iframe `sandbox` attribute in the guard shell, and
+ *   • as a `Content-Security-Policy: sandbox …` response header here,
+ *
+ * so agent-controlled HTML is opaque even when it is reached *without* the
+ * shell — a lured top-level navigation to a preview URL must not hand the
+ * agent a usable dashboard origin either.
+ *
+ * `allow-top-navigation` is absent so a preview can never navigate the
+ * dashboard away, and `allow-popups-to-escape-sandbox` is absent so popups
+ * the preview opens inherit the same opaque origin.
+ */
+export declare const PREVIEW_SANDBOX_TOKENS = "allow-scripts allow-forms allow-popups";
+export type PreviewProxyResolution = SessionPreviewResolution | {
+    ok: false;
+    status: 503;
+    error: 'daemon_offline';
+};
+export interface SessionPreviewProxyOptions {
+    /** Management-cookie authentication. Query tokens are deliberately not
+     * accepted: a preview URL must never contain the dashboard token. */
+    authenticated: (req: IncomingMessage) => boolean;
+    /** Positive session/daemon ownership lookup followed by registered-target
+     * resolution. The URL contributes only the session id, never a target. */
+    resolve: (sessionId: string) => PreviewProxyResolution;
+    /**
+     * Verify the path-scoped capability that authorises the sandboxed content
+     * stream for exactly this session. Required, not optional: the content path
+     * carries no cookie by construction, so a missing verifier would either be
+     * an open proxy or a dead route — both worse than a compile error.
+     */
+    verifyContentCapability: (capability: string, sessionId: string) => boolean;
+    /**
+     * P1-8：把一条已授权的长连接（SSE / 长响应 / WebSocket 桥）挂到签发它的认证
+     * 会话下，返回注销闭包（连接自然结束时调用）。认证结束时由外层索引统一
+     * `close()`。返回 null 表示这条流没有可绑定的身份（不该发生，调用方自行决定
+     * 是否记录），此时行为与不提供本钩子一致。
+     *
+     * 授权与撤销是两件事：`authenticated` / `verifyContentCapability` 只在握手那
+     * 一刻说话，而预览的 SSE 与 WebSocket 一握手就能流上几个小时。没有这个钩子，
+     * 登出只能等对端自己断开。
+     *
+     * P1-4：返回 `false` 表示「这条流所属的认证会话已经结束，不许登记」。授权发生
+     * 在**拨号前**，而 dev server 的握手最长可以拖 45 秒；登出若落在这段窗口里，撤
+     * 销扫描遍历索引时这条连接还不在里面，一条都关不到，等上游握完手再补登记就等于
+     * 把一条活流挂到已经死掉的认证会话名下——从此再没有任何撤销能碰到它。本钩子因此
+     * 是「登记点」也是「最后一次判定点」：调用方在这里重查存活，代理按 false 销毁
+     * 上游、不登记、不回 101/200。
+     *
+     * P1-1：`context.target` 是**拨号那一刻**用的目标。同一段 45 秒窗口里换代 / 切
+     * CLI / 端口易主换来的新目标，旧流握完手照样能拿到 200/101，还会被重新登记进索引
+     * （换靶时的 teardown 扫的是索引，扫不到一条还没入索引的流）。所以调用方在这里
+     * 除了复核身份，还要把目标重解一遍与它比对——不是同一次注册就返回 false。
+     */
+    bindStream?: (req: IncomingMessage, context: {
+        sessionId: string;
+        contentCapability: string | null;
+        target: SessionPreviewTarget;
+    }, close: () => void) => (() => void) | null | false;
+}
+type ParsedPreviewPath = {
+    matched: false;
+} | {
+    matched: true;
+    ok: false;
+    error: 'invalid_preview_path' | 'query_token_forbidden';
+} | {
+    matched: true;
+    ok: true;
+    sessionId: string;
+    upstreamPath: string;
+    basePath: string;
+    /** Present only on `/preview/<id>/__botmux_preview_content/<cap>/…`. */
+    contentCapability: string | null;
+};
+export declare function parseSessionPreviewRequest(url: URL): ParsedPreviewPath;
+/** Never forward dashboard/browser credentials into agent-controlled preview
+ * servers. Host and Origin are rewritten to the literal loopback target so
+ * common dev servers can still perform their normal origin checks. */
+export declare function previewRequestHeaders(headers: IncomingHttpHeaders, target: SessionPreviewTarget, options?: {
+    upgrade?: boolean;
+}): OutgoingHttpHeaders;
+export declare function createSessionPreviewProxy(options: SessionPreviewProxyOptions): {
+    handleHttp: (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<boolean>;
+    handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+};
+export {};
+//# sourceMappingURL=preview-proxy.d.ts.map

package/dist/dashboard/preview-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-proxy.d.ts","sourceRoot":"","sources":["../../src/dashboard/preview-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAQL,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE;+EAC+E;AAC/E,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAC3D,eAAO,MAAM,yCAAyC,QAAS,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,2CAA2C,CAAC;AAG/E,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,GAAG;IAC9D,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,GAAG,CAAC;IACZ,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC;yEACqE;IACrE,aAAa,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC;IACjD;8EAC0E;IAC1E,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,sBAAsB,CAAC;IACvD;;;;;OAKG;IACH,uBAAuB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CAAC,EAAE,CACX,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,MAAM,EAAE,oBAAoB,CAAC;KAC9B,EACD,KAAK,EAAE,MAAM,IAAI,KACd,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;CAClC;AAED,KAAK,iBAAiB,GAClB;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,sBAAsB,GAAG,uBAAuB,CAAA;CAAE,GACrF;IACE,OAAO,EAAE,IAAI,CAAC;IACd,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAAC;AASN,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAwCtE;AAoCD;;sEAEsE;AACtE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAClC,mBAAmB,CAgBrB;AA0HD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG;IAC9E,UAAU,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,aAAa,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAChF,CAyRA"}