# @dnsid-ai/registry 中文文档

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

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

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

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

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

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

## 中文简介

DNSid 注册客户端和 TXT 出版助手.

## 安装

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

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

## README

# @dnsid-ai/登记

DNSid TypeScript软件包的注册控制-平面客户端和TXT发布助手.

此软件包拥有当前 DNSid 注册 API 表面和注册形状的生命周期/状态行为. 它有意将特定登记册国家与议定书国家分开 `@dnsid-ai/protocol` 代理状态类型.

## 安装

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

## 示例

```ts
import { RegistryClient, publishClientControlledRecord } from '@dnsid-ai/registry';
import { createRegistryClientFromEnvironment } from '@dnsid-ai/sdk/node';

// Local by default: http://127.0.0.1:7755 from `dnsid local up`, no credential.
// Hosted: set DNSID_REGISTRY_URL and DNSID_API_KEY from the console.
const registryClient = await createRegistryClientFromEnvironment();
// Or explicitly: new RegistryClient({ baseUrl, token }). HTTPS required except on loopback.

await publishClientControlledRecord({
  config,
  entityKeyProvider,
  registryClient,
});
```

## 页:1

登记册工作流程状态与协议分开 `AgentStatus`。使用 `publishClientControlledRecord()`; 登记册管理的身份使用 `awaitRegistryManagedPublication()`,它要求在成功前有经观察和核实的DNS记录. `publishToRegistry()` 仍为已贬值的相容性别名.

客户端支持自我管理、区域明确和Live注册工作流程、认证/海关请求、核查/质疑帮助者、按键准备C2SP发布和密钥旋转、记录签名、撤销、取消、未登记和退休帮助者. `registerLiveAgent()` 套装 `tier: "live"` 财务报告和审定财务报表 `managed: true` 在内部,需要单独的一等钥匙,并返回一个明显的证明挑战,而不是正常的登记。 虽然 `challenge_pending`,反应包括指定的域名和经验证的质疑记录. 签名最新解码的精确字节 `challengeMessage`;重发的挑战取代了先前的每一个挑战和消息. 准备返回时只返回不信任的精确响应字节;它不提交或附加它们. 签字前,对照其签字的参考文献验证签发 `lr` 以及后来违反身份记录的事件 这个 `DNSID-Log-Reference` 响应头被忽略 。 登记处管理的生命周期操作是单所有者的工作流程:呼叫者通过登记处提交,不得附加重复的本地生命周期事件.

### 统一登记和恢复

`registerAgent({ publicKeyJwk }, idempotencyKey?)` 请求在 登记簿的沙箱根,没有插入遗留的默认值。 可选 `domain`, (中文(简体) ), `rootDomain`,以及 `governanceDomain` 选择精确的FQDN,呼叫者拥有 积极根并预期负责的GI. `domain` 财务报告和审定财务报表 `rootDomain` 彼此之间 专有。 指定名称需要公用钥匙;登记处决定托管, 所有权、承认和是否要求精确域请求需要密钥.

客户端验证创建响应的不可改变性 `id`,域名,并需要 `publication_config`,然后读取经认证的管理状态以获取 `publicationAuthority`返回时 `publicationConfig` 财务报告和审定财务报表 `oidcIssuerUrl` 为: 创建快照,而不是从选择器推断出或被后置替换的值 状态默认。 坚持它们;它们不给予对方信任.

普通登记允许省略的密钥。 为了重试安全性,生成并坚持 键 **和第一次尝试前的登记投入**,然后重复使用 调和。 现有 `input.idempotencyKey` 继续支持。 在每次重试时不要生成新密钥 : POST 可能有 创建代理, 即使其响应或后续状态失败 . 匹配普通注册回放仍需要HTTP 201.

请求/ 答复失败 `RegistrationError` 与 `idempotencyKey`,则 原文 `input` 财务报告和审定财务报表 `cause`, (中文(简体) ), `httpStatus` 和登记册 `code` 可用时, 财务报告和审定财务报表 `creation` 包含任何已解码的创建事实(包括ID,域名, 出版物配置,以及 OIDC 发行商)。 如果 验证失败 . `domain` 在解析时也会被曝光。 如果域名已经知道, 调用 `getRegistration(error.domain)` (一) 恢复状态,不另作其他职务; 否则只用原始密钥和完整的输入重放。 不重试 无密钥的未知创建结果 。 治理-无法获取或投入-匹配 错误不会触发倒转根,替换创建,或者匿名读取. 错误不能证明创建成功或失败 。 无自动 重复进行;解决永久请求错误而不是盲目 重新尝试它们.

自动管理回收需要永久 **组织范围** 复出说法. 同名词 不同组织的低级密钥串是独立的. 命名的 SDK 设置生成密钥 从组织的ID, 普通名称, 以及初始的按键缩写; 服务器必须验证 在分配前,每个组织/名称在解剖学上要求一个非绝对身份, 拒绝相互冲突的密钥/输入,不作变异或披露。 匹配主机打开相同的 不可改变的身份。 要求在退休/删除后幸存下来 终端错误,从不替换。 明确替换使用新的钥匙、身份证、域名和 日志流,保存历史并拒绝所有以前使用的密钥.

`getOrganizationOnboarding()` 读取已验证的 `/api/v1/org/onboarding` 结束点 并验证账户/GI域和校正域的一致性。 已配置或保存的通过 `organizationId` 财务报告和审定财务报表 `governanceId` 期望比较约束. `ready` 只有在GI得到核实、大门授权和实体钥匙的情况下才属实 代表团经过核实。 失踪和待取证据仍然可用 `ready: false`他们不得授权设立。 发现不返回一个实体 JWKS URL或建立对手信任. 授权错误和 HTTP 503 仍然是错误; 失败的读取从未匿名重审 .

这些是需要的服务器合同,而不是要求部署的支助。 真实地验证 在启用命名恢复前进行服务器持续/整合测试; 已到期存储 这还不够,承认的旗帜不能确立安全.

密钥旋转准备需要所有者证书:会话饼干或组织API密钥. 不接受代理无记名证书.

登记册状态语义在认为该API稳定之前,仍可望与正在进行的登记册服务器状态工作保持一致.

遗产选择器 `environment`, (中文(简体) ), `managed`,以及 `zoneId` 继续得到支持; 清晰的 GI/ root 选择器不会被发送到服务器分辨率 . `registerSelfManagedAgent({ domain })` 财务报告和审定财务报表 `registerInZone({ zoneId, publicKeyJwk })` 保持其生产环境 默认。 准确的域名并不能保证客户端控制的出版物. 私人JWK成员和JWKS-形状的密钥在发出任何请求之前都会被拒绝. 客户控制 出版物验证每个已知的 TXT 标签 有效的出版配置. `config.maxKeyAge` 控制 `ka` 标记; 省略时, 帮助者需要 `ka` 删去。 传教士可能 通过 `effectiveMaxKeyAge` 以明确覆盖。 呼叫者必须配置 有效 `gi`, (中文(简体) ), `ek`, (中文(简体) ), `ku`, (中文(简体) ), `lr`, (中文(简体) ), `su`, (中文(简体) ), `fl`,以及 `cu` 准确的价值观.

`submitPreparedEvent()` 掷出 `PreparedEventSubmissionError` 结构化 产品错误。 仅 `TLOG_SUBMISSION_BUSY` 财务报告和审定财务报表 `TLOG_SUBMISSION_INDETERMINATE` (b) 呼叫者必须保留 重试相同的等同键和精确的条目字节 `retryWithSameBytes` 这是真的.

## 常见问题

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

DNSid 注册客户端和 TXT 出版助手\.

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

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

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

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

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

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

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

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

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

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

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

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