# @growth-labs/auth 中文文档

规范地址：https://npmcn.com/package/%40growth-labs/auth/

版本：0\.26\.3
npm 元数据更新时间：2026-11-05T12:23:24.171Z
中文译文更新时间：2026-11-17T02:38:40.218Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40growth-labs/auth
原文对照：https://npmcn.com/package/%40growth-labs/auth/?lang=original

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

- 包体积（解压后）：869 kB，299 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：hono ^4\.12\.25，astro ^6\.1\.10 \|\| ^7\.0\.0，@growth-labs/analytics \>=0\.5\.1
- 首次发布：2026-04-13T14:32:02.457Z
- 最新版本发布：2026-11-05T12:23:23.947Z
- 近 30 天下载量：9362（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

打开认证 **客户端** astro + Cloudflare 软件包。 验证JWTs,管理会话 cookie,闸门被保护路径,发布一个签名的服务器可读身份cookie,并注入登录/日志出/调回路径.

## 安装

```sh
npm install @growth-labs/auth
```

也可以使用：`pnpm add @growth-labs/auth`、`yarn add @growth-labs/auth`、`bun add @growth-labs/auth`

## README

# @ growth- labs/ auth (音乐)

打开认证 **客户端** astro + Cloudflare 软件包。 验证JWTs,管理会话 cookie,闸门被保护路径,发布一个签名的服务器可读身份cookie,并注入登录/日志出/调回路径.

**这仅仅是一个客户.** 它不运行 OpenAuth 发行器 。 峡谷发行商运行时间住在 `growth-labs/identity-platform`· ; `apps/auth-server/` 在这个repo中,只是一个最小的样本工人.

**身份,不是授权.** 回答"这个用户是谁?"——而不是"他们能访问什么?". 角色、应享待遇和保险费检查是消费者关切的问题(例如:. `@fulcrum/auth`) (中文(简体) ).

## 配置

```typescript
import auth from '@growth-labs/auth'

auth({
  issuer: 'https://auth.fedweek.com',           // Browser-facing OpenAuth issuer URL
  issuerInternal: 'https://auth-internal.example.com', // Optional back-channel issuer URL
  clientId: 'fedweek-prod',                      // Optional; defaults to request hostname
  clientSecret: 'AUTH_CLIENT_SECRET',            // Worker secret or Secrets Store binding name, resolved at request time
  resource: 'https://fedweek.com',               // Required RFC 8707 resource/JWT audience URI
  cookiePrefix: 'fedweek',                       // → fedweek_at, fedweek_rt, fedweek_provider cookies
  sessionCookieDomain: '.fedweek.com',           // Cross-subdomain sharing (optional)
  gatedPaths: ['/premium/*', '/account/*'],      // Glob patterns for protected routes
  loginPath: '/login',                           // Redirect target for unauthenticated users
  logoutRedirect: '/',
  callbackPath: '/api/auth/callback',
  passwordPath: '/password',                     // Local branded password form when renderers.password is set
  verifyCodePath: '/verify-code',                // Local branded magic-code form when renderers.verifyCode is set
  providers: ['google', 'password', 'email-code'],
  loginPage: {
    title: 'Sign in',
    brandName: 'FEDweek',
    logoUrl: 'https://media.fedweek.com/logos/header.png',
  },
  renderers: {
    // Optional all-or-nothing UI overrides per auth surface.
    // Flow logic, cookies, callback exchange, and issuer URLs remain package-owned.
    login: { module: '/src/auth/auth-render', export: 'renderLogin' },
    password: { module: '/src/auth/auth-render', export: 'renderPassword' },
    verifyCode: { module: '/src/auth/auth-render', export: 'renderVerifyCode' },
  },
  accessTokenMaxAge: 900,                        // 15 min (seconds)
  refreshTokenMaxAge: 2592000,                   // 30 days
})
```

## 输入什么

**中间软件** (每个请求运行):

1.  读取 `{cookiePrefix}_at` 财务报告和审定财务报表 `{cookiePrefix}_rt` 饼干
2.  对照内部发行商的JWKS(`{issuerInternal ?? issuer}/.well-known/jwks.json`,在工人记忆中缓存)
3.  需要访问符号 `aud` 以匹配 `resource`; 错误或缺失的受众仍然未经认证
4.  如果过期但刷新令牌有效 ~ 静默刷新, 请验证新的访问令牌受众, 然后设置新的 cookie ——每个同位素进行一对一的交换,而绝不在信标上或先入为主(那些被作为客人回答) `425`,然后下一个真正的请求刷新) —— 发行人拒绝的刷新符号被记住于 `<prefix>_rtx`; 发行者在匹配时不会再次被询问, 只有当文档导航% 60s 被第二次拒绝时, 才清除符号 cookie
5.  分布 `context.locals.user` 作为 `User | null`, (中文(简体) ), `context.locals.authSession` 会话是如何解决的,并且——每当刷新路径被输入时—— `context.locals.authRefreshFingerprint` 带有SHA-256前缀的提交刷新符号(决不是符号),用于将一个站点的会话活动加入发行商的发行 `tokenFingerprint`
6.  如果路径匹配 `gatedPaths` 财务报告和审定财务报表 `user` 无效 重新定向到 `loginPath`

**路线 :**

-   `GET /login` 提供者-选择网页; `?provider=google|password|email-code` 启动本地认证并重定向到发行人的通用 `/authorize` 结束点
-   `GET /logout` ——清除饼干,撤销内部发行商的刷新令牌,重新定向
-   `GET /api/auth/callback` – OAuth 调用处理器( PKCE 代码交换, cookie seting)
-   `GET /forgot-password` 编号 : `GET /reset-password` ——本地重定向到发行者拥有的密码 UI, 除非配置出纸器
-   `GET /password` 编号 : `GET /verify-code` - 本地品牌密码和魔法码查看时 `renderers.password` 编号 : `renderers.verifyCode` 已配置
-   `POST /api/auth/password/verify`, (中文(简体) ), `/api/auth/code/request`, (中文(简体) ), `/api/auth/code/verify`, (中文(简体) ), `/api/auth/password/reset/request`, (中文(简体) ), `/api/auth/password/reset/confirm` ——包自有后通道表单处理器,通过JSON API调用发行者 `issuerInternal`,然后返回 a `303` 浏览器重定向或 JSON 重定向合同 `Accept: application/json` 请求

## 已命名的 Auth UI

消费者可以供应 `renderers.login`, (中文(简体) ), `renderers.forgotPassword`,以及 `renderers.resetPassword` 内 `auth()` 选项。 消费者想要 密码和魔法码步骤可以保留在自己的域中,也可以提供 `renderers.password` 财务报告和审定财务报表 `renderers.verifyCode`每个渲染器收到一个 从 `@growth-labs/auth/types` 带有本地格式的软件包 操作、 提供者或发行者 URL, 以及品牌值, 然后返回一个 HTML 字符串或一个 `Response`。 。 。 .

渲染器只替换格式视图 。 召回,登出,交换信使, cookie, PKCE/状态, POST CSRF 检查, 以及发行商的通讯 软件包拥有。 何时 `renderers.password` 或者说 `renderers.verifyCode` 已配置, `/login` 将这些供应商按钮链接到本地品牌路由;否则 保持现有发行商托管的 OpenAuth UI 流量.

被遗忘/重置的渲染器既接收历史发行商的URL,又接收新的 本地 API 格式目标 。 使用 `passwordResetRequestUrl` 财务报告和审定财务报表 `passwordResetConfirmUrl` 用于消费者托管的重置表格.

软件包拥有的 POST 路线对本地表格安全,并加固 造物师. 收到的土著表格 `303 See Other` 调头 获取呼叫者应该 发送 `Accept: application/json`; 成功返回 `{ ok: true, redirect }`,以及 返回错误 `{ error, redirect }` 带有 `400` 状态。 后置请求不包含 同一来源 `Origin` 拒绝标题为 `403` 在发行人 电话.

## 服务器 SDK

```ts
import { authClient } from '@growth-labs/auth/server'

const client = authClient(context)

await client.password.verify({ email, password })
await client.code.request({ email })
await client.code.verify({ email, code })
await client.password.reset.request({ email })
await client.password.reset.confirm({ token, newPassword })
```

`authClient(context)` 读取已解析的集成配置和工作人 绑定,帖子到 `{issuerInternal ?? issuer}/api/v1/auth/*`,解决 `clientSecret` 应请求保存绑定名称 使用模块 - 私密请求 - 寿命缓存存储 `(Request, binding name)`发送 `client_secret_basic` 保密客户,以及 包含 `client_id`, (中文(简体) ), `redirect_uri`电脑交换中心 `code_challenge`, (中文(简体) ), `state`,以及 `resource` 签发授权代码 打电话 密码重置请求呼叫还包括 `reset_url_base` 从 当前消费源, 发行商可以将重置链接发送回相同的 注册主机。 软件包拥有的 POST 路线直接使用这种 SDK ; 消费者也可以从自定义服务器路由中使用.

如果配置的保密客户端装订缺失, 空的, 每一个 SDK 方法均不正确或被拒绝 `{ error: 'auth_service_unavailable' }` 并且不执行发行人请求.

## 分析事件

何时 `@growth-labs/analytics@0.4.0` 或新安装, 成功 调用和 JSON 校验路径 `signup_completed` 或者说 `login_completed` 结束 `trackServerEvent` 从 `@growth-labs/analytics/utils`有效载荷是:

```ts
{
  provider: 'google' | 'password' | 'email-code' | 'unknown',
  isNewUser: boolean,
  auth_path: string,
  identity_user_id: string,
}
```

事件来自消费网站请求的背景,所以分析 可以保存网站的匿名 `visitor_id`, (中文(简体) ), `session_id`属性 饼干,和 `gl_identity_links` 排队 身份平台不需要这个 查看网站归属饼干.

Auth 失败释放操作事件 `auth_failed` 与 `provider`, (中文(简体) ), `reason`,以及 `auth_path`失败的有效载荷从不包含原始载荷 电子邮件地址,密码,魔法代码,或重设符.

## 使用 `context.locals.user`

```typescript
// Gated page — user guaranteed authenticated
const { user } = Astro.locals
// user.id, user.email, user.name, user.avatarUrl

// Non-gated page — check first
if (user) {
  // show personalized content
}
```

## 类型脚本

```typescript
interface User {
  id: string
  email: string
  name?: string | null
  avatarUrl?: string | null
}

// Available as User | null on context.locals.user (Astro.locals.user in .astro files)
```

## 装订

`GL_IDENTITY_SECRET` 当分析仪表板需要登录与匿名分区时,则需要。 必须是32字节的秘密编码,并有标准基数64,每个租户都应该独一无二.

注入的路由读取“工人绑定” `cloudflare:workers`,匹配 Astro 6 + `@astrojs/cloudflare` v13. 他们不依赖 `Astro.locals.runtime` 或者说 `context.locals.runtime`。 。 。 .

发行商需要 KV + D1 ——参见 `growth-labs/identity-platform` 用于生产运行时形状,或 `apps/auth-server/README.md` 这里的样本很少.

## 融合顺序

Auth 中间软件 MUST 在同意和分析中间软件之前运行. 列表 `auth()` 先进 `astro.config.mjs` 集成数组.

## 无法接触到的发行商( 启动游戏)

JWKS被缓存于工人记忆. 如果冷起步时无法接触到发行者 :

-   **非建议路径 :** 无法打开.. `user = null`,页面正常服务
-   **有线路径 :** 已关闭失败 — 重定向到登录Path

此普通发行者无法获取的行为不适用于配置 客户端秘密解析失败 。 如果有刷新符号,则 中间软件在访问端验证和返回前解决了这个秘密 a 固定的503,不带JWKS或发行器取取. 浏览器请求收到纯 \* 文本; `Accept: application/json` 收到的请求 `{"error":"auth_service_unavailable"}`。日志仍然清除本地饼干.

驱逐JWKS缓存没有公开运行时间/admin API. 缓存 遵守工人隔离生命周期的规定; `_resetJwksCache()` 是一个 内部软件包测试帮助器,而不导出 `@growth-labs/auth/utils`。 。 。 .

## OAuth 流量摘要

1.  用户点击本地登录页面上的供应商 – 浏览器点击 `/login?provider=...` 或当地品牌 `/password` 编号 : `/verify-code` 配置渲染器时的路由
2.  当地 `/login` 启动路由存储 PKCE/状态/重定向/提供者 cookie并重定向到 `{issuer}/authorize?provider=...`; 已配置 `resource` 作为RFC 8707资源指标发送。 消费者主办 `/password` 财务报告和审定财务报表 `/verify-code` 页面种子 `{cookiePrefix}_pkce` 两者 `/` 财务报告和审定财务报表 `callbackPath`:root-path复制件可见于软件包拥有的POST处理器和JSON验证流量,而Callback-path复制件则通过Callback路由保留了原生形式交接. 被遗忘的密码路由种子 本地流 cookie 但没有设置一个提供者 cookie .
3.  对于消费者托管的密码或魔法码流,包拥有的POST线路呼叫 `{issuerInternal ?? issuer}/api/v1/auth/*`; 接收本地表格 `303` 重定向通过 `/api/auth/callback?code=...&state=...`时 `Accept: application/json` 验证调用者在位置上交换代码, 设定会话 cookie, 发送成功事件并接收 `{ ok, redirect }` 为最终目的地.
4.  发行人认证或发布 JSON 授权代码 – 回调交换代码 `{issuerInternal ?? issuer}/token` 通过PKCE,发送 `Authorization: Basic base64(client_id:client_secret)` 何时 `clientSecret` 包含 `resource`,读取 `properties.isNewUser` 从JWT有效载荷返回到顶级 `isNewUser` 对于遗留的发行者,使用 `{cookiePrefix}_provider` 登录时设置了认证流程 cookie , 用于提供者归属、 设定会话 cookie、 设定 `gl_id` 何时 `GL_IDENTITY_SECRET` 配置、 释放成功/失败分析, 并重定向到原始页面或返回 JSON 重定向合同 `Accept: application/json`。 。 。 .

## 签名身份Cookie

`gl_id` 允许服务器侧分析器区分登录请求,而不将PII存储在工人分析引擎中,也不信任一个客户端可写入的旗帜.

-   格式 : `<base64url(payload)>.<base64url(hmac_sha256(payload_bytes, secret_bytes))>` 没有补丁
-   有效载荷: 小写十六进制 `sha256(sub + GL_IDENTITY_SECRET)`时 `sub` 是访问对象。 原始主题从未被写入饼干.
-   秘诀 : `GL_IDENTITY_SECRET`32字节标准基数64
-   属性 : `HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=2592000`
-   发布: 回调成功或 JSON 在符交换后验证成功
-   已清除 : `/logout` 与 `Max-Age=0`

验证助手 :

```typescript
import { verifyIdentityCookie } from '@growth-labs/auth/utils'

const result = await verifyIdentityCookie(cookieValue, env.GL_IDENTITY_SECRET)
if (result.valid) {
  console.log(result.payload) // 64-char opaque hex digest
}
```

`signIdentityCookie(payload, secret)` 财务报告和审定财务报表 `verifyIdentityCookie(cookieValue, secret)` 使用网络加密( W)`crypto.subtle`并且是同声的。 Cookie在签署前就把信使主题搁置了.

## 分析一体化

可选分析助手 `login_completed`, (中文(简体) ), `signup_completed`,以及 `auth_failed`。成功事件名称来源于 从访问文件夹 JWT `isNewUser` 索赔,主张 `payload.properties.isNewUser` 然后掉回顶层 `payload.isNewUser` 为遗产发行商。 软件包使用公众 `@growth-labs/analytics/utils.trackServerEvent` 可选合同时 已安装分析端点 .

## 密钥模式

-   虚拟模块 : `virtual:growth-labs/auth/config` (斜,不是连字符)
-   Cookie 名称 : `{cookiePrefix}_at`, (中文(简体) ), `{cookiePrefix}_rt`, (中文(简体) ), `{cookiePrefix}_pkce`, (中文(简体) ), `{cookiePrefix}_state`, (中文(简体) ), `{cookiePrefix}_redirect`, (中文(简体) ), `{cookiePrefix}_provider`, (中文(简体) ), `gl_id`
-   PKCE 流动 `code_verifier` 编号 : `code_challenge` (S/256); `{cookiePrefix}_pkce` 范围为 `callbackPath` 用于发行者重定向流量,并设置在两者 `/` 财务报告和审定财务报表 `callbackPath` 用于消费者托管的密码/代码流,既可在现场张贴JSON,也可交出回调
-   `issuer` 是浏览器- 显示; 可选 `issuerInternal` 用于符号交换、静态刷新、JWT核查/JWKS查询和撤销。 如果省略,则, `issuerInternal` 倒计时 `issuer`。 。 。 .
-   `issuerFetch` (仅限工人客户端):用于这些后道通话的取回. 一个工人 **同一云层区域** 由于发行人必须在此通过服务装订的取回(`issuerFetch: (input, init) => env.IDENTITY.fetch(input, init)` 与 `[[services]] binding = "IDENTITY" service = "<issuer worker>"`),因为同区工人/工人 `fetch()` 以主机名失败 。 全局默认值 `fetch`。 。 。 .
-   使用机密用户 `client_secret_basic` 值交换和刷新时 `clientSecret` 已配置。 偏好工人秘密或 Cloudflare 秘密存储器绑定名称, 如 `AUTH_CLIENT_SECRET`; 运行时代码解决了每次绑定一次 `(Request, binding name)` 在模块-私有请求-寿命缓存中,在发行者/JWKS I/O之前返回固定的已关闭的503或SDK出错。 没有缓存符号、承诺、结果或秘密字节附在可见消费者身上 `Request`。 。 。 .
-   RFC 8707 (英语) `resource` 以授权、 令牌交换和配置时刷新方式发送
-   `email-code` 是发行方 OpenAuth 的客户端别名 `code` 提供者
-   CSRF 状态参数在回调时被验证
-   A. 用户使用权要求 `payload.properties.*`; 客户端倒回顶级 `payload.email`, (中文(简体) ), `payload.name`, (中文(简体) ), `payload.image`,以及 `payload.isNewUser` 遗产发行人
-   被遗忘/重置的密码路由仍可以是发行商拥有的重定向或使用渲染器提供的本地API格式目标
-   软件包自定义 POST 路由需要同样来源 `Origin` 页眉; 缺少 或跨场表格提交回复 `403`
-   使用标记认证屏幕 `renderers`,而不是消费者-地方影子路线
-   访问端 `aud` 必须匹配配置的 RFC 8707 `resource` 没错
-   `.astro` 组件文件为源文件, 未编译

## 常见问题

### @growth-labs/auth 是什么？

打开认证 客户端 astro \+ Cloudflare 软件包。 验证JWTs,管理会话 cookie,闸门被保护路径,发布一个签名的服务器可读身份cookie,并注入登录/日志出/调回路径\.

### 如何安装 @growth-labs/auth？

在项目目录运行 npm install @growth-labs/auth，或使用 pnpm add / yarn add / bun add。

### @growth-labs/auth 支持 TypeScript 吗？

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

### @growth-labs/auth 支持 ESM 还是 CommonJS？

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

### @growth-labs/auth 可以商用吗？

@growth-labs/auth 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @growth-labs/auth 的下载量有多少？

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

### @growth-labs/auth 还在维护吗？

最新版本 0\.26\.3 发布于 2026/11/05（11 天前）；至今共发布 64 个版本，其中过去 12 个月发布了 64 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

