@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 用于其他关键类型.
安装
npm install @dnsid-ai/web-bot-auth @dnsid-ai/protocol
示例
签署外出请求 :
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:
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 对于这个终点.
校验请求
仅限验证的构造不需要本地身份或签名密钥:
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_urijWKS的终点.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 离舰队不移除这种暴露;专用的舰队钥匙授权需要单独的安全设计.