CSP in Hyvä einrichten: registerInlineScript und Co

1. Warum Hyvä von Haus aus auf eine strikte Content Security Policy setzt

CSP in Hyvä ist kein optionales Add-on, sondern eine bewusste Architekturentscheidung. Hyvä Themes verzichten komplett auf jQuery, Knockout.js und die Magento-UI-Components, arbeiten stattdessen mit schlanken phtml-Templates und Alpine.js direkt im Markup. Genau dieses Muster, viele kleine Inline-Skripte statt weniger großer Bundles, kollidiert ohne Gegenmaßnahme mit einer strikten Content Security Policy, die per Definition jede Skriptausführung blockiert, die nicht explizit erlaubt wurde. Wer CSP in Hyvä von Anfang an mitdenkt, vermeidet genau diesen Konflikt, statt ihn erst im Produktivbetrieb zu entdecken.

Der zweite Grund ist die reale Angriffsfläche von Magento-Shops. Checkout-Formulare, Kundenkonten und Zahlungsdaten machen Magento-Installationen zu einem lohnenden Ziel für Cross-Site-Scripting, und genau gegen diese Angriffsklasse ist eine Content Security Policy die wirksamste Browser-seitige Verteidigungslinie. Eine Content Security Policy in Hyvä, die durchgängig unsafe-inline erlaubt, um Entwicklungsaufwand zu sparen, hebt diesen Schutz faktisch wieder auf und reduziert die CSP auf ein Feigenblatt ohne echte Wirkung.

Der dritte Grund ist technischer Natur und betrifft direkt die Magento-Caching-Architektur. Klassische nonce-basierte CSP-Ansätze generieren pro Request einen neuen Zufallswert, was mit dem Full Page Cache kollidiert, sobald identisches HTML an mehrere Besucher ausgeliefert wird. CSP in Hyvä löst dieses Problem über einen Hash-basierten Mechanismus für Inline-Skripte, der in den folgenden Abschnitten im Detail erklärt wird und der Cache-Kompatibilität und strikte Policy gleichzeitig ermöglicht.

2. Wie Magento_Csp funktioniert: Policies, csp_whitelist.xml und der Report-Only-Modus

Das Kernmodul Magento_Csp ist seit Magento 2.3.5 fester Bestandteil des Core und liefert die komplette Infrastruktur, auf der CSP in Hyvä aufbaut. Es sammelt aus verschiedenen Quellen, Konfiguration, Events und deklarativen XML-Dateien, eine Liste erlaubter Quellen je Direktive (script-src, style-src, img-src und weitere) und rendert daraus den Content-Security-Policy-Header für jede Antwort. Storefront und Admin-Bereich werden dabei komplett getrennt konfiguriert, unter Stores > Konfiguration > Sicherheit > Content Security Policy, sodass eine striktere Policy im Checkout nicht automatisch den Admin-Bereich betrifft und umgekehrt.

Zwei Betriebsmodi sind für jede Einführung von CSP in Hyvä entscheidend: der Enforce-Modus, der Verstöße aktiv blockiert und über den Content-Security-Policy-Header ausgeliefert wird, und der Report-Only-Modus, der über Content-Security-Policy-Report-Only ausgeliefert wird, Verstöße nur protokolliert, aber nichts blockiert. Für jede produktive Einführung von Content Security Policy in Hyvä empfiehlt sich zunächst der Report-Only-Modus über mehrere Tage im echten Traffic, bevor auf Enforce umgeschaltet wird, weil sich so übersehene Quellen finden lassen, ohne dass Kunden im Checkout tatsächlich blockierte Skripte erleben.

Die eigentliche Freigabe zusätzlicher Quellen läuft über csp_whitelist.xml, eine deklarative XML-Datei, die pro Modul oder Theme eigene Policy-Ergänzungen definiert, ohne bestehende Konfiguration zu überschreiben. Magento merged beim Bootstrap alle gefundenen csp_whitelist.xml-Dateien zu einer einzigen effektiven Policy je Area. Damit lässt sich CSP in Hyvä modular pflegen: Jedes Modul, das eine externe Ressource benötigt, liefert seine eigene Freigabe mit, statt eine zentrale Konfigurationsdatei manuell zu pflegen.

3. Das registerInlineScript()-Pattern im Detail: HyvaCsp-ViewModel und Nonce-Mechanismus

Der Kern von CSP in Hyvä ist das HyvaCsp-ViewModel, das Hyvä Themes für exakt dieses Problem mitbringen: Wie erlaubt man ein einzelnes, statisches Inline-Skript, ohne die gesamte script-src-Direktive mit unsafe-inline für jedes beliebige Skript zu öffnen? Die Antwort ist ein Hash-basierter Ansatz. Beim Rendern eines Templates berechnet das ViewModel für jeden registrierten Skript-Block einen SHA-256-Hash über den exakten Inhalt zwischen den <script>-Tags und trägt diesen Hash als zusätzliche erlaubte Quelle in die script-src-Direktive der Response ein.

Dieser Hash-Mechanismus ist der entscheidende Unterschied zum klassischen Nonce-Ansatz, den Magento_Csp für dynamisch gerenderte Skripte im Kern-Framework ebenfalls unterstützt. Ein Nonce ist ein pro Request neu generierter Zufallswert, der sowohl im Response-Header als auch im nonce-Attribut des Skript-Tags erscheinen muss. Das funktioniert zuverlässig für unversionierte, dynamisch gerenderte Seiten, kollidiert aber mit dem Full Page Cache: Zwei Besucher, die dieselbe gecachte Kategorie-Seite ausgeliefert bekommen, würden unterschiedliche Nonce-Werte im Header erwarten, aber identisches HTML mit dem eingebrannten Nonce der ersten Anfrage sehen. Für CSP in Hyvä wäre das ein direkter Widerspruch zum zentralen Performance-Vorteil des Themes.

Der Hash eines identischen Skriptinhalts bleibt dagegen über beliebig viele Requests stabil, weil er ausschließlich vom Textinhalt zwischen den Tags abhängt, nicht vom Zeitpunkt der Anfrage. Genau deshalb ist registerInlineScript() Cache-kompatibel: Der Full Page Cache liefert dasselbe HTML mit demselben eingebetteten Skript aus, und der zugehörige Hash in der Policy bleibt für jede Auslieferung gültig. Das ViewModel wird dazu klassisch über Constructor Property Promotion und die Hyvä-ViewModel-Registry in ein Template eingebunden.

<?php

declare(strict_types=1);

namespace Mironsoft\Csp\ViewModel;

use Hyva\Theme\ViewModel\HyvaCsp;
use Magento\Framework\View\Element\Block\ArgumentInterface;

/**
 * ViewModel that exposes the HyvaCsp helper to a custom block/template pair
 * so inline scripts can be registered against the active CSP policy.
 */
final class NewsletterPopup implements ArgumentInterface
{
    /**
     * @param HyvaCsp $hyvaCsp Hyvä ViewModel handling inline script and style hash registration
     */
    public function __construct(
        private readonly HyvaCsp $hyvaCsp
    ) {
    }

    /**
     * Returns the HyvaCsp instance for direct use inside the phtml template.
     *
     * @return HyvaCsp
     */
    public function getHyvaCsp(): HyvaCsp
    {
        return $this->hyvaCsp;
    }
}

4. Eigene Inline-Skripte korrekt registrieren: Codebeispiel Schritt für Schritt

In der Praxis wird das HyvaCsp-ViewModel selten manuell wie oben injiziert, meist reicht der Standardweg über die Hyvä-ViewModel-Registry direkt im Template: $hyvaCsp = $viewModels->require(Hyva\Theme\ViewModel\HyvaCsp::class);. Danach steht die Instanz im gesamten Template zur Verfügung, und die feste Projektregel bei mironsoft.de lautet: Auf jeden <script>-Block folgt unmittelbar der Aufruf $hyvaCsp->registerInlineScript(). Diese Konvention ist keine Stilfrage, sondern notwendig, damit die Ausgabe des Aufrufs, ein unsichtbarer HTML-Kommentar mit dem berechneten Hash, an genau der richtigen Stelle im gerenderten Markup landet und Magento_Csp den zugehörigen Hash zuordnen kann.

Wichtig ist dabei die Reihenfolge: Der PHP-Aufruf muss den exakten, bereits final gerenderten Skriptinhalt sehen, deshalb steht er immer nach dem schließenden </script>-Tag, niemals davor. Wird nachträglich auch nur ein Leerzeichen im Skriptinhalt verändert, ändert sich der SHA-256-Hash, und die alte Freigabe wird ungültig, was in der Entwicklung sofort als CSP-Verstoß in der Konsole sichtbar wird. Das ist beabsichtigt: CSP in Hyvä verlässt sich bewusst auf diese Fragilität, weil sie garantiert, dass niemand unbemerkt den Inhalt eines freigegebenen Skripts austauschen kann, ohne dass die Policy das bemerkt.

Das folgende Beispiel zeigt das vollständige Muster in einem Hyvä-Template, exakt wie es in jeder mironsoft.de-Codebasis vorkommen muss, sobald ein Inline-Skript benötigt wird, etwa um einen Alpine-Store zu initialisieren, der Daten aus PHP übernimmt.

<?php
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
$stockThreshold = (int) $block->getData('low_stock_threshold') ?: 5;
?>
<div x-data="lowStockBanner()" x-show="isLowStock" class="rounded-lg bg-orange-50 p-3 text-sm">
  <span x-text="message"></span>
</div>

<script>
  // Alpine.js component reading a PHP-provided threshold, registered for CSP in Hyva
  function lowStockBanner() {
    return {
      isLowStock: false,
      message: '',
      threshold: <?= (int) $stockThreshold ?>,
      init() {
        this.isLowStock = window.productQty <= this.threshold;
        this.message = this.isLowStock ? 'Nur noch wenige Stueck verfuegbar' : '';
      }
    };
  }
</script>
<?= /* @noEscape */ $hyvaCsp->registerInlineScript() ?>

Fehlt am Ende dieser Aufruf, bleibt das Skript im Quellcode sichtbar, wird aber unter einer strikten Content Security Policy in Hyvä vom Browser stillschweigend nicht ausgeführt, ohne einen offensichtlichen PHP-Fehler zu erzeugen. Genau diese Klasse von Fehlern ist im Code-Review am schwersten zu erkennen und gehört deshalb in jede Checkliste vor dem Merge eines neuen Templates.

5. Externe Domains und Skripte über csp_whitelist.xml freigeben

Nicht jedes Skript ist Inline-Code aus dem eigenen Theme. Zahlungsanbieter, Tracking-Dienste und externe Widgets liefern ihren Code fast immer über ein <script src="https://...">-Tag von einer fremden Domain aus. Für diesen Fall greift der Hash-Mechanismus von registerInlineScript() nicht, weil der Inhalt des Skripts zur Build-Zeit gar nicht bekannt ist. Stattdessen muss die Quell-Domain selbst über csp_whitelist.xml in die script-src-Direktive aufgenommen werden, damit CSP in Hyvä das Nachladen überhaupt erlaubt.

Die Datei liegt üblicherweise unter etc/frontend/csp_whitelist.xml im jeweiligen Modul oder Theme und wird beim Cache-Aufbau eingelesen. Jede <policy> referenziert eine CSP-Direktive über die id, und jeder <value>-Eintrag darunter definiert eine erlaubte Quelle mit einem type-Attribut, üblicherweise host für eine Domain oder hash für statische Inhalte. Eine saubere Freigabe für einen Zahlungsanbieter wie im folgenden Beispiel gehört in jedes Modul, das eine Zahlungsmethode mit externem JavaScript-SDK anbindet.

<!-- app/code/Mironsoft/PaymentGateway/etc/frontend/csp_whitelist.xml -->
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <!-- Allow the payment provider SDK to be loaded and executed -->
        <policy id="script-src">
            <values>
                <value id="payment-sdk-host" type="host">https://js.payment-provider.example</value>
            </values>
        </policy>
        <!-- The provider's checkout iframe needs frame-src as well -->
        <policy id="frame-src">
            <values>
                <value id="payment-sdk-frame" type="host">https://checkout.payment-provider.example</value>
            </values>
        </policy>
        <!-- Requests triggered by the SDK (status polling) need connect-src -->
        <policy id="connect-src">
            <values>
                <value id="payment-sdk-api" type="host">https://api.payment-provider.example</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

Ein häufiger Fehler bei CSP in Hyvä: Entwickler geben nur script-src frei und wundern sich, warum das Zahlungswidget trotzdem nicht lädt, weil das eingebettete Checkout-Iframe zusätzlich frame-src und die internen Ajax-Aufrufe des SDKs connect-src benötigen. Eine vollständige Freigabe deckt deshalb immer alle Direktiven ab, die das Drittanbieter-Skript tatsächlich anspricht, nicht nur die naheliegende script-src-Direktive.

6. Alpine.js und CSP: Inline-Expressions, x-data und die unsafe-eval-Problematik

Alpine.js, das zentrale JavaScript-Framework in Hyvä, wertet Ausdrücke wie x-data="{ open: false }" oder x-show="open" zur Laufzeit direkt aus dem HTML-Attribut aus. Technisch geschieht das über einen internen new Function(...)-Aufruf, der den Ausdruck als JavaScript-Code interpretiert. Eine besonders strikte Content Security Policy in Hyvä, die unsafe-eval aus der script-src-Direktive vollständig entfernt, blockiert damit potenziell jede Alpine-Direktive im gesamten Theme, nicht nur einzelne Inline-Skripte.

In der Standardkonfiguration von Hyvä Themes ist unsafe-eval deshalb bewusst Teil der freigegebenen script-src-Direktive, weil Alpine ohne diese Erlaubnis schlicht nicht funktioniert. Wer eine noch striktere Policy anstrebt, kann auf den offiziellen CSP-kompatiblen Alpine-Build zurückgreifen, der Ausdrücke über einen eingeschränkten, eval-freien Parser auswertet statt über new Function(...). Der Umstieg erfordert allerdings, dass komplexere JavaScript-Ausdrücke in x-data-Attributen vermieden und stattdessen in benannte Alpine-Komponenten ausgelagert werden.

Für die meisten mironsoft.de-Projekte ist der pragmatische Weg, unsafe-eval gezielt nur für script-src zuzulassen und gleichzeitig alle anderen Direktiven so strikt wie möglich zu halten. So bleibt CSP in Hyvä praxistauglich, ohne dass jede Alpine-Komponente im Theme neu geschrieben werden muss, während Angriffsvektoren wie das Nachladen unautorisierter externer Skripte trotzdem zuverlässig blockiert werden.

7. CSP-Verstöße debuggen: Browser-Konsole, Report-Only-Modus und csp_report_uri

Der schnellste Einstieg beim Debuggen von CSP in Hyvä ist die Browser-Konsole: Jeder blockierte Aufruf erscheint dort als eigene Fehlermeldung mit der genauen Direktive, die verletzt wurde, und dem blockierten Skript oder der blockierten Ressource. Diese Meldungen sind der erste Anlaufpunkt, sobald ein Alpine-Widget nach einem Deployment plötzlich nicht mehr reagiert, obwohl der Code im Quelltext unverändert aussieht.

Für systematisches Debugging über einzelne Browser-Sessions hinaus liefert Magento_Csp einen eigenen Report-Endpunkt, der über den Report-Only-Modus konfiguriert wird. Statt nur zu blockieren, sendet der Browser bei jedem Verstoß automatisch einen JSON-Report an die konfigurierte csp_report_uri, inklusive der blockierten URI und der verletzten Direktive. Diese Reports lassen sich zentral sammeln und auswerten, statt auf einzelne Kunden-Support-Tickets zu warten, in denen ein defektes Formular gemeldet wird.

{
  "csp-report": {
    "document-uri": "https://www.mironsoft-shop.example/checkout/",
    "referrer": "",
    "violated-directive": "script-src-elem",
    "effective-directive": "script-src-elem",
    "original-policy": "default-src 'self'; script-src 'self' 'unsafe-eval' 'sha256-abc123...'; report-uri /csp/reports/store",
    "disposition": "report",
    "blocked-uri": "https://widgets.some-tracking-vendor.example/tag.js",
    "line-number": 42,
    "source-file": "https://www.mironsoft-shop.example/checkout/",
    "status-code": 200,
    "script-sample": ""
  }
}

An diesem Beispiel-Report lässt sich sofort ablesen, was zu tun ist: Die blocked-uri zeigt eine externe Tracking-Domain, die noch nicht in csp_whitelist.xml freigegeben ist. Für CSP in Hyvä ist der Report-Only-Modus deshalb kein Debugging-Werkzeug nur für die lokale Entwicklung, sondern gehört als dauerhafte Sicherheitsnetz-Option in produktive Staging-Umgebungen, bevor eine neue Freigabe in den Enforce-Modus übernommen wird.

8. Third-Party-Skripte (Tracking, Payment-Provider) CSP-konform einbinden

Tracking-Skripte wie Analytics-Tags oder Conversion-Pixel sind eine der häufigsten Quellen für CSP-Verstöße in produktiven Shops, weil sie oft nachträglich per Tag-Manager oder Marketing-Team eingebaut werden, ohne dass der Entwickler informiert wird. Für eine belastbare Content Security Policy in Hyvä muss deshalb jeder neue Third-Party-Dienst denselben Prozess durchlaufen wie ein internes Modul: Die tatsächlich benötigten Domains identifizieren, in csp_whitelist.xml eintragen und im Report-Only-Modus verifizieren, bevor der Dienst produktiv geschaltet wird.

Bei Payment-Providern kommt eine zusätzliche Schwierigkeit hinzu: Viele SDKs laden zur Laufzeit dynamisch weitere Sub-Domains nach, etwa für Betrugserkennung oder A/B-Tests innerhalb des Zahlungsflusses, die zum Zeitpunkt der Integration noch nicht dokumentiert sind. Für CSP in Hyvä empfiehlt sich hier, zunächst großzügig mit dem Report-Only-Modus zu arbeiten, alle tatsächlich auftretenden Domains über mehrere Tage im echten Checkout-Traffic zu sammeln, und erst danach eine minimale, aber vollständige Freigabeliste in den Enforce-Modus zu überführen.

Grundsätzlich gilt: Ein Wildcard-Eintrag wie https://*.example mag kurzfristig jeden Verstoß beheben, untergräbt aber den eigentlichen Zweck der Policy, weil er potenziell jede Subdomain des Anbieters freigibt, auch kompromittierte oder später zweckentfremdete. Für CSP in Hyvä gehört deshalb jede Third-Party-Domain einzeln benannt in die Whitelist, auch wenn das mehr Pflegeaufwand bedeutet als eine pauschale Freigabe.

9. Deployment-Checkliste: CSP zwischen Staging und Produktion konsistent testen

Ein typisches Muster in gewachsenen Magento-Projekten: Auf Staging läuft eine großzügigere Policy oder der Report-Only-Modus, auf Produktion eine strikte Enforce-Policy, und niemand hat die beiden Umgebungen zuletzt synchron getestet. Genau dann tauchen CSP-Verstöße erst nach dem Go-Live auf, wenn der Kunde im echten Checkout ein blockiertes Zahlungswidget meldet. Für zuverlässige CSP in Hyvä gehört ein Header-Vergleich zwischen beiden Umgebungen deshalb in jede Deployment-Checkliste.

Ein einfacher curl-Aufruf gegen beide Umgebungen zeigt sofort, ob die effektive Policy identisch ist. Nach jeder Änderung an csp_whitelist.xml ist zusätzlich ein expliziter Cache-Flush notwendig, weil die zusammengeführte Policy Teil des Konfigurations-Caches ist und sonst weiterhin die alte, gemergte Fassung ausgeliefert wird, selbst wenn die XML-Datei bereits aktualisiert wurde.

# Compare the effective CSP header between staging and production
curl -sI https://staging.mironsoft-shop.example/ | grep -i content-security-policy
curl -sI https://www.mironsoft-shop.example/ | grep -i content-security-policy

# After editing csp_whitelist.xml, always flush config and full page cache
bin/magento cache:flush config
bin/magento cache:flush full_page

# Verify Report-Only mode is disabled before going live with an enforced policy
bin/magento config:show csp/mode/storefront_mode

Vor jedem Go-Live einer neuen Third-Party-Integration gehört zusätzlich ein manueller Checkout-Durchlauf mit geöffneter Browser-Konsole zur Checkliste, weil automatisierte Tests CSP-Verstöße bei dynamisch nachgeladenen Skripten leicht übersehen. Erst wenn Staging und Produktion identische Header ausliefern und ein realer Checkout-Durchlauf ohne Konsolenfehler bleibt, gilt eine Änderung an CSP in Hyvä als deploy-bereit.

Die wichtigsten Situationen im direkten Vergleich: Die folgende Übersicht zeigt, wie sich typische Stolperfallen bei Content Security Policy in Hyvä von der empfohlenen Lösung unterscheiden.

10. Zusammenfassung

Eine saubere Umsetzung von CSP in Hyvä ist kein einzelner Konfigurationsschalter, sondern das Zusammenspiel mehrerer Bausteine: Magento_Csp liefert die Infrastruktur für Policies, Report-Only-Modus und Report-Endpunkt, das HyvaCsp-ViewModel übernimmt mit registerInlineScript() die Hash-basierte Freigabe eigener Inline-Skripte Cache-kompatibel, und csp_whitelist.xml regelt deklarativ, welche externen Domains überhaupt geladen werden dürfen. Wer diese drei Bausteine sauber trennt, statt sie mit einer pauschalen unsafe-inline-Freigabe zu umgehen, bekommt eine Policy, die tatsächlich schützt, statt nur formal zu existieren.

Der zweite entscheidende Punkt ist der Prozess: Content Security Policy in Hyvä gehört als fester Bestandteil in jede Deployment-Checkliste, mit Report-Only-Phase vor jedem Enforce-Rollout, mit Header-Vergleich zwischen Staging und Produktion, und mit einer klaren Regel für neue Third-Party-Skripte. Ohne diesen Prozess bleibt CSP in Hyvä ein einmaliges Setup, das beim nächsten unbedacht eingebauten Tracking-Pixel oder Zahlungswidget wieder bricht.

11. FAQ: CSP in Hyvä