Address comments for stronger wording including section on avoiding denial of service by having scanning wait until all file uploads complete.

Author: cjames23

peps/pep-0694.rst

@@ -299,9 +299,16 @@ system alone can neither publish a release nor discard a pending one.
 Cancellation is protected because it is destructive: it discards the staged files and frees the name-version
 pair.  An index that left it at the upload-permission level would let a compromised upload credential delete a
 release a maintainer has staged and is waiting to publish (a denial-of-release), or discard a session that
-has been flagged and is awaiting review.  An index that instead wants an automated uploader to be able to
-abort its *own* in-progress uploads **MAY** leave cancellation at the upload-permission level.  How any
-additional authorization is expressed, and whether it is offered at all, is determined by the index operator.
+has been flagged and is awaiting review.  For a first release of a new project, cancellation also releases the
+temporary project-name reservation the index holds for the session, so an index that did not protect it would
+let a compromised upload credential discard the session and allow the name to be claimed by someone else.  An
+index that instead wants an automated uploader to be able to abort its *own* in-progress uploads **MAY** leave
+cancellation at the upload-permission level.
+
+How any additional authorization is expressed, and whether it is offered at all, is determined by the index
+operator.  An index **MAY** keep this choice operator-wide, or expose it to individual project owners, for
+example by letting a project owner require the separate authorization for their own project, or allow a single
+principal to hold both.
 
 
 .. _session-errors:
@@ -618,29 +625,36 @@ expected to remain available anyway, as this PEP does not propose a deprecation
 an index **MAY** allow a legacy upload to create a publishing session, so that from creation onward the session is the
 same as one created directly.
 
-An index that supports this **MUST** document it, and **SHOULD** accept a ``staged`` field with the value
+An index that supports this **MUST** document it, and **MUST** accept a ``staged`` field with the value
 ``true`` in the legacy ``multipart/form-data`` upload request.  When that field is present, the index creates a
 publishing session in the ``open`` state for the uploaded file's project and version, adds the file to it as a
-:ref:`completed <file-upload-session-states>` file upload, and does not publish it.  The index **SHOULD**
+:ref:`completed <file-upload-session-states>` file upload, and does not publish it.  The index **MUST**
 return the :ref:`publishing session creation response body <publishing-session-response>` from that upload,
 including the ``links`` and ``session-token`` keys, so that the publisher can then use the endpoints in this
 PEP to :ref:`preview <staged-preview>`, :ref:`publish <publishing-session-completion>`, or :ref:`cancel
-<publishing-session-cancellation>` the session.  An index **MAY** also create a session for an upload based on
+<publishing-session-cancellation>` the session.  Returning the body is required because a client that sets
+``staged=true`` but receives no session handle would be left unable to publish or cancel the staged release.
+Note that a client that sets ``staged=true`` without understanding the response may record it (for example in
+public CI logs); the ``session-token`` it contains grants only read-only :ref:`preview <staged-preview>`
+access, but indexes and publishers **SHOULD** be aware that it can be exposed this way.  An index **MAY** also create a session for an upload based on
 its own policy or the project's configuration, without the field being present; this allows a project to
 require that its releases are staged in a way that an upload client cannot bypass.  In this policy driven
 case no client change is required at all; the ``staged`` field lets a publisher opt in per upload with only a
 minimal change to existing tooling.
 
 Because the legacy API uploads a single file per request, subsequent legacy uploads for the same project and
 version **SHOULD** be added to the same open session when that session was itself created through a legacy
-upload, so that the release is still published as a unit.
+upload, so that the release is still published as a unit.  Once such a session exists, a subsequent legacy
+upload for that project and version is added to it whether or not it carries the ``staged`` field: the field
+is not required again, and the index **MUST NOT** reject the upload for omitting it.  The field is still
+permitted on these uploads as an explicit statement of intent.
 
 A session's creation path is fixed when it is created, and the two paths **MUST NOT** be mixed.
 If a non-terminal session already exists for a name-version pair (see :ref:`publishing-session-multiple`), a request to
-contribute to it through the *other* path **MUST** be rejected with a ``409 Conflict``: a legacy
-``staged=true`` upload for a pair that already has an open session created through the Upload 2.0 API is
-rejected, and an Upload 2.0 request that would add to a session created through a legacy upload is likewise
-rejected.
+contribute to it through the *other* path **MUST** be rejected with a ``409 Conflict``: any legacy upload for
+a pair that already has an open session created through the Upload 2.0 API is rejected (whether or not it
+carries the ``staged`` field), and an Upload 2.0 request that would add to a session created through a legacy
+upload is likewise rejected.
 
 Fixing the path at creation avoids ambiguity in how the session reaches a terminal state.  An Upload 2.0
 session is driven to completion by a client that holds its ``session-token`` and calls the control plane
@@ -826,6 +840,15 @@ change: deferred processing resolves to either ``published`` on success or ``err
 resolves to ``error``, the session remains editable and the reason is reported in the session's ``notices``,
 as described in :ref:`publishing-session-states`.
 
+Reviewing an upload can produce two kinds of result, surfaced at different points.  Correctness problems that
+can be decided about a single file in isolation, such as its size, checksum, metadata, or compatibility tags,
+are surfaced when that :ref:`file upload session <file-upload-session-states>` completes, moving the file to
+the ``error`` state, from which it cannot be repaired in place.  Results that concern whether the release may
+become public, such as malware detection, instead gate the publish step and are described below.  An index
+**MAY** run malware review per file, as each file is uploaded, as well as (or instead of) at publication; a
+file remains uploadable to a stage for some time before the release is published, so reviewing each file as it
+arrives can shorten the window in which an unreviewed file sits in a stage.
+
 The ``processing`` state **MAY** be used to run asynchronous review of a session's files before it is
 published, such as malware scanning.  If the review completes without an adverse result, the session resolves
 to ``published`` as normal.  If the review does not complete within a period chosen by the index, the server
@@ -849,7 +872,9 @@ change is left to the index: it might run to completion, rescan only the changed
 Because editing a session can trigger re-review, an index **SHOULD** guard against abuse of the review system.
 For example, a client might repeatedly upload a file it knows will be flagged, delete it, and re-upload it to
 force repeated scans.  Mitigations such as rate-limiting reviews, capping the number of review attempts for a
-session, or moving a persistently adverse session to a terminal state are left to the index.
+session, or moving a persistently adverse session to a terminal state are left to the index.  An index can
+also avoid this class of abuse entirely by performing the review only at publication time, when the session's
+files are fixed for the duration of the publish and cannot be swapped out to force another scan.
 
 A publish attempt that fails *synchronously* (i.e. within the publish request itself) is returned to the
 client as an :ref:`error response <session-errors>` and leaves the session in its current editable state; it
@@ -1955,16 +1980,21 @@ as experience is gained operating Upload 2.0.
 Change History
 ==============
 
-* `01-Aug-2026 <https://discuss.python.org/t/pre-pep-staged-releases-separated-from-pep-694/107804/58>`__
+* `01-Oct-2026 <https://discuss.python.org/t/pre-pep-staged-releases-separated-from-pep-694/107804/58>`__
 
   * Add :ref:`Legacy Upload API Interoperability <legacy-interop>`, allowing a legacy upload to create a
     publishing session (via a ``staged`` field, or by index or project configuration that an upload client
     cannot bypass) so that staging is usable before upload tooling adopts this API, and allowing an index to
-    publish such a session itself once automated processing resolves or its window elapses.
+    publish such a session itself once automated processing resolves or its window elapses.  Require that an
+    index supporting this accept the ``staged`` field and return the session creation response body, specify
+    that subsequent legacy uploads to an open stage need not repeat the field, and forbid mixing the two
+    session-creation paths.
   * Note that the ``processing`` state **MAY** be used for asynchronous review such as malware scanning, with
-    an index-chosen window after which the review is treated as having produced no adverse result.
+    an index-chosen window after which the review is treated as having produced no adverse result.  Distinguish
+    per-file correctness results from release-level review, allow review per file or at publication, and note
+    that reviewing at publication time avoids re-scan abuse.
   * Allow an index to require additional authorization, beyond upload permission, to publish or cancel a
-    session, so that duties can be separated.
+    session, so that duties can be separated, optionally exposing that choice to project owners.
 
 * `29-Jul-2026 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-4/108320>`__