dsh-plugin-manager-companion 0.1.0

package/dist/rest.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 自有能力的传输层：REST 原语（信任围栏、请求体读取、响应信封、job 注册表）。
+ *
+ * 归属：A 类·重写（旧仓库把围栏、信封、job 全塞在 index.ts 里，2358 行；
+ *   这里把它们抽成可独立测试的原语）。
+ * 官方复用：ctx.webServer.register（官方公开路由 API，不经 typert 生成器）。
+ * 前提检查：见 docs/DESIGN.md 第 11 节——官方 Remote 的能力集合是编译期固定的，
+ *   第三方自带 Remote 需 typert 生成器，而其 npm 可用版本远落后于运行时。
+ *   所以自有能力走 REST，官方能力仍走官方 Remote（客户端直连）。
+ *
+ * 安全模型（这层是 host 的唯一入口，必须自己扛）：
+ *   1. 只接受 POST —— 浏览器同源 GET 会被 <img>/<script> 等载具触发，
+ *      而 POST + JSON 需要预检，天然收紧。
+ *   2. content-type 必须是 JSON —— 挡掉简单表单跨站提交。
+ *   3. Host 必须是回环或显式白名单 —— 挡 DNS-rebinding（攻击者域名解析到 127.0.0.1）。
+ *   4. Origin 存在时必须同源 —— 挡 CSRF。无 Origin 的非浏览器载体按本地语义放行，
+ *      但此时必须同时满足"无 Origin 且非 cross-site"。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** 自有 REST 的路由前缀。避开旧仓库的 /api2/plugin-manager（两包可能短期共存）。 */
+export declare const ROUTE_PREFIX = "/api2/companion";
+/** 默认请求体上限（字节）：普通操作。 */
+export declare const BODY_LIMIT_DEFAULT: number;
+/** 备份导入的请求体上限（字节）。 */
+export declare const BODY_LIMIT_BACKUP: number;
+/**
+ * 按 op 名给出请求体上限。
+ *
+ * 分级而不是统一放宽：备份导入确实可能很大，但普通操作没有理由接受兆级 body，
+ * 统一放宽等于把所有 op 的暴露面都放大。
+ *
+ * @param op - 操作名。
+ * @returns 该 op 允许的最大请求体字节数。
+ */
+export declare function bodyLimitFor(op: string): number;
+/** 成功信封。 */
+export interface OkEnvelope<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/** 失败信封。code 是稳定机器码，message 面向用户。 */
+export interface ErrEnvelope {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** 任意响应信封。 */
+export type Envelope<T> = OkEnvelope<T> | ErrEnvelope;
+/**
+ * 信任围栏：判断一个请求是否来自可信的同源浏览器上下文。
+ *
+ * 与旧实现的差别：旧版把"Host 回环判定 + Origin 同源"混在一个布尔里，且对
+ * 非 HTTP 载体（无 Host 头）的处理是在补丁里加的。这里把规则写成可穷举测试的纯函数，
+ * 并显式区分"有 Host"与"无 Host（非 HTTP 载体）"两种语义。
+ *
+ * @param req - 传入请求（只读其 headers）。
+ * @param options - 可信 Host 白名单（不含端口）与是否允许非 HTTP 载体。
+ * @returns 允许与否，以及拒绝时的机器码。
+ */
+export declare function isTrustedRequest(req: Pick<IncomingMessage, "headers" | "method">, options?: {
+    readonly trustedHosts?: readonly string[];
+    readonly allowNonHttpCarrier?: boolean;
+}): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** 判定请求是否是一个可接受的 JSON POST。 */
+export declare function isJsonPost(req: Pick<IncomingMessage, "headers" | "method">): boolean;
+/**
+ * 读取并解析 JSON 请求体，带硬上限。
+ *
+ * 上限在**读取过程中**生效（超出即停止累积并拒绝），而不是先读完再判断长度——
+ * 后者对超大 body 毫无保护。
+ *
+ * @param req - 传入请求。
+ * @param limit - 允许的最大字节数。
+ * @returns 解析结果；失败时给出机器码。
+ */
+export declare function readJsonBody<T = Record<string, unknown>>(req: AsyncIterable<Buffer | string>, limit: number): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+}>;
+/** 写一个 JSON 响应（含状态码）。 */
+export declare function sendJson(res: ServerResponse, status: number, payload: unknown): void;
+/** job 结果保留时长（毫秒）。与旧仓库一致的 30 分钟。 */
+export declare const JOB_TTL_MS: number;
+/** 同时在途的 job 上限。超出即背压拒绝，避免堆叠点击打爆进程。 */
+export declare const JOB_MAX_PENDING = 4;
+/** job 注册表（进程内）。 */
+export declare class JobRegistry {
+    private readonly jobs;
+    private seq;
+    /**
+     * 启动一个 job。
+     * @param task - 要执行的工作。
+     * @returns job id。
+     * @throws {Error} 在途数量达到上限时（调用方应回 429）。
+     */
+    start(task: () => Promise<unknown>): string;
+    /**
+     * 读一个 job 的状态。
+     * @param id - job id。
+     * @returns 状态；id 不存在（或已过期）时 `missing: true`。
+     */
+    status(id: string): {
+        done: boolean;
+        result?: unknown;
+        error?: string;
+        missing?: true;
+    };
+    /** 清掉超过 TTL 的记录。 */
+    private prune;
+}

package/dist/rest.js

@@ -0,0 +1,219 @@
+/**
+ * 自有能力的传输层：REST 原语（信任围栏、请求体读取、响应信封、job 注册表）。
+ *
+ * 归属：A 类·重写（旧仓库把围栏、信封、job 全塞在 index.ts 里，2358 行；
+ *   这里把它们抽成可独立测试的原语）。
+ * 官方复用：ctx.webServer.register（官方公开路由 API，不经 typert 生成器）。
+ * 前提检查：见 docs/DESIGN.md 第 11 节——官方 Remote 的能力集合是编译期固定的，
+ *   第三方自带 Remote 需 typert 生成器，而其 npm 可用版本远落后于运行时。
+ *   所以自有能力走 REST，官方能力仍走官方 Remote（客户端直连）。
+ *
+ * 安全模型（这层是 host 的唯一入口，必须自己扛）：
+ *   1. 只接受 POST —— 浏览器同源 GET 会被 <img>/<script> 等载具触发，
+ *      而 POST + JSON 需要预检，天然收紧。
+ *   2. content-type 必须是 JSON —— 挡掉简单表单跨站提交。
+ *   3. Host 必须是回环或显式白名单 —— 挡 DNS-rebinding（攻击者域名解析到 127.0.0.1）。
+ *   4. Origin 存在时必须同源 —— 挡 CSRF。无 Origin 的非浏览器载体按本地语义放行，
+ *      但此时必须同时满足"无 Origin 且非 cross-site"。
+ */
+/** 自有 REST 的路由前缀。避开旧仓库的 /api2/plugin-manager（两包可能短期共存）。 */
+export const ROUTE_PREFIX = "/api2/companion";
+/** 默认请求体上限（字节）：普通操作。 */
+export const BODY_LIMIT_DEFAULT = 1024 * 1024;
+/** 备份导入的请求体上限（字节）。 */
+export const BODY_LIMIT_BACKUP = 16 * 1024 * 1024;
+/**
+ * 按 op 名给出请求体上限。
+ *
+ * 分级而不是统一放宽：备份导入确实可能很大，但普通操作没有理由接受兆级 body，
+ * 统一放宽等于把所有 op 的暴露面都放大。
+ *
+ * @param op - 操作名。
+ * @returns 该 op 允许的最大请求体字节数。
+ */
+export function bodyLimitFor(op) {
+    return op === "backupRestore" ? BODY_LIMIT_BACKUP : BODY_LIMIT_DEFAULT;
+}
+/**
+ * 信任围栏：判断一个请求是否来自可信的同源浏览器上下文。
+ *
+ * 与旧实现的差别：旧版把"Host 回环判定 + Origin 同源"混在一个布尔里，且对
+ * 非 HTTP 载体（无 Host 头）的处理是在补丁里加的。这里把规则写成可穷举测试的纯函数，
+ * 并显式区分"有 Host"与"无 Host（非 HTTP 载体）"两种语义。
+ *
+ * @param req - 传入请求（只读其 headers）。
+ * @param options - 可信 Host 白名单（不含端口）与是否允许非 HTTP 载体。
+ * @returns 允许与否，以及拒绝时的机器码。
+ */
+export function isTrustedRequest(req, options = {}) {
+    const host = headerValue(req.headers["host"]);
+    const origin = headerValue(req.headers["origin"]);
+    // 非 HTTP 载体（第三方桌面壳 / app:// 自定义协议）：不带 Host 头。
+    // 这类请求没有浏览器同源模型的保护，因此要求"无 Origin 且非 cross-site"。
+    if (host === undefined) {
+        if (options.allowNonHttpCarrier !== true) {
+            return { ok: false, code: "untrusted-host", message: "request carries no Host header" };
+        }
+        if (crossSite(req.headers["sec-fetch-site"]) !== false) {
+            return { ok: false, code: "cross-site", message: "cross-site request refused" };
+        }
+        return { ok: true };
+    }
+    const hostname = stripPort(host);
+    if (!isLoopbackHost(hostname) && !(options.trustedHosts ?? []).includes(hostname)) {
+        return { ok: false, code: "untrusted-host", message: "host is not loopback or allowlisted" };
+    }
+    if (origin !== undefined) {
+        let originHost;
+        try {
+            originHost = new URL(origin).host;
+        }
+        catch {
+            return { ok: false, code: "bad-origin", message: "Origin is not a valid URL" };
+        }
+        if (originHost !== host) {
+            return { ok: false, code: "cross-origin", message: "Origin does not match Host" };
+        }
+    }
+    return { ok: true };
+}
+/** 取首值：node 的 header 可能是数组。 */
+function headerValue(raw) {
+    if (raw === undefined)
+        return undefined;
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/** 去掉 Host 里的端口（IPv6 字面量的方括号保留处理）。 */
+function stripPort(host) {
+    // IPv6 字面量形如 [::1]:3080 —— 先处理方括号形式，避免把 ::1 里的冒号当端口分隔符。
+    if (host.startsWith("[")) {
+        const close = host.indexOf("]");
+        return close === -1 ? host : host.slice(1, close);
+    }
+    const colon = host.lastIndexOf(":");
+    return colon === -1 ? host : host.slice(0, colon);
+}
+/** 回环判定：IPv4 回环段、IPv6 回环、localhost。 */
+function isLoopbackHost(hostname) {
+    if (hostname === "localhost")
+        return true;
+    if (hostname === "::1" || hostname === "0:0:0:0:0:0:0:1")
+        return true;
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+    if (v4 === null)
+        return false;
+    const first = Number(v4[1]);
+    // 严格说整个 127/8 都是回环；实践中 127.0.0.1 与 127.x.y.z 都要放行。
+    return first === 127;
+}
+/**
+ * sec-fetch-site 判定：明确为 cross-site 时返回 true，其它（含缺失）返回 false。
+ *
+ * 缺失时判 false 是刻意的：非浏览器载体不带这个头，把它当 cross-site 会让
+ * 合法载体被拒（旧仓库 issue #11）。真正的防跨站由 Origin/Host 规则承担。
+ */
+function crossSite(raw) {
+    return headerValue(raw)?.toLowerCase() === "cross-site";
+}
+/** 判定请求是否是一个可接受的 JSON POST。 */
+export function isJsonPost(req) {
+    if (req.method !== "POST")
+        return false;
+    const contentType = headerValue(req.headers["content-type"]) ?? "";
+    return contentType.split(";")[0].trim().toLowerCase() === "application/json";
+}
+/**
+ * 读取并解析 JSON 请求体，带硬上限。
+ *
+ * 上限在**读取过程中**生效（超出即停止累积并拒绝），而不是先读完再判断长度——
+ * 后者对超大 body 毫无保护。
+ *
+ * @param req - 传入请求。
+ * @param limit - 允许的最大字节数。
+ * @returns 解析结果；失败时给出机器码。
+ */
+export async function readJsonBody(req, limit) {
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of req) {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            size += buf.byteLength;
+            if (size > limit) {
+                return { ok: false, code: "body-too-large", message: `request body exceeds ${String(limit)} bytes` };
+            }
+            chunks.push(buf);
+        }
+    }
+    catch (error) {
+        return { ok: false, code: "body-read-failed", message: error instanceof Error ? error.message : String(error) };
+    }
+    const text = Buffer.concat(chunks).toString("utf8").trim();
+    if (text === "")
+        return { ok: true, value: {} };
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return { ok: false, code: "bad-json", message: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 写一个 JSON 响应（含状态码）。 */
+export function sendJson(res, status, payload) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(body);
+}
+/** job 结果保留时长（毫秒）。与旧仓库一致的 30 分钟。 */
+export const JOB_TTL_MS = 30 * 60 * 1000;
+/** 同时在途的 job 上限。超出即背压拒绝，避免堆叠点击打爆进程。 */
+export const JOB_MAX_PENDING = 4;
+/** job 注册表（进程内）。 */
+export class JobRegistry {
+    jobs = new Map();
+    seq = 0;
+    /**
+     * 启动一个 job。
+     * @param task - 要执行的工作。
+     * @returns job id。
+     * @throws {Error} 在途数量达到上限时（调用方应回 429）。
+     */
+    start(task) {
+        this.prune();
+        const pending = [...this.jobs.values()].filter(job => !job.done).length;
+        if (pending >= JOB_MAX_PENDING) {
+            throw new Error(`too many operations in flight (${String(pending)}); wait for one to finish`);
+        }
+        this.seq += 1;
+        const id = `${Date.now().toString(36)}-${this.seq.toString(36)}`;
+        const record = { startedAt: Date.now(), done: false };
+        this.jobs.set(id, record);
+        // 结果与错误都落进 record：调用方只通过 job op 读，避免"谁先到"的竞态。
+        void task().then((value) => { record.result = value; record.done = true; }, (error) => { record.error = error instanceof Error ? error.message : String(error); record.done = true; });
+        return id;
+    }
+    /**
+     * 读一个 job 的状态。
+     * @param id - job id。
+     * @returns 状态；id 不存在（或已过期）时 `missing: true`。
+     */
+    status(id) {
+        this.prune();
+        const record = this.jobs.get(id);
+        if (record === undefined)
+            return { done: true, missing: true };
+        return {
+            done: record.done,
+            ...record.result === undefined ? {} : { result: record.result },
+            ...record.error === undefined ? {} : { error: record.error },
+        };
+    }
+    /** 清掉超过 TTL 的记录。 */
+    prune() {
+        const cutoff = Date.now() - JOB_TTL_MS;
+        for (const [id, record] of this.jobs) {
+            if (record.startedAt < cutoff)
+                this.jobs.delete(id);
+        }
+    }
+}

package/dist/scan.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 安装期环境变量需求扫描与子进程环境过滤（给 git 源插件用）。
+ *
+ * 归属：B 类·参考算法后重写（纯决策 + 有界只读扫描；旧 src/scan.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/scan.ts（91 行，2 层/40 文件/8 变量上限、
+ *   TOKEN|KEY|SECRET|PASSWORD|PASS|CREDENTIAL 六族敏感键、\b 词边界的坑）。
+ * 官方复用：无（官方没有安装期 env 扫描；官方 plugin-manager 用 scrubbedParentEnv()
+ *   清空 service 侧子进程环境，我们借鉴其"默认最小"的取向，但实现自有）。
+ * 前提检查：仍然成立——git 源插件的 pnpm 解析与生命周期脚本会继承子进程 env，
+ *   全量透传等于把宿主凭据交给未审核的第三方代码。旧实现的已知限制（只覆盖常见
+ *   敏感键形态）在这里被显式扩大：见 SENSITIVE_FAMILIES / SENSITIVE_PREFIXES；
+ *   未被覆盖的形态仍然放行，这一事实写在 buildFilteredEnv 的文档里，不假装完整。
+ *
+ * 三条安全不变量（写在代码里，不靠调用方自觉）：
+ *   1. answers 只按**扫描白名单**注入——PATH/HOME/NODE_OPTIONS 这类键永远进不来
+ *      （旧仓库审计点：任意键注入可劫持子进程执行）。
+ *   2. 子进程环境默认剔除敏感键形态；扫描出的键由调用方显式给定值时按值注入
+ *      （用户显式提供即同意），未提供的宿主同名残留值仍被剔除。
+ *   3. 过滤是"剔除"，不是"清空"：宿主仍需要 PATH/HOME 才能跑 pnpm。这与官方
+ *      service 侧的全清策略不同是有意的：CLI 的生命周期脚本依赖用户工具链
+ *      （nvm 下的 node/pnpm 解析），清空会让安装直接失败。
+ */
+/** 扫描成本上限：目录层数、候选文件数、返回变量数、单文件字节数。 */
+export interface ScanLimits {
+    /** 递归层数上限（根为第 0 层）。 */
+    readonly maxDepth: number;
+    /** 最多读取的候选文件数。 */
+    readonly maxFiles: number;
+    /** 最多返回的变量名数量。 */
+    readonly maxVariables: number;
+    /** 单个候选文件的读取上限（字节）；超出即放弃该文件并记账。 */
+    readonly maxFileBytes: number;
+}
+/** 默认上限。旧仓库实测：2 层/40 文件足够覆盖 README + package.json + .env.example。 */
+export declare const DEFAULT_SCAN_LIMITS: ScanLimits;
+/**
+ * 敏感环境变量名判定。
+ *
+ * 边界用字母数字感知（不能用 \b：下划线属于 \w，GITHUB_TOKEN 中 TOKEN 前无边界）。
+ * 结果：GITHUB_TOKEN / OPENAI_API_KEY / DB_PASSWORD / XXX_PASS 命中，
+ * KEYBOARD_LAYOUT（KEY 后接 B）不误伤，AWS_SECRET_ACCESS_KEY 命中。
+ *
+ * @param name - 变量名；非字符串输入按字符串处理（调用方可能传任意 JSON）。
+ * @returns 是否属于敏感形态。
+ */
+export declare function isSensitiveEnvKey(name: string): boolean;
+/** 扫描源：从哪个文件/字段发现了这个变量名。 */
+export interface ScanSource {
+    /** 相对仓库根的路径；用于输出让用户能自己核实。 */
+    readonly file: string;
+    /** 发现位置（文件名 / package.json 字段）。 */
+    readonly via: string;
+    /** 该变量名是否被判为敏感形态。 */
+    readonly sensitive: boolean;
+}
+/** 一次扫描的结果。 */
+export interface ScanReport {
+    /** 需要的变量名（去重、按发现顺序、受 maxVariables 限制）。 */
+    readonly requirements: readonly string[];
+    /** 每个变量名的来源，与 requirements 同序。 */
+    readonly sources: readonly ScanSource[];
+    /** 层数/文件数/变量数触顶时为 true——超限如实标注，不静默截断。 */
+    readonly truncated: boolean;
+    /** 触顶的维度说明，直接面向用户展示。 */
+    readonly truncatedReasons: readonly string[];
+    /** 实际被读取的候选文件数。 */
+    readonly filesRead: number;
+    /** 实际遍历到的最深层数。 */
+    readonly depthReached: number;
+    /** 因超过单文件上限而被跳过的文件数。 */
+    readonly oversized: number;
+}
+/** 扫描选项。 */
+export interface ScanOptions {
+    /** 覆盖默认上限（部分覆盖）。 */
+    readonly limits?: Partial<ScanLimits>;
+    /** 是否收录非敏感形态的变量名。默认 false（只收敏感形态，避免打扰用户）。 */
+    readonly includePlain?: boolean;
+}
+/**
+ * 扫描仓库目录，给出安装/构建阶段可能需要的环境变量名。
+ *
+ * 有界：层数、文件数、变量数、单文件大小全部设上限；触顶时 truncated 为 true
+ * 并在 truncatedReasons 里说明是哪个维度触顶——漏报一个必需变量会让用户在安装
+ * 中途才失败，所以超限必须如实标注而不是静默截断。
+ *
+ * 只读取，不执行：仓库里的 install.sh 永远不会被本模块或调用方自动执行。
+ *
+ * @param repoDir - 已克隆/已就绪的仓库根目录。
+ * @param options - 上限覆盖与是否收录非敏感形态。
+ * @returns 扫描报告。
+ */
+export declare function scanRequirements(repoDir: string, options?: ScanOptions): Promise<ScanReport>;
+/** 取某个变量名在扫描报告里的来源。 */
+export declare function sourceOf(report: ScanReport, name: string): ScanSource | undefined;
+/**
+ * 过滤子进程环境：剔除敏感键。
+ *
+ * 取值为 undefined 的键（Node 允许）保持 undefined，其余原样保留——这里是过滤器
+ * 而不是构造器，宿主工具链（PATH/HOME/NVM_DIR）必须继续可用，否则 nvm 用户的
+ * node/pnpm 解析会失败（旧仓库 issue 记录）。
+ *
+ * @param source - 基础环境；默认 process.env。
+ * @returns 剔除敏感键后的新对象（不改动传入对象）。
+ */
+export declare function buildFilteredEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 构造注入给子进程的环境：先剔敏感键，再按白名单注入用户提供的值。
+ *
+ * 白名单来自扫描（session 或 CLI 本次扫描），因此 PATH/HOME/NODE_OPTIONS/
+ * __proto__ 这类键即使出现在 answers 里也不会被注入。
+ *
+ * 显式提供即同意：用户主动为某个**敏感**键提供值时该值会被注入——这个值只存在于
+ * 用户自己的机器上、由用户自己录入，安装链路没有"静默读取宿主凭据"的部分。
+ * 未提供时，宿主同名变量仍然被剔除。
+ *
+ * @param source - 基础环境（通常是 process.env）。
+ * @param answers - 用户提供的键值；键不在白名单内或值不是非空字符串即忽略。
+ * @param allowlist - 允许注入的键（扫描结果）。
+ * @returns 供子进程使用的环境对象。
+ */
+export declare function buildFilteredEnvWithAnswers(source: NodeJS.ProcessEnv, answers: Readonly<Record<string, string>> | undefined, allowlist: readonly string[]): NodeJS.ProcessEnv;
+/** 给用户看的缺失变量清单（CLI 输出用；含每个变量的来源，便于用户自己核实）。 */
+export declare function formatMissingRequirements(report: ScanReport, provided: Readonly<Record<string, string>>): string[];
+/**
+ * 是否需要为某次安装做 env 扫描。
+ *
+ * 只对 git 源扫描：本地路径是用户自己的目录（想读环境变量早就读了），npm 包在
+ * 安装前没有可扫的仓库内容。git+ / github: / git@ / .git 结尾 / git URL 都算。
+ *
+ * @param spec - 安装源。
+ * @returns 是否为 git 源。
+ */
+export declare function isGitSource(spec: string): boolean;