docs: add Debian runtime notes

docs/healthchecks.md

@@ -0,0 +1,88 @@
+# Healthchecks
+
+This repository contains the operational wrapper for the headless login healthcheck. The underlying smoke client lives in `m2dev-server-src`.
+
+## What Exists
+
+Source repository:
+
+- `tests/login_smoke.cpp`
+- binary target: `metin_login_smoke`
+
+Runtime repository:
+
+- `deploy/healthcheck/metin-login-healthcheck.sh`
+
+Installed on the VPS:
+
+- `/usr/local/sbin/metin-login-healthcheck`
+
+## What The Headless Login Check Verifies
+
+The check performs the real two-step Metin login flow without a GUI client:
+
+1. Connect to the auth socket.
+2. Complete the secure handshake.
+3. Send login credentials.
+4. Receive `AUTH_SUCCESS` and the login key.
+5. Open a second connection to the channel socket.
+6. Complete the secure handshake again.
+7. Send `LOGIN2` with `login` + `login_key`.
+8. Verify `EMPIRE`.
+9. Verify `LOGIN_SUCCESS4`.
+
+This is an end-to-end login verification, not just a TCP port check.
+
+## How The Wrapper Works
+
+`metin-login-healthcheck.sh` does the following:
+
+- creates a temporary account in MariaDB
+- runs `metin_login_smoke`
+- verifies a successful auth + channel login
+- deletes the temporary account on exit
+
+It is intended for manual admin use on the VPS.
+
+## Usage
+
+On the VPS:
+
+```bash
+ssh mt2
+/usr/local/sbin/metin-login-healthcheck
+```
+
+The smoke binary can also be run directly:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev \
+  /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \
+  173.249.9.66 11000 11011 <login> <password>
+```
+
+Or with password passed through the environment:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev env METIN_LOGIN_SMOKE_PASSWORD='<password>' \
+  /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \
+  173.249.9.66 11000 11011 <login> --password-env=METIN_LOGIN_SMOKE_PASSWORD
+```
+
+## Security Notes
+
+This does not open a new public network surface. It is a local operational tool.
+
+Current guardrails:
+
+- no new listening port
+- root-only installed wrapper (`/usr/local/sbin/metin-login-healthcheck`, mode `700`)
+- temporary credentials
+- cleanup trap removes the test account
+- wrapper passes the password through environment instead of command-line plaintext
+- secrets are not committed to git
+
+Remaining trust boundary:
+
+- anyone with effective root access can still inspect or run the check
+- therefore this tool assumes root is already trusted