@pnpm/deps.security.signatures 1101.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Rico Sta. Cruz and other contributors
+Copyright (c) 2016-2026 Zoltan Kochan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @pnpm/deps.security.signatures
+
+> Verify package signatures from npm registries
+
+[![npm version](https://img.shields.io/npm/v/@pnpm/deps.security.signatures.svg)](https://npmx.dev/package/@pnpm/deps.security.signatures)
+
+## Installation
+
+```sh
+pnpm add @pnpm/deps.security.signatures
+```
+
+## Signature Verification
+
+`verifySignatures()` verifies ECDSA registry signatures for installed package versions. It fetches public keys from each package's registry at `/-/npm/v1/keys`, fetches full package metadata, and verifies each signature over `${name}@${version}:${integrity}`.
+
+Registries that do not expose signing keys are skipped. Sigstore provenance attestations are not yet verified by this package; they are tracked as future scope.
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './verifySignatures.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from './verifySignatures.js';
+//# sourceMappingURL=index.js.map

package/lib/verifySignatures.d.ts

@@ -0,0 +1,24 @@
+import type { GetAuthHeader } from '@pnpm/fetching.types';
+import { type CreateFetchFromRegistryOptions, type RetryTimeoutOptions } from '@pnpm/network.fetch';
+export interface SignaturePackage {
+    name: string;
+    registry: string;
+    version: string;
+}
+export interface SignatureIssue extends SignaturePackage {
+    integrity?: string;
+    reason?: string;
+    resolved?: string;
+}
+export interface SignatureVerificationResult {
+    audited: number;
+    invalid: SignatureIssue[];
+    missing: SignatureIssue[];
+    verified: number;
+}
+export interface VerifySignaturesOptions extends CreateFetchFromRegistryOptions {
+    networkConcurrency?: number;
+    retry?: RetryTimeoutOptions;
+    timeout?: number;
+}
+export declare function verifySignatures(packages: SignaturePackage[], getAuthHeader: GetAuthHeader, opts: VerifySignaturesOptions): Promise<SignatureVerificationResult>;

package/lib/verifySignatures.js

@@ -0,0 +1,234 @@
+import crypto from 'node:crypto';
+import url from 'node:url';
+import util from 'node:util';
+import { PnpmError } from '@pnpm/error';
+import { createFetchFromRegistry } from '@pnpm/network.fetch';
+import pLimit from 'p-limit';
+export async function verifySignatures(packages, getAuthHeader, opts) {
+    const registries = new Set(packages.map(({ registry }) => registry));
+    const keysByRegistry = await getKeysByRegistry(registries, getAuthHeader, opts);
+    const result = {
+        audited: 0,
+        invalid: [],
+        missing: [],
+        verified: 0,
+    };
+    // Registries without signing keys are not counted as audited: there is no
+    // registry trust root to verify against.
+    const packumentCache = new Map();
+    const limit = pLimit(opts.networkConcurrency ?? 16);
+    await Promise.all(packages.map((pkg) => limit(async () => {
+        const keys = keysByRegistry.get(pkg.registry) ?? [];
+        if (keys.length === 0)
+            return;
+        let version;
+        let publishedAt;
+        try {
+            const packument = await getPackument(pkg, getAuthHeader, opts, packumentCache);
+            if (!packument)
+                return;
+            result.audited++;
+            version = packument.versions?.[pkg.version];
+            publishedAt = packument.time?.[pkg.version];
+        }
+        catch (err) {
+            result.invalid.push({ ...pkg, reason: util.types.isNativeError(err) ? err.message : String(err) });
+            return;
+        }
+        const integrity = version?.dist?.integrity;
+        const resolved = version?.dist?.tarball;
+        const rawSignatures = version?.dist?.signatures;
+        if (rawSignatures != null && !Array.isArray(rawSignatures)) {
+            result.invalid.push({ ...pkg, integrity, resolved, reason: `Malformed registry signatures metadata for ${pkg.name}@${pkg.version}` });
+            return;
+        }
+        const signatures = rawSignatures ?? [];
+        if (!signatures.every(isPackageSignature)) {
+            result.invalid.push({ ...pkg, integrity, resolved, reason: `Malformed registry signatures metadata for ${pkg.name}@${pkg.version}` });
+            return;
+        }
+        if (!version) {
+            result.invalid.push({ ...pkg, reason: `Missing registry metadata for ${pkg.name}@${pkg.version}` });
+            return;
+        }
+        if (!integrity) {
+            result.missing.push({ ...pkg, resolved });
+            return;
+        }
+        if (signatures.length === 0) {
+            result.missing.push({ ...pkg, integrity, resolved });
+            return;
+        }
+        const issue = verifyPackageSignatures({ ...pkg, integrity, publishedAt, resolved, signatures }, keys);
+        if (issue) {
+            result.invalid.push(issue);
+            return;
+        }
+        result.verified++;
+    })));
+    result.invalid.sort(sortIssue);
+    result.missing.sort(sortIssue);
+    return result;
+}
+async function getKeysByRegistry(registries, getAuthHeader, opts) {
+    const keysByRegistry = new Map();
+    await Promise.all(Array.from(registries, async (registry) => {
+        const keys = await fetchRegistryKeys(registry, getAuthHeader, opts);
+        keysByRegistry.set(registry, keys);
+    }));
+    return keysByRegistry;
+}
+async function fetchRegistryKeys(registry, getAuthHeader, opts) {
+    const registryUrl = registry.endsWith('/') ? registry : `${registry}/`;
+    const keysUrl = new url.URL('-/npm/v1/keys', registryUrl).toString();
+    const fetchFromRegistry = createFetchFromRegistry(opts);
+    const response = await fetchFromRegistry(keysUrl, {
+        authHeaderValue: getAuthHeader(registryUrl),
+        method: 'GET',
+        retry: opts.retry,
+        timeout: opts.timeout,
+    });
+    if (response.status === 404 || response.status === 400) {
+        return [];
+    }
+    if (response.status !== 200) {
+        const code = 'AUDIT_SIGNATURE_KEYS_FETCH_FAIL';
+        const message = `The registry keys endpoint (at ${response.url}) responded with ${response.status}: ${await response.text()}`;
+        throw new PnpmError(code, message);
+    }
+    const body = await parseJsonResponse(response, 'AUDIT_SIGNATURE_KEYS_FETCH_FAIL', 'The registry keys endpoint');
+    if (!isRegistryKeysResponse(body)) {
+        const code = 'AUDIT_SIGNATURE_KEYS_FETCH_FAIL';
+        const message = `The registry keys endpoint (at ${response.url}) returned an unexpected body. Expected an object with a keys array; got: ${JSON.stringify(body)?.slice(0, 500) ?? String(body)}`;
+        throw new PnpmError(code, message);
+    }
+    // npm registry signing currently uses ECDSA P-256 keys. Sigstore provenance
+    // attestations are intentionally handled separately from this registry check.
+    return body.keys.filter(({ keytype, scheme }) => keytype === 'ecdsa-sha2-nistp256' && scheme === 'ecdsa-sha2-nistp256');
+}
+async function getPackument(pkg, getAuthHeader, opts, packumentCache) {
+    const cacheKey = `${pkg.registry}:${pkg.name}`;
+    let packument = packumentCache.get(cacheKey);
+    if (!packument) {
+        // Multiple installed versions share one full packument fetch.
+        packument = fetchPackument(pkg, getAuthHeader, opts);
+        packumentCache.set(cacheKey, packument);
+    }
+    return packument;
+}
+async function fetchPackument(pkg, getAuthHeader, opts) {
+    const registryUrl = pkg.registry.endsWith('/') ? pkg.registry : `${pkg.registry}/`;
+    const packumentUrl = toUri(pkg.name, registryUrl);
+    const fetchFromRegistry = createFetchFromRegistry(opts);
+    const response = await fetchFromRegistry(packumentUrl, {
+        authHeaderValue: getAuthHeader(registryUrl),
+        fullMetadata: true,
+        method: 'GET',
+        retry: opts.retry,
+        timeout: opts.timeout,
+    });
+    if (response.status === 404) {
+        return undefined;
+    }
+    if (response.status !== 200) {
+        const code = 'AUDIT_SIGNATURE_PACKUMENT_FETCH_FAIL';
+        const message = `The packument endpoint (at ${response.url}) responded with ${response.status}: ${await response.text()}`;
+        throw new PnpmError(code, message);
+    }
+    const body = await parseJsonResponse(response, 'AUDIT_SIGNATURE_PACKUMENT_FETCH_FAIL', 'The packument endpoint');
+    if (!isPackument(body)) {
+        const code = 'AUDIT_SIGNATURE_PACKUMENT_FETCH_FAIL';
+        const message = `The packument endpoint (at ${response.url}) returned an unexpected body. Expected an object with versions; got: ${JSON.stringify(body)?.slice(0, 500) ?? String(body)}`;
+        throw new PnpmError(code, message);
+    }
+    return body;
+}
+function verifyPackageSignatures(pkg, keys) {
+    // Registry signatures cover the package identity and content integrity.
+    const message = `${pkg.name}@${pkg.version}:${pkg.integrity}`;
+    const publishedTime = pkg.publishedAt ? Date.parse(pkg.publishedAt) : undefined;
+    for (const signature of pkg.signatures) {
+        const key = keys.find(({ keyid }) => keyid === signature.keyid);
+        if (!key) {
+            const reason = `${pkg.name}@${pkg.version} has a registry signature with keyid ${signature.keyid} but no corresponding public key can be found`;
+            return toSignatureIssue(pkg, reason);
+        }
+        // Without publish time metadata we cannot safely compare against key expiry,
+        // so keep verifying with the key instead of failing closed on incomplete metadata.
+        if (key.expires && publishedTime != null && publishedTime >= Date.parse(key.expires)) {
+            const reason = `${pkg.name}@${pkg.version} has a registry signature with keyid ${signature.keyid} but the corresponding public key has expired ${key.expires}`;
+            return toSignatureIssue(pkg, reason);
+        }
+        const verifier = crypto.createVerify('SHA256');
+        verifier.write(message);
+        verifier.end();
+        const pem = `-----BEGIN PUBLIC KEY-----\n${key.key}\n-----END PUBLIC KEY-----`;
+        // crypto.verify can throw on malformed PEM key material or signature bytes
+        // returned by the registry; treat any failure as an invalid signature so
+        // one bad key doesn't crash the whole audit.
+        let verified;
+        try {
+            verified = verifier.verify(pem, signature.sig, 'base64');
+        }
+        catch {
+            verified = false;
+        }
+        if (!verified) {
+            const reason = `${pkg.name}@${pkg.version} has an invalid registry signature with keyid ${signature.keyid}`;
+            return toSignatureIssue(pkg, reason);
+        }
+    }
+    return undefined;
+}
+function toSignatureIssue(pkg, reason) {
+    return {
+        integrity: pkg.integrity,
+        name: pkg.name,
+        reason,
+        registry: pkg.registry,
+        resolved: pkg.resolved,
+        version: pkg.version,
+    };
+}
+async function parseJsonResponse(response, errorCode, endpointDescription) {
+    const rawBody = await response.text();
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch (err) {
+        const reason = util.types.isNativeError(err) ? err.message : String(err);
+        throw new PnpmError(errorCode, `${endpointDescription} (at ${response.url}) returned invalid JSON: ${reason}. Response body: ${rawBody.slice(0, 500)}`);
+    }
+}
+function toUri(pkgName, registry) {
+    let encodedName;
+    if (pkgName[0] === '@') {
+        encodedName = `@${encodeURIComponent(pkgName.slice(1))}`;
+    }
+    else {
+        encodedName = encodeURIComponent(pkgName);
+    }
+    return new url.URL(encodedName, registry.endsWith('/') ? registry : `${registry}/`).toString();
+}
+function isRegistryKeysResponse(body) {
+    return typeof body === 'object' && body != null &&
+        Array.isArray(body.keys) &&
+        body.keys.every((key) => typeof key === 'object' && key != null &&
+            typeof key.keyid === 'string' &&
+            typeof key.keytype === 'string' &&
+            typeof key.scheme === 'string' &&
+            typeof key.key === 'string' &&
+            (key.expires == null || typeof key.expires === 'string'));
+}
+function isPackument(body) {
+    return typeof body === 'object' && body != null && typeof body.versions === 'object' && body.versions != null;
+}
+function isPackageSignature(signature) {
+    return typeof signature === 'object' && signature != null &&
+        typeof signature.keyid === 'string' &&
+        typeof signature.sig === 'string';
+}
+function sortIssue(a, b) {
+    return `${a.name}@${a.version}`.localeCompare(`${b.name}@${b.version}`);
+}
+//# sourceMappingURL=verifySignatures.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pnpm/deps.security.signatures",
+  "version": "1101.1.0",
+  "description": "Verify package signatures from npm registries",
+  "keywords": [
+    "pnpm",
+    "pnpm11",
+    "audit",
+    "signatures"
+  ],
+  "license": "MIT",
+  "funding": "https://opencollective.com/pnpm",
+  "repository": "https://github.com/pnpm/pnpm/tree/main/deps/security/signatures",
+  "homepage": "https://github.com/pnpm/pnpm/tree/main/deps/security/signatures#readme",
+  "bugs": {
+    "url": "https://github.com/pnpm/pnpm/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "!*.map"
+  ],
+  "dependencies": {
+    "p-limit": "^7.1.0",
+    "@pnpm/network.fetch": "1100.0.3",
+    "@pnpm/fetching.types": "1100.0.1",
+    "@pnpm/error": "1100.0.0"
+  },
+  "peerDependencies": {
+    "@pnpm/logger": ">=1001.0.0 <1002.0.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "30.3.0",
+    "@pnpm/deps.security.signatures": "1101.1.0",
+    "@pnpm/logger": "1100.0.0",
+    "@pnpm/testing.mock-agent": "1100.0.3"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "jest": {
+    "preset": "@pnpm/jest-config"
+  },
+  "scripts": {
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "pn compile && pn .test",
+    "compile": "tsgo --build && pn lint --fix",
+    ".test": "cross-env NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules --disable-warning=ExperimentalWarning --disable-warning=DEP0169\" jest"
+  }
+}