# @dnsid-ai/protocol 中文文档

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

版本：0\.37\.0
npm 元数据更新时间：2026-11-11T18:03:31.611Z
中文译文更新时间：2026-11-12T13:30:19.176Z
软件包许可：Apache-2\.0

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

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

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

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

## 中文简介

DNSid协议核心合同,TXT记录解析,JWKS验证,以及身份验证引擎.

## 安装

```sh
npm install @dnsid-ai/protocol
```

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

## README

# 校对:soup

DNSid TypeScript包的协议核心.

需要DNSid协议引擎和合同时使用此软件包,而无需运行时间特定的默认.

## 责任

-   `IdentityManager`
-   DNSid TXT 记录解析、验证、序列化和条形化
-   JWKS 验证和 JWK 拇指印
-   协议数据类型和严格的协议状态验证
-   DNS、取取、缓存、密钥提供者和日志合同
-   常见的 DNSid 错误和校验原始

这个包有意不包括节点DNS/HTTPS运输,本地文件系统密钥存储,环境可变加载,登记册特定生命周期行为,或配置特定方便.

## 安装

```sh
npm install @dnsid-ai/protocol
```

## 示例

```ts
import { IdentityManager } from '@dnsid-ai/protocol';

// config is data only; runtime objects are injected as dependencies.
const idm = new IdentityManager(
  {
    identity,                                  // omit for a verification-only manager
    verification: { dnssecMode: 'required', trustedEntities: [{ governanceId: 'agent.example' }] },
  },
  { keyProvider, entityKeyProvider, logRegistry, dnsResolver, cache, fetchJson },
);
```

`verification.trustedEntities` 是一个可选的对手许可列表, 请检查每个 `verifyDomain` 在协议验证后返回(包括缓存点击)。 条目匹配 已核实的记录治理 ID 准确; 可选 `entityKeyThumbprints` 针入 当前记录签名密钥。 允许它不作出接受的决定; `[]` 否认一切 A 类 拒绝提出 `VerificationError` 有代码 `CounterpartyNotAccepted` 只携带 观察 `verifiedGovernanceId`编号 :`verifiedEntityKeyThumbprint`。 。 。 .

核心没有默认的 DNS 或 HTTPS 执行, 因此 `config.transport` 设置是 在此拒绝; 使用 `@dnsid-ai/sdk/node`用来消化它们的缺省.

对于工程学节点默认值,使用 `@dnsid-ai/sdk/node` 与 `@dnsid-ai/transport`。 。 。 .

## 核查的背景和限制

`verifyDomain(domain, peerCert?, { timeoutMs?, signal? })` 还有30秒 整个操作默认值。 每个联合呼叫者保留其最后期限;共享 身份工作也有一个30秒的上限,当其最后一个呼叫者离开时被取消. DNS,HTTPS重定向,生命周期证据分担其余预算. 喷出溶液 取取器 和日志工厂必须尊重 提供的信号, 保持信任配置不变,并在分配前将其回复绑定. 本地系统 DNS 工作可能会在平台的有限背景下完成 解析器重试限制; 已取消的校验不进行, 也不填充缓存 . TXT 输入限制为 65 535个字符 1, 024个块; JWKS 和状态获取 分别要求 256 KB 和 16 KB 限制 .

被注入的缓存被每个管理器命名空格,从未单独被域共享. 配置和日志方法选择在构建时被快照; 使用 a 更改了信托政策的新经理。 DNS的过期期从寻找开始, 未完成核查。 状态刷新从不扩展, 0- TTL 答案 永远不再重复使用,在返回前检查DNS/TLS/键龄界限.

`refreshDomain(domain, peerCert?, options?)` 进行完整的核查,不 重新使用缓存身份或失败后退后。 同时刷新 共享获取,但每个呼叫者仍然通过对等和验收检查. 注射JSON采集器和木工厂必须尊崇 `revalidate: true` 通过绕行 本地缓存并重新验证上游证据。 DNS 答案保留其正常的 TTL. 旧的飞行中检查无法覆盖成功的刷新 .

## 高价值业务日志检查

`verifyDomain()` 验证对每个身份具有约束力的双边出版物。 若为 经核实的记录广告 `fl=logchk`,申请必须附加 在依赖身份之前进行当前不撤销检查 它分类为高值或不可逆:

```ts
const verified = await idm.verifyDomain('agent.example');
if (verified.requiresLogCheck()) {
  const evidence = await verified.verifyNonRevocation();
  console.log(evidence.logReference, evidence.freshnessTime);
}
```

业务分类仍然是应用政策。 打电话 `verifyNonRevocation()` 不论当地政策公布的旗帜如何 需要它来。 返回的证据确定已核实的历史界限、完整性 (a) 机制、检查站和新鲜度边界; 无法提供日志或陈旧证据的检查失败.

## 常见问题

### @dnsid-ai/protocol 是什么？

DNSid协议核心合同,TXT记录解析,JWKS验证,以及身份验证引擎\.

### 如何安装 @dnsid-ai/protocol？

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

### @dnsid-ai/protocol 支持 TypeScript 吗？

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

### @dnsid-ai/protocol 支持 ESM 还是 CommonJS？

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

### @dnsid-ai/protocol 可以商用吗？

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

### @dnsid-ai/protocol 的下载量有多少？

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

### @dnsid-ai/protocol 还在维护吗？

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