@ agentproto/ auth (英语)

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

与工作操作系统结盟 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://github.com/workos/auth.md (中文(简体) )

安装

pnpm add @agentproto/auth

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

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

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 并不经编辑登记 这个软件包——显示解析器是扩展接合器.

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

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

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

运行一流

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

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 键链, 测试中的内映图, 或 无头主机加密文件 .

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 如此的标志 写入 裁决书 不变 读取.

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

证书经纪人—— resolveHeaders

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

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 字段,所以每根针都是 一个鲜明的,真实的钱包:

{ "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数字 :

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

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

API 表面

许可证

麻省理工学院——见 自由主义。 。 。 .