Constraints

Unless explicitly stated otherwise, the following constraintsapply to all parts of this PEP’s specification:

• All URLsMUST havepotentially trustworthy origins.In practice, this means that all URLsMUST use thehttpsscheme, be some variant of a local loopback (localhost,127.0.0.1, etc.), or otherwise be considereda priori trustworthyin the context of the interaction (e.g. an internal network).

  Uploading clientsMUST reject any URLs that do not meet this constraint.

• All server-supplied URLs (i.e. those in discovery responses)MUSThave the same host subcomponent as the user-provided upload URL. UploadingclientsMUST reject any URLs that do not meet this constraint.

  In practice, this means that a discovery request tohttps://upload.example.com/.well-known/pytp/{key} can onlyreturn URLs with theupload.example.com host.

• All client requestsSHOULD have anAccept:application/vnd.pypi.pytp.v1+json header. In the absence ofanAccept header, the receiving serverMUST behave as if this headerwere present.

  Receiving serversSHOULD respond with a406NotAcceptablestatus code if any otherAccept header is present.

• Unless otherwise specified, all error (4xx and 5xx) responses from the serverMUST use theRFC 9457 (Problem Details for HTTP APIs) format.In particular, the serverMUST use the “Problem Details JSON Object”defined inSection 3 andSHOULD usetheapplication/problem+json media type in its responses.

Trusted Publishing Discovery

All Python package uploading is currently “endpoint driven,” in the senseuploading clients (liketwine anduv) are given an upload URL (andnot merely a domain name).

For example, to upload to PyPI, uploading clients are expected to connecttohttps://upload.pypi.org/legacy/.

The discovery mechanism proposed below takes advantage of this fact toallow single domains to advertise support for multiple indices(and their corresponding upload endpoints).

The discovery mechanism is as follows:

1. The uploading client is given an upload URL, e.g.https://upload.example.com/legacy/.
2. The uploading client extracts thepath component of the URL,as defined inRFC 3986. If the path component is empty,the empty string should be used.

   For the above example, the path component is/legacy/.

3. The uploading client takes the SHA2-256 hash of the path component,producing thediscovery key.

   For the above example, the discovery key is0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7.[1]

4. The uploading client constructs adiscovery URL by taking thescheme and authority components (as defined inRFC 3986)of the upload URL and appending/.well-known/pytp/and the discovery key.

   For the above example, the discovery URL ishttps://upload.example.com/.well-known/pytp/af030c06750716b1b35852298fe852b90def13dcbd012a5fe5148470f1206bfc.

5. The uploading client performs an HTTP GET request to the discovery URL.
6. The server responds with a200OK status code and a bodycontaining a JSON object if the index supports Trusted Publishingfor the given upload URL. The JSON objectMUST contain the followingfields:
   • audience-endpoint: a string containing the URL of the OIDCaudience endpoint to be used during token exchange.
   • token-mint-endpoint: a string containing the URL of thetoken minting endpoint to be used during token exchange.

   For the above example, a valid response body would be:

   {"audience-endpoint":"https://upload.example.com/_/oidc/audience","token-mint-endpoint":"https://upload.example.com/_/oidc/mint-token"}

If the server does not support Trusted Publishing for the givenupload URL, itMUST respond with a404NotFound status code.

ServersMAY additionally respond with any other standard HTTPerror code in the 400 or 500 range to indicate an appropriate errorcondition.

Trusted Publishing Token Exchange

Once an uploading client has performed a successfuldiscovery flow, it can proceed to performthe actual Trusted Publishing token exchange.

Token exchange occurs in three steps:

1. The uploading client uses theaudience endpoint obtainedduring discovery to ask the index for its expected OIDC audience.
2. The uploading client uses the expected audience to obtain anappropriately boundidentity credential from the Trusted Publishingprovider being used (i.e. the CI/CD or cloud provider that the uploadis being performed from). The details of this step are provider-specific,and are out of scope for this PEP.[2]
3. The uploading client uses thetoken minting endpoint obtainedduring discovery to exchange the obtained identity credentialfor a short-livedupload credential that can be used to uploadto the index.

“Lateral” Discovery

This PEP’s discovery mechanism uses the.well-known location schemedefined inRFC 8615. This scheme is widely adopted by machine-to-machineprotocols, including OpenID Connect itself (forOpenID Connect Discovery).

An alternative idea considered was to use a “lateral” discovery mechanism,in which the uploading client would attempt discovery by constructing aadjacent path relative to the upload URL. For example, forhttps://upload.example.com/legacy/, the uploading client wouldattempt to discover Trusted Publishing support athttps://upload.example.com/legacy/pytp (or some equivalent).

The advantage of this approach is that it doesn’t require index operatorsto have control over their (sub-)domain, which the.well-known schemeexpects (as well-known URIs can only be served from the root of a domain).

However, this approach also has downsides:

• It assumes that arbitrary indices can provide an adjacent path withoutinterfering with existing functionality, which isn’t necessarily true.For example, a given third-party implementation may already useall routes under/legacy/{*} for other purposes.
• It’s less consistent with existing machine-to-machine protocolconventions, which overwhelmingly use the.well-known scheme. Developinga custom location scheme here would require additional informationalmaterials for server administrators and operators who are accustomedto the.well-known scheme.

“Implicit” Discovery

Another alternative idea considered was the perform “implicit” discovery,similar to what PyPI currently does for Trusted Publishing: instead of anexplicitdiscovery step, the uploading client could jumpstraight to attempting the audience and token minting steps, andhandle any errors that arise.

The advantage of this approach is simplicity: it eliminates the networkround-trip needed for the discovery step, and eliminates the indirectionof obtaining the audience and token minting endpoints from the discoveryresponse.

This approach too has downsides:

• It implicitly limits a given domain to a single index/upload implementation,since the implicit “discovery” step on PyPI is to construct the audienceand token minting endpoints against the base domain of the upload URL.This limitation is acceptable in the context of a single index hostlike PyPI, but does not generalize to other index topologies (likeindex hosts that provide isolated private indices).
• It relies on entirely static endpoint construction rules forthe audience and token minting endpoints, which means significant disruptionto existing clients if those endpoints ever need to change.