zipcalm 0.0.0-stage → 1.0.2

package/server/http/routes/compress.js

@@ -0,0 +1,339 @@
+// 压缩 / 解压 / 任务 路由（M2）
+//
+// 契约：docs/M0/API规范.md §3.3 端点总表 + §4.3 压缩与任务
+// - 压缩与解压**共用**任务查询/取消/确认删除（`/tasks/{id}/...`），`/compress/tasks/{id}/...` 只是别名；
+// - 所有入参路径都过 `app.fsGuard`（INV-06），业务层再用 core 复算一遍（defense in depth）；
+// - 创建任务前先跑预检：预检不通过**不建任务**（避免"排队后秒失败"的噪音任务）。
+//
+// 结构：**每个端点一个 handler 函数**，参数解析单独抽出（parseCompressRequest / parseExtractRequest），
+// 插件函数 compressRoutes 只做"路由表注册"这一件事。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { resolveWithinRoot } from '../../core/fs/safePath.js';
+import { compressPreflight, extractPreflight } from '../../core/compress/preflight.js';
+import { defaultExtractDir } from '../../core/compress/orchestrator.js';
+
+const COMPRESS_MODES = ['single', 'bundle'];
+
+// ===== 端点 handler =====
+
+/** GET /formats —— 格式列表 + 可用性 + 能力声明（UI 置灰依据） */
+async function handleListFormats(app, request, reply) {
+  const formats = await app.m2.registry.list();
+  // 能力声明：前端据此决定「密码开关能否点」。取值口径是
+  // 「格式声明的 capabilities ∩ 能力插件的 appliesTo ∩ 能力已成功加载」，
+  // 由 capRegistry 统一算，避免前端自己拼条件。
+  // 注意 PW-4：这里只影响 UI，后端仍在建任务时独立校验（不信前端）。
+  const capRegistry = app.m2.capRegistry;
+  if (capRegistry) {
+    for (const format of formats) {
+      // 不能直接把能力模块塞进响应：它内部的 methods 是 Map（JSON 会变成 {}），
+      // 还带着 verify/prepareCreate 等函数。统一走 describe() 取可序列化视图，
+      // 再补上 params（前端要靠它渲染密码输入框的 schema）。
+      format.capabilities = capRegistry.capabilitiesForFormat(format.id).map((cap) => ({
+        ...(typeof cap.describe === 'function' ? cap.describe() : { id: cap.id, name: cap.name }),
+        params: cap.params,
+      }));
+    }
+  }
+  reply.ok({ formats });
+}
+
+/** POST /compress/preflight —— 压缩预检（不建任务） */
+async function handleCompressPreflight(app, request, reply) {
+  const parsed = await parseCompressRequest(app, request.body || {});
+  const preflight = await compressPreflightFor(app, parsed);
+  reply.ok(preflight);
+}
+
+/** POST /compress/tasks —— 创建压缩任务（预检不通过则不建） */
+async function handleCompressTaskCreate(app, request, reply) {
+  const { manager, orchestrator, config } = app.m2;
+  const parsed = await parseCompressRequest(app, request.body || {}, { enforceSourceLimit: true });
+
+  const preflight = await compressPreflightFor(app, parsed);
+  if (!preflight.canProceed) {
+    throw apiError(preflight.blockedReason.code, preflight.blockedReason.message);
+  }
+  if (!(await app.m2.registry.isAvailable(parsed.format))) {
+    throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, `格式 ${parsed.format} 当前不可用`);
+  }
+
+  // 预检已把目录展开成 size/fileCount，直接用于进度分母。
+  // willSkip 的源（整源都被黑名单跳过）不建包 —— 契约：single 模式"跳过文件不生成空压缩包"。
+  const enriched = parsed.sources
+    .map((source, index) => ({
+      ...source,
+      size: preflight.items[index] ? preflight.items[index].size : 0,
+      fileCount: preflight.items[index] ? preflight.items[index].keptFiles : 0,
+      willSkip: Boolean(preflight.items[index] && preflight.items[index].willSkip),
+    }))
+    .filter((source) => !source.willSkip);
+  if (enriched.length === 0) {
+    throw apiError(ERROR_CODES.ALL_SOURCES_SKIPPED, '没有可压缩的文件：全部命中黑名单');
+  }
+
+  const task = await manager.create({
+    kind: 'compress',
+    mode: parsed.mode,
+    format: parsed.format,
+    sources: enriched,
+    options: {
+      level: Number.isInteger(parsed.options.level) ? parsed.options.level : config.compress.defaultLevel,
+      keepOriginal: parsed.options.keepOriginal !== false,
+      deleteConfirmed: parsed.options.deleteConfirmed === true,
+      bundle: parsed.mode === 'bundle',
+      // 黑名单意图随任务落盘：打包阶段要按同一份意图重新解析（用户可能在创建后改过用户层）
+      blacklist: {
+        enabled: !parsed.options.blacklist || parsed.options.blacklist.enabled !== false,
+        extraPatterns: (parsed.options.blacklist && Array.isArray(parsed.options.blacklist.extraPatterns))
+          ? parsed.options.blacklist.extraPatterns
+          : [],
+      },
+      // 能力参数（docs/19 §六）：原样交给编排层，由 capRegistry 校验并装配成 create 选项。
+      // 明文只活到压缩完成；落盘前 store.js 按各能力插件的 redact() 剔除（PW-1）。
+      // 注意：这里必须透传，否则装配循环拿不到参数 → 加密静默不生效。
+      ...(parsed.options.capabilities && typeof parsed.options.capabilities === 'object'
+        ? { capabilities: parsed.options.capabilities }
+        : {}),
+    },
+    // 绝对路径只走 internal（不会出现在 API 响应里）
+    // rootAbs 必须随任务落盘：执行/删除阶段的 INV-06 复核要用**任务自己的根**，不能用服务默认根
+    internal: { outputDirAbs: parsed.outputDirAbs, rootAbs: parsed.rootAbs },
+  });
+
+  manager.enqueue(task.id, (record) => orchestrator.runCompress(record));
+  reply.ok({ task: manager.get(task.id) }, 201);
+}
+
+/** POST /extract/preflight —— 解压预检（归档可读可解析 / 目标可写 / 空间） */
+async function handleExtractPreflight(app, request, reply) {
+  const parsed = await parseExtractRequest(app, request.body || {});
+  const preflight = await extractPreflightFor(app, parsed);
+  // 把"这个归档被识别成哪个格式"显式告诉前端：复合扩展名（x.tar.gz）的识别完全在服务端做，
+  // 对话框据此展示，用户可一眼确认没被更短的 .gz 抢走
+  reply.ok({ ...preflight, format: parsed.plugin.id, formatName: parsed.plugin.name });
+}
+
+/** POST /extract/tasks —— 创建解压任务 */
+async function handleExtractTaskCreate(app, request, reply) {
+  const { manager, orchestrator } = app.m2;
+  const parsed = await parseExtractRequest(app, request.body || {});
+
+  const preflight = await extractPreflightFor(app, parsed);
+  if (!preflight.canProceed) {
+    throw apiError(preflight.blockedReason.code, preflight.blockedReason.message);
+  }
+  if (!(await app.m2.registry.isAvailable(parsed.plugin.id))) {
+    throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, `格式 ${parsed.plugin.id} 当前不可用`);
+  }
+
+  const task = await manager.create({
+    kind: 'extract',
+    mode: 'bundle',
+    format: parsed.plugin.id,
+    sources: [],
+    archivePath: parsed.archive.userPath,
+    targetDir: parsed.target.userPath,
+    // 绝对路径只走 internal（不泄漏到 API 响应）
+    internal: {
+      archiveAbsPath: parsed.archive.realPath,
+      targetAbsDir: parsed.target.absPath,
+      rootAbs: parsed.rootAbs,
+    },
+    options: {
+      deleteArchiveAfterExtract: parsed.options.deleteArchiveAfterExtract === true,
+      deleteConfirmed: parsed.options.deleteConfirmed === true,
+      // P4：加密包解压密码（normalizeOptions 会透传；PW-1 落盘脱敏走 manager 通道）
+      ...(typeof parsed.options.password === 'string' && parsed.options.password.length > 0
+        ? { password: parsed.options.password }
+        : {}),
+    },
+  });
+
+  manager.enqueue(task.id, (record) => orchestrator.runExtract(record));
+  reply.ok({ task: manager.get(task.id) }, 201);
+}
+
+// ===== 路由注册（只做接线；任务类端点统一在 routes/tasks.js）=====
+
+export default async function compressRoutes(app) {
+  const auth = { preHandler: [app.requireAuth] };
+  const bind = (handler) => (request, reply) => handler(app, request, reply);
+
+  app.get('/formats', auth, bind(handleListFormats));
+
+  app.post('/compress/preflight', auth, bind(handleCompressPreflight));
+  app.post('/compress/tasks', auth, bind(handleCompressTaskCreate));
+
+  app.post('/extract/preflight', auth, bind(handleExtractPreflight));
+  app.post('/extract/tasks', auth, bind(handleExtractTaskCreate));
+}
+
+// ===== 参数解析与内部工具（保持路由层"薄"：解析入参 + 调 core）=====
+
+/** 校验并解析压缩请求（sources / format / mode / outputDir） */
+async function parseCompressRequest(app, body, options = {}) {
+  const { config } = app.m2;
+  // 根先定下来：源解析/输出目录/预检都以它为准（未知 rootId → VALIDATION_FAILED）
+  const root = app.fsGuard.root(body.rootId);
+  const rootAbs = root.absPath;
+  const sources = await resolveSources(app, body.sources, rootAbs);
+  const format = String(body.format || config.compress.defaultFormat);
+  const mode = String(body.mode || config.compress.defaultMode);
+
+  if (!COMPRESS_MODES.includes(mode)) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'mode 只能是 single 或 bundle', { mode });
+  }
+  if (options.enforceSourceLimit && sources.length > config.limits.maxSourcesPerTask) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, `一次最多 ${config.limits.maxSourcesPerTask} 个源`, { count: sources.length });
+  }
+
+  const requestedOutputDir = body.options && body.options.outputDir;
+  const outputDirAbs = requestedOutputDir
+    ? (await resolveDirForWrite(app, requestedOutputDir, { allowRoot: true, rootAbs })).absPath
+    : path.dirname(sources[0].absPath);
+
+  return { sources, format, mode, outputDirAbs, rootAbs, rootId: root.id, options: body.options || {} };
+}
+
+/** 校验并解析解压请求（归档 + 目标目录 + 选项） */
+async function parseExtractRequest(app, body) {
+  const root = app.fsGuard.root(body.rootId);
+  const archive = await app.fsGuard.resolveRealIn(root.absPath, body.path);
+  const stat = await fsStat(archive.realPath);
+  if (!stat.isFile()) {
+    throw apiError(ERROR_CODES.NOT_A_DIRECTORY, '解压目标必须是文件', { path: archive.userPath });
+  }
+
+  const plugin = pluginForArchive(app, archive.userPath);
+  const target = body.targetDir
+    ? await resolveDirForWrite(app, body.targetDir, { rootAbs: root.absPath })
+    : await defaultTarget(app, archive.realPath);
+
+  return { archive, plugin, target, rootAbs: root.absPath, rootId: root.id, options: body.options || {} };
+}
+
+/** 未指定目标目录时：用"与压缩包同级的同名目录"（可能尚不存在） */
+async function defaultTarget(app, archiveAbsPath) {
+  const targetAbsDir = await defaultExtractDir(archiveAbsPath);
+  return { userPath: relUserPath(app, targetAbsDir), absPath: targetAbsDir };
+}
+
+/** 把 body.sources（API 路径数组）解析成白名单内的实体 */
+async function resolveSources(app, rawSources, rootAbs) {
+  if (!Array.isArray(rawSources) || rawSources.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'sources 必须是非空数组');
+  }
+  const resolved = [];
+  for (const raw of rawSources) {
+    const { userPath, realPath } = await app.fsGuard.resolveRealIn(rootAbs, raw);
+    resolved.push({
+      path: userPath,
+      userPath,
+      absPath: realPath,
+      name: userPath === '/' ? '/' : path.basename(userPath),
+      kind: (await fsStat(realPath)).isDirectory() ? 'dir' : 'file',
+    });
+  }
+  return resolved;
+}
+
+function fsStat(target) {
+  return fsp.stat(target);
+}
+
+async function compressPreflightFor(app, parsed) {
+  // 黑名单层在这里解析一次：预检与（随后的）打包必须用同一套判定语义
+  const blacklist = parsed.options.blacklist || {};
+  const layers = await app.blacklist.layersFor({
+    enabled: blacklist.enabled !== false,
+    taskPatterns: Array.isArray(blacklist.extraPatterns) ? blacklist.extraPatterns : [],
+  });
+  return compressPreflight(
+    { config: app.m2.config, rootAbs: parsed.rootAbs, blacklistLayers: layers },
+    {
+      sources: parsed.sources,
+      format: parsed.format,
+      mode: parsed.mode,
+      outputDir: parsed.outputDirAbs,
+    },
+  );
+}
+
+async function extractPreflightFor(app, parsed) {
+  const preflight = await extractPreflight(
+    { config: app.m2.config, plugin: parsed.plugin },
+    {
+      archivePath: parsed.archive.userPath,
+      archiveAbsPath: parsed.archive.realPath,
+      targetDir: parsed.target.userPath,
+      targetAbsDir: parsed.target.absPath,
+    },
+  );
+  // 加密包预检：由格式插件自报（ZIP 读 central directory 标志位，RAR 看 unrar 列表输出）。
+  // 不能写死某个格式 —— 任何能解加密包的插件都应让前端弹密码框，
+  // 否则用户会停在「提示要密码、却没有输入框」的死角。
+  if (typeof parsed.plugin.probeEncryption === 'function') {
+    const probe = await parsed.plugin.probeEncryption(parsed.archive.realPath);
+    if (probe.encrypted && !(parsed.options && parsed.options.password)) {
+      preflight.encrypted = true;
+      preflight.isAes = probe.isAes === true;
+    }
+  }
+  return preflight;
+}
+
+/** 归档 → 格式包（按扩展名匹配；匹配不到报 UNSUPPORTED_FORMAT）
+ *  注意：必须传**完整文件名/路径**而不是 path.extname() —— 复合扩展名如 `x.tar.gz` 的
+ *  extname 只有 `.gz`，光看它匹配不到 `targz`（注册表按"整体后缀最长匹配"判定）。
+ */
+function pluginForArchive(app, userPath) {
+  const plugin = app.m2.registry.byExtension(path.basename(userPath));
+  if (!plugin) {
+    throw apiError(ERROR_CODES.UNSUPPORTED_FORMAT, '不支持的压缩包格式', { path: userPath });
+  }
+  return plugin;
+}
+
+/** 绝对路径 → API 用户路径（内部路径不出 API） */
+function relUserPath(app, absPath) {
+  const root = app.fsContext.rootAbs;
+  const relative = path.relative(root, absPath);
+  if (relative === '') return '/';
+  return `/${relative.split(path.sep).join('/')}`;
+}
+
+/**
+ * 解析"写入用的目录"（outputDir / targetDir）：
+ * - 允许目标**尚不存在**（解压目标、新建产物目录都会先给一个不存在的路径）；
+ * - 先用 fsGuard.resolve 做形态 + 白名单前缀校验（不碰磁盘），
+ *   再对**父目录**做 resolveReal（父目录必须存在，借此拦住 symlink 逃逸）。
+ */
+/** 在指定根下做同步形态校验（与 fsGuard.resolve 同规则，只是换了基准） */
+function resolveWithinRootFor(rootAbs, rawUserPath, fsContext) {
+  return resolveWithinRoot(rootAbs, rawUserPath, {
+    maxPathLength: fsContext.maxPathLength,
+    maxPathSegmentLength: fsContext.maxPathSegmentLength,
+  });
+}
+
+async function resolveDirForWrite(app, rawUserPath, options = {}) {
+  // 多根：输出目录也必须在**本次请求的根**下解析（否则任务会把产物写到另一个根里）
+  const rootAbs = options.rootAbs || app.fsContext.rootAbs;
+  const { userPath } = resolveWithinRootFor(rootAbs, rawUserPath, app.fsContext);
+  if (userPath === '/') {
+    if (options.allowRoot) return { userPath: '/', absPath: rootAbs };
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'targetDir 不能是存储根目录', { path: userPath });
+  }
+  const parentUserPath = path.posix.dirname(userPath);
+  const parent = await app.fsGuard.resolveRealIn(rootAbs, parentUserPath);
+  const absPath = path.join(parent.realPath, path.posix.basename(userPath));
+  if (!absPath.startsWith(parent.realPath + path.sep)) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '目录超出可访问范围', { path: userPath });
+  }
+  return { userPath, absPath };
+}

package/server/http/routes/fs.js

@@ -0,0 +1,109 @@
+// 文件浏览路由（M1：docs/M0/API规范.md §4.2 的 fs/list 与 fs/stat）
+//
+// 安全约定：所有涉及路径的端点都挂 `app.guardPath()`（中间件层白名单）+
+// 业务层（core/fs/*）再次校验 —— defense in depth。
+//
+// 响应字段严格照契约：list → {path,parent,entries,total,truncated,...}；
+// stat → 单条目对象。**不出现在响应里的绝对路径**（进程内部字段不返回）。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { listDirectory } from '../../core/fs/list.js';
+import { listRoots } from '../../core/fs/roots.js';
+import { searchFiles } from '../../core/fs/search.js';
+import { deleteEntries, makeDirectory, moveEntries, renameEntry } from '../../core/fs/writeOps.js';
+import { repairNamesInDirectory } from '../../core/fs/repairNames.js';
+import { statEntry } from '../../core/fs/stat.js';
+
+/** 查询串里的数字参数解析（非法值→undefined，由 core 用默认值） */
+function toInt(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isInteger(parsed) ? parsed : undefined;
+}
+
+function toBool(value) {
+  if (value === true || value === 'true' || value === '1') return true;
+  if (value === false || value === 'false' || value === '0') return false;
+  return undefined;
+}
+
+export default async function fsRoutes(app) {
+  /**
+   * 存储根列表（docs/16 §三.2）：平台 + 模式 + 根列表 + 容量。
+   * 两种数据源（卷 / 共享）由 roots.js 按平台决定；statfs 失败只让容量为 null，不报错。
+   */
+  app.get('/fs/volumes', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const storage = app.m2.config.storage;
+    const rootsPayload = await listRoots({ storage, env: process.env });
+    // 回写缓存：新增/删除共享后，带 rootId 的请求不必等重启就能用
+    if (typeof app.refreshRoots === 'function') app.refreshRoots(rootsPayload);
+    // 配置里显式给了 roots 时，把它们的 label 一并带上（自动发现的 label 已在 roots.js 里定好）
+    reply.ok(rootsPayload);
+  });
+
+  app.get('/fs/list', { preHandler: [app.requireAuth, app.guardPath({ source: 'query' })] }, async (request, reply) => {
+    const query = request.query || {};
+    // 黑名单层（用户层有缓存，逐请求解析成本可忽略）；契约 §4.2 的 blacklisted/blacklistLayer 由服务端算
+    const blacklistLayers = await app.blacklist.layersFor({ enabled: true, taskPatterns: [] });
+    const listing = await listDirectory(app.requestContext(request), {
+      blacklistLayers,
+      // 用中间件已校验过的 userPath 再走一遍 core（core 内部仍会完整校验）
+      path: request.userPath,
+      sort: query.sort,
+      order: query.order,
+      showHidden: toBool(query.showHidden),
+      limit: toInt(query.limit),
+      offset: toInt(query.offset),
+    });
+    reply.ok(listing);
+  });
+
+  // ===== 写操作（M8 右键菜单/快捷键/拖拽的后端支撑，形状照 API 规范 §4.2）=====
+  // 路径校验在这里**不做 preHandler**：四个端点都可能是"源 + 目标"或数组路径，
+  // 统一交给 core/fs/writeOps 逐条走 safePath（含符号链接复核），避免半套校验。
+  app.post('/fs/mkdir', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await makeDirectory(app.requestContext(request), request.body || {}));
+  });
+
+  app.post('/fs/rename', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await renameEntry(app.requestContext(request), request.body || {}));
+  });
+
+  app.post('/fs/move', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await moveEntries(app.requestContext(request), request.body || {}));
+  });
+
+  // 批量修复乱码文件名（U+FFFE + 私有区字节转义 → 原名）。dryRun 默认 true，不显式传 false 只出清单。
+  app.post('/fs/repair-names', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await repairNamesInDirectory(app.requestContext(request), request.body || {}));
+  });
+  app.post('/fs/delete', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await deleteEntries(app.requestContext(request), request.body || {}, {
+      // 与 M5 删除原文件同一机制：进回收站（delete.mode 决定是 trash 还是 log-only 记账）
+      deleter: app.m2.deleteService,
+      maxDeleteItems: app.fsContext.maxDeleteItems,
+      // 删除任务的 INV-06 复核基准跟随本次请求的根（多根下不能用全局默认根）
+      rootAbs: app.requestContext(request).rootAbs,
+    }));
+  });
+
+  /**
+   * 文件名搜索（有界遍历：深度 6 / 结果 500 / 3s）：只在当前根内、不跟随符号链接、跳过黑名单目录。
+   * 未给 q 或为空 → 400（前端"未输入不请求"）。
+   */
+  app.get('/fs/search', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const context = app.requestContext(request);
+    const layers = await app.blacklist.layersFor({ enabled: true, taskPatterns: [] });
+    const searchPayload = await searchFiles(context, request.query.q, { limit: request.query.limit, layers });
+    reply.ok(searchPayload);
+  });
+
+  app.get('/fs/stat', { preHandler: [app.requireAuth, app.guardPath({ source: 'query' })] }, async (request, reply) => {
+    if (request.userPath === undefined) {
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必填');
+    }
+    const blacklistLayers = await app.blacklist.layersFor({ enabled: true, taskPatterns: [] });
+    const entry = await statEntry(app.requestContext(request), request.userPath, { blacklistLayers });
+    reply.ok(entry);
+  });
+}

package/server/http/routes/hardlink.js

@@ -0,0 +1,160 @@
+// 硬链接去重端点（docs/15 §三）
+//
+// - POST /hardlink/scan     扫描重复分组（**默认 dry-run，不动任何文件**——本端点本身永不改文件）
+//   请求：{ path: string, extensions?: string[] }
+//   响应：data.groups[] = { size, hash, master, duplicates[], savedBytes } + data.stats
+//   路径全部走 fsGuard.resolveReal（INV-06 白名单 + 符号链接复核）；响应里只出 userPath。
+//
+// - POST /hardlink/execute  批次②实现（执行替换，需显式 confirmed）——本文件先放参数守卫与
+//   409 占位，避免批次①就开执行面。
+//
+// 风险纪律（docs/15 §四）：风险与 M5 同级 → 扫描只读、扩展名白名单、日志（批次②）。
+
+import path from 'node:path';
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { executeHardlinkGroups } from '../../core/hardlink/executor.js';
+import { scanHardlinkDuplicates } from '../../core/hardlink/scanner.js';
+
+/** 扩展名默认白名单（docs/15 §三.前端：mp4/mkv/avi/mov/iso/zip/7z） */
+const DEFAULT_EXTENSIONS = ['mp4', 'mkv', 'avi', 'mov', 'iso', 'zip', '7z'];
+/** 扩展名条目上限（防异常请求撑爆配置面） */
+const MAX_EXTENSIONS = 64;
+
+/** 解析并归一化扩展名白名单（小写、去点、去空、限数） */
+function normalizeExtensions(raw) {
+  if (raw === undefined || raw === null) return DEFAULT_EXTENSIONS;
+  if (!Array.isArray(raw)) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'extensions 必须是字符串数组', { got: typeof raw });
+  }
+  const cleaned = [...new Set(raw
+    .filter((item) => typeof item === 'string')
+    .map((item) => item.trim().replace(/^\./, '').toLowerCase())
+    .filter(Boolean))];
+  if (cleaned.length === 0 || cleaned.length > MAX_EXTENSIONS) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, `extensions 需要 1~${MAX_EXTENSIONS} 个有效条目`, { got: cleaned.length });
+  }
+  return cleaned;
+}
+
+/**
+ * 在当前请求所属存储根内解析路径（docs/16 多根：与 fs 路由同源，用 app.requestContext）。
+ * 错误文案要能区分两种"扫不了"：
+ * - PATH_NOT_FOUND：当前根里没有这个目录（可能是手填错了）
+ * - PATH_OUT_OF_ROOT：路径不在当前根内（例如没切根就去扫别的共享）→ 提示先切根
+ */
+async function resolveInRoot(app, context, rawPath) {
+  try {
+    return await app.fsGuard.resolveRealIn(context.rootAbs, rawPath);
+  } catch (error) {
+    if (error && error.code === ERROR_CODES.PATH_NOT_FOUND) {
+      throw apiError(ERROR_CODES.PATH_NOT_FOUND, '该目录在当前存储根内不存在', { path: rawPath, rootId: context.rootId });
+    }
+    if (error && error.code === ERROR_CODES.PATH_OUT_OF_ROOT) {
+      throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '不在当前根内，请先从左侧切换存储位置', { path: rawPath, rootId: context.rootId });
+    }
+    throw error;
+  }
+}
+
+export default async function hardlinkRoutes(app) {
+  /**
+   * 扫描重复分组（只读；永不改文件）。
+   * docs/15：默认 dry-run 语义 = 本端点天然只读；「执行」是独立端点（批次②）且需显式确认。
+   */
+  app.post('/hardlink/scan', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const body = request.body || {};
+    if (typeof body.path !== 'string' || body.path.length === 0) {
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必须是非空字符串');
+    }
+    const extensions = normalizeExtensions(body.extensions);
+    // 白名单 + 符号链接复核（INV-06，与 fs 路由同源），基准是**本请求的存储根**
+    const context = app.requestContext(request);
+    const resolved = await resolveInRoot(app, context, body.path);
+    const scanPayload = await scanHardlinkDuplicates(resolved.absPath, extensions);
+
+    // 响应路径统一转 userPath（绝对路径绝不进 API，INV-06 红线）
+    const rootPrefix = resolved.absPath;
+    const toUser = (absPath) => {
+      const relative = path.posix.relative(rootPrefix.replaceAll(path.sep, '/'), absPath.replaceAll(path.sep, '/'));
+      const base = resolved.userPath === '/' ? '' : resolved.userPath.replace(/\/$/, '');
+      return `${base}/${relative}`;
+    };
+    const groups = scanPayload.groups.map((group) => ({
+      ...group,
+      master: toUser(group.master),
+      duplicates: group.duplicates.map(toUser),
+    }));
+
+    reply.ok({
+      path: resolved.userPath,
+      extensions,
+      groups,
+      stats: scanPayload.stats,
+    });
+  });
+
+  /**
+   * 执行替换（批次②）：对 scan 产出的分组执行 rename→link→unlink 三步替换。
+   * 请求：{ path, extensions?, groups: [{size, hash, master, duplicates[]}]（userPath 坐标系，必须来自 scan 响应）, confirmed: true }
+   * 守卫链：confirmed 显式 true → 组路径逐一过白名单并限定在扫描根下 → 服务端重新全量哈希复核
+   * （不信任客户端判定，扫描到执行之间文件可能变化；不一致整组跳过）→ 三步替换
+   * （EXDEV/EEXIST/EPERM/ENOSPC 单条隔离，失败回滚 rename）。每条落 hardlink-*.jsonl。
+   */
+  app.post('/hardlink/execute', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const body = request.body || {};
+    if (body.confirmed !== true) {
+      throw apiError(ERROR_CODES.INVALID_STATE, '执行需要显式确认（confirmed=true）；先跑 scan 看预览');
+    }
+    if (typeof body.path !== 'string' || body.path.length === 0) {
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, 'path 必须是非空字符串');
+    }
+    if (!Array.isArray(body.groups) || body.groups.length === 0) {
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, 'groups 必须是非空数组（来自 scan 响应）');
+    }
+    const extensions = normalizeExtensions(body.extensions);
+    const context = app.requestContext(request);
+    const resolved = await resolveInRoot(app, context, body.path);
+
+    // 组路径白名单复核（INV-06：执行面是写路径，比 scan 更严——逐个 resolveReal 并限定在扫描根下）
+    const resolveGroup = async (group) => {
+      if (!group || typeof group.master !== 'string' || !Array.isArray(group.duplicates) || group.duplicates.length === 0) {
+        throw apiError(ERROR_CODES.VALIDATION_FAILED, 'groups 每项需要 master 与非空 duplicates');
+      }
+      const toAbs = async (userPath) => {
+        const resolvedEntry = await resolveInRoot(app, context, userPath);
+        const rel = path.relative(resolved.absPath, resolvedEntry.absPath);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+          throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '分组路径不在扫描根下', { userPath });
+        }
+        return resolvedEntry.absPath;
+      };
+      return {
+        size: Number(group.size) || 0,
+        master: await toAbs(group.master),
+        duplicates: await Promise.all(group.duplicates.map(toAbs)),
+      };
+    };
+    const resolvedGroups = await Promise.all(body.groups.map(resolveGroup));
+
+    const executeOutcome = await executeHardlinkGroups(
+      { logDir: app.hardlinkLogDir, logger: app.appLogger },
+      resolvedGroups,
+      { confirmed: true },
+    );
+
+    // 响应路径转回 userPath（内部 absPath 绝不进 API）
+    const toUser = (absPath) => {
+      const rel = path.relative(resolved.absPath, absPath).split(path.sep).join('/');
+      const base = resolved.userPath === '/' ? '' : resolved.userPath.replace(/\/$/, '');
+      return `${base}/${rel}`;
+    };
+    reply.ok({
+      executed: executeOutcome.executed,
+      savedBytes: executeOutcome.savedBytes,
+      failed: executeOutcome.failed.map((item) => ({ duplicate: toUser(item.duplicate), code: item.code })),
+      skippedGroups: executeOutcome.skippedGroups.map((item) => ({ master: toUser(item.master), reason: item.reason })),
+    });
+  });
+}
+

package/server/http/routes/health.js

@@ -0,0 +1,52 @@
+// 健康检查（docs/M0/API规范.md §4.6 的 M1 子集）
+//
+// 用途：启停脚本的 status 判定、前端"服务是否在线"探测。
+// 安全：**不返回存储根的绝对路径**（避免把本机目录结构暴露给任何能访问端口的客户端），
+// 只返回"是否已配置/可写"这类布尔与统计值。
+
+import os from 'node:os';
+
+/** 取服务进程的**实际**运行身份（决定它能读哪些文件；拿不到用户名就只给 uid） */
+function runtimeIdentity() {
+  let uid = null;
+  let user = null;
+  try {
+    uid = typeof process.getuid === 'function' ? process.getuid() : null;
+  } catch {
+    uid = null;
+  }
+  try {
+    user = os.userInfo().username || null;
+  } catch {
+    user = null;
+  }
+  return { uid, user };
+}
+
+export default async function healthRoutes(app, options) {
+  const { meta } = options;
+
+  app.get('/health', async (request, reply) => {
+    const authStats = app.authStore ? app.authStore.stats() : { sessions: 0, tokens: 0 };
+    const taskStats = app.tasks ? app.tasks.manager.stats() : { total: 0, active: null, waiting: 0, subscribers: 0, seq: 0 };
+    reply.ok({
+      version: meta.version,
+      startedAt: meta.startedAt,
+      uptimeMs: Date.now() - meta.startedAt,
+      bootId: app.tasks ? app.tasks.manager.bootId : meta.bootId,
+      auth: { sessions: authStats.sessions, tokens: authStats.tokens },
+      storage: { configured: true, readable: true, writable: meta.rootWritable === true },
+      tasks: {
+        total: taskStats.total,
+        active: taskStats.active,
+        waiting: taskStats.waiting,
+        subscribers: taskStats.subscribers,
+        seq: taskStats.seq,
+      },
+      // 运行身份：权限提示要能说清"服务以谁的身份在访问文件"，不能写死（套件代启 vs 用户手动启不同）
+      runtime: runtimeIdentity(),
+      // M2 已实现压缩/解压；M3 补齐任务系统；指标看板在 M7
+      features: { fs: true, auth: true, compress: true, tasks: true, metrics: true },
+    });
+  });
+}