@yixinshuke/node-auth 0.0.0-stage → 0.1.0

package/src/jwt.ts

@@ -0,0 +1,346 @@
+import {
+  randomUUID,
+  sign as cryptoSign,
+  verify as cryptoVerify,
+  createPrivateKey,
+  createPublicKey,
+  type KeyObject,
+} from "node:crypto";
+import { authConfig, keyVersionOf } from "./config.js";
+
+/**
+ * 极简 RS256 JWT（零依赖，`node:crypto` 实现）—— 只服务本项目的登录态。
+ *
+ * 设计：`docs/操作员多商户登录设计.md` §5、`docs/JWT双轨鉴权设计.md` §2
+ *  - **无状态**：服务端不存 access token，只验签 + 验过期；撤销能力由「落库的 refresh token」承担；
+ *  - **不含门店/商户权限明细**：payload 只带当前租户 `mid`，权限每次请求现查（防 token 里的旧权限）；
+ *  - **RS256 非对称**：签发用私钥、验签用公钥（密钥由宿主 `configureAuth` 注入）。
+ *     只有「登录方」持有私钥，**验签方即便被攻破也无法伪造令牌**——这是选用非对称的唯一理由。
+ *
+ * 失败策略（**fail-closed**）：未配置公钥时无法验签 → 所有令牌判定无效，绝不放行。
+ */
+
+/** access / pre 票据的载荷 */
+export interface TokenPayload {
+  /** 账号编号（I_账号编号） */
+  sub: number;
+  /** 当前租户ID（pre 票据为 0）：商户后台=商户ID，代理商后台=代理商ID */
+  mid: number;
+  /** 操作员档案ID（pre 票据为 0） */
+  oid: number;
+  /** 是否管理员（快照，仅用于 UI 显隐；鉴权以库里为准） */
+  adm: 0 | 1;
+  /** access = 正式令牌；pre = 预登录票据（只能用于「选择商户」） */
+  typ: "access" | "pre";
+  iat: number;
+  exp: number;
+  jti: string;
+  /**
+   * 调用域（partner / merchant）：由签发方写入并随令牌签名，属冗余记录；
+   * 权威 dom 由 `verifyTokenDom` 按「命中哪把公钥」给出（签发方无法伪造域）。
+   */
+  dom?: string;
+  /**
+   * 宿主自定义声明（如 `I_用户Id` / `I_代理Id` / `I_商户Id`）：原样透传，
+   * 供鉴权中间件 `forceWriteFields` 按同名 key 拷回请求体。本包不约束其名称/数量。
+   */
+  [k: string]: unknown;
+}
+
+/** 多域验签结果：payload + 命中公钥的调用域 dom */
+export interface VerifiedToken {
+  /** 令牌载荷（标准 5 字段 + 宿主自定义声明） */
+  payload: TokenPayload;
+  /** 调用域：命中公钥标注的 dom（如 `"partner"` / `"merchant"`），由验签方确定、不可伪造 */
+  dom: string;
+}
+
+/** 签发入参（iat/exp/jti 由签发函数补）；除标准 5 字段外，可附带任意宿主自定义声明（会被写入 payload 顶层） */
+export type TokenInput = Pick<TokenPayload, "sub" | "mid" | "oid" | "adm" | "typ"> & {
+  [k: string]: unknown;
+};
+
+const JWT_ALG = "RS256";
+
+let cachedPriv: KeyObject | null = null;
+let cachedPrivVer = -1;
+/** 公钥缓存：按 pem + keyVersion 失效；多域各自一把 */
+let cachedPubs: Array<{ pem: string; key: KeyObject | null; ver: number }> = [];
+let warnedNoPub = false;
+
+/**
+ * 私钥（签发用）—— 未配置直接抛错：无法签发时静默降级等于放行伪造令牌。
+ * 缓存按 `keyVersionOf()` 失效：运行期重新注入密钥后立即生效，不会沿用旧 KeyObject。
+ */
+function privKey(): KeyObject {
+  const ver = keyVersionOf();
+  if (cachedPriv && cachedPrivVer === ver) return cachedPriv;
+  if (!authConfig.privateKey) {
+    throw new Error("[jwt] 未配置 RS256 私钥（JWT_PRIVATE_KEY），无法签发令牌");
+  }
+  cachedPriv = createPrivateKey(authConfig.privateKey);
+  cachedPrivVer = ver;
+  return cachedPriv;
+}
+
+/** 取验签公钥（按 pem + keyVersion 缓存；解析失败返回 null，调用方按「该域无法验签」跳过） */
+function pubFor(pem: string): KeyObject | null {
+  const ver = keyVersionOf();
+  const hit = cachedPubs.find((c) => c.pem === pem && c.ver === ver);
+  if (hit) return hit.key;
+  let k: KeyObject | null = null;
+  try {
+    k = createPublicKey(pem);
+  } catch {
+    k = null;
+  }
+  cachedPubs.push({ pem, key: k, ver });
+  return k;
+}
+
+/**
+ * 内部验签：逐把公钥试签，命中即返回 `{ payload, dom }`（dom 取命中公钥标注的调用域）。
+ * 失败（结构错 / alg 非 RS256 / 全部公钥都不匹配 / 过期 / 缺标准字段）一律返回 null（fail-closed）。
+ */
+function verifyInternal(token: unknown): VerifiedToken | null {
+  try {
+    const parts = String(token ?? "").trim().split(".");
+    if (parts.length !== 3) return null;
+    const [h, b, s] = parts;
+
+    // 先验 header 的算法声明：不是 RS256 一律拒绝（禁止 none / HS256 降级）
+    const header = JSON.parse(Buffer.from(h, "base64url").toString("utf8")) as { alg?: string };
+    if (header?.alg !== JWT_ALG) return null;
+
+    const entries = authConfig.verifyEntries;
+    if (!entries.length) {
+      if (!warnedNoPub) {
+        warnedNoPub = true;
+        console.warn(
+          "[jwt] 未配置 RS256 公钥（JWT_PUBLIC_KEY / publicKeys）：无法验签，所有令牌将判定为未登录（fail-closed）",
+        );
+      }
+      return null;
+    }
+
+    for (const entry of entries) {
+      const pub = pubFor(entry.pem);
+      if (!pub) continue; // 该域公钥解析失败 → 跳过试下一把
+      const okSig = cryptoVerify("sha256", Buffer.from(`${h}.${b}`), pub, Buffer.from(s, "base64url"));
+      if (!okSig) continue;
+      const payload = JSON.parse(Buffer.from(b, "base64url").toString("utf8")) as TokenPayload;
+      if (!payload || typeof payload.sub !== "number" || typeof payload.mid !== "number") return null;
+      if (Number(payload.exp) * 1000 <= Date.now()) return null;
+      return { payload, dom: entry.dom };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** 签发令牌（ttlMs 有效期毫秒） */
+export function signToken(input: TokenInput, ttlMs: number): string {
+  const now = Math.floor(Date.now() / 1000);
+  // ttl <= 0（或非法）→ 立即过期：调用方显式传 0 就是「签发即失效」，不做隐式下限兜底
+  const ttlSec = Number.isFinite(ttlMs) ? Math.floor(ttlMs / 1000) : 0;
+  const payload: TokenPayload = {
+    ...input,
+    iat: now,
+    exp: now + Math.max(0, ttlSec),
+    jti: randomUUID(),
+  };
+  const header = Buffer.from(JSON.stringify({ alg: JWT_ALG, typ: "JWT" })).toString("base64url");
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const signing = Buffer.from(`${header}.${body}`);
+  const sig = cryptoSign("sha256", signing, privKey()).toString("base64url");
+  return `${header}.${body}.${sig}`;
+}
+
+/**
+ * 校验令牌：失败一律返回 `null`（调用方决定是否 401）。
+ * 覆盖：结构、**alg 必须是 RS256**（防 alg 混淆攻击，如降级到 HS256 / none）、签名、过期。
+ */
+/**
+ * 验签（旧版兼容，只返回 payload）：单/多密钥均可验，dom 被忽略。
+ * 仍维持 fail-closed：无公钥 / 全部不匹配 / 过期 → null。
+ */
+export function verifyToken(token: unknown): TokenPayload | null {
+  return verifyInternal(token)?.payload ?? null;
+}
+
+/**
+ * 多域验签（新增）：返回 `payload` + 命中公钥的 `dom`（调用域）。
+ * 下游据此区分调用方身份：`dom === "partner"` 走伙伴域（前缀匹配 6 段级别链），
+ * `dom === "merchant"` 走商户域（单商户），`dom === "service"` 为机器签名通道。
+ */
+export function verifyTokenDom(token: unknown): VerifiedToken | null {
+  return verifyInternal(token);
+}
+
+/** 读取 JWT 的 exp（绝对 Unix 秒，不验签）；非法令牌返回 -1。供前端/调试面板判断 access 剩余有效时间。 */
+export function accessTokenExp(token: string): number {
+  try {
+    const p = JSON.parse(Buffer.from(String(token).split(".")[1] ?? "", "base64url").toString("utf8"));
+    return typeof p?.exp === "number" ? p.exp : -1;
+  } catch {
+    return -1;
+  }
+}
+
+/** 从 Authorization 头取值（兼容 `Bearer xxx` 与裸令牌） */
+export function bearerOf(header: unknown): string {
+  const s = String(header ?? "").trim();
+  return s.startsWith("Bearer ") ? s.slice(7).trim() : s;
+}
+
+/**
+ * 访问令牌 Cookie 名（与 Bearer 头并存：地址栏 GET 走 Cookie，API/脚本走 Bearer 头）。
+ * HttpOnly：JS 读不到，防 XSS 偷 token；SameSite=Lax：允许同站顶层 GET 导航携带
+ * （调试面板页 `GET /api/<module>` 因此可用），但挡掉跨站 POST（CSRF）。
+ * **Path 锁定 `/api`**：登录态只属于人用通道，`/open`、`/callback`（机器签名通道）、静态页与
+ * `/_sys` 观测端点都不会自动带上它——同一份报文里只存在一套身份，避免混着两套导致语义混乱。
+ */
+export const ACCESS_TOKEN_COOKIE = "accessToken";
+
+/** 手写解析 Cookie 头（避免引入 @fastify/cookie 依赖；本项目未注册该插件） */
+export function parseCookies(header: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  const s = String(header ?? "").trim();
+  if (!s) return out;
+  for (const part of s.split(";")) {
+    const idx = part.indexOf("=");
+    if (idx < 0) continue;
+    const k = part.slice(0, idx).trim();
+    const v = part.slice(idx + 1).trim();
+    if (k) out[k] = decodeURIComponent(v);
+  }
+  return out;
+}
+
+/** 是否 https 请求（决定是否加 Secure；本地 http 不加，否则 Cookie 不会被浏览器发送） */
+function isSecureReq(req: any): boolean {
+  if (String(req?.protocol ?? "").toLowerCase() === "https") return true;
+  return String(req?.headers?.["x-forwarded-proto"] ?? "").toLowerCase() === "https";
+}
+
+function cookieValue(token: string, maxAgeSec: number, secure: boolean): string {
+  const parts = [
+    `${ACCESS_TOKEN_COOKIE}=${encodeURIComponent(token)}`,
+    // Path 锁 `/api`：登录态只在人用通道自动携带（面板页 GET /api/<module> 靠它），
+    // /open、/callback（机器签名通道）与静态页一律不带——机器通道的身份只有 appId 签名一套。
+    "Path=/api",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${Math.max(0, Math.floor(maxAgeSec))}`,
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/**
+ * 种一个 Set-Cookie。
+ * ⚠️ 关键：Fastify 5 的 `reply.header("Set-Cookie", value)` 对同一名字是**追加**语义
+ * （传数组则把数组每个元素都追加进内部 set-cookie 列表，而非覆盖或一次性设多个）。
+ * 因此每到一个 Cookie 就调用一次标量 `reply.header("Set-Cookie", cookieStr)` 即可，
+ * 多个 Cookie 各自追加、互不覆盖。切勿先 `getHeader` 读回再数组合并重设——那会重复追加、造成重复 Set-Cookie。
+ */
+function appendSetCookie(reply: any, value: string): void {
+  if (!reply || typeof reply.header !== "function") return;
+  reply.header("Set-Cookie", value);
+}
+
+/** 在响应上种访问令牌 Cookie（供地址栏 GET 自动携带，被鉴权中间件识别） */
+export function setAuthCookie(reply: any, token: string): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, cookieValue(token, authConfig.accessTtlMs / 1000, secure));
+}
+
+/** 清除访问令牌 Cookie（登出时） */
+export function clearAuthCookie(reply: any): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, cookieValue("", 0, secure));
+}
+
+/**
+ * 刷新令牌 Cookie 名（默认 `refreshToken`，可由 `setTokenCookieNames` 按服务覆盖，如 1dl→`dlrefreshToken`）。
+ * 仅认证模块 `/api/auth` 自动携带（见下方 Path 锁定）——其余 /api/* 业务模块不会带，降低 refreshToken 暴露面。
+ */
+export let REFRESH_TOKEN_COOKIE = "refreshToken";
+
+/**
+ * 刷新 Cookie 值：**Path 锁定整个认证模块 `/api/auth`**（刷新命令 `续期` 是其中一员之一），
+ * 浏览器在该模块下所有请求（登录 / 选代理商 / 切换 / 续期 / 登出 等）自动带上 refreshToken，
+ * 但 `/api/partner`、`/api/account` 等业务模块绝不自动发送。HttpOnly：JS 读不到，防 XSS 偷 refreshToken；
+ * SameSite=Lax：挡跨站 POST（CSRF）；Secure：https 下才下发（本地 http 调试不加，否则 Cookie 不被发送）。
+ * Max-Age = refreshTtlMs（刷新令牌长期有效，与落库 TTL 对齐）。
+ */
+function refreshCookieValue(token: string, maxAgeSec: number, secure: boolean): string {
+  const parts = [
+    `${REFRESH_TOKEN_COOKIE}=${encodeURIComponent(token)}`,
+    "Path=/api/auth",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${Math.max(0, Math.floor(maxAgeSec))}`,
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/** 种刷新令牌 Cookie（仅专用刷新路由自动携带；与 access 的 setAuthCookie 对称） */
+export function setRefreshCookie(reply: any, token: string): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, refreshCookieValue(token, authConfig.refreshTtlMs / 1000, secure));
+}
+
+/** 清除刷新令牌 Cookie（登出 / 切换设备时） */
+export function clearRefreshCookie(reply: any): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, refreshCookieValue("", 0, secure));
+}
+
+// ── 设备令牌 Cookie（仅 /api/auth 自动携带）────────────────────────────────
+
+/**
+ * 设备令牌 Cookie 名（默认 `deviceToken`，可由 `setTokenCookieNames` 按服务覆盖，如 1dl→`dldeviceToken`）。Path 锁定整个认证模块 `/api/auth`：
+ * 浏览器在该模块下所有请求（登录 / 选代理商 / 切换 / 续期 / 我的设备 / 踢设备 / 登出）自动带上，
+ * 业务模块 `/api/partner` 等绝不自动发送，降低设备令牌暴露面。HttpOnly：JS 读不到，防 XSS 偷设备令牌；
+ * SameSite=Lax：挡跨站 POST；Secure：https 下才下发（本地 http 调试不加）。
+ * ⚠️ 与 refreshToken 同 Path：二者都只在认证链路使用。设备令牌由服务端在登录/选代理商时生成并种入，
+ * 前端不持有明文（不再经响应体下发），仅依赖浏览器自动携带。
+ */
+export let DEVICE_TOKEN_COOKIE = "deviceToken";
+
+/**
+ * 按宿主服务覆盖 refresh / device 的 Cookie 名（默认 `refreshToken` / `deviceToken`）。
+ * 由 `registerAuthHook` 在启动时注入，使同源多服务（如 1dl→`dl*`、2sh→`sh*`）可使用不同 Cookie 名，避免跨服务串号。
+ * 未注入的服务保持默认，对未配置的 3pay/4hy/5footpos 等无影响。
+ */
+export function setTokenCookieNames(refreshName?: string, deviceName?: string): void {
+  if (refreshName) REFRESH_TOKEN_COOKIE = refreshName;
+  if (deviceName) DEVICE_TOKEN_COOKIE = deviceName;
+}
+
+function deviceCookieValue(token: string, maxAgeSec: number, secure: boolean): string {
+  const parts = [
+    `${DEVICE_TOKEN_COOKIE}=${encodeURIComponent(token)}`,
+    "Path=/api/auth",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${Math.max(0, Math.floor(maxAgeSec))}`,
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/** 种设备令牌 Cookie（随登录/选代理商/切换/续期响应下发；仅 /api/auth 模块自动携带） */
+export function setDeviceCookie(reply: any, token: string): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, deviceCookieValue(token, authConfig.refreshTtlMs / 1000, secure));
+}
+
+/** 清除设备令牌 Cookie（登出 / 切换设备时） */
+export function clearDeviceCookie(reply: any): void {
+  const secure = isSecureReq(reply?.request);
+  appendSetCookie(reply, deviceCookieValue("", 0, secure));
+}

package/src/openSecret.ts

@@ -0,0 +1,137 @@
+/**
+ * 开放通道调用方 secret + 命令白/黑名单解析的**通用核心**（纯算法 + 缓存，不绑定任何业务库/表/列）。
+ *
+ * ## 为什么放 node-auth（而不是 5 个业务服务各复制一份）
+ * 解密 / 缓存 / 命令放通这套算法**完全相同**，单点维护避免「一起改容易不同步」。
+ *
+ * ## 通用组件的边界（重要）
+ * 本文件**不出现任何业务字段**（如 b_开放应用 / a_开放应用 / C_AppId / C_Secret / J_白名单）。
+ * 「查哪张表、哪些列、启用/删除标志」一律由调用方经 `query` 回调注入——
+ * 因为别人用 node-auth 时，表名/列名可能是任意样子，组件无法、也不该预设。
+ *
+ * ## 数据来源：只有一条路（DB，禁止旁路）
+ * secret **唯一**来源是「本域开放应用表」（C_Secret 密文，AES 解密）。
+ * 命令白/黑名单来自同表的 J_白名单 / J_黑名单（JSON 数组，NULL=不限制）。
+ * 不提供环境变量 / 密库等旁路兜底——避免多人协作时各服务接不同来源、行为不一致。
+ * query 查不到或解密失败，统一返回 null → 调用方验签拒绝（fail-closed，全失败即拒绝）。
+ *
+ * ## 用法
+ *   const resolve = createOpenSecretSource({
+ *     name: "b_开放应用",
+ *     query: async (appId) => {
+ *       const db = getShAuthDb();
+ *       if (!db) return null;
+ *       const r = await db.from("b_开放应用")
+ *         .where({ C_AppId: appId, I_删除: 0, I_启用: 1 })
+ *         .first(["C_Secret", "J_白名单", "J_黑名单"]);
+ *       const row = r?.row as any;
+ *       if (!row || !row.C_Secret) return null;
+ *       return {
+ *         secret: row.C_Secret,
+ *         whiteList: asStringArray(row.J_白名单),
+ *         blackList: asStringArray(row.J_黑名单),
+ *       };
+ *     },
+ *   });
+ *   resolve(appId) -> OpenSecretBundle | null   // 含 secret 明文 + 白/黑名单，供验签与命令放通
+ *
+ * 解密降级（数据格式容错，非「多来源」）：未注入密钥时若拿到密文则**原样返回**（兼容库内明文残留），不抛错；
+ * 命中后即写入进程内缓存（默认 60s），避免每请求查库。白/黑名单随 secret 一并缓存。
+ */
+
+/**
+ * 开放应用解析结果（secret 密文 + 命令白/黑名单）。
+ *
+ * `query` 回调从本域表取出的是库内 **C_Secret 密文** 与 **J_白名单/J_黑名单（JSON）**；
+ * 组件负责把 C_Secret 解密成明文、把 JSON 解析成字符串数组，最终交给验签与命令放通使用。
+ */
+export interface OpenSecretBundle {
+  /** 库内 C_Secret 密文（组件会按密钥就绪情况自动解密为明文）；为空视为未知调用方 */
+  secret: string;
+  /** 命令白名单（cmd 前缀数组）。空/NULL 表示不限制（全部允许） */
+  whiteList?: string[] | null;
+  /** 命令黑名单（cmd 前缀数组）。空/NULL 表示无黑名单 */
+  blackList?: string[] | null;
+}
+
+/**
+ * 把库里读出的「命令列表」字段归一化成 `string[] | null`。
+ * 兼容三种来源：JSON 数组（MySQL JSON 列原生）、JSON 字符串、旧式逗号串；空/NULL 返回 null。
+ * 由各服务 openSecret.ts 的 `query` 回调调用，避免 6 份接线各写一遍解析。
+ */
+export function asStringArray(v: unknown): string[] | null {
+  if (v == null) return null;
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  if (typeof v === "string") {
+    const s = v.trim();
+    if (!s) return null;
+    try {
+      const p = JSON.parse(s);
+      return Array.isArray(p) ? p.map((x) => String(x)) : [String(p)];
+    } catch {
+      // 兼容旧式逗号分隔串
+      const arr = s.split(",").map((x) => x.trim()).filter(Boolean);
+      return arr.length ? arr : null;
+    }
+  }
+  return null;
+}
+
+const buckets = new Map<string, Map<string, { bundle: OpenSecretBundle; ts: number }>>();
+
+function bucketOf(name: string): Map<string, { bundle: OpenSecretBundle; ts: number }> {
+  let b = buckets.get(name);
+  if (!b) {
+    b = new Map();
+    buckets.set(name, b);
+  }
+  return b;
+}
+
+export interface OpenSecretSourceOptions {
+  /** 标识：用于日志与缓存命名空间（建议传业务表名以便排查），可空。仅作标识，不参与查询。 */
+  name?: string;
+  /**
+   * 查库回调：传入 appId，返回 **OpenSecretBundle**（含 secret 密文 + 白/黑名单）或 null。
+   * 业务层在此决定表名 / 列名 / 启用删除标志（组件不预设）。
+   * 抛错被吞（视为 null），不让异常泄漏给调用方。
+   */
+  query: (appId: string) => Promise<OpenSecretBundle | null>;
+  /** 缓存 TTL（毫秒），默认 60000 */
+  ttlMs?: number;
+}
+
+export function createOpenSecretSource(
+  opts: OpenSecretSourceOptions,
+): (appId: string) => Promise<OpenSecretBundle | null> {
+  const ttl = opts.ttlMs ?? 60_000;
+  const bucket = bucketOf(opts.name ?? "open-secret");
+  const label = opts.name ?? "open-secret";
+
+  return async (appId: string): Promise<OpenSecretBundle | null> => {
+    const id = String(appId ?? "").trim();
+    if (!id) return null;
+    const now = Date.now();
+    const hit = bucket.get(id);
+    if (hit && now - hit.ts < ttl) return hit.bundle;
+
+    try {
+      const bundle = await opts.query(id);
+      if (bundle && bundle.secret && String(bundle.secret).trim()) {
+        // 密钥已由 shardorm C4（crypto:"encrypt" 列）在读路径透明解密，此处取到的即为明文
+        const secret = bundle.secret;
+        const b: OpenSecretBundle = {
+          secret: String(secret).trim(),
+          whiteList: bundle.whiteList ?? null,
+          blackList: bundle.blackList ?? null,
+        };
+        bucket.set(id, { bundle: b, ts: now });
+        return b;
+      }
+    } catch (e) {
+      // 查询失败：告警但不阻断（让验签走到 null → 拒绝），避免异常泄漏给调用方
+      console.warn(`[open] 查询 ${label} 失败(${id})：`, (e as Error)?.message ?? String(e));
+    }
+    return null;
+  };
+}

package/src/permissions.ts

@@ -0,0 +1,68 @@
+/** 跨服务权限协议。这里只处理目录、集合与 HTTP，不预设业务表或身份字段。 */
+export interface PermissionFeature {
+  code: string;
+  name: string;
+  group: string;
+  scope: "merchant" | "store";
+  requires: string[];
+}
+export interface PermissionCatalog {
+  system: string;
+  name: string;
+  version: string;
+  features: PermissionFeature[];
+}
+export interface PermissionRule {
+  scope: "商户" | "全部门店" | "分组" | "门店";
+  target: number | null;
+  system: string;
+  features: string[];
+}
+export function effectivePermissions(rules: PermissionRule[], storeId: number | null, ancestors: number[]): string[] {
+  const result = new Set<string>();
+  for (const rule of rules) {
+    const matches = storeId === null ? rule.scope === "商户" :
+      rule.scope === "全部门店" || rule.scope === "门店" && rule.target === storeId ||
+      rule.scope === "分组" && rule.target !== null && ancestors.includes(rule.target);
+    if (matches) for (const feature of rule.features) result.add(`${rule.system}:${feature}`);
+  }
+  return [...result].sort();
+}
+
+/** 包装模块注册，无需业务代码复制路由器或绕过 schema / 文档管线。 */
+export function guardCommandRouter<T extends { register: (...args: any[]) => any }>(
+  router: T,
+  guard: (command: string, raw: any, ctx: any, signal: AbortSignal | undefined, run: () => Promise<any>) => Promise<any>,
+): T {
+  return new Proxy(router, {
+    get(target, property) {
+      if (property === "register") return (command: string, options: unknown, handler: (...args: any[]) => any) =>
+        target.register(command, options, (raw: unknown, ctx: unknown, signal?: AbortSignal) =>
+          guard(command, raw, ctx, signal, () => Promise.resolve(handler(raw, ctx, signal))));
+      const value = Reflect.get(target, property);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+/** 转发用户的 Bearer；远端自行验签与解析身份，不接受调用方伪造账号。 */
+export async function callPermissionApi<T>(url: string, authorization: unknown, cmd: string, payload: unknown, signal?: AbortSignal): Promise<T> {
+  if (typeof authorization !== "string" || !/^Bearer\s+\S+$/i.test(authorization)) {
+    throw Object.assign(new Error("缺少有效登录凭据"), { statusCode: 401 });
+  }
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST", headers: { "content-type": "application/json", authorization },
+      body: JSON.stringify({ cmd, payload }),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(8000)]) : AbortSignal.timeout(8000),
+    });
+  } catch {
+    throw Object.assign(new Error("权限服务暂不可用，请稍后重试"), { statusCode: 503 });
+  }
+  if (!response.ok) throw Object.assign(new Error("权限服务请求失败"), { statusCode: 503 });
+  const body = await response.json() as { result?: string; data: T; error?: string };
+  if (body.result !== "成功") throw Object.assign(new Error(body.error || "权限校验未通过"), { statusCode: body.result === "未登录" ? 401 : 403 });
+  return body.data;
+}
+