49 lines
2.0 KiB
Markdown
49 lines
2.0 KiB
Markdown
# 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.
|