Add an egress CIDR allowlist to the SSRF guard (closes #204)

The SSRF blocklist had no escape hatch, so the thing webhooker is
mostly for — taking a public webhook and forwarding it to something
on your own network — could not be configured at all. Every private
address, Docker sibling and loopback service was permanently
unreachable as a delivery destination.

ALLOWED_EGRESS_CIDRS (default empty) names blocks that delivery
targets may reach despite the default blocklist. It is an allowlist
and only ever adds destinations: there is no boolean, and no value
disables SSRF protection wholesale. Empty, it adds nothing and the
guard permits and refuses the same addresses it did before, save
the two spellings named below.

A small set of addresses is refused before the allowlist is
consulted, so no supplied CIDR opens one — not the exact address,
not a supernet, not 0.0.0.0/0 or ::/0. alwaysBlockedNetworks in
internal/delivery/ssrf.go is the authoritative list and states the
membership criterion in full; it is deliberately not copied here,
because a copy drifts out of date. In short: the provider fixes the
address, so a host route for it collides with nothing the operator
runs, and reaching it discloses credentials or user data. A
publicly routable address never qualifies however well it meets
both — nothing in this set can be reopened, so blocking one here
would leave the operator no escape hatch at all. Those belong in
blockedNetworks, which an allowlist can override.

Every entry is already inside the default blocklist, which is what
makes it unconditional rather than newly blocked, with two
exceptions that are the one behaviour change visible when the
allowlist is unset: ::a9fe:a9fe and 64:ff9b::a9fe:a9fe, the
IPv4-compatible and NAT64 spellings of 169.254.169.254, were
reachable before and are refused now. net.IPNet.Contains normalises
only the IPv4-mapped form via To4(), so 169.254.0.0/16 never
matched those two. The ten it does cover now report a metadata
error rather than the generic private-range one.

The policy now lives in one function, Guard.checkIP, which both
target-creation validation and the delivery dialer call. The two
paths previously decided separately, which is how they came to
disagree about a destination. The guard is built once from config
and injected via fx into both the handlers and the delivery engine,
so there is a single instance and a single answer.

A set-but-unparseable value aborts startup naming the variable,
reusing the existing envPrefixList parser. A non-empty list is
logged at startup with the blocks spelled out, not counted, so the
hole is visible in the log of any deployment that has one.

Tests: an allowlisted loopback CIDR both validates and delivers to a
live server (and the same URL still fails without the allowlist); a
private address outside the listed block stays refused on both
paths; every unconditionally blocked address stays refused on both
paths under an allowlist that covers it, and the set itself is
pinned entry by entry; public addresses are unaffected either way;
and config coverage for parsing, startup abort, and the warning's
contents.

internal/config/config_test.go

@@ -663,6 +663,187 @@ func testTrustedProxiesSuccess(
 	assert.Equal(t, expected, got)
 }
 
+// TestAllowedEgressCIDRs covers ALLOWED_EGRESS_CIDRS, the escape
+// hatch that lets a self-hosted deployment forward to its own
+// network. Unset it must stay empty, so the SSRF guard keeps
+// refusing every private/reserved range; a set-but-unparseable
+// value must abort startup naming the variable rather than
+// silently running with a list the operator did not write.
+func TestAllowedEgressCIDRs(t *testing.T) {
+	tests := []struct {
+		name        string
+		set         bool
+		value       string
+		expected    []string
+		expectError bool
+	}{
+		{
+			name:     caseUnsetUsesDefault,
+			set:      false,
+			expected: []string{},
+		},
+		{
+			name:     "empty value yields empty list",
+			set:      true,
+			value:    "",
+			expected: []string{},
+		},
+		{
+			name:     caseValidValueParsed,
+			set:      true,
+			value:    cidrPrivateV4,
+			expected: []string{cidrPrivateV4},
+		},
+		{
+			name:     "multiple blocks with whitespace",
+			set:      true,
+			value:    " 10.0.0.0/8 , 127.0.0.0/8 ",
+			expected: []string{cidrPrivateV4, "127.0.0.0/8"},
+		},
+		{
+			name:     "bare address becomes a single host",
+			set:      true,
+			value:    "172.17.0.5",
+			expected: []string{"172.17.0.5/32"},
+		},
+		{
+			name:        caseUnparseableFails,
+			set:         true,
+			value:       cidrPrivateV4 + ",not-an-address",
+			expectError: true,
+		},
+		{
+			name:        "out-of-range prefix length fails startup",
+			set:         true,
+			value:       "10.0.0.0/33",
+			expectError: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Cannot use t.Parallel() here because t.Setenv
+			// is incompatible with parallel subtests.
+			t.Setenv("WEBHOOKER_ENVIRONMENT", "dev")
+
+			if tt.set {
+				t.Setenv("ALLOWED_EGRESS_CIDRS", tt.value)
+			} else {
+				require.NoError(
+					t, os.Unsetenv("ALLOWED_EGRESS_CIDRS"),
+				)
+			}
+
+			if tt.expectError {
+				expectStartupErrorFor(
+					t, "ALLOWED_EGRESS_CIDRS", config.ErrInvalidCIDR,
+				)
+			} else {
+				testAllowedEgressCIDRsSuccess(t, tt.expected)
+			}
+		})
+	}
+}
+
+func testAllowedEgressCIDRsSuccess(
+	t *testing.T,
+	expected []string,
+) {
+	t.Helper()
+
+	var cfg *config.Config
+
+	app := fxtest.New(
+		t,
+		fx.Provide(
+			globals.New,
+			logger.New,
+			config.New,
+		),
+		fx.Populate(&cfg),
+	)
+	require.NoError(t, app.Err())
+
+	app.RequireStart()
+
+	defer app.RequireStop()
+
+	assert.Equal(
+		t, expected, config.PrefixStrings(cfg.AllowedEgressCIDRs),
+	)
+}
+
+// TestEgressAllowlistWarning covers the startup log that shows an
+// operator the hole ALLOWED_EGRESS_CIDRS opened. It must stay
+// silent on the default (empty) list and, when set, print the
+// blocks themselves rather than a count.
+func TestEgressAllowlistWarning(t *testing.T) {
+	tests := []struct {
+		name          string
+		allowed       string
+		expectWarning bool
+	}{
+		{
+			name:          "empty allowlist is quiet",
+			expectWarning: false,
+		},
+		{
+			name:          "non-empty allowlist warns",
+			allowed:       "10.0.0.0/8,127.0.0.0/8",
+			expectWarning: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Cannot use t.Parallel() here because t.Setenv
+			// is incompatible with parallel subtests.
+			t.Setenv("WEBHOOKER_ENVIRONMENT", config.EnvironmentDev)
+
+			if tt.allowed == "" {
+				require.NoError(
+					t, os.Unsetenv("ALLOWED_EGRESS_CIDRS"),
+				)
+			} else {
+				t.Setenv("ALLOWED_EGRESS_CIDRS", tt.allowed)
+			}
+
+			var buf bytes.Buffer
+
+			log := slog.New(slog.NewJSONHandler(
+				&buf, &slog.HandlerOptions{
+					Level: slog.LevelDebug,
+				},
+			))
+
+			require.NoError(
+				t, config.WarnEgressAllowlistForTest(log),
+			)
+
+			if !tt.expectWarning {
+				assert.Empty(t, buf.String())
+
+				return
+			}
+
+			logged := buf.String()
+
+			assert.Contains(t, logged, `"level":"WARN"`)
+			assert.Contains(t, logged, "ALLOWED_EGRESS_CIDRS")
+			// The blocks themselves, not a count: the operator has
+			// to be able to read back which networks are open.
+			assert.Contains(t, logged, "10.0.0.0/8")
+			assert.Contains(t, logged, "127.0.0.0/8")
+			// What stays shut. Asserted on the clause naming the
+			// wider set rather than on "Link-local" alone, so the
+			// string cannot narrow back to link-local only while
+			// the always-blocked set covers ULA, CGNAT and two
+			// public metadata addresses as well.
+			assert.Contains(t, logged, "metadata endpoints outside it")
+		})
+	}
+}
+
 // TestSharedRateLimitBucketWarning covers the startup warning that
 // tells an operator a deployment behind a reverse proxy shares one
 // rate-limit bucket between every client, which turns the receiver