# @dnsid-ai/web-bot-auth 中文文档

规范地址：https://npmcn.com/package/%40dnsid-ai/web-bot-auth/

版本：0\.37\.0
npm 元数据更新时间：2026-11-11T18:03:29.420Z
中文译文更新时间：2026-11-13T06:04:49.490Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：120 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-09-22T12:59:25.219Z
- 最新版本发布：2026-11-11T18:03:29.022Z
- 近 30 天下载量：2158（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

DNSid Web Bot Auth 配置文件帮助器.

## 安装

```sh
npm install @dnsid-ai/web-bot-auth
```

也可以使用：`pnpm add @dnsid-ai/web-bot-auth`、`yarn add @dnsid-ai/web-bot-auth`、`bun add @dnsid-ai/web-bot-auth`

## README

# @dnsid-ai/web-bot-auth (英语)

DNSid Web Bot Auth 配置文件帮助器.

此套件标志并验证 DNSid 网络瓶 Auth 请求( RFC 9421 HTTP Messages signature with the `web-bot-auth` 标签),服务于已签名的密钥目录,并对照当前 DNSid 操作验证已发现目录(`ku`钥匙。 目标已公布 `draft-ietf-webbotauth-httpsig-protocol-00`,包括它的目录格式,而不是编辑器的副本或一个已定稿的WBA标准. 这是较窄的DNSid简介,而不是WBA的一般执行. 外部伙伴的互操作性尚未得到测试.

其基础是 `@dnsid-ai/http-signatures` 财务报告和审定财务报表 `@dnsid-ai/protocol` 合同,不进行DNS或HTTPS运输本身。 签名需要 Ed25519 操作密钥; 配置文件抛出 `ArgumentError` 用于其他关键类型.

## 安装

```sh
npm install @dnsid-ai/web-bot-auth @dnsid-ai/protocol
```

## 示例

签署外出请求 :

```ts
import { createWebBotAuthProfile } from '@dnsid-ai/web-bot-auth';

const profile = createWebBotAuthProfile({
  domain: 'agent.example',
  keyProvider, // Ed25519 operational key
});

const signed = await profile.createWebBotAuthSignedRequest(
  new Request('https://origin.example/api'),
);
await fetch(signed);
```

服务密钥目录( 以 `/.well-known/http-message-signatures-directory`:

```ts
const response = await profile.serveHttpMessageSignaturesDirectory(request);
```

目录回复与 `http-message-signatures-directory` 标签并担任 `application/http-message-signatures-directory+json`。签名日期为 `min(5, ttl - 1)` 秒而不延长寿命。 默认响应最多有295秒新鲜度并签名 `Cache-Control: max-age=295, must-revalidate`禁用 CDN 固态覆盖, `stale-while-revalidate`,以及 `stale-if-error` 对于这个终点.

## 校验请求

仅限验证的构造不需要本地身份或签名密钥:

```ts
import { createSsrfSafeFetch } from '@dnsid-ai/transport'; // Node transport

const safeFetch = createSsrfSafeFetch({}, { decompress: false });
const verifier = createWebBotAuthProfile({
  identityResolver, // RefreshingIdentityResolver, including configured entity acceptance
  discoveryFetch: request => safeFetch(request),
});
const identity = await verifier.verifyWebBotAuthSignedRequest(request, {
  signerDomain: 'agent.example', // trusted application policy
  requiredComponents: ['@method', '@target-uri'], // enforce operation binding
  peerCert, // current application peer certificate, required for fl=mtls
  timeoutMs: 30_000,
  signal,
});
```

安装 `@dnsid-ai/transport` 以使用此节点运输。 软件包保持运行时间中立 : `discoveryFetch` 需要并且必须执行有效的Web PKI, 公共地址 DNS 检查和连接在每条连接上接上, 拒绝所有重定向( 包括同为主机的 HTTPS), 取消, 以及没有解压的未修改的响应字节和标题 。 编码目录被拒绝 。 普通服务器侧 `fetch` 不值得信赖的发现是不安全的。 不允许为 WBA 的发现设定私人地址例外 .

或者,明确规定 `allowSignatureAgentDomain: true` 以让已签名的 HTTPS 发现主机识别签名符。 跨东道代表团被拒绝. `Signature-Agent` 并且其精确的密钥覆盖是强制性的,即使信任 `discovery: { uri, type }`,它现在限制着已签名的终点,而不是替换. 网络工作前失踪,被揭发,无效或不支持的发现拒绝. 默认类型是 `directory` 并且需要精确的 ASCII HTTPS 源头,没有后遗症; `jwks_uri` 地址是直接签名的目录终点,而不是未签名的JWKS。 签名重贴标签保留了被覆盖的原始发现成员.

每次引用都会验证请求和目录签名,内容摘要,以及当前的DNSid密钥绑定和接受. 没有仅目录倒置或内部目录缓存. 每个发现请求用途 `cache: 'no-store'` 财务报告和审定财务报表 `Cache-Control: no-cache`。注入的运输必须绕过本地缓存,并在每次呼叫中重新验证上游。 一个新目录丢失了密钥而未重试 。 HTTP- stale 时,即使是新得到的回复也会被拒绝. `max-age`, (中文(简体) ), `Date`, (中文(简体) ), `Age`,并获取延迟设定一个在返回前再次检查的最后期限。 重新确认 `max-age=0` 没有或零的响应 `Age` 可能有利于获得援引,因为 `no-store` 或者说 `no-cache` 回应。 注射缓存运输必须使用原始获取时间和HTTP时代元数据执行RFC 9111新鲜度,拒绝没有足够元数据的再利用,在返回同一份响应时绝不重启新鲜度. 密钥归属必须在政策背景中使用规范的发现 URL和拇指印. 更新分辨率替换更旧的密钥集,包括已删除的密钥; 命令签名的证明由 `created`。失败刷新既不能驱逐证据,也不能扩展新内容。 核查者不推断缓存再利用,也不从签名的创建时间推断出HTTP最后期限. 结果认证身份,但不批准申请。 默认要求的涵盖范围是 `@authority`,而不是方法或路径。 使用签名 `additionalComponents` 添加约束和验证符 `requiredComponents` 要求它们,精确的参数平等。 Nested WBA 签名不支持. 在发现前检查覆盖率政策;政策不当 `ArgumentError`键入 `Content-Digest` 组件必须选择 `sha-256`;不支持的成员被拒绝。 配置,包括嵌入式发现设置,在构造上被快照并验证.

一次性申请,供应 `consumeNonce(entry, signal)`它必须在解剖上消耗 `(signerDomain, keyid, nonce)` 并保留条目至 `retainUntil` (单位:千美元)`expires + clockSkew`) (中文(简体) ). 返回时 `false` ; 存储错误拒绝校验。 没有这个钩子,可以重放时间验证请求.

总体超时默认为30秒并涵盖发现,读取,DNSid验证,并重放存储. 改编内容被否决. 限制有:256个KiB目录内容,64个密钥,JSON深度16,16个KiB签名/发现/Digest头和URL,64个KiB聚合头字符,1个MiB请求内容. 主机层必须先将收到的请求流捆绑再克隆;验证保存了原来的请求正文. 签名寿命不得超过300秒. 目录签名创建不能在未来, 即使是在配置的时钟 skew 内 。 证据新鲜度在返回之前再次检查,包括证书和关键年龄。 新鲜的0-TTL DNS证据仅在获取引用中有效. 目录超时和临时的 HTTP 失败是短暂的;无效的 TLS,不安全的目的地和无效的签名仍然是永久的.

## 选项

-   `signatureAgent` 发现URI和型号 `Signature-Agent`。它默认域名的 HTTPS 源代码为 `type=directory`; 使用 `type=jwks_uri` jWKS的终点.
-   `directoryURL` ——被贬损的相容性选项,解释为直接 `jwks_uri` 终点 使用 `signatureAgent.uri` 换句话说.
-   `signatureTTL` 编号 : `directorySignatureTTL` ——签名寿命以秒计(默认:请求为60个,目录为300个).
-   `clockSkew` ——以秒计的非负校正可容忍性(默认:5);永远不允许未来目录创建.

您也可以通过签名身份管理器构建配置文件 `WebBotAuthProfile.fromIdentityManager(idm)`。 。 。 .

这个 `includeSignatureAgent` 配置和要求 `signatureAgent` 删除了省略选项。 只有目前的 DNSid 操作密钥被接受,没有重叠的密钥宽度. 需要核查 `RefreshingIdentityResolver`; 缺少 `refreshDomain` 筹集 `ArgumentError` 关于建筑。 在有效的请求和目录签名后, 当前密钥不匹配允许 `refreshDomain` 尝试每5秒一个正常的签名器域,通过同时呼叫和发现URL共享. 失败的尝试消耗了津贴;同时进行的复试被压制。 录取状态上限为 1024 个域, 完全关闭时失败 。 刷新后的证据必须经过正常的验收,流相,流相,和新鲜度检查. 没有任何驱逐工作绕过或退缩。 宣传性和可用性仍然可以中断旋转,而学习新密钥会拒绝未决的旧密钥请求.

代理域是身份FQDN,而不是其责任实体或请求目的地. WBA的发现必须和直播分开 `ku` JWKS,包括查询/分解变体. `fromIdentityManager` 拒绝本地配置 `ku` ; 核查 `ku` 终点 在代理商的公众场合验证的 HTTPS `ku` 端点提供DNSid的代理-FQDN TLS检查,没有进入爬行程序. 与 `fl=mtls`,当前仍需要应用类证据.

使用共享有管理的旋转/回收工作流程:其暂停钩必须屏蔽新的请求/指令签名并等待已有的签名操作后再解决. 检测新密钥通过验证器来请求旧密钥. 共享的 HTTP 签名器将每个返回的签名对照其元数据选中的公用密钥进行校验,并在不匹配时失败 。 当地和AWS供应商在飞行中排出签名,在激活时拒绝新的签名;定制供应商必须执行同样的合同。 对于丢失或被怀疑已失密的密钥,停止签名并使用吊销/再发,而不是常规旋转. 短 TTL 和不匹配的刷新不会撤销被窃的密钥 。 一样 `ku` 也授权 `KEY_ROTATION`:签名节点上不受限制的密钥访问可以授权身份旋转,而不仅仅是伪造请求. 保存中 `ek` 离舰队不移除这种暴露;专用的舰队钥匙授权需要单独的安全设计.

## 常见问题

### @dnsid-ai/web-bot-auth 是什么？

DNSid Web Bot Auth 配置文件帮助器\.

### 如何安装 @dnsid-ai/web-bot-auth？

在项目目录运行 npm install @dnsid-ai/web-bot-auth，或使用 pnpm add / yarn add / bun add。

### @dnsid-ai/web-bot-auth 支持 TypeScript 吗？

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

### @dnsid-ai/web-bot-auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dnsid-ai/web-bot-auth 可以商用吗？

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

### @dnsid-ai/web-bot-auth 的下载量有多少？

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

### @dnsid-ai/web-bot-auth 还在维护吗？

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