Module ThaliaBridge

Le module ThaliaBridge fournit des connecteurs read-only entre l'agent IA Thalia et les outils externes de l'intranet.

Règle absolue : ThaliaBridge ne fait jamais de POST/PUT/PATCH/DELETE sur les APIs externes.

Périmètre

Service	Statut	Opérations autorisées
BookStack	✅ Actif (Phase 4)	search, list books, list pages, get page
GitLab	⏳ Phase 5	—
Nextcloud	⏳ Phase 5	—
Passbolt	🚫 Jamais	Aucun accès (mots de passe)

Architecture

Modules/ThaliaBridge/
├── app/
│   ├── DTO/BookStack/
│   │   ├── BookStackBookDTO.php
│   │   ├── BookStackPageDTO.php
│   │   └── BookStackSearchResultDTO.php
│   ├── Exceptions/
│   │   └── BridgeConnectionException.php
│   ├── Providers/
│   │   └── ThaliaBridgeServiceProvider.php
│   └── Services/BookStack/
│       ├── BookStackClient.php   ← HTTP client (Http facade)
│       └── BookStackService.php  ← façade read-only
├── config/
│   └── thaliabridge.php
└── module.json

Les données API brutes passent toujours par les DTOs avant d'atteindre les contrôleurs.

Configuration .env

BOOKSTACK_BASE_URL=https://wiki.example.com
BOOKSTACK_TOKEN_ID=your_token_id
BOOKSTACK_TOKEN_SECRET=your_token_secret
BOOKSTACK_TIMEOUT=10

Les tokens BookStack ne doivent jamais apparaître dans les logs — ThaliaAuditService::sanitizeParams() filtre automatiquement les champs token, secret, key.

Endpoints API v2

Tous les endpoints bridge nécessitent :

1. Un Bearer token valide (middleware api.key)
2. Le scope bridge.read (middleware api.scope:bridge.read via ThaliaPermissionService)

Méthode	Route	Description
GET	/api/v2/bridge/bookstack/search?q=...&limit=10	Recherche full-text
GET	/api/v2/bridge/bookstack/books	Liste des livres
GET	/api/v2/bridge/bookstack/books/{id}	Détail d'un livre
GET	/api/v2/bridge/bookstack/books/{id}/pages	Pages d'un livre
GET	/api/v2/bridge/bookstack/pages/{id}	Contenu d'une page

Le manifeste v2 complet est disponible sur GET /api/v2/tools.json (public, sans authentification).

Codes d'erreur

Code HTTP	Cause
400	Paramètre manquant (ex: q absent)
401	Token BookStack invalide
403	Scope bridge.read non accordé
404	Ressource introuvable
502	Erreur de communication avec BookStack
503	Module non configuré (variables d'env manquantes)

Initialisation des permissions

php artisan db:seed --class="Modules\Thalia\Database\Seeders\ThaliaToolPermissionSeeder"