From 0997a9dc66d877fcac191cc84700d2f20660e106 Mon Sep 17 00:00:00 2001
From: Joost de Valk <joost@altha.nl>
Date: Tue, 15 Sep 2026 16:59:51 +0200
Subject: [PATCH] Use a shared validated client IP for exclusions and settings

---
 README.md                             |  8 +++++
 simple-analytics.php                  |  1 +
 src/Settings/Blocks/Fields/IpList.php |  5 ++-
 src/Support/IpAddress.php             | 22 +++++++++++++
 src/TrackingRules.php                 |  8 +++--
 tests/Browser/phpRegression.spec.ts   | 16 ++++++++++
 tests/Regression/client-ip.php        | 45 +++++++++++++++++++++++++++
 tests/Support/isolated-options.php    | 39 +++++++++++++++++++++++
 8 files changed, 140 insertions(+), 4 deletions(-)
 create mode 100644 src/Support/IpAddress.php
 create mode 100644 tests/Browser/phpRegression.spec.ts
 create mode 100644 tests/Regression/client-ip.php
 create mode 100644 tests/Support/isolated-options.php

diff --git a/README.md b/README.md
index e0b072d..f0c7930 100644
--- a/README.md
+++ b/README.md
@@ -10,5 +10,13 @@ You need a Simple Analytics account. Start with the [free plan](https://www.simp
 
 ## Resources
 
+### Client IP addresses behind a proxy
+
+IP exclusions and **Add Current IP** both use the validated `REMOTE_ADDR` supplied by your web server. Forwarded headers are no longer trusted automatically. Configure your server's trusted proxy handling to populate the visitor's address in `REMOTE_ADDR`.
+
+If your deployment needs a different resolver, the `simpleanalytics_client_ip` filter receives that address (or `null` when unavailable). Return one visitor IP only after validating the connecting proxy and its headers. The plugin validates and normalizes the returned IPv4 or IPv6 address and uses it consistently for tracking and the settings UI. Never pass an untrusted `X-Forwarded-For` header directly through this filter.
+
+### Links
+
 -   [WordPress plugin page](https://wordpress.org/plugins/simpleanalytics/)
 -   [Create a Simple Analytics account](https://www.simpleanalytics.com/signup)
diff --git a/simple-analytics.php b/simple-analytics.php
index 3c253cd..97813a0 100644
--- a/simple-analytics.php
+++ b/simple-analytics.php
@@ -29,6 +29,7 @@
  * @note Manual loading rather than Composer to avoid potential conflict with plugins/themes that ship older autoloader.
  */
 require __DIR__ . '/src/Support/SvgIcon.php';
+require __DIR__ . '/src/Support/IpAddress.php';
 require __DIR__ . '/helpers.php';
 require __DIR__ . '/src/Plugin.php';
 require __DIR__ . '/src/WordPressHooks.php';
diff --git a/src/Settings/Blocks/Fields/IpList.php b/src/Settings/Blocks/Fields/IpList.php
index cc671d8..fab461f 100644
--- a/src/Settings/Blocks/Fields/IpList.php
+++ b/src/Settings/Blocks/Fields/IpList.php
@@ -3,6 +3,7 @@
 namespace SimpleAnalytics\Settings\Blocks\Fields;
 
 use SimpleAnalytics\Setting;
+use SimpleAnalytics\Support\IpAddress;
 use SimpleAnalytics\Settings\Concerns\HasDocs;
 use SimpleAnalytics\Settings\Concerns\HasPlaceholder;
 use SimpleAnalytics\UI\LabelComponent;
@@ -38,7 +39,7 @@ public function getValueType(): string
     public function render(): void
     {
         $value = implode("\n", Setting::array($this->getKey()));
-        $currentIp = $_SERVER['REMOTE_ADDR'];
+        $currentIp = IpAddress::current();
         ?>
         <?php 
         (new LabelComponent(
@@ -66,6 +67,7 @@ class="block w-full rounded-md border-0 text-gray-900 shadow-sm ring-1 ring-inse
         echo esc_textarea($value);
         ?></textarea>
         </div>
+        <?php if ($currentIp !== null): ?>
         <div class="mt-2">
             <button
                 type="button"
@@ -81,6 +83,7 @@ class="rounded bg-white px-2 py-1 text-xs font-semibold text-gray-900 shadow-sm
         ?>)
             </button>
         </div>
+        <?php endif; ?>
         <p class="mt-2 text-sm text-gray-500">
             Enter IP addresses to exclude from tracking, one per line.
         </p>
diff --git a/src/Support/IpAddress.php b/src/Support/IpAddress.php
new file mode 100644
index 0000000..5165cdb
--- /dev/null
+++ b/src/Support/IpAddress.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace SimpleAnalytics\Support;
+
+class IpAddress
+{
+    public static function current(): ?string
+    {
+        // Forwarded headers are not trustworthy without a deployment-specific
+        // proxy policy. Let the web server normalize REMOTE_ADDR by default.
+        return self::normalize(apply_filters('simpleanalytics_client_ip', $_SERVER['REMOTE_ADDR'] ?? null));
+    }
+
+    public static function normalize($value): ?string
+    {
+        if (! is_string($value)) return null;
+        $value = trim($value);
+        if (filter_var($value, FILTER_VALIDATE_IP) === false) return null;
+
+        return inet_ntop(inet_pton($value));
+    }
+}
diff --git a/src/TrackingRules.php b/src/TrackingRules.php
index 9e09f84..696511b 100644
--- a/src/TrackingRules.php
+++ b/src/TrackingRules.php
@@ -2,6 +2,8 @@
 
 namespace SimpleAnalytics;
 
+use SimpleAnalytics\Support\IpAddress;
+
 class TrackingRules
 {
     protected $settings;
@@ -13,13 +15,13 @@ public function __construct(WordPressSettings $settings)
 
     public function hasExcludedIp(): bool
     {
-        $ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? ($_SERVER['REMOTE_ADDR'] ?? null);
+        $ip = IpAddress::current();
 
         if (empty($ip)) return false;
 
-        $list = $this->settings->array(SettingName::EXCLUDED_IP_ADDRESSES);
+        $list = array_map([IpAddress::class, 'normalize'], $this->settings->array(SettingName::EXCLUDED_IP_ADDRESSES));
 
-        return in_array($ip, $list);
+        return in_array($ip, $list, true);
     }
 
     public function hasExcludedUserRole(): bool
diff --git a/tests/Browser/phpRegression.spec.ts b/tests/Browser/phpRegression.spec.ts
new file mode 100644
index 0000000..4202937
--- /dev/null
+++ b/tests/Browser/phpRegression.spec.ts
@@ -0,0 +1,16 @@
+import { test, expect } from '@playwright/test';
+import { execFileSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+
+// Each script uses its own temporary options table, so these checks can run
+// alongside browser tests without changing their WordPress settings.
+for (const file of readdirSync(resolve('tests/Regression')).filter(name => name.endsWith('.php'))) {
+  test(`WordPress regression: ${file}`, () => {
+    const output = execFileSync(resolve('node_modules/.bin/wp-env'), [
+      'run', 'cli', 'wp', 'eval-file',
+      `wp-content/plugins/${basename(process.cwd())}/tests/Regression/${file}`,
+    ], { encoding: 'utf8', timeout: 45000 });
+    expect(output).toContain('Regression checks passed');
+  });
+}
diff --git a/tests/Regression/client-ip.php b/tests/Regression/client-ip.php
new file mode 100644
index 0000000..8ad59b7
--- /dev/null
+++ b/tests/Regression/client-ip.php
@@ -0,0 +1,45 @@
+<?php
+
+require __DIR__ . '/../Support/isolated-options.php';
+
+sa_with_isolated_options(static function () {
+    $key = SimpleAnalytics\SettingName::EXCLUDED_IP_ADDRESSES;
+    $rules = new SimpleAnalytics\TrackingRules(new SimpleAnalytics\WordPressSettings());
+    update_option($key, ['203.0.113.10', '2001:0DB8:0:0:0:0:0:1']);
+
+    $_SERVER['REMOTE_ADDR'] = '203.0.113.10';
+    $_SERVER['HTTP_X_FORWARDED_FOR'] = '203.0.113.200, 10.0.0.1';
+    sa_assert($rules->hasExcludedIp(), 'A forwarded chain must not override the address shown by Add Current IP.');
+    $_SERVER['REMOTE_ADDR'] = '203.0.113.20';
+    $_SERVER['HTTP_X_FORWARDED_FOR'] = '203.0.113.10';
+    sa_assert(! $rules->hasExcludedIp(), 'An untrusted header must not spoof an excluded visitor.');
+
+    $_SERVER['REMOTE_ADDR'] = '2001:db8::1';
+    sa_assert($rules->hasExcludedIp(), 'Equivalent IPv6 addresses must match.');
+    $field = new SimpleAnalytics\Settings\Blocks\Fields\IpList($key, 'IP addresses');
+    ob_start();
+    $field->render();
+    $html = ob_get_clean();
+    sa_assert(strpos($html, 'Add Current IP (2001:db8::1)') !== false, 'The UI must use the same normalized address.');
+
+    $override = static function ($ip) { return '203.0.113.10'; };
+    add_filter('simpleanalytics_client_ip', $override);
+    $_SERVER['REMOTE_ADDR'] = '10.0.0.1';
+    sa_assert($rules->hasExcludedIp(), 'A deployment-specific IP resolver must apply to tracking.');
+    ob_start();
+    $field->render();
+    $html = ob_get_clean();
+    sa_assert(strpos($html, 'Add Current IP (203.0.113.10)') !== false, 'The same filter must apply to the UI.');
+    remove_filter('simpleanalytics_client_ip', $override);
+
+    foreach (['invalid', '203.0.113.10, 10.0.0.1', '', null, []] as $invalid) {
+        $_SERVER['REMOTE_ADDR'] = $invalid;
+        sa_assert(! $rules->hasExcludedIp(), 'Invalid addresses must not match.');
+    }
+    unset($_SERVER['REMOTE_ADDR']);
+    sa_assert(! $rules->hasExcludedIp(), 'Missing addresses must not match.');
+    ob_start();
+    $field->render();
+    $html = ob_get_clean();
+    sa_assert(strpos($html, 'Add Current IP') === false, 'Hide the add button when the address is unavailable.');
+});
diff --git a/tests/Support/isolated-options.php b/tests/Support/isolated-options.php
new file mode 100644
index 0000000..f4f724e
--- /dev/null
+++ b/tests/Support/isolated-options.php
@@ -0,0 +1,39 @@
+<?php
+
+/** Run only through wp eval-file against the local wp-env installation. */
+function sa_assert($condition, string $message): void
+{
+    if (! $condition) throw new RuntimeException($message);
+}
+
+function sa_with_isolated_options(callable $test): void
+{
+    global $wpdb, $wp_object_cache;
+
+    sa_assert(! wp_using_ext_object_cache(), 'Regression tests require the default object cache.');
+    $originalTable = $wpdb->options;
+    $originalCache = $wp_object_cache;
+    $table = 'sa_regression_options';
+    $guard = static function ($sql) use ($table) {
+        if (! preg_match('/^\s*(SELECT|SHOW|DESCRIBE|EXPLAIN)\b/i', $sql) && strpos($sql, $table) === false) {
+            throw new RuntimeException('Refusing a write outside the temporary test table.');
+        }
+        return $sql;
+    };
+    add_filter('query', $guard, 9999);
+
+    try {
+        sa_assert($wpdb->query("CREATE TEMPORARY TABLE $table LIKE $originalTable") !== false, $wpdb->last_error);
+        sa_assert($wpdb->query("INSERT INTO $table SELECT * FROM $originalTable") !== false, $wpdb->last_error);
+        $wpdb->options = $table;
+        $wp_object_cache = new WP_Object_Cache();
+        wp_cache_switch_to_blog(get_current_blog_id());
+        $test();
+        echo "Regression checks passed\n";
+    } finally {
+        $wpdb->options = $originalTable;
+        $wp_object_cache = $originalCache;
+        remove_filter('query', $guard, 9999);
+    }
+    // The database connection automatically drops the temporary table on exit.
+}