Constraints

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

• All URLs MUST have potentially trustworthy origins. In practice, this means that all URLs MUST use the https scheme, be some variant of a local loopback (localhost, 127.0.0.1, etc.), or otherwise be considered a priori trustworthy in the context of the interaction (e.g. an internal network).

  Uploading clients MUST reject any URLs that do not meet this constraint.

• All server-supplied URLs (i.e. those in discovery responses) MUST have the same host subcomponent as the user-provided upload URL. Uploading 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 return URLs with the upload.example.com host.

• All client requests SHOULD have an Accept: application/vnd.pypi.pytp.v1+json header. In the absence of an Accept header, the receiving server MUST behave as if this header were present.

  Receiving servers SHOULD respond with a 406 Not Acceptable status code if any other Accept header is present.

Trusted Publishing Discovery

All Python package uploading is currently “endpoint driven,” in the sense uploading clients (like twine and uv) are given an upload URL (and not merely a domain name).

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

The discovery mechanism proposed below takes advantage of this fact to allow 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 the path component of the URL, as defined in RFC 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 the discovery key.

   For the above example, the discovery key is 0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7. [1]

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.

   For the above example, the discovery URL is https://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 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 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.

   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 given upload URL, it MUST respond with a 404 Not Found status code. When responding with a 404 Not Found, the server SHOULD NOT include a response body. If a response body is included, it MUST be ignored by the client.

Servers MAY additionally respond with any other standard HTTP error code in the 400 or 500 range to indicate an error condition.

Non-200 OK, non-404 Not Found responses MAY include a body which, if present, MUST be a JSON object containing an Error Response.

Trusted Publishing Token Exchange

Once an uploading client has performed a successful discovery flow, it can proceed to perform the actual Trusted Publishing token exchange.

Token exchange occurs in three steps:

1. The uploading client uses the audience endpoint obtained during discovery to ask the index for its expected OIDC audience.
2. The uploading client uses the expected audience to obtain an appropriately bound identity credential from the Trusted Publishing provider being used (i.e. the CI/CD or cloud provider that the upload is 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 the token minting endpoint obtained during discovery to exchange the obtained identity credential for a short-lived upload credential that can be used to upload to the index.

Error Responses

When an error response body is included, it MUST be a JSON object containing the following fields:

• message: a string containing a short, high-level

  human-readable summary of the error.

• errors: an array of one or more objects, each containing

  the following fields:

  • code: a string containing a machine-readable error code.
  • description: a string containing a human-readable description of the error.

This PEP does not specify any particular error codes. Clients SHOULD NOT assume that error codes are consistent across different indices, and instead MUST treat error codes as opaque strings.

“Lateral” Discovery

This PEP’s discovery mechanism uses the .well-known location scheme defined in RFC 8615. This scheme is widely adopted by machine-to-machine protocols, including OpenID Connect itself (for OpenID Connect Discovery).

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

The advantage of this approach is that it doesn’t require index operators to have control over their (sub-)domain, which the .well-known scheme expects (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 without interfering with existing functionality, which isn’t necessarily true. For example, a given third-party implementation may already use all routes under /legacy/{*} for other purposes.
• It’s less consistent with existing machine-to-machine protocol conventions, which overwhelmingly use the .well-known scheme. Developing a custom location scheme here would require additional informational materials for server administrators and operators who are accustomed to 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 an explicit discovery step, the uploading client could jump straight to attempting the audience and token minting steps, and handle any errors that arise.

The advantage of this approach is simplicity: it eliminates the network round-trip needed for the discovery step, and eliminates the indirection of obtaining the audience and token minting endpoints from the discovery response.

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 audience and token minting endpoints against the base domain of the upload URL. This limitation is acceptable in the context of a single index host like PyPI, but does not generalize to other index topologies (like index hosts that provide isolated private indices).
• It relies on entirely static endpoint construction rules for the audience and token minting endpoints, which means significant disruption to existing clients if those endpoints ever need to change.