flowdeck/docs/coffre-reference-flowdeck.md

# Flowdeck — Connecteurs à référence ObsiGate (Phase 4, issue ObsiGate #22)

## Principe

Un connecteur personnel d'un workspace peut pointer vers une référence
ObsiGate au lieu d'un jeton :

```
coffre:<slug>/<nom>          ex. coffre:flowdeck/gitea-lecture
```

* Le champ jeton du connecteur **devient** le champ référence : aucun
  jeton n'est stocké pour ce connecteur (`secret_encrypted` reste vide).
* L'octroi est **toujours lié à un `workspace_id`** : créer un connecteur
  à référence sans workspace est refusé (HTTP 400 / `ValueError`).
* À l'appel, le **serveur** Flowdeck appelle
  `POST /api/coffres/distribuer` d'ObsiGate avec le jeton consommateur
  Flowdeck et un contexte `flowdeck_workspace / <workspace_id>`, utilise
  la valeur **en mémoire**, puis l'oublie. La valeur n'est jamais
  persistée, jamais mise en cache, jamais journalisée, jamais renvoyée
  à une réponse API ni au LLM.

## Configuration (serveur Flowdeck)

| Variable | Défaut | Rôle |
| --- | --- | --- |
| `OBSIGATE_COFFRE_URL` | dérivée de `DRACO_SSO_URL` | Base ObsiGate pour `/api/coffres/distribuer` |
| `OBSIGATE_CONSUMER_TOKEN` | (vide = distribution désactivée) | Jeton **consommateur** Flowdeck enregistré dans ObsiGate |

Le jeton consommateur est distinct du jeton MCP de notes et de la
session SSO. Il ne figure dans aucun log, rapport ou réponse.

## Isolation workspace — ce qui est garanti, et sa limite honnête

**Garanti côté Flowdeck, avant tout appel** (`connectors.resolve_secret`) :

* un connecteur à référence ne se résout que pour son propre
  `workspace_id` ;
* workspace A tentant d'utiliser le connecteur (donc la référence /
  l'octroi) du workspace B reçoit un refus explicite
  (`CoffreWorkspaceMismatch` : « … ne peut pas utiliser ce connecteur
  (il appartient au workspace …) : octroi d'un autre workspace refusé »)
  et **le distributeur n'est pas appelé** ;
* un `workspace_id` déjà posé sur un connecteur est immuable : on ne
  transfère pas un octroi en éditant le connecteur ;
* un connecteur à référence testé/appelé sans `workspace_id` échoue
  proprement, jamais avec la valeur d'un autre workspace.

**Limite à connaître** : côté ObsiGate, l'octroi est accordé au
consommateur **Flowdeck** (un jeton par application), pas à un workspace
— le `contexte_id` transmis sert à la traçabilité, pas à un contrôle
d'accès côté ObsiGate. L'isolation par workspace repose donc sur le
contrôle Flowdeck ci-dessus. Une isolation appliquée côté ObsiGate
exigerait un consommateur par workspace : c'est un reste à faire
décidé côté ObsiGate (enregistrement de consommateurs par workspace),
pas un prérequis pour utiliser ce mécanisme.

## Échecs propres, sans repli

| Situation | Comportement Flowdeck |
| --- | --- |
| ObsiGate injoignable / timeout / HTTP 5xx | `CoffreIndisponible` — l'appel échoue, **aucune** valeur en cache n'est utilisée (il n'y en a pas) |
| Octroi révoqué / consommateur révoqué (403) | `CoffreAccesRefuse` — message « accès révoqué, à ré-accorder dans ObsiGate » |
| Octroi expiré (403) / secret expiré (410) | `CoffreAccesRefuse` avec le code ObsiGate, sans la valeur |
| Référence mal formée | `CoffreReferenceInvalide` (format `coffre:<slug>/<nom>`, slug 3–64, nom 3–128, minuscules, chiffres, `-`/`_`, aligné sur ObsiGate) |

## Secrets déjà chiffrés : pas de big-bang

Les connecteurs historiques (`secret_encrypted` Fernet) restent valides
tels quels. La migration est **opportuniste, connecteur par
connecteur** :

1. (optionnel) rattacher d'abord le connecteur à son workspace
   (`PATCH /api/agent/connectors/{id}` avec `workspace_id`) ;
2. puis basculer vers la référence (`PATCH …` avec
   `coffre_reference: "coffre:<slug>/<nom>"`) — le jeton local dormant
   n'est pas effacé automatiquement, il est simplement ignoré tant que
   la référence est posée ; effacer la référence (`""`) le réactive ;
3. vérifier par un probe avec `workspace_id`, puis supprimer le jeton
   local si besoin (rotation côté ObsiGate).

## Chemin de migration par connecteur

| Connecteur actuel | État dans cette branche | Chemin |
| --- | --- | --- |
| Personnels (`custom`, `discord`, `telegram`, `mcp`, `tiktak`, `obsigate`) | **Implémenté** : `workspace_id` + `coffre_reference`, résolution en mémoire, isolation testée | Basculer connecteur par connecteur (ci-dessus) |
| Natifs Gitea / GitHub | **Inchangés** : jetons globaux d'instance (`GITEA_TOKEN`, `GITHUB_TOKEN` en `.env`) | Créer un connecteur personnel workspace-scopé à référence vers le même service et l'utiliser à la place du natif, quand le besoin workspace par workspace se présente ; les natifs ne sont pas supprimés (pas de big-bang) |
| LLM global (`llm_config` id=1) et clés par utilisateur (`user_llm_keys`) | **Inchangés** : clés en clair en base (globale / par utilisateur, pas par workspace) | Travail ultérieur dédié : ajouter une colonne référence sur `user_llm_keys` + résolution par workspace, avec le même patron (distribution en mémoire, workspace obligatoire) ; hors périmètre de cette branche |
| OAuth Google / M365 (`connector_tokens`) | **Inchangés** : jetons OAuth chiffrés par (kind, utilisateur) | Hors périmètre : le flux OAuth ne se prête pas à une référence coffre sans repenser le refresh ; à traiter séparément si besoin |

## API

* `POST /api/agent/connectors` accepte `workspace_id` et
  `coffre_reference` (référence sans workspace → 400).
* `PATCH /api/agent/connectors/{id}` accepte `workspace_id`
  (premier rattachement seulement) et `coffre_reference` (`""` =
  effacer la référence).
* `POST /api/agent/connectors/probe` accepte `workspace_id`.
* Réponses : `workspace_id`, `coffre_reference`, `secret_source`
  (`coffre` | `chiffre_local` | `aucun`) — jamais de valeur.
* `GET /api/agent/connectors` liste les connecteurs avec ces champs.

## Ce qui reste à faire (validation réelle)

* Valider contre une vraie instance ObsiGate : créer le consommateur
  Flowdeck + les octrois, puis un probe réel avec `workspace_id`
  (les tests ici utilisent un faux endpoint de distribution).
* Threader `workspace_id` depuis l'agent : `AgentEngine.workspace_id`
  → `connector_fetch` (outil LLM) et `McpTool.call_tool` — aujourd'hui
  ces chemins appellent sans workspace et échouent proprement pour les
  connecteurs à référence (refus, pas de fuite) ; les connecteurs
  historiques ne sont pas affectés.
* Le cas échéant, consommateur ObsiGate par workspace (voir limite
  ci-dessus) et bascule des natifs Gitea/GitHub et des clés LLM
  (tableau ci-dessus).
* Interface : sélecteur de référence dans le formulaire connecteur
  (aujourd'hui, champ `coffre_reference` via l'API seulement).