Harden proxy auth handling and add bulk-request support

[sgiehl]

Summary

Hardens how the tracker-proxy handles authentication-controlled tracking parameters, and adds proper support for bulk tracking requests. The proxy no longer lets its privileged token_auth authorize parameters a client tried to set itself (IP / location / timestamp overrides), for both single and bulk requests, while still recording the correct visitor IP.

Background

The proxy forwards browser tracking requests to a hidden Matomo server and injects two things: the real visitor IP as cip, and a privileged token_auth (write/admin) needed to authorize that cip. The side effect is that the same token authorizes every auth-controlled parameter in the request. In Matomo, cip, country, region, city, lat, long, cdt and cdo are only honored for an authenticated request — otherwise the request is rejected (InvalidRequestParameterException → HTTP 400 for a single request; the offending entry is skipped for a bulk request). So a visitor who appended e.g. &country=ru&cdt=… would have those overrides authorized by the proxy's token and silently tracked.

A previous change (#103) addressed this for single requests by stripping the override params. That had two problems:

1. Bulk requests were not covered. Matomo's JS tracker batches multiple actions into a single {"requests":[…]} POST by default, and the overrides live inside the nested entries — which the strip logic never inspected. The proxy's token (reached via Matomo's auth fallback) then authorized them.
2. Type-juggling bypass. The "did the client send a token?" check used isset(), so token_auth= (empty) or token_auth[]=x (array) made the proxy skip stripping while Matomo treated the token as absent and fell back to the injected privileged token.

It also changed semantics in a questionable way: stripping turns a request Matomo would reject into one that tracks (minus the override).

What changed

Approach: withhold the token instead of stripping params. The proxy injects its token_auth only for requests/entries that did not try to override anything. Anything carrying its own auth-controlled param (or its own token_auth) gets no token from us, so Matomo applies its native rules — rejecting a single request, skipping an offending bulk entry — rather than us
laundering it.

• Bulk requests (proxy.php injectVisitIpIntoBulkRequest): the body is parsed exactly the way Matomo's BulkTracking plugin parses it (json_decode, parse_url+parse_str for string entries, arrays used directly, same "requests" detection, sanitizeLineBreaks). Each clean entry gets cip + token_auth injected; offending entries are left verbatim. A client-supplied top-level token_auth makes the whole body pass through untouched (the client's token governs).
• Two visitor-IP modes:
  • $http_ip_forward_header set → the proxy injects nothing; the visitor IP is sent in that header (now for GET as well as POST) and Matomo derives it from the connection. Cleanest, no token involved.
  • not set (default) → the IP is conveyed via cip, authorized by the token, only on clean requests/entries.
• Type-juggling safe: a client token_auth counts only when it's a non-empty string (matching how Matomo reads it); auth-controlled params are detected by key presence, so empty/array values can't slip past. Includes both cdt and cdo.
• Client cip is never overridden — if the client sent one, we don't add ours (an authorized client may set it; an unauthorized one is rejected).

Why this approach

We deliberately do not track a request Matomo would reject. If a client includes an auth-controlled override without valid auth, the proxy refuses to lend its token, so Matomo rejects/skips it — same outcome as sending it directly. Clean requests (the normal case) are unaffected and still get the correct visitor IP.

Verified against Matomo

• Bulk entries are built only from the JSON body, so a GET cip never reaches them — per-entry cip injection is genuinely required (core/Tracker/RequestSet.php, plugins/BulkTracking/Tracker/Requests.php).
• cdo alone backdates the visit (cdt = now - abs(cdo)) and requires auth if older than 24h (core/Tracker/Request.php::getCustomTimestamp).
• Token resolution / conflict validation (core/Request/AuthenticationToken.php) — the proxy never creates a conflicting second token source.
• The auth-gated parameter set matches Matomo's (RequestHandlerTrait::$fieldsThatRequireAuth + Request.php).

replaces #95

Checklist

• [✔/✖/NA] I have understood, reviewed, and tested all AI outputs before use
• [✔/✖/NA] All AI instructions respect security, IP, and privacy rules

Review

• Functional review done
• Potential edge cases thought about (behaviour of the code with strange input, with strange internal state or possible interactions with other Matomo subsystems)
• Usability review done (is anything maybe unclear or think about anything that would cause people to reach out to support)
• Security review done
• Wording review done
• Code review done
• Tests were added if useful/possible
• Reviewed for breaking changes
• Developer changelog updated if needed
• New documentation added or existing documentation updated