@pronghorn/shield

Shield

Shield is a lightweight, TypeScript-first security header middleware built as an external plugin for Pronghorn. It sets Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, and other hardening headers with secure-by-default settings, filling the gap left by Pronghorn's built-in cors middleware, which only ever handled cross-origin headers.

Built as a standalone package (@pronghorn/shield), the Pronghorn equivalent of Express's helmet, pairs naturally with cors in the global middleware chain.

Why Shield

Pronghorn ships cors for cross-origin headers, but nothing for the broader set of response headers that protect against clickjacking, MIME-sniffing, protocol downgrade attacks, and unsafe script/style injection. Shield closes that gap with secure defaults out of the box.

• Sets Content-Security-Policy with a default-src 'none' whitelist baseline, merged with any directives you provide.
• Sets Strict-Transport-Security to force HTTPS on repeat visits, with configurable max-age, subdomain inclusion, and preload support.
• Sets X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy.
• Strips X-Powered-By to avoid leaking framework fingerprints.
• Every directive can be disabled individually by passing false, nothing is forced on you.
• Zero runtime dependencies, pronghorn is only a peer dependency for types.

Installation

bun add @pronghorn/shield

Requires Bun >=1.3.0 and pronghorn >=0.1.2 as a peer dependency (used for typing the middleware only).

Quick Start

import { createApp, cors } from 'pronghorn'
import { shield } from '@pronghorn/shield'

const app = createApp()

app.use(cors)
app.use(shield())

app.get('/', context => context.json({ message: 'Secured by Shield 🛡️' }))

await app.listen(4000)

Register shield alongside (and typically after) cors, since it rebuilds the response with merged headers, the same ordering pattern used by @pronghorn/cookie.

Core Concepts

Content Security Policy

Shield ships a restrictive default-src 'none' baseline. Pass directives to merge your own allowlists on top of it, only the keys you provide are overridden, the rest keep their secure defaults.

app.use(shield({
  contentSecurityPolicy: {
    directives: {
      'script-src': ["'self'", 'https://cdn.example.com'],
      'img-src': ["'self'", 'data:', 'https:'],
      'connect-src': ["'self'", 'https://api.example.com']
    }
  }
}))

Set reportOnly: true to send Content-Security-Policy-Report-Only instead, useful for testing a policy without enforcing it yet.

app.use(shield({
  contentSecurityPolicy: { reportOnly: true, directives: { 'script-src': ["'self'"] } }
}))

Disable CSP entirely by passing false.

app.use(shield({ contentSecurityPolicy: false }))

Strict Transport Security

Forces browsers to only connect over HTTPS for the configured duration. Defaults to one year with subdomains included.

app.use(shield({
  strictTransportSecurity: { maxAge: 63_072_000, includeSubDomains: true, preload: true }
}))

Frame options

Prevents your app from being embedded in an <iframe> on another origin, mitigating clickjacking. Defaults to DENY.

app.use(shield({ frameOptions: 'SAMEORIGIN' }))

MIME sniffing protection

Sets X-Content-Type-Options: nosniff, stopping browsers from guessing a response's content type and executing it as something other than declared. Enabled by default.

app.use(shield({ noSniff: false })) // opt out if you have a specific reason to

Referrer policy

Controls how much referrer information is sent on outgoing requests/navigations. Defaults to strict-origin-when-cross-origin.

app.use(shield({ referrerPolicy: 'no-referrer' }))

Permissions policy

Restricts which browser features (camera, geolocation, etc.) your app is allowed to use, and whether embedded content can use them.

app.use(shield({
  permissionsPolicy: {
    geolocation: [],
    camera: ["'self'"],
    microphone: []
  }
}))

Hiding the framework fingerprint

Strips any X-Powered-By header before the response leaves your server. Enabled by default.

app.use(shield({ hidePoweredBy: false }))

Middleware Options

Option	Type	Default	Description
contentSecurityPolicy	ContentSecurityPolicyOptions | false	{} (secure baseline)	Content-Security-Policy configuration, or false to disable
strictTransportSecurity	StrictTransportSecurityOptions | false	{} (1 year, subdomains)	Strict-Transport-Security configuration, or false to disable
frameOptions	'DENY' | 'SAMEORIGIN' | false	'DENY'	X-Frame-Options value, or false to disable
noSniff	boolean	true	Sets X-Content-Type-Options: nosniff
referrerPolicy	ReferrerPolicy | false	'strict-origin-when-cross-origin'	Referrer-Policy value, or false to disable
hidePoweredBy	boolean	true	Removes the X-Powered-By header if present
permissionsPolicy	Record<string, string[]> | false	undefined (not set)	Permissions-Policy feature allowlist map

ContentSecurityPolicyOptions

Property	Type	Description
directives	Record<string, string[]>	Directive-to-allowlist map, merged over the secure baseline
reportOnly	boolean	Sends Content-Security-Policy-Report-Only instead of enforcing

StrictTransportSecurityOptions

Property	Type	Default	Description
maxAge	number	31536000 (1 year)	Duration in seconds browsers should remember to use HTTPS only
includeSubDomains	boolean	true	Applies the policy to all subdomains
preload	boolean	false	Opts into browser HSTS preload lists

API Reference

shield(options?: ShieldOptions): Middleware — global middleware factory, register via app.use(shield(options)).

Lower-level header builders are also exported for advanced use outside the middleware:

import { buildCspHeader, buildHstsHeader, buildPermissionsPolicyHeader } from '@pronghorn/shield'

const csp = buildCspHeader({ directives: { 'script-src': ["'self'"] } })
const hsts = buildHstsHeader({ maxAge: 31_536_000, preload: true })
const permissions = buildPermissionsPolicyHeader({ camera: [] })

Architecture

Shield is split into two modules, each with a single responsibility.

Module	Responsibility
directives.ts	Builds individual header value strings (CSP, HSTS, Permissions-Policy) from structured options
middleware.ts	Applies each enabled header to the response, rebuilding it with a merged Headers object since immutable responses (e.g. from Response.json()) can't have headers mutated directly

Shield rebuilds the response the same way @pronghorn/cookie and Pronghorn's built-in cors middleware do, by constructing a new Response with the original body, status, and a merged Headers instance, rather than calling .set() on the original response's headers.

Security Notes

• Start with the default default-src 'none' CSP baseline and add only the directives your app actually needs, an overly permissive CSP defeats its own purpose.
• Use reportOnly: true when rolling out a new CSP to production, to catch violations via browser reports before enforcing the policy.
• Always enable strictTransportSecurity in production once your app is fully served over HTTPS, enabling it prematurely on a mixed HTTP/HTTPS setup can lock out HTTP-only clients.
• preload: true submits your domain to browser HSTS preload lists, this is effectively permanent and hard to reverse, only enable it once you're certain HTTPS will never be removed.

License

WTFPL (Do What the Fuck You Want to Public License), see LICENSE for details.