@longzai-intelligence-auth/express 0.0.5 → 0.0.7

package/dist/index.d.ts

@@ -3,89 +3,160 @@ import { AccessTokenPayload, IdentityAuthBackend, LoggerService, RateLimiterPort
 import { NextFunction, Request, RequestHandler, Response } from "express";
 
 //#region src/core/error-mapper.d.ts
-/** 根据 DomainError 类型映射 HTTP 状态码 */
+/**
+ * 根据 DomainError 类型映射 HTTP 状态码
+ *
+ * @param error - 需要映射的领域错误实例
+ *
+ * @returns 对应的 HTTP 状态码
+ */
 declare function mapDomainErrorToStatus(error: DomainError): number;
 //#endregion
 //#region src/types/express-auth.types.d.ts
 /**
  * 扩展 Express Request，附加认证信息
  */
-interface AuthRequest extends Request {
-  /** 认证载荷 */
+type AuthRequest = {
+  /**
+   * 认证载荷
+   */
   auth: AccessTokenPayload;
-  /** 租户 ID */
+  /**
+   * 租户 ID
+   */
   tenantId: string;
-  /** 客户端 IP */
+  /**
+   * 客户端 IP
+   */
   clientIp?: string;
-  /** 限流剩余配额 */
+  /**
+   * 限流剩余配额
+   */
   rateLimitRemaining?: number;
-}
+} & Request;
 /**
  * JWT 验证中间件配置
  */
 type JwtVerifyMiddlewareOptions = {
-  /** 令牌验证器端口实例（用户注入） */verifier: TokenVerifierPort; /** 默认租户 ID */
+  /**
+   * 令牌验证器端口实例（用户注入）
+   */
+  verifier: TokenVerifierPort;
+  /**
+   * 默认租户 ID
+   */
   defaultTenantId?: string;
 };
 /**
  * RBAC 中间件配置
  */
 type RbacMiddlewareOptions = {
-  /** 令牌验证器端口实例（用户注入） */verifier: TokenVerifierPort; /** 默认租户 ID */
+  /**
+   * 令牌验证器端口实例（用户注入）
+   */
+  verifier: TokenVerifierPort;
+  /**
+   * 默认租户 ID
+   */
   defaultTenantId?: string;
 };
 /**
  * 租户中间件配置
  */
 type TenantMiddlewareOptions = {
-  /** 默认租户 ID */defaultTenantId?: string; /** 认证后端适配器 */
+  /**
+   * 默认租户 ID
+   */
+  defaultTenantId?: string;
+  /**
+   * 认证后端适配器
+   */
   adapter?: IdentityAuthBackend;
 };
 /**
  * 限流中间件配置
  */
 type RateLimitMiddlewareOptions = {
-  /** 速率限制器端口实例（用户注入） */limiter: RateLimiterPort; /** 日志服务 */
-  logger?: LoggerService; /** 限流键生成器 */
+  /**
+   * 速率限制器端口实例（用户注入）
+   */
+  limiter: RateLimiterPort;
+  /**
+   * 日志服务
+   */
+  logger?: LoggerService;
+  /**
+   * 限流键生成器
+   */
   keyGenerator?: (req: Request) => string;
 };
 /**
  * 日志中间件配置
  */
 type LoggerMiddlewareOptions = {
-  /** 日志服务 */logger: LoggerService;
+  /**
+   * 日志服务
+   */
+  logger: LoggerService;
 };
 /**
  * 错误处理中间件配置
  */
 type ErrorHandlerMiddlewareOptions = {
-  /** 日志服务 */logger?: LoggerService;
+  /**
+   * 日志服务
+   */
+  logger?: LoggerService;
 };
 /**
  * 基础预设配置
  */
 type BasicPresetOptions = {
-  /** 令牌验证器端口实例（用户注入） */tokenVerifier: TokenVerifierPort; /** 默认租户 ID */
-  defaultTenantId?: string; /** 日志服务 */
+  /**
+   * 令牌验证器端口实例（用户注入）
+   */
+  tokenVerifier: TokenVerifierPort;
+  /**
+   * 默认租户 ID
+   */
+  defaultTenantId?: string;
+  /**
+   * 日志服务
+   */
   logger?: LoggerService;
 };
 /**
  * 标准预设配置
  */
 type StandardPresetOptions = {
-  /** 令牌验证器端口实例（用户注入） */tokenVerifier: TokenVerifierPort; /** 速率限制器端口实例（用户注入） */
-  rateLimiter: RateLimiterPort; /** 默认租户 ID */
-  defaultTenantId?: string; /** 认证后端适配器 */
-  adapter: IdentityAuthBackend; /** 日志服务 */
+  /**
+   * 令牌验证器端口实例（用户注入）
+   */
+  tokenVerifier: TokenVerifierPort;
+  /**
+   * 速率限制器端口实例（用户注入）
+   */
+  rateLimiter: RateLimiterPort;
+  /**
+   * 默认租户 ID
+   */
+  defaultTenantId?: string;
+  /**
+   * 认证后端适配器
+   */
+  adapter: IdentityAuthBackend;
+  /**
+   * 日志服务
+   */
   logger?: LoggerService;
 };
 //#endregion
 //#region src/middlewares/jwt-verify.middleware.d.ts
 /**
  * 创建 JWT 验证中间件，从 Authorization Bearer 头提取令牌并验证
+ *
  * @param options - 中间件配置选项
- * @param options.verifier - 令牌验证器端口实例（用户注入）
- * @param options.defaultTenantId - 默认租户 ID
+ *
  * @returns Express 中间件函数
  */
 declare function createJwtVerifyMiddleware(options: JwtVerifyMiddlewareOptions): (req: Request, _res: Response, next: NextFunction) => Promise<void>;
@@ -93,9 +164,9 @@ declare function createJwtVerifyMiddleware(options: JwtVerifyMiddlewareOptions):
 //#region src/middlewares/rbac.middleware.d.ts
 /**
  * 创建 RBAC 权限检查中间件，验证请求是否拥有指定权限
+ *
  * @param options - 中间件配置选项
- * @param options.verifier - 令牌验证器端口实例（用户注入）
- * @param options.defaultTenantId - 默认租户 ID
+ *
  * @returns 返回一个函数，接收权限字符串并返回 Express 中间件
  */
 declare function createRbacMiddleware(options: RbacMiddlewareOptions): (permission: string) => (req: Request, _res: Response, next: NextFunction) => Promise<void>;
@@ -103,22 +174,27 @@ declare function createRbacMiddleware(options: RbacMiddlewareOptions): (permissi
 //#region src/middlewares/tenant.middleware.d.ts
 /**
  * 创建租户中间件，从 x-tenant-id 头提取租户 ID 并验证租户状态
+ *
+ * @param options - 中间件配置选项
+ *
+ * @returns Express 中间件函数
  */
 declare function createTenantMiddleware(options?: TenantMiddlewareOptions): (req: Request, _res: Response, next: NextFunction) => Promise<void>;
 //#endregion
 //#region src/middlewares/rate-limit.middleware.d.ts
 /**
  * 默认限流键生成器，从请求中提取客户端 IP
+ *
  * @param req - Express 请求对象
+ *
  * @returns 客户端 IP 地址
  */
 declare function defaultKeyGenerator(req: Request): string;
 /**
  * 创建限流中间件，基于 IP + 路径进行限流
+ *
  * @param options - 中间件配置选项
- * @param options.limiter - 速率限制器端口实例（用户注入）
- * @param options.logger - 日志服务（可选）
- * @param options.keyGenerator - 限流键生成器（可选）
+ *
  * @returns Express 中间件函数
  */
 declare function createRateLimitMiddleware(options: RateLimitMiddlewareOptions): (req: Request, _res: Response, next: NextFunction) => Promise<void>;
@@ -126,18 +202,27 @@ declare function createRateLimitMiddleware(options: RateLimitMiddlewareOptions):
 //#region src/middlewares/logger.middleware.d.ts
 /**
  * 创建日志中间件，记录请求、响应和错误日志
+ *
+ * @param options - 中间件配置选项
+ *
+ * @returns Express 中间件函数
  */
 declare function createLoggerMiddleware(options: LoggerMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
 //#endregion
 //#region src/middlewares/error-handler.middleware.d.ts
 /**
  * 创建错误处理中间件，捕获 DomainError 并映射为 HTTP 状态码响应
+ *
+ * @param options - 中间件配置选项
+ *
+ * @returns Express 错误处理中间件函数
  */
 declare function createErrorHandlerMiddleware(options?: ErrorHandlerMiddlewareOptions): (error: Error, req: Request, res: Response, _next: NextFunction) => void;
 //#endregion
 //#region src/presets/basic-preset.d.ts
 /**
  * 创建基础预设中间件集合，包含 JWT 验证和错误处理
+ *
  * @param options - 预设配置选项
  * @param options.tokenVerifier - 令牌验证器端口实例（用户注入）
  * @param options.defaultTenantId - 默认租户 ID（可选）
@@ -149,6 +234,7 @@ declare function createBasicPreset(options: BasicPresetOptions): RequestHandler[
 //#region src/presets/standard-preset.d.ts
 /**
  * 创建标准预设中间件集合，包含 JWT 验证、RBAC、租户、限流和错误处理
+ *
  * @param options - 预设配置选项
  * @param options.tokenVerifier - 令牌验证器端口实例（用户注入）
  * @param options.rateLimiter - 速率限制器端口实例（用户注入）
@@ -160,11 +246,23 @@ declare function createBasicPreset(options: BasicPresetOptions): RequestHandler[
 declare function createStandardPreset(options: StandardPresetOptions): RequestHandler[];
 //#endregion
 //#region src/utils/extract-client-ip.d.ts
-/** 从请求中提取客户端 IP 地址 */
+/**
+ * 从请求中提取客户端 IP 地址
+ *
+ * @param req - Express 请求对象
+ *
+ * @returns 客户端 IP 地址，如果无法提取则返回 undefined
+ */
 declare function extractClientIp(req: Request): string | undefined;
 //#endregion
 //#region src/utils/extract-user-agent.d.ts
-/** 从请求中提取用户代理 */
+/**
+ * 从请求中提取用户代理
+ *
+ * @param req - Express 请求对象
+ *
+ * @returns 用户代理字符串，如果不存在则返回 undefined
+ */
 declare function extractUserAgent(req: Request): string | undefined;
 //#endregion
 export { type AuthRequest, type BasicPresetOptions, type ErrorHandlerMiddlewareOptions, type JwtVerifyMiddlewareOptions, type LoggerMiddlewareOptions, type RateLimitMiddlewareOptions, type RbacMiddlewareOptions, type StandardPresetOptions, type TenantMiddlewareOptions, createBasicPreset, createErrorHandlerMiddleware, createJwtVerifyMiddleware, createLoggerMiddleware, createRateLimitMiddleware, createRbacMiddleware, createStandardPreset, createTenantMiddleware, defaultKeyGenerator, extractClientIp, extractUserAgent, mapDomainErrorToStatus };

package/dist/index.js

@@ -1 +1 @@
-import{AuthenticationError as e,DomainError as t,DuplicateEntityError as n,isBusinessRuleError as r,isConcurrencyError as i,isEntityNotFoundError as a,isPermissionDeniedError as o,isValidationError as s}from"@longzai-intelligence/error";import{AccountDisabledError as c,InvalidCredentialsError as l,MfaRequiredError as u,RateLimitExceededError as d,TokenExpiredError as f,TokenInvalidError as p,TokenMissingError as m}from"@longzai-intelligence-auth/core";function h(t){return s(t)?400:t instanceof f||t instanceof p||t instanceof m||t instanceof u||t instanceof l||t instanceof c||t instanceof e?401:o(t)?403:a(t)?404:t instanceof n?409:t instanceof d?429:i(t)?409:r(t)?422:500}function g(e){let{verifier:t,defaultTenantId:n=`default`}=e;return async(e,r,i)=>{try{let r=e,a=e.headers.authorization,o=typeof a==`string`&&a.startsWith(`Bearer `)?a.slice(7):null;if(!o)throw new m;let s=await t.verifyAccessToken(o);if(!s.success||!s.payload)throw new p(s.error);let c=s.payload;r.auth=c,r.tenantId=c.tenantId??n,i()}catch(e){i(e)}}}function _(){return{extractRolesFromPayload(e){return{userId:e.sub,tenantId:e.tenantId,roles:e.roles??[]}},hasRole(e,t){return(e.roles??[]).includes(t)},hasAnyRole(e,t){let n=e.roles??[];return t.some(e=>n.includes(e))},hasPermission(e,t,n){let r=e.permissions??[],i=`${t}:${n}`;return!!(r.includes(i)||r.includes(`${t}:*`)||r.includes(`*:${n}`)||r.includes(`*:*`))},hasAnyPermission(e,t){let n=e.permissions??[];return t.some(e=>{let t=`${e.resource}:${e.action}`;return!!(n.includes(t)||n.includes(`${e.resource}:*`)||n.includes(`*:${e.action}`)||n.includes(`*:*`))})}}}function v(e){let{verifier:t,defaultTenantId:n=`default`}=e,r=_();return e=>async(i,a,o)=>{try{let a=i,s=i.headers.authorization,c=typeof s==`string`&&s.startsWith(`Bearer `)?s.slice(7):null;if(!c)throw new m;let l=await t.verifyAccessToken(c);if(!l.success||!l.payload)throw new p(l.error);let u=l.payload;a.auth=u,a.tenantId=u.tenantId??n;let[d,f]=e.split(`:`);if(!d||!f)throw Error(`无效的权限格式: ${e}，应为 resource:action`);if(!r.hasPermission(u,d,f)){let{PermissionDeniedError:e}=await import(`@longzai-intelligence/error`);throw new e(d,f)}o()}catch(e){o(e)}}}function y(e={}){let{defaultTenantId:t=`default`,adapter:n}=e;return async(e,r,i)=>{try{let r=e,a=e.headers[`x-tenant-id`]??t;if(r.tenantId=a,n&&a!==t&&!(await n.tenant.validateStatus(a)).valid){let{PermissionDeniedError:e}=await import(`@longzai-intelligence/error`);throw new e(`tenant`,`access`)}i()}catch(e){i(e)}}}function b(e){return e.headers[`x-forwarded-for`]?.split(`,`)[0]?.trim()??e.headers[`x-real-ip`]??e.ip??`unknown`}function x(e){let{limiter:t,logger:n}=e,r=e.keyGenerator??b;return async(e,i,a)=>{try{let i=e,o=r(e);i.clientIp=o;let s=e.path,c=`${o}:${s}`,l=await t.checkLimit(c);if(!l.allowed)throw n?.warn(`限流触发`,{clientIp:o,path:s}),new d;i.rateLimitRemaining=l.remaining,a()}catch(e){a(e)}}}function S(e){let{logger:t}=e;return(e,n,r)=>{let i=Date.now();t.info(`${e.method} ${e.originalUrl}`),n.on(`finish`,()=>{let r=Date.now()-i;t.info(`${e.method} ${e.originalUrl} ${n.statusCode} ${r}ms`)}),n.on(`error`,n=>{t.error(`${e.method} ${e.originalUrl} 请求错误`,{error:n instanceof Error?n.message:String(n)})}),r()}}function C(e={}){let{logger:n}=e;return(e,r,i,a)=>{if(e instanceof t){let t=h(e);i.status(t).json({code:e.code,message:e.message,...e.context&&Object.keys(e.context).length>0?{details:e.context}:{}});return}n?.error(`未预期的错误`,{error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0}),i.status(500).json({code:`INTERNAL_ERROR`,message:`服务器内部错误`})}}function w(e){return[g({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId}),C({logger:e.logger})]}function T(e){let t=v({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId});return[g({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId}),t(`*:*`),y({defaultTenantId:e.defaultTenantId,adapter:e.adapter}),x({limiter:e.rateLimiter,logger:e.logger}),C({logger:e.logger})]}function E(e){return e.headers[`x-forwarded-for`]?.split(`,`)[0]?.trim()??e.headers[`x-real-ip`]??e.ip??void 0}function D(e){return e.headers[`user-agent`]??void 0}export{w as createBasicPreset,C as createErrorHandlerMiddleware,g as createJwtVerifyMiddleware,S as createLoggerMiddleware,x as createRateLimitMiddleware,v as createRbacMiddleware,T as createStandardPreset,y as createTenantMiddleware,b as defaultKeyGenerator,E as extractClientIp,D as extractUserAgent,h as mapDomainErrorToStatus};
+import{AuthenticationError as e,DomainError as t,DuplicateEntityError as n,isBusinessRuleError as r,isConcurrencyError as i,isEntityNotFoundError as a,isPermissionDeniedError as o,isValidationError as s}from"@longzai-intelligence/error";import{AccountDisabledError as c,InvalidCredentialsError as l,MfaRequiredError as u,RateLimitExceededError as d,TokenExpiredError as f,TokenInvalidError as p,TokenMissingError as m}from"@longzai-intelligence-auth/core";function h(t){return s(t)?400:t instanceof f||t instanceof p||t instanceof m||t instanceof u||t instanceof l||t instanceof c||t instanceof e?401:o(t)?403:a(t)?404:t instanceof n?409:t instanceof d?429:i(t)?409:r(t)?422:500}function g(e){let{verifier:t,defaultTenantId:n=`default`}=e;async function r(e,r,i){try{let r=e,a=e.headers.authorization,o=typeof a==`string`&&a.startsWith(`Bearer `)?a.slice(7):null;if(!o)throw new m;let s=await t.verifyAccessToken(o);if(!s.success||!s.payload)throw new p(s.error);let c=s.payload;r.auth=c,r.tenantId=c.tenantId??n,i()}catch(e){i(e)}}return r}function _(){return{extractRolesFromPayload(e){return{userId:e.sub,tenantId:e.tenantId,roles:e.roles??[]}},hasRole(e,t){return(e.roles??[]).includes(t)},hasAnyRole(e,t){let n=e.roles??[];return t.some(e=>n.includes(e))},hasPermission(e,t,n){let r=e.permissions??[],i=`${t}:${n}`;return!!(r.includes(i)||r.includes(`${t}:*`)||r.includes(`*:${n}`)||r.includes(`*:*`))},hasAnyPermission(e,t){let n=e.permissions??[];return t.some(e=>{let t=`${e.resource}:${e.action}`;return!!(n.includes(t)||n.includes(`${e.resource}:*`)||n.includes(`*:${e.action}`)||n.includes(`*:*`))})}}}function v(e){let{verifier:t,defaultTenantId:n=`default`}=e,r=_();function i(e){async function i(i,a,o){try{let a=i,s=i.headers.authorization,c=typeof s==`string`&&s.startsWith(`Bearer `)?s.slice(7):null;if(!c)throw new m;let l=await t.verifyAccessToken(c);if(!l.success||!l.payload)throw new p(l.error);let u=l.payload;a.auth=u,a.tenantId=u.tenantId??n;let[d,f]=e.split(`:`);if(!d||!f)throw Error(`无效的权限格式: ${e}，应为 resource:action`);if(!r.hasPermission(u,d,f)){let{PermissionDeniedError:e}=await import(`@longzai-intelligence/error`);throw new e(d,f)}o()}catch(e){o(e)}}return i}return i}function y(e={}){let{defaultTenantId:t=`default`,adapter:n}=e;async function r(e,r,i){try{let r=e,a=e.headers[`x-tenant-id`]??t;if(r.tenantId=a,n&&a!==t&&!(await n.tenant.validateStatus(a)).valid){let{PermissionDeniedError:e}=await import(`@longzai-intelligence/error`);throw new e(`tenant`,`access`)}i()}catch(e){i(e)}}return r}function b(e){return e.headers[`x-forwarded-for`]?.split(`,`)[0]?.trim()??e.headers[`x-real-ip`]??e.ip??`unknown`}function x(e){let{limiter:t,logger:n}=e,r=e.keyGenerator??b;async function i(e,i,a){try{let i=e,o=r(e);i.clientIp=o;let s=e.path,c=`${o}:${s}`,l=await t.checkLimit(c);if(!l.allowed)throw n?.warn(`限流触发`,{clientIp:o,path:s}),new d;i.rateLimitRemaining=l.remaining,a()}catch(e){a(e)}}return i}function S(e){let{logger:t}=e;return(e,n,r)=>{let i=Date.now();t.info(`${e.method} ${e.originalUrl}`),n.on(`finish`,()=>{let r=Date.now()-i;t.info(`${e.method} ${e.originalUrl} ${n.statusCode} ${r}ms`)}),n.on(`error`,n=>{t.error(`${e.method} ${e.originalUrl} 请求错误`,{error:n instanceof Error?n.message:String(n)})}),r()}}function C(e={}){let{logger:n}=e;return(e,r,i,a)=>{if(e instanceof t){let t=h(e);i.status(t).json({code:e.code,message:e.message,...e.context&&Object.keys(e.context).length>0?{details:e.context}:{}});return}n?.error(`未预期的错误`,{error:e instanceof Error?e.message:String(e),stack:e instanceof Error?e.stack:void 0}),i.status(500).json({code:`INTERNAL_ERROR`,message:`服务器内部错误`})}}function w(e){return[g({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId}),C({logger:e.logger})]}function T(e){let t=v({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId});return[g({verifier:e.tokenVerifier,defaultTenantId:e.defaultTenantId}),t(`*:*`),y({defaultTenantId:e.defaultTenantId,adapter:e.adapter}),x({limiter:e.rateLimiter,logger:e.logger}),C({logger:e.logger})]}function E(e){return e.headers[`x-forwarded-for`]?.split(`,`)[0]?.trim()??e.headers[`x-real-ip`]??e.ip??void 0}function D(e){return e.headers[`user-agent`]??void 0}export{w as createBasicPreset,C as createErrorHandlerMiddleware,g as createJwtVerifyMiddleware,S as createLoggerMiddleware,x as createRateLimitMiddleware,v as createRbacMiddleware,T as createStandardPreset,y as createTenantMiddleware,b as defaultKeyGenerator,E as extractClientIp,D as extractUserAgent,h as mapDomainErrorToStatus};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longzai-intelligence-auth/express",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -24,7 +24,7 @@
     "directory": "packages/express"
   },
   "dependencies": {
-    "@longzai-intelligence-auth/core": "0.0.5",
+    "@longzai-intelligence-auth/core": "0.0.7",
     "@longzai-intelligence/error": "^0.0.5"
   },
   "peerDependencies": {
@@ -49,6 +49,6 @@
     "test:coverage": "bun test --coverage",
     "test:unit": "bun test src/__tests__/unit/",
     "test:integration": "bun test src/__tests__/integration/",
-    "clean": "rm -rf dist out .cache"
+    "clean": "rimraf dist out .cache"
   }
 }