Add the NPM project level API

The existing API has been split in two:
- Project level API
- Instance level API

Common endpoints are shared with a Concern

app/finders/packages/npm/package_finder.rb

@@ -12,6 +12,8 @@ module Packages
       end
 
       def execute
+        return Packages::Package.none unless project
+
         packages
       end
 

changelogs/unreleased/220985-add-npm-project-level-manager-api.yml

+---
+title: NPM project level API
+merge_request: 46867
+author:
+type: added

doc/user/packages/npm_registry/index.md

@@ -79,7 +79,18 @@ To create a project:
    the [naming convention](#package-naming-convention) and is scoped to the
    project or group where the registry exists.
 
-A `package.json` file is created. 
+A `package.json` file is created.
+
+## Use the GitLab endpoint for NPM packages
+
+To use the GitLab endpoint for NPM packages, choose an option:
+
+- **Project-level**: Use when you have few NPM packages and they are not in
+  the same GitLab group.
+- **Instance-level**: Use when you have many NPM packages in different
+  GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention).
+
+Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint.
 
 ## Authenticate to the Package Registry
 
@@ -94,20 +105,19 @@ To authenticate to the Package Registry, you must use one of the following:
 
 ### Authenticate with a personal access token or deploy token
 
-To authenticate with a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md),
-set your NPM configuration:
+To authenticate with the Package Registry, you will need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md).
 
-```shell
-# Set URL for your scoped packages
-# For example, a package named `@foo/bar` uses this URL for download
-npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/
+#### Project-level NPM endpoint
 
-# Add the token for the scoped packages URL 
-# Use this to download `@foo/` packages from private projects
-npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"
+To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration:
+
+```shell
+# Set URL for your scoped packages.
+# For example package with name `@foo/bar` will use this URL for download
+npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/
 
-# Add token for to publish to the package registry
-# Replace <your_project_id> with the project you want to publish your package to
+# Add the token for the scoped packages URL. Replace <your_project_id>
+# with the project where your package is located.
 npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>"
 ```
 
@@ -120,6 +130,28 @@ You should now be able to publish and install NPM packages in your project.
 If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view
 [troubleshooting steps](#troubleshooting).
 
+#### Instance-level NPM endpoint
+
+To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration:
+
+```shell
+# Set URL for your scoped packages.
+# For example package with name `@foo/bar` will use this URL for download
+npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/
+
+# Add the token for the scoped packages URL. This will allow you to download
+# `@foo/` packages from private projects.
+npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"
+```
+
+- `<your_token>` is your personal access token or deploy token.
+- Replace `gitlab.example.com` with your domain name.
+
+You should now be able to publish and install NPM packages in your project.
+
+If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view
+[troubleshooting steps](#troubleshooting).
+
 ### Authenticate with a CI job token
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5.
@@ -128,12 +160,22 @@ If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view
 If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token.
 The token inherits the permissions of the user that generates the pipeline.
 
-Add a corresponding section to your `.npmrc` file:
+#### Project-level NPM endpoint
+
+To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file:
+
+```ini
+@foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/
+//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}
+```
+
+#### Instance-level NPM endpoint
+
+To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file:
 
 ```ini
 @foo:registry=https://gitlab.example.com/api/v4/packages/npm/
 //gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN}
-//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}
 ```
 
 #### Use variables to avoid hard-coding auth token values
@@ -184,37 +226,22 @@ In GitLab, this regex validates all package names from all package managers:
 This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed).
 
 The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be
-identical to the root namespace of the project. 
+identical to the root namespace of the project.
 
 CAUTION: **Caution:**
 When you update the path of a user or group, or transfer a subgroup or project,
-you must remove any NPM packages first. You cannot update the root namespace 
+you must remove any NPM packages first. You cannot update the root namespace
 of a project with NPM packages. Make sure you update your `.npmrc` files to follow
 the naming convention and run `npm publish` if necessary.
 
 ## Publish an NPM package
 
-Before you can publish a package, you must specify the registry
-for NPM. To do this, add the following section to the bottom of `package.json`:
+Prerequisites:
 
-```json
-"publishConfig": {
-  "@foo:registry":"https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/"
-}
-```
-
-- `<your_project_id>` is your project ID, found on the project's home page.
-- `@foo` is your scope.
-- Replace `gitlab.example.com` with your domain name.
-
-DANGER: **Warning:**
-The `publishConfig` entry in the `package.json` file is not respected, because of a
-[bug in NPM](https://github.com/npm/cli/issues/1994) version `7.x` and later. You must
-use an earlier version of NPM, or temporarily set your `.npmrc` scope to
-`@foo:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm`.
+- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry.
+- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages).
 
-After you have set up [authentication](#authenticate-to-the-package-registry),
-you can upload an NPM package to your project:
+To upload an NPM package to your project, run this command:
 
 ```shell
 npm publish
@@ -227,6 +254,11 @@ a given scope, you get a `403 Forbidden!` error.
 
 ## Publish an NPM package by using CI/CD
 
+Prerequisites:
+
+- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry.
+- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages).
+
 To work with NPM commands within [GitLab CI/CD](../../../ci/README.md), you can use
 `CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands.
 
@@ -267,7 +299,7 @@ in a JavaScript project.
    Replace `@foo` with your scope.
 
 1. Ensure [authentication](#authenticate-to-the-package-registry) is configured.
-   
+
 1. In your project, to install a package, run:
 
    ```shell
@@ -390,9 +422,6 @@ should look like:
   "name": "@foo/my-package",
   "version": "1.0.0",
   "description": "Example package for GitLab NPM registry",
-  "publishConfig": {
-    "@foo:registry":"https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/"
-  }
 }
 ```
 

lib/api/api.rb

@@ -218,7 +218,8 @@ module API
       mount ::API::DebianGroupPackages
       mount ::API::DebianProjectPackages
       mount ::API::MavenPackages
-      mount ::API::NpmPackages
+      mount ::API::NpmProjectPackages
+      mount ::API::NpmInstancePackages
       mount ::API::GenericPackages
       mount ::API::GoProxy
       mount ::API::Pages

lib/api/concerns/packages/npm_endpoints.rb

+# frozen_string_literal: true
+
+# NPM Package Manager Client API
+#
+# These API endpoints are not consumed directly by users, so there is no documentation for the
+# individual endpoints. They are called by the NPM package manager client when users run commands
+# like `npm install` or `npm publish`. The usage of the GitLab NPM registry is documented here:
+# https://docs.gitlab.com/ee/user/packages/npm_registry/
+#
+# Technical debt: https://gitlab.com/gitlab-org/gitlab/issues/35798
+#
+# Caution: This Concern has to be included at the end of the API class
+# The last route of this Concern has a globbing wildcard that will match all urls.
+# As such, routes declared after the last route of this Concern will not match any url.
+module API
+  module Concerns
+    module Packages
+      module NpmEndpoints
+        extend ActiveSupport::Concern
+
+        included do
+          helpers ::API::Helpers::Packages::DependencyProxyHelpers
+
+          before do
+            require_packages_enabled!
+            authenticate_non_get!
+          end
+
+          params do
+            requires :package_name, type: String, desc: 'Package name'
+          end
+          namespace '-/package/*package_name' do
+            desc 'Get all tags for a given an NPM package' do
+              detail 'This feature was introduced in GitLab 12.7'
+              success ::API::Entities::NpmPackageTag
+            end
+            get 'dist-tags', format: false, requirements: ::API::Helpers::Packages::Npm::NPM_ENDPOINT_REQUIREMENTS do
+              package_name = params[:package_name]
+
+              bad_request!('Package Name') if package_name.blank?
+
+              authorize_read_package!(project)
+
+              packages = ::Packages::Npm::PackageFinder.new(project, package_name)
+                                                      .execute
+
+              not_found! if packages.empty?
+
+              present ::Packages::Npm::PackagePresenter.new(package_name, packages),
+                      with: ::API::Entities::NpmPackageTag
+            end
+
+            params do
+              requires :tag, type: String, desc: "Package dist-tag"
+            end
+            namespace 'dist-tags/:tag', requirements: ::API::Helpers::Packages::Npm::NPM_ENDPOINT_REQUIREMENTS do
+              desc 'Create or Update the given tag for the given NPM package and version' do
+                detail 'This feature was introduced in GitLab 12.7'
+              end
+              put format: false do
+                package_name = params[:package_name]
+                version = env['api.request.body']
+                tag = params[:tag]
+
+                bad_request!('Package Name') if package_name.blank?
+                bad_request!('Version') if version.blank?
+                bad_request!('Tag') if tag.blank?
+
+                authorize_create_package!(project)
+
+                package = ::Packages::Npm::PackageFinder
+                  .new(project, package_name)
+                  .find_by_version(version)
+                not_found!('Package') unless package
+
+                ::Packages::Npm::CreateTagService.new(package, tag).execute
+
+                no_content!
+              end
+
+              desc 'Deletes the given tag' do
+                detail 'This feature was introduced in GitLab 12.7'
+              end
+              delete format: false do
+                package_name = params[:package_name]
+                tag = params[:tag]
+
+                bad_request!('Package Name') if package_name.blank?
+                bad_request!('Tag') if tag.blank?
+
+                authorize_destroy_package!(project)
+
+                package_tag = ::Packages::TagsFinder
+                  .new(project, package_name, package_type: :npm)
+                  .find_by_name(tag)
+
+                not_found!('Package tag') unless package_tag
+
+                ::Packages::RemoveTagService.new(package_tag).execute
+
+                no_content!
+              end
+            end
+          end
+
+          desc 'NPM registry metadata endpoint' do
+            detail 'This feature was introduced in GitLab 11.8'
+          end
+          params do
+            requires :package_name, type: String, desc: 'Package name'
+          end
+          route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
+          get '*package_name', format: false, requirements: ::API::Helpers::Packages::Npm::NPM_ENDPOINT_REQUIREMENTS do
+            package_name = params[:package_name]
+
+            packages = ::Packages::Npm::PackageFinder.new(project_or_nil, package_name)
+                                                    .execute
+
+            redirect_request = project_or_nil.blank? || packages.empty?
+
+            redirect_registry_request(redirect_request, :npm, package_name: package_name) do
+              authorize_read_package!(project)
+
+              not_found!('Packages') if packages.empty?
+
+              present ::Packages::Npm::PackagePresenter.new(package_name, packages),
+                with: ::API::Entities::NpmPackage
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/api/helpers/packages/npm.rb

+# frozen_string_literal: true
+
+module API
+  module Helpers
+    module Packages
+      module Npm
+        include Gitlab::Utils::StrongMemoize
+        include ::API::Helpers::PackagesHelpers
+
+        NPM_ENDPOINT_REQUIREMENTS = {
+          package_name: API::NO_SLASH_URL_PART_REGEX
+        }.freeze
+
+        def endpoint_scope
+          params[:id].present? ? :project : :instance
+        end
+
+        def project
+          strong_memoize(:project) do
+            case endpoint_scope
+            when :project
+              user_project
+            when :instance
+              # Simulate the same behavior as #user_project by re-using #find_project!
+              # but take care if the project_id is nil as #find_project! is not designed
+              # to handle it.
+              project_id = project_id_or_nil
+
+              not_found!('Project') unless project_id
+
+              find_project!(project_id)
+            end
+          end
+        end
+
+        def project_or_nil
+          # mainly used by the metadata endpoint where we need to get a project
+          # and return nil if not found (no errors should be raised)
+          strong_memoize(:project_or_nil) do
+            next unless project_id_or_nil
+
+            find_project(project_id_or_nil)
+          end
+        end
+
+        def project_id_or_nil
+          strong_memoize(:project_id_or_nil) do
+            case endpoint_scope
+            when :project
+              params[:id]
+            when :instance
+              ::Packages::Package.npm
+                                .with_name(params[:package_name])
+                                .first
+                                &.project_id
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/api/npm_instance_packages.rb

+# frozen_string_literal: true
+module API
+  class NpmInstancePackages < ::API::Base
+    helpers ::API::Helpers::Packages::Npm
+
+    feature_category :package_registry
+
+    rescue_from ActiveRecord::RecordInvalid do |e|
+      render_api_error!(e.message, 400)
+    end
+
+    namespace 'packages/npm' do
+      include ::API::Concerns::Packages::NpmEndpoints
+    end
+  end
+end

lib/api/npm_packages.rb

-# frozen_string_literal: true
-module API
-  class NpmPackages < ::API::Base
-    helpers ::API::Helpers::PackagesHelpers
-    helpers ::API::Helpers::Packages::DependencyProxyHelpers
-
-    feature_category :package_registry
-
-    NPM_ENDPOINT_REQUIREMENTS = {
-      package_name: API::NO_SLASH_URL_PART_REGEX
-    }.freeze
-
-    rescue_from ActiveRecord::RecordInvalid do |e|
-      render_api_error!(e.message, 400)
-    end
-
-    before do
-      require_packages_enabled!
-      authenticate_non_get!
-    end
-
-    helpers do
-      def project_by_package_name
-        strong_memoize(:project_by_package_name) do
-          ::Packages::Package.npm.with_name(params[:package_name]).first&.project
-        end
-      end
-    end
-
-    desc 'Get all tags for a given an NPM package' do
-      detail 'This feature was introduced in GitLab 12.7'
-      success ::API::Entities::NpmPackageTag
-    end
-    params do
-      requires :package_name, type: String, desc: 'Package name'
-    end
-    get 'packages/npm/-/package/*package_name/dist-tags', format: false, requirements: NPM_ENDPOINT_REQUIREMENTS do
-      package_name = params[:package_name]
-
-      bad_request!('Package Name') if package_name.blank?
-
-      authorize_read_package!(project_by_package_name)
-
-      packages = ::Packages::Npm::PackageFinder.new(project_by_package_name, package_name)
-                                              .execute
-
-      present ::Packages::Npm::PackagePresenter.new(package_name, packages),
-              with: ::API::Entities::NpmPackageTag
-    end
-
-    params do
-      requires :package_name, type: String, desc: 'Package name'
-      requires :tag, type: String, desc: "Package dist-tag"
-    end
-    namespace 'packages/npm/-/package/*package_name/dist-tags/:tag', requirements: NPM_ENDPOINT_REQUIREMENTS do
-      desc 'Create or Update the given tag for the given NPM package and version' do
-        detail 'This feature was introduced in GitLab 12.7'
-      end
-      put format: false do
-        package_name = params[:package_name]
-        version = env['api.request.body']
-        tag = params[:tag]
-
-        bad_request!('Package Name') if package_name.blank?
-        bad_request!('Version') if version.blank?
-        bad_request!('Tag') if tag.blank?
-
-        authorize_create_package!(project_by_package_name)
-
-        package = ::Packages::Npm::PackageFinder
-          .new(project_by_package_name, package_name)
-          .find_by_version(version)
-        not_found!('Package') unless package
-
-        ::Packages::Npm::CreateTagService.new(package, tag).execute
-
-        no_content!
-      end
-
-      desc 'Deletes the given tag' do
-        detail 'This feature was introduced in GitLab 12.7'
-      end
-      delete format: false do
-        package_name = params[:package_name]
-        tag = params[:tag]
-
-        bad_request!('Package Name') if package_name.blank?
-        bad_request!('Tag') if tag.blank?
-
-        authorize_destroy_package!(project_by_package_name)
-
-        package_tag = ::Packages::TagsFinder
-          .new(project_by_package_name, package_name, package_type: :npm)
-          .find_by_name(tag)
-
-        not_found!('Package tag') unless package_tag
-
-        ::Packages::RemoveTagService.new(package_tag).execute
-
-        no_content!
-      end
-    end
-
-    desc 'NPM registry endpoint at instance level' do
-      detail 'This feature was introduced in GitLab 11.8'
-    end
-    params do
-      requires :package_name, type: String, desc: 'Package name'
-    end
-    route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
-    get 'packages/npm/*package_name', format: false, requirements: NPM_ENDPOINT_REQUIREMENTS do
-      package_name = params[:package_name]
-
-      redirect_registry_request(project_by_package_name.blank?, :npm, package_name: package_name) do
-        authorize_read_package!(project_by_package_name)
-
-        packages = ::Packages::Npm::PackageFinder
-          .new(project_by_package_name, package_name).execute
-
-        present ::Packages::Npm::PackagePresenter.new(package_name, packages),
-          with: ::API::Entities::NpmPackage
-      end
-    end
-
-    params do
-      requires :id, type: String, desc: 'The ID of a project'
-    end
-    resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
-      desc 'Download the NPM tarball' do
-        detail 'This feature was introduced in GitLab 11.8'
-      end
-      params do
-        requires :package_name, type: String, desc: 'Package name'
-        requires :file_name, type: String, desc: 'Package file name'
-      end
-      route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
-      get ':id/packages/npm/*package_name/-/*file_name', format: false do
-        authorize_read_package!(user_project)
-
-        package = user_project.packages.npm
-          .by_name_and_file_name(params[:package_name], params[:file_name])
-
-        package_file = ::Packages::PackageFileFinder
-          .new(package, params[:file_name]).execute!
-
-        track_package_event('pull_package', package)
-
-        present_carrierwave_file!(package_file.file)
-      end
-
-      desc 'Create NPM package' do
-        detail 'This feature was introduced in GitLab 11.8'
-      end
-      params do
-        requires :package_name, type: String, desc: 'Package name'
-        requires :versions, type: Hash, desc: 'Package version info'
-      end
-      route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
-      put ':id/packages/npm/:package_name', requirements: NPM_ENDPOINT_REQUIREMENTS do
-        authorize_create_package!(user_project)
-
-        track_package_event('push_package', :npm)
-
-        created_package = ::Packages::Npm::CreatePackageService
-          .new(user_project, current_user, params.merge(build: current_authenticated_job)).execute
-
-        if created_package[:status] == :error
-          render_api_error!(created_package[:message], created_package[:http_status])
-        else
-          created_package
-        end
-      end
-    end
-  end
-end

lib/api/npm_project_packages.rb

+# frozen_string_literal: true
+module API
+  class NpmProjectPackages < ::API::Base
+    helpers ::API::Helpers::Packages::Npm
+
+    feature_category :package_registry
+
+    rescue_from ActiveRecord::RecordInvalid do |e|
+      render_api_error!(e.message, 400)
+    end
+
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
+    namespace 'projects/:id/packages/npm' do
+      desc 'Download the NPM tarball' do
+        detail 'This feature was introduced in GitLab 11.8'
+      end
+      params do
+        requires :package_name, type: String, desc: 'Package name'
+        requires :file_name, type: String, desc: 'Package file name'
+      end
+      route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
+      get '*package_name/-/*file_name', format: false do
+        authorize_read_package!(project)
+
+        package = project.packages.npm
+          .by_name_and_file_name(params[:package_name], params[:file_name])
+
+        not_found!('Package') unless package
+
+        package_file = ::Packages::PackageFileFinder
+          .new(package, params[:file_name]).execute!
+
+        track_package_event('pull_package', package, category: 'API::NpmPackages')
+
+        present_carrierwave_file!(package_file.file)
+      end
+
+      desc 'Create NPM package' do
+        detail 'This feature was introduced in GitLab 11.8'
+      end
+      params do
+        requires :package_name, type: String, desc: 'Package name'
+        requires :versions, type: Hash, desc: 'Package version info'
+      end
+      route_setting :authentication, job_token_allowed: true, deploy_token_allowed: true
+      put ':package_name', requirements: ::API::Helpers::Packages::Npm::NPM_ENDPOINT_REQUIREMENTS do
+        authorize_create_package!(project)
+
+        track_package_event('push_package', :npm, category: 'API::NpmPackages')
+
+        created_package = ::Packages::Npm::CreatePackageService
+          .new(project, current_user, params.merge(build: current_authenticated_job)).execute
+
+        if created_package[:status] == :error
+          render_api_error!(created_package[:message], created_package[:http_status])
+        else
+          created_package
+        end
+      end
+
+      include ::API::Concerns::Packages::NpmEndpoints
+    end
+  end
+end

spec/finders/packages/npm/package_finder_spec.rb

@@ -16,6 +16,12 @@ RSpec.describe ::Packages::Npm::PackageFinder do
 
       it { is_expected.to be_empty }
     end
+
+    context 'with nil project' do
+      let(:project) { nil }
+
+      it { is_expected.to be_empty }
+    end
   end
 
   describe '#find_by_version' do

spec/requests/api/npm_instance_packages_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe API::NpmInstancePackages do
+  include_context 'npm api setup'
+
+  describe 'GET /api/v4/packages/npm/*package_name' do
+    it_behaves_like 'handling get metadata requests' do
+      let(:url) { api("/packages/npm/#{package_name}") }
+    end
+  end
+
+  describe 'GET /api/v4/packages/npm/-/package/*package_name/dist-tags' do
+    it_behaves_like 'handling get dist tags requests', scope: :instance do
+      let(:url) { api("/packages/npm/-/package/#{package_name}/dist-tags") }
+    end
+  end
+
+  describe 'PUT /api/v4/packages/npm/-/package/*package_name/dist-tags/:tag' do
+    it_behaves_like 'handling create dist tag requests', scope: :instance do
+      let(:url) { api("/packages/npm/-/package/#{package_name}/dist-tags/#{tag_name}") }
+    end
+  end
+
+  describe 'DELETE /api/v4/packages/npm/-/package/*package_name/dist-tags/:tag' do
+    it_behaves_like 'handling delete dist tag requests', scope: :instance do
+      let(:url) { api("/packages/npm/-/package/#{package_name}/dist-tags/#{tag_name}") }
+    end
+  end
+end

spec/support/shared_contexts/requests/api/npm_packages_shared_context.rb

+# frozen_string_literal: true
+
+RSpec.shared_context 'npm api setup' do
+  include PackagesManagerApiSpecHelpers
+  include HttpBasicAuthHelpers
+
+  let_it_be(:user) { create(:user) }
+  let_it_be(:group) { create(:group) }
+  let_it_be(:project, reload: true) { create(:project, :public, namespace: group) }
+  let_it_be(:package, reload: true) { create(:npm_package, project: project) }
+  let_it_be(:token) { create(:oauth_access_token, scopes: 'api', resource_owner: user) }
+  let_it_be(:personal_access_token) { create(:personal_access_token, user: user) }
+  let_it_be(:job, reload: true) { create(:ci_build, user: user, status: :running) }
+  let_it_be(:deploy_token) { create(:deploy_token, read_package_registry: true, write_package_registry: true) }
+  let_it_be(:project_deploy_token) { create(:project_deploy_token, deploy_token: deploy_token, project: project) }
+
+  let(:package_name) { package.name }
+
+  before do
+    project.add_developer(user)
+  end
+end

spec/support/shared_examples/requests/api/npm_packages_shared_examples.rb

+# frozen_string_literal: true
+
+RSpec.shared_examples 'handling get metadata requests' do
+  let_it_be(:package_dependency_link1) { create(:packages_dependency_link, package: package, dependency_type: :dependencies) }
+  let_it_be(:package_dependency_link2) { create(:packages_dependency_link, package: package, dependency_type: :devDependencies) }
+  let_it_be(:package_dependency_link3) { create(:packages_dependency_link, package: package, dependency_type: :bundleDependencies) }
+  let_it_be(:package_dependency_link4) { create(:packages_dependency_link, package: package, dependency_type: :peerDependencies) }
+
+  let(:params) { {} }
+  let(:headers) { {} }
+
+  subject { get(url, params: params, headers: headers) }
+
+  shared_examples 'returning the npm package info' do
+    it 'returns the package info' do
+      subject
+
+      expect_a_valid_package_response
+    end
+  end
+
+  shared_examples 'a package that requires auth' do
+    it 'denies request without oauth token' do
+      subject
+
+      expect(response).to have_gitlab_http_status(:not_found)
+    end
+
+    context 'with oauth token' do
+      let(:params) { { access_token: token.token } }
+
+      it 'returns the package info with oauth token' do
+        subject
+
+        expect_a_valid_package_response
+      end
+    end
+
+    context 'with job token' do
+      let(:params) { { job_token: job.token } }
+
+      it 'returns the package info with running job token' do
+        subject
+
+        expect_a_valid_package_response
+      end
+
+      it 'denies request without running job token' do
+        job.update!(status: :success)
+
+        subject
+
+        expect(response).to have_gitlab_http_status(:unauthorized)
+      end
+    end
+
+    context 'with deploy token' do
+      let(:headers) { build_token_auth_header(deploy_token.token) }
+
+      it 'returns the package info with deploy token' do
+        subject
+
+        expect_a_valid_package_response
+      end
+    end
+  end
+
+  context 'a public project' do
+    it_behaves_like 'returning the npm package info'
+
+    context 'project path with a dot' do
+      before do
+        project.update!(path: 'foo.bar')
+      end
+
+      it_behaves_like 'returning the npm package info'
+    end
+
+    context 'with request forward disabled' do
+      before do
+        stub_application_setting(npm_package_requests_forwarding: false)
+      end
+
+      it_behaves_like 'returning the npm package info'
+
+      context 'with unknown package' do
+        let(:package_name) { 'unknown' }
+
+        it 'returns the proper response' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:not_found)
+        end
+      end
+    end
+
+    context 'with request forward enabled' do
+      before do
+        stub_application_setting(npm_package_requests_forwarding: true)
+      end
+
+      it_behaves_like 'returning the npm package info'
+
+      context 'with unknown package' do
+        let(:package_name) { 'unknown' }
+
+        it 'returns a redirect' do
+          subject
+
+          expect(response).to have_gitlab_http_status(:found)
+          expect(response.headers['Location']).to eq('https://registry.npmjs.org/unknown')
+        end
+
+        it_behaves_like 'a gitlab tracking event', described_class.name, 'npm_request_forward'
+      end
+    end
+  end
+
+  context 'internal project' do
+    before do
+      project.update!(visibility_level: Gitlab::VisibilityLevel::INTERNAL)
+    end
+
+    it_behaves_like 'a package that requires auth'
+  end
+
+  context 'private project' do
+    before do
+      project.update!(visibility_level: Gitlab::VisibilityLevel::PRIVATE)
+    end
+
+    it_behaves_like 'a package that requires auth'
+
+    context 'with guest' do
+      let(:params) { { access_token: token.token } }
+
+      it 'denies request when not enough permissions' do
+        project.add_guest(user)
+
+        subject
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+  end
+
+  def expect_a_valid_package_response
+    expect(response).to have_gitlab_http_status(:ok)
+    expect(response.media_type).to eq('application/json')
+    expect(response).to match_response_schema('public_api/v4/packages/npm_package')
+    expect(json_response['name']).to eq(package.name)
+    expect(json_response['versions'][package.version]).to match_schema('public_api/v4/packages/npm_package_version')
+    ::Packages::Npm::PackagePresenter::NPM_VALID_DEPENDENCY_TYPES.each do |dependency_type|
+      expect(json_response.dig('versions', package.version, dependency_type.to_s)).to be_any
+    end
+    expect(json_response['dist-tags']).to match_schema('public_api/v4/packages/npm_package_tags')
+  end
+end
+
+RSpec.shared_examples 'handling get dist tags requests' do
+  let_it_be(:package_tag1) { create(:packages_tag, package: package) }
+  let_it_be(:package_tag2) { create(:packages_tag, package: package) }
+
+  let(:params) { {} }
+
+  subject { get(url, params: params) }
+
+  context 'with public project' do
+    context 'with authenticated user' do
+      let(:params) { { private_token: personal_access_token.token } }
+
+      it_behaves_like 'returns package tags', :maintainer
+      it_behaves_like 'returns package tags', :developer
+      it_behaves_like 'returns package tags', :reporter
+      it_behaves_like 'returns package tags', :guest
+    end
+
+    context 'with unauthenticated user' do
+      it_behaves_like 'returns package tags', :no_type
+    end
+  end
+
+  context 'with private project' do
+    before do
+      project.update!(visibility_level: Gitlab::VisibilityLevel::PRIVATE)
+    end
+
+    context 'with authenticated user' do
+      let(:params) { { private_token: personal_access_token.token } }
+
+      it_behaves_like 'returns package tags', :maintainer
+      it_behaves_like 'returns package tags', :developer
+      it_behaves_like 'returns package tags', :reporter
+      it_behaves_like 'rejects package tags access', :guest, :forbidden
+    end
+
+    context 'with unauthenticated user' do
+      it_behaves_like 'rejects package tags access', :no_type, :not_found
+    end
+  end
+end
+
+RSpec.shared_examples 'handling create dist tag requests' do
+  let_it_be(:tag_name) { 'test' }
+
+  let(:params) { {} }
+  let(:env) { {} }
+  let(:version) { package.version }
+
+  subject { put(url, env: env, params: params) }
+
+  context 'with public project' do
+    context 'with authenticated user' do
+      let(:params) { { private_token: personal_access_token.token } }
+      let(:env) { { 'api.request.body': version } }
+
+      it_behaves_like 'create package tag', :maintainer
+      it_behaves_like 'create package tag', :developer
+      it_behaves_like 'rejects package tags access', :reporter, :forbidden
+      it_behaves_like 'rejects package tags access', :guest, :forbidden
+    end
+
+    context 'with unauthenticated user' do
+      it_behaves_like 'rejects package tags access', :no_type, :unauthorized
+    end
+  end
+end
+
+RSpec.shared_examples 'handling delete dist tag requests' do
+  let_it_be(:package_tag) { create(:packages_tag, package: package) }
+
+  let(:params) { {} }
+  let(:tag_name) { package_tag.name }
+
+  subject { delete(url, params: params) }
+
+  context 'with public project' do
+    context 'with authenticated user' do
+      let(:params) { { private_token: personal_access_token.token } }
+
+      it_behaves_like 'delete package tag', :maintainer
+      it_behaves_like 'rejects package tags access', :developer, :forbidden
+      it_behaves_like 'rejects package tags access', :reporter, :forbidden
+      it_behaves_like 'rejects package tags access', :guest, :forbidden
+    end
+
+    context 'with unauthenticated user' do
+      it_behaves_like 'rejects package tags access', :no_type, :unauthorized
+    end
+  end
+
+  context 'with private project' do
+    before do
+      project.update!(visibility_level: Gitlab::VisibilityLevel::PRIVATE)
+    end
+
+    context 'with authenticated user' do
+      let(:params) { { private_token: personal_access_token.token } }
+
+      it_behaves_like 'delete package tag', :maintainer
+      it_behaves_like 'rejects package tags access', :developer, :forbidden
+      it_behaves_like 'rejects package tags access', :reporter, :forbidden
+      it_behaves_like 'rejects package tags access', :guest, :forbidden
+    end
+
+    context 'with unauthenticated user' do
+      it_behaves_like 'rejects package tags access', :no_type, :unauthorized
+    end
+  end
+end

spec/support/shared_examples/requests/api/packages_tags_shared_examples.rb

@@ -40,7 +40,7 @@ RSpec.shared_examples 'returns package tags' do |user_type|
   context 'with invalid package name' do
     where(:package_name, :status) do
       '%20' | :bad_request
-      nil   | :forbidden
+      nil   | :not_found
     end
 
     with_them do
@@ -95,7 +95,7 @@ RSpec.shared_examples 'create package tag' do |user_type|
 
   context 'with invalid package name' do
     where(:package_name, :status) do
-      'unknown' | :forbidden
+      'unknown' | :not_found
       ''        | :not_found
       '%20'     | :bad_request
     end
@@ -160,7 +160,7 @@ RSpec.shared_examples 'delete package tag' do |user_type|
 
     context 'with invalid package name' do
       where(:package_name, :status) do
-        'unknown' | :forbidden
+        'unknown' | :not_found
         ''        | :not_found
         '%20'     | :bad_request
       end