ESP32_ZACUS/AUDIT_QUICK_START.md

# ⚡ Quick Start – Audit Outputs (Lire en 5 min)

## 📋 TL;DR – Audit Complet en 3 Points

1. **🔴 Sécurité CRITIQUE**: WiFi creds en dur + 0 auth API → Fix cette semaine (2-3 days)
2. **🟡 Architecture MOYEN**: Race conditions (g_scenario), memory leak (audio) → Fix semaine 1-2
3. **🟢 Tests ABSENT**: 0 unit tests C++ → Ajouter semaine 3-4 (40h)

**Verdict**: ⚠️ NOT PRODUCTION READY sans semaine 1.

---

## 📁 Fichiers Rapport Générés

| Fichier | Taille | Audience | Lire si |
|---------|--------|----------|---------|
| `AUDIT_COMPLET_2026-03-01.md` | 15KB | Tech Lead, Senior Dev | Veux comprendre détails profonds |
| `PLAN_ACTION_SEMAINE1.md` | 12KB | Dev assigné | Besoin d'action concrète jour par jour |
| `SECURITY_AUDIT_REPORT.json` | 8KB | Security Team | Analyse vuln structurée |
| `REMEDIATION_GUIDE.md` | 10KB | Dev | Code samples + timetable |
| `RISK_ANALYSIS.md` | 9KB | Management | Timeline business impact |

**👉 Commence par**: `PLAN_ACTION_SEMAINE1.md`

---

## 🚨 Top3 Issues à Fixer IMMÉDIATEMENT

### Issue #1: WiFi Credentials Hardcoded 🔴 CRITIQUE
**Fichier**: `data/story/apps/APP_WIFI.json`  
**Problem**: SSID + password en texte clair = device contrôlable par n'importe qui  
**Fix** (1h):
```bash
# Éditer le fichier et remplacer par placeholders
vi data/story/apps/APP_WIFI.json
# Changer "Les cils" → "YOUR_SSID" et "mascarade" → "YOUR_PASSWORD"
git commit -m "Security: Remove hardcoded WiFi credentials"
```
**Status**: 🟠 URGENT

---

### Issue #2: API Sans Authentication 🔴 CRITIQUE  
**Files**: `ui_freenove_allinone/src/main.cpp` (~40 endpoints `/api/*`)  
**Problem**: Endpoints acceptent n'importe quelle requête  
**Fix** (4h):
```cpp
// Ajouter dans CHAQUE endpoint:
if (request->header("Authorization") != "Bearer " + g_auth_token) {
  request->send(401, "text/plain", "Unauthorized");
  return;
}
```
**Status**: 🟠 URGENT

---

### Issue #3: Audio Memory Leak 🔴 HAUT
**File**: `ui_freenove_allinone/src/audio_manager.cpp:159-160`  
**Problem**: Raw `new` sans garantie cleanup  
**Fix** (3h):
```cpp
// AVANT (BUG):
AudioFileSource* source = new AudioFileSource(...);
AudioGenerator* decoder = new AudioGenerator(...);

// APRÈS (FIX):
auto source = std::make_unique<AudioFileSource>(...);
auto decoder = std::make_unique<AudioGenerator>(...);
```
**Status**: 🟠 URGENT

---

## 📊 Risques par Catégorie

### 🔴 CRITICAL (Fix ce weekend)
- [ ] WiFi credentials → Remove
- [ ] API auth → Add Bearer token check
- [ ] Watchdog timer → Add esp_task_wdt_init()

### 🟡 HIGH (Fix semaine 1)
- [ ] Audio memory leak → unique_ptr
- [ ] Race conditions (g_scenario) → Add mutex
- [ ] LVGL non-reentrant → Dedicate core
- [ ] handleSerialCommand() 50+ cases → Refactor to command map

### 🟢 MEDIUM (Fix semaine 2-3)
- [ ] Buffer overflow (serial) → Add size validation
- [ ] Path traversal → Whitelist paths
- [ ] JSON parsing → Add size limits + schema validation
- [ ] No watchdog → Add TWDT

### 🔵 LOW (Fix semaine 4+)
- [ ] Memory fragmentation → Use pool allocator
- [ ] No tests (C++) → Setup gtest
- [ ] Docs outdated → Update ARCHITECTURE.md

---

## 🎯 Action Items – Copier/Coller

### Aujourd'hui (30 min) – Audit Review
```bash
# Clone le repo localement
cd ~/Documents/Lelectron_rare/ESP32_ZACUS

# Lire les rapports
cat AUDIT_COMPLET_2026-03-01.md | head -100  # Vue générale
cat PLAN_ACTION_SEMAINE1.md | grep "LUNDI" -A 20  # Commencer lundi

# Identifier issues dans le code
grep -r "server.on.*api" ui_freenove_allinone/src/main.cpp | wc -l
# Output: 40+ endpoints sans auth

grep -n "new AudioFileSource\|new AudioGenerator" ui_freenove_allinone/src/audio_manager.cpp
# Output: Lines 159-160 are vulnerable
```

### Demain (2h) – Sécurité
```bash
# Commit 1: WiFi credentials
vi data/story/apps/APP_WIFI.json
# Replace "Les cils" & "mascarade" with placeholders
git add .
git commit -m "Security: Remove hardcoded WiFi credentials"

# Commit 2: API Auth
# Edit main.cpp, add auth check in handlers
# (See PLAN_ACTION_SEMAINE1.md, MARDI section for details)
git commit -m "Feature: Bearer token authentication for web API"

# Commit 3: Watchdog
# Edit main.cpp setup(), add TWDT init
git commit -m "Feature: Add ESP32 Task Watchdog Timer"
```

### Semaine 1 (40h) – Roadmap
```bash
# Each day, follow PLAN_ACTION_SEMAINE1.md schedule
# LUN: Security + Watchdog (3 commits)
# MAR: Audio leak + Mutex + Buffer (3 commits)
# WED: Path traversal + Serial refactor (2 commits)
# JEU: JSON validation + Telemetry + Docs (3 commits)
# VEN: Integration test + Code review (1 commit)

# Total: ~12 commits, ~40 hours, 3 P0/P1 fixes
```

---

## 🔍 How to Read Audit Report

### If you have 5 min:
→ Read: "Executive Summary" section of AUDIT_COMPLET_2026-03-01.md

### If you have 15 min:
→ Read: AUDIT_COMPLET_2026-03-01.md sections:
- Executive Summary
- Top 10 Risks Consolidated
- Roadmap Remediation (Phase 1)

### If you have 60 min:
→ Read: AUDIT_COMPLET_2026-03-01.md fully (all 5 audit sections)

### If you want action items:
→ Read: PLAN_ACTION_SEMAINE1.md with todo checkboxes

### If you're security-focused:
→ Read: SECURITY_AUDIT_REPORT.json + REMEDIATION_GUIDE.md

### If you're managing timeline:
→ Read: RISK_ANALYSIS.md + Roadmap Remediation phases

---

## 🧪 Testing Current Build

```bash
# Build (current = should work, but has issues)
pio clean
pio run -e freenove_esp32s3_full_with_ui
pio run -e freenove_esp32s3_full_with_ui -t buildfs
pio run -e freenove_esp32s3_full_with_ui -t uploadfs --upload-port /dev/cu.usbmodem5AB907*
pio run -e freenove_esp32s3_full_with_ui -t upload --upload-port /dev/cu.usbmodem5AB907*

# Test scenarios (python serial)
python lib/zacus_story_portable/test_story_4scenarios.py --port /dev/cu.usbmodem5AB907*

# Check for known issues
# 1. Look for "ERR" or "PANIC" in serial output
# 2. Check if reboot loop occurs (known issue)
# 3. Verify task watchdog NOT in logs (we'll add it)
```

---

## 📞 Questions Fréquentes

**Q: Par où commencer?**  
A: PLAN_ACTION_SEMAINE1.md, lundi, section "Audit + Triage"

**Q: Combien de temps pour corriger tout?**  
A: 6 semaines (P0=1w, P1=1w, P2=2w, P3=2w)

**Q: Peut-on détoyer en production maintenant?**  
A: ❌ Non, abandon WiFi creds + API auth minimum avant production

**Q: Qui doit faire quoi?**  
A: Voir AUDIT_COMPLET_2026-03-01.md, section "ROADMAP", column "Owner"

**Q: Teste-t-on avant chaque commit?**  
A: Oui, PLAN_ACTION_SEMAINE1.md mentionne tests par jour

**Q: Peut-on faire en parallèle?**  
A: Partiellement. Day 1-2 sécurité + stabilité en parallèle (2 devs), Day 3+ séquentiellement

---

## 📈 Success Metrics (End of Week 1)

```
Day 1 (LUN):
  ✅ 3 commits (WiFi, Auth, Watchdog)
  ✅ 0 new security issues
  
Day 2 (MAR):
  ✅ Audio leak fixed
  ✅ Race conditions identified
  ✅ 3 commits merged
  
Day 3 (WED):
  ✅ handleSerialCommand() cyclo < 20
  ✅ Path traversal fixed
  ✅ 2 commits merged
  
Day 4 (JEU):
  ✅ JSON validation added
  ✅ Telemetry task running
  ✅ Docs created (3 files)
  ✅ 3 commits merged
  
Day 5 (VEN):
  ✅ Tests passing (4 scenarios x10 = no crash)
  ✅ Memory stable (>80KB free internal heap)
  ✅ API requires Bearer token
  ✅ PR ready for review
  ✅ 1 final commit
```

**Grand Total**: 12+ commits, 40h effort, 3 critical issues fixed, production-ready baseline

---

## 🎓 Learning Resources

### Security
- [OWASP Embedded](https://owasp.org/www-project-embedded-application-security/)
- [ESP32 Security](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/)

### Architecture
- [Effective C++ (Modern C++)](https://en.cppreference.com/)
- [Design Patterns for Embedded](https://en.wikipedia.org/wiki/Design_Patterns)

### Testing
- [Google Test Framework](https://github.com/google/googletest)
- [Arduino Testing](https://github.com/mmurdoch/arduinounit)

### FreeRTOS
- [Task Watchdog Timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/wdts.html)
- [Mutex & Sync Primitives](https://www.freertos.org/Real-time-embedded-RTOS-kernels.html)

---

## 🚀 PRX Steps (After Week 1)

1. **Code Review** (2h)
   - Senior dev reviews 12 commits
   - Security team spot-checks Bearer token impl
   
2. **Merge to Main**
   - Create feature branch: `security/critical-fixes`
   - All CI checks pass
   - Tag: `v1.1.0-security`

3. **Phase 2 Planning**
   - LVGL re-entrancy (core dedication)
   - Network async state machine
   - Unit test framework setup (gtest)

4. **Release Notes**
   ```
   ## v1.1.0-security (2026-03-08)
   
   ### Security Fixes 🔐
   - Removed hardcoded WiFi credentials
   - Added Bearer token auth to all API endpoints
   - Fixed serial buffer overflow
   - Added path traversal validation
   - JSON schema validation with size limits
   
   ### Stability Fixes ⚙️
   - Fixed audio memory leak (unique_ptr)
   - Added mutex protection for global state
   - Implemented ESP32 Task Watchdog Timer
   - Added memory telemetry task
   
   ### Code Quality 📝
   - Refactored handleSerialCommand() (50+ cases → command map)
   - Added ARCHITECTURE.md, SECURITY.md docs
   - Integration tests for auth + memory stability
   
   **Status**: ✅ Production-Ready
   ```

---

**Tu as besoin d'aide pour démarrer? Demande moi de créer un code snippet ou un premier commit template.** 💪