EmDash 插件注册表客户端（@emdash-cms/registry-client）演进全解：从 atproto 发布流水线到 GitHub OIDC 委托发布

CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载导读emdash-cms/registry-client是 EmDash基于 Astro 的全栈 TypeScript CMS中负责与插件注册表打交道的核心客户端包它把插件发布与插件发现/安装两条链路统一建立在 AT Protocolatproto之上。本文以该包从0.0.1到0.6.0的 CHANGELOG 为骨架逐版本还原其演进脉络并结合仓库源码包入口、README 及各子模块实现讲解每一层能力的设计动机、信任边界与实战用法。读完本文你将掌握如何用该客户端在发布者 PDS 上写入签名记录、如何从聚合器做只读发现并防御恶意数据、如何通过DirectPdsClient直接核验仓库证明以及如何接入实验性的 GitHub OpenID Connect 委托发布服务。兼容性说明该包目前为实验阶段0.x面向com.emdashcms.experimental.*lexicon 与实验性聚合器。在 RFC 0001 尘埃落定前NSID 与数据结构仍可能变化官方建议固定到精确版本使用见 README 与 src/index.ts。一、0.0.1三层架构的诞生emdash-cms/registry-client最早随 PR #923 引入对应 CHANGELOG 0.0.1定位是atproto-aware 的 EmDash 插件注册表客户端。从一开始它就刻意拆成三个相互独立的层凭证存储credential storage持久化发布者的 atproto 会话发布者仓库操作publisher repo operations针对发布者自己 PDS 的记录读写发现discovery针对聚合器的只读 XRPC 客户端。这一分层至今未变且从包入口的导出结构可以清楚看到它被进一步细化为可按子路径独立导入的模块src/index.tsemdash-cms/registry-client/credentials → 凭证存储 emdash-cms/registry-client/publishing → 发布操作 emdash-cms/registry-client/discovery → 聚合器发现 emdash-cms/registry-client/direct-pds → 直接读取发布者 PDS emdash-cms/registry-client/release-service → 委托发布服务 emdash-cms/registry-client/env → 环境兼容性 emdash-cms/registry-client/listing-policy → 上架策略 emdash-cms/registry-client/withdrawal → 下架标签这样拆分的好处源码注释中明确说明见 src/index.ts发现链路的消费者不会被迫加载发布链路及其 OAuth 依赖减小了浏览器端与管理后台的体积。凭证存储三种实现与默认选择策略凭证层定义了统一的CredentialStore接口src/credentials/types.ts以DID 为键支持一台机器上为多个发布者身份如个人 DID 公司 DID各自保存会话并记录当前 DID。三种实现实现用途关键行为FileCredentialStore交互式 CLI 默认持久化到~/.emdash/credentials.json文件权限 0600写入先落临时文件再rename()POSIX 上原子替换目录写入后 fsync 保证断电持久性src/credentials/file.tsEnvCredentialStoreCI 只读读取EMDASH_PUBLISHER_DID/EMDASH_PUBLISHER_HANDLE/EMDASH_PUBLISHER_PDS三个环境变量所有变更方法抛ReadOnlyCredentialStoreErrorsrc/credentials/env.tsMemoryCredentialStore测试进程内Map无持久化src/credentials/memory.tsdefaultCredentialStore()的策略很简单三个EMDASH_PUBLISHER_*环境变量全部存在时返回环境变量存储否则回落到文件存储src/credentials/index.ts。源码注释特别提醒CI 中如果尝试交互式登录就是配置错误环境变量存储会抛出响亮错误而不是悄悄把凭证写进 runner 的文件系统src/credentials/env.ts。文件存储还有两个值得注意的防御性设计前向兼容拒绝磁盘信封带version字段如果文件版本高于当前 CLI 认识的版本直接拒绝读取而不是静默降级覆盖——否则会把未来 CLI 新增的字段弄丢src/credentials/file.ts。写前校验put()之前先用结构校验器验证会话DID 合法性、handle/pds 非空、updatedAt是有限数字把坏会话写盘 → 下次登录被锁死的隐患提前到登录时刻报错src/credentials/file.ts。发布操作typed 写入与原子批次PublishingClient包装一个由atcute/oauth-node-client构建的已认证 fetch handlerOAuth 交互流程在 CLI 中实现本包不做见 src/publishing/index.ts提供putRecord、getRecord、listRecords、uploadBlob等操作。三个设计要点typed 写入putRecord以 collection NSID 泛型推导 record 的 TS 类型把 profile 形状的记录写进 release collection 会在编译期报错src/publishing/index.tsunsafePutRecord是逃生舱。服务端校验默认开启validate: true是默认值PDS 会拒绝不匹配 lexicon 的记录src/publishing/index.ts。原子批次applyWrites多个 create/update/delete 在单个 atproto commit 内完成publish 流程用它把profile 引导 release 创建放进一次往返避免网络抖动造成半发布状态src/publishing/index.ts。swapRecord/swapCommit乐观并发前置条件0.2.0 引入见下也在这里实现写入时若当前 CID 不匹配则失败防止读-改-写流程静默覆盖并发编辑。二、0.1.0读侧信任边界——聚合器响应验证聚合器是一个不签名记录却中继签名记录的不可信远端索引所以 0.1.0PR #1112在DiscoveryClient上加了两层验证对应 CHANGELOG 0.1.0实现见 src/discovery/index.ts响应信封验证uri、cid、did、slug、version等外层字段由atcute/client按聚合器方法的输出 lexicon 校验不符合即抛ClientValidationError。内嵌签名记录验证聚合器原样中继的profile/release记录类型是unknown客户端用safeParse对com.emdashcms.experimental.package.profile/release做结构校验。单条坏记录不拖垮整个页面——不合规时置为null调用方必须做 null 检查。由此导出的ValidatedPackageView/ValidatedReleaseView/ValidatedSearchPackages/ValidatedListReleases类型明确标注profile: PackageProfile.Main | nullsrc/discovery/index.ts。源码注释还强调两个边界只做结构校验lexicon 的uri格式允许非 HTTP scheme包括javascript:所以 UI 渲染 URL 时必须自己再做 scheme 白名单src/discovery/index.ts。不做字段剥离atcute 校验不会移除未识别的键lexicon 对象是开放的多余键原样透传——它们是惰性的因为消费者只读 typed 字段刻意不手写白名单去剥离因为那正是这个边界要取代的脆弱的逐记录解析。DiscoveryClient本身零认证、纯只读用simpleFetchHandler绑定聚合器 base URL并把atproto-accept-labelers头透传进每个请求src/discovery/index.ts。它提供searchPackages、getPackage、resolvePackage、listReleases、getLatestRelease等与聚合器 XRPC 方法同名的方法其中getLatestRelease刻意把最高非下架版本的选择逻辑留给聚合器实现因为版本约束引擎在服务端src/discovery/index.ts。三、0.2.0update-package与乐观并发0.2.0PR #1126为 CLI 增加emdash-plugin update-package用于不发布新版本地编辑已发布插件的注册表记录license、作者、安全联系人、名称、描述、关键词。几个关键语义对应 CHANGELOG 0.2.0无--yes时先打印 diff 再退出不写入写入用swapRecord前置条件并发写入以STALE_RECORD失败而不是互相静默覆盖可选字段遵循manifest 缺失 不修改策略从 manifest 删掉一个 key 不会清空已发布值重命名插件时如果新 slug 不存在会提示看起来像重命名并列出发布者现有包避免旧 slug 下产生孤儿 release。这也是putRecord/unsafePutRecord获得swapRecord参数、applyWrites获得swapCommit参数的版本src/publishing/index.ts。swapCommit在仓库级别做同样的乐观并发保护若发布者仓库当前 commit 与期望 CID 不一致则整个批次中止src/publishing/index.ts。四、0.3.0环境要求requires约束0.3.0PR #1238让插件 manifest 可以声明 release 级环境要求例如{ env:emdash: 1.0.0, env:astro: 4.16 }该块会被发布进 release 记录。管理后台浏览插件时会把约束与运行中的 EmDash / Astro 版本比较不满足则显示兼容性警告并禁用 Install 按钮服务端在安装/更新时执行同一检查拒绝不兼容 release 并返回ENV_INCOMPATIBLE前端禁用无法被绕过对应 CHANGELOG 0.3.0。底层实现集中在 src/env/index.ts一个实现三端共用CLI 发布时校验、服务端安装门禁、管理后台浏览器警告见 src/env/index.tsparseRequires把 lexicon 类型为unknown的requires值守卫成字符串值记录只保留env:*键与 DID 形状键永不抛异常src/env/index.tshostEnvFromVersions从宿主上报的 EmDash / Astro 版本构建环境映射版本未知如未编译构建上报dev则跳过该键而不是阻塞src/env/index.tssatisfiesRangefails open——版本或范围任一不可解析都返回true门禁只在确定不匹配时拒绝src/env/index.ts范围求值委托给 node-semver完整支持 caret、tilde、通配符、||并集与预发布门控。0.3.1 与 0.3.2构建与依赖修复0.3.1修复astro devCloudflare Workers 的 workerd SSR下所有 API 路由require is not defined崩溃。根因是semverCommonJS在dependencies中被构建外部化消费者加载了嵌套 CJS 副本而 workerd 无require绑定修复方式是把 semver 打进 ESM 输出CHANGELOG 0.3.1。semver在 package.json 中仍保留为 devDependency运行时走打包后的内置实现。0.3.2对齐atcute系列依赖到 v2消除安装时的 peer dependency 警告atcute/client5、atcute/lexicons2、atcute/atproto4、atcute/oauth-node-client2CHANGELOG 0.3.2。五、0.4.0PDS blob 托管、artifactCaches 与安全强化0.4.0PR #2765、#2647是发布与安全语义的大版本。发布制品默认托管在发布者 PDSemdash-plugin publish默认把插件 bundle、图标、banner、截图作为 blob 上传到发布者自己的 PDSCLI 构建 bundle → 检查已存的 OAuth grant → 上传制品 → 把 CID 绑定的校验和写进 release 记录CHANGELOG 0.4.0。仍可用emdash-plugin publish --url https-url保持外部托管但 CLI 会下载该 URL 以校验并哈希实际服务字节防止记录与实物不一致。--artifact-base-url选项被移除并给出迁移指引。mirrors改为artifactCaches实验性聚合器 release 信封用类型化的artifactCaches取代mirrors。滚动升级期间字段可选更新的客户端把缺省字段视为空缓存列表view.artifactCaches ?? []见 src/discovery/index.ts。记录级缓存描述符提供服务端点客户端推导出/r/{did}/{collection}/{rkey}/{recordCid}/{blobCid}缓存准入被绑定到精确的 release 修订版防止旧修订内容被复用。安装/更新会对 raw 缓存、PDS、外部回退三种来源的字节都做签名校验和与 blob 元数据校验经过身份验证的图片代理可提供记录级缓存渲染缓存不可用时回退到校验过的 PDS 或外部字节。列表图仍限制 1 MiB。升级注意站点必须升级 EmDash 后才能安装制品仅以 PDS blob 形式存在的 release旧版 EmDash 要求外部包 URLCHANGELOG 0.4.0。签名标签策略与下架状态DiscoveryClient的所有请求现在携带聚合器要求的 listing policy带可选 accepted-labeler 声明下架withdrawn的 release 从安装/更新结果中排除CHANGELOG 0.4.0。对应实现listing-policy.tsregistryLabelerPolicy构造{ enforcement: required, acceptLabelers? }registryLabelerPolicyKey生成含声明内容的稳定缓存键listing-policy.tswithdrawal.tsevaluateRegistryReleaseWithdrawal通过共享的 moderation 策略求值水合后的 release 下架标签畸形标签数据 fails closedREADME Withdrawal 小节管理后台等待新鲜的 listing-policy 响应后再渲染注册表元数据使用已批准的作者名或发布者 DID而非可变 handle展示身份未批准 release 不请求媒体CHANGELOG 0.4.0。SSRF 防护注册表制品下载与代理媒体只连接每个 URL 验证过的公网 IP 地址防止验证与连接之间的 DNS 变更把流量导向内网服务CHANGELOG 0.4.0。六、0.5.0DirectPdsClient 与委托发布服务客户端0.5.0PR #2848、#2849、#2746、#2747、#2749、#2892把注册表推向去中心化信任 自动化发布。DirectPdsClient直接核验发布者 PDS[PR #2746] 引入DirectPdsClient安装/更新时直接向发布者的 PDS 核验当前签名记录[PR #2849] 增加getPackageRepository()一次证明验证的仓库导出中读取 profile 和全部 releaseconst { profile, releases } await directPdsClient.getPackageRepository(gallery);实现细节src/direct-pds/index.ts默认请求超时 10 秒、最大响应 5 MiBDEFAULT_DIRECT_PDS_REQUEST_TIMEOUT_MS/DEFAULT_DIRECT_PDS_MAX_RESPONSE_BYTES见 direct-pds/index.ts客户端验证仓库 commit 签名、record blocks 与完整 Merkle search tree 后才返回记录未签名的repo.getRecord/repo.listRecords信封不能替代或省略包数据缺失导出上报REPOSITORY_NOT_FOUND错误统一为带稳定 code 的DirectPdsReadErrorDID_DOCUMENT_INVALID、RECORD_PROOF_INVALID、PDS_RESPONSE_TOO_LARGE等 16 种direct-pds/index.tsDID 文档解析默认用CompositeDidDocumentResolver组合AtprotoWebDidDocumentResolver与PlcDidDocumentResolverdirect-pds/index.ts。聚合器记录完整性、发布者身份与来源证明安装/更新拒绝 URI 或 CID 与发布者签名记录不一致的聚合器元数据服务端在抓取制品或请求同意前返回AGGREGATOR_RECORD_MISMATCHhandle 解析只是咨询性身份信号resolveDidToHandle()明确返回invalid时阻塞安装网络失败、不支持的 DID 方法或缺 handle 的不确定结果显示发布者 DID 且不阻塞。安装/更新信任 DID 与签名仓库证明handle 仅是展示元数据CHANGELOG 0.5.0安装器应用签名 profile 的 release policy独立获取并校验提供的 Sigstore/SLSA provenance并把 moderation 标签绑定到精确的 profile/release CID。缺失必需 provenance、或提供的 provenance 不可用/畸形/不匹配/不支持都会阻塞安装与更新CHANGELOG 0.5.0校验包另导出inspectPackageReleaseRecords可在制品与 provenance 证据到位前先行校验签名记录与策略安装/更新同意界面现在展示精确验证过的 profile/release CID、签名发布者策略与 provenance 状态同意所用的权限与 MCP 工具来自验证过的 bundle而非聚合器记录副本CHANGELOG 0.5.0安装、更新与委托发布校验要求制品与 provenance 文档使用小写 base32 multibasesha2-256multihash插件 CLI 已产出该格式经身份验证的图片制品代理仍接受旧式裸十六进制 SHA-256 用于仅展示图片CHANGELOG 0.5.0。ReleaseServiceClient与ReleaseServiceOperatorClient[PR #2747] 为实验性委托发布服务添加 typed 客户端src/release-service/index.tsReleaseServiceClient提交、轮询、取消 GitHub OpenID Connect release intents管理发布者 workload 策略与保留委托通过发布者会话检查 profile 列出的审批者是否有活跃 passkey、查看发布者作用域审计事件。ReleaseServiceOperatorClientCloudflare Access 状态与清洗后的审计、分片化的发布者/审批者目录、暂停、挂起、撤销、取消、对账、可恢复的加密密钥轮换、Workflow 支撑的舰队验证、审计密钥退役、加密 R2 归档以及失败安全的发布者恢复与中止操作。通用设计两个客户端都校验响应信封返回带稳定ReleaseServiceErrorcode 与重试元数据的错误变更辅助方法要求幂等键workload 轮询每次调用都从配置的 provider 请求新 tokenCHANGELOG 0.5.0委托提交用 URL-source release 记录每个包或列表图制品只提供校验和绑定的 HTTPS URL 与无 blob服务通过发布者的委托分段并上传字节然后创建 blob-only release 记录。submit 与 dry-run 在请求 GitHub OIDC 之前拒绝混合或 blob 背书的来源输入CHANGELOG 0.5.0交互式release delegate、revoke、workload、enrol、approve、reject命令打印验证过的浏览器交接发布者应用会话、OAuth 凭证与 passkey 断言停留在 release-service 源站不进入终端进程CHANGELOG 0.5.0客户端不把 GitHub OIDC 兑换成 AT Protocol 权限workload 方法通过调用方提供的workloadToken函数请求新 tokenrelease service 持有其独立的 create-only 发布者委托README。配套 CLI 命令emdash-plugin release dry-run、release submit、release status、release cancel。首次release submit为永久 workflow 请求浏览器审批并等待确认后才创建 intentdry-run验证现有 workload 准入而不创建连接请求/intent、不消耗速率预算、不预留版本命令从 runner 请求 audience 绑定的 OIDC token支持 JSON 输出发生变更时默认用 GitHub run 身份作幂等键CHANGELOG 0.5.0。emdash-plugin release setup与工作流连接邀请[PR #2749]emdash-plugin release setup生成永久 GitHub Actions workflow——构建并证明插件、等待首次浏览器授权、通过 GitHub OIDC 上传精确的 bundle 与 provenance 后再发布ReleaseServiceClient.uploadReleaseArtifact()支持自定义 workflow 分段暂存校验和绑定的 bundle/图片/provenance 字节CHANGELOG 0.5.0。[PR #2848]发布者创建的工作流连接邀请。首次或不匹配的 GitHub workflow 必须先持有包绑定、一次性的邀请才能请求发布者审批已连接 workflow 无需邀请。邀请在发布者 dashboard 或createWorkflowConnectionInvitation()创建值存为仓库的EMDASH_CONNECTION_INVITATIONGitHub Actions secret生成的 release workflow 自动把它传给 release Action自定义 workflow 可向requestWorkflowConnection()传invitationToken发布者可用rejectWorkflowConnection()拒绝待决请求CHANGELOG 0.5.0。交互式 profile 设置[PR #2892]emdash-plugin release setup现在会先创建缺失的 profile 或给既有有效 profile 增加委托发布设置再写 GitHub Actions workflowemdash-plugin profile setup --dir package-directory只准备 profile。交互式设置会询问 GitHub 仓库emdash-plugin.jsonc缺失时、选择何时需要审批并确认写入非交互调用方在需要改 profile 时必须传--yes。release service 在签名 profile 缺失、缺少委托发布设置或指向不同 GitHub 仓库时于接受制品上传前返回PACKAGE_PROFILE_REQUIRED既有 release intents 在其权威 profile 失效时也会以可操作的错误原因终止CHANGELOG 0.5.0。七、0.6.0仓库级自动发布与首版豁免策略0.6.0PR #3078、#3081解决两个规模化问题。仓库级自动发布PR #3081emdash-plugin release setup现在会在Git 仓库根目录写入一份共享的.github/workflows/emdash-release.yml即使 setup 从嵌套包目录运行也是如此。该 workflow把slugversiontag 解析到唯一插件 manifest在 attestation 之前拒绝版本不匹配通过 GitHub OpenID Connect 请求首个仓库连接无需 Actions secret对应 CHANGELOG 0.6.0。后续包用emdash-plugin profile setup --dir package-directory准备其首个 release 在签名包 profile 指向同一仓库时复用已批准的仓库级 workflow 作用域。Tag 与手动触发作用域在发布者确认后累积而非互相替换既有包级审批保持包级直到发布者显式确认仓库连接既有生成的 workflow 与遗留的可选连接邀请输入仍受支持。首版豁免策略PR #3078给注册表可选的最小发布年龄策略加了一个fail-closed 的首版豁免包的第一个 release 只有在聚合器报告恰好保留一条 release、且确认持续观测了该包的 release 历史时才能立即安装对应 CHANGELOG 0.6.0。判定逻辑在 listing-policy.ts 的isProvenFirstReleaseexport function isProvenFirstRelease(evidence: ReleaseHistoryEvidence): boolean { return ( evidence.releaseHistoryComplete true Number.isSafeInteger(evidence.historicalReleaseCount) evidence.historicalReleaseCount 1 ); }既有包、回填包以及历史缺失/不完整的包仍受 holdback 约束已删除的 release 仍然计数显式的发布者或包豁免照常生效。依赖演进0.6.0 依赖emdash-cms/registry-lexicons0.5.0与emdash-cms/registry-moderation0.2.0CHANGELOG 0.6.0两者均为 workspace 依赖package.jsonlexicon 形状随注册表协议同步演进。八、快速上手与稳定性约定最小示例发现import { DiscoveryClient } from emdash-cms/registry-client; const discovery new DiscoveryClient({ aggregatorUrl: https://registry.emdashcms.com, // 可选向聚合器声明接受的 labeler DID参与缓存身份 acceptLabelers: did:plc:example, }); const result await discovery.searchPackages({ q: gallery, limit: 10 }); for (const pkg of result.packages) { // profile 可能为 null聚合器是不可信远端索引必须 null 检查 console.log(pkg.uri, pkg.profile?.name ?? pkg.slug); }完整示例见 src/discovery/index.ts。最小示例直接核验发布者仓库import { DirectPdsClient } from emdash-cms/registry-client; const client new DirectPdsClient({ did: did:plc:..., fetch: globalThis.fetch, // 可选requestTimeoutMs 默认 10_000maxResponseBytes 默认 5 MiB }); const { profile, releases } await client.getPackageRepository(gallery);稳定性说明0.x 阶段交互式登录流程CLI 集成刻意不在此包实现可能迁移别处凭证文件格式可能演进磁盘信封带version字段做前向兼容NSID 与 lexicon 形状跟随emdash-cms/registry-lexicons发布到 PDS blob 的 release 要求站点先升级 EmDash。结语从 0.0.1 的三层客户端骨架到 0.6.0 的仓库级 GitHub OIDC 自动发布emdash-cms/registry-client的每次版本跃迁都在强化同一个主题把发布者签名记录作为唯一信任根聚合器只是可被验证的中继。凭证层的防御性存储、发现层的读侧校验、直接 PDS 的仓库证明核验、委托发布服务的 OIDC 工作流连接构成了一条完整的写时签名、读时核验、发布自动化链路。对希望深入源码的读者建议从 src/index.ts 的导出清单出发沿discovery→publishing→direct-pds→release-service的顺序阅读四个模块正好对应文章梳理的四条主线。赞分享CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载相关推荐EmDash 插件注册表 atproto 客户端 emdash-cms/registry-client 深入解析凭据、发布、发现与委托发布全流程EmDash 插件注册表 atproto 客户端 emdash cms/registry client 深入解析凭据、发布、发现与委托发布全流程 emdaCMS后端前端插件系统EmDash 沙箱插件发布指南从 emdash-plugin.jsonc 校验到 GitHub Actions 委托发布EmDash 沙箱插件发布指南从 emdash plugin.jsonc 校验到 GitHub Actions 委托发布 本文面向 EmDash基于 AstCMS后端前端插件系统EmDash 插件注册表 Lexicon 实战emdash-cms/registry-lexicons 的类型生成、运行时校验与委托发布策略EmDash 插件注册表 Lexicon 实战emdash cms/registry lexicons 的类型生成、运行时校验与委托发布策略 emdashCMS后端前端插件系统上一篇终极指南如何快速掌握 conventions 开源项目的最佳实践下一篇Puter社区贡献指南如何参与开源互联网操作系统开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考