@xlt-token/express 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,163 @@
+import * as express from "express";
+import { ErrorRequestHandler, Request, RequestHandler, Response } from "express";
+import { AuthResult, AuthResult as AuthResult$1, CookieOptions, CreateOptions, DEFAULT_XLT_TOKEN_CONFIG, DeviceInfo, HttpContext, HttpContext as HttpContext$1, JwtConfig, MemoryStore, NotLoginException, NotLoginType, NotPermissionException, NotRoleException, NotSafeException, StpInterface, StpLogic, StpPermLogic, StpUtil, TokenStrategy, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, XltHooks, XltMode, XltMode as XltMode$1, XltSession, XltTokenConfig, XltTokenConfig as XltTokenConfig$1, XltTokenContext, XltTokenContext as XltTokenContext$1, XltTokenStore, createMockHttpContext, createXltToken, matchPermission, setStpLogic, setStpPermLogic } from "@xlt-token/core";
+
+//#region src/context.d.ts
+interface ExpressLikeRequest {
+  _xltState?: Record<string, unknown>;
+}
+interface ExpressLikeResponse {
+  setHeader(name: string, value: string): void;
+  cookie(name: string, value: string, options?: unknown): void;
+}
+/**
+ * 将 Express `req` / `res` 适配为 core 的 `HttpContext`。
+ *
+ * `state` 复用挂在 `req._xltState` 上的请求级共享对象，使同一请求多次调用拿到同一引用。
+ */
+declare function createExpressContext(req: Request, res: Response): HttpContext$1;
+//#endregion
+//#region src/types.d.ts
+interface RouteAuthMeta {
+  ignore?: boolean;
+  requireLogin?: boolean;
+  permissions?: {
+    list: string[];
+    mode: XltMode$1;
+  };
+  roles?: {
+    list: string[];
+    mode: XltMode$1;
+  };
+  safeBusiness?: string;
+}
+type AuthMatcher = string | RegExp | ((req: express.Request) => boolean);
+interface RouteAuthPolicy extends RouteAuthMeta {
+  match: AuthMatcher | AuthMatcher[];
+  methods?: string[];
+}
+interface XltMiddlewareOptions {
+  /** 快捷白名单，会被转换为 { match, ignore: true } */
+  ignore?: AuthMatcher[];
+  /** 路由级鉴权策略。xltMiddleware 会在鉴权前解析这些规则。 */
+  policies?: RouteAuthPolicy[];
+}
+declare global {
+  namespace Express {
+    interface Request {
+      _xltState?: Record<string, unknown>;
+      _xltRouteMeta?: RouteAuthMeta;
+      stpLoginId?: string;
+      stpToken?: string;
+    }
+  }
+} //# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/middleware/xlt-middleware.d.ts
+/**
+ * 全局登录校验中间件。
+ *
+ * 执行流程：
+ * 1. `createExpressContext(req, res)`
+ * 2. `resolveRouteAuthMeta` → 写入 `req._xltRouteMeta`
+ * 3. `shouldCheckLogin` 判断是否需要校验，不需要则直接放行
+ * 4. `runAuth`（登录 + 权限 + 角色 + safe），成功后 `syncExpressAuthState`
+ * 5. 任意异常通过 `next(err)` 交给 `xltErrorHandler`
+ */
+declare function xltMiddleware(xlt: XltTokenContext$1, options?: XltMiddlewareOptions): RequestHandler;
+//#endregion
+//#region src/middleware/ignore-auth.d.ts
+/**
+ * 路由级 helper：标记当前路由忽略登录校验（黑名单模式下放行）。
+ *
+ * 仅写入 `req._xltRouteMeta`，因此必须在同一条 route chain 中位于 `xltMiddleware` 之前才有效。
+ * 推荐主路径仍是 `xltMiddleware` 的 `ignore` / `policies` 选项。
+ */
+declare function ignoreAuth(): RequestHandler;
+//#endregion
+//#region src/middleware/require-login.d.ts
+/**
+ * 路由级 helper：标记当前路由需要登录（白名单模式下开启校验）。
+ *
+ * 仅写入 `req._xltRouteMeta`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function requireLogin(): RequestHandler;
+//#endregion
+//#region src/middleware/check-permission.d.ts
+/**
+ * 路由级 helper：声明当前路由所需权限。
+ *
+ * 仅写入 `req._xltRouteMeta.permissions`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkPermission(permission: string | string[], mode?: XltMode$1): RequestHandler;
+//#endregion
+//#region src/middleware/check-role.d.ts
+/**
+ * 路由级 helper：声明当前路由所需角色。
+ *
+ * 仅写入 `req._xltRouteMeta.roles`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkRole(role: string | string[], mode?: XltMode$1): RequestHandler;
+//#endregion
+//#region src/middleware/check-safe.d.ts
+/**
+ * 路由级 helper：声明当前路由需要二级认证安全窗口。
+ *
+ * 仅写入 `req._xltRouteMeta.safeBusiness`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkSafe(business: string): RequestHandler;
+//#endregion
+//#region src/error/xlt-error-handler.d.ts
+/**
+ * 四参数 Express 错误中间件，挂在路由链末尾，将 core 鉴权异常转为 401/403 JSON。
+ * 非 xlt-token 异常透传给下一个错误处理器。
+ *
+ * @example
+ * app.use(xltErrorHandler());
+ */
+declare function xltErrorHandler(): ErrorRequestHandler;
+//#endregion
+//#region src/auth/run-auth.d.ts
+/**
+ * 编排登录 + 权限 + 角色 + 二级认证校验。
+ *
+ * 与 `XltTokenGuard.canActivate` 中的权限块逻辑等价：
+ * `checkLogin` 失败时抛出 `NotLoginException`，权限/角色/safe 校验失败时分别抛出对应异常。
+ */
+declare function runAuth(xlt: XltTokenContext$1, httpCtx: HttpContext$1, req: Request): Promise<AuthResult$1>;
+//#endregion
+//#region src/auth/should-check-login.d.ts
+/**
+ * 是否需要对当前请求执行登录校验。
+ *
+ * 与 NestJS `XltTokenGuard.requiresLogin` 行为一致：
+ * - 黑名单模式（`defaultCheck === true`）：除被 `ignore` 标记的路由外全部校验
+ * - 白名单模式（`defaultCheck === false`）：仅校验被 `requireLogin` 标记的路由
+ *
+ * 路由元数据由 `resolveRouteAuthMeta` 提前写入 `req._xltRouteMeta`。
+ */
+declare function shouldCheckLogin(req: Request, config: XltTokenConfig$1): boolean;
+//#endregion
+//#region src/auth/resolve-route-auth-meta.d.ts
+/**
+ * 解析当前请求命中的路由鉴权元数据。
+ *
+ * 在 `shouldCheckLogin` 和 `runAuth` 之前调用，使用 `req.originalUrl` 作为匹配目标，
+ * 避免 Router 嵌套时 `req.path` 丢失挂载前缀。
+ *
+ * 当多条策略同时命中时，后声明的策略覆盖前者的简单字段，并合并权限/角色列表，
+ * 因此用户可先声明 `/api` 默认策略，再声明 `/api/public` 例外。
+ */
+declare function resolveRouteAuthMeta(req: Request, options?: XltMiddlewareOptions): RouteAuthMeta;
+//#endregion
+//#region src/sync-state.d.ts
+/**
+ * 将鉴权成功后写入 `ctx.state` 的登录态同步到 Express `req` 上。
+ *
+ * core 在 `_resolveLoginId` 中写入 `ctx.state.stpLoginId` / `ctx.state.stpToken`，
+ * 这里对应同步到 `req.stpLoginId` / `req.stpToken`（与 NestJS Guard 字段命名一致）。
+ */
+declare function syncExpressAuthState(req: Request, ctx: HttpContext$1): void;
+//#endregion
+export { type AuthMatcher, type AuthResult, type CookieOptions, type CreateOptions, DEFAULT_XLT_TOKEN_CONFIG, type DeviceInfo, type ExpressLikeRequest, type ExpressLikeResponse, type HttpContext, type JwtConfig, MemoryStore, NotLoginException, NotLoginType, NotPermissionException, NotRoleException, NotSafeException, type RouteAuthMeta, type RouteAuthPolicy, type StpInterface, StpLogic, StpPermLogic, StpUtil, type TokenStrategy, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, type XltHooks, type XltMiddlewareOptions, XltMode, XltSession, type XltTokenConfig, type XltTokenContext, type XltTokenStore, checkPermission, checkRole, checkSafe, createExpressContext, createMockHttpContext, createXltToken, ignoreAuth, matchPermission, requireLogin, resolveRouteAuthMeta, runAuth, setStpLogic, setStpPermLogic, shouldCheckLogin, syncExpressAuthState, xltErrorHandler, xltMiddleware };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/context.ts","../src/types.ts","../src/middleware/xlt-middleware.ts","../src/middleware/ignore-auth.ts","../src/middleware/require-login.ts","../src/middleware/check-permission.ts","../src/middleware/check-role.ts","../src/middleware/check-safe.ts","../src/error/xlt-error-handler.ts","../src/auth/run-auth.ts","../src/auth/should-check-login.ts","../src/auth/resolve-route-auth-meta.ts","../src/sync-state.ts"],"mappings":";;;;;UAGiB,kBAAA;EACf,SAAA,GAAY,MAAA;AAAA;AAAA,UAGG,mBAAA;EACf,SAAA,CAAU,IAAA,UAAc,KAAA;EACxB,MAAA,CAAO,IAAA,UAAc,KAAA,UAAe,OAAA;AAAA;;AAFtC;;;;iBAUgB,oBAAA,CAAqB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,GAAW,aAAA;;;UCflD,aAAA;EACf,MAAA;EACA,YAAA;EACA,WAAA;IAAgB,IAAA;IAAgB,IAAA,EAAM,SAAA;EAAA;EACtC,KAAA;IAAU,IAAA;IAAgB,IAAA,EAAM,SAAA;EAAA;EAChC,YAAA;AAAA;AAAA,KAGU,WAAA,YAER,MAAA,KACE,GAAA,EADI,OAAA,CACmB,OAAA;AAAA,UAEZ,eAAA,SAAwB,aAAA;EACvC,KAAA,EAAO,WAAA,GAAc,WAAA;EACrB,OAAA;AAAA;AAAA,UAGe,oBAAA;EDXqB;ECapC,MAAA,GAAS,WAAA;EDb4C;ECerD,QAAA,GAAW,eAAA;AAAA;AAAA,QAWL,MAAA;EAAA,UACI,OAAA;IAAA,UACE,OAAA;MACR,SAAA,GAAY,MAAA;MACZ,aAAA,GAAgB,aAAA;MAChB,UAAA;MACA,QAAA;IAAA;EAAA;AAAA;;;;ADtCN;;;;;AAIA;;;;iBEcgB,aAAA,CACd,GAAA,EAAK,iBAAA,EACL,OAAA,GAAS,oBAAA,GACR,cAAA;;;;;;;AFrBH;;iBGKgB,UAAA,CAAA,GAAc,cAAA;;;;;;;AHL9B;iBIIgB,YAAA,CAAA,GAAgB,cAAA;;;;;;AJJhC;;iBKKgB,eAAA,CACd,UAAA,qBACA,IAAA,GAAM,SAAA,GACL,cAAA;;;;;;ALRH;;iBMKgB,SAAA,CAAU,IAAA,qBAAyB,IAAA,GAAM,SAAA,GAAwB,cAAA;;;;;;;ANLjF;iBOIgB,SAAA,CAAU,QAAA,WAAmB,cAAA;;;;;;;APJ7C;;;iBQOgB,eAAA,CAAA,GAAmB,mBAAA;;;;;;ARPnC;;;iBSMsB,OAAA,CACpB,GAAA,EAAK,iBAAA,EACL,OAAA,EAAS,aAAA,EACT,GAAA,EAAK,OAAA,GACJ,OAAA,CAAQ,YAAA;;;;;;ATVX;;;;;AAIA;iBUKgB,gBAAA,CAAiB,GAAA,EAAK,OAAA,EAAS,MAAA,EAAQ,gBAAA;;;;;;AVTvD;;;;;AAIA;iBWUgB,oBAAA,CACd,GAAA,EAAK,OAAA,EACL,OAAA,GAAS,oBAAA,GACR,aAAA;;;;;;AXjBH;;;iBYMgB,oBAAA,CAAqB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,aAAA"}

package/dist/index.d.mts

@@ -0,0 +1,163 @@
+import { AuthResult, AuthResult as AuthResult$1, CookieOptions, CreateOptions, DEFAULT_XLT_TOKEN_CONFIG, DeviceInfo, HttpContext, HttpContext as HttpContext$1, JwtConfig, MemoryStore, NotLoginException, NotLoginType, NotPermissionException, NotRoleException, NotSafeException, StpInterface, StpLogic, StpPermLogic, StpUtil, TokenStrategy, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, XltHooks, XltMode, XltMode as XltMode$1, XltSession, XltTokenConfig, XltTokenConfig as XltTokenConfig$1, XltTokenContext, XltTokenContext as XltTokenContext$1, XltTokenStore, createMockHttpContext, createXltToken, matchPermission, setStpLogic, setStpPermLogic } from "@xlt-token/core";
+import * as express from "express";
+import { ErrorRequestHandler, Request, RequestHandler, Response } from "express";
+
+//#region src/context.d.ts
+interface ExpressLikeRequest {
+  _xltState?: Record<string, unknown>;
+}
+interface ExpressLikeResponse {
+  setHeader(name: string, value: string): void;
+  cookie(name: string, value: string, options?: unknown): void;
+}
+/**
+ * 将 Express `req` / `res` 适配为 core 的 `HttpContext`。
+ *
+ * `state` 复用挂在 `req._xltState` 上的请求级共享对象，使同一请求多次调用拿到同一引用。
+ */
+declare function createExpressContext(req: Request, res: Response): HttpContext$1;
+//#endregion
+//#region src/types.d.ts
+interface RouteAuthMeta {
+  ignore?: boolean;
+  requireLogin?: boolean;
+  permissions?: {
+    list: string[];
+    mode: XltMode$1;
+  };
+  roles?: {
+    list: string[];
+    mode: XltMode$1;
+  };
+  safeBusiness?: string;
+}
+type AuthMatcher = string | RegExp | ((req: express.Request) => boolean);
+interface RouteAuthPolicy extends RouteAuthMeta {
+  match: AuthMatcher | AuthMatcher[];
+  methods?: string[];
+}
+interface XltMiddlewareOptions {
+  /** 快捷白名单，会被转换为 { match, ignore: true } */
+  ignore?: AuthMatcher[];
+  /** 路由级鉴权策略。xltMiddleware 会在鉴权前解析这些规则。 */
+  policies?: RouteAuthPolicy[];
+}
+declare global {
+  namespace Express {
+    interface Request {
+      _xltState?: Record<string, unknown>;
+      _xltRouteMeta?: RouteAuthMeta;
+      stpLoginId?: string;
+      stpToken?: string;
+    }
+  }
+} //# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/middleware/xlt-middleware.d.ts
+/**
+ * 全局登录校验中间件。
+ *
+ * 执行流程：
+ * 1. `createExpressContext(req, res)`
+ * 2. `resolveRouteAuthMeta` → 写入 `req._xltRouteMeta`
+ * 3. `shouldCheckLogin` 判断是否需要校验，不需要则直接放行
+ * 4. `runAuth`（登录 + 权限 + 角色 + safe），成功后 `syncExpressAuthState`
+ * 5. 任意异常通过 `next(err)` 交给 `xltErrorHandler`
+ */
+declare function xltMiddleware(xlt: XltTokenContext$1, options?: XltMiddlewareOptions): RequestHandler;
+//#endregion
+//#region src/middleware/ignore-auth.d.ts
+/**
+ * 路由级 helper：标记当前路由忽略登录校验（黑名单模式下放行）。
+ *
+ * 仅写入 `req._xltRouteMeta`，因此必须在同一条 route chain 中位于 `xltMiddleware` 之前才有效。
+ * 推荐主路径仍是 `xltMiddleware` 的 `ignore` / `policies` 选项。
+ */
+declare function ignoreAuth(): RequestHandler;
+//#endregion
+//#region src/middleware/require-login.d.ts
+/**
+ * 路由级 helper：标记当前路由需要登录（白名单模式下开启校验）。
+ *
+ * 仅写入 `req._xltRouteMeta`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function requireLogin(): RequestHandler;
+//#endregion
+//#region src/middleware/check-permission.d.ts
+/**
+ * 路由级 helper：声明当前路由所需权限。
+ *
+ * 仅写入 `req._xltRouteMeta.permissions`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkPermission(permission: string | string[], mode?: XltMode$1): RequestHandler;
+//#endregion
+//#region src/middleware/check-role.d.ts
+/**
+ * 路由级 helper：声明当前路由所需角色。
+ *
+ * 仅写入 `req._xltRouteMeta.roles`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkRole(role: string | string[], mode?: XltMode$1): RequestHandler;
+//#endregion
+//#region src/middleware/check-safe.d.ts
+/**
+ * 路由级 helper：声明当前路由需要二级认证安全窗口。
+ *
+ * 仅写入 `req._xltRouteMeta.safeBusiness`，必须位于 `xltMiddleware` 之前才生效。
+ */
+declare function checkSafe(business: string): RequestHandler;
+//#endregion
+//#region src/error/xlt-error-handler.d.ts
+/**
+ * 四参数 Express 错误中间件，挂在路由链末尾，将 core 鉴权异常转为 401/403 JSON。
+ * 非 xlt-token 异常透传给下一个错误处理器。
+ *
+ * @example
+ * app.use(xltErrorHandler());
+ */
+declare function xltErrorHandler(): ErrorRequestHandler;
+//#endregion
+//#region src/auth/run-auth.d.ts
+/**
+ * 编排登录 + 权限 + 角色 + 二级认证校验。
+ *
+ * 与 `XltTokenGuard.canActivate` 中的权限块逻辑等价：
+ * `checkLogin` 失败时抛出 `NotLoginException`，权限/角色/safe 校验失败时分别抛出对应异常。
+ */
+declare function runAuth(xlt: XltTokenContext$1, httpCtx: HttpContext$1, req: Request): Promise<AuthResult$1>;
+//#endregion
+//#region src/auth/should-check-login.d.ts
+/**
+ * 是否需要对当前请求执行登录校验。
+ *
+ * 与 NestJS `XltTokenGuard.requiresLogin` 行为一致：
+ * - 黑名单模式（`defaultCheck === true`）：除被 `ignore` 标记的路由外全部校验
+ * - 白名单模式（`defaultCheck === false`）：仅校验被 `requireLogin` 标记的路由
+ *
+ * 路由元数据由 `resolveRouteAuthMeta` 提前写入 `req._xltRouteMeta`。
+ */
+declare function shouldCheckLogin(req: Request, config: XltTokenConfig$1): boolean;
+//#endregion
+//#region src/auth/resolve-route-auth-meta.d.ts
+/**
+ * 解析当前请求命中的路由鉴权元数据。
+ *
+ * 在 `shouldCheckLogin` 和 `runAuth` 之前调用，使用 `req.originalUrl` 作为匹配目标，
+ * 避免 Router 嵌套时 `req.path` 丢失挂载前缀。
+ *
+ * 当多条策略同时命中时，后声明的策略覆盖前者的简单字段，并合并权限/角色列表，
+ * 因此用户可先声明 `/api` 默认策略，再声明 `/api/public` 例外。
+ */
+declare function resolveRouteAuthMeta(req: Request, options?: XltMiddlewareOptions): RouteAuthMeta;
+//#endregion
+//#region src/sync-state.d.ts
+/**
+ * 将鉴权成功后写入 `ctx.state` 的登录态同步到 Express `req` 上。
+ *
+ * core 在 `_resolveLoginId` 中写入 `ctx.state.stpLoginId` / `ctx.state.stpToken`，
+ * 这里对应同步到 `req.stpLoginId` / `req.stpToken`（与 NestJS Guard 字段命名一致）。
+ */
+declare function syncExpressAuthState(req: Request, ctx: HttpContext$1): void;
+//#endregion
+export { type AuthMatcher, type AuthResult, type CookieOptions, type CreateOptions, DEFAULT_XLT_TOKEN_CONFIG, type DeviceInfo, type ExpressLikeRequest, type ExpressLikeResponse, type HttpContext, type JwtConfig, MemoryStore, NotLoginException, NotLoginType, NotPermissionException, NotRoleException, NotSafeException, type RouteAuthMeta, type RouteAuthPolicy, type StpInterface, StpLogic, StpPermLogic, StpUtil, type TokenStrategy, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, type XltHooks, type XltMiddlewareOptions, XltMode, XltSession, type XltTokenConfig, type XltTokenContext, type XltTokenStore, checkPermission, checkRole, checkSafe, createExpressContext, createMockHttpContext, createXltToken, ignoreAuth, matchPermission, requireLogin, resolveRouteAuthMeta, runAuth, setStpLogic, setStpPermLogic, shouldCheckLogin, syncExpressAuthState, xltErrorHandler, xltMiddleware };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.ts","../src/types.ts","../src/middleware/xlt-middleware.ts","../src/middleware/ignore-auth.ts","../src/middleware/require-login.ts","../src/middleware/check-permission.ts","../src/middleware/check-role.ts","../src/middleware/check-safe.ts","../src/error/xlt-error-handler.ts","../src/auth/run-auth.ts","../src/auth/should-check-login.ts","../src/auth/resolve-route-auth-meta.ts","../src/sync-state.ts"],"mappings":";;;;;UAGiB,kBAAA;EACf,SAAA,GAAY,MAAA;AAAA;AAAA,UAGG,mBAAA;EACf,SAAA,CAAU,IAAA,UAAc,KAAA;EACxB,MAAA,CAAO,IAAA,UAAc,KAAA,UAAe,OAAA;AAAA;;AAFtC;;;;iBAUgB,oBAAA,CAAqB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,GAAW,aAAA;;;UCflD,aAAA;EACf,MAAA;EACA,YAAA;EACA,WAAA;IAAgB,IAAA;IAAgB,IAAA,EAAM,SAAA;EAAA;EACtC,KAAA;IAAU,IAAA;IAAgB,IAAA,EAAM,SAAA;EAAA;EAChC,YAAA;AAAA;AAAA,KAGU,WAAA,YAER,MAAA,KACE,GAAA,EADI,OAAA,CACmB,OAAA;AAAA,UAEZ,eAAA,SAAwB,aAAA;EACvC,KAAA,EAAO,WAAA,GAAc,WAAA;EACrB,OAAA;AAAA;AAAA,UAGe,oBAAA;EDXqB;ECapC,MAAA,GAAS,WAAA;EDb4C;ECerD,QAAA,GAAW,eAAA;AAAA;AAAA,QAWL,MAAA;EAAA,UACI,OAAA;IAAA,UACE,OAAA;MACR,SAAA,GAAY,MAAA;MACZ,aAAA,GAAgB,aAAA;MAChB,UAAA;MACA,QAAA;IAAA;EAAA;AAAA;;;;ADtCN;;;;;AAIA;;;;iBEcgB,aAAA,CACd,GAAA,EAAK,iBAAA,EACL,OAAA,GAAS,oBAAA,GACR,cAAA;;;;;;;AFrBH;;iBGKgB,UAAA,CAAA,GAAc,cAAA;;;;;;;AHL9B;iBIIgB,YAAA,CAAA,GAAgB,cAAA;;;;;;AJJhC;;iBKKgB,eAAA,CACd,UAAA,qBACA,IAAA,GAAM,SAAA,GACL,cAAA;;;;;;ALRH;;iBMKgB,SAAA,CAAU,IAAA,qBAAyB,IAAA,GAAM,SAAA,GAAwB,cAAA;;;;;;;ANLjF;iBOIgB,SAAA,CAAU,QAAA,WAAmB,cAAA;;;;;;;APJ7C;;;iBQOgB,eAAA,CAAA,GAAmB,mBAAA;;;;;;ARPnC;;;iBSMsB,OAAA,CACpB,GAAA,EAAK,iBAAA,EACL,OAAA,EAAS,aAAA,EACT,GAAA,EAAK,OAAA,GACJ,OAAA,CAAQ,YAAA;;;;;;ATVX;;;;;AAIA;iBUKgB,gBAAA,CAAiB,GAAA,EAAK,OAAA,EAAS,MAAA,EAAQ,gBAAA;;;;;;AVTvD;;;;;AAIA;iBWUgB,oBAAA,CACd,GAAA,EAAK,OAAA,EACL,OAAA,GAAS,oBAAA,GACR,aAAA;;;;;;AXjBH;;;iBYMgB,oBAAA,CAAqB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,aAAA"}

package/dist/index.mjs

@@ -0,0 +1,328 @@
+import { DEFAULT_XLT_TOKEN_CONFIG, MemoryStore, NotLoginException, NotLoginException as NotLoginException$1, NotLoginType, NotPermissionException, NotPermissionException as NotPermissionException$1, NotRoleException, NotRoleException as NotRoleException$1, NotSafeException, NotSafeException as NotSafeException$1, StpLogic, StpPermLogic, StpUtil, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, XltMode, XltMode as XltMode$1, XltSession, createMockHttpContext, createXltToken, matchPermission, setStpLogic, setStpPermLogic } from "@xlt-token/core";
+
+//#region src/context.ts
+/**
+* 将 Express `req` / `res` 适配为 core 的 `HttpContext`。
+*
+* `state` 复用挂在 `req._xltState` 上的请求级共享对象，使同一请求多次调用拿到同一引用。
+*/
+function createExpressContext(req, res) {
+	return {
+		headers: { get: (name) => req.headers[name.toLowerCase()] ?? null },
+		cookies: { get: (name) => req.cookies?.[name] ?? null },
+		query: { get: (name) => req.query[name] ?? null },
+		state: req._xltState ??= {},
+		setHeader: (name, value) => {
+			res.setHeader(name, value);
+		},
+		setCookie: (name, value, options) => {
+			if (options) res.cookie(name, value, options);
+			else res.cookie(name, value);
+		},
+		raw: () => req
+	};
+}
+
+//#endregion
+//#region src/auth/resolve-route-auth-meta.ts
+function matchPathPrefix(path, prefix) {
+	const pathname = path.split("?")[0] ?? path;
+	return prefix === "/" || pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+/**
+* 解析当前请求命中的路由鉴权元数据。
+*
+* 在 `shouldCheckLogin` 和 `runAuth` 之前调用，使用 `req.originalUrl` 作为匹配目标，
+* 避免 Router 嵌套时 `req.path` 丢失挂载前缀。
+*
+* 当多条策略同时命中时，后声明的策略覆盖前者的简单字段，并合并权限/角色列表，
+* 因此用户可先声明 `/api` 默认策略，再声明 `/api/public` 例外。
+*/
+function resolveRouteAuthMeta(req, options = {}) {
+	return [...(options.ignore ?? []).map((match) => ({
+		match,
+		ignore: true
+	})), ...options.policies ?? []].reduce((meta, policy) => {
+		if (!matchPolicy(req, policy)) return meta;
+		const { match: _match, methods: _methods, ...nextMeta } = policy;
+		return mergeRouteAuthMeta(meta, nextMeta);
+	}, {});
+}
+/** 判断单条策略是否命中当前请求。 */
+function matchPolicy(req, policy) {
+	if (policy.methods?.length) {
+		const method = req.method.toUpperCase();
+		if (!policy.methods.map((m) => m.toUpperCase()).includes(method)) return false;
+	}
+	return (Array.isArray(policy.match) ? policy.match : [policy.match]).some((matcher) => {
+		if (typeof matcher === "function") return matcher(req);
+		if (typeof matcher === "string") return matchPathPrefix(req.originalUrl, matcher);
+		return matcher.test(req.originalUrl);
+	});
+}
+/**
+* 合并两段路由元数据：
+* - `ignore` / `requireLogin` / `safeBusiness` 等简单字段：后者覆盖前者
+* - `permissions` / `roles`：两者都存在时合并列表，mode 取后者
+*/
+function mergeRouteAuthMeta(base, next) {
+	const merged = {
+		...base,
+		...next
+	};
+	if (base.permissions && next.permissions) merged.permissions = {
+		list: [...base.permissions.list, ...next.permissions.list],
+		mode: next.permissions.mode
+	};
+	if (base.roles && next.roles) merged.roles = {
+		list: [...base.roles.list, ...next.roles.list],
+		mode: next.roles.mode
+	};
+	return merged;
+}
+
+//#endregion
+//#region src/auth/should-check-login.ts
+/**
+* 是否需要对当前请求执行登录校验。
+*
+* 与 NestJS `XltTokenGuard.requiresLogin` 行为一致：
+* - 黑名单模式（`defaultCheck === true`）：除被 `ignore` 标记的路由外全部校验
+* - 白名单模式（`defaultCheck === false`）：仅校验被 `requireLogin` 标记的路由
+*
+* 路由元数据由 `resolveRouteAuthMeta` 提前写入 `req._xltRouteMeta`。
+*/
+function shouldCheckLogin(req, config) {
+	const meta = req._xltRouteMeta;
+	if (config.defaultCheck) return !meta?.ignore;
+	return meta?.requireLogin ?? false;
+}
+
+//#endregion
+//#region src/auth/run-auth.ts
+/**
+* 编排登录 + 权限 + 角色 + 二级认证校验。
+*
+* 与 `XltTokenGuard.canActivate` 中的权限块逻辑等价：
+* `checkLogin` 失败时抛出 `NotLoginException`，权限/角色/safe 校验失败时分别抛出对应异常。
+*/
+async function runAuth(xlt, httpCtx, req) {
+	const result = await xlt.stpLogic.checkLogin(httpCtx);
+	const meta = req._xltRouteMeta;
+	if (meta?.permissions && xlt.stpPermLogic) await xlt.stpPermLogic.checkPermission(result.loginId, meta.permissions.list, meta.permissions.mode);
+	if (meta?.roles && xlt.stpPermLogic) await xlt.stpPermLogic.checkRole(result.loginId, meta.roles.list, meta.roles.mode);
+	if (meta?.safeBusiness) await xlt.stpLogic.checkSafe(result.token, meta.safeBusiness);
+	return result;
+}
+
+//#endregion
+//#region src/sync-state.ts
+/**
+* 将鉴权成功后写入 `ctx.state` 的登录态同步到 Express `req` 上。
+*
+* core 在 `_resolveLoginId` 中写入 `ctx.state.stpLoginId` / `ctx.state.stpToken`，
+* 这里对应同步到 `req.stpLoginId` / `req.stpToken`（与 NestJS Guard 字段命名一致）。
+*/
+function syncExpressAuthState(req, ctx) {
+	const loginId = ctx.state.stpLoginId;
+	const token = ctx.state.stpToken;
+	if (loginId != null) req.stpLoginId = String(loginId);
+	if (token != null) req.stpToken = String(token);
+}
+
+//#endregion
+//#region src/middleware/xlt-middleware.ts
+/**
+* 全局登录校验中间件。
+*
+* 执行流程：
+* 1. `createExpressContext(req, res)`
+* 2. `resolveRouteAuthMeta` → 写入 `req._xltRouteMeta`
+* 3. `shouldCheckLogin` 判断是否需要校验，不需要则直接放行
+* 4. `runAuth`（登录 + 权限 + 角色 + safe），成功后 `syncExpressAuthState`
+* 5. 任意异常通过 `next(err)` 交给 `xltErrorHandler`
+*/
+function xltMiddleware(xlt, options = {}) {
+	return async (req, res, next) => {
+		const httpCtx = createExpressContext(req, res);
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			...resolveRouteAuthMeta(req, options)
+		};
+		if (!shouldCheckLogin(req, xlt.config)) return next();
+		try {
+			await runAuth(xlt, httpCtx, req);
+			syncExpressAuthState(req, httpCtx);
+			next();
+		} catch (err) {
+			next(err);
+		}
+	};
+}
+
+//#endregion
+//#region src/middleware/ignore-auth.ts
+/**
+* 路由级 helper：标记当前路由忽略登录校验（黑名单模式下放行）。
+*
+* 仅写入 `req._xltRouteMeta`，因此必须在同一条 route chain 中位于 `xltMiddleware` 之前才有效。
+* 推荐主路径仍是 `xltMiddleware` 的 `ignore` / `policies` 选项。
+*/
+function ignoreAuth() {
+	return (req, _res, next) => {
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			ignore: true
+		};
+		next();
+	};
+}
+
+//#endregion
+//#region src/middleware/require-login.ts
+/**
+* 路由级 helper：标记当前路由需要登录（白名单模式下开启校验）。
+*
+* 仅写入 `req._xltRouteMeta`，必须位于 `xltMiddleware` 之前才生效。
+*/
+function requireLogin() {
+	return (req, _res, next) => {
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			requireLogin: true
+		};
+		next();
+	};
+}
+
+//#endregion
+//#region src/middleware/check-permission.ts
+/**
+* 路由级 helper：声明当前路由所需权限。
+*
+* 仅写入 `req._xltRouteMeta.permissions`，必须位于 `xltMiddleware` 之前才生效。
+*/
+function checkPermission(permission, mode = XltMode$1.AND) {
+	return (req, _res, next) => {
+		const list = Array.isArray(permission) ? permission : [permission];
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			permissions: {
+				list,
+				mode
+			}
+		};
+		next();
+	};
+}
+
+//#endregion
+//#region src/middleware/check-role.ts
+/**
+* 路由级 helper：声明当前路由所需角色。
+*
+* 仅写入 `req._xltRouteMeta.roles`，必须位于 `xltMiddleware` 之前才生效。
+*/
+function checkRole(role, mode = XltMode$1.AND) {
+	return (req, _res, next) => {
+		const list = Array.isArray(role) ? role : [role];
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			roles: {
+				list,
+				mode
+			}
+		};
+		next();
+	};
+}
+
+//#endregion
+//#region src/middleware/check-safe.ts
+/**
+* 路由级 helper：声明当前路由需要二级认证安全窗口。
+*
+* 仅写入 `req._xltRouteMeta.safeBusiness`，必须位于 `xltMiddleware` 之前才生效。
+*/
+function checkSafe(business) {
+	return (req, _res, next) => {
+		req._xltRouteMeta = {
+			...req._xltRouteMeta,
+			safeBusiness: business
+		};
+		next();
+	};
+}
+
+//#endregion
+//#region src/error/map-xlt-error.ts
+/**
+* 将 core 鉴权异常映射为 HTTP 状态码 + JSON body。
+* 非 xlt-token 异常返回 `null`，交由调用方继续向后传递。
+*/
+function mapXltError(err) {
+	if (err instanceof NotLoginException$1) return {
+		status: 401,
+		body: {
+			statusCode: 401,
+			code: err.code,
+			type: err.type,
+			message: err.message,
+			token: err.token
+		}
+	};
+	if (err instanceof NotPermissionException$1) return {
+		status: 403,
+		body: {
+			statusCode: 403,
+			code: err.code,
+			permission: err.permission,
+			mode: err.mode,
+			message: err.message
+		}
+	};
+	if (err instanceof NotRoleException$1) return {
+		status: 403,
+		body: {
+			statusCode: 403,
+			code: err.code,
+			role: err.role,
+			mode: err.mode,
+			message: err.message
+		}
+	};
+	if (err instanceof NotSafeException$1) return {
+		status: 403,
+		body: {
+			statusCode: 403,
+			code: err.code,
+			business: err.business,
+			message: err.message
+		}
+	};
+	return null;
+}
+
+//#endregion
+//#region src/error/xlt-error-handler.ts
+/**
+* 四参数 Express 错误中间件，挂在路由链末尾，将 core 鉴权异常转为 401/403 JSON。
+* 非 xlt-token 异常透传给下一个错误处理器。
+*
+* @example
+* app.use(xltErrorHandler());
+*/
+function xltErrorHandler() {
+	return (err, _req, res, next) => {
+		const mapped = mapXltError(err);
+		if (!mapped) {
+			next(err);
+			return;
+		}
+		res.status(mapped.status).json(mapped.body);
+	};
+}
+
+//#endregion
+export { DEFAULT_XLT_TOKEN_CONFIG, MemoryStore, NotLoginException, NotLoginType, NotPermissionException, NotRoleException, NotSafeException, StpLogic, StpPermLogic, StpUtil, UuidStrategy, XLT_STP_INTERFACE, XLT_TOKEN_CONFIG, XLT_TOKEN_HOOKS, XLT_TOKEN_STORE, XLT_TOKEN_STRATEGY, XltError, XltMode, XltSession, checkPermission, checkRole, checkSafe, createExpressContext, createMockHttpContext, createXltToken, ignoreAuth, matchPermission, requireLogin, resolveRouteAuthMeta, runAuth, setStpLogic, setStpPermLogic, shouldCheckLogin, syncExpressAuthState, xltErrorHandler, xltMiddleware };
+//# sourceMappingURL=index.mjs.map