API 

Extension points and the compatibility promise 

Most interfaces in this chapter are for calling. Six are for implementing: an extension plugs its own code into nr-vault through them. They carry the #[\Netresearch\NrVault\Attribute\ExtensionPoint] attribute, and the test suite checks this list against that attribute:

• Netresearch\NrVault\Adapter\VaultAdapterInterface — a storage backend (Custom storage adapters)
• Netresearch\NrVault\Crypto\MasterKeyProviderInterface — a master-key source, selected by the identifier it declares and registered with the nr_vault.master_key_provider tag (Custom master key providers)
• Netresearch\NrVault\Audit\Sink\AuditSinkInterface — an external destination for audit evidence
• Netresearch\NrVault\Crypto\ForeignEnvelopeRotatorInterface — re-wraps the envelopes a consuming extension stores itself (ForeignEnvelopeRotator)
• Netresearch\NrVault\Service\Doctor\ReadinessCheckInterface — an additional vault:doctor control
• Netresearch\NrVault\Http\CancellationSignalInterface — a caller-owned cancellation signal for a secure outbound send (Cancelling an outbound request)

A new method means different things to a caller and to an implementation, so the two kinds of interface carry different promises:

Extension points

No method is added, and no method signature changes, outside a major release — not even by an optional parameter. PHP refuses to load a class whose methods no longer match its interface, so either change would break every existing implementation. A new capability arrives as a separate interface that an implementation may additionally implement and a caller detects with instanceof, the way CancellableHttpClientInterface joined VaultHttpClientInterface.

All other interfaces

Are for calling. A minor release may add methods to them; existing calls keep working. Implementing one of them outside this package is not supported, and such an implementation may stop loading after any update.

Removing or changing anything a caller uses — a method, a parameter, an enum backing value, an exception class — is a breaking change for either kind and waits for a major release.

VaultService 

The main service for interacting with the vault.

interface VaultServiceInterface

Fully qualified name

\Netresearch\NrVault\Service\VaultServiceInterface

Main interface for vault operations.

Note

The plaintext parameters $secret / $newSecret carry the PHP #[\SensitiveParameter] attribute on the interface, so they are redacted from stack traces and var_dump() output. Mirror the attribute on any custom implementation.

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

Store a secret in the vault. $secret is a #[\SensitiveParameter].

param string $identifier

Unique identifier for the secret.

param string $secret

The secret value to store (#[\SensitiveParameter]).

param array $options

Optional configuration: owner (int BE-user UID), groups (int[] BE-group UIDs), context (string), expiresAt (int|DateTimeInterface|null), metadata (array), description (string), scopePid (int).

throws ValidationException

If the identifier is invalid.

throws AccessDeniedException

If the per-secret ACL or the operation permission refuses the write — secret.create on a new secret, secret.rotate on an existing one, and additionally secret.manage_policy when the options change the owner or the group tiers.

throws EncryptionException

If encryption fails.

Operation permissions and the per-secret ACL are two independent gates. Holding one never implies the other, and both are asserted before the value is written.

retrieve(string $identifier)

Retrieve a secret from the vault.

param string $identifier

The secret identifier.

returntype

string|null

throws AccessDeniedException

If user lacks read permission.

throws SecretExpiredException

If the secret has expired.

Returns

The decrypted secret value or null if not found.

retrieveForFrontend(string $identifier)

Frontend-scoped counterpart of retrieve(). Only secrets flagged frontend_accessible resolve here, and that requirement holds for every caller — including a request that happens to carry a backend session, whose ambient privileges would otherwise widen retrieve()'s access decision. Expiry, decryption, audit logging and read statistics behave as in retrieve(). See ADR-035: Per-request allow-set of frontend-resolvable identifiers.

param string $identifier

The secret identifier.

returntype

string|null

throws AccessDeniedException

If the secret is not frontend-accessible, or the actor lacks read permission.

throws SecretExpiredException

If the secret has expired.

Returns

The decrypted secret value or null if not found.

exists(string $identifier): bool

Check if a secret exists.

param string $identifier

The secret identifier.

Returns

True if the secret exists.

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

Delete a secret from the vault.

The secret is gone for every vault operation, and there is no restore operation. The row is a soft delete, though: it is marked deleted and keeps its ciphertext and wrapped DEK, in the database and in every backup, until it is removed at the database level. vault:rotate-master-key does not re-wrap deleted rows, so destroying the master key they were wrapped under makes them unreadable. See Secret disposal.

param string $identifier

The secret identifier.

param string $reason

Optional reason for deletion (logged).

throws SecretNotFoundException

If secret doesn't exist.

throws AccessDeniedException

If user lacks delete permission.

assertDeletable(string $identifier): void

Assert that delete() is permitted for this identifier — without deleting. Exists for callers that delete several secrets as one logical unit, such as a record delete spanning multiple vault fields: a vault delete cannot be undone through the vault, so a partially applied batch cannot be compensated, and the only way to keep it all-or-nothing is to run every permission gate up front and abort before the first deletion.

A secret that does not exist returns without throwing — the goal state is already reached. Ask exists() to distinguish absent from present. Passing does not guarantee the subsequent delete succeeds: an audit-write failure, or a permission revoked in between, can still abort it.

param string $identifier

The secret identifier.

throws AccessDeniedException

If the current actor lacks delete permission.

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

Rotate a secret with a new value. $newSecret is a #[\SensitiveParameter].

param string $identifier

The secret identifier.

param string $newSecret

The new secret value (#[\SensitiveParameter]).

param string $reason

Optional reason for rotation (logged).

throws SecretNotFoundException

If the secret does not exist.

throws AccessDeniedException

If the per-secret ACL or the secret.rotate operation permission refuses it.

throws EncryptionException

If encryption fails.

setEnabled(string $identifier, bool $enabled, string $reason = ''): void

Enable or disable a secret — the single write path for its availability.

Disabling withdraws the secret from every read path at once: the record carries TCA's disabled enable column, so a disabled secret resolves to nothing in retrieve() , retrieveForFrontend() and every placeholder that goes through them. It stays administrable — it can be re-enabled, rotated, deleted, and its metadata read — and reports its state in SecretDetails::$enabled .

The state is absolute rather than a toggle: setting the state a secret already has is a no-op and writes no audit entry. A change is audited as metadata_update, the same action the FormEngine path writes for the same column, and is all-or-nothing with that entry (ADR-036: Mutation and audit are all-or-nothing): if the audit write fails the previous availability is restored and the failure surfaces.

param string $identifier

The secret identifier.

param bool $enabled

The availability the secret should have afterwards.

param string $reason

Optional justification, recorded in the audit entry alongside the direction of the change.

throws SecretNotFoundException

If the secret does not exist.

throws AccessDeniedException

If the per-secret ACL or the secret.manage_policy operation permission refuses it.

list(?string $pattern = null, bool $includeDisabled = false): array

List accessible secrets.

param string|null $pattern

Optional pattern to filter identifiers (supports the * wildcard).

param bool $includeDisabled

Also return disabled secrets. Off by default, so a consumer asking which secrets are available keeps the answer it had; the management surfaces pass true, because a disabled secret that never appears in a listing cannot be re-enabled.

Returns

A list<SecretMetadata> of secret metadata DTOs (Netresearch\NrVault\Domain\Dto\SecretMetadata); each entry reports its availability in $enabled.

getMetadata(string $identifier): SecretDetails

Get metadata for a secret without retrieving its value. Resolves a disabled secret too — metadata is not the value, and withholding it would hide the record from the form that re-enables it.

param string $identifier

The secret identifier.

throws SecretNotFoundException

If secret doesn't exist.

throws AccessDeniedException

If user lacks permission.

Returns

A SecretDetails DTO (Netresearch\NrVault\Domain\Dto\SecretDetails) with identifier, description, owner, groups, version, availability ($enabled), etc.

http(): VaultHttpClientInterface

Get an HTTP client that can inject secrets into requests.

Returns

A PSR-18 compatible vault-aware HTTP client.

EncryptionService 

The crypto boundary: libsodium envelope encryption (per-secret DEK wrapped by the master key).

interface EncryptionServiceInterface

Fully qualified name

\Netresearch\NrVault\Crypto\EncryptionServiceInterface

Low-level encryption operations. Most callers use VaultServiceInterface instead.

Note

Plaintext and key parameters ($plaintext, $encryptedValue, $encryptedDek, $oldMasterKey, $newMasterKey) carry the #[\SensitiveParameter] attribute on the interface.

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

Encrypt a plaintext value with a unique DEK. $plaintext is a #[\SensitiveParameter].

param string $plaintext

The value to encrypt (#[\SensitiveParameter]).

param string $identifier

Secret identifier (used as AAD).

throws EncryptionException

If encryption fails.

Returns

An EncryptedData value object (Netresearch\NrVault\Crypto\EncryptedData) holding the ciphertext, encrypted DEK, and nonces.

decrypt(string $encryptedValue, string $encryptedDek, string $dekNonce, string $valueNonce, string $identifier, int $encryptionVersion = 1, string $encryptionAlgorithm = ''): string

Decrypt a previously encrypted value. $encryptedValue and $encryptedDek are #[\SensitiveParameter].

param string $encryptedValue

Base64-encoded ciphertext (#[\SensitiveParameter]).

param string $encryptedDek

Base64-encoded encrypted DEK (#[\SensitiveParameter]).

param string $dekNonce

Base64-encoded DEK nonce.

param string $valueNonce

Base64-encoded value nonce.

param string $identifier

Secret identifier (used as AAD).

param int $encryptionVersion

Stored per-secret encryption version. Defaults to ENCRYPTION_VERSION_LEGACY (1), where the algorithm is derived from host capabilities.

param string $encryptionAlgorithm

Stored per-secret algorithm marker. Required for version 2+, must be '' for version 1.

throws EncryptionException

If decryption fails or the marker is unknown on this host.

Returns

The decrypted plaintext.

generateDek(): string

Generate a new Data Encryption Key.

Returns

A 32-byte random key.

calculateChecksum(string $plaintext): string

Calculate a value checksum for change detection. $plaintext is a #[\SensitiveParameter].

param string $plaintext

The secret value (#[\SensitiveParameter]).

Returns

SHA-256 hash (64 hex characters).

reEncryptDek(string $encryptedDek, string $dekNonce, string $identifier, string $oldMasterKey, string $newMasterKey, int $encryptionVersion = 1, string $encryptionAlgorithm = ''): ReEncryptedDek

Re-encrypt a DEK with a new master key (used during master-key rotation). $encryptedDek, $oldMasterKey and $newMasterKey are #[\SensitiveParameter].

param string $encryptedDek

Current encrypted DEK (#[\SensitiveParameter]).

param string $dekNonce

Current DEK nonce.

param string $identifier

Secret identifier.

param string $oldMasterKey

Previous master key (#[\SensitiveParameter]).

param string $newMasterKey

New master key (#[\SensitiveParameter]).

param int $encryptionVersion

Stored per-secret encryption version.

param string $encryptionAlgorithm

Stored per-secret algorithm marker (required for version 2+).

The DEK is re-wrapped with the SAME algorithm the secret was encrypted with; the version and algorithm markers are unchanged by the operation.

Returns

A ReEncryptedDek value object (Netresearch\NrVault\Crypto\ReEncryptedDek).

EnvelopeCodec 

Envelope encryption for a payload you keep in ONE column of your own table (ADR-032). Use this instead of EncryptionServiceInterface when you have a blob rather than the vault's seven-column layout.

interface EnvelopeCodecInterface

Fully qualified name

\Netresearch\NrVault\Crypto\EnvelopeCodecInterface

const MARKER

'nrv1:' — the version marker of the envelopes seal() produces. A stored value is self-identifying, so a column can hold sealed and unsealed values during a migration.

seal(string $plaintext, string $identifier): string

Encrypt a payload into a single string. $plaintext is a #[\SensitiveParameter].

param string $plaintext

The payload to protect (#[\SensitiveParameter]).

param string $identifier

Context label bound to the ciphertext as additional authenticated data. Use a stable, per-purpose value (a column or use-case name), never a per-row one.

throws EncryptionException

If encryption fails or the master key is unavailable.

Returns

MARKER + base64-encoded JSON envelope.

open(string $sealed, string $identifier): string

Decrypt a sealed string. The stored change-detection checksum is not verified — integrity comes from the AEAD tag, which is always checked.

param string $sealed

A string produced by seal() .

param string $identifier

The SAME identifier the payload was sealed with.

throws EnvelopeFormatException

If the string is not a well-formed envelope.

throws EncryptionException

If authentication fails, the algorithm marker is unknown on this host, or the master key is unavailable.

Returns

The decrypted payload.

isSealed(string $value): bool

Whether a stored value is an envelope, as opposed to a plain value written before sealing was introduced.

rewrap(string $sealed, string $identifier, string $oldMasterKey, string $newMasterKey): string

Re-wrap the envelope's DEK from one master key to another, leaving the payload ciphertext untouched — nothing is decrypted. This is the primitive behind ForeignEnvelopeRotatorInterface ; you normally reach it through EnvelopeRotationContext::rewrap() rather than calling it directly.

ForeignEnvelopeRotator 

How a consuming extension joins master-key rotation (ADR-033). Tag your implementation:

Vendor\Extension\Crypto\MyEnvelopeRotator:
  tags: ['nrvault.foreign_envelope_rotator']

interface ForeignEnvelopeRotatorInterface

Fully qualified name

\Netresearch\NrVault\Crypto\ForeignEnvelopeRotatorInterface

getIdentifier(): string

Short label naming your extension and the data it owns, for the operator-facing rotation report (e.g. nr-llm: agent run state).

getTables(): array

Every table rewrapAll() writes to. The command refuses to rotate when one of them is mapped to a different database connection than tx_nrvault_secret, because atomicity across two connections is a fiction.

countEnvelopes(): int

How many sealed envelopes you hold. Called outside the transaction, for the dry-run report and the operator summary. Throwing aborts the rotation before anything is touched.

rewrapAll(EnvelopeRotationContext $context): int

Re-wrap every envelope you own; return how many. Runs INSIDE the vault's rotation transaction, after the vault's own secrets and before the commit.

Do not open, commit or roll back a transaction, and do not swallow failures: throwing rolls the ENTIRE rotation back, which is deliberate — a partial rotation leaves data wrapped under a key the operator has been told to destroy. Work in batches; the whole pass is one transaction.

class EnvelopeRotationContext

Fully qualified name

\Netresearch\NrVault\Crypto\EnvelopeRotationContext

Handed to rewrapAll() . It closes over the old and new master keys and exposes only the operation, so you move envelopes between keys without ever holding key material.

rewrap(string $sealed, string $identifier): string

Re-wrap one envelope's DEK. The payload is not decrypted.

isSealed(string $value): bool

For skipping rows written before you started sealing.

SecretRedactor 

The shared catalogue of recognisable secret shapes (ADR-031), used by this extension's plaintext scanner and available to any consumer that needs to mask secrets in log lines, error messages or outbound payloads.

This is a best-effort net for secrets that have already escaped their proper home. It recognises the catalogued shapes and nothing else, and is not a substitute for keeping secrets in the vault.

interface SecretRedactorInterface

Fully qualified name

\Netresearch\NrVault\Secret\SecretRedactorInterface

redact(string $text, bool $includeEmails = false): string

Replace every recognised secret occurrence in free text with a mask.

param bool $includeEmails

Also mask e-mail addresses. Off by default: an address is personal data rather than a secret, and masking one inside, say, a model prompt changes what the text says.

Returns

The masked text. If the regex engine gives up on a pathological input the text is returned as-is rather than emptied.

isSecretIdentifier(string $identifier, SecretIdentifierKind $kind): bool

Whether a name reads as secret-bearing within its namespace. The kind matters: database columns and configuration keys are suffix-anchored, while environment variables use a broad substring rule. A name check alone is not enough — GITHUB_PAT says nothing about being secret — so pair it with identifyValue() or redact() on the value.

identifyValue(string $value)

The shape name when the WHOLE value is a known secret format, else null. Leading and trailing whitespace is ignored.

Returns

string|null — the matched shape name, or null.

enum SecretIdentifierKind

Fully qualified name

\Netresearch\NrVault\Secret\SecretIdentifierKind

DatabaseColumn, ConfigurationKey, EnvironmentVariable — the three identifier namespaces, deliberately not merged into one rule set.

use Netresearch\NrVault\Service\VaultServiceInterface;

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

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

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

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

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

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

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

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

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

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

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

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

use Netresearch\NrVault\Http\CancellableHttpClientInterface;
use Netresearch\NrVault\Http\CancellationSignalInterface;
use Netresearch\NrVault\Exception\RequestCancelledException;

final class RunCancellationSignal implements CancellationSignalInterface
{
    public function __construct(private readonly MyRunState $run) {}

    public function isCancelled(): bool
    {
        return $this->run->wasCancelled();
    }
}

$client = $this->vaultService->http()
    ->withAuthentication('tool_api_key')
    ->withReason('MCP tool call')
    ->withTimeout(15);

try {
    $response = $client instanceof CancellableHttpClientInterface && $client->supportsCancellation()
        ? $client->sendCancellable($request, new RunCancellationSignal($run))
        : $client->sendRequest($request);
} catch (RequestCancelledException $e) {
    // The call was abandoned on purpose; the audit log already recorded it.
}

use Netresearch\NrVault\Http\StreamingHttpClientInterface;

$client = $this->vaultService->http()
    ->withAuthentication('openai_api_key')
    ->withReason('Chat completion stream')
    ->withTimeout(120);

if ($client instanceof StreamingHttpClientInterface && $client->supportsStreaming()) {
    $response = $client->sendStreaming($request, $signal);
} else {
    $response = $client->sendRequest($request);
}

$body = $response->getBody();
$buffer = '';
while (!$body->eof()) {
    $buffer .= $body->read(8192);
    while (($end = strpos($buffer, "\n")) !== false) {
        $this->handleLine(substr($buffer, 0, $end));
        $buffer = substr($buffer, $end + 1);
    }
}

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

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

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

// Custom Authorization scheme (e.g. DeepL "Authorization: DeepL-Auth-Key <key>")
$client = $this->vault->http()
    ->withAuthentication('deepl_api_key', SecretPlacement::Header, [
        'headerName' => 'Authorization',
        'prefix' => 'DeepL-Auth-Key ',
    ]);
$response = $client->sendRequest(
    new Request('POST', 'https://api-free.deepl.com/v2/translate', [], $body)
);

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

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