Server-validated X-Real-IP proxy handling, publicPort lifecycle fix, peer-statistic iam parameter, transfer-IP fallback, and matching tests/docs

9 files changed, 65 insertions, 8 deletions

diff --git a/help/AccessTracker_p.md b/help/AccessTracker_p.md
index 09684e4bc..63a56634b 100644
--- a/help/AccessTracker_p.md
+++ b/help/AccessTracker_p.md
@@ -63,12 +63,12 @@ GET or POST /AccessTracker_p.html?host=...&page=...
 Expect observations: counts, logs, queues, timing, network rows, thread states, or resource values. Monitoring does not fix the issue by itself; it points to the next page or setting to change.
 
 When YaCy is reached through a reverse proxy, Access Tracker uses `X-Real-IP`
-only when the proxy's direct socket IP matches one of the comma-separated regular
-expressions in `server.reverseProxy.trusted`. Loopback proxies are trusted by
-default. Authentication and access-control decisions continue to use the direct
-socket IP, not the forwarded address. The reverse proxy must overwrite
-`X-Real-IP` with the client address; it must not pass a client-supplied value
-unchanged.
+only when the proxy's direct socket IP matches one of the comma-separated
+regular expressions in `server.reverseProxy.trusted` and the header contains
+one valid IPv4 or IPv6 address. Loopback proxies are trusted by default.
+Authentication and access-control decisions continue to use the direct socket
+IP, not the forwarded address. The reverse proxy must overwrite `X-Real-IP`
+with the client address; it must not pass a client-supplied value unchanged.
 
 ## Related Pages
 
diff --git a/help/SettingsAck_p.md b/help/SettingsAck_p.md
index 20d9224fa..96844bfa9 100644
--- a/help/SettingsAck_p.md
+++ b/help/SettingsAck_p.md
@@ -58,11 +58,12 @@ The table explains values that an agent or script must set deliberately. Paramet
 | `fileHost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
 | `msgForwardingEnabled` | Enables the named feature. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. |
 | `port` | HTTP port where YaCy listens. Values below 1024 are ignored by this form; changing the port triggers reconnect/redirect behavior. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. |
+| `publicPort` | Optional public non-TLS HTTP port, from 1 through 65535, advertised in YaCy's seed/P2P metadata. It takes precedence over UPnP and the local listening port. An empty value disables the manual override. | Processed with the `serveraccount` settings action. Invalid, non-numeric, zero, or out-of-range values leave the previous setting unchanged. Set it when NAT or a reverse proxy exposes YaCy on a different external port. |
 | `proxyaccess` | Saves the proxy client IP-number filter. | Changes proxy access scope; verify the filter before submitting. |
 | `proxyfilter` | Filter expression. It decides which records are included, excluded, displayed, exported, or processed on this page. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
 | `remoteProxyHost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
 | `remoteProxyUser` | User or account value. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
-| `serveraccount` | User or account value. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `serveraccount` | Action marker whose presence applies the Server Access form, including `fileHost`, `staticIP`, `publicPort`, and `serverfilter`. Its submitted value is not interpreted. | Requires administrator access and a valid transaction token. Include the complete Server Access form state because the action processes its related fields together. |
 | `serverfilter` | Filter expression. It decides which records are included, excluded, displayed, exported, or processed on this page. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
 | `serveruser` | User or account value. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
 | `urlproxydomains` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
@@ -75,6 +76,12 @@ Example request shape:
 GET or POST /SettingsAck_p.html?port=...&adminaccount=...&adminpw1=...&adminpw2=...&adminuser=...
 ```
 
+For a server-access form submission, `serveraccount` selects the action and
+`publicPort` carries the optional override. A valid value is stored and applied
+to the current peer seed. Clearing the value removes the override; subsequent
+seed refreshes then use the UPnP mapping when available, otherwise the local
+HTTP listening port. The setting does not override the public TLS port.
+
 ## What To Expect
 
 A successful change is visible as a saved value, a confirmation, or changed behavior on a related page. Some settings take effect immediately; others require reconnecting, reloading translations, restarting services, or watching the status page.
diff --git a/help/yacy/hello.md b/help/yacy/hello.md
index f73593ce5..bda5bad2c 100644
--- a/help/yacy/hello.md
+++ b/help/yacy/hello.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/hello.java`.
diff --git a/help/yacy/list.md b/help/yacy/list.md
index 546f4aa24..cc6f59848 100644
--- a/help/yacy/list.md
+++ b/help/yacy/list.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/list.java`.
diff --git a/help/yacy/message.md b/help/yacy/message.md
index aeeab8bf7..d8a4fec12 100644
--- a/help/yacy/message.md
+++ b/help/yacy/message.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/message.java`.
diff --git a/help/yacy/profile.md b/help/yacy/profile.md
index 53d642f76..303829a6f 100644
--- a/help/yacy/profile.md
+++ b/help/yacy/profile.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/profile.java`.
diff --git a/help/yacy/query.md b/help/yacy/query.md
index aa785593b..c385ae264 100644
--- a/help/yacy/query.md
+++ b/help/yacy/query.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/query.java`.
diff --git a/help/yacy/search.md b/help/yacy/search.md
index e8cba7e54..c7b3387e8 100644
--- a/help/yacy/search.md
+++ b/help/yacy/search.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/search.java`.
@@ -53,6 +60,7 @@ The table explains values that an agent or script must set deliberately. Paramet
 | `contentdom` | Content domain filter. Common values are `all`, `text`, `image`, `audio`, `video`, and `app`; use it to ask for web pages, media, or application documents deliberately. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
 | `count` | SRU-style result count. It is an alternative to `maximumRecords` on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
 | `filter` | Filter text or expression used to narrow the displayed records. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
+| `iam` | Twelve-character enhanced-Base64 seed hash of the requesting YaCy peer. When it identifies a known peer, YaCy uses it for search-statistics attribution so peers sharing an address behind NAT remain distinguishable. | This is attribution metadata, not an independent authentication credential. Missing, malformed, or unknown hashes fall back to the effective request client IP. |
 | `language` | Interface language. Values are `browser` for the browser-preferred language, `default` for English, or a language code such as `de`, `fr`, `es`, `zh`, `ja`, or `ko`. | Changes stored data, configuration, or a running job. Use the authenticated action flow where required and verify the result. |
 | `query` | Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
 | `sitehost` | Host or domain scope. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
@@ -63,7 +71,7 @@ The table explains values that an agent or script must set deliberately. Paramet
 Example request shape:
 
 ```http
-GET or POST /yacy/search.html?language=...&query=...&contentdom=...&abstracts=...&author=...
+GET or POST /yacy/search.html?iam=...&language=...&query=...&contentdom=...&abstracts=...&author=...
 ```
 
 ## What To Expect
diff --git a/help/yacy/transferRWI.md b/help/yacy/transferRWI.md
index 3f7fe06cf..5cea79956 100644
--- a/help/yacy/transferRWI.md
+++ b/help/yacy/transferRWI.md
@@ -34,6 +34,13 @@ Call the endpoint as a protocol surface. Use exact parameter names and encoded v
 
 This is a peer-service endpoint for YaCy peer communication, not a normal editing page.
 
+Behind a reverse proxy, YaCy accepts `X-Real-IP` as the effective client and
+routing address only when the proxy socket IP matches
+`server.reverseProxy.trusted` and the header contains one valid IPv4 or IPv6
+address. Otherwise YaCy uses the socket IP. Authentication and access control
+always use the socket IP. The proxy must overwrite, not pass through, any
+client-supplied `X-Real-IP` value.
+
 ## Automation And API
 
 Page backend: `source/net/yacy/htroot/yacy/transferRWI.java`.