dsh-config-manager 0.1.0

package/src/schema/config.ts

@@ -0,0 +1,137 @@
+/**
+ * 各分区数据结构：ZIP 内 JSON 分区文件 → 解析/校验，以及分区文件路径表。
+ * 类型本体在 types.ts；本文件是「分区数据如何落盘/读回」的唯一出口。
+ */
+import { parseJsonSafe } from '../utils/json.ts';
+import type {
+  CredentialsSection, FilesSection, McpSection, PluginsSection,
+  PromptsSection, ProvidersSection, SectionData, SectionId,
+  SettingsSection, UiSection, WorkspacesSection,
+} from './types.ts';
+
+/** 全部分区 id（manifest 校验与 adapter registry 共用） */
+export const SECTION_IDS: readonly SectionId[] = [
+  'settings', 'ui', 'providers', 'plugins', 'mcp', 'prompts',
+  'skills', 'agentPresets', 'workspaces', 'pluginFiles',
+  'credentialsStatus', 'secrets', 'sessions',
+];
+
+/** JSON 分区在 ZIP 内的相对路径；文件类分区（skills 等）走目录前缀，不在此表 */
+export const SECTION_JSON_PATHS: Partial<Record<SectionId, string>> = {
+  settings: 'config/settings.json',
+  ui: 'config/ui.json',
+  providers: 'ai/providers.json',
+  plugins: 'plugins/plugins.json',
+  mcp: 'mcp/servers.json',
+  prompts: 'custom/prompts.json',
+  workspaces: 'workspaces/workspaces.json',
+  credentialsStatus: 'security/credentials.json',
+};
+
+/** 文件类分区在 ZIP 内的目录前缀 */
+export const SECTION_FILE_PREFIXES: Partial<Record<SectionId, string>> = {
+  skills: 'custom/skills/',
+  agentPresets: 'agents/presets/',
+  pluginFiles: 'plugin-files/',
+  sessions: 'sessions/',
+};
+
+/** 该分区是否是「文件类」分区（ZIP 内以真实文件存放而非 JSON） */
+export function isFileSection(sectionId: SectionId): boolean {
+  return sectionId in SECTION_FILE_PREFIXES;
+}
+
+/** 从 ZIP 内 JSON 解析分区数据（深度保护 + 结构校验） */
+export function parseSectionJson<T extends SectionData>(sectionId: SectionId, raw: string): T {
+  const parsed = parseJsonSafe(raw) as T;
+  const issues = validateSectionData(sectionId, parsed);
+  const errors = issues.filter((i) => i.severity === 'error');
+  if (errors.length > 0) {
+    throw new Error(`分区 ${sectionId} 数据无效: ${errors.map((e) => e.message).join('; ')}`);
+  }
+  return parsed;
+}
+
+export interface SectionIssue { path: string; message: string; severity: 'error' | 'warning'; }
+
+/** 分区数据结构基础校验（version 字段 + 顶层形状） */
+export function validateSectionData(sectionId: SectionId, data: unknown): SectionIssue[] {
+  const issues: SectionIssue[] = [];
+  if (data === null || typeof data !== 'object') {
+    return [{ path: '$', message: `分区 ${sectionId} 数据必须是对象`, severity: 'error' }];
+  }
+  const obj = data as Record<string, unknown>;
+  if (obj['version'] !== 1) {
+    issues.push({ path: 'version', message: `分区 ${sectionId} 的 version 必须为 1（收到 ${String(obj['version'])}）`, severity: 'error' });
+    return issues;
+  }
+  switch (sectionId) {
+    case 'settings':
+    case 'ui': {
+      const ns = obj['namespaces'];
+      if (ns === null || typeof ns !== 'object') {
+        issues.push({ path: 'namespaces', message: `分区 ${sectionId} 缺少 namespaces 对象`, severity: 'error' });
+      } else {
+        for (const [name, rec] of Object.entries(ns as Record<string, unknown>)) {
+          if (rec === null || typeof rec !== 'object') {
+            issues.push({ path: `namespaces.${name}`, message: 'namespace 记录必须是对象', severity: 'error' });
+            continue;
+          }
+          const r = rec as Record<string, unknown>;
+          if (typeof r['revision'] !== 'number') issues.push({ path: `namespaces.${name}.revision`, message: 'revision 必须是数字', severity: 'error' });
+          if (!('value' in r)) issues.push({ path: `namespaces.${name}.value`, message: '缺少 value', severity: 'error' });
+          const secrets = r['secrets'];
+          if (secrets !== undefined && !Array.isArray(secrets)) issues.push({ path: `namespaces.${name}.secrets`, message: 'secrets 必须是数组', severity: 'error' });
+        }
+      }
+      break;
+    }
+    case 'providers': {
+      const p = obj['providers'];
+      if (p === null || typeof p !== 'object') issues.push({ path: 'providers', message: '缺少 providers 对象', severity: 'error' });
+      break;
+    }
+    case 'plugins': {
+      if (!Array.isArray(obj['plugins'])) issues.push({ path: 'plugins', message: 'plugins 必须是数组', severity: 'error' });
+      if (obj['patch'] !== undefined && !Array.isArray(obj['patch'])) issues.push({ path: 'patch', message: 'patch 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'mcp': {
+      if (!Array.isArray(obj['servers'])) issues.push({ path: 'servers', message: 'servers 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'prompts': {
+      if (!Array.isArray(obj['prompts'])) issues.push({ path: 'prompts', message: 'prompts 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'workspaces': {
+      if (!Array.isArray(obj['workspaces'])) issues.push({ path: 'workspaces', message: 'workspaces 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'credentialsStatus': {
+      if (!Array.isArray(obj['credentials'])) issues.push({ path: 'credentials', message: 'credentials 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'skills':
+    case 'agentPresets':
+    case 'pluginFiles':
+    case 'sessions': {
+      if (!Array.isArray(obj['files'])) issues.push({ path: 'files', message: 'files 必须是数组', severity: 'error' });
+      break;
+    }
+    default:
+      issues.push({ path: '$', message: `未知分区 ${sectionId}`, severity: 'error' });
+  }
+  return issues;
+}
+
+/** 分区 JSON 载荷的类型收窄（供 adapter / analyzer 使用） */
+export function asSettingsSection(data: unknown): SettingsSection { return data as SettingsSection; }
+export function asUiSection(data: unknown): UiSection { return data as UiSection; }
+export function asProvidersSection(data: unknown): ProvidersSection { return data as ProvidersSection; }
+export function asPluginsSection(data: unknown): PluginsSection { return data as PluginsSection; }
+export function asMcpSection(data: unknown): McpSection { return data as McpSection; }
+export function asPromptsSection(data: unknown): PromptsSection { return data as PromptsSection; }
+export function asWorkspacesSection(data: unknown): WorkspacesSection { return data as WorkspacesSection; }
+export function asCredentialsSection(data: unknown): CredentialsSection { return data as CredentialsSection; }
+export function asFilesSection(data: unknown): FilesSection { return data as FilesSection; }

package/src/schema/manifest.ts

@@ -0,0 +1,124 @@
+/**
+ * manifest.json 的类型、解析、序列化与结构校验。
+ * 类型本体在 types.ts（§13.1）；本文件负责 manifest 的读写与结构完整性。
+ */
+import { parseJsonSafe } from '../utils/json.ts';
+import { CURRENT_SCHEMA_VERSION } from './versions.ts';
+import type { Manifest, Platform, SectionId } from './types.ts';
+import { SECTION_IDS } from './config.ts';
+
+export const MANIFEST_FILE = 'manifest.json';
+export const CHECKSUMS_FILE = 'integrity/checksums.json';
+export const EXPORTER_NAME = 'DSH Config Manager';
+
+export interface BuildManifestInput {
+  exporterVersion: string;
+  dshVersion: string;
+  platform: Platform;
+  arch: string;
+  sections: Record<SectionId, boolean>;
+  containsSecrets: boolean;
+  encrypted: boolean;
+  encryption: Manifest['security']['encryption'];
+  exportedAt?: string; // 测试可注入固定时间
+}
+
+/** 构造 manifest（schemaVersion 恒为当前版本，集中于此） */
+export function buildManifest(input: BuildManifestInput): Manifest {
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    exporter: { name: EXPORTER_NAME, version: input.exporterVersion },
+    source: {
+      dshVersion: input.dshVersion,
+      platform: input.platform,
+      arch: input.arch,
+    },
+    exportedAt: input.exportedAt ?? new Date().toISOString(),
+    sections: input.sections,
+    security: {
+      containsSecrets: input.containsSecrets,
+      encrypted: input.encrypted,
+      encryption: input.encryption,
+    },
+  };
+}
+
+/** 序列化（pretty JSON，供 ZIP 内 manifest.json） */
+export function serializeManifest(manifest: Manifest): string {
+  return JSON.stringify(manifest, null, 2);
+}
+
+/** 解析 + 结构校验；非法输入抛错（导入第一道闸之一） */
+export function parseManifest(raw: string): Manifest {
+  const parsed = parseJsonSafe(raw);
+  const issues = validateManifest(parsed);
+  const errors = issues.filter((i) => i.severity === 'error');
+  if (errors.length > 0) {
+    throw new Error(`manifest.json 无效: ${errors.map((e) => e.message).join('; ')}`);
+  }
+  return parsed as Manifest;
+}
+
+export interface ManifestIssue { path: string; message: string; severity: 'error' | 'warning'; }
+
+/** 结构校验：字段类型 / sections 键集合 / security 形状 */
+export function validateManifest(m: unknown): ManifestIssue[] {
+  const issues: ManifestIssue[] = [];
+  if (m === null || typeof m !== 'object') {
+    return [{ path: '$', message: 'manifest 必须是对象', severity: 'error' }];
+  }
+  const obj = m as Record<string, unknown>;
+
+  if (typeof obj['schemaVersion'] !== 'number') {
+    issues.push({ path: 'schemaVersion', message: 'schemaVersion 必须是数字', severity: 'error' });
+  }
+
+  const exporter = obj['exporter'] as Record<string, unknown> | undefined;
+  if (!exporter || typeof exporter !== 'object') {
+    issues.push({ path: 'exporter', message: 'exporter 缺失', severity: 'error' });
+  } else {
+    if (typeof exporter['name'] !== 'string') issues.push({ path: 'exporter.name', message: 'exporter.name 必须是字符串', severity: 'error' });
+    if (typeof exporter['version'] !== 'string') issues.push({ path: 'exporter.version', message: 'exporter.version 必须是字符串', severity: 'error' });
+  }
+
+  const source = obj['source'] as Record<string, unknown> | undefined;
+  if (!source || typeof source !== 'object') {
+    issues.push({ path: 'source', message: 'source 缺失', severity: 'error' });
+  } else {
+    if (typeof source['dshVersion'] !== 'string') issues.push({ path: 'source.dshVersion', message: 'source.dshVersion 必须是字符串', severity: 'error' });
+    if (typeof source['platform'] !== 'string') issues.push({ path: 'source.platform', message: 'source.platform 必须是字符串', severity: 'error' });
+    if (typeof source['arch'] !== 'string') issues.push({ path: 'source.arch', message: 'source.arch 必须是字符串', severity: 'error' });
+  }
+
+  if (typeof obj['exportedAt'] !== 'string' || Number.isNaN(Date.parse(obj['exportedAt']))) {
+    issues.push({ path: 'exportedAt', message: 'exportedAt 必须是合法 ISO-8601 时间', severity: 'error' });
+  }
+
+  const sections = obj['sections'] as Record<string, unknown> | undefined;
+  if (!sections || typeof sections !== 'object') {
+    issues.push({ path: 'sections', message: 'sections 缺失', severity: 'error' });
+  } else {
+    for (const key of Object.keys(sections)) {
+      if (!(SECTION_IDS as readonly string[]).includes(key)) {
+        issues.push({ path: `sections.${key}`, message: `未知分区 "${key}"`, severity: 'warning' });
+      }
+      if (typeof sections[key] !== 'boolean') {
+        issues.push({ path: `sections.${key}`, message: `sections.${key} 必须是布尔`, severity: 'error' });
+      }
+    }
+  }
+
+  const security = obj['security'] as Record<string, unknown> | undefined;
+  if (!security || typeof security !== 'object') {
+    issues.push({ path: 'security', message: 'security 缺失', severity: 'error' });
+  } else {
+    if (typeof security['containsSecrets'] !== 'boolean') issues.push({ path: 'security.containsSecrets', message: 'containsSecrets 必须是布尔', severity: 'error' });
+    if (typeof security['encrypted'] !== 'boolean') issues.push({ path: 'security.encrypted', message: 'encrypted 必须是布尔', severity: 'error' });
+    const enc = security['encryption'];
+    if (enc !== null && (typeof enc !== 'object' || enc === undefined)) {
+      issues.push({ path: 'security.encryption', message: 'encryption 必须是对象或 null', severity: 'error' });
+    }
+  }
+
+  return issues;
+}

package/src/schema/types.ts

@@ -0,0 +1,179 @@
+/**
+ * 核心领域类型（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）不在此列。
+ */
+export type SectionId =
+  | 'settings' | 'ui' | 'providers' | 'plugins' | 'mcp' | 'prompts'
+  | 'skills' | 'agentPresets' | 'workspaces' | 'pluginFiles'
+  | 'credentialsStatus' | 'secrets' | 'sessions';
+
+/** 加密备份的算法参数（非秘密：salt/iv/authTag 仅用于解密与完整性校验） */
+export interface EncryptionInfo {
+  algorithm: 'aes-256-gcm';
+  kdf: 'scrypt';
+  kdfParams: { N: number; r: number; p: number; keyLength: number };
+  salt: string;   // base64
+  iv: string;     // base64
+  authTag: string;// base64（GCM 认证标签）
+  version: number;
+}
+
+/** 每个导出 ZIP 根部的 manifest.json */
+export interface Manifest {
+  schemaVersion: number;
+  exporter: { name: string; version: string };
+  source: { dshVersion: string; platform: Platform; arch: string };
+  exportedAt: string; // ISO-8601 UTC
+  sections: Record<SectionId, boolean>;
+  security: {
+    containsSecrets: boolean;
+    encrypted: boolean;
+    encryption: EncryptionInfo | null;
+  };
+}
+
+/* —— settings / ui 分区 —— */
+
+/** 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[];
+}
+
+/* —— providers 分区 —— */
+
+export interface ProviderEntry {
+  route: string;
+  apiKeyEnv?: string; // 只记环境变量名，值在 credentials
+  displayName?: string;
+  baseURL?: string;
+  models?: unknown[];
+  modelOverrides?: unknown;
+  reasoning?: unknown;
+  transport?: unknown;
+  retryPolicy?: unknown;
+}
+
+export interface ProvidersSection { version: 1; providers: Record<string, ProviderEntry>; }
+
+/* —— plugins 分区 —— */
+
+export interface PluginEntry {
+  name: string;     // 包名
+  version: string;
+  isBundle: boolean;
+  inBundles: string[];
+  enabled: boolean;
+  fiberPhase?: string;
+}
+
+export interface PatchLine { file: string; lineId: string; raw: unknown; }
+
+export interface PluginsSection {
+  version: 1;
+  plugins: PluginEntry[];
+  patch: PatchLine[];
+}
+
+/* —— mcp 分区 —— */
+
+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[]; }
+
+/* —— prompts 分区 —— */
+
+export interface PromptEntry {
+  id: string;
+  name: string;
+  kind: 'systemPrompt' | 'planMode';
+  text: string;
+  sourceLineId?: string;
+}
+
+export interface PromptsSection { version: 1; prompts: PromptEntry[]; }
+
+/* —— workspaces 分区（绝对路径 → 跨设备必须路径映射） —— */
+
+export interface WorkspaceRecord {
+  id: string;
+  path: string;
+  title?: string;
+  sessionIds: string[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface WorkspacesSection { version: 1; workspaces: WorkspaceRecord[]; }
+
+/* —— credentials 状态分区（永不含值） —— */
+
+export interface CredentialStatus {
+  ref: string;
+  required: boolean;
+  configured: boolean;
+  source?: 'env' | 'file' | 'projectEnv' | 'other';
+  hasValue: boolean; // 普通备份恒 false（值未导出）
+}
+
+export interface CredentialsSection { version: 1; credentials: CredentialStatus[]; }
+
+/* —— 文件类分区（skills/agentPresets/pluginFiles/sessions） ——
+ * 这些分区以真实文件形式进入 ZIP（custom/skills/… 等），
+ * 内存中统一表示为 FilesSection（ZIP 内不落此 JSON，见 exporter）。 */
+
+export interface FileEntry {
+  relativePath: string;
+  data: Uint8Array;
+  contentHash: string; // SHA-256 hex
+}
+
+export interface FilesSection { version: 1; files: FileEntry[]; }
+
+/** 分区 JSON 文件的统一载荷（schema 校验用） */
+export type SectionData =
+  | SettingsSection | UiSection | ProvidersSection | PluginsSection
+  | McpSection | PromptsSection | WorkspacesSection | CredentialsSection
+  | FilesSection;

package/src/schema/versions.ts

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

package/src/security/encryption.ts

@@ -0,0 +1,180 @@
+/**
+ * 凭据加密（规范 §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';
+import type { EncryptionInfo } from '../schema/types.ts';
+import type { EncryptionProvider } from '../core/types.ts';
+
+const scryptAsync = promisify(crypto.scrypt) as (
+  password: crypto.BinaryLike,
+  salt: crypto.BinaryLike,
+  keylen: number,
+  options: crypto.ScryptOptions,
+) => Promise<Buffer>;
+
+export const SCHEMA_MAGIC = 'DSC1';
+export const SCHEMA_VERSION = 1;
+export const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, keyLength: 32 } as const;
+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 type SecurityErrorCode = 'BAD_PASSWORD' | 'TAMPERED' | 'UNSUPPORTED_FORMAT';
+
+export class SecurityError extends Error {
+  readonly code: SecurityErrorCode;
+  constructor(code: SecurityErrorCode, message: string) {
+    super(message);
+    this.name = 'SecurityError';
+    this.code = code;
+  }
+}
+
+/** KDF 参数值域校验（防 manifest 被篡改成超大 N 导致 DoS；非法即拒绝） */
+export function validateKdfParams(params: unknown): params is EncryptionInfo['kdfParams'] {
+  if (params === null || typeof params !== 'object') return false;
+  const p = params as Record<string, unknown>;
+  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: string,
+  salt: Uint8Array,
+  params: EncryptionInfo['kdfParams'] = SCRYPT_PARAMS,
+): Promise<Buffer> {
+  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: string,
+  password: string,
+): Promise<{ blob: Uint8Array; info: EncryptionInfo }> {
+  if (password === '') throw new SecurityError('BAD_PASSWORD', '加密密码不能为空');
+  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: EncryptionInfo = {
+    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: Uint8Array,
+  info: EncryptionInfo,
+  password: string,
+): Promise<string> {
+  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: Buffer;
+  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', '解密认证失败：密码错误或密文被篡改');
+  }
+}
+
+/** 密码强度校验（导出 UI 用；≥8 字符，建议 12+ 混合） */
+export function validatePasswordStrength(password: string): { ok: boolean; message: string } {
+  if (password.length < 8) {
+    return { ok: false, message: '密码至少 8 个字符（建议 12+ 且含大小写与数字）' };
+  }
+  const variety = /[a-z]/.test(password) && /[A-Z]/.test(password) && /[0-9]/.test(password);
+  if (password.length < 12 && !variety) {
+    return { ok: true, message: '密码强度偏弱：建议 12+ 字符且混合大小写与数字' };
+  }
+  return { ok: true, message: '' };
+}
+
+/**
+ * 创建 core `EncryptionProvider`（对齐 core/types.ts 契约）。
+ * encrypt 使用闭包持有密码；decrypt 使用调用方传入的密码（支持换密码解密）。
+ */
+export function createEncryptionProvider(password: string): EncryptionProvider {
+  return {
+    async encrypt(plaintext: string): Promise<{ blob: Uint8Array; info: EncryptionInfo }> {
+      return encryptCredentials(plaintext, password);
+    },
+    async decrypt(blob: Uint8Array, info: EncryptionInfo, pw: string): Promise<string> {
+      return decryptCredentials(blob, info, pw);
+    },
+  };
+}