# @atproto/oauth-client-browser 中文文档

规范地址：https://npmcn.com/package/%40atproto/oauth-client-browser/

版本：0\.5\.14
npm 元数据更新时间：2026-11-06T01:43:19.714Z
中文译文更新时间：2026-11-07T03:53:21.329Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40atproto/oauth-client-browser
原文对照：https://npmcn.com/package/%40atproto/oauth-client-browser/?lang=original
项目主页：https://atproto.com/
源码仓库：https://github.com/bluesky-social/atproto

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

- 包体积（解压后）：181 kB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：9 个
- 首次发布：2024-06-18T20:02:16.027Z
- 最新版本发布：2026-11-06T01:43:19.349Z
- 近 30 天下载量：55747（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 43 个）

## 中文简介

浏览器的 ATPROTO OAuth 客户端( 在 WebCrypto 和索引 DB 上显示)

## 安装

```sh
npm install @atproto/oauth-client-browser
```

也可以使用：`pnpm add @atproto/oauth-client-browser`、`yarn add @atproto/oauth-client-browser`、`bun add @atproto/oauth-client-browser`

## README

# aproto OAuth 浏览器客户端

此软件包提供了浏览器特定的 OAuth 客户端执行 阿特罗多。 它执行所有 OAuth 特性 [意大利](https://atproto.com/ "AT Protocol") (PKCE、DPoP、, 页:1.

`@atproto/oauth-client-browser` 是为做前端应用程序设计的 没有后端服务器来管理 OAuth 会话, a. k. a" Single Page 应用程序" (SPA).

> \[大
> 
> 当后端服务器可用时,建议使用 [`@atproto/oauth-client-node`](https://www.npmjs.com/package/@atproto/oauth-client-node) 从服务器端管理 OAuth 会话并使用会话 cookie来映射 oAuth 会话到前端。 因为这个机制允许后端 要在比例上取消 OAuth 证书,此方法比 从前端直接管理 OAuth 会话。 感谢添加的 安全, OAuth 服务器在给 BFF(后端为前端).

## 设置

### 客户身份

这个 `client_id` 用于识别您在 OAuth 服务器上的应用程序 。 没错 用于获取客户端元数据并启动 OAuth 流量。 这个 `client_id` 必须是指向 [客户端 元数据](https://npmcn.com/package/%40atproto/oauth-client-browser/#readme-client-metadata)。 。 。 .

### 客户端元数据

您的 OAuth 客户端元数据应当以对应的 URL 运行 `client_id` 您的申请。 此 URL 应返回 JSON 对象与 客户端元数据。 客户端元数据应当按照 请务必尊重 [意大利](https://atproto.com/ "AT Protocol") 谱.

```json
{
  // Must be the same URL as the one used to obtain this JSON object
  "client_id": "https://my-app.com/client-metadata.json",
  "client_name": "My App",
  "client_uri": "https://my-app.com",
  "logo_uri": "https://my-app.com/logo.png",
  "tos_uri": "https://my-app.com/tos",
  "policy_uri": "https://my-app.com/policy",
  "redirect_uris": ["https://my-app.com/callback"],
  "scope": "atproto",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "application_type": "web",
  "dpop_bound_access_tokens": true
}
```

客户端元数据用于即时化OAuth客户端. 有两种方式 这样做:

1.  要么你把元数据"烧"进你的应用程序:
    
    ```typescript
    import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
    
    const client = new BrowserOAuthClient({
      clientMetadata: {
        // Exact same JSON object as the one returned by the client_id URL
      },
      // ...
    })
    ```
    
2.  或者从URL同步加载:
    
    ```typescript
    import { OAuthClient } from '@atproto/oauth-client-browser'
    
    const client = await BrowserOAuthClient.load({
      clientId: 'https://my-app.com/client-metadata.json',
      // ...
    })
    ```
    

如果性能对你很重要,建议烧掉元数据 输入脚本。 服务器侧向渲染技术也可以用于注入 在运行时将元数据输入脚本.

### 处理解析器

当您的申请启动 OAuth 流时, 它就会开始解决 (用户提供者)APTROTO操作器。 这通常通过 DNS请求. 然而,由于浏览器中没有DNS分辨率,a 必须提供后端服务.

> \[叹息\]
> 
> 使用 Bluesky 托管的服务处理解析(例如 `bsky.social` 端点)将同时将用户IP地址和处理标识器泄露给Bluesky, a 第三方。 虽然Bluesky有公开的隐私政策,但两个开发者 和应用程序的用户需要了解和了解隐私 这一安排的影响。 鼓励应用程序开发者 改善用户隐私,在何时操作自己的处理器解析服务 也许吧 如果您是 PDS 自宿主, 您可以使用您的 PDS 的 URL `handleResolver`。 。 。 .

如果有的话 `string` 或者说 `URL` 对象用作 `handleResolver`图书馆会 期望此值是运行该程序的服务的 URL `com.atproto.identity.resolveHandle` XRPC Lexicon 方法.

> \[TIP\]
> 
> 如果您主机为自己的PDS,您可以使用它的URL作为处理解析器.

```typescript
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'

const client = new BrowserOAuthClient({
  handleResolver: 'https://my-pds.example.com',
  // ...
})
```

或者,如果有“DNS over HTTPS”(DoH)服务,则可以使用 解决了手柄。 在这种情况下 `handleResolver` 应初始化 带有 `AtprotoDohHandleResolver` 实例:

```typescript
import {
  BrowserOAuthClient,
  AtprotoDohHandleResolver,
} from '@atproto/oauth-client-browser'

const client = new BrowserOAuthClient({
  handleResolver: new AtprotoDohHandleResolver('https://my-doh.example.com'),
  // ...
})
```

### 其他配置选项

何况 [客户端元数据](https://npmcn.com/package/%40atproto/oauth-client-browser/#readme-client-metadata) 财务报告和审定财务报表 [处理 解析器](https://npmcn.com/package/%40atproto/oauth-client-browser/#readme-handle-resolver),则 `BrowserOAuthClient` 构造器接受 遵循可选配置选项:

-   `fetch`: 自定义包装 `fetch` 函数。 这对 添加自定义信头、记录或使用不同的获取执行. 默认为 `window.fetch`。 。 。 .
    
-   `responseMode`数字 : `query` 或者说 `fragment`确定授权方式 响应返回客户端。 默认为 `fragment`。 。 。 .
    
-   `plcDirectoryUrl`: PLC 目录的URL. 这通常不会 除非您在本地运行整个 Atproto 堆栈 。 默认为 `https://plc.directory`。 。 。 .
    

## 使用量

一旦 `client` ,可用于启动和管理 OAuth 会话.

### 初始化客户端

客户端会为你管理会话. 要做到这一点,首先 自我初始化 。 注意这项行动必须进行一次(和 **仅限 一次**当网络应用程序被装入时.

```typescript
const result: undefined | { session: OAuthSession; state?: string } =
  await client.init()

if (result) {
  const { session, state } = result
  if (state != null) {
    console.log(
      `${session.sub} was successfully authenticated (state: ${state})`,
    )
  } else {
    console.log(`${session.sub} was restored (last active session)`)
  }
}
```

返回值可用于确定客户端是否能够恢复 上次使用的会话( x)`session` 或如果当前导航是 授权重新定向的结果 `session` 财务报告和审定财务报表 `state` 页:1.

### 启动 OAuth 流量

为了启动OAuth流,我们必须首先确定哪些PDS 将启动认证流程 。 这意味着用户必须 请提供下列资料之一:

-   用户的手柄
-   用户做到了
-   PDS/ 入口地址

利用这些信息,OAuthClient将解决所有需要的信息 以启动 OAuth 流程,并将用户重定向到 OAuth 服务器.

```typescript
try {
  await client.signIn('my.handle.com', {
    state: 'some value needed later',
    prompt: 'none', // Attempt to sign in without user interaction (SSO)
    ui_locales: 'fr-CA fr en', // Only supported by some OAuth servers (requires OpenID Connect support + i18n support)
    signal: new AbortController().signal, // Optional, allows to cancel the sign in (and destroy the pending authorization, for better security)
  })

  console.log('Never executed')
} catch (err) {
  console.log('The user aborted the authorization process by navigating "back"')
}
```

返回的承诺永远不会解决(因为用户会被重定向到 oAuth 服务器。 如果用户在其中取消标志, 承诺会拒绝 (使用 `AbortSignal`),或者用户从 OAuth 服务器返回 (因为浏览器的后向缓存).

### 处理 OAuth 回复

当用户被重定向回应用程序时, OAuth 响应将会是 可在 URL 中找到。 这个 `BrowserOAuthClient` 将自动检测 反应和处理它时 `client.init()` 名为. 或者 应用程序可以手动处理使用 `client.callback(urlQueryParams)` 方法.

### 恢复会话

客户端通过内部跟踪管理的所有会话 存储。 不论从 `client.init()` 调用,任何其他会话都可以使用 `client.restore()` 方法。 这个 如果会话已无法使用, 或已存在错误, 方法会丢出错误 变成过期.

```ts
const aliceSession = await client.restore('did:plc:alice')
const bobSession = await client.restore('did:plc:bob')
```

当前形式的客户端不披露列出所有会话的方法 在它的商店。 应用必须跟踪这些东西.

### 监视会话无效

当会话无法进行时,客户端会发出事件,以便 触发全局行为(例如显示登录页).

```ts
client.addEventListener(
  'deleted',
  (
    event: CustomEvent<{
      sub: string
      cause: TokenRefreshError | TokenRevokedError | TokenInvalidError
    }>,
  ) => {
    const { sub, cause } = event.detail
    console.error(`Session for ${sub} is no longer available (cause: ${cause})`)
  },
)
```

## 用法为 `@atproto/api`

这个 `@atproto/api` 软件包提供了与多个 Bluesky 交互的方法 具体的XRPC词汇表(`com.atproto`, (中文(简体) ), `app.bsky`, (中文(简体) ), `chat.bsky`, (中文(简体) ), `tools.ozone`(中文(简体) ) 通过 `Agent` 接口。 这个 `oauthSession` 返回时间 `BrowserOAuthClient` 可用于即时 `Agent` 举个例子.

```typescript
import { Agent } from '@atproto/api'

const session = await client.restore('did:plc:alice')

const agent = new Agent(session)

await agent.getProfile({ actor: agent.accountDid })
```

任何更新的证书 都会在引擎盖下 和新的标志 将保存在会话存储中(在浏览器索引的 DB 中).

## 预付款使用情况

### 用于开发(当地主机)

OAuth 服务器必须能够获取 `client_metadata` 对象。 最好的一个 如果你还没有部署你的应用软件 就是用地道 服务类 [无](https://ngrok.com/)。 。 。 .

这个 `client_id` 这将是类似的东西 `https://<your-ngrok-id>.ngrok.io/<path_to_your_client_metadata>`。 。 。 .

不过,回放客户有特殊情况。 循环客户端是 运行中的客户端 `localhost`。在这种情况下, OAuth 服务器将无法 以获取 `client_metadata` 对象因为 `localhost` 无法从 外边 要解决这个问题,需要Atproto OAuth服务器支持 通过提供硬码 `client_metadata` 对象.

这有几个限制:

1.  没有配置客户端元数据(名称,标志等)的方法
2.  刷新符号(如果有的话)的有效性将非常有限(通常为1个) 页:1
3.  安静的签名是不允许的
4.  仅 `http://127.0.0.1:<any_port>` 财务报告和审定财务报表 `http://[::1]:<any_port>` 可用于 作为您的应用程序的来源,以及 **没有** `http://localhost:<any_port>`这个 库将自动将用户重定向到基于 IP 的来源 (单位:千美元)`http://127.0.0.1:<port>`(a) 与下列人员一起访问原籍国时: `localhost`。 。 。 .

仅为开发目的推荐使用回转客户端. 循环 客户端可以像这样被即时化 :

```typescript
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'

const client = new BrowserOAuthClient({
  handleResolver: 'https://bsky.social',
  // Only works if the current origin is a loopback address:
  clientMetadata: undefined,
})
```

如果你需要使用一个特殊的 `redirect_uris`,您可以这样配置它们:

```typescript
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'

const client = new BrowserOAuthClient({
  handleResolver: 'https://bsky.social',
  // Note that the origin of the "client_id" URL must be "http://localhost" when
  // using this configuration, regardless of the actual hostname ("127.0.0.1" or
  // "[::1]"), port or pathname. Only the `redirect_uris` must contain the
  // actual url that will be used to redirect the user back to the application.
  clientMetadata: `http://localhost?redirect_uri=${encodeURIComponent('http://127.0.0.1:8080/callback')}`,
})
```

## 常见问题

### @atproto/oauth-client-browser 是什么？

浏览器的 ATPROTO OAuth 客户端\( 在 WebCrypto 和索引 DB 上显示\)

### 如何安装 @atproto/oauth-client-browser？

在项目目录运行 npm install @atproto/oauth-client-browser，或使用 pnpm add / yarn add / bun add。

### @atproto/oauth-client-browser 支持 TypeScript 吗？

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

### @atproto/oauth-client-browser 支持 ESM 还是 CommonJS？

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

### @atproto/oauth-client-browser 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @atproto/oauth-client-browser 可以商用吗？

@atproto/oauth-client-browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @atproto/oauth-client-browser 的下载量有多少？

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

### @atproto/oauth-client-browser 还在维护吗？

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