47 lines
2.2 KiB
TypeScript
47 lines
2.2 KiB
TypeScript
export type BuildCspArgs = {
|
|
/** Google Analytics / GTM — adds googletagmanager + google-analytics. */
|
|
analytics?: boolean;
|
|
/** Extra sources per directive, merged with the built-ins. */
|
|
extra?: Partial<Record<CspDirective, string[]>>;
|
|
/** Google Maps embeds — adds maps.google.com / *.gstatic.com. */
|
|
googleMaps?: boolean;
|
|
/** 'enforce' → Content-Security-Policy; 'report-only' → …-Report-Only header. */
|
|
mode?: 'enforce' | 'report-only';
|
|
/** Media/R2 public URL (from R2_PUBLIC_URL) — added to img-src. */
|
|
r2Url?: string;
|
|
/** Cloudflare Turnstile — adds challenges.cloudflare.com to script/frame/connect. */
|
|
turnstile?: boolean;
|
|
/** YouTube embeds — adds youtube to frame-src. */
|
|
youtube?: boolean;
|
|
};
|
|
type CspDirective = 'base-uri' | 'connect-src' | 'default-src' | 'font-src' | 'form-action' | 'frame-ancestors' | 'frame-src' | 'img-src' | 'media-src' | 'object-src' | 'script-src' | 'style-src' | 'worker-src';
|
|
/**
|
|
* Builds a Content-Security-Policy string with the hard OWASP/Lighthouse-required
|
|
* directives baked in, and opt-in sources for common third parties. Solves the
|
|
* real risk of hand-writing raw CSP per project and forgetting `base-uri 'self'`
|
|
* or `object-src 'none'`.
|
|
*
|
|
* CSP still lives in the project (it lists the project's own domains), but this
|
|
* helper standardizes the skeleton so every project's CSP has the same hardened
|
|
* base — you only flip flags for what the project actually loads.
|
|
*
|
|
* Returns { key, value } ready for buildSecurityHeaders `additional`:
|
|
*
|
|
* import { buildCsp, buildSecurityHeaders } from '@intecion/ipal-kit'
|
|
* const csp = buildCsp({
|
|
* mode: 'report-only', // start here; switch to 'enforce' when clean
|
|
* r2Url: process.env.R2_PUBLIC_URL,
|
|
* turnstile: true, analytics: true,
|
|
* })
|
|
* const headers = buildSecurityHeaders({ hsts: prod, additional: [csp] })
|
|
*
|
|
* Deploy CSP carefully: start with mode:'report-only', check the console for
|
|
* violations across the whole site (forms/Turnstile, gallery/R2, embeds), add
|
|
* missing sources via `extra`, THEN switch to 'enforce'. See docs/security.md.
|
|
*/
|
|
export declare function buildCsp(args?: BuildCspArgs): {
|
|
key: string;
|
|
value: string;
|
|
};
|
|
export {};
|