# @happyvertical/auth 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/auth/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:00:57.742Z
中文译文更新时间：2026-11-17T09:48:30.323Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/auth
原文对照：https://npmcn.com/package/%40happyvertical/auth/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/auth#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：728 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-23T08:14:11.611Z
- 最新版本发布：2026-11-17T00:00:57.530Z
- 近 30 天下载量：17403（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：132（近 12 个月 132 个）

## 中文简介

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

## 安装

```sh
npm install @happyvertical/auth
```

也可以使用：`pnpm add @happyvertical/auth`、`yarn add @happyvertical/auth`、`bun add @happyvertical/auth`

## README

# @ happyvertical/ auth (笑) (笑)

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

## 供应商

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

## 安装

```bash
npm install @happyvertical/auth
```

## Claude 代码背景

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

```bash
npx have-auth-context
```

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

## 快速启动

```typescript
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
}
```

## 文档

见 [阿根特·姆德(签名)](https://npmcn.com/package/%40happyvertical/auth/AGENT.md) 用于完整的API文档.

## 授权服务器

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

```typescript
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 是什么？

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 和提交记录判断。

