telegram-gateway/AUTH.md

← README · HOWTO_ADD_BOT · Authentification

Détails de design : factory ADR 20260509 — telegram-gateway auth

Authentification

Le gateway est protégé en deux couches :

1. Allowlist (ALLOWED_USERS, optionnelle) — filtre la liste des Telegram user IDs autorisés à parler à n'importe quel bot. Hors-liste : silent drop, le bot ne répond rien (l'inconnu ne sait même pas que le bot existe).
2. Session /auth — par défaut, tous les bots du gateway exigent une session active (requireAuth: true par défaut). Pour ouvrir une session, il faut DM @arcodange_factory_bot avec /auth <code>. Une session dure 24 h (configurable via AUTH_SESSION_TTL).

Côté utilisateur

1. Ouvrir une session

1. Sur Telegram, ouvre @arcodange_factory_bot.
2. Envoie /auth <code> (le code t'a été partagé par l'admin du gateway).
3. Le bot répond ✅ Authentifié pour 24 h. Ton message contenant le code est automatiquement supprimé du chat (replay defense).
4. Tu peux maintenant DM les autres bots normalement.

2. Vérifier sa session

/whoami

Réponse type : user=123456 : ✅ authentifié, reste 23h59m. ou user=123456 : non authentifié..

3. Fermer une session

/logout

4. Quand un bot répond 🔒 Authentifie-toi …

Ta session a expiré (TTL dépassé) ou tu n'as jamais fait /auth. Va sur @arcodange_factory_bot, refais /auth <code>.

Côté opérateur

Définir / changer le code AUTH_SECRET

# Choisir un code fort (ex : openssl rand -hex 16)
SECRET='<chosen-code>'

kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
  {\"op\":\"replace\",\"path\":\"/data/AUTH_SECRET\",\"value\":\"$(echo -n "$SECRET" | base64)\"}
]"

# Restart pour reload du Secret
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway

Rotation : changer AUTH_SECRET invalide les futurs /auth mais pas les sessions Redis déjà ouvertes (elles vivent jusqu'à leur TTL). Pour invalider tout : kubectl exec -n tools redis-0 -- redis-cli --scan --pattern 'tg-gw:auth:*' | xargs -I{} kubectl exec -n tools redis-0 -- redis-cli DEL {}.

Définir / changer l'allowlist

kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
  {\"op\":\"replace\",\"path\":\"/data/ALLOWED_USERS\",\"value\":\"$(echo -n '12345,67890' | base64)\"}
]"
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway

Pour désactiver l'allowlist (ouvrir à tout Telegram user en allowlist) :

kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p='[
  {"op":"remove","path":"/data/ALLOWED_USERS"}
]'
kubectl -n telegram-gateway rollout restart deploy/telegram-gateway

Inspecter une session Redis

USER_ID=123456
kubectl exec -n tools redis-0 -- redis-cli GET   "tg-gw:auth:$USER_ID"   # → "1" ou (nil)
kubectl exec -n tools redis-0 -- redis-cli TTL   "tg-gw:auth:$USER_ID"   # → secondes restantes
kubectl exec -n tools redis-0 -- redis-cli DEL   "tg-gw:auth:$USER_ID"   # → forcer logout

Rendre un bot public (opt-out de l'auth)

Dans chart/values.yaml, ajouter requireAuth: false au bot concerné :

bots:
  statusbot:
    handler: echo
    requireAuth: false   # bot public, pas de session requise

Cas spécial : handler: auth (le bot principal factory) force toujours requireAuth: false automatiquement (sinon l'auth elle-même serait inaccessible — chicken-and-egg).

Limites connues

• Pas de TOTP / OTP rotatif — un code partagé suffit pour cet usage privé. À reconsidérer si on ouvre à plus d'utilisateurs.
• Pas de rate-limit sur /auth — l'ALLOWED_USERS joue le rôle de garde-fou. Avec un code fort (≥ 128 bits), le bruteforce est inutile dans la fenêtre de TTL.
• Sessions invalidées si Redis tombe — fail-closed : tous les bots gated répondent 🔒 jusqu'à ce que Redis revienne. Acceptable.
• from.id-based, pas IP-based — Telegram n'expose pas l'IP du user au bot. Une session couvre tous les devices d'un même compte Telegram, ce qui est le comportement attendu.

Chemin de migration vers Vault (Phase 2+)

Aujourd'hui, AUTH_SECRET et ALLOWED_USERS vivent dans un Secret k8s créé via kubectl create secret. À terme, ils basculeront dans Vault (toggle vault.enabled: true dans chart/values.yaml, provisionner kvv2/telegram-gateway/config). Le code n'a pas à changer — envFrom: secretRef consomme indifféremment un Secret manuel ou un Secret produit par VaultStaticSecret.