进阶 docs.pypi.org 2026-10-20 06:39:13 · 16 阅读

第21章 PyPI 发布证明(v1)规范

PyPI Publish Attestation (v1)

类型 URI:https://docs.pypi.org/attestations/publish/v1 版本 1.0

目的

为通过 Trusted Publishing 发布的 PyPI 包提供一种最简的、"隐式"数字证明。

使用场景

Trusted Publisher 在发布 PyPI 项目的某个特定版本时可以生成此证明。这让项目的使用者能够验证以下两点:

- 某个版本的分发包(即 sdist 或 wheel)确实是通过 Trusted Publisher 上传的,而非其他发布方式(例如本地保存的 API token)。 - 发布该项目时使用的具体 Trusted Publisher 身份,例如某个 GitHub Actions workflow、GitLab 身份、Google Cloud 服务账号等。

综合起来,用户可以通过确认包文件是经由对应特定机器身份(如 GitHub Actions workflow)的短期凭证发布的,从而对发布到 PyPI 的项目完整性(但不一定可信度)建立更高的信心。

还可以进一步结合监控手段,例如持续跟踪某个 PyPI 项目所证明的 Trusted Publisher 是否随时间发生变化,以此发现潜在的项目恶意篡改。

前置条件

此谓词依赖于 in-toto Attestation Framework。

模型

此谓词表达了 Trusted Publisher 将包发布到 PyPI 的意图。

它通过生成签名的身份,隐式传达了发布时 Trusted Publisher 的状态。在验证阶段,可以按照 PEP 740,通过 PyPI 索引 API 提供的 "provenance" 对象来交叉核对该身份。

模式

此谓词没有模式。类型 URI 是唯一必需的字段,且必须(MUST)为 https://docs.pypi.org/attestations/publish/v1。

谓词主体本身必须(MUST)为空(即空 JSON 对象 {}),或者不提供(即 JSON null)。

评论 (0)