The secret problem 

Your TYPO3 site integrates with Stripe, SendGrid, Google Maps, and a dozen other services. Where are those API keys right now?

Probably in one of these places:

• Plain text in LocalConfiguration.php (committed to git?)
• Unencrypted in a database field (visible in backups, exports, SQL injection)
• Hardcoded in extension configuration (accessible to every backend user)

If your database leaks, your secrets leak. If an intern gets backend access, they can see your payment credentials. If you need to rotate a compromised key, you're editing config files and redeploying.

There has to be a better way.

How secrets are typically stored 

Let's compare common approaches, from most to least secure:

The trade-off nobody talks about 

Notice something? All the "more secure" methods share the same operational pain:

• External services: Infrastructure cost, complexity, another system to maintain
• Environment variables: Need DevOps to change a value. Restart containers. No audit trail. "Who changed the Stripe key last Tuesday?" Good luck.
• Files outside webroot: Same deployment dance. No UI. No history.

And then there's plain text - which is what most TYPO3 extensions actually use.

Why nr-vault? 

nr-vault is the sweet spot between "no security" and "enterprise complexity":

The pitch: Enterprise-grade secret management without enterprise-grade complexity.

What is nr-vault? 

nr-vault is a TYPO3 extension providing:

Encryption at rest

Every secret is encrypted with its own key (envelope encryption - the same pattern used by AWS KMS and Google Cloud KMS). Even if your database leaks, secrets remain protected.

Runtime management

Create, update, rotate, and revoke secrets through the TYPO3 backend. No deployments. No config file editing. No container restarts.

Access control

Fine-grained permissions based on backend user groups. The marketing team can manage their Mailchimp key without seeing payment credentials.

Audit logging

Tamper-evident logs with hash chain verification. Know exactly who accessed what, when - for compliance and incident response.

Usage analytics

A backend dashboard surfaces stale, expired, never-rotated, and unused secrets - redaction candidates you can safely remove. Automated and manual reads are counted separately, so a secret revealed only by hand is not mistaken for one a running integration still depends on.

TYPO3-native integration

TCA field type, site configuration support, TypoScript integration, CLI commands. Works the way TYPO3 developers expect.

Use cases 

• Payment gateway credentials - Stripe, PayPal, Adyen API keys
• Email service authentication - SMTP passwords, Mailchimp, SendGrid tokens
• Third-party API keys - Google Maps, analytics, CRM integrations
• OAuth client secrets - with automatic token refresh via Vault HTTP Client
• Database credentials - connection strings for external systems
• Per-record credentials - different API keys per client in TCA records
• Multi-site secrets - site-specific configuration in multi-domain setups

Requirements 

• TYPO3 v13.4 LTS or v14.3 LTS
• PHP 8.2 or higher
• PHP sodium extension (bundled with PHP 8.2+)
• Composer-based TYPO3 installation

Requirements 

Before installing nr-vault, ensure your system meets these requirements:

• TYPO3 v13.4 LTS or v14.3 LTS.
• PHP 8.2 or higher.
• PHP sodium extension (usually included in PHP 8.2+).
• Composer-based TYPO3 installation.

Installation via Composer 

Install the extension using Composer:

composer require netresearch/nr-vault

Activate the extension 

After installation, activate the extension in the TYPO3 backend:

1. Go to Admin Tools > Extensions.
2. Find "nr-vault" in the list.
3. Click the activation icon.

Or use the command line:

vendor/bin/typo3 extension:activate nr_vault

Database schema 

Update the database schema to create the required tables:

vendor/bin/typo3 database:updateschema

This creates the following tables:

• tx_nrvault_secret - Stores encrypted secrets with metadata.
• tx_nrvault_secret_begroups_mm - Read-tier group relations.
• tx_nrvault_secret_writegroups_mm - Write-tier group relations.
• tx_nrvault_audit_log - Stores audit log entries with hash chain.

The chain tip anchor, the break-glass session and the per-sink delivery state live in core's sys_registry rather than in a table of their own.

Master key setup 

nr-vault requires a master encryption key to protect your secrets. There are four options, from simplest to most configurable:

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

Verify installation 

Verify the installation by listing secrets (should return empty if newly installed):

vendor/bin/typo3 vault:list

If the command executes without errors, the extension is properly configured.

You can also test by storing and retrieving a test secret. Note that this probe needs CLI access that is off by default: allowCliAccess must be on, and secret.reveal and secret.delete must be added to cliAllowedOperations, which excludes both. If you would rather not widen that for a smoke test, create and reveal a secret in the backend module instead — it exercises the same encrypt and decrypt path.

# Store a test secret (needs allowCliAccess; secret.create is in the default allowlist)
vendor/bin/typo3 vault:store test_secret --value="test-value"

# Retrieve it (additionally needs secret.reveal in cliAllowedOperations)
vendor/bin/typo3 vault:retrieve test_secret

# Clean up (additionally needs secret.delete in cliAllowedOperations)
vendor/bin/typo3 vault:delete test_secret --force

Extension configuration 

Configure nr-vault in Admin Tools > Settings > Extension Configuration.

AWS Secrets Manager 

CLI access 

External audit sinks 

The database table tx_nrvault_audit_log is the chain-authoritative audit sink. External sinks are additional, best-effort copies whose purpose is to put audit evidence somewhere a database-write attacker cannot reach.

Two properties are worth stating up front:

• A sink failure never fails the audited vault operation. Fan-out happens after the chain row has committed and after the audit lock has been released, so a slow or broken destination cannot roll back a secret operation or serialise every other vault call behind itself. Failures are logged, counted, and reported by vault:audit-verify.
• Only an external sink makes a full audit table reset detectable. See vault:audit-anchor for why the in-database hash chain structurally cannot catch a truncate-and-rebuild.

Under the hardened security profile (securityProfile = hardened), having no usable external sink is reported as a NO_EXTERNAL_SINK finding.

Master key providers 

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

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

export NR_VAULT_MASTER_KEY="base64-encoded-key"

vault secrets enable transit
vault write -f transit/keys/nr-vault-master

path "transit/encrypt/nr-vault-master" {
  capabilities = ["update"]
}

path "transit/decrypt/nr-vault-master" {
  capabilities = ["update"]
}

vault policy write nr-vault-transit nr-vault-transit.hcl
vault token create -policy=nr-vault-transit -period=768h

export VAULT_TOKEN="hvs...."

vendor/bin/typo3 vault:init

vendor/bin/typo3 vault:rotate-master-key

Access control 

Access to secrets is controlled by:

1. Ownership: The user who created the secret has full access.
2. Group membership: Secrets can be shared with backend user groups, in two tiers — allowed_groups grants read, write_groups grants read and write. Neither grants delete.
3. Admin access: Backend administrators have access to all secrets — unless the hardened profile withdrew that bypass via disableAdminOverride, after which an administrator holds only what their own groups grant.
4. CLI access: Configurable via allowCliAccess, narrowed by cliAllowedOperations.
5. Operation permissions: independently of all of the above, every privileged operation (secret.create, secret.rotate, secret.delete, secret.manage_policy, …) is granted per backend user group and asserted centrally. Passing the per-secret tiers never implies holding the operation. See Operation permissions.

Analytics thresholds 

These decide when the usage-analytics dashboard and the secrets.dead / secrets.never_rotated readiness controls flag a secret. They are reporting thresholds only — nothing expires or is deleted because of them.

Context-based scoping 

Organize secrets by context for easier management:

• payment - Payment gateway credentials.
• email - Email service API keys.
• api - Third-party API tokens.
• database - External database credentials.

Contexts are user-defined strings that help organize and filter secrets.

Site configuration integration 

Use the %vault(identifier)% syntax in site configuration files:

settings:
  payment:
    stripeSecretKey: '%vault(stripe_api_key)%'
  email:
    mailchimpKey: '%vault(mailchimp_key)%'

References are resolved on demand, in the reading context, via SiteConfigurationVaultProcessor — not automatically when the site configuration is loaded:

use Netresearch\NrVault\Configuration\SiteConfigurationVaultProcessor;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$site = $request->getAttribute('site');
$processor = GeneralUtility::makeInstance(SiteConfigurationVaultProcessor::class);
$config = $processor->processConfiguration($site->getConfiguration(), $site);
$stripeKey = $config['settings']['payment']['stripeSecretKey'];

This keeps sensitive values out of version control while allowing configuration through the standard TYPO3 site settings.

Frontend-accessible secrets 

By default, secrets cannot be resolved in frontend context (TypoScript). To allow a secret to be used in TypoScript:

1. Create the secret with frontend_accessible metadata.
2. Use the %vault(identifier)% syntax in TypoScript.

frontend_accessible says the secret may appear in a page; it does not say which placeholders get expanded. In a frontend request — and on the command line, unless frontendPlaceholderLegacyCli is on — the identifier must also be published through an admin-only source — the TypoScript setup array, the site configuration, plugin.tx_nrvault.frontendResolvableIdentifiers , or FrontendPlaceholderPolicyInterface::allowIdentifier() . Step 2 satisfies that on its own; an identifier used only in a Fluid template file or an eID handler needs one of the last two. See Which placeholders resolve in the frontend.

$this->vaultService->store(
    'google_maps_key',
    $apiKey,
    [
        'metadata' => [
            'frontend_accessible' => true,
        ],
    ],
);

Backend module 

Access the vault through the TYPO3 backend:

1. Go to Admin Tools > Vault.
2. The overview shows statistics and quick-start examples.
3. Navigate to Secrets to manage your secrets.

The overview also carries a Security Readiness panel: the active security profile, an "N of M controls passed" ratio, and the open findings with the risk each one carries and the command that fixes it. The detailed finding list requires the vault.configure permission, because it names this installation's concrete weak points; everyone else sees the profile badge and the ratio.

The panel and vault:doctor evaluate the same controls, so the module and a CI gate cannot disagree. Use the command for anything scheduled or automated — see Deployment gate.

Viewing and editing secrets 

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

Note

Revealing a secret creates an audit log entry.

Analytics 

The Analytics submodule gives administrators an at-a-glance view of secret usage and highlights secrets that may be safe to remove. Choose the evaluation window with the 30d / 90d / 180d / 365d selector at the top.

Key metrics 

Total secrets

Active (non-deleted) secrets in the vault.

Expired

Secrets whose expiration date has passed but that still exist.

Redaction candidates

Secrets flagged by at least one staleness rule (see below).

Frontend-accessible

Secrets marked frontend_accessible - review these with extra care.

Never rotated

Secrets that have never been rotated within the configured threshold.

Reads in window (automated / manual)

Read activity for the selected window, split into automated reads (CLI, scheduler, API) and manual reveals performed in the backend.

Redaction candidates 

The table lists every flagged secret together with the rule(s) that flagged it, its last read of any kind, the automated / manual read split for the window, and its age in days. Open deep-links straight to the secret record so you can review or delete it.

Secrets are flagged by these rules:

Dead

Never read and older than the threshold, or not read for a long time - the primary deletion candidate.

Expired

Past its expiration date but still present in the vault.

Never rotated

Older than the rotation threshold without ever having been rotated.

Automation-stale

Revealed manually but never read by automation. This is a review signal rather than a deletion signal: the secret may legitimately be used only through manual workflows. It is therefore never combined with Dead.

Note

The automated-versus-manual split is derived from the audit log (actor_type), so it reflects only reads recorded while audit logging was active. Reads in TYPO3 CLI context (console commands, scheduled jobs, queue workers) are recorded with actor type cli and count as automated, even though the CLI bootstrap authenticates the _cli_ backend user. The day thresholds are configurable — see staleNeverReadDays, staleNotReadDays and staleNeverRotatedDays.

Tip

To explore the dashboard with realistic, dated history on a development instance, seed demo secrets and audit events with the vault:seed-demo command (development context only).

Site configuration 

Reference secrets in your site configuration files using the %vault(identifier)% syntax:

settings:
  payment:
    stripePublicKey: 'pk_live_...'
    stripeSecretKey: '%vault(stripe_secret_key)%'
  email:
    mailchimpApiKey: '%vault(mailchimp_api_key)%'
    sendgridToken: '%vault(sendgrid_token)%'

References are not resolved automatically when TYPO3 loads the site configuration. Resolve them explicitly, at the point of use, with SiteConfigurationVaultProcessor :

use Netresearch\NrVault\Configuration\SiteConfigurationVaultProcessor;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$site = $request->getAttribute('site');
$processor = GeneralUtility::makeInstance(SiteConfigurationVaultProcessor::class);
$config = $processor->processConfiguration($site->getConfiguration(), $site);
$stripeSecret = $config['settings']['payment']['stripeSecretKey'];

This keeps sensitive values out of your version control while still allowing you to configure them through the familiar site settings.

TypoScript integration 

Use vault references in TypoScript for frontend-accessible secrets:

lib.googleMapsKey = TEXT
lib.googleMapsKey {
  value = %vault(google_maps_api_key)%
  stdWrap.cache.disable = 1
}

page.headerData.10 = TEXT
page.headerData.10 {
  value = <script>var API_KEY = '%vault(public_api_key)%';</script>
  stdWrap.cache.disable = 1
}

plugin.tx_nrvault.frontendResolvableIdentifiers = my_api_key, public_widget_token

use Netresearch\NrVault\Security\FrontendPlaceholderPolicyInterface;
use TYPO3\CMS\Core\Utility\GeneralUtility;

// $request is the PSR-7 request your handler received.
GeneralUtility::makeInstance(FrontendPlaceholderPolicyInterface::class)
    ->allowIdentifier('my_api_key', $request);

CLI commands 

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

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

# With options (arbitrary metadata via repeatable --metadata key=value)
vendor/bin/typo3 vault:store payment_key \
  --value="sk_live_..." \
  --metadata="description=Stripe production key" \
  --metadata="context=payment" \
  --groups="1,2"

vendor/bin/typo3 vault:retrieve stripe_api_key

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

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

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

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

vault:audit 

View the audit log:

View audit log

# View entries since a given date
vendor/bin/typo3 vault:audit --since=2026-05-01

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

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

Copied!

Verify the tamper-evident chain:

Verify audit chain integrity

vendor/bin/typo3 vault:audit --verify

Copied!

The output ends with a Tip anchor: line. The anchor is what detects removal of the end of the log — a truncation leaves no gap and no broken link, so the chain walk alone cannot see it (see Tip anchor (truncation detection)).

ok

The anchored entry is still present and unchanged.

NOT ARMED

No anchor recorded yet. It arms itself on the next audit log write.

VIOLATED

The anchored entry is gone or was replaced — the log was truncated or wiped. Snapshot the table before changing anything else.

UNREADABLE

The stored anchor is malformed or its MAC does not verify — a tampered value, or a master key changed without a re-seal. Treated as critical regardless of auditAnchorRequired, and never resolved by clearing the anchor before you know which of the two it was.

Three further states appear in narrower situations: not checked (a range-bounded verification, which does not evaluate the anchor at all), disabled (auditHmacEpoch = 0, where the anchor does not run), and inconclusive (a re-seal committed while verification was reading — re-run it).

After a wipe or purge you performed deliberately, clear the anchor so it can arm again. The reset is itself written into the chain:

Re-arm the anchor after a deliberate wipe

vendor/bin/typo3 vault:audit --reset-anchor

Copied!

# 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

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

# 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

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

PHP API 

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_*');

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);
    }
}

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));

Step 1: Define the TCA table 

<?php

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

return [
    'ctrl' => [
        'title' => 'API Endpoints',
        'label' => 'name',
    ],
    'columns' => [
        'name' => [
            'label' => 'Name',
            'config' => ['type' => 'input', 'required' => true],
        ],
        'url' => [
            'label' => 'API Base URL',
            'config' => ['type' => 'input', 'required' => true],
        ],
        'token' => [
            'label' => 'API Token',
            'config' => [
                'type' => 'input',
                'renderType' => 'vaultSecret',
            ],
        ],
    ],
];

Creating an API endpoint record (backend):

1. Go to List module and select your storage folder
2. Click + Create new record and select API Endpoint

3. Fill in the form:

   • Name: Stripe
   • API Base URL: https://api.stripe.com/v1
   • API Token: Paste your actual API key (stored securely in vault)
4. Click Save

The token field uses renderType: 'vaultSecret' which:

• Shows a masked password field with a reveal button — and a copy button outside the hardened profile, which disables copying because the clipboard outlives the dialog
• Automatically stores the secret in the vault on save
• Stores only a UUID v7 reference in the database

What gets stored in the database:

SELECT uid, name, url, token FROM tx_myext_apiendpoint;
-- | uid | name   | url                       | token                                |
-- |-----|--------|---------------------------|--------------------------------------|
-- | 1   | Stripe | https://api.stripe.com/v1 | 01937b6e-4b6c-7abc-8def-0123456789ab |

Step 2: Create a DTO for type safety 

<?php

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

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Dto;

final readonly class ApiEndpoint
{
    public function __construct(
        public int $uid,
        public string $name,
        public string $url,
        public string $token,  // Contains vault UUID, not the secret
    ) {}

    /**
     * @param array<string, mixed> $row
     */
    public static function fromDatabaseRow(array $row): self
    {
        return new self(
            uid: (int) $row['uid'],
            name: (string) $row['name'],
            url: (string) $row['url'],
            token: (string) $row['token'],
        );
    }
}

Step 3: Create a service for authenticated requests 

<?php

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

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use MyVendor\MyExtension\Domain\Dto\ApiEndpoint;
use Netresearch\NrVault\Http\SecretPlacement;
use Netresearch\NrVault\Service\VaultServiceInterface;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Http\RequestFactory;

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

    /**
     * Call an API endpoint with vault-managed authentication.
     *
     * The token is retrieved from vault and injected at request time.
     * It never appears in this code and is wiped from memory immediately.
     */
    public function call(
        ApiEndpoint $endpoint,
        string $method,
        string $path,
        array $data = [],
    ): ResponseInterface {
        // Create PSR-7 request using TYPO3's RequestFactory
        $request = $this->requestFactory->createRequest(
            $method,
            rtrim($endpoint->url, '/') . '/' . ltrim($path, '/'),
        );

        if ($data !== [] && \in_array($method, ['POST', 'PUT', 'PATCH'], true)) {
            $request = $request
                ->withHeader('Content-Type', 'application/json')
                ->withBody(
                    \GuzzleHttp\Psr7\Utils::streamFor(json_encode($data))
                );
        }

        // Send via VaultHttpClient - token never exposed to application
        return $this->vault->http()
            ->withAuthentication($endpoint->token, SecretPlacement::Bearer)
            ->withReason('API call to ' . $endpoint->name . ': ' . $path)
            ->sendRequest($request);
    }

    /**
     * Convenience method for GET requests.
     */
    public function get(ApiEndpoint $endpoint, string $path): array
    {
        $response = $this->call($endpoint, 'GET', $path);

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

Step 4: Use the service 

<?php

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

use MyVendor\MyExtension\Domain\Dto\ApiEndpoint;
use MyVendor\MyExtension\Service\ApiClientService;

// Load endpoint from database
$row = $connection->select(['*'], 'tx_myext_apiendpoint', ['uid' => 1])
    ->fetchAssociative();
$endpoint = ApiEndpoint::fromDatabaseRow($row);

// Make authenticated API call
$customers = $this->apiClientService->get($endpoint, '/customers');

What happens under the hood 

1. The token field contains a UUID v7 like 01937b6e-4b6c-...
2. VaultHttpClient::sendRequest() retrieves the actual token from vault
3. Token is injected into the Authorization: Bearer ... header
4. sodium_memzero() immediately wipes the token from memory
5. The HTTP call is logged to the audit trail (without the secret)

Security benefits 

This pattern provides several security advantages:

No secret exposure

Application code never sees the actual API token. The DTO contains only the vault UUID, which is useless without vault access.

Memory safety

Secrets are cleared from memory immediately after injection using sodium_memzero() .

Audit trail

Every HTTP call is logged with the endpoint name, HTTP method, URL, and status code - but never the secret itself.

Separation of concerns

Credential management is handled by the vault. Application code focuses on business logic.

No CLI or file access required

Editors and admins can manage API endpoints entirely through the TYPO3 backend. The vault secret field provides a secure password input with reveal — and copy, outside the hardened profile — with no command line needed.

The challenge 

Extension settings defined in ext_conf_template.txt are stored in LocalConfiguration.php - not in TCA tables. This means:

• The renderType: 'vaultSecret' approach doesn't work directly
• API keys are stored as plaintext in the filesystem
• Keys may end up in version control or backups

Approaches 

There are three approaches to secure extension settings with vault:

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

<?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.
        // DeepL uses the "Authorization: DeepL-Auth-Key <key>" scheme (not Bearer),
        // expressed via the Header placement + prefix option.
        $response = $this->vault->http()
            ->withAuthentication(
                $this->apiKeyRef->identifier,
                SecretPlacement::Header,
                ['headerName' => 'Authorization', 'prefix' => 'DeepL-Auth-Key '],
            )
            ->withReason('DeepL translation request')
            ->sendRequest($request);

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

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

<?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'] ?? '';
    }
}

<?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'],
    ],
];

<?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;
    }
}

<?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'],
        );
    }
}

<?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'] ?? '';
    }
}

Comparison 

Recommendation: Use Approach 1 for simple single-key integrations, Approach 3 for complex integrations requiring multiple configurations or strict access control.

Encryption architecture 

nr-vault uses envelope encryption, an industry-standard pattern for protecting sensitive data.

+-------------------+
|    Master Key     |
+--------+----------+
         |
         | encrypts
         |
   +-----+------+--------+
   |            |         |
   v            v         v
+------+    +------+   +------+
| DEK1 |    | DEK2 |   | DEK3 |
+--+---+    +--+---+   +--+---+
   |           |          |
   | encrypts  | encrypts | encrypts
   v           v          v
+------+    +------+   +------+
|Value1|    |Value2|   |Value3|
+------+    +------+   +------+

Secret 1    Secret 2   Secret 3

Algorithms 

XChaCha20-Poly1305 (default)

ChaCha20 stream cipher with extended nonce and Poly1305 MAC. The deliberate default for new secrets: available in every libsodium build, and its 24-byte nonce makes random-nonce collisions a non-concern, so vault contents stay portable across hosts with differing CPU capabilities.

AES-256-GCM (opt-in)

Advanced Encryption Standard with 256-bit keys in Galois/Counter Mode. Selected per installation via encryptionAlgorithm, and only worth choosing on hosts with hardware AES support.

Both algorithms provide:

• 256-bit key strength.
• Authenticated encryption (AEAD).
• Protection against tampering.

Master key security 

The master key is the root of trust for all secrets.

Audit logging 

All secret operations are logged with:

• Timestamp.
• Action (create, read, update, delete).
• Actor (user ID, username, type).
• Secret identifier.
• IP address.
• Result (success/failure).

vendor/bin/typo3 vault:audit --reset-anchor

Access control 

Access is decided by two independent gates. Both must pass.

Per-secret access answers "may this actor touch this secret?":

1. Authentication: Backend user must be logged in.
2. Ownership: Creator has full access.
3. Group membership: Shared access via backend groups.
4. Admin override: Administrators can access all secrets.

Operation permissions answer "may this actor perform this kind of operation at all?" — see the next section.

securityProfile = hardened
disableAdminOverride = 1

$GLOBALS['TYPO3_CONF_VARS']['SYS']['nrVault']['disableAdminOverride'] = true;

# 1. Confirm the state
vendor/bin/typo3 vault:break-glass --status

# 2. Open a window with a justification
vendor/bin/typo3 vault:break-glass --activate --reason="INC-4711 rotate leaked deploy key" --minutes=30

# 3. Do the work in the backend or on the CLI

# 4. Close it — do not wait for the expiry
vendor/bin/typo3 vault:break-glass --deactivate --reason="INC-4711 closed"

Deployment gate 

Every control described on this page is checkable from a shell. vault:doctor evaluates them all and reduces the result to a process exit code, which makes it usable as the last step of a deployment pipeline rather than as a document somebody is supposed to have read.

vendor/bin/typo3 vault:doctor --profile=hardened

vendor/bin/typo3 vault:doctor
test $? -le 1

vendor/bin/typo3 vault:doctor

Security best practices 

1. Regular key rotation: Rotate the master key annually or after security incidents.
2. Audit log review: Regularly review audit logs for suspicious access.
3. Minimal permissions: Grant access only to users who need it.
4. Secret rotation: Rotate secrets when personnel changes occur.
5. Monitoring: Set up alerts for access_denied events.
6. Backup security: Encrypt backups and store them securely.

Reporting vulnerabilities 

If you discover a security vulnerability, please report it responsibly:

DO NOT create a public GitHub issue.

Use GitHub's private security reporting feature: Report a vulnerability

See SECURITY.md for the full security policy.

Assets 

Actors 

Trust boundaries 

┌────────────────────────────────────────────────────────────────┐
│  Browser (backend operator)                                    │
│  · revealed plaintext, max 30 s, no-store, no copy in hardened │
└───────────────────────────┬────────────────────────────────────┘
                            │  (1) HTTPS + BE session + CSRF
                            │      + secret.reveal AND secret.use
┌───────────────────────────┴────────────────────────────────────┐
│  PHP process  ── the trust anchor ──                           │
│  · master key cached for one request                           │
│  · plaintext exists here and only here                         │
│  · AccessControlService decides every access                   │
└──┬──────────────────┬───────────────────┬──────────────────────┘
   │ (2) SQL          │ (3) filesystem    │ (4) HTTPS + token
   │                  │                   │
┌──┴────────────┐  ┌──┴─────────────┐  ┌──┴────────────────┐
│  Database     │  │  Filesystem    │  │  KMS (Transit)    │
│  ciphertext,  │  │  key file,     │  │  unwraps the      │
│  wrapped DEKs,│  │  wrapped key,  │  │  master key;      │
│  audit chain  │  │  anchor NDJSON │  │  audits each call │
└───────────────┘  └────────────────┘  └───────────────────┘
   │
   │ (5) syslog / NDJSON / webhook — one-way, after commit
┌──┴──────────────────────────────────────────────────────────┐
│  SIEM / log pipeline                                        │
│  · holds evidence the database owner cannot reach           │
└─────────────────────────────────────────────────────────────┘

Trust boundaries describes what crossing each boundary requires, and what each boundary does not stop.

STRIDE-lite 

Attack scenarios 

Each scenario names the control that answers it and the risk that remains.

Standard 

Secure defaults with zero-configuration TYPO3 integration. Envelope encryption, the full permission model, the tamper-evident audit chain and the reveal lifecycle are all active — this is not a "off" setting.

What it deliberately allows: the typo3 master-key provider, provider auto-detection when the configured provider is unavailable, copy-to-clipboard on reveal, the unconditional administrator override, and external audit sinks as opt-in.

Choose it when TYPO3 administrators are already trusted with production credentials, and the vault's job is to stop plaintext sitting in database columns and configuration files.

Hardened 

Fail-closed and audit-ready. The premise is different: "TYPO3 administrator" and "may read production credentials" are separate roles, and every plaintext access must be attributable to a granted permission rather than to a role.

A misconfigured hardened vault stops. It never silently continues on weaker key material — that is the contract, and choosing the profile is the explicit statement that it has been read.

Exact technical differences 

Unchanged between the profiles: the cryptography, the ten operation permissions, the per-secret ownership and group tiers, the audit chain and its epochs, allowCliAccess (off by default in both), the reveal auto-hide and wipe-on-leave lifecycle, and Cache-Control: no-store on reveal responses. Hardening does not turn controls on that were previously off; it removes escape hatches.

Why disableAdminOverride is inert in the standard profile 

It looks like an inconsistency and is a deliberate guard. Setting that flag alone, without the rest of the hardened policy — an explicit external provider, no fallback to the TYPO3 encryption key — is far more likely to be a misunderstanding than a decision, and its failure mode is locking every administrator out of the vault.

So the bypass seam checks the flag and the profile: not privileged → no bypass; flag off → bypass, without even resolving the profile (which throws on an unknown value, and must stay off the hot path of every existing installation); profile standard → bypass anyway; hardened and flag set → bypass only inside an open break-glass window.

The mismatch is visible rather than silent. vault:break-glass --status reports adminOverrideDisabledEffective alongside the raw setting, and vault:doctor pairs the two.

Migrating from standard to hardened 

Do this in the order below. Steps 1 to 3 are prerequisites; switching the profile before them is what produces an unreadable vault.

vendor/bin/typo3 vault:doctor --profile=hardened

1. Move off the ``typo3`` provider. Choose file, env or transit (Key custody), then rotate the master key onto it with vault:rotate-master-key. Verify that secrets still decrypt before touching the profile — under hardened there is no fallback that would mask a mistake.
2. Back up the new key material separately from the database, and verify the backup. See Backup and restore.
3. Grant the operation permissions your groups actually need. With the override withdrawn, administrators hold exactly what their groups were granted. Editors working with vault-backed fields need secret.use; whoever operates the vault needs the administrative permissions explicitly. See Operation permissions.
4. Enable at least one external audit sink and schedule anchoring and verification (Monitoring and alerting). Without this, hardened verification reports NO_EXTERNAL_SINK.

5. Set the profile.

   Extension configuration

   securityProfile = hardened

   Copied!

6. Withdraw the admin override, and pin it. Set disableAdminOverride = 1, then pin the value where the backend cannot reach it:

   config/system/additional.php

   $GLOBALS['TYPO3_CONF_VARS']['SYS']['nrVault']['disableAdminOverride'] = true;

   Copied!

7. Confirm break-glass works before you need it. Open and close a window once, on purpose, and check that both rows appear in the audit log:

   vendor/bin/typo3 vault:break-glass --status
   vendor/bin/typo3 vault:break-glass --activate --reason="Verify break-glass path after hardening" --minutes=1
   vendor/bin/typo3 vault:break-glass --deactivate --reason="Verification complete"

   Copied!
8. Gate the deployment. vault:doctor --profile=hardened must pass.
9. Smoke test the surfaces that changed: a reveal (no copy button, value disappears after 30 seconds), a non-admin editor loading a form with a vault-backed field, and an unprivileged administrator confirming they no longer reach secrets they do not own.

The PHP process is the trust anchor 

Everything else on this page is relative to one fact: plaintext exists in the PHP process and nowhere else. The master key is loaded there, cached there for the duration of one request ( AbstractMasterKeyProvider::getMasterKey() , see ADR-020: Master key request-lifetime caching), and wiped with sodium_memzero() when the provider's cache slot is cleared. DEKs are unwrapped there and wiped on every path, including the error paths.

Consequently: a fully compromised PHP process defeats every control in this extension. nr-vault raises the cost of a database compromise, a backup leak, a misconfigured backend group and an insider with SQL access. It does not defend the process against itself. See Known limitations.

Boundary 1 — browser to PHP process 

Crossing requires: a TYPO3 backend session, the CSRF protection built into @typo3/core/ajax/ajax-request.js, a POST request, and — for a reveal — both secret.reveal (displaying plaintext to a human) and secret.use (obtaining the plaintext at all), plus per-secret read access. The vault_reveal route is registered access => 'user' on purpose: AjaxController::revealAction() re-asserts the method and the permission server-side, so authorization holds even if the route configuration is later loosened.

What the boundary protects. Plaintext leaves the process only in a response marked Cache-Control: no-store (and Pragma: no-cache), on success and error alike, so no browser, proxy or service worker retains it. Nothing is cached client-side: every reveal re-hits the endpoint, which is what makes every reveal produce its own audit row.

What it does not protect. Once the plaintext is in the browser it is outside anything PHP can enforce:

• JavaScript strings cannot be zeroized. startRevealLifecycle() bounds the exposure window — 30 seconds, or immediately on visibilitychange (tab hidden) and pagehide — but the engine may retain copies after the field is cleared.
• The clipboard outlives the dialog and cannot be cleared reliably from JavaScript. That is why the hardened profile reports copyAllowed = false and offers no copy button.
• Screenshots, screen sharing and cameras are outside scope entirely.

Boundary 2 — PHP process to database 

Crossing requires: the database credentials in settings.php, or any other path to SQL execution.

What the boundary protects. The database holds ciphertext, wrapped DEKs, nonces, algorithm markers and the audit chain. It holds no master key under any provider — the typo3 provider derives it from encryptionKey in settings.php, the others read a file, an environment variable or a KMS. A read-only database compromise therefore yields nothing directly usable.

A database write compromise is the interesting case, and the audit chain is designed for exactly it: from epoch 1 the entry hash is an HMAC under a key derived from the master key, which the database does not contain. An attacker who can rewrite rows cannot re-sign them.

What it does not protect.

• Metadata is not encrypted. Identifiers, owners, group tiers, timestamps, version counters and the full audit trail are readable plaintext. The audit log in particular maps out the credential topology — which is why reading it is its own permission (audit.view) rather than a side effect of holding a secret permission.
• The chain detects tampering; it does not prevent it, and it cannot by itself detect a wholesale reset. That needs the external anchor (Audit evidence).
• value_checksum is a keyed change detector over the ciphertext, not an integrity control — integrity comes from the AEAD tag.

Boundary 3 — PHP process to filesystem 

Crossing requires: filesystem access as the web-server or CLI user.

What crosses it. Depending on configuration: the master-key file (file provider), the wrapped master key (transit), the NDJSON audit stream and the anchor file (file sink), and — always — config/system/settings.php and additional.php.

What the boundary protects. Permissions, and only permissions. The file provider writes its key with the umask tightened to 0o077 before the write, then chmod to 0400, so there is no window in which the freshly created file is world-readable. The transit provider writes the wrapped key the same way but at 0600 (rotation must be able to overwrite it) and via write-to-temp-then-rename, because a truncated wrapped key is an unrecoverable vault rather than a failed write. The NDJSON sink creates files 0600 and directories 0700, and refuses paths under a public root.

What it does not protect. The web-server user can read what the web-server user can read. A key file readable by the PHP process is readable by anything running as that process — which is the whole point of Known limitations on the typo3 provider, and the reason Key custody treats "who else runs as this user" as the question that matters.

Pinning matters here. Settings that are editable in Admin Tools > Settings can be changed by a compromised administrator; the same settings pinned in config/system/additional.php require filesystem access to change. disableAdminOverride is the canonical example (Disabling the admin override).

Boundary 4 — PHP process to KMS 

Applies to the transit master-key provider, which ships in the same release train as this documentation.

Crossing requires: network reachability of the Vault address and a valid token, read from the configured environment variable in preference to the stored setting (the stored one is readable in the Install Tool and appears in configuration exports).

What the boundary protects. Custody, rotation and auditability. Only the wrapped ciphertext (vault:v1:…) sits on the local filesystem; unwrapping is a live API call. Pulling the token or the policy locks the vault out immediately, with no key file left behind to recover. Every unwrap is logged centrally, by a system the TYPO3 administrator does not control. A stolen database plus a stolen webroot is useless without Vault access.

Path safety is enforced before interpolation: mount segments and the key name must match [A-Za-z0-9._-]+ and must not be . or .., so a configured mount cannot traverse the API path. Token-shaped strings are redacted from transport error messages before they reach a log.

What it does not protect. A live attacker inside the request. The process holds a token it may legitimately use, so it can call decrypt and obtain the master key. A KMS protects custody, not runtime. Stated plainly because it is the most common misreading of what a KMS buys.

Availability also becomes a dependency: an unreachable Vault means an unreadable vault. isAvailable() deliberately performs no network call so a Vault outage does not become a per-request HTTP timeout on hot paths, but the first real getMasterKey() will fail.

Boundary 5 — PHP process to SIEM 

Crossing requires: nothing from the attacker's side — this boundary is one-way and outbound. Its purpose is to put evidence where the database owner cannot reach it.

What crosses it. Audit entries, chain-tip anchors and integrity alerts, through any enabled sink: local syslog as RFC 5424 structured data at facility LOG_LOCAL0, an append-only NDJSON file, or an HTTP POST to a collector.

Ordering matters. Fan-out happens after the transaction commits and after the advisory audit lock is released. Two consequences, both deliberate: a hanging collector cannot serialise every other vault operation behind the audit lock, and a sink failure is a delivery problem that never fails or rolls back the audited operation. Failures are contained per sink, counted, logged, and raised as a SINK_FAILURE alert.

What it does not protect. The window between a write and its delivery. A sink that has been failing since Tuesday is an availability problem with integrity consequences, which is why the failure counters exist and why SINK_FAILURE belongs in your alerting (see Monitoring and alerting).

Frontend and page-cache caveats 

The frontend is not a boundary nr-vault defends across — it is a context in which the vault deliberately refuses to act.

• Frontend requests hold no operation permission. isGranted() returns false for any frontend request regardless of what $GLOBALS['BE_USER'] contains, because TYPO3 populates that global for any visitor carrying a valid backend session, and frontend output is shared with anonymous visitors through the page cache.
• Frontend reads are a property of the secret, not of the visitor. Only the secret's own frontend_accessible flag governs them — and for %vault(id)% placeholders, additionally the request's FrontendPlaceholderPolicy allow-set (ADR-035: Per-request allow-set of frontend-resolvable identifiers): being frontend_accessible no longer makes an identifier resolvable from editor-authored content.
• Anything rendered into a cached page is public. A secret resolved into frontend output is cached alongside it and served to everyone. Vault values belong in server-side integrations — HTTP clients, API calls, and site configuration resolved at read time (ADR-030: Read-time resolution of site-configuration vault references) — not in rendered markup.

Primitives 

libsodium only. There is no openssl_* fallback path anywhere in the extension.

Envelope scheme 

Each secret carries its own DEK, wrapped by the master key:

1. A fresh DEK of the algorithm's key length is generated with random_bytes() .
2. Two independent nonces of the algorithm's nonce length are generated, one for the DEK envelope and one for the value.
3. The DEK is encrypted under the master key, with the secret identifier as associated data.
4. The value is encrypted under the DEK, with the same identifier as associated data.
5. A change-detection token is computed (see The change-detection token).
6. The DEK, the derived MAC key and the plaintext are wiped with sodium_memzero() .

Decryption reverses it: unwrap the DEK with the master key, then decrypt the value with the DEK, then wipe the DEK. A failed AEAD tag surfaces as Authentication failed - data may have been tampered with rather than as a garbled plaintext.

The practical consequence is that rotating the master key never touches a secret value: only the DEK layer is re-wrapped ( EncryptionService::reEncryptDek() ), which is why Key rotation is an operation on envelopes rather than a re-encryption of the vault.

Algorithm agility 

Which algorithm a given envelope uses is recorded, not re-derived. That distinction is the whole point: an envelope written on a host with hardware AES must still open on a host without it.

New envelopes are always version 2. The marker values — xchacha20poly1305 and aes256gcm — are persisted per secret and are byte-for-byte stable: changing one would make every secret carrying the old string undecryptable.

The default for new secrets is XChaCha20-Poly1305, deliberately. It is available in every libsodium build (AES-256-GCM requires hardware support), and its 24-byte nonce makes random-nonce collisions a non-concern — so vault contents stay portable across hosts with differing CPU capabilities. A site can pin the other algorithm through the encryptionAlgorithm setting.

Unknown or unavailable values fail loudly. An unrecognised marker on a version-2 row is a hard error, not a guess; an encryptionAlgorithm setting naming an unknown or host-unavailable algorithm refuses to encrypt. For a vault, refusing to encrypt beats encrypting with an algorithm the operator did not choose, and refusing to decrypt beats silently trying the wrong primitive.

HKDF usages 

Four derivations, each with its own info string so no two outputs can collide even though three of them start from the same master key.

The audit derivation is what gives the chain cryptographic separation from encryption key material: an attacker who somehow obtained the audit HMAC key could forge chain hashes but not decrypt anything, and vice versa.

The change-detection token 

value_checksum is a keyed MAC over the ciphertext, never over the plaintext, with a MAC key derived per secret from that secret's DEK. Two properties follow, and both were the reason for the design:

• The stored checksum is not an offline-computable function of the plaintext, so it is no guess-confirmation oracle for someone holding the database.
• Identical plaintexts in different secrets produce different checksums, so the column leaks no equality relation between secrets.

It exists to answer "did this value change?" for the audit trail's hash_before / hash_after fields. It is not an integrity control and is not required to open an envelope.

Key and nonce lengths 

Nonces are random per operation and never reused across the DEK envelope and the value envelope — two independent nonces are drawn for every encrypt() call, and re-wrapping a DEK during master-key rotation draws a fresh one.

Constant-time comparison 

Every comparison of a secret or an integrity tag uses hash_equals() . The comparisons that matter:

• audit chain verification — both previous_hash and entry_hash;
• chain-tip anchor comparison — the anchored tip against the stored row;
• the transit provider's check of whether a token copy is safe to wipe.

Plain !== is never used on that class of value. AEAD tag verification is libsodium's own, and constant-time by construction.

Memory scrubbing policy 

sodium_memzero() is called on plaintexts, DEKs and derived MAC keys — on the success path and in finally blocks, so the error paths reachable through tampered ciphertext do not leak buffers.

Two deliberate exceptions, both documented at the call sites:

• The master key is not wiped by the encryption service. What getMasterKey() returns is the provider's shared request-lifetime cache entry. Wiping the local reference would either be a no-op (PHP's sodium_memzero() skips strings with a refcount above one) or corrupt the cached key for every later vault operation in the request. The provider owns that lifecycle and wipes its slot in clearCachedKey() . See ADR-020: Master key request-lifetime caching.
• A token that came from configuration is not wiped. It shares its string buffer with the configuration singleton, so zeroing it would NUL out the stored setting for the rest of the request. Only env-derived copies — freshly allocated by getenv() — are wiped.

Algorithm agility policy 

Adding an algorithm means adding an EncryptionAlgorithm case with a new stable string value and bumping nothing else: existing rows keep their marker and keep decrypting. Removing one is a breaking change that requires re-encrypting every affected secret first, because the marker is what the decrypt path dispatches on.

The same applies to the audit chain, where the analogous version marker is hmac_key_epoch: epochs are additive, verification dispatches per row, and a downgrade is treated as an attack (see Epochs: what each one binds).

The envelope framing used for portable, off-table storage ( EnvelopeCodec ) is deliberately tolerant in one direction only: it ignores unknown fields when reading, and re-wrapping rewrites just the DEK layer on top of the body as it was read. Rebuilding the body from known fields would make rotation lossy for an envelope written by a newer version — irreversibly, once the old key is gone.

What the log proves — and against whom 

Tamper-evident, not tamper-proof. Every row of that table is detection. None of it is prevention.

Epochs: what each one binds 

hmac_key_epoch is a per-row algorithm selector. Verification dispatches on it row by row, so a chain may legitimately span epochs at a migration boundary. The default for new installations is auditHmacEpoch = 3.

The HMAC key is never stored. It is derived per request as hash_hkdf('sha256', $masterKey, 32, 'nr-vault-audit-hmac-v1') , giving the chain cryptographic separation from encryption key material.

Epoch 0 chains carry no keyed evidence. Migrate them with vault:audit-migrate-hmac (see vault:audit-migrate-hmac).

Chain verification 

AuditLogService::verifyHashChain() walks the chain and checks, per row, that the stored previous_hash matches the predecessor's entry_hash and that the stored entry_hash recomputes — both with hash_equals() . It reports missing uids as structured data alongside the per-row errors.

Two epoch checks sit on top:

• Per-row. A decrease between consecutive rows is a downgrade finding. An increase is a legitimate migration boundary and is reported as a warning, not an error.
• Chain level. The chain's highest observed epoch must reach the configured floor (auditHmacEpoch). This catches the uniform case — a downgrade of every row to keyless epoch 0, which no per-row comparison would notice. The floor is only applied to a full-chain verification; a ranged verification may legitimately exclude the higher-epoch rows.

Anchoring 

Two anchors record the chain tip, at different distances from an attacker. They are complementary: the in-database one works with no sink configured at all, the external one survives an attacker who owns the whole database.

{"type":"anchor","source":"nr-vault","anchor":{"sequence":4821,"chainTip":"…","timestamp":1753900000,"hmacEpoch":3}}

Sinks 

Sinks mirror three record kinds — entries, anchors and alerts — outside the database. Fan-out happens after the transaction commits and after the advisory audit lock is released, so a slow collector cannot serialise vault operations, and a delivery failure never fails the audited operation.

Failure handling is uniform: each sink call is wrapped individually, so one broken destination does not blind the others; failures are logged, counted per sink, and raised as SINK_FAILURE. A sink whose own enablement probe throws is treated as disabled rather than being allowed to take the audited operation down. An enabled-but-unconfigured webhook reports itself disabled, because claiming to be external evidence while delivering nothing is precisely the false confidence the hardened check exists to catch.

Custom destinations are a tagged service: implement AuditSinkInterface and tag it nr_vault.audit_sink.

Alert reason codes 

Per-code definitions are in the command reference: Reason codes. What matters for evidence, rather than for reading CLI output:

• They are external contract. The strings appear in webhook payloads, syslog structured data and the NDJSON stream, and vault:audit-verify prints and exits on them. Treat them as stable API, not as labels — a SIEM rule switching on TABLE_RESET must keep working across releases.
• Four are tamper evidence, three are not. HASH_MISMATCH, UID_GAP, TABLE_RESET and EPOCH_DOWNGRADE indicate manipulation; SINK_FAILURE and NO_EXTERNAL_SINK are availability and configuration findings, and BREAK_GLASS is reserved for the emergency-access flow. AuditIntegrityReason::isTamperEvidence() is the intended switch between "page someone now" and "log it" — see What to page on.
• One finding is raised per reason code, not per erroring row. A broken chain commonly fails every row after the break, and ten thousand identical alerts would bury the signal; the affected row count travels in the finding context instead.
• A delivery finding still has integrity consequences. SINK_FAILURE is not tamper evidence, but while it holds you have no independent copy of the entries written during the outage.

Findings are dispatched as AuditIntegrityAlertEvent , so listeners fire even when nobody reads the CLI output. A throwing listener costs neither the remaining findings nor the report.

What an auditor should export 

The chain is only evidence if the tip can be tied to something outside the installation. Export both:

1. The entry sequence — the audit rows themselves, over the period under review, including uid, previous_hash, entry_hash and hmac_key_epoch. Without the hash columns the export is a log, not evidence.
2. The anchored tip — the anchor records covering the same period, taken from the external store rather than from the installation, plus the output of a verification run.

An export leaves the tamper-evident store behind: the downloaded copy has no hash chain of its own, no retention policy and no further access control. That is why audit.export is a separate permission from audit.view, and why the export should itself be treated as sensitive material.

Evidence collection gives the exact commands and the full artefact list.

A compromised PHP process can request every secret 

The limitation. Arbitrary code execution in the TYPO3 PHP process — an RCE, a malicious extension, a hostile Composer dependency, a compromised deployment — defeats every control in this extension. The attacker is inside the trust anchor: they can call VaultService::retrieve() , or load the master key provider directly, and take whatever the process may legitimately take.

Why it cannot be fixed here. nr-vault runs in that process. A control implemented in the same address space as its attacker is not a control.

What actually helps. Moving decryption out of the process, so that a compromise yields a request-rate-limited oracle instead of the key. That is a different architecture, evaluated in ADR-016: Sidecar daemon option, and it is not what this extension is today.

What still holds. Attribution. A read performed by compromised code still writes an audit row, and with a KMS every unwrap is logged by a system the attacker does not control. Detection after the fact is a genuinely different thing from prevention — just not a substitute for it.

The typo3 provider does not separate the vault from TYPO3 

The limitation. The default provider derives the master key from $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'] with HKDF-SHA256. The derivation is sound, but it changes nothing about custody: anyone who can read config/system/settings.php can derive the master key. That includes every backup of the configuration directory, every developer with a copy of the production settings, and every process running as the web-server user.

Its strength also cannot exceed the strength of encryptionKey itself. The provider refuses source keys shorter than 32 characters, but a weak-but-long key still yields a weak master key.

Consequence for backups. A dump of the database plus the configuration directory is a complete break. See Backup and restore.

What to do. Use file, env or transit for anything holding production credentials. The hardened profile enforces this: typo3 is rejected outright with exception code 1753900002, and there is no auto-detection fallback that could quietly put you back on it.

Revealed plaintext in the browser cannot be zeroized 

The limitation. JavaScript strings are immutable and garbage-collected. Setting input.value = '' removes the value from the DOM; it does not remove the engine's copies from memory. There is no browser API that would.

What is actually provided. A bounded exposure window, not secure deletion: 30 seconds of visibility, plus an immediate wipe when the tab is hidden (visibilitychange) or the page goes away (pagehide). Nothing is cached client-side, so a revealed value does not survive a modal close, and the response is marked Cache-Control: no-store.

The clipboard is worse. Clipboard contents outlive the dialog, outlive the page, and cannot be cleared reliably from JavaScript — they may also synchronise to other devices. That is why the hardened profile disables the copy button entirely rather than clearing the clipboard on a timer, which would be theatre.

The hash chain does not prevent a database reset 

The limitation. The HMAC chain proves that no row was altered within the stored chain. It cannot prove that the chain is still the same chain. An attacker with DELETE rights on tx_nrvault_audit_log can truncate it and let the service build a fresh, internally consistent chain from uid 1 — the chain itself cannot distinguish that from a genuinely young installation.

What closes the gap, partially. Two chain-tip anchors, at different distances from the attacker.

The in-database anchor (ADR-034: Audit chain tip anchor) records "row uid=A still exists with entry_hash=H" in sys_registry, MACed under a key derived from the master key — which is not in the database. Truncating the audit table alone therefore no longer looks like a young installation: the anchor still names a row that is gone, and verification reports a violation.

The external anchor is published to a store the database owner does not control at all, giving verification two facts to check that no database write can reach: the chain cannot have shrunk, and the row at the anchored sequence must still hash to the anchored tip.

What remains. Detection, not prevention — and each anchor only as far as its storage is trustworthy. An attacker who also holds DELETE on sys_registry can remove the in-database anchor, which then reads as "not armed" rather than as a violation; auditAnchorRequired is what closes that, turning a missing anchor into a critical finding a database writer cannot silence. It lives in the extension configuration, so a database-write attacker cannot reach it — but unlike disableAdminOverride it accepts no $TYPO3_CONF_VARS pin, so a compromised administrator can still clear it from the Settings module. An anchor file on a host the attacker owns can likewise be truncated, so anchors shipped off-host through syslog or a webhook are what makes the external property real. And in every case: tamper-evident, not tamper-proof.

A KMS protects custody, not runtime 

The limitation. With the transit provider the master key is unwrapped by HashiCorp Vault on demand and only the wrapped ciphertext sits locally. That is a genuine improvement in custody, rotation and auditability. It does not stop a live attacker inside the request: the process holds a token it may legitimately use, so it can call decrypt and obtain the master key exactly as the vault does.

What it buys, precisely. Key custody and rotation move into Vault; every unwrap is centrally audited and revocable, so pulling the token or the policy locks the vault out immediately with no key file left to recover; and a stolen database plus a stolen webroot is useless without Vault access.

What it costs. Availability. An unreachable Vault is an unreadable vault.

Backups need the database and separately stored key material 

The limitation. A database backup alone cannot be restored into a working vault — the ciphertext is undecryptable without the master key. A backup of both, stored together, is a single artefact that contains everything.

Both failure modes are real, and they pull in opposite directions. Storing key material with the dump destroys the protection; storing it nowhere destroys the data. The only correct answer is: back up both, store them separately, restore both, and verify the restore with a probe decrypt. See Backup and restore.

Master key loss is data loss 

The limitation. There is no recovery path, no escrow, no vendor-side reset. If the master key is lost, every secret in the vault is permanently unreadable. This is not a limitation to be engineered away — a vault with a recovery backdoor is a vault with a backdoor.

The typo3 provider makes this easier to trip over than it looks: rotating TYPO3's encryptionKey changes the derived master key and orphans every stored secret. Treat encryptionKey as vault key material for as long as that provider is configured.

Break-glass restores full admin power 

The limitation. While a break-glass window is open, an administrator has exactly what they had before the override was disabled: every operation permission, and read, write and delete on every secret. Break-glass prevents nothing.

Its value is evidence and time boxing — a named actor, a mandatory typed justification, a hash-chained audit row written before the window opens, a PSR-14 event observers can alert on, a banner every operator sees, and an expiry between 1 and 60 minutes that nobody has to remember, evaluated at read time on every access-control decision.

Two gaps worth naming. A window that simply expires writes no audit row — nothing runs at the moment it lapses, so reconstruct the closed interval from the activation row's expiresAt context value. And an administrator with filesystem access can unpin disableAdminOverride instead of using break-glass at all; that path is visible in the filesystem, not in the audit log.

Treat an activation as an incident to review, not as routine maintenance (Incident response).

Metadata is not confidential 

Identifiers, ownership, group tiers, timestamps, version counters and the whole audit trail are stored unencrypted. The audit log is the sensitive one: it maps who holds which credential and when they use it, which is a useful target in its own right. That is why audit.view and audit.export are separate permissions, and why an export — which leaves the tamper-evident store behind, with no hash chain, no retention policy and no further access control — is gated apart from viewing.

Out of scope entirely 

nr-vault makes no claim about, and provides no control over:

• the operating system, the web server, the PHP runtime and its extensions;
• the database server, its access control, its backups and its replicas;
• TYPO3 core authentication, session handling and CSRF (inherited, not provided);
• the browser, the clipboard, screenshots, screen sharing and cameras;
• the SIEM or log pipeline once evidence has left the process;
• physical and network security, and the trustworthiness of every other installed TYPO3 extension.

Target of evaluation states the same boundary in the form an assessor needs.

Start here 

The four things that actually matter 

Everything else on these pages is detail around these.

1. The master key is not in the database — keep it that way in backups too. A dump taken together with the key material is a single artefact containing everything. This is easiest to get wrong with the typo3 provider, where the key lives in config/system/settings.php.
2. Master key loss is data loss. There is no escrow and no reset. Back it up separately, and verify the backup by restoring it somewhere and decrypting something.
3. The audit chain needs an external anchor to be worth anything against a database writer. The chain detects row edits; only an anchor published outside the database detects a wholesale reset — and only if it is stored somewhere the attacker cannot truncate.
4. A scheduled check whose failures nobody receives is not a control. Schedule anchoring and verification, then wire the alerts, then break the delivery on purpose once to confirm the alert arrives.

Step 1 — Choose a master-key provider 

The hardened profile rejects the ``typo3`` provider with exception code 1753900002, and there is no auto-detection fallback that could quietly put you back on it. Pick one of the others; the trade-offs are in Key custody.

masterKeyProvider = file
masterKeySource = /var/lib/typo3-secrets/vault-master.key

Initialise the key if this is a new vault:

vendor/bin/typo3 vault:init

Back up the new key material now, separately from the database, and verify the backup: Backup and restore.

Step 2 — Set the profile 

securityProfile = hardened

From this point the vault is fail-closed: no provider auto-detection, no fallback to the TYPO3 encryption key, and a misconfigured provider stops vault operations instead of continuing on weaker key material. An unknown value for the setting is refused outright with code 1753900001.

Verify immediately, before going further:

vendor/bin/typo3 vault:list
vendor/bin/typo3 vault:doctor --profile=hardened

A vault:list that works only proves the database is reachable — it reads metadata and never touches the master key. The real check comes in step 7.

Step 3 — Grant the operation permissions 

Do this before step 6. With the override withdrawn, administrators hold exactly what their groups were granted — so if the grants are not in place first, nobody can operate the vault and the only way back in is break-glass.

Grants live per backend user group in Backend Users > Groups, field Custom module options, group Vault: operation permissions. The full table of ten permissions and what each governs is in Operation permissions.

A workable starting split:

Remember that operation permissions are only one of two gates. Per-secret ownership and group tiers still apply — see Access control.

Step 4 — Enable an external audit sink 

The hardened profile requires one. Without an enabled and usable sink, vault:audit-verify reports NO_EXTERNAL_SINK: the audit trail would exist only in the database it is meant to protect, and no chain-tip anchor could be published.

Cheapest sufficient configuration, if the host already has a log shipper:

auditSinkSyslogEnabled = 1
auditSinkSyslogIdent = nr-vault-prod

auditSinkFileEnabled = 1
auditSinkFilePath = /var/log/typo3/nr-vault-audit.ndjson
auditSinkAnchorPath = /var/log/typo3/nr-vault-anchors.ndjson

Enable the file sink even when shipping to syslog: it is what writes the NDJSON anchor stream that AnchorFileReader reads back during verification. Both paths must be outside any public root, or the sink reports itself disabled rather than writing anyway.

For a webhook collector, read the allowed_hosts note in Monitoring and alerting before configuring the URL — a private-address collector is refused by design.

Step 5 — Schedule anchoring and verification 

Two separate jobs, doing different things (see Scheduler tasks):

vendor/bin/typo3 vault:audit-anchor    # publish the tip — hourly
vendor/bin/typo3 vault:audit-verify    # verify chain + anchor — every 15 min

Register AuditAnchorTask and AuditVerifyTask in Scheduler > Add task, or run the commands from cron.

Publish the first anchor by hand now, so verification has a baseline immediately rather than after the first scheduled run:

vendor/bin/typo3 vault:audit-anchor
vendor/bin/typo3 vault:audit-verify

Wire the alerting at the same time — a scheduled check whose failures nobody receives is not a control. What to page on says what to page on.

The external anchor above is only half of the control. A second, independent tip anchor lives in sys_registry (ADR-034: Audit chain tip anchor) and is what makes a full wipe of tx_nrvault_audit_log detectable from inside the installation. It arms itself on the next audit write; confirm it did, then require it:

vendor/bin/typo3 vault:audit --verify   # "Tip anchor: ok" — not "NOT ARMED"

auditAnchorRequired = 1

Order matters. Turned on before the anchor is armed, every verification reports a violation: an install that never had an anchor and one whose anchor an attacker deleted look identical. Once on, the requirement lives in the extension configuration rather than in a table, so a database-write attacker can no longer silence the control by deleting the anchor row. vault:doctor reports the state as audit.db_anchor.

Unlike disableAdminOverride and frontendPlaceholderLegacyCli, this setting accepts no $TYPO3_CONF_VARS pin — only those three keys do — so a compromised administrator can still clear it from the Settings module. It closes the database-writer path, not the backend-administrator one.

Step 6 — Withdraw the administrator override, and pin it 

disableAdminOverride = 1

This withdraws the bypass in one place and therefore everywhere it was consulted: the operation permissions, the per-secret read/write/delete tiers, the privileged-column policy, and the technical-actor equivalents. An override disabled in only some of those would be worse than none, because the deployment would believe it is protected.

Then pin it, or the control is only as strong as the backend it is configured in — a compromised administrator can untick a checkbox:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['nrVault']['disableAdminOverride'] = true;

// Pin the strict CLI placeholder policy off-limits too (ADR-035). The
// value below is the DEFAULT — pinning false is what stops an
// administrator from turning the legacy CLI bypass back on. A deployment
// that genuinely needs the old behaviour pins true instead.
$GLOBALS['TYPO3_CONF_VARS']['SYS']['nrVault']['frontendPlaceholderLegacyCli'] = false;

Only three settings accept such a pin: disableAdminOverride, frontendPlaceholderLegacyCli and auditReads. Everything else in the hardened set stays editable from the Settings module by whoever holds vault.configure.

frontendPlaceholderLegacyCli matters here because scheduler:run authenticates the _cli_ administrator: the admin bypass grants the read, so the allow-set is the only remaining gate between an editor-authored tt_content field and a secret in the output of a scheduled newsletter or export job.

The pinned value wins in both directions and requires filesystem access to change. Confirm it took effect:

vendor/bin/typo3 vault:break-glass --status

The output reports adminOverrideDisabledEffective alongside the raw setting, so a "flag set, profile standard" mismatch is visible rather than silent.

Exercise break-glass once, deliberately, before you need it:

vendor/bin/typo3 vault:break-glass --activate --reason="Verify break-glass path after hardening" --minutes=1
vendor/bin/typo3 vault:break-glass --status
vendor/bin/typo3 vault:break-glass --deactivate --reason="Verification complete"
vendor/bin/typo3 vault:audit --identifier=__break_glass__

Both rows must appear. See Break-glass mode and Break-glass usage policy and review.

Step 7 — Gate the deployment on vault:doctor 

vendor/bin/typo3 vault:doctor --profile=hardened

Exit codes are the contract:

Severity is worst-wins, so a long list of passes cannot average a critical finding away.

Use it as an actual gate in the pipeline, and keep the JSON for the deployment record:

set -e
vendor/bin/typo3 vault:doctor --profile=hardened --format=json > vault-doctor.json
# A non-zero exit stops the deploy; the artefact goes to the release record.

The machine-readable output is what makes this auditable rather than a screenshot: each finding carries a stable identifier, so a pipeline can assert on specific findings and an auditor can compare runs over time. See Evidence collection.

Run it periodically too, not only at deploy time — Periodic vault:doctor.

Step 8 — Smoke test 

Verify the behaviour that actually changed. A green doctor says the configuration is coherent; these steps say the deployment works.

Crypto and provider

• [ ] A real secret decrypts: vault:retrieve <identifier>, or a reveal in

  the backend module. Metadata listing is not proof.

• [ ] Probe at least two secrets, ideally one from each encryption version —

  see Restore verification: the probe decrypt.

Reveal lifecycle

• [ ] A reveal shows the value and no copy button — the hardened profile

  reports copyAllowed = false.

• [ ] The value disappears after 30 seconds, and immediately when the tab is

  switched away or the page is left.

• [ ] The reveal response carries Cache-Control: no-store.

• [ ] Each reveal writes its own read audit row — reveal twice and check

  for two rows.

Permissions

• [ ] A non-admin editor with secret.use can load a form containing a

  vault-backed field.

• [ ] That editor cannot reveal (HTTP 403), and the denial appears as an

  access_denied audit row.

• [ ] An administrator without explicit grants cannot reach a secret they do

  not own. This is the check that proves step 6 took effect — if they still can, the flag is not effective, and --status will show why.

• [ ] The audit module is reachable by a group holding audit.view and not

  by one without it.

• [ ] The strict CLI placeholder policy is in force: vault:doctor

  reports cli.frontend_placeholder_legacy as a pass (it is critical under this profile when the flag is on). Confirm it empirically as well — put a %vault(id)% placeholder for a frontend_accessible secret into an editor-editable field, run a scheduled render over it ( scheduler:run ), and confirm the placeholder does not resolve. If it does, frontendPlaceholderLegacyCli is on — check the pin.

Audit pipeline

• [ ] vault:audit-verify reports a valid chain and no findings.

• [ ] An anchor exists and is recent — check the newest timestamp in the

  anchor file.

• [ ] vault:audit --verify reports Tip anchor: ok, and

  auditAnchorRequired is on so a deleted anchor cannot silence the control.

• [ ] Records actually arrive at the collector: run

  vault:doctor --active-probes (every enabled sink must accept the chain-tip anchor end-to-end), then perform a reveal and look for it in syslog or the SIEM. Do not infer delivery from the absence of errors.

• [ ] Break the delivery on purpose once (point the webhook at an

  unreachable host, or make the NDJSON directory read-only), confirm a SINK_FAILURE alert reaches your alerting, then restore it. An untested alert path is not an alert path.

Recovery

• [ ] Break-glass opens and closes, and both rows are in the chain.

• [ ] The key-material backup restores on a scratch system and a probe

  decrypt succeeds there.

Configuration summary 

securityProfile = hardened
disableAdminOverride = 1        # and pinned in additional.php

masterKeyProvider = file        # or env / transit — never typo3
masterKeySource = /var/lib/typo3-secrets/vault-master.key

allowCliAccess = 0              # default; 1 is a CRITICAL doctor finding
                                # under --profile=hardened, i.e. exit 2
cliAllowedOperations = secret.use,secret.create,secret.rotate
                                # default; only read when allowCliAccess = 1
frontendPlaceholderLegacyCli = 0  # default; pin it in additional.php
auditReads = 1
auditHmacEpoch = 3
auditAnchorRequired = 1         # only after the in-DB anchor reports ok

auditSinkSyslogEnabled = 1
auditSinkSyslogIdent = nr-vault-prod
auditSinkFileEnabled = 1
auditSinkFilePath = /var/log/typo3/nr-vault-audit.ndjson
auditSinkAnchorPath = /var/log/typo3/nr-vault-anchors.ndjson

Per-setting reference: Configuration.

Provider comparison 

typo3 — derived from the TYPO3 encryption key 

The default, and the only zero-configuration option. HKDF-SHA256 over SYS/encryptionKey with the domain-separation string nr-vault-master-key, yielding 32 bytes. Source keys shorter than 32 characters are refused outright — they would give HKDF far less than 256 bits of entropy.

What it does not do is separate the vault from TYPO3. The derivation is sound; the custody is not improved at all. See The typo3 provider does not separate the vault from TYPO3.

Two operational consequences that catch people out:

• encryptionKey is vault key material for as long as this provider is configured. Rotating it orphans every secret.
• The provider defines no destructor, so its request-lifetime cache slot survives individual instances. Long-running processes — scheduler daemons, messenger workers — must call Typo3MasterKeyProvider::clearCachedKey() to observe a rotated encryptionKey.

Acceptable for: development, staging, and installations where the secrets are no more sensitive than the rest of settings.php. Not acceptable for a hardened deployment, and the profile enforces that.

file — a key file outside the web root 

masterKeyProvider = file
masterKeySource = /var/lib/typo3-secrets/vault-master.key

The path must be outside the document root. The file is written with the umask tightened to 0o077 before the write and then chmod to 0400, so there is no window in which it is world-readable — an ordering that matters on hosts with permissive umasks.

# Owned by the user the PHP process runs as; nothing else needs it.
install -d -m 0700 -o www-data -g www-data /var/lib/typo3-secrets
chown www-data:www-data /var/lib/typo3-secrets/vault-master.key
chmod 0400 /var/lib/typo3-secrets/vault-master.key

The provider accepts the file as raw 32 bytes or as base64 (trailing newlines are tolerated). Anything else is rejected on length rather than padded.

Checklist: outside the web root; 0400; owned by the PHP user; excluded from application backups and included in a separate key backup (Backup and restore); on a filesystem whose snapshots you also control; access-logged if the platform allows it.

env — an environment variable 

masterKeyProvider = env
masterKeySource = NR_VAULT_MASTER_KEY

The natural fit for containers and any platform with a secret-injection mechanism (Kubernetes secrets, systemd LoadCredential, a supervisor's environment file). Raw 32 bytes or base64; the provider zeroes the base64 string once decoded.

Where environment variables leak. Process listings on some platforms, phpinfo(), crash dumps, /proc/<pid>/environ for the same user or root, child processes, and — commonly — CI logs and container inspection output. Verify that yours does not, rather than assuming.

The provider cannot persist a value, so vault:rotate-master-key cannot write the new key for you: set the variable in the injection mechanism, restart the process, and rotate with the new value supplied explicitly.

transit — wrapped by HashiCorp Vault 

masterKeyProvider = transit
hashicorp.address = https://vault.example.internal:8200
hashicorp.authMethod = token
hashicorp.tokenEnvVar = VAULT_TOKEN
hashicorp.transitMount = transit
hashicorp.transitKeyName = nr-vault-master
hashicorp.transitWrappedKeyPath = /var/lib/typo3-secrets/vault-master.wrapped

The master key is generated once, wrapped by Vault's transit engine, and only the ciphertext is stored locally. Every unwrap is a POST to /v1/{mount}/decrypt/{key}.

Custody notes.

• Token, not configuration. The token is read from hashicorp.tokenEnvVar in preference to hashicorp.token, because a token in the extension configuration is readable in the Install Tool and lands in configuration exports. Leave hashicorp.token empty in production.
• Token auth only. approle and kubernetes are rejected rather than silently downgraded to something weaker.
• Least-privilege policy. The token needs update on transit/decrypt/<key>, plus update on transit/encrypt/<key> only for initialisation and rotation. Nothing else. Withhold transit/keys/* so the vault cannot delete or export its own key.
• Path safety is enforced. Mount segments and the key name must match [A-Za-z0-9._-]+ and must not be . or .., so a configured mount cannot traverse the API path. A nested mount such as platform/transit stays usable.
• The wrapped file is written safely. 0600 (rotation must overwrite it) via write-to-temp-then-rename, because a half-written wrapped key is an unrecoverable vault rather than a failed write.
• Errors are redacted. Token-shaped strings are stripped from transport error messages, and non-2xx response bodies are never surfaced — Vault echoes the submitted ciphertext on some error paths.

What it buys and what it does not. Custody, rotation and central, revocable audit of every unwrap; a stolen database plus a stolen webroot is useless. It does not protect a live attacker inside the request — see A KMS protects custody, not runtime. And it makes Vault an availability dependency: isAvailable() performs no network call so an outage does not become a per-request timeout, but the first real key load will fail.

HSM and cloud KMS 

nr-vault has no direct HSM or cloud-KMS integration. The transit provider is the supported indirection: HashiCorp Vault can itself be backed by an HSM or a cloud KMS for its own seal, which puts the vault's master key under that custody transitively without nr-vault needing a provider per KMS vendor.

Anything else — AWS KMS, Azure Key Vault, GCP KMS directly — would need a new MasterKeyProviderInterface implementation. The interface is a single method, and AbstractMasterKeyProvider already implements the caching and wiping contract, so the surface is small; but it does not exist today, and no configuration setting will produce it.

What custody cannot fix 

Regardless of provider, the master key is present in the PHP process for the duration of a request that touches a secret. It is cached in a static keyed by provider class, and wiped with sodium_memzero() when the slot is cleared — but while it is there, code running in that process can read it.

Custody decides who can obtain the key outside the request. It has no opinion about the request itself. Everything on this page is about the former.

What has to be backed up 

Restore procedure 

1. Restore the database. Secrets, audit log, and be_groups.
2. Restore the configuration, including the provider setting, the security profile, auditHmacEpoch and any pinned values in additional.php.
3. Restore the key material to the location the configuration expects, with the right ownership and mode — 0400 for a file key, 0600 for a transit wrapped blob. For env, re-inject the variable and restart the process so it is actually in the environment.

4. Confirm the provider resolves before touching secrets.

   vendor/bin/typo3 vault:doctor --format=json

   Copied!

   On a hardened target, gate on the profile explicitly:

   vendor/bin/typo3 vault:doctor --profile=hardened

   Copied!
5. Probe-decrypt. See below. A restore is not verified until a real secret has come back as plaintext.

6. Verify the audit chain and compare it against the external anchor.

   vendor/bin/typo3 vault:audit-verify

   Copied!

7. Re-anchor — both anchors. A point-in-time restore rolls the audit table back, so the external baseline is stale and the in-database tip anchor now names a row the restored table no longer has, which reports as VIOLATED.

   # External baseline
   vendor/bin/typo3 vault:audit-anchor
   
   # In-database anchor. Verify FIRST that the violation is explained by
   # the restore you just performed — clearing the anchor discards the
   # very evidence that would show a truncation, so never run this to
   # make a finding go away.
   vendor/bin/typo3 vault:audit --verify
   vendor/bin/typo3 vault:audit --reset-anchor

   Copied!

Restore verification: the probe decrypt 

Listing secrets proves nothing — the list reads metadata and never touches the master key. Verification means decrypting.

# 1. Metadata is readable (proves the database restore, not the key).
vendor/bin/typo3 vault:list

# 2. Plaintext comes back (proves the key restore).
vendor/bin/typo3 vault:retrieve <a-known-identifier>

Probe more than one secret, and pick them deliberately: at least one written recently (encryption version 2, with an algorithm marker) and, if the installation has any, one legacy secret (version 1, algorithm derived from host capabilities). Those two take different branches through EncryptionService::resolveAlgorithm() , and a host that lacks hardware AES will fail the second while passing the first.

Every probe writes an audit row, which is the intended side effect: the restore verification leaves its own evidence.

Wrong-key symptoms 

Audit-chain consistency after a restore 

A restore is one of the few legitimate ways to produce findings that otherwise mean tampering. Expect and interpret them:

• ``HASH_MISMATCH`` from a given uid onwards — the audit table and the master key came from different points in time, or the table was restored partially. The chain is bound to the key from epoch 1 up.
• ``UID_GAP`` — rows were lost between the last backup and the restore point, or the dump excluded rows. A genuine restore artefact; document it with the backup timestamps rather than dismissing it.
• ``TABLE_RESET`` — the restored chain is shorter than the last published anchor, or the row at the anchored sequence hashes differently. This is the expected finding after restoring to an earlier point in time, and it is also exactly what a malicious reset looks like. The only thing that distinguishes them is your own record of the restore. Write it down: which backup, taken when, restored when, by whom — and keep the pre-restore anchor file alongside it.
• ``EPOCH_DOWNGRADE`` — usually a configuration mismatch: the restored auditHmacEpoch is higher than the epoch the restored rows carry. Restore the configuration that matches the data, then migrate forward with vault:audit-migrate-hmac if you want the higher epoch.
• ``NO_EXTERNAL_SINK`` (hardened only) — sinks were not re-enabled, or the anchor file was not restored. Re-enable and re-anchor.

Always re-anchor after a restore, and keep the old anchor file. The old anchor is what proves the restore happened when you say it did; the new one is what gives the next verification a usable baseline.