dsh-config-manager 0.1.0

package/lib/utils/zip.js

@@ -0,0 +1,285 @@
+/**
+ * ZIP 读写封装：node:zlib（deflate raw）+ 自实现 CRC32，零依赖。
+ * 同时是 ZIP 安全的第一道防线（规范 §19，m4 的 zip-security 可在此基础上强化）：
+ *   - 条目名 isPathSafe（拒绝 ../、绝对路径、盘符、UNC、NUL）
+ *   - 条目数 / 压缩体积 / 解压体积 / 单条 / 压缩比（zip bomb）上限
+ *   - 解压时逐条 CRC32 与尺寸校验，损坏即整体拒绝
+ * 解压只允许写入受控目标目录（safeExtract），绝不落任意路径。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { parseJsonSafe } from "./json.js";
+import { isPathSafe, isSameOrChild } from "./paths.js";
+export const DEFAULT_ZIP_SAFETY_LIMITS = {
+    maxEntries: 10_000,
+    maxTotalBytes: 500 * 1024 * 1024,
+    maxCompressedBytes: 200 * 1024 * 1024,
+    maxSingleBytes: 100 * 1024 * 1024,
+    maxRatio: 200,
+};
+export class ZipSafetyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZipSafetyError';
+    }
+}
+/* ---------------- CRC32（表驱动） ---------------- */
+let crcTable = null;
+function getCrcTable() {
+    if (crcTable)
+        return crcTable;
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = (c & 1) !== 0 ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+        }
+        table[n] = c >>> 0;
+    }
+    crcTable = table;
+    return table;
+}
+export function crc32(data) {
+    const table = getCrcTable();
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        crc = table[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/* ---------------- 写入 ---------------- */
+function dosDateTime() {
+    const now = new Date();
+    const time = ((now.getHours() & 0x1f) << 11) | ((now.getMinutes() & 0x3f) << 5) | ((now.getSeconds() >> 1) & 0x1f);
+    const date = (((now.getFullYear() - 1980) & 0x7f) << 9) | (((now.getMonth() + 1) & 0x0f) << 5) | (now.getDate() & 0x1f);
+    return { time, date };
+}
+/** 组装 ZIP 字节（全部条目 method=8 deflate，UTF-8 文件名，含中央目录与 EOCD） */
+export function zipToBuffer(entries) {
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    const { time, date } = dosDateTime();
+    for (const entry of entries) {
+        if (!isPathSafe(entry.name)) {
+            throw new ZipSafetyError(`拒绝写入不安全的条目名: ${entry.name}`);
+        }
+        const nameBuf = Buffer.from(entry.name, 'utf8');
+        const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data);
+        const compressed = zlib.deflateRawSync(data);
+        const crc = crc32(data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6); // UTF-8 文件名
+        local.writeUInt16LE(8, 8); // deflate
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(nameBuf.length, 26);
+        local.writeUInt16LE(0, 28);
+        chunks.push(local, nameBuf, compressed);
+        const cen = Buffer.alloc(46);
+        cen.writeUInt32LE(0x02014b50, 0);
+        cen.writeUInt16LE(20, 4);
+        cen.writeUInt16LE(20, 6);
+        cen.writeUInt16LE(0x0800, 8);
+        cen.writeUInt16LE(8, 10);
+        cen.writeUInt16LE(time, 12);
+        cen.writeUInt16LE(date, 14);
+        cen.writeUInt32LE(crc, 16);
+        cen.writeUInt32LE(compressed.length, 20);
+        cen.writeUInt32LE(data.length, 24);
+        cen.writeUInt16LE(nameBuf.length, 28);
+        cen.writeUInt16LE(0, 30);
+        cen.writeUInt16LE(0, 32);
+        cen.writeUInt16LE(0, 34);
+        cen.writeUInt16LE(0, 36);
+        cen.writeUInt32LE(0, 38);
+        cen.writeUInt32LE(offset, 42);
+        central.push(cen, nameBuf);
+        offset += local.length + nameBuf.length + compressed.length;
+    }
+    const cd = Buffer.concat(central);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(0, 4);
+    eocd.writeUInt16LE(0, 6);
+    eocd.writeUInt16LE(entries.length, 8);
+    eocd.writeUInt16LE(entries.length, 10);
+    eocd.writeUInt32LE(cd.length, 12);
+    eocd.writeUInt32LE(offset, 16);
+    eocd.writeUInt16LE(0, 20);
+    return Buffer.concat([...chunks, cd, eocd]);
+}
+/** 写出 ZIP 文件 */
+export async function writeZip(zipPath, entries) {
+    const buf = zipToBuffer(entries);
+    await fs.mkdir(path.dirname(zipPath), { recursive: true });
+    await fs.writeFile(zipPath, buf);
+}
+/* ---------------- 读取 ---------------- */
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+/** 内存 ZIP 归档：构造时校验全部条目名与上限；读取时逐条解压 + CRC/尺寸/比预算校验 */
+export class ZipArchive {
+    buf;
+    metas;
+    limits;
+    totalUncompressed = 0;
+    constructor(buf, metas, limits) {
+        this.buf = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+        this.metas = metas;
+        this.limits = limits;
+    }
+    names() {
+        return this.metas.map((m) => m.name);
+    }
+    entries() {
+        return this.metas.map((m) => ({ ...m }));
+    }
+    has(name) {
+        return this.metas.some((m) => m.name === name);
+    }
+    /** 读取并解压单条目（带 CRC32 / 尺寸 / 体积预算 / 压缩比校验） */
+    readEntry(name) {
+        const meta = this.metas.find((m) => m.name === name);
+        if (!meta)
+            throw new ZipSafetyError(`ZIP 中不存在条目: ${name}`);
+        if (meta.isDirectory)
+            return Buffer.alloc(0);
+        const lhOffset = meta.localOffset;
+        const lh = this.buf.subarray(lhOffset, lhOffset + 30);
+        if (lh.length < 30 || lh.readUInt32LE(0) !== LOCAL_SIG) {
+            throw new ZipSafetyError(`条目 "${name}" 的本地文件头损坏`);
+        }
+        const nameLen = lh.readUInt16LE(26);
+        const extraLen = lh.readUInt16LE(28);
+        const dataStart = lhOffset + 30 + nameLen + extraLen;
+        if (dataStart + meta.compressedSize > this.buf.length) {
+            throw new ZipSafetyError(`条目 "${name}" 数据越界`);
+        }
+        const raw = this.buf.subarray(dataStart, dataStart + meta.compressedSize);
+        let out;
+        if (meta.method === 0) {
+            out = raw;
+        }
+        else if (meta.method === 8) {
+            try {
+                out = zlib.inflateRawSync(raw, { maxOutputLength: this.limits.maxSingleBytes });
+            }
+            catch (err) {
+                throw new ZipSafetyError(`条目 "${name}" 解压失败: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            throw new ZipSafetyError(`条目 "${name}" 使用未知压缩方法 ${meta.method}`);
+        }
+        if (out.length !== meta.uncompressedSize) {
+            throw new ZipSafetyError(`条目 "${name}" 解压尺寸不符（${out.length} ≠ ${meta.uncompressedSize}）`);
+        }
+        if (crc32(out) !== meta.crc32) {
+            throw new ZipSafetyError(`条目 "${name}" CRC32 校验失败（ZIP 已损坏）`);
+        }
+        this.totalUncompressed += out.length;
+        if (this.totalUncompressed > this.limits.maxTotalBytes) {
+            throw new ZipSafetyError('ZIP 解压总字节数超过上限');
+        }
+        if (meta.compressedSize > 0) {
+            const ratio = out.length / meta.compressedSize;
+            if (ratio > this.limits.maxRatio) {
+                throw new ZipSafetyError(`条目 "${name}" 压缩比 ${ratio.toFixed(1)} 超过上限（疑似 zip bomb）`);
+            }
+        }
+        return out;
+    }
+    readEntryText(name) {
+        return Buffer.from(this.readEntry(name)).toString('utf8');
+    }
+    /** 读取并深度保护解析 JSON 条目 */
+    readEntryJson(name) {
+        return parseJsonSafe(this.readEntryText(name));
+    }
+}
+/** 解析 ZIP（含安全校验：条目名 / 条目数 / 压缩体积） */
+export function parseZip(buf, limits = {}) {
+    const merged = { ...DEFAULT_ZIP_SAFETY_LIMITS, ...limits };
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    if (b.length < 22)
+        throw new ZipSafetyError('不是合法的 ZIP 文件（体积过小）');
+    const eocdIdx = b.lastIndexOf(EOCD_SIG);
+    if (eocdIdx < 0 || eocdIdx + 22 > b.length) {
+        throw new ZipSafetyError('不是合法的 ZIP 文件（缺少中央目录结束记录）');
+    }
+    const totalEntries = b.readUInt16LE(eocdIdx + 10);
+    const cdSize = b.readUInt32LE(eocdIdx + 12);
+    const cdOffset = b.readUInt32LE(eocdIdx + 16);
+    if (cdOffset + cdSize > b.length) {
+        throw new ZipSafetyError('中央目录越界（ZIP 损坏）');
+    }
+    if (totalEntries > merged.maxEntries) {
+        throw new ZipSafetyError(`ZIP 条目数 ${totalEntries} 超过上限 ${merged.maxEntries}`);
+    }
+    const metas = [];
+    let pos = cdOffset;
+    let compressedTotal = 0;
+    for (let i = 0; i < totalEntries; i++) {
+        if (pos + 46 > cdOffset + cdSize)
+            throw new ZipSafetyError('中央目录条目越界（ZIP 损坏）');
+        if (b.readUInt32LE(pos) !== CENTRAL_SIG)
+            throw new ZipSafetyError('中央目录签名损坏');
+        const method = b.readUInt16LE(pos + 10);
+        const crc = b.readUInt32LE(pos + 16);
+        const compSize = b.readUInt32LE(pos + 20);
+        const uncompSize = b.readUInt32LE(pos + 24);
+        const nameLen = b.readUInt16LE(pos + 28);
+        const extraLen = b.readUInt16LE(pos + 30);
+        const commentLen = b.readUInt16LE(pos + 32);
+        const localOffset = b.readUInt32LE(pos + 42);
+        const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+        if (!isPathSafe(name))
+            throw new ZipSafetyError(`ZIP 条目名不安全: ${name}`);
+        compressedTotal += compSize;
+        if (compressedTotal > merged.maxCompressedBytes) {
+            throw new ZipSafetyError('ZIP 压缩数据总量超过上限');
+        }
+        metas.push({
+            name,
+            method,
+            compressedSize: compSize,
+            uncompressedSize: uncompSize,
+            crc32: crc,
+            isDirectory: name.endsWith('/'),
+            localOffset,
+        });
+        pos += 46 + nameLen + extraLen + commentLen;
+    }
+    return new ZipArchive(b, metas, merged);
+}
+/**
+ * 安全解压到受控目录（对齐设计 §13.4 safeExtract 签名）。
+ * 返回条目相对路径列表；任何越界/损坏即整体拒绝（不部分落盘）。
+ * m4 的 zip-security 可替换/强化本实现。
+ */
+export async function safeExtract(zipPath, destDir, limits = {}) {
+    const data = await fs.readFile(zipPath);
+    const archive = parseZip(data, limits);
+    const extracted = [];
+    for (const meta of archive.entries()) {
+        if (meta.isDirectory)
+            continue;
+        const target = path.join(destDir, ...meta.name.split('/'));
+        if (!isSameOrChild(target, destDir)) {
+            throw new ZipSafetyError(`解压目标越界: ${meta.name}`);
+        }
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(target, archive.readEntry(meta.name));
+        extracted.push(meta.name);
+    }
+    return extracted;
+}
+//# sourceMappingURL=zip.js.map

package/lib/utils/zip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.js","sourceRoot":"","sources":["../../src/utils/zip.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqBvD,MAAM,CAAC,MAAM,yBAAyB,GAA8B;IAClE,UAAU,EAAE,MAAM;IAClB,aAAa,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAChC,kBAAkB,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IACrC,cAAc,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IACjC,QAAQ,EAAE,GAAG;CACd,CAAC;AAEF,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,kDAAkD;AAElD,IAAI,QAAQ,GAAuB,IAAI,CAAC;AACxC,SAAS,WAAW;IAClB,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,QAAQ,GAAG,KAAK,CAAC;IACjB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAgB;IACpC,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC;IAC5B,IAAI,GAAG,GAAG,UAAU,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,GAAG,KAAK,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,GAAG,IAAI,CAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,0CAA0C;AAE1C,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnH,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACxH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAID,6DAA6D;AAC7D,MAAM,UAAU,WAAW,CAAC,OAAwB;IAClD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,cAAc,CAAC,gBAAgB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChF,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAExB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/B,KAAK,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACnC,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC3B,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY;QAC5C,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAK,UAAU;QACzC,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC7B,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC3C,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACrC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxC,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAExC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,GAAG,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACjC,GAAG,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7B,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5B,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5B,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3B,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACtC,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAE3B,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/B,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAE1B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,gBAAgB;AAChB,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,OAAwB;IACtE,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,0CAA0C;AAE1C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AACvD,MAAM,SAAS,GAAG,UAAU,CAAC;AAC7B,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,qDAAqD;AACrD,MAAM,OAAO,UAAU;IACJ,GAAG,CAAS;IACZ,KAAK,CAAiB;IAC9B,MAAM,CAA4B;IACnC,iBAAiB,GAAG,CAAC,CAAC;IAE9B,YAAY,GAAe,EAAE,KAAqB,EAAE,MAAiC;QACnF,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,4CAA4C;IAC5C,SAAS,CAAC,IAAY;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,cAAc,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAE7C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC;QAClC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,EAAE,CAAC,CAAC;QACtD,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YACvD,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,YAAY,CAAC,CAAC;QACpD,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,GAAG,EAAE,GAAG,OAAO,GAAG,QAAQ,CAAC;QACrD,IAAI,SAAS,GAAG,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YACtD,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,QAAQ,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;QAE1E,IAAI,GAAW,CAAC;QAChB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,GAAG,GAAG,GAAG,CAAC;QACZ,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;YAClF,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,WAAW,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrG,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,cAAc,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACzC,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,YAAY,GAAG,CAAC,MAAM,MAAM,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,uBAAuB,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,CAAC,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC;QACrC,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YACvD,MAAM,IAAI,cAAc,CAAC,gBAAgB,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC;YAC/C,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACjC,MAAM,IAAI,cAAc,CAAC,OAAO,IAAI,SAAS,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAY;QACxB,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5D,CAAC;IAED,wBAAwB;IACxB,aAAa,CAAC,IAAY;QACxB,OAAO,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,UAAU,QAAQ,CAAC,GAAe,EAAE,SAA0B,EAAE;IACpE,MAAM,MAAM,GAA8B,EAAE,GAAG,yBAAyB,EAAE,GAAG,MAAM,EAAE,CAAC;IACtF,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxD,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE;QAAE,MAAM,IAAI,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,cAAc,CAAC,0BAA0B,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,CAAC,CAAC,YAAY,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IAC9C,IAAI,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,IAAI,cAAc,CAAC,gBAAgB,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,YAAY,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,IAAI,cAAc,CAAC,WAAW,YAAY,SAAS,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,GAAG,GAAG,EAAE,GAAG,QAAQ,GAAG,MAAM;YAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;QAC/E,IAAI,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,WAAW;YAAE,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC5C,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEvE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QACvE,eAAe,IAAI,QAAQ,CAAC;QAC5B,IAAI,eAAe,GAAG,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAChD,MAAM,IAAI,cAAc,CAAC,gBAAgB,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,IAAI;YACJ,MAAM;YACN,cAAc,EAAE,QAAQ;YACxB,gBAAgB,EAAE,UAAU;YAC5B,KAAK,EAAE,GAAG;YACV,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAC/B,WAAW;SACZ,CAAC,CAAC;QACH,GAAG,IAAI,EAAE,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,OAAe,EACf,SAA0B,EAAE;IAE5B,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,WAAW;YAAE,SAAS;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3D,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,cAAc,CAAC,WAAW,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "dsh-config-manager",
+  "version": "0.1.0",
+  "description": "DSH Config Manager — backup / export / import / migrate DSH configuration (dual-face Cordis plugin: host engine + web UI). Manifest shape mirrors @linxin666/dsh-ssh@0.1.12.",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./core": {
+      "types": "./lib/core/index.d.ts",
+      "default": "./lib/core/index.js"
+    },
+    "./schema": {
+      "types": "./lib/schema/types.d.ts",
+      "default": "./lib/schema/types.js"
+    },
+    "./client": {
+      "types": "./lib/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "dsh.bundle.patch",
+    "dsh.client",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "scripts": {
+    "test": "node --test \"src/**/*.test.ts\" \"tests/**/*.test.ts\"",
+    "smoke": "node --test src/core/smoke.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "clean": "node -e \"require('node:fs').rmSync('lib', { recursive: true, force: true })\""
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-plugin-inventory": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-plugin-marketplace": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-plugin-inventory": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.5",
+    "lightningcss": "1.32.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "schemastery": "^3.18.0",
+    "tsdown": "0.22.2",
+    "typescript": "^5.9.0"
+  }
+}

package/src/adapters/agent-presets.ts

@@ -0,0 +1,14 @@
+/**
+ * agentPresets 分区 adapter（设计 §3.3）：
+ * 数据源 = ~/.dsh/.agent-presets/（用户可写目录，每预设一个目录：agent.cordis.yml + preset.yml）。
+ * system 预设（安装目录）只记引用不复制（本 adapter 只读用户目录）。
+ */
+import { FileCollectionAdapter } from './file-collection.ts';
+
+export class AgentPresetsAdapter extends FileCollectionAdapter {
+  readonly id = 'agentPresets' as const;
+  readonly displayName = 'Agent Presets';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  readonly baseDir = '.agent-presets';
+}

package/src/adapters/credentials.test.ts

@@ -0,0 +1,90 @@
+/**
+ * credentials adapter 测试：状态导出（永不泄值）、ref 收集、MissingSecret 由引擎兜底、
+ * applyItem 经 secretInputs/decryptedCredentials 补录（仅内存）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { CredentialsAdapter, defaultCredentialRefs } from './credentials.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import type { PlanItem } from '../core/types.ts';
+
+const NS = ['llm-deepseek', 'llm-pi-ai'];
+
+test('credentials: 状态导出（configured/source/hasValue=false，值绝不含）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  });
+  ctx.settings.ns.set('llm-pi-ai', {
+    value: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } },
+    revision: 2,
+    secrets: [],
+  });
+  ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-super-secret-123');
+
+  const adapter = new CredentialsAdapter({ namespaces: NS });
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  const refs = out.data.credentials.map((c) => c.ref).sort();
+  assert.deepEqual(refs, ['DEEPSEEK_API_KEY', 'OPENAI_API_KEY'], '从 apiKeyEnv + secrets 标记收集');
+  const dk = out.data.credentials.find((c) => c.ref === 'DEEPSEEK_API_KEY');
+  assert.equal(dk?.configured, true);
+  assert.equal(dk?.hasValue, false, '值未导出（安全不变量）');
+  const ok = out.data.credentials.find((c) => c.ref === 'OPENAI_API_KEY');
+  assert.equal(ok?.configured, false);
+  // 序列化后的导出数据不得包含秘密值
+  const serialized = JSON.stringify(out.data);
+  assert.ok(!serialized.includes('sk-super-secret-123'), '凭据值不得进入导出数据');
+
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('credentials: defaultCredentialRefs 从 settings 收集', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  // 顶层 apiKeyEnv + secrets 引用类字段（apiKeyEnv）的值 = 凭据 ref
+  ctx.settings.ns.set('llm-deepseek', { value: { apiKeyEnv: 'DEEPSEEK_API_KEY' }, revision: 1, secrets: [{ path: ['apiKeyEnv'], set: true }] });
+  const refs = await defaultCredentialRefs(NS)(ctx);
+  assert.ok(refs.includes('DEEPSEEK_API_KEY'));
+  // secrets[].path[0] 若为非引用类字段（如 apiKey 字段路径），不收集为 ref
+  const ctx2 = makeContext('win32', 'C:\\Users\\alice');
+  ctx2.settings.ns.set('llm-deepseek', { value: { apiKeyEnv: 'DEEPSEEK_API_KEY' }, revision: 1, secrets: [{ path: ['apiKey'], set: true }] });
+  const refs2 = await defaultCredentialRefs(NS)(ctx2);
+  assert.ok(!refs2.includes('apiKey'), '字段路径不是凭据 ref');
+});
+
+test('credentials: applyItem 用 secretInputs / decryptedCredentials 补录（仅内存，不落盘值）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.settings.ns.set('llm-deepseek', { value: { apiKeyEnv: 'DEEPSEEK_API_KEY' }, revision: 1, secrets: [] });
+  const adapter = new CredentialsAdapter({ namespaces: NS });
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['credentialsStatus', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  const ictx = makeImportContext(dst, sections, { secretInputs: { DEEPSEEK_API_KEY: 'sk-from-user-input' } });
+  const item: PlanItem = {
+    id: 'secret:DEEPSEEK_API_KEY', kind: 'MissingSecret', adapter: 'credentialsStatus',
+    description: '凭据补录', severity: 'warning', target: { adapter: 'credentialsStatus', ref: 'DEEPSEEK_API_KEY' },
+  };
+  const r = await adapter.applyItem(item, ictx);
+  assert.equal(r.ok, true);
+  assert.equal(dst.credentials.values.get('DEEPSEEK_API_KEY'), 'sk-from-user-input');
+
+  // 解密通道（加密备份）
+  const dst2 = makeContext('linux', '/home/bob');
+  const dec = new Map<string, string>([['DEEPSEEK_API_KEY', 'sk-decrypted']]);
+  const r2 = await adapter.applyItem(item, makeImportContext(dst2, sections, { decryptedCredentials: dec }));
+  assert.equal(r2.ok, true);
+  assert.equal(dst2.credentials.values.get('DEEPSEEK_API_KEY'), 'sk-decrypted');
+
+  // 无值 → 失败（引擎在 MissingSecret 无值时先跳过，这里兜底）
+  const r3 = await adapter.applyItem(item, makeImportContext(dst2, sections));
+  assert.equal(r3.ok, false);
+});
+
+test('credentials: validate 拒绝 hasValue=true（安全不变量）', async () => {
+  const adapter = new CredentialsAdapter();
+  const bad = await adapter.validate({ version: 1, credentials: [{ ref: 'X', required: true, configured: true, hasValue: true } as never] });
+  assert.equal(bad.valid, false);
+});

package/src/adapters/credentials.ts

@@ -0,0 +1,141 @@
+/**
+ * credentialsStatus 分区 adapter（设计 §3.3/§7.1）：
+ * 数据源 = ctx.credentials.describe(ref) 的状态（configured/source/writable），
+ * 以及 settings secrets 标记 / llm apiKeyEnv 中引用的凭据 ref 名。
+ *
+ * 安全不变量：永不导出值（hasValue 恒 false）；导入生成 MissingSecret 清单，
+ * 用户补录值经 ctx.secretInputs / decryptedCredentials（仅内存）→ credentials.set()。
+ * .credentials.yaml 文件字节交由 m4 加密层处理，本 adapter 不触碰。
+ */
+import type { CredentialStatus, CredentialsSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { resolveNamespaces, type NamespaceProvider } from './settings.ts';
+
+export type CredentialRefsProvider = (ctx: HostContext) => Promise<string[]>;
+
+/** 缺省 ref 收集：遍历 settings namespace，收集 llm apiKeyEnv / providers[].apiKeyEnv，
+ * 以及 secrets 标记中「引用类字段」（apiKeyEnv/tokenEnv…）的字段值。
+ * 注意 secrets[].path[0] 是 settings 文档内的字段路径（如 ['apiKey']），本身不是凭据 ref（设计 §4.2），
+ * 只有指向 env 名的引用字段才值得收集。 */
+export function defaultCredentialRefs(namespaces: string[] | NamespaceProvider): CredentialRefsProvider {
+  return async (ctx: HostContext): Promise<string[]> => {
+    const refs = new Set<string>();
+    for (const ns of await resolveNamespaces(namespaces, ctx)) {
+      try {
+        const info = await ctx.settings.describe(ns, { redactSecrets: true });
+        const value = (info.value ?? {}) as Record<string, unknown>;
+        // 引用类字段名（值 = env/凭据引用名，非秘密本身）
+        const REFERENCE_REF_FIELDS = new Set([
+          'apikeyenv', 'api_key_env', 'apikeyname', 'tokenenv', 'accesstokenenv',
+          'refreshtokenenv', 'clientsecretenv', 'passwordenv',
+        ]);
+        for (const s of info.secrets) {
+          const first = s.path?.[0];
+          if (typeof first !== 'string' || first === '') continue;
+          const norm = first.toLowerCase().replace(/[^a-z0-9]/g, '');
+          if (!REFERENCE_REF_FIELDS.has(norm)) continue;
+          const val = value[first];
+          if (typeof val === 'string' && val !== '') refs.add(val);
+        }
+        if (typeof value['apiKeyEnv'] === 'string' && value['apiKeyEnv'] !== '') refs.add(value['apiKeyEnv'] as string);
+        const providers = value['providers'];
+        if (providers !== null && typeof providers === 'object') {
+          for (const pv of Object.values(providers as Record<string, { apiKeyEnv?: unknown }>)) {
+            if (pv !== null && typeof pv === 'object' && typeof pv.apiKeyEnv === 'string' && pv.apiKeyEnv !== '') {
+              refs.add(pv.apiKeyEnv);
+            }
+          }
+        }
+      } catch {
+        // namespace 不存在则跳过
+      }
+    }
+    return [...refs];
+  };
+}
+
+export interface CredentialsAdapterOptions {
+  /** 凭据 ref 名收集器（缺省从 settings 推断） */
+  refs?: CredentialRefsProvider;
+  /** 供缺省 refs 使用的 namespace 清单 */
+  namespaces?: string[] | NamespaceProvider;
+}
+
+export class CredentialsAdapter implements ConfigAdapter<CredentialsSection> {
+  readonly id = 'credentialsStatus' as const;
+  readonly displayName = 'Credentials';
+  readonly defaultIncluded = true;
+  readonly portability = 'deviceSpecific' as const;
+  private readonly refs: CredentialRefsProvider;
+
+  constructor(options: CredentialsAdapterOptions = {}) {
+    this.refs = options.refs ?? defaultCredentialRefs(options.namespaces ?? []);
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<CredentialsSection>> {
+    const credentials: CredentialStatus[] = [];
+    const warnings: string[] = [];
+    for (const ref of await this.refs(ctx)) {
+      try {
+        const status = await ctx.credentials.describe(ref);
+        credentials.push({
+          ref,
+          required: true,
+          configured: status.configured,
+          source: (status.source as CredentialStatus['source']) ?? 'file',
+          hasValue: false, // 值未导出（安全不变量）
+        });
+      } catch (err) {
+        warnings.push(`凭据 ${ref} 状态读取失败: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return {
+      sectionId: 'credentialsStatus',
+      data: { version: 1, credentials },
+      counts: { credentials: credentials.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(_data: CredentialsSection, _ctx: ImportContext): Promise<PlanItem[]> {
+    // MissingSecret 计划项由引擎在 createImportPlan 兜底生成（analyzer.ensureMissingSecrets），
+    // 依据 = 本分区里 configured=true 的凭据 → 用户补录清单。这里保持零写入纯计算。
+    return [];
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: '缺少 target.ref' };
+    const value = ctx.secretInputs[ref] ?? ctx.decryptedCredentials?.get(ref);
+    if (value === undefined || value === '') return { ok: false, message: '凭据值未提供（需补录）' };
+    await ctx.target.credentials.set(ref, value);
+    return { ok: true };
+  }
+
+  async validate(data: CredentialsSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'credentials 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (!Array.isArray(data.credentials)) {
+      issues.push({ path: 'credentials', message: 'credentials 必须是数组', severity: 'error' });
+    } else {
+      for (const c of data.credentials) {
+        if (c === null || typeof c !== 'object' || typeof c.ref !== 'string' || c.ref === '') {
+          issues.push({ path: 'credentials[]', message: '凭据记录必须含非空 ref', severity: 'error' });
+        }
+        if (c.hasValue === true) {
+          // 安全不变量：普通导出恒不携带值；若备份声称有值，视为结构异常
+          issues.push({ path: `credentials.${c.ref}.hasValue`, message: '值未导出，hasValue 必须为 false', severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}