@happyvertical/auth

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.7万

Keycloak、 Cognitto、 Nostr 以及 OAuth2/OIDC 本地 ChatGPT 会话和公共密钥身份的统一认证

中文使用文档
文档目录8 节
  1. 供应商
  2. 安装
  3. Claude 代码背景
  4. 快速启动
  5. 文档
  6. 授权服务器
  7. 本地签名为 ChatGPT
  8. 许可证

@ happyvertical/ auth (笑) (笑)

支持多个供应商的统一认证接口.

供应商

  • 键盘 - 具有行政管理能力的OIDC/OAuth2完全
  • AWS 认知 - OAuth2与主机UI
  • 鼻头 - 分散公用钥匙身份

安装

npm install @happyvertical/auth

Claude 代码背景

为 AI 辅助开发安装 Claude 代码上下文文件 :

npx have-auth-context

这个复制包 AGENT.md 文献和记录 metadata.json 元数据到您的项目 .claude/ 目录,使克洛德能够在使用该套件时提供更好的帮助.

快速启动

import { getAuth } from '@happyvertical/auth';

// Keycloak
const auth = await getAuth({
  type: 'keycloak',
  serverUrl: 'https://auth.example.com',
  realm: 'my-realm',
  clientId: 'my-app'
});

// Cognito
const auth = await getAuth({
  type: 'cognito',
  region: 'us-east-1',
  userPoolId: 'us-east-1_xxx',
  clientId: 'xxx'
});

// Nostr
const auth = await getAuth({
  type: 'nostr',
  relays: ['wss://relay.damus.io']
});

// Authenticate
const result = await auth.authenticate({ username, password });
console.log(result.accessToken);

// Validate token
const claims = await auth.validateToken(token);

// Check role
if (await auth.hasRole(token, 'admin')) {
  // Admin access
}

文档

见 阿根特·姆德(签名) 用于完整的API文档.

授权服务器

@happyvertical/auth/server 提供框架独立的 OAuth 2.0 授权码发布器。 它故意不认证浏览器 届会或同意:应用程序验证其本届会议和 权限,然后调用 parseAuthorizationRequest() 财务报告和审定财务报表 approve() 带有 应用程序拥有 OAuthConsentContext。 。 。 .

import { createAuthorizationServer } from '@happyvertical/auth/server';

const request = await server.parseAuthorizationRequest(url.searchParams);
const approved = await server.approve(request, {
  subject: session.userId,
  tenantId: session.activeTenantId,
});
return Response.redirect(approved.redirectUri, 302);

提供耐用 OAuthAuthorizationStorage 执行。 内容 consumeAuthorizationCode 财务报告和审定财务报表 rotateRefreshGrant 操作必须是原子 数据库交易(或比较和扫描操作); 输出的内存 存储只用于测试。 服务器执行S256 PKCE,精确重定向URI和 资源绑定, JWT 签名/ JWKS, 随家族重放的刷新键旋转 在代码交换和刷新时进行实时授权检查 结束 OAuthIdentityProvider.revalidateConsent (遗产) refreshConsent 钩子是两者的倒背). 返回未更改科目和租户,可选 替换应用索赔,以及作为 赠款。 返回无效;改变身份、租户或扩大范围失败 关闭。 Omiting 索赔取消了以前的申请索赔。 JWT协议索赔 预留。 获得同意 approve 也可缩小所要求的范围.

存储必须执行 narrowRefreshGrant 当发布刷新令牌时( 构造者拒绝没有它的商店): 解剖 验证替换符号散列和主动赠款,然后只保留一个子集 范围。 抛出任何失败。 服务器取消家族关系 活检失败或持久性缩小; 它永远不会返回替换 . 储存失败必须拒绝;在作出持久承诺之前永远不要恢复成功。 A 类 承诺后连接失败可留下无法获取的散列单项赠款,但 不得暴露任何标志。 混凝土SQL适配器和方言测试属于 主机应用程序.

路径发布器, 如 https://host/oauth 广告结尾 /oauth 财务报告和审定财务报表 RFC 8414号发现地点 /.well-known/oauth-authorization-server/oauth公开 DCR只接受代码响应,授权代码/重新授权,允许 瞄准镜和HTTPS重定向。 HTTP回转方向需要明确 allowLoopbackRedirects: true 面向本地/发展客户。 资源服务器必须传递给自己的受众 verifyAccessToken(token, audience)。访问端 需要核查 typ: at+jwt,过期,发布 -at,主题,观众,标志 具有有效索赔类型的身份证、客户身份证和范围。 登记机构在流动时仅限于16个基B,包括何时 内容- Length 不存在或少报。 元数据允许最多10个方向 用户界面每个字符2 048个,256个字符的客户端名称,2 048个字符的用户端名称 范围字符串、两种赠款类型和一种响应类型。 直接 register() 电话 应用相同的字段界限。 体型过大者返回413具后再活; 无效元数据返回 400 。 未知扩展元数据在 身体限制。 撤销返回未知或无效的令牌成功, 但是 存储退出返回一个通用的500个服务器 error, 因此调用者可以在之后重试 复原。 CIMD未执行。 签名的 API 支持一个活键; 未执行重叠的签名键旋转。 主机必须提供公众 JWK匹配私用签名密钥,并保留私用材料出自JWKS.

本地签名为 ChatGPT

只有节点的本地应用程序可以导入 @happyvertical/auth/local 管理 他们与 ChatGPT 会话签名。 经理使用 127.0.0.1 循环 调用、 PKCE 和 OIDC 验证, 并写入可复制的账户范围 在解剖学上,只允许拥有证书。 通过配置路径 在项目目录外打开返回的授权 URL 系统浏览器。 从不透露来自 sessions()。 。 。 .

使用 accessToken(clientId) 在授权请求之前; 将符号序列化 新鲜. logout(clientId) 总是清除本地的证书和报告 是否确认远程撤销 。 本地运行时间没有变化 推断请求或使用浏览器存储.

许可证

麻省理工学院

刷新存储适配器必须执行 narrowRefreshGrant 在解剖学上,既维持范围缩小,又维持目前 claims 在返回之前, 输入确切的替换符。 明确 undefined (c) 索赔价值为先前申请索赔的结清额。 托肯和吊销表体随注册共享16KiB流线限制. 刷新请求可能要求原赠款范围的子集;扩展请求被拒绝.

版本与发布记录

@happyvertical/auth 共发布 132 个版本,首次发布于 2026/06/23;过去 12 个月发布了 132 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/auth 的常见问题

@happyvertical/auth 是什么?

Keycloak、 Cognitto、 Nostr 以及 OAuth2/OIDC 本地 ChatGPT 会话和公共密钥身份的统一认证

如何安装 @happyvertical/auth?

在项目目录运行 npm install @happyvertical/auth,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-auth-context,可以用 npx have-auth-context 直接运行。

@happyvertical/auth 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/auth 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/auth 可以商用吗?

@happyvertical/auth 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/auth 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/auth 在 2026/10/17 – 2026/11/15 这 30 天内被下载 17,403 次,日均约 580 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/auth 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 132 个版本,其中过去 12 个月发布了 132 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。