@logictan/dsh-config-manager 0.1.60

package/lib/schema/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * 核心领域类型（Export Schema v1 的纯类型定义）。
+ *
+ * 对齐 Docs/design/architecture.md §13.1 —— m3/m5 的共同契约。
+ * 本文件只含与 DSH 运行时无关的纯数据形状；DSH Service 门面类型见 src/core/types.ts。
+ */
+/** 运行平台（等价 NodeJS.Platform，但保持类型自包含，可在浏览器侧引用） */
+export type Platform = 'win32' | 'darwin' | 'linux' | 'freebsd' | 'openbsd' | 'aix' | 'sunos' | 'android' | 'cygwin' | 'haiku' | 'netbsd' | 'other';
+/**
+ * 分区标识，与 ZIP 目录结构、manifest.sections 键一一对应。
+ * 明确不实现的分区（keybindings/workflows/commands）不在此列；
+ * rules 已由 agentInstructions（~/.dsh/AGENTS.md，dsh-agent-instructions 全局指令）承接。
+ */
+export type SectionId = 'settings' | 'ui' | 'providers' | 'plugins' | 'mcp' | 'prompts' | 'skills' | 'agentPresets' | 'agentInstructions' | 'workspaces' | 'pluginFiles' | 'credentialsStatus' | 'secrets' | 'sessions' | 'self';
+/** 加密备份的算法参数（非秘密：salt/iv/authTag 仅用于解密与完整性校验） */
+export interface EncryptionInfo {
+    algorithm: 'aes-256-gcm';
+    kdf: 'scrypt';
+    kdfParams: {
+        N: number;
+        r: number;
+        p: number;
+        keyLength: number;
+    };
+    salt: string;
+    iv: string;
+    authTag: string;
+    version: number;
+}
+/** 每个导出 ZIP 根部的 manifest.json */
+export interface Manifest {
+    schemaVersion: number;
+    exporter: {
+        name: string;
+        version: string;
+    };
+    source: {
+        dshVersion: string;
+        platform: Platform;
+        arch: string;
+    };
+    exportedAt: string;
+    sections: Record<SectionId, boolean>;
+    security: {
+        containsSecrets: boolean;
+        encrypted: boolean;
+        encryption: EncryptionInfo | null;
+    };
+}
+/** settings.yaml 中单个 namespace 的导出记录（redacted 值 + 乐观锁 revision） */
+export interface NamespaceRecord {
+    value: unknown;
+    base?: unknown;
+    revision: number;
+    applies?: string[];
+    /** DSH describe({redactSecrets:true}) 报告的 secrets 位置（只含路径标记，不含值） */
+    secrets: {
+        path: string[];
+        set: boolean;
+    }[];
+}
+export interface SettingsSection {
+    version: 1;
+    namespaces: Record<string, NamespaceRecord>;
+}
+export interface UiMigrationNote {
+    plugin: string;
+    storage: string;
+    key: string;
+    migratable: false;
+    reason: string;
+}
+export interface UiSection {
+    version: 1;
+    namespaces: Record<string, NamespaceRecord>;
+    /** localStorage 等 Host 不可迁移项的说明（纯说明，不含任何值） */
+    uiMigrationNotes: UiMigrationNote[];
+}
+export interface ProviderEntry {
+    route: string;
+    apiKeyEnv?: string;
+    displayName?: string;
+    baseURL?: string;
+    models?: unknown[];
+    modelOverrides?: unknown;
+    reasoning?: unknown;
+    transport?: unknown;
+    retryPolicy?: unknown;
+}
+export interface ProvidersSection {
+    version: 1;
+    providers: Record<string, ProviderEntry>;
+}
+export interface PluginEntry {
+    name: string;
+    version: string;
+    /**
+     * 声明依赖 spec（profile package.json dependencies 原样），如 ^0.3.6、
+     * github:csyangwen/dsh-memory-evolve、file:/link: 等。
+     * 导入时非 registry 来源（github:/git+/file:/link:/workspace: 等）按此 spec 安装，
+     * 否则按裸包名走 npm 最新版（官方机制）。
+     */
+    spec?: string;
+    isBundle: boolean;
+    inBundles: string[];
+    enabled: boolean;
+    fiberPhase?: string;
+}
+export interface PatchLine {
+    file: string;
+    lineId: string;
+    raw: unknown;
+}
+/**
+ * 本地源插件的打包产物（T1）。
+ *
+ * 为什么放在 `plugins` 分区内（而非 `plugin-files/` 前缀）：
+ * plugins 是 `defaultIncluded=true` 且 portable，而 pluginFiles 是 `deviceSpecific`
+ * 且 defaultIncluded=false —— 后者会让「快速导出」（默认路径）拿不到 tarball，
+ * 而「本地插件换机丢失」恰恰是最需要默认覆盖的场景。
+ *
+ * 为什么不新增分区 id：新增 SectionId 需同步 SECTION_IDS / SECTION_FILE_PREFIXES /
+ * manifest 校验 / analyzer / exporter / market BANNED / sync layout 共 7 处契约，
+ * 风险远大于收益；本字段落在既有 plugins 分区内即可被全部既有机制正确处理。
+ *
+ * 安全：base64 仅为传输编码，不做任何执行；导入端只把解包出的 tgz 交给官方
+ * `dsh plugin add` 通道。**市场侧已在发布与导入两端同时拒绝携带本字段的条目**
+ * （`market/prepare.ts` 6b3 + `market/security.ts`）——因为 tarball 是不可经公开仓库审阅的
+ * 不透明二进制，安装时可能执行 postinstall，等于给「分享配置」开一条携带任意代码、
+ * 绕过 BANNED 分区的通道。本地插件迁移只应发生在自己的备份里。
+ */
+export interface LocalPluginTarball {
+    /** 包名（与 PluginEntry.name 对应） */
+    packageName: string;
+    /** 打包时的插件版本 */
+    version: string;
+    /** 归档内相对路径（`local-plugins/<x>.tgz`，恒正斜杠） */
+    relativePath: string;
+    /** tarball 字节的 base64（非秘密；仅本地源插件的源码包） */
+    base64: string;
+}
+/**
+ * profile 的 `patches/**` 文件（issue #35）：pnpm-workspace.yaml 的 `patchedDependencies`
+ * 引用的补丁文件本身。声明与文件必须同进同出——只搬声明会让目标机的 pnpm 拒绝一切 `add`
+ * （`Failed to read patch file ... os error 2`）。
+ */
+export interface PnpmPatchFile {
+    /** 相对 **profile 目录** 的路径（如 `patches/dsh-approval-gate.patch`，恒正斜杠） */
+    relativePath: string;
+    /** 文件字节的 base64（patch 是纯文本、非秘密；仅为传输编码） */
+    base64: string;
+}
+export interface PluginsSection {
+    version: 1;
+    plugins: PluginEntry[];
+    patch: PatchLine[];
+    /**
+     * profile 的 pnpm-workspace.yaml 原文（allowBuilds / minimumReleaseAgeExclude /
+     * nodeLinker 等）。随插件分区迁移，保证目标 profile 的 pnpm 能按来源配置安装
+     * （git 插件构建脚本白名单、新发布版本冷静期等）。缺省/无文件为 null。
+     */
+    pnpmWorkspace?: string | null;
+    /**
+     * 本地源（`link:` / `file:`）插件的打包产物（T1）。缺省/无本地源插件 = 不出现。
+     * 导出时由宿主注入的打包钩子填充；导入时据此把 spec 重写为 `file:<解包后的绝对路径>`。
+     */
+    localTarballs?: LocalPluginTarball[];
+    /**
+     * `patchedDependencies` 引用的 patch 文件（issue #35）。缺省 = 无声明或无文件可收集。
+     * 导入端先落文件、再写（已剔除不可满足声明的）pnpm-workspace.yaml。
+     */
+    patchFiles?: PnpmPatchFile[];
+}
+export interface McpServerEntry {
+    serverName: string;
+    type: 'stdio' | 'streamable-http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export interface McpSection {
+    version: 1;
+    servers: McpServerEntry[];
+}
+export interface PromptEntry {
+    id: string;
+    name: string;
+    kind: 'systemPrompt' | 'planMode';
+    text: string;
+    sourceLineId?: string;
+}
+export interface PromptsSection {
+    version: 1;
+    prompts: PromptEntry[];
+}
+export interface WorkspaceRecord {
+    id: string;
+    path: string;
+    title?: string;
+    sessionIds: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface WorkspacesSection {
+    version: 1;
+    workspaces: WorkspaceRecord[];
+}
+export interface CredentialStatus {
+    ref: string;
+    required: boolean;
+    configured: boolean;
+    source?: 'env' | 'file' | 'projectEnv' | 'other';
+    hasValue: boolean;
+}
+export interface CredentialsSection {
+    version: 1;
+    credentials: CredentialStatus[];
+}
+export interface FileEntry {
+    relativePath: string;
+    data: Uint8Array;
+    contentHash: string;
+}
+export interface FilesSection {
+    version: 1;
+    files: FileEntry[];
+}
+/** 分区 JSON 文件的统一载荷（schema 校验用） */
+export type SectionData = SettingsSection | UiSection | ProvidersSection | PluginsSection | McpSection | PromptsSection | WorkspacesSection | CredentialsSection | FilesSection;

package/lib/schema/types.js

@@ -0,0 +1,8 @@
+/**
+ * 核心领域类型（Export Schema v1 的纯类型定义）。
+ *
+ * 对齐 Docs/design/architecture.md §13.1 —— m3/m5 的共同契约。
+ * 本文件只含与 DSH 运行时无关的纯数据形状；DSH Service 门面类型见 src/core/types.ts。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/schema/versions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Export Schema 版本判定 —— 集中唯一出口（对齐 Docs/design/architecture.md §10.3）。
+ *
+ * 业务代码零版本判断：所有模块一律通过本文件函数判定，
+ * 任何 `if (v === 1)` 式散落判断均为禁止项。
+ */
+/** 当前 Export Schema 版本（v1 起点；未来随迁移链演进） */
+export declare const CURRENT_SCHEMA_VERSION: 1;
+/** 本插件支持导入的最低 schema 版本 */
+export declare const MIN_SUPPORTED_SCHEMA_VERSION: 1;
+/** 版本不受支持（过新或过旧）时的错误；携带版本号便于 UI 提示升级/更新备份 */
+export declare class UnsupportedSchemaError extends Error {
+    readonly version: number;
+    constructor(version: number, message?: string);
+}
+/** 恰好是当前版本 */
+export declare function isCurrent(v: number): boolean;
+/** 版本在支持范围内（含需要迁移的旧版本） */
+export declare function isSupported(v: number): boolean;
+/** 旧版本：低于当前但仍在支持范围内 → 需要沿迁移链升级 */
+export declare function needsMigration(v: number): boolean;
+/** 过新版本：高于当前 → 必须升级本插件才能导入 */
+export declare function isTooNew(v: number): boolean;
+/** 是否可导入（当前版本或可迁移的旧版本） */
+export declare function canImport(v: number): boolean;
+/** 版本的可读描述（报告/日志用） */
+export declare function describeVersion(v: number): string;

package/lib/schema/versions.js

@@ -0,0 +1,50 @@
+/**
+ * Export Schema 版本判定 —— 集中唯一出口（对齐 Docs/design/architecture.md §10.3）。
+ *
+ * 业务代码零版本判断：所有模块一律通过本文件函数判定，
+ * 任何 `if (v === 1)` 式散落判断均为禁止项。
+ */
+/** 当前 Export Schema 版本（v1 起点；未来随迁移链演进） */
+export const CURRENT_SCHEMA_VERSION = 1;
+/** 本插件支持导入的最低 schema 版本 */
+export const MIN_SUPPORTED_SCHEMA_VERSION = 1;
+/** 版本不受支持（过新或过旧）时的错误；携带版本号便于 UI 提示升级/更新备份 */
+export class UnsupportedSchemaError extends Error {
+    version;
+    constructor(version, message = `Export schema version ${version} is not supported (current: ${CURRENT_SCHEMA_VERSION})`) {
+        super(message);
+        this.name = 'UnsupportedSchemaError';
+        this.version = version;
+    }
+}
+/** 恰好是当前版本 */
+export function isCurrent(v) {
+    return v === CURRENT_SCHEMA_VERSION;
+}
+/** 版本在支持范围内（含需要迁移的旧版本） */
+export function isSupported(v) {
+    return v >= MIN_SUPPORTED_SCHEMA_VERSION && v <= CURRENT_SCHEMA_VERSION;
+}
+/** 旧版本：低于当前但仍在支持范围内 → 需要沿迁移链升级 */
+export function needsMigration(v) {
+    return v >= MIN_SUPPORTED_SCHEMA_VERSION && v < CURRENT_SCHEMA_VERSION;
+}
+/** 过新版本：高于当前 → 必须升级本插件才能导入 */
+export function isTooNew(v) {
+    return v > CURRENT_SCHEMA_VERSION;
+}
+/** 是否可导入（当前版本或可迁移的旧版本） */
+export function canImport(v) {
+    return isCurrent(v) || needsMigration(v);
+}
+/** 版本的可读描述（报告/日志用） */
+export function describeVersion(v) {
+    if (isTooNew(v))
+        return `schema v${v}（高于当前 ${CURRENT_SCHEMA_VERSION}，需升级插件）`;
+    if (needsMigration(v))
+        return `schema v${v}（旧版，将迁移到 v${CURRENT_SCHEMA_VERSION}）`;
+    if (isCurrent(v))
+        return `schema v${v}（当前版本）`;
+    return `schema v${v}（低于最低支持 ${MIN_SUPPORTED_SCHEMA_VERSION}，不受支持）`;
+}
+//# sourceMappingURL=versions.js.map

package/lib/security/encryption.d.ts

@@ -0,0 +1,85 @@
+import type { EncryptionInfo } from '../schema/types.ts';
+import type { EncryptionProvider } from '../core/types.ts';
+export declare const SCHEMA_MAGIC = "DSC1";
+export declare const SCHEMA_VERSION = 1;
+/** 整体加密备份容器的 magic（D C A rchive）：头部布局同 secrets.enc，kdf 参数用默认常量 */
+export declare const ARCHIVE_MAGIC = "DCA1";
+export declare const ARCHIVE_VERSION = 1;
+/** 探测字节是否为整体加密备份容器（上传/下载时判定 containerType） */
+export declare function isArchiveBlob(buf: Uint8Array): boolean;
+export declare const SCRYPT_PARAMS: {
+    readonly N: 16384;
+    readonly r: 8;
+    readonly p: 1;
+    readonly keyLength: 32;
+};
+export declare const SALT_LENGTH = 16;
+export declare const IV_LENGTH = 12;
+export declare const TAG_LENGTH = 16;
+/** magic(4) + version(1) + salt(16) + iv(12) + authTag(16) */
+export declare const HEADER_LENGTH: number;
+export type SecurityErrorCode = 'BAD_PASSWORD' | 'TAMPERED' | 'UNSUPPORTED_FORMAT';
+export declare class SecurityError extends Error {
+    readonly code: SecurityErrorCode;
+    constructor(code: SecurityErrorCode, message: string);
+}
+/** KDF 参数值域校验（防 manifest 被篡改成超大 N 导致 DoS；非法即拒绝） */
+export declare function validateKdfParams(params: unknown): params is EncryptionInfo['kdfParams'];
+/** 派生密钥（scrypt，参数可来自 manifest；默认常量） */
+export declare function deriveKey(password: string, salt: Uint8Array, params?: EncryptionInfo['kdfParams']): Promise<Buffer>;
+/** 加密 .credentials.yaml 原文 → { blob, info }（info 直接进 manifest.security.encryption） */
+export declare function encryptCredentials(plaintext: string, password: string): Promise<{
+    blob: Uint8Array;
+    info: EncryptionInfo;
+}>;
+/** 解密 secrets.enc（authTag 校验失败抛 BAD_PASSWORD；元数据不一致抛 TAMPERED） */
+export declare function decryptCredentials(blob: Uint8Array, info: EncryptionInfo, password: string): Promise<string>;
+/**
+ * 创建 core `EncryptionProvider`（对齐 core/types.ts 契约）。
+ * encrypt 使用闭包持有密码；decrypt 使用调用方传入的密码（支持换密码解密）。
+ */
+export declare function createEncryptionProvider(password: string): EncryptionProvider;
+/**
+ * 加密完整 ZIP 字节 → 加密容器 blob。
+ *
+ * 布局（DCA1，与 secrets.enc 同构，kdf 参数用默认常量）：
+ *   magic "DCA1"(4B) + version(1B) + salt(16B) + iv(12B) + authTag(16B) + ciphertext(plainZIP)
+ *
+ * 语义：整个备份（manifest / 各分区 JSON / sessions / 插件文件 / secrets.enc……）
+ * 全部进入 ciphertext，磁盘上无法看到任何明文内容。verifyEncryptedBlob 用于
+ * 校验密码正确（GCM authTag 通过）且返回真实解密用的随机参数。
+ */
+export declare function encryptArchive(plainZip: Uint8Array, password: string): Promise<{
+    blob: Uint8Array;
+    info: EncryptionInfo;
+    kdf: {
+        salt: Buffer;
+        iv: Buffer;
+    };
+}>;
+/** 容器版解密：用「先验真实参数」校验密码并解密（—— 调用方必须先用 verifyEncryptedBlob 拿到 info/kdf） */
+export declare function decryptArchive(blob: Uint8Array, info: EncryptionInfo, kdfParam: {
+    salt: Buffer;
+    iv: Buffer;
+}, password: string): Promise<Uint8Array>;
+export interface EncryptedBlobInfo {
+    /** 容器是否合法（magic/version/header 校验通过） */
+    valid: boolean;
+    /** 密码是否正确（GCM authTag 认证通过）；valid=false 时恒 false */
+    ok: boolean;
+    /** 解密所需参数（valid && ok 时有效；用默认常量派生 key） */
+    info: EncryptionInfo | null;
+    kdf: {
+        salt: Buffer;
+        iv: Buffer;
+    } | null;
+    /** 错误码（供上层转用户可读错误）：BAD_PASSWORD / TAMPERED / UNSUPPORTED_FORMAT */
+    code: SecurityErrorCode | null;
+}
+/**
+ * 校验加密备份容器并验证密码（只读，零解密返回内容）。
+ * - 容器不合法（非 DCA1 / 截断 / 参数异常）→ valid=false + code
+ * - 密码正确 → ok=true + 返回随机参数（后续 decryptArchive 用之）
+ * - 密码错误 → ok=false + code=BAD_PASSWORD
+ */
+export declare function verifyEncryptedBlob(blob: Uint8Array, password: string): Promise<EncryptedBlobInfo>;

package/lib/security/encryption.js

@@ -0,0 +1,279 @@
+/**
+ * 凭据加密（规范 §7 / 设计 §7.3 / core `EncryptionProvider` 契约实现，零依赖 node:crypto）。
+ *
+ * 方案：scrypt（KDF）+ AES-256-GCM（AEAD），每次导出 salt/iv 全随机，密码绝不落盘。
+ * secrets.enc 二进制布局（设计 §7.3 细化）：
+ *
+ *   magic "DSC1"(4B) + version(1B) + salt(16B) + iv(12B) + authTag(16B) + ciphertext
+ *
+ * - magic/version 不符 → `UNSUPPORTED_FORMAT`（不是本插件产物 / 版本过新）
+ * - blob 内嵌参数与 manifest 的 EncryptionInfo 不一致 → `TAMPERED`（元数据被篡改）
+ * - GCM 认证失败（密码错误或密文被改） → `BAD_PASSWORD`（提示重输密码或核对备份来源）
+ *
+ * 与 core 契约的关系：
+ * - `createEncryptionProvider(password)` 返回 core `EncryptionProvider`（encrypt 无密码参数，
+ *   闭包持有导出密码；decrypt 用调用方传入的密码 → 支持「换密码解密」）。
+ * - 底层纯函数 encryptCredentials/decryptCredentials 对齐设计 §13.4，供直接调用与测试。
+ * - plaintext 语义：`.credentials.yaml` 文件原文（m5 经 HostContext.fs 文件级读取提供；
+ *   ctx.credentials 永不回读值——研究报告 §3.2 硬约束），本模块只做字节级加解密。
+ */
+import crypto from 'node:crypto';
+import { promisify } from 'node:util';
+const scryptAsync = promisify(crypto.scrypt);
+export const SCHEMA_MAGIC = 'DSC1';
+export const SCHEMA_VERSION = 1;
+/** 整体加密备份容器的 magic（D C A rchive）：头部布局同 secrets.enc，kdf 参数用默认常量 */
+export const ARCHIVE_MAGIC = 'DCA1';
+export const ARCHIVE_VERSION = 1;
+/** 探测字节是否为整体加密备份容器（上传/下载时判定 containerType） */
+export function isArchiveBlob(buf) {
+    return Buffer.from(buf.subarray(0, 4)).toString('ascii') === ARCHIVE_MAGIC;
+}
+export const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, keyLength: 32 };
+export const SALT_LENGTH = 16;
+export const IV_LENGTH = 12;
+export const TAG_LENGTH = 16;
+/** magic(4) + version(1) + salt(16) + iv(12) + authTag(16) */
+export const HEADER_LENGTH = 4 + 1 + SALT_LENGTH + IV_LENGTH + TAG_LENGTH;
+export class SecurityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SecurityError';
+        this.code = code;
+    }
+}
+/** KDF 参数值域校验（防 manifest 被篡改成超大 N 导致 DoS；非法即拒绝） */
+export function validateKdfParams(params) {
+    if (params === null || typeof params !== 'object')
+        return false;
+    const p = params;
+    if (typeof p['N'] !== 'number' || p['N'] < 2 ** 14 || p['N'] > 2 ** 20)
+        return false;
+    if (typeof p['r'] !== 'number' || p['r'] < 1 || p['r'] > 32)
+        return false;
+    if (typeof p['p'] !== 'number' || p['p'] < 1 || p['p'] > 32)
+        return false;
+    return typeof p['keyLength'] === 'number' && p['keyLength'] === 32;
+}
+/** 派生密钥（scrypt，参数可来自 manifest；默认常量） */
+export async function deriveKey(password, salt, params = SCRYPT_PARAMS) {
+    return scryptAsync(password, salt, params.keyLength, { N: params.N, r: params.r, p: params.p });
+}
+/** 加密 .credentials.yaml 原文 → { blob, info }（info 直接进 manifest.security.encryption） */
+export async function encryptCredentials(plaintext, password) {
+    if (password === '')
+        throw new SecurityError('BAD_PASSWORD', '加密密码不能为空');
+    // 产品决策（2026-09-13）：加密**不做任何密码强度校验**——用户提供的任何密码都必须可用。
+    // 请勿在此重新加入强度闸门；用户自定的密码策略不由本插件约束。
+    const salt = crypto.randomBytes(SALT_LENGTH);
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const key = await deriveKey(password, salt);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const header = Buffer.alloc(HEADER_LENGTH);
+    header.write(SCHEMA_MAGIC, 0, 'ascii');
+    header[4] = SCHEMA_VERSION;
+    salt.copy(header, 5);
+    iv.copy(header, 5 + SALT_LENGTH);
+    authTag.copy(header, 5 + SALT_LENGTH + IV_LENGTH);
+    const info = {
+        algorithm: 'aes-256-gcm',
+        kdf: 'scrypt',
+        kdfParams: { ...SCRYPT_PARAMS },
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: authTag.toString('base64'),
+        version: SCHEMA_VERSION,
+    };
+    return { blob: Buffer.concat([header, encrypted]), info };
+}
+/** 解密 secrets.enc（authTag 校验失败抛 BAD_PASSWORD；元数据不一致抛 TAMPERED） */
+export async function decryptCredentials(blob, info, password) {
+    if (blob.length < HEADER_LENGTH) {
+        throw new SecurityError('TAMPERED', 'secrets.enc 体积过小（截断或损坏）');
+    }
+    const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+    if (magic !== SCHEMA_MAGIC) {
+        throw new SecurityError('UNSUPPORTED_FORMAT', `未知文件格式 magic "${magic}"，不是本插件产物`);
+    }
+    const version = blob[4];
+    if (version !== SCHEMA_VERSION) {
+        throw new SecurityError('UNSUPPORTED_FORMAT', `不支持的 secrets.enc 版本 ${version}`);
+    }
+    if (info.algorithm !== 'aes-256-gcm' || info.kdf !== 'scrypt' || !validateKdfParams(info.kdfParams)) {
+        throw new SecurityError('UNSUPPORTED_FORMAT', 'manifest 加密参数非法或不受支持');
+    }
+    const blobSalt = blob.subarray(5, 5 + SALT_LENGTH);
+    const blobIv = blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH);
+    const blobTag = blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH);
+    if (info.salt !== Buffer.from(blobSalt).toString('base64') ||
+        info.iv !== Buffer.from(blobIv).toString('base64') ||
+        info.authTag !== Buffer.from(blobTag).toString('base64')) {
+        throw new SecurityError('TAMPERED', 'secrets.enc 与 manifest 加密参数不一致（可能被篡改）');
+    }
+    let key;
+    try {
+        key = await deriveKey(password, blobSalt, info.kdfParams);
+    }
+    catch (err) {
+        throw new SecurityError('BAD_PASSWORD', `密钥派生失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, blobIv);
+    decipher.setAuthTag(blobTag);
+    try {
+        const decrypted = Buffer.concat([
+            decipher.update(blob.subarray(HEADER_LENGTH)),
+            decipher.final(),
+        ]);
+        return decrypted.toString('utf8');
+    }
+    catch {
+        throw new SecurityError('BAD_PASSWORD', '解密认证失败：密码错误或密文被篡改');
+    }
+}
+/**
+ * 创建 core `EncryptionProvider`（对齐 core/types.ts 契约）。
+ * encrypt 使用闭包持有密码；decrypt 使用调用方传入的密码（支持换密码解密）。
+ */
+export function createEncryptionProvider(password) {
+    return {
+        async encrypt(plaintext) {
+            return encryptCredentials(plaintext, password);
+        },
+        async decrypt(blob, info, pw) {
+            return decryptCredentials(blob, info, pw);
+        },
+    };
+}
+/* ---------------- 整体备份容器加密（§7.4：加密整个 ZIP，而非仅 secrets） ---------------- */
+/**
+ * 加密完整 ZIP 字节 → 加密容器 blob。
+ *
+ * 布局（DCA1，与 secrets.enc 同构，kdf 参数用默认常量）：
+ *   magic "DCA1"(4B) + version(1B) + salt(16B) + iv(12B) + authTag(16B) + ciphertext(plainZIP)
+ *
+ * 语义：整个备份（manifest / 各分区 JSON / sessions / 插件文件 / secrets.enc……）
+ * 全部进入 ciphertext，磁盘上无法看到任何明文内容。verifyEncryptedBlob 用于
+ * 校验密码正确（GCM authTag 通过）且返回真实解密用的随机参数。
+ */
+export async function encryptArchive(plainZip, password) {
+    if (password === '')
+        throw new SecurityError('BAD_PASSWORD', '加密密码不能为空');
+    // 产品决策（2026-09-13）：加密**不做任何密码强度校验**——用户提供的任何密码都必须可用。
+    // 请勿在此重新加入强度闸门；用户自定的密码策略不由本插件约束。
+    const salt = crypto.randomBytes(SALT_LENGTH);
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const key = await deriveKey(password, salt);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plainZip), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const header = Buffer.alloc(HEADER_LENGTH);
+    header.write(ARCHIVE_MAGIC, 0, 'ascii');
+    header[4] = ARCHIVE_VERSION;
+    salt.copy(header, 5);
+    iv.copy(header, 5 + SALT_LENGTH);
+    authTag.copy(header, 5 + SALT_LENGTH + IV_LENGTH);
+    const info = {
+        algorithm: 'aes-256-gcm',
+        kdf: 'scrypt',
+        kdfParams: { ...SCRYPT_PARAMS },
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: authTag.toString('base64'),
+        version: ARCHIVE_VERSION,
+    };
+    return { blob: Buffer.concat([header, encrypted]), info, kdf: { salt, iv } };
+}
+/** 容器版解密：用「先验真实参数」校验密码并解密（—— 调用方必须先用 verifyEncryptedBlob 拿到 info/kdf） */
+export async function decryptArchive(blob, info, kdfParam, password) {
+    if (blob.length < HEADER_LENGTH) {
+        throw new SecurityError('TAMPERED', '加密备份容器体积过小（截断或损坏）');
+    }
+    const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+    if (magic !== ARCHIVE_MAGIC) {
+        throw new SecurityError('UNSUPPORTED_FORMAT', `未知文件格式 magic "${magic}"，不是本插件产物`);
+    }
+    const version = blob[4];
+    if (version !== ARCHIVE_VERSION) {
+        throw new SecurityError('UNSUPPORTED_FORMAT', `不支持的加密备份版本 ${version}`);
+    }
+    const blobSalt = Buffer.from(blob.subarray(5, 5 + SALT_LENGTH));
+    const blobIv = Buffer.from(blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH));
+    const blobTag = Buffer.from(blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH));
+    const paramSalt = Buffer.isBuffer(kdfParam.salt) ? kdfParam.salt : Buffer.from(kdfParam.salt);
+    const paramIv = Buffer.isBuffer(kdfParam.iv) ? kdfParam.iv : Buffer.from(kdfParam.iv);
+    // 与此时真实的随机参数对齐（参数来自 verify 阶段读取，防调用方换参数）
+    if (!blobSalt.equals(paramSalt) ||
+        !blobIv.equals(paramIv)) {
+        throw new SecurityError('TAMPERED', '加密备份参数不一致（可能被篡改）');
+    }
+    let key;
+    try {
+        key = await deriveKey(password, blobSalt, info.kdfParams);
+    }
+    catch (err) {
+        throw new SecurityError('BAD_PASSWORD', `密钥派生失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, blobIv);
+    decipher.setAuthTag(blobTag);
+    try {
+        return Buffer.concat([
+            decipher.update(blob.subarray(HEADER_LENGTH)),
+            decipher.final(),
+        ]);
+    }
+    catch {
+        throw new SecurityError('BAD_PASSWORD', '解密认证失败：密码错误或密文被篡改');
+    }
+}
+/**
+ * 校验加密备份容器并验证密码（只读，零解密返回内容）。
+ * - 容器不合法（非 DCA1 / 截断 / 参数异常）→ valid=false + code
+ * - 密码正确 → ok=true + 返回随机参数（后续 decryptArchive 用之）
+ * - 密码错误 → ok=false + code=BAD_PASSWORD
+ */
+export async function verifyEncryptedBlob(blob, password) {
+    if (blob.length < HEADER_LENGTH) {
+        return { valid: false, ok: false, info: null, kdf: null, code: 'TAMPERED' };
+    }
+    const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+    if (magic !== ARCHIVE_MAGIC) {
+        return { valid: false, ok: false, info: null, kdf: null, code: 'UNSUPPORTED_FORMAT' };
+    }
+    const version = blob[4];
+    if (version !== ARCHIVE_VERSION) {
+        return { valid: false, ok: false, info: null, kdf: null, code: 'UNSUPPORTED_FORMAT' };
+    }
+    const salt = Buffer.from(blob.subarray(5, 5 + SALT_LENGTH));
+    const iv = Buffer.from(blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH));
+    const tag = Buffer.from(blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH));
+    const info = {
+        algorithm: 'aes-256-gcm',
+        kdf: 'scrypt',
+        kdfParams: { ...SCRYPT_PARAMS },
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        authTag: tag.toString('base64'),
+        version: ARCHIVE_VERSION,
+    };
+    let key;
+    try {
+        key = await deriveKey(password, salt, info.kdfParams);
+    }
+    catch (err) {
+        return { valid: true, ok: false, info, kdf: { salt, iv }, code: 'BAD_PASSWORD' };
+    }
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        decipher.update(blob.subarray(HEADER_LENGTH));
+        decipher.final();
+    }
+    catch {
+        return { valid: true, ok: false, info, kdf: { salt, iv }, code: 'BAD_PASSWORD' };
+    }
+    return { valid: true, ok: true, info, kdf: { salt, iv }, code: null };
+}
+//# sourceMappingURL=encryption.js.map