Update start.sh

start.sh

@@ -238,10 +238,47 @@ PRIVATE_IP_LOG=true
 #   FORWARD_IP=X-Real-IP   any other value = trust that header, no probing
 FORWARD_IP="${FORWARD_IP:-auto}"
 FORWARD_IP_HEADER="${FORWARD_IP_HEADER:-}"
-FORWARD_IP_CANDIDATES="${FORWARD_IP_CANDIDATES:-X-Real-IP X-Forwarded-For CF-Connecting-IP True-Client-IP}"
+FORWARD_IP_CANDIDATES="${FORWARD_IP_CANDIDATES:-X-Real-IP X-Forwarded-For CF-Connecting-IP True-Client-IP X-Envoy-External-Address X-Client-IP}"
 PUBLIC_URL="${PUBLIC_URL:-https://smodusermc-12.hf.space/}"
-FORWARD_IP_STATE="$PRIVATE_DIR/forward-ip.state"
+FORWARD_IP_STATE="$PRIV_DIR/forward-ip.state"
 FORWARD_IP_PROBE_PY="${FORWARD_IP_PROBE_PY:-/tmp/forward_ip_probe.py}"
+#   The boot probe can only succeed once the Space really answers on its public
+#   URL, which is usually not the case while it is still starting up - and a
+#   failed probe used to be final until the next restart. It is therefore
+#   retried in the background until a header works; a retry restarts the proxy,
+#   so it only ever happens while nobody is online. 0 disables the retries.
+FORWARD_IP_RETRY_INTERVAL="${FORWARD_IP_RETRY_INTERVAL:-600}"
+#   Which of the two it is - the player's address or the proxy's - is not a
+#   matter of opinion: everything from outside reaches the game port through the
+#   ingress, so the PEERS of that port are the proxy's own addresses. Comparing
+#   a logged address against them is what makes "the IPs are wrong" answerable:
+#   a logged address that equals a peer is the proxy's, never a player's.
+PROXY_PEERS_PY="${PROXY_PEERS_PY:-/tmp/proxy_peers.py}"
+PROXY_PEERS_STATE="$PRIV_DIR/proxy-peers.log"
+PROXY_PEERS_VIEW="$SEC_DIR/proxy-peers.txt"
+GAME_PORT="${GAME_PORT:-7860}"
+
+# =============================================
+# AUTH LOG CAPTURE  (why /login needs a patch)
+# =============================================
+# Paper prints "Steve issued server command: /login hunter2" for every command
+# a player types, and that line is the only place the security logger can read
+# /login, /register and /changepassword from.  LoginSecurity 3.3.1 (and AuthMe)
+# install a log filter that makes the logging framework DROP every line like
+# that before the console, the log file or the parser ever see it - which is
+# why no login was picked up at all.  tools/patch_auth_filter.py rewrites the
+# string constants of that filter inside the plugin jar, so the filter cannot
+# match any more; the plugin itself keeps working unchanged.  apply_auth_filter_patch
+# does that before Paper starts, checks the patched class with the JVM's own
+# parser (javap) and rolls back if anything looks wrong.
+AUTH_FILTER_PATCH="${AUTH_FILTER_PATCH:-true}"   # false = leave the plugin jars alone
+AUTH_FILTER_PATCH_PY="${AUTH_FILTER_PATCH_PY:-/tmp/patch_auth_filter.py}"
+AUTH_PATCH_BACKUP_DIR="${AUTH_PATCH_BACKUP_DIR:-/tmp/authlog-jar-backups}"
+AUTH_PATCH_JAR_GLOB="${AUTH_PATCH_JAR_GLOB:-*LoginSecurity*.jar *AuthMe*.jar *loginsecurity*.jar *authme*.jar}"
+AUTH_PATCH_STATUS="not run"
+AUTH_PATCHED_CLASSES=""      # "<jar>|<class>|<backup>" per patched filter class
+AUTH_PATCH_EXPECT=""         # plugin names that must appear in "Enabling ..." lines
+AUTH_PATCH_RESTART_DONE=false
 
 # >>> embedded forward_ip_probe.py (generated from tools/forward_ip_probe.py) >>>
 write_forward_ip_probe_py() {
@@ -348,6 +385,865 @@ ensure_forward_ip_probe_py() {
 }
 # <<< embedded forward_ip_probe.py <<<
 
+# >>> embedded proxy_peers.py (generated from tools/proxy_peers.py) >>>
+write_proxy_peers_py() {
+    mkdir -p "$(dirname "$PROXY_PEERS_PY")" 2>/dev/null
+    cat > "$PROXY_PEERS_PY" <<'PROXY_PEERS_EOF'
+#!/usr/bin/env python3
+"""proxy_peers.py - the addresses of the proxy that sits in front of the game port.
+
+Everything that reaches the game port (7860) from outside goes through the
+Hugging Face ingress, so the *peers* of the listening socket are the ingress's
+own addresses - never a player's.  Comparing a logged player address with them
+is what answers the question the logs alone cannot:
+
+  * the address equals a proxy peer -> the log holds the PROXY's address, not
+    the player's (no forwarded header is in use, so two logins can legitimately
+    show two different addresses for one player: the ingress has several nodes)
+  * it does not                     -> the log holds the player's own address
+
+No `ss`/`iproute2` needed: the kernel's own tables are read (/proc/net/tcp and
+/proc/net/tcp6, where they exist).
+
+usage:
+  proxy_peers.py                       # peers of port 7860
+  proxy_peers.py --port 25565 --json
+  proxy_peers.py --proc-dir ./fixture  # for the tests
+
+Exit code is 0 even when nothing can be read - "no peers" is a valid answer.
+"""
+
+import argparse
+import ipaddress
+import json
+import os
+import sys
+
+
+def decode_v4(hex_addr: str):
+    raw = bytes.fromhex(hex_addr)
+    if len(raw) != 4:
+        return None
+    return str(ipaddress.IPv4Address(raw[::-1]))
+
+
+def decode_v6(hex_addr: str):
+    raw = bytes.fromhex(hex_addr)
+    if len(raw) != 16:
+        return None
+    # /proc/net/tcp6 stores the address as four 32-bit words, each in host
+    # (little endian) byte order
+    out = b""
+    for i in range(4):
+        out += raw[i * 4:(i + 1) * 4][::-1]
+    return str(ipaddress.IPv6Address(out))
+
+
+def split_addr(field: str):
+    if ":" not in field:
+        return None, None
+    hex_addr, _, hex_port = field.rpartition(":")
+    try:
+        port = int(hex_port, 16)
+    except ValueError:
+        return None, None
+    return hex_addr, port
+
+
+def peers(port: int, proc_dir: str = "/proc"):
+    found = []
+    for name, decode in (("tcp", decode_v4), ("tcp6", decode_v6)):
+        path = os.path.join(proc_dir, "net", name)
+        try:
+            with open(path, "r") as fh:
+                lines = fh.read().splitlines()[1:]
+        except OSError:
+            continue
+        for line in lines:
+            parts = line.split()
+            if len(parts) < 4:
+                continue
+            local_addr, local_port = split_addr(parts[1])
+            rem_addr, rem_port = split_addr(parts[2])
+            if local_port != port or not rem_port:
+                continue
+            if set(rem_addr) == {"0"}:          # the listening socket itself
+                continue
+            addr = decode(rem_addr)
+            if addr and addr not in found:
+                found.append(addr)
+    return sorted(found, key=lambda a: (0 if "." in a else 1, ipaddress.ip_address(a).packed))
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="addresses of the proxy in front of the game port")
+    ap.add_argument("--port", type=int, default=7860)
+    ap.add_argument("--proc-dir", default="/proc")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    found = peers(args.port, args.proc_dir)
+    if args.json:
+        print(json.dumps({
+            "port": args.port,
+            "peers": found,
+            "ipv4": len([a for a in found if ":" not in a]),
+            "ipv6": len([a for a in found if ":" in a]),
+        }))
+    else:
+        for addr in found:
+            print(addr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+PROXY_PEERS_EOF
+}
+ensure_proxy_peers_py() {
+    [ -s "$PROXY_PEERS_PY" ] || write_proxy_peers_py
+}
+# <<< embedded proxy_peers.py <<<
+
+
+# >>> embedded patch_auth_filter.py (generated from tools/patch_auth_filter.py) >>>
+write_auth_filter_patch_py() {
+    mkdir -p "$(dirname "$AUTH_FILTER_PATCH_PY")" 2>/dev/null
+    cat > "$AUTH_FILTER_PATCH_PY" <<'AUTH_FILTER_PATCH_PY_EOF'
+#!/usr/bin/env python3
+"""Stop the auth plugins' log filters from hiding /login from the console.
+
+Why this exists
+---------------
+The security logger in start.sh reads /login, /register and /changepassword
+out of the *console log* (Paper prints "Steve issued server command: /login
+hunter2" for every command a player types).  LoginSecurity 3.3.1 does not let
+that line reach the console: its `LoggingFilter` is added to the log4j root
+logger in `LoginSecurity.enable()` and returns DENY for every message that
+looks like an auth command, so the line is dropped before Paper, the file log
+and our parser ever see it.  AuthMe does the same thing through
+`LogFilterHelper` (used by its ConsoleFilter and Log4JFilter).  That is why
+"logins are not picked up" - no amount of pattern matching can find a line
+that the logging framework never writes.
+
+What this does
+--------------
+It rewrites *only the string constants* of those filter classes inside the
+plugin jar, so the deny check can never match a real console line again:
+
+    "/login"                   -> "[authlog-patched] /login"
+    "issued server command: "  -> "[authlog-patched] issued server command: "
+
+Nothing else changes: the class file keeps its bytecode, its structure and its
+constant indices (only the bytes of those UTF-8 constants and their lengths are
+rewritten), which `javap -c` on the original and the patched class proves line
+by line.  The plugin keeps working exactly as before - it just cannot hide the
+auth lines any more, which is what the server owner wants, because those lines
+are the only place the passwords can be read from (private-logs/auth.log).
+
+The password itself is still never written down for the verified client (see
+the masking in start.sh), and the copies of the raw console logs that are
+synced to the bucket have the passwords masked as well.
+
+Usage
+-----
+    python3 tools/patch_auth_filter.py --check   <jar> [<jar> ...]
+    python3 tools/patch_auth_filter.py --apply   <jar> [<jar> ...]
+    python3 tools/patch_auth_filter.py --restore <jar> [<jar> ...]
+    python3 tools/patch_auth_filter.py --selftest [--dir DIR]
+
+    --apply keeps a copy of the untouched jar (--backup-dir, default: next to
+    the jar as <jar>.authlog-orig) so --restore can put it back.
+    --json prints one machine readable object per jar for start.sh.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import struct
+import sys
+import zipfile
+from pathlib import Path
+
+# The marker that is put in front of every deny string.  It makes the string
+# impossible to match ("issued server command: [authlog-patched] /login" never
+# appears in a log) and it is what --check and the tests grep for.
+PATCH_PREFIX = "[authlog-patched] "
+
+BACKUP_SUFFIX = ".authlog-orig"
+
+# One entry per plugin we know.  `class` is the class inside the jar that does
+# the hiding, `markers` are the exact string constants that make the filter
+# match.  A jar is only touched when the class file really contains one of
+# them, and every marker that is found must be patchable.
+RULES = [
+    {
+        "plugin": "LoginSecurity",
+        "class": "com/lenis0012/bukkit/loginsecurity/util/LoggingFilter.class",
+        "markers": [
+            "/login",
+            "/register",
+            "/changepassword",
+            "/changepass",
+            "issued server command: ",
+        ],
+        "why": (
+            "LoginSecurity 3.3.x adds this filter to the log4j root logger and "
+            "denies every console line that contains 'issued server command: ' "
+            "followed by one of the auth commands"
+        ),
+    },
+    {
+        "plugin": "AuthMe",
+        "class": "fr/xephi/authme/output/LogFilterHelper.class",
+        "markers": ["issued server command:"],
+        "why": (
+            "AuthMe 5.x uses this helper from ConsoleFilter and Log4JFilter to "
+            "hide every auth command from the console"
+        ),
+    },
+]
+
+# Used by --selftest: a tiny, valid class file that prints the given strings.
+# It exists so the patch can be proven on a class the JVM really loads and runs
+# (tests/test_verified_client.sh does exactly that), also on machines that have
+# no auth plugin jar at hand.
+FIXTURE_CLASS = "com/lenis0012/bukkit/loginsecurity/util/LoggingFilter"
+
+
+# --------------------------------------------------------------------------- #
+# class file handling
+# --------------------------------------------------------------------------- #
+class ClassFile:
+    """Just enough of the class file format to rewrite UTF-8 constants."""
+
+    MAGIC = 0xCAFEBABE
+
+    def __init__(self, data: bytes):
+        self.data = data
+        if len(data) < 10 or struct.unpack_from(">I", data, 0)[0] != self.MAGIC:
+            raise ValueError("not a class file")
+        self.major, self.minor = struct.unpack_from(">HH", data, 6)
+        self.count = struct.unpack_from(">H", data, 8)[0]
+        self.utf8 = []  # (index, value, length_offset, bytes_offset)
+        self._walk()
+
+    def _walk(self) -> None:
+        pos = 10
+        i = 1
+        while i < self.count:
+            tag = self.data[pos]
+            pos += 1
+            if tag == 1:  # CONSTANT_Utf8
+                (length,) = struct.unpack_from(">H", self.data, pos)
+                start = pos + 2
+                value = self.data[start:start + length]
+                self.utf8.append((i, value, pos, start))
+                pos = start + length
+            elif tag in (7, 8, 16, 19, 20):  # Class, String, MethodType, Module, Package
+                pos += 2
+            elif tag in (15,):  # MethodHandle
+                pos += 3
+            elif tag in (3, 4, 9, 10, 11, 12, 17, 18):  # int, float, refs, NameAndType, dynamic
+                pos += 4
+            elif tag in (5, 6):  # long, double take two slots
+                pos += 8
+                i += 1
+            else:
+                raise ValueError(f"unknown constant pool tag {tag} at {pos - 1}")
+            i += 1
+        if pos > len(self.data):
+            raise ValueError("class file constant pool runs past the end of the file")
+
+    def strings(self) -> list[str]:
+        return [value.decode("utf-8", "replace") for _, value, _, _ in self.utf8]
+
+    @staticmethod
+    def dangerous(strings: list[str]) -> list[str]:
+        """Strings that could still make a password-hiding filter deny a line.
+
+        A class *name* may contain "/login" by accident, so only exact matches
+        of an auth command and strings containing the console prefix count.
+        """
+        words = {
+            "/login", "/l", "/log", "/register", "/reg", "/unregister", "/unreg",
+            "/changepassword", "/changepass", "/cp", "/authme",
+        }
+        return [s for s in strings
+                if not s.startswith(PATCH_PREFIX)
+                and ("issued server command" in s or s in words)]
+
+    def patch(self, markers: list[str]) -> tuple[bytes, list[str], list[str]]:
+        """Prefix every marker constant, keep everything else byte identical."""
+        want = {m.encode(): PATCH_PREFIX.encode() + m.encode() for m in markers}
+        done: list[str] = []
+        out = bytearray()
+        cursor = 0
+        for _, value, length_offset, bytes_offset in self.utf8:
+            new = want.get(value)
+            if new is None or value.startswith(PATCH_PREFIX.encode()):
+                continue
+            # keep the bytes before this constant, then write the longer one
+            out += self.data[cursor:length_offset]
+            out += struct.pack(">H", len(new))
+            out += new
+            cursor = bytes_offset + len(value)
+            done.append(value.decode("utf-8", "replace"))
+        if not done:
+            return self.data, [], []
+        out += self.data[cursor:]
+        patched = ClassFile(bytes(out))  # re-parse, so a broken rewrite fails here
+        return bytes(out), done, self.dangerous(patched.strings())
+
+
+# --------------------------------------------------------------------------- #
+# jar handling
+# --------------------------------------------------------------------------- #
+def read_text_file(path: Path) -> dict:
+    """Read a whole jar into memory (plugin jars are a few MB)."""
+    with zipfile.ZipFile(path) as zf:
+        return {
+            "comment": zf.comment,
+            "entries": [(info, zf.read(info.filename)) for info in zf.infolist()],
+        }
+
+
+def write_jar(path: Path, entries: list, comment: bytes) -> None:
+    tmp = path.with_name(path.name + ".tmp")
+    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zf:
+        if comment:
+            zf.comment = comment
+        for info, data in entries:
+            zf.writestr(info, data)
+    os.replace(tmp, path)
+
+
+def patch_jar(path: Path, apply: bool, backup_dir: Path | None) -> dict:
+    report = {
+        "jar": str(path),
+        "exists": path.is_file(),
+        "plugin": None,
+        "class": None,
+        "status": "no-rule-class",
+        "markers_found": [],
+        "markers_patched": [],
+        "residual": [],
+        "backup": None,
+        "error": None,
+    }
+    if not path.is_file():
+        report["status"] = "missing"
+        return report
+
+    try:
+        content = read_text_file(path)
+        by_name = {info.filename: (info, data) for info, data in content["entries"]}
+
+        changed_any = False
+        errors = []
+        for rule in RULES:
+            entry = by_name.get(rule["class"])
+            if entry is None:
+                continue
+            info, data = entry
+            report["plugin"] = rule["plugin"]
+            report["class"] = rule["class"]
+            try:
+                patched_bytes, done, residual = ClassFile(data).patch(rule["markers"])
+            except ValueError as exc:
+                report["status"] = "error"
+                report["error"] = str(exc)
+                return report
+
+            strings = ClassFile(data).strings()
+            found = done or [m for m in rule["markers"] if m in strings]
+            report["markers_found"] = found
+            if residual:
+                # a deny string we cannot neutralise: refuse to touch the jar
+                report["status"] = "unpatchable"
+                report["residual"] = residual
+                return report
+            if not done:
+                # nothing left to patch: either already patched or the strings
+                # are not constants in this build of the plugin
+                already = [s for s in strings
+                           if s.startswith(PATCH_PREFIX)
+                           and s[len(PATCH_PREFIX):] in rule["markers"]]
+                report["status"] = "already-patched" if already else "markers-missing"
+                report["markers_patched"] = already and rule["markers"] or []
+                return report
+
+            report["markers_patched"] = done
+            if not apply:
+                report["status"] = "would-patch"
+                return report
+
+            # write it back, keeping a copy of the original first
+            backup = None
+            if backup_dir is not None:
+                backup_dir.mkdir(parents=True, exist_ok=True)
+                backup = backup_dir / (path.name + BACKUP_SUFFIX)
+                if not backup.is_file():
+                    shutil.copy2(path, backup)
+            elif not (path.with_name(path.name + BACKUP_SUFFIX)).is_file():
+                backup = path.with_name(path.name + BACKUP_SUFFIX)
+                shutil.copy2(path, backup)
+            if backup is not None:
+                report["backup"] = str(backup)
+
+            entries = [(i, patched_bytes if i.filename == rule["class"] else d)
+                       for i, d in content["entries"]]
+            write_jar(path, entries, content["comment"])
+            # read it back and prove the whole jar is intact and patched
+            check = read_text_file(path)
+            check_by_name = {info.filename: data for info, data in check["entries"]}
+            if check_by_name.get(rule["class"]) != patched_bytes:
+                errors.append(f"{rule['class']} did not survive the rewrite")
+            for i, d in content["entries"]:
+                if i.filename != rule["class"] and check_by_name.get(i.filename) != d:
+                    errors.append(f"unrelated entry {i.filename} changed")
+            report["status"] = "patched" if not errors else "error"
+            report["error"] = "; ".join(errors) or None
+            changed_any = True
+            return report
+
+        if report["status"] == "no-rule-class":
+            report["status"] = "not-applicable"
+        return report
+    except (zipfile.BadZipFile, OSError) as exc:
+        report["status"] = "error"
+        report["error"] = f"{type(exc).__name__}: {exc}"
+        return report
+
+
+def restore_jar(path: Path, backup_dir: Path | None) -> dict:
+    candidates = []
+    if backup_dir is not None:
+        candidates.append(backup_dir / (path.name + BACKUP_SUFFIX))
+    candidates.append(path.with_name(path.name + BACKUP_SUFFIX))
+    for backup in candidates:
+        if backup.is_file():
+            shutil.copy2(backup, path)
+            return {"jar": str(path), "status": "restored", "backup": str(backup)}
+    return {"jar": str(path), "status": "no-backup", "backup": None}
+
+
+# --------------------------------------------------------------------------- #
+# self test: build a class the JVM can load and run, then patch it
+# --------------------------------------------------------------------------- #
+class _Pool:
+    """A tiny constant pool builder (dedupes entries by their key)."""
+
+    def __init__(self):
+        self.entries: list[tuple] = []
+        self.index: dict = {}
+
+    def _add(self, key, payload, slots=1):
+        if key in self.index:
+            return self.index[key]
+        idx = len(self.entries) + 1
+        self.entries.append((key, payload, slots))
+        self.index[key] = idx
+        if slots == 2:
+            self.entries.append((None, b"", 0))
+        return idx
+
+    def utf8(self, s: str) -> int:
+        b = s.encode("utf-8")
+        return self._add(("utf8", s), struct.pack(">BH", 1, len(b)) + b)
+
+    def string(self, s: str) -> int:
+        # ldc needs a CONSTANT_String entry; pointing it at the Utf8 would be
+        # "Illegal type at constant pool entry"
+        return self._add(("string", s), struct.pack(">BH", 8, self.utf8(s)))
+
+    def cls(self, name: str) -> int:
+        return self._add(("class", name), struct.pack(">BH", 7, self.utf8(name)))
+
+    def nat(self, name: str, desc: str) -> int:
+        return self._add(("nat", name, desc),
+                         struct.pack(">BHH", 12, self.utf8(name), self.utf8(desc)))
+
+    def fieldref(self, cls: str, name: str, desc: str) -> int:
+        return self._add(("field", cls, name, desc),
+                         struct.pack(">BHH", 9, self.cls(cls), self.nat(name, desc)))
+
+    def methodref(self, cls: str, name: str, desc: str) -> int:
+        return self._add(("method", cls, name, desc),
+                         struct.pack(">BHH", 10, self.cls(cls), self.nat(name, desc)))
+
+    def dump(self) -> bytes:
+        out = struct.pack(">H", len(self.entries) + 1)
+        for _, payload, _slots in self.entries:
+            out += payload
+        return out
+
+
+def build_fixture_class(name: str, strings: list[str]) -> bytes:
+    """A valid Java 8 class whose main() prints `strings`, one per line.
+
+    Straight line code only, so an empty StackMapTable is enough - the same
+    shape javac emits for a method without branches.
+    """
+    pool = _Pool()
+    # constant pool class entries use the internal form, "com/foo/Bar"
+    this_cls = pool.cls(name.replace(".", "/"))
+    super_cls = pool.cls("java/lang/Object")
+    ptr = "Ljava/io/PrintStream;"
+    sb = "java/lang/StringBuilder"
+    main = pool.utf8("main")
+    main_desc = pool.utf8("([Ljava/lang/String;)V")
+    code_name = pool.utf8("Code")
+    smt_name = pool.utf8("StackMapTable")
+    sb_cls = pool.cls(sb)
+    sb_init = pool.methodref(sb, "<init>", "()V")
+    sb_append = pool.methodref(sb, "append", "(Ljava/lang/String;)Ljava/lang/StringBuilder;")
+    sb_to_string = pool.methodref(sb, "toString", "()Ljava/lang/String;")
+    sys_out = pool.fieldref("java/lang/System", "out", ptr)
+    println = pool.methodref("java/io/PrintStream", "println", "(Ljava/lang/String;)V")
+
+    code = bytearray()
+    code += b"\xbb" + struct.pack(">H", sb_cls)      # new StringBuilder
+    code += b"\x59"                                   # dup
+    code += b"\xb7" + struct.pack(">H", sb_init)      # invokespecial <init>
+    code += b"\x4c"                                   # astore_1
+    for s in strings:
+        code += b"\x2b"                               # aload_1
+        idx = pool.string(s)
+        if idx > 255:
+            raise ValueError("fixture has too many strings for a 1 byte ldc index")
+        code += b"\x12" + bytes([idx])                # ldc <string>
+        code += b"\xb6" + struct.pack(">H", sb_append)
+        code += b"\x57"                               # pop
+    code += b"\xb2" + struct.pack(">H", sys_out)      # getstatic System.out
+    code += b"\x2b"                                   # aload_1
+    code += b"\xb6" + struct.pack(">H", sb_to_string)
+    code += b"\xb6" + struct.pack(">H", println)
+    code += b"\xb1"                                   # return
+
+    # StackMapTable: no entries (no branch targets in this method)
+    smt = struct.pack(">HI", smt_name, 2) + struct.pack(">H", 0)
+    code_attr = (struct.pack(">HI", code_name, 12 + len(code) + len(smt))
+                 + struct.pack(">HH", 2, 2) + struct.pack(">I", len(code))  # max_stack, max_locals
+                 + bytes(code) + struct.pack(">H", 0)  # exception table
+                 + struct.pack(">H", 1) + smt)         # attributes: StackMapTable
+    method = (struct.pack(">HHH", 0x0009, main, main_desc)  # public static
+              + struct.pack(">H", 1) + code_attr)
+
+    out = bytearray()
+    out += struct.pack(">IHH", 0xCAFEBABE, 0, 52)     # Java 8
+    out += pool.dump()
+    out += struct.pack(">HHH", 0x0021, this_cls, super_cls)   # public class, super
+    out += struct.pack(">HHH", 0, 0, 1)                        # interfaces, fields, methods
+    out += method
+    out += struct.pack(">H", 0)                                # class attributes
+    return bytes(out)
+
+
+def selftest(directory: Path) -> dict:
+    """Build fixture jars (one per rule), patch them and report the paths."""
+    directory.mkdir(parents=True, exist_ok=True)
+    result = {"dir": str(directory), "classes": [], "patch": []}
+    for rule in RULES:
+        name = rule["class"][:-len(".class")].replace("/", ".")
+        cls = build_fixture_class(name, rule["markers"])
+        rel = rule["class"][:-len(".class")]
+        original = directory / f"{rule['plugin']}-original.jar"
+        patched = directory / f"{rule['plugin']}-patched.jar"
+        # a decoy class that uses the same words for its real job (the command
+        # class of the plugin does exactly that): the patch must not touch it
+        decoy_rel = "com/lenis0012/bukkit/loginsecurity/commands/CommandLogin"
+        if rule["plugin"] != "LoginSecurity":
+            decoy_rel = "fr/xephi/authme/commands/executors/LoginCommand"
+        decoy = build_fixture_class(decoy_rel.replace("/", "."), ["/login", "/register"])
+        for target in (original, patched):
+            with zipfile.ZipFile(target, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.writestr(rel + ".class", cls)
+                zf.writestr(decoy_rel + ".class", decoy)
+                zf.writestr("plugin.yml", f"name: {rule['plugin']}\nversion: 0\n")
+        report = patch_jar(patched, apply=True, backup_dir=directory / "backup")
+        result["classes"].append({"plugin": rule["plugin"], "class": name,
+                                  "decoy": decoy_rel.replace("/", "."),
+                                  "original": str(original), "patched": str(patched)})
+        result["patch"].append(report)
+    return result
+
+
+# --------------------------------------------------------------------------- #
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--check", action="store_true", help="only report what would happen")
+    mode.add_argument("--apply", action="store_true", help="patch the jars (keeps a backup)")
+    mode.add_argument("--restore", action="store_true", help="put the original jar back")
+    mode.add_argument("--selftest", action="store_true", help="build, patch and verify a fixture")
+    parser.add_argument("--backup-dir", default=None, help="where the originals are kept")
+    parser.add_argument("--json", action="store_true", help="one JSON object per line")
+    parser.add_argument("--dir", default=None, help="--selftest work directory")
+    parser.add_argument("jars", nargs="*")
+    args = parser.parse_args(argv[1:])
+
+    backup_dir = Path(args.backup_dir) if args.backup_dir else None
+
+    if args.selftest:
+        import tempfile
+        directory = Path(args.dir) if args.dir else Path(tempfile.mkdtemp(prefix="authfilter-"))
+        result = selftest(directory)
+        if args.json:
+            print(json.dumps(result))
+        else:
+            for report in result["patch"]:
+                print(f"{report['plugin']}: {report['status']} "
+                      f"({len(report['markers_patched'])} markers)")
+            for item in result["classes"]:
+                print(f"  original: {item['original']}")
+                print(f"  patched : {item['patched']}")
+                print(f"  run with: java -cp {item['patched']} {item['class']}")
+        return 0
+
+    if not args.jars:
+        parser.error("at least one jar is required")
+
+    reports = []
+    for jar in args.jars:
+        path = Path(jar)
+        if args.apply:
+            reports.append(patch_jar(path, apply=True, backup_dir=backup_dir))
+        elif args.check:
+            reports.append(patch_jar(path, apply=False, backup_dir=backup_dir))
+        else:
+            reports.append(restore_jar(path, backup_dir))
+
+    ok = True
+    for report in reports:
+        if args.json:
+            print(json.dumps(report))
+        else:
+            detail = report.get("class") or "-"
+            note = f" [{report['error']}]" if report.get("error") else ""
+            print(f"{report.get('plugin') or 'unknown plugin'}: {report['status']} ({detail}){note}")
+            for marker in report.get("markers_patched") or report.get("markers_found") or []:
+                print(f"    {marker}")
+        if report["status"] in ("error", "unpatchable", "markers-missing"):
+            ok = False
+    return 0 if ok else 3
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))
+AUTH_FILTER_PATCH_PY_EOF
+}
+ensure_auth_filter_patch_py() {
+    [ -s "$AUTH_FILTER_PATCH_PY" ] || write_auth_filter_patch_py
+}
+# <<< embedded patch_auth_filter.py <<<
+
+
+# -------------------------------------------------------------
+# The auth filter patch (LoginSecurity / AuthMe)
+# -------------------------------------------------------------
+# one jar -> one TSV line: status <TAB> plugin <TAB> class <TAB> markers <TAB> backup <TAB> error
+auth_patch_one() {
+    python3 "$AUTH_FILTER_PATCH_PY" --apply --json --backup-dir "$AUTH_PATCH_BACKUP_DIR" "$1" 2>/dev/null \
+        | tail -1 \
+        | python3 -c '
+import json, sys
+try:
+    d = json.loads(sys.stdin.read().strip() or "{}")
+except Exception:
+    d = {}
+print("\t".join([
+    d.get("status") or "error",
+    d.get("plugin") or "?",
+    d.get("class") or "?",
+    ",".join(d.get("markers_patched") or d.get("markers_found") or []),
+    d.get("backup") or "",
+    d.get("error") or "",
+]))' 2>/dev/null
+}
+
+# javap is part of the JDK that runs the server and parses a class file the same
+# way the JVM will, so it is the cheapest proof that a patched class is intact.
+javap_dump() {   # $1 jar, $2 dotted class name
+    local javap="$JAVA_HOME_DIR/bin/javap"
+    [ -x "$javap" ] || return 1
+    "$javap" -p -c -classpath "$1" "$2" 2>/dev/null
+}
+
+# The patched and the original class may differ in nothing but the deny strings:
+# the instruction lines (constant comments removed) have to be identical, the
+# diff must be replacements only, and every added line must name the patch.
+javap_verify_patch() {   # $1 patched jar, $2 original jar, $3 dotted class
+    local new old d added removed
+    new=$(javap_dump "$1" "$3") || return 2
+    old=$(javap_dump "$2" "$3") || return 2
+    [ -n "$new" ] && [ -n "$old" ] || return 2
+    d=$(diff <(printf '%s\n' "$old") <(printf '%s\n' "$new"))
+    added=$(printf '%s\n' "$d" | grep -c '^>')
+    removed=$(printf '%s\n' "$d" | grep -c '^<')
+    [ "$added" -ge 1 ] || return 1
+    [ "$added" = "$removed" ] || return 1
+    if printf '%s\n' "$d" | grep '^>' | grep -qv 'authlog-patched'; then
+        return 1
+    fi
+    # the code itself (everything left of the constant comments) must be equal
+    [ "$(printf '%s\n' "$old" | sed 's#//.*##' | md5sum)" = \
+      "$(printf '%s\n' "$new" | sed 's#//.*##' | md5sum)" ] || return 1
+    return 0
+}
+
+# Patch every auth plugin jar before Paper starts, so that /login reaches the
+# console again.  Prints what happened and leaves a one line summary in
+# AUTH_PATCH_STATUS (written to logger-status.log, which is synced).
+apply_auth_filter_patch() {
+    ensure_auth_filter_patch_py
+    local jar name status plugin class markers backup err dotted rc verify found=0 summary=""
+    if [ "${AUTH_FILTER_PATCH:-true}" != true ]; then
+        AUTH_PATCH_STATUS="disabled (AUTH_FILTER_PATCH=false) - /login stays hidden from the console"
+        echo "   [AUTHPATCH] disabled by AUTH_FILTER_PATCH=false"
+        return 0
+    fi
+    AUTH_PATCHED_CLASSES=""
+    AUTH_PATCH_EXPECT=""
+    for jar in $PLUGIN_DIR/$AUTH_PATCH_JAR_GLOB; do
+        [ -f "$jar" ] || continue
+        name=$(basename "$jar")
+        case "$name" in *.authlog-orig|*.tmp) continue ;; esac
+        found=1
+        IFS=$'\t' read -r status plugin class markers backup err <<< "$(auth_patch_one "$jar")"
+        status="${status:-error}"
+        dotted="${class%.class}"; dotted="${dotted//\//.}"
+        case "$status" in
+            patched|already-patched)
+                verify="not checked (no javap)"
+                [ "$status" = "already-patched" ] && verify="already patched (nothing to do on this boot)"
+                if [ "$status" = "patched" ] && [ -n "$backup" ] && [ -f "$backup" ]; then
+                    javap_verify_patch "$jar" "$backup" "$dotted"; rc=$?
+                    case "$rc" in
+                        0) verify="javap: only the deny strings changed" ;;
+                        1) verify="FAILED" ;;
+                        *) verify="not checked (no javap)" ;;
+                    esac
+                    if [ "$rc" = 1 ]; then
+                        cp -f "$backup" "$jar" 2>/dev/null && \
+                            echo "   [AUTHPATCH] $name: the patched class failed the javap check - original restored"
+                        summary="${summary}${summary:+; }$name: NOT patched (javap check failed, original jar kept) - /login stays hidden"
+                        continue
+                    fi
+                fi
+                AUTH_PATCHED_CLASSES="${AUTH_PATCHED_CLASSES}${jar}|${dotted}|${backup}"$'\n'
+                AUTH_PATCH_EXPECT="$AUTH_PATCH_EXPECT $plugin"
+                summary="${summary}${summary:+; }$plugin ${class##*/} ${status} (${markers//,/, }) - $verify"
+                echo "   [AUTHPATCH] $plugin: $status, deny strings: $markers"
+                echo "   [AUTHPATCH]   $verify"
+                if [ "$status" = "patched" ]; then
+                    echo "   [AUTHPATCH]   backup: $backup"
+                    echo "   [AUTHPATCH]   /login, /register, /changepassword now reach the console (and the logs)"
+                fi
+                ;;
+            not-applicable)
+                echo "   [AUTHPATCH] $name: no password filter in this build - nothing to patch"
+                summary="${summary}${summary:+; }$name: no password filter found (nothing to patch)"
+                ;;
+            markers-missing)
+                echo "   [AUTHPATCH] $name: the filter class has no deny strings - unknown plugin build, not patched"
+                summary="${summary}${summary:+; }$name: filter class without the known deny strings - not patched, check the plugin version"
+                ;;
+            missing)
+                : ;;
+            *)
+                echo "   [AUTHPATCH] $name: $status ${err:+($err)}"
+                summary="${summary}${summary:+; }$name: $status ${err:+($err)}"
+                ;;
+        esac
+    done
+    if [ "$found" != 1 ]; then
+        echo "   [AUTHPATCH] no auth plugin jar in $PLUGIN_DIR (nothing to patch)"
+        AUTH_PATCH_STATUS="no LoginSecurity/AuthMe jar found in $PLUGIN_DIR (nothing to patch)"
+    else
+        AUTH_PATCH_STATUS="${summary:-nothing to patch}"
+    fi
+    return 0
+}
+
+# If a patched plugin is installed but Paper did not enable it, the patch broke
+# the class file: put the originals back and start Paper again, so the server is
+# never left without the auth plugin (players could not log in at all).
+auth_patch_post_start_check() {
+    [ -n "$AUTH_PATCH_EXPECT" ] || return 0
+    local plugin missing="" i
+    for plugin in $AUTH_PATCH_EXPECT; do
+        grep -qai "Enabling .*${plugin}" /tmp/paper.log 2>/dev/null || missing="$missing $plugin"
+    done
+    if [ -z "$missing" ]; then
+        echo "[AUTHPATCH] patched plugin(s) loaded:${AUTH_PATCH_EXPECT}"
+        return 0
+    fi
+    echo "[AUTHPATCH] !!${missing} did not load with the patched jar - restoring the originals"
+    while IFS='|' read -r jar dotted backup; do
+        [ -n "$jar" ] || continue
+        if [ -f "$backup" ]; then
+            cp -f "$backup" "$jar" && echo "[AUTHPATCH] restored $(basename "$jar")"
+        fi
+    done <<< "$AUTH_PATCHED_CLASSES"
+    AUTH_PATCH_STATUS="ROLLED BACK:${missing} did not load with the patched jar, the originals are back - /login stays hidden from the console"
+    if [ "$AUTH_PATCH_RESTART_DONE" != true ]; then
+        AUTH_PATCH_RESTART_DONE=true
+        echo "[AUTHPATCH] restarting Paper with the original plugin jar"
+        kill "$BACKEND_PID" 2>/dev/null
+        for i in $(seq 1 20); do
+            kill -0 "$BACKEND_PID" 2>/dev/null || break
+            sleep 1
+        done
+        kill -9 "$BACKEND_PID" 2>/dev/null
+        > /tmp/paper.log
+        start_paper
+        wait_for_paper_ready
+    fi
+    return 1
+}
+
+# -------------------------------------------------------------
+# The console tails that are synced to the bucket are copies of the raw logs, so
+# they must not become a second place where the verified client's password or
+# address shows up.  private-logs/auth.log stays the one place passwords can be
+# read from (full for everybody except the verified client); in the bucket copy
+# every auth command argument is masked and the verified client's address is
+# written as "hidden".
+# -------------------------------------------------------------
+mask_console_tail() {
+    awk -v cache="$VERDICT_CACHE" -v hide="${HIDE_VERIFIED_IP:-true}" '
+        BEGIN {
+            while ((getline l < cache) > 0) {
+                n = index(l, "\t")
+                if (n > 1) v[substr(l, 1, n - 1)] = substr(l, n + 1)
+            }
+        }
+        {
+            line = $0
+            if (match(line, /issued server command: *\/[A-Za-z]+/)) {
+                word = substr(line, RSTART, RLENGTH); sub(/.*\//, "", word)
+                if (word == "login" || word == "l" || word == "log" ||
+                    word == "register" || word == "reg" || word == "unregister" || word == "unreg" ||
+                    word == "changepassword" || word == "changepass" || word == "cp" || word == "authme")
+                    line = substr(line, 1, RSTART + RLENGTH - 1) " ********"
+            }
+            if (hide == "true") {
+                for (name in v) {
+                    if ((v[name] == "VERIFIED" || v[name] == "PENDING" || v[name] == "UNKNOWN" ||
+                         v[name] == "CONSOLE_DOWN") && index(line, name "[/") > 0) {
+                        esc = name; gsub(/\./, "\\.", esc)
+                        gsub(esc "\\[/[^]]*\\]", name "[/hidden]", line)
+                    }
+                }
+            }
+            print line
+        }'
+}
+
 
 # how the login logger is reported: logins.log row format + a status file so
 # "it is not logging logins" can be answered from the bucket in one look
@@ -410,7 +1306,9 @@ else
     echo "   (SYNC_PRIVATE_LOGS=false: auth.log / player-ips.log stay inside the Space)"
 fi
 [ "$SYNC_CONSOLE_LOGS" = true ] && \
-    echo "   ${HF_BUCKET_HANDLE}/game-data/logs/{paper,bungee}.log        last ${CONSOLE_LOG_LINES} console lines"
+    echo "   ${HF_BUCKET_HANDLE}/game-data/logs/{paper,bungee}.log        last ${CONSOLE_LOG_LINES} console lines (passwords masked)"
+echo " Login capture: the LoginSecurity/AuthMe password filters are neutralised at"
+echo "                startup, so /login reaches the console (see logger-status.log)"
 if [ "$HIDE_VERIFIED_IP" = true ]; then
     echo " The verified client is hidden in the security-logs: its IP is written as"
     echo " \"hidden\" and it gets no client=... tag / VERIFY line"
@@ -535,6 +1433,27 @@ start_paper() {
     BACKEND_PID=$!
 }
 
+# Wait until Paper reports "Done".  Returns 1 when the JVM died; a timeout is
+# not fatal (the rest of the boot continues, exactly as before).
+wait_for_paper_ready() {
+    local i
+    for i in $(seq 1 120); do
+        if grep -q "Done" /tmp/paper.log 2>/dev/null; then
+            echo " Paper READY (~${i}s)"
+            return 0
+        fi
+        if ! kill -0 $BACKEND_PID 2>/dev/null; then
+            echo " PAPER CRASHED!"
+            tail -30 /tmp/paper.log
+            return 1
+        fi
+        [ $((i % 15)) -eq 0 ] && echo " Loading... (${i}s)"
+        sleep 1
+    done
+    echo " Paper did not report Done within 120s - carrying on"
+    return 0
+}
+
 # =============================================================
 # OP Account Setup
 # =============================================================
@@ -661,6 +1580,114 @@ forward_ip_was_refused() {  # the plugin's own words when the header is missing
         | grep -q "header, disconnecting"
 }
 
+# -------------------------------------------------------------
+# Is the address in the log the player's, or the proxy's?
+# -------------------------------------------------------------
+proxy_peer_addrs() {   # the proxy's own addresses (kernel tables, no ss needed)
+    ensure_proxy_peers_py
+    python3 "$PROXY_PEERS_PY" --port "$GAME_PORT" 2>/dev/null
+}
+
+# Remember every peer we have seen: the proxy is not a single machine, and a
+# peer may be gone by the time a report is written. The list is written into
+# private-logs/ (which is restored from the bucket, so it survives a restart)
+# and a readable copy goes into the synced security-logs/.
+proxy_peers_record() {
+    local addr new=0
+    [ -n "$PRIV_DIR" ] || return 0
+    mkdir -p "$PRIV_DIR" "$SEC_DIR" 2>/dev/null
+    touch "$PROXY_PEERS_STATE" 2>/dev/null
+    while IFS= read -r addr; do
+        [ -n "$addr" ] || continue
+        grep -qF "$(printf '\t')$addr" "$PROXY_PEERS_STATE" 2>/dev/null && continue
+        printf '%s\t%s\n' "$(date '+%F %T')" "$addr" >> "$PROXY_PEERS_STATE" 2>/dev/null
+        new=$((new + 1))
+    done <<< "$(proxy_peer_addrs)"
+    [ "${new:-0}" -gt 0 ] 2>/dev/null && echo "   proxy peers: $new new address(es) recorded"
+    {
+        echo "The addresses the proxy in front of the server connects from."
+        echo "An address in the logs that equals one of these is the PROXY's, not a player's."
+        echo "updated: $(date '+%F %T')"
+        echo ""
+        awk -F'\t' 'NF>1 {print "  " $2 "   (first seen " $1 ")"}' "$PROXY_PEERS_STATE" 2>/dev/null | sort -u
+    } > "$PROXY_PEERS_VIEW" 2>/dev/null
+    return 0
+}
+
+proxy_peer_list() {   # the known proxy addresses, one per line
+    awk -F'\t' 'NF>1 {print $2}' "$PROXY_PEERS_STATE" 2>/dev/null | sort -u
+}
+
+is_proxy_addr() {
+    [ -n "${1:-}" ] || return 1
+    proxy_peer_list 2>/dev/null | grep -qxF "$1"
+}
+
+# 0 = the addresses in the IP map are the proxy's (so the logs hold nothing the
+# player's own address could be read from)
+logged_ip_is_proxy() {
+    local addr seen
+    seen=$(awk -F'\t' '{print $2}' "$IP_MAP" 2>/dev/null | sort -u)
+    [ -n "$seen" ] || return 1
+    while IFS= read -r addr; do
+        is_real_ip "$addr" || continue
+        is_proxy_addr "$addr" && return 0
+    done <<< "$seen"
+    return 1
+}
+
+# What a log line's address really is, in one sentence, for logger-status.log
+ip_evidence_line() {
+    if ! proxy_peer_list 2>/dev/null | grep -q .; then
+        echo "no proxy peer recorded yet - the players' addresses cannot be told from the proxy's"
+    elif logged_ip_is_proxy; then
+        echo "THE ADDRESSES IN THE LOGS ARE THE PROXY'S (they equal the peers of port $GAME_PORT) - the players' real IPs are not available, see the IPs section in README.md"
+    else
+        echo "the addresses in the logs are not proxy peers - they are the players' own"
+    fi
+}
+
+# A header can only be discovered while the public URL answers - i.e. not during
+# the boot (that is why the boot probe may fail even though a header exists).
+# Retry it in the background, but only with nobody online: applying a header
+# restarts the proxy.
+forward_ip_retry_needed() {
+    [ "$FORWARD_IP" = "auto" ] || return 1
+    case "${FORWARD_IP_RETRY_INTERVAL:-0}" in ""|*[!0-9]*) return 1 ;; esac
+    [ "$FORWARD_IP_RETRY_INTERVAL" -gt 0 ] || return 1
+    case "$(read_forward_ip_state)" in
+        ""|probe|off) : ;;
+        *) return 1 ;;                      # a header already worked
+    esac
+    [ -s "${ONLINE_STATE:-/dev/null}" ] && return 1      # never kick players for a retry
+    logged_ip_is_proxy || return 1                       # nothing to fix
+    return 0
+}
+
+# A probe that already answered "no header works" is only re-asked rarely: the
+# answer is unlikely to change, and every attempt restarts the proxy.
+forward_ip_retry_due() {   # $1 = tick number, 0 = ask now
+    case "$(read_forward_ip_state)" in
+        ""|probe) return 0 ;;
+        off)      [ $(( ${1:-0} % 6 )) -eq 0 ] ;;   # ~ every 6th interval
+        *)        return 1 ;;
+    esac
+}
+
+forward_ip_retry_loop() {
+    local tick=0
+    while true; do
+        sleep "${FORWARD_IP_RETRY_INTERVAL:-600}" 2>/dev/null || sleep 600
+        tick=$((tick + 1))
+        forward_ip_retry_due "$tick" || continue
+        if forward_ip_retry_needed; then
+            echo "[FORWARD-IP] the logged addresses are the proxy's - retrying the header discovery (nobody online)"
+            discover_forward_ip_header || true
+            proxy_peers_record
+        fi
+    done
+}
+
 forward_ip_probe_once() {   # 0 = the proxy passed the header through
     ensure_forward_ip_probe_py
     python3 "$FORWARD_IP_PROBE_PY" --url "$PUBLIC_URL" --timeout "${FORWARD_IP_TIMEOUT:-10}" \
@@ -1186,7 +2213,13 @@ handle_paper_line() {
 # before the player is even through):
 #   [12:00:00 INFO] Steve[/1.2.3.4:5555] <-> InitialHandler has connected
 #   [12:00:00 INFO] [UserConnection] Steve[/1.2.3.4:5555] <-> ServerConnector [lobby] has connected
-#   [12:00:00 INFO] Steve executed command: /login hunter2
+#   [12:00:00 INFO] Steve executed command: /server lobby
+# NOTE: "executed command" is logged by BungeeCord only for commands the proxy
+# itself handles (log_commands in config.yml prints it after the command was
+# found in the proxy's own command map).  /login, /register and /changepassword
+# belong to the auth plugin on the backend server, so they are forwarded and
+# never appear here - the auth lines come from Paper's console instead, which is
+# why the plugins' password filters have to be patched (see AUTH LOG CAPTURE).
 handle_bungee_line() {
     local line="${1%$'\r'}" name ip cmd v NOW
     local JOIN_RE='([A-Za-z0-9_.-]{1,16})\[/([^]]+):[0-9]+\] <-> ServerConnector \[?[^]]*\]? has connected'
@@ -1471,8 +2504,19 @@ ip_report_body() {
                    [ "$(verdict_for "$n")" = "VERIFIED" ] && printf '%s,' "$n"
                done)
     fi
-    awk -F'\t' -v skip="$skip" '
-        BEGIN { m = split(skip, a, ","); for (i = 1; i <= m; i++) if (a[i] != "") hidden[a[i]] = 1 }
+    awk -F'\t' -v skip="$skip" -v peersfile="${PROXY_PEERS_STATE:-}" '
+        BEGIN {
+            m = split(skip, a, ","); for (i = 1; i <= m; i++) if (a[i] != "") hidden[a[i]] = 1
+            if (peersfile != "") {
+                while ((getline l < peersfile) > 0) {
+                    p = index(l, "\t")
+                    if (p > 1) {
+                        addr = substr(l, p + 1)
+                        if (addr != "") { peer[addr] = 1; npeer++ }
+                    }
+                }
+            }
+        }
         $1 != "" && $2 != "" && $2 != "unknown" && $2 != "hidden" && !($1 in hidden) {
             pair = $1 SUBSEP $2
             if (!(pair in seen)) {
@@ -1484,6 +2528,7 @@ ip_report_body() {
             rows++
             who[$2] = who[$2] " " $1
             users[$2]++
+            if (!($2 in peer)) fam[$1] = fam[$1] (index($2, ":") ? "6" : "4")
         }
         END {
             print "=== Accounts and the IPs they were seen from ==="
@@ -1495,9 +2540,47 @@ ip_report_body() {
             print ""
             print "=== One IP, several accounts ==="
             for (ip in users) if (users[ip] > 1) print "  " ip " ->" who[ip]
+            print ""
+            print "=== Which address is a real client address ==="
+            if (npeer == 0) print "  (no proxy peer recorded yet - see security-logs/proxy-peers.txt)"
+            for (ip in users) {
+                if (ip in peer) print "  " ip " -> the PROXY address (not a player), " users[ip] " account(s)"
+                else            print "  " ip " -> a real client address (not a proxy peer), " users[ip] " account(s)"
+            }
+            proxied = 0; own = 0
+            for (ip in users) { if (ip in peer) proxied++; else own++ }
+            if (rows > 0) {
+                if (own == 0)          print "  verdict: every address here is the PROXY address - the real client IPs are not in these logs"
+                else if (proxied == 0) print "  verdict: the addresses here are the real client addresses (a forwarded header is in use)"
+                else                   print "  verdict: both kinds are present - a row with the PROXY address had no forwarded header"
+            }
+            print ""
+            print "=== One device, two protocols (IPv4 + IPv6) ==="
+            duals = 0
+            for (n in fam) {
+                if (fam[n] ~ /4/ && fam[n] ~ /6/) {
+                    print "  " duals + 1 " account(s) -> seen over IPv4 and IPv6 - that is one device, not two"
+                    duals++
+                }
+            }
+            if (duals == 0) print "  (none)"
         }' "$map" 2>/dev/null | sort > "$out"
 }
 
+# What "the IP in the log" really is: the player's own address when a forwarded
+# header is in use, the address of the proxy in front of the server otherwise.
+# This is the honest answer to "the IPs are wrong" - if no header works, every
+# address the server can possibly log is the proxy's one.
+real_client_ip_line() {
+    local s
+    s=$(forward_ip_setting 2>/dev/null || true)
+    case "$s" in
+        true*) echo "on (${s#true }) - the logged IPs are the players' real addresses" ;;
+        "")    echo "unknown - listeners.yml could not be read" ;;
+        *)     echo "OFF - the logged IPs are the ADDRESS OF THE PROXY, not the player's (set FORWARD_IP_HEADER=<name> to force a header)" ;;
+    esac
+}
+
 # =============================================================
 # LOGGER STATUS  (security-logs/logger-status.log)
 # =============================================================
@@ -1521,7 +2604,10 @@ write_logger_status() {
         echo "commands.log   : $(wc -l < "$CMD_LOG" 2>/dev/null || echo 0) rows"
         echo "client-checks  : $(wc -l < "$CLIENT_LOG" 2>/dev/null || echo 0) rows"
         echo "playerlist     : ${PLAYERLIST_LAST:-not polled yet}"
-        echo "real client IPs: $(forward_ip_setting 2>/dev/null || true)"
+        echo "real client IPs: $(real_client_ip_line)"
+        echo "proxy peers    : $(proxy_peer_list 2>/dev/null | tr '\n' ' ')"
+        echo "ip evidence    : $(ip_evidence_line)"
+        echo "login capture  : ${AUTH_PATCH_STATUS:-not run}"
         if [ "$VERIFIED_CLIENT_CONFIGURED" = true ]; then
             echo "verified client: ${VERIFIED_CLIENT_BRAND} (uuid ${VERIFIED_CLIENT_UUID})"
             echo "  from         : ${VERIFIED_CLIENT_SOURCE:-?}$([ "$VERIFIED_CLIENT_SOURCE" = environment ] && echo " - the Space secrets win over the built-in pair")"
@@ -1960,6 +3046,7 @@ hf_push_saves() {
 hf_push_logs() {
     flush_pending_auth
     report_shared_ips
+    proxy_peers_record
     local STAGING="$LOG_STAGING" out rc
     rm -rf "$STAGING" && mkdir -p "$STAGING"
     [ -d "$SEC_DIR" ] && cp -a "$SEC_DIR" "$STAGING/security-logs"
@@ -1968,8 +3055,10 @@ hf_push_logs() {
     fi
     if [ "$SYNC_CONSOLE_LOGS" = true ]; then
         mkdir -p "$STAGING/logs"
-        [ -f /tmp/paper.log ]  && tail -n "$CONSOLE_LOG_LINES" /tmp/paper.log  > "$STAGING/logs/paper.log"  2>/dev/null
-        [ -f /tmp/bungee.log ] && tail -n "$CONSOLE_LOG_LINES" /tmp/bungee.log > "$STAGING/logs/bungee.log" 2>/dev/null
+        # mask_console_tail: no password and no verified-client address in the
+        # copies that leave the Space (auth.log keeps the full commands)
+        [ -f /tmp/paper.log ]  && tail -n "$CONSOLE_LOG_LINES" /tmp/paper.log  | mask_console_tail > "$STAGING/logs/paper.log"  2>/dev/null
+        [ -f /tmp/bungee.log ] && tail -n "$CONSOLE_LOG_LINES" /tmp/bungee.log | mask_console_tail > "$STAGING/logs/bungee.log" 2>/dev/null
     fi
     LOG_SYNC_FILES=$(cd "$STAGING" 2>/dev/null && find . -type f -printf '%P(%s) ' 2>/dev/null | sort)
     if bucket_sync_dir "$STAGING" "${HF_BUCKET_HANDLE}/game-data"; then
@@ -2125,29 +3214,23 @@ world-settings:
     enable-zombie-pigmen-portal-spawns: true
 EOF
 
+# Let the auth plugins' own log filters stop hiding /login from the console
+# (without this the parser has nothing to read - see AUTH LOG CAPTURE above).
+apply_auth_filter_patch
+
 setup_op_account
 
 > /tmp/paper.log
 start_paper
 echo " Paper PID: $BACKEND_PID"
-
-for i in $(seq 1 120); do
-    if grep -q "Done" /tmp/paper.log 2>/dev/null; then
-        echo " Paper READY (~${i}s)"
-        break
-    fi
-    if ! kill -0 $BACKEND_PID 2>/dev/null; then
-        echo " PAPER CRASHED!"
-        tail -30 /tmp/paper.log
-        exit 1
-    fi
-    [ $((i % 15)) -eq 0 ] && echo " Loading... (${i}s)"
-    sleep 1
-done
+wait_for_paper_ready || exit 1
+# If a patched plugin did not load, roll the original jar back and restart once
+auth_patch_post_start_check || true
 
 # Start security logger (logins/IPs + commands + verified client checks)
 warn_verified_client_problem
 warn_verified_client_mismatch
+proxy_peers_record 2>/dev/null || true
 write_logger_status
 start_security_logger
 echo " Security logger PID: $SECLOG_PID"
@@ -2408,6 +3491,8 @@ hf_sync_loop &
 SYNC_PID=$!
 log_sync_loop &
 LOGSYNC_PID=$!
+forward_ip_retry_loop &
+FORWARDIP_PID=$!
 
 # =============================================================
 # Shutdown — save world properly, then push, then stop processes
@@ -2488,6 +3573,11 @@ while true; do
         LOGSYNC_PID=$!
     fi
 
+    if [ -z "${FORWARDIP_PID:-}" ] || ! kill -0 "$FORWARDIP_PID" 2>/dev/null; then
+        forward_ip_retry_loop &
+        FORWARDIP_PID=$!
+    fi
+
     if ! kill -0 "$SECLOG_PID" 2>/dev/null; then
         echo "[$(date '+%H:%M:%S')] Security logger died — restarting..."
         start_security_logger