Claude Add complete API files with filesystem endpoints

README.md

@@ -0,0 +1,212 @@
+# Jetson Agent API
+
+API middleware sécurisée pour accès lecture aux fichiers du Jetson Nano.
+
+## 📋 Description
+
+Cette API permet un accès sécurisé et contrôlé aux fichiers du Jetson Nano, principalement pour permettre à des LLMs (Claude, Gemini, etc.) de lire et analyser les fichiers de l'application web mathématiques.
+
+## ✨ Fonctionnalités
+
+- ✅ **Lecture de fichiers** sécurisée avec validation de chemins
+- ✅ **Listing de répertoires** avec support récursif
+- ✅ **Arborescence** (tree) de dossiers
+- ✅ **Recherche** (grep) dans les fichiers
+- ✅ **Validation** d'extensions et tailles de fichiers
+- ✅ **API REST** avec documentation Swagger intégrée
+
+## 🚀 Installation
+
+### Prérequis
+
+- Python 3.11+
+- pip
+- Git
+
+### Installation rapide
+
+```bash
+# Se positionner dans le projet
+cd ~/projects/jetson-agent
+
+# Créer environnement virtuel
+python3 -m venv .venv
+
+# Activer l'environnement
+source .venv/bin/activate
+
+# Installer les dépendances
+pip install -r requirements.txt
+```
+
+## ⚙️ Configuration
+
+### 1. Créer le fichier .env
+
+```bash
+# Copier l'exemple
+cp config/example.env .env
+
+# Générer une clé secrète JWT
+openssl rand -hex 32
+
+# Éditer .env et remplacer JWT_SECRET_KEY par la clé générée
+nano .env
+```
+
+### 2. Adapter les chemins autorisés
+
+Éditer `config/allowed_paths.yaml` pour ajouter/retirer des chemins :
+
+```yaml
+allowed_read_paths:
+  - /var/www/mathematiques
+  - /var/www/html
+  # Ajouter d'autres chemins si nécessaire
+```
+
+## 🏃 Lancement
+
+### Mode développement
+
+```bash
+# Activer l'environnement
+source .venv/bin/activate
+
+# Lancer l'API
+cd src
+uvicorn jetson_agent.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+L'API est accessible sur : `http://localhost:8000`
+
+Documentation Swagger : `http://localhost:8000/docs`
+
+### Mode production (avec systemd)
+
+Créer un service systemd (à venir).
+
+## 📚 Utilisation de l'API
+
+### Endpoints disponibles
+
+#### 1. Lister les fichiers d'un dossier
+
+```bash
+GET /api/files/list?path=/var/www/mathematiques
+
+# Avec récursion
+GET /api/files/list?path=/var/www/mathematiques&recursive=true&max_depth=3
+```
+
+#### 2. Lire un fichier
+
+```bash
+GET /api/files/read?path=/var/www/mathematiques/index.php
+```
+
+#### 3. Arborescence (tree)
+
+```bash
+GET /api/files/tree?path=/var/www/mathematiques&max_depth=5
+```
+
+#### 4. Rechercher dans les fichiers (grep)
+
+```bash
+GET /api/files/grep?path=/var/www/mathematiques&pattern=function&file_pattern=*.php
+```
+
+### Exemples avec curl
+
+```bash
+# Health check
+curl http://localhost:8000/api/health
+
+# Lister fichiers
+curl "http://localhost:8000/api/files/list?path=/var/www/mathematiques"
+
+# Lire un fichier
+curl "http://localhost:8000/api/files/read?path=/var/www/mathematiques/index.php"
+
+# Arborescence
+curl "http://localhost:8000/api/files/tree?path=/var/www/mathematiques&max_depth=3"
+
+# Recherche
+curl "http://localhost:8000/api/files/grep?path=/var/www/mathematiques&pattern=mysql&file_pattern=*.php"
+```
+
+## 🔐 Sécurité
+
+### Chemins autorisés
+
+L'API n'autorise l'accès qu'aux chemins définis dans `config/allowed_paths.yaml`.
+
+### Validation
+
+- ✅ Pas de traversal de chemin (`..`)
+- ✅ Blocklist de chemins sensibles (`/etc`, `/root`, etc.)
+- ✅ Validation d'extensions de fichiers
+- ✅ Limite de taille de fichiers (10 MB par défaut)
+- ✅ Limite du nombre de résultats
+
+### Recommandations
+
+- [ ] Utiliser HTTPS en production (via nginx reverse proxy)
+- [ ] Configurer un pare-feu (UFW)
+- [ ] Limiter l'accès IP si possible
+- [ ] Activer l'authentification JWT (à venir)
+
+## 📁 Structure du projet
+
+```
+jetson-agent/
+├── src/
+│   └── jetson_agent/
+│       ├── __init__.py
+│       ├── main.py              # Point d'entrée FastAPI
+│       ├── config.py            # Configuration
+│       ├── path_validator.py   # Validation de chemins
+│       └── api/
+│           ├── __init__.py
+│           └── filesystem.py   # Endpoints fichiers
+├── config/
+│   ├── example.env
+│   └── allowed_paths.yaml
+├── tests/                       # Tests (à venir)
+├── requirements.txt
+└── README.md
+```
+
+## 🧪 Tests
+
+```bash
+# Installer les dépendances de dev
+pip install pytest pytest-asyncio httpx
+
+# Lancer les tests (à venir)
+pytest
+```
+
+## 📝 TODO / Roadmap
+
+- [ ] Authentification JWT
+- [ ] Endpoints base de données (lecture MariaDB)
+- [ ] Rate limiting
+- [ ] Logs structurés
+- [ ] Tests unitaires
+- [ ] Déploiement systemd
+- [ ] Documentation API complète
+- [ ] Support GPIO (lecture/écriture pins)
+
+## 🤝 Contribution
+
+Projet personnel pour contrôle du Jetson Nano via LLM.
+
+## 📄 Licence
+
+Privé - Usage personnel
+
+## 👤 Auteur
+
+Nicolas - 2025