secret-resolver — secrets in site configs, at runtime.

Usage

Simple 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'

The key is resolved through all registered providers in priority order — first match wins.

Extended keys (provider-targeted)

# Direct vault lookup — bypasses cascade, goes to the "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 extraction: if a provider returns e.g. {"password":"s3cret","username":"admin"}, the sub-key password automatically extracts "s3cret". Simple keys (without :) keep working as before — fully backwards-compatible.

Works in all TYPO3 YAML files

%secret()% hooks into TYPO3’s central YamlFileLoader — not just site configurations. The placeholder works everywhere TYPO3 loads YAML:

• Site Configuration (config/sites/*/config.yaml)
• Form Framework YAML definitions
• Services.yaml (Dependency Injection)
• Any other YAML file loaded through TYPO3’s standard YAML loader

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:

Where we use this …

This package carries the secret handling in TYPO3 Kubernetes and is a mandatory building block for any setup that takes Open Source & Digital Sovereignty seriously — keys stay with you, not in the image. Managed variant: AI-Ready CMS as a Service.