pinned-http-client — PSR-18 client for untrusted URLs that pins the connection to checked addresses
$ composer require rasuvaeff/pinned-http-client
$client = new PinnedClient(); // public addresses only, IPv4 + IPv6, 8 s / 4 s, body <= 10 MiB, no proxy try { $response = (new RedirectFollower($client))->sendRequest(new Request('GET', $untrustedUrl));} catch (RequestRefused $refused) { $refused->reason; // Refusal::UnsupportedScheme | MissingHost | AddressNotAllowed} catch (ResponseTooLarge $tooLarge) { // the body (decompressed) passed maxBodyBytes; the transfer was cut} catch (ClientException $failed) { // TransferFailed (connection, TLS, timeout), ResolutionFailed (DNS) or TooManyRedirects}
A PSR-18 client for untrusted URLs. It resolves the host once, checks every address and pins cURL to them.
DNS can answer a public address to the check and 127.0.0.1 or 169.254.169.254 (cloud metadata) to the later request. Checking the host name is not an SSRF defence.
PublicAddresses default policy refuses private, loopback, link-local, CGNAT and multicast ranges.AddressPolicy and Resolver interfaces.RedirectFollower re-resolves, re-checks and re-pins every hop.HTTP_PROXY / HTTPS_PROXY from the environment; a proxy is opt-in via proxy:.RequestRefused, ResolutionFailed, ResponseTooLarge, TransferFailed, TooManyRedirects.The default policy allows only public addresses; private, loopback and link-local ones are refused, and an IPv4-mapped address is judged as the IPv4 it carries.
$policy = new PublicAddresses(); foreach (['93.184.216.34', '::ffff:8.8.8.8', '127.0.0.1', '10.0.0.5', '169.254.169.254', '::ffff:10.0.0.1', 'fd12::1', '100.64.0.1'] as $address) { echo str_pad($address, 24), $policy->allows($address) ? 'allowed' : 'refused', "\n";}
A custom AddressPolicy relaxes or tightens the rule, for instance to let a development host through.
final readonly class PublicOrLoopback implements AddressPolicy{ public function __construct(private AddressPolicy $inner) {} public function allows(string $address): bool { return $address === '127.0.0.1' || $this->inner->allows($address); }} $client = new PinnedClient(policy: new PublicOrLoopback(new PublicAddresses()));
link-preview recommends it as the PSR-18 client for its Fetcher.
timeoutSeconds does not bound DNS resolution, and a hostile system resolver is out of scope. With an explicit proxy, the proxy becomes your SSRF boundary.
Requires ext-curl, ext-filter, Guzzle 7.9 and PSR HTTP interfaces.
First released as v0.1.0 on 2026-10-23; 5 releases in all.
| v1.0.1 | 2026-11-19 |
| v1.0.0 | 2026-11-01 |
| v0.3.0 | 2026-11-01 |
| v0.2.0 | 2026-11-01 |
| v0.1.0 | 2026-10-23 |
/ search · n N next, previous · g G top, bottom · q back to the index