Phase 1.5 — auth layer (Redis sessions, allowlist, requireAuth)

Adds an authentication layer in front of the bot handlers :

- Auth handler on the principal bot (@arcodange_factory_bot, slug
  factory) parses /start, /auth <code>, /whoami, /logout. On a
  successful /auth, the message containing the code is best-effort
  deleted from the user's chat (replay defense).
- Redis-backed sessions (key tg-gw:auth:<from.id>, TTL 24h, configurable
  via AUTH_SESSION_TTL). Constant-time secret compare via crypto/subtle.
- ALLOWED_USERS env (CSV of Telegram user IDs) — silent-drops anyone
  not in the list before the auth gate runs.
- New per-bot field 'requireAuth' (pointer-bool). Default = true (secure
  by default). Auto-forced to false for handler=auth (chicken-and-egg).
- Server gates: allowlist first, then requireAuth before handler dispatch.
- Fail-at-startup if a bot is configured with handler=auth or
  requireAuth: true while AUTH_SECRET is unset.

Design: factory/docs/adr/20260509-telegram-gateway-auth.md (in factory PR).
User docs: AUTH.md (new), HOWTO_ADD_BOT.md (Cas 2 updated for default
true and gated flow).

New deps: github.com/redis/go-redis/v9.

Refs ~/.claude/plans/pour-les-notifications-on-inherited-seal.md § Phase 1.5.

HOWTO_ADD_BOT.md

@@ -31,49 +31,74 @@ la session n'a rien à recevoir en retour.
 
 ---
 
-## Cas 2 — Bot echo simple via le gateway (Phase 1)
+## Cas 2 — Bot echo simple via le gateway (Phase 1, gated par auth)
 
 Utile pour valider la chaîne, créer un canal de log conversationnel, etc.
 
+> **Auth (Phase 1.5, ADR [20260509](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/docs/adr/20260509-telegram-gateway-auth.md))** : par défaut, **`requireAuth: true`** s'applique → tout user qui DM ce bot doit d'abord ouvrir une session via `/auth <code>` chez `@arcodange_factory_bot`. Voir [`AUTH.md`](AUTH.md). Pour rendre un bot public, ajouter explicitement `requireAuth: false`.
+
 Steps (humain ou session Claude avec accès au cluster + au repo) :
 
-```bash
-# 1. @BotFather crée le bot, noter le TOKEN
-TOKEN='1234:AAA...'
-SLUG='monbot'                                    # kebab-case, [a-z0-9-]+
-ENV_SLUG=$(echo "$SLUG" | tr 'a-z-' 'A-Z_')      # ex: monbot → MONBOT
-SECRET=$(openssl rand -hex 32)
+1. **@BotFather crée le bot**, noter le TOKEN.
 
-# 2. Patcher le Secret cluster (ajoute les 2 clés sans toucher aux existantes)
-kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
-  {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_TOKEN\",\"value\":\"$(echo -n "$TOKEN" | base64)\"},
-  {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_SECRET\",\"value\":\"$(echo -n "$SECRET" | base64)\"}
-]"
+   ```bash
+   TOKEN='1234:AAA...'
+   SLUG='monbot'                                    # kebab-case, [a-z0-9-]+
+   ENV_SLUG=$(echo "$SLUG" | tr 'a-z-' 'A-Z_')      # ex: monbot → MONBOT
+   SECRET=$(openssl rand -hex 32)
+   ```
 
-# 3. Déclarer le bot dans chart/values.yaml sous bots:
-#    (édite le fichier puis push)
-cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
-# ajouter sous "bots:" :
-#   monbot:
-#     handler: echo
-git add chart/values.yaml
-git commit -m "bots: add $SLUG"
-git push
+2. **Patcher le Secret cluster** (ajoute les 2 clés sans toucher aux existantes) :
 
-# 4. Forcer le rollout pour que le pod relise la ConfigMap (le checksum
-#    annotation s'en charge en théorie, mais on s'assure)
-kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
-kubectl -n telegram-gateway rollout status deploy/telegram-gateway
+   ```bash
+   kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
+     {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_TOKEN\",\"value\":\"$(echo -n "$TOKEN" | base64)\"},
+     {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_SECRET\",\"value\":\"$(echo -n "$SECRET" | base64)\"}
+   ]"
+   ```
 
-# 5. Enregistrer le webhook côté Telegram
-export BOT_${ENV_SLUG}_TOKEN="$TOKEN"
-export BOT_${ENV_SLUG}_SECRET="$SECRET"
-make setwebhook SLUG="$SLUG" BASE_URL=https://tg.arcodange.fr
+3. **Déclarer le bot** dans `chart/values.yaml` sous `bots:` :
 
-# 6. Test : envoie un message au bot, attends < 2s pour l'echo
-```
+   ```yaml
+   bots:
+     monbot:
+       handler: echo
+       # requireAuth: true  (implicite — défaut sécurisé)
+   ```
 
-**Limite Phase 1** : tous les bots ont le handler `echo`. Pas encore de routage vers une logique métier différente par bot.
+   Pour un bot public (notifications status, etc.), opt-out explicite :
+
+   ```yaml
+   bots:
+     statusbot:
+       handler: echo
+       requireAuth: false
+   ```
+
+4. **Push + rollout** :
+
+   ```bash
+   cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
+   git add chart/values.yaml
+   git commit -m "bots: add $SLUG"
+   git push
+   kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
+   kubectl -n telegram-gateway rollout status  deploy/telegram-gateway
+   ```
+
+5. **Enregistrer le webhook côté Telegram** :
+
+   ```bash
+   export BOT_${ENV_SLUG}_TOKEN="$TOKEN"
+   export BOT_${ENV_SLUG}_SECRET="$SECRET"
+   make setwebhook SLUG="$SLUG" BASE_URL=https://tg.arcodange.fr
+   ```
+
+6. **Test** :
+   - Si `requireAuth` est laissé à true : envoie un message → réponse `🔒 /auth chez @arcodange_factory_bot` ; fais `/auth <code>` chez factory ; renvoie un message → echo en < 2 s.
+   - Si `requireAuth: false` : echo direct en < 2 s.
+
+**Limite Phase 1** : tous les bots ont le handler `echo` ou `auth`. Pas encore de routage vers une logique métier différente par bot — voir Cas 3.
 
 ---