Added security scripts support

docs/security.md

@@ -71,7 +71,44 @@ analytics, Turnstile, fonty). Generyczny CSP byłby albo za luźny (`*` =
 bezużyteczny), albo psułby stronę. Więc plugin daje mechanizm (`additional`),
 projekt dostarcza CSP dopasowany do siebie.
 
-### Budowa CSP — domeny z env, nie hardkod
+### buildCsp — generator CSP (zalecane zamiast ręcznego)
+
+Zamiast pisać surowy CSP w każdym projekcie (ryzyko pominięcia base-uri,
+object-src), użyj `buildCsp` — ma twarde reguły OWASP/Lighthouse wbudowane, a Ty
+włączasz tylko flagi tego, co projekt ładuje:
+
+```ts
+// next.config.ts
+import { buildCsp, buildSecurityHeaders } from '@intecion/ipal-kit'
+
+const csp = buildCsp({
+  mode: 'report-only',              // zacznij tu; 'enforce' gdy konsola czysta
+  r2Url: process.env.R2_PUBLIC_URL, // media R2 → img-src
+  turnstile: true,                  // challenges.cloudflare.com → script/frame/connect
+  analytics: true,                  // GTM + GA
+  youtube: true,                    // youtube → frame-src
+  googleMaps: true,                 // mapy Google
+  // extra: { 'script-src': ['https://inny-skrypt.pl'] },  // dodatkowe źródła
+})
+
+const securityHeaders = buildSecurityHeaders({
+  hsts: process.env.NODE_ENV === 'production',
+  additional: [csp],
+})
+```
+
+**Twarde reguły wbudowane** (zawsze, nie da się zapomnieć): `base-uri 'self'`,
+`object-src 'none'`, `frame-ancestors 'none'`. To te, które Lighthouse/OWASP
+wymagają, a łatwo je pominąć pisząc CSP ręcznie.
+
+`buildCsp` NIE dodaje `'unsafe-eval'` (osłabia CSP) — dodaj przez `extra` tylko
+jeśli biblioteka tego wymaga. `mode: 'report-only'` daje nagłówek
+`…-Report-Only`; `'enforce'` daje `Content-Security-Policy`.
+
+CSP dalej „w projekcie" (Ty wybierasz flagi wg tego, co ładujesz), ale skeleton
+jest z pluginu — każdy projekt ma ten sam zahardowany fundament.
+
+### Budowa CSP — ręcznie (jeśli potrzebujesz pełnej kontroli)
 
 Domenę mediów czytaj z `R2_PUBLIC_URL` (env), nie zaszywaj. Resztę źródeł
 dopasuj do tego, co projekt faktycznie ładuje:
@@ -138,4 +175,26 @@ wpięte i czy Cloudflare (jeśli przed aplikacją) nie filtruje nagłówków.
 
 > Uwaga Cloudflare: jeśli CF jest przed aplikacją, może nadpisywać/filtrować
 > nagłówki. Wtedy ustaw je też w CF (Transform Rules → Modify Response Header)
-> albo upewnij się, że CF przepuszcza nagłówki z origin.
+> albo upewnij się, że CF przepuszcza nagłówki z origin.
+
+
+## COOP (Cross-Origin-Opener-Policy) — domyślnie włączony
+
+buildSecurityHeaders wysyła domyślnie `Cross-Origin-Opener-Policy: same-origin` —
+izoluje kontekst przeglądarki (ochrona przed XS-Leaks / Spectre, wyciekiem
+window.opener). Uniwersalny nagłówek, więc z automatu.
+
+- Domyślnie `same-origin` (najbezpieczniejsze)
+- `coop: 'same-origin-allow-popups'` — jeśli otwierasz popupy OAuth/płatności
+  wymagające window.opener
+- `coop: false` — wyłącz (rzadko potrzebne)
+
+## Trusted Types — NIE wdrażać (na teraz)
+
+NIE wymuszaj `require-trusted-types-for 'script'`. Powód:
+- Audyt Lighthouse to „Bez oceny" (informacyjny/eksperymentalny w Chromium)
+- Wymuszenie bez kompleksowego silnika polityk w Next/React powoduje `TypeError`
+  przy zewnętrznych skryptach manipulujących DOM stringami (Turnstile, GA)
+- Zysk bezpieczeństwa nie równoważy ryzyka zepsucia strony
+
+Zostaw Trusted Types poza CSP, dopóki Next/React nie da natywnego wsparcia.