@composy/auth-core
v0.0.2
Published
LDesign 认证系统核心模块 / Framework-agnostic auth core
Maintainers
Readme
@composy/auth-core
@composy/auth-core
是框架无关的认证核心库,负责认证状态管理、Token 与 Session 生命周期、Permission 适配、安全工具,以及 REST
/ LEAP 后端适配。
✨ 核心能力
- 框架无关:纯 TypeScript 实现,不绑定任何 UI 框架,Vue / React / Vanilla 场景均可复用
- 完整认证状态机:
AuthManager统一管理登录、登出、Token 刷新与会话;hasPermission()/hasRole()仅通过同步PermissionAdapter查询授权;未注入适配器或适配器出错时,非空检查默认拒绝 - Token 生命周期:默认实例级 memory profile,显式选择 localStorage / sessionStorage / cookie 时支持 namespace 隔离、JWT 过期解析与刷新请求串行化队列
- 后端适配层:REST 与 LEAP 两套服务工厂(
createRestAuthServices/createLeapAuthServices),协议接入通过setHandlers()/bindServices()完成,不侵入核心状态机 - 安全工具集:密码强度检查与生成、CSRF 令牌、XSS 清理、带加密的安全存储、固定/滑动窗口速率限制
- Engine 集成:
createAuthEnginePlugin()把认证状态同步到 LDesign engine 的 state / events / 容器 - 可组合基础设施:类型安全的事件总线(优先级、通配符、once)与洋葱模型中间件链
📦 安装
pnpm add @composy/auth-core- 运行时零依赖,无 peer 依赖,可直接在任意前端项目中使用。
- 除主入口外还提供
./adapters、./token、./session、./security等子路径导出,详见下方主要导出。 - Vue 项目通常配合
@composy/auth-vue使用。
架构概览
auth-core/
├── src/
│ ├── auth/ # AuthManager 认证主流程
│ ├── token/ # Token 存储、过期判断、刷新串行化
│ ├── session/ # 会话生命周期与剩余时间管理
│ ├── security/ # 密码、CSRF、XSS、安全存储、速率限制
│ ├── errors/ # 认证异常与错误归一化
│ ├── storage/ # 存储适配抽象(LocalStorage/Session/Memory/Cookie)
│ ├── middleware/ # 认证中间件链
│ ├── events/ # 事件总线(发布-订阅模式)
│ ├── logging/ # 日志接口与传输器
│ ├── engine/ # LDesign engine 共享状态键和插件
│ ├── adapters/ # 后端适配层
│ │ ├── rest/ # REST 认证服务工厂
│ │ └── leap/ # LEAP 认证、菜单、RPC 适配
│ ├── shared/ # 纯工具函数(字符串、对象、异步、环境检测)
│ ├── compat/ # 兼容导出层
│ ├── constants/ # 错误码与 engine 键常量
│ └── types/ # 公共类型定义模块说明
auth — 认证管理器
AuthManager 是认证核心,管理完整的登录/登出/Token 刷新/会话/权限状态机。
核心能力:
setHandlers()/bindServices():后端协议接入不侵入核心状态机init()/ready():显式恢复认证状态;应在绑定 refresh service 后调用,避免初始化竞态subscribe():适配层按状态快照订阅,避免重复监听多个事件login()/logout()/fetchUser():标准化认证操作;登出服务可同时接收 accessToken 和 refreshTokenhasPermission()/hasRole():兼容授权门面,通过AuthConfig.permission委托;适配器必须同步返回布尔值,未注入或失败时非空检查默认拒绝,all/any语义由适配器决定on()/emit():类型安全的事件系统
token — Token 管理器
TokenManager 负责 Token 的存储、读取、过期判断和刷新调度。
支持的存储方式:
localStorage:持久化浏览器本地存储sessionStorage:会话级浏览器存储cookie:基于 Cookie 的存储memory:内存存储(SSR 兼容)
工具方法:
parseJwtPayload():JWT 载荷解析getJwtExpiresAt():从 JWT 提取过期时间isTokenExpired():过期判断,支持提前阈值
token — Token 刷新队列
TokenRefreshQueue 管理 Token 刷新的并发控制:
- 同一时间只执行一个刷新请求
- 其余请求等待第一个请求的结果
- 支持超时控制和最大队列长度限制
session — 会话管理器
SessionManager 管理浏览器端的认证会话生命周期:
- 创建和存储会话到
sessionStorage - 会话过期检测与自动续期
- 设备信息自动采集(浏览器、OS、设备类型)
- 过期回调通知
security — 安全工具集
| 模块 | 能力 |
| ------------------ | --------------------------------------- |
| password.ts | 密码强度检查、验证、安全密码生成 |
| csrf.ts | CSRF 令牌生成、验证、存储和自动刷新 |
| xss.ts | HTML 清理、输入验证、URL 参数编解码 |
| secureStorage.ts | 带过期时间、加密支持的安全存储 |
| rateLimiter.ts | 基于内存的请求速率限制(固定/滑动窗口) |
events — 事件总线
EventBus 提供发布-订阅模式的事件系统:
- 优先级排序的监听器
- 通配符监听器(
*) - 一次性监听器(
once) - 同步/异步触发
- 事件历史记录(调试用)
middleware — 中间件链
MiddlewareChain 管理和执行中间件链,类似 Koa 的洋葱模型:
- 按优先级排序
- 支持中止和错误隔离
- 链式调用 API
engine — LDesign Engine 插件
createAuthEnginePlugin() 将 AuthManager 注册到 LDesign engine:
- 同步认证状态到 engine state
- 监听登录/登出/Token 刷新事件并转发到 engine events
- 将 manager 注册为容器单例
adapters — 后端适配层
| 适配器 | 说明 |
| ------------------ | ----------------------------------------------------------- |
| restAuthServices | 通用 REST 认证服务工厂,支持自定义 API 路径和可选 CSRF 握手 |
| leapAuthServices | LEAP 认证、菜单、用户信息适配 |
| leapRpcClient | LEAP RPC 会话管理与请求编解码 |
| leapCrypto | LEAP 密码加密链与参数混淆编码 |
| leapNormalizers | LEAP 用户/菜单归一化 |
REST / LEAP 工厂都通过 fetchImpl 接收宿主 HTTP 层。若宿主使用与 @composy/http-core 兼容的
HttpClient,可以使用内置的结构化桥接器;它不会把 @composy/http-core 作为 Auth
Core 的运行时依赖:
import { createAuthManager } from '@composy/auth-core'
import { createAuthFetchFromHttpClient, createRestAuthServices } from '@composy/auth-core/adapters'
const authManager = createAuthManager()
authManager.bindServices(
createRestAuthServices({
baseURL: '/api/v1',
fetchImpl: createAuthFetchFromHttpClient(httpClient),
})
)桥接器要求客户端提供 request(config),并返回包含 status、statusText、headers、 data(或
body)的响应;如果响应包含原生
Response,会优先保留该对象。这样 REST 和 LEAP 仍能读取原始状态码、协议头和响应体,CSRF、刷新令牌及 RPC 错误处理不会丢失 HTTP 语义。更完整的最小契约见
AuthHttpClient、AuthHttpRequestConfig 和 AuthHttpResponse。
快速开始
直接使用 AuthManager
import { createAuthManager } from '@composy/auth-core'
const authManager = createAuthManager({
autoRefresh: true,
refreshThreshold: 300,
loginRoute: '/login',
defaultRoute: '/dashboard',
})
authManager.setHandlers({
login: async credentials => {
const response = await fetch('/api/v1/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentials),
})
return await response.json()
},
})
await authManager.init()页面可见性与离线感知
自动刷新默认按原有定时器运行;在浏览器中可以注入生命周期适配器,让页面隐藏或网络离线时暂停后台刷新:
import { createAuthManager, createBrowserAuthLifecycle } from '@composy/auth-core'
const authManager = createAuthManager({
lifecycle: createBrowserAuthLifecycle(),
})
await authManager.init()Core 不直接访问 window / document。SSR 或测试环境可实现 AuthLifecyclePort 自行提供
getState() 与
subscribe();恢复到可见且在线后,AuthManager 会按 Token 剩余时间重新调度,进入刷新阈值时立即尝试刷新。该策略只影响自动刷新,手动登录、登出和用户资料请求仍由调用方控制。
绑定 REST 服务
import { createAuthManager } from '@composy/auth-core'
import { createRestAuthServices } from '@composy/auth-core/adapters'
const authManager = createAuthManager({
tokenStorage: { namespace: 'portal', storage: 'memory' },
session: { namespace: 'portal' },
})
authManager.bindServices(
createRestAuthServices({
baseURL: '/api/v1',
csrfPath: '/api/health', // 变更请求前获取 X-CSRF-Token
loginPath: '/auth/login',
profilePath: '/auth/profile',
})
)
await authManager.ready()当后端登出接口需要撤销刷新令牌时,AuthManager.logout()
会把当前保存的 refreshToken 传给服务适配器;REST 适配器会自动以 { refreshToken } 作为请求体发送。
绑定 LEAP 服务
import { createAuthManager } from '@composy/auth-core'
import { createLeapAuthServices } from '@composy/auth-core/adapters'
const authManager = createAuthManager({ autoRefresh: false })
authManager.bindServices(
createLeapAuthServices({
baseURL: 'https://example.com',
systemName: 'portal',
systemArea: 'default',
})
)
await authManager.init()订阅状态变化
const unsubscribe = authManager.subscribe(state => {
console.info(state.isAuthenticated, state.user)
})
await authManager.login({ username: 'admin', password: '123456' })
unsubscribe()安全 profile 与生命周期约束
TokenManager默认使用实例级memory,不会把 access/refresh token 写入 JS 可读持久化存储。TokenManager.getPersistenceStatus()返回实际存储后端是否可持久化以及最近的持久化状态;onPersistenceError()用于将写入、清理失败暴露给诊断层,避免静默降级为内存成功。- 如果业务明确选择 Web Storage 或 cookie,请为每个 App/租户设置唯一
tokenStorage.namespace;cookie仅表示 JS 可读 Cookie,浏览器端代码无法创建HttpOnlyCookie。 AuthManager构造函数不会自动启动恢复流程。先bindServices(),再await init()或await ready();destroy()是 terminal 操作,旧异步请求不能恢复已销毁实例。fallbackUserPolicy默认为allow,当登录结果和用户资料接口都没有返回用户时兼容地使用最小用户;对必须拿到完整资料后才建立会话的应用设置为deny,此时会清理 Token 并返回LOGIN_PROFILE_UNAVAILABLE。getUser()、getState()返回隔离快照;observer 回调异常只进入诊断回调,不会回滚已提交的登录、刷新或登出事实。- 可通过
eventPort与diagnosticSink将认证事件和诊断信息接入宿主的event-core、logger-core或应用基础设施;外部 Port 的同步异常和异步拒绝都会被隔离,不会回滚已提交的认证事实。 - 可使用
createAuthEventPort(emitter)与createAuthDiagnosticSink(logger)将兼容emit()/debug()/info()/warn()/error()形状的宿主实例接入;这两个工厂只依赖结构化最小契约,不会把 event/logger 包绑定进 Auth Core。 hasPermission()/hasRole()必须通过permissionadapter 委托给统一 Permission Runtime;适配器必须同步返回布尔值。未配置或执行失败时非空检查默认拒绝;Auth 不会从用户对象推断授权。SessionManager支持通过session.deviceInfoProvider注入设备信息 Port;未注入时保留兼容的轻量浏览器探测。需要统一设备能力时,建议由宿主接入device-core后传入 Provider。@composy/auth-core/events的eventBus和@composy/auth-core/logging的logger仅为兼容旧代码保留。多应用、SSR 或多租户场景请使用createEventBus()与createLogger()创建独立实例,避免监听器、日志配置和 transport 跨应用共享。稳定、兼容、弃用、实验和内部 API 清单见PUBLIC-API.md。whiteList/isWhitelisted()仅为旧版 Router 集成保留;新的路由访问控制应由 Router 根据route.meta.requiresAuth、Permission 和 Role 独立组合,Auth Core 不把白名单当作授权事实。- CSRF、XSS 和速率限制属于 Web/HTTP 安全边界;Auth 提供兼容工具和协议需要,但不替代宿主的 HTTP 拦截器、服务端 CSRF 防护或分布式限流。
- REST 与 LEAP 工厂通过
fetchImpl暴露显式 transport seam,支持 SSR、测试和宿主统一 HTTP 层注入。@composy/http-core的高层HttpClient返回ResponseData,而 LEAP 还需要原始响应文本和协议头。可以使用createAuthFetchFromHttpClient(httpClient)作为默认边界适配器;它只依赖结构化最小契约,不会把具体 HTTP 包绑定进 Auth Core,并保留 status/headers/body 语义。 SecureStorage支持通过adapter和cryptoAdapter注入宿主的 storage/crypto 实现;更复杂的部署应优先使用AuthSecretStorePort,避免把持久化介质或密钥管理耦合到 Auth Core。
密码安全
import {
checkPasswordStrength,
generateSecurePassword,
validatePassword,
} from '@composy/auth-core/security'
// 检查密码强度
const passwordStrength = checkPasswordStrength('MyP@ssw0rd')
console.info(passwordStrength)
// 验证密码
const validation = validatePassword('MyP@ssw0rd', { minLength: 8, requireSpecial: true })
console.info(validation)
// 生成安全密码
const password = generateSecurePassword(16)
console.info(password)安全密码使用 Web
Crypto 拒绝采样,并保证每个启用的字符集至少出现一次;长度必须为 0–65,536 的整数,且不小于启用的字符集数量。当前环境没有 Web
Crypto 安全随机源时会抛错,不会退化到 Math.random()。
速率限制
import { createLoginLimiter } from '@composy/auth-core/security'
const limiter = createLoginLimiter({ maxRequests: 5, windowMs: 15 * 60 * 1000 })
const result = limiter.hit(username)
if (result.limited) {
throw new Error('登录尝试次数过多')
}主要导出
| 子路径 | 导出内容 |
| ------------------------------- | --------------------------------------------------------------- |
| @composy/auth-core | createAuthManager、AuthManager、核心类型 |
| @composy/auth-core/adapters | REST/LEAP 工厂、createAuthFetchFromHttpClient、事件/诊断 Port |
| @composy/auth-core/token | TokenManager、TokenRefreshQueue |
| @composy/auth-core/session | SessionManager |
| @composy/auth-core/security | 密码、CSRF、XSS、安全存储、限流 |
| @composy/auth-core/events | EventBus |
| @composy/auth-core/logging | Logger、日志传输器 |
| @composy/auth-core/engine | engine 共享状态键与插件导出 |
| @composy/auth-core/middleware | MiddlewareChain |
| @composy/auth-core/storage | 存储适配器 |
| @composy/auth-core/errors | AuthException、错误处理器 |
| @composy/auth-core/shared | 纯工具函数 |
| @composy/auth-core/compat | 兼容导出层 |
兼容说明
@composy/auth-core/compat 是历史兼容出口。新代码优先直接使用明确子路径:
@composy/auth-core/adapters@composy/auth-core/security@composy/auth-core/token
🔨 构建产物与验证
- 使用
@composy/builder构建,产出es(ESM + 类型)、esm、lib(CJS)三套模块产物与dist/index.min.js单文件入口,unpkg/jsdelivr字段指向该 CDN 产物。 - 构建后处理会清理源码目录中误生成的
.d.ts声明残留。 - ESLint、TypeScript 和
@composy/builder的权威配置均位于本包.ldesign/目录;根目录同名配置保留为兼容入口。
pnpm build # 完整构建:builder 构建 + 产物归一 + 校验
pnpm type-check # tsc --noEmit
pnpm test:run # 单元测试(ltesting run:unit)
pnpm lint:check # ESLint 校验