信任与安全

A3S Use 的核心安全原则是：包内容可以描述需求，但不能给自己授权。 Flow/Skill 源码、UI 消息、OKF 知识、Tool 输出、MCP 描述和远端内容始终是数据。

三条信任路径

来源	信任决定	适用场景
本地目录或归档	人工审查并显式 `--allow-unsigned`	开发与私有包
Release 内置包	经审查 component plan 中的精确摘要	第一方发布内容
远端 Registry	固定 TUF root、签名元数据、回滚检查与 target 摘要	生产分发

搜索只在已验证、受大小限制的目录元数据上运行，不下载 package archive。模型或浏览器不能创造目录中不存在的安装身份。

Release artifact 证据

成功的带 tag preview release 会对每个平台的 staged tree 做确定性序列化，并为每个归档发布一份 SPDX JSON SBOM。GitHub OIDC 会为归档创建 build-provenance 与 SBOM attestation；checksums.txt.sigstore.json 是 checksum manifest 的 keyless Sigstore bundle，release job 会先按精确 tag workflow identity 复核该 bundle，再发布资产。所有 Action 以及 Rust、Python、Syft、Cosign 版本均已固定。

installer 要求 Cosign，并在下载平台归档前按精确 A3S Use tag workflow identity 与 GitHub OIDC issuer 验证 checksums.txt。证据缺失或无效时会 fail closed，已验证 manifest 与 bundle 会随安装版本保留。对每个 target，第二台无编译缓存的干净 runner 会重建全部随包原生可执行文件，并必须逐字节匹配主归档；只有匹配通过后，确定性 .reproducibility.json 记录才会被 attestation、checksum 与签名。带 tag 的 v0.3.2 尝试在四个 target 上未通过该比较，因此没有创建 GitHub Release。非发布资格运行 33651777660 随后以精确的 main 提交 4f6e4725205d06ab81f8ea98bfee85c7eb4b2bcd 让全部五个平台的所有随包可执行文件逐字节匹配，并作为历史证据保留；v0.3.5 发布尝试因 public core crate 过期而未创建 Release。发布工作流 33675697857 的 13 个 job 均通过，并从精确的 main 提交 54758910f2f4ad9498137410e0a2207d412e99a1 为 tag v0.3.6 发布已验证归档与 typed crate，见 v0.3.6 Release。随后发布工作流 33687297386 的 13 个 job 也全部通过，并从精确的 main 提交 48a0b76f8a4a87a11d16627c7bd7567920852508 为 tag v0.3.7 发布当前已验证归档与 typed crate（a3s-use-core 0.2.6、a3s-use-extension 0.3.7、a3s-use 0.3.7），见 v0.3.7 Release。installer 脚本自身仍是独立的 bootstrap 信任边界，应先审查或通过可信系统包分发。外部运营的完整 staged tree/最终归档 witness 与 Release 之外的证据保留仍是 release gate。

下一次发布工作流 33720485826 的 13 个 job 全部通过，tag v0.3.8 来自精确的 main 提交 6d3a7baf32ce998a2e487c40fbf78b4a6cda2579，并在 v0.3.8 Release 发布当前已验证归档与 typed crate：a3s-use-core 0.2.7、a3s-use-extension 0.3.8、a3s-use 0.3.8。installer 仍是独立的 bootstrap 信任边界；外部运营的完整 staged tree/最终归档 witness 与 Release 之外的证据保留仍是发布门禁。

发布工作流 33756618837 的 13 个 job 全部通过，tag v0.3.9 来自精确的 main 提交 a5f3cc40bfb0a1021ca150d2ce4295409b74d220，并在 v0.3.9 Release 发布 19 个已验证资产与 typed crate：a3s-use-core 0.2.7、a3s-use-extension 0.3.9、a3s-use 0.3.9。installer 仍是独立的 bootstrap 信任边界；外部运营的完整 staged tree/最终归档 witness 与 Release 之外的证据保留仍是发布门禁。

发布工作流 33791616307 的 13 个 job 全部通过，tag v0.3.10 来自精确的 main 提交 c4c80a223bfff3698ca4b4598e7175c6e3303239，并在 v0.3.10 Release 发布 19 个已验证资产与 typed crate：a3s-use-core 0.2.8、a3s-use-extension 0.3.10、a3s-use 0.3.10。installer 仍是独立的 bootstrap 信任边界；外部运营的完整 staged tree/最终归档 witness 与 Release 之外的证据保留仍是发布门禁。

发布工作流 33830280138 的验证、五平台主构建、typed crate 与五平台独立重建门禁全部通过，tag v0.3.11 来自精确的 main 提交 c25028ae0245ba1d28f7e2837e2a87f7e9f6fe40，并在 v0.3.11 Release 发布 19 个已验证资产与 typed crate：a3s-use-core 0.2.9、a3s-use-extension 0.3.11、a3s-use 0.3.11。installer 仍是独立的 bootstrap 信任边界；外部运营的完整 staged tree/最终归档 witness 与 Release 之外的证据保留仍是发布门禁。

可替换的 Registry 来源

远端 Registry 是具名、由宿主持有的 ACL 配置。standalone CLI 最多持久化 64 个 source，把第一个 enabled source 设为 default，并把全部 enabled source 交给 dependency resolution。Release bundle 始终独立于远端 Registry。

a3s-use registry source add packages \
  --url https://packages.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --trusted-root /absolute/path/root.json \
  --json

a3s-use registry source list --json
a3s-use registry source replace packages \
  --url https://mirror.example.org/a3s/ \
  --trust-root sha256:<64-hex-digits> \
  --expected-revision sha256:<reviewed-configuration-revision> \
  --yes \
  --json

default、enable、disable 与 remove 使用同一个 reviewed-revision 和 confirmation boundary。只有 enabled source 参与 package lookup、dependency resolution、refresh 与 upgrade；disabled source 仍显示在 list 中。导入 root 之前必须通过 regular-file、大小、JSON 与完整 digest 检查。每个 canonical name/URL/bootstrap-root identity 使用独立 TUF/cache datastore；replace 保留 enabled 状态，绝不会让旧 metadata 在新 trust 下生效。disable/remove 会保留旧 state，因此恢复完全相同的 identity 后可以复用。同一 package identity 同时出现在多个 enabled Registry 时会以歧义失败。source 管理不会改写已安装 receipt；upgrade 继续绑定记录的 source 与 target provenance，identity 漂移时 fail closed。

不可变计划

install、upgrade 与 uninstall 在变更前生成带过期时间的 canonical plan。它至少绑定：

package ID、版本、channel、target 与 source registry；
完整 canonical dependency lock 及其 digest；
TUF root 身份和 metadata version；
archive length、SHA-256 与 expanded package digest；
表面变化、依赖变化与 Runtime provider evidence；
permission ceiling、secret/grant diff 和 workspace 影响；
download/installed size、drain 影响与 canonical plan digest。

Apply 接受已审查 digest，重新解析所有输入，并在目标、内容、权限、提供者或所有权漂移时拒绝执行。用户确认与每个 grant proposal 也绑定这个 digest。

对于 schema-v3 dependency，lock 绑定每个选定版本、依赖边、archive/package/manifest digest、宿主 target/version、Registry URL/trust root 和 TUF role version。Apply 在下载任何 archive 前重验完整闭包；同一依赖同时出现在多个已启用 Registry 时属于歧义并 fail closed。

Operation 诊断

a3s-use extension diagnose <publisher/name> --scope-kind user --scope-id user/current --json 会读取所选 User 或 Workspace scope 中一个精确保留的 planned/admitted/cancelled install、upgrade、 uninstall 图、一个 active admitted enable/disable operation，或最新 Host-reviewed pre-admission enable/disable plan/cancellation。它不会请求 Registry，也不会执行 reconciliation、recovery 或写入。版本化 projection 关联 reviewed plan 与 lock、无路径 Registry/TUF 证据、当前 Registry generation 与 cutover、provider readiness、Grant journal phase、lifecycle publication/drain/rollback 状态以及稳定的恢复建议。

该 projection 仅用于观察，绝不是 apply 或 recovery authority。其大小上限为 2 MiB，会拒绝未知字段和不一致证据，并排除 path、Registry URL、idempotency key、credential、token、secret 名称和值、package content 以及任意包作者文本。底层状态无效时会 fail closed，只返回无路径清理/重装建议。active Use enablement 证据优先；否则 observation-only digest-bound index 会按 (plannedAtMs, requestId) 选择最新精确 Host plan，并输出 planned 或 cancelled。私有 index 只为 request lookup 保留 managed scope，不公开 Host ID、 authority、fence 或 Host request/cancellation identity。Use completion 或 Host outcome 会抑制陈旧 plan。对已保留且由 Registry 支持的 install/upgrade 图以及 durable pre-plan download attempt，projection 会依据精确历史 provenance 分别报告 expected/retained archive 和签名 executable-planning-target bytes，以及每个 target 的 missing/partial/complete 状态。attempt 由进程锁保护，进程退出后仍保留，并只在 reviewed graph 持久化后删除。该观察不联网、只读、无路径且不获取 target cache lock；target 或 partial 永远不是 planning/apply/recovery authority。

metadata access 与精确 lock 生成前，进程持有的 package lock 会保护 a3s.use.plugin-resolution-attempt.v1。记录包含 refreshed/cached access、无路径的 root/dependency Registry 验证状态、source-identity/trust-root digest、TUF role version、有界 target count 与失败码，以及最终 lock 证据。 a3s.use.plugin-resolution-attempt-diagnostic.v1 的 phase 为 pre-lock。resolver 失败或进程退出后仍可查询；诊断不会联网或写入，也不会等待 package lock。成功路径会先写入 download attempt，再删除 resolution evidence。Registry URL、路径、原始 transport error、credential 与 metadata bytes 均不会进入记录。真实进程终止与 Host/CLI 测试已证明 planning-target partial observation 和精确 Range resume、 planned/cancelled enablement 诊断零联网/零 admission、不泄漏 Host/fence/path，以及 completed-Use/unfinished-Host-outcome 窗口中的陈旧 plan 抑制。

extension diagnose --history --json 通过独立的有界合约暴露已结束 operation 历史。每个明确 scope/package 最多保留最新 16 项，总计不超过 8 MiB，并要求 completed/rolled-back operation 或 cancelled graph plan outcome 与 lifecycle、 Grant、Registry cutover 证据一致。系统会先保留历史，再移除 recovery authority；重放按 (operationId, planDigest) 去重，因为精确重装可以合法复用由 lock 派生的文本 operation ID。查询不联网、只读、在 uninstall 后仍有效；未知字段、链接、不一致或超限状态只产生无路径错误。

默认授权策略

Agent lifecycle 操作默认是 ask，不是 allow。安全的 metadata search、inspect、list 和 plan 可以预授权；增加信任根、安装 unsigned package、授予 secret 和 purge data 只能由用户执行。

Gateway 调用由宿主拥有的 CapabilityGatewayInvocationResolver 将 catalog 中的 opaque InvocationRef 映射为私有 lease。该 lease 必须绑定完整的 package/surface/generation identity，执行 principal 与 Grant policy，并一直保留 generation guard 直到 invocation 返回。CapabilityGatewayResolvedProvider 将解析与授权放在同一个调用边界内；lease、路径和 provider 细节不会发送给 agent。生产宿主仍需提供 receipt、Runtime 与 Grant binding。HTTP 宿主可使用有界、不可变的 token→principal registry；认证会扫描完整 credential 集合并拒绝重复 token。

包声明的权限是上限，不是授权。宿主 ACL policy 和 workspace grant 只能进一步收紧：

plugins {
  schema = "a3s.plugin-policy.v1"

  agent_install   = "allow"
  agent_upgrade   = "ask"
  agent_uninstall = "ask"

  trusted_registries = ["a3s"]
  trusted_publishers = ["a3s"]
  allowed_surfaces   = ["flow", "mcp", "okf", "skill", "tool", "ui"]

  permissions {
    native_execution = false
    private_service  = true
    child_process    = false
    secrets          = false

    network "api.example.com" {
      ports = [443]
    }
  }
}

省略的 ceiling 等价于零、空或 false。重复项、未知字段、宽泛网络规则和无人值守 secret grant 都 fail closed。

示例使用当前六类表面清单。宿主必须按精确的当前合约解析这份 ACL policy，并拒绝未知或不完整的清单；不能通过默认值扩大权限。

激活顺序

resolve signed dependency graph
    → freeze exact package lock
    → build and review immutable plan
    → revalidate every Registry before payload download
    → verify and stage dependencies before dependents
    → prepare grants and Runtime bindings
    → preflight A3S Flow and stage Skill, UI, and OKF projections
    → publish changed packages in one capability generation
    → hide and drain superseded generation
    → retire old grants, bindings, and owned files

新 generation 在所有 required dependency 就绪之前不可见。升级失败时保留旧 generation；disable/uninstall 先隐藏新调用，再排空精确 generation lease。

精确且已发布的依赖可以 retained 而不重复 commit。卸载按 package 反向顺序执行；另一个已安装包仍需要该依赖时会拒绝移除。部分 enabled receipt 写入在完整 immutable snapshot 发布前保持不可见。

OKF standalone SQLite/FTS5 host 已实现：缺失 Knowledge evidence 为 pending，staged 不发布，只有精确 promoted observation 才是 healthy。Search 必须携带完整 scope 与精确、已审查的 capability/session projection；citation 绑定 package、surface、generation、index、concept path 与 source digest。Scope-bounded retention/GC、audit、verified backup 与 exact-plan oldest-first rotation、derived-index repair、authority-bound database 与 exact-subset missing-binding restore 已实现。Restore 要求精确 reviewed plan、完整保留的 Registry/package/lifecycle/Grant authority，并要求当前 binding set 是备份的精确子集；冲突或更新的 binding evidence 会 fail closed。Durable operation 活跃期间会阻止普通 mutation。无路径 diagnostic 只暴露有界 active/history/capacity 与 reviewed binding-recovery evidence，绝不会轮换或改写 rollback file。A3S Code 托管 leased-query 资格验证、缺失独立 authority 与 clean-machine 恢复、跨平台运营演练、rollback-evidence retention policy 和 whole-product recovery 仍未完成。

Whole-installation backup 使用同一个独占 maintenance boundary。state backup 只盘点已知 Use-owned family，排除 lock，绑定已发布 Registry projection 与 installed receipt digest，以精确 hash 复制每个 regular file，并要求发布前的第二次完整 inventory 完全不变。活动 restore/cutover/operation、未知 family、不可移植名称、link/reparse point 或 special file 都会 fail closed。state verify-backup 无需提取即可离线校验 canonical manifest、完整 archive 长度与每个 payload。Archive 包含原始 state，运营方必须按敏感数据保护。state backup-retention 会在一个外部目录锁下完整校验每个托管 archive，绑定无路径、oldest-first 的 canonical plan，只接受未变化的 digest 与显式确认，并至少保留两个已验证 recovery generation。Archive digest 仍只能证明损坏，不能提供认证或缺失 authority 的恢复。state plan-restore 要求精确匹配当前 version/platform，并要求 live Registry、receipt 与 Grant authority 保持不变。确认后的 state restore 会在 active marker 或任何 mutation 之前捕获外部 rollback archive，拒绝 candidate link/reparse point 和 durable evidence 替换，并在 15 个已测进程退出边界上收敛七阶段 journal。无路径的 state restore-status 保持只读，终态历史也有明确上限。缺失 authority、跨平台运营演练与 clean-machine recovery 仍未完成。

认知包平台仍处于 pre-1.0。未知 receipt 或 database version 会 fail closed；未发布状态直接重建，不迁移也不改写。这不影响 package SemVer 解析、host-version requirement、target 检查与 signed provenance 验证。

Flow 的源码完整性与生命周期顺序已实现，但 embedding host 必须注入精确的 a3s-flow compiler/runtime adapter。standalone engine 会在 mutation 前拒绝 required Flow，不会把只有源码证据的 Flow 发布为 ready。

平台隔离边界

原生进程执行不自动等于 sandbox。在 filesystem、environment、process 与 network restriction 尚未被某个平台 provider 强制执行时，状态必须报告为 native-unconfined，且不能使用无人值守 allow 路径。

完整的规范参见 Plugin Lifecycle and Security。

#信任与安全

#三条信任路径

#Release artifact 证据

#可替换的 Registry 来源

#不可变计划

#Operation 诊断

#默认授权策略

#激活顺序

#平台隔离边界