vite-plugin-sri4 4.1.0 → 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Zac
+
+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

@@ -13,7 +13,9 @@ 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)
 - [Best Practices](#best-practices)
 - [Troubleshooting](#troubleshooting)
@@ -25,8 +27,10 @@ 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.
+- **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.
 - **Robust Content Support:** Handles various content types including strings, Buffer, and Uint8Array.
 - **Dynamic Routes:** Optional import map integrity and an SRI manifest cover `import()`-loaded chunks and SSR builds, which have no build-time HTML tag to rewrite.
@@ -50,8 +54,10 @@ import sri from 'vite-plugin-sri4';
 export default defineConfig({
   plugins: [
     sri({
-      // Optional. The security hash algorithm. Defaults to "sha384".
+      // Optional. 'sha256' | 'sha384' | 'sha512'. Defaults to 'sha384'.
       hashAlgorithm: 'sha384',
+      // Optional. 'anonymous' | 'use-credentials'. Defaults to 'anonymous'.
+      crossorigin: 'anonymous',
       // Optional. Domains to bypass SRI injection.
       bypassDomains: ['example.com'],
       // Optional. Suppress warnings for missing assets.
@@ -85,11 +91,15 @@ Output:
 ## Plugin Options
 
 * `hashAlgorithm` (string):
-  The hash algorithm used for computing SRI. Default is `sha384`. You may change it to other supported algorithms like `sha256` or `sha512`.
+  The hash algorithm used for computing SRI. One of `sha256`, `sha384` (default) or `sha512` — the only three the SRI spec defines. Anything else fails at startup rather than producing an attribute browsers silently reject.
+* `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, suppresses warnings for assets that are not found in the bundle. Default is `false`.
+  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):
   Log verbosity. One of `silent`, `error`, `warn`, `info`, `debug`. Default is `warn`. Use `debug` to see per-resource decisions during the build.
 * `importmap` (boolean):
@@ -128,12 +138,102 @@ 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:
+
+```js
+sri({ trustDomains: ['assets.internal.example'] })
+```
+
+Do not point `trustDomains` at a vendor's rolling URL. Stripe, for one, documents that `js.stripe.com/v3/` must not be pinned; forcing a hash onto it produces a page that works until their next deploy.
+
+**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.
 
 If everything is served from a single origin, SRI buys much less than it appears to: an attacker who can rewrite `/assets/index-abc123.js` on your server can usually rewrite the `index.html` carrying its hash just as easily. It is not useless - it narrows some deploy and cache-layer mistakes - but for same-origin builds, a Content Security Policy and Vite's default hashed, immutable filenames do more for you than SRI does. Enable it because it is cheap, not because it closes the hole you think it closes.
 
+### Skipping a Single Tag
+
+`bypassDomains` only reaches external hosts. To exclude one specific element, add `skip-sri` to it. The attribute is stripped from the output:
+
+```html
+<script skip-sri src="/legacy.js"></script>
+```
+
+```html
+<!-- built output -->
+<script src="/legacy.js"></script>
+```
+
+## How It Attaches Hashes
+
+There are three places a Vite plugin can compute SRI hashes, and they are not equivalent. This one matters more than it looks, so it is worth writing down.
+
+**In `transformIndexHtml`.** The obvious choice, and the one that reads best — you get the finished HTML and the bundle on the context. It produces wrong hashes for entry chunks. Vite's import-analysis plugin substitutes `__VITE_PRELOAD__` inside its own `generateBundle`, which runs *after* `transformIndexHtml`, so an entry chunk still reads `import("./route.js"), __VITE_PRELOAD__)` at that point while the written file reads `import("./route.js"), [])`. The hash describes bytes that never ship, and the browser rejects the file with no build error at all.
+
+**In a plain `enforce: 'post'` `generateBundle`.** Same problem. Vite places its import-analysis plugin immediately after post user plugins, so a post hook is still one step too early.
+
+**Where this plugin does it.** During `configResolved` it moves itself after that plugin in `config.plugins`, then works in an ordinary `generateBundle`. Measured on Vite 8.2.2, hashing the entry chunk:
+
+| Hook | Entry chunk | Matches shipped file |
+|---|---|---|
+| `transformIndexHtml` (post) | `io6MKsmc4G5y` | ✗ |
+| `generateBundle` (post) | `io6MKsmc4G5y` | ✗ |
+| after repositioning | `lvFyraHkqPN0` | ✓ |
+| written file | `lvFyraHkqPN0` | — |
+
+Only the entry chunk is affected, so a build without a dynamic import will not reveal the difference. As a second safeguard, every hashed file is re-hashed in `writeBundle` and the build fails if anything changed after the hash was taken.
+
+This ordering constraint was first identified by [vite-plugin-sri3](https://github.com/yoyo930021/vite-plugin-sri3), which this plugin began as a fork of. Beyond it, this plugin adds `crossorigin` injection, a CORS pre-check with timeouts and retries for external resources, import map and manifest output for dynamically imported routes, `publicDir` resolution, and the drift check above.
+
 ## Example Project
 
 The plugin includes an example project in the `example` directory that demonstrates its usage with a simple Vite application. To try it:
@@ -164,10 +264,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
@@ -182,17 +283,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