@dharma-ai-labs/agent-fabric-relay-client

中文文档
0.2.37发布于 2026/11/05MITTypeScriptES Module构建来源已验证近 30 天下载 1970

Outbound signed device enrollment and relay client for Dharma Agent Fabric

原始使用文档

@dharma-ai-labs/agent-fabric-relay-client

Outbound device enrollment and relay client for Agent Fabric. It uses device signatures, nonce and sequence replay protection, durable cursors, idempotent receipts, and organization-scoped browser approval. It does not expose an inbound shell or arbitrary local-file API.

Read-only signing-expiry recovery planning

planDeviceSigningRecovery() prepares local public context under a mandatory owning-host scope. The host supplies already verified source consent and native session selections, never model/challenge declarations. The function reads the selected device configuration and its matching protected public enrollment anchor with fresh reads and readOnly: true. It does not migrate an old anchor, read a private key, generate an identity, contact the server, issue a proof or change trust. A second configuration read rejects replacement during planning; scope withdrawal and elapsed session/15-minute limits deny output.

The plan is explicitly local_context_only_not_recovery_authorization. It does not authenticate the selections against current server membership, role, revocation, source policy or a live native session. Its recorded budget is only an input to a binding digest, not new spending authority. The old anchor does not itself attest installation, membership or source selection; the server and trusted native caller must independently verify those before approval/use. This API is not yet wired to bootstrap or an executable recovery command.

Canonical bindings use the existing canonicalize() UTF-8 JSON representation:

  • sourceSelectionDigest: SHA-256 of dharma.agent-fabric.signing-recovery-source-selection/v1 + NUL + canonical JSON of the exact source-selection fields and the existing public setupClaimReference. Source consent references map to the original generation/receipt/revision/policy-hash records, not raw repository contents.
  • nativeSessionBindingDigest: SHA-256 of dharma.agent-fabric.signing-recovery-native-session/v1 + NUL + canonical JSON of {session, hostBinding, installationId}. The session selection binds the exact member/device/repository/workspace/endpoint/binding/provider, named session/owner/times/budget; the host selection binds connection/context/thread/ turn. Private local paths, cookies, transcripts and credentials are excluded.
  • previousAnchorHash, protectedConfigDigest and previousKeysetHash: SHA-256 of canonical JSON of the exact corresponding public snapshots. The configuration hash includes the merged on-disk connection preference but changes none. It is not protected-store attestation; only the anchor snapshot comes from the protected store.
  • previousRootFingerprint: SHA-256 of the canonical decoded 32-byte Ed25519 public root. Digests use the sha256: lowercase-hex prefix.

Historical validation verifies the pinned-root signature and signer window immediately before the recorded old expiry; it does not make that trust valid now. This planner supports the pinned-root historical case, not arbitrary post-rotation lineage. Unsupported history fails closed. New signer provenance, owner/intended-recipient approval, one-use replay admission and a dedicated protected installation/restart journal remain separate unimplemented gates.

claimSetupReference is the native, noninteractive public-reference enrollment transport used by agent-run bootstrap. A reference confers no bearer authority. The client proves its protected Ed25519 device identity, binds an ephemeral encryption key to the exact challenge, and waits for the intended recipient's browser approval. The compatible server must enforce its live authenticator, immutable scope, deadlines and atomic approved-key enrollment/recovery.

Decrypted enrollment credentials remain inside this method and are saved only through the existing protected credential store. Its return value contains public device configuration and scope names. It never returns a token, ciphertext, private key or private terminal input. HTTPS redirects, changed approval context, expired responses and unavailable protected storage fail closed. Source tests do not establish live enrollment or startup readiness.

The optional local onFailureDiagnostic observer receives only a frozen dharma.setup-claim-failure/v1 record with the fixed setup_claim_failed code and an allowlisted phase. It may add a typed reason, the server's error code as serverCode when it is a known code, and a server correlationId; approval_expired means browser approval was not given before the wait ended. The CLI emits this record to stderr, followed by the fixed setupClaimFailureMessage line when a reason is known; stdout and the existing sanitized exception remain unchanged. Observer failures are ignored. No caught exception, server message, credential, approval URL or device data is included. A phase describes the last local boundary attempted, not the remote root cause, proof that a preceding phase succeeded atomically, or authority to retry. In particular, a credential_commit failure may retain protected partial writes for the existing same-key recovery path.

This diagnostic does not provide a trusted pre-enrollment host callback, relax the coding sandbox, or make an unavailable OS-backed store usable. Qualify those runtime boundaries independently before actual onboarding.

AgentFabricClient.open({ ...paths, readOnly: true }) uses the already accepted device key and enrollment anchor without repairing or migrating them. Its one openSession() creates a separate authenticated server protocol session; its sequence and pending read remain in memory. It neither reads nor rewrites the durable relay outbox and cannot replay its pending work. Subsequent application POSTs, session replacement and implicit retry after an ambiguous read are denied. Signed GETs retain normal device/session/nonce/sequence validation. This is not an anonymous or server-side permission bypass: opening the session creates the ordinary authentication/audit record. Report that effect separately from source, plan and credential mutations. Unavailable or inconsistent protected identity fails closed instead of enrolling or generating a replacement key.

Licensed under MIT.

版本与发布记录

@dharma-ai-labs/agent-fabric-relay-client 共发布 43 个版本,首次发布于 2026/08/09;过去 12 个月发布了 43 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.37latest2026/11/0510 天前
0.2.362026/11/0511 天前
0.2.352026/11/0411 天前
0.2.342026/10/1828 天前
0.2.332026/10/151 个月前
0.2.322026/10/101 个月前

关于 @dharma-ai-labs/agent-fabric-relay-client 的常见问题

@dharma-ai-labs/agent-fabric-relay-client 是什么?

Outbound signed device enrollment and relay client for Dharma Agent Fabric

如何安装 @dharma-ai-labs/agent-fabric-relay-client?

在项目目录运行 npm install @dharma-ai-labs/agent-fabric-relay-client,或使用 pnpm add / yarn add / bun add。

@dharma-ai-labs/agent-fabric-relay-client 支持 TypeScript 吗?

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

@dharma-ai-labs/agent-fabric-relay-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@dharma-ai-labs/agent-fabric-relay-client 可以商用吗?

@dharma-ai-labs/agent-fabric-relay-client 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@dharma-ai-labs/agent-fabric-relay-client 的下载量有多少?

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

@dharma-ai-labs/agent-fabric-relay-client 还在维护吗?

最新版本 0.2.37 发布于 2026/11/05(10 天前);至今共发布 43 个版本,其中过去 12 个月发布了 43 个;首次发布于 2026/08/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。