PEP 752: Address feedback, round 2 (#3922)

peps/pep-0752.rst

@@ -2,7 +2,7 @@ PEP: 752
 Title: Package repository namespaces
 Author: Ofek Lev <ofekmeister@gmail.com>
 Sponsor: Barry Warsaw <barry@python.org>
-PEP-Delegate: Donald Stufft <donald@stufft.io>
+PEP-Delegate: Dustin Ingram <di@python.org>
 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",
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
-described in :rfc:`2119`.
+interpreted as described in :rfc:`2119`.
 
 Organization
     `Organizations <orgs_>`_ are entities that own projects and have various
@@ -153,8 +154,8 @@ Organization
 Corporate Organization
     `Corporate organizations <corp-orgs_>`_ are organizations that have paid
     for special functionality on PyPI.
-Public Namespace
+Shared Namespace
-    A `public <public-namespaces_>`_ namespace allows for uploads from any
+    A `shared <shared-namespaces_>`_ 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 <naming_>`_ 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 <orgs_>`_ 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 <child-grant_>`_.
 
+Root grants MUST NOT overlap. For example, if there is an existing root grant
+for ``foo-bar`` then an organization cannot `apply <grant-application_>`_ for
+``foo``. An overlap is determined by comparing the `normalized <naming_>`_
+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 <https://pypi.org/project/google-cloud-compute/1.19.2/>`__)
-that both matches an active namespace grant and is tied to an
+that matches an active namespace grant MUST indicate what the prefix is (NuGet
-`owner <grant-ownership_>`_
+currently does not do this). This value MUST match the ``namespace.name`` key
-MUST receive a special indicator that signifies this tie.
+in the `API <repository-metadata_>`_.
 
-The UI also MUST indicate what the prefix is (NuGet does not do this) and this
+Clicking on the namespace MUST take the user to a page that has more
-value MUST match the ``namespace`` key in the `API <repository-metadata_>`_.
+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
+Any indicator used in the following scenarios for projects that match an active
-namespace grant and which organization(s) own it.
+namespace grant MUST be distinct from one another:
 
-.. _public-namespaces:
+1. Projects that are tied to a `grant owner <grant-ownership_>`_ MAY have an
+   indicator.
+2. Projects that are not tied to a `grant owner <grant-ownership_>`_ and the
+   matching grant is `shared <shared-namespaces_>`_ MUST have an indicator.
+3. Projects that are not tied to a `grant owner <grant-ownership_>`_ 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 <uploads_>`_ for new projects matching the namespace from any user
-but such releases MUST NOT have the `visual indicator <user-interface_>`_.
+but such projects MUST have a distinct `visual indicator <user-interface_>`_.
 
 It is possible for the `owner <grant-ownership_>`_ of a namespace to both make
-it public and allow other organizations to use it. In this case, the permitted
+it shared and allow other organizations to use the grant. In this case, the
-organizations have no special permissions and are essentially only public.
+permitted organizations have no special permissions and are equivalent to a
+shared grant without ownership.
 
-Root grants given to `community projects <grant-approval-criteria_>`_ SHALL
+When a `child grant <child-grant_>`_ is created, its shared status SHALL be
-always be public.
-
-When a `child grant <child-grant_>`_ is created, its public status SHALL be
 inherited from the `root grant <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 <grant-approval-criteria_>`_ 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 <grant-ownership_>`_ 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
+* ``shared``: This is a boolean indicating whether the namespace is
-  `public <public-namespaces_>`_.
+  `shared <shared-namespaces_>`_.
 
 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 <orgs_>`_ have access to the page for submitting grant
 applications. Reviews of `corporate organizations <corp-orgs_>`_ 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 <https://github.com/owid>`__
 
+Recommendations
+===============
+
+Visual Indicators
+-----------------
+
+For projects that match an active namespace grant, the namespace is always
+shown in `the UI <user-interface_>`_. 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 <grant-ownership_>`_ 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 <grant-ownership_>`_ and are
+   part of a `shared <shared-namespaces_>`_ namespace should never have an
+   indicator that conveys mistrust or danger. A good choice might be the
+   `users <https://fontawesome.com/icons/users>`_ icon from Font Awesome or the
+   `groups`__ icon from Google Fonts.
+3. Projects that are not tied to a `grant owner <grant-ownership_>`_ 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 <public-namespaces_>`_. This is almost always desired by
+projects are `shared <shared-namespaces_>`_. 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