Skip to content

Commit 4dd2a7f

Browse files
committed
Remove the metadata key from the file upload session creation request
* The file's contents are always the authoritative source of truth * PyPI is actively moving toward extracting metadata from the file. Also, add a little clarifying text to the Security Implications section.
1 parent 5d001ee commit 4dd2a7f

1 file changed

Lines changed: 21 additions & 12 deletions

File tree

peps/pep-0694.rst

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -733,7 +733,6 @@ The request looks like:
733733
"filename": "foo-1.0.tar.gz",
734734
"size": 1000,
735735
"hashes": {"sha256": "...", "blake2b": "..."},
736-
"metadata": "...",
737736
"mechanism": "http-post-bytes"
738737
}
739738
@@ -769,16 +768,11 @@ Besides the standard ``meta`` key, the request JSON has the following additional
769768
A client **MAY** send a mechanism that is not advertised in cases where server operators have
770769
documented a new or upcoming mechanism that is available for use on a "pre-release" basis.
771770

772-
``metadata`` (**optional**)
773-
If given, this is a string value containing the file's `core metadata
774-
<https://packaging.python.org/en/latest/specifications/core-metadata/>`_.
775-
776771
Servers **MAY** use the data provided in this request to do some sanity checking prior to allowing
777772
the file to be uploaded. These checks may include, but are not limited to:
778773

779774
- checking if the ``filename`` already exists in a published release;
780-
- checking if the ``size`` would exceed any project or file quota;
781-
- checking if the contents of the ``metadata``, if provided, are valid.
775+
- checking if the ``size`` would exceed any project or file quota.
782776

783777
A publishing session **MAY** be created for a ``name`` and ``version`` that has already been published, for
784778
example to add wheels for additional platforms to an existing release. However, because published artifacts
@@ -1305,6 +1299,9 @@ A suggested approach:
13051299
Security Implications
13061300
=====================
13071301

1302+
Name squatting potential
1303+
------------------------
1304+
13081305
Does PEP 694 make it easier to (maliciously) register project names, i.e. to name- or typo-squat? The authors
13091306
do not believe so. With the legacy API, it's trivially easy to create and upload a dummy package to register
13101307
a project name. This PEP does not effectively change that equation either way, nor does it aim to. That
@@ -1313,6 +1310,9 @@ rate limiting either the legacy API or Upload 2.0 API for empty packages or sess
13131310
which supports organizations or :pep:`752`-style implicit namespaces, could implement different rate limiting
13141311
rules for different actors. Such implementations are left as index-specific policy decisions.
13151312

1313+
Session authorization
1314+
---------------------
1315+
13161316
Session access is authorized contemporaneously rather than being bound to the credentials that created the
13171317
session (see :ref:`authentication`). Indexes **MUST** re-validate authorization on each session request --
13181318
including artifact uploads, file upload session completion, session extension requests, and publishing -- so
@@ -1328,15 +1328,22 @@ but who has already obtained the stage URL -- retains read-only preview access t
13281328
session is published or canceled. This is a narrow and accepted limitation; an index that considers it a
13291329
concern can mitigate it by canceling the affected session, or by limiting session lifetimes and extensions.
13301330

1331+
Malware hosting potential
1332+
-------------------------
1333+
13311334
Staged releases, while useful for testing and embargoes, do provide some potential for larger scale hosting of
1332-
malware which isn't detectable by third party, external scanning tools, because staged artifacts are only
1335+
malware which isn't detectable by third party external scanning tools, because staged artifacts are only
13331336
visible to clients which hold the stage token/url. It's not clear how much proactive malware scanning is
13341337
actually going on today with indexes such as PyPI, so it's unclear whether the (optional) staging feature is
13351338
much of an additional malware vector. Indexes should likely do some amount of proactive malware scanning on
1336-
all artifacts, regardless of the protocol used to upload them. Indexes can also mitigate the problem by
1337-
putting limits on session extensions, which might differ between projects depending on the user or (in the
1338-
case of PyPI) organization which owns the project. Indexes can refuse to extend sessions, and they can use
1339-
this to limit the availability of packages with unverified contents.
1339+
all artifacts, regardless of the protocol used to upload them. Because of the multi-step protocol proposed in
1340+
this PEP, indexes could share session links or uploaded staged files to trusted third party security partners
1341+
who could assist in scanning.
1342+
1343+
Indexes can also mitigate the problem by putting limits on session extensions, which might differ between
1344+
projects depending on the user or (in the case of PyPI) organization which owns the project. Indexes can
1345+
refuse to extend sessions, and they can use this to limit the availability of packages with unverified
1346+
contents.
13401347

13411348
Considering the testing and embargoed use cases may lead to different session expiry choices. Testing a
13421349
release can have a relatively short session lifespan, e.g. on the order of hours. Embargoed sessions may need
@@ -1489,6 +1496,8 @@ Change History
14891496
project, evaluated contemporaneously on each request. Adds an **Authentication and Authorization** model,
14901497
handles permission changes mid-session, supports rotating Trusted Publishing tokens and multiple
14911498
publishers contributing to one session, and notes the related security implications.
1499+
* Remove the optional ``metadata`` key from the file upload session creation request. The uploaded file is
1500+
the authoritative source of metadata, which the index extracts from the file itself.
14921501

14931502
* `07-Dec-2025 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/35>`__
14941503

0 commit comments

Comments
 (0)