# @agentproto/auth 中文文档

规范地址：https://npmcn.com/package/%40agentproto/auth/

版本：1\.4\.0
npm 元数据更新时间：2026-10-27T13:34:11.464Z
中文译文更新时间：2026-11-05T22:37:14.798Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40agentproto/auth
原文对照：https://npmcn.com/package/%40agentproto/auth/?lang=original
项目主页：https://agentproto.sh/docs/aip-50
源码仓库：https://github.com/agentproto/ts

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

- 包体积（解压后）：341 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-06-20T17:05:21.158Z
- 最新版本发布：2026-10-27T13:34:10.872Z
- 近 30 天下载量：11624（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

@agentproto/auth — AIP-50 AUTH.md 参考执行. Auth-professor doctype:CLI工具和代理如何通过标准化的发现链和可插流引擎认证到API服务器,与WorkOS auth.md开放标准相配合.

## 安装

```sh
npm install @agentproto/auth
```

也可以使用：`pnpm add @agentproto/auth`、`yarn add @agentproto/auth`、`bun add @agentproto/auth`

## README

# @ agentproto/ auth (英语)

第50条 `AUTH.md` 参考执行。 认证提供者 Doc 类型: 下标 + 前题(或 TS- 升) 显示为 API 服务器, **怎么样** (单位:千美元) CLI 工具或代理认证 **地点** 将AIP-19条款称为 结束点。 它拥有配置,从不认证——流动引擎读取或 运行时提示证书.

与工作操作系统结盟 [auth.md 数据](https://github.com/workos/auth.md) 打开标准 : 双跳 `.well-known` 发现 `agent_auth` 元数据块和 (b) 索赔仪式`urn:workos:agent-auth:grant-type:claim`) (中文(简体) ).

> **状态:0.2.0-α.** V1 中指定的两个流量 (`pat`, (中文(简体) ), `service-auth`(三); `id-jag` (agentproto-as-IdP)是保留.

谱: [https://agentproto.sh/docs/aip-50 (中文(简体) )](https://agentproto.sh/docs/aip-50) 标准: [https://github.com/workos/auth.md (中文(简体) )](https://github.com/workos/auth.md)

## 安装

```bash
pnpm add @agentproto/auth
```

## 两个作者路径, 一个验证的形状

单一Zod计划(`./schema.ts`)倒行两道,因此字形不整并 a 错误 `.md` 与同样的诊断失败.

### TS 字义

```ts
import { defineAuthProvider } from "@agentproto/auth"

export const guilde = defineAuthProvider({
  id: "guilde",
  description: "Guilde AI company platform — browser-approve, no key to paste.",
  apiBase: "https://api.guilde.work",
  auth: {
    flow: "service-auth",
    clientId: "agentproto-cli",
    tokenStore: { keychain: "bureau-guilde", account: "{server}" },
  },
  install: {
    sealKey: "/guilde/api/v1/connectors/seal-key",
    secretBacked: "/guilde/api/v1/guilds/{guildId}/connectors/secret-backed",
  },
})
```

### `.md` 显示

主办方读取自己的供应商 `*.auth.md` 并不经编辑登记 这个软件包——显示解析器是扩展接合器.

```md
---
id: acme
description: ACME API — paste a personal access token.
apiBase: https://api.acme.example
auth:
  flow: pat
  tokenStore:
    keychain: acme-cli
    account: "{server}"
---

# ACME

Human/LLM-facing prose about how to obtain a token lives in the body.
```

```ts
import { parseAuthProviderManifest, registerAuthProvider } from "@agentproto/auth"

const acme = parseAuthProviderManifest(await readFile("acme.auth.md", "utf8"))
registerAuthProvider(acme)
```

## 运行一流

`runAuthFlow` 解决提供者、尝试发现和发送到 选择的引擎 `provider.auth.flow` 没有 `if`编号 :`switch` 连锁在呼叫站点.

```ts
import { getAuthProvider, runAuthFlow } from "@agentproto/auth"

const provider = getAuthProvider("guilde")!
const result = await runAuthFlow(provider, { server: "https://api.guilde.work" })
// → { accessToken: "oat_…", tokenKind: "oat" }
```

### `pat` 流动

从平台 Keychain 读取已有的令牌, 或快速读取一个 互动. 没有浏览器,没有仪式——服务器的与遗产兼容的路径 签发个人访问钥匙.

### `service-auth` 流动

Auth.md 索赔仪式:

1.  `POST {identity_endpoint}` 与 `{ type: "service_auth", client_id }` → `claim_token` + 键 `claim.{ user_code, verification_uri, expires_in }`。 。 。 .
2.  打开浏览器 `verification_uri`;用户批准.
3.  票价 `POST {token_endpoint}` 与 `grant_type=urn:workos:agent-auth:grant-type:claim` 财务报告和审定财务报表 `claim_token` 直至 `access_token` 返回( e)`authorization_pending` 编号 : `slow_down` 编号 : `expired_token` 编号 : `access_denied` 由RFC 8628处理.
4.  成功时,请存储 **`identity_assertion` 日本** 关键链中 AIP-50, 断言是持久的证书 `access_token` 实值 麻风并 **从来没有坚持过**,则 `claim_token` 留在内存中 只有这个.

在接下来的一次运行中, 仪式尽可能跳过: 存储的断言 在符号端点通过 `urn:ietf:params:oauth:grant-type:jwt-bearer` 为了新鲜的 `access_token` (这个) 是新鲜的路径, 只有在主张到期或 被拒绝(`invalid_grant`) 开始一个新的浏览器仪式.

## 发现

`discoverEndpoints(apiBase)` 执行双跳链和 **掷出 `DiscoveryError`** 当服务器在 auth.md 之前。 打电话的人抓住它然后退后 到静态的表征配置——发现失败绝不能阻挡静态流.

```
GET {apiBase}/.well-known/oauth-protected-resource     → authorization_servers[0]
GET {authServerBase}/.well-known/oauth-authorization-server
                                  → token_endpoint + agent_auth.identity_endpoint
```

每个请求(发现、仪式、刷新)都以每个请求为界 超时( e)`DEFAULT_HTTP_TIMEOUT_MS`,通过 `discoverEndpoints(base, { timeoutMs })`和荣誉的来电者 `AbortSignal` (单位:千美元)`{ signal }` 编号 : `FlowRunOptions.signal`),所以挂起的服务器永远不能拖住CLI. 回应 是在边界上验证的而不是信任的.

## 托肯存储

`token-store.ts` 是平台开关 **守护平台** —— 说 `readKeychainToken` 编号 : `writeKeychainToken` 在没有后端时丢出一个明显的错误 而不是默默返回 `undefined` (这将会重现每一次) 运行)。 macOS 包装 `security` CLI; Windows (cap D7) 封存一个 DPAPI 保护文件 `~/.agentproto/keychain-dpapi/` 通过.NET `ProtectedData` 时间 `CurrentUser` 通过PowerShell——每个用户 加密, 0 npm 依赖性, 并且除了股票之外没有其他任何 (不需要证书) Linux 仍未执行; libsecret就相当于这里. `resolveAccount(account, server)` 扩展 `{server}` 模板在一个 `tokenStore.account` 谱.

## 证书存储

流动引擎从不碰混凝土后端——它们依赖于 `CredentialStore` 接口,所以相同 `pat` 编号 : `service-auth` 流量运行 反 CLI 中的 macOS 键链, 测试中的内映图, 或 无头主机加密文件 .

```ts
interface CredentialStore {
  read(ref: StoreRef): Promise<StoredCredential | undefined>
  write(ref: StoreRef, cred: StoredCredential): Promise<void>
  delete?(ref: StoreRef): Promise<void>   // optional — backend permitting
}

interface StoreRef { path: string; account?: string }      // where it lives
interface StoredCredential {                               // what's stored
  value: string
  kind: "pat" | "assertion" | "oat"
  expiresAt?: string
  metadata?: Record<string, unknown>
}
```

`resolveStoreRef(tokenStore, server)` 绘制提供者的地图 `tokenStore` 光谱 (扩大 `{server}` 模板)改为a `StoreRef` 如此的标志 **写入** 裁决书 **不变** 读取.

| 后端 | 使用 |
| --- | --- |
| `KeychainStore` | 马科斯 `security` CLI — 交互式- CLI 默认 |
| `MemoryStore` | 麻黄,测试用 |
| `FileStore` | AES-256-GCM在休息;密钥来自 `AGENTPROTO_STORE_KEY`, (中文(简体) ), **没有正文倒置** 用于无键链的无头主机 |

主机可以在自己的金库上执行接口(Guilde用一个 AAD 受限,每个用户的秘密服务。 流动引擎最聪明了.

## 证书经纪人—— `resolveHeaders`

经纪人是"Agent.pw平面":给它一个 **路径**回来 备用 HTTP 认证信头 _新鲜_ 符号在呼叫时解决。 这个 将存储的证书( 或全流运行) 转换为 `{ Authorization: "Bearer …" }` 没有打电话的人知道是什么.

```ts
import { CredentialBroker } from "@agentproto/auth"

const broker = new CredentialBroker({ store, getProvider: getAuthProvider })

const headers = await broker.resolveHeaders({
  path: "guilde",              // "<providerId>" or "<providerId>/<account>"
  server: "https://api.guilde.work", // optional; defaults to provider.apiBase
  signal,                      // optional AbortSignal
})
// → { Authorization: "Bearer oat_…" }
```

`resolveHeaders`数字 :

1.  剖析 `path` → `providerId` (+ 可选) `account`解决 供应商通过 `getProvider`· ; **掷出** 在一个不知名的提供者身上;
2.  如果存储的无记名证书是 还是 **新鲜** (过去是60s skew),直接返回;
3.  以其他方式管理提供者的流量(`runAuthFlow`,线程相同 `store` + 键 `signal`)——用于 `service-auth`说到这里 `jwt-bearer` 交换——并返回已铸造的代币;
4.  如果流量未产生可用访问符,则丢出.

**新鲜的,没有长寿头缓存.** 这是无头/克龙 支付: 计划代理人重解有效 `Authorization` 连接时间 只要有耐用证书(PAT,或 `service-auth` 在商店里坐着.

> **可运行实例 :** `src/__tests__/broker.example.test.ts` 是一个 零摩克、可复制的窃听(提供商) · 商店 · 经纪人 · `resolveHeaders`你可以抬起逐字记录.

### 供餐 MCP 运输工具

`@agentproto/secrets/exposure` 声明a **结构** `McpHeaderResolver` (单位:千美元)`resolveHeaders({ path, server?, signal? })`这 `CredentialBroker` 满足于没有适配器——因此连接器可以声明一个 `mcp-header` 接触和拥有 `resolveMcpHeaderExposure(exposure, broker)` 经纪人 信头放在运输工具上. `secrets` 保留 **零依赖性** 打开 `auth` 穿过结构接缝 见 `@agentproto/secrets`'读取.

## 分账户

一个 _账户_ (登录或计费身份) _子账户_ - 猪, 工作空间、项目——每个项目都有自己的配额。 一张画夹上一张 选项 `subaccount` 字段,所以每根针都是 一个鲜明的,真实的钱包:

```jsonc
{ "id": "acme-ws01", "endpoint": "<endpoint>", "method": "api-key",
  "source": "<account-source>", "subaccount": { "kind": "org", "id": "org_01ABC", "name": "Ws01" } }
```

`kind` 实值 `[a-z][a-z0-9-]*`· ; `id` 不透明; `name` 是用于 使用限制标记 。 字段是可选的,在盘存储格式是 不变。 CLI: 爱丽丝 `agentproto auth profile create <id> --subaccount <kind>:<id>` 财务报告和审定财务报表 `agentproto auth subaccounts list <profile|account> [--create [--prefix]]`。 。 。 .

钉子是怎样的 _应用_ 属于提供者,绝不属于此软件包或软件包 运行时间。 提供工具 `SubaccountProvider` 添加为 `registerSubaccountProvider`数字 :

| 成员 | 目的 |
| --- | --- |
| `id`, (中文(简体) ), `source?`, (中文(简体) ), `endpoints?`, (中文(简体) ), `kinds` | 身份,以及它拥有的账户 `source` 名称, 否则以终点表示) |
| `list(account)` | 发现 : `{ account, subaccounts: [{kind, id, name}] }` |
| `resolve(profile, { credential? })` | 产卵时间 : `{ credential?, credentialEnvOverride?, env?, isolateDataHome? }` |
| `migrateLegacySource?(source)` | 预针提供者编码的读取时间迁移 `source` 进入针口 |

提供者抛出 `SubaccountError` 无法列出或解开指针时 运行时会响亮地失败 而不是回到账户的默认状态 范围。 供应商携带适配器出船,并由东道主登记(CLI) 对内设人员来说,是这样做的.

登记册是全过程的,并启动EMPTY:一个使用 `@agentproto/auth` 在CLI之外必须呼叫 `registerSubaccountProvider` 页:1 在创建、读取或生成被绑定的剖面之前,它需要每个提供者. 在那之前,创建一个有遗产的简介 `opencode-console:<orgId>` 来源是 被否决,在被封存的图谱上产卵,其供货商没有注册失败 与 `auth_source_unresolved` (它从未运行在账户的默认范围). A 类 证书支持的配置文件上的 pin 在创建时被接受, 即使没有 提供者拥有它的终点;明显的错误发生在产卵时间.

## API 表面

| 导出 | 目的 |
| --- | --- |
| `defineAuthProvider(def)` | TS-立体写作 ^ 被冻结的手柄 |
| `parseAuthProviderManifest(src)` | `.md` 写作 — 被冻结的手柄 |
| `registerAuthProvider` 编号 : `getAuthProvider` 编号 : `listAuthProviders` 编号 : `listAuthProviderIds` | 模块级登记册(使用内建件种子前) |
| `discoverEndpoints` 编号 : `DiscoveryError` | 双跳 `.well-known` 发现 |
| `runAuthFlow` | ——发现——发送 |
| `FLOW_ENGINES` | 注册的流动发动机(`pat`, (中文(简体) ), `service-auth`(中文(简体) ) |
| `CredentialBroker` 编号 : `CredentialBrokerOptions` | 路径 \\ 新鲜 `resolveHeaders` |
| `eligibleProfiles` | `(adapter × route) → vendor + profile eligibility predicate` |
| `CredentialStore` 编号 : `StoreRef` 编号 : `StoredCredential` | 可插件存储界面+形状 |
| `KeychainStore` 编号 : `MemoryStore` 编号 : `FileStore` 编号 : `resolveStoreRef` | 内建后端 + ref 解析器 |
| `readKeychainToken` 编号 : `writeKeychainToken` 编号 : `resolveAccount` | 键链助手 |
| `guildeAuthProvider` 编号 : `BUILTIN_AUTH_PROVIDERS` | 已运出内建 |
| `registerSubaccountProvider` 编号 : `findSubaccountProvider` 编号 : `listSubaccountProviders` | 子账户提供者登记处 |
| `SubaccountProvider` 编号 : `SubaccountPin` 编号 : `SubaccountError` 编号 : `parseSubaccountPin` | 分账户合同 |

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40agentproto/auth/LICENSE)。 。 。 .

## 常见问题

### @agentproto/auth 是什么？

@agentproto/auth — AIP-50 AUTH\.md 参考执行\. Auth-professor doctype:CLI工具和代理如何通过标准化的发现链和可插流引擎认证到API服务器,与WorkOS auth\.md开放标准相配合\.

### 如何安装 @agentproto/auth？

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

### @agentproto/auth 支持 TypeScript 吗？

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

### @agentproto/auth 支持 ESM 还是 CommonJS？

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

### @agentproto/auth 可以商用吗？

@agentproto/auth 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agentproto/auth 的下载量有多少？

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

### @agentproto/auth 还在维护吗？

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