secret-resolver — Secrets in Site-Configs, zur Laufzeit.

Verwendung

Einfache Keys (Cascade-Resolution)

# config/sites/main/config.yaml
apiKey: '%secret(API_KEY)%'
dbPassword: '%secret(DB_PASSWORD)%'

# Inline in Strings:
dsn: 'mysql://user:%secret(DB_PASSWORD)%@db:3306/app'

Der Key wird durch alle registrierten Provider in Prioritätsreihenfolge aufgelöst — First Match Wins.

Erweiterte Keys (Provider-targeted)

# Direkter Vault-Lookup — umgeht Cascade, geht an den "vault"-Provider
dbPassword: '%secret(vault:kv-v2/database.password)%'
apiToken: '%secret(vault:transit/api_token)%'

# AWS Secrets Manager
dbPassword: '%secret(aws-sm:prod/database.password)%'

Format: %secret(provider:path/to/secret.subKey)%

Sub-Key-Extraktion: Liefert ein Provider z. B. {"password":"s3cret","username":"admin"}, extrahiert der Sub-Key password automatisch "s3cret". Einfache Keys (ohne :) funktionieren weiter wie bisher — vollständig rückwärtskompatibel.

Resolution-Cascade & Priorities

Bei einfachen Schlüsseln wie %secret(DB_PASSWORD)% wird der Schlüssel durch alle registrierten Provider in absteigender Priority-Reihenfolge gereicht. Der erste Treffer gewinnt; leere Werte und Dateien, die nur Whitespace enthalten, werden übersprungen.

Built-in Cascade

Erweiterte Schlüssel im Format %secret(provider:path/to/secret.subKey)% umgehen die Cascade und werden direkt an den genannten Provider geroutet. Rückgabewerte in JSON-Form lassen sich über den Sub-Key extrahieren: aus {"password":"s3cret","username":"admin"} liefert der Sub-Key password automatisch s3cret.

Priority-Guidelines

Aufgelöste Werte werden in cache.core abgelegt — identisch zu %env()%. Nach einer Secret-Rotation räumt vendor/bin/typo3 cache:flush den Cache.

Eigene SecretProvider entwickeln

Die Erweiterung ist auf Erweiterbarkeit ausgelegt. Jede TYPO3-Extension kann einen eigenen Provider beisteuern, ohne das Core-Paket zu ändern. Drei Schritte genügen.

Step 1: SecretProviderInterface implementieren

Der Provider liefert einen eindeutigen Namen für erweiterte Schlüssel, entscheidet über supports(), ob er die Auflösung versucht, und gibt in resolve() den Wert oder null zurück. Eine statische priority() bestimmt die Position in der Cascade.

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Infrastructure\Provider;

use Moselwal\SecretResolver\Domain\Contract\SecretProviderInterface;
use Moselwal\SecretResolver\Domain\ValueObject\SecretKey;

final readonly class VaultSecretProvider implements SecretProviderInterface
{
    public function __construct(
        private VaultClient $client,
    ) {}

    public function getName(): string
    {
        // Return a unique provider name for extended key format targeting.
        // Users can then write %secret(vault:kv-v2/db.password)%
        // Return '' to participate only in the cascade (simple keys).
        return 'vault';
    }

    public function supports(SecretKey $key): bool
    {
        if ($key->isExtended()) {
            $path = $key->getSecretPath() ?? $key->getKeyName();
            return $this->client->secretExists($path);
        }

        return $this->client->secretExists($key->lowerCase);
    }

    public function resolve(SecretKey $key): ?string
    {
        $path = $key->isExtended()
            ? ($key->getSecretPath() ?? $key->getKeyName())
            : $key->lowerCase;

        try {
            $value = $this->client->readSecret($path);
        } catch (\Throwable) {
            return null; // Fallback to next provider in cascade
        }

        return $value !== '' ? $value : null;
    }

    public static function priority(): int
    {
        // Higher priority = checked first.
        // Built-in: FileEnv=30, RunSecrets=20
        return 40;
    }
}

Step 2: Über Services.yaml registrieren

Manuelle Registrierung entfällt — TYPO3s DI-Container erkennt alle SecretProviderInterface-Implementierungen über das von dieser Extension konfigurierte _instanceof-Auto-Tagging. Voraussetzung ist, dass Ihre Extension das übliche Autowiring nutzt.

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  MyVendor\MyExtension\:
    resource: '../Classes/*'

Abhängigkeiten wie VaultClient werden automatisch injiziert, wenn sie im DI-Container Ihrer Extension verfügbar sind.

Step 3: Provider verwenden

Einfache Schlüssel laufen durch die Cascade; ein Provider mit Priority 40 wird vor den built-in-Providern befragt. Erweiterte Schlüssel routen direkt zum benannten Provider und unterstützen optionale Sub-Key-Extraktion aus JSON-Antworten.

# Simple key - goes through cascade (Vault at priority 40 is checked first)
apiKey: '%secret(API_KEY)%'

# Extended key - routes directly to Vault, extracts "password" from JSON response
dbPassword: '%secret(vault:kv-v2/database.password)%'

# Extended key - full secret path, no sub-key extraction
certificate: '%secret(vault:pki/issue/my-cert)%'

SecretKey-Properties

Die folgenden Properties stehen Providern auf dem übergebenen SecretKey-Value-Object zur Verfügung:

Setzen wir ein bei …

Dieses Paket trägt das Secret-Handling in TYPO3 Kubernetes und ist Pflicht-Bestandteil eines Setups, das Open Source & Digitale Souveränität ernst nimmt — Schlüssel bleiben bei Ihnen, nicht im Image. In der betreuten Variante: AI-Ready CMS as a Service.