nroxy/docs/ops/telegram-pairing.md

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.