@yixinshuke/node-auth 0.0.0-stage → 0.1.1

package/src/request-sign.ts

@@ -0,0 +1,341 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { type OpenSecretBundle } from "./openSecret.js";
+
+/**
+ * 服务调用签名（appId + secret，HMAC-SHA256）。
+ *
+ * 适用通道：`/open`（对外开放接口）、`/callback`（回调）——区别于 `/api` 的人用登录态（JWT）。
+ *
+ * ## 签名四要素在「提交数据」里，不在 HTTP 头里
+ *  四项要素 `appId / timestamp / nonce / sign` 与业务参数**同处一个 JSON body**（见 `SIGN_FIELDS`）。
+ *  理由：① 开放通道刻意不带 `Authorization` / `Cookie`（那是 `/api` 的人用登录态，不该出现在机器通道上，
+ *  否则同一份报文里混着两套身份，语义混乱且容易误判）；② body 才是被签名覆盖的载体，要素与报文绑在一起
+ *  不会被代理 / 网关掐头；③ 调用方只需拼一个 JSON，不必再操心头部。
+ *  摘要计算时由 `buildSignBase` **统一剔除**这四项（见 `stripSignFields`），故报文中带不带它们、
+ *  带的是旧值还是新值都不影响签名——两端永远算同一份「纯业务报文」摘要。
+ *
+ * ## 为什么用 HMAC-SHA256 而不是裸 sha1(secret + 串)
+ *  - 拼接式哈希存在「长度扩展攻击」隐患，HMAC 天生免疫；
+ *  - SHA1 碰撞已被攻破，不再适合做签名基元；
+ *  - HMAC-SHA256 与 SHA1 同量级开销，node:crypto 一行可得。
+ *
+ * ## 对称密钥的现实代价（使用者必须知道）
+ *  校验方同时握有所有调用方的 secret ⇒ **校验方一旦被攻破，攻击者可伪装成任意一个调用方**。
+ *  因此必须坚持「一个 appId 一把 secret」，才能做单独吊销与轮换，避免一处泄露全盘失效。
+ *
+ * ## 关于重放（replay）
+ *  本模块**不内置** nonce 去重，只提供 `checkNonce` 供宿主按需注入（回调类通道建议业务侧幂等兜住，
+ *  因为「平台正常重投」与「攻击者重放」在字节流上无法区分，最终都只能靠幂等收敛）。
+ */
+
+/** 签名四要素在**提交数据（JSON body）**里的字段名 */
+export const SIGN_FIELDS = {
+  appId: "appId",
+  timestamp: "timestamp",
+  nonce: "nonce",
+  sign: "sign",
+} as const;
+
+/** 四项要素的键集合（用于从报文里剔除它们后再算摘要） */
+const SIGN_FIELD_KEYS: ReadonlySet<string> = new Set([
+  SIGN_FIELDS.appId,
+  SIGN_FIELDS.timestamp,
+  SIGN_FIELDS.nonce,
+  SIGN_FIELDS.sign,
+]);
+
+/**
+ * 剔除报文里的四项签名要素，剩下的才是参与摘要的**纯业务报文**。
+ *
+ * 必要性：要素要跟业务参数同处一个 body，但 `sign` 自身不可能被自己覆盖（鸡生蛋问题），
+ * 且 `timestamp` / `nonce` 已在待签串里单独成行。统一在本函数剥掉，调用方无需自己过滤。
+ */
+export function stripSignFields(body: unknown): unknown {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+  const o = body as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(o)) {
+    if (!SIGN_FIELD_KEYS.has(k)) out[k] = o[k];
+  }
+  return out;
+}
+
+/** 默认允许的时钟偏差（毫秒）：±5 分钟 */
+export const DEFAULT_TOLERANCE_MS = 5 * 60 * 1000;
+
+/** 签名所需的原始要素 */
+export interface SignatureParts {
+  method: string;
+  /** 路径（含前缀，不含 query） */
+  path: string;
+  /** unix 秒 */
+  timestamp: number;
+  nonce: string;
+  /** 已解析的请求体对象 */
+  body: unknown;
+}
+
+/**
+ * 规范化 JSON：对象键按字典序**递归**排序，紧凑输出（无空格）。
+ *
+ * 这是签名能否验通的关键 —— 若两端各自 `JSON.stringify`，键顺序或空格差异都会导致签名对不上，
+ * 因此双方**必须**都用本函数生成待摘要体。
+ */
+export function canonicalJson(value: unknown): string {
+  return canonicalize(value);
+}
+
+function canonicalize(v: unknown): string {
+  if (v === undefined) return "null";
+  if (v === null) return "null";
+  const t = typeof v;
+  if (t === "number" || t === "boolean") return String(v);
+  if (t === "string") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalize).join(",")}]`;
+  if (t === "object") {
+    const obj = v as Record<string, unknown>;
+    const body = Object.keys(obj)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`)
+      .join(",");
+    return `{${body}}`;
+  }
+  // bigint / symbol / function 等：统一退化成字符串，保证两端一致
+  return JSON.stringify(String(v));
+}
+
+/**
+ * 空请求体规范：`undefined` / `null` 一律视为 `{}`。
+ *
+ * 必要性（踩过的坑）：调用方「不传 body」时自己签名用的是 undefined，
+ * 而服务端 body parser 解析出来的往往是 `{}` —— 若两边各自原样序列化，
+ * `null` 与 `{}` 会算出完全不同的摘要，导致**空 body 的调用永远验签失败**。
+ * 因此必须在一个地方统一。
+ */
+export function normalizeBody(v: unknown): unknown {
+  return v === undefined || v === null ? {} : v;
+}
+
+/** 组装待签串：`METHOD\npath\ntimestamp\nnonce\nsha256hex(canonicalJson(纯业务报文))` */
+export function buildSignBase(parts: SignatureParts): string {
+  return [
+    String(parts.method ?? "").toUpperCase(),
+    String(parts.path ?? ""),
+    String(parts.timestamp ?? ""),
+    String(parts.nonce ?? ""),
+    // 剔除四项签名要素后再摘要：报文里带不带它们、带的什么值都不影响结果
+    sha256Hex(canonicalJson(normalizeBody(stripSignFields(parts.body)))),
+  ].join("\n");
+}
+
+/** 计算签名：base64(HMAC-SHA256(待签串, secret)) */
+export function signRequest(secret: string, parts: SignatureParts): string {
+  return createHmac("sha256", String(secret ?? "")).update(buildSignBase(parts), "utf8").digest("base64");
+}
+
+/** 从提交数据里解析出的四项凭证（method/path/body 需由调用方按当前请求补齐后才可用于验签） */
+export interface SignedFields extends SignatureParts {
+  appId: string;
+  sign: string;
+}
+
+/** 从提交数据（JSON body）里取出四项凭证（缺失/非法返回 null） */
+export function readSignedBody(body: unknown): SignedFields | null {
+  const o = (body && typeof body === "object" && !Array.isArray(body) ? body : {}) as Record<string, unknown>;
+  const appId = String(o[SIGN_FIELDS.appId] ?? "").trim();
+  const tsRaw = o[SIGN_FIELDS.timestamp];
+  const nonce = String(o[SIGN_FIELDS.nonce] ?? "").trim();
+  const sign = String(o[SIGN_FIELDS.sign] ?? "").trim();
+  if (!appId || !sign) return null;
+  const timestamp = Number(tsRaw);
+  if (!Number.isFinite(timestamp)) return null;
+  return { appId, timestamp, nonce, sign, method: "", path: "", body: undefined };
+}
+
+/**
+ * 把四项签名要素写进提交数据（调用方 / 调试面板 / 自检脚本的统一出口）。
+ *
+ * 返回的是「业务报文 + appId/timestamp/nonce/sign」的新对象（不改原对象）。
+ * 摘要只覆盖业务报文部分，故先算签名、再把要素并进去，顺序不能反。
+ */
+export function attachSignature(
+  secret: string,
+  parts: SignatureParts & { appId: string },
+): Record<string, unknown> {
+  const payload = (normalizeBody(stripSignFields(parts.body)) ?? {}) as Record<string, unknown>;
+  const sign = signRequest(secret, parts);
+  return {
+    ...payload,
+    [SIGN_FIELDS.appId]: String(parts.appId ?? ""),
+    [SIGN_FIELDS.timestamp]: Number(parts.timestamp),
+    [SIGN_FIELDS.nonce]: String(parts.nonce ?? ""),
+    [SIGN_FIELDS.sign]: sign,
+  };
+}
+
+export interface VerifyInput {
+  /** 宿主指定此入口允许的调用方；不配置时按该模块原有协议授权。 */
+  allowedAppIds?: readonly string[];
+  /** 宿主可要求 nonce 必传，用于内部请求防重放。 */
+  requireNonce?: boolean;
+  method: string;
+  path: string;
+  /**
+   * 客户端提交的完整 JSON（**含**四项签名要素）。
+   * 摘要计算由 `buildSignBase` 内部剔除要素后完成，调用方直接传原样报文即可。
+   */
+  body: unknown;
+  /**
+   * 按 appId 取密钥。可返回明文 secret 字符串，或直接返回 OpenSecretBundle（含 secret + 命令白/黑名单）；
+   * 返回 null 视为未知 appId。推荐返回 bundle，以便一并做命令放通校验。
+   */
+  resolveSecret: (appId: string) => string | OpenSecretBundle | null | Promise<string | OpenSecretBundle | null>;
+  /** 允许的时钟偏差，默认 5 分钟 */
+  toleranceMs?: number;
+  /**
+   * 可选的 nonce 去重：返回 true 表示「这个 nonce 已经用过了」→ 判定为重放。
+   * 不传则不防重放（一期默认如此）。
+   */
+  seenNonce?: (nonce: string) => boolean | Promise<boolean>;
+  /** 当前时间（便于测试注入），默认 Date.now() */
+  now?: number;
+  /**
+   * 是否参与签名的 body 必须存在：关闭后允许空 body 调用（默认 false，即允许空 body）。
+   * 打开可用于要求调用方必须传 body 的严格场景。
+   */
+  requireBody?: boolean;
+}
+
+export type VerifyResult =
+  | { ok: true; appId: string }
+  | { ok: false; code: 401 | 403; reason: string };
+
+/**
+ * 校验一次签名请求。
+ *
+ * 校验顺序（每一步失败都**立即返回**，不做后续计算）：
+ *   1. 提交数据里四项要素齐全且 timestamp 是数字
+ *   2. 时间窗：|now - timestamp| <= toleranceMs（挡住过期报文）
+ *   3. appId 能查到 secret（未知 appId 与「签名错」返回同一文案，避免暴露哪些 appId 存在）
+ *   4. nonce 去重（可选）
+ *   5. HMAC 比对（定长时间安全比较，防时序侧信道）
+ */
+export async function verifySignedRequest(input: VerifyInput): Promise<VerifyResult> {
+  const sig = readSignedBody(input.body);
+  if (!sig) {
+    return { ok: false, code: 401, reason: "缺少签名要素（提交数据需带 appId / timestamp / sign）" };
+  }
+  if (input.requireNonce && !sig.nonce) return { ok: false, code: 401, reason: "缺少签名要素 nonce" };
+  if (input.requireBody && input.body == null) {
+    return { ok: false, code: 401, reason: "缺少请求体" };
+  }
+
+  const now = Number.isFinite(input.now) ? Number(input.now) : Date.now();
+  const toleranceMs = input.toleranceMs ?? DEFAULT_TOLERANCE_MS;
+  if (Math.abs(now - sig.timestamp * 1000) > toleranceMs) {
+    return { ok: false, code: 401, reason: "签名已过期或时间戳偏差过大" };
+  }
+
+  let resolved: string | OpenSecretBundle | null = null;
+  try {
+    resolved = await input.resolveSecret(sig.appId);
+  } catch {
+    resolved = null;
+  }
+  const secret = typeof resolved === "string" ? resolved : (resolved?.secret ?? null);
+  const whiteList = typeof resolved === "string" ? null : (resolved?.whiteList ?? null);
+  const blackList = typeof resolved === "string" ? null : (resolved?.blackList ?? null);
+  if (!secret) {
+    return { ok: false, code: 401, reason: "签名校验失败：无效的调用凭据" };
+  }
+
+  if (input.seenNonce && sig.nonce) {
+    try {
+      if (await input.seenNonce(sig.nonce)) {
+        return { ok: false, code: 403, reason: "请求已被处理过（重放）" };
+      }
+    } catch {
+      // nonce 存储故障：按「没有记录」处理，宁可放过也不因中间件故障误杀合法调用
+    }
+  }
+
+  // 传原样报文即可：buildSignBase 内部会剔除四项要素，与调用方签名时的口径逐字节一致
+  const expect = signRequest(secret, {
+    method: input.method,
+    path: input.path,
+    timestamp: sig.timestamp,
+    nonce: sig.nonce,
+    body: input.body,
+  });
+
+  if (!safeEqual(expect, sig.sign)) {
+    return { ok: false, code: 401, reason: "签名校验失败：无效的调用凭据" };
+  }
+  if (input.allowedAppIds && !input.allowedAppIds.includes(sig.appId)) {
+    return { ok: false, code: 403, reason: `调用方未获准访问此入口：appId=${sig.appId}` };
+  }
+  // 命令白/黑名单放通：合法调用方进一步受限于其白/黑名单。
+  const cmd = extractCmd(input.body);
+  if (!isCommandAllowed(cmd, whiteList, blackList)) {
+    return { ok: false, code: 403, reason: "调用方无权执行该命令（被白/黑名单拒绝）" };
+  }
+  return { ok: true, appId: sig.appId };
+}
+
+/** 定长时间安全比较：避免通过响应耗时逐字节猜签名 */
+function safeEqual(a: string, b: string): boolean {
+  const ba = Buffer.from(String(a ?? ""), "utf8");
+  const bb = Buffer.from(String(b ?? ""), "utf8");
+  if (ba.length === 0 || bb.length === 0 || ba.length !== bb.length) return false;
+  try {
+    return timingSafeEqual(ba, bb);
+  } catch {
+    return false;
+  }
+}
+
+/** 从请求体取出 cmd（开放通道的调用命令，如 "order.list"）；取不到返回空串 */
+function extractCmd(body: unknown): string {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const c = (body as Record<string, unknown>).cmd;
+    if (typeof c === "string") return c;
+    if (typeof c === "number") return String(c);
+  }
+  return "";
+}
+
+/**
+ * 命令放通判定（基于开放应用表的 J_白名单 / J_黑名单）。
+ * 规则：
+ *   - 黑名单优先：命中即拒绝（黑名单 "*" 表示全部拒绝）；
+ *   - 白名单为空 / NULL：不限制（全部允许）；
+ *   - 白名单命中（含 "*"）：允许；否则拒绝。
+ */
+export function isCommandAllowed(
+  cmd: string,
+  whiteList?: string[] | null,
+  blackList?: string[] | null,
+): boolean {
+  if (matchAny(cmd, blackList)) return false; // 黑名单命中即拒绝
+  if (!whiteList || whiteList.length === 0) return true; // 白名单空 = 不限制
+  return matchAny(cmd, whiteList);
+}
+
+function matchAny(cmd: string, list?: string[] | null): boolean {
+  if (!list || list.length === 0) return false;
+  return list.some((p) => matchPattern(cmd, p));
+}
+
+/** 单条模式匹配：支持 "*"（全部）、"prefix.*"（前缀）、精确串 */
+function matchPattern(cmd: string, pattern: string): boolean {
+  const p = String(pattern ?? "").trim();
+  if (!p) return false;
+  if (p === "*") return true;
+  if (p.endsWith(".*")) return cmd.startsWith(p.slice(0, -2));
+  return cmd === p;
+}
+
+/** body 摘要：SHA-256（不是 HMAC —— 摘要不需要密钥，用标准 hash 才能让其它语言原样复现） */
+function sha256Hex(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.