PEP 752: Address feedback, round 2 (#3922)
This commit is contained in:
Ofek Lev
GitHub
parent
7fbacdcd9d
commit
82f51125a6
|
|
@ -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",
|
||||
"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 <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
|
||||
A `public <public-namespaces_>`_ namespace allows for uploads from any
|
||||
Shared Namespace
|
||||
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
|
||||
`owner <grant-ownership_>`_
|
||||
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 <repository-metadata_>`_.
|
||||
|
||||
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 <repository-metadata_>`_.
|
||||
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 <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
|
||||
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 <grant-approval-criteria_>`_ SHALL
|
||||
always be public.
|
||||
|
||||
When a `child grant <child-grant_>`_ is created, its public status SHALL be
|
||||
When a `child grant <child-grant_>`_ is created, its shared 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
|
||||
`public <public-namespaces_>`_.
|
||||
* ``shared``: This is a boolean indicating whether the namespace is
|
||||
`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
|
||||
|
|
|
|||
Loading…
Reference in New Issue