@yixinshuke/node-auth 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,21 @@
-{
-  "name": "@yixinshuke/node-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@yixinshuke/node-auth",
+  "version": "0.1.0",
+  "description": "登录态 JWT 签发/验签 + 开放通道 HMAC 验签 + Fastify 鉴权中间件（双轨 JWT 设计）",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "verify": "node --import tsx scripts/verify-sign.ts",
+    "test": "node --import tsx --test scripts/verify-open-command.ts",
+    "pub": "npm publish --access public",
+    "pub:dry": "npm publish --access public --dry-run"
+  },
+  "license": "MIT"
+}

package/src/auth-context.ts

@@ -0,0 +1,280 @@
+import { bearerOf, parseCookies, ACCESS_TOKEN_COOKIE, setAuthCookie, clearAuthCookie, setRefreshCookie, clearRefreshCookie, verifyTokenDom, setTokenCookieNames } from "./jwt.js";
+import { isPublicPrefix } from "./config.js";
+
+/**
+ * 鉴权中间件（Fastify 应用级 hook）—— **强制鉴权** + 把「可信身份」原样注入请求体。
+ *
+ * 通用化设计：本包**不认识**任何宿主的业务表列名。要强写哪些字段、叫什么名字，
+ * 完全由调用方在 `AuthHookOptions.forceWriteFields` 数组里声明；每个已鉴权请求，
+ * 本包把 **token payload 中同名 key 原样拷进请求体、覆盖客户端传值**（「服务端只信令牌、防越权冒充」的落点）。
+ *
+ * 例：`forceWriteFields = ["I_用户Id","I_代理Id","I_商户Id"]` →
+ *     token 须携带 `{"I_用户Id":1,"I_代理Id":2,"I_商户Id":3,...}`，本包原样写入 body 这三个字段。
+ *     字段数量/名称/语义全部由调用方决定，本包零硬编码列名、可通用。
+ *
+ * 规则（**fail-closed**）：
+ *   1. 免鉴权路径（`isPublicPath`）→ 放行；
+ *   2. 其余 `/api/*` 必须带**有效** access 令牌：缺令牌 / 无效 / 过期 / 非 access → 401；
+ *   3. 校验链抛错 → **503 拒绝**，绝不放行（无法确认身份时放行 = 安全漏洞）。
+ *
+ * 令牌来源：优先 `Authorization: Bearer <token>`；兼容请求体 `token` / `accessToken`；最后 HttpOnly Cookie。
+ */
+
+
+
+/**
+ * 服务调用身份（`/open`、`/callback` 这类「appId + 签名」通道专用）。
+ *
+ * 与人用登录态（JWT 强写）的区别：没有账号、没有租户、没有操作员。
+ * 租户由调用方在提交数据里显式指定并被签名保护，服务端不再强写。
+ */
+export interface ServiceIdentity {
+  /** 调用方应用标识（一个 appId 对应一把独立 secret，可单独吊销/轮换） */
+  appId: string;
+}
+
+/**
+ * 路径是否命中某条服务通道前缀（精确匹配或以 `前缀/` 开头）。
+ * 导出是为了让宿主/测试能复用同一套匹配语义，避免各自写 startsWith 走偏。
+ */
+export function isServicePath(path: string, prefixes: string[]): boolean {
+  const p = String(path ?? "");
+  return (prefixes ?? []).some((x) => {
+    const s = String(x ?? "").trim();
+    if (!s) return false;
+    if (p === s || p.startsWith(s + "/")) return true;
+    // 面板/契约的紧凑形式也必须纳入同一保护：<prefix>.json / <prefix>.skill
+    // 否则它们会掉进 isPublicPath 的「不是 /api 开头就算公开」分支，把接口清单直接裸奔出去。
+    return p === `${s}.json` || p === `${s}.skill`;
+  });
+}
+
+export interface AuthHookOptions {
+  /**
+   * **强写字段名数组（通用化核心）**：声明本服务要把 token 里哪些字段「原样拷进请求体、覆盖客户端传值」。
+   * 字段数量与名称完全由调用方决定，本包不硬编码任何业务列名。
+   *
+   * 每个已鉴权请求，本包读取 token payload 中**同名 key**，写入 `body[字段名]`（客户端伪造无效）。
+   * 例：`["I_用户Id","I_代理Id","I_商户Id"]` → token 须携带这三个 key，原样写入 body。
+   * 服务通道（`/open`、`/callback`）下这些字段统一置 0（中性），并标 `role="service"`。
+   */
+  forceWriteFields: string[];
+  /**
+   * 服务调用通道的 URL 前缀（如 `["/open", "/callback"]`）。
+   * 命中即改走 `resolveService` 验签：**不要求 JWT**，且**不注入用户身份**（身份由调用方在提交数据指定并签名保护）。
+   * 不配置则该能力完全关闭，行为与旧版逐字节一致。
+   */
+  servicePrefixes?: string[];
+  /**
+   * 服务通道验签器：成功返回服务身份，失败返回 null。
+   * 宿主通常用它自己拼装 request-sign 的 `verifySignedRequest`。
+   */
+  resolveService?: (req: any) => Promise<ServiceIdentity | null>;
+  /** 大屏观测端点 /_sys 是否需授权（默认 false 公开） */
+  obsRequireAuth?: boolean;
+  /**
+   * 是否启用「令牌双轨」Cookie 同步（默认 true）：认证成功响应（cmd 以 `auth/` 开头）在出网前
+   * 种 HttpOnly Cookie（`accessToken`），使地址栏 GET（调试面板）也能自动携带；登出（`ok:true`）清 Cookie。
+   * 逻辑与身份注入同属认证能力，一并在此注册，宿主只需调 `registerAuthHook` 一行。
+   */
+  cookieSync?: boolean;
+  /**
+   * 调试面板 GET 公开开关（默认 false）：
+   *  - true（开发/测试环境）：所有 `/api/*` 的 GET（模块面板页 / 文档 .json / .skill / 批量脚本）一律公开，便于地址栏直接调试；
+   *  - false（生产环境）：所有 `/api/*` GET 强制鉴权（杜绝接口结构裸奔；已登录面板经 Bearer 头拉取，不影响使用）。
+   * POST 命令派发始终强制鉴权，与此开关无关。由宿主按 `config.env !== "prod"` 注入。
+   */
+  publicApiGet?: boolean;
+  /**
+   * refresh / device 的 Cookie 名覆盖（默认 `refreshToken` / `deviceToken`）：
+   * 用于同源多服务（如 1dl→`dl*`、2sh→`sh*`）区分 Cookie 名，避免跨服务串号。未配置则保持默认，对其它服务无影响。
+   */
+  refreshCookieName?: string;
+  deviceCookieName?: string;
+}
+
+/**
+ * 系统观测端点分两类（双出口），与业务模块（/api/<module>）完全分离：
+ *   - /api/_sys/*  —— node-apirouter 内部出口，供调试面板自给（**始终公开**）。
+ *   - /_sys/*      —— 宿主对外出口，供大屏聚合（默认公开；obsRequireAuth=true 时走令牌鉴权）。
+ *   - /api/<module> 业务接口：生产环境全部强制鉴权（含 GET）；**开发/测试环境**所有 `/api/*` 的 GET
+ *     （面板页/文档/契约/批量脚本）一律公开（便于地址栏调试），POST 派发始终强制鉴权。由 `allowPublicApiGet` 控制。
+ */
+/** 调试面板 GET 公开开关：由 registerAuthHook 按环境注入（dev/test=true，prod=false） */
+let allowPublicApiGet = false;
+
+export function isPublicPath(method: string, url: string, cmd: string, obsRequireAuth = false): boolean {
+  const path = String(url ?? "").split("?")[0];
+  const m = String(method ?? "GET").toUpperCase();
+
+  // 大屏观测对外出口：默认公开；requireAuth 时落到下方令牌鉴权（不在此放行）
+  if (path.startsWith("/_sys")) return !obsRequireAuth;
+  // 非 /api 且非 /_sys：静态大屏、`/health` 等
+  if (!path.startsWith("/api")) return true;
+  // node-apirouter 内部观测出口：调试面板用，始终公开
+  if (path.startsWith("/api/_sys")) return true;
+  // 只匹配认证模块本身、子路径及文档；authorization 等同名前缀的业务模块必须正常鉴权并注入身份。
+  if (/^\/api\/auth(?:\/|$|\.(?:json|skill(?:\.md)?|batch\.json)$)/.test(path)) return true;
+  // 调试面板文档/契约（.json/.skill）与地址栏 GET /api/*：仅开发/测试环境公开（allowPublicApiGet），
+  // 生产环境不放行 —— 所有 /api/* 的 GET 强制鉴权（杜绝接口结构裸奔；已登录面板经 Bearer 头拉取，不影响使用）。
+  if (allowPublicApiGet && /^\/api\/[^/]+\.(json|skill)$/.test(path)) return true; // 模块文档/契约
+  if (allowPublicApiGet && m === "GET" && path.startsWith("/api/")) return true; // 面板页/批量脚本等
+  if (path === "/api" || path === "/api/") {
+    // GET /api = 调试面板页面；POST /api = 面板派发（全名 cmd）
+    return m !== "POST" || String(cmd ?? "").startsWith("auth/");
+  }
+  // 宿主注入的免鉴权白名单（增量放行，仅用于真正公开的端点）
+  if (isPublicPrefix(path)) return true;
+  return false;
+}
+
+export function registerAuthHook(app: any, opts: AuthHookOptions): void {
+  const obsRequireAuth = opts.obsRequireAuth ?? false;
+  // 调试面板 GET 公开开关：dev/test 放开 GET 便于地址栏调试；prod 强制 GET 鉴权
+  allowPublicApiGet = opts.publicApiGet === true;
+  // refresh/device Cookie 名按服务覆盖（如 1dl→dl*、2sh→sh*），避免跨服务串号
+  setTokenCookieNames(opts.refreshCookieName, opts.deviceCookieName);
+  // 服务调用通道前缀：不传即退化成纯 JWT 模式，对既有服务零影响
+  const svcPrefixes = (opts.servicePrefixes ?? []).map((p) => String(p).trim()).filter(Boolean);
+  // 强写字段名（通用化核心）：数量/名称由调用方声明，本包零硬编码业务列名
+  const forceWriteFields = (opts.forceWriteFields ?? []).map((f) => String(f).trim()).filter(Boolean);
+  app.addHook("preValidation", async (request: any, reply: any) => {
+    // CORS 预检(OPTIONS)不参与鉴权：按规范浏览器发预检时**不携带任何凭据**
+    // （既无 Authorization 头也无 Cookie），若在此要求令牌，跨源业务请求会卡在预检 401。
+    // 预检能否放行交由 CORS 来源白名单决定（未命中则不回 CORS 头，浏览器自行拦截）。
+    if (String(request.method ?? "").toUpperCase() === "OPTIONS") return;
+    const req = request as any;
+    const body: any = req.body;
+    const cmd = body && typeof body === "object" ? String(body.cmd ?? "") : "";
+
+    // 统一解析令牌：优先 Bearer 头 → 请求体 token/accessToken → HttpOnly Cookie（地址栏 GET 自动携带）；
+    // Bearer（头或体）优先于 Cookie，冲突以 Bearer 为准。
+    const header = (request.headers as any)?.authorization;
+    let token = header
+      ? bearerOf(header)
+      : body && typeof body === "object"
+        ? bearerOf(body.accessToken)
+        : "";
+    if (!token) {
+      const cookies = parseCookies((request.headers as any)?.cookie);
+      token = cookies[ACCESS_TOKEN_COOKIE] ?? "";
+    }
+    // 把解析出的令牌回写 body.accessToken（让头/体/Cookie 三种调用方式被业务 handler 一致识别；auth 模块各 cmd
+    // 只能从请求体读 token 的坑——调试面板把 token 放在 Authorization 头，中间件若不回写，handler 会误判「未登录」）。
+    // 此回写只动 accessToken 字段，绝不动 I_商户Id（auth 模块的 I_商户Id 语义是「目标商户」，由业务自行解析）。
+    if (body && typeof body === "object" && token) body.accessToken = token;
+
+    // 统一拒绝出口（提前到此处定义：服务通道分支在 isPublicPath 之前，也要用它）
+    // 统一拒绝出口：与 apirouter 信封保持一致 —— **HTTP 恒 200**，业务结论由 body.result 表达。
+    // 401 → 未登录（前端按 result 跳登录/静默续期）；5xx → 异常（鉴权基础设施故障，需告警）；其余 → 错误。
+    // ⚠️ 不再用 HTTP 401/503 表达业务结论：HTTP 码只表示「请求有没有拿到信封」。
+    const deny = (code: number, message: string) => {
+      const result = code >= 500 ? "异常" : code === 401 ? "未登录" : "错误";
+      return reply
+        .code(200)
+        .send({ cmd, result, error: message, time: 0, requestId: String(req.id ?? "") }) as any;
+    };
+
+    // —— 服务调用通道（appId + 签名）：必须**先于** isPublicPath 判断 ——
+    //    因为 isPublicPath 里有一条「不是 /api 开头就算公开」的规则（原本是给静态资源/健康检查用的），
+    //    /open 与 /callback 若走那条规则会被直接放行变成裸奔接口。
+    const reqPath = String(req.url ?? "").split("?")[0];
+    if (isServicePath(reqPath, svcPrefixes)) {
+      // 只读文档直接放行：面板页 / `.json` 契约 / `.skill` 说明书 —— 等价于开放平台的在线文档，
+      // 浏览器必须能直接打开，调用方也靠它查参数。**只有产生副作用的写请求才验签。**
+      const verb = String(req.method ?? "GET").toUpperCase();
+      if (verb === "GET" || verb === "HEAD" || verb === "OPTIONS") return;
+      try {
+        const svc = opts.resolveService ? await opts.resolveService(req) : null;
+        if (!svc) return deny(401, "服务调用鉴权失败：AppId 或签名无效");
+        // 挂到 request 上，供 apirouter 装载器透传给业务 handler 的 ctx.service（绕过 zod strip）
+        (req as any).__service = { appId: String(svc.appId ?? "") };
+        if (body && typeof body === "object") {
+          // 服务通道**不注入用户身份**：所有强写字段置 0（中性，表示「无登录用户」），并标 role=service
+          // 以示机器签名调用——业务 handler 据此区分「人登录态」与「机器调用」。字段名跟随 forceWriteFields，本包零硬编码。
+          for (const f of forceWriteFields) body[f] = 0;
+          body.role = "service";
+          // 调用者身份标记（service 通道）：dom=service，供 handler 统一判定 Machine 调用
+          body.__auth = { dom: "service" };
+        }
+        return;
+      } catch (e) {
+        // fail-closed：验签链路异常（密钥库不可用等）无法确认身份 → 拒绝，绝不放行
+        console.error("[auth] 服务调用鉴权异常，已拒绝请求：", (e as Error).message);
+        return deny(503, "鉴权服务暂不可用，请稍后重试");
+      }
+    }
+
+    if (isPublicPath(String(req.method ?? ""), String(req.url ?? ""), cmd, obsRequireAuth)) return;
+
+    try {
+      if (!token) return deny(401, "未登录：请在 Authorization 头（Bearer）或请求体传 token");
+
+      const v = verifyTokenDom(token);
+      // 仅接受正式 access 令牌；pre 预登录票据（用于选商户）不可当业务令牌用
+      if (!v || v.payload.typ !== "access") return deny(401, "登录已过期或令牌无效，请重新登录");
+      const payload = v.payload;
+      const dom = v.dom;
+
+      if (body && typeof body === "object") {
+        // 通用强写：token payload 中同名 key 原样覆盖客户端传值，防冒充（本包不识任何业务列名）
+        for (const f of forceWriteFields) body[f] = payload[f];
+        // 调用者身份全集（dom + 全部载荷声明）：业务 handler 据此区分 partner/merchant/service，
+        // 并取级别链（I_伙伴级别1~6编号）等做数据范围过滤。服务端强写，客户端伪造的 __auth 会被覆盖。
+        body.__auth = { ...payload, dom };
+      }
+    } catch (e) {
+      // fail-closed：鉴权校验链异常（如 DB 不可用）无法确认身份 → 拒绝，绝不放行
+      console.error("[auth] 身份校验异常，已拒绝请求：", (e as Error).message);
+      return deny(503, "鉴权服务暂不可用，请稍后重试");
+    }
+  });
+  // 令牌双轨 Cookie 同步（默认开）：认证响应种/清 HttpOnly Cookie，地址栏 GET 自动携带。
+  // 与上面的身份注入同属认证能力，一并在此注册，宿主只需调 registerAuthHook 一行。
+  if (opts.cookieSync !== false) registerAuthCookieSync(app);
+}
+
+/**
+ * 令牌双轨同步：登录 / 选商户 / 切换 / 续期成功时，响应体已返回 token（前端存 localStorage 走 Bearer 头），
+ * 这里再把它种进 HttpOnly Cookie，使**地址栏 GET（如调试面板 /api/<module>）也能自动携带、被鉴权中间件识别**——
+ * 从而同时满足「/api/* 全部强制鉴权」与「面板页可访问」。登出成功则清 Cookie。
+ *
+ * 与 registerAuthHook 配合：钩子仅对 `auth/*` 的成功响应生效（读响应体 data.accessToken），
+ * 不侵入业务逻辑、不改 service 签名；Bearer + Cookie 任一带上即通过。
+ */
+export function registerAuthCookieSync(app: any): void {
+  if (!app || typeof app.addHook !== "function") return;
+  app.addHook("onSend", async (_request: any, reply: any, payload: any) => {
+    // payload 可能是字符串（已序列化）或对象（apirouter 派发多为对象），两种情况都处理
+    let body: any = payload;
+    if (typeof payload === "string") {
+      try {
+        body = JSON.parse(payload);
+      } catch {
+        return payload;
+      }
+    } else if (payload === null || typeof payload !== "object") {
+      return payload;
+    }
+    // 只处理认证模块的响应：cmd 形如 `auth/登录` 或带命名空间 `api/auth/登录`，
+    // 用「含 auth 段」匹配，兼容命名空间前缀（旧写法 startsWith("auth/") 在带前缀时永远不命中）
+    if (!String(body?.cmd ?? "").split("/").includes("auth")) return payload;
+    // access 唯一字段名 `accessToken`（旧字段名 `token` 已作废，不保留回落 ——
+    // 原则二：开发阶段不做向后兼容，改名即干净落地）。命中后种入 HttpOnly Cookie，
+    // 供地址栏 GET（调试面板 /api/<module>）自动携带。
+    const tok = body?.data?.accessToken ?? body?.accessToken;
+    if (tok) {
+      setAuthCookie(reply, String(tok));
+      // 刷新令牌同样双轨同步：登录 / 选代理商 / 切换 / 续期 等认证响应只要带了 refreshToken，
+      // 就把它种进 HttpOnly Cookie（Path 锁定 /api/auth 认证模块），浏览器在该模块下请求自动携带，防 XSS 偷 refreshToken。
+      const rft = body?.data?.refreshToken ?? body?.refreshToken;
+      if (rft) setRefreshCookie(reply, String(rft));
+      return payload;
+    }
+    if (body?.data?.ok === true || body?.ok === true) {
+      clearAuthCookie(reply);
+      clearRefreshCookie(reply);
+    }
+    return payload;
+  });
+}

package/src/config.ts

@@ -0,0 +1,144 @@
+/**
+ * 鉴权配置注入点（替代原 node-server 的 config.jwt）。
+ *
+ * 包不读环境变量，由宿主在启动时调用 `configureAuth({ privateKey, publicKey })` 注入——
+ * 这样包自身不依赖任何宿主的 config 模块，可被各服务各自注入各自的密钥。
+ *
+ * ## RS256 职责分离（这是选用非对称签名的唯一理由）
+ *   - **签发方**（有登录入口的后台，如商户/代理商后台）：注入 `privateKey` + `publicKey`；
+ *   - **验签方**（无登录入口的对外服务，如支付/会员/收银）：**只注入 `publicKey`**。
+ *     公钥只能验签不能签发 ⇒ 即便该服务被攻破，攻击者也无法伪造其它域的令牌。
+ *
+ * 对照 HS256：所有节点共用一把既能签又能验的密钥，任一节点沦陷即可伪造全局令牌。
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+let privateKey = "";
+let publicKey = "";
+/** 验签公钥集合（多域）；单 `publicKey` 也会规整成 `[{pem, dom:"merchant"}]` 存于此 */
+let verifyEntries: Array<{ pem: string; dom: string }> = [];
+let accessTtlMs = 30 * 60 * 1000;
+let preTtlMs = 5 * 60 * 1000;
+let refreshTtlMs = 7 * 24 * 60 * 60 * 1000;
+/** 免鉴权路径白名单（宿主在启动时注入） */
+let publicPrefixes: string[] = [];
+
+export interface AuthConfigInput {
+  /** PEM 私钥（RS256 签发用）。可传 PEM 内容，也可传 `.pem` 文件路径；环境变量里的 `\n` 会自动还原为真换行 */
+  privateKey?: string;
+  /** PEM 公钥（RS256 验签用）。同上 */
+  publicKey?: string;
+  /**
+   * 多公钥验签（新增）：一个服务要信任多个签发域时（例如商户后台既要验本域 merchant 令牌、
+   * 又要验代理商域 partner 令牌），传此数组，每项标注 `dom`（调用域，如 `"partner"` / `"merchant"`）。
+   * `verifyTokenDom` 逐把试签，返回命中公钥对应的 `dom`。
+   * 与旧版单 `publicKey` 互斥：传了 `publicKeys` 即以它为准（单 `publicKey` 等价于 `[{pem, dom:"merchant"}]`）。
+   */
+  publicKeys?: Array<{ pem: string; dom?: string }>;
+  /** access 有效期（默认 30 分钟） */
+  accessTtlMs?: number;
+  /** 预登录票据有效期（默认 5 分钟） */
+  preTtlMs?: number;
+  /** refresh 有效期（默认 7 天） */
+  refreshTtlMs?: number;
+  /**
+   * 免鉴权路径白名单（增量放行，不影响既有规则）。
+   * 仅用于把「真正公开」的端点（如联调测试接口 `/api/test`）加入放行列表；
+   * 切勿把业务接口（如 `/api/partner`）放入，否则等于将其降权为公开。
+   */
+  publicPrefixes?: string[];
+}
+
+/**
+ * 归一化为 PEM 内容：
+ *   - 空值 → ""；
+ *   - 是存在的文件路径（含路径分隔符 / 以 .pem 结尾且磁盘上存在）→ 读文件内容；
+ *   - 否则视为 PEM 文本，并把环境变量常见的字面 `\n` 还原为真换行。
+ */
+function resolvePem(v: string | undefined): string {
+  const s = String(v ?? "").trim();
+  if (!s) return "";
+  const looksLikePath = /[\\/]/.test(s) || /\.pem$/i.test(s);
+  if (looksLikePath) {
+    try {
+      if (existsSync(s)) return readFileSync(s, "utf8").trim();
+    } catch {
+      /* 读不到就按 PEM 内容处理 */
+    }
+  }
+  return s.includes("\\n") ? s.replace(/\\n/g, "\n") : s;
+}
+
+/**
+ * 密钥版本号：每次**重新注入密钥**就自增。
+ * `jwt.ts` 缓存 KeyObject 时比对版本号，配置一变就重建 —— 否则「运行期换密钥」会被旧缓存静默吞掉。
+ */
+let keyVersion = 0;
+
+export function configureAuth(opts: AuthConfigInput): void {
+  if (opts.privateKey !== undefined) {
+    privateKey = resolvePem(opts.privateKey);
+    keyVersion++;
+  }
+  if (opts.publicKeys !== undefined) {
+    // 多域验签：每项解析 PEM 并标 dom（缺省 "merchant" 兼容旧语义）
+    verifyEntries = opts.publicKeys.map((k) => ({ pem: resolvePem(k.pem), dom: k.dom ?? "merchant" }));
+    keyVersion++;
+  } else if (opts.publicKey !== undefined) {
+    publicKey = resolvePem(opts.publicKey);
+    verifyEntries = [{ pem: publicKey, dom: "merchant" }];
+    keyVersion++;
+  }
+  if (opts.accessTtlMs !== undefined) accessTtlMs = opts.accessTtlMs;
+  if (opts.preTtlMs !== undefined) preTtlMs = opts.preTtlMs;
+  if (opts.refreshTtlMs !== undefined) refreshTtlMs = opts.refreshTtlMs;
+  if (opts.publicPrefixes !== undefined) publicPrefixes = opts.publicPrefixes;
+}
+
+/** 当前密钥版本号（供 jwt.ts 判断缓存是否过期） */
+export function keyVersionOf(): number {
+  return keyVersion;
+}
+
+/** 当前免鉴权白名单（供 isPublicPath 使用） */
+export function getPublicPrefixes(): string[] {
+  return publicPrefixes;
+}
+
+/** 路径是否命中免鉴权白名单（精确匹配或以 前缀/ 开头） */
+export function isPublicPrefix(path: string): boolean {
+  return publicPrefixes.some((p) => path === p || path.startsWith(p + "/"));
+}
+
+export const authConfig = {
+  get privateKey() {
+    return privateKey;
+  },
+  get publicKey() {
+    return publicKey;
+  },
+  /** 验签公钥集合（含各自 dom）；`verifyToken` / `verifyTokenDom` 据此逐把试签 */
+  get verifyEntries() {
+    return verifyEntries;
+  },
+  get accessTtlMs() {
+    return accessTtlMs;
+  },
+  get preTtlMs() {
+    return preTtlMs;
+  },
+  get refreshTtlMs() {
+    return refreshTtlMs;
+  },
+};
+
+/** 能否签发令牌（是否持有私钥）—— 只有登录方才应为 true */
+export function canSign(): boolean {
+  return Boolean(privateKey);
+}
+
+/** 能否验签（是否持有公钥）—— 验签方至少要有公钥，否则所有令牌都会判定无效 */
+export function canVerify(): boolean {
+  return Boolean(publicKey);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./jwt.js";
+export * from "./openSecret.js";
+export * from "./auth-context.js";
+export * from "./request-sign.js";
+export { configureAuth, authConfig, canSign, canVerify } from "./config.js";
+export type { AuthConfigInput } from "./config.js";
+export * from "./permissions.js";