@aalis/plugin-webui-server 0.14.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @aalis/plugin-webui-server
 
-Web 管理界面后端：对话/插件/服务/市场/文件
+Web 管理界面后端：会话连接、管理面推送、插件、服务与市场
 ## 角色
 
 运行时插件
@@ -11,6 +11,10 @@ Web 管理界面后端：对话/插件/服务/市场/文件
 pnpm add @aalis/plugin-webui-server
 ```
 
+## 宿主路径
+
+以 `optional(hostPaths)` 声明 `host-paths`（`@aalis/api-host-paths`），从安装集扫描本机包与前端。宿主不提供时发现不到前端，整个 WebUI 前端不可用，只剩 HTTP 接口，市场与系统组件接口返回 503。Node 宿主 `@aalis/runtime` 总会提供它。
+
 ## 文档
 
 详见 [docs/plugins/plugin-webui-server.md](../../docs/plugins/plugin-webui-server.md)。

package/dist/admin-channel.d.ts

@@ -0,0 +1,10 @@
+import type { LogFilter, WebuiAdminEvent } from '@aalis/api-webui';
+import type { LogEntry, Logger } from '@aalis/core';
+import { WebSocket } from 'ws';
+export declare const ADMIN_PATH = "/admin";
+/** match 按筛选给出判定日志的函数 */
+export declare function createAdminChannel(logger: Logger, match: (filter: LogFilter) => (entry: LogEntry) => boolean): {
+    accept: (ws: WebSocket) => void;
+    send: (event: WebuiAdminEvent) => void;
+};
+//# sourceMappingURL=admin-channel.d.ts.map

package/dist/admin-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-channel.d.ts","sourceRoot":"","sources":["../src/admin-channel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAG/B,eAAO,MAAM,UAAU,WAAW,CAAC;AAYnC,yBAAyB;AACzB,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO;iBAKvF,SAAS,KAAG,IAAI;kBAgBf,eAAe,KAAG,IAAI;EAY5C"}

package/dist/admin-channel.js

@@ -0,0 +1,57 @@
+// ============================================================
+// admin-channel.ts — /admin：管理面事件推送
+//
+// 会话之外的推送（日志、插件与页面登记表的变化、重启、换前端）走这条端点，与会话协议的 /session 分开。
+// 事件类型见 @aalis/api-webui 的 WebuiAdminEvent：日志只推给订阅了、符合它订阅时的筛选的连接，其余事件推给全部连接。
+// 前端发来的只有日志的订阅（可带筛选，再订阅一次换掉筛选）与退订；认不出的消息（含写法不对的筛选）记一行告警后忽略，
+// 连接与之前的订阅照常，较新的前端连上较旧的服务端也不会被断开。
+// ============================================================
+import { WebSocket } from 'ws';
+import { parseLogFilter } from './logs.js';
+export const ADMIN_PATH = '/admin';
+/** 帧按 JSON 读出的对象；不是 JSON 对象时为 undefined */
+function messageOf(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === 'object' && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** match 按筛选给出判定日志的函数 */
+export function createAdminChannel(logger, match) {
+    const clients = new Set();
+    const logSubscribers = new Map();
+    /** 接一条已认证的 /admin 连接 */
+    function accept(ws) {
+        clients.add(ws);
+        ws.on('message', data => {
+            const message = messageOf(String(data));
+            const filter = message?.type === 'log.subscribe' ? parseLogFilter(message.filter) : undefined;
+            if (filter)
+                logSubscribers.set(ws, match(filter));
+            else if (message?.type === 'log.unsubscribe')
+                logSubscribers.delete(ws);
+            else
+                logger.warn('WebUI /admin 收到认不出的消息，已忽略');
+        });
+        ws.on('close', () => {
+            clients.delete(ws);
+            logSubscribers.delete(ws);
+        });
+    }
+    /** 推一个事件：日志推给订阅了、符合筛选的连接，其余推给全部连接 */
+    function send(event) {
+        const json = JSON.stringify(event);
+        const targets = event.type === 'log'
+            ? [...logSubscribers].flatMap(([ws, accepts]) => (accepts(event.entry) ? [ws] : []))
+            : clients;
+        for (const ws of targets) {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(json);
+        }
+    }
+    return { accept, send };
+}
+//# sourceMappingURL=admin-channel.js.map

package/dist/admin-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-channel.js","sourceRoot":"","sources":["../src/admin-channel.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,oCAAoC;AACpC,EAAE;AACF,0DAA0D;AAC1D,6EAA6E;AAC7E,4DAA4D;AAC5D,kCAAkC;AAClC,+DAA+D;AAI/D,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC;AAEnC,2CAA2C;AAC3C,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,KAA0D;IAC3G,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;IACrC,MAAM,cAAc,GAAG,IAAI,GAAG,EAA2C,CAAC;IAE1E,wBAAwB;IACxB,SAAS,MAAM,CAAC,EAAa;QAC3B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE;YACtB,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,OAAO,EAAE,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9F,IAAI,MAAM;gBAAE,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;iBAC7C,IAAI,OAAO,EAAE,IAAI,KAAK,iBAAiB;gBAAE,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;;gBACnE,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAClB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACnB,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,qCAAqC;IACrC,SAAS,IAAI,CAAC,KAAsB;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,OAAO,GACX,KAAK,CAAC,IAAI,KAAK,KAAK;YAClB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpF,CAAC,CAAC,OAAO,CAAC;QACd,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI;gBAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/attention.d.ts

@@ -0,0 +1,36 @@
+import type { Approval } from '@aalis/api-approval';
+import type { HostConfig } from '@aalis/api-host-config';
+import type { SessionManagerService } from '@aalis/api-session-manager';
+import type { AttentionItem, Notice, PluginBlockers, WebuiAdminEvent } from '@aalis/api-webui';
+import type { PluginManagerService, PluginStatusEntry, ServiceSelection, Services } from '@aalis/core';
+/** 算插件没起来的原因要读的：插件状态与定义、当前有提供者的服务名、配置文档（宿主不提供时读运行态配置） */
+interface BlockerSources {
+    plugins: Pick<PluginManagerService, 'getStatus' | 'getPlugin'>;
+    services: Pick<Services, 'names'>;
+    doc?: Pick<HostConfig, 'getPluginConfig'>;
+}
+/** 插件状态快照，每个实例带上没起来的原因 */
+export declare function blockedStatus({ plugins, services, doc }: BlockerSources): Array<PluginStatusEntry & PluginBlockers>;
+interface AttentionDeps {
+    /** 推出未结的审批；审批服务不在时没有 */
+    approvals(): readonly Approval[];
+    /** 会话管理：审批所在会话的标题 */
+    sessions: Pick<ServiceSelection<Pick<SessionManagerService, 'getSession'>>, 'present' | 'use'>;
+    /** 插件状态与没起来的原因；插件管理服务不在时为空 */
+    plugins(): ReadonlyArray<PluginStatusEntry & PluginBlockers>;
+    /** 登记着的提示，带所属实例 */
+    notices(): ReadonlyArray<Notice & {
+        instance: string;
+    }>;
+    send(event: WebuiAdminEvent): void;
+}
+export declare function createAttention(deps: AttentionDeps): {
+    /** 审批在前，其后是插件故障与提示，各按先后 */
+    items: () => AttentionItem[];
+    /** 审批推出或结算了 */
+    changed: () => void;
+    /** 插件登记表重算过：故障（连同链与根）变了才推 */
+    pluginsChanged(): void;
+};
+export {};
+//# sourceMappingURL=attention.d.ts.map

package/dist/attention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention.d.ts","sourceRoot":"","sources":["../src/attention.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvG,yDAAyD;AACzD,UAAU,cAAc;IACtB,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;IAC/D,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;CAC3C;AAED,0BAA0B;AAC1B,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,KAAK,CAAC,iBAAiB,GAAG,cAAc,CAAC,CAgBnH;AAED,UAAU,aAAa;IACrB,wBAAwB;IACxB,SAAS,IAAI,SAAS,QAAQ,EAAE,CAAC;IACjC,qBAAqB;IACrB,QAAQ,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,CAAC;IAC/F,8BAA8B;IAC9B,OAAO,IAAI,aAAa,CAAC,iBAAiB,GAAG,cAAc,CAAC,CAAC;IAC7D,mBAAmB;IACnB,OAAO,IAAI,aAAa,CAAC,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa;IA2B/C,2BAA2B;iBAChB,aAAa,EAAE;IAQ1B,eAAe;;IAEf,6BAA6B;sBACX,IAAI;EAOzB"}

package/dist/attention.js

@@ -0,0 +1,73 @@
+// ============================================================
+// attention.ts — 插件没起来的原因与「需要处理」
+//
+// 插件没起来的原因（缺、在等、待配置）在这里算一份，插件列表与「需要处理」共用：缺与在等按 api-doctor 的共享判据沿依赖链
+// 追到根，与 runtime 的启动告警、诊断同一说法；失败的另按配置 schema 校验它的配置，列出必填却没填的项。
+//
+// 「需要处理」：推出未结的审批、插件故障（失败与缺服务；只在等别的插件启动的不算）与插件的提示汇总成一个列表，每项计 1，
+// 经 GET /api/attention 给出。变了就经 /admin 推 attention.changed：审批推出或结算是变化，提示的登记与撤回由页面登记表推
+// （pages.ts）；插件登记表每次重算之后比一次故障（连同链与根），变了才推（重算很频繁，多数与故障无关）。
+// ============================================================
+import { unmetDependencies } from '@aalis/api-doctor';
+import { validateConfig } from '@aalis/schema-config';
+/** 插件状态快照，每个实例带上没起来的原因 */
+export function blockedStatus({ plugins, services, doc }) {
+    const status = plugins.getStatus();
+    const unmet = unmetDependencies(status, services.names());
+    /** 必填却没填的配置项：`''` 算没填，密钥引用算填了（validateConfig 的 missing） */
+    const unconfigured = (instanceId) => {
+        const entry = plugins.getPlugin(instanceId);
+        const config = doc ? doc.getPluginConfig(instanceId) : (entry?.config ?? {});
+        return validateConfig(entry?.definition.configSchema, config)
+            .filter(issue => issue.kind === 'missing')
+            .map(issue => issue.path);
+    };
+    return status.map(entry => ({
+        ...entry,
+        ...(unmet.get(entry.instanceId) ?? { lacking: [], waiting: [] }),
+        unconfigured: entry.state === 'error' ? unconfigured(entry.instanceId) : [],
+    }));
+}
+export function createAttention(deps) {
+    const faults = () => deps.plugins().flatMap(({ instanceId, state, error, lacking, waiting, unconfigured }) => state === 'error' || (state === 'pending' && lacking.length > 0)
+        ? [
+            {
+                kind: 'plugin',
+                instance: instanceId,
+                state,
+                ...(error !== undefined && { error }),
+                lacking,
+                waiting,
+                unconfigured,
+            },
+        ]
+        : []);
+    const titleOf = (sessionId) => {
+        const info = deps.sessions.present ? deps.sessions.use.getSession(sessionId) : undefined;
+        return info && (info.title || info.name);
+    };
+    let reported = JSON.stringify(faults());
+    const changed = () => deps.send({ type: 'attention.changed' });
+    return {
+        /** 审批在前，其后是插件故障与提示，各按先后 */
+        items: () => [
+            ...deps.approvals().map(({ id, sessionId, tool }) => {
+                const session = titleOf(sessionId);
+                return { kind: 'approval', id, sessionId, ...(session !== undefined && { session }), tool };
+            }),
+            ...faults(),
+            ...deps.notices().map(notice => ({ kind: 'notice', ...notice })),
+        ],
+        /** 审批推出或结算了 */
+        changed,
+        /** 插件登记表重算过：故障（连同链与根）变了才推 */
+        pluginsChanged() {
+            const now = JSON.stringify(faults());
+            if (now === reported)
+                return;
+            reported = now;
+            changed();
+        },
+    };
+}
+//# sourceMappingURL=attention.js.map

package/dist/attention.js.map

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

package/dist/auth.d.ts

@@ -1,10 +1,23 @@
 import type { IncomingMessage } from 'node:http';
 import type { UserIdentity } from '@aalis/api-authority';
 import type { ProcessService } from '@aalis/api-process';
-import type { RequestHandler } from 'express';
+import type express from 'express';
+/** 失败计数表最多记这么多个地址：满了再记新地址时丢掉最早的那条，内存有界，也不因此变成全局锁定 */
+export declare const LOGIN_FAILURE_ADDRESSES_MAX = 10000;
+/**
+ * 请求的来源能不能收，WebSocket 升级与改状态的请求（非 GET）共用。浏览器发起的握手与 POST 一律带 Origin，只收与本服务同源的：
+ * Origin 的主机与端口等于请求的 Host。同一主机别的端口上的网页与本服务同站，SameSite cookie 会随它的请求发出，
+ * 靠这一关拦下。没有 Origin 的是浏览器之外的客户端（脚本、命令行），不会被别的网页借用户的浏览器发起，交给 token。
+ * Host 按 Origin 的协议解析后再比，两边的默认端口都去掉（代理转来的 Host 可能写成 `x:443`）。
+ * 经反向代理访问时，代理要把原始的 Host 转给本服务。
+ */
+export declare function originAllowed(req: Pick<IncomingMessage, 'headers'>): boolean;
 export interface AuthSystem {
-    /** Express 中间件：处理 ?token= 重定向、登录端点、未认证拦截、登录页 */
-    middleware: RequestHandler;
+    /**
+     * 挂上认证，要在 JSON 解析之后、其余路由之前：改状态的请求先核来源，再是登录页的脚本、`?token=` 一键登录、登录、
+     * 登录状态与注销，其余未登录的请求一律拦下（API 回 401，GET 页面回登录页）
+     */
+    install(expressApp: express.Express): void;
     /** 校验 WebSocket 升级请求是否已认证（cookie 读取） */
     verifyWsClient(req: IncomingMessage): boolean;
     /** 解析调用者身份：单 token 模式 → `webui:console`（owner 级，单人语义）；未认证 → undefined。 */
@@ -16,6 +29,12 @@ export interface AuthSystem {
  * - token 由调用方经 getToken 提供，每次校验现取：persist 模式下 storage 晚上线时，调用方会把
  *   启动时的临时 token 换成读回的持久化 token（见 index.ts 的 token 解析）
  * - HttpOnly + SameSite=Strict cookie；`?token=` 一键登录；同源 POST /api/auth/login 提交
+ * - 改状态的请求（非 GET、HEAD、OPTIONS）按 {@link originAllowed} 校验来源，与 WebSocket 升级同一个判定：SameSite 按站判、
+ *   不分端口，同一主机别的端口上的网页发一个简单 POST 就会带上 cookie
+ * - `?token=` 与登录接口按来源地址限速：失败计数见 LOGIN_MAX_FAILURES、LOGIN_FAILURE_WINDOW_MS，成功清零。
+ *   别的网页借 owner 的浏览器发起的登录（跨源的 POST、别的站点打开的 `?token=`）不比对也不计数，免得别人替 owner 把
+ *   地址锁住。带 cookie 的请求不计数：各种模式的 token 都够长（随机生成的 24 字节，固定的至少 32 个字符），
+ *   按 cookie 逐个猜猜不中；对 cookie 也锁定的话，共用一个来源地址（同一个反向代理）的已登录页面会被别人一起锁住
  * - 身份恒为 `webui:console`（owner 级，单人模式语义）
  */
 export declare function createAuthSystem(getToken: () => string): AuthSystem;

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA0E9C,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,UAAU,EAAE,cAAc,CAAC;IAC3B,wCAAwC;IACxC,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;IAC9C,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,YAAY,GAAG,SAAS,CAAC;CAC3E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,UAAU,CAiFnE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAwBnE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AASnC,qDAAqD;AACrD,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAclD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,OAAO,CAO5E;AAmGD,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3C,wCAAwC;IACxC,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;IAC9C,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,YAAY,GAAG,SAAS,CAAC;CAC3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,UAAU,CA4InE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAwBnE"}

package/dist/auth.js

@@ -1,4 +1,48 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { BUILTIN_THEMES, DEFAULT_THEMES } from '@aalis/api-webui';
+import { route } from './route.js';
 const TOKEN_COOKIE = 'aalis_webui_token';
+/** 同一来源地址在一个窗口内登录失败满这么多次，到窗口结束前它的登录一律回 429（正确的 token 也不收） */
+const LOGIN_MAX_FAILURES = 10;
+/** 登录失败的计数窗口，从这个地址的第一次失败算起；窗口结束自动解除，计数归零 */
+const LOGIN_FAILURE_WINDOW_MS = 10 * 60 * 1000;
+/** 失败计数表最多记这么多个地址：满了再记新地址时丢掉最早的那条，内存有界，也不因此变成全局锁定 */
+export const LOGIN_FAILURE_ADDRESSES_MAX = 10_000;
+/**
+ * token 的定时安全比较：两边先取 SHA-256 摘要再逐字节比，比较耗时与 token 的内容和长度都无关，
+ * 逐字节试探与按长度试探都得不到信号。
+ */
+function tokenEquals(given, expected) {
+    const digest = (s) => createHash('sha256').update(s).digest();
+    return timingSafeEqual(digest(given), digest(expected));
+}
+/** 不改状态的请求方法：不校验来源 */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/**
+ * 请求的来源能不能收，WebSocket 升级与改状态的请求（非 GET）共用。浏览器发起的握手与 POST 一律带 Origin，只收与本服务同源的：
+ * Origin 的主机与端口等于请求的 Host。同一主机别的端口上的网页与本服务同站，SameSite cookie 会随它的请求发出，
+ * 靠这一关拦下。没有 Origin 的是浏览器之外的客户端（脚本、命令行），不会被别的网页借用户的浏览器发起，交给 token。
+ * Host 按 Origin 的协议解析后再比，两边的默认端口都去掉（代理转来的 Host 可能写成 `x:443`）。
+ * 经反向代理访问时，代理要把原始的 Host 转给本服务。
+ */
+export function originAllowed(req) {
+    const { origin, host } = req.headers;
+    if (origin === undefined)
+        return true;
+    if (host === undefined || !URL.canParse(origin))
+        return false;
+    const { protocol, host: originHost } = new URL(origin);
+    const target = `${protocol}//${host}`;
+    return URL.canParse(target) && new URL(target).host === originHost;
+}
+/**
+ * 这次导航是不是别的网页发起的：Sec-Fetch-Site 为 cross-site 或 same-site。粘贴链接、书签与启动时自动打开的
+ * 一键登录链接是 none，本服务自己页面里的跳转是 same-origin；不带这个头的（浏览器之外的客户端、旧浏览器）不算
+ */
+function navigatedFromOtherSite(req) {
+    const site = req.headers['sec-fetch-site'];
+    return site === 'cross-site' || site === 'same-site';
+}
 function parseCookieValue(header, name) {
     if (!header)
         return undefined;
@@ -24,45 +68,58 @@ function buildSetCookie(name, value, maxAgeSec) {
 function buildClearCookie(name) {
     return `${name}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0`;
 }
-/** 登录页：自包含 HTML，不引入外部资源；提交 POST /api/auth/login 后刷新到 / */
+/** 登录页的脚本：文档级 CSP 只许同源脚本，不内联，由这个地址给出（不需登录） */
+const LOGIN_SCRIPT_PATH = '/api/auth/login.js';
+/** 提交 POST /api/auth/login，成功后刷新到 / */
+const LOGIN_SCRIPT = `const f=document.getElementById('f'),t=document.getElementById('t'),b=document.getElementById('b'),e=document.getElementById('e');
+f.addEventListener('submit',async ev=>{
+  ev.preventDefault();e.textContent='';b.disabled=true;
+  try{
+    const r=await fetch('/api/auth/login',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({token:t.value.trim()})});
+    if(r.ok){location.replace('/');}else{const j=await r.json().catch(()=>({}));e.textContent=j.error||'token 不正确';b.disabled=false;t.select();}
+  }catch(err){e.textContent='网络错误';b.disabled=false;}
+});
+`;
+/** 一个内置主题的颜色令牌，写成 CSS 自定义属性的声明 */
+const themeTokens = (id) => Object.entries(BUILTIN_THEMES[id].colors)
+    .map(([name, value]) => `${name}:${value}`)
+    .join(';');
+/**
+ * 登录页的样式：颜色取默认主题的令牌，深浅跟随系统（界面在登录之后才读得到本浏览器选的主题）。与界面同一套写法：
+ * 不用卡片、不加阴影，圆角用小档
+ */
+const LOGIN_STYLE = `:root{color-scheme:light dark;${themeTokens(DEFAULT_THEMES.dark)}}
+@media (prefers-color-scheme: light){:root{${themeTokens(DEFAULT_THEMES.light)}}}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;min-height:100dvh;display:flex;align-items:center;justify-content:center;padding:1rem;font-family:system-ui,-apple-system,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;font-size:0.875rem;line-height:1.375rem;background:var(--color-bg);color:var(--color-text)}
+form{width:min(22.5rem,100%);display:flex;flex-direction:column;gap:0.75rem}
+h1{margin:0;font-size:1rem;line-height:1.5rem;font-weight:600}
+p{margin:0;color:var(--color-text-2)}
+p.note{color:var(--color-warning-text)}
+input{width:100%;height:2.25rem;padding:0 0.75rem;font-family:ui-monospace,"SF Mono",Menlo,Consolas,monospace;font-size:1rem;color:var(--color-text);background:transparent;border:1px solid var(--color-border-control);border-radius:4px}
+input:focus-visible,button:focus-visible{outline:2px solid var(--color-focus);outline-offset:2px}
+button{height:2.25rem;font:inherit;font-weight:500;color:var(--color-on-accent);background:var(--color-accent);border:0;border-radius:4px;cursor:pointer}
+button:hover{background:var(--color-accent-hover)}
+button:disabled{opacity:0.6;cursor:wait}
+.err{min-height:1.375rem;color:var(--color-danger-text)}`;
+/** 登录页：只引用同源的登录脚本，不引入别的资源 */
 function loginPageHtml(reason) {
     const note = reason ? `<p class="note">${escapeHtml(reason)}</p>` : '';
     return `<!DOCTYPE html><html lang="zh-CN"><head>
 <meta charset="utf-8"><title>Aalis WebUI 登录</title>
 <meta name="viewport" content="width=device-width,initial-scale=1">
 <style>
-:root{color-scheme:light dark}
-*{box-sizing:border-box}
-body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#0b0d10;color:#e6e8eb}
-.card{width:min(420px,90vw);padding:32px;background:#16191d;border:1px solid #262b32;border-radius:12px;box-shadow:0 12px 36px rgba(0,0,0,.4)}
-h1{margin:0 0 8px;font-size:22px;font-weight:600}
-p{margin:0 0 16px;color:#8b95a1;font-size:14px;line-height:1.5}
-p.note{color:#ffb300}
-input{width:100%;padding:10px 12px;font-size:14px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;background:#0b0d10;color:#e6e8eb;border:1px solid #2a3038;border-radius:6px;outline:none}
-input:focus{border-color:#5b8def}
-button{width:100%;margin-top:12px;padding:10px;font-size:14px;font-weight:500;background:#5b8def;color:#fff;border:0;border-radius:6px;cursor:pointer}
-button:hover{background:#4a7de0}
-button:disabled{opacity:.5;cursor:wait}
-.err{margin-top:10px;color:#ff6b6b;font-size:13px;min-height:18px}
+${LOGIN_STYLE}
 </style></head>
-<body><form class="card" id="f">
+<body><form id="f">
 <h1>Aalis WebUI</h1>
-<p>请输入启动日志或 data/webui/access.txt 中显示的访问 token。</p>
+<p>访问 token 在家目录的 state/webui/access.txt 里，启动日志「访问凭据已写入」那行给出它的完整路径；tokenMode 为 fixed 时它是配置项 fixedToken，启动后值存在家目录的 secrets.yaml 里（配置文件里是引用）。</p>
 ${note}
 <input id="t" type="password" autocomplete="off" placeholder="访问 token" autofocus required>
 <button type="submit" id="b">登录</button>
 <div class="err" id="e"></div>
 </form>
-<script>
-const f=document.getElementById('f'),t=document.getElementById('t'),b=document.getElementById('b'),e=document.getElementById('e');
-f.addEventListener('submit',async ev=>{
-  ev.preventDefault();e.textContent='';b.disabled=true;
-  try{
-    const r=await fetch('/api/auth/login',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({token:t.value.trim()})});
-    if(r.ok){location.replace('/');}else{const j=await r.json().catch(()=>({}));e.textContent=j.error||'token 不正确';b.disabled=false;t.select();}
-  }catch(err){e.textContent='网络错误';b.disabled=false;}
-});
-</script></body></html>`;
+<script src="${LOGIN_SCRIPT_PATH}"></script></body></html>`;
 }
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
@@ -73,77 +130,144 @@ function escapeHtml(s) {
  * - token 由调用方经 getToken 提供，每次校验现取：persist 模式下 storage 晚上线时，调用方会把
  *   启动时的临时 token 换成读回的持久化 token（见 index.ts 的 token 解析）
  * - HttpOnly + SameSite=Strict cookie；`?token=` 一键登录；同源 POST /api/auth/login 提交
+ * - 改状态的请求（非 GET、HEAD、OPTIONS）按 {@link originAllowed} 校验来源，与 WebSocket 升级同一个判定：SameSite 按站判、
+ *   不分端口，同一主机别的端口上的网页发一个简单 POST 就会带上 cookie
+ * - `?token=` 与登录接口按来源地址限速：失败计数见 LOGIN_MAX_FAILURES、LOGIN_FAILURE_WINDOW_MS，成功清零。
+ *   别的网页借 owner 的浏览器发起的登录（跨源的 POST、别的站点打开的 `?token=`）不比对也不计数，免得别人替 owner 把
+ *   地址锁住。带 cookie 的请求不计数：各种模式的 token 都够长（随机生成的 24 字节，固定的至少 32 个字符），
+ *   按 cookie 逐个猜猜不中；对 cookie 也锁定的话，共用一个来源地址（同一个反向代理）的已登录页面会被别人一起锁住
  * - 身份恒为 `webui:console`（owner 级，单人模式语义）
  */
 export function createAuthSystem(getToken) {
     const cookieMaxAge = 30 * 24 * 3600; // 30d；进程重启 token 轮换后无效
+    // 登录失败按来源地址计数。本机回环也计数：经同机反向代理来的请求全是回环地址，豁免回环等于不限速；
+    // owner 自己输错满额也只等到窗口结束，已登录的页面不受影响。
+    // 时间取单调时钟，键的插入顺序就是窗口结束的先后，过期的从表头剪掉；表满时也从表头丢，最多 LOGIN_FAILURE_ADDRESSES_MAX 条。
+    const failures = new Map();
+    /** 这个地址还要等多少毫秒才能再登录，不受限时为 0；先剪掉窗口已过的计数 */
+    function lockedFor(address) {
+        const now = performance.now();
+        for (const [key, entry] of failures) {
+            if (entry.resetAt > now)
+                break;
+            failures.delete(key);
+        }
+        const entry = failures.get(address);
+        return entry && entry.count >= LOGIN_MAX_FAILURES ? entry.resetAt - now : 0;
+    }
+    /** 记一次失败；须紧跟在 lockedFor 之后调用，表里留着的计数都还在窗口内 */
+    function recordFailure(address) {
+        const entry = failures.get(address);
+        if (entry) {
+            entry.count++;
+            return;
+        }
+        if (failures.size >= LOGIN_FAILURE_ADDRESSES_MAX)
+            failures.delete(failures.keys().next().value);
+        failures.set(address, { count: 1, resetAt: performance.now() + LOGIN_FAILURE_WINDOW_MS });
+    }
+    /** 给被限速的登录写好 429 与 Retry-After，返回给人看的说明 */
+    function rejectLocked(res, waitMs) {
+        res.status(429);
+        res.setHeader('Retry-After', String(Math.ceil(waitMs / 1000)));
+        return `登录失败次数过多，请 ${Math.ceil(waitMs / 60_000)} 分钟后再试。`;
+    }
     function tokenAuthed(req) {
         const cookieToken = parseCookieValue(req.headers.cookie, TOKEN_COOKIE);
-        return !!cookieToken && cookieToken === getToken();
+        return !!cookieToken && tokenEquals(cookieToken, getToken());
     }
     function identify(req) {
         return tokenAuthed(req) ? { platform: 'webui', userId: 'console' } : undefined;
     }
-    const middleware = (req, res, next) => {
-        const url = req.path;
-        const qToken = typeof req.query?.token === 'string' ? req.query.token : undefined;
-        // 1. ?token= 命中 → 设置 cookie → 302 到不带 query 的同路径
-        if (req.method === 'GET' && qToken) {
+    const addressOf = (req) => req.socket.remoteAddress ?? '';
+    function install(expressApp) {
+        // 改状态的请求先看来源：别的网页借 owner 的浏览器发来的（带着 cookie）一律拒，登录与注销也一样
+        expressApp.use((req, res, next) => {
+            if (SAFE_METHODS.has(req.method) || originAllowed(req))
+                return next();
+            res
+                .status(403)
+                .json({ error: '请求来源与本服务不同源（经反向代理访问时，代理要转发原始的 Host）' });
+        });
+        // 登录页的脚本不需登录
+        route(expressApp, 'GET /api/auth/login.js', (_req, res) => {
+            res.type('application/javascript').send(LOGIN_SCRIPT);
+        });
+        // ?token= 命中 → 设置 cookie → 302 到同一路径，只去掉 token，其余查询串（如日志的筛选）照留。别的站点打开的不认 token，
+        // 按没带 token 往下走
+        expressApp.use((req, res, next) => {
+            const qToken = typeof req.query?.token === 'string' ? req.query.token : undefined;
+            if (req.method !== 'GET' || !qToken || navigatedFromOtherSite(req))
+                return next();
+            const address = addressOf(req);
+            const waitMs = lockedFor(address);
+            if (waitMs > 0) {
+                const note = rejectLocked(res, waitMs);
+                res.type('html').send(loginPageHtml(note));
+                return;
+            }
             const token = getToken();
-            if (qToken === token) {
+            if (tokenEquals(qToken, token)) {
+                failures.delete(address);
                 res.setHeader('Set-Cookie', buildSetCookie(TOKEN_COOKIE, token, cookieMaxAge));
-                res.redirect(302, url);
+                const rest = new URLSearchParams(req.originalUrl.slice(req.originalUrl.indexOf('?') + 1));
+                rest.delete('token');
+                const search = rest.toString();
+                res.redirect(302, search ? `${req.path}?${search}` : req.path);
                 return;
             }
+            recordFailure(address);
             res.status(401).type('html').send(loginPageHtml('URL 中的 token 不正确，请手动输入。'));
-            return;
-        }
-        // 2. 登录端点：{token}
-        if (url === '/api/auth/login' && req.method === 'POST') {
+        });
+        // 登录：{ token }。跨源的已在上面拒掉，不计数
+        route(expressApp, 'POST /api/auth/login', (req, res) => {
+            const address = addressOf(req);
+            const waitMs = lockedFor(address);
+            if (waitMs > 0) {
+                res.json({ error: rejectLocked(res, waitMs) });
+                return;
+            }
             const body = req.body ?? {};
             const token = getToken();
-            if (typeof body.token === 'string' && body.token === token) {
+            if (typeof body.token === 'string' && tokenEquals(body.token, token)) {
+                failures.delete(address);
                 res.setHeader('Set-Cookie', buildSetCookie(TOKEN_COOKIE, token, cookieMaxAge));
                 res.json({ ok: true, identity: { platform: 'webui', userId: 'console' } });
             }
             else {
-                res.status(401).json({ ok: false, error: 'token 不正确' });
+                recordFailure(address);
+                res.status(401).json({ error: 'token 不正确' });
             }
-            return;
-        }
-        // 3. 状态查询（含当前身份，供前端顶栏展示）
-        if (url === '/api/auth/status' && req.method === 'GET') {
+        });
+        // 登录状态（含当前身份，供前端顶栏展示）
+        route(expressApp, 'GET /api/auth/status', (req, res) => {
             const identity = identify(req);
             res.json({ authed: !!identity, identity });
-            return;
-        }
-        // 4. 注销：清 token cookie
-        if (url === '/api/auth/logout' && req.method === 'POST') {
+        });
+        // 注销：清 token cookie
+        route(expressApp, 'POST /api/auth/logout', (_req, res) => {
             res.setHeader('Set-Cookie', buildClearCookie(TOKEN_COOKIE));
             res.json({ ok: true });
-            return;
-        }
-        // 5. 已认证 → 放行
-        if (tokenAuthed(req)) {
-            next();
-            return;
-        }
-        // 6. 未认证：API 一律 401
-        if (url.startsWith('/api/')) {
-            res.status(401).json({ error: 'unauthenticated' });
-            return;
-        }
-        // 7. 未认证 GET：返回内联登录页（覆盖 SPA shell，不暴露任何静态资源）
-        if (req.method === 'GET') {
-            res.status(401).type('html').send(loginPageHtml());
-            return;
-        }
-        res.status(401).end();
-    };
+        });
+        // 已登录的放行；没登录的 API 一律 401，GET 回内联登录页（覆盖 SPA shell，不暴露任何静态资源）
+        expressApp.use((req, res, next) => {
+            if (tokenAuthed(req))
+                return next();
+            if (req.path.startsWith('/api/')) {
+                res.status(401).json({ error: 'unauthenticated' });
+                return;
+            }
+            if (req.method === 'GET') {
+                res.status(401).type('html').send(loginPageHtml());
+                return;
+            }
+            res.status(401).end();
+        });
+    }
     function verifyWsClient(req) {
         return tokenAuthed(req);
     }
-    return { middleware, verifyWsClient, identify };
+    return { install, verifyWsClient, identify };
 }
 /**
  * 跨平台打开默认浏览器到指定 URL（无外部依赖）