PEP 807: make discovery procedure reversible (#4791)

Author: woodruffw

peps/pep-0807.rst

@@ -114,7 +114,7 @@ apply to all parts of this PEP's specification:
   clients **MUST** reject any URLs that do not meet this constraint.
 
   In practice, this means that a discovery request to
-  ``https://upload.example.com/.well-known/pytp/{key}`` can only
+  ``https://upload.example.com/.well-known/pytp?discover={key}`` can only
   return URLs with the ``upload.example.com`` host.
 
 * All client requests **SHOULD** have an
@@ -157,19 +157,21 @@ The discovery mechanism is as follows:
    For the above example, the path component is
    ``/legacy/``.
 
-3. The uploading client takes the SHA2-256 hash of the path component,
-   producing the *discovery key*.
+3. The uploading client performs a query-safe URL encoding of the path component
+   (i.e. percent-encoding as defined in :rfc:`3986`, including encoding
+   of forward slashes and spaces), producing the *discovery key*.
 
    For the above example, the discovery key is
-   ``0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7``. [#fn-hash]_
+   ``%2Flegacy%2F``. [#fn-discovery-key]_
 
 4. The uploading client constructs a *discovery URL* by taking the
    scheme and authority components (as defined in :rfc:`3986`)
-   of the upload URL and appending ``/.well-known/pytp/``
-   and the discovery key.
+   of the upload URL and appending ``/.well-known/pytp`` as the path.
+   Then, the uploading client appends the discovery key as the value
+   of the ``discover`` query parameter.
 
    For the above example, the discovery URL is
-   ``https://upload.example.com/.well-known/pytp/af030c06750716b1b35852298fe852b90def13dcbd012a5fe5148470f1206bfc``.
+   ``https://upload.example.com/.well-known/pytp?discover=%2Flegacy%2F``.
 
 5. The uploading client performs an HTTP GET request to the discovery URL.
 
@@ -445,17 +447,17 @@ This approach too has downsides:
 Footnotes
 =========
 
-.. [#fn-hash]
+.. [#fn-discovery-key]
 
    The discovery key may be computed thusly:
 
    .. code-block:: pycon
 
-      >>> import hashlib
+      >>> import urllib.parse
       >>> path = "/legacy/"
-      >>> key = hashlib.sha256(path.encode("utf-8")).hexdigest()
+      >>> key = urllib.parse.quote_plus(path)
       >>> print(key)
-      0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7
+      '%2Flegacy%2F'
 
 .. [#fn-oidc] Widely used CI/CD and cloud providers variously implement "ambient"
               OIDC token retrieval mechanisms that aren't standardized.