@xlt-token/express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xltorg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @xlt-token/express
+
+Express middleware adapter for xlt-token. It connects Express `req` / `res` to `@xlt-token/core` and provides login checks, route policies, route helpers, and JSON error handling.
+
+## Installation
+
+```bash
+pnpm add express @xlt-token/express
+pnpm add -D @types/express
+```
+
+## Quick Start
+
+```ts
+import express from 'express';
+import {
+  createXltToken,
+  MemoryStore,
+  XltMode,
+  xltErrorHandler,
+  xltMiddleware,
+  type StpInterface,
+} from '@xlt-token/express';
+
+const stpInterface: StpInterface = {
+  getPermissionList: async (loginId) =>
+    loginId === '1001' ? ['user:read', 'order:*'] : [],
+  getRoleList: async (loginId) => (loginId === '1001' ? ['admin'] : []),
+};
+
+const xlt = createXltToken({
+  config: { tokenPrefix: '' },
+  store: new MemoryStore(),
+  stpInterface,
+});
+
+const app = express();
+app.use(express.json());
+
+const api = express.Router();
+
+api.use(
+  xltMiddleware(xlt, {
+    ignore: ['/api/auth/login', '/api/public'],
+    policies: [
+      { match: '/api/order', permissions: { list: ['order:read'], mode: XltMode.AND } },
+      { match: '/api/admin', roles: { list: ['admin'], mode: XltMode.AND } },
+      { match: '/api/pay', methods: ['POST'], safeBusiness: 'pay' },
+    ],
+  }),
+);
+
+api.post('/auth/login', async (req, res) => {
+  const { userId = '1001' } = req.body ?? {};
+  const token = await xlt.stpLogic.login(userId);
+  res.json({ token });
+});
+
+api.get('/public', (_req, res) => {
+  res.json({ ok: true });
+});
+
+api.get('/me', (req, res) => {
+  res.json({ id: req.stpLoginId, token: req.stpToken });
+});
+
+api.get('/order', (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.use('/api', api);
+app.use(xltErrorHandler());
+
+app.listen(3000);
+```
+
+## Route Policies
+
+Use `ignore` and `policies` when mounting `xltMiddleware` globally or at router level. Policies run before authentication, so they are the recommended Express integration path.
+
+```ts
+api.use(
+  xltMiddleware(xlt, {
+    ignore: ['/api/auth/login'],
+    policies: [
+      { match: '/api/me', requireLogin: true },
+      { match: '/api/order', permissions: { list: ['order:read'], mode: XltMode.AND } },
+      { match: '/api/report', roles: { list: ['admin', 'ops'], mode: XltMode.OR } },
+      { match: '/api/pay', methods: ['POST'], safeBusiness: 'pay' },
+    ],
+  }),
+);
+```
+
+String matchers use path-segment prefix matching. `/api/public` matches `/api/public/docs` and `/api/public?from=web`, but it does not match `/api/publicity`.
+
+## Route Helpers
+
+The adapter also exports `ignoreAuth()`, `requireLogin()`, `checkPermission()`, `checkRole()`, and `checkSafe()`. These helpers must run before `xltMiddleware` in the same route chain.
+
+```ts
+app.get('/public', ignoreAuth(), xltMiddleware(xlt), (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.get('/order', checkPermission('order:read'), xltMiddleware(xlt), (_req, res) => {
+  res.json({ ok: true });
+});
+```
+
+Do not mount `api.use(xltMiddleware(xlt))` before route helpers and expect those helpers to affect the same request. Express runs middleware in registration order.
+
+## Exports
+
+- `createXltToken`
+- `MemoryStore`
+- `UuidStrategy`
+- `StpLogic`
+- `StpPermLogic`
+- `StpUtil`
+- `XltMode`
+- `createExpressContext`
+- `xltMiddleware`
+- `xltErrorHandler`
+- `ignoreAuth`
+- `requireLogin`
+- `checkPermission`
+- `checkRole`
+- `checkSafe`
+- `runAuth`
+- `shouldCheckLogin`
+- `resolveRouteAuthMeta`
+- `syncExpressAuthState`
+
+## Documentation
+
+Read the full guide at <https://xiaolangtou.github.io/xlt-token/adapters/express>.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,483 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _xlt_token_core = require("@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 = _xlt_token_core.XltMode.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 = _xlt_token_core.XltMode.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 _xlt_token_core.NotLoginException) return {
+		status: 401,
+		body: {
+			statusCode: 401,
+			code: err.code,
+			type: err.type,
+			message: err.message,
+			token: err.token
+		}
+	};
+	if (err instanceof _xlt_token_core.NotPermissionException) return {
+		status: 403,
+		body: {
+			statusCode: 403,
+			code: err.code,
+			permission: err.permission,
+			mode: err.mode,
+			message: err.message
+		}
+	};
+	if (err instanceof _xlt_token_core.NotRoleException) return {
+		status: 403,
+		body: {
+			statusCode: 403,
+			code: err.code,
+			role: err.role,
+			mode: err.mode,
+			message: err.message
+		}
+	};
+	if (err instanceof _xlt_token_core.NotSafeException) 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
+Object.defineProperty(exports, 'DEFAULT_XLT_TOKEN_CONFIG', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.DEFAULT_XLT_TOKEN_CONFIG;
+  }
+});
+Object.defineProperty(exports, 'MemoryStore', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.MemoryStore;
+  }
+});
+Object.defineProperty(exports, 'NotLoginException', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.NotLoginException;
+  }
+});
+Object.defineProperty(exports, 'NotLoginType', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.NotLoginType;
+  }
+});
+Object.defineProperty(exports, 'NotPermissionException', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.NotPermissionException;
+  }
+});
+Object.defineProperty(exports, 'NotRoleException', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.NotRoleException;
+  }
+});
+Object.defineProperty(exports, 'NotSafeException', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.NotSafeException;
+  }
+});
+Object.defineProperty(exports, 'StpLogic', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.StpLogic;
+  }
+});
+Object.defineProperty(exports, 'StpPermLogic', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.StpPermLogic;
+  }
+});
+Object.defineProperty(exports, 'StpUtil', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.StpUtil;
+  }
+});
+Object.defineProperty(exports, 'UuidStrategy', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.UuidStrategy;
+  }
+});
+Object.defineProperty(exports, 'XLT_STP_INTERFACE', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XLT_STP_INTERFACE;
+  }
+});
+Object.defineProperty(exports, 'XLT_TOKEN_CONFIG', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XLT_TOKEN_CONFIG;
+  }
+});
+Object.defineProperty(exports, 'XLT_TOKEN_HOOKS', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XLT_TOKEN_HOOKS;
+  }
+});
+Object.defineProperty(exports, 'XLT_TOKEN_STORE', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XLT_TOKEN_STORE;
+  }
+});
+Object.defineProperty(exports, 'XLT_TOKEN_STRATEGY', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XLT_TOKEN_STRATEGY;
+  }
+});
+Object.defineProperty(exports, 'XltError', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XltError;
+  }
+});
+Object.defineProperty(exports, 'XltMode', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XltMode;
+  }
+});
+Object.defineProperty(exports, 'XltSession', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.XltSession;
+  }
+});
+exports.checkPermission = checkPermission;
+exports.checkRole = checkRole;
+exports.checkSafe = checkSafe;
+exports.createExpressContext = createExpressContext;
+Object.defineProperty(exports, 'createMockHttpContext', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.createMockHttpContext;
+  }
+});
+Object.defineProperty(exports, 'createXltToken', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.createXltToken;
+  }
+});
+exports.ignoreAuth = ignoreAuth;
+Object.defineProperty(exports, 'matchPermission', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.matchPermission;
+  }
+});
+exports.requireLogin = requireLogin;
+exports.resolveRouteAuthMeta = resolveRouteAuthMeta;
+exports.runAuth = runAuth;
+Object.defineProperty(exports, 'setStpLogic', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.setStpLogic;
+  }
+});
+Object.defineProperty(exports, 'setStpPermLogic', {
+  enumerable: true,
+  get: function () {
+    return _xlt_token_core.setStpPermLogic;
+  }
+});
+exports.shouldCheckLogin = shouldCheckLogin;
+exports.syncExpressAuthState = syncExpressAuthState;
+exports.xltErrorHandler = xltErrorHandler;
+exports.xltMiddleware = xltMiddleware;