Option 1: TYPO3 encryption key (default, zero configuration) 

This is the recommended default. nr-vault automatically derives a master key from TYPO3's built-in encryption key ( $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'] ).

No configuration required - nr-vault works immediately after installation.

Benefits:

• Zero setup - works out of the box
• Unique per TYPO3 installation
• Already secured by TYPO3's configuration protection

Option 2: Environment variable 

For containerized deployments or when you need explicit control:

1. Generate a master key:

   Generate master key

   openssl rand -base64 32

   Copied!

2. Set the environment variable:

   Set environment variable

   export NR_VAULT_MASTER_KEY="your-generated-key"

   Copied!

3. Configure the extension in Admin Tools > Settings > Extension Configuration:

   • masterKeyProvider: env
   • masterKeySource: NR_VAULT_MASTER_KEY

Option 3: Key file 

For maximum security, store the key in a file outside the web root:

openssl rand -base64 32 > /secure/path/vault.key
chmod 0400 /secure/path/vault.key

Configure the extension:

• masterKeyProvider: file
• masterKeySource: /secure/path/vault.key

See Master key providers for detailed information on each provider.

TYPO3 provider (default) 

Uses TYPO3's built-in encryption key to derive the master key. This is the recommended default because:

• Zero configuration: Works immediately after installation.
• No server access required: Ideal for users without shell access.
• Unique per installation: Each TYPO3 instance has its own key.
• Already secured: TYPO3's encryption key is already protected.

The master key is derived from the encryption key using HKDF-SHA256 with a nr-vault-specific context, ensuring it cannot be used to compromise other TYPO3 functionality.

// How it works internally
$masterKey = hash_hkdf(
    'sha256',
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'],
    32,
    'nr-vault-master-key'
);

File provider 

Store the master key in a file with restrictive permissions:

# Generate a new key
openssl rand -base64 32 > /secure/path/vault-master.key
chmod 0400 /secure/path/vault-master.key

Configure in extension settings:

• masterKeyProvider: file
• masterKeySource: /secure/path/vault-master.key

Environment provider 

Store the master key in an environment variable:

export NR_VAULT_MASTER_KEY="base64-encoded-key"

Configure in extension settings:

• masterKeyProvider: env
• masterKeySource: NR_VAULT_MASTER_KEY

This is ideal for containerized deployments where secrets are injected via environment variables.

Creating secrets 

1. Click Create Secret (+ button).

2. Fill in the form:

   Identifier

   Unique identifier for the secret (e.g., stripe_api_key).

   Value

   The secret value to encrypt.

   Description

   Optional description for documentation.

   Context

   Optional context for organization (e.g., payment).

   Allowed groups

   Backend user groups that can access this secret.

   Expiration

   Optional expiration date after which the secret becomes inaccessible.

3. Click Save.

Viewing and editing secrets 

Secrets are displayed with their metadata but not their values. Click Reveal to temporarily show a secret value.

vault:init 

Initialize the vault and generate a master key:

vendor/bin/typo3 vault:init

# Output as environment variable format
vendor/bin/typo3 vault:init --env

# Specify custom output location
vendor/bin/typo3 vault:init --output=/secure/path/vault.key

vault:store 

Create or update a secret:

# Interactive (prompts for value)
vendor/bin/typo3 vault:store stripe_api_key

# With all options
vendor/bin/typo3 vault:store payment_key \
  --value="sk_live_..." \
  --description="Stripe production key" \
  --context="payment" \
  --expires="+90 days" \
  --groups="1,2"

vault:retrieve 

Retrieve a secret value:

vendor/bin/typo3 vault:retrieve stripe_api_key

# Quiet mode for scripting
API_KEY=$(vendor/bin/typo3 vault:retrieve -q stripe_api_key)

vault:list 

List all accessible secrets:

vendor/bin/typo3 vault:list

# Filter by pattern
vendor/bin/typo3 vault:list --pattern="payment_*"

# JSON output for automation
vendor/bin/typo3 vault:list --format=json

vault:rotate 

Rotate a secret with a new value:

vendor/bin/typo3 vault:rotate stripe_api_key \
  --reason="Scheduled quarterly rotation"

vault:delete 

Delete a secret:

vendor/bin/typo3 vault:delete old_api_key \
  --reason="Service deprecated" \
  --force

vault:audit 

View the audit log:

# View recent entries
vendor/bin/typo3 vault:audit --days=7

# Filter by secret
vendor/bin/typo3 vault:audit --identifier=stripe_api_key

# Export to JSON
vendor/bin/typo3 vault:audit --format=json > audit.json

vault:rotate-master-key 

Rotate the master encryption key (re-encrypts all DEKs):

# Using old key from file, new key from current config
vendor/bin/typo3 vault:rotate-master-key \
  --old-key=/path/to/old.key \
  --confirm

# Dry run to simulate
vendor/bin/typo3 vault:rotate-master-key \
  --old-key=/path/to/old.key \
  --dry-run

vault:scan 

Scan for potential plaintext secrets in database:

vendor/bin/typo3 vault:scan

# Only critical issues
vendor/bin/typo3 vault:scan --severity=critical

# JSON for CI/CD
vendor/bin/typo3 vault:scan --format=json

vault:migrate-field 

Migrate existing plaintext field values to vault:

# Preview
vendor/bin/typo3 vault:migrate-field tx_myext_settings api_key --dry-run

# Execute
vendor/bin/typo3 vault:migrate-field tx_myext_settings api_key

vault:cleanup-orphans 

Remove orphaned secrets from deleted records:

vendor/bin/typo3 vault:cleanup-orphans --dry-run
vendor/bin/typo3 vault:cleanup-orphans --retention-days=30

VaultService 

Inject the VaultService to access secrets programmatically:

use Netresearch\NrVault\Service\VaultServiceInterface;

final class PaymentService
{
    public function __construct(
        private readonly VaultServiceInterface $vaultService,
    ) {}

    public function getApiKey(): ?string
    {
        return $this->vaultService->retrieve('stripe_api_key');
    }
}

$this->vaultService->store(
    identifier: 'payment_api_key',
    secret: 'sk_live_...',
    options: [
        'description' => 'Stripe production API key',
        'context' => 'payment',
        'groups' => [1, 2], // Backend user group UIDs
        'expiresAt' => time() + (86400 * 90), // 90 days
    ],
);

if ($this->vaultService->exists('stripe_api_key')) {
    $value = $this->vaultService->retrieve('stripe_api_key');
}

// Get all accessible secrets
$secrets = $this->vaultService->list();

// Filter by pattern
$paymentSecrets = $this->vaultService->list(pattern: 'payment_*');

Vault HTTP client 

Make authenticated API calls without exposing secrets to your code. The HTTP client is PSR-18 compatible. Configure authentication with withAuthentication(), then use standard sendRequest().

Inject VaultHttpClientInterface directly:

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Http\VaultHttpClientInterface;

final class ExternalApiService
{
    public function __construct(
        private readonly VaultHttpClientInterface $httpClient,
    ) {}

    public function fetchData(): array
    {
        // Configure authentication, then use PSR-18
        $client = $this->httpClient->withAuthentication(
            'api_token',
            SecretPlacement::Bearer,
        );

        $request = new Request('GET', 'https://api.example.com/data');
        $response = $client->sendRequest($request);

        return json_decode($response->getBody()->getContents(), true);
    }
}

Or access via VaultService:

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;

$client = $this->vaultService->http()
    ->withAuthentication('stripe_api_key', SecretPlacement::Bearer);

$request = new Request(
    'POST',
    'https://api.stripe.com/v1/charges',
    ['Content-Type' => 'application/json'],
    json_encode($payload),
);

$response = $client->sendRequest($request);

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;

// Bearer token
$client = $vault->http()
    ->withAuthentication('api_token', SecretPlacement::Bearer);
$response = $client->sendRequest(new Request('GET', $url));

// API key header (X-API-Key)
$client = $vault->http()
    ->withAuthentication('api_key', SecretPlacement::ApiKey);
$response = $client->sendRequest(new Request('GET', $url));

// Custom header
$client = $vault->http()
    ->withAuthentication('api_key', SecretPlacement::Header, [
        'headerName' => 'X-Custom-Auth',
    ]);
$response = $client->sendRequest(new Request('GET', $url));

// Basic authentication with separate secrets
$client = $vault->http()
    ->withAuthentication('service_password', SecretPlacement::BasicAuth, [
        'usernameSecret' => 'service_user',
    ]);
$response = $client->sendRequest(new Request('GET', $url));

// Query parameter
$client = $vault->http()
    ->withAuthentication('api_key', SecretPlacement::QueryParam, [
        'queryParam' => 'key',
    ]);
$response = $client->sendRequest(new Request('GET', $url));

Approach 1: Store vault identifier in settings (recommended) 

Store a vault reference in extension settings, resolve at runtime.

Advantages:

• Works with existing extension settings UI
• No schema changes required
• Secrets properly encrypted in vault
• Self-documenting vault: prefix

Extension settings template:

# cat=api; type=string; label=DeepL API Key (Vault Reference): Enter vault:your-secret-id
deeplApiKey = vault:

The admin enters a vault reference like vault:deepl_api_key (not the actual key).

The vault: prefix makes it clear this is a vault reference and enables validation. See ADR-009: Extension configuration secrets for the design rationale.

Service implementation:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

declare(strict_types=1);

namespace MyVendor\MyDeeplExtension\Service;

use Netresearch\NrVault\Configuration\VaultReference;
use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Service\VaultServiceInterface;
use TYPO3\CMS\Core\Configuration\ExtensionConfiguration;
use TYPO3\CMS\Core\Http\RequestFactory;

final class DeepLService
{
    private const API_URL = 'https://api-free.deepl.com/v2';

    private ?VaultReference $apiKeyRef = null;

    public function __construct(
        private readonly VaultServiceInterface $vault,
        private readonly RequestFactory $requestFactory,
        ExtensionConfiguration $extensionConfiguration,
    ) {
        $config = $extensionConfiguration->get('my_deepl_extension');
        $setting = (string) ($config['deeplApiKey'] ?? '');

        // Parse vault reference (validates format, extracts identifier)
        $this->apiKeyRef = VaultReference::tryParse($setting);
    }

    public function translate(string $text, string $targetLang): string
    {
        if ($this->apiKeyRef === null) {
            throw new \RuntimeException(
                'DeepL API key not configured. Enter vault:your-secret-id in extension settings.',
                1735900000
            );
        }

        $request = $this->requestFactory->createRequest('POST', self::API_URL . '/translate')
            ->withHeader('Content-Type', 'application/json')
            ->withBody(\GuzzleHttp\Psr7\Utils::streamFor(json_encode([
                'text' => [$text],
                'target_lang' => $targetLang,
            ])));

        // Secret resolved at use time, not config load time
        $response = $this->vault->http()
            ->withAuthentication($this->apiKeyRef->identifier, SecretPlacement::Bearer)
            ->withReason('DeepL translation request')
            ->sendRequest($request);

        $data = json_decode($response->getBody()->getContents(), true);
        return $data['translations'][0]['text'] ?? '';
    }
}

Setup steps:

1. Store the actual DeepL API key in vault:

   Via backend (recommended):

   1. Go to Admin Tools > Vault > Secrets
   2. Click + Create new
   3. Enter identifier: deepl_api_key
   4. Paste your DeepL API key into the secret field
   5. Optionally set owner and allowed groups
   6. Click Save

   Via CLI (alternative):

   Store API key via command line

   ./vendor/bin/typo3 vault:store deepl_api_key "your-deepl-api-key-here"

   Copied!

2. Configure extension setting with vault reference:

   Via backend:

   1. Go to Admin Tools > Settings > Extension Configuration
   2. Find your extension and expand it
   3. Enter the vault reference: vault:deepl_api_key
   4. Click Save
3. The service parses the vault: prefix and resolves the secret at use time.

Approach 2: Environment variable reference 

For containerized deployments, reference environment variables.

Extension settings template:

# cat=api; type=string; label=DeepL API Key (env var): Environment variable name containing the API key
deeplApiKeyEnvVar = DEEPL_API_KEY

Service implementation:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

declare(strict_types=1);

namespace MyVendor\MyDeeplExtension\Service;

use TYPO3\CMS\Core\Configuration\ExtensionConfiguration;
use TYPO3\CMS\Core\Http\RequestFactory;

final class DeepLService
{
    private const API_URL = 'https://api-free.deepl.com/v2';

    private string $apiKey;

    public function __construct(
        private readonly RequestFactory $requestFactory,
        ExtensionConfiguration $extensionConfiguration,
    ) {
        $config = $extensionConfiguration->get('my_deepl_extension');
        $envVar = (string) ($config['deeplApiKeyEnvVar'] ?? 'DEEPL_API_KEY');
        $this->apiKey = getenv($envVar) ?: '';
    }

    public function translate(string $text, string $targetLang): string
    {
        // Use TYPO3's RequestFactory directly with env-provided key
        $response = $this->requestFactory->request(
            self::API_URL . '/translate',
            'POST',
            [
                'headers' => [
                    'Authorization' => 'DeepL-Auth-Key ' . $this->apiKey,
                    'Content-Type' => 'application/json',
                ],
                'body' => json_encode([
                    'text' => [$text],
                    'target_lang' => $targetLang,
                ]),
            ]
        );

        $data = json_decode($response->getBody()->getContents(), true);
        return $data['translations'][0]['text'] ?? '';
    }
}

Approach 3: Configuration record with TCA vault field 

For maximum security and a proper backend UI, create a configuration record.

TCA definition:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

return [
    'ctrl' => [
        'title' => 'DeepL Configuration',
        'label' => 'name',
        'rootLevel' => 1,
        'security' => [
            'ignorePageTypeRestriction' => true,
        ],
    ],
    'columns' => [
        'name' => [
            'label' => 'Configuration Name',
            'config' => [
                'type' => 'input',
                'default' => 'Default',
            ],
        ],
        'api_key' => [
            'label' => 'DeepL API Key',
            'config' => [
                'type' => 'input',
                'renderType' => 'vaultSecret',
            ],
        ],
        'api_url' => [
            'label' => 'API URL',
            'config' => [
                'type' => 'input',
                'default' => 'https://api-free.deepl.com/v2',
            ],
        ],
    ],
    'types' => [
        '0' => ['showitem' => 'name, api_key, api_url'],
    ],
];

Repository to load configuration:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

declare(strict_types=1);

namespace MyVendor\MyDeeplExtension\Domain\Repository;

use MyVendor\MyDeeplExtension\Domain\Dto\DeepLConfig;
use TYPO3\CMS\Core\Database\ConnectionPool;

final class ConfigRepository
{
    public function __construct(
        private readonly ConnectionPool $connectionPool,
    ) {}

    public function findDefault(): ?DeepLConfig
    {
        $row = $this->connectionPool
            ->getConnectionForTable('tx_mydeeplext_config')
            ->select(['*'], 'tx_mydeeplext_config', ['deleted' => 0])
            ->fetchAssociative();

        return $row ? DeepLConfig::fromDatabaseRow($row) : null;
    }
}

DTO:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

declare(strict_types=1);

namespace MyVendor\MyDeeplExtension\Domain\Dto;

final readonly class DeepLConfig
{
    public function __construct(
        public int $uid,
        public string $name,
        public string $apiKey,  // Vault UUID
        public string $apiUrl,
    ) {}

    public static function fromDatabaseRow(array $row): self
    {
        return new self(
            uid: (int) $row['uid'],
            name: (string) $row['name'],
            apiKey: (string) $row['api_key'],
            apiUrl: (string) $row['api_url'],
        );
    }
}

Service using config record:

<?php

/*
 * Copyright (c) 2025-2026 Netresearch DTT GmbH
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

declare(strict_types=1);

namespace MyVendor\MyDeeplExtension\Service;

use MyVendor\MyDeeplExtension\Domain\Repository\ConfigRepository;
use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Service\VaultServiceInterface;
use TYPO3\CMS\Core\Http\RequestFactory;

final class DeepLService
{
    public function __construct(
        private readonly VaultServiceInterface $vault,
        private readonly RequestFactory $requestFactory,
        private readonly ConfigRepository $configRepository,
    ) {}

    public function translate(string $text, string $targetLang): string
    {
        $config = $this->configRepository->findDefault();
        if ($config === null) {
            throw new \RuntimeException('DeepL not configured', 1735900001);
        }

        $request = $this->requestFactory
            ->createRequest('POST', $config->apiUrl . '/translate')
            ->withHeader('Content-Type', 'application/json')
            ->withBody(\GuzzleHttp\Psr7\Utils::streamFor(json_encode([
                'text' => [$text],
                'target_lang' => $targetLang,
            ])));

        $response = $this->vault->http()
            ->withAuthentication($config->apiKey, SecretPlacement::Bearer)
            ->withReason('DeepL translation: ' . $targetLang)
            ->sendRequest($request);

        $data = json_decode($response->getBody()->getContents(), true);
        return $data['translations'][0]['text'] ?? '';
    }
}

Advantages of Approach 3:

• Full vault UI with masked input, reveal, copy buttons
• Proper access control (owner, groups)
• Audit logging of configuration access
• Multiple configurations possible (e.g., per site)

How it works 

1. Data Encryption Key (DEK): Each secret gets a unique 256-bit key generated using cryptographically secure random bytes.
2. Value encryption: The secret value is encrypted with its DEK using AES-256-GCM (or XChaCha20-Poly1305).
3. DEK encryption: The DEK is encrypted with the Master Key and stored alongside the encrypted value.
4. Decryption: To read a secret, first decrypt the DEK with the Master Key, then use the DEK to decrypt the value.

Benefits 

• Key rotation: Rotating the master key only requires re-encrypting DEKs, not the actual secret values.
• Blast radius: If a DEK is compromised, only one secret is affected.
• Performance: Bulk operations on secrets don't require the master key for each operation.

Provider security comparison 

TYPO3 provider (default, recommended for most users)

Security depends on TYPO3's encryption key protection. Suitable for environments where the encryption key is properly secured in settings.php. No additional configuration required.

File provider (recommended for high-security environments)

Allows storing the key outside the database and web root with strict permissions. Requires server access to configure.

Environment provider (recommended for containers)

Ideal for containerized deployments where secrets are injected at runtime. Follows 12-factor app methodology.

File storage recommendations 

When using the file provider:

1. Outside web root: Never store in publicly accessible directories.
2. Restrictive permissions: Use 0400 (read-only by owner).
3. Separate backup: Back up the master key separately from the database.
4. Access logging: Monitor access to the key file.
5. Key rotation: Rotate the master key periodically.

Hash chain integrity 

Audit log entries form a hash chain where each entry includes a hash of the previous entry. This provides:

• Tamper detection: Any modification to log entries breaks the chain.
• Completeness: Deleted entries are detectable.
• Non-repudiation: Actions cannot be denied after logging.

HMAC-keyed audit chain 

The audit hash chain is authenticated with HMAC-SHA256, using a key derived from the master key via HKDF (see ADR-023: Audit hash chain HMAC consideration). This provides adversarial tamper resistance in addition to tamper detection:

• Adversarial resistance: An attacker with database access but without the master key cannot forge valid HMAC values or recompute the hash chain.
• Cryptographic separation: The HMAC key is derived with a dedicated context string ("nr-vault-audit-hmac-v1"), ensuring independence from encryption key material.
• Backward compatibility: Legacy entries (epoch 0) created before the HMAC migration remain verifiable using the original SHA-256 algorithm. New entries (epoch 1+) use HMAC-SHA256.

Use the vault:audit-migrate-hmac command to migrate existing legacy entries to HMAC-SHA256. See vault:audit-migrate-hmac for details.

Custom storage adapters 

Implement VaultAdapterInterface to add new storage backends:

namespace MyVendor\MyExtension\Adapter;

use Netresearch\NrVault\Adapter\VaultAdapterInterface;
use Netresearch\NrVault\Domain\Model\Secret;

final class CustomAdapter implements VaultAdapterInterface
{
    public function getIdentifier(): string
    {
        return 'custom';
    }

    public function isAvailable(): bool
    {
        // Check if your backend is configured and reachable
    }

    public function store(Secret $secret): void
    {
        // Store secret in your backend
    }

    public function retrieve(string $identifier): ?Secret
    {
        // Retrieve secret from your backend
    }

    public function delete(string $identifier): void
    {
        // Delete from your backend
    }

    public function exists(string $identifier): bool
    {
        // Check if secret exists
    }

    public function list(?\Netresearch\NrVault\Domain\Dto\SecretFilters $filters = null): array
    {
        // List secret identifiers
    }

    public function getMetadata(string $identifier): ?array
    {
        // Get secret metadata
    }

    public function updateMetadata(string $identifier, array $metadata): void
    {
        // Update metadata
    }

    public function incrementReadCount(int $uid): void
    {
        // Increment read counter atomically
    }
}

Register in Services.yaml:

MyVendor\MyExtension\Adapter\CustomAdapter:
  tags:
    - name: nr_vault.adapter
      identifier: custom

Custom master key providers 

Implement MasterKeyProviderInterface for custom key sources:

namespace MyVendor\MyExtension\Crypto;

use Netresearch\NrVault\Crypto\MasterKeyProviderInterface;

final class VaultKeyProvider implements MasterKeyProviderInterface
{
    public function getIdentifier(): string
    {
        return 'hashicorp';
    }

    public function isAvailable(): bool
    {
        // Check if HashiCorp Vault is accessible
    }

    public function getMasterKey(): string
    {
        // Retrieve key from HashiCorp Vault
    }

    public function storeMasterKey(string $key): void
    {
        // Store key in HashiCorp Vault
    }

    public function generateMasterKey(): string
    {
        return random_bytes(32);
    }
}

Development setup 

Use DDEV for local development:

ddev start
ddev install-v14
ddev vault-init

Running tests 

# Unit tests
Build/Scripts/runTests.sh -s unit

# Functional tests
Build/Scripts/runTests.sh -s functional

Code quality 

# Code style (PHP-CS-Fixer)
Build/Scripts/runTests.sh -s cgl

# Static analysis (PHPStan)
Build/Scripts/runTests.sh -s phpstan

VaultService 

class VaultService

Fully qualified name

\Netresearch\\NrVault\\Service\VaultService

Main facade for vault operations.

retrieve ( string $identifier)

Retrieve a decrypted secret value.

returntype

string|null

store ( string $identifier, string $secret, array $options = []) : void

Create or update a secret.

exists ( string $identifier) : bool

Check if a secret exists and is accessible.

delete ( string $identifier, string $reason = '') : void

Delete a secret.

rotate ( string $identifier, string $newSecret, string $reason = '') : void

Rotate a secret with a new value.

list ( string $pattern = null) : array

List accessible secrets.

param string|null $pattern

Optional filter pattern.

getMetadata ( string $identifier) : array

Get metadata for a secret.

http ( ) : VaultHttpClientInterface

Get the Vault HTTP Client.

EncryptionService 

class EncryptionService

Fully qualified name

\Netresearch\\NrVault\\Crypto\EncryptionService

Envelope encryption implementation.

encrypt ( string $plaintext, string $identifier) : array

Encrypt a value using envelope encryption.

decrypt ( string $encryptedValue, string $encryptedDek, string $dekNonce, string $valueNonce, string $identifier) : string

Decrypt an envelope-encrypted value.

generateDek ( ) : string

Generate a new Data Encryption Key.

calculateChecksum ( string $plaintext) : string

Calculate value checksum for change detection.

reEncryptDek ( string $encryptedDek, string $dekNonce, string $identifier, string $oldMasterKey, string $newMasterKey) : array

Re-encrypt a DEK with a new master key (for master key rotation).

Usage examples 

use Netresearch\NrVault\Service\VaultServiceInterface;

class MyService
{
    public function __construct(
        private readonly VaultServiceInterface $vault,
    ) {}

    public function storeApiKey(string $apiKey): void
    {
        $this->vault->store(
            'my_extension_api_key',
            $apiKey,
            [
                'description' => 'API key for external service',
                'groups' => [1, 2], // Admin, Editor groups
                'context' => 'payment',
                'expiresAt' => time() + 86400 * 90, // 90 days
            ]
        );
    }
}

public function getApiKey(): ?string
{
    return $this->vault->retrieve('my_extension_api_key');
}

Vault HTTP client 

The vault provides a PSR-18 compatible HTTP client that can inject secrets into requests without exposing them to your code. Configure authentication with withAuthentication(), then use standard sendRequest().

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Http\VaultHttpClientInterface;

final class ExternalApiService
{
    public function __construct(
        private readonly VaultHttpClientInterface $httpClient,
    ) {}

    public function fetchData(): array
    {
        // Configure authentication, then use standard PSR-18
        $client = $this->httpClient->withAuthentication(
            'api_token',
            SecretPlacement::Bearer,
        );

        $request = new Request('GET', 'https://api.example.com/data');
        $response = $client->sendRequest($request);

        return json_decode($response->getBody()->getContents(), true);
    }
}

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;

$client = $this->vaultService->http()
    ->withAuthentication('stripe_api_key', SecretPlacement::Bearer);

$request = new Request(
    'POST',
    'https://api.stripe.com/v1/charges',
    ['Content-Type' => 'application/json'],
    json_encode($payload),
);

$response = $client->sendRequest($request);

use GuzzleHttp\Psr7\Request;
use Netresearch\NrVault\Http\SecretPlacement;

// Bearer authentication
$client = $this->vault->http()
    ->withAuthentication('stripe_api_key', SecretPlacement::Bearer);
$response = $client->sendRequest(
    new Request('POST', 'https://api.stripe.com/v1/charges', [], $body)
);

// Custom header
$client = $this->vault->http()
    ->withAuthentication('api_token', SecretPlacement::Header, [
        'headerName' => 'X-API-Key',
    ]);
$response = $client->sendRequest(
    new Request('GET', 'https://api.example.com/data')
);

// Basic authentication with separate credentials
$client = $this->vault->http()
    ->withAuthentication('service_password', SecretPlacement::BasicAuth, [
        'usernameSecret' => 'service_username',
        'reason' => 'Fetching secure data',
    ]);
$response = $client->sendRequest(
    new Request('GET', 'https://api.example.com/secure')
);

// Query parameter
$client = $this->vault->http()
    ->withAuthentication('api_key', SecretPlacement::QueryParam, [
        'queryParam' => 'key',
    ]);
$response = $client->sendRequest(
    new Request('GET', 'https://maps.example.com/geocode')
);

PSR-14 events 

The vault dispatches events during secret operations.

class SecretCreatedEvent

Fully qualified name

\Netresearch\NrVault\Service\SecretCreatedEvent

Dispatched when a new secret is created.

• getIdentifier(): The secret identifier.
• getSecret(): The Secret entity.
• getActorUid(): User ID who created it.

class SecretAccessedEvent

Fully qualified name

\Netresearch\NrVault\Service\SecretAccessedEvent

Dispatched when a secret is read.

• getIdentifier(): The secret identifier.
• getActorUid(): User ID who accessed it.
• getContext(): The secret's context.

class SecretRotatedEvent

Fully qualified name

\Netresearch\NrVault\Service\SecretRotatedEvent

Dispatched when a secret is rotated.

• getIdentifier(): The secret identifier.
• getNewVersion(): The new version number.
• getActorUid(): User ID who rotated it.
• getReason(): The rotation reason.

class SecretDeletedEvent

Fully qualified name

\Netresearch\NrVault\Service\SecretDeletedEvent

Dispatched when a secret is deleted.

• getIdentifier(): The secret identifier.
• getActorUid(): User ID who deleted it.
• getReason(): The deletion reason.

class SecretUpdatedEvent

Fully qualified name

\Netresearch\NrVault\Service\SecretUpdatedEvent

Dispatched when a secret value is updated (without rotation).

• getIdentifier(): The secret identifier.
• getNewVersion(): The new version number.
• getActorUid(): User ID who updated it.

class MasterKeyRotatedEvent

Fully qualified name

\Netresearch\NrVault\Service\MasterKeyRotatedEvent

Dispatched after master key rotation completes.

• getSecretsReEncrypted(): Number of secrets re-encrypted.
• getActorUid(): User ID who performed the rotation.
• getRotatedAt(): DateTimeImmutable of when rotation completed.

Options 

--output, -o

Path to store the master key file (default: configured path or var/vault/master.key).

--force, -f

Overwrite existing master key (dangerous - existing secrets become unrecoverable!).

--env, -e

Output key as environment variable format instead of file.

Example 

# Initialize with default location
vendor/bin/typo3 vault:init

# Specify custom key file location
vendor/bin/typo3 vault:init --output=/secure/path/vault.key

# Output as environment variable
vendor/bin/typo3 vault:init --env

Arguments 

identifier

Unique identifier for the secret.

Options 

--value=SECRET

The secret value (will prompt if not provided).

--description=TEXT

Optional description.

--context=CONTEXT

Optional context for permission scoping.

--expires=TIMESTAMP

Expiration timestamp or relative time (e.g., +90 days).

--groups=GROUPS

Comma-separated list of allowed backend user group IDs.

Example 

# Interactive (prompts for secret)
vendor/bin/typo3 vault:store stripe_api_key

# With options
vendor/bin/typo3 vault:store payment_key \
  --value="sk_live_..." \
  --description="Stripe production key" \
  --context="payment" \
  --expires="+90 days" \
  --groups="1,2"

Options 

--quiet, -q

Output only the secret value (for scripting).

Example 

# Display with metadata
vendor/bin/typo3 vault:retrieve stripe_api_key

# For use in scripts
API_KEY=$(vendor/bin/typo3 vault:retrieve -q stripe_api_key)

Options 

--pattern=PATTERN

Filter by identifier pattern (supports * wildcard).

--format=FORMAT

Output format: table (default), json, csv.

Example 

# List all secrets
vendor/bin/typo3 vault:list

# Filter by pattern
vendor/bin/typo3 vault:list --pattern="payment_*"

# JSON output for automation
vendor/bin/typo3 vault:list --format=json

Options 

--value=SECRET

The new secret value (will prompt if not provided).

--reason=TEXT

Reason for rotation (logged in audit).

Example 

vendor/bin/typo3 vault:rotate stripe_api_key \
  --reason="Scheduled quarterly rotation"

Options 

--reason=TEXT

Reason for deletion (logged in audit).

--force, -f

Skip confirmation prompt.

Example 

vendor/bin/typo3 vault:delete old_api_key \
  --reason="Service deprecated" \
  --force

Options 

--identifier=ID

Filter by secret identifier.

--action=ACTION

Filter by action (create, read, update, delete, rotate).

--days=N

Show entries from last N days (default: 30).

--limit=N

Maximum entries to show (default: 100).

--format=FORMAT

Output format: table (default), json.

Example 

# View recent audit log
vendor/bin/typo3 vault:audit --days=7

# Filter by secret
vendor/bin/typo3 vault:audit --identifier=stripe_api_key

# Export to JSON
vendor/bin/typo3 vault:audit --format=json > audit.json

Options 

--old-key=PATH

Path to file containing the old master key (defaults to current configured key).

--new-key=PATH

Path to file containing the new master key (defaults to current configured key).

--dry-run

Simulate the rotation without making changes.

--confirm

Required for actual execution (safety measure).

Example 

# Old key from file, new key from current config
vendor/bin/typo3 vault:rotate-master-key \
  --old-key=/secure/path/old-master.key \
  --confirm

# Both keys from files
vendor/bin/typo3 vault:rotate-master-key \
  --old-key=/path/to/old.key \
  --new-key=/path/to/new.key \
  --confirm

# Dry run to verify before actual rotation
vendor/bin/typo3 vault:rotate-master-key \
  --old-key=/path/to/old.key \
  --dry-run

Options 

--format, -f

Output format: table (default), json, or summary.

--exclude, -e

Comma-separated list of tables to exclude (supports wildcards).

--severity, -s

Minimum severity to report: critical, high, medium, low (default: low).

--database-only

Only scan database tables.

--config-only

Only scan configuration files.

The command detects:

• Database columns with secret-like names (password, api_key, token, etc.).
• Known API key patterns (Stripe, AWS, GitHub, Slack, etc.).
• Extension configuration secrets.
• LocalConfiguration secrets (SMTP password, etc.).

Severity levels 

critical

Known API key pattern detected (Stripe, AWS, etc.).

high

Password or private key column with non-empty value.

medium

Token or API key column with suspicious value.

low

Secret-like column name detected.

Example 

# Scan all sources
vendor/bin/typo3 vault:scan

# Output as JSON for CI/CD
vendor/bin/typo3 vault:scan --format=json

# Exclude cache tables
vendor/bin/typo3 vault:scan --exclude=cache_*,cf_*

# Only show critical issues
vendor/bin/typo3 vault:scan --severity=critical

Arguments 

table

Database table name (e.g., tx_myext_settings).

field

Field name containing plaintext values to migrate.

Options 

--dry-run

Show what would be migrated without making changes.

--batch-size, -b

Number of records to process per batch (default: 100).

--where, -w

Additional WHERE clause to filter records (e.g., pid=1).

--force, -f

Migrate even if field already contains vault identifiers.

--clear-source

Clear the source field after migration (set to empty string).

--uid-field

Name of the UID field (default: uid).

Example 

# Preview migration
vendor/bin/typo3 vault:migrate-field tx_myext_settings api_key --dry-run

# Migrate with specific records
vendor/bin/typo3 vault:migrate-field tx_myext_settings api_key --where="pid=1"

# Migrate and clear source field
vendor/bin/typo3 vault:migrate-field tx_myext_settings api_key --clear-source

Options 

--dry-run

Show what would be deleted without making changes.

--retention-days, -r

Only delete orphans older than this many days (default: 0).

--table, -t

Only check secrets for this specific table.

--batch-size, -b

Number of secrets to check per batch (default: 100).

Example 

# Preview orphan cleanup
vendor/bin/typo3 vault:cleanup-orphans --dry-run

# Only clean up orphans older than 30 days
vendor/bin/typo3 vault:cleanup-orphans --retention-days=30

# Clean up orphans for specific table only
vendor/bin/typo3 vault:cleanup-orphans --table=tx_myext_settings

Options 

--dry-run

Show what would be migrated without making changes.

Example 

# Preview migration
vendor/bin/typo3 vault:audit-migrate-hmac --dry-run

# Run the migration
vendor/bin/typo3 vault:audit-migrate-hmac

Step 1: Add dependency 

Add nr-vault as a dependency in your extension's composer.json:

{
    "require": {
        "netresearch/nr-vault": "^0.4"
    }
}

Step 2: Configure TCA field 

Use the vaultSecret renderType in your TCA configuration:

<?php
return [
    'ctrl' => [
        'title' => 'My Extension Settings',
        // ... other ctrl settings
    ],
    'columns' => [
        'api_key' => [
            'label' => 'API Key',
            'config' => [
                'type' => 'input',
                'renderType' => 'vaultSecret',
                'size' => 30,
            ],
        ],
    ],
];

Step 3: Add database column 

Add the column to your extension's ext_tables.sql:

CREATE TABLE tx_myext_settings (
    api_key varchar(255) DEFAULT '' NOT NULL
);

The column stores the vault identifier, not the actual secret.

Step 4: Retrieve secrets in code 

Use the VaultFieldResolver utility to retrieve actual secret values:

use Netresearch\NrVault\Utility\VaultFieldResolver;

class MyService
{
    public function callExternalApi(array $settings): void
    {
        // Resolve vault identifiers to actual values
        $resolved = VaultFieldResolver::resolveFields(
            $settings,
            ['api_key', 'api_secret']
        );

        // Now $resolved['api_key'] contains the actual secret
        $client->authenticate($resolved['api_key']);
    }
}

Available options 

resolveFields() 

Resolve specific fields in a data array:

$resolved = VaultFieldResolver::resolveFields(
    $data,           // Array with potential vault identifiers
    ['field1'],      // Fields to resolve
    false            // Throw on error (default: false)
);

resolve() 

Resolve a single vault identifier (UUID v7 format):

// TCA field identifiers use UUID v7 format
$secret = VaultFieldResolver::resolve('01937b6e-4b6c-7abc-8def-0123456789ab');

resolveRecord() 

Automatically resolve all vault fields in a record based on TCA:

$resolved = VaultFieldResolver::resolveRecord('tx_myext_settings', $record);

isVaultIdentifier() 

Check if a value is a vault identifier:

if (VaultFieldResolver::isVaultIdentifier($value)) {
    // This is a vault identifier
}

getVaultFieldsForTable() 

Get list of vault field names for a table:

$fields = VaultFieldResolver::getVaultFieldsForTable('tx_myext_settings');
// Returns: ['api_key', 'api_secret']

Data flow 

1. Form display: The VaultSecretElement renders an obfuscated password field with reveal/copy buttons.

2. Form submit: The DataHandlerHook intercepts the form data:

   • Extracts the secret value from the form.
   • Generates a UUID v7 identifier (time-ordered, unique).
   • Stores the secret in the vault with metadata (table, field, uid).
   • Saves only the UUID identifier to the database.
3. Runtime retrieval: Your code uses VaultFieldResolver to look up the actual secret from the vault using the UUID.

Identifier format 

TCA and FlexForm fields use UUID v7 identifiers:

01937b6e-4b6c-7abc-8def-0123456789ab

UUID v7 provides:

• Time-ordering: Better B-tree index performance in databases.
• Uniqueness: Collision-free without central coordination.
• Security: Does not expose table/field names in the identifier.

The source context (table, field, uid) is stored as metadata in the vault, not in the identifier itself.

Record operations 

• Create: New vault secret is stored automatically.
• Update: Secret is rotated (maintains audit trail).
• Delete: Vault secret is removed when record is deleted.
• Copy: Vault secret is copied to new record.

Access control 

Vault secrets inherit the access control of the record they belong to. If a backend user can edit the record, they can update the vault secret.

The reveal button requires explicit user action and is logged.

Audit trail 

All vault operations are logged:

• Secret creation.
• Secret reads (via reveal button).
• Secret updates.
• Secret deletion.

Review the audit log in the backend module under Admin Tools > Vault > Audit Log.

No plaintext in database 

Only vault identifiers are stored in your extension's database tables. The actual secrets are encrypted with AES-256-GCM in the vault.

Service Registry 

Services are centrally configured with:

• serviceId: stable identifier used by consuming code
• base URLs: allowed endpoint URLs
• security policy: allowed hosts, methods, path patterns, timeout caps
• credential binding: link to a Credential Set

Extensions never hardcode endpoints. They reference services by serviceId.

Credential Sets 

Credential Sets are typed wrappers over nr-vault secrets. They store encrypted JSON payloads containing all fields for a credential type:

Bearer Token:

{"token": "sk-abc123..."}

OAuth2 Client Credentials:

{
  "client_id": "my-client",
  "client_secret": "secret123",
  "token_url": "https://oauth.example.com/token",
  "scopes": ["read", "write"]
}

Supported credential types (MVP):

• Bearer Token
• API Key Header
• Basic Authentication
• OAuth2 Client Credentials

SecureHttpClient API 

Extensions call external services using a simple PHP API:

interface SecureHttpClientInterface
{
    public function request(
        string $serviceId,
        string $method,
        string $path,
        array $options = []
    ): SecureHttpResponse;
}

Request options:

• query: Query parameters
• headers: Additional headers (non-secret)
• json: JSON body
• body: Raw body
• timeout: Timeout override (clamped by policy)
• idempotencyKey: Optional idempotency key

Response:

$response->statusCode();  // int
$response->headers();     // array
$response->body();        // string
$response->json();        // array (throws on invalid JSON)

Policy enforcement 

All requests are validated against the service's security policy:

• Allowed hosts/base URLs: Requests can only go to configured endpoints
• Allowed methods: Restrict to GET, POST, etc.
• Allowed path patterns: Limit which paths can be called
• Private range blocking: Block access to private IPs, link-local, metadata endpoints
• Timeout caps: Maximum request duration
• Max body sizes: Prevent resource exhaustion

Audit logging 

Every outbound call is logged with metadata:

• serviceId, caller identity, timestamp
• method, path template, status code
• duration, bytes in/out
• error classification, correlation ID

Request/response bodies and secrets are never logged.

Secret protection 

Credentials are:

• stored encrypted at rest
• never exposed in PHP variables when using Rust transport
• redacted from all logs and debug output
• rotated centrally without code changes

PhpTransport (default) 

Uses PSR-18 or Symfony HttpClient. Works everywhere, no special requirements.

RustFfiTransport (optional) 

Rust-based transport that:

• decrypts credentials inside the Rust runtime
• makes HTTP requests without exposing secrets to PHP
• supports HTTP/2 and optional HTTP/3

Requires:

• Rust library installed separately
• PHP ffi.enable=preload configuration

See ADR-013: Rust FFI preload-only mode for security considerations.

SidecarTransport (future) 

For highest security requirements, a separate daemon process can provide stronger isolation. See ADR-016: Sidecar daemon option.

Option 1: Human-readable format 

Format: {table}__{field}__{uid} (e.g., tx_myext__api_key__42)

Pros:

• Human-readable, easy to understand
• Contains context about the secret's source

Cons:

• Exposes internal database structure
• Complex format for FlexForm fields
• Requires parsing logic
• Not suitable for non-TCA secrets

Option 2: UUID v4 (random) 

Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

Pros:

• Simple to generate
• Widely supported
• No information leakage

Cons:

• Random distribution causes poor B-tree index performance
• No time-ordering (debugging harder)
• Index fragmentation over time

Option 3: UUID v7 (time-ordered) 

Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx

Pros:

• Time-ordered (48-bit millisecond timestamp)
• Excellent B-tree index performance
• Timestamp aids debugging
• Collision-free with randomness
• RFC 9562 standardized

Cons:

• Slightly more complex generation
• Timestamp visible in identifier (minor information leak)

Option 4: GUID (Microsoft format) 

Similar to UUID v4 but with different byte ordering.

Pros:

• Familiar to Windows developers

Cons:

• Non-standard in Unix/Linux environments
• Same performance issues as UUID v4

UUID v7 generation 

private function generateUuid(): string
{
    // 48-bit timestamp in milliseconds
    $time = (int) (microtime(true) * 1000);
    $random = random_bytes(10);

    return sprintf(
        '%08x-%04x-7%03x-%04x-%012x',
        ($time >> 16) & 0xFFFFFFFF,
        $time & 0xFFFF,
        ord($random[0]) << 4 | ord($random[1]) >> 4 & 0x0FFF,
        (ord($random[1]) & 0x0F) << 8 | ord($random[2]) & 0x3FFF | 0x8000,
        (ord($random[3]) << 40) | (ord($random[4]) << 32)
            | (ord($random[5]) << 24) | (ord($random[6]) << 16)
            | (ord($random[7]) << 8) | ord($random[8]),
    );
}

UUID v7 validation 

Pattern used to validate UUID v7 identifiers:

private const string UUID_PATTERN =
    '/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i';

public static function isVaultIdentifier(mixed $value): bool
{
    if (!is_string($value) || $value === '') {
        return false;
    }

    return preg_match(self::UUID_PATTERN, $value) === 1;
}

Example identifiers 

Valid UUID v7 examples:

01937b6e-4b6c-7abc-8def-0123456789ab
01937b6f-0000-7000-8000-000000000000
01937b6f-ffff-7fff-bfff-ffffffffffff

The format components:

• Positions 1-8: Timestamp (high bits)
• Positions 10-13: Timestamp (low bits)
• Position 15: Version (always 7)
• Positions 16-18: Random data
• Position 20: Variant (8, 9, a, or b)
• Positions 21-23: Random data
• Positions 25-36: Random data

Positive 

• Excellent index performance: Time-ordered UUIDs append to indexes, avoiding random inserts and page splits.
• No structure leakage: Identifiers don't reveal table/field names.
• Unified format: Same identifier format for TCA fields, FlexForm fields, and manually managed secrets.
• Debuggable timestamps: Creation time can be extracted for diagnostics.
• RFC standardized: Future-proof, widely supported format.

Negative 

• No context in identifier: Cannot determine source table/field from identifier alone (use metadata instead).
• Timestamp visible: Minor information leak about creation time.

Risks 

• Clock skew on distributed systems could affect ordering (mitigated by random component).
• Migration from old format required for existing installations.

Option 1: Direct encryption with master key 

Encrypt each secret directly with the master key.

Pros:

• Simple implementation
• Single key to manage

Cons:

• Master key rotation requires re-encrypting ALL secrets
• Same key used for all secrets (higher exposure risk)

Option 2: Envelope encryption (DEK/KEK) 

Two-layer encryption: unique Data Encryption Key (DEK) per secret, encrypted with Master Key (KEK).

Pros:

• Master key rotation only re-encrypts DEKs (fast)
• Each secret has unique encryption key
• Industry-standard pattern (AWS KMS, Google Cloud KMS)

Cons:

• Slightly more complex implementation
• More data to store (encrypted DEK + nonces)

Encryption flow 

1. Generate unique DEK (32 bytes) for the secret
2. Generate two random nonces (12 or 24 bytes each)
3. Encrypt DEK with master key: encryptedDek = AEAD(DEK, masterKey, dekNonce)
4. Encrypt secret with DEK: encryptedValue = AEAD(secret, DEK, valueNonce)
5. Calculate SHA-256 checksum for change detection
6. Clear sensitive data from memory (sodium_memzero)
7. Store: encryptedValue, encryptedDek, dekNonce, valueNonce, checksum

Decryption flow 

1. Retrieve master key from provider
2. Decrypt DEK: DEK = AEAD_decrypt(encryptedDek, masterKey, dekNonce)
3. Decrypt secret: secret = AEAD_decrypt(encryptedValue, DEK, valueNonce)
4. Clear DEK and master key from memory
5. Return plaintext secret

Algorithm selection 

private function useAes256Gcm(): bool
{
    // Use AES-256-GCM if hardware acceleration available
    // Otherwise fall back to XChaCha20-Poly1305
    if (!sodium_crypto_aead_aes256gcm_is_available()) {
        return false;
    }

    return !$this->configuration->preferXChaCha20();
}

private function getNonceLength(): int
{
    return $this->useAes256Gcm()
        ? SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES      // 12 bytes
        : SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES;  // 24 bytes
}

Memory safety 

try {
    $dek = $this->generateDek();
    $encryptedValue = $this->encryptWithKey($plaintext, $dek, $valueNonce);
    // ... store encrypted data
} finally {
    sodium_memzero($dek);
    sodium_memzero($masterKey);
    sodium_memzero($plaintext);
}

Master key rotation 

With envelope encryption, rotating the master key is efficient:

public function reEncryptDek(
    string $encryptedDek,
    string $dekNonce,
    string $identifier,
    string $oldMasterKey,
    string $newMasterKey,
): array {
    // Decrypt DEK with old master key
    $dek = $this->decryptDek($encryptedDek, $dekNonce, $identifier, $oldMasterKey);

    // Re-encrypt DEK with new master key
    $newNonce = random_bytes($this->getNonceLength());
    $newEncryptedDek = $this->encryptWithKey($dek, $newMasterKey, $newNonce);

    sodium_memzero($dek);
    return ['encrypted_dek' => $newEncryptedDek, 'dek_nonce' => $newNonce];
}

Database storage 

encrypted_value mediumblob,           -- AEAD ciphertext + auth tag
encrypted_dek text,                   -- Base64-encoded encrypted DEK
dek_nonce varchar(24) NOT NULL,       -- Base64-encoded DEK nonce
value_nonce varchar(24) NOT NULL,     -- Base64-encoded value nonce
encryption_version int unsigned,      -- For algorithm migrations
value_checksum char(64) NOT NULL,     -- SHA-256 for change detection

Positive 

• Fast key rotation: Only DEKs re-encrypted, O(n) simple operations
• Unique keys per secret: Compromise of one DEK doesn't expose others
• Hardware acceleration: AES-256-GCM uses AES-NI when available
• Authenticated encryption: Tampering is detected and rejected
• Memory safety: Sensitive data cleared immediately after use

Negative 

• More storage: Each secret requires DEK + two nonces
• Complexity: Two-layer encryption requires careful implementation
• Algorithm migration: Changing algorithms requires re-encryption

Risks 

• Master key loss = all secrets unrecoverable (mitigate with secure backups)
• Memory-based attacks could capture keys during brief window of use

Option 1: Single hardcoded source 

Always derive from TYPO3's encryption key.

Pros:

• Zero configuration
• Always available

Cons:

• No separation between TYPO3 and vault security
• Cannot use external key management

Option 2: Pluggable provider system 

Interface-based providers with factory pattern for selection.

Pros:

• Flexible deployment options
• Enterprise integration (HashiCorp Vault, AWS KMS)
• Testable with mock providers

Cons:

• More complex configuration
• Multiple code paths to maintain

Provider interface 

interface MasterKeyProviderInterface
{
    public function getIdentifier(): string;
    public function isAvailable(): bool;
    public function getMasterKey(): string;
    public function storeMasterKey(string $key): void;
    public function generateMasterKey(): string;
}

TYPO3 provider (default) 

Uses HKDF-SHA256 to derive a vault-specific key from TYPO3's encryption key:

final class Typo3MasterKeyProvider implements MasterKeyProviderInterface
{
    private const int KEY_LENGTH = 32;
    private const string HKDF_INFO = 'nr-vault-master-key';

    public function getMasterKey(): string
    {
        $encryptionKey = $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'];

        return hash_hkdf(
            'sha256',
            $encryptionKey,
            self::KEY_LENGTH,
            self::HKDF_INFO,
        );
    }
}

The HKDF context string nr-vault-master-key ensures the derived key is unique to nr-vault even if other extensions use the same derivation pattern.

File provider 

Reads a 32-byte key from a file with strict permission requirements:

public function getMasterKey(): string
{
    $key = file_get_contents($this->keyPath);
    $key = trim($key);  // Remove trailing newlines

    // Handle base64-encoded keys
    if (strlen($key) !== self::KEY_LENGTH) {
        $decoded = base64_decode($key, true);
        if ($decoded !== false && strlen($decoded) === self::KEY_LENGTH) {
            return $decoded;
        }
    }

    return $key;
}

public function storeMasterKey(string $key): void
{
    file_put_contents($this->keyPath, base64_encode($key));
    chmod($this->keyPath, 0o400);  // Read-only for owner
}

Environment provider 

Reads key from environment variable (default: NR_VAULT_MASTER_KEY):

public function getMasterKey(): string
{
    $key = getenv($this->envVarName);

    if ($key === false || $key === '') {
        throw MasterKeyException::environmentVariableNotSet($this->envVarName);
    }

    // Handle base64-encoded keys
    $decoded = base64_decode($key, true);
    if ($decoded !== false && strlen($decoded) === self::KEY_LENGTH) {
        return $decoded;
    }

    return $key;
}

Factory with auto-detection 

public function getAvailableProvider(): MasterKeyProviderInterface
{
    // 1. Try explicitly configured provider
    $configured = $this->configuration->getMasterKeyProvider();
    if ($configured && $this->providers[$configured]->isAvailable()) {
        return $this->providers[$configured];
    }

    // 2. Fallback chain: typo3 -> env -> file
    foreach (['typo3', 'env', 'file'] as $id) {
        if ($this->providers[$id]->isAvailable()) {
            return $this->providers[$id];
        }
    }

    // 3. Return TYPO3 provider (will fail with clear error)
    return $this->providers['typo3'];
}

Configuration 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_vault'] = [
    'masterKeyProvider' => 'typo3',  // typo3, file, or env
    'masterKeySource' => 'NR_VAULT_MASTER_KEY',  // env var or file path
    'autoKeyPath' => 'var/secrets/vault-master.key',  // auto-generated key
];

Key rotation command 

# Dry run first
vendor/bin/typo3 vault:rotate-master-key --dry-run

# Execute rotation
vendor/bin/typo3 vault:rotate-master-key \
    --old-key=/path/to/old.key \
    --new-key=/path/to/new.key \
    --confirm

The rotation process:

1. Verify old key can decrypt existing secrets
2. Re-encrypt all DEKs with new master key (transactional)
3. Dispatch MasterKeyRotatedEvent
4. Update configuration to use new key

Positive 

• Zero-config default: Works immediately with TYPO3 installation
• Deployment flexibility: File/env for containers, external for enterprise
• Key separation: HKDF ensures vault key is distinct from TYPO3 key
• Atomic rotation: Database transaction ensures consistency
• Extensibility: Custom providers via interface implementation

Negative 

• Configuration complexity: Multiple options to understand
• Key synchronization: Multi-server deployments need key distribution

Risks 

• TYPO3 provider: Changing encryptionKey breaks vault access
• File provider: Key file backup and distribution challenges
• All providers: Master key loss = permanent data loss

Mitigation 

• Document backup procedures prominently
• Provide key export command for disaster recovery
• Log warnings when using derived keys in production

Option 1: Custom field type 

Create a completely new TCA field type.

Pros:

• Full control over behavior

Cons:

• Requires TCA rewrite for existing extensions
• Different behavior from standard fields

Option 2: FormEngine override 

Override the default input field rendering globally.

Pros:

• No TCA changes needed

Cons:

• Affects all input fields
• Difficult to target specific fields
• Potential conflicts

Option 3: Custom renderType with DataHandler hooks 

Provide a renderType for FormEngine and intercept saves via hooks.

Pros:

• Opt-in per field (add renderType: 'vaultSecret')
• Uses standard TYPO3 hook system
• Familiar pattern for TYPO3 developers

Cons:

• Requires TCA modification (but minimal)
• Two components to maintain (element + hook)

FormEngine element 

final class VaultSecretElement extends AbstractFormElement
{
    public function render(): array
    {
        // Render password field with:
        // - Masked display (dots)
        // - Reveal button (permission-based)
        // - Copy button (permission-based)
        // - Hidden field for vault identifier
    }
}

Registration in ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1735400000] = [
    'nodeName' => 'vaultSecret',
    'priority' => 40,
    'class' => VaultSecretElement::class,
];

DataHandler hook 

final class DataHandlerHook
{
    // Before save: Extract secret, generate UUID, queue for storage
    public function processDatamap_preProcessFieldArray(...): void
    {
        foreach ($this->getVaultFields($table) as $field) {
            if ($this->hasSecretValue($fieldArray, $field)) {
                $uuid = $this->generateUuid();
                $this->pendingSecrets[$table][$id][$field] = [
                    'uuid' => $uuid,
                    'value' => $fieldArray[$field]['value'],
                ];
                $fieldArray[$field] = $uuid;  // Store UUID in database
            }
        }
    }

    // After save: Store secrets with correct UID
    public function processDatamap_afterDatabaseOperations(...): void
    {
        foreach ($this->pendingSecrets[$table][$id] as $field => $data) {
            $this->vaultService->store($data['uuid'], $data['value'], [
                'metadata' => [
                    'table' => $table,
                    'field' => $field,
                    'uid' => $recordUid,
                    'source' => 'tca_field',
                ],
            ]);
        }
    }

    // Before delete: Remove associated secrets
    public function processCmdmap_preProcess(...): void;

    // After copy: Create new secrets for copied record
    public function processCmdmap_postProcess(...): void;
}

FlexForm hook 

Separate hook for FlexForm fields due to different data structure:

final class FlexFormVaultHook
{
    public function processDatamap_preProcessFieldArray(...): void
    {
        // Recursively scan FlexForm XML for vaultSecret fields
        // Same UUID-based approach as TCA fields
        // Store metadata: flexField, sheet, fieldPath
    }
}

TCA configuration 

Extensions add vault support with one line:

'api_key' => [
    'label' => 'API Key',
    'config' => [
        'type' => 'input',
        'renderType' => 'vaultSecret',  // This one line
        'size' => 30,
    ],
],

Helper for common patterns:

use Netresearch\NrVault\TCA\VaultFieldHelper;

'api_key' => VaultFieldHelper::getSecureFieldConfig('API Key'),

Data flow 

Form Display:
1. VaultSecretElement renders password field
2. If UUID exists, shows masked value with reveal option
3. JavaScript handles reveal/copy interactions

Form Submit:
1. DataHandlerHook.preProcess extracts secret value
2. Generates UUID v7 identifier (see ADR-001)
3. Sets field value to UUID (for database)
4. DataHandlerHook.afterDatabaseOperations stores secret in vault

Record Delete:
1. DataHandlerHook.processCmdmap_preProcess finds vault fields
2. Retrieves UUIDs from record
3. Deletes corresponding vault secrets

Record Copy:
1. DataHandlerHook.processCmdmap_postProcess detects copy
2. Retrieves source secrets by UUID
3. Creates new secrets with new UUIDs for copied record

Runtime resolution 

use Netresearch\NrVault\Utility\VaultFieldResolver;

// Resolve specific fields
$resolved = VaultFieldResolver::resolveFields($record, ['api_key']);

// Auto-detect vault fields from TCA
$resolved = VaultFieldResolver::resolveRecord('tx_myext_settings', $record);

Positive 

• Minimal migration: Add renderType to existing fields
• Familiar patterns: Standard FormEngine and DataHandler usage
• Full lifecycle: Handles all record operations automatically
• Audit trail: All operations logged with context metadata
• UUID portability: Secrets not tied to table structure

Negative 

• Two hooks required: Separate handling for TCA and FlexForm
• Runtime resolution: Application code must resolve UUIDs to values
• Learning curve: Developers must understand vault resolution

Risks 

• Hook execution order conflicts with other extensions
• FlexForm structure changes could break field detection

Mitigation 

• Use high priority for hooks
• Comprehensive test coverage for FlexForm parsing
• Clear documentation for resolution patterns

Option 1: TYPO3 page-based permissions 

Inherit permissions from the page tree where secrets are stored.

Pros:

• Familiar TYPO3 pattern
• Works with existing mount points

Cons:

• Secrets aren't naturally page-based
• Complex for cross-page secrets
• Inflexible for API-created secrets

Option 2: Custom ACL system 

Build a separate permission system specific to vault.

Pros:

• Maximum flexibility
• Could model complex scenarios

Cons:

• Learning curve for administrators
• Doesn't leverage existing TYPO3 knowledge
• More code to maintain

Option 3: Owner/Group model with TYPO3 integration 

Each secret has an owner (backend user) and allowed groups (backend groups).

Pros:

• Maps to TYPO3 concepts (users, groups)
• Simple mental model: "who owns it, who can access it"
• Familiar to Unix-style permissions

Cons:

• Less granular than full ACL
• No per-operation permissions (read vs write)

Permission model 

Access Decision Tree:

1. Is user a TYPO3 admin or system maintainer?
   → YES: ALLOW (full access)

2. Is user the secret's owner (owner_uid)?
   → YES: ALLOW (full access)

3. Is user a member of any allowed_groups?
   → YES: ALLOW (read/write access)

4. Is this a CLI/scheduler context with CLI access enabled?
   → YES: Check CLI access groups
   → Group matches: ALLOW

5. Is this frontend context with frontend_accessible=true?
   → YES: ALLOW (read only)

6. Default: DENY

Database schema 

-- Single owner
owner_uid int(11) unsigned DEFAULT 0 NOT NULL,

-- Multiple groups (many-to-many)
allowed_groups text,

-- Frontend access flag
frontend_accessible tinyint(1) unsigned DEFAULT 0 NOT NULL,

-- Permission scoping
context varchar(50) DEFAULT '' NOT NULL,
scope_pid int(11) unsigned DEFAULT 0 NOT NULL,

-- Many-to-many relation table
CREATE TABLE tx_nrvault_secret_begroups_mm (
    uid_local int(11) unsigned,    -- Secret UID
    uid_foreign int(11) unsigned,  -- Backend group UID
);

AccessControlService 

final readonly class AccessControlService implements AccessControlServiceInterface
{
    public function canRead(Secret $secret): bool
    {
        return $this->checkAccess($secret);
    }

    public function canWrite(Secret $secret): bool
    {
        return $this->checkAccess($secret);
    }

    public function canDelete(Secret $secret): bool
    {
        return $this->checkAccess($secret);
    }

    private function checkAccess(Secret $secret): bool
    {
        $backendUser = $GLOBALS['BE_USER'] ?? null;

        if ($backendUser === null) {
            return $this->checkCliAccess($secret);
        }

        // Admins and system maintainers have full access
        if ($backendUser->isAdmin() || $backendUser->isSystemMaintainer()) {
            return true;
        }

        // Owner has full access
        $userUid = (int) ($backendUser->user['uid'] ?? 0);
        if ($userUid === $secret->getOwnerUid()) {
            return true;
        }

        // Check group membership
        $userGroups = $backendUser->userGroupsUID ?? [];
        $allowedGroups = $secret->getAllowedGroups();

        return count(array_intersect($userGroups, $allowedGroups)) > 0;
    }
}