Filing this for discussion/feedback before I send a small PR 🙂

This idea came out of a discussion with @sigmavirus24 via the "automatic token refresh" idea in pypa/twine#1246 -- the basic idea there is that twine (and other tools) want to automatically refresh their TP-issued API tokens so that long-running multi-file uploads don't fail when the token expires between files.

From this, the observation is that twine (and other tools) need a way to know when they should refresh the API token. To do this they need to know when the token is going to expire, so that they can refresh with sufficient leeway.

This is technically possible today: any tool that uses the mint-token endpoint to do a TP exchange can decode the resulting macaroon and extract the expiration caveat. However, doing so means employing a macaroon deserializer, which is a nontrivial dependency to add to foundational dependencies like twine. Additionally, it requires client tools to track and maintain compatibility with PyPI's caveat encoding, which is not a public API (and has changed in the past).

Proposed solution

Rather than requiring tools to decode and consume the macaroon's caveat, the mint-token endpoint could duplicate the expiry directly in the response.

This should be trivial to do, since the expiry is computed directly in the mint_token helper right before being added to its caveat:

In effect, the success response from mint-token would change from:

{
  "success": true,
  "token": "pypi-..."
}

to:

{
  "success": true,
  "token": "pypi-...",
  "expires": <unix timestamp>
}

...where <unix timestamp> is the exact same timestamp as in the macaroon's expiration caveat.

I believe this poses no significant backwards compatibility risk, since it's a new field.

Alternatives considered

1. Instead of attempting to refresh the token "intelligently," tools could refresh it on every file upload. This would work and avoid the immediate expiration problem, but would result in a much larger volume of security event noise (since each TP exchange produces a project-level security event).
2. Tools could absorb a bit of additional complexity and decode the Macaroon themselves, although this would come with compatibility risks around the caveat encoding.

CC @di @ewdurbin @miketheman for thoughts 🙂