botmux 3.14.0 → 3.16.0

package/dist/dashboard/control-audit.js

@@ -0,0 +1,195 @@
+import { appendFileSync, chmodSync, close, createWriteStream, fchmod, open, mkdirSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export function defaultControlAuditPath() {
+    return process.env.BOTMUX_DASHBOARD_CONTROL_AUDIT_PATH?.trim()
+        || join(homedir(), '.botmux', 'audit', 'dashboard-control.ndjson');
+}
+function safeAuditIdentity(value, fallback) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 256 || /[\r\n\0]/.test(normalized))
+        return fallback;
+    return normalized;
+}
+export function controlAuditRecord(user, session, action, opts = {}) {
+    const bytes = opts.bytes;
+    return {
+        timestamp: (opts.now ?? new Date()).toISOString(),
+        user: safeAuditIdentity(user, 'unknown'),
+        session: safeAuditIdentity(session, 'dashboard'),
+        action,
+        ...(Number.isSafeInteger(bytes) && bytes >= 0 ? { bytes } : {}),
+    };
+}
+/**
+ * Append-only 0600 NDJSON sink. `appendFileSync` issues one O_APPEND write per
+ * compact record, so workers may safely share the file without a read/modify/
+ * rename race. Audit failures are intentionally non-fatal to terminal I/O;
+ * callers may inject a strict sink in deployments that require fail-closed
+ * accounting.
+ */
+export class FileControlAuditSink {
+    path;
+    constructor(opts = {}) {
+        this.path = opts.path ?? defaultControlAuditPath();
+    }
+    append(record) {
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        appendFileSync(this.path, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600 });
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch { /* best effort after append */ }
+    }
+}
+/**
+ * Backpressure cap for the async sink's in-memory queue. While the stream is
+ * still opening or `write()` has signalled backpressure, at most this many
+ * records wait in memory; older ones are dropped (and counted) first, so a
+ * slow/NFS disk under sustained terminal input can never turn into unbounded
+ * heap growth.
+ */
+export const AUDIT_ASYNC_MAX_PENDING = 2_000;
+/**
+ * High-frequency, best-effort sink for terminal input counters. Directory and
+ * permissions are established exactly once, then compact records are queued to
+ * one O_APPEND stream so a slow/NFS home directory never blocks the worker's
+ * PTY event loop for every keystroke. Security-boundary actions keep using the
+ * synchronous FileControlAuditSink above so takeover can remain fail-closed.
+ *
+ * Backpressure contract: `append()` always returns synchronously (the audit is
+ * a fire-and-forget side channel — it must never block or slow the caller).
+ * When `write()` returns false the sink stops writing until `drain`; arriving
+ * records queue up to {@link AUDIT_ASYNC_MAX_PENDING}, beyond which the oldest
+ * are dropped and counted. Once writing resumes, an `audit.dropped` marker
+ * record lands first so the gap is visible in the file.
+ */
+export class AsyncFileControlAuditSink {
+    path;
+    maxPending;
+    streamFactory;
+    stream;
+    opening;
+    pending = [];
+    droppedCount = 0;
+    waitingDrain = false;
+    unavailable = false;
+    constructor(opts = {}) {
+        this.path = opts.path ?? defaultControlAuditPath();
+        this.maxPending = Math.max(1, Math.floor(opts.maxPending ?? AUDIT_ASYNC_MAX_PENDING));
+        this.streamFactory = opts.streamFactory;
+    }
+    append(record) {
+        if (this.unavailable)
+            return;
+        this.enqueue(`${JSON.stringify(record)}\n`);
+        if (this.stream) {
+            this.flush();
+            return;
+        }
+        void (this.opening ??= this.openStream()).then(() => this.flush());
+    }
+    /** Queue with the cap enforced: drop-oldest keeps the freshest records and
+     *  bounds memory no matter how long the disk stalls. */
+    enqueue(line) {
+        this.pending.push(line);
+        while (this.pending.length > this.maxPending) {
+            this.pending.shift();
+            this.droppedCount += 1;
+        }
+    }
+    /** Drain the queue onto the stream until it pushes back. Synchronous; safe to
+     *  call at any time (no-ops while unavailable, still opening, or awaiting
+     *  `drain`). The dropped-marker goes out first — everything it accounts for
+     *  is older than every surviving queued record. */
+    flush() {
+        const stream = this.stream;
+        if (!stream || this.unavailable || this.waitingDrain)
+            return;
+        while (this.droppedCount > 0 || this.pending.length > 0) {
+            const line = this.droppedCount > 0 ? this.takeDroppedMarker() : this.pending.shift();
+            // Node buffers the chunk even when write() returns false, so `line` is
+            // never lost here — false only means "stop sending until drain".
+            if (!stream.write(line, 'utf8')) {
+                this.waitingDrain = true;
+                stream.once('drain', () => {
+                    this.waitingDrain = false;
+                    this.flush();
+                });
+                return;
+            }
+        }
+    }
+    takeDroppedMarker() {
+        const dropped = this.droppedCount;
+        this.droppedCount = 0;
+        const marker = {
+            timestamp: new Date().toISOString(),
+            user: 'system',
+            session: 'audit',
+            action: 'audit.dropped',
+            dropped,
+        };
+        return `${JSON.stringify(marker)}\n`;
+    }
+    markUnavailable() {
+        this.unavailable = true;
+        // Free the queue: nothing will ever drain it once the sink is dead.
+        this.pending.length = 0;
+        this.droppedCount = 0;
+    }
+    async openStream() {
+        try {
+            const stream = this.streamFactory ? await this.streamFactory() : await this.openFileStream();
+            if (!stream) {
+                this.markUnavailable();
+                return undefined;
+            }
+            stream.on('error', () => {
+                this.markUnavailable();
+                // autoClose owns the descriptor once the stream is constructed.
+                // Closing it again here can race the stream's own error cleanup.
+            });
+            this.stream = stream;
+            return stream;
+        }
+        catch {
+            this.markUnavailable();
+            return undefined;
+        }
+    }
+    async openFileStream() {
+        const { mkdir } = await import('node:fs/promises');
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const fd = await new Promise((resolve, reject) => {
+            open(this.path, 'a', 0o600, (error, value) => error ? reject(error) : resolve(value));
+        });
+        await new Promise((resolve, reject) => {
+            fchmod(fd, 0o600, error => error ? reject(error) : resolve());
+        }).catch(error => {
+            close(fd, () => { });
+            throw error;
+        });
+        return createWriteStream(this.path, {
+            fd,
+            flags: 'a',
+            autoClose: true,
+            encoding: 'utf8',
+        });
+    }
+}
+let defaultSink;
+export function appendControlAudit(record) {
+    try {
+        (defaultSink ??= new AsyncFileControlAuditSink()).append(record);
+    }
+    catch {
+        // Never include the record or underlying error in logs: either could carry
+        // an operator-controlled path/identifier. Runtime remains available.
+    }
+}
+/** Test seam; production code should use the default append-only file sink. */
+export function setDefaultControlAuditSinkForTest(sink) {
+    defaultSink = sink;
+}
+//# sourceMappingURL=control-audit.js.map

package/dist/dashboard/control-audit.js.map

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

package/dist/dashboard/control-csrf.d.ts

@@ -0,0 +1,123 @@
+/** 提交控制类请求时携带 CSRF 票据的头名。`<form>` 设不了自定义头，这是关键。 */
+export declare const CONTROL_CSRF_HEADER = "x-botmux-csrf";
+/** 页面注入票据用的 meta 名（SPA 与 preview guard 壳都读它）。 */
+export declare const CONTROL_CSRF_META_NAME = "botmux-csrf";
+export type ControlRequestOriginState = 'same-origin' | 'foreign' | 'unknown';
+export interface ControlRequestHeadersLike {
+    origin?: string | string[];
+    host?: string | string[];
+    'sec-fetch-site'?: string | string[];
+    [key: string]: string | string[] | undefined;
+}
+/**
+ * `Origin` 是否与本请求自己的 authority 同源。两边都归一化成 hostname + 有效端
+ * 口后比较，不比 scheme：中心化平台在 TLS 终止后把明文转给本进程，浏览器发的是
+ * `https://…` 而本地看到的是明文连接，比 scheme 会把正常访问全判成跨站。
+ * hostname + 端口相等已经足以区分兄弟子域与其它端口——那正是本条要防的。
+ *
+ * 端口必须两边对称归一化：`new URL('https://dash.example').host` 会被 URL 规范
+ * 剥成 `dash.example`，而 `Host` 头是原始字符串，反代常写成 `dash.example:443`。
+ * 早先直接比字符串，于是 `proxy_set_header Host $host:$server_port;` 这类广为流
+ * 传的配置会把自己人的控制请求全判成跨站。
+ *
+ * `host` 可以给多个候选：反代/平台隧道下 `Host` 可能已被改写成回环地址，浏览器
+ * 真正看到的域名在 `X-Forwarded-Host` 里。这不削弱防线——浏览器不允许页面设置
+ * `Origin`，而 `X-Forwarded-Host` 是自定义头，跨站 `<form>` 设不了、跨站 fetch
+ * 会先触发预检（本服务不答 CORS，预检直接失败），所以攻击页两个头都伪造不了。
+ */
+export declare function originMatchesHost(origin: string | undefined, host: string | undefined | ReadonlyArray<string | undefined>): boolean;
+/**
+ * 综合 `Sec-Fetch-Site` 与 `Origin` 判定来源。任一信号明确说「不是同源」就是
+ * `foreign`；两个信号都缺席是 `unknown`（非浏览器客户端），由调用方决定 fail
+ * closed 还是放行。
+ */
+export declare function controlRequestOriginState(headers: ControlRequestHeadersLike): ControlRequestOriginState;
+/**
+ * `Referer` 兜底的同源判定：请求既没带 `Origin` 也没带 `Sec-Fetch-Site` 时，用
+ * Referer 的 origin 与本请求的候选 authority 比一次（复用上面那套归一化，不另写
+ * 一份比较逻辑）。
+ *
+ * 为什么需要它：同源 **GET** 在浏览器里通常两个信号都没有——`Origin` 只在跨源和
+ * 非 GET 请求上发，`Sec-Fetch-*` 是较新的浏览器才有（Safari 16.4 之前没有）。对
+ * 「有副作用的 POST」两信号缺席一律 fail closed 是对的（那条路径没有需要放行的非
+ * 浏览器调用方），但一条**发放凭证的 GET** 若照搬那条规则，会把老浏览器上的真
+ * owner 一起挡在门外。Referer 在默认的 `strict-origin-when-cross-origin` 策略下
+ * 对同源请求带完整 URL，正好补上这一格。
+ *
+ * 这不放宽防线：Referer 同样是浏览器写、页面改不了的头，而**明确判为跨站**
+ * （`controlRequestOriginState` 已经返回 `foreign`）的请求绝不会走到这里——调用方
+ * 只在 `unknown` 时才用它兜底。
+ */
+export declare function refererMatchesHost(headers: ControlRequestHeadersLike): boolean;
+/**
+ * 管理类 WebSocket 升级的 Origin 判定（terminal / debug-terminal）。
+ * 带 Origin 就必须同源（`null` 也算带了，直接拒）；不带 Origin 视为非浏览器客
+ * 户端放行。Preview 自身的 WS 不走这里，见文件头注释。
+ */
+export declare function managementUpgradeOrigin(headers: ControlRequestHeadersLike): {
+    ok: true;
+} | {
+    ok: false;
+    error: 'upgrade_origin_forbidden';
+};
+export interface ControlCsrfTokensOptions {
+    /** 闲置寿命（每次成功校验续期）。 */
+    ttlMs?: number;
+    maxTokens?: number;
+    now?: () => number;
+    randomToken?: () => string;
+}
+/**
+ * 一次性签发、绑定认证会话的 CSRF 票据表。
+ *
+ * - **一次性签发**：每次页面加载现签一枚随机票据，不是从长期密钥推导的稳定值，
+ *   页面刷新即换新票，旧票随 TTL / 认证结束消失。
+ * - **绑定认证会话**：校验时必须与当前请求解析出的 authSessionId 一致，所以一
+ *   枚票据换不到别人的身份，登出后也立刻作废（`revokeAuthSession`）。
+ * - 只存 SHA-256 摘要，明文票据只在注入页面和请求头里存在。
+ *
+ * 不做「用一次即焚」：工作台一次交互会连打多条控制请求（unlock 之后每 20s 一条
+ * activity），单次即焚会退化成每个操作都要先取票，多一次往返还会在弱网下把解锁
+ * 变成必然失败。这里的安全性来自「跨站拿不到票 + 同源证明」，不来自使用次数。
+ */
+export declare class ControlCsrfTokens {
+    private readonly byHash;
+    private readonly hashesByAuthSession;
+    private readonly ttlMs;
+    private readonly maxTokens;
+    private readonly now;
+    private readonly randomToken;
+    constructor(opts?: ControlCsrfTokensOptions);
+    mint(authSessionId: string): string;
+    verify(token: string | undefined, authSessionId: string): boolean;
+    /** 认证结束（logout / 到期 / rotate / 解绑）时作废该会话的全部票据。 */
+    revokeAuthSession(authSessionId: string): number;
+    size(): number;
+    private forget;
+    private sweep;
+}
+/**
+ * 把本次页面加载现签的票据注入 HTML 壳（SPA index.html / preview guard 壳）。
+ * 票据只进 `<meta>`：跨站页面读不到本源 DOM，`<form>` 也设不了自定义头，所以
+ * 「无 body 表单触发接管/解锁」这条路就此断掉。注入后的壳必须 `no-store`，
+ * 否则浏览器会把已作废的票据缓存下来复用。
+ */
+export declare function injectControlCsrfMeta(html: string, token: string): string;
+export type ControlRequestGuardResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 403;
+    error: 'control_origin_forbidden' | 'control_csrf_invalid';
+};
+/**
+ * 控制类请求（takeover/release、preview-interaction unlock/activity/lock、
+ * locate 等有副作用且可被无 body 表单触发的 POST）的统一门禁。
+ * 调用点必须已经解析出身份——匿名请求在路由层就该 401，这里只管跨站伪造。
+ */
+export declare function guardControlRequest(input: {
+    headers: ControlRequestHeadersLike;
+    authSessionId: string;
+    tokens: ControlCsrfTokens;
+}): ControlRequestGuardResult;
+//# sourceMappingURL=control-csrf.d.ts.map

package/dist/dashboard/control-csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-csrf.d.ts","sourceRoot":"","sources":["../../src/dashboard/control-csrf.ts"],"names":[],"mappings":"AAiCA,mDAAmD;AACnD,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AACnD,iDAAiD;AACjD,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AASpD,MAAM,MAAM,yBAAyB,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAC9C;AA6DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,GAC3D,OAAO,CAST;AA4DD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,yBAAyB,CAUvG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAY9E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,yBAAyB,GACxE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,0BAA0B,CAAA;CAAE,CAQhE;AAMD,MAAM,WAAW,wBAAwB;IACvC,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmE;IAC1F,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IACtE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;gBAE/B,IAAI,GAAE,wBAA6B;IAO/C,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;IAqBnC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAejE,kDAAkD;IAClD,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;IAWhD,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,KAAK;CAMd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKzE;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,0BAA0B,GAAG,sBAAsB,CAAA;CAAE,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,OAAO,EAAE,yBAAyB,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,GAAG,yBAAyB,CAW5B"}