@app4you/cookie-banner 0.0.0-stage → 2.0.2

package/dist/native.d.ts

@@ -0,0 +1,27 @@
+import type { ServiceDefinition } from "./types.js";
+export { resolveLocalizedConfig } from "./i18n/locale.js";
+export { buildConsentCsp, consentCspHeaders, readCspConsent } from "./core/csp.js";
+export type { ConsentCspOptions, CspSources } from "./core/csp.js";
+import type { BannerConfig, ConsentReceipt } from "./types.js";
+export { hasServiceConsent, setServiceConsent, onServiceConsent, } from "./core/service-consent.js";
+export type { BannerConfig, LocalizedContent, ConsentState, ServiceDefinition, ConsentCleanup, } from "./types.js";
+/** Safe in server components/SSR: never supplies a live src. */
+export declare function blockedContentProps(service: string, src?: string): {
+    "data-cb-service": string;
+    "data-cb-src": string | undefined;
+    hidden: boolean;
+};
+/** Use a native <script>, not a framework's eager script loader. */
+export declare function blockedScriptProps(service: string, src?: string): {
+    type: string;
+    "data-cb-type": string;
+    "data-cb-service": string;
+    "data-cb-src": string | undefined;
+    hidden: boolean;
+};
+/** Call in a client effect. Importing this entry on the server is safe. */
+export declare function initializeConsent(config: BannerConfig): Promise<() => void>;
+export declare const getConsentReceipt: () => ConsentReceipt | null;
+export type { ConsentReceipt } from "./types.js";
+/** Current observed services, using the same registry as the consent UI and blocker. */
+export declare function getDetectedServices(): ServiceDefinition[];

package/dist/native.js

@@ -0,0 +1,15 @@
+import { B as n, E as o, F as t, G as a, H as i, I as r, J as C, K as c, L as p, M as d, y as l, s as v } from "./native/native-B9FXlXDp.js";
+export {
+  n as blockedContentProps,
+  o as blockedScriptProps,
+  t as buildConsentCsp,
+  a as consentCspHeaders,
+  i as getConsentReceipt,
+  r as getDetectedServices,
+  C as hasServiceConsent,
+  c as initializeConsent,
+  p as onServiceConsent,
+  d as readCspConsent,
+  l as resolveLocalizedConfig,
+  v as setServiceConsent
+};

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+export type ConsentCategory = "essential" | "analytics" | "marketing";
+export type ConsentState = Record<ConsentCategory, boolean> & {
+    services?: Record<string, boolean>;
+};
+export type BannerMode = "gtm" | "standalone";
+export type BannerVariant = "modal" | "bar";
+export type BannerView = "overlay" | "preferences" | "idle";
+export interface ScriptDef {
+    /** Optional scripts require both the category and this provider choice. */
+    service: string;
+    src?: string;
+    inline?: string;
+    async?: boolean;
+}
+export interface ThemeConfig {
+    primary?: string;
+    /** Hover shade for primary buttons; derived from `primary` when omitted. */
+    primaryHover?: string;
+    background?: string;
+    text?: string;
+}
+export interface ConsentCleanup {
+    /** Exact first-party cookie names; never use wildcard deletion. */
+    cookies?: string[];
+    localStorage?: string[];
+    sessionStorage?: string[];
+}
+export interface ServiceDefinition {
+    id: string;
+    name: string;
+    description: string;
+    privacyUrl?: string;
+    /** Reviewed retention period or criteria for this integration. */
+    retention?: string;
+    cleanup?: ConsentCleanup;
+    /** Absolute URL prefixes; matched on hostname and path, not arbitrary substrings. */
+    urls?: string[];
+}
+export interface ConsentReceipt {
+    id: string;
+    version: number;
+    at: number;
+    services: Record<string, boolean>;
+    categories: Record<ConsentCategory, boolean>;
+    noticeKey: string;
+    notice: {
+        lang?: string;
+        content?: Record<string, string>;
+        overlay: Record<string, string>;
+        preferences: Record<string, string | Record<ConsentCategory, {
+            label: string;
+            description: string;
+        }>>;
+        services: ServiceDefinition[];
+    };
+}
+export interface LocalizedContent {
+    controller?: {
+        name: string;
+        contactUrl?: string;
+    };
+    purposes?: string;
+    privacyPolicyUrl?: string;
+    cookiePolicyUrl?: string;
+    customTexts?: Record<string, unknown>;
+    serviceDisclosures?: Record<string, {
+        name?: string;
+        description?: string;
+        privacyUrl?: string;
+        retention?: string;
+    }>;
+}
+export interface BannerConfig {
+    /** Defaults to standard in npm. WordPress defaults to equal. Never changes blocking or consent requirements. */
+    buttonStyle?: "standard" | "equal";
+    /** Per-page locale content: base language, then exact regional override. */
+    localizations?: Record<string, LocalizedContent>;
+    /** Internal isolated admin preview: memory storage, no evidence submission. */
+    preview?: boolean;
+    /** Legal identity of the website controller, not the software vendor. */
+    controller?: {
+        name: string;
+        contactUrl?: string;
+    };
+    /** Required; bump whenever policy contents, purposes or recipients change. */
+    noticeVersion?: string;
+    /** Reviewed, site-specific explanation of the requested optional processing. */
+    purposes?: string;
+    /** HTTP CSP supplied by the host; consent changes require a fresh document. */
+    strictCsp?: boolean;
+    services?: ServiceDefinition[];
+    /** Disclosure overrides for catalog providers; no duplicate blocking rules. */
+    serviceDisclosures?: Record<string, {
+        name?: string;
+        description?: string;
+        privacyUrl?: string;
+        retention?: string;
+        cleanup?: ConsentCleanup;
+    }>;
+    categoryCleanup?: Partial<Record<"analytics" | "marketing", ConsentCleanup>>;
+    /** Same-origin endpoint receiving minimal, versioned receipts (optional for native hosts). */
+    receiptEndpoint?: string;
+    receiptNonce?: string;
+    /** Early best-effort interception for third-party code. Enabled by the WP plugin. */
+    autoBlock?: boolean;
+    auditMode?: boolean;
+    mode: BannerMode;
+    variant?: BannerVariant;
+    gtmId?: string;
+    loadGtm?: boolean;
+    /** @deprecated Ignored: consent always requires a visitor action. */
+    testMode?: boolean;
+    /** @deprecated Ignored: consent always requires a visitor action. */
+    autoAcceptAll?: boolean;
+    lang: string;
+    privacyPolicyUrl?: string;
+    cookiePolicyUrl?: string;
+    theme?: ThemeConfig;
+    /** @deprecated Custom links always work; the floating withdrawal controls remain visible. */
+    useCustomSettingsLink?: boolean;
+    customTexts?: Record<string, unknown>;
+    detectedServices?: string[];
+    scripts?: {
+        analytics?: ScriptDef[];
+        marketing?: ScriptDef[];
+    };
+}
+export declare const STORAGE_PREFIX = "cb_consent_";
+export declare const STORAGE_HAS_CONSENTED = "cb_has_consented";
+export declare const STORAGE_COMMIT = "cb_consent_commit";
+export declare const CONSENT_CATEGORIES: ConsentCategory[];
+export declare const DEFAULT_CONSENT_STATE: ConsentState;
+export declare const GTM_CONSENT_KEYS: readonly ["ad_storage", "analytics_storage", "ad_user_data", "ad_personalization", "functionality_storage", "security_storage", "personalization_storage"];
+export type GTMConsentKey = (typeof GTM_CONSENT_KEYS)[number];
+export type GTMConsentPayload = Record<GTMConsentKey, "granted" | "denied">;
+export declare const DEFAULT_GTM_CONSENT_DENIED: GTMConsentPayload;
+export declare const GTM_CONSENT_MAP: Record<ConsentCategory, readonly GTMConsentKey[]>;
+declare global {
+    interface Window {
+        __cookieConsent?: BannerConfig;
+        dataLayer?: any[];
+        gtag?: (...args: unknown[]) => void;
+        fbq?: (...args: unknown[]) => void;
+    }
+}

package/docs/consent-compliance.md

@@ -0,0 +1,142 @@
+# Konfiguracja zgód i informacji o prywatności
+
+Baner nie uruchamia opcjonalnego przetwarzania,
+jeżeli brakuje danych administratora, celu, wersji informacji lub poprawnego linku
+do polityki prywatności. Stare rekordy zgody są unieważniane. Odmowa działa także
+przy niedostępnym localStorage; opcjonalne zgody wymagają skutecznego zapisu.
+
+To mechanizmy wspierające zgodne wdrożenie. Nie są certyfikatem zgodności całej
+witryny ani oceną prawdziwości danych wpisanych przez jej administratora.
+
+## WordPress
+
+1. W „Banner & texts” wpisz rzeczywistą nazwę administratora, konkretne cele
+   opcjonalnego przetwarzania, URL opublikowanej polityki i jej wersję. Zmiana
+   celów, odbiorców lub polityki pod zewnętrznym URL wymaga zmiany wersji.
+   Zmiana treści lokalnej strony polityki oraz buildu bannera jest wykrywana automatycznie.
+2. Uruchom istniejący skaner. W „Services” sprawdź informacje o wykrytych
+   dostawcach: rzeczywisty cel na tej stronie, politykę dostawcy oraz okres
+   przechowywania danych lub kryteria jego określenia. Sugestie korzystają
+   z tej samej bazy i identyfikatorów co skaner i blokowanie, bez drugiej tabeli
+   cookies. Opisy bazy są sugestiami, nie potwierdzeniem konkretnego wdrożenia.
+3. Nierozpoznane lub nieopisane usługi pozostają zablokowane. Zarejestruj
+   własną integrację z jej URL-ami i pełnymi informacjami, zamiast zgadywać cel
+   nieznanej domeny. Zmiana integracji wymaga nowego identyfikatora usługi.
+4. Link `.open-consent-settings` i shortcode `[cookie_preferences_link]`
+   nadal działają. Kontrolka ustawień pozostaje widoczna; przy aktywnych zgodach
+   jest też bezpośredni przycisk wycofania wszystkich opcjonalnych zgód.
+5. Zachowaj blokowanie CSP, wyczyść stare cache HTML i sprawdź CDN/reverse proxy.
+   HTML zależny od zgód nie może być współdzielony między odwiedzającymi.
+
+Samo zaznaczenie kategorii nie zastępuje zgody na odrębnie pokazanego dostawcę.
+Nie należy oznaczać wszystkich „funkcjonalnych” cookies jako ściśle niezbędnych.
+Tabela cookies domyślnie pokazuje także nierozpoznane pozycje.
+
+## npm / Next.js
+
+Serwer i klient muszą używać tej samej `noticeVersion`. Uaktualniaj ją przy
+zmianach informacji, celów, odbiorców lub polityki. Bez wersji serwerowy helper
+pozostawia opcjonalne domeny zablokowane. Sam import JS nie zastąpi nagłówka HTTP
+CSP i nieaktywnych atrybutów SSR.
+
+```ts
+const noticeVersion = '2026-11-06.1';
+const config = {
+  mode: 'standalone', lang: 'pl', strictCsp: true, noticeVersion,
+  controller: {name: 'RZECZYWISTA NAZWA ADMINISTRATORA'},
+  purposes: 'Konkretne cele opcjonalnego przetwarzania na tej stronie.',
+  privacyPolicyUrl: '/polityka-prywatnosci',
+  services: [{
+    id: 'video', name: 'Dostawca filmu',
+    description: 'Konkretny cel i zakres integracji, w tym przekazywane dane.',
+    privacyUrl: 'https://video.example/privacy',
+    retention: 'Rzeczywisty okres lub kryteria usunięcia danych — po weryfikacji.',
+    urls: ['https://video.example/'],
+    cleanup: {cookies: ['video_session'], localStorage: ['video-id']},
+  }],
+};
+// Te dane są wzorem konfiguracji, nie gotową polityką konkretnej witryny.
+const headers = consentCspHeaders({noticeVersion, services: {
+  video: {'frame-src': ['https://video.example']},
+}}, request.headers.get('cookie') || '');
+```
+
+Dla usług z katalogu można ustawić `serviceDisclosures[id]` z polami
+`description`, `privacyUrl`, `retention` i opcjonalnym `cleanup`, bez powielania
+reguł rozpoznawania URL. Dotychczasowe `scripts.analytics` / `scripts.marketing`
+wymagają teraz `service` w każdym skrypcie; wykonanie wymaga zarówno zgody na
+kategorię, jak i daną usługę. API `setServiceConsent` wywołuj w odpowiedzi na
+świadomy wybór użytkownika, a nie podczas automatycznego startu aplikacji.
+
+## Zapis decyzji i dowody
+
+Przeglądarka zachowuje jeden aktualny rekord: losowy identyfikator decyzji, czas,
+kategorie, wybory dostawców, wersję i kopię pokazanych informacji. `getConsentReceipt()`
+i zdarzenie `cb:consent-receipt` udostępniają go integratorowi. Rekord może służyć
+powiązaniu decyzji z procesami własnego backendu; nie należy wysyłać dodatkowych
+identyfikatorów dostawcom bez potrzeby i odpowiedniej informacji.
+
+WordPress zapisuje minimalną kopię decyzji i wersjonowane informacje po stronie
+serwera, z czasem serwera i hashem runtime. Nie zapisuje w tym rekordzie IP,
+user-agenta ani trwałego identyfikatora odwiedzającego. Powtórzenie ID nie zmienia
+istniejącego dowodu. Krótkotrwały, solony skrót adresu służy osobno do ograniczania
+nadużyć endpointu i wygasa po minucie. Zapis nie jest podpisem użytkownika ani
+potwierdzeniem jego tożsamości.
+
+- `GET /wp-json/cookie4/v1/consent-receipts?offset=0`: eksport dla administratora,
+  100 pozycji na stronę, `nextOffset` wskazuje kolejną partię; wymaga zwykłego
+  uwierzytelnienia WordPress REST. Panel Diagnostics eksportuje ostatnie 100.
+- `POST` tego endpointu przyjmuje aktualną wersję i ściśle sprawdzone wybory;
+  wymaga nonce. Brak uprawnienia nie daje dostępu do eksportu.
+- Hook `cookie4_consent_recorded` pozwala administratorowi integrować własną
+  retencję lub archiwum. `cb:receipt-error` sygnalizuje klientowi błąd wysyłki;
+  lokalny pełny rekord pozostaje dostępny dla integratora.
+- Domyślna ważność wyboru i retencja dowodów wynoszą 180 dni. To ustawienie
+  produktu, nie uniwersalny termin ustawowy. Backendowy filtr
+  `cookie4_receipt_retention_days` pozwala ustalić 1–365 dni. Zasady retencji
+  muszą być opisane przez administratora. Usuwanie wykonuje też dzienny WP-Cron;
+  przy wyłączonym WP-Cron trzeba zapewnić jego uruchamianie na serwerze.
+
+## Wycofanie i ograniczenia techniczne
+
+Wycofanie natychmiast zaostrza CSP bieżącego dokumentu przed wywołaniem SDK
+i przeładowaniem, żeby zatrzymać także pingi consent-update i pagehide. Następnie
+aktualizuje decyzję, wyłącza elementy korzystające z subskrypcji,
+wysyła sygnały cofnięcia do używanego mechanizmu GTM/Meta i przeładowuje dokument
+z odmawiającym CSP. Zmiana w innej karcie również odświeża politykę. Stary grant
+serwerowy jest usuwany przed zmianami localStorage, aby inna karta nie odświeżyła
+się ze starym zezwoleniem. Przywrócenie strony z bfcache odświeża ścisłe CSP. Zmiana wersji informacji
+podczas ponownej inicjalizacji nawigacji klientowej również wymusza nowy dokument.
+
+Usuwane są tylko jawnie wskazane identyfikatory first-party. WordPress korzysta
+z nazw cookies sklasyfikowanych przez istniejący skaner jako analityczne lub
+marketingowe; należy zweryfikować tę klasyfikację. npm ma `cleanup` per dostawca
+oraz `categoryCleanup`. Nie usuwamy koszyka ani sesji strony „na wszelki wypadek”.
+HttpOnly i dane u dostawcy wymagają odpowiedniej obsługi serwera/dostawcy;
+przeglądarkowy JS nie ma uprawnień do ich dowolnego kasowania. Żądań już
+rozpoczętych przed wycofaniem nie da się cofnąć; aktywność obcego dokumentu iframe
+pozostaje ograniczeniem opisanym poniżej.
+
+Polityka CSP kontroluje żądania dokumentu strony, nie całą wewnętrzną aktywność
+zdalnego dokumentu iframe. Zgoda na osadzenie musi uwzględniać przetwarzanie tego
+dostawcy. Lokalne iframe i workery są domyślnie zablokowane, ponieważ ich własne dokumenty
+nie muszą dziedziczyć reguł sieciowych rodzica. Jawnie dopuszczone niezbędne
+workery lub ramki wymagają właściwych nagłówków także na ich odpowiedziach.
+Tracking first-party, proxy, backend, konfiguracja GTM, transfery poza
+EOG, rzeczywiste cele i pełny obowiązek informacyjny wymagają oceny konkretnej
+witryny. Kolory HEX z panelu dostają korektę kontrastu; zaawansowane kolory CSS
+podane w integracji własnej trzeba zweryfikować w jej rzeczywistym otoczeniu.
+
+Nie da się rzetelnie zamienić tych testów w gwarancję „100% zgodności każdej
+strony z RODO”. Podstawy: [PKE art. 399–400](https://eli.gov.pl/api/acts/DU/2024/1221/text.html),
+[RODO art. 4, 7, 12–13, 25 i rozdział V](https://eur-lex.europa.eu/legal-content/PL/TXT/?uri=CELEX:32016R0679),
+[raport EROD o bannerach](https://www.edpb.europa.eu/system/files/2023-01/edpb_20230118_report_cookie_banner_taskforce_en.pdf).
+
+### Styl przycisków
+
+WordPress: **Banner & texts → Consent button style**. Standardowy oznacza
+wypełnioną akceptację i obrysowaną odmowę; ścisły oznacza identyczne przyciski
+decyzji. Zapis preferencji ma neutralny styl. Ustawienie zmienia tylko wygląd,
+nie blokowanie, CSP ani wymagania zgody. Nazwy trybów nie stanowią oceny prawnej.
+W npm domyślną wartością `buttonStyle` jest `standard`. W WordPressie domyślną
+wartością jest `equal`.

package/docs/consent-integration.md

@@ -0,0 +1,262 @@
+# Integracja zgód: npm i WordPress
+
+Pakiet i wtyczka korzystają z jednego modelu zgód oraz rejestru rozpoznawania usług. Wyniki skanowania pozostają w istniejącym module `plugin/src/features/scanner` i dotychczasowych opcjach WordPressa. Nie ma drugiej tabeli cookies.
+
+[Wymagane informacje i konfiguracja zgód](consent-compliance.md).
+
+## Npm: kod własnej strony / Next.js
+
+Punkt wejścia: `@app4you/cookie-banner/native`. Sam import i funkcje generujące atrybuty są bezpieczne w SSR. Klient pobiera kod bannera dopiero podczas inicjalizacji. Dotychczasowy bundle IIFE pozostaje w `@app4you/cookie-banner` i `@app4you/cookie-banner/auto`.
+
+W komponencie serwerowym można od razu wygenerować nieaktywny iframe:
+
+```tsx
+import { blockedContentProps } from "@app4you/cookie-banner/native";
+
+export function Video() {
+  return <iframe
+    {...blockedContentProps("youtube", "https://www.youtube-nocookie.com/embed/VIDEO_ID")}
+    title="Film o naszej firmie"
+    width={800}
+    height={450}
+    allowFullScreen
+  />;
+}
+```
+
+W HTML nie ma `src`, tylko `data-cb-src`. Brak JS nie uruchomi dostawcy. Identyczne właściwości działają z Reactem i Preactem. Przykład w tym repo faktycznie korzysta z API: `src/demo.tsx`.
+
+Inicjalizacja po hydratacji, np. w jednym komponencie klientowym Next.js:
+
+```tsx
+"use client";
+import { useEffect } from "react";
+import { initializeConsent } from "@app4you/cookie-banner/native";
+
+export function ConsentProvider() {
+  useEffect(() => {
+    let cancelled = false;
+    let dispose: (() => void) | undefined;
+    initializeConsent({
+      mode: "standalone",
+      lang: "pl",
+      variant: "bar",
+      noticeVersion: "2026-11-06.1",
+      controller: {name: "RZECZYWISTA NAZWA ADMINISTRATORA"},
+      purposes: "Odtwarzanie opcjonalnych filmów przez zewnętrznego dostawcę.",
+      privacyPolicyUrl: "/polityka-prywatnosci",
+      services: [{
+        id: "youtube",
+        name: "YouTube",
+        description: "Odtwarzanie osadzonych filmów. Po zgodzie Google otrzyma adres IP i dane przeglądarki.",
+        privacyUrl: "https://policies.google.com/privacy",
+        retention: "Wpisz zweryfikowany okres lub kryteria usunięcia danych dla tego wdrożenia.",
+      }],
+    }).then(cleanup => {
+      if (cancelled) cleanup();
+      else dispose = cleanup;
+    });
+    return () => { cancelled = true; dispose?.(); };
+  }, []);
+  return null;
+}
+```
+
+Dla zwykłego skryptu użyj `blockedScriptProps("service-id", "https://provider.example/sdk.js")`. Skrypt inline również musi dostać te atrybuty i `type="text/plain"`. Nie przekazuj aktywnego `src` do `next/script`, preloadu ani frameworkowego komponentu, który sam rozpoczyna połączenie. Identyfikator usługi musi być taki sam w konfiguracji i atrybutach.
+
+Dla komponentu wykonującego żądania podczas montowania zastosuj `onServiceConsent` **przed jego zamontowaniem**:
+
+```ts
+import { onServiceConsent } from "@app4you/cookie-banner/native";
+
+const unsubscribe = onServiceConsent("support-chat", granted => {
+  if (granted) mountChat();
+  else unmountChat();
+});
+// Przy odmontowaniu właściciela: unsubscribe().
+```
+
+`mountChat()` powinno zawierać również import/uruchomienie SDK — nie importuj wcześniej modułu mającego efekty uboczne. Zarejestruj własną usługę w `services` z jej rzeczywistym celem i polityką. `urls` pozwala przypisać dokładne prefiksy URL (porównywane po origin i ścieżce), także własnych skryptów. Domyślnie natywna integracja nie zmienia prototypów przeglądarki; `autoBlock: true` włącza dodatkowy guard dla zewnętrznego, niekontrolowanego kodu.
+
+Dostępne są też `hasServiceConsent(id)` i `setServiceConsent(id, boolean)`. Wycofanie zgody przeładowuje dokument, ponieważ usunięcie znacznika script nie usuwa uruchomionych timerów i listenerów SDK. Zgody usług są niezależne od kategorii analityka/marketing.
+
+## WordPress
+
+Warstwy działania:
+
+1. `script_loader_tag`, `wp_inline_script_attributes`, `render_block`, `embed_oembed_html` przekształcają rozpoznane zasoby i kod powiązany z enqueue.
+2. Bufor całej odpowiedzi PHP obejmuje również surowe `echo`, iframe i rozpoznane inline loadery. Parser WP neutralizuje `src`, alternatywne adresy lazy load, srcset i odpowiednie wskazówki połączeń. Skrypty są `text/plain`.
+3. Synchronous bootstrap jest przenoszony na początek gotowego head, przed kod wydrukowany przed `wp_head`. Ma atrybuty wyłączenia optymalizacji dla popularnych loaderów.
+4. Guard przechwytuje natywne właściwości URL, `setAttribute`, wstawianie węzłów i typowe operacje HTML przed wywołaniem implementacji przeglądarki. Dodatkowo zatrzymuje rozpoznane opcjonalne żądania `fetch`, XHR i `sendBeacon`. Nieznane iframe są grupowane osobno według dostawcy/domeny i pozostają nieaktywne do uzupełnienia informacji; celu nieznanych skryptów nie zgadujemy.
+5. Runtime pokazuje lokalny boks bez zewnętrznej miniatury, aktywuje wyłącznie wybraną usługę i zachowuje kolejność odblokowywanych skryptów. Piksele śledzące i wskazówki połączeń nie dostają dużych widocznych boksów.
+6. Istniejący skaner rozróżnia zablokowany element od requestu zaobserwowanego w Performance API. Audyt administratora wymusza odmowę bez nadpisywania jego zapamiętanych wyborów.
+
+Własny kod WordPressa może emitować:
+
+```html
+<iframe hidden data-cb-service="youtube"
+  data-cb-src="https://www.youtube.com/embed/VIDEO_ID" title="Film"></iframe>
+<script type="text/plain" data-cb-service="custom-analytics"
+  data-cb-src="https://metrics.example/sdk.js"></script>
+```
+
+Filtr `cookie4_config` pozwala dodać `services` (ten sam format co npm) i ustawić `autoBlock: false` w razie konfliktu konkretnej witryny. To wyłącza dodatkowy guard; transformacja PHP pozostaje. Własne usługi oznaczone w HTML pozostają blokowane bez zgody niezależnie od obecności w bazie.
+
+Boksy dziedziczą rodzinę fontów i kolor tekstu strony, z kompaktowymi rozmiarami tekstu i przycisków. Tło oraz obramowanie są delikatnymi odcieniami bieżącego koloru, a YouTube ma lokalną ikonę odtwarzania bez pobierania miniatury. Strona może nadpisać zmienne CSS: `--cb-content-background`, `--cb-content-color`, `--cb-content-border`, `--cb-content-radius`, `--cb-content-primary`, `--cb-content-button-text` oraz klasę `.cb-content-placeholder`.
+
+## Bazy i aktualizacje
+
+- `plugin/includes/cookie-database.json`: istniejąca Open Cookie Database, zaktualizowana w miejscu — 2280 wpisów.
+- `plugin/includes/service-database.json`: dane Third Party Web — 2141 dostawców, 3132 wzorce domen.
+- `tracker-database.json`: niewielka warstwa dokładniejszych reguł produktów i metadanych (np. odróżnienie GA od kontenera GTM).
+- `database-sources.json`: wersje źródłowe; `bun run update:databases` odtwarza import. Aktualizacja rewizji jest świadomą zmianą kodu, bez pobierania bazy podczas wizyty użytkownika. Import nie wykonuje pobranego JS.
+- Licencje i atrybucja są w `plugin/NOTICE` oraz `plugin/licenses/`.
+
+Preferencje pokazują usługi skonfigurowane lub zaobserwowane na witrynie, a nie całą bazę. Trzeba zweryfikować rzeczywisty cel przetwarzania, administratorów i polityki nieznanych usług. Kategorie z bazy są wskazówką, a nie oceną prawną konkretnej konfiguracji.
+
+## Ograniczenia integracji
+
+Nie deklarujemy automatycznej pełnej zgodności całej witryny z RODO. Baza nie zna wszystkich celów; guard nie stanowi kompletnego firewalla przeglądarki. Nie obejmuje każdej ścieżki, np. Workerów, obcych realmów, wcześniej przechwyconych API, dowolnego `document.write`, zasobów CSS, Early Hints i serwerowego trackingu. Nie usuwa cudzych cookies HttpOnly ani cookies na domenie dostawcy. Te przypadki wymagają integracji u źródła i audytu docelowej strony.
+
+`testMode` i `autoAcceptAll` nie udzielają już zgód. Dotychczasowe zgody bez aktualnego rekordu wersji są uznawane za nieważne; nowy zapis ma wersję, czas i okres ważności 180 dni (wybór produktu, nie uniwersalny termin ustawowy). Google działa w Basic Consent Mode: GTM wymaga aktywnej zgody na usługę oraz cel, a przy odmowie nie jest ładowany. Tagi wewnątrz kontenera muszą nadal mieć poprawnie skonfigurowane wymagania zgód.
+
+
+## Strict network CSP (server integration)
+
+`@app4you/cookie-banner/native` exports server-safe `consentCspHeaders`,
+`buildConsentCsp` and `readCspConsent`. This is an HTTP policy, not a policy
+installed by a client effect. Apply it to the initial HTML response:
+
+```ts
+import { consentCspHeaders } from '@app4you/cookie-banner/native';
+
+const csp = {
+  noticeVersion: "2026-11-06.1", // Same value in the client config.
+  services: {
+    youtube: {
+      'script-src': ['https://www.youtube.com', 'https://s.ytimg.com'],
+      'frame-src': ['https://www.youtube.com', 'https://www.youtube-nocookie.com'],
+    },
+    analytics: {
+      'script-src': ['https://analytics.example.com'],
+      'connect-src': ['https://analytics.example.com'],
+    },
+  },
+};
+const headers = consentCspHeaders(csp, request.headers.get('cookie') || '');
+// Set every returned header on the HTML response. Preserve other Vary tokens.
+// Initialize the client banner with strictCsp: true and the same service IDs.
+```
+
+For Next.js, compute these headers in middleware/proxy for document routes;
+make the protected route/layout dynamic (`export const dynamic = 'force-dynamic'`)
+and bypass CDN/full-page caching. Remove external HTTP Link/103 Early Hints and
+HTML preconnect/prefetch hints; the helper disables DNS prefetch but cannot rewrite
+HTML or a proxy configuration. A static export cannot emit a different HTTP
+policy per visitor. Keep `blockedContentProps` / `blockedScriptProps` on optional
+resources, including server-rendered markup. `initializeConsent` belongs in a
+client effect; constructing response headers belongs on the server. The included
+
+The cookie `cb_csp_consent` contains only explicitly granted service IDs, expires
+in 180 days, and uses Path=/, SameSite=Lax and Secure on HTTPS. The server ignores
+unknown IDs; the cookie cannot add arbitrary origins. Every consent change reloads
+the document before the client dispatches integration activation. Cross-tab storage
+changes reload strict-CSP documents too. Serve one consent scope per host/path-root;
+applications sharing an origin must use a common service registry.
+
+Default policy: `default-src 'none'`, self-hosted resources, inline scripts/styles,
+data images/fonts; no external sources, objects or external form submissions.
+Service allowlists accept HTTPS origins only, optionally with a leading wildcard.
+`essential` allows explicitly reviewed necessary destinations. `allowEval: true`
+is an explicit optimizer compatibility escape hatch, not enabled by default.
+Inline scripts remain allowed for framework/WordPress compatibility: this is a
+network privacy policy, not a nonce-based XSS protection policy.
+
+## WordPress CSP and caches
+
+Strict CSP is enabled by default on frontend HTML, both as a response header and
+as the first head meta policy (the header enforces additional directives such as
+frame-ancestors). Registered service domains reuse the existing scanner registry;
+unknown destinations stay blocked. Unknown HTTPS iframe origins are registered
+for frame-src only from the actual HTML of the current response; consent cookies
+cannot invent a destination. Customize `cookie4_csp_services` with a map of
+service IDs to directive/origin arrays; use `cookie4_csp_essential` for necessary
+origins. `cookie4_strict_csp` controls the whole mode. `cookie4_csp_allow_eval` can
+force-disable the eval compatibility required by WP Rocket Delay JS, at the cost
+of disabling that loader's behavior. Eval is otherwise allowed only while that
+active optimizer has Delay JS enabled. LiteSpeed Delay JS instead needs local
+`blob:` scripts; `cookie4_csp_allow_blob_scripts` can override that compatibility
+exception. Neither exception adds an external network destination.
+
+The plugin sets private/no-store HTML, Vary: Cookie, DONOTCACHEPAGE and LiteSpeed
+no-cache controls, prevents LiteSpeed page-cache storage and WP Rocket HTML cache writes.
+It purges both optimizers on deployment/activation and regenerates Rocket config
+and Apache rules. Rocket's DONOTCACHEPAGE override is installed only when this
+plugin defined that constant itself; cache writes remain disabled independently.
+Local JS/CSS minification, combining and delay remain testable and active.
+External HTML resource hints are removed, HTTP Link hints removed, and DNS prefetch
+is disabled. Assets themselves remain cacheable.
+
+Deploy through plugin activation/admin or explicitly run
+`wp eval 'cookie4_csp_refresh_cache();'` **before reopening public traffic**. An
+already cached HTML response can be served before WordPress loads the updated
+plugin. Purge and bypass HTML at any additional CDN/reverse proxy/server cache;
+PHP cannot reconfigure an unidentified upstream system or remove 103 Early Hints
+it emits. Do not cache granted HTML variants, and do not let a CDN override no-store.
+The meta policy is defense in depth, not permission to ignore these requirements.
+
+CSP does not stop first-party tracking/proxy endpoints, server-to-server requests,
+ordinary user navigation, or control requests inside an allowed cross-origin
+iframe. YouTube's nested third-party dependencies become possible after YouTube
+consent. Review the chosen integration's whole purpose and vendor dependencies.
+This implementation does not itself establish legal compliance for a website.
+
+References: [MDN CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP),
+[WP Rocket caching](https://docs.wp-rocket.me/article/1528-page-caching).
+
+
+## WordPress administrator workspace
+
+The WordPress panel now has Overview, Banner & texts, Services, Cookies & scan,
+WordPress integration and Diagnostics sections. Banner and service drafts remain
+mounted when switching sections; the banner save indicator preserves edits made
+while an earlier save is in flight.
+
+Services can be registered through the panel with an ID, name, purpose, HTTPS URL
+prefixes and optional privacy policy URL. The same saved definitions feed scanner
+detection, HTML blocking, frontend service preferences and CSP. Built-in IDs cannot
+be overridden. To change an integration's purpose/destinations, create a new ID:
+the server retains a hash of prior definitions so deleting/recreating a service
+cannot reuse earlier consent for something different.
+
+Diagnostics exposes local prerequisites, detected cache adapters and known other
+active consent plugins. Its explicit homepage check fetches HTML without executing
+it and reports actual response headers for the administrator session; this does
+not replace anonymous full-site request testing. Native WordPress Site Health also
+shows these prerequisites and support information.
+
+The live banner preview uses a sandbox that cannot read/write the site's actual
+consent storage. It loads locally bundled assets; preview choices and changing
+appearance do not reset a real visitor's consent.
+
+### Te same funkcje poza WordPressem
+
+Rdzeń npm i wtyczka używają tych samych komponentów i mechanizmów zgody.
+W npm domyślny `buttonStyle: 'standard'` daje wypełnioną akceptację i obrysowaną
+odmowę. WordPress domyślnie wybiera `'equal'`, czyli jednakowy wygląd obu
+przycisków. Ustawienie dotyczy wyglądu przycisków.
+
+W konfiguracji npm dostępne są również `localizations`, `customTexts`,
+`serviceDisclosures`, `categoryCleanup`, `autoBlock: true`, `strictCsp: true`,
+`receiptEndpoint` i `receiptNonce`. CSP wymaga nagłówka z serwera aplikacji;
+przykład Next.js/SSR znajduje się w `docs/multilingual.md`.
+
+Z `@app4you/cookie-banner/native` można odczytać `getDetectedServices()` (zaobserwowane
+usługi z tego samego rejestru), `getConsentReceipt()` i korzystać z
+`hasServiceConsent`, `setServiceConsent`, `onServiceConsent` oraz nieaktywnych
+atrybutów `blockedContentProps` / `blockedScriptProps`.
+
+Panel, zapis w tabeli bazy danych WordPressa, WPML/Polylang i czyszczenie cache
+wtyczek są adapterami WordPressa. W innej aplikacji jej backend odbiera dowody przez
+`receiptEndpoint`, a ustawienia przekazuje się jako konfigurację npm. Sam pakiet
+przeglądarkowy nie tworzy bazy danych ani panelu administracyjnego hosta.

package/docs/deployment-security.md

@@ -0,0 +1,28 @@
+# Bezpieczny deployment i limity dowodów zgody
+
+## Przesyłanie do WordPressa
+
+Usunięto grunt-ftp-push i transport FTP. `grunt deploy` i `grunt dev:ssh` korzystają z rsync przez SSH; `grunt dev:ftp` jest wyłącznie aliasem do bezpiecznej ścieżki. Nie ma powrotu do zwykłego FTP. Wymagane są rsync, OpenSSH, klucz lub agent SSH i wcześniej zweryfikowany klucz serwera w known_hosts.
+
+```dotenv
+SSH_HOST=example.com
+SSH_USER=deploy
+SSH_PORT=22
+SSH_WP_PLUGINS_FOLDER_PATH=/var/www/wp-content/plugins
+```
+
+Ścieżka musi być bezwzględna, bez spacji i metaznaków powłoki. Stare FTP_HOST/FTP_USERNAME/FTP_PASSWORD nie uruchomią transmisji. BatchMode i StrictHostKeyChecking=yes powodują zatrzymanie przy braku uwierzytelnienia lub nieznanym/zmienionym kluczu. Potwierdź fingerprint niezależnym kanałem przed dodaniem klucza — samo pobranie przez ssh-keyscan nie jest weryfikacją.
+
+## WordPress.org SVN
+
+SVN_USERNAME i SVN_PASSWORD nadal działają. SVN 1.10+ odczytuje hasło przez --password-from-stdin, hasło nie trafia do argv ani konfiguracji Grunta i jest usuwane ze środowiska procesu potomnego svn. Polecenia uwierzytelniane nie przechodzą przez sh -c. Weryfikacja certyfikatu pozostaje włączona, cache hasła jest wyłączony. Hasło zawierające CR/LF jest odrzucane — stdin wymaga pojedynczej linii.
+
+## Publiczne dowody zgody
+
+Kategorie muszą zawierać dokładnie essential=true, analytics=boolean i marketing=boolean. Inne pola kategorii, zagnieżdżone payloady i skalary są odrzucane. Limit body: 16 000 bajtów; pełny zapis z informacjami administratora: 16 384 bajty. Długie konfiguracje przekraczające ten limit zwracają 413 i wymagają skrócenia informacji.
+
+Atomowe limity: 600 poprawnych żądań na minutę globalnie i 120 na minutę dla jednego z 256 stałych koszyków adresów. Koszyki mogą współdzielić limit; nie przechowują surowych adresów. Spóźnione żądanie nie może cofnąć okna czasu. Liczba liczników wynosi najwyżej 258 (capacity, minute, ip_0…ip_255).
+
+Domyślny budżet to 10 000 dowodów, zmieniany filtrem cookie4_receipt_max_records (zakres 1–100 000). Przy wyczerpaniu nowe dowody zwracają 503, a już zapisany identyfikator pozostaje idempotentny. W tym momencie wykonywane jest także usuwanie przeterminowanych dowodów, niezależnie od WP-Cron. Retencja nadal korzysta z cookie4_receipt_retention_days (domyślnie 180 dni). Frontend nadal emituje cb:receipt-error przy nieudanym zapisie serwerowym; należy monitorować ten sygnał i pojemność na witrynach o większym ruchu. Odmowa i cofnięcie zgody nie zależą od dostępności archiwum.
+
+Rezerwacja budżetu i zapis są jedną transakcją. Przerwanie procesu lub rollback nie zużywa miejsca. Usuwanie i zwalnianie budżetu również jest transakcyjne. Migracja przygotowuje licznik przed uruchomieniem nowej retencji; na MySQL wymaga InnoDB i w razie potrzeby konwertuje te dwie tabele. Przy błędzie migracji zapis jest odrzucany. Dotychczasowe dowody nie są przycinane ani usuwane z powodu samej migracji. Stare transients z poprzedniej wersji mogą pozostać do standardowego sprzątania WordPressa.