@growth-labs/auth

中文文档
0.26.3发布于 2026/11/05TypeScriptES Module近 30 天下载 9362

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

中文使用文档
文档目录14 节
  1. 配置
  2. 输入什么
  3. 已命名的 Auth UI
  4. 服务器 SDK
  5. 分析事件
  6. 使用 context.locals.user
  7. 类型脚本
  8. 装订
  9. 融合顺序
  10. 无法接触到的发行商( 启动游戏)
  11. OAuth 流量摘要
  12. 签名身份Cookie
  13. 分析一体化
  14. 密钥模式

@ growth- labs/ auth (音乐)

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

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

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

配置

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

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/[email protected] 或新安装, 成功 调用和 JSON 校验路径 signup_completed 或者说 login_completed 结束 trackServerEvent 从 @growth-labs/analytics/utils有效载荷是:

{
  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

// 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
}

类型脚本

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。 。 。 .

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

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

验证助手 :

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 共发布 64 个版本,首次发布于 2026/04/13;过去 12 个月发布了 64 个版本。

版本发布日期距今
0.26.3latest2026/11/0511 天前
0.26.12026/11/0512 天前
0.26.02026/11/0512 天前
0.25.02026/11/0412 天前
0.24.72026/11/0413 天前
0.24.62026/11/0413 天前

关于 @growth-labs/auth 的常见问题

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