PEP 740: data-provenance attribute value tweaks (#3971)

Signed-off-by: William Woodruff <[email protected]>
Co-authored-by: Dustin Ingram <[email protected]>

Author: woodruffw

peps/pep-0740.rst

@@ -203,25 +203,35 @@ The following changes are made to the
 :ref:`simple repository API <packaging:simple-repository-api-base>`:
 
 * When an uploaded file has one or more attestations, the index **MAY**
-  provide a ``.provenance`` file adjacent to the hosted distribution.
-  The format of the ``.provenance`` file **SHALL** be a JSON-encoded
-  :ref:`provenance object <provenance-object>`, which **SHALL** contain
-  the file's attestations.
+  provide a provenance file containing attestations associated with
+  a given distribution. The format of the provenance file
+  **SHALL** be a JSON-encoded :ref:`provenance object <provenance-object>`,
+  which **SHALL** contain the file's attestations.
 
-  For example, if an uploaded file is hosted at
-  the URL ``https://example.com/sampleproject-1.2.3.tar.gz``, the provenance
-  URL would be ``https://example.com/sampleproject-1.2.3.tar.gz.provenance``.
+  The location of the provenance file is signaled by the index via
+  the ``data-provenance`` attribute.
 
-* When a ``.provenance`` file is present, the index **MAY** include a
+* When a provenance file is present, the index **MAY** include a
   ``data-provenance`` attribute on its file link. The value of the
-  ``data-provenance`` attribute **SHALL** be the SHA-256 digest of the
-  associated ``.provenance`` file.
+  ``data-provenance`` attribute **SHALL** be a fully qualified URL,
+  signaling the the file's provenance can be found
+  at that URL. This URL **MUST** represent a
+  `secure origin <https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features/>`_.
 
-* The index **MAY** choose to modify the ``.provenance`` file. For example,
+  The following table provides examples of release file URLs, ``data-provenance``
+  values, and their resulting provenance file URLs.
+
+  .. csv-table::
+    :header: "File URL", "``data-provenance``", "Provenance URL"
+
+    "https://example.com/sampleproject-1.2.3.tar.gz", "``https://example.com/sampleproject-1.2.3.tar.gz.provenance``", "https://example.com/sampleproject-1.2.3.tar.gz.provenance"
+    "https://example.com/sampleproject-1.2.3.tar.gz", "``https://other.example.com/sampleproject-1.2.3.tar.gz/provenance``", "https://other.example.com/sampleproject-1.2.3.tar.gz/provenance"
+    "https://example.com/sampleproject-1.2.3.tar.gz", "``../relative``", "*(invalid: not a fully qualified URL)*"
+    "https://example.com/sampleproject-1.2.3.tar.gz", "``http://unencrypted.example.com/provenance``", "*(invalid: not a secure origin)*"
+
+* The index **MAY** choose to modify the provenance file. For example,
   the index **MAY** permit adding additional attestations and verification
   materials, such as attestations from third-party auditors or other services.
-  When the index modifies the ``.provenance`` file, it **MUST** also update the
-  ``data-provenance`` attribute's value to the new SHA-256 digest.
 
   See :ref:`changes-to-provenance-objects` for an additional discussion of
   reasons why a file's provenance may change.
@@ -236,8 +246,8 @@ The following changes are made to the
   include a ``provenance`` key in the ``file`` dictionary for that file.
 
   The value of the ``provenance`` key **SHALL** be either a JSON string
-  or ``null``. If ``provenance`` is not ``null``, it **SHALL** be the SHA-256
-  digest of the associated ``.provenance`` file, as in the Simple Index.
+  or ``null``. If ``provenance`` is not ``null``, it **SHALL** be a URL
+  to the associated provenance file.
 
   See :ref:`appendix-3` for an explanation of the technical decision to
   embed the SHA-256 digest in the JSON API, rather than the full