--- title: "Architecture decision records" manual: "nr-vault" version: "1.0" permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:adr-index@1.0" source: "Developer/Adr/Index.rst" rendered: "2026-09-18T07:37:50+00:00" --- # Architecture decision records {#architecture-decision-records} This section documents significant architectural decisions made during the development of nr-vault, along with the context and consequences of each decision. Architecture Decision Records (ADRs) capture important decisions along with their context and consequences. They provide a historical record of why certain decisions were made, helping future maintainers understand the codebase. **Table of contents** - [Overview](https://docs.typo3.org/permalink/netresearch/nr-vault:overview@1.0) ## Overview {#overview} | ADR | Title | Status | | --- | --- | --- | | 001 | [ADR-001: UUID v7 for secret identifiers](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-001-uuid-v7@1.0) | Accepted | | 002 | [ADR-002: Envelope encryption](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-002-envelope-encryption@1.0) | Accepted | | 003 | [ADR-003: Master key management](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-003-master-key-management@1.0) | Accepted | | 004 | [ADR-004: TCA integration](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-004-tca-integration@1.0) | Accepted | | 005 | [ADR-005: Access control](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-005-access-control@1.0) | Accepted | | 006 | [ADR-006: Audit logging](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-006-audit-logging@1.0) | Accepted | | 007 | [ADR-007: Secret metadata](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-007-secret-metadata@1.0) | Accepted | | 008 | [ADR-008: HTTP client](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-008-http-client@1.0) | Accepted | | 009 | [ADR-009: Extension configuration secrets](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-009-extension-configuration-secrets@1.0) | Accepted | | 010 | [ADR-010: Secure Outbound inside nr-vault](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-010-secure-outbound@1.0) | Accepted | | 011 | [ADR-011: Credential Sets data model](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-011-credential-sets@1.0) | Accepted | | 012 | [ADR-012: SecureHttpClient API and transports](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-012-secure-http-transports@1.0) | Accepted | | 013 | [ADR-013: Rust FFI preload-only mode](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-013-rust-ffi-preload@1.0) | Accepted | | 014 | [ADR-014: Packaging native artifacts](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-014-packaging-native@1.0) | Accepted | | 015 | [ADR-015: HTTP/3 feature flag](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-015-http3-feature-flag@1.0) | Accepted | | 016 | [ADR-016: Sidecar daemon option](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-016-sidecar-option@1.0) | Accepted | | 017 | [ADR-017: Audit metadata retention](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-017-audit-metadata-retention@1.0) | Accepted | | 018 | [ADR-018: FlexForm secret lifecycle management](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-018-flexform-secret-lifecycle@1.0) | Accepted | | 019 | [ADR-019: Configurable audit read logging](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-019-configurable-audit-read-logging@1.0) | Accepted | | 020 | [ADR-020: Master key request-lifetime caching](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-020-master-key-request-lifetime-caching@1.0) | Accepted | | 021 | [ADR-021: Batch secret loading](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-021-batch-secret-loading@1.0) | Accepted | | 022 | [ADR-022: Dedicated OAuth exception](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-022-dedicated-oauth-exception@1.0) | Accepted | | 023 | [ADR-023: Audit hash chain HMAC consideration](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-023-audit-hash-chain-hmac@1.0) | Accepted | | 024 | [ADR-024: Audit hash payload covers forensic fields](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-024-audit-hash-forensic-fields@1.0) | Accepted | | 025 | [ADR-025: Secret entity is a readonly value object](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-025-secret-entity-readonly@1.0) | Accepted | | 026 | [ADR-026: DNS-rebinding defence via CURLOPT_RESOLVE](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-026-dns-rebinding-defence@1.0) | Amended | | 027 | [ADR-027: OAuth token requests use the secure HTTP client](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-027-oauth-client-unification@1.0) | Accepted | | 028 | [ADR-028: PHPat architectural lock for HTTP client construction](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-028-phpat-http-client-lock@1.0) | Accepted | | 029 | [ADR-029: Scoped technical-actor identity for headless use](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-029-technical-actor-context@1.0) | Accepted | | 030 | [ADR-030: Read-time resolution of site-configuration vault references](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-030-site-config-vault-read-time-resolution@1.0) | Accepted | | 031 | [ADR-031: One shared catalogue of secret shapes](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-031-shared-secret-pattern-catalogue@1.0) | Accepted | | 032 | [ADR-032: A portable envelope codec for consumer-owned payloads](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-032-portable-envelope-codec@1.0) | Accepted | | 033 | [ADR-033: Master-key rotation reaches consumer-owned envelopes](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-033-foreign-envelope-rotation@1.0) | Accepted | | 034 | [ADR-034: Audit chain tip anchor](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-034-audit-chain-tip-anchor@1.0) | Accepted | | 035 | [ADR-035: Per-request allow-set of frontend-resolvable identifiers](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-035-frontend-placeholder-allow-set@1.0) | Amended | | 036 | [ADR-036: Mutation and audit are all-or-nothing](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-036-mutation-audit-atomicity@1.0) | Accepted | | 037 | [ADR-037: A cancellable send is a method, not an exported handle](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-037-cancellable-outbound-send@1.0) | Accepted | | 038 | [ADR-038: A host we cannot resolve is refused, not handed to curl](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-038-unresolvable-host-is-refused@1.0) | Accepted | - [ADR-001: UUID v7 for secret identifiers](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-001-uuid-v7-for-secret-identifiers@1.0) - [ADR-002: Envelope encryption](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-002-envelope-encryption-1@1.0) - [ADR-003: Master key management](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-003-master-key-management-1@1.0) - [ADR-004: TCA integration](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-004-tca-integration-1@1.0) - [ADR-005: Access control](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-005-access-control-1@1.0) - [ADR-006: Audit logging](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-006-audit-logging-1@1.0) - [ADR-007: Secret metadata](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-007-secret-metadata-1@1.0) - [ADR-008: HTTP client](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-008-http-client-1@1.0) - [ADR-009: Extension configuration secrets](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-009-extension-configuration-secrets-1@1.0) - [ADR-010: Secure Outbound inside nr-vault](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-010-secure-outbound-inside-nr-vault@1.0) - [ADR-011: Credential Sets data model](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-011-credential-sets-data-model@1.0) - [ADR-012: SecureHttpClient API and transports](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-012-securehttpclient-api-and-transports@1.0) - [ADR-013: Rust FFI preload-only mode](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-013-rust-ffi-preload-only-mode@1.0) - [ADR-014: Packaging native artifacts](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-014-packaging-native-artifacts@1.0) - [ADR-015: HTTP/3 feature flag](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-015-http-3-feature-flag@1.0) - [ADR-016: Sidecar daemon option](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-016-sidecar-daemon-option@1.0) - [ADR-017: Audit metadata retention](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-017-audit-metadata-retention-1@1.0) - [ADR-018: FlexForm secret lifecycle management](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-018-flexform-secret-lifecycle-management@1.0) - [ADR-019: Configurable audit read logging](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-019-configurable-audit-read-logging-1@1.0) - [ADR-020: Master key request-lifetime caching](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-020-master-key-request-lifetime-caching-1@1.0) - [ADR-021: Batch secret loading](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-021-batch-secret-loading-1@1.0) - [ADR-022: Dedicated OAuth exception](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-022-dedicated-oauth-exception-1@1.0) - [ADR-023: Audit hash chain HMAC consideration](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-023-audit-hash-chain-hmac-consideration@1.0) - [ADR-024: Audit hash payload covers forensic fields](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-024-audit-hash-payload-covers-forensic-fields@1.0) - [ADR-025: Secret entity is a readonly value object](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-025-secret-entity-is-a-readonly-value-object@1.0) - [ADR-026: DNS-rebinding defence via CURLOPT_RESOLVE](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-026-dns-rebinding-defence-via-curlopt-resolve@1.0) - [ADR-027: OAuth token requests use the secure HTTP client](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-027-oauth-token-requests-use-the-secure-http-client@1.0) - [ADR-028: PHPat architectural lock for HTTP client construction](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-028-phpat-architectural-lock-for-http-client-construction@1.0) - [ADR-029: Scoped technical-actor identity for headless use](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-029-scoped-technical-actor-identity-for-headless-use@1.0) - [ADR-030: Read-time resolution of site-configuration vault references](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-030-read-time-resolution-of-site-configuration-vault-references@1.0) - [ADR-031: One shared catalogue of secret shapes](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-031-one-shared-catalogue-of-secret-shapes@1.0) - [ADR-032: A portable envelope codec for consumer-owned payloads](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-032-a-portable-envelope-codec-for-consumer-owned-payloads@1.0) - [ADR-033: Master-key rotation reaches consumer-owned envelopes](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-033-master-key-rotation-reaches-consumer-owned-envelopes@1.0) - [ADR-034: Audit chain tip anchor](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-034-audit-chain-tip-anchor-1@1.0) - [ADR-035: Per-request allow-set of frontend-resolvable identifiers](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-035-per-request-allow-set-of-frontend-resolvable-identifiers@1.0) - [ADR-036: Mutation and audit are all-or-nothing](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-036-mutation-and-audit-are-all-or-nothing@1.0) - [ADR-037: A cancellable send is a method, not an exported handle](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-037-a-cancellable-send-is-a-method-not-an-exported-handle@1.0) - [ADR-038: A host we cannot resolve is refused, not handed to curl](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-038-a-host-we-cannot-resolve-is-refused-not-handed-to-curl@1.0)