Developer 

What a custom provider must hold to 

Extending AbstractMasterKeyProvider is the supported route. What the base class supplies is the ADR-020 request-lifetime contract — the key is loaded at most once per request, cached in a slot keyed by your class, and wiped with sodium_memzero() — which it implements once as a final getMasterKey() plus the static clearCachedKey() . In exchange you implement loadRawKey() , its single abstract method.

The remaining MasterKeyProviderInterface methods stay with the provider either way: getIdentifier() , isAvailable() , storeMasterKey() and generateMasterKey() — the example above writes all four. Implementing the interface directly is allowed; then the caching and clearCachedKey() are yours to get right as well.

The rest is the contract every provider is held to:

Identifier

Distinct and non-blank. Two providers claiming one identifier is refused with exception code 1789430001, a blank identifier with 1789430002. An identifier decides which key source protects the vault, so the registry will not settle a collision by load order — and while one exists it refuses every lookup, not only the colliding name.

Constructor

Cheap. It runs while the registry builds its index, on the first vault operation of a request. Reaching the key source belongs in isAvailable() and loadRawKey() .

isAvailable()

Configuration completeness and local preconditions, with no network call. It is consulted on hot paths, so an outage at your key source must not turn into a per-request timeout. The built-in transit provider is the worked example.

getMasterKey()

Exactly 32 bytes. Never log the key and never put it in an exception message — that includes the path or URL it came from, which the built-in providers route to the PSR-3 log instead.

Rotation

storeMasterKey() is what vault:rotate-master-key calls. A source that cannot be written to should throw MasterKeyException::cannotStore() with a message saying how to rotate out of band, as the env provider does.

Security profile

A custom provider is permitted in the hardened profile. That profile refuses typo3 by name, because its demand is that the key lives outside config/system/settings.php, and an external provider is the case it asks for. It cannot police what your provider then does — deriving a key from the TYPO3 encryption key under another name would pass — so the installation is trusting the extension it installed.

Auto-detection never reaches a custom provider. When the configured provider is unavailable, the standard profile falls back through typo3, env and file only: quietly adopting an external key custody nobody configured would be worse than the misconfiguration it papers over.

Interpreting MSI 

MSI (Mutation Score Indicator)

% of all generated mutants that were detected (killed) by the test suite. Raw indicator of assertion density across the whole codebase.

Covered Code MSI

% of mutants in code reachable by tests that were killed. Removes noise from intentionally untested code (e.g. interfaces, enums).

Mutation Code Coverage

% of source lines that carry at least one mutant with a test. Closely tracks line coverage.

CI thresholds 

Thresholds live in infection.json5. They follow a ratchet strategy, so the committed values track the currently measured MSI rather than the long-term target:

{
    "minMsi": 77,
    "minCoveredMsi": 77
}

A run that falls below either threshold fails CI. Ratchet these numbers upward as test coverage improves; avoid ratcheting them downward (use a brief TODO with a ticket instead). The measurement the floors were set from, and the next target, are kept next to the values in infection.json5.

Badge generation 

After a successful Infection run, emit a shields.io-compatible badge:

./Build/Scripts/check-msi.sh > .Build/infection/badge.json

The output matches the shields.io endpoint schema and can be served from any HTTPS endpoint (GitHub Pages, CDN, …) and referenced from the README.

Manifest schema 

{
  "schemaVersion": 1,
  "extension": "nr_vault",
  "version": "0.13.0",
  "commit": "9267b6abba37cbe3b7cbdb856b0dc5a00beb2e07",
  "builtAt": "2026-07-31T20:15:00+00:00",
  "checks": [
    {
      "id": "coverage-line",
      "status": "pass",
      "summary": "line 95.65% (11454/11974 statements), branch 87.12% (6579/7551), path 5.02% (2411/47969) — bar 93.00%",
      "source": "clover.xml + coverage-text.txt"
    }
  ],
  "artifacts": [
    {"name": "clover.xml", "path": "artifacts/clover.xml", "sha256": "…"},
    {"name": "nr-vault-0.13.0.zip", "url": "https://github.com/…"}
  ]
}

The checks array is emitted in a fixed order with stable ids: release-identity, tests, coverage-line, coverage-security-dirs, coverage-branch, mutation-msi, mutation-msi-security, static-analysis, dependency-audit, vault-doctor. coverage-branch was added without a schema version change: it is a new entry in the checks array, and no existing field changed shape.

status

One of pass, warn, fail or absent.

absent

The producing step did not run in this build. This is recorded, never hidden, and never fails the collector.

tests

Aggregates every suite that left a JUnit log, keeping the per-suite counts in the summary. A suite that did not run is not listed — it is never counted as passing.

coverage-line

Line coverage against its bar, with branch and path coverage reported beside it. Branch and path figures exist only when the run collected them (Xdebug --path-coverage); otherwise they read n/a. Path coverage is reported but not gated: its denominator grows combinatorially with nested conditions, so a bar on it would punish readable branching rather than missing tests.

coverage-branch

Branch coverage overall and per security directory, each against its own bar. A coverage report without branch data is a warn, never a pass: the report exists, but it cannot show the bar was met.

mutation-msi-security

The same mutation analysis narrowed to Classes/Crypto, Classes/Security, Classes/Audit and Classes/Http, held to the stricter thresholds in infection-security.json5.

vault-doctor

Read from highestSeverity (pass/warning/critical), falling back to exitCode (0/1/2). Two subtleties matter, because vault:doctor overloads exit code 2:

• A run that could not start emits {"error": …, "exitCode": …} with no findings key — an unusable --profile value or an internal crash. That is recorded as fail: the gate did not run, and an ungated release is not a clean one.
• VaultDoctorService contains a crashing check by turning it into a check.crashed critical finding, so an unreachable database looks exactly like bad posture. When every critical is a check.crashed, the check is downgraded to warn and the summary says INCOMPLETE, naming the checks from details.check. A real critical alongside a crash still fails, so a crash can never mask an actual control failure.

An override is recorded too: --profile=hardened on a standard install renders as profile hardened (configured: standard), so the evidence never implies the live profile was the one evaluated.

Artifacts carry either a bundle-relative path plus sha256 (copied into the bundle) or a url (produced and signed by the release workflow, living on the GitHub Release — the manifest references those, it does not reproduce them).

Graceful degradation 

The collector exits 0 whenever it can describe the release honestly, including when producers are missing; a check status never changes the exit code. It exits 1 only when an artifact is present but unparseable, because then the bundle would misrepresent a check that really ran.

The schema, the per-producer degradation, and the malformed-artifact contract are pinned by a fixture-driven self-check that runs as part of composer ci :

composer ci:test:evidence