diff --git a/AGENTS.md b/AGENTS.md index 3cd6c00..559e206 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,7 @@ bash scripts/run-e2e-local.sh -g "nom du test" # filtre / --headed | Travail à venir + index | `docs/ROADMAP.md` | | Historique des versions | `CHANGELOG.md` | | Conception par feature | `docs/features/.md` | +| Guides d'utilisation | `docs/GUIDES/` | | Archive du complété | `docs/archive/COMPLETED_v1-v2.md` | | Bugs / TODO | `docs/ISSUES_TODOLIST.md` | | Build & releases | `docs/DEVELOPMENT_AND_RELEASES.md` | diff --git a/CHANGELOG.md b/CHANGELOG.md index d549356..851b93d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ Format basé sur [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/), et [Semantic Versioning](https://semver.org/spec/v2.0.0.html). > **En cours de développement** : les changements à venir sont listés dans la section -> [Unreleased](#unreleased). La dernière version livrée est **2.16.5**. +> [Unreleased](#unreleased). La dernière version livrée est **2.16.6**. --- @@ -14,6 +14,27 @@ et [Semantic Versioning](https://semver.org/spec/v2.0.0.html). --- +## [2.16.6] — 2026-09-22 + +### Ajouté + +- **Guides d'utilisation `docs/GUIDES/`** : nouvel index + 10 guides FR + (prise en main, recherche/PDF/Excalidraw, assistant IA & Forge, + collaboration temps réel, PWA & hors-ligne, API REST, serveur MCP, + authentification & sécurité, déploiement Docker, desktop Tauri). Le guide MCP + est déplacé dans `docs/GUIDES/MCP.md` ; `docs/MCP_GUIDE.md` devient une page + de redirection. + +### Modifié + +- **README.md / README.fr.md** : capture d'écran réelle de l'application en tête + (remplace l'illustration ASCII) ; un emoji sur chaque entrée de la table des + matières ; nouvelle section « Guides » avec liens vers `docs/GUIDES/` ; + renvois vers les guides depuis les sections API, Recherche, Sécurité, Desktop + et Collaboration. + +--- + ## [2.16.5] — 2026-09-22 ### Corrigé diff --git a/README.fr.md b/README.fr.md index 32034a9..577bf5d 100644 --- a/README.fr.md +++ b/README.fr.md @@ -1,61 +1,75 @@ # ObsiGate -> **Version française** — ce document est le miroir synchronisé de [README.md](README.md) (référence complète). Dernière synchronisation : juin 2026. +> **Version française** — ce document est le miroir synchronisé de [README.md](README.md) (référence complète). Dernière synchronisation : septembre 2026. **Porte d'entrée web ultra-léger pour vos vaults Obsidian** — Accédez, naviguez et recherchez dans toutes vos notes Obsidian depuis n'importe quel appareil via une interface web moderne et responsive. -[![Version](https://img.shields.io/badge/Version-2.16.5-blue.svg)]() +[![Version](https://img.shields.io/badge/Version-2.16.6-blue.svg)]() [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/) [![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://www.python.org/) [![CI/CD](https://img.shields.io/badge/CI%2FCD-Gitea_Actions-green.svg)](https://git.dracodev.net/Projets/ObsiGate/actions) -``` -┌─────────────────────────────────────────────────────────┐ -│ [🔍 Recherche...] [☀/🌙 Thème] ObsiGate │ -├──────────────┬──────────────────────────────────────────┤ -│ SIDEBAR │ CONTENT AREA │ -│ ▼ Recettes │ 📄 Titre du fichier │ -│ 📁 Soupes │ Tags: #recette #rapide │ -│ 📄 Pizza │ [Contenu Markdown rendu] │ -│ ▼ IT │ │ -│ 📁 Docker │ │ -│ Tags Cloud │ │ -└──────────────┴──────────────────────────────────────────┘ -``` +![Interface ObsiGate — tableau de bord Statistiques avec vaults, tags et raccourcis clavier](docs/images/obsigate-home.png) + +> Interface web d'ObsiGate : sidebar multi-vault, recherche globale, statistiques et raccourcis. + +--- + +## 📚 Guides + +Les **guides d'utilisation** pas à pas se trouvent dans [`docs/GUIDES/`](docs/GUIDES/) : + +| Guide | Contenu | +|---|---| +| 🚀 [Prise en main](docs/GUIDES/PRISE_EN_MAIN.md) | Premier lancement, interface, navigation, vaults, raccourcis | +| 🔍 [Recherche, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) | Syntaxe de requête, recherche sémantique, lecteur PDF, diagrammes | +| 🤖 [Assistant IA & Forge](docs/GUIDES/ASSISTANT_IA_FORGE.md) | Fournisseurs, éditeur IA, BooksLM, Forge, commandes `@` / `/` | +| 📝 [Édition & collaboration](docs/GUIDES/COLLABORATION.md) | Édition simultanée, curseurs distants, persistance | +| 📱 [PWA & hors-ligne](docs/GUIDES/PWA_HORS_LIGNE.md) | Installation, cache hors-ligne, file de synchro, notifications | +| 🔌 [API REST](docs/GUIDES/API_REST.md) | Authentification, clés API, endpoints, exemples `curl`, SSE | +| 🧩 [Serveur MCP](docs/GUIDES/MCP.md) | Brancher Claude Desktop, Cursor, Cline… sur vos vaults | +| 🔒 [Authentification & sécurité](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) | Utilisateurs, MFA, permissions par vault, durcissement | +| 🐳 [Déploiement Docker](docs/GUIDES/DEPLOIEMENT_DOCKER.md) | `docker-compose`, volumes, reverse proxy, mises à jour | +| 🖥️ [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) | Installation, premier lancement, build depuis les sources, dépannage | + +> Index complet : [`docs/GUIDES/README.md`](docs/GUIDES/README.md). --- ## 📋 Table des matières -- [Fonctionnalités](#fonctionnalites) -- [Prérequis](#prerequis) -- [Installation rapide](#installation-rapide) -- [Configuration détaillée](#configuration-detaillee) -- [Variables d'environnement](#variables-denvironnement) -- [🔒 Authentification](#authentification) -- [Ajouter une nouvelle vault](#ajouter-une-nouvelle-vault) -- [Build & déploiement avec build.sh](#build-deploiement-avec-buildsh) -- [Rendu d'images Obsidian](#rendu-dimages-obsidian) -- [Desktop (Tauri) — Application native](#desktop-tauri-application-native) -- [Utilisation](#utilisation) -- [API](#api) -- [Recherche avancée](#recherche-avancee) -- [Dépannage](#depannage) -- [Performance](#performance) -- [Sécurité](#securite) -- [Stack technique](#stack-technique) -- [Architecture](#architecture) -- [Développement](#developpement) -- [Licence](#licence) -- [Changelog](#changelog) +- ✨ [Fonctionnalités](#fonctionnalites) +- 📚 [Guides](#guides) +- 🚀 [Prérequis](#prerequis) +- ⚡ [Installation rapide](#installation-rapide) +- ⚙️ [Configuration détaillée](#configuration-detaillee) +- 🌍 [Variables d'environnement](#variables-denvironnement) +- 🔒 [Authentification](#authentification) +- ➕ [Ajouter une nouvelle vault](#ajouter-une-nouvelle-vault) +- 🔨 [Build & déploiement avec build.sh](#build-deploiement-avec-buildsh) +- 🖼️ [Rendu d'images Obsidian](#rendu-dimages-obsidian) +- 🖥️ [Desktop (Tauri) — Application native](#desktop-tauri-application-native) +- 📖 [Utilisation](#utilisation) +- 👥 [Collaboration temps réel](#collaboration-temps-reel) +- 🔌 [API](#api) +- 🔍 [Recherche avancée](#recherche-avancee) +- 🔧 [Dépannage](#depannage) +- ⚡ [Performance](#performance) +- 🛡️ [Sécurité](#securite) +- 🏗️ [Stack technique](#stack-technique) +- 🏠 [Architecture](#architecture) +- 📝 [Développement](#developpement) +- 📄 [Licence](#licence) +- 🤝 [Support](#support) +- 📝 [Changelog](#changelog) --- ## ✨ Fonctionnalités - **🤖 AI Editor intégré** — Éditeur CodeMirror 6 avec toolbar IA : amélioration, correction, traduction, génération, réécriture personnalisée, toolbox (liste, tableau, frontmatter, canvas) — multi-provider DeepSeek/OpenRouter/Gemini -- **🧩 Serveur MCP & agent IA** — Serveur Model Context Protocol intégré (`/mcp`) et assistant avec function calling : lisez, cherchez et modifiez vos vaults depuis Claude Desktop, Cursor… avec confirmations two-step, permissions par vault, rate limiting et redaction des secrets ([guide](docs/MCP_GUIDE.md)) +- **🧩 Serveur MCP & agent IA** — Serveur Model Context Protocol intégré (`/mcp`) et assistant avec function calling : lisez, cherchez et modifiez vos vaults depuis Claude Desktop, Cursor… avec confirmations two-step, permissions par vault, rate limiting et redaction des secrets ([guide](docs/GUIDES/MCP.md)) - **👥 Collaboration temps réel** — Édition simultanée d'un même document (Yjs/CRDT) : curseurs distants colorés, indicateur de présence, fusion sans conflit, reconnexion automatique et persistance serveur ([détail](docs/features/collaboration.md)) - **📖 Guide d'utilisation intégré** — Aide complète en FR/EN accessible depuis le menu Options : interface, navigation, recherche, fichiers, IA, sécurité, API & intégrations (OpenAPI, MCP), hors-ligne, collaboration, desktop, plus une section **Architecture** avec diagramme Mermaid ; téléchargeable en **Markdown** et **PDF** dans la langue courante ([détail](docs/features/guide-coverage-105.md)) - **📱 Éditeur mobile natif** — Édition optimisée pour le tactile : barre d'outils Markdown flottante (gras/italique/code/liste/lien), bouton « Coller » persistant (contournement iOS), zoom par pincement et hauteur ajustable, raccourcis swipe (liens entrants / table des matières) et mode lecture plein écran avec navigation entre fichiers ([détail](docs/features/mobile-editor.md)) @@ -412,6 +426,8 @@ curl -X POST http://localhost:2020/api/attachments/rescan/MonVault ## 🖥️ Desktop (Tauri) — Application native +> 📖 Guide complet : [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) + ObsiGate Desktop est une application native construite avec [Tauri](https://tauri.app/) (Rust + webview système). Elle embarque le backend Python et le frontend dans un exécutable standalone — zéro Docker, zéro ligne de commande. > 🚧 **Version 2.0.0 — binaires en cours de stabilisation.** Pour l'instant, le build depuis les sources est recommandé. @@ -571,6 +587,8 @@ Cycle de vie : Tauri spawn le backend Python → health check → splash de dém ## 👥 Collaboration temps réel +> 📖 Guide complet : [Édition & collaboration](docs/GUIDES/COLLABORATION.md) + Plusieurs utilisateurs peuvent éditer le même document markdown simultanément (façon Google Docs) : - **Fusion sans conflit** grâce à Yjs (CRDT) : deux personnes peuvent taper au même endroit, aucune @@ -590,6 +608,8 @@ fenêtres) pour voir la collaboration en action. ## 🔌 API +> 📖 Guide complet : [API REST](docs/GUIDES/API_REST.md) · [Serveur MCP](docs/GUIDES/MCP.md) + ObsiGate expose une API REST complète : | Endpoint | Description | Méthode | Auth | @@ -637,6 +657,8 @@ curl "http://localhost:2020/api/file/Recettes?path=pizza.md" ## 🔍 Recherche avancée +> 📖 Guide complet : [Recherche, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) + ### Syntaxe de requête | Opérateur | Description | Exemple | @@ -758,6 +780,8 @@ Configurables via l'interface (Settings) ou l'API `/api/config`. ## 🛡️ Sécurité +> 📖 Guide complet : [Authentification & sécurité](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) + - **Path traversal** : tous les endpoints fichier valident que le chemin résolu reste dans la vault - **Rate limiting** : 10 tentatives de login max par IP sur 15 minutes + lockout par compte (5 tentatives) - **Audit log** : écritures/suppressions/config journalisées dans `data/audit.log` (JSON lines, rotation 10 MB) @@ -927,8 +951,8 @@ Ce projet est sous licence **MIT** — voir le fichier [LICENSE](LICENSE) pour l ## 📝 Changelog -Consultez le [CHANGELOG.md](./CHANGELOG.md) pour l'historique complet de toutes les versions (v1.0.0 → v2.16.5). +Consultez le [CHANGELOG.md](./CHANGELOG.md) pour l'historique complet de toutes les versions (v1.0.0 → v2.16.6). --- -*Projet : ObsiGate | Version : 2.16.5 | Dernière mise à jour : Juin 2026* +*Projet : ObsiGate | Version : 2.16.6 | Dernière mise à jour : Septembre 2026* diff --git a/README.md b/README.md index cde5eeb..af62fae 100644 --- a/README.md +++ b/README.md @@ -2,53 +2,73 @@ **Ultra-light web gateway for your Obsidian vaults** — Access, browse, and search all your Obsidian notes from any device via a modern, responsive web interface. -[![Version](https://img.shields.io/badge/Version-2.16.5-blue.svg)]() +[![Version](https://img.shields.io/badge/Version-2.16.6-blue.svg)]() [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/) [![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://www.python.org/) [![CI/CD](https://img.shields.io/badge/CI%2FCD-Gitea_Actions-green.svg)](https://git.dracodev.net/Projets/ObsiGate/actions) -``` -┌─────────────────────────────────────────────────────────┐ -│ [🔍 Search...] [☀/🌙 Theme] ObsiGate │ -├──────────────┬──────────────────────────────────────────┤ -│ SIDEBAR │ CONTENT AREA │ -│ ▼ Recipes │ 📄 File Title │ -│ 📁 Soups │ Tags: #recipe #quick │ -│ 📄 Pizza │ [Rendered Markdown Content] │ -│ ▼ IT │ │ -│ 📁 Docker │ │ -│ Tags Cloud │ │ -└──────────────┴──────────────────────────────────────────┘ -``` +![ObsiGate interface — statistics dashboard with vaults, tags and keyboard shortcuts](docs/images/obsigate-home.png) + +> ObsiGate web interface: multi-vault sidebar, global search, dashboard stats and shortcuts. + +--- + +## 📚 Guides + +Step-by-step **user guides** live in [`docs/GUIDES/`](docs/GUIDES/): + +| Guide | What it covers | +|---|---| +| 🚀 [Getting Started](docs/GUIDES/PRISE_EN_MAIN.md) | First run, interface, navigation, vaults, shortcuts | +| 🔍 [Search, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) | Query syntax, semantic search, PDF viewer, diagrams | +| 🤖 [AI Assistant & Forge](docs/GUIDES/ASSISTANT_IA_FORGE.md) | Providers, AI editor, BooksLM, Forge, `@` / `/` commands | +| 📝 [Editing & Collaboration](docs/GUIDES/COLLABORATION.md) | Simultaneous editing, remote cursors, persistence | +| 📱 [PWA & Offline](docs/GUIDES/PWA_HORS_LIGNE.md) | Install as an app, offline cache, sync queue, push | +| 🔌 [REST API](docs/GUIDES/API_REST.md) | Authentication, API keys, endpoints, `curl` examples, SSE | +| 🧩 [MCP Server](docs/GUIDES/MCP.md) | Connect Claude Desktop, Cursor, Cline… to your vaults | +| 🔒 [Auth & Security](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) | Users, MFA, per-vault permissions, hardening | +| 🐳 [Docker Deployment](docs/GUIDES/DEPLOIEMENT_DOCKER.md) | `docker-compose`, volumes, reverse proxy, updates | +| 🖥️ [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) | Install, first run, build from source, troubleshooting | + +> All guides are currently written in **French**. See the full index: +> [`docs/GUIDES/README.md`](docs/GUIDES/README.md). --- ## 📋 Table of Contents -- [Features](#features) -- [Architecture](#architecture) -- [Prerequisites](#prerequisites) -- [Quick Installation](#quick-installation) -- [Detailed Configuration](#detailed-configuration) -- [Environment Variables](#environment-variables) -- [🔒 Authentication](#authentication) -- [Adding a New Vault](#adding-a-new-vault) -- [Build & Deployment with build.sh](#build--deployment-with-buildsh) -- [Desktop (Tauri) — Native Application](#desktop-tauri--native-application) -- [Usage](#usage) -- [API](#api) -- [Performance](#performance) -- [Troubleshooting](#troubleshooting) -- [Tech Stack](#tech-stack) -- [Changelog](#changelog) +- ✨ [Features](#features) +- 📚 [Guides](#guides) +- 🚀 [Prerequisites](#prerequisites) +- ⚡ [Quick Installation](#quick-installation) +- ⚙️ [Detailed Configuration](#detailed-configuration) +- 🌍 [Environment Variables](#environment-variables) +- 🔒 [Authentication](#authentication) +- ➕ [Adding a New Vault](#adding-a-new-vault) +- 🔨 [Build & Deployment with build.sh](#build--deployment-with-buildsh) +- 🖼️ [Obsidian Image Rendering](#obsidian-image-rendering) +- 🖥️ [Desktop (Tauri) — Native Application](#desktop-tauri--native-application) +- 📖 [Usage](#usage) +- 👥 [Real-time Collaboration](#real-time-collaboration) +- 🔌 [API](#api) +- 🔍 [Advanced Search](#advanced-search) +- 🛡️ [Security](#security) +- ⚡ [Performance](#performance) +- 🔧 [Troubleshooting](#troubleshooting) +- 🏗️ [Tech Stack](#tech-stack) +- 🏠 [Architecture](#architecture) +- 📝 [Development](#development) +- 📄 [License](#license) +- 🤝 [Support](#support) +- 📝 [Changelog](#changelog) --- ## ✨ Features - **🤖 Integrated AI Editor** — CodeMirror 6 editor with AI toolbar: improve, correct, translate, generate, custom rewrite, toolbox (list, table, frontmatter, canvas) — multi-provider DeepSeek/OpenRouter/Gemini -- **🧩 MCP Server & AI Agent** — Built-in Model Context Protocol server (`/mcp`) and tool-calling assistant: read, search and edit your vaults from Claude Desktop, Cursor… with two-step confirmations, per-vault permissions, rate limiting and secret redaction ([guide](docs/MCP_GUIDE.md)) +- **🧩 MCP Server & AI Agent** — Built-in Model Context Protocol server (`/mcp`) and tool-calling assistant: read, search and edit your vaults from Claude Desktop, Cursor… with two-step confirmations, per-vault permissions, rate limiting and secret redaction ([guide](docs/GUIDES/MCP.md)) - **👥 Real-time Collaboration** — Simultaneous editing of the same document (Yjs/CRDT): colored remote cursors, presence indicator, conflict-free merge, automatic reconnection and server-side persistence ([details](docs/features/collaboration.md)) - **📖 Built-in User Guide** — Complete FR/EN help from the Options menu: interface, navigation, search, files, AI, security, API & integrations (OpenAPI, MCP), offline, collaboration, desktop, plus an **Architecture** section with a Mermaid diagram; downloadable as **Markdown** and **PDF** in the current language ([details](docs/features/guide-coverage-105.md)) - **📱 Native Mobile Editor** — Touch-optimised editing: floating Markdown toolbar (bold/italic/code/list/link), persistent Paste button (iOS workaround), pinch-zoom font & adjustable height, swipe shortcuts (backlinks / table of contents) and a full-screen reading mode with page navigation ([details](docs/features/mobile-editor.md)) @@ -520,6 +540,8 @@ curl -X POST http://localhost:2020/api/attachments/rescan/MyVault ## 🖥️ Desktop (Tauri) — Native Application +> 📖 Full guide: [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) + ObsiGate Desktop is a native application built with [Tauri](https://tauri.app/) (Rust + system webview). It embeds the Python backend and frontend in a standalone executable — zero Docker, zero command line. > 🚧 **Version 2.0.0 — binaries are being stabilized.** For now, building from source is recommended. @@ -687,6 +709,8 @@ Lifecycle: Tauri spawns the Python backend → health check → opens the webvie ## 👥 Real-time Collaboration +> 📖 Full guide: [Editing & Collaboration](docs/GUIDES/COLLABORATION.md) + Multiple users can edit the same markdown document simultaneously (Google Docs style): - **Conflict-free merge** via Yjs (CRDT): two people can type in the same place, no change is lost. @@ -703,6 +727,8 @@ No configuration is required: open the same file in two browsers (or two windows ## 🔌 API +> 📖 Full guide: [REST API](docs/GUIDES/API_REST.md) · [MCP Server](docs/GUIDES/MCP.md) + ObsiGate exposes a complete REST API : | Endpoint | Description | Method | Auth | @@ -763,6 +789,8 @@ curl "http://localhost:2020/api/file/Recipes?path=pizza.md" ## 🔍 Advanced Search +> 📖 Full guide: [Search, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) + ### Query Syntax | Operator | Description | Example | @@ -915,6 +943,8 @@ These parameters are configurable via the interface (Settings) or the `/api/conf ## 🛡️ Security +> 📖 Full guide: [Auth & Security](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) + - **Path traversal** : All file endpoints validate that the resolved path stays within the vault - **Rate limiting** : 10 login attempts max per IP over 15 minutes + per-account lockout (5 attempts) - **Audit log** : All writes, deletions, and config changes are logged in `data/audit.log` (JSON lines, 10 MB rotation) @@ -1070,7 +1100,9 @@ ObsiGate/ ├── Dockerfile # Multi-stage, healthcheck, non-root ├── docker-compose.yml # Deployment with healthcheck and auth env vars ├── build.sh # Automated build & deployment (docker compose build + up) -└── docs/CONTRIBUTING.md # Contribution guide +└── docs/ + ├── GUIDES/ # User guides (getting started, API, MCP, desktop…) + └── CONTRIBUTING.md # Contribution guide ``` ### Contributing @@ -1096,8 +1128,8 @@ This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) ## 📝 Changelog -See [CHANGELOG.md](./CHANGELOG.md) for the complete version history (v1.0.0 → v2.16.5). +See [CHANGELOG.md](./CHANGELOG.md) for the complete version history (v1.0.0 → v2.16.6). --- -*Project: ObsiGate | Version: 2.16.5 | Last updated: May 2026* +*Project: ObsiGate | Version: 2.16.6 | Last updated: September 2026* diff --git a/VERSION b/VERSION index ffa5fee..3c5d010 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.16.5 +2.16.6 diff --git a/desktop/Cargo.lock b/desktop/Cargo.lock index 6db9bf0..bd4e201 100644 --- a/desktop/Cargo.lock +++ b/desktop/Cargo.lock @@ -2626,7 +2626,7 @@ dependencies = [ [[package]] name = "obsigate-desktop" -version = "2.16.5" +version = "2.16.6" dependencies = [ "chrono", "env_logger", diff --git a/desktop/Cargo.toml b/desktop/Cargo.toml index a902024..1bb7f8f 100644 --- a/desktop/Cargo.toml +++ b/desktop/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "obsigate-desktop" -version = "2.16.5" +version = "2.16.6" description = "ObsiGate Desktop — Porte d'entrée native pour vos vaults Obsidian" authors = ["Bruno Charest"] edition = "2021" diff --git a/desktop/tauri.conf.json b/desktop/tauri.conf.json index be0eed7..5caef42 100644 --- a/desktop/tauri.conf.json +++ b/desktop/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://raw.githubusercontent.com/nicedoc/obsigate/main/desktop/tauri.conf.schema.json", "productName": "ObsiGate", - "version": "2.16.5", + "version": "2.16.6", "identifier": "com.obsigate.desktop", "build": { "frontendDist": "../frontend", diff --git a/docs/AI_ARCHITECTURE_GUIDE.md b/docs/AI_ARCHITECTURE_GUIDE.md index 98556c0..eec8cad 100644 --- a/docs/AI_ARCHITECTURE_GUIDE.md +++ b/docs/AI_ARCHITECTURE_GUIDE.md @@ -347,7 +347,7 @@ Pour répondre au besoin de cibler un fournisseur/modèle sans dépendre uniquem | **0 — Fondations** | `backend/tools/` (registry, context, service, audit) + extraction des services métier + tests unitaires | Couche d'outils testable sans IA | | **1 — Function calling in-app** | Abstraction tool-calling multi-provider, agent loop, confirmations UI, SSE réel, outils de navigation | Assistant qui lit/cherche/lit/ouvre/modifie avec confirmation | | **2 — Serveur MCP** | `backend/mcp/server.py` (tools + resources + prompts), **Streamable HTTP** (`/mcp`, auth JWT), confirmation two-step | ObsiGate accessible comme serveur MCP (local + distant, multi-utilisateur) | -| **3 — Durcissement** ✅ | Rate limiting (`backend/tools/ratelimit.py`), quotas `BOOKSLM_MAX_*`, redaction systématique des résultats (`backend/tools/redaction.py`), doc OpenAPI (tag/path MCP) + [guide MCP](./MCP_GUIDE.md), tests E2E | Observabilité et sécurité complètes | +| **3 — Durcissement** ✅ | Rate limiting (`backend/tools/ratelimit.py`), quotas `BOOKSLM_MAX_*`, redaction systématique des résultats (`backend/tools/redaction.py`), doc OpenAPI (tag/path MCP) + [guide MCP](./GUIDES/MCP.md), tests E2E | Observabilité et sécurité complètes | Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités. @@ -380,7 +380,7 @@ Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités. - `backend/mcp/confirmations.py` — jetons de confirmation signés (two-step, anti-rejeu) - `backend/tools/ratelimit.py` — rate limiting par jeton/outil (phase F) - `backend/tools/redaction.py` — redaction récursive des résultats d'outils (phase F) -- `docs/MCP_GUIDE.md` — guide d'installation et d'utilisation des clients MCP +- `docs/GUIDES/MCP.md` — guide d'installation et d'utilisation des clients MCP - `backend/bookslm.py`, `backend/bookslm_routes.py` — assistant contextuel (+ endpoint `/agent`) - `frontend/js/ai.js`, `frontend/js/bookslm.js` — UI IA - `backend/auth/middleware.py` — permissions diff --git a/docs/GUIDES/API_REST.md b/docs/GUIDES/API_REST.md new file mode 100644 index 0000000..88292da --- /dev/null +++ b/docs/GUIDES/API_REST.md @@ -0,0 +1,326 @@ +# 🔌 Guide de l'API REST + +ObsiGate expose une **API REST complète** couvrant toute l'application : +vaults, fichiers, recherche, sauvegardes, exports, IA, partage, webhooks et +administration. Ce guide explique l'authentification, la création de clés et +donne des exemples prêts à l'emploi. + +> **Public :** développeurs, intégrateurs, scripts d'automatisation +> **Doc interactive :** `/docs` (Swagger UI) · `/redoc` (ReDoc) · `/openapi.json` +> **Voir aussi :** [Serveur MCP](./MCP.md) · [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) + +--- + +## 1. Base et conventions + +| Élément | Valeur | +|---|---| +| URL de base | `http://:2020` (Docker) ou `http://127.0.0.1:17890` (desktop) | +| Préfixe API | `/api` | +| Format | JSON (`application/json`) | +| Version | suit la version d'ObsiGate (header `X-…`, `/api/health`) | +| Erreurs | `{"detail": "..."}` + code HTTP (`400`, `401`, `403`, `404`, `409`, `422`, `500`) | + +Quand l'authentification est **désactivée** (`OBSIGATE_AUTH_ENABLED=false`), tous +les endpoints sont accessibles sans jeton (utilisateur anonyme avec accès à tous +les vaults). + +--- + +## 2. Authentification + +### 2.1 Jeton de session (JWT) + +Obtenu via `POST /api/auth/login`. Le jeton d'accès a une durée de vie courte +(`OBSIGATE_ACCESS_TOKEN_TTL`, défaut 3600 s) et un refresh token longue durée est +posé en cookie HTTP-only. + +```bash +curl -s -X POST http://localhost:2020/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"admin","password":"votre_mot_de_passe"}' +``` + +Réponse (extrait) : + +```json +{ + "access_token": "eyJ...", + "token_type": "bearer", + "expires_in": 3600, + "user": { "username": "admin", "role": "admin", "vaults": ["*"] } +} +``` + +Deux façons de présenter le jeton : + +```http +Authorization: Bearer +``` + +ou, pour un client navigateur, le cookie HTTP-only avec +`credentials: "include"` (le login pose aussi un cookie `access_token`). + +### 2.2 Clés API longue durée (recommandé pour scripts & MCP) + +Une **seule clé** authentifie **l'API REST et le serveur MCP**. Créez-la depuis +l'interface (Configurations → **🔑 Clés API & MCP**) ou par API : + +```bash +# 1. Se connecter, récupérer le token (section 2.1) +# 2. Créer une clé valable 30 jours +curl -s -X POST http://localhost:2020/api/auth/tokens \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"Script backup","expiry":"30d"}' +``` + +Réponse (`token` affiché **une seule fois**) : + +```json +{ + "token": "eyJ...", + "jti": "…", + "name": "Script backup", + "created_at": 1790000000, + "expires_at": 1792592000, + "expiry_key": "30d" +} +``` + +| `expiry` | Durée | +|---|---| +| `1d` | 1 jour | +| `30d` | 1 mois | +| `180d` | 6 mois | +| `365d` | 1 an | +| `never` | sans expiration | + +Gestion : + +| Endpoint | Rôle | +|---|---| +| `GET /api/auth/tokens` | Lister vos clés (`last_used_at`, statut) | +| `POST /api/auth/tokens` | Créer (`{name, expiry}`) | +| `DELETE /api/auth/tokens/{jti}` | Révoquer immédiatement (API **et** MCP) | + +> Le JWT brut n'est **jamais persisté** : copiez-le à la création. Plafond : +> 50 clés actives par utilisateur. + +--- + +## 3. Référence des endpoints + +> Liste non exhaustive — la référence faisant foi est `/openapi.json`. Les +> colonnes **Auth** indiquent le niveau requis (`—`, `Oui`, `Admin`). + +### 3.1 Système + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/health` | Santé (statut, version, stats) | GET | — | +| `/api/health/detailed` | Santé détaillée | GET | — | +| `/api/config` | Lire / écrire la configuration | GET/POST | Oui/Admin | +| `/api/diagnostics` | Statistiques index & mémoire | GET | Admin | +| `/api/dashboard` | Statistiques du tableau de bord | GET | Oui | +| `/api/events` | Flux SSE temps réel | GET | Oui | + +### 3.2 Vaults + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/vaults` | Liste (filtrée par permissions) | GET | Oui | +| `/api/vaults/status` | Statut de toutes les vaults | GET | Oui | +| `/api/vaults/add` | Ajouter une vault (volume déjà monté) | POST | Admin | +| `/api/vaults/{name}` | Supprimer une vault | DELETE | Admin | +| `/api/index/reload` | Réindexation complète | GET | Admin | +| `/api/index/reload/{vault}` | Réindexer une vault | GET | Oui | +| `/api/vaults/{vault}/settings` | Lire / écrire les réglages | GET/POST | Oui | +| `/api/attachments/rescan/{vault}` | Rescanner les attachements | POST | Oui | + +### 3.3 Fichiers + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/browse/{vault}?path=` | Naviguer dans les dossiers | GET | Oui | +| `/api/file/{vault}?path=` | Contenu rendu (Markdown) | GET | Oui | +| `/api/file/{vault}/raw?path=` | Contenu brut | GET | Oui | +| `/api/file/{vault}/download?path=` | Télécharger | GET | Oui | +| `/api/file/{vault}/save?path=` | Enregistrer | PUT | Oui | +| `/api/file/{vault}` | Créer | POST | Oui | +| `/api/file/{vault}` | Renommer | PATCH | Oui | +| `/api/file/{vault}` | Supprimer | DELETE | Oui | +| `/api/directory/{vault}` | Créer / renommer / supprimer un dossier | POST/PATCH/DELETE | Oui | +| `/api/move/{vault}` | Déplacer un fichier/dossier | POST | Oui | +| `/api/vault/{vault}/batch-upload` | Upload multiple (multipart) | POST | Oui | +| `/api/image/{vault}?path=` | Servir une image | GET | Oui | + +### 3.4 Recherche & graphe + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/search` | Recherche simple (legacy) | GET | Oui | +| `/api/search/advanced` | Recherche TF-IDF avancée (facettes, tri, pagination, `semantic=`) | GET | Oui | +| `/api/search/replace` | Recherche/remplacement multi-fichiers | POST | Oui | +| `/api/tags?vault=` | Tags uniques avec compteurs | GET | Oui | +| `/api/suggest?q=` | Autocomplétion de titres | GET | Oui | +| `/api/tags/suggest?q=` | Autocomplétion de tags | GET | Oui | +| `/api/tree-search` | Recherche de fichiers/dossiers | GET | Oui | +| `/api/vault/{vault}/paths` | Liste de chemins | GET | Oui | +| `/api/graph/{vault}` | Graphe de liens | GET | Oui | + +### 3.5 Sauvegardes + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/file/{vault}/backups` | Backups d'un fichier | GET | Oui | +| `/api/file/{vault}/diff` | Diff avec une version | GET | Oui | +| `/api/file/{vault}/restore` | Restaurer une version | POST | Oui | +| `/api/backups` | Lister les backups | GET | Oui | +| `/api/backups/content` | Contenu d'un backup | GET | Oui | +| `/api/backups/delete` / `/purge` / `/compress` / `/auto` | Gestion & purge | POST | Oui | + +### 3.6 Exports + +| Endpoint | Description | Méthode | +|---|---|---| +| `/api/export/html` | Exporter en HTML | GET | +| `/api/export/md-bundle` | Exporter en bundle Markdown (ZIP) | GET | +| `/api/export/epub` | Exporter en ePub | GET | +| `/api/guide/download?format=md\|pdf&lang=fr\|en` | Télécharger le guide intégré | GET | + +### 3.7 PDF + +| Endpoint | Description | Méthode | +|---|---|---| +| `/api/file/{vault}/pdf/info` | Métadonnées sans transfert | GET | +| `/api/file/{vault}/pdf/stream` | Streaming (HTTP Range, 206) | GET | + +### 3.8 IA + +| Endpoint | Description | Méthode | +|---|---|---| +| `/api/ai/status` | Statut des fournisseurs | GET | +| `/api/ai/improve`, `/fix-spelling`, `/summarize`, `/translate`, `/rewrite`, `/to-list`, `/to-table`, `/frontmatter`, `/inline-complete`, `/to-canvas`… | Actions éditeur IA | POST | +| `/api/ai/model-capabilities?provider=&model=` | Capacités d'un modèle | GET | +| `/api/ai/bookslm/*` | Console IA par répertoire | POST/GET | +| `/api/ai/skills` | Lister / créer / supprimer des skills | GET/POST/DELETE | +| `/api/config/ai-keys` · `/api/config/tool-keys` | Clés fournisseurs & sources | GET/POST/DELETE | + +### 3.9 Authentification & administration + +| Endpoint | Description | Méthode | Auth | +|---|---|---|---| +| `/api/auth/status` | Statut de l'auth | GET | — | +| `/api/auth/login` · `/refresh` · `/logout` | Cycle de session | POST | — / Cookie / Oui | +| `/api/auth/me` | Profil courant | GET/PATCH | Oui | +| `/api/auth/change-password` | Changer le mot de passe | POST | Oui | +| `/api/auth/mfa/*` | TOTP, WebAuthn, recovery | POST/GET | Oui | +| `/api/auth/tokens` | Clés API (voir §2.2) | GET/POST/DELETE | Oui | +| `/api/auth/admin/users` | Lister / créer des utilisateurs | GET/POST | Admin | +| `/api/auth/admin/users/{u}` | Modifier / supprimer | PATCH/DELETE | Admin | +| `/api/admin/stats` · `/audit` · `/backup-stats` · `/stream` | Monitoring admin | GET | Admin | + +### 3.10 Partage, webhooks, conflits, plugins, push + +| Endpoint | Description | Méthode | +|---|---|---| +| `/api/share/{vault}` | Créer un lien de partage public | POST | +| `/api/shares` | Lister / supprimer les partages | GET/DELETE | +| `/api/webhooks` | CRUD webhooks (HMAC-SHA256) | GET/POST/PATCH/DELETE | +| `/api/conflicts` · `/api/conflicts/resolve` | Conflits Syncthing | GET/POST | +| `/api/plugins` | Installer / activer / désactiver | GET/POST/DELETE | +| `/api/push/*` | Abonnement Web Push (VAPID) | GET/POST/DELETE | + +--- + +## 4. Exemples `curl` + +```bash +BASE=http://localhost:2020 +TOKEN=$(curl -s -X POST $BASE/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"admin","password":"secret"}' | jq -r .access_token) + +# Santé +curl -s $BASE/api/health + +# Lister les vaults +curl -s $BASE/api/vaults -H "Authorization: Bearer $TOKEN" + +# Naviguer +curl -s "$BASE/api/browse/Recettes?path=" -H "Authorization: Bearer $TOKEN" + +# Lire un fichier (rendu Markdown) +curl -s "$BASE/api/file/Recettes?path=pizza.md" -H "Authorization: Bearer $TOKEN" + +# Lire en brut +curl -s "$BASE/api/file/Recettes/raw?path=pizza.md" -H "Authorization: Bearer $TOKEN" + +# Sauvegarder +curl -s -X PUT "$BASE/api/file/Recettes/save?path=pizza.md" \ + -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ + -d '{"content":"# Pizza\n\nNouvelle recette."}' + +# Recherche avancée +curl -s "$BASE/api/search/advanced?q=tag:cuisine%20pizza&vault=all&limit=20&offset=0&sort=relevance" \ + -H "Authorization: Bearer $TOKEN" + +# Autocomplétion +curl -s "$BASE/api/suggest?q=piz&vault=all" -H "Authorization: Bearer $TOKEN" + +# Forcer une réindexation +curl -s $BASE/api/index/reload -H "Authorization: Bearer $TOKEN" +``` + +> Le mot de passe peut aussi être fourni par une clé API dans `Authorization`. +> Quand l'auth est désactivée, omettez l'en-tête. + +--- + +## 5. Temps réel + +### 5.1 SSE — `/api/events` + +Flux d'événements de changement d'index (fichiers créés/supprimés/modifiés), avec +reconnexion automatique côté client. + +```bash +curl -N "$BASE/api/events" +``` + +### 5.2 WebSocket — collaboration + +`ws(s):///ws/collab/{vault}/{path}` transporte les mises à jour +Yjs/CRDT et la présence (curseurs distants). Authentification par cookie +`access_token` ou paramètre `?token=`, avec contrôle d'accès par vault. +Voir [Édition & collaboration](./COLLABORATION.md). + +--- + +## 6. Limites et bonnes pratiques + +- **Rate limiting** : les endpoints de login et les outils IA sont limités ; + respectez `retry_after` en cas de `429`. +- **Permissions** : chaque endpoint fichier vérifie l'accès au vault et rejette + les chemins hors vault (path traversal). +- **Clés API** : préférez-les aux mots de passe pour les scripts ; révoquez-les + dès qu'elles ne servent plus. +- **Gros volumes** : utilisez la pagination (`limit`/`offset`) et le streaming + HTTP Range pour les PDF. +- **Exports** : `md-bundle` et `epub` renvoient un fichier binaire — utilisez + `-o` avec `curl`. + +--- + +## 7. Dépannage + +| Code | Cause probable | +|---|---| +| `401` | Jeton absent, expiré ou révoqué | +| `403` | Compte sans accès à cette vault / réservé admin | +| `404` | Vault, fichier ou chemin inexistant | +| `409` | Conflit (fichier déjà existant, etc.) | +| `422` | Corps de requête invalide (schéma Pydantic) | +| `429` | Rate limit dépassé — voir `retry_after` | +| `501` | Export PDF indisponible (WeasyPrint/GTK absent) | diff --git a/docs/GUIDES/ASSISTANT_IA_FORGE.md b/docs/GUIDES/ASSISTANT_IA_FORGE.md new file mode 100644 index 0000000..479be6e --- /dev/null +++ b/docs/GUIDES/ASSISTANT_IA_FORGE.md @@ -0,0 +1,217 @@ +# 🤖 Guide Assistant IA & Forge + +ObsiGate intègre un **assistant IA** capable de lire, rechercher et modifier vos +notes, ainsi qu'un **éditeur IA** (CodeMirror + toolbar) et une console +contextuelle par répertoire (**BooksLM**). Ce guide explique comment les +configurer et les utiliser. + +> **Fiches techniques :** [`ai-tools-mcp.md`](../features/ai-tools-mcp.md) · +> [`ai-assistant-commands.md`](../features/ai-assistant-commands.md) · +> [`ai-quick-actions.md`](../features/ai-quick-actions.md) · +> [`forge-assistant.md`](../features/forge-assistant.md) · +> [`bookslm.md`](../features/bookslm.md) · +> [`ai-tools-roadmap.md`](../features/ai-tools-roadmap.md) +> **Voir aussi :** [Serveur MCP](./MCP.md) · [API REST](./API_REST.md) + +--- + +## 1. Vue d'ensemble + +L'IA d'ObsiGate se compose de plusieurs surfaces complémentaires : + +| Surface | Rôle | +|---|---| +| **Éditeur IA** | Toolbar d'actions sur le document ouvert (CodeMirror) | +| **Assistant IA** | Panneau de discussion avec *function calling* sur vos vaults | +| **BooksLM** | Console IA contextuelle sur un **répertoire** (style NotebookLM) | +| **Forge** | Éditeur avancé avec assistant IA intégré | +| **Outils (tools)** | Lecture, recherche, écriture, opérations destructives (two-step) | +| **MCP** | Exposition des mêmes outils à Claude Desktop, Cursor, Cline… | + +--- + +## 2. Configurer un fournisseur + +### 2.1 Fournisseurs supportés + +ObsiGate est **multi-fournisseur** : + +- **DeepSeek** +- **OpenRouter** +- **Google Gemini** + +Chaque fournisseur se configure au choix : + +1. **Depuis l'interface** — menu → Configurations → **Clés API IA**. La clé saisie + est stockée dans `data/api_keys.json` et **prime** sur la variable + d'environnement. +2. **Par variable d'environnement** — voir `.env.example`. + +### 2.2 Modèle et capacités + +L'interface affiche les **capacités** de chaque modèle (8 indicateurs : vision, +tool calling, contexte long, etc.), via +`GET /api/ai/model-capabilities?provider=&model=`. Le picker de l'assistant +propose une recherche de modèle et une bulle d'information ⓘ. + +Vous pouvez définir un **modèle par défaut** et un fournisseur par défaut dans la +configuration. Le fournisseur/modèle est **partagé** entre l'assistant et Forge. + +### 2.3 Tester la configuration + +`POST /api/config/ai-keys/test` vérifie qu'une clé fonctionne. En cas d'échec, +un message explicite s'affiche. + +--- + +## 3. Éditeur IA (toolbar) + +Quand un document Markdown est ouvert dans l'éditeur, une **toolbar IA** propose +des actions qui remplacent ou insèrent du contenu. Actions principales : + +| Action | Effet | +|---|---| +| **Améliorer** | Relecture et amélioration générale | +| **Corriger** | Correction orthographique et grammaticale | +| **Raccourcir / Allonger** | Ajuste la longueur du texte | +| **Simplifier** | Vulgarise le contenu | +| **Ton** | Adapte le registre (formel, neutre…) | +| **Traduire** | Traduit la sélection ou le document | +| **Expliquer** | Explique un passage | +| **Résumer** | Produit un résumé | +| **Continuer** | Prolonge le texte | +| **Réécrire** | Réécriture personnalisée libre | +| **En liste / En tableau** | Convertit en liste à puces ou tableau Markdown | +| **Frontmatter** | Génère ou met à jour le frontmatter YAML | +| **Complétion inline** | `Ctrl + J` — complétion directement dans l'éditeur | +| **En canvas** | Transforme en diagramme canvas | + +> Les actions sont exposées par `backend/ai_routes.py` (préfixe `/api/ai`). Le +> contexte ad-hoc (fichiers ouverts, répertoire, recherche, récents) est injecté +> automatiquement. + +--- + +## 4. Forge et Editer + +- **Editer** ouvre le document dans l'éditeur CodeMirror classique. +- **Forge** ouvre l'**éditeur avancé** : mêmes capacités d'édition, mais avec + l'**assistant IA partagé** intégré (bouton AI Panel), insertion rapide + (`Alt + I`), aide (`F1`) et mode plein écran. + +Dans les deux cas, `Editer` et `Forge` **remplacent** la vue lecture ; revenez en +lecture avec `✓` / `×` ou `Échap`. Le panneau de l'assistant reste accessible à +côté. + +--- + +## 5. Assistant IA & BooksLM + +### 5.1 Discussion avec outils + +L'assistant (panneau latéral) discute et **appelle des outils** pour agir sur +vos vaults : `list_vaults`, `read_file`, `search_fulltext`, `get_backlinks`, +`list_tags`, etc. Les opérations d'écriture passent par une **confirmation en +deux temps** (aperçu + jeton, puis application). + +### 5.2 Contexte `@` + +Tapez `@` pour attacher : + +- un **fichier** (chip de contexte) ; +- un **répertoire** (chip de contexte) ; +- une **image** (pièce jointe, si le modèle gère la vision). + +Le menu est alimenté par `/api/tree-search` (repli sur la liste des fichiers du +vault). Les chips sont retirables et rechargent le contexte. + +### 5.3 Commandes `/` et skills + +Tapez `/` pour ouvrir le **menu de commandes** (navigation `↑`/`↓`/`Entrée`/`Échap`). + +**30 skills intégrés**, répartis par familles : + +| Famille | Exemples | +|---|---| +| Base | `/research`, `/resume`, `/reformuler`, `/correction`, `/brainstorm`, `/plan`, `/ask`, `/meeting-note`, `/livrable` | +| Extraction & structuration | `/extract`, `/timeline`, `/glossary`, `/tag` | +| Transformation & adaptation | `/translate`, `/adapt`, `/clean`, `/summary-progressive` | +| Analyse critique & décision | `/critique`, `/compare`, `/prioritize`, `/swot`, `/debate` | +| Apprentissage & mémorisation | `/quiz`, `/reading-note`, `/qa-generator` | +| Méta-gestion & confidentialité | `/link`, `/anonymize`, `/estimate` | + +Chaque skill applique un bloc de règles commun (français, notes traitées comme +données, anti-hallucination, conservation des noms/dates/chiffres). + +**Skills utilisateur** : `/create-new-skill` ouvre une modale et persiste le +skill dans `data/skills.json` (par utilisateur). Ils sont listés par +`GET /api/ai/skills` et supprimables. + +**Commandes admin** (exécutées localement, sans LLM) : `/help`, `/providers`, +`/provider `, `/model `, `/keys`. + +### 5.4 Actions rapides + +Un catalogue de **25 actions** en 6 catégories est proposé sous forme de boutons +contextuels (« Résumer en 3 points », « Checklist d'actions », « Générer le +frontmatter », « Expliquer le code », « Fusionner », « Traduire »…). Un tiroir +**« Toutes les actions »** permet de rechercher dans le catalogue. + +### 5.5 Deep Research + +Le mode **Deep Research** enchaîne recherche web et synthèse. Il est activé via +le panneau **« + »** de l'assistant (fichiers, contextes, skills, Deep Research). + +### 5.6 Historique + +Les conversations sont **persistées côté backend** et accessibles depuis la +sidebar « Historique IA », avec filtre de recherche. + +--- + +## 6. Outils (function calling) + +Les outils sont définis dans `backend/tools/` — **source unique de vérité**, +partagée par l'assistant in-app et le serveur MCP. + +| Catégorie | Outils | +|---|---| +| Vaults / navigation | `list_vaults`, `list_directory`, `list_all_files` | +| Lecture | `read_file`, `read_file_raw`, `get_backlinks`, `list_backups`, `diff_backup`, `get_graph` | +| Recherche | `search_fulltext`, `search_advanced`, `search_paths`, `list_tags`, `suggest_tags`, `list_recent` | +| Écriture (propose/apply) | `create_file`, `create_directory`, `edit_file`, `append_to_file`, `restore_backup` | +| Destructif (propose/apply) | `rename_file`, `rename_directory`, `move_path`, `replace_in_files`, `delete_file`, `delete_directory` | +| Web / sources connectées | `web_search`, `fetch_url`, sources Gitea/GitHub… | + +Les mutations suivent un flux **two-step** : `propose_` renvoie un aperçu +et un **jeton signé à usage unique**, puis `apply_` exécute. + +--- + +## 7. Sécurité + +- **Permissions par vault** appliquées à chaque outil. +- **Anti path-traversal** via `resolve_safe_path`. +- **Confirmation two-step** pour toute mutation. +- **Toggle `aiDestructiveTools`** par vault : le désactiver bloque + rename/move/replace/delete, sans bloquer create/edit/append. +- **Backup automatique** avant chaque opération destructive. +- **Rate limiting** par identité et par outil. +- **Redaction des secrets** dans tous les retours d'outils. +- **Audit** de chaque appel (`data/audit.log`, action `ai_tool_call`). + +Détails : [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) et +[`MCP.md`](./MCP.md) §5. + +--- + +## 8. Dépannage + +| Symptôme | Piste | +|---|---| +| « Aucun fournisseur configuré » | Saisir une clé API (Configurations → Clés API IA) et la tester | +| L'IA n'a pas accès à un fichier | Vérifier `list_vaults` et les permissions du compte | +| L'image est refusée | Le modèle ne supporte pas la vision (400) — choisir un modèle multimodal | +| Une mutation reste bloquée | Vérifier `aiDestructiveTools` et le flux `propose_` → `apply_` | +| Quota d'outils atteint | Respecter `OBSIGATE_TOOL_RATE_LIMIT` / `retry_after` | +| Réponse tronquée | Ajuster `BOOKSLM_MAX_TOOL_READ_BYTES` / le modèle | diff --git a/docs/GUIDES/AUTHENTIFICATION_SECURITE.md b/docs/GUIDES/AUTHENTIFICATION_SECURITE.md new file mode 100644 index 0000000..53dabf8 --- /dev/null +++ b/docs/GUIDES/AUTHENTIFICATION_SECURITE.md @@ -0,0 +1,229 @@ +# 🔒 Guide Authentification & sécurité + +ObsiGate embarque un système d'authentification optionnel **JWT + Argon2id**, +un contrôle d'accès **par vault**, du MFA (TOTP, WebAuthn, codes de secours) et +des mécanismes de durcissement. Ce guide couvre l'activation, la gestion des +comptes et les bonnes pratiques. + +> **Public :** administrateurs · **Voir aussi :** +> [`features/api-mcp-tokens-107.md`](../features/api-mcp-tokens-107.md) · +> [API REST](./API_REST.md) · [MCP](./MCP.md) · [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) + +--- + +## 1. Vue d'ensemble + +- **Désactivée par défaut** (`OBSIGATE_AUTH_ENABLED=false`) — compatible avec + toutes les installations existantes. +- Quand elle est activée, l'écran de connexion s'affiche et chaque endpoint + vérifie l'utilisateur et ses permissions. +- Les données d'auth (`users.json`, `secret.key`, `api_tokens.json`) vivent dans + `/app/data` — **montez ce dossier en volume** pour les persister. + +--- + +## 2. Activer l'authentification + +### 2.1 Fichier `.env` + +```bash +cp .env.example .env +``` + +```bash +OBSIGATE_AUTH_ENABLED=true +OBSIGATE_ADMIN_USER=admin +OBSIGATE_ADMIN_PASSWORD=votre_mot_de_passe # vide = auto-généré (voir logs) +# OBSIGATE_SECURE_COOKIES=false # true si derrière HTTPS +``` + +### 2.2 `docker-compose.yml` + +```yaml +env_file: + - .env +``` + +> **Ne mettez jamais de mot de passe dans `docker-compose.yml` !** Utilisez +> toujours `.env` (non committé). + +### 2.3 Premier démarrage + +Si aucun utilisateur n'existe, ObsiGate crée un compte admin et affiche le mot de +passe **une seule fois dans les logs** : + +```bash +docker compose logs obsigate | grep -A4 "FIRST" +``` + +``` +============================================================ +FIRST STARTUP — Admin account created automatically + Username : admin + Password : xK9mQ3pLr7wN2jT5 +CHANGE THIS PASSWORD on first login! +============================================================ +``` + +Changez-le immédiatement (menu profil → *Changer le mot de passe*). + +--- + +## 3. Gestion des utilisateurs + +### 3.1 Interface d'administration + +Un compte **admin** voit une icône 🛡️ dans le header. Le panneau permet de : + +- lister tous les utilisateurs ; +- créer / modifier / supprimer des comptes ; +- assigner les vaults accessibles par utilisateur ; +- activer / désactiver des comptes. + +### 3.2 Ligne de commande + +```bash +# Créer un utilisateur +docker exec obsigate python backend/create_admin.py create alice MotDePasse --role user --vaults Recettes IT + +# Créer un admin avec accès total +docker exec obsigate python backend/create_admin.py create bob SecretPass --role admin --vaults "*" + +# Lister +docker exec obsigate python backend/create_admin.py list + +# Supprimer +docker exec obsigate python backend/create_admin.py delete alice +``` + +### 3.3 Contrôle d'accès par vault + +| Valeur `vaults` | Accès | +|---|---| +| `["*"]` | Toutes les vaults (y compris futures) — défaut admin | +| `["Recettes", "IT"]` | Uniquement ces vaults | +| `[]` | Aucun accès | + +Les permissions sont revérifiées à chaque requête (et à chaque connexion +WebSocket de collaboration). + +--- + +## 4. MFA (authentification multifacteur) + +ObsiGate propose trois secondes facteurs, configurables par l'utilisateur. + +### 4.1 TOTP (application d'authentification) + +1. Menu profil → **Sécurité** → *Configurer TOTP* (`POST /api/auth/mfa/totp/setup`). +2. Scannez le QR code avec Google Authenticator, Authy, etc. +3. Validez le code (`POST /api/auth/mfa/totp/enable`). +4. Désactivation : `POST /api/auth/mfa/totp/disable` (mot de passe requis). + +### 4.2 Clés de sécurité & biométrie (WebAuthn) + +- Enregistrement : `POST /api/auth/mfa/webauthn/register/options` puis + `POST /api/auth/mfa/webauthn/register`. +- Connexion : `POST /api/auth/mfa/webauthn/options` puis `/verify`. +- Gestion des clés : `GET /api/auth/mfa/webauthn/credentials`, + `POST /api/auth/mfa/webauthn/credentials/remove`. + +> Le *relying party* (domaine) est **dérivé de la requête** (hôte exact, port +> inclus) ; derrière un reverse proxy, activez `OBSIGATE_TRUST_PROXY=true` pour +> que `X-Forwarded-Host/Proto` soient pris en compte. + +### 4.3 Codes de secours + +À l'activation du MFA, des **codes de récupération** sont générés. Utilisez-en un +via `POST /api/auth/mfa/recovery` si vous perdez votre second facteur. Conservez- +les hors ligne. + +### 4.4 Statut + +`GET /api/auth/mfa/status` indique les facteurs actifs pour le compte courant. + +--- + +## 5. Clés API & MCP + +Pour les scripts et les clients externes, créez une **clé API longue durée** +(1 j, 1 mois, 6 mois, 1 an, sans fin) depuis Configurations → 🔑 **Clés API & +MCP**. Une seule clé authentifie l'API REST **et** le serveur MCP. + +- Le secret n'est **affiché qu'une fois** (pattern GitHub) et n'est jamais persisté. +- La révocation est **immédiate** des deux côtés. +- Une colonne « dernière utilisation » (throttlée) aide à repérer les clés + dormantes. + +Détails : [API REST §2.2](./API_REST.md#22-clés-api-longue-durée-recommandé-pour-scripts--mcp) +et [`features/api-mcp-tokens-107.md`](../features/api-mcp-tokens-107.md). + +--- + +## 6. Mécanismes de durcissement + +| Mécanisme | Détail | +|---|---| +| **Path traversal** | Chaque endpoint fichier valide que le chemin résolu reste dans la vault | +| **Rate limiting** | 10 tentatives de login max par IP / 15 min + lockout par compte | +| **Rate limiting MFA** | Appliqué aux endpoints TOTP/WebAuthn/recovery | +| **Audit log** | Écritures, suppressions, config dans `data/audit.log` (JSON lines, rotation 10 Mo) | +| **Backup automatique** | Avant chaque modification/suppression dans `.obsigate-backup/` | +| **Redaction** | Masquage des JWT, clés API, tokens dans les aperçus et retours d'outils | +| **CSP** | `object-src`, `base-uri`, `form-action`, `frame-ancestors` restreints | +| **Cookie HttpOnly** | Jeton retiré de `sessionStorage`, porté par cookie HTTP-only | +| **Utilisateur non-root** | Conteneur sous `obsigate` (UID 1000) | +| **Volumes read-only** | Vaults montées `:ro` par défaut | +| **Atomic writes** | `users.json`, `shares.json`, `webhooks.json` écrits en tmp+replace | +| **Symlinks ignorés** | L'index n'indexe pas les liens symboliques | + +### Politique de mot de passe + +Une politique minimale est validée à la création d'un compte. Choisissez des mots +de passe longs et uniques ; activez le MFA pour les comptes admin. + +--- + +## 7. Variables d'environnement + +| Variable | Description | Défaut | +|---|---|---| +| `OBSIGATE_AUTH_ENABLED` | Activer l'authentification | `false` | +| `OBSIGATE_ADMIN_USER` | Nom de l'admin auto-créé | `admin` | +| `OBSIGATE_ADMIN_PASSWORD` | Mot de passe admin (vide = auto-généré) | *(auto)* | +| `OBSIGATE_SECURE_COOKIES` | Cookie `Secure` (HTTPS uniquement) | `false` | +| `OBSIGATE_ACCESS_TOKEN_TTL` | Durée de vie du token d'accès (s) | `3600` | +| `OBSIGATE_REFRESH_TOKEN_TTL` | Durée de vie du refresh token (s) | `2592000` | +| `OBSIGATE_LOGIN_MAX_ATTEMPTS` | Tentatives de login max par IP | `10` | +| `OBSIGATE_ACCOUNT_MAX_ATTEMPTS` | Tentatives de login max par compte | `10` | +| `OBSIGATE_LOGIN_WINDOW_SECONDS` | Fenêtre de rate limiting (s) | `900` | +| `OBSIGATE_TRUST_PROXY` | Faire confiance à `X-Forwarded-For` / `Host` | `false` | + +Toutes ces variables sont documentées dans `.env.example`. + +--- + +## 8. Déploiement sécurisé (checklist) + +- [ ] `OBSIGATE_AUTH_ENABLED=true` sur toute instance exposée. +- [ ] Mot de passe admin fort, changé après le premier démarrage. +- [ ] MFA activé pour les comptes admin. +- [ ] HTTPS via reverse proxy + `OBSIGATE_SECURE_COOKIES=true`. +- [ ] `OBSIGATE_TRUST_PROXY=true` **uniquement** derrière un proxy de confiance. +- [ ] Volume `./data:/app/data` monté et **sauvegardé**. +- [ ] Vaults montées en `:ro` (lecture seule) sauf besoin d'écriture. +- [ ] Clés API révoquées dès qu'elles ne servent plus. +- [ ] Accès réseau restreint (VPN / pare-feu) si possible. + +--- + +## 9. Dépannage + +| Symptôme | Piste | +|---|---| +| Login bloqué `429` | Rate limit : attendre la fenêtre (`OBSIGATE_LOGIN_WINDOW_SECONDS`) | +| WebAuthn refuse l'enregistrement | Domaine/port non dérivés — activer `OBSIGATE_TRUST_PROXY` derrière un proxy | +| TOTP « challenge inattendu » | Relancer la cérémonie ; les 5 derniers challenges sont acceptés | +| Perte du second facteur | Utiliser un code de secours (`/api/auth/mfa/recovery`) | +| Sessions perdues au redémarrage | Le volume `./data` n'est pas monté | +| Clé API `401` | Clé expirée ou révoquée — en créer une nouvelle | diff --git a/docs/GUIDES/COLLABORATION.md b/docs/GUIDES/COLLABORATION.md new file mode 100644 index 0000000..49f728c --- /dev/null +++ b/docs/GUIDES/COLLABORATION.md @@ -0,0 +1,86 @@ +# 📝 Guide Édition & collaboration temps réel + +Plusieurs utilisateurs peuvent éditer le **même document Markdown +simultanément**, façon Google Docs, grâce à Yjs (CRDT) et à un canal WebSocket. +Ce guide explique le fonctionnement et l'utilisation. + +> **Public :** tous les utilisateurs · **Fiche technique :** +> [`features/collaboration.md`](../features/collaboration.md) +> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [API REST](./API_REST.md) + +--- + +## 1. Ce que fait la collaboration + +- **Fusion sans conflit** via **Yjs (CRDT)** : deux personnes peuvent taper au + même endroit, aucune modification n'est perdue. +- **Curseurs distants colorés** et sélections visibles dans CodeMirror, étiquetés + avec le nom de chaque utilisateur. +- **Indicateur de présence** dans l'en-tête de l'éditeur (avatars + statut de + connexion). +- **Reconnexion automatique** (backoff exponentiel) : l'état est fusionné au retour. +- **Persistance serveur** : le document est écrit sur disque **2 s** après la + dernière modification. + +--- + +## 2. Utilisation + +Aucune configuration n'est nécessaire : + +1. Ouvrez le même fichier dans **deux navigateurs** (ou deux fenêtres). +2. Passez en mode **Editer** (ou **Forge**) dans les deux. +3. Tapez : les modifications apparaissent en temps réel des deux côtés, avec les + curseurs de chacun. + +> L'édition collaborative nécessite que la vault soit **accessible en écriture** +> (le volume Docker doit être monté **sans** `:ro` pour les vaults modifiables). + +--- + +## 3. Transport & protocole + +| Élément | Valeur | +|---|---| +| Endpoint | `ws(s):///ws/collab/{vault}/{chemin}` | +| Authentification | Cookie `access_token` (ou paramètre `?token=`) | +| Autorisation | Contrôle d'accès **par vault** appliqué à chaque connexion | +| Protocole | Yjs / CRDT — updates + awareness (curseurs) | +| Persistance | Écriture disque débouncée (2 s) côté serveur | + +Le canal est mis à niveau à partir de la même origine que l'application. Derrière +un reverse proxy, autorisez les **upgrades WebSocket** et augmentez +`proxy_read_timeout` (voir [Déploiement Docker](./DEPLOIEMENT_DOCKER.md)). + +--- + +## 4. Sécurité + +- L'accès au document est **revérifié à la connexion** (permissions du compte). +- Un utilisateur sans droit sur la vault ne peut pas rejoindre la session. +- Les échanges passent par le même domaine que l'application (pas de serveur + tiers). + +--- + +## 5. Limitations & bonnes pratiques + +- La collaboration vise les fichiers **Markdown**. +- Évitez d'éditer le même fichier simultanément depuis ObsiGate **et** une + application de synchronisation externe (risque de conflits au niveau fichier). +- Le document est écrit après un court délai ; attendez la fin de la sauvegarde + avant de fermer brutalement l'onglet. +- En cas de conflit de synchronisation externe (Syncthing), l'écran + **Conflits** (`/api/conflicts`) aide à résoudre. + +--- + +## 6. Dépannage + +| Symptôme | Piste | +|---|---| +| Les curseurs des autres n'apparaissent pas | Vérifier le WebSocket (proxy sans support `Upgrade`) | +| Reconnecté sans cesse | Réseau instable ou timeout proxy trop court | +| Modifications non persistées | Vault montée en lecture seule (`:ro`) ? | +| `401` à la connexion | Session expirée — se reconnecter | +| Accès refusé | Le compte n'a pas la permission sur cette vault | diff --git a/docs/GUIDES/DEPLOIEMENT_DOCKER.md b/docs/GUIDES/DEPLOIEMENT_DOCKER.md new file mode 100644 index 0000000..0e10b8c --- /dev/null +++ b/docs/GUIDES/DEPLOIEMENT_DOCKER.md @@ -0,0 +1,221 @@ +# 🐳 Guide de déploiement Docker + +Ce guide couvre l'installation, la configuration et l'exploitation d'ObsiGate +avec Docker / Docker Compose, y compris le reverse proxy HTTPS et les mises à jour. + +> **Public :** administrateurs, ops +> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · +> [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) · +> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md) + +--- + +## 1. Prérequis + +| Composant | Version minimale | +|---|---| +| Docker | ≥ 20.10 | +| docker-compose | ≥ 2.0 | +| Espace disque | ~200 Mo pour l'image | + +Systèmes supportés : Linux (Ubuntu, Debian…), macOS (Intel & Apple Silicon), +Windows (Docker Desktop), NAS compatibles Docker (Synology, QNAP…). + +--- + +## 2. Configuration de `docker-compose.yml` + +```yaml +services: + obsigate: + build: + context: . + image: obsigate:latest + container_name: obsigate + restart: unless-stopped + ports: + - "2020:8080" # port local 2020 → conteneur 8080 + volumes: + - /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro + - /home/user/Documents/Obsidian-IT:/vaults/IT:ro + - ./data:/app/data # persistance auth/config/backups + environment: + - VAULT_1_NAME=Recettes + - VAULT_1_PATH=/vaults/Recettes + - VAULT_2_NAME=IT + - VAULT_2_PATH=/vaults/IT + - OBSIGATE_AUTH_ENABLED=true + - OBSIGATE_ADMIN_USER=admin + env_file: + - .env # secrets (mot de passe admin…) +``` + +> **Important :** les chemins de vaults doivent être **absolus** et montés en +> **lecture seule** (`:ro`) sauf si vous voulez autoriser l'édition depuis +> ObsiGate. Le dossier `./data` doit être **persistant**. + +### Variables de vault + +| Variable | Description | Exemple | +|---|---|---| +| `VAULT_N_NAME` | Nom affiché | `Recettes` | +| `VAULT_N_PATH` | Chemin dans le conteneur | `/vaults/Recettes` | +| `VAULT_N_ATTACHMENTS_PATH` | Dossier d'attachements (optionnel) | `Assets/Images` | +| `VAULT_N_SCAN_ATTACHMENTS` | Scanner les images au démarrage | `true` | + +**Nommage :** lettres, chiffres et tirets uniquement ; le nom doit correspondre au +chemin interne. + +--- + +## 3. Construire et lancer + +### 3.1 Script `build.sh` (recommandé) + +```bash +chmod +x build.sh # une seule fois +./build.sh +``` + +Le script : + +1. vérifie Docker et Docker Compose (versions) ; +2. valide `docker-compose.yml` (présence + syntaxe) ; +3. contrôle chaque volume monté (avertit si la source n'existe pas) ; +4. construit l'image (multi-stage, ~180 Mo) ; +5. démarre le conteneur ; +6. affiche le statut puis les logs en temps réel. + +| Option | Description | +|---|---| +| `--help`, `-h` | Aide complète | +| `--build-only` | Construire sans démarrer | +| `--no-cache` | Rebuild complet sans cache **(défaut)** | +| `--cache` | Utiliser le cache Docker (plus rapide) | +| `--progress=plain` / `--progress=tty` | Sortie verbeuse / interactive | + +### 3.2 Alternative manuelle + +```bash +docker compose build --no-cache +docker compose up -d +``` + +### 3.3 Exploitation + +```bash +docker compose down # arrêter +docker compose up -d # redémarrer sans rebuild +docker compose logs -f # logs temps réel +docker compose logs --tail=100 obsigate +``` + +> **Compatibilité Docker :** l'image utilise une variante `uvicorn` minimale et +> `fastapi 0.110.3` pour éviter des dépendances natives optionnelles +> (`watchfiles`, `uvloop`, `httptools`, `fastapi-cli`…) qui échouent sur Alpine, +> ARM ou i386. + +--- + +## 4. Reverse proxy & HTTPS + +ObsiGate sert du HTTP en clair ; placez un reverse proxy devant pour TLS. + +### 4.1 Nginx (exemple) + +```nginx +server { + listen 443 ssl http2; + server_name obsigate.example.com; + + ssl_certificate /etc/letsencrypt/live/obsigate.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/obsigate.example.com/privkey.pem; + + location / { + proxy_pass http://127.0.0.1:2020; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; # WebSocket collab + proxy_set_header Connection "upgrade"; + proxy_read_timeout 3600s; # SSE / WebSocket + } +} +``` + +### 4.2 Variables à activer derrière un proxy + +```bash +OBSIGATE_SECURE_COOKIES=true # cookie Secure (HTTPS uniquement) +OBSIGATE_TRUST_PROXY=true # confiance à X-Forwarded-For / Host +``` + +> N'activez `OBSIGATE_TRUST_PROXY` **que** derrière un proxy de confiance, sinon +> l'adresse IP client peut être usurpée (rate limiting, audit). + +Cloudflare Tunnel, Caddy et Traefik fonctionnent de la même façon (pensez au +support WebSocket et aux longs timeouts pour le SSE). + +--- + +## 5. Healthcheck & supervision + +L'image intègre un healthcheck sur `/api/health` (statut, version, stats). Vous +pouvez aussi l'interroger depuis l'hôte : + +```bash +curl -s http://localhost:2020/api/health +curl -s http://localhost:2020/api/health/detailed # admin +``` + +`/api/admin/stream` fournit un flux d'administration (admin uniquement). + +--- + +## 6. Mises à jour + +```bash +git pull +./build.sh # reconstruit et redémarre +``` + +Vos données (`./data`) et vos vaults (volumes `:ro`) sont conservées. Pour un +rebuild propre sans cache : `./build.sh --no-cache`. + +> **Version :** le fichier `VERSION` à la racine est la source unique de vérité ; +> l'image et l'UI affichent la même version. Voir +> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md). + +--- + +## 7. Sauvegardes + +- **Données applicatives** : sauvegardez `./data` (utilisateurs, clés, partages, + webhooks, jetons). +- **Vos notes** : ObsiGate n'écrit dans les vaults que si elles sont montées en + écriture. Un backup automatique interne est créé dans `.obsigate-backup/` avant + chaque modification (rotation 10 Mo d'audit). +- **Backups desktop** : voir [Desktop](./DESKTOP.md). + +--- + +## 8. Multi-plateforme + +L'image est publiée pour `linux/amd64`, `linux/arm64`, `linux/arm/v7` et +`linux/386`. Sur un NAS ou un Raspberry Pi, choisissez la variante correspondante +(Buildx / `platform:` dans le compose). + +--- + +## 9. Dépannage + +| Symptôme | Piste | +|---|---| +| Port déjà utilisé | `sudo netstat -tulpn \| grep 2020` puis changer `ports: "2021:8080"` | +| Vault introuvable | Chemin absolu, permissions de lecture, redémarrer après modif | +| Build qui échoue | `docker system prune -f` puis `./build.sh --progress=plain` | +| Logs | `docker compose logs -f obsigate` | +| Widgets temps réel inopérants derrière un proxy | Autoriser les upgrades WebSocket et augmenter `proxy_read_timeout` | +| Login « insecure cookie » | Passer en HTTPS ou retirer `OBSIGATE_SECURE_COOKIES` | diff --git a/docs/GUIDES/DESKTOP.md b/docs/GUIDES/DESKTOP.md new file mode 100644 index 0000000..7d7319b --- /dev/null +++ b/docs/GUIDES/DESKTOP.md @@ -0,0 +1,201 @@ +# 🖥️ Guide de l'application desktop (Tauri) + +ObsiGate Desktop est une application native construite avec +[Tauri](https://tauri.app/) (Rust + webview système). Elle embarque le backend +Python et le frontend dans un exécutable autonome — **zéro Docker, zéro ligne de +commande**. + +> **Public :** tous les utilisateurs · **Statut :** version 2.x, binaires en +> cours de stabilisation (build depuis les sources recommandé) +> **Fiche technique :** [`features/desktop-tauri.md`](../features/desktop-tauri.md) · +> **Checklist E2E :** [`DESKTOP_E2E_CHECKLIST.md`](../DESKTOP_E2E_CHECKLIST.md) + +--- + +## 1. Fonctionnalités natives + +| Fonctionnalité | Web | Desktop | +|---|---|---| +| Accès fichiers local | Via upload | Natif (sélecteur de dossier) | +| Thème système | Manuel | Auto (suit l'OS clair/sombre) | +| Notifications | Service Worker | Natif OS | +| Association `.md` | ❌ | ✅ « Ouvrir avec ObsiGate » | +| Icône de barre des tâches (tray) | ❌ | ✅ | +| Auto-update | ❌ | ✅ (vérifie les releases Gitea) | +| Mode hors-ligne | Limité | Complet (backend local) | + +--- + +## 2. Téléchargement des binaires + +Les releases sont publiées sur +[Gitea](https://git.dracodev.net/Projets/ObsiGate/releases) : + +| Plateforme | Formats | +|---|---| +| **Linux** | `.deb` + `.AppImage` | +| **Windows** | `.msi` + `.exe` (NSIS) | + +### Linux + +```bash +# .deb (Debian / Ubuntu / Deepin) +sudo dpkg -i obsigate_2.0.0_amd64.deb +# Lancer : ObsiGate depuis le menu applications, ou `obsigate-desktop` + +# .AppImage (toute distribution) +chmod +x ObsiGate_2.0.0_amd64.AppImage +./ObsiGate_2.0.0_amd64.AppImage +``` + +### Windows + +```cmd +:: Double-cliquer sur ObsiGate_2.0.0_x64.msi (ou le setup NSIS) +:: Ou lancer ObsiGate depuis le menu Démarrer +``` + +--- + +## 3. Démarrage + +1. **Lancez l'application** depuis le menu ou la ligne de commande. +2. Le backend Python démarre automatiquement sur `127.0.0.1:17890` + (splash « Démarrage… » pendant le boot). +3. La fenêtre s'ouvre et charge l'interface ObsiGate. +4. **Premier lancement** : sélectionnez le dossier de vos vaults Obsidian via le + sélecteur natif. +5. Pour fermer : icône tray → **Quitter** (arrêt propre du backend). + +--- + +## 4. Construire depuis les sources + +Guide détaillé : [`desktop/README.md`](../../desktop/README.md). + +### 4.1 Prérequis communs + +| Outil | Version | Installation | +|---|---|---| +| Rust (cargo) | ≥ 1.75 | `rustup` | +| Tauri CLI | ≥ 2.0 | `cargo install tauri-cli` | +| Git | — | — | +| Dépendances système Linux | — | `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev` | + +> **Important — staging :** `tauri.conf.json` embarque `backend/**` et +> `frontend/**` **depuis le dossier `desktop/`**. Les scripts de build copient +> automatiquement `../backend` et `../frontend` dans `desktop/` avant +> `cargo tauri build`. Sans ce staging, le build échoue avec +> « glob pattern backend/**/* path not found ». + +### 4.2 Windows — `build-windows.bat` + +```cmd +REM Prérequis (via Scoop) : rustup, curl, git +scoop install rustup curl git +rustup default stable +cargo install tauri-cli + +cd desktop +build-windows.bat +``` + +Étapes du script : + +1. Tue les processus Python résiduels (`taskkill /F /IM python.exe`). +2. Télécharge **Python 3.11 embed** (python.org) → `desktop\python-embed\` + + active pip (`python311._pth`). +3. `pip install -r ..\backend\requirements.txt` dans l'embed. +4. **Staging** : copie `..\backend` et `..\frontend` dans `desktop\`. +5. `cargo tauri build --target x86_64-pc-windows-msvc --bundles nsis`. +6. Copie `python-embed` à côté de l'exécutable pour le mode dev local. +7. Nettoie les dossiers stagés. + +→ **Artefact :** `desktop\target\x86_64-pc-windows-msvc\release\bundle\nsis\ObsiGate_2.0.0_x64-setup.exe` + +### 4.3 Linux — `build-linux.sh` + +```bash +cd desktop +chmod +x build-linux.sh +./build-linux.sh +``` + +Étapes du script : + +1. Vérifie Rust + Tauri CLI, installe les dépendances système (apt). +2. Crée un venv `desktop/python-embed/venv` + `pip install -r ../backend/requirements.txt`. +3. **Staging** : copie `../backend` et `../frontend` dans `desktop/`. +4. `cargo tauri build --target x86_64-unknown-linux-gnu --bundles deb,appimage`. +5. Copie le runtime (`python-embed/`, `backend/`, `frontend/`) à côté de l'exécutable. + +→ **Artefacts :** + +- `desktop/target/x86_64-unknown-linux-gnu/release/bundle/deb/obsigate_2.0.0_amd64.deb` +- `desktop/target/x86_64-unknown-linux-gnu/release/bundle/appimage/ObsiGate_2.0.0_amd64.AppImage` + +--- + +## 5. Builds CI/CD automatiques + +Le workflow [`.gitea/workflows/desktop-build.yml`](../../.gitea/workflows/desktop-build.yml) +construit les binaires desktop à chaque push sur `main` touchant `desktop/**`, +`frontend/**` ou `backend/**` (et manuellement via `workflow_dispatch`), sur des +**runners self-hosted** : + +| Job | Runner | Artefacts (30 jours) | +|---|---|---| +| `build-windows` | `[self-hosted, windows, desktop]` | `desktop/target/release/bundle/msi/*.msi` | +| `build-linux` | `[self-hosted, linux, desktop]` | `*.AppImage` + `*.deb` | + +Les artefacts sont téléchargeables depuis la page **Actions** du run Gitea ; la +publication en **Gitea Release** est prévue sur les tags `v*`. + +--- + +## 6. Architecture desktop + +``` +┌────────────────────────────────────────────┐ +│ Tauri (Rust) │ +│ ├─ Webview (webview système) │ +│ │ └─ Frontend (HTML/JS/CSS) │ +│ └─ Sidecar Python │ +│ └─ uvicorn backend.main:app │ +│ └─ port 127.0.0.1:17890 │ +└────────────────────────────────────────────┘ +``` + +Cycle de vie : Tauri spawn le backend Python → health check → splash → webview. +À la fermeture : arrêt propre du backend (SIGTERM / kill). + +--- + +## 7. Mises à jour + +L'application vérifie les **releases Gitea** et propose la mise à jour (updater +Tauri signé). Le manifeste `latest.json` est généré automatiquement. + +> La **signature de code Windows** n'est pas retenue (pas de certificat) : le +> binaire peut déclencher un avertissement SmartScreen. Alternatives possibles : +> SignPath.io (OSS gratuit), Certum OSS, Azure Trusted Signing, certificat EV. + +--- + +## 8. Logs & dépannage + +Les logs du backend sont écrits dans : + +- **Windows** : `%APPDATA%\ObsiGate\logs\backend.log` +- **Linux** : `~/.config/obsigate/logs/backend.log` + +| Symptôme | Piste | +|---|---| +| « Backend ne répond pas » | Vérifier le port `17890` (conflit) et relancer | +| Build « glob pattern backend/**/* not found » | Le staging n'a pas été fait — utiliser les scripts fournis | +| Le sélecteur de dossier ne s'ouvre pas | Permissions système / dialogue natif bloqué | +| Fenêtre blanche | Consulter `backend.log` ; le backend a peut-être échoué au boot | +| Mise à jour non proposée | Vérifier la connectivité aux releases Gitea | + +Voir aussi [Prise en main](./PRISE_EN_MAIN.md) et +[Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md). diff --git a/docs/GUIDES/MCP.md b/docs/GUIDES/MCP.md new file mode 100644 index 0000000..bdfc3e0 --- /dev/null +++ b/docs/GUIDES/MCP.md @@ -0,0 +1,191 @@ +# 🧩 Guide MCP (Model Context Protocol) + +ObsiGate expose ses vaults à des **clients MCP externes** (Claude Desktop, Cursor, +Cline, tout client compatible MCP) via un serveur **Streamable HTTP** monté sur +`/mcp`. Les outils sont les **mêmes** que ceux de l'assistant in-app : la couche +`backend/tools/` est la source unique de vérité. + +> **Statut :** livré (#79 phase E + F) · **Dernière mise à jour :** 2026-09 +> **Voir aussi :** [`features/ai-tools-mcp.md`](../features/ai-tools-mcp.md) · +> [`AI_ARCHITECTURE_GUIDE.md`](../AI_ARCHITECTURE_GUIDE.md) · +> [API REST](./API_REST.md) · [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) + +--- + +## 1. Prérequis + +1. Une instance ObsiGate accessible (locale ou distante). +2. Une **clé API** (recommandé) ou un **jeton JWT** valide + (`Authorization: Bearer `). Une seule clé fonctionne pour l'API REST + **et** le MCP. Créez-la depuis l'interface (Configurations → 🔑 Clés API & MCP) + ou via `POST /api/auth/tokens` — voir [API REST §2.2](./API_REST.md#22-clés-api-longue-durée-recommandé-pour-scripts--mcp). +3. Si l'authentification est désactivée (`OBSIGATE_AUTH_ENABLED=false`), le + serveur MCP accepte un utilisateur anonyme disposant de tous les vaults. + +> Le transport `stdio` n'est pas encore supporté ; utilisez le transport HTTP +> (un pont local type `mcp-remote` si votre client ne gère pas nativement le +> Streamable HTTP distant). + +--- + +## 2. Endpoint & protocole + +| Élément | Valeur | +|---|---| +| URL | `https:///mcp` | +| Transport | Streamable HTTP (`POST` JSON-RPC 2.0, `Accept: application/json, text/event-stream`) | +| Auth | `Authorization: Bearer ` | +| Protocole MCP | `2025-03-26` (négocié à l'`initialize`) | +| Réponses | JSON (`json_response=True`) | + +Handshake minimal : + +```bash +curl -sS https://obsigate.example/mcp \ + -H "Authorization: Bearer $TOKEN" \ + -H "Accept: application/json, text/event-stream" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ + "protocolVersion":"2025-03-26","capabilities":{}, + "clientInfo":{"name":"curl","version":"1.0"}}}' +``` + +La réponse contient l'en-tête `Mcp-Session-Id` à réutiliser pour les appels +suivants (`tools/list`, `tools/call`, `resources/read`, …). + +--- + +## 3. Configuration des clients + +### Claude Desktop (via pont `mcp-remote`) + +```json +{ + "mcpServers": { + "obsigate": { + "command": "npx", + "args": [ + "-y", "mcp-remote", + "https://obsigate.example/mcp", + "--header", "Authorization: Bearer ${OBSIGATE_TOKEN}" + ], + "env": { "OBSIGATE_TOKEN": "eyJ..." } + } + } +} +``` + +### Cursor + +`.cursor/mcp.json` : + +```json +{ + "mcpServers": { + "obsigate": { + "url": "https://obsigate.example/mcp", + "headers": { "Authorization": "Bearer eyJ..." } + } + } +} +``` + +### Client générique (config raccourcie) + +```json +{"mcpServers": {"obsigate": { + "url": "http://localhost:2020/mcp", + "headers": {"Authorization": "Bearer "} +}}} +``` + +--- + +## 4. Primitives exposées + +### 4.1 Tools + +Les outils de **lecture/recherche** sont exposés directement. Les outils +**d'écriture/destructifs** sont exposés via une paire **two-step** : +`propose_` (aperçu + jeton de confirmation, aucune modification) puis +`apply_` (consomme le jeton et exécute). + +| Catégorie | Outils | +|---|---| +| Vaults / navigation | `list_vaults`, `list_directory`, `list_all_files` | +| Lecture | `read_file`, `read_file_raw`, `get_backlinks`, `list_backups`, `diff_backup`, `get_graph` | +| Recherche | `search_fulltext`, `search_advanced`, `search_paths`, `list_tags`, `suggest_tags`, `list_recent` | +| Écriture (propose/apply) | `create_file`, `create_directory`, `edit_file`, `append_to_file`, `restore_backup` | +| Destructif (propose/apply) | `rename_file`, `rename_directory`, `move_path`, `replace_in_files`, `delete_file`, `delete_directory` | + +Flux d'une mutation : + +```text +1. tools/call { name: "propose_edit_file", + arguments: { vault, path, content } } + → { tool, arguments, diff, confirmation_token, expires_in } + +2. (l'utilisateur / l'agent valide) + +3. tools/call { name: "apply_edit_file", + arguments: { confirmation_token } } + → { ok: true, data: { ... } } +``` + +Le jeton est **signé (JWT), à usage unique et à durée de vie limitée** +(`OBSIGATE_MCP_CONFIRMATION_TTL`, défaut 300 s). Un rejeu renvoie `token_reused`. + +### 4.2 Resources + +| URI | Contenu | +|---|---| +| `vault://` | Vault accessible (métadonnées, nombre de fichiers) | +| `vault:///` | Contenu d'un fichier (lecture seule, **secrets redactés**) | + +### 4.3 Prompts + +`summarize-directory`, `generate-note`, `find-related`. + +--- + +## 5. Sécurité + +- **Permissions par vault** : `check_vault_access` est appliqué à chaque outil + et chaque resource ; un utilisateur ne voit que ses vaults. +- **Anti path-traversal** : `resolve_safe_path` rejette tout chemin hors du vault. +- **Confirmation two-step** pour toute mutation (jeton signé, usage unique). +- **Toggle par vault** `aiDestructiveTools` (défaut : activé) : le désactiver + bloque rename/move/replace/delete tout en laissant create/edit/append. +- **Backup automatique** avant chaque opération destructive. +- **Rate limiting** : par jeton et par outil + (`OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`, + `OBSIGATE_TOOL_RATE_WINDOW`). Une limite dépassée renvoie le code `rate_limited`. +- **Redaction des secrets** : les résultats d'outils (lectures, diffs, extraits + de recherche) sont nettoyés avant tout retour au client. +- **Audit** : chaque appel est journalisé (`data/audit.log`, action + `ai_tool_call`) avec arguments sensibles résumés. + +### Variables d'environnement + +| Variable | Défaut | Rôle | +|---|---|---| +| `OBSIGATE_MCP_CONFIRMATION_TTL` | `300` | Durée de vie (s) des jetons de confirmation | +| `OBSIGATE_TOOL_RATE_LIMIT` | `60` | Appels d'outils max par identité et par fenêtre | +| `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL` | = global | Appels max par outil et par fenêtre | +| `OBSIGATE_TOOL_RATE_WINDOW` | `60` | Longueur de la fenêtre (s) | +| `BOOKSLM_MAX_TOOL_CALLS` | `25` | Quota d'appels d'outils par run d'agent | +| `BOOKSLM_MAX_TOOL_READ_BYTES` | `200000` | Taille max renvoyée par `read_file` | + +--- + +## 6. Dépannage + +| Symptôme | Cause probable / remède | +|---|---| +| `401 Authentification requise` | En-tête `Authorization: Bearer` absent ou jeton expiré | +| `vault_access_denied` | Le jeton n'a pas accès à ce vault (`vaults` / `_token_vaults`) | +| `destructive_tools_disabled` | `aiDestructiveTools=false` pour ce vault | +| `confirmation_required` | Appeler d'abord `propose_` puis `apply_` | +| `token_reused` / `invalid_confirmation` | Jeton déjà consommé ou expiré → refaire un `propose_` | +| `rate_limited` | Quota dépassé ; respecter `retry_after` | +| Le client ne se connecte pas | Vérifier le transport Streamable HTTP / le pont `mcp-remote` | diff --git a/docs/GUIDES/PRISE_EN_MAIN.md b/docs/GUIDES/PRISE_EN_MAIN.md new file mode 100644 index 0000000..c592262 --- /dev/null +++ b/docs/GUIDES/PRISE_EN_MAIN.md @@ -0,0 +1,236 @@ +# 🚀 Guide de prise en main + +Ce guide vous fait passer d'une installation fraîche à une utilisation courante +d'ObsiGate : première connexion, découverte de l'interface, navigation dans vos +vaults Obsidian et raccourcis essentiels. + +> **Public :** tous les utilisateurs · **Durée de lecture :** ~10 min +> **Voir aussi :** [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) · +> [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) · +> [API REST](./API_REST.md) + +--- + +## 1. Qu'est-ce qu'ObsiGate ? + +ObsiGate est une **porte d'entrée web ultra-légère** vers vos vaults Obsidian. +Il indexe vos notes en mémoire, les rend accessibles depuis n'importe quel +navigateur (ordinateur, tablette, téléphone) et ajoute une couche moderne : +recherche avancée, lecture Markdown, liens `[[wikilinks]]`, images, PDF, +Excalidraw, Mermaid, assistant IA, collaboration temps réel. + +Points clés : + +- **Aucune modification de vos vaults** : les volumes sont montés en lecture seule (`:ro`) par défaut. +- **Pas de base de données** : tout l'état tient dans des fichiers JSON sous `data/`. +- **Temps réel** : un watcher surveille le système de fichiers et met l'index à jour à chaud. +- **Multi-vault** : plusieurs vaults peuvent être affichés et recherchés simultanément. + +--- + +## 2. Prérequis + +| Composant | Version | Remarque | +|---|---|---| +| Docker | ≥ 20.10 | ou Node/`uv` pour un lancement manuel | +| docker-compose | ≥ 2.0 | inclus avec Docker Desktop | +| Navigateur | récent | Chrome, Edge, Firefox, Safari | + +Vous aurez aussi besoin du **chemin absolu** de chaque vault Obsidian sur la +machine qui héberge Docker. + +--- + +## 3. Lancer ObsiGate en 3 étapes + +> La procédure complète (reverse proxy, HTTPS, mises à jour) est détaillée dans le +> [Guide de déploiement Docker](./DEPLOIEMENT_DOCKER.md). + +### 3.1 Cloner le dépôt + +```bash +git clone https://git.dracodev.net/Projets/ObsiGate.git +cd ObsiGate +``` + +### 3.2 Déclarer vos vaults + +Éditez `docker-compose.yml` pour monter vos dossiers (chemins absolus, lecture seule) : + +```yaml +volumes: + - /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro + - /home/user/Documents/Obsidian-IT:/vaults/IT:ro + - ./data:/app/data # persistance auth/config +environment: + - VAULT_1_NAME=Recettes + - VAULT_1_PATH=/vaults/Recettes + - VAULT_2_NAME=IT + - VAULT_2_PATH=/vaults/IT +``` + +Créez le fichier de secrets à partir du modèle : + +```bash +cp .env.example .env +# Éditez .env (mot de passe admin, options d'auth…) +``` + +### 3.3 Construire et démarrer + +```bash +chmod +x build.sh # une seule fois +./build.sh +``` + +`build.sh` vérifie Docker, valide les volumes, construit l'image et démarre le +conteneur. Ouvrez ensuite **http://localhost:2020**. + +> Options utiles : `./build.sh --help`, `./build.sh --cache` (rebuild rapide), +> `./build.sh --build-only` (construire sans démarrer). + +--- + +## 4. Premier accès + +### 4.1 Si l'authentification est désactivée (défaut) + +Vous arrivez directement sur l'interface. Toutes les fonctionnalités sont +accessibles sans compte — **à réserver à un usage sur réseau de confiance**. + +### 4.2 Si l'authentification est activée + +L'écran de connexion s'affiche. Au **tout premier démarrage**, ObsiGate crée un +compte admin et affiche le mot de passe **une seule fois dans les logs** : + +```bash +docker compose logs obsigate | grep -A4 "FIRST" +``` + +Changez ce mot de passe dès la première connexion (menu → profil → +*Changer le mot de passe*). La gestion complète des comptes, du MFA et des +permissions est décrite dans le +[Guide Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md). + +--- + +## 5. Découvrir l'interface + +L'interface se compose de trois zones principales. + +### 5.1 L'en-tête (header) + +| Élément | Rôle | +|---|---| +| 🔍 **Barre de recherche globale** | Recherche dans toutes les vaults autorisées | +| Filtre | Restreint la recherche (type, tag, vault…) | +| Sélecteur de vault | Bascule l'arborescence sur une vault ou « Toutes les vaults » | +| Utilisateur | Nom du compte connecté (si auth activée) | +| Version | Version courante d'ObsiGate | +| ⚙️ **Options** | Configuration, thème, guide d'utilisation, administration | + +### 5.2 La barre latérale (sidebar) + +Elle regroupe les vues principales via des icônes : + +- **Arborescence** — parcourt les dossiers et fichiers de la vault sélectionnée. +- **Graphe** — vue force-directed des liens entre notes. +- **Récents** — derniers fichiers ouverts. +- **Signets** — vos fichiers et recherches enregistrés. +- **Partagés** — liens de partage public que vous avez créés. + +Un champ **« Filtrer fichiers… »** restreint l'arborescence en temps réel, et le +bouton **Aa** ajuste l'affichage des libellés. + +### 5.3 La zone de contenu + +Elle affiche l'onglet actif : tableau de bord **Statistiques**, **Bookmarks**, +**Récents**, **Partagés**, ou le document ouvert. Les documents s'ouvrent dans +des **onglets** (avec possibilité de vue multi-panneaux / split view). + +--- + +## 6. Navigation et lecture + +1. **Déployez une vault** dans la sidebar (clic sur son nom). +2. **Cliquez sur un dossier** pour l'ouvrir, sur un **fichier** pour l'afficher. +3. Le **breadcrumb** en haut du document permet de remonter rapidement. +4. Les **wikilinks** `[[note]]` sont cliquables ; les images et diagrammes + s'affichent automatiquement. +5. Utilisez **Ctrl + clic** sur un lien pour l'ouvrir en aperçu rapide selon le + contexte, ou ouvrir le graphe centré sur un nœud. + +### Créer et modifier + +- **Bouton « Editer »** : ouvre le document dans l'éditeur Markdown (CodeMirror). +- **Bouton « Forge »** (éditeur avancé) : ouvre la version enrichie avec + assistant IA intégré. Voir [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md). +- **Nouveau fichier / dossier** : depuis les actions de la sidebar ou la palette + de commandes. +- **Sauvegarde** : `Ctrl + S` (et auto-sauvegarde dans l'éditeur IA). + +> Selon le mode, la lecture et l'édition se remplacent : `Editer` et `Forge` +> prennent la place de la vue lecture ; revenez avec `✓` / `×` ou `Échap`. + +--- + +## 7. Rechercher + +La recherche est un point fort d'ObsiGate : index inversé TF-IDF, stemming +français, normalisation des accents, facettes et pagination. La syntaxe complète +(`tag:`, `#`, `vault:`, `title:`, `path:`, `ext:`, phrases exactes) est décrite +dans le [Guide Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md). + +Démarrage rapide : + +- Tapez dans la barre de recherche, `Ctrl + K` pour y revenir. +- `/` focalise la recherche hors champ de saisie. +- `/` + `↑`/`↓` navigue dans les suggestions. + +--- + +## 8. Apparence et confort + +- **Thème clair/sombre** : bascule persistée en `localStorage` ; le desktop suit + aussi le thème du système. +- **Thèmes** : clair, sombre, contraste élevé, sépia — import/export possible. +- **Responsive** : l'interface s'adapte au mobile (éditeur tactile, barre + d'outils flottante). +- **PWA** : installable comme application native, mode hors-ligne partiel. + +Voir [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md). + +--- + +## 9. Raccourcis clavier essentiels + +| Action | Raccourci | +|---|---| +| Palette de commandes | `Ctrl + Shift + Space` | +| Palette de fichiers (navigation rapide) | `Ctrl + Alt + Space` | +| Focus barre de recherche | `Ctrl + K` | +| Recherche rapide (hors champ texte) | `/` | +| Sauvegarder le fichier ouvert | `Ctrl + S` | +| Rechercher dans le document | `Ctrl + F` | +| Completion IA inline (éditeur) | `Ctrl + J` | +| Insertion rapide (éditeur Forge) | `Alt + I` | +| Fermer l'éditeur / modale | `Échap` | +| Aide de l'éditeur Forge | `F1` | +| Naviguer dans les suggestions | `↑` / `↓` | +| Lancer la recherche / valider | `Entrée` | + +> Le panneau **Raccourcis & Astuces** du tableau de bord Statistiques récapitule +> ces raccourcis directement dans l'application. + +--- + +## 10. Et ensuite ? + +| Objectif | Guide | +|---|---| +| Mieux chercher, lire PDF et Excalidraw | [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) | +| Utiliser l'IA intégrée | [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) | +| Éditer à plusieurs | [Édition & collaboration](./COLLABORATION.md) | +| Sécuriser l'accès | [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) | +| Automatiser via API/MCP | [API REST](./API_REST.md) · [MCP](./MCP.md) | +| Installer l'application native | [Desktop (Tauri)](./DESKTOP.md) | diff --git a/docs/GUIDES/PWA_HORS_LIGNE.md b/docs/GUIDES/PWA_HORS_LIGNE.md new file mode 100644 index 0000000..c23843c --- /dev/null +++ b/docs/GUIDES/PWA_HORS_LIGNE.md @@ -0,0 +1,136 @@ +# 📱 Guide PWA & mode hors-ligne + +ObsiGate est une **Progressive Web App (PWA)** : installez-la comme une +application native, consultez vos notes **hors-ligne**, recevez des +notifications et synchronisez vos modifications à la reconnexion. + +> **Public :** tous les utilisateurs · **Guides techniques :** +> [`PWA_GUIDE.md`](../PWA_GUIDE.md) · [`INSTALLATION_PWA.md`](../INSTALLATION_PWA.md) +> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [Édition & collaboration](./COLLABORATION.md) + +--- + +## 1. Qu'est-ce que la PWA d'ObsiGate ? + +Une PWA combine le meilleur du web et du natif : + +- **Installation** sur l'écran d'accueil, sans store. +- **Mode hors-ligne** : interface et dernières données consultées mises en cache. +- **Notifications** : alertes de mise à jour et Web Push. +- **Performance** : chargement rapide via cache intelligent. +- **Multi-plateforme** : desktop, mobile, tablette. + +--- + +## 2. Installer la PWA + +### Desktop (Chrome, Edge, Brave) + +1. Ouvrez ObsiGate dans le navigateur. +2. Cliquez sur l'icône d'installation dans la barre d'adresse (➕ / ⬇️). +3. Cliquez sur **Installer** dans la popup. +4. ObsiGate apparaît dans vos applications. + +*Alternative :* menu ⋮ → **Installer ObsiGate…** + +### Android (Chrome) + +1. Ouvrez ObsiGate dans Chrome. +2. Menu ⋮ → **Ajouter à l'écran d'accueil**. +3. Confirmez. + +### iOS / iPadOS (Safari) + +1. Ouvrez ObsiGate dans Safari. +2. Bouton Partager 📤 → **Sur l'écran d'accueil**. +3. Nommez l'application puis **Ajouter**. + +--- + +## 3. Mode hors-ligne + +Le **Service Worker** (`frontend/sw.js`) met en cache : + +- l'interface (HTML, CSS, JavaScript, manifeste) ; +- les ressources statiques (icônes, polices) ; +- les dernières données API consultées. + +### Stratégies de cache + +| Ressource | Stratégie | +|---|---| +| Code (HTML/JS/CSS/manifest) | **Network-first** (cache en secours hors-ligne) | +| API | **Network-first** (+ cache hors-ligne) | +| Autres assets (images, polices) | **Stale-while-revalidate** | +| Nettoyage | Purge des caches d'une version antérieure à l'activation | + +> Le choix **network-first** est délibéré : les assets ne sont pas fingerprintés, +> un cache-first servirait indéfiniment un ancien build sur mobile. + +### File de synchronisation & conflits + +- Les modifications faites hors-ligne sont stockées (IndexedDB) et rejouées à la + reconnexion. +- Les conflits éventuels sont détectés et peuvent être résolus (écran + **Conflits**, `GET /api/conflicts`). + +### Tester hors-ligne + +1. DevTools (F12) → onglet **Network**. +2. Cochez **Offline**. +3. Rechargez : l'application doit fonctionner avec le cache. + +--- + +## 4. Notifications (Web Push) + +- Abonnement à partir de l'interface (permission navigateur requise). +- Endpoints : `GET /api/push/vapid-public-key`, + `POST /api/push/subscribe`, `DELETE /api/push/subscribe`, + `GET /api/push/subscriptions`. +- Les notifications sont signées **VAPID** et peuvent prévenir de changements + (collaboration, mises à jour). + +--- + +## 5. Mises à jour + +- Vérification régulière des mises à jour. +- Notification quand une nouvelle version est disponible. +- Mise à jour en un clic, **sans perte de données**. +- Le numéro `SW_VERSION` invalide l'ancien cache à chaque livraison. + +### Forcer une mise à jour (console) + +```javascript +navigator.serviceWorker.getRegistration().then(reg => reg.update()); +``` + +--- + +## 6. Débogage + +### Vérifier l'installation + +Chrome DevTools → onglet **Application** : + +- **Manifest** : métadonnées ; +- **Service Workers** : enregistrement ; +- **Cache Storage** : contenu du cache. + +### Désinstaller le Service Worker + +```javascript +navigator.serviceWorker.getRegistrations().then(regs => regs.forEach(r => r.unregister())); +``` + +--- + +## 7. Limites + +- Le hors-ligne dépend des données déjà mises en cache. +- Les actions d'écriture hors-ligne s'appliquent à la reconnexion (pas en temps + réel). +- iOS applique des contraintes spécifiques (persistance, notifications). + +Voir [Édition & collaboration](./COLLABORATION.md) pour le temps réel. diff --git a/docs/GUIDES/README.md b/docs/GUIDES/README.md new file mode 100644 index 0000000..f2c9571 --- /dev/null +++ b/docs/GUIDES/README.md @@ -0,0 +1,54 @@ +# 📚 Guides d'utilisation ObsiGate + +Bienvenue dans le répertoire des **guides utilisateur** d'ObsiGate. Chaque guide est +autonome, écrit en français et illustré d'exemples concrets (commandes, configuration, +captures conceptuelles). + +> **Vous découvrez ObsiGate ?** Commencez par le **[Guide de prise en main](./PRISE_EN_MAIN.md)**. +> Une aide rapide est aussi intégrée directement dans l'application (menu Options → +> **Guide d'utilisation**, FR/EN, téléchargeable en Markdown et PDF). + +--- + +## 🗂️ Sommaire des guides + +| Guide | Public | Contenu | +|---|---|---| +| 🚀 [Prise en main](./PRISE_EN_MAIN.md) | Tous | Premier lancement, interface, navigation, vaults, raccourcis | +| 🔍 [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) | Tous | Syntaxe de requête, recherche sémantique, lecteur PDF, diagrammes | +| 🤖 [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) | Tous | Fournisseurs, éditeur IA, BooksLM, Forge, commandes `@` / `/` | +| 📝 [Édition & collaboration](./COLLABORATION.md) | Tous | Édition simultanée, curseurs distants, persistance | +| 📱 [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md) | Tous | Installation PWA, cache, file de synchronisation, notifications | +| 🔌 [API REST](./API_REST.md) | Développeurs | Authentification, clés API, endpoints, exemples `curl`, SSE | +| 🧩 [Serveur MCP](./MCP.md) | Développeurs / IA | Brancher Claude Desktop, Cursor, Cline… sur vos vaults | +| 🔒 [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) | Admin | Utilisateurs, MFA, permissions par vault, bonnes pratiques | +| 🐳 [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) | Admin / Ops | `docker-compose`, volumes, reverse proxy, mises à jour | +| 🖥️ [Application desktop (Tauri)](./DESKTOP.md) | Tous | Installation, premier lancement, build depuis les sources | + +--- + +## 🧭 Par où commencer ? + +- **Je veux juste utiliser l'application** → [Prise en main](./PRISE_EN_MAIN.md) +- **Je veux sécuriser mon instance** → [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) +- **Je veux brancher une IA** → [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) puis [MCP](./MCP.md) +- **Je veux scripter/automatiser** → [API REST](./API_REST.md) +- **Je veux héberger sur un serveur** → [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) + +--- + +## 📖 Documentation associée + +| Type | Où | +|---|---| +| Vue d'ensemble produit | [`README.fr.md`](../../README.fr.md) · [`README.md`](../../README.md) | +| Conception détaillée par fonctionnalité | [`docs/features/`](../features/) | +| Standards de code | [`docs/CONTRIBUTING.md`](../CONTRIBUTING.md) | +| Méthode de livraison (Definition of Done) | [`docs/DELIVERY_WORKFLOW.md`](../DELIVERY_WORKFLOW.md) | +| Roadmap / travail à venir | [`docs/ROADMAP.md`](../ROADMAP.md) | +| Historique des versions | [`CHANGELOG.md`](../../CHANGELOG.md) | +| API interactive (Swagger / ReDoc) | `/docs` · `/redoc` (instance ObsiGate) | + +> **Convention :** ce répertoire est la **porte d'entrée utilisateur**. Le *comment* +> (utilisation) vit ici ; le *pourquoi* (conception technique) vit dans +> [`docs/features/`](../features/). Ne jamais dupliquer le détail technique des fiches. diff --git a/docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md b/docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md new file mode 100644 index 0000000..5a239f9 --- /dev/null +++ b/docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md @@ -0,0 +1,193 @@ +# 🔍 Guide Recherche, PDF & Excalidraw + +ObsiGate va au-delà de la simple lecture : recherche puissante, rendu des +documents riches (PDF, diagrammes) et indexation de leur contenu pour que tout +soit retrouvable. + +> **Public :** tous les utilisateurs +> **Fiches techniques :** [`features/semantic-search.md`](../features/semantic-search.md) · +> [`features/pdf.md`](../features/pdf.md) · [`features/excalidraw.md`](../features/excalidraw.md) + +--- + +## 1. Recherche plein texte (TF-IDF) + +Le moteur d'ObsiGate s'appuie sur un **index inversé** et un scoring **TF-IDF** +avec : + +- **Boost titre** — une correspondance dans le titre pèse 3× plus. +- **Normalisation des accents** — `resume` trouve `résumé`, `elephant` trouve `éléphant`. +- **Stemming français** — les variantes des mots sont rapprochées. +- **Snippets surlignés** — les termes trouvés sont mis en `` dans l'extrait. +- **Facettes** — compteurs par vault et par tag sur les résultats. +- **Pagination** — 50 résultats par page. +- **Tri** — par pertinence (TF-IDF) ou par date de modification. +- **Chips de filtres** — les filtres actifs apparaissent sous forme de puces retirables. +- **Historique** — les 50 dernières recherches sont conservées en `localStorage`. + +La recherche s'effectue **sans I/O disque** : le contenu est déjà en mémoire. + +--- + +## 2. Syntaxe de requête + +| Opérateur | Description | Exemple | +|---|---|---| +| `tag:` | Filtre par tag | `tag:recette docker` | +| `#` | Raccourci de tag | `#linux serveur` | +| `vault:` | Filtre par vault | `vault:IT kubernetes` | +| `title:` | Filtre par titre | `title:pizza` | +| `path:` | Filtre par chemin | `path:recettes/soupes` | +| `ext:` | Filtre par type de fichier | `ext:md kubernetes` | +| `"phrase exacte"` | Recherche d'une phrase | `tag:"multi mots"` | + +Les opérateurs sont **combinables** : + +```text +tag:linux vault:IT ext:md serveur web +``` + +Cette requête cherche « serveur web » dans les fichiers Markdown de la vault +`IT` portant le tag `linux`. + +### Filtres par extension + +| Extension | Contenu | +|---|---| +| `ext:md` | Notes Markdown | +| `ext:py`, `ext:sh`, `ext:js` | Scripts et code | +| `ext:pdf` | Documents PDF (texte extrait) | +| `ext:excalidraw` | Diagrammes Excalidraw (texte extrait) | + +--- + +## 3. Autocomplétion et suggestions + +- **`/api/suggest`** — suggère des titres de fichiers. +- **`/api/tags/suggest`** — suggère des tags. +- Navigation clavier : `↑` / `↓` puis `Entrée` ; `Échap` ferme les suggestions. + +### Raccourcis de recherche + +| Raccourci | Action | +|---|---| +| `Ctrl + K` / `Cmd + K` | Focaliser la barre de recherche | +| `/` | Focaliser la recherche (hors champ texte) | +| `↑` / `↓` | Naviguer dans les suggestions | +| `Entrée` | Sélectionner la suggestion active ou lancer la recherche | +| `Échap` | Fermer les suggestions / quitter la recherche | + +Recherches sauvegardées et signets sont disponibles via l'API +(`/api/saved-searches`, `/api/bookmarks`). + +--- + +## 4. Recherche sémantique (optionnelle) + +Au classement TF-IDF peut s'ajouter un classement **par embeddings**, fusionné +via la méthode **RRF** (Reciprocal Rank Fusion). Activation : touche `~` +(ou `Alt + S`) dans la recherche. + +Deux modes : + +1. **Sans dépendance** — un *embedder* par hachage fournit une base utilisable + immédiatement. +2. **Embeddings réels** — installez `backend/requirements-semantic.txt` et/ou + renseignez les variables `OBSIGATE_EMBEDDING_*` pour utiliser + `all-MiniLM-L6-v2`. + +Détails et configuration : +[`features/semantic-search.md`](../features/semantic-search.md). + +--- + +## 5. Support PDF + +### Lecture + +Les fichiers PDF de vos vaults s'affichent **en ligne** dans le navigateur via le +visualiseur PDF natif (iframe + ``). Le fichier est **streamé** en HTTP +Range (`206 Partial Content`) : les gros PDF se chargent progressivement. + +### Recherche + +Le texte est **extrait à l'indexation** (`pypdf` / `pymupdf`), donc le contenu +des PDF est recherchable via la recherche plein texte. Utilisez `ext:pdf` pour +limiter les résultats aux PDF. + +### Métadonnées + +`GET /api/file/{vault}/pdf/info` renvoie les métadonnées (pages, titre, auteur) +**sans transférer** le document. + +```bash +curl "http://localhost:2020/api/file/Recettes/pdf/info?path=menu.pdf" +``` + +### Limites + +- **Pas d'OCR** : les PDF scannés (images) ne sont pas recherchables. +- Pas d'annotation ni d'édition du PDF lui-même. + +--- + +## 6. Diagrammes Excalidraw + +Les fichiers `.excalidraw` et `.excalidraw.md` (dont le format compressé du +**plugin Obsidian Excalidraw**) s'ouvrent dans un **éditeur visuel Excalidraw +complet**, dans une iframe sandboxée. + +- **Dessin et édition** sans quitter ObsiGate. +- **Sauvegarde automatique** (débounce 2 s) ou `Ctrl + S`. +- **Thème** clair/sombre suivi automatiquement. +- **Texte indexé** : le texte des éléments du diagramme est extrait à + l'indexation et donc recherchable (`ext:excalidraw`). + +Fiche technique : [`features/excalidraw.md`](../features/excalidraw.md). + +--- + +## 7. Autres contenus riches + +### Mermaid + +Les blocs de code ` ```mermaid ` sont rendus en diagrammes interactifs (live +preview, thèmes, zoom, plein écran, pré-processeur compatible syntaxe Obsidian). + +### Images Obsidian + +Toutes les syntaxes d'images sont supportées avec résolution intelligente en +7 stratégies : + +1. chemin absolu ; +2. dossier d'attachements configuré (`VAULT_N_ATTACHMENTS_PATH`) ; +3. index de démarrage (correspondance unique) ; +4. même répertoire que la note ; +5. racine de la vault ; +6. index de démarrage (correspondance la plus proche) ; +7. repli : `[image not found: fichier.ext]`. + +Rescan manuel des attachements : + +```bash +curl -X POST "http://localhost:2020/api/attachments/rescan/Recettes" +``` + +### Graphe et backlinks + +- **Graphe** : vue force-directed (Barnes-Hut), filtres (tag, type), profondeur, + mode focus, export PNG, aperçu au survol (`Ctrl + clic`). +- **Backlinks** : `GET /api/file/{vault}/backlinks?path=…` liste les notes + pointant vers un document. + +--- + +## 8. Dépannage + +| Symptôme | Piste | +|---|---| +| Un PDF ne s'affiche pas | Vérifier la taille (`OBSIGATE_PDF_MAX_SIZE_MB`, défaut 50 Mo) | +| Le texte d'un PDF scanné n'est pas trouvé | Pas d'OCR : normal | +| Une image reste introuvable | Configurer `VAULT_N_ATTACHMENTS_PATH`, puis rescan | +| La recherche sémantique ne s'active pas | Vérifier le toggle `~` et `OBSIGATE_EMBEDDING_*` | +| Résultats obsolètes | Forcer une réindexation : `GET /api/index/reload` | diff --git a/docs/MCP_GUIDE.md b/docs/MCP_GUIDE.md index fc12059..ea14999 100644 --- a/docs/MCP_GUIDE.md +++ b/docs/MCP_GUIDE.md @@ -1,182 +1,10 @@ -# ObsiGate — Guide MCP (Model Context Protocol) +# Guide MCP — déplacé -> **Statut :** livré (#79 phase E + F) · **Dernière mise à jour :** 2026-09-11 -> **Voir aussi :** [AI_ARCHITECTURE_GUIDE.md](./AI_ARCHITECTURE_GUIDE.md) · -> [features/ai-tools-mcp.md](./features/ai-tools-mcp.md) · [ROADMAP.md](./ROADMAP.md) +> Ce guide a été déplacé dans le répertoire des guides utilisateur : +> **[docs/GUIDES/MCP.md](./GUIDES/MCP.md)**. -ObsiGate expose ses vaults à des **clients MCP externes** (Claude Desktop, Cursor, -tout client compatible MCP) via un serveur **Streamable HTTP** monté sur `/mcp`. -Les outils sont les **mêmes** que ceux de l'assistant in-app : la couche -`backend/tools/` est la source unique de vérité. +Le serveur MCP d'ObsiGate (`/mcp`) expose les mêmes outils que l'assistant IA à +Claude Desktop, Cursor, Cline et tout client compatible MCP. Configuration, +outils, resources/prompts, sécurité et dépannage s'y trouvent désormais. ---- - -## 1. Prérequis - -1. Une instance ObsiGate accessible (locale ou distante). -2. Un **jeton JWT** valide (`Authorization: Bearer `), obtenu via - `POST /api/auth/login` (ou une clé API). Le jeton porte les permissions par - vault de l'utilisateur — l'autorisation MCP réutilise `get_current_user`. -3. Si l'authentification est désactivée (`OBSIGATE_AUTH_ENABLED=false`), le - serveur MCP accepte un utilisateur anonyme disposant de tous les vaults. - -> Le transport `stdio` n'est **pas** encore supporté ; utilisez le transport -> HTTP (un pont local type `mcp-remote` si votre client ne gère pas nativement -> le Streamable HTTP distant). - ---- - -## 2. Endpoint & protocole - -| Élément | Valeur | -|---|---| -| URL | `https:///mcp` | -| Transport | Streamable HTTP (`POST` JSON-RPC 2.0, `Accept: application/json, text/event-stream`) | -| Auth | `Authorization: Bearer ` | -| Protocole MCP | `2025-03-26` (négocié à l'`initialize`) | -| Réponses | JSON (`json_response=True`) | - -Handshake minimal : - -```bash -curl -sS https://obsigate.example/mcp \ - -H "Authorization: Bearer $TOKEN" \ - -H "Accept: application/json, text/event-stream" \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{ - "protocolVersion":"2025-03-26","capabilities":{}, - "clientInfo":{"name":"curl","version":"1.0"}}}' -``` - -La réponse contient l'en-tête `Mcp-Session-Id` à réutiliser pour les appels -suivants (`tools/list`, `tools/call`, `resources/read`, …). - ---- - -## 3. Configuration des clients - -### Claude Desktop (via pont `mcp-remote`) - -```json -{ - "mcpServers": { - "obsigate": { - "command": "npx", - "args": [ - "-y", "mcp-remote", - "https://obsigate.example/mcp", - "--header", "Authorization: Bearer ${OBSIGATE_TOKEN}" - ], - "env": { "OBSIGATE_TOKEN": "eyJ..." } - } - } -} -``` - -### Cursor - -`.cursor/mcp.json` : - -```json -{ - "mcpServers": { - "obsigate": { - "url": "https://obsigate.example/mcp", - "headers": { "Authorization": "Bearer eyJ..." } - } - } -} -``` - ---- - -## 4. Primitives exposées - -### 4.1 Tools - -Les outils de **lecture/recherche** sont exposés directement. Les outils -**d'écriture/destructifs** sont exposés via une paire **two-step** : -`propose_` (aperçu + jeton de confirmation, aucune modification) puis -`apply_` (consomme le jeton et exécute). - -| Catégorie | Outils | -|---|---| -| Vaults / navigation | `list_vaults`, `list_directory`, `list_all_files` | -| Lecture | `read_file`, `read_file_raw`, `get_backlinks`, `list_backups`, `diff_backup`, `get_graph` | -| Recherche | `search_fulltext`, `search_advanced`, `search_paths`, `list_tags`, `suggest_tags`, `list_recent` | -| Écriture (propose/apply) | `create_file`, `create_directory`, `edit_file`, `append_to_file`, `restore_backup` | -| Destructif (propose/apply) | `rename_file`, `rename_directory`, `move_path`, `replace_in_files`, `delete_file`, `delete_directory` | - -Flux d'une mutation : - -```text -1. tools/call { name: "propose_edit_file", - arguments: { vault, path, content } } - → { tool, arguments, diff, confirmation_token, expires_in } - -2. (l'utilisateur / l'agent valide) - -3. tools/call { name: "apply_edit_file", - arguments: { confirmation_token } } - → { ok: true, data: { ... } } -``` - -Le jeton est **signé (JWT), à usage unique et à durée de vie limitée** -(`OBSIGATE_MCP_CONFIRMATION_TTL`, défaut 300 s). Un rejeu renvoie -`token_reused`. - -### 4.2 Resources - -| URI | Contenu | -|---|---| -| `vault://` | Vault accessible (métadonnées, nombre de fichiers) | -| `vault:///` | Contenu d'un fichier (lecture seule, **secrets redactés**) | - -### 4.3 Prompts - -`summarize-directory`, `generate-note`, `find-related`. - ---- - -## 5. Sécurité - -- **Permissions par vault** : `check_vault_access` est appliqué à chaque outil - et chaque resource ; un utilisateur ne voit que ses vaults. -- **Anti path-traversal** : `resolve_safe_path` rejette tout chemin hors du vault. -- **Confirmation two-step** pour toute mutation (jeton signé, usage unique). -- **Toggle par vault** `aiDestructiveTools` (défaut : activé) : le désactiver - bloque rename/move/replace/delete tout en laissant create/edit/append. -- **Backup automatique** avant chaque opération destructive. -- **Rate limiting** : par jeton et par outil - (`OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`, - `OBSIGATE_TOOL_RATE_WINDOW`). Une limite dépassée renvoie le code - `rate_limited`. -- **Redaction des secrets** : les résultats d'outils (lectures, diffs, - extraits de recherche) sont nettoyés avant tout retour au client. -- **Audit** : chaque appel est journalisé (`data/audit.log`, action - `ai_tool_call`) avec arguments sensibles résumés. - -### Variables d'environnement - -| Variable | Défaut | Rôle | -|---|---|---| -| `OBSIGATE_MCP_CONFIRMATION_TTL` | `300` | Durée de vie (s) des jetons de confirmation | -| `OBSIGATE_TOOL_RATE_LIMIT` | `60` | Appels d'outils max par identité et par fenêtre | -| `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL` | = global | Appels max par outil et par fenêtre | -| `OBSIGATE_TOOL_RATE_WINDOW` | `60` | Longueur de la fenêtre (s) | -| `BOOKSLM_MAX_TOOL_CALLS` | `25` | Quota d'appels d'outils par run d'agent | -| `BOOKSLM_MAX_TOOL_READ_BYTES` | `200000` | Taille max renvoyée par `read_file` | - ---- - -## 6. Dépannage - -| Symptôme | Cause probable / remède | -|---|---| -| `401 Authentification requise` | En-tête `Authorization: Bearer` absent ou jeton expiré | -| `vault_access_denied` | Le jeton n'a pas accès à ce vault (`vaults` / `_token_vaults`) | -| `destructive_tools_disabled` | `aiDestructiveTools=false` pour ce vault | -| `confirmation_required` | Appeler d'abord `propose_` puis `apply_` | -| `token_reused` / `invalid_confirmation` | Jeton déjà consommé ou expiré → refaire un `propose_` | -| `rate_limited` | Quota dépassé ; respecter `retry_after` | -| Le client ne se connecte pas | Vérifier le transport Streamable HTTP / le pont `mcp-remote` | +Sommaire des guides : [docs/GUIDES/README.md](./GUIDES/README.md). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 33003b6..2221051 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # ObsiGate — Roadmap -> **Version :** 2.16.5 | **Dernière mise à jour :** 2026-09-22 +> **Version :** 2.16.6 | **Dernière mise à jour :** 2026-09-22 > **Ce fichier ne contient que le travail à venir** (🔵 En cours + ⚪ Backlog) et un index compact > vers les fonctionnalités livrées. > - **Méthode de livraison à appliquer pour toute tâche : [DELIVERY_WORKFLOW.md](./DELIVERY_WORKFLOW.md)** diff --git a/docs/features/ai-tools-mcp.md b/docs/features/ai-tools-mcp.md index f21a67f..e45d29a 100644 --- a/docs/features/ai-tools-mcp.md +++ b/docs/features/ai-tools-mcp.md @@ -67,7 +67,7 @@ `call_tool` (couvre les diffs, extraits de recherche et lectures non pré-redactées). - [x] **F3.** Documentation OpenAPI + guide MCP — `backend/openapi_docs.py` : tag `MCP`, règle `/mcp`, injection du path `/mcp` (Streamable HTTP, JSON-RPC) dans le schéma ; - nouveau [`docs/MCP_GUIDE.md`](../MCP_GUIDE.md) (endpoint, auth, config Claude Desktop / + nouveau [`docs/GUIDES/MCP.md`](../GUIDES/MCP.md) (endpoint, auth, config Claude Desktop / Cursor, tools/resources/prompts, sécurité, variables, dépannage). - [x] **F4.** Tests E2E de bout en bout — `tests/test_ai_e2e.py` : agent in-app read→confirmation→write, quota d'outils, rate limiting, redaction, et flux MCP complet diff --git a/docs/images/obsigate-home.png b/docs/images/obsigate-home.png new file mode 100644 index 0000000..b9c6c7b Binary files /dev/null and b/docs/images/obsigate-home.png differ diff --git a/package.json b/package.json index f2203d8..a0628da 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "obsigate", - "version": "2.16.5", + "version": "2.16.6", "description": "**Porte d'entrée web ultra-léger pour vos vaults Obsidian** — Accédez, naviguez et recherchez dans toutes vos notes Obsidian depuis n'importe quel appareil via une interface web moderne et responsive.", "main": "patch.js", "directories": {