Content-API und Medienbrücke

Zielbild

Das PIM bleibt die führende Quelle für Produkte, Artikel, Taxonomien und Assets. Kirby verwaltet redaktionelle Seiten und Layouts. Katalogdaten werden nicht als zweite Kopie in Kirby gespeichert, sondern vom Nuxt-Frontend serverseitig über die Content-API gelesen.

Für redaktionelle Bilder gibt es im Kirby-Panel die PIM-Mediathek. Dort können Redakteure nur ausdrücklich freigegebene PIM-Ordner durchsuchen. Ein ausgewähltes Asset wird nicht nach Kirby kopiert: Das Feld (pimmedia) speichert nur einen Verweis wie pim://ext:4970. Die Website löst ihn beim Anzeigen über ihren eigenen Server-Proxy auf und lädt das Bild in passender Größe aus dem PIM. Siehe CMS → Medien aus dem PIM.

Zugriffsschutz

• Token werden im PIM unter Systemverwaltung > API-Tokens erstellt.
• Profil Content-CMS besitzt nur content:catalog:read und content:media:read.
• Der Token steht ausschließlich in Umgebungsvariablen, nie in Kirby-Inhalten oder im Git-Repository.
• PIM-Ordner werden über Für Content-CMS freigeben veröffentlicht. Die Freigabe gilt für aktive Unterordner; inaktive Ordner bleiben gesperrt.
• Bildvorschauen laufen über einen angemeldeten Kirby-Proxy. Der PIM-Token wird daher nie an den Browser übertragen.

Konfiguration

Kirby benötigt ein Content-CMS-Token mit Katalog- und Medienrechten:

CONTENT_API_URL=https://admin.matev.eu/api/v1
CONTENT_API_TOKEN=<token-aus-dem-pim>

Der serverseitige Nuxt-Proxy verwendet einen separaten Token mit content:catalog:read. Der Token ist Teil der privaten Runtime-Konfiguration und darf niemals als NUXT_PUBLIC_* an den Browser ausgeliefert werden.

Kirby unterstützt zusätzlich CONTENT_API_VERIFY_TLS. In Produktion bleibt dieser Wert true; im lokalen DDEV mit selbst signiertem Zertifikat ist er false.

Der produktive Compose-Stack muss je Dienst den passenden Secret-Wert als CONTENT_API_TOKEN in den Container geben. Auf Stack-Ebene sollten dafür zwei getrennte Secrets verwendet werden, etwa CMS_CONTENT_API_TOKEN und STAGING_CONTENT_API_TOKEN. Anschließend müssen CMS und Staging neu gestartet werden.

Lokal liegen die getrennten Tokens in den von DDEV ignorierten Dateien cms/.ddev/config.local.yaml und staging/.ddev/config.local.yaml. Sie haben Dateirechte 0600 und gehören nicht ins Repository.

Hashing und Secret-Speicherung

Laravel Sanctum speichert ausgegebene API-Tokens serverseitig nur als SHA-256-Hash. Der Klartext wird genau einmal beim Erstellen ausgegeben. Das ist für die Prüfung eingehender Bearer-Tokens ideal.

Kirby und Nuxt müssen den Bearer-Token dagegen an die Content-API senden. Ein Hash ist dort nicht verwendbar, weil Hashing nicht umkehrbar ist. Der Klartext muss deshalb zur Laufzeit aus einem geschützten Secret Store kommen, zum Beispiel Docker Secrets, CI/CD-Secrets, SOPS/age oder einem Vault.

Laravel unterstützt mit env:encrypt und env:decrypt außerdem verschlüsselte Environment-Dateien. Der dafür notwendige Entschlüsselungsschlüssel muss separat als Deployment-Secret bereitgestellt werden; er darf nicht zusammen mit der verschlüsselten Datei committed werden. Für lokale DDEV-Entwicklung sind die gitignorierten config.local.yaml-Dateien einfacher und ausreichend.

API

Geschützte Endpunkte liegen unter /api/v1/content/*:

• products, articles, taxonomies
• media, media-folders
• media/{id}/preview, media/{id}/download

Die vorhandenen öffentlichen Endpunkte bleiben für bestehende Integrationen unverändert. Die neuen Endpunkte verwenden getrennte Contracts für Ordnerzugriff und Binärauflösung, damit Herkunft und Speicherort der Dateien nicht in Controllern oder Kirby-Code fest verdrahtet sind.