ADR-0007: Controlled cURL only; no proxies or PHP streams in v1

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-005, HG-020, HG-021, HG-022, HG-028, HG-042
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

PHP streams do not implement a cURL pin. With proxies, origin resolution can happen at the proxy; a locally checked IP then does not prove its target connection. Guzzle majors differ in permitted raw options.

Sources: [S05, S08, S12, S13, S17].

Decision

Enforce requires a tested cURL/curl-multi adapter. stream=true, foreign handlers, raw cURL options and uncertified transport-sharing settings are denied. cURL constants and behavior are checked for actual availability. The functional minimum version for multi-address support alone is not an accepted security baseline.

Version 1 supports no proxies. Explicit and actually inherited proxy configuration is detected; neither sending through it nor silently bypassing it is permitted. After the check passes, the controlled adapter prevents accidental proxy inheritance. An incoming HTTP Proxy header is not trusted process configuration.

The shared library contains separate, tested Guzzle 7/8 option adapters. Options that redirect transport remain owned by the guard. CA bundles, mTLS and approved timeouts are not replaced through raw override options.

Rejected alternatives

Allow every Guzzle handler: no uniform guarantee.
Allowlist a proxy as a private endpoint: checks only the proxy, not its origin access.
Automatic direct fallback: bypasses corporate routing.
Pass through arbitrary raw cURL flags: opens independent target/resolver paths.

Consequences

The v1 scope is clear and verifiable, but excludes proxy installations. A support error is visible rather than silently unsafe. Development must test real version combinations, not only Composer resolution.

Evidence and acceptance in the original proposal

T040, T041, T042, T043, T044, T058, T080, T084. 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 proxy adapter requires its own ADR, a defined trust model and evidence for the actual origin path. PHP streams also require independently proven binding before approval.