# Scope B2 — Serveur d'autorisation OAuth 2.1 pour le connecteur MCP

**Issue :** #114 (« Permettre l'accès aux données colibre via ChatGPT et Claude.ai »),
2ᵉ partie de #111.
**Date :** 2026-07-13
**Statut :** design approuvé
**Prérequis :** scopes A et B livrés et fusionnés dans `dev` (serveur MCP `/_mcp`,
`src/mcp/`, garde jeton statique `src/mcp/auth.py`, page `/compte/mcp`).

## Objectif

Permettre aux clients grand public qui exigent OAuth — **Claude.ai, Claude Desktop,
Claude mobile, ChatGPT** — de se connecter au serveur MCP colibre sans copier-coller
de jeton, en faisant de colibre son **propre serveur d'autorisation OAuth 2.1**
conforme à la spec MCP (authorization, 2025-06-18 / 2025-11-25). L'accès reste
**conditionné à un abonnement colibre actif**, vérifié à chaque requête.

Le chemin « jeton statique » livré en scope B (clients CLI : Claude Code, Gemini,
Mistral) est **conservé sans régression**. Ce scope l'**ajoute** en parallèle.

## Décisions de conception (arbitrées)

1. **colibre = serveur d'autorisation ET resource server**, sur le même Flask
   (`app.server`) qui sert déjà `/_mcp`. L'étape de consentement réutilise la
   **session flask_login existante**.
2. **authlib** (déjà en dépendance pour LinkedIn) via son cœur OAuth 2.0
   (`authlib.oauth2.rfc6749/7591/7636/8414`), avec un **stockage SQLite maison**
   (`sqlite3` brut, comme `tokens_db.py` / `auth.db` / `subscriptions.db`). Pas de
   SQLAlchemy.
3. **Tokens d'accès opaques**, validés par lookup haché en base (colibre étant AS
   **et** RS sur le même hôte). Pas de JWT/JWKS/signature. L'audience (`resource`)
   est stockée sur la ligne du token.
4. **DCR (RFC 7591) comme baseline** d'enregistrement client. Claude et ChatGPT le
   supportent nativement et retombent dessus si CIMD n'est pas annoncé. Clients
   **publics** (`token_endpoint_auth_methods_supported: ["none"]` + PKCE S256).
5. **Gate abonnement bloquant tôt, à `/authorize`**, ET re-vérifié à chaque requête
   `/_mcp` et à chaque refresh (défense en profondeur — voir §« Abonnement »).
6. **Détection d'usage (niveau 1)** : table `mcp_usage` journalisant chaque requête
   `/_mcp` authentifiée. Pas de rate-limiting actif (hors-périmètre).
7. **Durées de vie** : access token **1 h**, refresh token **60 j**, **rotation du
   refresh** à chaque usage (exigence client public).

## Exigences externes vérifiées (2026-07)

Sources : spec MCP authorization (2025-06-18/2025-11-25), doc connecteurs Claude
(`claude.com/docs/connectors/building/authentication`), doc Apps SDK ChatGPT
(`developers.openai.com/apps-sdk/build/auth`).

Communes à Claude **et** ChatGPT :

- **Découverte** : PRM (RFC 9728) à `/.well-known/oauth-protected-resource`
  (+ variante suffixée `/_mcp`) ; AS metadata (RFC 8414) à
  `/.well-known/oauth-authorization-server` ; **`/.well-known/openid-configuration`**
  aussi (sondé par ChatGPT). Le champ `resource` de la PRM doit valoir **exactement**
  l'URL saisie par l'utilisateur (`https://colibre.fr/_mcp`) ; `authorization_servers`
  liste l'issuer, **1ʳᵉ entrée utilisée** (pas de fallback vers les suivantes).
- **401 + `WWW-Authenticate: Bearer …, resource_metadata="…"`** : c'est ce header
  qui déclenche le flux OAuth côté client. Le 401 (pas 200) est requis.
- **PKCE S256** obligatoire ; metadata doit annoncer
  `code_challenge_methods_supported: ["S256"]`.
- **Audience RFC 8707** : `resource` envoyé sur `/authorize` et `/token`, copié sur
  le token, validé à `/_mcp`.
- **`/token`** accepte `application/x-www-form-urlencoded`, renvoie des codes
  d'erreur **RFC 6749** (`invalid_grant`). `/register` en `application/json`.
- **Refresh** : Claude fait la **rotation** (client public) et n'ajoute
  `offline_access` que si annoncé dans `scopes_supported`. ChatGPT ne l'exige pas.
  → on supporte le refresh et on annonce `offline_access`.
- **Redirect URIs** validés en **exact-match** contre ceux fournis au DCR :
  Claude `https://claude.ai/api/mcp/auth_callback` ; ChatGPT
  `https://chatgpt.com/connector/oauth/{id}` (+ legacy
  `https://chatgpt.com/connector_platform_oauth_redirect`). Rien à coder en dur.
- **Consentement** : l'écran doit afficher le **hostname du redirect_uri** (risque
  d'usurpation loopback, spec 2025-11-25).
- **Latence** : discovery/registration/token < 10 s, refresh < 30 s (les opérations
  sqlite sont bien en-deçà).
- **Ops** : l'AS et `/_mcp` doivent rester joignables depuis l'egress Anthropic
  `160.79.104.0/21` sans WAF bloquant, en **HTTPS** (localhost toléré en dev).

## Architecture

### Coexistence des deux chemins d'auth sur `/_mcp`

| Chemin                                         | Clients                                   | Mécanisme                                                  |
| ---------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| Jeton statique `colibre_…` (scope B, inchangé) | Claude Code, Gemini, Mistral              | collé à la main depuis `/compte/mcp`                       |
| **OAuth 2.1 (ce scope B2)**                    | Claude.ai, Claude Desktop/mobile, ChatGPT | « Ajouter un connecteur » → flux OAuth, zéro copier-coller |

### Arborescence

```
src/mcp/oauth/
  __init__.py
  store.py       # stores sqlite bruts : clients (DCR), codes, tokens
  server.py      # authlib AuthorizationServer : AuthorizationCodeGrant+PKCE, RefreshTokenGrant, DCR
  metadata.py    # documents JSON RFC 9728 (protected-resource) + RFC 8414 (AS)
  consent.py     # écran de consentement + gate abonnement
  routes.py      # blueprint Flask : /.well-known/*, /oauth/register, /oauth/authorize, /oauth/token, /oauth/revoke
src/mcp/usage.py # journal d'usage /_mcp (niveau 1 détection)
```

Fichiers **modifiés** : `src/mcp/auth.py` (garde `/_mcp` accepte aussi les tokens
OAuth + en-tête `resource_metadata` + journal `mcp_usage`), `src/migrations.py`
(nouvelles tables), `src/pages/compte/mcp.py` (instructions Claude.ai / ChatGPT),
`src/app.py` (enregistrement blueprint + exemption CSRF).

### Isolation des unités

- `store.py` : accès sqlite pur (clients/codes/tokens), testable sans HTTP ni authlib.
- `server.py` : configuration authlib (grants, hooks `query_client`/`save_token`),
  branchée sur `store.py`.
- `metadata.py` : documents JSON purs (fonctions déterministes de `APP_BASE_URL`).
- `consent.py` : rendu de l'écran + gate abonnement, testable indépendamment.
- `usage.py` : journal `/_mcp`, testable isolément.

## Stockage — 3 tables OAuth + 1 table usage (`users.sqlite`)

Créées via `_MIGRATIONS` et initialisées au démarrage (`init_schema`, comme
`tokens_db`), **avant** `apply_pending()`. Tolérance _duplicate_ déjà gérée.

- **`oauth_clients`** — `client_id` (PK), `client_metadata` (JSON : `redirect_uris`,
  `client_name`, `token_endpoint_auth_method='none'`, `grant_types`, `scope`),
  `created_at`. Clients **publics**, créés par DCR.
- **`oauth_codes`** — `code_hash` (PK), `client_id`, `user_id`, `redirect_uri`,
  `code_challenge`, `code_challenge_method`, `scope`, `resource`, `expires_at`,
  `used`. Éphémère (~60 s).
- **`oauth_tokens`** — `access_token_hash`, `refresh_token_hash`, `client_id`,
  `user_id`, `scope`, `resource` (audience), `issued_at`, `access_expires_at`
  (+1 h), `refresh_expires_at` (+60 j), `revoked_at`. Rotation du refresh à chaque
  usage.
- **`mcp_usage`** — `id` (PK), `user_id`, `token_id`, `kind` (`'static'`|`'oauth'`),
  `created_at`. Une ligne par requête `/_mcp` **authentifiée** (niveau 1 détection).

Les jetons statiques restent dans `api_tokens` (inchangé).

## Endpoints, discovery & flux OAuth

Blueprint `src/mcp/oauth/routes.py` sur `app.server`, **exempté de CSRF** (comme
`/_mcp` ; POST externes sans jeton CSRF).

| Route                                                                           | Méthode     | Rôle                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/.well-known/oauth-protected-resource` + `…/oauth-protected-resource/_mcp`     | GET         | **PRM (RFC 9728)** : `{ resource:"<base>/_mcp", authorization_servers:[issuer], scopes_supported:["mcp","offline_access"] }`                                                                                                                                                                                           |
| `/.well-known/oauth-authorization-server` + `/.well-known/openid-configuration` | GET         | **AS metadata (RFC 8414)** : `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `code_challenge_methods_supported:["S256"]`, `token_endpoint_auth_methods_supported:["none"]`, `grant_types_supported:["authorization_code","refresh_token"]`, `scopes_supported:["mcp","offline_access"]`, `issuer` |
| `/oauth/register`                                                               | POST (JSON) | **DCR (RFC 7591)** : crée un `oauth_clients` public, renvoie `client_id` + metadata                                                                                                                                                                                                                                    |
| `/oauth/authorize`                                                              | GET / POST  | **Consentement** : login flask_login → gate abonnement → écran → code                                                                                                                                                                                                                                                  |
| `/oauth/token`                                                                  | POST (form) | grants `authorization_code` (+PKCE) et `refresh_token` (rotation)                                                                                                                                                                                                                                                      |
| `/oauth/revoke`                                                                 | POST (form) | **RFC 7009** (révocation ; peu coûteux)                                                                                                                                                                                                                                                                                |

### Flux `/authorize`

1. `server.get_consent_grant()` (authlib) valide `client_id`, `redirect_uri`
   (exact-match), `resource`, `code_challenge`.
2. `current_user` non authentifié → `redirect('/connexion?next=<authorize-url>')`,
   retour ici après login.
3. Connecté mais **pas d'abonnement actif** (`TOUS_ABONNES or has_active_subscription(user_id)` faux) → page HTML « Abonnement requis » + lien
   `/compte/abonnement`, **aucun code émis**.
4. Sinon → écran de consentement minimal : nom du client, **hostname du
   redirect_uri**, périmètre (« lire les données colibre en votre nom »),
   boutons Autoriser / Refuser.
5. **Autoriser** → `server.create_authorization_response(grant_user=current_user)` :
   `code_hash` stocké dans `oauth_codes` (avec `resource`, `code_challenge`),
   redirection vers le client.

### Flux `/token`

- `authorization_code` : authlib échange code + `code_verifier` (PKCE S256) →
  `oauth_tokens` (access 1 h, refresh 60 j, `resource` copié comme audience).
  Code invalide / `code_verifier` erroné → `invalid_grant`.
- `refresh_token` : **rotation** (ancien refresh révoqué, nouveau renvoyé dans la
  même réponse), et **re-vérification de l'abonnement** : si perdu → `invalid_grant`,
  ce qui force le client à relancer le flux complet (lequel rebute au gate
  `/authorize`).

## Garde `/_mcp` unifié (`src/mcp/auth.py`)

1. **401 enrichi** :
   `WWW-Authenticate: Bearer realm="colibre-mcp", resource_metadata="<base>/.well-known/oauth-protected-resource/_mcp"`.
2. **Routage du Bearer** :
   - préfixe `colibre_` → chemin statique existant (`api_tokens`, inchangé) ;
   - sinon → chemin OAuth (`oauth_tokens` : lookup haché, **non expiré**,
     **audience == `<base>/_mcp`**, non révoqué).
3. Convergence : `user_id` → abonnement actif → `increment_usage` →
   **`mcp_usage.record(user_id, token_id, kind)`** (best-effort) → laisser passer.
4. Échecs : token invalide / expiré / mauvaise audience / révoqué → **401** (avec
   le header) ; `user_id` nul ou abonnement inactif → **403**. Rien n'est journalisé
   dans `mcp_usage` sur échec.

## Abonnement : sémantique `TOUS_ABONNES` et « pas de droit acquis »

`TOUS_ABONNES` est lu au démarrage (constante d'`os.getenv`). L'abonnement est
**re-vérifié à chaque requête** `/_mcp`, pas seulement à l'émission du token :

| Moment                                       | Effet sur un token OAuth existant                                                                                                                                                            |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOUS_ABONNES=true`                          | Tout utilisateur connecté franchit `/authorize`, obtient un token ; chaque requête `/_mcp` passe.                                                                                            |
| `TOUS_ABONNES` → `false` (après redémarrage) | Token ni supprimé ni révoqué, mais à la requête suivante le garde ré-évalue `False or has_active_subscription(user_id)`. Sans abonnement actif → **403** immédiat ; le token devient inerte. |
| L'utilisateur s'abonne ensuite               | Le **même** token refonctionne (garde de nouveau vrai), sans re-login.                                                                                                                       |

Il n'existe **aucune fenêtre de tolérance** : le check étant par requête, même un
token émis juste avant le basculement est bloqué dès l'appel suivant. Cohérent avec
le refresh (`invalid_grant` si abonnement perdu).

## Détection d'usage — niveau 1 (`src/mcp/usage.py`)

Objectif : rendre l'usage `/_mcp` **interrogeable** (socle d'un futur quota /
rate-limiting), sans encore plafonner.

- **`record(db_path, user_id, token_id, kind)`** : insère `(user_id, token_id, kind, created_at)` dans `mcp_usage`. Appelé par le garde après un succès. **Best-effort**
  (jamais bloquant).
- **`count_since(db_path, user_id, iso_ts) -> int`** : nombre de requêtes d'un
  utilisateur depuis un horodatage (base d'un futur seuil/minute).
- **`purge_older_than(db_path, days=90)`** : suppression des lignes anciennes,
  appelée **au démarrage** (mirror de `db.purge_expired_tokens()`), pour borner la
  croissance.

Signaux de détection disponibles **au total** après ce scope :

- **Matomo** (déjà câblé, scope A) : volume par tool dans le temps (anonyme).
- **Compteurs par token** : `count_total` / `last_used_at` (`api_tokens` +
  `oauth_tokens`), cumulatifs.
- **`mcp_usage`** : journal par requête, fenêtrable par utilisateur.
- **Logs d'accès** gunicorn/nginx : brut, par IP.

## UI `/compte/mcp` (`src/pages/compte/mcp.py`)

La page conserve son générateur de jetons statiques ; l'accordéon `client_instructions`
évolue :

- **Claude Code / Gemini / Mistral** : inchangés (jeton statique collé).
- **Claude.ai / Desktop / mobile** : nouvelle entrée « Aucun jeton à copier » →
  _Paramètres → Connecteurs → Ajouter un connecteur personnalisé → URL
  `https://colibre.fr/_mcp` → se connecter avec colibre → Autoriser_. Champ
  « Client Secret » laissé vide (client public).
- **ChatGPT** : remplace le texte « votez pour la fonctionnalité » par les étapes
  réelles (connecteurs → ajouter par URL `https://colibre.fr/_mcp` → flux OAuth) ;
  note que la disponibilité dépend du plan ChatGPT de l'utilisateur.
- Court paragraphe expliquant : **jeton = clients CLI**, **OAuth = apps grand
  public**, même abonnement requis.

Les tokens OAuth (éphémères, gérés par le client) ne sont **pas** listés dans le
tableau, qui reste réservé aux jetons statiques.

## Activation & configuration

- Toujours piloté par **`DASH_MCP_ENABLED=true`** (le flux OAuth ne s'enregistre que
  dans ce bloc de `app.py`, après `configure_mcp_server`).
- **`APP_BASE_URL`** sert d'**issuer** et à construire `resource` / URLs well-known.
  **HTTPS obligatoire** hors dev (exigence spec) ; localhost toléré en dev.
- **Aucun nouveau secret** (tokens opaques hachés ; `SECRET_KEY` déjà présent).
- `.template.env` : documenter que le flux OAuth requiert `APP_BASE_URL` en HTTPS et
  que l'egress Anthropic `160.79.104.0/21` doit être joignable.
- Déploiement recommandé : activer d'abord sur `test.colibre.fr` (branche `dev`),
  valider un connecteur Claude.ai réel, puis `main`.

## Stratégie de test

- **`tests/mcp/test_oauth_metadata.py`** : PRM (`resource` exact, `authorization_servers`,
  `scopes_supported` inclut `offline_access`) ; AS metadata
  (`code_challenge_methods_supported:["S256"]`, `none`, `registration_endpoint`,
  grants) ; `/.well-known/openid-configuration` = miroir ; variantes suffixées `/_mcp`.
- **`tests/mcp/test_oauth_store.py`** : CRUD clients/codes/tokens, hachage,
  expiration, rotation refresh, révocation.
- **`tests/mcp/test_oauth_flow.py`** : DCR → client public ; `/authorize`
  (non connecté → redirection ; connecté sans abonnement → « Abonnement requis »,
  **aucun code** ; avec abonnement → code) ; `/token` avec PKCE S256 (mauvais
  `code_verifier` → `invalid_grant`) ; `resource`/audience copiée ; redirect_uri
  non enregistrée → rejet.
- **`tests/mcp/test_auth.py`** (étendre) : garde accepte un token OAuth valide ;
  rejette expiré / mauvaise audience / révoqué (**401 + `resource_metadata`**) ;
  **`TOUS_ABONNES=false` + pas d'abonnement → 403 même avec token OAuth valide** ;
  refresh refusé (`invalid_grant`) si abonnement perdu.
- **`tests/mcp/test_usage.py`** (nouveau) : `record` insère sur succès ; **aucune
  insertion sur 401/403** ; fenêtrage de `count_since` ; `purge_older_than`.
- **Migration** : `apply_pending()` idempotente (DB existante → ajoute les tables ;
  DB fraîche → tolère _duplicate_).

## Hors-périmètre (YAGNI → itérations futures)

- **CIMD** (Client ID Metadata Document, spec MCP 2025-11-25) et redirect loopback
  port-agnostic (Claude Code passe déjà par jeton statique).
- `oauth_anthropic_creds`, `private_key_jwt`, mTLS, `id_token_hint`, tokens JWT/JWKS.
- **Rate-limiting / quotas / 429 / alerting** (niveaux 2-3) : `mcp_usage` en pose le
  socle, le plafonnement effectif fera l'objet d'une issue dédiée.
- Scopes fins par tool ; écran de gestion/révocation des connexions OAuth actives
  côté utilisateur.
- Soumission au directory de connecteurs Claude / ChatGPT.