PEP 807: add feature negotiation

peps/pep-0807.rst

@@ -175,21 +175,37 @@ The discovery mechanism is as follows:
 
 6. The server responds with a ``200 OK`` status code and a body
    containing a JSON object if the index supports Trusted Publishing
-   for the given upload URL. The JSON object **MUST** contain the following
+   for the given upload URL.
+
+   The JSON object **MUST** contain the following
    fields:
 
    - ``audience-endpoint``: a string containing the URL of the OIDC
      audience endpoint to be used during token exchange.
    - ``token-mint-endpoint``: a string containing the URL of the
      token minting endpoint to be used during token exchange.
 
+   Additionally, the JSON object **MAY** contain the following fields:
+
+   - ``features``: an array of strings indicating optional features
+     supported by the index's Trusted Publishing implementation.
+     The set of possible features is defined under `<Feature Negotiation_>`__.
+
+   - ``default-features``: an array of strings indicating the default
+     features used by the index's Trusted Publishing implementation
+     if a request does not explicitly specify any features.
+     If the ``default-features`` field is not present, the uploading client
+     **MUST** assume a default of ``["multi-use-token"]``.
+
    For the above example, a valid response body would be:
 
    .. code-block:: json
 
       {
          "audience-endpoint": "https://upload.example.com/_/oidc/audience",
-         "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token"
+         "token-mint-endpoint": "https://upload.example.com/_/oidc/mint-token",
+         "features": ["single-use-token", "multi-use-token"],
+         "default-features": ["multi-use-token"]
       }
 
 If the server does not support Trusted Publishing for the given
@@ -250,6 +266,20 @@ POST request **MUST** be a JSON object containing the following:
 
 - ``token``: a string containing the identity credential
   obtained from the Trusted Publishing provider.
+- ``features``: an **optional** array of strings
+  indicating the desired features for the minted upload credential.
+  If this field is not provided by the client, the server **MUST** use
+  its own default features as specified in the
+  ``default-features`` field during discovery.
+
+For example, a valid request body would be:
+
+.. code-block:: json
+
+   {
+      "token": "ey...",
+      "features": ["single-use-token"]
+   }
 
 On success, the server responds with a ``200 OK`` status code and a body
 containing a JSON object with the following fields:
@@ -275,6 +305,32 @@ containing a JSON object with the following fields:
 On failure, the server **MUST** respond with any standard HTTP
 error code in the 400 or 500 range to indicate the appropriate error condition.
 
+Feature Negotiation
+~~~~~~~~~~~~~~~~~~~
+
+The protocol defined in this PEP supports an *optional* mechanism for
+negotiating non-default features between the uploading client and the
+receiving index server. These features are advertised as an array of
+strings in the ``features`` field of the discovery response; the client
+can then request one or more features by including them in the ``features``
+field of the token minting request.
+
+The following features are defined:
+
+- ``single-use-token``: the tokens minted by the index server
+  **MUST** be single-use tokens. In other words, the token returned
+  by the token minting endpoint **MUST** only be usable for a single
+  upload operation. Any subsequent upload attempts using the same
+  token **MUST** be rejected by the index server. Clients that request
+  the ``single-use-token`` feature **MUST** be prepared to perform
+  multiple token minting operations if multiple upload operations
+  are needed.
+
+- ``multi-use-token``: the tokens minted by the index server
+  **MUST** be multi-use tokens. In other words, the token returned
+  by the token minting endpoint **MAY** be usable for multiple
+  upload operations until it expires.
+
 Security Implications
 =====================