zipcalm 0.0.0-stage → 1.0.2

package/server/http/middleware/pathGuard.js

@@ -0,0 +1,119 @@
+// 路径白名单中间件（M1 安全红线，INV-06）
+//
+// 这一层做两件事：
+// 1. 把存储根与限制参数固化成 `app.fsContext`，全局只有一份（避免每个路由各自读配置）；
+// 2. 提供 preHandler 工厂 `app.guardPath`：**在进入业务逻辑之前**先做形态校验 + 白名单解析，
+//    把结果挂到 request.userPath / request.absPath。业务层（core/fs/*）还会再校验一次，
+//    这是刻意的 defense in depth：中间件被绕过也还有兜底。
+//
+// 真正的算法在 server/core/fs/safePath.js（拆段拒绝 .. + 带分隔符的前缀校验 + realpath 二次校验）。
+
+import { resolveRequestPath, resolveWithinRoot } from '../../core/fs/safePath.js';
+import { DEFAULT_ROOT_ID, listRoots, resolveRoot } from '../../core/fs/roots.js';
+
+/** 请求里的 rootId（query 优先、body 兜底）；空串视作未指定 */
+function requestedRootIdOf(request) {
+  const fromQuery = request.query && request.query.rootId;
+  const fromBody = request.body && request.body.rootId;
+  const preferred = typeof fromQuery === 'string' && fromQuery.length > 0 ? fromQuery : fromBody;
+  return typeof preferred === 'string' && preferred.length > 0 ? preferred : undefined;
+}
+
+export async function registerPathGuard(app, { config, logger }) {
+  const fsContext = {
+    rootAbs: config.storage.root,
+    /** 可切换的根（docs/16）：id/label/path 都是绝对路径；空数组=自动发现（由 /fs/volumes 现扫） */
+    roots: Array.isArray(config.storage.roots) ? config.storage.roots : [],
+    defaultRootId: DEFAULT_ROOT_ID,
+    maxPathLength: config.limits.maxPathLength,
+    maxPathSegmentLength: config.limits.maxPathSegmentLength,
+    maxListEntries: config.limits.maxListEntries,
+    defaultPageSize: config.limits.defaultPageSize,
+    maxMoveItems: config.limits.maxMoveItems,
+    maxDeleteItems: config.limits.maxDeleteItems,
+  };
+
+  // 启动时发现一次根（群晖共享 / 卷），让带 rootId 的请求**无需先调 /fs/volumes** 就能用；
+  // 之后 /fs/volumes 每次应答会用最新结果回写这里（加共享不用重启）。
+  const discovered = await listRoots({ storage: config.storage, env: process.env });
+  fsContext.platform = discovered.platform;
+  fsContext.mode = discovered.mode;
+  fsContext.roots = discovered.roots;
+
+  /** 用最新发现结果刷新缓存（/fs/volumes 调用后执行） */
+  app.decorate('refreshRoots', (fresh) => {
+    if (!fresh || !Array.isArray(fresh.roots)) return;
+    fsContext.platform = fresh.platform;
+    fsContext.mode = fresh.mode;
+    fsContext.roots = fresh.roots;
+  });
+
+  app.decorate('fsContext', fsContext);
+
+  /**
+   * 取（或生成）本请求的上下文：按 rootId 切基准，返回 { ...fsContext, rootAbs }。
+   * 有 `guardPath` 的路由已经生成过；写操作类路由（没走 guardPath）用它自己生成 ——
+   * 关键点：**每个请求一份副本**，绝不像改全局 rootAbs 那样让并发请求互相污染。
+   */
+  app.decorate('requestContext', function requestContext(request) {
+    if (request.fsContext) return request.fsContext;
+    const root = resolveRoot(fsContext, requestedRootIdOf(request));
+    request.rootId = root.id;
+    request.rootAbs = root.absPath;
+    request.fsContext = { ...fsContext, rootAbs: root.absPath };
+    return request.fsContext;
+  });
+  app.decorate('fsGuard', {
+    /** 同步形态校验（不碰磁盘） */
+    resolve(raw) {
+      return resolveWithinRoot(fsContext.rootAbs, raw, { maxPathLength: fsContext.maxPathLength });
+    },
+    /** 含符号链接二次校验（会访问磁盘） */
+    async resolveReal(raw) {
+      return resolveRequestPath(fsContext, raw);
+    },
+    /** 在**指定根**下解析（多根：压缩任务用自己的根，与默认根无关） */
+    async resolveRealIn(rootAbs, raw) {
+      return resolveRequestPath({ ...fsContext, rootAbs }, raw);
+    },
+    /** 按 rootId 取根（未知 id 抛 VALIDATION_FAILED，不静默回落） */
+    root(rootId) {
+      return resolveRoot(fsContext, rootId);
+    },
+  });
+
+  /**
+   * 生成受保护路由的 preHandler。
+   * @param {{source?: 'query'|'body', required?: boolean, key?: string}} options
+   */
+  app.decorate('guardPath', function guardPath(options = {}) {
+    const source = options.source || 'query';
+    const key = options.key || 'path';
+    const required = options.required !== false;
+
+    return async function pathGuardPreHandler(request) {
+      // 根先定下来：后面的白名单解析全部以它为基准
+      const root = resolveRoot(fsContext, requestedRootIdOf(request));
+      const requestContext = { ...fsContext, rootAbs: root.absPath };
+      request.rootId = root.id;
+      request.rootAbs = root.absPath;
+      request.fsContext = requestContext;
+
+      const container = source === 'body' ? request.body : request.query;
+      const raw = container ? container[key] : undefined;
+
+      if (raw === undefined || raw === null || raw === '') {
+        if (!required) return;
+        // 缺省视为存储根（API 规范：根为 /）
+      }
+
+      const target = raw === undefined || raw === null || raw === '' ? '/' : raw;
+      const { userPath, absPath, realPath } = await resolveRequestPath(requestContext, target);
+
+      request.userPath = userPath;
+      request.absPath = absPath;
+      request.realPath = realPath;
+      logger.debug('path guard resolved', { userPath, requestId: request.requestId });
+    };
+  });
+}

package/server/http/router.js

@@ -0,0 +1,29 @@
+// 路由注册表（docs/12 §二：http/router.js 只做装配，不写业务）
+//
+// 所有业务路由统一挂在 /api/v1 前缀下（契约 §一：API 版本化）。
+
+import authRoutes from './routes/auth.js';
+import blacklistRoutes from './routes/blacklist.js';
+import capabilityRoutes from './routes/capabilities.js';
+import compressRoutes from './routes/compress.js';
+import fsRoutes from './routes/fs.js';
+import hardlinkRoutes from './routes/hardlink.js';
+import healthRoutes from './routes/health.js';
+import metricsRoutes from './routes/metrics.js';
+import taskRoutes from './routes/tasks.js';
+
+export default async function router(app, options) {
+  const { config, logger, store, meta, verifyPassword } = options;
+
+  app.decorate('appLogger', logger);
+
+  await app.register(authRoutes, { config: config.auth, store, verifyPassword });
+  await app.register(fsRoutes, {});
+  await app.register(compressRoutes, {});
+  await app.register(blacklistRoutes, {});
+  await app.register(capabilityRoutes, {});
+  await app.register(hardlinkRoutes, {});
+  await app.register(metricsRoutes, {});
+  await app.register(taskRoutes, {});
+  await app.register(healthRoutes, { meta });
+}

package/server/http/routes/auth.js

@@ -0,0 +1,115 @@
+// 认证路由（docs/M0/API规范.md §4.1）
+//
+// 端点：login / logout / me / token/refresh
+// 要点：
+// - 登录一次同时下发 Session Cookie 与 Bearer Token（契约 §二）；
+// - 密码只比对哈希（scrypt），明文永不落盘、不入日志；
+// - 失败限流用内存计数（配置 auth.loginRateLimit）。
+//
+// 结构：每个端点的处理是模块级函数（接收 ctx），工厂只做路由注册 —— 这样单个函数短、可单测。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 请求体统一取成对象（Fastify 在无 body 时给 undefined） */
+function bodyOf(request) {
+  return request.body && typeof request.body === 'object' ? request.body : {};
+}
+
+/** 从 Authorization 头里取出 Bearer token 原文（没有则空串） */
+function bearerTokenOf(request) {
+  const header = request.headers.authorization || '';
+  return header.replace(/^Bearer\s+/i, '').trim();
+}
+
+/** POST /auth/login：校验 → 限流 → 比对 → 下发 session + token */
+async function handleLogin(ctx, request, reply) {
+  const { username, password } = bodyOf(request);
+
+  if (typeof username !== 'string' || username.length === 0 || typeof password !== 'string' || password.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'username 与 password 必填', { fields: ['username', 'password'] });
+  }
+
+  const ip = request.ip || 'unknown';
+  if (ctx.store.isLoginBlocked(ip, ctx.config.loginRateLimit)) {
+    throw apiError(ERROR_CODES.RATE_LIMITED, '登录失败次数过多，请稍后再试');
+  }
+
+  const usernameMatches = username === ctx.config.username;
+  const passwordMatches = await ctx.verifyPassword(password);
+
+  if (!usernameMatches || !passwordMatches) {
+    ctx.store.recordLoginFailure(ip, ctx.config.loginRateLimit);
+    // 不区分"用户名错"与"密码错"（避免账号枚举）
+    throw apiError(ERROR_CODES.AUTH_INVALID, '用户名或密码错误');
+  }
+
+  ctx.store.clearLoginFailures(ip);
+
+  const session = ctx.store.createSession(username);
+  const token = ctx.store.createToken(username);
+  ctx.app.setSessionCookie(reply, session.sid, ctx.store.sessionTtlMs);
+
+  ctx.app.appLogger.info('login succeeded', { requestId: request.requestId, user: username, authType: 'session+bearer' });
+
+  reply.ok({
+    user: { name: username },
+    token: token.token,
+    tokenExpiresAt: token.expiresAt,
+    sessionExpiresAt: session.expiresAt,
+  });
+}
+
+/** POST /auth/logout：撤销当前会话（与 Bearer token），可选全设备下线；幂等 */
+async function handleLogout(ctx, request, reply) {
+  const body = bodyOf(request);
+
+  if (request.sessionId) ctx.store.revokeSession(request.sessionId);
+  if (request.auth && request.auth.type === 'bearer') {
+    ctx.store.revokeToken(bearerTokenOf(request));
+  }
+
+  let revokedTokens = 0;
+  if (body.allDevices === true) {
+    revokedTokens = ctx.store.revokeAllTokens ? ctx.store.revokeAllTokens() : 0;
+  }
+
+  ctx.app.clearSessionCookie(reply);
+  // 幂等：未登录调用也返回成功（API 规范 §4.1）
+  reply.ok({ loggedOut: true, revokedTokens });
+}
+
+/** GET /auth/me：回显当前身份与过期时间 */
+async function handleMe(request, reply) {
+  reply.ok({
+    user: { name: request.auth.user },
+    authType: request.auth.type,
+    expiresAt: request.auth.expiresAt,
+  });
+}
+
+/** POST /auth/token/refresh：默认轮换（旧 token 立即失效） */
+async function handleTokenRefresh(ctx, request, reply) {
+  const body = bodyOf(request);
+  const rotate = body.rotate !== false;
+
+  if (rotate && request.auth.type === 'bearer') {
+    ctx.store.revokeToken(bearerTokenOf(request));
+  }
+
+  const token = ctx.store.createToken(request.auth.user);
+  reply.ok({ token: token.token, tokenExpiresAt: token.expiresAt });
+}
+
+export default async function authRoutes(app, options) {
+  const ctx = {
+    app,
+    config: options.config,
+    store: options.store,
+    verifyPassword: options.verifyPassword,
+  };
+
+  app.post('/auth/login', (request, reply) => handleLogin(ctx, request, reply));
+  app.post('/auth/logout', (request, reply) => handleLogout(ctx, request, reply));
+  app.get('/auth/me', { preHandler: [app.requireAuth] }, (request, reply) => handleMe(request, reply));
+  app.post('/auth/token/refresh', { preHandler: [app.requireAuth] }, (request, reply) => handleTokenRefresh(ctx, request, reply));
+}

package/server/http/routes/blacklist.js

@@ -0,0 +1,97 @@
+// 黑名单端点（docs/M0/API规范.md §4.5，形状严格照契约，不自创字段）
+//
+// - GET  /blacklist            三层读取（global / user / effectiveCount）
+// - PUT  /blacklist/user       用户层全量替换（幂等；校验单条 ≤128、总数 ≤200、拒绝对路径与 /）
+// - POST /blacklist/preview    { paths[], extraPatterns[] } → data.skipped[{path,pattern,layer}] + data.kept[]
+//
+// 三个端点都需要登录（黑名单属于用户设置）；匹配与判定全在服务端（docs/09 §五）。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { matchEntry } from '../../core/compress/blacklist.js';
+import { collectFilesUnder } from '../../core/compress/sourceWalk.js';
+
+/**
+ * 单个源的预览：返回该源命中的文件与"是否还有可压的文件"。
+ * 抽出来是为了让路由本体只做"解析参数 → 逐个源调用 → 拼响应"（单函数不超 50 行）。
+ */
+async function previewOneSource(app, rawPath, layers, rootAbs) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'paths 里每一项都必须是非空字符串');
+  }
+  const resolved = await app.fsGuard.resolveRealIn(rootAbs, rawPath);
+  const files = await collectFilesUnder(resolved.absPath);
+  const skipped = [];
+  let keptFiles = 0;
+  for (const file of files) {
+    const hit = matchEntry(layers, { name: file.name, segments: file.segments });
+    if (hit) skipped.push({ path: joinUserPath(resolved.userPath, file.relative), pattern: hit.pattern, layer: hit.layer });
+    else keptFiles += 1;
+  }
+  return { skipped, keptFiles, userPath: resolved.userPath, fileCount: files.length };
+}
+
+/**
+ * 预览多源：解析参数 → 逐个源判定 → 汇总 skipped/kept。
+ * 放在模块作用域（而非路由闭包里）是为了让路由表只做挂载，也让两段逻辑各自可读、可单测。
+ */
+async function previewManySources(app, body) {
+  const rawPaths = body.paths;
+  if (!Array.isArray(rawPaths) || rawPaths.length === 0) {
+    throw apiError(ERROR_CODES.VALIDATION_FAILED, 'paths 必须是非空字符串数组');
+  }
+
+  const taskPatterns = Array.isArray(body.extraPatterns) ? body.extraPatterns : [];
+  const layers = await app.blacklist.layersFor({ enabled: true, taskPatterns });
+  // 根：与 fs 路由同一套语义（未知 rootId → VALIDATION_FAILED）
+  const root = app.fsGuard.root(body.rootId);
+  const skipped = [];
+  const kept = [];
+
+  for (const rawPath of rawPaths) {
+    const one = await previewOneSource(app, rawPath, layers, root.absPath);
+    skipped.push(...one.skipped);
+    // 空目录/不可读：不算"跳过"，如实放进 kept（真正原因由压缩预检去报）；
+    // 有文件留下也算 kept；整源都被跳过时不放进 kept（前端据此提示"该目录没有可压缩文件"）
+    if (one.fileCount === 0 || one.keptFiles > 0) kept.push(one.userPath);
+  }
+
+  return { skipped, kept };
+}
+
+export default async function blacklistRoutes(app) {
+  /** 三层读取：global 恒 locked（不可改/不可删），user 来自 storage/blacklist-user.json */
+  app.get('/blacklist', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await app.blacklist.snapshot());
+  });
+
+  /** 用户层全量替换（幂等）：契约 §4.5 的校验规则由 blacklist.validatePatterns 统一实现 */
+  app.put('/blacklist/user', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const body = request.body || {};
+    if (!Array.isArray(body.patterns)) {
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, 'patterns 必须是字符串数组');
+    }
+    try {
+      const user = await app.blacklist.replaceUser({ patterns: body.patterns, enabled: body.enabled !== false });
+      reply.ok({ user });
+    } catch (error) {
+      // validatePatterns 抛的是带 validation 标记的普通 Error：翻译成契约错误码
+      throw apiError(ERROR_CODES.VALIDATION_FAILED, error.message);
+    }
+  });
+
+  /**
+   * 命中预览：压缩设置抽屉用它显示「X 个文件已跳过（已压缩格式）」。
+   * 契约：data.skipped[] = { path, pattern, layer }（**userPath**，绝不带 absPath）；data.kept[] 只给路径。
+   * 路径校验逐个走 fsGuard.resolveReal（与 fs 路由同一套白名单 + 符号链接复核）。
+   */
+  app.post('/blacklist/preview', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    reply.ok(await previewManySources(app, request.body || {}));
+  });
+}
+
+/** 用户路径拼接（POSIX 风格，避免 path.join 在 Windows 上换成反斜杠） */
+function joinUserPath(base, relative) {
+  if (!relative) return base;
+  const prefix = base === '/' ? '' : base.replace(/\/$/, '');
+  return `${prefix}/${relative}`;
+}

package/server/http/routes/capabilities.js

@@ -0,0 +1,21 @@
+// 能力元数据端点（docs/19 §三：前端不硬编码能力列表，运行时从 API 拉取）
+//
+// GET /capabilities/:id —— 返回能力元数据（name/appliesTo/methods 含 caveat），
+// 绝不包含任何密码值（PW-1）。id 必须在已知能力白名单内（shared/capabilities.js）。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import { CAPABILITY_IDS } from '../../../shared/capabilities.js';
+
+export default async function capabilityRoutes(app) {
+  app.get('/capabilities/:id', { preHandler: [app.requireAuth] }, async (request, reply) => {
+    const { id } = request.params;
+    if (!CAPABILITY_IDS.includes(id)) {
+      throw apiError(ERROR_CODES.PATH_NOT_FOUND, `未知能力：${String(id)}`);
+    }
+    const cap = app.m2.capRegistry && app.m2.capRegistry.get(id);
+    if (!cap || typeof cap.describe !== 'function') {
+      throw apiError(ERROR_CODES.PATH_NOT_FOUND, `能力 ${id} 未加载`);
+    }
+    reply.ok(cap.describe());
+  });
+}