ADR-004: TCA integration 

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

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

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

    // After save: Store secrets with correct UID. The shipped hook
    // delegates this to PendingSecretPersister, which rolls the field
    // value back and reports to the editor when the store is refused.
    public function processDatamap_afterDatabaseOperations(...): void
    {
        foreach ($this->pendingSecrets[$table][$id] as $field => $data) {
            $this->vaultService->store($data['uuid'], $data['value'], [
                'metadata' => [
                    'table' => $table,
                    'field' => $field,
                    'uid' => $recordUid,
                    'source' => 'tca_field',
                ],
            ]);
        }
    }

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

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

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

    // Store the pending secrets once the record has its final UID
    public function processDatamap_afterDatabaseOperations(...): void;

    // Before delete: remove the secrets the FlexForm references
    public function processCmdmap_deleteAction(...): void;

    // After copy: re-key the copied FlexForm onto fresh identifiers
    public function processCmdmap_postProcess(...): void;
}

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

use Netresearch\NrVault\TCA\VaultFieldHelper;

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

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

Form Submit:
1. DataHandlerHook.preProcess extracts secret value
2. Generates UUID v7 identifier (see ADR-001)
3. Sets field value to UUID (for database)
4. DataHandlerHook.afterDatabaseOperations delegates to
   PendingSecretPersister, which stores the secret in the vault
5. On refusal: the field value is rolled back, VaultFailureReporter tells
   the editor, and no success audit entry survives

Record Delete:
1. DataHandlerHook.processCmdmap_preProcess finds vault fields
2. Retrieves UUIDs from record
3. Asserts every field's delete gate BEFORE removing the first secret
4. Deletes corresponding vault secrets
5. On failure: processCmdmap cancels the record delete, so the record and
   its surviving secret stay together rather than orphaning either

Record Copy:
1. DataHandlerHook.processCmdmap_postProcess detects copy
2. Retrieves source secrets by UUID
3. Creates new secrets with new UUIDs for copied record
4. On failure: the secrets already cloned are deleted again and every
   vault field of the new record is blanked; both steps are best-effort,
   so a failed rollback delete leaves an orphaned clone and a failed
   blanking leaves the copy referencing the source record's secrets

use Netresearch\NrVault\Utility\VaultFieldResolver;

// VaultFieldResolver is a DI service, not a static utility — inject it.
public function __construct(
    private readonly VaultFieldResolver $vaultFieldResolver,
) {}

// Resolve specific fields
$resolved = $this->vaultFieldResolver->resolveFields($record, ['api_key']);

// Auto-detect vault fields from TCA
$resolved = $this->vaultFieldResolver->resolveRecord('tx_myext_settings', $record);