ADR-0012: Stable denial reasons without new secret leaks

Status: Historical proposal (original status: Proposed)
Date: 2026-10-08
Original decision makers: Project architecture/security owners; approval still pending in the original proposal.
Requirements: HG-031, HG-032, HG-033, HG-034, HG-035
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.

The later single-package decision is recorded in ADR-0015: One installable extension.

Context

A security guard needs diagnostics, but logs can themselves expose credentials. URLs may carry query tokens; requests contain bodies, cookies and authentication headers. A statistics callback run after sending is also not preventive connection control.

Sources: [S04, S08, S15].

Decision

The library supplies fixed reason codes with a typed exception surface. Synchronous and promise-based calls do not differ in policy decision. Policy errors are not disguised as ordinary network timeouts. PSR-18 recognizes them as client errors; the included request may still be a sensitive object.

Telemetry contains mode, decision, profile/policy identifier, address class, scheme/port, resolver source and correlation. No bodies, header values, URL paths, queries or complete exceptions. Host display is configured separately; pseudonymous host values use an operator HMAC key, not a publicly guessable hash presented as anonymization. Metric labels retain low cardinality.

Logger errors must never turn deny into allow. Rate limits reduce log floods, not denial counters. Diagnostic commands send no probe HTTP requests. on_stats may report a deviation afterwards, but never replaces plan/pin protection.

Rejected alternatives

Log complete requests for debugging: creates an exfiltration path.
Label every denial an attack: confuses typos, DNS problems and abuse.
Always deny HTTP on logging failure: unnecessary global availability coupling; Vault audit may separately be stricter.

Consequences

Operations can identify causes without exposing secrets. Deeper debugging requires targeted synthetic reproduction. Other project middleware remains responsible for its own logs; the guard cannot retrospectively sanitize its telemetry.

Evidence and acceptance in the original proposal

T062, T063, T064, T065, T067, T068. 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

Before inclusion, new telemetry fields are checked for secret content and cardinality. A complete request dump is not permitted as a debugging convenience.