PEP 740: initial attestation docs

docs/mkdocs-user-docs.yml

@@ -14,7 +14,8 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
-      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}
+      slugify:
+        !!python/object/apply:pymdownx.slugs.slugify { kwds: { case: lower } }
   - tables
 theme:
   name: material
@@ -66,3 +67,6 @@ nav:
       - "trusted-publishers/security-model.md"
       - "trusted-publishers/troubleshooting.md"
       - "trusted-publishers/internals.md"
+  - "Digital Attestations":
+      - "attestations/index.md"
+      - "attestations/publish/v1.md"

docs/user/attestations/index.md

@@ -0,0 +1,34 @@
+---
+title: Getting Started
+---
+
+<!--[[ preview('index-attestations') ]]-->
+
+# Digital Attestations for PyPI
+
+These pages document PyPI's implementation of index attestations ([PEP 740]),
+including in-toto attestation predicates specific to PyPI itself.
+
+## Quick background
+
+*Index attestations* enable package maintainers as well as third parties (such
+as the index itself, external auditors, etc.) to *cryptographically sign*
+for uploaded packages.
+
+These signatures bind each release distribution (such as an individual sdist or
+wheel) to a strong cryptographic digest of its contents, allowing both PyPI
+and downstream users to verify that a particular package was attested to by
+a particular identity (such as a GitHub Actions workflow).
+
+These attestations can take multiple forms, including ["publish" attestations]
+for publicly verifiable proof that a package was published via a specific
+[Trusted Publisher], or more general [SLSA provenance] attesting to a package's
+original source location.
+
+[PEP 740]: https://peps.python.org/pep-0740/
+
+["publish" attestations]: /attestations/publish/v1/
+
+[Trusted Publisher]: /trusted-publishers/
+
+[SLSA provenance]: https://slsa.dev/spec/v1.0/provenance

docs/user/attestations/publish/v1.md

@@ -0,0 +1,67 @@
+---
+title: PyPI Publish Attestation (v1)
+---
+
+<!--[[ preview('index-attestations') ]]-->
+
+# Predicate type: PyPI Publish
+
+Type URI: <https://docs.pypi.org/attestations/publish/v1>
+
+Version 1.0
+
+## Purpose
+
+To provide a minimal, "implicit" digital attestation for PyPI packages published
+via Trusted Publishing.
+
+## Use Cases
+
+A [Trusted Publisher] can produce this attestation during the publishing
+process for a particular release of a PyPI project. This allows consumers of
+that release version to verify the following:
+
+1. That a particular PyPI project release was, in fact, uploaded via a Trusted
+   Publisher and not some other publishing mechanism (such as a locally-held
+   API token).
+2. That a *specific* Trusted Publisher identity was used to publish the
+   release, such as a particular GitHub Actions workflow, GitLab identity,
+   etc.
+
+Put together, these allow users to assert a higher degree of confidence in
+the integrity (but not necessarily trustworthiness) of releases made to PyPI,
+by asserting that the package is published via a short-lived credential
+corresponding to a specific machine identity (such as a GitHub Actions workflow).
+
+This can be further composed with monitoring, e.g. for changes to a PyPI
+project's attested Trusted Publisher over time, indicating potentially
+malicious changes to the project.
+
+## Prerequisites
+
+This predicate depends on the [in-toto Attestation Framework].
+
+## Model
+
+This predicate conveys a [Trusted Publisher]'s intent to publish a package
+to PyPI.
+
+It implicitly communicates the state of the Trusted Publisher (at the time of
+publishing) via the identity that produced the signature. This identity
+can be cross-checked during verification, per [PEP 740], via the
+["provenance" objects] served by PyPI's index APIs.
+
+## Schema
+
+This predicate has no schema. The Type URI is the only required field,
+and it **MUST** be `https://docs.pypi.org/attestations/publish/v1`.
+
+The `predicate` body itself **MUST** be either empty or not supplied.
+
+[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/README.md
+
+[Trusted Publisher]: /trusted-publishers/
+
+[PEP 740]: https://peps.python.org/pep-0740/
+
+["provenance" objects]: https://peps.python.org/pep-0740/#provenance-objects

docs/user/main.py

@@ -1,6 +1,5 @@
 from pathlib import Path
 
-
 ORG_ACCOUNTS = """
 !!! info
 
@@ -11,7 +10,17 @@
     to be one of the first to know how you can begin using them.
 """
 
-PREVIEW_FEATURES = {"org-accounts": ORG_ACCOUNTS}
+INDEX_ATTESTATIONS = """
+!!! info
+
+    Index attestations are currently under active development,
+    and are not generally available yet.
+"""
+
+PREVIEW_FEATURES = {
+    "org-accounts": ORG_ACCOUNTS,
+    "index-attestations": INDEX_ATTESTATIONS,
+}
 
 _HERE = Path(__file__).parent.resolve()