package-url / packageurl-js Goto Github PK

https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#pub

We should validate as the spec suggests the purls of pub type,
It states:

Pub normalizes all package names to be lowercase and using underscores. The only allowed characters are [a-z0-9_].

The PURL test suite contains the PURL pkg:gem/[email protected]?Platform=java which is supposed to parse as having a qualifier platform=java, but packageurl-js parses it as Platform=java. This will cause problems if code uses packageurl-js to look for the value of a qualifier.

const purlString = new PackageURL('generic', null, ':name', '1.0.0').toString();
const purl = PackageURL.fromString(purlString);

The second line fails to parse the purl string with the error:
Error: purl is missing the required "type" component.

PackageURL.fromString("pkg:golang//github.com/ll/[email protected]") throws the below error:

purl is missing the required "type" component

After parsing the version number out of a PURL string, packageurl-js validates that the version number was encoded exactly the way that packageurl-js would have encoded it. This seems like an extra thing that packageurl-js does, undirected by the spec. Even if the spec did say to validate that the version number was percent encoded, that doesn't actually mean anything because technically any ASCII string that doesn't contain '%' is a valid percent encoded string by definition.

This is problematic because different PURL implementations encode different sets of characters. If a version number contains a character that one PURL implementation unnecessary escapes and packageurl-js does not, or vice versa, packageurl-js will correctly parse the version number and then throw an exception because the encoding validation failed. For example, packageurl-js will fail to decode this valid PURL produced by packageurl-java: pkg:t/n@1%3A2.

in the JavaScript/node ecosystem, it is common to pack/transpile/transform source code for a target system.
babel, webpack, esbuild, ... these tools are usually used for the tasks.

tools minify code by stripping comments.
a license-text-comment should not be stripped, but it should be kept.
therefore these tools do not touch block-comments that start with /*!. some tools replace these comments with a text that states in which file the original text can still be found. yet they respect the ! and keep the texts.

task: make all license-text comments be block-comments starting with an enforcer-mark !

See https://github.com/package-url/purl-spec and package-url/purl-spec#31 for the latest

Parsing npm purls such as pkg:npm/@godaddy/[email protected] throws the following error: Error: purl is missing the required "name" component.

An incorrect purl is generated when call toString() in a PackageURL object with those parameters:

    "type": "golang",
    "namespace": "github.com/cncf/xds",
    "name": "go",
    "version": "v0.0.0-20210922020428-25de7278fc84"

Instead of getting the correct purl: pkg:golang/github.com/cncf/xds/[email protected]
An encoded slash is generated in the namespace

Hi there,

...maybe this is just misunderstanding from my side, but when I create a purl object for a purl like this
pkg:oci/azure-cli@sha256:9df8ac260650dbae684ab7e47916d4def942582b491d1fe0593b22eb1cac235b?repository_url=index.docker.io%2Fbitnami%2Fazure-cli\u0026arch=amd64
it seems that the (encoded) query parameter from the query parameter repository_url is handled as separate query parameter of the purl and not of the repository_url.
The result is:

PackageURL {
      type: 'oci',
      name: 'azure-cli',
      namespace: null,
      version: 'sha256:9df8ac260650dbae684ab7e47916d4def942582b491d1fe0593b22eb1cac235b',
      qualifiers: {
        repository_url: 'index.docker.io/bitnami/azure-cli',
        arch: 'amd64'
      },
      subpath: null
    }

My expectation would have been:

PackageURL {
      type: 'oci',
      name: 'azure-cli',
      namespace: null,
      version: 'sha256:9df8ac260650dbae684ab7e47916d4def942582b491d1fe0593b22eb1cac235b',
      qualifiers: {
        repository_url: 'index.docker.io/bitnami/azure-cli&arch=amd64'
      },
      subpath: null
    }

Is my expectation wrong or is this a bug?

Currently we throw an exception when creating a packageURL with qualifiers that are strings.

The python version currently handles this, so the JS version should as well.

gh pr checkout 39

In method fromString() the version variable is used in line 147 to construct a new object,
but the variable is declared with a block scope inside an if statement (line 123).

This is an issue when using packageurl-js from typescript:
https://www.typescriptlang.org/docs/handbook/variable-declarations.html#block-scoping

As a consequence, fromString() always throws an error using typescript:

message:"version is not defined"
stack:"ReferenceError: version is not defined

in fromString(), the qualifiers are extracted using query(), which returns the querystring

https://github.com/package-url/packageurl-js/blob/master/index.js#L109

afterwards, a new instance is created, but the constructor expects the qualifiers to be a (key/value) object:

https://github.com/package-url/packageurl-js/blob/master/index.js#L42

The PURL test suite contains the PURL pkg://maven/org.apache.commons/io which is supposed to parse as a namespace of org.apache.commons and a name of io, but packageurl-js parses it as having no namespace. The namespace just disappears. It doesn't become part of the name.

There are currently no type definitions for TypeScript available.
Since TypeScript is becoming more and more popular it would be great to have them.

I dont believe versions can begin with special characters:
eg. pkg:npm/foo@! pkg:npm/foo@; `pkg:npm/foo@{ should throw an error.

currently the versioning of this library is 0.0.x.
This library is distributed via https://npmjs.org - therefore semantic versioning is enforced by all consuming dependency management systems.

The problem i see: according to semantic versioning each version of 0.0.x is identified as a breaking change.
This means: projects that require this very library usually do this via ^0.0.x - so if they depend on ^0.0.1 they are incompatible to any later version - dependency management tools will not install it because ^0.0.1 conflicts with 0.0.6 and this conflicts with 0.0.7
This means: projects that use multiple downstream libraries that require different versions of this library wlll force pnpm, yarn, npm and others package managers to fail (or install multiple different versions to be installed). This leads to a dependency mess.

See some example downstream usage:

• https://github.com/sonatype-nexus-community/js-sona-types/blob/main/package.json#L76 -- ^0.0.5
• https://github.com/EngCpp/dependency-track-node-module/blob/master/package.json#L47 -- ^0.0.1
• https://github.com/CycloneDX/cyclonedx-node-module/blob/master/package.json#L62 -- ^0.0.6
• https://github.com/CycloneDX/cyclonedx-node-npm/blob/1.0-dev/package.json#L46 -- ^0.0.7
• https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/package.json#L42 -- >=0.0.6 <0.0.8

solution: Just release a 1.x.x version.
This library will never be feature complete, because PackageURL is a living standard that is never complete. SO keeping a 0.x.x or even 0.0.x version strategy is an unnecessary obstruction.
Releasing a major version would enable you to finally use proper semantic versioning with major(breaking) , minor(feature) and patch(bugfix) sub versioning.

see also NPM's version tester, to experience the impact : https://semver.npmjs.com/

PURL - 'pkg:maven/org.apache.commons:[email protected]' passes as valid

p.PackageURL.fromString('pkg:maven/org.apache.commons:[email protected]')
PackageURL {
type: 'maven',
name: 'org.apache.commons:io',
namespace: null,
version: '1.3.4',
qualifiers: null,
subpath: null
}

However, it shouldn't be because the namespace is not percent-encoded.

Hi, I encounter this error: Invalid purl: version must be percent-encoded when parse the purl pkg:npm/@vue/[email protected] with method PackageURL.fromString().
This purl was validated successfully by other library mvn:[email protected] in the backend.

When I look into the code of packageurl-js, I see this:

if (p.includes('@')) {
    let f = p.indexOf('@'),
      u = p.substring(f + 1)
    a = decodeURIComponent(u)
    let y = encodeURIComponent(a).replace(/%3A/g, ':').replace(/%2B/g, '+')
    if (u !== y)
      throw new Error('Invalid purl: version must be percent-encoded')
    i = p.substring(0, f)
}

I think it could have an issue because method indexOf() return the first matched index, but in this case pkg:npm/@vue/[email protected], it has another @ so f+1 is not the start of version substring.

The spec is a little redundant, but here are the important things it says about qualifier keys:

• "must be composed only of ASCII letters and numbers, '.', '-' and '_' (period, dash and underscore)"
• "cannot start with a number"
• "case insensitive"

packageurl-js implements this using the expression /^[a-z]+$/i.test(key) || /[\.-_]/.test(key) (negated and simplified to make this easier to describe).

• The regular expression (?i)^[a-z]+$ matches for any string which is entirely letters. We'll call this subexpression allLetters.
• The regular expression [\.-_] matches any ASCII character value between '.' and '_', which includes '/', numbers, '=', etc but doesn't include '-'. This seems like it was meant to be [\.\-_], which matches the three characters that are called out in the spec. We'll call this corrected subexpression containsAllowedSpecial.

Substituting in those names, we get the expression allLetters || containsAllowedSpecial for determining if a qualifier key is valid. Even with the corrected regular expression, this does not match the spec. a1 is invalid because it contains a number, but it should be valid. _! is valid because it contains '_', but it should be invalid because '!' is not an allowed character.

I found this because with the incorrect regular expression, x- prefixed qualifiers are incorrectly considered to be invalid.

I've been working on some issues for cdxgen with generating Gradle purls for projects. My issue is that Gradle prefixes project names with a ':', which should imho not be an issue if the name would actually be percent-encoded. I noticed during testing however, that this is not the case.

Checking your code, you do actually use encodeURIComponent, but then explicitly turn '%3A' back into ':'. When I then feed the generated purl into your fromString-method to validate it, it fails, because of the ':' in the purl:

Now, for a top-level project in Gradle, I could remove the ':', but then the question becomes how to handle sub-projects. These have the ':' not just at the front, but inbetween the layered projects as well (eg. :a:b:c:d). Currently, cdxgen removes the initial ':' and changes the remaining ':' to a '/', which unfortunately with the way your code works, makes all parts before the last '/' part of the namespace! This could then generate a purl that identifies multiple projects, eg:

• Namespace 'a/b/c', name 'd' --> purl: 'a/b/c/d'
• Namespace 'a/b', name ':c:d' --> purl 'a/b/c/d'

I would expect when using a name like :a:b, to get a purl looking more or less like pkg:maven/namespace/%3Aa%3Ab@version.

In case the current behavior is not an error, but actually expected, I think there is need for a discussion about how to make purls for Gradle (in case there hasn't already been one).

Also, in case this is an error, there's more places in your code where specific characters are explicitly decoded -- maybe worth taking a look at those as well...

This is needed for proper releases on Github and on npm.

It's currently possible to create an 'invalid' Maven purl because it doesn't validate the namespace.

This functionality is included in the Java package, so presumably we want parity with other implementations.
https://github.com/package-url/packageurl-java/blob/bd3241aaa27ea297766a0a99e48b48ca17465956/src/main/java/com/github/packageurl/PackageURL.java#L561-L567

Hello.

We have used the library and it works good for us in most of cases.

But we noticed the following issue: according to the pURL specification, for PyPi packages all underscores "_" must be replaced with dashes "-" in the name. However, it seems as if only the first occurrence is replaced using "someString.replace(...)".

Can you please have a look at this?
(There are also other usages of replace function.)

Thank you very much,
Pavel

Any of the following purls will fail in the latest version
pkg:pypi/[email protected]+cpu
pkg:deb/debian/[email protected]+deb9u1?arch=amd64&upstream=gettext&distro=debian-9
pkg:deb/debian/libprocps3@2:3.3.9-9+deb8u1?arch=amd64&upstream=procps&distro=debian-8
pkg:deb/debian/[email protected]+deb10u3?arch=amd64&upstream=openssl&distro=debian-10

any purl that has a plus sign will fail with the error:
Invalid purl: version must be percent-encoded

The PURL test suite contains a PURL pkg:PYPI/[email protected]. packageurl-js parses this as type PYPI instead of the expected pypi.

This causes two problems:

1. Code that is looking for pypi PURLs won't see them.
2. The pypi-specific name normalization rules that packageurl-js implements for pypi are not applied, so the package name comes out as Django_package instead of the expected django-package.

Because qualifiers will not accept undefined or null, the code used to add qualifiers will always be trigged, adding a ? to the of all purls.

The d.ts file likely just needs updated with | undefined or akin for qualifiers.

The readme document does not yet show any usage examples to help developers use this.

I've created a pull request which I hope will help with this #24.

Let me know if this works for you all.

Thx Much :-)