# @clammet/convex-googly-auth 中文文档

规范地址：https://npmcn.com/package/%40clammet/convex-googly-auth/

版本：1\.0\.3
npm 元数据更新时间：2026-10-28T00:51:57.115Z
中文译文更新时间：2026-11-09T23:32:27.687Z
软件包许可：Unlicense

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

原始 npm 页面：https://www.npmjs.com/package/%40clammet/convex-googly-auth
原文对照：https://npmcn.com/package/%40clammet/convex-googly-auth/?lang=original
项目主页：https://github.com/clammet/convex-googly-auth#readme
源码仓库：https://github.com/clammet/convex-googly-auth

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

- 包体积（解压后）：195 kB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.43\.0
- 首次发布：2026-08-08T14:15:12.683Z
- 最新版本发布：2026-10-28T00:51:56.734Z
- 近 30 天下载量：2321（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Google OIDC + Convex应用的可选匿名身份组件.

## 安装

```sh
npm install @clammet/convex-googly-auth
```

也可以使用：`pnpm add @clammet/convex-googly-auth`、`yarn add @clammet/convex-googly-auth`、`bun add @clammet/convex-googly-auth`

## README

# 对流-谷歌-天

A 类 [对流组件](https://docs.convex.dev/components) 提供共享的 "轻松匿名/Google账户"身份计划被使用 `upgallery` 财务报告和审定财务报表 `when`: Google OIDC 登录服务器控件刷新令牌,加可选 匿名身份,由无记名无记名者索赔所支持 匿名证劫犯等级 结构固定,在一个地方.

## 安保模式

-   **谷歌登录.** Google发行ID代号; Convex 验证发行人, 并且通过应用程序签名 `convex/auth.config.ts`复习 符号从不离开组件 `authSessions` 表格 – 只有浏览器 持有不透明的 HMAC 签名的会话符号, 并交换它以换取新的 ID 通过刷新路径的符号。 每次刷新都会旋转会话符号 (有一个短的优雅窗口用于赛车标签),所以一个被过滤出的信使去 下个刷新时就停了 会议在180天后结束 默认闲置60天; 配置通过 `sessionAbsoluteTtlMs` 编号 : `sessionIdleTtlMs` 打开 `new GooglyAuth(...)`。签名使用 `prompt=select_account`; 回调会以 `prompt=consent` 只有在需要刷新令牌且没有保存时.
-   **匿名用户(可选).** 256位六分位数索赔确认 饼干 索赔是无记名秘密;只有SHA-256大麻被储存.
-   **结构性劫机预防.** 全权证书在自己的表格内 (单位:千美元)`googleCredentials`, (中文(简体) ), `anonymousCredentials`)指向一个 `identities` 排队 将匿名账户升级到 Google 登录 _删除_ 页:1 匿名证书行,所以退休的索赔不能保持第二, 密码无入帐——"标注兼有" 原图后的形状 `anonymousId` 劫持错误是 无法形容,一个防守的警卫退休 遗留下来的双重信用排 视之一见. 回归套件 `example/convex/auth.test.ts` 财务报告和审定财务报表 `src/component/lib.test.ts` 钉住所有这一切.
-   **Apps从未见过证书.** 组件将应用程序交给不透明 `identityId` 字符串; 应用程序按它自己的配置表键 。 现场 升级不变 `identityId`,所以当用户时应用程序数据不会移动 签入.

## 安装

```bash
npm install @clammet/convex-googly-auth
```

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import googlyAuth from "@clammet/convex-googly-auth/convex.config.js";

const app = defineApp();
app.use(googlyAuth);
export default app;
```

```ts
// convex/auth.config.ts
export default {
  providers: [
    {
      domain: "https://accounts.google.com",
      applicationID: process.env.AUTH_GOOGLE_ID,
    },
  ],
};
```

部署时的环境变量: `AUTH_GOOGLE_ID`, (中文(简体) ), `AUTH_GOOGLE_SECRET`, (中文(简体) ), `SITE_URL` (canonic web 起源).

## 服务器使用情况

```ts
// convex/lib/auth.ts — one instance for the whole app
import { GooglyAuth } from "@clammet/convex-googly-auth";
import { components } from "../_generated/api";

export const googly = new GooglyAuth(components.googlyAuth);
// Google-only app? Anonymous claims are then ignored server-side everywhere:
// export const googly = new GooglyAuth(components.googlyAuth, { anonymous: false });
```

```ts
// convex/profiles.ts — the app owns its profile table
export const ensureCurrent = mutation({
  args: { anonymousClaim: v.optional(v.string()) },
  handler: async (ctx, args) => {
    const result = await googly.ensureIdentity(ctx, args);
    // result.identityId  — key your profile row by this (index it!)
    // result.identity    — the verified Google UserIdentity, or null
    // result.upgraded    — anonymous identity gained Google sign-in in place
    // result.mergedFromId — an anonymous identity was absorbed into this
    //                       one; move or alias your rows keyed by it
    ...
  },
});

// In queries/mutations that need the caller:
const identityId = await googly.resolveIdentity(ctx, {
  anonymousClaim: args.anonymousClaim,
});
```

```ts
// convex/http.ts
const http = httpRouter();
googly.registerRoutes(http, {
  // All optional; defaults read AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET / SITE_URL.
  allowedOrigins: ["https://alt.example.com"],
  // Or check a table of custom domains:
  // isAllowedOrigin: async (ctx, origin) => { ... },
});
export default http;
```

挂起的路由( 可通过 `pathPrefix`: `GET /auth/google/start`, (中文(简体) ), `GET /auth/google/callback`, (中文(简体) ), `POST /auth/refresh`, (中文(简体) ), `POST /auth/sign-out`。 。 。 . 回调重定向到 `{origin}/auth/callback` 在网络应用.

可选地增加一个克龙呼叫 `googly.cleanupExpiredSessions(ctx)`。 。 。 .

## 反应使用

```ts
// src/lib/authClient.ts
import { createGooglyAuthClient } from "@clammet/convex-googly-auth/react";

export const authClient = createGooglyAuthClient({
  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL,
  googleClientId: import.meta.env.VITE_GOOGLE_CLIENT_ID,
  storagePrefix: "myapp",       // localStorage keys + claim cookie name
  // anonymous: false,          // must match the server-side option
});
```

```tsx
// main.tsx
<authClient.GoogleAuthProvider>
  <ConvexProviderWithAuth client={convex} useAuth={authClient.useConvexGooglyAuth}>
    <App />
  </ConvexProviderWithAuth>
</authClient.GoogleAuthProvider>
```

-   `authClient.useGoogleAuth()` → `{ isLoading, isAuthenticated, signIn, signOut }`
-   `authClient.useAnonymousClaim()` - 要求转让给Convex职能 (仅限Google模式)
-   在你身边 `/auth/callback` 页面调用 `authClient.handleAuthCallback()` 一次 导航到返回的 `redirect` (见 `example/src/App.tsx`(中文(简体) )
-   签到后 `ensure` 成功, 调用 `authClient.clearAnonymousClaim()`

这个 `example/` 目录是一个完整的工作应用程序; 运行测试 `npm test`消费者可以自己登记该组件 `convex-test` 套房通过 `@clammet/convex-googly-auth/test` (见 `example/convex/setup.test.ts`) (中文(简体) ).

## 移动升华 / 当移动到此组件时

两个应用程序都保留其配置表和授权逻辑;只有 证书列移入组件 .

1.  添加 `identityId: v.string()` (已索引) 到配置表; 保留 只应用字段(播放名称,角色,时区,.
2.  后填: 对于每个配置行, 插入组件行 - `googleSubject` − a 个 `googleCredentials` 排队,直播 `anonymousClaimHash` 编号 : `anonymousId` - 一个 `anonymousCredentials` 行数( 小时数) `when`简单的文字 编号为SHA-256 → 第 Base64url; **跳过任何匿名证书 具有 Google 主题的行** 这些正是可以劫持的 。 。 。 将返回的身份编号存储于 `identityId`。 。 。 .
3.  替换 `getCurrentProfile`\- 有型号的助手 `googly.resolveIdentity(...)` +a 键 `by_identityId` 剖面检索,以及 prototstrap/相生突变 `googly.ensureIdentity(...)`, (中文(简体) ), 处理 `mergedFromId` 与应用程序的现有合并策略 (上行:别名行;当: `moveProfileData`) (中文(简体) ).
4.  替换手卷 `/auth/*` HTTP 路线 `googly.registerRoutes(http, ...)` (upgallery:通过一个 `isAllowedOrigin` 回调检查 `galleryHosts`),前端则 `googleAuth.tsx` 索赔援助人员 `createGooglyAuthClient`。 。 。 .

注释:

-   签名密钥来源于 `AUTH_GOOGLE_SECRET` 加一个 `signingNamespace` (默认) `"googly-auth"`因此,现有届会和 飞行中的 OAuth 状态在迁移时无效;用户只需签名即可 再来一次.
-   `when`本地Storage UUID 软件 `anonymousId`s为无效索赔(索赔为 (原始内容存档于2017-04-26). 64-hex. 要么接受移民前的匿名访客得到新鲜 身份,或做一次性的应用程序交换:服务器向上查找 将新的索偿(客户存储)附加到同一处 身份,然后删除遗留的 id.
-   要求数 `convex >= 1.43`。 。 。 .

* * *

### 仓库布局

-   `src/component/` 组成部分:计划(身份、证书、, (b) 安排会议工作。 拥有自己的 `_generated/`。 。 。 .
-   `src/client/` - 辅助 `GooglyAuth` 类和 HTTP 路由注册 (auth + env 访问发生在应用程序,而不是组件).
-   `src/react/` ——浏览器客户端工厂.
-   `src/test.ts` —— 说 `convex-test` 注册助手(以 `@clammet/convex-googly-auth/test`) (中文(简体) ).
-   `example/` ——工作示例app+回归测试套件.

### 发展

```bash
npm install --ignore-scripts   # prepare runs a build; skip on first install
npm run build                  # or build:codegen with a configured deployment
npm run check
```

## 常见问题

### @clammet/convex-googly-auth 是什么？

Google OIDC \+ Convex应用的可选匿名身份组件\.

### 如何安装 @clammet/convex-googly-auth？

在项目目录运行 npm install @clammet/convex-googly-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.43\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clammet/convex-googly-auth 支持 TypeScript 吗？

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

### @clammet/convex-googly-auth 支持 ESM 还是 CommonJS？

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

### @clammet/convex-googly-auth 可以商用吗？

@clammet/convex-googly-auth 使用 Unlicense 许可。作者将代码贡献到公共领域，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

### @clammet/convex-googly-auth 的下载量有多少？

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

### @clammet/convex-googly-auth 还在维护吗？

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