diff --git a/README.md b/README.md index 63a3c10..e7057c0 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ SPDX-FileCopyrightText: 2024 KindSpells Labs S.L. SPDX-License-Identifier: CC-BY-4.0 --> -# @kindspells/astro-sri-scp +# @kindspells/astro-shield [![NPM Version](https://img.shields.io/npm/v/%40kindspells%2Fastro-shield)](https://www.npmjs.com/package/@kindspells/astro-shield) ![NPM Downloads](https://img.shields.io/npm/dw/%40kindspells%2Fastro-shield) @@ -45,13 +45,13 @@ In your `astro.config.mjs` file: import { resolve } from 'node:path' import { defineConfig } from 'astro/config' -import { sriCSP } from '@kindspells/astro-shield' +import { shield } from '@kindspells/astro-shield' const rootDir = new URL('.', import.meta.url).pathname export default defineConfig({ integrations: [ - sriCSP({ + shield({ // This is the path where we'll generate the module containing the SRI // hashes for your scripts and styles. There's no need to pass this // parameter if you don't need this data, but it can be useful to @@ -62,6 +62,66 @@ export default defineConfig({ }) ``` +### Generating Content-Security-Policy Headers + +Although `@kindspells/astro-shield` does not generate CSP headers for you (yet), +it will make it much easier. + +Once you run `astro build`, `@kindspells/astro-shield` will analyse the static +output and generate a new module that exports the SRI hashes, so you can use +them in your CSP headers. + +Here you can see an example of how the generated module looks: + +```javascript +// Do not edit this file manually + +export const inlineScriptHashes = /** @type {string[]} */ ([]) + +export const inlineStyleHashes = /** @type {string[]} */ ([ + 'sha256-VC84dQdO3Mo7nZIRaNTJgrqPQ0foHI8gdp/DS+e9/lk=', +]) + +export const extScriptHashes = /** @type {string[]} */ ([ + 'sha256-+aSouJX5t2z1jleTbCvA9DS7+ag/F4e4ZpB/adun4Sg=', +]) + +export const extStyleHashes = /** @type {string[]} */ ([ + 'sha256-iwd3GNfA+kImEozakD3ZZQSZ8VVb3MFBOhJH6dEMnDE=', +]) + +export const perPageSriHashes = + /** @type {Record} */ ({ + 'index.html': { + scripts: [ + 'sha256-+aSouJX5t2z1jleTbCvA9DS7+ag/F4e4ZpB/adun4Sg=', + ], + styles: [ + 'sha256-VC84dQdO3Mo7nZIRaNTJgrqPQ0foHI8gdp/DS+e9/lk=' + ], + }, + 'about.html': { + scripts: [ + 'sha256-+aSouJX5t2z1jleTbCvA9DS7+ag/F4e4ZpB/adun4Sg=', + ], + styles: [ + 'sha256-iwd3GNfA+kImEozakD3ZZQSZ8VVb3MFBOhJH6dEMnDE=', + ], + }, + }) +``` + +> [!IMPORTANT] +> If your website is very small or it relies on +> [View Transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API), +> then it's best to rely on the `inlineScriptHashes`, `inlineStyleHashes`, +> `extScriptHashes` and `extStyleHashes` values. + +> [!IMPORTANT] +> If you don't rely on View Transitions and you care about minimising the size +> of your CSP headers, then you can rely on the `perPageSriHashes` exported +> value. + ## Known limitations - For now, this integration only works for generated static content (the diff --git a/package.json b/package.json index 87d5a26..3d5f2d8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kindspells/astro-shield", - "version": "0.5.0", + "version": "0.5.1", "description": "An Astro plugin to compute and inject SRI hashes for script and style tags", "private": false, "type": "module",