dsh-plugin-tool-management 0.5.1 → 0.7.0

package/lib/http-fence.js

@@ -0,0 +1,94 @@
+// 插件 HTTP 路由的请求栅栏。
+//
+// 为什么需要它：宿主的 BrowserAuth 栅栏**只包在宿主自己注册的路由上**
+// （dsh-client-connection 的 register()/upgrade、dsh-api-gateway、
+// dsh-host-open-in-app），dsh-host-webserver 本身没有全局中间件。宿主生态的
+// 既定约定是每个注册方自己调 `connection.requestRejection(req)`，它做两件事：
+//
+//   1. Host/Origin 栅栏 —— Host 必须是回环地址、deployment 派生的 LAN IP 字面量
+//      或声明的 trustedHosts。Host 是 DNS rebinding 唯一伪造不了的头：攻击者
+//      控制域名 → 浏览器发 `Host: evil.com`，但插件的自比对式 Origin 检查
+//      （origin.host === host）会同时成立，于是被误判为同源。
+//   2. browser-session cookie 鉴权（HttpOnly + SameSite=Strict，Path=/）。
+//
+// 只查公开常量 `x-dsh-plugin` 与自比对 Origin 等于没鉴权：本机任意进程都能调写 op，
+// 而写 op 里包含 `mcpm-add`（command/args 无白名单，宿主 stdio 传输会 spawn 它
+// → 任意命令执行）与 `history-delete`（永久删除会话）。
+const headerValue = (req, name) => {
+    const v = req.headers?.[name];
+    return Array.isArray(v) ? v[0] ?? '' : v ?? '';
+};
+/**
+ * 判定请求是否应被拒（返回 null = 放行）。
+ *
+ * 优先用宿主栅栏；它不在场时（非 web 组合、服务未注册）退回等价的本地判定，
+ * 而不是静默放行。栅栏自身抛错时同样退回本地判定 —— 宁可拒绝也不要因为宿主
+ * 内部变动而变成开放路由。
+ *
+ * @param req - Node 请求对象（只读 headers）。
+ * @param connection - ctx.get('connection')，可缺失。
+ */
+export function fenceRejection(req, connection) {
+    try {
+        const rejection = connection?.requestRejection?.(req);
+        if (typeof rejection === 'number') {
+            return {
+                status: rejection,
+                error: rejection === 401
+                    ? '未通过宿主的浏览器鉴权：请在 DSH Web GUI 内操作，或为本插件配置访问令牌（config.token / DSH_PLUGIN_TOOL_MANAGEMENT_TOKEN）'
+                    : 'Host/Origin 栅栏拒绝：该请求不是发往本机地址的同源请求',
+            };
+        }
+        // 栅栏在场且未返回拒绝码 ⇒ 已通过，不再叠加本地判定（宿主的 trustedHosts
+        // 部署信息这里拿不到，重复判定只会更松或更严，都不对）。
+        if (typeof connection?.requestRejection === 'function')
+            return null;
+    }
+    catch (e) { /* 见上方说明：退回本地判定 */ }
+    const hostHdr = headerValue(req, 'host');
+    let host;
+    try {
+        host = new URL('http://' + hostHdr);
+    }
+    catch {
+        return { status: 403, error: 'Host 头缺失或无法解析' };
+    }
+    const loopback = host.hostname === 'localhost' || host.hostname === '[::1]'
+        || /^127(?:\.\d{1,3}){3}$/.test(host.hostname);
+    if (!loopback)
+        return { status: 403, error: 'Host 必须是本机回环地址（防 DNS rebinding）' };
+    if (headerValue(req, 'sec-fetch-site') === 'cross-site')
+        return { status: 403, error: '跨站请求被拒' };
+    const origin = headerValue(req, 'origin');
+    if (origin) {
+        try {
+            if (new URL(origin).host !== host.host)
+                return { status: 403, error: '跨源请求被拒' };
+        }
+        catch {
+            return { status: 403, error: 'Origin 头无法解析' };
+        }
+    }
+    return null;
+}
+/**
+ * 判定敏感 op 是否应被拒（返回 null = 放行）。
+ *
+ * 两种情况分开报，因为处置方式不同：没配令牌要去宿主配置里加，配了但没带/带错
+ * 只要在界面里填对即可（界面按 code 决定给不给输入框）。
+ */
+export function secretOpRejection(state) {
+    if (!state.tokenConfigured) {
+        return {
+            code: 'error.secret.noToken',
+            error: '明文查看与导出已被禁用：宿主未配置访问令牌。请在本插件配置里加 token（或设环境变量 DSH_PLUGIN_TOOL_MANAGEMENT_TOKEN）后重启 DSH，再在界面上填入同一个令牌。',
+        };
+    }
+    if (!state.tokenAccepted) {
+        return {
+            code: 'error.secret.badToken',
+            error: '访问令牌缺失或不正确：请在界面里填入与宿主配置相同的令牌（随请求以 x-dsh-token 发送）。',
+        };
+    }
+    return null;
+}

package/lib/hub.js

@@ -24,8 +24,9 @@
 //      搬不动的（被占用、跨卷失败）留在原地，下次启动再试。
 //   2. **绝不覆盖**——目标已存在同名项时跳过该项，保留目标。
 //   3. **每进程一次**——迁移是启动期的一次性动作，失败也不阻断服务（旧目录仍可读）。
-import { cp, lstat, mkdir, readdir, rename, rm } from 'node:fs/promises';
-import { join } from 'node:path';
+import { cp, lstat, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join, dirname } from 'node:path';
 import { resolveDshHome } from './skills/core.js';
 /** hub 根目录名（`$DSH_HOME` 下）。 */
 export const HUB_DIR = 'tool-management';
@@ -92,3 +93,160 @@ export async function relocateEntries(from, to, filter) {
     }
     return moved;
 }
+/** 某一类回收站的根目录：`hub/trash/<kind>-trash`。 */
+export function trashKindDir(kind) {
+    return hubPath('trash', `${kind}-trash`);
+}
+/** 新条目 id（时间戳 base36 + uuid 前 8 位，与记忆回收站同形）。 */
+export function newTrashId() {
+    return Date.now().toString(36) + '-' + randomUUID().slice(0, 8);
+}
+/** id 只由本模块生成：严格白名单，杜绝路径穿越。 */
+export function isValidTrashId(id) {
+    return /^[a-z0-9]+-[a-z0-9]{1,32}$/i.test(id);
+}
+/** 条目目录（id 非法时返回 null）。 */
+export function trashEntryPath(kind, id) {
+    if (!isValidTrashId(id))
+        return null;
+    return join(trashKindDir(kind), id);
+}
+async function readManifest(kind, id) {
+    const dir = trashEntryPath(kind, id);
+    if (dir === null)
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        if (String(parsed.kind) !== kind || String(parsed.id) !== id)
+            return null;
+        return {
+            v: Number(parsed.v) || 1,
+            kind,
+            id,
+            name: String(parsed.name ?? ''),
+            deletedAt: String(parsed.deletedAt ?? ''),
+            files: Array.isArray(parsed.files) ? parsed.files.map((n) => String(n)) : [],
+            ...(parsed.data === undefined ? {} : { data: parsed.data }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把一个文件/目录移入回收站（新建条目）。
+ *
+ * @param kind 种类（决定子目录）
+ * @param name 恢复时用的名字
+ * @param moves 要搬的项：`from` 绝对路径 → 条目目录内的 `dest` 名
+ * @param data 可选的非文件型负载（如场景的记录与档案）
+ */
+export async function moveToTrash(kind, name, moves, data) {
+    const id = newTrashId();
+    const dir = join(trashKindDir(kind), id);
+    const done = [];
+    try {
+        await mkdir(dir, { recursive: true });
+        for (const move of moves) {
+            const to = join(dir, move.dest);
+            try {
+                await rename(move.from, to);
+            }
+            catch {
+                // 跨卷 / 被占用 → 复制后删源；两步都失败就抛出去走回滚。
+                await cp(move.from, to, { recursive: true });
+                await rm(move.from, { recursive: true, force: true });
+            }
+            done.push({ from: move.from, to });
+        }
+        const manifest = {
+            v: 1,
+            kind,
+            id,
+            name,
+            deletedAt: new Date().toISOString(),
+            files: moves.map((m) => m.dest),
+            ...(data === undefined ? {} : { data }),
+        };
+        await writeFile(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+        return { ok: true, id };
+    }
+    catch (e) {
+        // 回滚：把已经搬走的搬回原处，再删掉半成品条目目录。
+        for (const item of done.reverse()) {
+            try {
+                await rename(item.to, item.from);
+            }
+            catch {
+                try {
+                    await cp(item.to, item.from, { recursive: true });
+                    await rm(item.to, { recursive: true, force: true });
+                }
+                catch { /* 回滚失败：把原因交给调用方的错误信息 */ }
+            }
+        }
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        return { ok: false, error: String(e?.message ?? e) };
+    }
+}
+/** 列出某一类回收站的条目（按删除时间倒序）。 */
+export async function listTrashEntries(kind) {
+    let names;
+    try {
+        names = (await readdir(trashKindDir(kind), { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const id of names) {
+        const manifest = await readManifest(kind, id);
+        if (!manifest)
+            continue;
+        entries.push({
+            id: manifest.id,
+            name: manifest.name,
+            deletedAt: manifest.deletedAt,
+            files: manifest.files,
+            hasData: manifest.data !== undefined,
+        });
+    }
+    return entries.sort((a, b) => (a.deletedAt === b.deletedAt ? b.id.localeCompare(a.id) : b.deletedAt.localeCompare(a.deletedAt)));
+}
+/** 读一条回收站条目的清单（不存在/损坏返回 null）。 */
+export async function readTrashEntry(kind, id) {
+    return await readManifest(kind, id);
+}
+/**
+ * 把条目里的一个负载搬回 `to`。**不覆盖**：调用方必须先确认 `to` 不存在。
+ * @throws 条目或负载缺失时抛错（调用方翻成人话）。
+ */
+export async function moveOutOfTrash(kind, id, dest, to) {
+    const dir = trashEntryPath(kind, id);
+    if (dir === null)
+        throw new Error(`回收站条目 id 非法：${id}`);
+    const from = join(dir, dest);
+    await mkdir(dirname(to), { recursive: true });
+    try {
+        await rename(from, to);
+    }
+    catch {
+        await cp(from, to, { recursive: true });
+        await rm(from, { recursive: true, force: true });
+    }
+}
+/** 永久删除一条回收站条目（连带负载）。 */
+export async function purgeTrashEntry(kind, id) {
+    const dir = trashEntryPath(kind, id);
+    if (dir === null)
+        return false;
+    const manifest = await readManifest(kind, id);
+    if (!manifest)
+        return false;
+    await rm(dir, { recursive: true, force: true });
+    return true;
+}