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,7 @@ nav:
       - "trusted-publishers/security-model.md"
       - "trusted-publishers/troubleshooting.md"
       - "trusted-publishers/internals.md"
+  - "Digital Attestations":
+      - "attestations/index.md"
+      - "attestations/publish/v1.md"
+      - "attestations/internals.md"

docs/user/attestations/index.md

@@ -0,0 +1,47 @@
+---
+title: Introduction
+---
+
+<!--[[ preview('index-attestations') ]]-->
+
+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.
+
+## Supported attestations
+
+PyPI uses the [in-toto Attestation Framework] for the attestations it accepts.
+
+Currently, PyPI allows the following attestation predicates:
+
+* [SLSA Provenance]
+* [PyPI Publish]
+
+[in-toto Attestation Framework]: https://github.com/in-toto/attestation/blob/main/spec/README.md
+
+[PEP 740]: https://peps.python.org/pep-0740/
+
+[PyPI Publish]: /attestations/publish/v1/
+
+[publish attestations]: /attestations/publish/v1/
+
+[Trusted Publisher]: /trusted-publishers/
+
+[SLSA Provenance]: https://slsa.dev/spec/v1.0/provenance
+
+