fix: allow Gotenberg to reach private/Docker-internal hosts (#691)

* fix: allow Gotenberg to reach private/Docker-internal hosts (Issue #688)

The SSRF guard introduced in #664/#671 correctly blocks arbitrary
private URLs, but also prevents legitimate use-cases where Gotenberg
runs alongside InvoiceShelf in a Docker Compose network (e.g. the
default http://pdf:3000 service name resolves to a private IP).

Add a `gotenberg_allow_private_host` setting (env:
GOTENBERG_ALLOW_PRIVATE_HOST, default false) that:
- skips PrivateNetworkGuard in GotenbergPdfDriver
- skips PublicHttpUrl validation in PDFConfigurationRequest
- exposes a clearly-warned toggle in the admin PDF settings UI
- is persisted to the settings table and loaded via AppConfigProvider

A disabled guard is safe for controlled private networks (Docker
Compose, LAN); it must never be enabled for untrusted hosts. The UI
surfaces a prominent warning to communicate this constraint.

Closes #688

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(gotenberg): scope the private-host exemption to a declared host

Reshapes the escape hatch from a boolean admin setting into an
environment-declared host allowlist.

The driver streams the upstream response body back as the PDF, so a
mis-set Gotenberg host is full-response SSRF — pointed at a link-local
metadata endpoint it returns cloud credentials. A blanket "allow
private" switch left that reachable: gotenberg_host stays editable from
the admin UI, so any install that enabled the switch to run a sidecar
could have the host repointed at an internal service. The population the
flag existed to serve was exactly the population it failed to protect.

GOTENBERG_ALLOWED_PRIVATE_HOST now names the single host that may skip
the guard. Only that exact value is exempt; every other private target
stays blocked. GotenbergHostPolicy owns the comparison so the save-time
rule and the runtime driver guard cannot drift, and normalises case,
trailing slash and surrounding whitespace on both sides.

Being env-only also drops the settings-table key, the AppConfigProvider
branch and the whole admin UI surface — the toggle there could not be
switched on in any case, since BaseSwitchSection has no slot and was
passed no v-model, so the child BaseSwitch was discarded and the value
never changed from false.

Restores the gotenberg_margins validation rule, which the previous
revision replaced rather than added alongside.

Tests cover both directions, including that declaring one private host
does not exempt another; sabotaging the policy to always exempt fails 16
of the 22.

Co-authored-by: csoscd <csoscd@users.noreply.github.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Darko Gjorgjijoski <dg@darkog.com>
Co-authored-by: csoscd <csoscd@users.noreply.github.com>

.env.example

@@ -22,6 +22,17 @@ TRUSTED_PROXIES="*"
 # Set true only if you fully trust all PDF HTML and need remote images/CSS.
 DOMPDF_ENABLE_REMOTE=false
 
+# Gotenberg (optional alternative PDF driver; the default is dompdf).
+# PDF_DRIVER=gotenberg
+# GOTENBERG_HOST=http://pdf:3000
+# GOTENBERG_PAPERSIZE="210mm 297mm"
+#
+# Gotenberg is normally a sidecar on a private network, which the SSRF guard
+# rejects. Name that one host to exempt it — and only it. Every other private
+# target stays blocked, so the host cannot later be repointed at an internal
+# service. Leave unset unless you actually run Gotenberg privately.
+# GOTENBERG_ALLOWED_PRIVATE_HOST=http://pdf:3000
+
 # InvoiceShelf marketplace and updater base URL.
 # Defaults to https://invoiceshelf.com. Override to point at a local website
 # checkout for development:

app/Http/Requests/PDFConfigurationRequest.php

@@ -3,7 +3,9 @@
 namespace App\Http\Requests;
 
 use App\Rules\PublicHttpUrl;
+use App\Support\Pdf\GotenbergHostPolicy;
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
 
 class PDFConfigurationRequest extends FormRequest
 {
@@ -30,6 +32,12 @@ class PDFConfigurationRequest extends FormRequest
                 ];
 
             case 'gotenberg':
+                // The operator-declared Gotenberg host skips the private-network
+                // check; anything else is still held to it. See GotenbergHostPolicy.
+                $isDeclaredHost = GotenbergHostPolicy::isExemptFromPrivateNetworkGuard(
+                    $this->input('gotenberg_host')
+                );
+
                 return [
                     'pdf_driver' => [
                         'required',
@@ -38,7 +46,7 @@ class PDFConfigurationRequest extends FormRequest
                     'gotenberg_host' => [
                         'required',
                         'url',
-                        new PublicHttpUrl,
+                        Rule::when(! $isDeclaredHost, [new PublicHttpUrl]),
                     ],
                     'gotenberg_papersize' => [
                         'required',

app/Support/Pdf/GotenbergHostPolicy.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace App\Support\Pdf;
+
+use App\Support\Net\PrivateNetworkGuard;
+
+/**
+ * Decides whether a Gotenberg host is exempt from {@see PrivateNetworkGuard}.
+ *
+ * Gotenberg is normally deployed as a sidecar on a private network — the shipped
+ * default host is `http://pdf:3000` — which the SSRF guard rejects. The exemption
+ * is declared in the environment and names the single host it trusts:
+ *
+ *     GOTENBERG_ALLOWED_PRIVATE_HOST=http://pdf:3000
+ *
+ * It is deliberately NOT a boolean and deliberately not settable from the admin UI.
+ * `gotenberg_host` itself stays editable by any super admin, and the driver returns
+ * the upstream response body verbatim as the PDF — so a blanket "allow private"
+ * switch would let that setting be repointed at a link-local metadata endpoint and
+ * read back the response. Matching one declared host keeps the sidecar working while
+ * every other private target stays blocked.
+ *
+ * Both the save-time validation rule and the runtime driver guard call this, so the
+ * two layers cannot drift apart.
+ */
+class GotenbergHostPolicy
+{
+    /**
+     * Whether the given host is the operator-declared Gotenberg host, and may
+     * therefore skip the private-network check.
+     */
+    public static function isExemptFromPrivateNetworkGuard(?string $host): bool
+    {
+        $allowed = config('pdf.connections.gotenberg.allowed_private_host');
+
+        if (! is_string($allowed) || ! is_string($host)) {
+            return false;
+        }
+
+        $allowed = self::normalize($allowed);
+        $host = self::normalize($host);
+
+        // An unset or unparseable allowlist never exempts anything.
+        return $allowed !== null && $allowed === $host;
+    }
+
+    /**
+     * Reduce a URL to scheme://host[:port][/path] with casing and any trailing
+     * slash removed, so `HTTP://PDF:3000/` and `http://pdf:3000` compare equal.
+     *
+     * Returns null when the value is empty or carries no scheme and host.
+     */
+    private static function normalize(string $url): ?string
+    {
+        $url = trim($url);
+
+        if ($url === '') {
+            return null;
+        }
+
+        $parts = parse_url($url);
+
+        if ($parts === false || ! isset($parts['scheme'], $parts['host'])) {
+            return null;
+        }
+
+        // parse_url keeps IPv6 literals bracketed; strip them on both sides so the
+        // comparison is consistent.
+        $host = strtolower(trim($parts['host'], '[]'));
+
+        if ($host === '') {
+            return null;
+        }
+
+        return sprintf(
+            '%s://%s%s%s',
+            strtolower($parts['scheme']),
+            $host,
+            isset($parts['port']) ? ':'.$parts['port'] : '',
+            rtrim($parts['path'] ?? '', '/'),
+        );
+    }
+}

app/Support/Pdf/GotenbergPdfDriver.php

@@ -19,12 +19,17 @@ class GotenbergPdfDriver
         $host = config('pdf.connections.gotenberg.host');
 
         // SSRF guard: gotenberg_host is an admin-supplied URL the server POSTs
-        // the rendered HTML to. Block private/reserved/link-local targets even
-        // if set via env/seed/stale config or reachable through DNS rebinding.
-        try {
-            PrivateNetworkGuard::assertAllowed((string) $host);
-        } catch (BlockedUrlException $e) {
-            throw new \InvalidArgumentException('Invalid Gotenberg host: '.$e->getMessage());
+        // the rendered HTML to, and whose response is streamed back as the PDF.
+        // Block private/reserved/link-local targets even if set via env/seed/stale
+        // config or reachable through DNS rebinding. The single exception is the
+        // host the operator declared in GOTENBERG_ALLOWED_PRIVATE_HOST, which is
+        // how a sidecar deployment is supported — see GotenbergHostPolicy.
+        if (! GotenbergHostPolicy::isExemptFromPrivateNetworkGuard((string) $host)) {
+            try {
+                PrivateNetworkGuard::assertAllowed((string) $host);
+            } catch (BlockedUrlException $e) {
+                throw new \InvalidArgumentException('Invalid Gotenberg host: '.$e->getMessage());
+            }
         }
 
         $request = Gotenberg::chromium($host)

config/pdf.php

@@ -30,6 +30,16 @@ return [
         'gotenberg' => [
             'host' => env('GOTENBERG_HOST', 'http://pdf:3000'),
             'papersize' => env('GOTENBERG_PAPERSIZE', '210mm 297mm'),
+
+            /*
+             * Gotenberg usually runs as a sidecar on a private network, which the
+             * SSRF guard rejects. Name that one host here to exempt it — e.g.
+             * GOTENBERG_ALLOWED_PRIVATE_HOST=http://pdf:3000. Only this exact value
+             * is exempt; the guard still blocks every other private target, so the
+             * host setting cannot be repointed at an internal service. No default:
+             * the `host` fallback above must never be trusted implicitly.
+             */
+            'allowed_private_host' => env('GOTENBERG_ALLOWED_PRIVATE_HOST'),
         ],
     ],
 

tests/Unit/GotenbergHostValidationTest.php

@@ -1,14 +1,26 @@
 <?php
 
 use App\Http\Requests\PDFConfigurationRequest;
+use App\Support\Pdf\GotenbergHostPolicy;
+use App\Support\Pdf\GotenbergPdfDriver;
 use Illuminate\Support\Facades\Validator;
 
+/**
+ * Build the gotenberg_host rules the way the form request would for a given
+ * submitted host, then validate that host against them.
+ */
+function validateGotenbergHost(string $url): Illuminate\Validation\Validator
+{
+    $rules = PDFConfigurationRequest::create('/', 'POST', [
+        'pdf_driver' => 'gotenberg',
+        'gotenberg_host' => $url,
+    ])->rules();
+
+    return Validator::make(['gotenberg_host' => $url], ['gotenberg_host' => $rules['gotenberg_host']]);
+}
+
 test('gotenberg host rejects private, loopback and link-local addresses', function (string $url) {
-    $rules = PDFConfigurationRequest::create('/', 'POST', ['pdf_driver' => 'gotenberg'])->rules();
-
-    $validator = Validator::make(['gotenberg_host' => $url], ['gotenberg_host' => $rules['gotenberg_host']]);
-
-    expect($validator->fails())->toBeTrue();
+    expect(validateGotenbergHost($url)->fails())->toBeTrue();
 })->with([
     'http://127.0.0.1',
     'http://169.254.169.254',
@@ -17,9 +29,75 @@ test('gotenberg host rejects private, loopback and link-local addresses', functi
 ]);
 
 test('gotenberg host allows a public address', function () {
-    $rules = PDFConfigurationRequest::create('/', 'POST', ['pdf_driver' => 'gotenberg'])->rules();
-
-    $validator = Validator::make(['gotenberg_host' => 'http://8.8.8.8'], ['gotenberg_host' => $rules['gotenberg_host']]);
-
-    expect($validator->errors()->has('gotenberg_host'))->toBeFalse();
+    expect(validateGotenbergHost('http://8.8.8.8')->errors()->has('gotenberg_host'))->toBeFalse();
+});
+
+test('gotenberg host accepts the private host declared in the environment', function () {
+    config(['pdf.connections.gotenberg.allowed_private_host' => 'http://10.0.0.5:3000']);
+
+    expect(validateGotenbergHost('http://10.0.0.5:3000')->errors()->has('gotenberg_host'))->toBeFalse();
+});
+
+/**
+ * The point of naming the host rather than flipping a boolean: declaring one
+ * private host must not open the guard for any other. Without this, an operator
+ * who enables the sidecar also hands a super admin the ability to repoint the
+ * setting at a cloud metadata endpoint and read the response back as a "PDF".
+ */
+test('declaring one private host does not exempt any other', function (string $url) {
+    config(['pdf.connections.gotenberg.allowed_private_host' => 'http://pdf:3000']);
+
+    expect(validateGotenbergHost($url)->fails())->toBeTrue();
+})->with([
+    'http://169.254.169.254',
+    'http://127.0.0.1:3000',
+    'http://10.0.0.5:3000',
+]);
+
+test('an unset allowlist exempts nothing', function () {
+    config(['pdf.connections.gotenberg.allowed_private_host' => null]);
+
+    expect(validateGotenbergHost('http://10.0.0.5:3000')->fails())->toBeTrue();
+});
+
+test('the declared host is matched ignoring case and trailing slash', function (string $configured, string $submitted) {
+    config(['pdf.connections.gotenberg.allowed_private_host' => $configured]);
+
+    expect(GotenbergHostPolicy::isExemptFromPrivateNetworkGuard($submitted))->toBeTrue();
+})->with([
+    ['http://pdf:3000', 'http://pdf:3000/'],
+    ['http://pdf:3000/', 'http://pdf:3000'],
+    ['HTTP://PDF:3000', 'http://pdf:3000'],
+    ['  http://pdf:3000  ', 'http://pdf:3000'],
+]);
+
+test('the policy rejects hosts that differ in any meaningful part', function (string $submitted) {
+    config(['pdf.connections.gotenberg.allowed_private_host' => 'http://pdf:3000']);
+
+    expect(GotenbergHostPolicy::isExemptFromPrivateNetworkGuard($submitted))->toBeFalse();
+})->with([
+    'http://pdf:3001',
+    'https://pdf:3000',
+    'http://pdf',
+    'http://other:3000',
+    'http://pdf:3000/render',
+    'not a url',
+    '',
+]);
+
+/**
+ * The driver guard is the authoritative layer — it re-checks at request time, so
+ * it has to agree with the validation rule. Asserted on the blocking path only:
+ * it throws before any HTTP call is attempted, so the test never touches the
+ * network.
+ */
+test('gotenberg driver still blocks a private host that was not declared', function () {
+    config([
+        'pdf.connections.gotenberg.host' => 'http://169.254.169.254',
+        'pdf.connections.gotenberg.papersize' => '210mm 297mm',
+        'pdf.connections.gotenberg.allowed_private_host' => 'http://pdf:3000',
+    ]);
+
+    expect(fn () => (new GotenbergPdfDriver)->loadView('app.pdf.invoice.invoice1'))
+        ->toThrow(InvalidArgumentException::class, 'Invalid Gotenberg host');
 });