@happyvertical/auth

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

Unified authentication for Keycloak, Cognito, Nostr, and local ChatGPT sessions with OAuth2/OIDC and public key identity

原始使用文档
文档目录8 节
  1. Providers
  2. Installation
  3. Claude Code Context
  4. Quick Start
  5. Documentation
  6. Authorization server
  7. Local Sign in with ChatGPT
  8. License

@happyvertical/auth

Unified authentication interface supporting multiple providers.

Providers

  • Keycloak - Full OIDC/OAuth2 with admin capabilities
  • AWS Cognito - OAuth2 with hosted UI
  • Nostr - Decentralized public key identity

Installation

npm install @happyvertical/auth

Claude Code Context

Install Claude Code context files for AI-assisted development:

npx have-auth-context

This copies the package's AGENT.md documentation and metadata.json metadata to your project's .claude/ directory, enabling Claude to provide better assistance when working with this package.

Quick Start

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
}

Documentation

See AGENT.md for complete API documentation.

Authorization server

@happyvertical/auth/server provides a framework-independent OAuth 2.0 authorization-code issuer. It intentionally does not authenticate browser sessions or render consent: an application validates its current session and permissions, then calls parseAuthorizationRequest() and approve() with an application-owned 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);

Supply a durable OAuthAuthorizationStorage implementation. Its consumeAuthorizationCode and rotateRefreshGrant operations must be atomic database transactions (or compare-and-swap operations); the exported in-memory store is for tests only. The server enforces S256 PKCE, exact redirect URI and resource binding, JWT signing/JWKS, refresh-token rotation with family replay revocation, and live authorization checks at both code exchange and refresh through OAuthIdentityProvider.revalidateConsent (the legacy refreshConsent hook is a fallback for both). Return the unchanged subject and tenant, optional replacement application claims, and optional scopes that are a subset of the grant. Return null to deny; changing identity, tenant, or expanding scope fails closed. Omitting claims removes previous application claims. JWT protocol claims are reserved. Consent supplied to approve may also narrow the requested scopes.

Stores must implement narrowRefreshGrant when refresh tokens are issued (the constructor rejects stores without it): atomically validate the replacement token hash and active grant, then persist only a subset of its current scopes. Throw on any failure. The server revokes the family on failed live checks or narrowing persistence; it never returns the replacement. Storage failures must reject; never return success before durable commit. A connection failure after commit can leave an unreachable hash-only grant, but must not expose any token. Concrete SQL adapters and dialect tests belong to the host application.

Path issuers such as https://host/oauth advertise endpoints under /oauth and RFC 8414 discovery at /.well-known/oauth-authorization-server/oauth. Public DCR accepts only code responses, authorization-code/refresh grants, allowed scopes, and HTTPS redirects. HTTP loopback redirects require explicit allowLoopbackRedirects: true for native/development clients. Resource servers must pass their own audience to verifyAccessToken(token, audience). Access-token verification requires typ: at+jwt, expiry, issued-at, subject, audience, token ID, client ID and scope with valid claim types. Registration bodies are limited to 16 KiB while streaming, including when Content-Length is absent or understated. Metadata permits at most 10 redirect URIs of 2,048 characters each, a 256-character client name, a 2,048-character scope string, two grant types and one response type. Direct register() calls apply the same field bounds. Oversized bodies return 413 before persistence; invalid metadata returns 400. Unknown extension metadata is ignored within the body limit. Revocation returns success for unknown or invalid tokens, but storage outages return a generic 500 server_error so callers can retry after recovery. CIMD is not implemented. The signing API supports one active key; overlapping signing-key rotation is not implemented. Hosts must supply a public JWK matching the private signing key and keep private material out of JWKS.

Local Sign in with ChatGPT

Node-only local applications can import @happyvertical/auth/local to manage their Sign in with ChatGPT session. The manager uses a 127.0.0.1 loopback callback, PKCE and OIDC validation, and writes account-scoped renewable credentials atomically with owner-only permissions. Pass a configuration path outside the project directory and open the returned authorization URL in the system browser. It never exposes credentials from sessions().

Use accessToken(clientId) before an authorized request; it serializes token refreshes. logout(clientId) always clears local credentials and reports whether remote revocation was confirmed. This local runtime does not make any inference request or use browser storage.

License

MIT

Refresh storage adapters must implement narrowRefreshGrant to atomically persist both the narrowed scopes and the current claims on the exact replacement token before it is returned. An explicit undefined claims value clears previous application claims. Token and revocation form bodies share the 16 KiB streaming limit with registration. Refresh requests may request a subset of the original grant scope; expansions are rejected.

版本与发布记录

@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 是什么?

Unified authentication for Keycloak, Cognito, Nostr, and local ChatGPT sessions with OAuth2/OIDC and public key identity

如何安装 @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 和提交记录判断。