Proposal: Document Trusted Publishing audience/route discovery more generically

[woodruffw]

I'm opening this up as a proposal; if it makes sense to you all I'm happy to submit the corresponding changes 🙂

The problem

At the moment, PyPI's implementation of Trusted Publishing uses some PyPI-specific APIs:

• /_/oidc/audience to retrieve the audience
• /_/oidc/mint-token to actually perform the token exchange

These work well! However, the docs currently describe these as being at the root of the domain, e.g. https://pypi.org/_/oidc/mint-token. This implicitly ties the index service itself to a single "registry," since there's no way to disambiguate requests from that URL (i.e., across multiple conceptual registries).

This (IMO) poses a challenge both for PyPI (if/when it plans to support multiple registries) and for third-party index services (which should IMO support Trusted Publishing, but may have registry or other sharding abstractions that don't make sense to fold into a single token-minting endpoint).

Proposal

My proposal is a documentation-only change: instead of describing the Trusted Publishing APIs as rooted to the domain itself, we could describe them as following the prefix of the upload API URL.

In other words, to discover the /_/oidc/audience endpoint, the client would:

1. Take the user's upload API URL (e.g. https://upload.pypi.org/legacy or `https://example.com/blah/blah)
2. Get the parent URL (e.g. https://upload.pypi.org/ or https://example.com/blah)
3. Append the API route from there (e.g. https://upload.pypi.org/_/oidc/audience or https://example.com/blah/_/oidc/audience)

The nice thing about this is that it's 100% compatible with the existing route: PyPI already places these routes in a location that's compatible with this discovery scheme. However, describing discovery this way (rather than as a route that's appended to the base domain) also enables the route to be changed or split across registries (or even different upload APIs, e.g. if PEP 694 is adopted).

Other considerations

I think this poses no significant compatibility risks, since it doesn't require any code changes to PyPI itself -- all it does is update the documentation to clarify the discovery procedure for Trusted Publishing support.

With that being said, if this makes sense then I'll send PRs to the appropriate downstream (i.e. uploader) clients -- I suspect at least a few of them are doing https://{domain}/{route} instead of https://{domain}/{base}/{route}, which currently works for PyPI but isn't fully general.

[woodruffw]

Some xrefs (note that "need" means for full generality, not to avoid breakage):

• gh-action-pypi-publish will need to be changed here
• twine will need to be changed here
• maturin will need to be changed here
• uv publish will need to change here and here
• pdm publish will need to change here

[woodruffw]

For tracking: there's a pre-PEP discussion around this as well: https://discuss.python.org/t/pre-pep-trusted-publishing-token-exchange/103067