@pnpm/crypto.shasums-file 1100.1.5 → 1100.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @pnpm/crypto.shasums-file
 
+## 1100.2.0
+
+### Minor Changes
+
+- Resolving a Node.js runtime version (`devEngines.runtime` / `runtime:` specifiers) is now much faster: the per-version release metadata is cached in the pnpm cache directory after its signature is verified, and an exact stable version such as `runtime:22.23.2` no longer downloads the Node.js release index. A pinned runtime whose metadata was fetched once resolves without any network access, which removes the noticeable delay on the first `node` invocation in a project pinning an already-downloaded runtime [#13899](https://github.com/pnpm/pnpm/issues/13899).
+
+### Patch Changes
+
+- Updated dependencies:
+  - @pnpm/error@1100.1.2
+
 ## 1100.1.5
 
 ### Patch Changes

package/lib/diskCache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * On-disk cache for per-version runtime `SHASUMS256.txt` bodies.
+ *
+ * A release's SHASUMS file lives under a version-pinned URL
+ * (`.../v22.0.0/SHASUMS256.txt`), so its content is immutable: a body fetched
+ * once — and, for signed channels, verified once — never needs to be fetched
+ * again. Entries live under
+ * `<cacheDir>/v11/runtime-shasums/<trust>/<host>/<url path>` so clearing the
+ * cache directory clears them together with the registry metadata mirror. The
+ * layout is shared with pacquet, which reads and writes the same files.
+ *
+ * Only hand immutable URLs to this cache. The cache directory is
+ * *project-configurable* (`cacheDir`), so entries under it must never carry
+ * more authority than the project that could have written them:
+ *
+ * - Signed-channel readers persist the detached signature next to the body
+ *   and re-verify it against the embedded release keys on every read (see
+ *   `fetchVerifiedNodeShasumsFileCached`), so a pre-seeded entry is only
+ *   accepted if it is a genuine release body.
+ * - Unverified entries are trusted on read, which grants a project nothing
+ *   new: the unsigned channels' mirrors are already project-configurable
+ *   (their bodies were project-controllable before the cache existed), and
+ *   the musl list's download URLs are derived from the hardcoded
+ *   unofficial-builds base, never from the cached body.
+ *
+ * The `<trust>` path segment keeps the two classes in disjoint subtrees so
+ * their read policies cannot be confused.
+ */
+export declare const RUNTIME_SHASUMS_DIR = "v11/runtime-shasums";
+/**
+ * How the body of a cache entry was authenticated before it was written.
+ * Each class caches into its own subtree.
+ */
+export type ShasumsTrust = 'verified' | 'unverified';
+export interface ShasumsCacheOpts {
+    cacheDir?: string;
+    trust: ShasumsTrust;
+}
+/**
+ * The cached body for `url` as UTF-8 text, via {@link readCachedBytes}.
+ * Invalid UTF-8 is a miss — a lossy decode would turn a corrupted entry
+ * into malformed rows instead of a refetch.
+ */
+export declare function readCachedShasums(url: string, opts: ShasumsCacheOpts): Promise<string | undefined>;
+/**
+ * The cached bytes for `url`, or `undefined` on any miss — a URL the mapping
+ * cannot represent, a missing or non-regular file, unreadable content, an
+ * empty file (never a valid entry, so it only signals a torn write), or a
+ * file over {@link MAX_CACHED_SHASUMS_LEN}.
+ */
+export declare function readCachedBytes(url: string, opts: ShasumsCacheOpts): Promise<Buffer | undefined>;
+/**
+ * Best-effort write of `body` for `url`: a cache-write failure only costs a
+ * refetch on the next resolve, so errors are deliberately dropped rather than
+ * failing the resolution that produced the body. The exclusively-created temp
+ * file + rename keeps concurrent writers (two installs resolving the same
+ * version) from exposing a torn body.
+ */
+export declare function writeCachedShasums(url: string, body: string | Uint8Array, opts: ShasumsCacheOpts): Promise<void>;

package/lib/diskCache.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { threadId } from 'node:worker_threads';
+/**
+ * On-disk cache for per-version runtime `SHASUMS256.txt` bodies.
+ *
+ * A release's SHASUMS file lives under a version-pinned URL
+ * (`.../v22.0.0/SHASUMS256.txt`), so its content is immutable: a body fetched
+ * once — and, for signed channels, verified once — never needs to be fetched
+ * again. Entries live under
+ * `<cacheDir>/v11/runtime-shasums/<trust>/<host>/<url path>` so clearing the
+ * cache directory clears them together with the registry metadata mirror. The
+ * layout is shared with pacquet, which reads and writes the same files.
+ *
+ * Only hand immutable URLs to this cache. The cache directory is
+ * *project-configurable* (`cacheDir`), so entries under it must never carry
+ * more authority than the project that could have written them:
+ *
+ * - Signed-channel readers persist the detached signature next to the body
+ *   and re-verify it against the embedded release keys on every read (see
+ *   `fetchVerifiedNodeShasumsFileCached`), so a pre-seeded entry is only
+ *   accepted if it is a genuine release body.
+ * - Unverified entries are trusted on read, which grants a project nothing
+ *   new: the unsigned channels' mirrors are already project-configurable
+ *   (their bodies were project-controllable before the cache existed), and
+ *   the musl list's download URLs are derived from the hardcoded
+ *   unofficial-builds base, never from the cached body.
+ *
+ * The `<trust>` path segment keeps the two classes in disjoint subtrees so
+ * their read policies cannot be confused.
+ */
+export const RUNTIME_SHASUMS_DIR = 'v11/runtime-shasums';
+/**
+ * Upper bound on a cache entry's size. Real SHASUMS bodies are a few
+ * kilobytes; anything past this bound is not a release asset list and is
+ * never read into memory or written.
+ */
+const MAX_CACHED_SHASUMS_LEN = 1024 * 1024;
+/**
+ * The cached body for `url` as UTF-8 text, via {@link readCachedBytes}.
+ * Invalid UTF-8 is a miss — a lossy decode would turn a corrupted entry
+ * into malformed rows instead of a refetch.
+ */
+export async function readCachedShasums(url, opts) {
+    const bytes = await readCachedBytes(url, opts);
+    if (bytes == null)
+        return undefined;
+    try {
+        return strictUtf8Decoder.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+const strictUtf8Decoder = new TextDecoder('utf8', { fatal: true });
+/**
+ * The cached bytes for `url`, or `undefined` on any miss — a URL the mapping
+ * cannot represent, a missing or non-regular file, unreadable content, an
+ * empty file (never a valid entry, so it only signals a torn write), or a
+ * file over {@link MAX_CACHED_SHASUMS_LEN}.
+ */
+export async function readCachedBytes(url, opts) {
+    if (opts.cacheDir == null)
+        return undefined;
+    const filePath = shasumsCachePath(opts.cacheDir, opts.trust, url);
+    if (filePath == null)
+        return undefined;
+    try {
+        // A FIFO planted at the entry path would block a plain open until a
+        // writer appears; O_NONBLOCK (a no-op for regular files, absent on
+        // Windows, whose directory entries cannot be named pipes) makes the open
+        // return immediately.
+        const file = await fs.promises.open(filePath, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+        try {
+            // Checked on the opened handle, so nothing can swap the regular file
+            // for a special one between check and read.
+            if (!(await file.stat()).isFile())
+                return undefined;
+            // A bounded read rather than a stat check keeps the cap race-free: at
+            // most one byte past the bound is ever read, whatever the file's size
+            // becomes between open and read.
+            const buffer = Buffer.allocUnsafe(MAX_CACHED_SHASUMS_LEN + 1);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+            if (bytesRead === 0 || bytesRead > MAX_CACHED_SHASUMS_LEN)
+                return undefined;
+            return buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Best-effort write of `body` for `url`: a cache-write failure only costs a
+ * refetch on the next resolve, so errors are deliberately dropped rather than
+ * failing the resolution that produced the body. The exclusively-created temp
+ * file + rename keeps concurrent writers (two installs resolving the same
+ * version) from exposing a torn body.
+ */
+export async function writeCachedShasums(url, body, opts) {
+    if (opts.cacheDir == null)
+        return;
+    if (Buffer.byteLength(body) > MAX_CACHED_SHASUMS_LEN)
+        return;
+    const filePath = shasumsCachePath(opts.cacheDir, opts.trust, url);
+    if (filePath == null)
+        return;
+    // The process id alone does not make the temp name unique (worker threads
+    // share it), so the thread id and a counter join it. The `wx` flag refuses
+    // to open a path that already exists — a colliding writer or a pre-seeded
+    // symlink fails the open instead of being followed — and any failure just
+    // skips the write.
+    const tempPath = `${filePath}.tmp-${process.pid.toString()}-${threadId.toString()}-${(tempCounter++).toString()}`;
+    try {
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        // Sync before the rename so a crash cannot persist the renamed name
+        // pointing at partially-written content — a torn SHASUMS prefix still
+        // parses and would otherwise be served (missing platform rows) until the
+        // cache is cleared.
+        const tempFile = await fs.promises.open(tempPath, 'wx');
+        try {
+            await tempFile.writeFile(body);
+            await tempFile.sync();
+        }
+        finally {
+            await tempFile.close();
+        }
+        await fs.promises.rename(tempPath, filePath);
+    }
+    catch {
+        try {
+            await fs.promises.rm(tempPath, { force: true });
+        }
+        catch { }
+    }
+}
+let tempCounter = 0;
+/**
+ * The cache file backing `url`, or `undefined` when the URL has a shape the
+ * path mapping does not cover (non-HTTP scheme, embedded credentials, query
+ * string, empty or dot-only path segments). Returning `undefined` just
+ * disables caching for that URL.
+ */
+function shasumsCachePath(cacheDir, trust, url) {
+    let rest;
+    if (url.startsWith('https://')) {
+        rest = url.substring('https://'.length);
+    }
+    else if (url.startsWith('http://')) {
+        rest = url.substring('http://'.length);
+    }
+    else {
+        return undefined;
+    }
+    if (/[?#@]/.test(rest))
+        return undefined;
+    const firstSlash = rest.indexOf('/');
+    if (firstSlash <= 0)
+        return undefined;
+    // `:` (a port separator) is not portable in file names; `+` is the same
+    // encoding the registry metadata mirror uses for it.
+    const host = rest.substring(0, firstSlash).toLowerCase().replaceAll(':', '+');
+    const parts = [encodePathSegment(host)];
+    for (const segment of rest.substring(firstSlash + 1).split('/')) {
+        if (!segment || segment === '.' || segment === '..')
+            return undefined;
+        parts.push(encodePathSegment(segment));
+    }
+    if (parts.some((part) => part == null))
+        return undefined;
+    return path.join(cacheDir, RUNTIME_SHASUMS_DIR, trust, ...parts);
+}
+/**
+ * Percent-encode the bytes of `segment` that are not portable across
+ * filesystems, keeping `[A-Za-z0-9._+-]` as-is. pacquet applies the same
+ * encoding, so both tools address one file.
+ */
+function encodePathSegment(segment) {
+    if (segment.length > 200)
+        return undefined;
+    let encoded = '';
+    for (const byte of Buffer.from(segment)) {
+        const char = String.fromCharCode(byte);
+        if (/[\w.+-]/.test(char)) {
+            encoded += char;
+        }
+        else {
+            encoded += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+        }
+    }
+    return encoded;
+}
+//# sourceMappingURL=diskCache.js.map

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { FetchFromRegistry } from '@pnpm/fetching.types';
-import { fetchVerifiedNodeShasums } from './verifyNodeShasums.js';
-export { fetchVerifiedNodeShasums };
+import { RUNTIME_SHASUMS_DIR } from './diskCache.js';
+import { type ArmoredKey, fetchVerifiedNodeShasums } from './verifyNodeShasums.js';
+export { fetchVerifiedNodeShasums, RUNTIME_SHASUMS_DIR };
 export interface ShasumsFileItem {
     integrity: string;
     fileName: string;
@@ -13,6 +14,31 @@ export declare function fetchShasumsFile(fetch: FetchFromRegistry, shasumsUrl: s
  * fetched from a repository-configurable Node.js mirror.
  */
 export declare function fetchVerifiedNodeShasumsFile(fetch: FetchFromRegistry, shasumsUrl: string): Promise<ShasumsFileItem[]>;
+export interface FetchShasumsFileCachedOpts {
+    cacheDir?: string;
+}
+export interface FetchVerifiedNodeShasumsFileCachedOpts extends FetchShasumsFileCachedOpts {
+    trustedKeys?: readonly ArmoredKey[];
+}
+/**
+ * Like {@link fetchVerifiedNodeShasumsFile}, backed by the disk cache when
+ * `opts.cacheDir` is given. The cache stores the body together with its
+ * detached signature, and a cache hit re-verifies that signature against the
+ * embedded release keys: the cache directory is project-configurable, so a
+ * pre-seeded entry must prove it is a genuine release body before it is
+ * served. Any verification failure is a miss and the pair is refetched.
+ * `shasumsUrl` must be version-pinned — a mutable URL must never be handed to
+ * the cache.
+ */
+export declare function fetchVerifiedNodeShasumsFileCached(fetch: FetchFromRegistry, shasumsUrl: string, opts?: FetchVerifiedNodeShasumsFileCachedOpts): Promise<ShasumsFileItem[]>;
+/**
+ * Like {@link fetchShasumsFile}, backed by the disk cache when `opts.cacheDir`
+ * is given. For mirrors whose SHASUMS files carry no verifiable signature the
+ * cached body is trusted exactly as far as the TLS fetch that produced it.
+ * `shasumsUrl` must be version-pinned — a mutable URL must never be handed to
+ * the cache.
+ */
+export declare function fetchShasumsFileCached(fetch: FetchFromRegistry, shasumsUrl: string, opts?: FetchShasumsFileCachedOpts): Promise<ShasumsFileItem[]>;
 export declare function parseShasumsFile(shasumsFileContent: string): ShasumsFileItem[];
 export declare function fetchShasumsFileRaw(fetch: FetchFromRegistry, shasumsUrl: string): Promise<string>;
 export declare function pickFileChecksumFromShasumsFile(body: string, fileName: string): string;

package/lib/index.js

@@ -1,6 +1,7 @@
 import { PnpmError } from '@pnpm/error';
-import { fetchVerifiedNodeShasums } from './verifyNodeShasums.js';
-export { fetchVerifiedNodeShasums };
+import { readCachedBytes, readCachedShasums, RUNTIME_SHASUMS_DIR, writeCachedShasums } from './diskCache.js';
+import { fetchVerifiedNodeShasums, fetchVerifiedNodeShasumsWithSignature, nodeShasumsSignatureVerifies, } from './verifyNodeShasums.js';
+export { fetchVerifiedNodeShasums, RUNTIME_SHASUMS_DIR };
 export async function fetchShasumsFile(fetch, shasumsUrl) {
     return parseShasumsFile(await fetchShasumsFileRaw(fetch, shasumsUrl));
 }
@@ -13,6 +14,50 @@ export async function fetchShasumsFile(fetch, shasumsUrl) {
 export async function fetchVerifiedNodeShasumsFile(fetch, shasumsUrl) {
     return parseShasumsFile(await fetchVerifiedNodeShasums(fetch, shasumsUrl));
 }
+/**
+ * Like {@link fetchVerifiedNodeShasumsFile}, backed by the disk cache when
+ * `opts.cacheDir` is given. The cache stores the body together with its
+ * detached signature, and a cache hit re-verifies that signature against the
+ * embedded release keys: the cache directory is project-configurable, so a
+ * pre-seeded entry must prove it is a genuine release body before it is
+ * served. Any verification failure is a miss and the pair is refetched.
+ * `shasumsUrl` must be version-pinned — a mutable URL must never be handed to
+ * the cache.
+ */
+export async function fetchVerifiedNodeShasumsFileCached(fetch, shasumsUrl, opts) {
+    const cacheOpts = { cacheDir: opts?.cacheDir, trust: 'verified' };
+    const signatureUrl = `${shasumsUrl}.sig`;
+    const [cachedBody, cachedSignature] = await Promise.all([
+        readCachedShasums(shasumsUrl, cacheOpts),
+        readCachedBytes(signatureUrl, cacheOpts),
+    ]);
+    if (cachedBody != null && cachedSignature != null &&
+        await nodeShasumsSignatureVerifies(Buffer.from(cachedBody, 'utf8'), cachedSignature, opts?.trustedKeys)) {
+        return parseShasumsFile(cachedBody);
+    }
+    const { body, signature } = await fetchVerifiedNodeShasumsWithSignature(fetch, shasumsUrl, opts?.trustedKeys);
+    await Promise.all([
+        writeCachedShasums(shasumsUrl, body, cacheOpts),
+        writeCachedShasums(signatureUrl, signature, cacheOpts),
+    ]);
+    return parseShasumsFile(body);
+}
+/**
+ * Like {@link fetchShasumsFile}, backed by the disk cache when `opts.cacheDir`
+ * is given. For mirrors whose SHASUMS files carry no verifiable signature the
+ * cached body is trusted exactly as far as the TLS fetch that produced it.
+ * `shasumsUrl` must be version-pinned — a mutable URL must never be handed to
+ * the cache.
+ */
+export async function fetchShasumsFileCached(fetch, shasumsUrl, opts) {
+    const cacheOpts = { cacheDir: opts?.cacheDir, trust: 'unverified' };
+    const cached = await readCachedShasums(shasumsUrl, cacheOpts);
+    if (cached != null)
+        return parseShasumsFile(cached);
+    const body = await fetchShasumsFileRaw(fetch, shasumsUrl);
+    await writeCachedShasums(shasumsUrl, body, cacheOpts);
+    return parseShasumsFile(body);
+}
 export function parseShasumsFile(shasumsFileContent) {
     const lines = shasumsFileContent.split('\n');
     const items = [];

package/lib/verifyNodeShasums.d.ts

@@ -22,3 +22,19 @@ export interface ArmoredKey {
  * Throws when the signature is missing or does not verify against a trusted key.
  */
 export declare function fetchVerifiedNodeShasums(fetch: FetchFromRegistry, shasumsUrl: string, trustedKeys?: readonly ArmoredKey[]): Promise<string>;
+/**
+ * {@link fetchVerifiedNodeShasums}, additionally returning the verified
+ * detached signature so the disk cache can persist it as the entry's
+ * verification evidence.
+ */
+export declare function fetchVerifiedNodeShasumsWithSignature(fetch: FetchFromRegistry, shasumsUrl: string, trustedKeys?: readonly ArmoredKey[]): Promise<{
+    body: string;
+    signature: Uint8Array;
+}>;
+/**
+ * Whether `signatureBytes` is a valid detached signature of `content` under
+ * the trusted keys, reporting any unreadable input as `false` rather than
+ * throwing. This is the read-side check for persisted cache evidence, where
+ * any failure just means a cache miss.
+ */
+export declare function nodeShasumsSignatureVerifies(content: Uint8Array, signatureBytes: Uint8Array, trustedKeys?: readonly ArmoredKey[]): Promise<boolean>;

package/lib/verifyNodeShasums.js

@@ -34,6 +34,15 @@ async function readSigningKeyPackets(trustedKeys) {
  * Throws when the signature is missing or does not verify against a trusted key.
  */
 export async function fetchVerifiedNodeShasums(fetch, shasumsUrl, trustedKeys = NODE_RELEASE_KEYS) {
+    const { body } = await fetchVerifiedNodeShasumsWithSignature(fetch, shasumsUrl, trustedKeys);
+    return body;
+}
+/**
+ * {@link fetchVerifiedNodeShasums}, additionally returning the verified
+ * detached signature so the disk cache can persist it as the entry's
+ * verification evidence.
+ */
+export async function fetchVerifiedNodeShasumsWithSignature(fetch, shasumsUrl, trustedKeys = NODE_RELEASE_KEYS) {
     const [shasumsBytes, signatureBytes] = await Promise.all([
         fetchBytes(fetch, shasumsUrl, 'SHASUMS256.txt'),
         fetchBytes(fetch, `${shasumsUrl}.sig`, 'SHASUMS256.txt.sig'),
@@ -42,7 +51,21 @@ export async function fetchVerifiedNodeShasums(fetch, shasumsUrl, trustedKeys =
         throw new PnpmError('NODE_SHASUMS_SIGNATURE_INVALID', `The OpenPGP signature of ${shasumsUrl} does not match any trusted Node.js release key. ` +
             'The downloaded Node.js runtime cannot be verified as a genuine release.');
     }
-    return Buffer.from(shasumsBytes).toString('utf8');
+    return { body: Buffer.from(shasumsBytes).toString('utf8'), signature: signatureBytes };
+}
+/**
+ * Whether `signatureBytes` is a valid detached signature of `content` under
+ * the trusted keys, reporting any unreadable input as `false` rather than
+ * throwing. This is the read-side check for persisted cache evidence, where
+ * any failure just means a cache miss.
+ */
+export async function nodeShasumsSignatureVerifies(content, signatureBytes, trustedKeys = NODE_RELEASE_KEYS) {
+    try {
+        return await isSignedByTrustedKey(content, signatureBytes, trustedKeys);
+    }
+    catch {
+        return false;
+    }
 }
 async function isSignedByTrustedKey(content, signatureBytes, trustedKeys) {
     let signature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/crypto.shasums-file",
-  "version": "1100.1.5",
+  "version": "1100.2.0",
   "description": "Utils for working with shasums files",
   "keywords": [
     "pnpm",
@@ -30,14 +30,14 @@
   ],
   "dependencies": {
     "@pnpm/crypto.hash": "1100.0.2",
-    "@pnpm/error": "1100.1.1",
+    "@pnpm/error": "1100.1.2",
     "@pnpm/fetching.types": "1100.0.3",
     "openpgp": "^6.3.1"
   },
   "devDependencies": {
     "@jest/globals": "30.4.1",
     "@openpgp/web-stream-tools": "0.3.1",
-    "@pnpm/crypto.shasums-file": "1100.1.5"
+    "@pnpm/crypto.shasums-file": "1100.2.0"
   },
   "engines": {
     "node": ">=22.13"