Added security scripts support

2026-09-19 22:07:57 +02:00
parent 1186f4f620
commit 9101a5b48e
17 changed files with 404 additions and 42 deletions
@@ -0,0 +1,46 @@
+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' | 'object-src' | 'script-src' | 'style-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 {};