@html-schema/auth

框架无关的认证、权限与 SSO 基础工具包。该包按可独立发布 npm 包维护，不依赖 Vue、React Native、Electron、DOM 组件或业务 app。

能力

• matchPermission(pattern, permission)：支持 : 分段权限和 * 通配符。
• createPermissionChecker(grants)：基于 allow/deny 授权列表生成 checker.can(permission, scope)。
• resolveSafeAuthMode()：生产环境 unsafe auth mode 防误配保护。
• parseGatewaySessionResponse()：严格解析网关后端 session 响应，避免 HTML 或异常响应误判为已认证。
• AuthKeyValueStorage：跨端 token 存储适配器接口，支持同步或异步存储。
• createAuthTokenVault()：基于注入式 storage 创建 token vault，统一保存、读取、清理 token。
• sm4EncryptBlock() / sm4DecryptBlock()：SM4 单分组加解密。
• sm4EncryptCbc() / sm4DecryptCbc()：SM4-CBC + PKCS7 padding。
• rsaOaepEncrypt() / rsaOaepDecrypt()：基于 WebCrypto 的 RSA-OAEP PEM 加解密。
• createSsoV2ExchangeInfoPayload()：生成 SSO v2 getExchangeInfo 表单载荷，统一处理 datainfo 和 secretkey 加密包装字段。

使用

import { createPermissionChecker } from "@html-schema/auth";

const checker = createPermissionChecker([
  { permission: "project:*", effect: "allow", scope: { projectId: "P1" } },
  { permission: "project:delete", effect: "deny", scope: { projectId: "P1" } }
]);

checker.can("project:read", { projectId: "P1" }); // true
checker.can("project:delete", { projectId: "P1" }); // false

import { createAuthTokenVault } from "@html-schema/auth";

const vault = createAuthTokenVault({
  storage: secureStorageAdapter,
  storageKey: "AuthToken"
});

await vault.save({ token: "jwt", source: "gateway-sso" });
const token = await vault.getToken();
await vault.clear();

import {
  createSsoV2ExchangeInfoPayload,
  hexToBytes,
  sm4EncryptCbc
} from "@html-schema/auth";

const key = hexToBytes("0123456789abcdeffedcba9876543210");
const iv = hexToBytes("000102030405060708090a0b0c0d0e0f");
const encrypted = sm4EncryptCbc(new TextEncoder().encode("payload"), key, iv);

const payload = createSsoV2ExchangeInfoPayload({
  secretType: "2",
  datainfo: { account: "example-user", appName: "example-app" },
  secretKey: "example-session-key",
  encrypt: (value) => customAesWrap(value)
});

边界

• 不绑定具体 token 存储介质；只通过调用方注入的 AuthKeyValueStorage 读写。
• 不处理浏览器跳转。
• 不依赖 Vue、Pinia、Axios 或浏览器页面 API。
• Web 认证 provider 仍由 apps/web/src/auth 维护。
• 不保存、生成或内置真实业务私钥；RSA 私钥、SM4 会话密钥必须由调用方在安全运行时传入。
• rsaOaepEncrypt() / rsaOaepDecrypt() 只封装标准 RSA-OAEP。若对接方要求 PKCS#1 v1.5 或专用填充，应由调用方在 Node/Electron 原生层另行适配。

命令

pnpm --filter @html-schema/auth test
pnpm --filter @html-schema/auth typecheck
pnpm --filter @html-schema/auth build