# 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