ADR-0002: A shared library instead of a Vault dependency for every extension

Status: Superseded by ADR-0015 (original status: Proposed)
Date: 2026-10-08
Original decision makers: Project architecture/security owners; approval still pending in the original proposal.
Requirements: HG-006, HG-036, HG-037, HG-041, HG-045
Original supersession: None; a new decision for the proposed product.

Note

This is the full English translation of the historical proposal dated 2026-10-08, originally Proposed. Its pending approval is historical and creates no additional alpha approval gate. Current Security model and limits, Development and tests, Verification report and Requirements and security invariants describe the operative scope and evidence.

ADR-0015: One installable extension supersedes the package split. The original reasons for separating security and integration responsibilities remain historical context; the original decision below is not silently rewritten.

Context

nr-vault already has target validation, DNS pinning and its own handler stack. It also performs tasks outside general network protection: secret access, credential injection, audit, OAuth and specialized streaming/cancellation APIs.

Sources: [S04-S08, S16].

Decision

Proposed split: netresearch/http-guard as a standalone PHP library and netresearch/nr-http-guard as the TYPO3 integration. nr-vault consumes the library through its own adapter. Configuration, resolver, clock and reporter are injected into the library; it reads no TYPO3 globals and knows no Vault database.

Security mechanisms and their regressions are extracted, rather than accepting every historical exception without review. Vault retains its credential-bearing interfaces and domain responsibility. The library package offers no secret export.

When existing Vault code is adopted, its copyright and SPDX notices are retained. As a compatible project proposal, both new packages use GPL-2.0-or-later; publication under a different license requires separate prior clarification of rights. This ADR grants no new rights.

Rejected alternatives

Every extension depends on nr-vault: unnecessary domain coupling.
A third copy of the same methods: security fixes drift between copies.
Replace Vault's entire client: threatens established authentication/streaming semantics.
Introduce a standalone library later: entrenches incorrect dependencies again.

Consequences

A security fix reaches every integrated path through the same corpus. Two new package surfaces and coordinated releases are required. Abstractions remain limited to the two actual integrations; this is not a general HTTP framework.

Evidence and acceptance in the original proposal

T007, T069, T070, T072, T076, T080. Details and expected results are in Original verification specification. These tests were specified, not executed as part of the original documentation delivery.

Reasons to reconsider

A third consumer may justify additional adapters. Extending the library with credential management requires a new decision and is not implicitly permitted.