diff --git a/peps/pep-0807.rst b/peps/pep-0807.rst index adff6c70f15..e8280d0e080 100644 --- a/peps/pep-0807.rst +++ b/peps/pep-0807.rst @@ -175,7 +175,9 @@ 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 @@ -183,13 +185,27 @@ The discovery mechanism is as follows: - ``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 ``__. + + - ``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 =====================