Configuration Reference

Configure the astro-shield integration

Astro-Shield is an integration built on top the Astro web framework. We can configure our project inside the astro.config.mjs configuration file:

astro.config.mjs

import { defineConfig } from 'astro/config'
import { shield } from '@kindspells/astro-shield'

export default defineConfig({
  integrations: [
    shield({}),
  ],
})

You can pass the following options to the @kindspells/astro-shield integration.

sri

The sri option allows us to configure the settings that control how Astro-Shield will handle Subresource Integrity (SRI) for our project.

Type: object | undefined, defaults to undefined.

Example:

import { resolve } from 'node:path'

import { defineConfig } from 'astro/config'
import { shield } from '@kindspells/astro-shield'

const rootDir = new URL('.', import.meta.url).pathname
const modulePath = resolve(rootDir, 'src', 'generated', 'sriHashes.mjs')

export default defineConfig({
  integrations: [
    shield({
      sri: {
        enableMiddleware: true,
        hashesModule: modulePath,
        allowInlineScripts: false,
        allowInlineStyles: false,
        scriptsAllowListUrls: [
          'https://example.com/script.js',
        ],
      },
    }),
  ],
})

sri.allowInlineScripts

Specifies whether Astro-Shield should allow inline scripts (and how). Its possible values are:

• 'all' (default): Allow all inline scripts in all pages.
• 'static': Allow inline scripts only in static pages.
• false: Disallow all inline scripts.

sri.allowInlineStyles

Specifies whether Astro-Shield should allow inline styles (and how). Its possible values are:

• 'all' (default): Allow all inline styles in all pages.
• 'static': Allow inline styles only in static pages.
• false: Disallow all inline styles.

sri.enableMiddleware

Specifies whether Astro-Shield should enable the middleware to compute the SRI hashes for our dynamic content.

It is also necessary in case we need to generate the Content-Security-Policy (CSP) headers for our dynamic content.

Type: boolean, defaults to false.

सावधानी

If set to true, it is advisable to set the sri.hashesModule option as well.

sri.enableStatic

Specifies whether Astro-Shield should generate the SRI hashes for our static content.

Type: boolean, defaults to true.

sri.hashesModule

Specifies the path to the autogenerated module that contains and exports the SRI hashes computed by Astro-Shield for our content.

We can import this module into our own code in case we need to implement any custom logic that requires the SRI hashes, but its main purpose is to be used together with the sri.enableMiddleware option.

Type: string | undefined, defaults to undefined.

sri.scriptsAllowListUrls

Cross-origin scripts must be explicitly allow-listed by URL so that the content security policies enforced via CSP headers do not block them.

This options allows us to define a list of script URLs that are allowed to be loaded in our pages.

Type: string[], defaults to [].

sri.stylesAllowListUrls

Cross-origin stylesheets must be explicitly allow-listed by URL so that the content security policies enforced via CSP headers do not block them.

This options allows us to define a list of stylesheet URLs that are allowed to be loaded in our pages.

Type: string[], defaults to [].

securityHeaders

The securityHeaders option allows us to configure the settings that control how Astro-Shield will generate the security headers for our project.

If set, it controls how the security headers will be generated for our project, otherwise no security headers will be generated.

Type: object | undefined, defaults to undefined.

Example:

astro.config.mjs

import { defineConfig } from 'astro/config'
import { shield } from '@kindspells/astro-shield'

export default defineConfig({
  integrations: [
    shield({
      securityHeaders: {
        enableOnStaticPages: { provider: 'netlify' },
        contentSecurityPolicy: {
          cspDirectives: {
            'default-src': "'none'",
          },
        },
      },
    }),
  ],
})

securityHeaders.contentSecurityPolicy

If set, it controls how the Content-Security-Policy (CSP) header will be generated (for our static and/or dynamic content).

If not set, no CSP header will be configured for our content.

Type: object | undefined, defaults to undefined.

securityHeaders.contentSecurityPolicy.cspDirectives

If set, it controls the “default” CSP directives (they can be overriden at runtime).

If not set, Astro-Shield will use a minimal set of default directives.

Type: Record<CSPDirectiveName, string>, defaults to {}.

securityHeaders.enableOnStaticPages

Specifies whether Astro-Shield should “generate” security headers for our static content.

If set, it controls how the security headers will be generated for our static content, otherwise no security headers will be generated for it.

Type: object | undefined, defaults to undefined.

securityHeaders.enableOnStaticPages.provider

Possible values are:

• 'netlify': Generate the security headers for static content on Netlify.