Écrire un connecteur externe

Un connecteur branche un service externe (Notion, Zapier, etc.) à un projet arka-deck via le module connectors-core. Il enregistre les actions disponibles, gère les credentials/OAuth, et expose un journal d’exécution.

Différence avec un addon classique

Aspect	Addon	Connecteur
Couplage core	Consomme des ports core	Consomme `ConnectorRegistry` + `for-connectors`
Surface UI	Vue dédiée, panneau chat, etc.	Vue de configuration + audit-log
Authentification	Local-only	OAuth ou token externe
Données	Locales	Référence externe + cache

L’addon notion-connect est l’implémentation de référence à étudier.

Structure type

addons/<connector>/
├── manifest.json
└── src/
    ├── index.ts              # register + re-exports
    ├── manifest.ts           # ConnectorManifest TS, re-exporté par index
    ├── adapters/             # client HTTP, OAuth
    ├── actions/              # une action = une opération externe
    └── use-cases/

Étapes

Déclarer le ConnectorManifest dans src/manifest.ts (slug, label, actions, OAuth scopes, etc.).
Implémenter les actions : chacune définit son schéma d’entrée/sortie et son handler.
Gérer l’authentification : OAuth state en mémoire avec TTL court, ou token statique chiffré.
Enregistrer auprès du ConnectorRegistry dans la composition root.
Tests : actions individuelles (Zod schemas), flux OAuth (mock state), audit-log.

Sécurité

Secrets (tokens, credentials) chiffrés via le port SecretCipher (AES-256-GCM, cf. ADR 0005).
OAuth state éphémère (TTL court, à usage unique).
Le connecteur n’importe jamais tout le workspace cible : il stocke uniquement des références et les exécutions explicites.

Ressources

Référence existante : notion-connect
Contrat addon (partage des fondations) : contrat-addon
Politique secrets : ADR 0005
Politique anti-SSRF : ADR 0006

État de la documentation

Cette page est un stub. Le tutoriel complet (squelette de connecteur, schémas Zod, audit-log, gestion erreurs) sera rédigé au lot P4 à partir du code de addons/notion-connect/.