限制

除非另有明确说明，否则本PEP规范的所有部分都适用以下限制：

• 所有URL**必须**具有潜在受信任的来源。实际上，这意味着所有URL**必须**使用https方案，是本地回环的某种变体（localhost、127.0.0.1等），或在交互上下文中被*先验*视为可信（例如，内部网络）。

  上传客户端**必须**拒绝任何不符合此限制的URL。

• 所有服务器提供的URL（即发现响应中的URL）**必须**与用户提供的上传URL具有相同的主机子组件。上传客户端**必须**拒绝任何不符合此限制的URL。

  实际上，这意味着对https://upload.example.com/.well-known/pytp/{key}的发现请求只能返回主机为upload.example.com的URL。

• 所有客户端请求**应该**包含Accept: application/vnd.pypi.pytp.v1+json头部。在没有Accept头部的情况下，接收服务器**必须**表现得如同此头部存在。

  如果存在任何其他Accept头部，接收服务器**应该**以406 Not Acceptable状态码响应。

信任发布发现

所有Python包上传目前都是“端点驱动”的，这意味着上传客户端（如*twine*和*uv*）会获得一个上传URL（而不是仅仅一个域名）。

例如，要上传到PyPI，上传客户端需要连接到https://upload.pypi.org/legacy/。

下面提出的发现机制利用了这一事实，允许单个域宣传对多个索引（及其相应的上传端点）的支持。

发现机制如下：

1. 上传客户端会获得一个上传URL，例如https://upload.example.com/legacy/。
2. 上传客户端提取URL的*路径组件*，如RFC 3986中所定义。如果路径组件为空，则应使用空字符串。

   对于上述示例，路径组件是/legacy/。

3. 上传客户端对路径组件进行SHA2-256哈希运算，生成*发现密钥*。

   对于上述示例，发现密钥是0cace9579789849db6e16d48df183951c8f17582200d84bc93c7678d6c8f78a7。[1]

4. 上传客户端通过获取上传URL的方案和权限组件（如RFC 3986中定义）并附加/.well-known/pytp/和发现密钥来构建*发现URL*。

   对于上述示例，发现 URL 是 https://upload.example.com/.well-known/pytp/af030c06750716b1b35852298fe852b90def13dcbd012a5fe5148470f1206bfc。

5. 上传客户端向发现URL执行HTTP GET请求。
6. 如果索引支持给定上传URL的信任发布，服务器会以200 OK状态码和包含JSON对象的正文进行响应。JSON对象**必须**包含以下字段：
   • audience-endpoint：一个字符串，包含在令牌交换期间使用的OIDC受众端点的URL。
   • token-mint-endpoint：一个字符串，包含在令牌交换期间使用的令牌铸造端点的URL。

   对于上述示例，一个有效的响应正文将是：

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

如果服务器不支持给定上传URL的信任发布，它**必须**以404 Not Found状态码响应。当以404 Not Found响应时，服务器**不应**包含响应正文。如果包含响应正文，客户端**必须**忽略它。

服务器**可以**额外响应任何其他400或500范围内的标准HTTP错误代码以指示错误情况。

非200 OK、非404 Not Found响应**可以**包含正文，如果存在，**必须**是包含错误响应的JSON对象。

信任发布令牌交换

一旦上传客户端成功执行了发现流程，它就可以继续执行实际的信任发布令牌交换。

令牌交换分三步进行：

1. 上传客户端使用在发现过程中获得的*受众端点*，向索引请求其预期的OIDC受众。
2. 上传客户端使用预期的受众，从正在使用的信任发布提供者（即执行上传操作的CI/CD或云提供商）获取适当绑定的*身份凭证*。此步骤的详细信息取决于提供商，超出了本PEP的范围。[2]
3. 上传客户端使用在发现过程中获得的*令牌铸造端点*，将获得的身份凭证交换为可用于上传到索引的短期*上传凭证*。

错误响应

当包含错误响应体时，它**必须**是一个包含以下字段的 JSON 对象：

• message：一个字符串，包含错误简短、高级的

  人类可读的摘要。

• errors：一个包含一个或多个对象的数组，每个对象包含

  以下字段：

  • code：一个字符串，包含机器可读的错误代码。
  • description：一个字符串，包含错误的人类可读描述。

本PEP未指定任何特定的错误代码。客户端**不应**假定错误代码在不同索引之间是一致的，而**必须**将错误代码视为不透明的字符串。

“横向”发现

本PEP的发现机制使用了RFC 8615中定义的.well-known位置方案。该方案被机器间协议广泛采用，包括OpenID Connect本身（用于OpenID Connect发现）。

另一种考虑的替代方案是使用“横向”发现机制，即上传客户端将尝试通过构建相对于上传URL的相邻路径进行发现。例如，对于https://upload.example.com/legacy/，上传客户端将尝试在https://upload.example.com/legacy/pytp（或类似的）处发现信任发布支持。

这种方法的优点是它不需要索引操作员控制他们的（子）域，而.well-known方案是期望的（因为众所周知的URI只能从域的根目录提供）。

然而，这种方法也有缺点：

• 它假设任意索引可以提供相邻路径而不会干扰现有功能，这不一定成立。例如，给定的第三方实现可能已经将/legacy/{*}下的所有路由用于其他目的。
• 它与现有机器间协议约定的一致性较差，后者绝大多数使用.well-known方案。在此处开发自定义位置方案将需要为习惯于.well-known方案的服务器管理员和操作员提供额外的说明材料。

“隐式”发现

另一种替代方案是执行“隐式”发现，类似于PyPI目前对信任发布所做的事情：上传客户端可以跳过明确的发现步骤，直接尝试受众和令牌铸造步骤，并处理可能出现的任何错误。

这种方法的优点是简单：它消除了发现步骤所需的网络往返，并消除了从发现响应中获取受众和令牌铸造端点的间接性。

这种方法也有缺点：

• 它隐式地将给定域限制为单个索引/上传实现，因为PyPI上的隐式“发现”步骤是根据上传URL的基础域构建受众和令牌铸造端点。此限制在像PyPI这样的单个索引主机的情况下是可以接受的，但不能推广到其他索引拓扑（如提供隔离私有索引的索引主机）。
• 它依赖于完全静态的受众和令牌铸造端点构造规则，这意味着如果这些端点需要更改，将对现有客户端造成重大干扰。