vite-plugin-sri4 4.2.0 → 5.1.0

package/README.md

@@ -1,6 +1,6 @@
 # vite-plugin-sri4
 
-![NPM Version](https://img.shields.io/npm/v/vite-plugin-sri4)
+[![NPM Version](https://img.shields.io/npm/v/vite-plugin-sri4)](https://www.npmjs.com/package/vite-plugin-sri4)
 [![codecov](https://codecov.io/gh/7a6163/vite-plugin-sri4/graph/badge.svg?token=GOVB4J3D19)](https://codecov.io/gh/7a6163/vite-plugin-sri4)
 ![License](https://img.shields.io/npm/l/vite-plugin-sri4)
 
@@ -13,6 +13,7 @@ A Vite plugin to generate Subresource Integrity (SRI) hashes for your assets dur
 - [Usage](#usage)
 - [Plugin Options](#plugin-options)
 - [Dynamic Routes](#dynamic-routes)
+- [External Resources](#external-resources)
 - [When SRI Actually Helps](#when-sri-actually-helps)
 - [How It Attaches Hashes](#how-it-attaches-hashes)
 - [Example Project](#example-project)
@@ -26,8 +27,8 @@ A Vite plugin to generate Subresource Integrity (SRI) hashes for your assets dur
 
 - **Automatic SRI Generation:** Computes SRI hashes for assets (chunks and files) using a configurable algorithm (default is `sha384`).
 - **HTML Injection:** Automatically injects `integrity` and `crossorigin` attributes into `<script>` and `<link>` tags in your HTML.
-- **CORS Support Check:** For external resources, a CORS check is performed to verify access via `Access-Control-Allow-Origin`.
-- **Bypass Domains:** Option to specify domains to bypass SRI injection, plus a `skip-sri` attribute to opt out a single tag.
+- **External Resource Gating:** A resource on someone else's origin is hashed only when it is reachable, answers `Access-Control-Allow-Origin: *`, and its origin declares the URL immutable. Anything else is left alone with a warning naming the reason — a hash pins one snapshot of bytes, so it is only correct on a URL whose bytes never change. See [External resources](#external-resources).
+- **Bypass and Trust Domains:** `bypassDomains` to leave a host alone, `trustDomains` to hash one whose headers do not declare it stable, plus a `skip-sri` attribute to opt out a single tag.
 - **Public Directory Support:** Assets served verbatim from `publicDir` are hashed from disk, not just bundle outputs.
 - **Zero Dependencies:** No runtime dependencies, and TypeScript definitions are included.
 - **Missing Asset Handling:** Configurable warning suppression for missing assets.
@@ -94,7 +95,9 @@ Output:
 * `crossorigin` (string):
   Value for the injected `crossorigin` attribute: `anonymous` (default) or `use-credentials`. Use the latter for a CDN that requires cookies or HTTP auth. Tags that already declare a `crossorigin` are left alone.
 * `bypassDomains` (Array<string>):
-  Array of domain names where SRI injection should be skipped. This allows external resources from specified domains to be excluded from SRI checks (for example, when they may not support CORS).
+  Hostnames to leave untouched, subdomains included. Use it to silence the warning for a host you have decided not to protect. See [External resources](#external-resources).
+* `trustDomains` (Array<string>):
+  Hostnames whose bytes you vouch for, subdomains included. An external resource is only hashed when its origin declares the URL immutable; a host listed here is hashed regardless. For a stable host that does not set the header — not for forcing SRI onto a vendor's rolling URL. See [External resources](#external-resources).
 * `ignoreMissingAsset` (boolean):
   When true, warns instead of failing the build for assets found in neither the bundle nor `publicDir`. Default is `false`, which fails the build rather than shipping a tag with no integrity.
 * `logLevel` (string):
@@ -135,6 +138,77 @@ This is the only mechanism available when the build produces no HTML asset.
 
 Hashes are computed during the build. A plugin that mutates chunk contents after this one (`@vitejs/plugin-legacy`, compression plugins that rewrite in place) would invalidate them, so the plugin re-hashes every file it touched in `writeBundle` and fails the build if anything drifted. You get a build error rather than a page that only breaks in the browser.
 
+## External resources
+
+The `writeBundle` drift check above covers **your own build outputs only**. Everything you build is hashed locally — bundle chunks and assets from their bytes, `public/` files from disk, and, with an absolute `base`, your own CDN URLs from the bundle rather than the network — so none of it depends on a server being reachable or honest at build time.
+
+An external URL pointing at someone else's origin is different. It is fetched **once, at build time, from your build machine**, and the hash is taken from that copy. An `integrity` attribute pins those bytes forever, so it is only correct on a URL whose bytes never change — and the origin is the only party that knows whether that is true.
+
+So the plugin asks it. An external resource is hashed only when **all three** hold:
+
+1. **`HEAD` succeeds.** Otherwise there is nothing to check.
+2. **`Access-Control-Allow-Origin: *`.** Injecting `integrity` also injects `crossorigin`, so a response scoped to one specific origin — or to none — would turn a working resource into a blocked one.
+3. **The origin declares the URL immutable**: `Cache-Control: immutable`, or a `max-age` of a year or more — and nothing in the same header contradicting it. `private`, `no-store` and `no-cache` each veto it: freshness and shareability are orthogonal, so a per-client response can carry a long `max-age`, and `no-cache, max-age=<long>` is a real CDN spelling of "cache it, but revalidate every time". Or the host is in `trustDomains`.
+
+Anything else is left alone, with a warning naming the URL and the reason. Nothing ships without integrity silently.
+
+### Why immutability, and not a list of bad origins
+
+Because the list is never finished. Version-pinned URLs and rolling ones are two clean clusters, and the CDNs drew the line themselves:
+
+| URL | `Cache-Control` | |
+|---|---|---|
+| `cdnjs …/jquery/3.7.1/jquery.min.js` | `max-age=30672000, immutable` | hashed |
+| `jsdelivr …/bootstrap@5.3.3/…` | `max-age=31536000, immutable` | hashed |
+| `unpkg …/htmx.org@1.9.12/…` | `max-age=31536000` | hashed |
+| `code.jquery.com/jquery-3.7.1.min.js` | `max-age=31536000` | hashed |
+| `jsdelivr …/vue@3/…` (floating) | `max-age=604800` | skipped |
+| `fonts.googleapis.com/css2?…` | `private, max-age=86400` | skipped |
+| `plausible.io/js/script.js` | `public, max-age=86400` | skipped |
+| `cdn.tailwindcss.com` | `max-age=14400` | skipped |
+| `connect.facebook.net/en_US/sdk.js` | `public, max-age=1200` | skipped |
+| `js.stripe.com/v3/` | `max-age=120` | skipped |
+| `unpkg …/react@18/…` (floating) | `max-age=60` | skipped |
+
+Nothing lands between 604800 and 30672000, so the threshold separates two clusters rather than splitting a spectrum.
+
+A blacklist would have to catch every one of the bottom rows individually, and the ones that are ordinary `public` responses — `cdn.tailwindcss.com`, `plausible.io` — look exactly like a resource you *should* hash. Each gap ships a build that works today and breaks whenever that vendor deploys. The whitelist fails the other way: a resource you could have protected ships unprotected, and says so in the log.
+
+`Vary` is deliberately not used. Google Fonts varies on `User-Agent` without declaring it there (`vary: Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site`), so a `Vary`-based check lets exactly that resource through.
+
+### Getting a resource hashed
+
+**Pin a version in the URL.** `unpkg.com/react@18.3.1/…` answers `max-age=31536000`; `unpkg.com/react@18/…` answers `max-age=60`. Same for jsdelivr. This is the fix, not a workaround — a floating URL and an integrity attribute are contradictory by construction.
+
+**Or vouch for the host** when you know it is stable and it just does not say so. The shape to look for is a URL that already carries a version, served by an origin that simply sends no `Cache-Control` at all:
+
+```
+https://js.tappaysdk.com/sdk/tpdirect/v5.19.2
+
+  access-control-allow-origin: *
+  (no cache-control header)
+```
+
+The version is in the path, so those bytes are as fixed as any `immutable` response — the origin just never says so. That is what `trustDomains` is for:
+
+```js
+sri({ trustDomains: ['js.tappaysdk.com'] })
+```
+
+**When not to use it.** `trustDomains` overrides the one check that stands between you and a hash that stops matching. Do not point it at:
+
+- **a URL without a version in it** — `js.stripe.com/v3/`, `cdn.tailwindcss.com`, `connect.facebook.net/en_US/sdk.js`. Stripe documents that `v3/` must not be pinned; forcing a hash onto it produces a page that works until their next deploy.
+- **a floating range** — `unpkg.com/react@18/…` resolves to whatever 18.x is current.
+- **a host that serves per-client responses** — `fonts.googleapis.com` answers `private` for a reason.
+
+The test is not "do I trust this vendor". It is "will these exact bytes still be at this exact URL after their next release". If the answer comes from the URL itself, `trustDomains` is right; if it comes from hope, use `bypassDomains`.
+
+**Or accept it and silence the warning** with `bypassDomains`. Third-party analytics and widget scripts are usually this case — they are built to auto-update, and there is nothing to pin:
+
+```js
+sri({ bypassDomains: ['www.googletagmanager.com', 'connect.facebook.net'] })
+```
+
 ## When SRI Actually Helps
 
 SRI is worth the most when your HTML and your assets have **different trust boundaries** - typically HTML served from your own origin and JS/CSS served from a CDN (`base: 'https://cdn.example.com/'`). If the CDN is compromised or a cache is poisoned, the integrity attribute in your origin-served HTML is what stops the browser from running the tampered file. That is the case this plugin is built for.
@@ -205,10 +279,11 @@ The example project shows:
    - Consider `sha512` for maximum security
    - Avoid `sha1` as it's considered cryptographically weak
 
-2. **CORS Configuration**
-   - Ensure your CDN or hosting service supports CORS
-   - Set appropriate `Access-Control-Allow-Origin` headers
-   - Use `bypassDomains` for trusted domains that don't support CORS
+2. **External Resources**
+   - Pin a version in the URL. `unpkg.com/react@18.3.1/…` answers `max-age=31536000` and gets a hash; `unpkg.com/react@18/…` answers `max-age=60` and does not
+   - Serve your own assets with `Access-Control-Allow-Origin: *` and an immutable `Cache-Control`
+   - Use `bypassDomains` for a host you have decided not to protect — a vendor's auto-updating widget or analytics script
+   - Use `trustDomains` only for a host you control that is stable but does not say so in its headers
 
 3. **Performance Optimization**
    - Enable `ignoreMissingAsset` in development for faster builds
@@ -223,17 +298,21 @@ The example project shows:
 
 ### Common Issues
 
-1. **Missing Integrity Attributes**
-   - Check if the file is in your build output
-   - Verify the file path is correct
-   - Enable debug mode to see detailed logs
+1. **An external resource has no integrity**
+   - Read the build log. Every skip warns and names its reason
+   - `does not declare this URL immutable` — the origin's `Cache-Control` is short, or carries `private` / `no-cache` / `no-store`. Pin a version in the URL, or see [Getting a resource hashed](#getting-a-resource-hashed)
+   - `Access-Control-Allow-Origin is absent` / `not "*"` — nothing to do at build time; `bypassDomains` silences it
+
+2. **A local asset has no integrity**
+   - Check the file is in your build output, or in `publicDir`
+   - Verify the path in the tag matches, including `base`
+   - Enable debug mode to see per-resource decisions
 
-2. **CORS Errors**
-   - Ensure the resource supports CORS
-   - Add the domain to `bypassDomains` if needed
-   - Check network tab for CORS headers
+3. **The browser blocks a resource that has integrity**
+   - The bytes changed after the build. If it is your own output, a plugin ordered after this one rewrote it — the `writeBundle` drift check should have failed the build, so check the plugin order
+   - If it is external, the URL is not as immutable as its headers claim. Move it to `bypassDomains`
 
-3. **Build Performance**
+4. **Build Performance**
    - Use `ignoreMissingAsset` if you have many external resources
    - Disable debug mode in production
    - Consider using a CDN for external resources

package/dist/index.cjs

@@ -49,20 +49,14 @@ class ResourceCache {
  */
 class CacheManager {
   constructor() {
-    this.urlSupportCache = new ResourceCache();
     this.resourceCache = new ResourceCache();
   }
 
-  getUrlSupportCache() {
-    return this.urlSupportCache
-  }
-
   getResourceCache() {
     return this.resourceCache
   }
 
   clearAll() {
-    this.urlSupportCache.clear();
     this.resourceCache.clear();
   }
 }
@@ -72,14 +66,16 @@ class CacheManager {
 const DEFAULT_TIMEOUT = 5000;
 
 /**
- * Check if URL is from a bypass domain
+ * Does an external URL's host match one of `domains`, or a subdomain of one?
+ * Used by both `bypassDomains` and `trustDomains`.
  */
-function isUrlFromBypassDomain(url, bypassDomains = [], logger = null) {
+function matchesDomain(url, domains = [], logger = null) {
   if (!url || typeof url !== 'string' || !url.startsWith('http')) return false
+  if (domains.length === 0) return false
 
   try {
     const urlObj = new URL(url);
-    return bypassDomains.some(domain =>
+    return domains.some(domain =>
       urlObj.hostname === domain || urlObj.hostname.endsWith(`.${domain}`)
     )
   } catch (error) {
@@ -90,76 +86,106 @@ function isUrlFromBypassDomain(url, bypassDomains = [], logger = null) {
   }
 }
 
+// A year. The conventional encoding of "this URL's bytes will never change",
+// and what every CDN puts on a version-pinned path.
+const IMMUTABLE_MAX_AGE = 31536000;
+
 /**
- * Resource check with retry mechanism
+ * Does the origin declare this URL's bytes immutable - `Cache-Control:
+ * immutable`, or a max-age of a year or more - and nothing in the same header
+ * contradicting it?
+ *
+ * Measured, because the split is what makes this usable as a gate. Pinned
+ * third-party libraries, the case SRI actually exists for:
+ *
+ *   cdnjs    jquery/3.7.1       max-age=30672000, immutable
+ *   jsdelivr bootstrap@5.3.3    max-age=31536000, immutable
+ *   unpkg    htmx.org@1.9.12    max-age=31536000
+ *   code.jquery.com  3.7.1      max-age=31536000
+ *
+ * Everything that rolls under a stable URL:
+ *
+ *   jsdelivr vue@3              max-age=604800
+ *   fonts.googleapis.com        max-age=86400   (also `private`)
+ *   plausible.io/js/script.js   max-age=86400
+ *   cdn.tailwindcss.com         max-age=14400
+ *   connect.facebook.net        max-age=1200
+ *   js.stripe.com/v3/           max-age=120
+ *   unpkg    react@18           max-age=60
+ *
+ * Nothing lands between 604800 and 30672000, so the threshold is not a
+ * balancing act - it separates two clusters the CDNs themselves created.
  */
-async function checkResourceSupport(url, urlSupportCache, logger = null, retries = 2) {
-  if (urlSupportCache.has(url)) {
-    return urlSupportCache.get(url)
-  }
-
-  let lastError;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-
-      const response = await fetch(url, {
-        method: 'HEAD',
-        signal: controller.signal
-      });
-
-      clearTimeout(timeoutId);
+function isImmutableResponse(cacheControl) {
+  if (!cacheControl) return false
+
+  let immutable = false;
+
+  for (const directive of cacheControl.split(',')) {
+    // Token equality, not substring: `x-immutable` is not this directive
+    const token = directive.trim().toLowerCase();
+
+    // These veto whatever else the header claims, and are checked against the
+    // whole header rather than returning early, because freshness and
+    // shareability are orthogonal - a per-client response can carry a long
+    // max-age, and `no-cache, max-age=<long>` is a real CDN spelling of "cache
+    // it, but revalidate every time", i.e. the bytes may have changed.
+    //
+    // The qualified forms (`private="set-cookie"`, `no-cache="set-cookie"`)
+    // only scope the directive to those headers, so vetoing on them is
+    // stricter than the spec requires. That is the right way to be wrong here:
+    // the cost is losing SRI on a resource that would have been fine, and it
+    // is logged. Not vetoing costs a page that only breaks in the browser.
+    if (
+      token === 'no-store' ||
+      token === 'private' || token.startsWith('private=') ||
+      token === 'no-cache' || token.startsWith('no-cache=')
+    ) {
+      return false
+    }
 
-      // Only `*` can be verified at build time. Injecting integrity also means
-      // injecting crossorigin="anonymous"; if the server answers with a
-      // concrete origin that does not match wherever the HTML ends up being
-      // served from, that turns a working script into a blocked one. Skipping
-      // is the safe outcome, but say so at warn level - silence here is what
-      // makes an unprotected resource easy to miss.
-      const corsHeader = response.headers.get('access-control-allow-origin');
-      const isSupported = response.ok && corsHeader === '*';
-      if (response.ok && corsHeader && corsHeader !== '*' && logger) {
-        logger.warn(
-          `Skipping SRI for ${url}: Access-Control-Allow-Origin is "${corsHeader}", not "*", ` +
-          'so crossorigin="anonymous" cannot be verified at build time. ' +
-          'Add the domain to bypassDomains to silence this.'
-        );
-      }
-      urlSupportCache.set(url, isSupported);
-      return isSupported
-    } catch (error) {
-      lastError = error;
-      if (error.name === 'AbortError') {
-        if (logger) {
-          logger.warn(`Resource check timed out: ${url}`);
-        }
-        break // Don't retry timeouts
-      }
+    if (token === 'immutable') immutable = true;
 
-      // Don't wait after the last failed attempt
-      if (attempt < retries) {
-        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
-      }
+    if (token.startsWith('max-age=')) {
+      // RFC 9111 permits a quoted-string value: `max-age="31536000"`
+      const seconds = Number(token.slice('max-age='.length).replace(/^"|"$/g, ''));
+      if (Number.isFinite(seconds) && seconds >= IMMUTABLE_MAX_AGE) immutable = true;
     }
   }
 
-  if (logger) {
-    logger.warn(`Failed to check resource support: ${url}`, lastError);
-  }
-  urlSupportCache.set(url, false);
-  return false
+  return immutable
 }
 
 /**
- * Optimized resource fetching function with retry mechanism and caching
+ * Resource check with retry mechanism
  */
-async function fetchResource(url, resourceCache, logger = null, retries = 1) {
-  // Check cache
+/**
+ * Fetch an external resource and return its bytes, or null if it must not be
+ * hashed. The reason is always logged - a tag that silently ships without
+ * integrity is the thing that is easy to miss.
+ *
+ * One GET, not a HEAD probe followed by a GET. The headers the gates need
+ * arrive on the response that carries the bytes anyway, so probing separately
+ * doubled the requests and threw the useful copy away - and made the plugin
+ * depend on HEAD being served at all. It often is not: js.tappaysdk.com
+ * answers 403 to HEAD and 200 to GET, which used to read as "could not be
+ * checked" on a payment SDK, exactly the kind of script SRI is for.
+ *
+ * The cost is that a rejected resource is downloaded before it is rejected.
+ * That is the right side to lose on: the accepted case, which is every build
+ * that actually ships hashes, goes from two requests to one.
+ */
+async function fetchVerifiedResource(url, resourceCache, logger = null, trusted = false, retries = 1) {
   if (resourceCache.has(url)) {
     return resourceCache.get(url)
   }
 
+  const reject = (message) => {
+    if (logger && message) logger.warn(message);
+    resourceCache.set(url, null);
+    return null
+  };
+
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
@@ -167,10 +193,52 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
       const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
 
       const response = await fetch(url, { signal: controller.signal });
+
       clearTimeout(timeoutId);
 
       if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`)
+        return reject(
+          `Skipping SRI for ${url}: the server answered ${response.status}. ` +
+          'Add the domain to bypassDomains to silence this.'
+        )
+      }
+
+      // Only `*` can be verified at build time. Injecting integrity also means
+      // injecting crossorigin="anonymous"; if the server answers with a
+      // concrete origin that does not match wherever the HTML ends up being
+      // served from, that turns a working script into a blocked one.
+      const corsHeader = response.headers.get('access-control-allow-origin');
+      if (corsHeader !== '*') {
+        return reject(
+          `Skipping SRI for ${url}: Access-Control-Allow-Origin is ` +
+          `${corsHeader ? `"${corsHeader}", not "*"` : 'absent'}, so crossorigin="anonymous" ` +
+          'cannot be verified at build time. ' +
+          'Add the domain to bypassDomains to silence this.'
+        )
+      }
+
+      // Reachable and CORS-eligible is not the same property as byte-stable.
+      // A hash pins one snapshot of bytes forever, so it is only safe on a URL
+      // whose bytes never change - and the origin is the only party that knows.
+      // Require it to say so rather than hunting for reasons to skip: a
+      // blacklist of known-bad origins is never finished (Google Fonts is
+      // `private`, but cdn.tailwindcss.com and plausible.io are ordinary
+      // `public` responses that roll just the same), and every gap in it ships
+      // a build that works today and breaks whenever the vendor deploys.
+      //
+      // Deliberately not `vary`: Google Fonts varies on User-Agent without
+      // declaring it (`vary: Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site`),
+      // so a vary-based gate would let that resource straight through.
+      const cacheControl = response.headers.get('cache-control');
+      if (!trusted && !isImmutableResponse(cacheControl)) {
+        return reject(
+          `Skipping SRI for ${url}: Cache-Control is ` +
+          `${cacheControl ? `"${cacheControl}"` : 'absent'}, so the origin does not declare ` +
+          'this URL immutable and its bytes may differ from the ones hashed here. Pin a ' +
+          'version in the URL, or add the domain to bypassDomains to accept it unprotected. ' +
+          'Only reach for trustDomains on a host you control - forcing a hash onto a ' +
+          "vendor's rolling URL ships a page that breaks on their next deploy."
+        )
       }
 
       const data = new Uint8Array(await response.arrayBuffer());
@@ -179,12 +247,10 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
     } catch (error) {
       lastError = error;
       if (error.name === 'AbortError') {
-        if (logger) {
-          logger.warn(`Resource fetch timed out: ${url}`);
-        }
-        break // Don't retry timeouts
+        return reject(`Skipping SRI for ${url}: the request timed out.`)
       }
 
+      // Don't wait after the last failed attempt
       if (attempt < retries) {
         await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
       }
@@ -192,8 +258,9 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
   }
 
   if (logger) {
-    logger.warn(`Failed to fetch external resource: ${url}`, lastError);
+    logger.warn(`Skipping SRI for ${url}: the request failed.`, lastError);
   }
+  resourceCache.set(url, null);
   return null
 }
 
@@ -339,15 +406,11 @@ async function calculateIntegrity(
   const {
     ignoreMissingAsset,
     bypassDomains,
+    trustDomains,
     hashAlgorithm,
     hashedAssets
   } = options;
 
-  // Skip specified domains
-  if (isUrlFromBypassDomain(url, bypassDomains, logger)) {
-    return null
-  }
-
   // With an absolute `base` (assets on a CDN) Vite emits absolute URLs for our
   // own build output. Those must be hashed from the bundle, not fetched - the
   // CDN may not have been deployed yet, and this is the very case SRI exists
@@ -356,12 +419,22 @@ async function calculateIntegrity(
   const ownAsset = (HTTP_RE.test(base) || base.startsWith('//')) && url.startsWith(base);
   const fetchUrl = ownAsset ? null : externalUrl(url);
 
+  // Both domain options match the URL that would actually be fetched.
+  // `matchesDomain` needs a scheme, so matching the raw `url` silently missed
+  // every protocol-relative `//host/path` - and `trustDomains` below, which
+  // already saw the normalized form, would then disagree with `bypassDomains`
+  // about the same tag.
+  if (matchesDomain(fetchUrl ?? url, bypassDomains, logger)) {
+    return null
+  }
+
   let source;
   let bundleFileName = null;
   if (fetchUrl) {
-    const isSupported = await checkResourceSupport(fetchUrl, cacheManager.getUrlSupportCache(), logger);
-    if (!isSupported) return null
-    source = await fetchResource(fetchUrl, cacheManager.getResourceCache(), logger);
+    const trusted = matchesDomain(fetchUrl, trustDomains, logger);
+    source = await fetchVerifiedResource(
+      fetchUrl, cacheManager.getResourceCache(), logger, trusted
+    );
     if (!source) return null
   } else if (!ownAsset && SCHEME_RE.test(url)) {
     // data:/blob: and unknown schemes cannot be resolved to a bundle asset
@@ -852,6 +925,7 @@ function sri(options = {}) {
   const {
     ignoreMissingAsset = false,
     bypassDomains = [],
+    trustDomains = [],
     hashAlgorithm = DEFAULT_HASH_ALGORITHM,
     crossorigin = 'anonymous',
     logLevel = 'warn',
@@ -914,6 +988,7 @@ function sri(options = {}) {
       transformer = createTransformer({
         ignoreMissingAsset,
         bypassDomains,
+        trustDomains,
         hashAlgorithm,
         crossorigin,
         hashedAssets

package/dist/index.js

@@ -45,20 +45,14 @@ class ResourceCache {
  */
 class CacheManager {
   constructor() {
-    this.urlSupportCache = new ResourceCache();
     this.resourceCache = new ResourceCache();
   }
 
-  getUrlSupportCache() {
-    return this.urlSupportCache
-  }
-
   getResourceCache() {
     return this.resourceCache
   }
 
   clearAll() {
-    this.urlSupportCache.clear();
     this.resourceCache.clear();
   }
 }
@@ -68,14 +62,16 @@ class CacheManager {
 const DEFAULT_TIMEOUT = 5000;
 
 /**
- * Check if URL is from a bypass domain
+ * Does an external URL's host match one of `domains`, or a subdomain of one?
+ * Used by both `bypassDomains` and `trustDomains`.
  */
-function isUrlFromBypassDomain(url, bypassDomains = [], logger = null) {
+function matchesDomain(url, domains = [], logger = null) {
   if (!url || typeof url !== 'string' || !url.startsWith('http')) return false
+  if (domains.length === 0) return false
 
   try {
     const urlObj = new URL(url);
-    return bypassDomains.some(domain =>
+    return domains.some(domain =>
       urlObj.hostname === domain || urlObj.hostname.endsWith(`.${domain}`)
     )
   } catch (error) {
@@ -86,76 +82,106 @@ function isUrlFromBypassDomain(url, bypassDomains = [], logger = null) {
   }
 }
 
+// A year. The conventional encoding of "this URL's bytes will never change",
+// and what every CDN puts on a version-pinned path.
+const IMMUTABLE_MAX_AGE = 31536000;
+
 /**
- * Resource check with retry mechanism
+ * Does the origin declare this URL's bytes immutable - `Cache-Control:
+ * immutable`, or a max-age of a year or more - and nothing in the same header
+ * contradicting it?
+ *
+ * Measured, because the split is what makes this usable as a gate. Pinned
+ * third-party libraries, the case SRI actually exists for:
+ *
+ *   cdnjs    jquery/3.7.1       max-age=30672000, immutable
+ *   jsdelivr bootstrap@5.3.3    max-age=31536000, immutable
+ *   unpkg    htmx.org@1.9.12    max-age=31536000
+ *   code.jquery.com  3.7.1      max-age=31536000
+ *
+ * Everything that rolls under a stable URL:
+ *
+ *   jsdelivr vue@3              max-age=604800
+ *   fonts.googleapis.com        max-age=86400   (also `private`)
+ *   plausible.io/js/script.js   max-age=86400
+ *   cdn.tailwindcss.com         max-age=14400
+ *   connect.facebook.net        max-age=1200
+ *   js.stripe.com/v3/           max-age=120
+ *   unpkg    react@18           max-age=60
+ *
+ * Nothing lands between 604800 and 30672000, so the threshold is not a
+ * balancing act - it separates two clusters the CDNs themselves created.
  */
-async function checkResourceSupport(url, urlSupportCache, logger = null, retries = 2) {
-  if (urlSupportCache.has(url)) {
-    return urlSupportCache.get(url)
-  }
-
-  let lastError;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-
-      const response = await fetch(url, {
-        method: 'HEAD',
-        signal: controller.signal
-      });
-
-      clearTimeout(timeoutId);
+function isImmutableResponse(cacheControl) {
+  if (!cacheControl) return false
+
+  let immutable = false;
+
+  for (const directive of cacheControl.split(',')) {
+    // Token equality, not substring: `x-immutable` is not this directive
+    const token = directive.trim().toLowerCase();
+
+    // These veto whatever else the header claims, and are checked against the
+    // whole header rather than returning early, because freshness and
+    // shareability are orthogonal - a per-client response can carry a long
+    // max-age, and `no-cache, max-age=<long>` is a real CDN spelling of "cache
+    // it, but revalidate every time", i.e. the bytes may have changed.
+    //
+    // The qualified forms (`private="set-cookie"`, `no-cache="set-cookie"`)
+    // only scope the directive to those headers, so vetoing on them is
+    // stricter than the spec requires. That is the right way to be wrong here:
+    // the cost is losing SRI on a resource that would have been fine, and it
+    // is logged. Not vetoing costs a page that only breaks in the browser.
+    if (
+      token === 'no-store' ||
+      token === 'private' || token.startsWith('private=') ||
+      token === 'no-cache' || token.startsWith('no-cache=')
+    ) {
+      return false
+    }
 
-      // Only `*` can be verified at build time. Injecting integrity also means
-      // injecting crossorigin="anonymous"; if the server answers with a
-      // concrete origin that does not match wherever the HTML ends up being
-      // served from, that turns a working script into a blocked one. Skipping
-      // is the safe outcome, but say so at warn level - silence here is what
-      // makes an unprotected resource easy to miss.
-      const corsHeader = response.headers.get('access-control-allow-origin');
-      const isSupported = response.ok && corsHeader === '*';
-      if (response.ok && corsHeader && corsHeader !== '*' && logger) {
-        logger.warn(
-          `Skipping SRI for ${url}: Access-Control-Allow-Origin is "${corsHeader}", not "*", ` +
-          'so crossorigin="anonymous" cannot be verified at build time. ' +
-          'Add the domain to bypassDomains to silence this.'
-        );
-      }
-      urlSupportCache.set(url, isSupported);
-      return isSupported
-    } catch (error) {
-      lastError = error;
-      if (error.name === 'AbortError') {
-        if (logger) {
-          logger.warn(`Resource check timed out: ${url}`);
-        }
-        break // Don't retry timeouts
-      }
+    if (token === 'immutable') immutable = true;
 
-      // Don't wait after the last failed attempt
-      if (attempt < retries) {
-        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
-      }
+    if (token.startsWith('max-age=')) {
+      // RFC 9111 permits a quoted-string value: `max-age="31536000"`
+      const seconds = Number(token.slice('max-age='.length).replace(/^"|"$/g, ''));
+      if (Number.isFinite(seconds) && seconds >= IMMUTABLE_MAX_AGE) immutable = true;
     }
   }
 
-  if (logger) {
-    logger.warn(`Failed to check resource support: ${url}`, lastError);
-  }
-  urlSupportCache.set(url, false);
-  return false
+  return immutable
 }
 
 /**
- * Optimized resource fetching function with retry mechanism and caching
+ * Resource check with retry mechanism
  */
-async function fetchResource(url, resourceCache, logger = null, retries = 1) {
-  // Check cache
+/**
+ * Fetch an external resource and return its bytes, or null if it must not be
+ * hashed. The reason is always logged - a tag that silently ships without
+ * integrity is the thing that is easy to miss.
+ *
+ * One GET, not a HEAD probe followed by a GET. The headers the gates need
+ * arrive on the response that carries the bytes anyway, so probing separately
+ * doubled the requests and threw the useful copy away - and made the plugin
+ * depend on HEAD being served at all. It often is not: js.tappaysdk.com
+ * answers 403 to HEAD and 200 to GET, which used to read as "could not be
+ * checked" on a payment SDK, exactly the kind of script SRI is for.
+ *
+ * The cost is that a rejected resource is downloaded before it is rejected.
+ * That is the right side to lose on: the accepted case, which is every build
+ * that actually ships hashes, goes from two requests to one.
+ */
+async function fetchVerifiedResource(url, resourceCache, logger = null, trusted = false, retries = 1) {
   if (resourceCache.has(url)) {
     return resourceCache.get(url)
   }
 
+  const reject = (message) => {
+    if (logger && message) logger.warn(message);
+    resourceCache.set(url, null);
+    return null
+  };
+
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
@@ -163,10 +189,52 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
       const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
 
       const response = await fetch(url, { signal: controller.signal });
+
       clearTimeout(timeoutId);
 
       if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`)
+        return reject(
+          `Skipping SRI for ${url}: the server answered ${response.status}. ` +
+          'Add the domain to bypassDomains to silence this.'
+        )
+      }
+
+      // Only `*` can be verified at build time. Injecting integrity also means
+      // injecting crossorigin="anonymous"; if the server answers with a
+      // concrete origin that does not match wherever the HTML ends up being
+      // served from, that turns a working script into a blocked one.
+      const corsHeader = response.headers.get('access-control-allow-origin');
+      if (corsHeader !== '*') {
+        return reject(
+          `Skipping SRI for ${url}: Access-Control-Allow-Origin is ` +
+          `${corsHeader ? `"${corsHeader}", not "*"` : 'absent'}, so crossorigin="anonymous" ` +
+          'cannot be verified at build time. ' +
+          'Add the domain to bypassDomains to silence this.'
+        )
+      }
+
+      // Reachable and CORS-eligible is not the same property as byte-stable.
+      // A hash pins one snapshot of bytes forever, so it is only safe on a URL
+      // whose bytes never change - and the origin is the only party that knows.
+      // Require it to say so rather than hunting for reasons to skip: a
+      // blacklist of known-bad origins is never finished (Google Fonts is
+      // `private`, but cdn.tailwindcss.com and plausible.io are ordinary
+      // `public` responses that roll just the same), and every gap in it ships
+      // a build that works today and breaks whenever the vendor deploys.
+      //
+      // Deliberately not `vary`: Google Fonts varies on User-Agent without
+      // declaring it (`vary: Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site`),
+      // so a vary-based gate would let that resource straight through.
+      const cacheControl = response.headers.get('cache-control');
+      if (!trusted && !isImmutableResponse(cacheControl)) {
+        return reject(
+          `Skipping SRI for ${url}: Cache-Control is ` +
+          `${cacheControl ? `"${cacheControl}"` : 'absent'}, so the origin does not declare ` +
+          'this URL immutable and its bytes may differ from the ones hashed here. Pin a ' +
+          'version in the URL, or add the domain to bypassDomains to accept it unprotected. ' +
+          'Only reach for trustDomains on a host you control - forcing a hash onto a ' +
+          "vendor's rolling URL ships a page that breaks on their next deploy."
+        )
       }
 
       const data = new Uint8Array(await response.arrayBuffer());
@@ -175,12 +243,10 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
     } catch (error) {
       lastError = error;
       if (error.name === 'AbortError') {
-        if (logger) {
-          logger.warn(`Resource fetch timed out: ${url}`);
-        }
-        break // Don't retry timeouts
+        return reject(`Skipping SRI for ${url}: the request timed out.`)
       }
 
+      // Don't wait after the last failed attempt
       if (attempt < retries) {
         await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
       }
@@ -188,8 +254,9 @@ async function fetchResource(url, resourceCache, logger = null, retries = 1) {
   }
 
   if (logger) {
-    logger.warn(`Failed to fetch external resource: ${url}`, lastError);
+    logger.warn(`Skipping SRI for ${url}: the request failed.`, lastError);
   }
+  resourceCache.set(url, null);
   return null
 }
 
@@ -335,15 +402,11 @@ async function calculateIntegrity(
   const {
     ignoreMissingAsset,
     bypassDomains,
+    trustDomains,
     hashAlgorithm,
     hashedAssets
   } = options;
 
-  // Skip specified domains
-  if (isUrlFromBypassDomain(url, bypassDomains, logger)) {
-    return null
-  }
-
   // With an absolute `base` (assets on a CDN) Vite emits absolute URLs for our
   // own build output. Those must be hashed from the bundle, not fetched - the
   // CDN may not have been deployed yet, and this is the very case SRI exists
@@ -352,12 +415,22 @@ async function calculateIntegrity(
   const ownAsset = (HTTP_RE.test(base) || base.startsWith('//')) && url.startsWith(base);
   const fetchUrl = ownAsset ? null : externalUrl(url);
 
+  // Both domain options match the URL that would actually be fetched.
+  // `matchesDomain` needs a scheme, so matching the raw `url` silently missed
+  // every protocol-relative `//host/path` - and `trustDomains` below, which
+  // already saw the normalized form, would then disagree with `bypassDomains`
+  // about the same tag.
+  if (matchesDomain(fetchUrl ?? url, bypassDomains, logger)) {
+    return null
+  }
+
   let source;
   let bundleFileName = null;
   if (fetchUrl) {
-    const isSupported = await checkResourceSupport(fetchUrl, cacheManager.getUrlSupportCache(), logger);
-    if (!isSupported) return null
-    source = await fetchResource(fetchUrl, cacheManager.getResourceCache(), logger);
+    const trusted = matchesDomain(fetchUrl, trustDomains, logger);
+    source = await fetchVerifiedResource(
+      fetchUrl, cacheManager.getResourceCache(), logger, trusted
+    );
     if (!source) return null
   } else if (!ownAsset && SCHEME_RE.test(url)) {
     // data:/blob: and unknown schemes cannot be resolved to a bundle asset
@@ -848,6 +921,7 @@ function sri(options = {}) {
   const {
     ignoreMissingAsset = false,
     bypassDomains = [],
+    trustDomains = [],
     hashAlgorithm = DEFAULT_HASH_ALGORITHM,
     crossorigin = 'anonymous',
     logLevel = 'warn',
@@ -910,6 +984,7 @@ function sri(options = {}) {
       transformer = createTransformer({
         ignoreMissingAsset,
         bypassDomains,
+        trustDomains,
         hashAlgorithm,
         crossorigin,
         hashedAssets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-sri4",
-  "version": "4.2.0",
+  "version": "5.1.0",
   "description": "A Vite plugin to generate Subresource Integrity (SRI) hashes for output files.",
   "type": "module",
   "main": "./dist/index.cjs",

package/types/index.d.ts

@@ -19,12 +19,24 @@ export interface SriOptions {
 
   /**
    * Hostnames to leave untouched. Matches the host itself and its subdomains.
-   * Only applies to external (http/https) URLs; use the `skip-sri` attribute
-   * on a tag to opt a single element out.
+   * Only applies to external URLs, protocol-relative `//host/path` included;
+   * use the `skip-sri` attribute on a tag to opt a single element out.
    * @default []
    */
   bypassDomains?: string[]
 
+  /**
+   * Hostnames whose bytes you vouch for. An external resource is normally only
+   * hashed when its origin declares the URL immutable (`Cache-Control:
+   * immutable`, or a max-age of a year or more); a host listed here is hashed
+   * regardless. Matches the host itself and its subdomains.
+   *
+   * Use it for a stable host that does not set the header - not to force SRI
+   * onto a vendor's rolling URL, which will break on their next deploy.
+   * @default []
+   */
+  trustDomains?: string[]
+
   /**
    * Warn instead of failing the build when an asset resolves to neither a
    * bundle entry nor a file in `publicDir`.