@arraypress/security-headers

Security response headers for static hosts — CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy. Generates a Cloudflare/Netlify _headers file, with an Astro integration. Zero dependencies.

npm install @arraypress/security-headers

// astro.config.mjs
import { defineConfig } from 'astro/config';
import headers from '@arraypress/security-headers/astro';

export default defineConfig({
  security: { csp: true },    // Astro owns CSP — see below
  integrations: [headers()],   // everything else, written to dist/_headers
});

The integration writes _headers on astro:build:done, so there's no separate build script to remember. It logs what it wrote:

[@arraypress/security-headers] wrote _headers — 7 headers on /*

On Cloudflare, a static-assets deploy with no server script serves requests for free. Adding middleware to set headers adds a script and makes every request billable. _headers is applied at the edge for nothing.

Astro has its own security.csp, and it can hash the inline <script> and <style> blocks Astro itself emits — the theme flash-guard, scoped component styles. A static _headers file can't hash them, so expressing the same policy there means 'unsafe-inline' on both directives, which is most of what CSP was protecting you from.

So Astro owns CSP, and this owns what Astro doesn't do: HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy, X-Content-Type-Options, Cross-Origin-Opener-Policy and X-Permitted-Cross-Domain-Policies.

Opt back in — for a host where Astro's CSP isn't in play:

integrations: [headers({ csp: { defaultSrc: ["'self'"] } })]

headers(config?, options?)

• config — a SecurityHeadersConfig (below). csp defaults to false here.
• options.path — path pattern the headers apply to. Default '/*'.
• options.filename — output name. Default '_headers'.

Cloudflare caps a _headers file at 100 rules; one path costs one rule however many headers it carries.

The generators are plain functions with no framework attached — use them from a build script, a Worker, or a test.

import { headersFile, buildHeaders, buildCSP, buildHSTS } from '@arraypress/security-headers';

// A _headers file, as a string.
writeFileSync('dist/_headers', headersFile({ csp: { scriptSrc: ["'self'"] } }));

// The same values as a plain object — for a Response you build yourself.
return new Response(body, { headers: buildHeaders() });

// Or one header at a time.
buildCSP({ defaultSrc: ["'self'"] });
buildHSTS({ maxAge: 31536000, includeSubDomains: true });

headersFile() renders the Cloudflare/Netlify format — a path line, then each header indented two spaces:

/*
  X-Content-Type-Options: nosniff
  X-Frame-Options: SAMEORIGIN
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: camera=(), microphone=(), geolocation=()
  Cross-Origin-Opener-Policy: same-origin
  X-Permitted-Cross-Domain-Policies: none
  Content-Security-Policy: default-src 'self'; script-src 'self'; …
  Strict-Transport-Security: max-age=31536000; includeSubDomains

Under the Astro integration the CSP line is absent, since Astro owns it.

Every header is independently togglable — pass false to skip it.

Cross-Origin-Opener-Policy is on by default: it severs window.opener across origins and needs nothing from the resources you load, so it costs you nothing. The one gotcha is OAuth popups that talk back via window.opener — those want 'same-origin-allow-popups'.

Cross-Origin-Embedder-Policy and Cross-Origin-Resource-Policy are off by default, deliberately. COEP blocks every cross-origin resource that hasn't opted in, and CORP stops other sites embedding your images and fonts. Turn them on together, with COOP 'same-origin', when you actually need crossOriginIsolated — that is, SharedArrayBuffer or wasm threads:

headers({
  crossOriginOpenerPolicy: 'same-origin',
  crossOriginEmbedderPolicy: 'require-corp',
  crossOriginResourcePolicy: 'same-origin',
})

An app using AudioWorklets or Workers does not need this on its own — only shared memory does.

Send a strict policy as report-only alongside a permissive enforced one, watch the reports, then promote it:

headers({
  csp: { scriptSrc: ["'self'", "'unsafe-inline'"] },   // enforced today
  cspReportOnly: { scriptSrc: ["'self'"] },             // the goal
  reportingEndpoints: { csp: 'https://example.com/csp-report' },
})

CSP directives are camelCase and become kebab-case on the wire: defaultSrc, scriptSrc, styleSrc, imgSrc, fontSrc, connectSrc, frameSrc, and the rest.

buildHeaders({
  csp: { scriptSrc: ["'self'", 'https://challenges.cloudflare.com'] },
  xFrameOptions: 'DENY',
  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
  permissionsPolicy: false,
});

Two defaults are strict on purpose and will bite if your site is the exception. Both fail silently in the browser, so they're worth knowing before you deploy.

Permissions-Policy defaults to camera=(), microphone=(), geolocation=(), which disables getUserMedia() outright — the call rejects, and nothing in your own code looks wrong. Right for a marketing or directory site; wrong for an app that records audio.

// An app with a record-from-mic button:
headers({ permissionsPolicy: 'camera=(), microphone=(self), geolocation=()' })

font-src defaults to 'self' and style-src to 'self' 'unsafe-inline', so a <link> to fonts.googleapis.com and the files it pulls from fonts.gstatic.com are both blocked:

headers({
  csp: {
    styleSrc: ["'self'", "'unsafe-inline'", 'https://fonts.googleapis.com'],
    fontSrc: ["'self'", 'https://fonts.gstatic.com'],
  },
})

The same applies to any third-party origin — analytics, embeds, a CDN. The default assumes a site that serves everything itself; add origins as you add dependencies rather than loosening default-src.

This one doesn't arise under the Astro integration, where CSP is off and Astro owns the policy.

X-Frame-Options is superseded by CSP's frame-ancestors but is still emitted for older browsers — they don't cost each other anything.

The Permissions-Policy default is a tight baseline suited to admin surfaces. If your site legitimately uses the camera, microphone or geolocation, extend it rather than dropping the header.

HSTS only takes effect over HTTPS, and preload is a one-way door — browsers cache it for a long time, so don't enable it until you're certain every subdomain can serve HTTPS.

MIT