@yixinshuke/node-auth 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yixinshuke/node-auth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "登录态 JWT 签发/验签 + 开放通道 HMAC 验签 + Fastify 鉴权中间件（双轨 JWT 设计）",
   "type": "module",
   "main": "src/index.ts",

package/src/auth-context.ts

@@ -1,5 +1,6 @@
 import { bearerOf, parseCookies, ACCESS_TOKEN_COOKIE, setAuthCookie, clearAuthCookie, setRefreshCookie, clearRefreshCookie, verifyTokenDom, setTokenCookieNames } from "./jwt.js";
 import { isPublicPrefix } from "./config.js";
+import { runWithAuditContext, setAuditRemark } from "./login-origin.js";
 
 /**
  * 鉴权中间件（Fastify 应用级 hook）—— **强制鉴权** + 把「可信身份」原样注入请求体。
@@ -33,6 +34,12 @@ export interface ServiceIdentity {
   appId: string;
 }
 
+/** 保留验签与授权的具体拒绝原因，避免被宿主统一压成“签名无效”。 */
+export interface ServiceAuthFailure {
+  code: number;
+  error: string;
+}
+
 /**
  * 路径是否命中某条服务通道前缀（精确匹配或以 `前缀/` 开头）。
  * 导出是为了让宿主/测试能复用同一套匹配语义，避免各自写 startsWith 走偏。
@@ -50,6 +57,10 @@ export function isServicePath(path: string, prefixes: string[]): boolean {
 }
 
 export interface AuthHookOptions {
+  /** 仅用已验签 JWT 生成审计备注，组件不预设业务字段。 */
+  auditRemarkOf?: (payload: Record<string, unknown>) => string;
+  /** 宿主可显式信任指定服务传递的审计备注；只记来源，不授予用户权限。 */
+  serviceAuditRemarkOf?: (service: ServiceIdentity, signedBody: any) => string;
   /**
    * **强写字段名数组（通用化核心）**：声明本服务要把 token 里哪些字段「原样拷进请求体、覆盖客户端传值」。
    * 字段数量与名称完全由调用方决定，本包不硬编码任何业务列名。
@@ -69,7 +80,7 @@ export interface AuthHookOptions {
    * 服务通道验签器：成功返回服务身份，失败返回 null。
    * 宿主通常用它自己拼装 request-sign 的 `verifySignedRequest`。
    */
-  resolveService?: (req: any) => Promise<ServiceIdentity | null>;
+  resolveService?: (req: any) => Promise<ServiceIdentity | ServiceAuthFailure | null>;
   /** 大屏观测端点 /_sys 是否需授权（默认 false 公开） */
   obsRequireAuth?: boolean;
   /**
@@ -129,6 +140,7 @@ export function isPublicPath(method: string, url: string, cmd: string, obsRequir
 }
 
 export function registerAuthHook(app: any, opts: AuthHookOptions): void {
+  app.addHook("onRequest", (_request: any, _reply: any, done: () => void) => runWithAuditContext(done));
   const obsRequireAuth = opts.obsRequireAuth ?? false;
   // 调试面板 GET 公开开关：dev/test 放开 GET 便于地址栏调试；prod 强制 GET 鉴权
   allowPublicApiGet = opts.publicApiGet === true;
@@ -187,6 +199,10 @@ export function registerAuthHook(app: any, opts: AuthHookOptions): void {
       try {
         const svc = opts.resolveService ? await opts.resolveService(req) : null;
         if (!svc) return deny(401, "服务调用鉴权失败：AppId 或签名无效");
+        if ("error" in svc) {
+          return deny(svc.code, `服务调用鉴权失败：path=${reqPath} cmd=${cmd} appId=${String(body?.appId ?? "")}；${svc.error}`);
+        }
+        setAuditRemark(opts.serviceAuditRemarkOf?.(svc, body) ?? "");
         // 挂到 request 上，供 apirouter 装载器透传给业务 handler 的 ctx.service（绕过 zod strip）
         (req as any).__service = { appId: String(svc.appId ?? "") };
         if (body && typeof body === "object") {
@@ -201,7 +217,7 @@ export function registerAuthHook(app: any, opts: AuthHookOptions): void {
       } catch (e) {
         // fail-closed：验签链路异常（密钥库不可用等）无法确认身份 → 拒绝，绝不放行
         console.error("[auth] 服务调用鉴权异常，已拒绝请求：", (e as Error).message);
-        return deny(503, "鉴权服务暂不可用，请稍后重试");
+        return deny(503, `服务调用鉴权异常：path=${reqPath} cmd=${cmd}；${(e as Error).message}`);
       }
     }
 
@@ -215,6 +231,7 @@ export function registerAuthHook(app: any, opts: AuthHookOptions): void {
       if (!v || v.payload.typ !== "access") return deny(401, "登录已过期或令牌无效，请重新登录");
       const payload = v.payload;
       const dom = v.dom;
+      setAuditRemark(opts.auditRemarkOf?.(payload) ?? "");
 
       if (body && typeof body === "object") {
         // 通用强写：token payload 中同名 key 原样覆盖客户端传值，防冒充（本包不识任何业务列名）

package/src/index.ts

@@ -5,3 +5,6 @@ export * from "./request-sign.js";
 export { configureAuth, authConfig, canSign, canVerify } from "./config.js";
 export type { AuthConfigInput } from "./config.js";
 export * from "./permissions.js";
+export * from "./open-client.js";
+export { loginOriginOf, splitDelegatedCredential, runWithAuditContext, setAuditRemark, getAuditRemark, appendAuditRemark, type LoginOrigin } from "./login-origin.js";
+export { withinDelegatedScope } from "./login-origin.js";

package/src/login-origin.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** 已验证的会话来源快照；不参与当前用户的授权。业务含义及备注由签发方提供。 */
+export interface LoginOrigin {
+  actorId: number;
+  actorLogin: string;
+  verifiedAt: number;
+  remark: string;
+}
+export function loginOriginOf(payload: any): LoginOrigin | undefined {
+  const o = payload?.loginOrigin;
+  return o && Number.isSafeInteger(o.actorId) && o.actorId > 0 && typeof o.actorLogin === "string"
+    && typeof o.verifiedAt === "number" && typeof o.remark === "string" ? o : undefined;
+}
+/** 只拆分，不尝试普通密码回落。账号格式由宿主检查。 */
+export function splitDelegatedCredential(password: string): { actorLogin: string; password: string } | null {
+  if (!password.includes("@")) return null;
+  const parts = password.split("@");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) throw new Error("代登录密码格式必须为：验证账号@密码，且只能包含一个 @");
+  return { actorLogin: parts[0], password: parts[1] };
+}
+/** 有效完整路径的前缀匹配；空路径和中间缺级均拒绝。 */
+export function withinDelegatedScope(target: number[], scopes: number[][], includeSelf: boolean): boolean {
+  const valid = (p: number[]) => p.length > 0 && p.length <= 6 && p.every(n => Number.isSafeInteger(n) && n > 0);
+  return valid(target) && scopes.some(p => valid(p) && (includeSelf ? target.length >= p.length : target.length > p.length)
+    && p.every((id, index) => target[index] === id));
+}
+
+const audit = new AsyncLocalStorage<{ remark: string }>();
+export function runWithAuditContext<T>(fn: () => T): T { return audit.run({ remark: "" }, fn); }
+export function setAuditRemark(remark: string): void { const ctx = audit.getStore(); if (ctx) ctx.remark = remark; }
+export function getAuditRemark(): string { return audit.getStore()?.remark ?? ""; }
+export function appendAuditRemark(existing: unknown, remark = getAuditRemark()): string {
+  return [String(existing ?? ""), remark].filter(Boolean).join("；");
+}

package/src/open-client.ts

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+import { attachSignature } from "./request-sign.js";
+import type { OpenSecretBundle } from "./openSecret.js";
+
+export interface OpenCallOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+}
+
+/** 只收口签名与报文派发，宿主注入应用身份、凭据查询和 HTTP 实现。 */
+export function createOpenClient(opts: {
+  appId: string;
+  resolveSecret: (appId: string) => Promise<OpenSecretBundle | null>;
+  allowHttp: boolean;
+  /** 宿主限定此客户端可调用的路径，防止业务误用其他模块协议。 */
+  paths?: readonly string[];
+  post: (url: string, body: Record<string, unknown>, options: OpenCallOptions) => Promise<unknown>;
+}) {
+  return async function callOpen<T = unknown>(url: string, body: Record<string, unknown>, options: OpenCallOptions = {}): Promise<T> {
+    const target = new URL(url);
+    if (target.username || target.password || target.search || target.hash || !/^\/open(?:\/|$)/.test(target.pathname)) {
+      throw new Error(`开放调用地址必须是不含凭据、查询串的 /open 路径：${target.origin}${target.pathname}`);
+    }
+    if (target.protocol !== "https:" && !(opts.allowHttp && target.protocol === "http:")) throw new Error("开放调用必须使用 HTTPS");
+    if (opts.paths && !opts.paths.includes(target.pathname)) throw new Error(`开放调用路径未授权：${target.pathname}`);
+    const credential = await opts.resolveSecret(opts.appId);
+    if (!credential?.secret) throw new Error(`开放调用凭据不存在或已停用：appId=${opts.appId}`);
+    // 签名基于实际 JSON 线上报文（剔除 undefined、归一 Date），避免发送端与接收端摘要不一致。
+    const wireBody = JSON.parse(JSON.stringify({ ...body, requestId: body.requestId || randomUUID() })) as Record<string, unknown>;
+    const signed = attachSignature(credential.secret, {
+      method: "POST", path: target.pathname, appId: opts.appId,
+      timestamp: Math.floor(Date.now() / 1000), nonce: randomUUID(), body: wireBody,
+    });
+    return await opts.post(target.toString(), signed, options) as T;
+  };
+}

package/src/request-sign.ts

@@ -174,6 +174,10 @@ export function attachSignature(
 }
 
 export interface VerifyInput {
+  /** 宿主指定此入口允许的调用方；不配置时按该模块原有协议授权。 */
+  allowedAppIds?: readonly string[];
+  /** 宿主可要求 nonce 必传，用于内部请求防重放。 */
+  requireNonce?: boolean;
   method: string;
   path: string;
   /**
@@ -221,6 +225,7 @@ export async function verifySignedRequest(input: VerifyInput): Promise<VerifyRes
   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: "缺少请求体" };
   }
@@ -266,7 +271,10 @@ export async function verifySignedRequest(input: VerifyInput): Promise<VerifyRes
   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: "调用方无权执行该命令（被白/黑名单拒绝）" };