4. 发布包结构规范：标准发布包目录结构、元数据文件（manifest.yaml）、签名文件（.sig）规范
发布包的结构规范是 RBAC 校验体系的基础。一个标准化的发布包不仅便于自动化流水线处理，更能确保校验流程的确定性。本节将定义标准目录结构、元数据清单以及签名文件的存放规则。
4.1 标准发布包目录结构
一个合规的 RBAC 发布包应遵循以下目录层级，确保所有组件在固定路径下可被校验工具发现：
rbac-release-package/
├── manifest.yaml # 元数据文件（必需）
├── rbac-package.sig # 签名文件（必需）
├── artifacts/ # 制品目录（必需）
│ ├── rbac-core.wasm # 核心策略引擎
│ ├── policy-bundle.tar.gz # 策略规则包
│ └── checksums.txt # 制品校验和清单
├── config/ # 配置目录（可选）
│ ├── default-policy.yaml
│ └── audit-rules.yaml
└── docs/ # 文档目录（可选）
└── release-notes.md
路径约定：所有必需文件必须位于发布包根目录，不得嵌套子目录。签名文件
rbac-package.sig 必须与 manifest.yaml 同级。
4.2 元数据文件（manifest.yaml）规范
manifest.yaml 是发布包的“身份证”，记录包的身份、内容清单、构建信息及校验参数。校验工具首先解析此文件，获取后续校验所需的所有元数据。
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
apiVersion |
string | 是 | 清单格式版本，当前为 rbac.io/v1 |
package.name |
string | 是 | 发布包唯一名称，遵循反向域名命名 |
package.version |
string | 是 | 语义化版本号，如 1.2.3 |
artifacts |
array | 是 | 制品列表，每个条目包含 path、digest、algorithm |
signature |
object | 是 | 签名配置，包含 keyId、algorithm、sigFile |
metadata |
object | 否 | 自定义标签，如构建流水线 ID、责任人 |
标准 manifest.yaml 示例：
apiVersion: rbac.io/v1
package:
name: io.rbac.policy.core
version: 1.2.3
releaseDate: 2025-03-15T10:00:00Z
artifacts:
- path: artifacts/rbac-core.wasm
digest: sha256:a1b2c3d4e5f6...
algorithm: sha256
- path: artifacts/policy-bundle.tar.gz
digest: sha256:f6e5d4c3b2a1...
algorithm: sha256
- path: artifacts/checksums.txt
digest: sha256:000111222333...
algorithm: sha256
signature:
keyId: 0xABCDEF1234567890
algorithm: ed25519
sigFile: rbac-package.sig
metadata:
pipelineId: ci-20250315-001
maintainer: security-team@example.com
校验要点：校验工具必须验证
artifacts 列表中每个制品的 digest 是否与文件实际哈希一致。任何制品缺失或哈希不匹配，应直接判定发布包无效。
4.3 签名文件（.sig）规范
签名文件 rbac-package.sig 是对 manifest.yaml 内容的数字签名，确保元数据在传输和存储过程中未被篡改。签名算法推荐使用 Ed25519 或 ECDSA P-384。
签名文件为二进制格式，不包含任何文本元数据。其内容结构如下：
| 偏移量 | 长度（字节） | 内容 |
|---|---|---|
| 0 | 4 | 魔数 0x52424143（ASCII: RBAC） |
| 4 | 2 | 签名算法标识（0x01 = Ed25519, 0x02 = ECDSA P-384） |
| 6 | 2 | 签名长度（大端序） |
| 8 | 可变 | 签名数据 |
签名流程：签名者使用私钥对
manifest.yaml 的完整内容（UTF-8 编码）进行签名，而非对单个制品签名。校验时，工具读取 manifest.yaml，使用公钥验证 .sig 文件中的签名值。
4.4 发布包结构关系图
下图展示了发布包各组件之间的校验依赖关系：
4.5 目录结构合规检查清单
在自动化流水线中，可使用以下清单快速验证发布包结构是否合规：
- 必需文件存在性：根目录下是否存在
manifest.yaml和rbac-package.sig - 制品目录完整性：
artifacts/目录是否存在且非空 - manifest 可解析性：YAML 格式正确，所有必需字段非空
- 签名算法匹配：
manifest.yaml中声明的算法与.sig文件头标识一致 - 制品路径一致性：
artifacts列表中每个path在包内真实存在 - 无多余顶层文件：除
manifest.yaml、.sig、artifacts/、config/、docs/外，根目录不应有其他文件
实践建议：在 CI/CD 流水线中，将结构合规检查作为发布包构建的最后一步。使用
rbac-verify structure --path ./rbac-release-package 命令可一键完成上述所有检查项。