pacote 21.0.4 → 21.2.0

package/README.md

@@ -21,24 +21,19 @@ pacote.tarball('https://server.com/package.tgz').then(data => {
 })
 ```
 
-`pacote` works with any kind of package specifier that npm can install.  If
-you can pass it to the npm CLI, you can pass it to pacote.  (In fact, that's
-exactly what the npm CLI does.)
+`pacote` works with any kind of package specifier that npm can install.
+If you can pass it to the npm CLI, you can pass it to pacote.
+(In fact, that's exactly what the npm CLI does.)
 
 Anything that you can do with one kind of package, you can do with another.
 
-Data that isn't relevant (like a packument for a tarball) will be
-simulated.
+Data that isn't relevant (like a packument for a tarball) will be simulated.
 
-`prepare` scripts will be run when generating tarballs from `git` and
-`directory` locations, to simulate what _would_ be published to the
-registry, so that you get a working package instead of just raw source
-code that might need to be transpiled.
+`prepare` scripts will be run when generating tarballs from `git` and `directory` locations, to simulate what _would_ be published to the registry, so that you get a working package instead of just raw source code that might need to be transpiled.
 
 ## CLI
 
-This module exports a command line interface that can do most of what is
-described below.  Run `pacote -h` to learn more.
+This module exports a command line interface that can do most of what is described below.  Run `pacote -h` to learn more.
 
 ```
 Pacote - The JavaScript Package Handler, v10.1.1
@@ -75,112 +70,105 @@ For example '--cache=/path/to/folder' will use that folder as the cache.
 
 ## API
 
-The `spec` refers to any kind of package specifier that npm can install.
-If you can pass it to the npm CLI, you can pass it to pacote.  (In fact,
-that's exactly what the npm CLI does.)
+The `spec` refers to any kind of [package specifier](npm.im/npm-package-arg) that npm can install.
 
 See below for valid `opts` values.
 
-* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or
-  `github:user/project` all the way to a tarball url, tarball file, or git
-  repo with commit hash.
+* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or `github:user/project` all the way to a tarball url, tarball file, or git repo with commit hash.
 
-* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a
-  destination folder.  Returns a promise that resolves to the
-  `{from,resolved,integrity}` of the extracted package.
+* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a destination folder.
+  Returns a promise that resolves to the `{from,resolved,integrity}` of the extracted package.
 
-* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest
-  (basically, the `package.json` file, plus a bit of metadata).
-  See below for more on manifests and packuments.  Returns a Promise that
-  resolves to the manifest object.
+* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest (basically, the `package.json` file, plus a bit of metadata).
+  See below for more on manifests and packuments.
+  Returns a Promise that resolves to the manifest object.
 
-* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument
-  (basically, the top-level package document listing all the manifests that
-  the registry returns).  See below for more on manifests and packuments.
+* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument (basically, the top-level package document listing all the manifests that the registry returns).
+  See below for more on manifests and packuments.
   Returns a Promise that resolves to the packument object.
 
 * `pacote.tarball(spec, opts)`  Get a package tarball data as a buffer in
-  memory.  Returns a Promise that resolves to the tarball data Buffer, with
-  `from`, `resolved`, and `integrity` fields attached.
+  memory.
+  Returns a Promise that resolves to the tarball data Buffer, with `from`, `resolved`, and `integrity` fields attached.
 
-* `pacote.tarball.file(spec, dest, opts)`  Save a package tarball data to
-  a file on disk.  Returns a Promise that resolves to
-  `{from,integrity,resolved}` of the fetched tarball.
+* `pacote.tarball.file(spec, dest, opts)`  Save a package tarball data to a file on disk.
+  Returns a Promise that resolves to `{from,integrity,resolved}` of the fetched tarball.
 
-* `pacote.tarball.stream(spec, streamHandler, opts)`  Fetch a tarball and
-  make the stream available to the `streamHandler` function.
+* `pacote.tarball.stream(spec, streamHandler, opts)`  Fetch a tarball and make the stream available to the `streamHandler` function.
 
-    This is mostly an internal function, but it is exposed because it does
-    provide some functionality that may be difficult to achieve otherwise.
+    This is mostly an internal function, but it is exposed because it does provide some functionality that may be difficult to achieve otherwise.
 
-    The `streamHandler` function MUST return a Promise that resolves when
-    the stream (and all associated work) is ended, or rejects if the stream
+    The `streamHandler` function MUST return a Promise that resolves when the stream (and all associated work) is ended, or rejects if the stream
     has an error.
 
-    The `streamHandler` function MAY be called multiple times, as Pacote
-    retries requests in some scenarios, such as cache corruption or
-    retriable network failures.
+    The `streamHandler` function MAY be called multiple times, as Pacote retries requests in some scenarios, such as cache corruption or retriable network failures.
 
 ### Options
 
 Options are passed to
-[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and
-[`cacache`](http://npm.im/cacache), so in addition to these, anything for
-those modules can be given to pacote as well.
+[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and [`cacache`](http://npm.im/cacache), so in addition to these, anything for those modules can be given to pacote as well.
 
-Options object is cloned, and mutated along the way to add integrity,
-resolved, and other properties, as they are determined.
+Options object is cloned, and mutated along the way to add integrity, resolved, and other properties, as they are determined.
 
-* `cache` Where to store cache entries and temp files.  Passed to
-  [`cacache`](http://npm.im/cacache).  Defaults to the same cache directory
-  that npm will use by default, based on platform and environment.
+* `cache` Where to store cache entries and temp files.
+  Passed to [`cacache`](http://npm.im/cacache).
+  Defaults to the same cache directory that npm will use by default, based on platform and environment.
 * `where` Base folder for resolving relative `file:` dependencies.
-* `resolved` Shortcut for looking up resolved values.  Should be specified
-  if known.
-* `integrity` Expected integrity of fetched package tarball.  If specified,
-  tarballs with mismatched integrity values will raise an `EINTEGRITY`
-  error.
+* `resolved` Shortcut for looking up resolved values.  Should be specified if known.
+* `integrity` Expected integrity of fetched package tarball.
+  If specified, tarballs with mismatched integrity values will raise an `EINTEGRITY` error.
 * `umask` Permission mode mask for extracted files and directories.
-  Defaults to `0o22`.  See "Extracted File Modes" below.
-* `fmode` Minimum permission mode for extracted files.  Defaults to
-  `0o666`.  See "Extracted File Modes" below.
-* `dmode` Minimum permission mode for extracted directories.  Defaults to
-  `0o777`.  See "Extracted File Modes" below.
-* `preferOnline` Prefer to revalidate cache entries, even when it would not
-  be strictly necessary.  Default `false`.
-* `before` When picking a manifest from a packument, only consider
-  packages published before the specified date.  Default `null`.
-* `defaultTag` The default `dist-tag` to use when choosing a manifest from a
-  packument.  Defaults to `latest`.
-* `registry` The npm registry to use by default.  Defaults to
-  `https://registry.npmjs.org/`.
-* `fullMetadata` Fetch the full metadata from the registry for packuments,
-  including information not strictly required for installation (author,
-  description, etc.)  Defaults to `true` when `before` is set, since the
-  version publish time is part of the extended packument metadata.
-* `fullReadJson` Use the slower `read-package-json` package insted of
-  `read-package-json-fast` in order to include extra fields like "readme" in
-  the manifest. Defaults to `false`.
-* `packumentCache` For registry packuments only, you may provide a `Map`
-  object which will be used to cache packument requests between pacote
-  calls.  This allows you to easily avoid hitting the registry multiple
-  times (even just to validate the cache) for a given packument, since it
-  is unlikely to change in the span of a single command.
-* `verifySignatures` A boolean that will make pacote verify the
-    integrity signature of a manifest, if present.  There must be a
-    configured `_keys` entry in the config that is scoped to the
-    registry the manifest is being fetched from.
-* `verifyAttestations` A boolean that will make pacote verify Sigstore
-    attestations, if present. There must be a configured `_keys` entry in the
-    config that is scoped to the registry the manifest is being fetched from.
-* `tufCache` Where to store metadata/target files when retrieving the package
-  attestation key material via TUF. Defaults to the same cache directory that
-  npm will use by default, based on platform and environment.
+  Defaults to `0o22`.
+  See "Extracted File Modes" below.
+* `fmode` Minimum permission mode for extracted files.
+  Defaults to `0o666`.
+  See "Extracted File Modes" below.
+* `dmode` Minimum permission mode for extracted directories.
+  Defaults to `0o777`.
+  See "Extracted File Modes" below.
+* `preferOnline` Prefer to revalidate cache entries, even when it would not be strictly necessary.
+  Defaults to `false`.
+* `before` When picking a manifest from a packument, only consider packages published before the specified date.
+  Defaults to `null`.
+* `defaultTag` The default `dist-tag` to use when choosing a manifest from a packument.
+  Defaults to `latest`.
+* `registry` The npm registry to use by default.
+  Defaults to `https://registry.npmjs.org/`.
+* `fullMetadata` Fetch the full metadata from the registry for packuments, including information not strictly required for installation (author, description, etc.).
+  Defaults to `true` when `before` is set, since the version publish time is part of the extended packument metadata.
+  Otherwise defaults to `false`.
+* `fullReadJson` Use the slower `read-package-json` package insted of `read-package-json-fast` in order to include extra fields like "readme" in the manifest.
+  Defaults to `false`.
+* `packumentCache` For registry packuments only, you may provide a `Map` object which will be used to cache packument requests between pacote calls.
+  This allows you to easily avoid hitting the registry multiple times (even just to validate the cache) for a given packument, since it is unlikely to change in the span of a single command.
+* `verifySignatures` A boolean that will make pacote verify the integrity signature of a manifest, if present.
+  There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
+* `verifyAttestations` A boolean that will make pacote verify Sigstore attestations, if present.
+  There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
+* `tufCache` Where to store metadata/target files when retrieving the package attestation key material via TUF.
+  Defaults to the same cache directory that npm will use by default, based on platform and environment.
+* `allowGit` Whether or not to allow data to be fetched from a git spec.
+  Possible values are `all`, `none`, or `root`.
+  Defaults to `all`.
+  `all` means git is allowed
+  `none` means git is not allowed
+  `root` means that git is only allowed if fetching from a root context.
+  Context for whether or not the package being fetched is `root` is set via the `_isRoot` option.
+* `allowRemote` Whether or not to allow data to be fetched from remote specs.
+  Possible values and defaults are the same as `allowGit`
+* `allowFile` Whether or not to allow data to be fetched from file specs.
+  Possible values and defaults are the same as `allowGit`
+* `allowDirectory` Whether or not to allow data to be fetched from directory specs.
+  Possible values and defaults are the same as `allowGit`
+* `_isRoot` Whether or not the package being fetched is in a root context.
+  Defaults to `false`,
+  For `npm` itself this means a package that is defined in the local project or workspace package.json, or a package that is being fetched for another command like `npm view`.  This informs the `allowX` options to let them know the context of the current request.
+
+For more info on spec types (i.e. git, remote) see [npm-package-arg](npm.im/npm-package-arg)
 
 ### Advanced API
 
-Each different type of fetcher is exposed for more advanced usage such as
-using helper methods from this classes:
+Each different type of fetcher is exposed for more advanced usage such as using helper methods from this classes:
 
 * `DirFetcher`
 * `FileFetcher`
@@ -196,87 +184,66 @@ Files are extracted with a mode matching the following formula:
 ( (tarball entry mode value) | (minimum mode option) ) ~ (umask)
 ```
 
-This is in order to prevent unreadable files or unlistable directories from
-cluttering a project's `node_modules` folder, even if the package tarball
-specifies that the file should be inaccessible.
+This is in order to prevent unreadable files or unlistable directories from cluttering a project's `node_modules` folder, even if the package tarball specifies that the file should be inaccessible.
 
-It also prevents files from being group- or world-writable without explicit
-opt-in by the user, because all file and directory modes are masked against
-the `umask` value.
+It also prevents files from being group- or world-writable without explicit opt-in by the user, because all file and directory modes are masked against the `umask` value.
 
-So, a file which is `0o771` in the tarball, using the default `fmode` of
-`0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:
+So, a file which is `0o771` in the tarball, using the default `fmode` of `0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:
 
 ```
 (0o771 | 0o666) => 0o777
 (0o777 ~ 0o22) => 0o755
 ```
 
-In almost every case, the defaults are appropriate.  To respect exactly
-what is in the package tarball (even if this makes an unusable system), set
-both `dmode` and `fmode` options to `0`.  Otherwise, the `umask` config
-should be used in most cases where file mode modifications are required,
-and this functions more or less the same as the `umask` value in most Unix
-systems.
+In almost every case, the defaults are appropriate.
+To respect exactly what is in the package tarball (even if this makes an unusable system), set both `dmode` and `fmode` options to `0`.
+Otherwise, the `umask` config should be used in most cases where file mode modifications are required, and this functions more or less the same as the `umask` value in most Unix systems.
 
 ## Extracted File Ownership
 
-When running as `root` on Unix systems, all extracted files and folders
-will have their owning `uid` and `gid` values set to match the ownership
-of the containing folder.
+When running as `root` on Unix systems, all extracted files and folders will have their owning `uid` and `gid` values set to match the ownership of the containing folder.
 
-This prevents `root`-owned files showing up in a project's `node_modules`
-folder when a user runs `sudo npm install`.
+This prevents `root`-owned files showing up in a project's `node_modules` folder when a user runs `sudo npm install`.
 
 ## Manifests
 
-A `manifest` is similar to a `package.json` file.  However, it has a few
-pieces of extra metadata, and sometimes lacks metadata that is inessential
-to package installation.
+A `manifest` is similar to a `package.json` file.
+However, it has a few pieces of extra metadata, and sometimes lacks metadata that is inessential to package installation.
 
 In addition to the common `package.json` fields, manifests include:
 
-* `manifest._resolved` The tarball url or file path where the package
-  artifact can be found.
+* `manifest._resolved` The tarball url or file path where the package artifact can be found.
 * `manifest._from` A normalized form of the spec passed in as an argument.
 * `manifest._integrity` The integrity value for the package artifact.
 * `manifest._id` The canonical spec of this package version: name@version.
-* `manifest.dist` Registry manifests (those included in a packument) have a
-  `dist` object.  Only `tarball` is required, though at least one of
-  `shasum` or `integrity` is almost always present.
-
-    * `tarball` The url to the associated package artifact.  (Copied by
-      Pacote to `manifest._resolved`.)
-    * `integrity` The integrity SRI string for the artifact.  This may not
-      be present for older packages on the npm registry.  (Copied by Pacote
-      to `manifest._integrity`.)
+* `manifest.dist` Registry manifests (those included in a packument) have a `dist` object.
+  Only `tarball` is required, though at least one of `shasum` or `integrity` is almost always present.
+
+    * `tarball` The url to the associated package artifact.
+      (Copied by Pacote to `manifest._resolved`.)
+    * `integrity` The integrity SRI string for the artifact.
+      This may not be present for older packages on the npm registry.
+      (Copied by Pacote to `manifest._integrity`.)
     * `shasum` Legacy integrity value.  Hexadecimal-encoded sha1 hash.
-      (Converted to an SRI string and copied by Pacote to
-      `manifest._integrity` when `dist.integrity` is not present.)
+      (Converted to an SRI string and copied by Pacote to `manifest._integrity` when `dist.integrity` is not present.)
     * `fileCount` Number of files in the tarball.
     * `unpackedSize` Size on disk of the package when unpacked.
-    * `signatures` Signatures of the shasum.  Includes the keyid that
-        correlates to a [`key from the npm
-        registry`](https://registry.npmjs.org/-/npm/v1/keys)
+    * `signatures` Signatures of the shasum.
+      Includes the keyid that correlates to a [`key from the npm registry`](https://registry.npmjs.org/-/npm/v1/keys)
 
 ## Packuments
 
-A packument is the top-level package document that lists the set of
-manifests for available versions for a package.
+A packument is the top-level package document that lists the set of manifests for available versions for a package.
 
-When a packument is fetched with `accept:
-application/vnd.npm.install-v1+json` in the HTTP headers, only the most
-minimum necessary metadata is returned.  Additional metadata is returned
-when fetched with only `accept: application/json`.
+When a packument is fetched with `accept: application/vnd.npm.install-v1+json` in the HTTP headers, only the most minimum necessary metadata is returned.
+Additional metadata is returned when fetched with only `accept: application/json`.
 
 For Pacote's purposes, the following fields are relevant:
 
-* `versions` An object where each key is a version, and each value is the
-  manifest for that version.
-* `dist-tags` An object mapping dist-tags to version numbers.  This is how
-  `foo@latest` gets turned into `foo@1.2.3`.
-* `time` In the full packument, an object mapping version numbers to
-  publication times, for the `opts.before` functionality.
+* `versions` An object where each key is a version, and each value is the manifest for that version.
+* `dist-tags` An object mapping dist-tags to version numbers.
+  This is how `foo@latest` gets turned into `foo@1.2.3`.
+* `time` In the full packument, an object mapping version numbers to publication times, for the `opts.before` functionality.
 
 Pacote adds the following field, regardless of the accept header:
 

package/lib/fetcher.js

@@ -469,14 +469,33 @@ const FileFetcher = require('./file.js')
 const DirFetcher = require('./dir.js')
 const RemoteFetcher = require('./remote.js')
 
+// possible values for allow: 'all', 'root', 'none'
+const canUse = ({ allow = 'all', isRoot = false, allowType, spec }) => {
+  if (allow === 'all') {
+    return true
+  }
+  if (allow !== 'none' && isRoot) {
+    return true
+  }
+  throw Object.assign(
+    new Error(`Fetching${allow === 'root' ? ' non-root' : ''} packages of type "${allowType}" have been disabled`),
+    {
+      code: `EALLOW${allowType.toUpperCase()}`,
+      package: spec.toString(),
+    }
+  )
+}
+
 // Get an appropriate fetcher object from a spec and options
 FetcherBase.get = (rawSpec, opts = {}) => {
   const spec = npa(rawSpec, opts.where)
   switch (spec.type) {
     case 'git':
+      canUse({ allow: opts.allowGit, isRoot: opts._isRoot, allowType: 'git', spec })
       return new GitFetcher(spec, opts)
 
     case 'remote':
+      canUse({ allow: opts.allowRemote, isRoot: opts._isRoot, allowType: 'remote', spec })
       return new RemoteFetcher(spec, opts)
 
     case 'version':
@@ -486,9 +505,11 @@ FetcherBase.get = (rawSpec, opts = {}) => {
       return new RegistryFetcher(spec.subSpec || spec, opts)
 
     case 'file':
+      canUse({ allow: opts.allowFile, isRoot: opts._isRoot, allowType: 'file', spec })
       return new FileFetcher(spec, opts)
 
     case 'directory':
+      canUse({ allow: opts.allowDirectory, isRoot: opts._isRoot, allowType: 'directory', spec })
       return new DirFetcher(spec, opts)
 
     default:

package/lib/git.js

@@ -245,7 +245,7 @@ class GitFetcher extends Fetcher {
           pkgid: `git:${nameat}${this.resolved}`,
           resolved: this.resolved,
           integrity: null, // it'll always be different, if we have one
-        }).extract(tmp).then(() => handler(tmp), er => {
+        }).extract(tmp).then(() => handler(`${tmp}${this.spec.gitSubdir || ''}`), er => {
           // fall back to ssh download if tarball fails
           if (er.constructor.name.match(/^Http/)) {
             return this.#clone(handler, false)
@@ -263,7 +263,7 @@ class GitFetcher extends Fetcher {
       if (!this.resolved) {
         await this.#addGitSha(sha)
       }
-      return handler(tmp)
+      return handler(`${tmp}${this.spec.gitSubdir || ''}`)
     })
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pacote",
-  "version": "21.0.4",
+  "version": "21.2.0",
   "description": "JavaScript package downloader",
   "author": "GitHub Inc.",
   "bin": {