Organizations

Any package repository that allows for the creation of projects (e.g. non-mirrors) MAY offer the concept of organizations. Organizations are entities that own projects and have various users associated with them.

Organizations MAY reserve one or more namespaces. Such reservations neither confer ownership nor grant special privileges to existing projects.

Naming

A namespace MUST be a valid project name and normalized internally e.g. foo.bar would become foo-bar.

Semantics

A namespace grant bestows ownership over the following:

1. A project matching the namespace itself such as the placeholder package microsoft.
2. Projects that start with the namespace followed by a hyphen. For example, the namespace foo would match the normalized project name foo-bar but not the project name foobar.

Package name matching acts upon the normalized namespace.

Namespaces are per-package repository and SHALL NOT be shared between repositories. For example, if PyPI has a namespace microsoft that is owned by the company Microsoft, packages starting with microsoft- that come from other non-PyPI mirror repositories do not confer the same level of trust.

Grants MUST NOT overlap. For example, if there is an existing grant for foo-bar then a new grant for foo would be forbidden. 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.

Uploads

If the following criteria are all true for a given upload:

1. The project does not yet exist.
2. The name matches a reserved namespace.
3. The project is not owned by an organization with an active grant for the namespace.

Then the upload MUST fail with a 403 HTTP status code.

Open 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.

It is possible for the owner of a namespace to both make it open and allow other organizations to use the grant. In this case, the authorized organizations have no special permissions and are equivalent to an open grant without ownership.

Hidden Grants

Repositories MAY create hidden grants that are not visible to the public which prevent their namespaces from being claimed by others. Such grants MUST NOT be open and SHOULD NOT be exposed in the API.

Hidden grants are useful for repositories that wish to enforce upload restrictions without the need to expose the namespace to the public.

Repository Metadata

The JSON API version will be incremented from 1.2 to 1.3. The following API changes MUST be implemented by repositories that support this PEP. Repositories that do not support this PEP MUST NOT implement these changes so that consumers of the API are able to determine whether the repository supports this PEP.

Grant Removal

When a reserved namespace becomes unclaimed, repositories MUST set the namespace key to null in the API.

Namespaces that were previously claimed but are now not SHOULD be eligible for claiming again by any organization.

Organization Scoping

The primary motivation for this PEP is to reduce dependency confusion attacks and NPM-style scoping with an allowance of the legacy flat namespace would increase the risk. If documentation instructed a user to install bar in the namespace foo then the user must be careful to install @foo/bar and not foo-bar, or vice versa. The Python packaging ecosystem has normalization rules for names in order to maximize the ease of communication and this would be a regression.

The runtime environment of Python is also not conducive to scoping. Whereas multiple versions of the same JavaScript package may coexist, Python only allows a single global namespace. Barring major changes to the language itself, this is nearly impossible to change. Additionally, users have come to expect that the package name is usually the same as what they would import and eliminating the flat namespace would do away with that convention.

Scoping would be particularly affected by organization changes which are bound to happen over time. An organization may change their name due to internal shuffling, an acquisition, or any other reason. Whenever this happens every project they own would in effect be renamed which would cause unnecessary confusion for users, frequently.

Finally, the disruption to the community would be massive because it would require an update from every package manager, security scanner, IDE, etc. New 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.

Encourage Dedicated Package Repositories

Critically, this imposes a burden on projects to maintain their own infra. This is an unrealistic expectation for the vast majority of companies and a complete non-starter for community projects.

This does not help in most cases because the default behavior of most package managers is to use PyPI so users attempting to perform a simple pip install would already be vulnerable to malicious packages.

In this theoretical future every project must document how to add their repository to dependency resolution, which would be different for each package manager. Few package managers are able to download specific dependencies from specific repositories and would require users to use verbose configuration in the common case.

The ones that do not support this would instead find a given package using an ordered enumeration of repositories, leading to dependency confusion. For example, say a user wants two packages from two custom repositories X and Y. If each repository has both packages but one is malicious on X and the other is malicious on Y then the user would be unable to satisfy their requirements without encountering a malicious package.

Use Fixed Prefixes

The idea here would be to have one or more top-level fixed prefixes that are used for namespace reservations:

• com-: Reserved for corporate organizations.
• org-: Reserved for community organizations.

Organizations would then apply for a namespace prefixed by the type of their organization.

This would cause perpetual disruption because when projects begin it is unknown whether a user base will be large enough to warrant a namespace reservation. Whenever that happens the project would have to be renamed which would put a high maintenance burden on the project maintainers and would cause confusion for users who have to learn a new way to reference the project’s packages. The potential for this deterring projects from reserving namespaces at all is high.

Another issue with this approach is that projects often have branding in mind (example) and would be reluctant to change their package names.

It’s unrealistic to expect every company and project to voluntarily change their existing and future package names.

Use DNS

The idea here is to add a new metadata field to projects in the API called domain-authority. Repositories would support a new endpoint for verifying the domain via HTTPS. Clients would then support options to allow certain domains.

This does not solve the problem for the target audience who do not check where their packages are coming from and is more about checking for the integrity of uploads which is already supported in a more secure way by PEP 740.

Most projects do not have a domain and could not benefit from this, unfairly favoring organizations that have the financial means to acquire one.