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>

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');
 });