qiick / laravel-outbound
SSRF-safe outbound HTTP and Standard Webhooks signing for qiick Laravel products.
Requires
- php: ^8.3
- ext-curl: *
- ext-intl: *
- guzzlehttp/guzzle: ^7.8 || ^8.0
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- larastan/larastan: ^3.3.1
- laravel/pint: ^1.30.4 <1.31.0
- nunomaduro/collision: ^8.5
- orchestra/testbench: ^10.0 || ^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-mutate: ^4.0
- phpstan/phpstan: ^2.1.11
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 17:26:39 UTC
README
qiick/laravel-outbound
In development. Not released and not on Packagist yet: do not depend on it.
SSRF-safe outbound HTTP and Standard Webhooks signing for qiick Laravel products.
Status
This package is under active construction against the approved design
(projects/qiick/packages/laravel-outbound-design.md in the qiick knowledge
base). Public APIs, evaluation order and security properties are binding once
shipped; until 0.1.0 lands on Packagist, treat every surface as unstable.
Purpose
One canonical path for:
- SSRF-safe outbound HTTP — curl-style IPv4 reading, metadata blocking
(including Alibaba/Oracle even when private hosts are allowed), resolve-all
DNS checks, and
CURLOPT_CONNECT_TOpinning (neverCURLOPT_RESOLVEalone). - Standard Webhooks — symmetric
v1signing and verification over the exact raw body bytes, multi-secret rotation bounds, and pure retry schedules.
Non-goals for v1: delivery tables/migrations, queue job bases / auto-disable
enforcement (product duty), asymmetric Standard Webhooks (v2a), global
helpers, a hard dependency on laravel/framework.
Threat model
Attackers who control a destination URL (webhook endpoint, IdP discovery URL, user-supplied fetch target) must not reach:
- Cloud metadata (
169.254.169.254,fd00:ec2::254,100.100.100.200,192.0.0.192,metadata/metadata.google.internal) - Loopback, private, CGNAT, link-local, ULA, or unspecified addresses when private hosts are disallowed
- Transition prefixes that re-embed IPv4 (NAT64, 6to4, Teredo)
- DNS-rebinding races (pin the checked address with
CURLOPT_CONNECT_TOon every hop; redirects never use transport auto-follow) - Signature forgery or replay on inbound Standard Webhooks (exact raw body,
integer timestamps, tolerance window,
hash_equals)
Products that adopt this package must still enforce per-endpoint concurrency
caps, timeouts, circuit-break / auto-disable after repeated failures, and
honour Retry-After / 410 / 429. The package documents that duty; it does not
ship auto-disable.
Requirements
- PHP ^8.3 with
ext-curlandext-intl - illuminate/contracts, illuminate/http, illuminate/support ^12 or ^13
- guzzlehttp/guzzle ^7.8 or ^8.0
Install (when released)
composer require qiick/laravel-outbound php artisan vendor:publish --tag=outbound-config
The service provider is auto-discovered.
Public API (so far)
SSRF
use Qiick\Outbound\Ssrf\RemoteUrlGuard; use Qiick\Outbound\Ssrf\UrlGuardOptions; use Qiick\Outbound\Testing\FakeHostResolver; $guard = new RemoteUrlGuard(new FakeHostResolver(['example.test' => ['93.184.216.34']])); $destination = $guard->authorize('https://example.test/hook'); // $destination->guzzleCurlOptions() → CURLOPT_CONNECT_TO pin only
assertBrowserUrlIsSafe() checks scheme and credentials for URLs the server
never connects to (browser redirects).
Pinned HTTP client
use Qiick\Outbound\Http\HttpRequestOptions; use Qiick\Outbound\Http\OutboundRequest; use Qiick\Outbound\Http\PinnedHttpClient; $client = app(PinnedHttpClient::class); $response = $client->send( 'POST', 'https://example.test/hook', function (OutboundRequest $request): void { $request->asJson(['event' => 'created'])->accept('application/json'); }, new HttpRequestOptions(followRedirects: true, maxRedirects: 3), );
The configure callable receives a package-owned {@see OutboundRequest} only
(headers, query on the authorised URL, raw/json/form/multipart body, Accept /
Content-Type). It never sees Laravel's PendingRequest, so it cannot change
the URI, timeouts, proxy, pin, redirects, verify, or stream. Transport settings
are re-applied by wrapping the curl handler.
Transport never auto-follows; when followRedirects is on, each Location is
resolved, SSRF-checked, and re-pinned. Cross-origin redirects are off by
default; when opted in, only 301/302/303 are allowed (body dropped) — cross-origin
307/308 are always refused, and only Accept / Accept-Language / User-Agent /
Content-Type (when a body is kept) are forwarded. Caller query values apply to
the first hop only. OutboundRequest refuses Host / X-Host / X-Original-Host and routing headers (X-Forwarded-*, Forwarded, X-Original-URL, X-Rewrite-URL). The
client uses a private HTTP factory so shared Http::globalOptions(['handler'])
cannot bypass the pin. Environment proxies are disabled so they cannot bypass
CONNECT_TO. Timeout caps and the total redirect deadline come from
outbound.http.* config and cannot be raised per call.
Testing PinnedHttpClient
Http::fake() and Http::globalOptions() on the shared facade factory do not
reach PinnedHttpClient when the service provider binds a private factory. Each
transfer also strips a request-level handler from factory global options so a
poisoned factory cannot bypass CONNECT_TO on Guzzle 7. In tests, inject a factory
from Qiick\Outbound\Testing\FakeOutboundHttpFactory::fake([...]) (or ::make()),
or use the transferHandler constructor seam for unit tests without a real client.
Retry schedule and delivery records
use Qiick\Outbound\Delivery\DeliveryAttempt; use Qiick\Outbound\Delivery\DeliveryStatus; use Qiick\Outbound\Retry\RetrySchedule; use Qiick\Outbound\Retry\SystemRandomizer; $delays = match (config('outbound.webhooks.retry_preset')) { 'short' => RetrySchedule::shortDelays(), default => RetrySchedule::standardDelays(), }; $wait = RetrySchedule::withJitter( $delays[0], (int) config('outbound.webhooks.retry_jitter_seconds'), new SystemRandomizer, ); $attempt = new DeliveryAttempt( eventId: $msgId, eventType: 'order.created', attempt: 1, status: DeliveryStatus::Failed, httpStatus: 503, errorMessage: 'upstream unavailable', at: new DateTimeImmutable, nextAttemptAt: new DateTimeImmutable('+'.$wait.' seconds'), );
Prefer standard delays (5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h — about
75.6 hours end-to-end); bound short ([10, 30, 60]) to a migration
window. Jitter is capped to ±floor(delay/2) so a positive delay is never
immediate. $errorMessage on DeliveryAttempt must be sanitised by the
caller (no URLs/tokens). Products still enforce per-endpoint concurrency,
timeouts, circuit-break / auto-disable, and honour Retry-After / 410 / 429 —
the package does not ship auto-disable.
Configuration
| Config key | Env | Default |
|---|---|---|
outbound.ssrf.allow_private_hosts |
OUTBOUND_ALLOW_PRIVATE_HOSTS |
false |
outbound.ssrf.https_only |
OUTBOUND_HTTPS_ONLY |
false |
outbound.http.timeout_seconds |
OUTBOUND_TIMEOUT_SECONDS |
5 |
outbound.http.connect_timeout_seconds |
OUTBOUND_CONNECT_TIMEOUT_SECONDS |
3 |
outbound.http.max_timeout_seconds |
OUTBOUND_MAX_TIMEOUT_SECONDS |
60 |
outbound.http.max_connect_timeout_seconds |
OUTBOUND_MAX_CONNECT_TIMEOUT_SECONDS |
30 |
outbound.http.total_deadline_seconds |
OUTBOUND_TOTAL_DEADLINE_SECONDS |
30 |
outbound.http.max_response_bytes |
OUTBOUND_MAX_RESPONSE_BYTES |
1048576 |
outbound.http.max_redirects |
OUTBOUND_MAX_REDIRECTS |
0 |
outbound.webhooks.replay_tolerance_seconds |
OUTBOUND_WEBHOOK_TOLERANCE_SECONDS |
300 |
outbound.webhooks.max_payload_bytes |
OUTBOUND_WEBHOOK_MAX_PAYLOAD_BYTES |
1048576 |
outbound.webhooks.max_signatures |
OUTBOUND_WEBHOOK_MAX_SIGNATURES |
8 |
outbound.webhooks.max_secrets |
OUTBOUND_WEBHOOK_MAX_SECRETS |
4 |
outbound.webhooks.retry_preset |
OUTBOUND_WEBHOOK_RETRY_PRESET |
standard |
outbound.webhooks.retry_jitter_seconds |
OUTBOUND_WEBHOOK_RETRY_JITTER |
30 |
outbound.webhooks.allow_raw_legacy_secret |
OUTBOUND_WEBHOOK_ALLOW_RAW_LEGACY_SECRET |
false |
Development
composer update composer test # Pest composer lint # Pint composer analyse # PHPStan level max
Mutation (CI): bash scripts/mutate-per-class.sh — each listed security class
must score ≥95% (RemoteUrlGuard, AuthorizedDestination, PinnedHttpClient,
RetrySchedule; more classes as they land). No method-level
@pest-mutate-ignore.
Tests are deterministic: no live network. DNS and HTTP use injectable fakes; clock and randomizer are fixed in tests.
Licence
MIT. See LICENSE.
Security
See SECURITY.md. Use GitHub private vulnerability reporting; do not open a public issue for security findings.