@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/auth.js

@@ -0,0 +1,349 @@
+// 登录、凭据生命周期与续期（契约 §4）。
+//
+// 四条纪律，全部在这里收口：
+//
+// 1. **令牌永不进 argv、永不进日志、永不进错误详情**。凭据只从
+//    `~/.config/xinhe-oa-cli/credentials.json`（0600）读；
+//    `login --password` 的口令从 **stdin** 读（不做 `--password <明文>`）。
+// 2. **设备指纹首次登录生成并持久化**，每个请求带 `X-Device-Id` +
+//    固定 UA（`xinhe-oa-cli/1`）。换设备 → 服务端 `auth.device_mismatch`。
+// 3. **续期**：access 默认 600s，提前 60s 用 refresh 换新的；
+//    refresh **一次性轮换**，新值**立即落盘**（换完就把旧的扔掉 = 自己把自己踢下线）。
+// 4. **换不回来 → 退出码 3 + hint 给出短信登录命令**（契约 §3.2 / §4）。
+
+import { CliError, Kind, loginHint } from './error.js';
+import {
+  ProxyMode,
+  hasAccess,
+  hasRefresh,
+  toCredentialJson,
+} from './config.js';
+import { Http, Auth, requestSpec } from './http.js';
+import { nowRfc3339, parseRfc3339 } from './util.js';
+import { verbose } from './output.js';
+
+/** 续期提前量（契约 §4：access 默认 600s，提前 60s 换）。 */
+export const REFRESH_MARGIN_SECS = 60;
+/** 续期请求允许的重试次数（轮换是"读改写"，重试要谨慎）。 */
+const REFRESH_ATTEMPTS = 2;
+
+/** 一次 API 调用所需的认证上下文。 */
+export class AuthContext {
+  constructor({ profile, http, credential, verbose: isVerbose = false }) {
+    this.profile = profile;
+    this.http = http;
+    this.credential = credential;
+    this.verbose = isVerbose;
+  }
+}
+
+function serverShapeError(what) {
+  return new CliError(
+    Kind.Server,
+    'cli.bad_response',
+    `服务端响应形状不对：${what}`,
+  ).withHint('这多半是服务端版本不匹配：跑 `xinhe-oa-cli doctor` 看两侧版本');
+}
+
+/** 服务端 `data.tokens` + `data.user` → 本地凭据。 */
+export function credentialFromTokens(body, baseUrl, deviceId, phone) {
+  const tokens = body?.tokens;
+  if (tokens === undefined || tokens === null) throw serverShapeError('响应里没有 data.tokens');
+  if (typeof tokens.access_token !== 'string') {
+    throw serverShapeError('响应里没有 tokens.access_token');
+  }
+  const credential = {
+    base_url: baseUrl,
+    device_id: deviceId,
+    tokens: {
+      access_token: tokens.access_token,
+      refresh_token: typeof tokens.refresh_token === 'string' ? tokens.refresh_token : '',
+    },
+  };
+  if (typeof tokens.access_expires_at === 'string') {
+    credential.tokens.access_expires_at = tokens.access_expires_at;
+  }
+  if (typeof tokens.refresh_expires_at === 'string') {
+    credential.tokens.refresh_expires_at = tokens.refresh_expires_at;
+  }
+  if (body?.user !== undefined && body?.user !== null) credential.user = body.user;
+  if (phone !== null && phone !== undefined) credential.phone = phone;
+  credential.updated_at = nowRfc3339();
+  return credential;
+}
+
+/**
+ * 从 stdin 读一行（口令用）。**不回显、不落历史、不进日志**。
+ *
+ * 读**整个** stdin 再取第一行 —— 与 Rust 版一致：`printf '%s' "$PW" | …`
+ * 没有换行结尾时，按行读会拿到空串。
+ */
+export async function readSecretFromStdin(prompt) {
+  process.stderr.write(prompt);
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString('utf8');
+  const secret = (text.split('\n')[0] ?? '').trim();
+  if (secret.length === 0) {
+    throw CliError.usage('标准输入里没有口令').withHint(
+      "用法：printf '%s' \"$XINHE_OA_PASSWORD\" | xinhe-oa-cli login --password --account <账号>",
+    );
+  }
+  return secret;
+}
+
+// ---------------------------------------------------------------------------
+// 令牌到期判断
+// ---------------------------------------------------------------------------
+/**
+ * access 是否已经过期或将在 `REFRESH_MARGIN_SECS` 内过期。
+ *
+ * **缺时间戳时返回 true**（宁可多刷一次，也不要拿一枚可能已经过期的令牌去撞 401：
+ * 服务端对过期令牌回 `auth.token_expired`，而它属于退出码 3 —— 那会让一次
+ * "其实能自动续上的"调用变成"请重新登录"）。
+ */
+export function accessNeedsRefresh(credential) {
+  const raw = credential?.tokens?.access_expires_at;
+  if (typeof raw !== 'string') return true;
+  const expiresAt = parseRfc3339(raw);
+  if (expiresAt === null) return true;
+  return expiresAt - Date.now() <= REFRESH_MARGIN_SECS * 1000;
+}
+
+/** refresh 是否已经过期（过期就别白跑一趟网络）。缺时间戳 = 不知道 = 不拦。 */
+export function refreshExpired(credential) {
+  const raw = credential?.tokens?.refresh_expires_at;
+  if (typeof raw !== 'string') return false;
+  const expiresAt = parseRfc3339(raw);
+  if (expiresAt === null) return false;
+  return expiresAt <= Date.now();
+}
+
+function expiredError(credential) {
+  return new CliError(
+    Kind.Auth,
+    'auth.refresh_expired',
+    '登录已过期，需要重新做一次短信验证',
+  ).withHint(loginHint(credential?.phone ?? null));
+}
+
+/** 服务端响应统一 `{"data": ...}` 包装；这里取 `data`（没有就退回整个响应体）。 */
+export function envelopeData(response) {
+  const body = response?.body;
+  if (body && typeof body === 'object' && body.data !== undefined && body.data !== null) {
+    return body.data;
+  }
+  return body ?? {};
+}
+
+// ---------------------------------------------------------------------------
+// 续期
+// ---------------------------------------------------------------------------
+/**
+ * 用 refresh 换新令牌。**新值立即落盘**（一次性轮换：不落盘就等于把这枚令牌弄丢了）。
+ *
+ * 调用方传进来的 `session` 是 `{ credential, store, profile }`：
+ * 凭据对象在这里被**原地更新**，落盘走 `store.put`。
+ */
+export async function refreshTokens(http, session, isVerbose) {
+  const { credential, store, profile } = session;
+  if (!hasRefresh(credential)) throw expiredError(credential);
+  if (refreshExpired(credential)) throw expiredError(credential);
+
+  let lastError = null;
+  for (let attempt = 0; attempt < REFRESH_ATTEMPTS; attempt += 1) {
+    const spec = requestSpec({ body: { refresh_token: credential.tokens.refresh_token } });
+    try {
+      const response = await http.send('POST', '/auth/refresh', Auth.none(), spec, '登录续期');
+      const body = envelopeData(response);
+      const fresh = credentialFromTokens(
+        body,
+        http.baseUrl,
+        credential.device_id,
+        credential.phone ?? null,
+      );
+      // 服务端可能不回 user（`POST /auth/refresh` 会回），保守起见沿用旧的。
+      if (fresh.user === undefined) fresh.user = credential.user;
+      verbose(isVerbose, 'access 已续期（refresh 已轮换并落盘）');
+      session.credential = fresh;
+      store.put(profile, fresh);
+      return fresh;
+    } catch (err) {
+      const retryable =
+        err instanceof CliError &&
+        ['cli.bad_response', 'internal.error', 'rate.limited'].includes(err.code) &&
+        attempt + 1 < REFRESH_ATTEMPTS;
+      if (retryable) {
+        process.stderr.write('· 续期响应异常，稍后重试一次\n');
+        await sleepMs(500);
+        lastError = err;
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError ?? expiredError(credential);
+}
+
+function sleepMs(ms) {
+  return new Promise((resolve) => {
+    const handle = setTimeout(resolve, ms);
+    if (typeof handle.unref === 'function') handle.unref();
+  });
+}
+
+/** access 需要刷新就先刷（幂等：不需要时一次网络都不发）。 */
+export async function ensureFresh(session, isVerbose) {
+  if (!accessNeedsRefresh(session.credential)) return;
+  if (!hasRefresh(session.credential)) throw expiredError(session.credential);
+  verbose(isVerbose, 'access 临近过期，先续期');
+  await refreshTokens(session.http, session, isVerbose);
+}
+
+/**
+ * 用当前凭据发一次**已认证**请求；access 快过期就先续期，
+ * 拿到 `auth.token_expired` 再续一次并重试一次。
+ */
+export async function authedSend(session, method, path, spec, command) {
+  await ensureFresh(session, session.verbose);
+  try {
+    return await session.http.send(
+      method,
+      path,
+      Auth.bearer(session.credential.tokens.access_token),
+      spec,
+      command,
+    );
+  } catch (err) {
+    if (!(err instanceof CliError) || err.code !== 'auth.token_expired') throw err;
+    // 本地时钟偏差或服务端刚吊销：续一次再试一次。
+    verbose(session.verbose, 'access 被服务端判为过期，续期后重试一次');
+    await refreshTokens(session.http, session, session.verbose);
+    return session.http.send(
+      method,
+      path,
+      Auth.bearer(session.credential.tokens.access_token),
+      spec,
+      command,
+    );
+  }
+}
+
+/** multipart 上传（附件用）。 */
+export async function authedUpload(session, path, form, command, idempotencyKey) {
+  await ensureFresh(session, session.verbose);
+  const spec = requestSpec({ multipart: form, idempotencyKey: idempotencyKey ?? null });
+  return session.http.send(
+    'POST',
+    path,
+    Auth.bearer(session.credential.tokens.access_token),
+    spec,
+    command,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 登录 / 登出
+// ---------------------------------------------------------------------------
+/**
+ * `login --phone --code`：校验并落盘凭据。
+ *
+ * 首次调用时 `deviceId` 必须是**先持久化再用**（由调用方保证）：
+ * 服务端把 refresh 绑在 `HMAC(UA + X-Device-Id)` 上，落盘前走网络不会有问题，
+ * 但**下一次**续期用的是落盘的那个 id —— 不一致就 `auth.device_mismatch`。
+ */
+export async function verifyOtp(http, phone, code, deviceId) {
+  const spec = requestSpec({ body: { phone, code } });
+  const response = await http.send('POST', '/auth/otp/verify', Auth.none(), spec, 'login --code');
+  return credentialFromTokens(envelopeData(response), http.baseUrl, deviceId, phone);
+}
+
+/** `login --password --account`：仅引导账号。口令从 stdin 读。 */
+export async function loginWithPassword(http, account, password, deviceId) {
+  const spec = requestSpec({ body: { account, password } });
+  const response = await http.send('POST', '/auth/login', Auth.none(), spec, 'login --password');
+  return credentialFromTokens(envelopeData(response), http.baseUrl, deviceId, account);
+}
+
+/**
+ * `login --adopt-session`：从 stdin 读一个 JSON 会话交接体并落盘。
+ *
+ * 形状（由 install.sh / install.ps1 生成）：
+ * ```jsonc
+ * {"base_url":"http://...","device_id":"dev-...",
+ *  "tokens":{"access_token":"...","refresh_token":"...","access_expires_at":"RFC3339",
+ *            "refresh_expires_at":"RFC3339"},
+ *  "user":{"id":"usr_...","name":"..."}}
+ * ```
+ */
+export function adoptSession(raw, fallbackBaseUrl) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw ?? '').trim());
+  } catch (err) {
+    throw CliError.usage(`从 stdin 读到的会话不是合法 JSON：${err.message}`).withHint(
+      "用法：echo '<install.sh 交接的会话 JSON>' | xinhe-oa-cli login --adopt-session",
+    );
+  }
+  const tokens = parsed?.tokens;
+  if (tokens === undefined || tokens === null) throw CliError.usage('交接体里缺 tokens');
+  if (typeof tokens.access_token !== 'string') {
+    throw CliError.usage('交接体里缺 tokens.access_token');
+  }
+  if (tokens.access_token.length === 0) {
+    throw CliError.usage('交接体里的 tokens.access_token 是空串');
+  }
+  // device_id 必须沿用交接方的：服务端把 refresh 绑在 HMAC(UA + X-Device-Id) 上，
+  // 这里换一个 id 会让第一次续期直接 `auth.device_mismatch`。
+  const deviceId =
+    typeof parsed.device_id === 'string' && parsed.device_id.trim().length > 0
+      ? parsed.device_id
+      : null;
+  if (deviceId === null) {
+    throw CliError.usage('交接体里缺 device_id').withHint(
+      'install.sh 必须把它做 OTP 时用的 X-Device-Id 一起交接，否则续期会被拒',
+    );
+  }
+  const baseUrl =
+    typeof parsed.base_url === 'string' && parsed.base_url.trim().length > 0
+      ? parsed.base_url.trim().replace(/\/+$/, '')
+      : String(fallbackBaseUrl ?? '').trim().replace(/\/+$/, '');
+
+  const credential = {
+    base_url: baseUrl,
+    device_id: deviceId,
+    tokens: {
+      access_token: tokens.access_token,
+      refresh_token: typeof tokens.refresh_token === 'string' ? tokens.refresh_token : '',
+    },
+  };
+  if (typeof tokens.access_expires_at === 'string') {
+    credential.tokens.access_expires_at = tokens.access_expires_at;
+  }
+  if (typeof tokens.refresh_expires_at === 'string') {
+    credential.tokens.refresh_expires_at = tokens.refresh_expires_at;
+  }
+  if (parsed.user !== undefined && parsed.user !== null) credential.user = parsed.user;
+  if (typeof parsed.phone === 'string') credential.phone = parsed.phone;
+  credential.updated_at = nowRfc3339();
+  return credential;
+}
+
+/** `logout`：吊销会话链并删掉本地凭据。 */
+export async function logout(http, credential) {
+  const body = hasRefresh(credential) ? { refresh_token: credential.tokens.refresh_token } : {};
+  const spec = requestSpec({ body });
+  // logout 常带着**已经过期**的 access 来：令牌过期不该挡登出，
+  // 所以这里用 refresh 当凭据、access 只是"如果能用就用"。
+  const auth = hasAccess(credential) ? Auth.bearer(credential.tokens.access_token) : Auth.none();
+  const response = await http.send('POST', '/auth/logout', auth, spec, 'logout');
+  return envelopeData(response);
+}
+
+/** 只给测试/工具用：把凭据的落盘形状导出（见 `toCredentialJson`）。 */
+export { toCredentialJson };
+
+/** 按 profile 建一个 Http 客户端（base_url 已经解析过）。 */
+export function httpFor(baseUrl, proxyMode, deviceId, timeoutMs) {
+  return new Http(baseUrl, proxyMode ?? ProxyMode.System, deviceId, timeoutMs);
+}

package/src/core/checkpoint.js

@@ -0,0 +1,226 @@
+// 导入断点续传（`bitable table --import` 的 checkpoint）。
+//
+// 现场问题（2026-09-29）：一次 5,611 行的导入被打断三次，每次都得**从头再来** ——
+// 服务端逐行写 31–57 ms，白跑的就是十几分钟。而"哪些批已经成功"这件事，
+// 客户端本来就知道（每批一个幂等键、每次成功都有响应），只是没落盘。
+//
+// 落盘内容（`<config>/checkpoints/<table_id>-<文件指纹>.json`）刻意包含
+// **批的边界本身**，而不只是"已完成到第几行"：
+//
+// ```json
+// {
+//   "version": 1, "table_id": "...", "file_fingerprint": "...",
+//   "rows": 5611, "batch_size": 500, "updated_at": "...",
+//   "batches": [{"index":0,"start":0,"end":500,"records":500,"done":true,
+//                "idempotency_key":"import:...:tbl_...:0"}, ...]
+// }
+// ```
+//
+// 为什么必须存边界：服务端的幂等键是**客户端给的**，而键里带着批序号。
+// 第二次运行时如果 `--batch-size` 变了，切出来的批与第一次不同 → 键不同 →
+// 服务端认为是新请求 → **同一份数据被写第二遍**。所以续传必须沿用第一次的批划分
+// （见 `samePlan`）。这条约束写在这里，是因为它不写下来就会被"优化"掉。
+//
+// 写盘用「临时文件 + rename」：导入中途断电只会留下旧文件或新文件，
+// 不会留下半个 JSON（半个 JSON 会让下一次运行判定为损坏并从头再来）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { CliError } from './error.js';
+import { rustIoErrorText } from './util.js';
+import { sortKeysDeep } from './util.js';
+
+/** checkpoint 的格式版本：字段含义变化时 +1（读到更高版本就当读不懂，从头来）。 */
+export const VERSION = 1;
+
+/** checkpoint 文件路径：`<config>/checkpoints/<table_id>-<file_fingerprint>.json`。
+ *
+ * 文件名里带**文件指纹**而不只是表 id：同一张表每月追加不同月份的文件时，
+ * 两个文件各自的进度不能互相覆盖（那会让"上个月导完了"变成"这个月不用导"）。
+ */
+export function pathFor(paths, tableId, fileFingerprint) {
+  return path.join(paths.checkpointsDir, `${sanitize(tableId)}-${sanitize(fileFingerprint)}.json`);
+}
+
+/** 表 id / 指纹理论上都是安全字符，但仍然过一道：它们会进文件名。 */
+function sanitize(raw) {
+  return Array.from(String(raw ?? ''))
+    .map((ch) => (/[A-Za-z0-9_-]/.test(ch) ? ch : '_'))
+    .join('');
+}
+
+/** 一次导入的断点记录（普通对象；字段名与 Rust 的 `Checkpoint` 逐字对应）。 */
+export function newCheckpoint({ tableId, fileFingerprint, rows, batchSize, batches, updatedAt }) {
+  return {
+    table_id: tableId,
+    file_fingerprint: fileFingerprint,
+    rows,
+    batch_size: batchSize,
+    updated_at: updatedAt,
+    batches: batches.map((batch) => ({
+      index: batch.index,
+      start: batch.start,
+      end: batch.end,
+      records: batch.end - batch.start,
+      idempotency_key: batch.idempotencyKey,
+      done: false,
+    })),
+  };
+}
+
+/** 已完成批数。 */
+export function doneCount(checkpoint) {
+  return checkpoint.batches.filter((batch) => batch.done).length;
+}
+
+/** 已完成批覆盖的行数。 */
+export function doneRecords(checkpoint) {
+  return checkpoint.batches
+    .filter((batch) => batch.done)
+    .reduce((sum, batch) => sum + batch.records, 0);
+}
+
+/** 计划里的每一批都已完成（重跑同一命令 = 全部幂等重放，不会写第二遍）。 */
+export function isComplete(checkpoint) {
+  return checkpoint.batches.length > 0 && checkpoint.batches.every((batch) => batch.done);
+}
+
+function toValue(checkpoint) {
+  // `sortKeysDeep` 让落盘键序与 Rust 的 `serde_json`（BTreeMap）逐字节同形 ——
+  // 同一份进度在两种实现之间来回读，diff 里不该出现"只是键序不同"的噪声。
+  return sortKeysDeep({
+    version: VERSION,
+    table_id: checkpoint.table_id,
+    file_fingerprint: checkpoint.file_fingerprint,
+    rows: checkpoint.rows,
+    batch_size: checkpoint.batch_size,
+    updated_at: checkpoint.updated_at,
+    batches: checkpoint.batches.map((batch) => ({
+      index: batch.index,
+      start: batch.start,
+      end: batch.end,
+      records: batch.records,
+      done: batch.done,
+      idempotency_key: batch.idempotency_key,
+    })),
+  });
+}
+
+/** 读不懂的形状一律 `null`（缺失字段/类型不对 = 这份进度不能用）。 */
+function fromValue(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.version !== VERSION) return null;
+  if (!Array.isArray(value.batches)) return null;
+  const batches = [];
+  for (const batch of value.batches) {
+    if (!batch || typeof batch !== 'object') return null;
+    if (
+      typeof batch.index !== 'number' ||
+      typeof batch.start !== 'number' ||
+      typeof batch.end !== 'number' ||
+      typeof batch.records !== 'number' ||
+      typeof batch.idempotency_key !== 'string'
+    ) {
+      return null;
+    }
+    batches.push({
+      index: batch.index,
+      start: batch.start,
+      end: batch.end,
+      records: batch.records,
+      idempotency_key: batch.idempotency_key,
+      done: batch.done === true,
+    });
+  }
+  if (
+    typeof value.table_id !== 'string' ||
+    typeof value.file_fingerprint !== 'string' ||
+    typeof value.rows !== 'number' ||
+    typeof value.batch_size !== 'number'
+  ) {
+    return null;
+  }
+  return {
+    table_id: value.table_id,
+    file_fingerprint: value.file_fingerprint,
+    rows: value.rows,
+    batch_size: value.batch_size,
+    updated_at: typeof value.updated_at === 'string' ? value.updated_at : '',
+    batches,
+  };
+}
+
+/**
+ * 读 checkpoint。文件不存在 → `null`；**读不懂也返回 `null`**（当作没有），
+ * 因为"磁盘上有半个 JSON"绝不该让导入直接失败 —— 最坏的结果只是从头再来。
+ */
+export function load(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    return fromValue(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** 落盘（临时文件 + rename，见模块头）。 */
+export function save(file, checkpoint) {
+  const parent = path.dirname(file);
+  try {
+    fs.mkdirSync(parent, { recursive: true });
+  } catch (err) {
+    throw CliError.local(`建不了 checkpoint 目录 ${parent}：${rustIoErrorText(err)}`);
+  }
+  const payload = JSON.stringify(toValue(checkpoint), null, 2);
+  const tmp = `${file}.tmp`;
+  try {
+    fs.writeFileSync(tmp, payload);
+  } catch (err) {
+    throw CliError.local(`写不了 checkpoint ${tmp}：${rustIoErrorText(err)}`);
+  }
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    throw CliError.local(`落不了 checkpoint ${file}：${rustIoErrorText(err)}`);
+  }
+}
+
+/** 删掉 checkpoint（导入完整成功后调用：下次重跑 = 新的一次导入）。 */
+export function remove(file) {
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    /* 删不掉不是错误：下次会当作"没有进度" */
+  }
+}
+
+/** 文件在不在（`--fresh` 时用来决定要不要打印提示）。 */
+export function exists(file) {
+  try {
+    fs.accessSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 旧 checkpoint 与这次的目标/批划分是否完全一致（逐批的起止行号都要对上）。
+ *
+ * 只比 `--batch-size` 是不够的：按体积二次切分让批边界依赖**具体内容**，
+ * 同样是 500 行上限，宽表可能切成 300+200。边界不同 → 幂等键不同 → 会写第二遍。
+ */
+export function samePlan(existing, tableId, planned) {
+  if (existing.table_id !== tableId) return false;
+  if (existing.batches.length !== planned.length) return false;
+  return existing.batches.every((batch, index) => {
+    const other = planned[index];
+    return batch.index === other.index && batch.start === other.start && batch.end === other.end;
+  });
+}