@vltpkg/package-info 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -67,6 +67,12 @@ export type PackageInfoClientOptions = RegistryClientOptions & SpecOptions & {
      * tarball, anything else goes through the global store first.
      */
     'store-linker'?: StoreLinker;
+    /**
+     * Resolve to the registry's Brotli (`.tar.br`) tarball when it
+     * advertises one in `dist.alternates`. Defaults to true; set false to
+     * always resolve to the gzip `.tgz`.
+     */
+    'brotli-tarballs'?: boolean;
 };
 export type PackageInfoClientRequestOptions = PickManifestOptions & RegistryClientRequestOptions & {
     /** dir to resolve `file://` specifiers against. Defaults to projectRoot. */
@@ -84,8 +90,8 @@ export type PackageInfoClientExtractOptions = PackageInfoClientRequestOptions &
     /**
      * When true, indicates that integrity + resolved came from a
      * lockfile (i.e. they were already verified on first install).
-     * Skips the client-side tarball integrity check.
-     * Defaults to false — fresh installs always verify integrity.
+     * Skips re-hashing a refetched body of an already verified url.
+     * Other network bodies are always checked.
      */
     fromLockfile?: boolean;
     /**

package/dist/index.js

@@ -8,7 +8,7 @@ import { pickManifest } from '@vltpkg/pick-manifest';
 import { registryErrorMessage, tokenRefusalAdvice, } from '@vltpkg/registry-client/registry-error';
 import { storeRoot } from '@vltpkg/registry-client/store-root';
 import { Spec } from '@vltpkg/spec';
-import { asPackument, integrityHex } from '@vltpkg/types';
+import { asPackument, brotliTarballUrl, integrityHex, tarballFormat, } from '@vltpkg/types';
 import ssri from 'ssri';
 import { Monorepo } from '@vltpkg/workspaces';
 import { XDG } from '@vltpkg/xdg';
@@ -178,6 +178,18 @@ export class PackageInfoClient {
         });
         return this.#tarPoolPromise;
     }
+    /**
+     * The absolute URL of a version's Brotli (`.tar.br`) tarball, or
+     * undefined when the registry advertised none, advertised one this
+     * client does not use (see {@link brotliTarballUrl}), or
+     * `--no-brotli-tarballs` is set. `dist.tarball` is already absolute
+     * here -- see `absolutizeTarballs`.
+     */
+    #brotliTarball(tarball, alternates) {
+        if (this.options['brotli-tarballs'] === false)
+            return undefined;
+        return brotliTarballUrl(tarball, alternates);
+    }
     constructor(options = {}) {
         this.options = options;
         this.#projectRoot = options.projectRoot || process.cwd();
@@ -210,10 +222,19 @@ export class PackageInfoClient {
         const { from = this.#projectRoot, integrity, resolved, fromLockfile = false, installScripts = false, } = options;
         const f = spec.final;
         // If the caller already provides both integrity and resolved
-        // (from lockfile or prior resolution), skip re-resolving.
-        const alreadyResolved = !!(integrity && resolved);
-        const r = alreadyResolved ?
-            { resolved, integrity, spec }
+        // (from lockfile or prior resolution), skip re-resolving. A
+        // `.tar.br` needs only the URL: its hash is not knowable before the
+        // download, so the graph can never hand one over, and `Repr-Digest`
+        // is what pins it -- `required`, so a registry that serves the
+        // alternate unlabelled is rejected rather than trusted.
+        const brotli = !!resolved && tarballFormat(resolved) === 'brotli';
+        const r = resolved && (integrity || brotli) ?
+            {
+                resolved,
+                integrity,
+                spec,
+                ...(brotli && !integrity ? { digestRequired: true } : {}),
+            }
             : await this.resolve(spec, options);
         switch (f.type) {
             case 'git': {
@@ -244,6 +265,9 @@ export class PackageInfoClient {
             }
             case 'registry': {
                 const pool = await this.getTarPool();
+                // brotli bytes carry no signature of their own, so every unpack
+                // below has to be told; gzip and raw tar are sniffed.
+                const format = tarballFormat(r.resolved);
                 // git tarballs keep the unpack path
                 const hex = f.type === 'registry' && this.#storeLinker !== 'unpack' ?
                     integrityHex(r.integrity)
@@ -281,12 +305,14 @@ export class PackageInfoClient {
                 });
                 if (cached) {
                     try {
-                        await pool.unpack(cached.body, target);
+                        await pool.unpack(cached.body, target, format);
                         logRequest(r.resolved, 'cache');
                         r.integrity ??= cached.integrity;
                         // a warm install writes nothing to the cache, so queue the
                         // store miss here or an existing cache never converges,
-                        // and a gzipped body with no store link, to unzip it
+                        // and a gzipped body with no store link, to unzip it.
+                        // (a brotli body is never rewritten: cache-unzip only
+                        // un-gzips, and leaving it compressed keeps the cache small.)
                         if (hex || cached.gzip) {
                             rc.queueForStore(cached.key, r.integrity);
                         }
@@ -316,24 +342,21 @@ export class PackageInfoClient {
                             response,
                         });
                     }
+                    // checkIntegrity() hashes the body unless its url is trusted
+                    const verified = !trustIntegrity &&
+                        response.checkIntegrity({ spec, url: resolved });
                     // if it's not trusted already, but valid, start trusting
-                    if (!trustIntegrity &&
-                        response.checkIntegrity({ spec, url: resolved })) {
+                    if (verified) {
                         this.#trustedIntegrities.set(r.resolved, response.integrity);
                     }
                     const buf = response.buffer();
                     if (r.integrity) {
-                        // Verify network-delivered tarball bytes against dist.integrity.
-                        // Skip cache-served bodies: they were verified on the fetch that
-                        // populated the cache, and cache-unzip rewrites them un-gzipped
-                        // so the gzip-hash can never match. Skip lockfile-sourced
-                        // integrity: it was verified on first install.
-                        if (!fromLockfile && !response.fromCache) {
+                        // hash only network bytes checkIntegrity() skipped (trusted
+                        // url). cache bodies were verified when cached.
+                        if (!verified && !fromLockfile && !response.fromCache) {
                             const hash = createHash('sha512');
                             hash.update(buf);
                             const computed = `sha512-${hash.digest('base64')}`;
-                            /* c8 ignore start - defense-in-depth: registry client's
-                             * checkIntegrity() usually catches mismatches first. */
                             if (computed !== r.integrity) {
                                 throw error('Tarball integrity check failed', {
                                     code: 'EINTEGRITY',
@@ -343,7 +366,6 @@ export class PackageInfoClient {
                                     found: computed,
                                 });
                             }
-                            /* c8 ignore stop */
                         }
                     }
                     else if (response.fromCache) {
@@ -379,7 +401,7 @@ export class PackageInfoClient {
                     }
                 }
                 try {
-                    await (await this.getTarPool()).unpack(buf, target);
+                    await pool.unpack(buf, target, format);
                 }
                 catch (er) {
                     throw this.#resolveError(spec, options, 'tar unpack failed', { cause: er });
@@ -568,19 +590,19 @@ export class PackageInfoClient {
                             `version may have been unpublished, or the registry may ` +
                             `be misconfigured or unreachable.`, { response, url: tarball });
                     }
+                    const verified = !trustIntegrity &&
+                        response.checkIntegrity({ spec, url: tarball });
                     // if we don't already trust it, but it's valid, start
                     // trusting it
-                    if (!trustIntegrity &&
-                        response.checkIntegrity({ spec, url: tarball })) {
+                    if (verified) {
                         this.#trustedIntegrities.set(tarball, response.integrity);
                     }
                     const buf = response.buffer();
-                    // Same as extract(): only hash network-delivered bodies.
-                    if (integrity && !response.fromCache) {
+                    // Same as extract()
+                    if (integrity && !verified && !response.fromCache) {
                         const hash = createHash('sha512');
                         hash.update(buf);
                         const computed = `sha512-${hash.digest('base64')}`;
-                        /* c8 ignore start - defense-in-depth (see extract) */
                         if (computed !== integrity) {
                             throw error('Tarball integrity check failed', {
                                 code: 'EINTEGRITY',
@@ -590,7 +612,6 @@ export class PackageInfoClient {
                                 found: computed,
                             });
                         }
-                        /* c8 ignore stop */
                     }
                     return buf;
                 };
@@ -977,15 +998,19 @@ export class PackageInfoClient {
             case 'registry': {
                 const mani = await this.manifest(spec, options);
                 if (mani.dist) {
-                    const { integrity, tarball, signatures } = mani.dist;
+                    const { integrity, tarball, signatures, alternates } = mani.dist;
                     if (tarball) {
-                        const r = {
-                            resolved: tarball,
-                            integrity,
-                            signatures,
-                            spec,
-                        };
-                        if (!integrity &&
+                        // A `.tar.br` is a distinct artifact, not a re-encoding of the
+                        // `.tgz`: it hashes differently, so `dist.integrity` and the
+                        // signatures over it describe the wrong bytes and are dropped.
+                        // What pins it instead is its own `Repr-Digest`, which the
+                        // registry that advertised it always sends -- hence `required`.
+                        const brotli = this.#brotliTarball(tarball, alternates);
+                        const r = brotli ?
+                            { resolved: brotli, spec, digestRequired: true }
+                            : { resolved: tarball, integrity, signatures, spec };
+                        if (!brotli &&
+                            !integrity &&
                             this.#vltPackuments.has(`${f.registry}${f.name}`)) {
                             r.digestRequired = true;
                         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/package-info",
   "description": "Resolve and fetch package metadata and tarballs",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -13,17 +13,17 @@
     "url": "http://vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.2.0",
-    "@vltpkg/git": "1.2.0",
-    "@vltpkg/output": "1.2.0",
-    "@vltpkg/package-json": "1.2.0",
-    "@vltpkg/pick-manifest": "1.2.0",
-    "@vltpkg/registry-client": "1.2.0",
-    "@vltpkg/spec": "1.2.0",
-    "@vltpkg/tar": "1.2.0",
-    "@vltpkg/types": "1.2.0",
-    "@vltpkg/workspaces": "1.2.0",
-    "@vltpkg/xdg": "1.2.0",
+    "@vltpkg/error-cause": "1.3.0",
+    "@vltpkg/git": "1.3.0",
+    "@vltpkg/output": "1.3.0",
+    "@vltpkg/package-json": "1.3.0",
+    "@vltpkg/pick-manifest": "1.3.0",
+    "@vltpkg/registry-client": "1.3.0",
+    "@vltpkg/spec": "1.3.0",
+    "@vltpkg/tar": "1.3.0",
+    "@vltpkg/types": "1.3.0",
+    "@vltpkg/workspaces": "1.3.0",
+    "@vltpkg/xdg": "1.3.0",
     "ssri": "^13.0.0",
     "tar": "^7.5.2"
   },
@@ -32,8 +32,8 @@
     "@types/node": "^22.19.2",
     "@types/pacote": "^11.1.8",
     "@vltpkg/benchmark": "0.0.0",
-    "@vltpkg/cache-unzip": "1.2.0",
-    "@vltpkg/vlt-json": "1.2.0",
+    "@vltpkg/cache-unzip": "1.3.0",
+    "@vltpkg/vlt-json": "1.3.0",
     "eslint": "^9.39.1",
     "pacote": "^21.0.4",
     "prettier": "^3.7.4",