zipcalm 0.0.0-stage → 1.0.2

package/server/config/index.js

@@ -0,0 +1,140 @@
+// 配置加载与校验（结构照 docs/M0/数据模型.md §八）
+//
+// 优先级（低 → 高）：
+//   1. server/config/defaults.js 内置默认值
+//   2. <项目根>/config.json          （可选，用于引导 dataDir 等）
+//   3. <dataDir>/config.json         （运行期覆盖项；storage/ 已 gitignore，凭据不进库）
+//   4. 环境变量白名单（ZIPCALM_*，只允许单值型部署差异）
+//
+// 为什么运行期配置放 <dataDir>/config.json：那里已被 .gitignore 忽略，
+// 密码哈希/端口这类部署差异不会误提交（INV-16 凭据不入库）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { DEFAULT_CONFIG, ENV_OVERRIDES } from './defaults.js';
+import { validateConfig } from './schema.js';
+import { checkAccess, ensureDir, readJson } from '../lib/atomic-json.js';
+
+/** 可深合并的普通对象（数组/标量/null 都不算） */
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 深合并（只合并普通对象；数组/标量直接覆盖） */
+function deepMerge(base, patch) {
+  if (!isPlainObject(patch)) return base;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    out[key] = isPlainObject(value) && isPlainObject(out[key]) ? deepMerge(out[key], value) : value;
+  }
+  return out;
+}
+
+/** 按 ENV_OVERRIDES 把环境变量写进配置（数字型字段做类型转换，非法值记 warning 并忽略） */
+function applyEnv(config, env) {
+  const applied = [];
+  const warnings = [];
+  for (const [envKey, configPath] of Object.entries(ENV_OVERRIDES)) {
+    const raw = env[envKey];
+    if (raw === undefined || raw === '') continue;
+    const [section, field] = configPath;
+    let resolvedValue = raw;
+    if (field === 'port') {
+      const parsed = Number.parseInt(raw, 10);
+      if (!Number.isInteger(parsed)) {
+        warnings.push(`环境变量 ${envKey} 不是整数，已忽略`);
+        continue;
+      }
+      resolvedValue = parsed;
+    }
+    config[section][field] = resolvedValue;
+    applied.push(`${envKey} → ${configPath.join('.')}`);
+  }
+  return { applied, warnings };
+}
+
+/**
+ * 加载并校验配置。
+ * @param {{projectRoot?: string, env?: Record<string,string>}} options
+ * @returns {Promise<{config: object, projectRoot: string, warnings: string[], sources: string[]}>}
+ */
+export async function loadConfig(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const env = options.env || process.env;
+  const warnings = [];
+  const sources = [];
+
+  // 1) 内置默认值
+  let config = deepMerge({}, DEFAULT_CONFIG);
+
+  // 2) 项目根 config.json（可选引导文件）
+  const rootConfigPath = path.join(projectRoot, 'config.json');
+  const rootConfig = await readJson(rootConfigPath, null);
+  if (rootConfig.ok && rootConfig.data) {
+    config = deepMerge(config, rootConfig.data);
+    sources.push('config.json');
+  }
+
+  // 3) <dataDir>/config.json（dataDir 可能被上面引导文件改过，所以放在后面读）
+  //    注意：**必须先把 ZIPCALM_DATA_DIR 考虑进来** —— 否则 `ZIPCALM_DATA_DIR` 指到别处时，
+  //    这里仍在项目根下找 config.json，用户数据目录里那份永远读不到（npm 包形态就是这种情况：
+  //    包目录里没有 config.json，配置在 ~/.zipcalm/config.json）。
+  const envDataDir = typeof env.ZIPCALM_DATA_DIR === 'string' && env.ZIPCALM_DATA_DIR.length > 0
+    ? env.ZIPCALM_DATA_DIR
+    : null;
+  const dataDir = path.resolve(projectRoot, envDataDir || config.storage.dataDir);
+  const runtimeConfigPath = path.join(dataDir, 'config.json');
+  const runtimeConfig = await readJson(runtimeConfigPath, null);
+  if (runtimeConfig.ok && runtimeConfig.data) {
+    config = deepMerge(config, runtimeConfig.data);
+    sources.push(path.relative(projectRoot, runtimeConfigPath));
+  }
+
+  // 4) 环境变量（部署差异）
+  const envResult = applyEnv(config, env);
+  warnings.push(...envResult.warnings);
+  if (envResult.applied.length > 0) sources.push(`env(${envResult.applied.length} 项)`);
+
+  // ===== 校验 =====
+  const { errors, warnings: schemaWarnings } = validateConfig(config);
+  warnings.push(...schemaWarnings);
+  if (errors.length > 0) {
+    const error = new Error(`配置校验未通过：\n${errors.map((item) => `  - ${item}`).join('\n')}`);
+    error.name = 'ConfigError';
+    error.errors = errors;
+    throw error;
+  }
+
+  // ===== 路径绝对化 =====
+  // 基准目录（项目根）只在一处决定：所有 storage 子路径都经它换算，避免四处各写一次 path.resolve
+  const resolveUnderProject = (value) => path.resolve(projectRoot, value);
+  const resolved = {
+    ...config,
+    storage: {
+      ...config.storage,
+      root: resolveUnderProject(config.storage.root),
+      // 每个可切换根也绝对化；**不 ensureDir**（它们可能是 NAS 卷，应用无权/不该创建）
+      roots: (config.storage.roots || []).map((root) => ({ ...root, path: resolveUnderProject(root.path) })),
+      dataDir: resolveUnderProject(config.storage.dataDir),
+      trashDir: resolveUnderProject(config.storage.trashDir),
+      logDir: resolveUnderProject(config.storage.logDir),
+    },
+  };
+
+  // ===== 目录准备与可访问性校验（给出明确原因，而不是启动后才发现）=====
+  await ensureDir(resolved.storage.dataDir);
+  await ensureDir(resolved.storage.logDir);
+  await ensureDir(resolved.storage.trashDir);
+  await ensureDir(resolved.storage.root);
+
+  const rootReadWrite = await checkAccess(resolved.storage.root, fs.constants.R_OK | fs.constants.W_OK);
+  if (!rootReadWrite.ok) {
+    const error = new Error(`存储根不可读写：${resolved.storage.root}（${rootReadWrite.reason}）`);
+    error.name = 'ConfigError';
+    error.errors = ['storage.root 需要可读且可写'];
+    throw error;
+  }
+
+  return { config: resolved, projectRoot, warnings, sources };
+}

package/server/config/schema.js

@@ -0,0 +1,244 @@
+// 配置校验（零依赖，手写规则；结构照 docs/M0/数据模型.md §八）
+//
+// 校验分两档：
+// - errors：必须修，否则启动失败（类型错、端口越界、连密码都没配…）
+// - warnings：可疑但不致命（未知字段、删除模式回落…），只提示
+//
+// 文件系统相关的检查（root 存在且可读写）在 config/index.js 里做异步校验，
+// 因为本文件要保持纯函数、便于单测。
+//
+// 结构说明：**每个配置区块一个校验函数**（server / auth / storage / limits / compress / delete / log），
+// 主函数 validateConfig 只负责按序调用并汇总结果 —— 这样单块规则好读、好测，也不会堆成一个巨型 if。
+
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+
+/** 本版本认识的配置段（用于"未知段"告警；新增区块时同步这里） */
+const KNOWN_SECTIONS = ['server', 'auth', 'storage', 'limits', 'compress', 'delete', 'log'];
+
+const SEGMENT_LENGTH_MIN = 16;
+const SEGMENT_LENGTH_MAX = 4096;
+
+/** 普通对象判断（数组/null 都不算） */
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 区块存在性检查：不是对象就记错误（后续细项校验直接跳过，避免刷屏与 TypeError）。
+ * @returns {boolean} 该区块是否可用于细项校验
+ */
+function requireSection(config, section, errors) {
+  if (!isPlainObject(config[section])) {
+    errors.push(`配置段 ${section} 必须是对象`);
+    return false;
+  }
+  return true;
+}
+
+// ===== 各区块校验 =====
+
+function validateServer(config, errors) {
+  if (!requireSection(config, 'server', errors)) return;
+  const { host, port } = config.server;
+  if (typeof host !== 'string' || host.length === 0) errors.push('server.host 必须是非空字符串');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) errors.push('server.port 必须是 1~65535 的整数');
+}
+
+/** 账号与口令相关校验（用户名 / passwordHash 或 password / 哈希格式） */
+function validateAuthCredentials(auth, errors, warnings) {
+  const { username, password, passwordHash } = auth;
+  if (typeof username !== 'string' || username.length === 0) errors.push('auth.username 必须是非空字符串');
+  if (!password && !passwordHash) errors.push('auth 必须配置 passwordHash（推荐）或 password 其中之一');
+  if (passwordHash && !/^scrypt\$/.test(String(passwordHash))) {
+    warnings.push('auth.passwordHash 不是本项目的 scrypt$ 格式，可能无法通过校验（请用 scripts/hash-password.js 生成）');
+  }
+}
+
+/** 会话/令牌与登录限流相关校验 */
+function validateAuthTokens(auth, errors) {
+  const { sessionTtlMs, tokenTtlMs, cookieName, loginRateLimit } = auth;
+  if (!Number.isInteger(sessionTtlMs) || sessionTtlMs <= 0) errors.push('auth.sessionTtlMs 必须是正整数');
+  if (!Number.isInteger(tokenTtlMs) || tokenTtlMs <= 0) errors.push('auth.tokenTtlMs 必须是正整数');
+  if (typeof cookieName !== 'string' || !/^[A-Za-z0-9_-]+$/.test(cookieName)) {
+    errors.push('auth.cookieName 只能是字母数字下划线连字符');
+  }
+  if (!isPlainObject(loginRateLimit) || !Number.isInteger(loginRateLimit.max) || !Number.isInteger(loginRateLimit.windowMs)) {
+    errors.push('auth.loginRateLimit 需要 { max, windowMs } 两个整数');
+  }
+}
+
+function validateAuth(config, errors, warnings) {
+  if (!requireSection(config, 'auth', errors)) return;
+  validateAuthCredentials(config.auth, errors, warnings);
+  validateAuthTokens(config.auth, errors);
+}
+
+function validateStorage(config, errors) {
+  if (!requireSection(config, 'storage', errors)) return;
+  const { root, dataDir, trashDir, logDir } = config.storage;
+
+  for (const [key, value] of Object.entries({ root, dataDir, trashDir, logDir })) {
+    if (typeof value !== 'string' || value.length === 0) errors.push(`storage.${key} 必须是非空字符串`);
+  }
+  // 防呆：存储根不允许直接指向文件系统根，否则白名单形同虚设（INV-06）
+  if (typeof root === 'string' && (root === '/' || /^[A-Za-z]:[\\/]?$/.test(root))) {
+    errors.push('storage.root 不允许指向文件系统根（会让路径白名单失去意义）');
+  }
+  validateRoots(config.storage.roots, errors);
+}
+
+/** 可切换根列表：结构 + id 唯一 + 不许指向文件系统根（同一个 INV-06 防呆） */
+function validateRoots(roots, errors) {
+  if (roots === undefined || roots === null) return;
+  if (!Array.isArray(roots)) {
+    errors.push('storage.roots 必须是数组（[{ id, label, path }]），空数组表示自动发现');
+    return;
+  }
+  const seen = new Set();
+  for (const [index, entry] of roots.entries()) {
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`storage.roots[${index}] 必须是对象 { id, label, path }`);
+      continue;
+    }
+    validateRootEntry(entry, index, seen, errors);
+  }
+}
+
+/** 单条根校验（拆出来是为了把 validateRoots 的圈复杂度压在阈值内） */
+function validateRootEntry(entry, index, seen, errors) {
+  for (const key of ['id', 'path']) {
+    if (typeof entry[key] !== 'string' || entry[key].length === 0) {
+      errors.push(`storage.roots[${index}].${key} 必须是非空字符串`);
+    }
+  }
+  if (entry.label !== undefined && typeof entry.label !== 'string') {
+    errors.push(`storage.roots[${index}].label 必须是字符串`);
+  }
+  if (typeof entry.id === 'string') {
+    if (seen.has(entry.id)) errors.push(`storage.roots 里 id 重复：${entry.id}`);
+    seen.add(entry.id);
+  }
+  if (entry.path === '/' || /^[A-Za-z]:[\\/]?$/.test(String(entry.path))) {
+    errors.push(`storage.roots[${index}].path 不允许指向文件系统根`);
+  }
+}
+
+/** 路径长度相关（含两者之间的相对关系） */
+/** 批量操作上限（移动/删除）：单独成函数，避免把路径校验的复杂度推到阈值外 */
+function validateBulkLimits(limits, errors) {
+  for (const key of ['maxMoveItems', 'maxDeleteItems']) {
+    if (limits[key] !== undefined && (!Number.isInteger(limits[key]) || limits[key] < 1)) {
+      errors.push(`limits.${key} 必须是 ≥1 的整数`);
+    }
+  }
+}
+
+function validatePathLimits(limits, errors) {
+  const { maxPathLength, maxPathSegmentLength } = limits;
+  validateBulkLimits(limits, errors);
+  if (!Number.isInteger(maxPathLength) || maxPathLength < 64) errors.push('limits.maxPathLength 必须是 ≥64 的整数');
+  if (
+    !Number.isInteger(maxPathSegmentLength)
+    || maxPathSegmentLength < SEGMENT_LENGTH_MIN
+    || maxPathSegmentLength > SEGMENT_LENGTH_MAX
+  ) {
+    errors.push('limits.maxPathSegmentLength 必须是 16~4096 的整数（单段长度上限，POSIX 常见值 255）');
+  }
+  if (Number.isInteger(maxPathSegmentLength) && Number.isInteger(maxPathLength) && maxPathSegmentLength > maxPathLength) {
+    errors.push('limits.maxPathSegmentLength 不能大于 limits.maxPathLength');
+  }
+}
+
+/** 列表与分页相关 */
+function validateListLimits(limits, errors) {
+  const { maxListEntries, defaultPageSize } = limits;
+  if (!Number.isInteger(maxListEntries) || maxListEntries < 1) errors.push('limits.maxListEntries 必须是正整数');
+  if (!Number.isInteger(defaultPageSize) || defaultPageSize < 1) errors.push('limits.defaultPageSize 必须是正整数');
+}
+
+/** 任务活动记录保留策略 */
+function validateTaskRetentionLimits(limits, errors) {
+  const { taskRetentionMax, taskRetentionDays } = limits;
+  if (!Number.isInteger(taskRetentionMax) || taskRetentionMax < 1) {
+    errors.push('limits.taskRetentionMax 必须是 ≥1 的整数');
+  }
+  if (typeof taskRetentionDays !== 'number' || Number.isNaN(taskRetentionDays) || taskRetentionDays <= 0) {
+    errors.push('limits.taskRetentionDays 必须是正数（天，可小数）');
+  }
+}
+
+function validateLimits(config, errors) {
+  if (!requireSection(config, 'limits', errors)) return;
+  const limits = config.limits;
+  validatePathLimits(limits, errors);
+  validateListLimits(limits, errors);
+  validateTaskRetentionLimits(limits, errors);
+}
+
+function validateCompress(config, errors) {
+  if (!requireSection(config, 'compress', errors)) return;
+  const { defaultFormat, defaultMode, defaultLevel, preflightFactor } = config.compress;
+
+  if (typeof defaultFormat !== 'string' || defaultFormat.length === 0) errors.push('compress.defaultFormat 必须是非空字符串');
+  if (!['single', 'bundle'].includes(defaultMode)) errors.push('compress.defaultMode 只能是 single 或 bundle');
+  if (!Number.isInteger(defaultLevel) || defaultLevel < 0 || defaultLevel > 19) errors.push('compress.defaultLevel 必须是 0~19 的整数');
+  // INV-07：2 倍是底线，配置不允许把它调小
+  if (!Number.isInteger(preflightFactor) || preflightFactor < 2) {
+    errors.push('compress.preflightFactor 必须是 ≥2 的整数（INV-07：剩余空间 ≥ 待压 × 2）');
+  }
+}
+
+function validateDelete(config, warnings) {
+  if (!requireSection(config, 'delete', [])) return;
+  const { mode, confirmTimeoutMs } = config.delete;
+  // 契约：未知值只告警并回落 log-only（回落动作由删除服务执行），这里不拦
+  if (!['log-only', 'trash'].includes(mode)) {
+    warnings.push(`delete.mode 只能是 log-only 或 trash，当前 "${String(mode)}" 将回落为 log-only`);
+  }
+  // 回收站后端：非法值只告警并回落 auto（回落动作由删除服务执行）
+  const { trashBackend } = config.delete;
+  if (trashBackend !== undefined && !['auto', 'system', 'project', 'none'].includes(trashBackend)) {
+    warnings.push(`delete.trashBackend 只能是 auto / system / project / none，当前 "${String(trashBackend)}" 将回落为 auto`);
+  }
+  // 契约 §八：confirmTimeoutMs 非法值 → 告警并回落默认（回落动作由消费方执行），这里不拦
+  if (confirmTimeoutMs !== undefined && (typeof confirmTimeoutMs !== 'number' || !Number.isInteger(confirmTimeoutMs) || confirmTimeoutMs < 0)) {
+    warnings.push(`delete.confirmTimeoutMs 必须是非负整数毫秒，当前 "${String(confirmTimeoutMs)}" 将回落为默认值 1800000`);
+  }
+}
+
+function validateLog(config, errors) {
+  if (!requireSection(config, 'log', errors)) return;
+  if (!LOG_LEVELS.includes(config.log.level)) {
+    errors.push(`log.level 必须是 ${LOG_LEVELS.join(' / ')} 之一`);
+  }
+}
+
+/** 未知段只警告不拦截（向前兼容：以后新增区块时不至于启动失败） */
+function warnUnknownSections(config, warnings) {
+  for (const key of Object.keys(config)) {
+    if (!KNOWN_SECTIONS.includes(key)) {
+      warnings.push(`配置里存在未知段 ${key}（当前版本未使用，可能是以后里程碑的配置）`);
+    }
+  }
+}
+
+/**
+ * 校验配置。
+ * @param {object} config 待校验配置（已合并默认值/文件/env）
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateConfig(config) {
+  const errors = [];
+  const warnings = [];
+
+  validateServer(config, errors);
+  validateAuth(config, errors, warnings);
+  validateStorage(config, errors);
+  validateLimits(config, errors);
+  validateCompress(config, errors);
+  validateDelete(config, warnings);
+  validateLog(config, errors);
+  warnUnknownSections(config, warnings);
+
+  return { errors, warnings };
+}

package/server/core/auth/password.js

@@ -0,0 +1,89 @@
+// 密码哈希（scrypt，Node 内置，零依赖）
+//
+// 为什么不用明文比较、也不引 bcrypt：NAS 上不想再引原生编译依赖（项目原则：优先成熟库，但
+// 这里的"成熟库"bcrypt/argon2 都要原生编译，在 noexec 挂载等受限环境下风险高）。
+// Node 内置 scrypt 属标准方案，格式自带参数，便于将来升级参数而不破坏老哈希。
+//
+// 存储格式：scrypt$N$r$p$<salt-base64>$<hash-base64>
+// 只存哈希与随机盐，不存明文（INV-16）。
+
+import crypto from 'node:crypto';
+
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, keylen: 64 };
+
+function scryptAsync(password, salt, params) {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, params.keylen, { N: params.N, r: params.r, p: params.p }, (error, derived) => {
+      if (error) reject(error);
+      else resolve(derived);
+    });
+  });
+}
+
+/**
+ * 生成密码哈希。
+ * @param {string} password 明文
+ * @returns {Promise<string>} scrypt$ 开头的字符串
+ */
+export async function hashPassword(password) {
+  if (typeof password !== 'string' || password.length === 0) {
+    throw new Error('hashPassword 需要非空字符串');
+  }
+  const salt = crypto.randomBytes(16);
+  const derived = await scryptAsync(password, salt, SCRYPT_PARAMS);
+  return [
+    'scrypt',
+    SCRYPT_PARAMS.N,
+    SCRYPT_PARAMS.r,
+    SCRYPT_PARAMS.p,
+    salt.toString('base64'),
+    derived.toString('base64'),
+  ].join('$');
+}
+
+/** 解析 scrypt$ 哈希串 → 派生参数；格式不对返回 null（不抛错，调用方按"校验失败"处理） */
+function parseScryptHash(stored) {
+  const parts = stored.split('$');
+  if (parts.length !== 6 || parts[0] !== 'scrypt') return null;
+
+  const [, nRaw, rRaw, pRaw, saltB64, hashB64] = parts;
+  const params = {
+    N: Number.parseInt(nRaw, 10),
+    r: Number.parseInt(rRaw, 10),
+    p: Number.parseInt(pRaw, 10),
+    keylen: Buffer.from(hashB64, 'base64').length,
+  };
+  const valid = Number.isInteger(params.N) && Number.isInteger(params.r) && Number.isInteger(params.p) && params.keylen > 0;
+  return valid ? { params, saltB64, hashB64 } : null;
+}
+
+/**
+ * 校验密码（timing-safe 比较）。
+ * @param {string} password 明文
+ * @param {string} stored 存储的哈希（scrypt$ 格式）
+ * @returns {Promise<boolean>}
+ */
+export async function verifyPassword(password, stored) {
+  if (typeof password !== 'string' || typeof stored !== 'string') return false;
+  const parsed = parseScryptHash(stored);
+  if (!parsed) return false;
+
+  try {
+    const derived = await scryptAsync(password, Buffer.from(parsed.saltB64, 'base64'), parsed.params);
+    const expected = Buffer.from(parsed.hashB64, 'base64');
+    if (expected.length !== derived.length) return false;
+    return crypto.timingSafeEqual(derived, expected);
+  } catch {
+    return false;
+  }
+}
+
+/** 生成不透明随机串（session id / bearer token 的明文形态） */
+export function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+/** 只存储哈希：日志与磁盘里都不会出现可用于登录的明文（INV-16） */
+export function sha256(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}