npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/auth-core

v0.0.2

Published

LDesign 认证系统核心模块 / Framework-agnostic auth core

Readme

@composy/auth-core

English

@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 和 refreshToken
  • hasPermission() / 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,浏览器端代码无法创建 HttpOnly Cookie。
  • 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() 必须通过 permission adapter 委托给统一 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 实现;更复杂的部署应优先使用 AuthSecretStore Port,避免把持久化介质或密钥管理耦合到 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 校验

相关文档