# security

Generyczne nagłówki bezpieczeństwa HTTP (HSTS, X-Frame-Options, nosniff,
Referrer-Policy, Permissions-Policy) jako funkcja do `next.config`. CSP CELOWO
pominięte — zależy od domen projektu, zostaje w projekcie.

## Zasada

Nagłówki, które są IDENTYCZNE między projektami, plugin dostarcza raz. CSP
(Content-Security-Policy) wymaga znajomości domen konkretnego projektu (skąd
ładują się skrypty, obrazy, fonty, analytics), więc nie może być generyczne —
zostaje w projekcie, dodawane przez `additional`.

## Użycie — next.config.ts

Nagłówki wpina się w `next.config`, NIE w proxy — bo muszą pokryć CAŁĄ
aplikację (też `/admin`, statyki), a proxy pomija te trasy.

```ts
// next.config.ts
import { withPayload } from '@payloadcms/next/withPayload'
import type { NextConfig } from 'next'
import { buildSecurityHeaders } from '@intecion/ipal-kit'

const securityHeaders = buildSecurityHeaders({
  hsts: process.env.NODE_ENV === 'production',   // WAŻNE: off w dev (http)
  additional: [
    // CSP projektu — zna swoje domeny:
    // { key: 'Content-Security-Policy', value: "default-src 'self'; ..." },
  ],
})

const nextConfig: NextConfig = {
  async headers() {
    return [{ source: '/:path*', headers: securityHeaders }]
  },
}

export default withPayload(nextConfig)
```

## Opcje

| Opcja | Domyślnie | Rola |
|---|---|---|
| `hsts` | `true` | Strict-Transport-Security (wymuś HTTPS) |
| `hstsMaxAge` | `63072000` (2 lata) | max-age HSTS w sekundach |
| `hstsIncludeSubDomains` | `true` | HSTS na subdomeny |
| `hstsPreload` | `false` | preload (tylko jeśli zgłaszasz do listy) |
| `frameOptions` | `'DENY'` | X-Frame-Options (anty-clickjacking) |
| `referrerPolicy` | `'strict-origin-when-cross-origin'` | Referrer-Policy |
| `permissionsPolicy` | blokuje camera/mic/geolocation | Permissions-Policy |
| `additional` | `[]` | dodatkowe nagłówki (np. CSP); same-key nadpisuje |

## PUŁAPKA — HSTS w dev

HSTS nad HTTP na localhost może zablokować przeglądarkę na HTTPS dla localhost.
ZAWSZE wyłączaj w dev: `hsts: process.env.NODE_ENV === 'production'`.

## Nadpisywanie i CSP

`additional` z tym samym kluczem NADPISUJE domyślny (np. zmień X-Frame-Options
na SAMEORIGIN). Nowy klucz (jak CSP) dodaje. CSP zawsze przez `additional` —
plugin go nie generuje, bo zależy od projektu.