vite-plugin-sri4 4.0.0 → 4.2.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

@@ -12,6 +12,9 @@ A Vite plugin to generate Subresource Integrity (SRI) hashes for your assets dur
 - [Installation](#installation)
 - [Usage](#usage)
 - [Plugin Options](#plugin-options)
+- [Dynamic Routes](#dynamic-routes)
+- [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)
@@ -24,10 +27,13 @@ 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.
+- **Bypass Domains:** Option to specify domains to bypass SRI injection, 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.
-- **Vite Compatibility:** Compatible with Vite 7.0 and Vite 8.0 (including the Rolldown-based native build path).
+- **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.
+- **Vite Compatibility:** Compatible with Vite 6.4, 7.0 and 8.0 (including the Rolldown-based native build path). `6.4` is the floor because it is the only Vite 6 line still receiving upstream security patches.
 
 ## Installation
 
@@ -47,14 +53,21 @@ 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.
       ignoreMissingAsset: false,
       // Optional. Log verbosity: 'silent' | 'error' | 'warn' | 'info' | 'debug'. Defaults to 'warn'.
-      logLevel: 'warn'
+      logLevel: 'warn',
+      // Optional. Inject an import map carrying integrity for every JS chunk,
+      // covering dynamically imported routes. Defaults to false.
+      importmap: false,
+      // Optional. Emit dist/sri-manifest.json for SSR to read. Defaults to false.
+      manifest: false
     })
   ]
 });
@@ -77,13 +90,90 @@ 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).
 * `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):
+  Inject a `<script type="importmap">` containing an `integrity` map for every JS chunk in the build. Default is `false`. See [Dynamic routes](#dynamic-routes).
+* `manifest` (boolean):
+  Emit `sri-manifest.json` alongside the build, mapping every non-HTML output file to its SRI hash. Default is `false`. See [Dynamic routes](#dynamic-routes).
+
+## Dynamic routes
+
+Rewriting HTML tags can only protect resources that have a tag at build time. A route loaded with `import()` has none - Vite's preload helper creates the `<link rel="modulepreload">` at runtime - and an SSR build emits no HTML at all. Two options cover those cases.
+
+### `importmap: true` (client-side dynamic imports)
+
+Emits an import map whose `integrity` key covers every JS chunk, including chunks only ever reached through `import()`:
+
+```html
+<script type="importmap">{"integrity":{"/assets/about-a1b2c3.js":"sha384-..."}}</script>
+```
+
+The map is injected before the first `<script>` so it applies to every module. Engines without support ignore the `integrity` key rather than failing, so this degrades safely - but check current browser support before relying on it as your only protection.
+
+### `manifest: true` (SSR / server-rendered HTML)
+
+Emits `sri-manifest.json` mapping output file names to hashes, which a server rendering HTML per request can read:
+
+```json
+{
+  "assets/index-a1b2c3.js": "sha384-...",
+  "assets/index-d4e5f6.css": "sha384-..."
+}
+```
+
+This is the only mechanism available when the build produces no HTML asset.
+
+### Caveat for both
+
+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.
+
+## 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