Initial import

docs/ops/telegram-pairing.md

@@ -0,0 +1,48 @@
+# Telegram Pairing Flow
+
+## Goal
+Allow a new Telegram admin to be approved from the server console without editing the database manually.
+
+## Runtime behavior
+### Unpaired user
+1. A user opens the Telegram bot.
+2. The bot checks whether `telegram_user_id` is present in the allowlist.
+3. If not present, the bot creates a pending pairing record with:
+   - Telegram user ID
+   - Telegram username and display name snapshot
+   - pairing code hash
+   - expiration timestamp
+   - status `pending`
+4. The bot replies with a message telling the user to run `nproxy pair <code>` on the server.
+
+Current runtime note:
+- The current bot runtime uses Telegram long polling.
+- On each message from an unpaired user, the bot rotates any previous pending code and issues a fresh pairing code.
+- Pending pairing creation writes an audit-log entry with actor type `system`.
+
+### Pair completion
+1. An operator runs `nproxy pair <code>` on the server.
+2. The CLI looks up the pending pairing by code.
+3. The CLI prints the target Telegram identity and asks for confirmation.
+4. On confirmation, the CLI adds the Telegram user to the allowlist.
+5. The CLI marks the pending pairing record as `completed`.
+6. The CLI writes an admin action log entry.
+
+## Required CLI commands
+- `nproxy pair <code>`
+- `nproxy pair list`
+- `nproxy pair revoke <telegram-user-id>`
+- `nproxy pair cleanup`
+
+## Current CLI behavior
+- `nproxy pair <code>` prints the Telegram identity and requires explicit confirmation unless `--yes` is provided.
+- `nproxy pair list` prints active allowlist entries and pending pairing records.
+- `nproxy pair revoke <telegram-user-id>` requires explicit confirmation unless `--yes` is provided.
+- `nproxy pair cleanup` marks expired pending pairing records as `expired` and writes an audit log entry.
+
+## Security rules
+- Pairing codes expire.
+- Pairing codes are stored hashed, not in plaintext.
+- Only the server-side CLI can complete a pairing.
+- Telegram bot access is denied until allowlist membership exists.
+- Every pairing and revocation action is auditable.