From 82f51125a6bbb17a065b1b8f916b6abb2a728c82 Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Sat, 24 Aug 2024 18:29:27 -0400 Subject: [PATCH] PEP 752: Address feedback, round 2 (#3922) --- peps/pep-0752.rst | 136 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 102 insertions(+), 34 deletions(-) diff --git a/peps/pep-0752.rst b/peps/pep-0752.rst index fcd4e625e..f73b31b1e 100644 --- a/peps/pep-0752.rst +++ b/peps/pep-0752.rst @@ -2,7 +2,7 @@ PEP: 752 Title: Package repository namespaces Author: Ofek Lev Sponsor: Barry Warsaw -PEP-Delegate: Donald Stufft +PEP-Delegate: Dustin Ingram Discussions-To: https://discuss.python.org/t/61227 Status: Draft Type: Standards Track @@ -47,7 +47,10 @@ verified pattern of ownership. Some examples: __ https://docs.datadoghq.com/developers/integrations/agent_integration/ -Such projects are uniquely vulnerable to `dependency confusion`__ attacks. +Such projects are uniquely vulnerable to name-squatting attacks +which can ultimately result in `dependency confusion`__. + +__ https://www.activestate.com/resources/quick-reads/dependency-confusion/ For example, say a new product is released for which monitoring would be valuable. It would be reasonable to assume that Datadog would eventually @@ -59,8 +62,6 @@ appears legitimate which would execute malicious code at runtime. Not only are users more likely to install such packages but doing so taints the perception of the entire project. -__ https://www.activestate.com/resources/quick-reads/dependency-confusion/ - Although :pep:`708` attempts to address this attack vector, it is specifically about the case of multiple repositories being considered during dependency resolution and does not offer any protection to the aforementioned use cases. @@ -142,9 +143,9 @@ specific scenarios) provides the following benefits: Terminology =========== -The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", -"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as -described in :rfc:`2119`. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in :rfc:`2119`. Organization `Organizations `_ are entities that own projects and have various @@ -153,8 +154,8 @@ Organization Corporate Organization `Corporate organizations `_ are organizations that have paid for special functionality on PyPI. -Public Namespace - A `public `_ namespace allows for uploads from any +Shared Namespace + A `shared `_ namespace allows for uploads from any project owner. Private Namespace A private namespace only allows uploads from an owner of the namespace. @@ -193,7 +194,9 @@ A namespace grant bestows ownership over the following: Package name matching acts upon the `normalized `_ namespace. Namespaces are per-package repository and SHALL NOT be shared between -repositories. +repositories. Each repository is responsible for managing namespaces the way +they want, and repositories are not expected to replicate namespaces from one +repository to another. Grant Types ----------- @@ -209,6 +212,14 @@ Only `organizations `_ have the ability to submit requests for namespace grants. An organization gets a root grant for every accepted request. This grant may produce any number of `child grants `_. +Root grants MUST NOT overlap. For example, if there is an existing root grant +for ``foo-bar`` then an organization cannot `apply `_ for +``foo``. An overlap is determined by comparing the `normalized `_ +proposed namespace with the normalized namespace of every existing root grant. +Every comparison must append a hyphen to the end of the proposed and existing +namespace. An overlap is detected when any existing namespace starts with the +proposed namespace. + .. _child-grant: Child Grant @@ -253,41 +264,55 @@ Then the upload MUST fail with a 403 HTTP status code. User Interface -------------- -Every page for a particular release +Every project's page (`example `__) -that both matches an active namespace grant and is tied to an -`owner `_ -MUST receive a special indicator that signifies this tie. +that matches an active namespace grant MUST indicate what the prefix is (NuGet +currently does not do this). This value MUST match the ``namespace.name`` key +in the `API `_. -The UI also MUST indicate what the prefix is (NuGet does not do this) and this -value MUST match the ``namespace`` key in the `API `_. +Clicking on the namespace MUST take the user to a page that has more +information such as the current owners and the time at which ownership was +granted. This page SHOULD enumerate every project that matches the namespace +and display a count of the total number of projects. -Repositories SHOULD have a dedicated page that enumerates every active -namespace grant and which organization(s) own it. +Any indicator used in the following scenarios for projects that match an active +namespace grant MUST be distinct from one another: -.. _public-namespaces: +1. Projects that are tied to a `grant owner `_ MAY have an + indicator. +2. Projects that are not tied to a `grant owner `_ and the + matching grant is `shared `_ MUST have an indicator. +3. Projects that are not tied to a `grant owner `_ and the + matching grant is private MUST have an indicator. This situation arises when + the project existed before the grant was created. -Public Namespaces +Repositories MUST NOT offer a way to view all active namespace grants. This is +to prevent leaking potentially private information such as an upcoming product. + +.. _shared-namespaces: + +Shared Namespaces ----------------- The owner of a grant may choose to allow others the ability to release new projects with the associated namespace. Doing so MUST allow `uploads `_ for new projects matching the namespace from any user -but such releases MUST NOT have the `visual indicator `_. +but such projects MUST have a distinct `visual indicator `_. It is possible for the `owner `_ of a namespace to both make -it public and allow other organizations to use it. In this case, the permitted -organizations have no special permissions and are essentially only public. +it shared and allow other organizations to use the grant. In this case, the +permitted organizations have no special permissions and are equivalent to a +shared grant without ownership. -Root grants given to `community projects `_ SHALL -always be public. - -When a `child grant `_ is created, its public status SHALL be +When a `child grant `_ is created, its shared status SHALL be inherited from the `root grant `_. Owners of child grants MAY -make them public at any time. If a grant is public, it MUST NOT be made private +make them shared at any time. If a grant is shared, it MUST NOT be made private unless the owner of the grant is the owner of every project that matches the namespace. +Root grants given to `community projects `_ SHOULD +only be shared but is ultimately up to the reviewer of the application. + .. _repository-metadata: Repository Metadata @@ -313,8 +338,8 @@ the value MUST be a mapping with the following keys: `own `_ the grant. This is useful for tools that wish to make a distinction between official and community packages by checking if the array contains the project ``owner``. -* ``public``: This is a boolean indicating whether the namespace is - `public `_. +* ``shared``: This is a boolean indicating whether the namespace is + `shared `_. The presence of the ``namespace`` key indicates support for this PEP. @@ -338,12 +363,14 @@ When a reserved namespace becomes unclaimed, repositories: Grant Applications ------------------ +.. _grant-application: + Submission '''''''''' Only `organizations `_ have access to the page for submitting grant applications. Reviews of `corporate organizations `_ applications -are prioritized. +MUST be prioritized. .. _grant-approval-criteria: @@ -366,6 +393,47 @@ represent one of the following: * NPOs/NGOs that actively publish packages like `Our World in Data `__ +Recommendations +=============== + +Visual Indicators +----------------- + +For projects that match an active namespace grant, the namespace is always +shown in `the UI `_. It is recommended that this should +stand out as a pill or label. + +There are three types of visual indicators for each type of project: + +1. There should be no indicator for projects that are tied to a + `grant owner `_ and users should solely rely on the + always-present namespace. If an indicator is chosen, it should not be + a check mark or similar because it may mistakingly convey that there are + associated security guarantees inherent to the use of the package. + Additionally, some social media platforms use a check mark for verified + users which may cause confusion. +2. Projects that are not tied to a `grant owner `_ and are + part of a `shared `_ namespace should never have an + indicator that conveys mistrust or danger. A good choice might be the + `users `_ icon from Font Awesome or the + `groups`__ icon from Google Fonts. +3. Projects that are not tied to a `grant owner `_ and are + part of a private grant (i.e. existed before the grant) should have an + indicator that conveys inauthenticity or lack of trust. A good choice might + be a warning sign (⚠). + +__ https://fonts.google.com/icons?selected=Material+Symbols+Outlined:groups + +Grant Applications +------------------ + +Generally speaking, reviewers should be more tolerant of corporate +organizations that apply for grants for which they are not yet using. + +For example, while it's reasonable to grant a namespace to a startup or an +existing company with a new product line, it's not as reasonable to grant a +namespace to a community project that doesn't have many users. + Backwards Compatibility ======================= @@ -451,11 +519,11 @@ packages released with the scoping would be incompatible with older tools and would cause confusion for users along with frustration from maintainers having to triage such complaints. -Allow Non-Public Namespaces for Community Projects --------------------------------------------------- +Allow Private Namespaces for Community Projects +----------------------------------------------- This PEP enforces that the discretionary namespace grants for community -projects are `public `_. This is almost always desired by +projects are `shared `_. This is almost always desired by such projects and prevents the following situations: * A perceived reduction in openness of community projects, for example if a