Tout ce qu'il faut pour
mettre Veilforge en route.

01

Démarrage rapide

Veilforge est une application Python (FastAPI) qui s'exécute en local. Aucune base externe n'est nécessaire : les correspondances sont stockées dans un fichier SQLite chiffré à côté du projet.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn veilforge.main:app --reload --port 8787

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn veilforge.main:app --reload --port 8787

02

Comment marche l'exemple

La démonstration de la page d'accueil exécute exactement deux appels à votre instance locale. Aucun modèle n'est sollicité : c'est le même mécanisme que la passerelle, isolé pour que vous puissiez le voir.

1. Mask — POST /api/v1/mask reçoit votre texte, détecte les valeurs sensibles, remplace chacune par un jeton et renvoie l'identifiant de session.
2. Transport — vous envoyeriez ce texte protégé au modèle. Dans la démonstration, le texte reste chez vous.
3. Unmask — POST /api/v1/unmask reçoit la réponse contenant les jetons, la même session, et rétablit les valeurs d'origine.

# 1) Masquage
curl -s http://localhost:8787/api/v1/mask \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Écrire à ana@example.com au +33 6 12 34 56 78"}'

# → {"masked_text":"Écrire à [[EMAIL_001]] au [[PHONE_001]]",
#     "session_id":"vf_...", "entities":[...]}

# 2) Restauration (même session)
curl -s http://localhost:8787/api/v1/unmask \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Réponse : [[EMAIL_001]] sera prévenu.","session_id":"vf_..."}'

# → {"text":"Réponse : ana@example.com sera prévenu.","unresolved":[]}

03

Passerelle compatible OpenAI

Veilforge implémente le contrat de /v1/chat/completions. Vous ne changez rien dans votre code : vous modifiez seulement l'URL de base et la clé.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8787/v1",
    api_key="local-dev-key",          # VEILFORGE_API_KEY
)

reponse = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user",
               "content": "Écris un mail à ana@example.com"}],
)
print(reponse.choices[0].message.content)

curl -s http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini",
       "messages":[{"role":"user","content":"Contact ana@example.com"}]}'

• Streaming — si "stream": true, les événements SSE sont transmis et démasqués à la volée ; l'en-tête X-Veilforge-Session renvoie la session utilisée.
• Session réutilisable — envoyez X-Veilforge-Session: vf_... pour conserver les mêmes jetons d'une requête à l'autre.
• Échec amont — en mode strict, une erreur du fournisseur renvoie 502 sans jamais restituer le texte protégé : la demande est refusée plutôt que risquée.
• Champ protégés — le masquage s'applique récursivement aux messages, aux schémas d'outils, aux arguments et aux résultats d'outils (chaînes uniquement), en ignorant model, role, stream, temperature et max_tokens.

04

Référence API

Toutes les routes /api/v1/* exigent l'en-tête Authorization: Bearer <VEILFORGE_API_KEY>. Le budget est de 120 requêtes par minute et par adresse IP. La page /api/v1/health et la racine sont exemptées.

Corps de requête commun

{
  "text": "Texte à analyser",
  "session_id": "vf_...",                  // optionnel : réutilise une session
  "custom_dictionary": {                   // optionnel : valeurs à protéger
    "CLIENT_INTERNE": ["nom de code Projet Sirius"]
  }
}

Réponse de POST /api/v1/mask

{
  "masked_text": "Écrire à [[EMAIL_001]] avant le [[DATE_OF_BIRTH_001]]",
  "session_id": "vf_Kd8s...",
  "entities": [
    {
      "type": "EMAIL",
      "placeholder": "[[EMAIL_001]]",
      "value": "ana@example.com",
      "start": 9,
      "end": 24,
      "confidence": 0.99,
      "source": "rules",
      "fingerprint": "1d420a5c0cf5948a"
    },
    {
      "type": "DATE_OF_BIRTH",
      "placeholder": "[[DATE_OF_BIRTH_001]]",
      "value": "12/07/1988",
      "start": 34,
      "end": 44,
      "confidence": 0.88,
      "source": "rules",
      "fingerprint": "7c19be03f8a41d55"
    }
  ]
}

05

Jetons & sessions

Un jeton a la forme [[TYPE_001]] : un type en majuscules, puis un numéro séquentiel sur trois chiffres, propre à chaque session.

06

Détection

Le détecteur par défaut repose sur des règles déterministes, vérifiables et rapides. Chaque entité est associée à un score de confiance ; les chevauchements sont résolus en gardant le span le plus fiable.

• Multilingue — indices en anglais, français, malgache, allemand et espagnol.
• Cas d'usage du dictionnaire — noms internes, codenames, clients récurrents : envoyez-les dans custom_dictionary pour un masquage certain.
• Étendre — branchez un NER local (spaCy, Presidio) en implémentant le protocole Detector : le reste de la chaîne ne change pas.
• Limite honnête — une détection par règles n'est pas une garantie de conformité. Faites toujours relire les sorties sensibles.

{
  "text": "Le client Projet Sirius demande un devis.",
  "custom_dictionary": {
    "CLIENT": ["Projet Sirius", "Compte Azurelion"]
  }
}

07

Configuration

Tout se règle par variables d'environnement, lues au démarrage du service.

VEILFORGE_API_KEY=change-me-in-production
VEILFORGE_ENCRYPTION_KEY=<python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())">
VEILFORGE_UPSTREAM_URL=https://api.openai.com/v1
VEILFORGE_UPSTREAM_API_KEY=sk-...
VEILFORGE_FAIL_CLOSED=true
VEILFORGE_RETENTION_HOURS=24

08

Sécurité

Le principe directeur : seul du contenu tokenisé franchit la frontière. Tout le reste reste sur la machine qui exécute le service.

Checklist de mise en production

1. Remplacer local-dev-key par une longue valeur aléatoire.
2. Définir VEILFORGE_ENCRYPTION_KEY et la conserver stable (gestionnaire de secrets).
3. Toujours VEILFORGE_FAIL_CLOSED=true.
4. Servir le service en HTTPS derrière un reverse proxy, exposé seulement à vos applications.
5. Choisir un VEILFORGE_DB_PATH sur un volume chiffré et sauvegardé.
6. Surveiller le journal d'audit (événements mask, unmask, upstream_error).
7. Relire les limites de la section Détection avant de déclarer une conformité.

09

Architecture

Le service est volontairement linéaire : un détecteur, un coffre de correspondances chiffré, une passerelle HTTP. Aucune donnée n'est envoyée à un tiers autre que le fournisseur que vous configurez.

client ─▶ Veilforge (détection + coffre chiffré) ─▶ fournisseur
client ◀─────────── restauration ◀──────────────── fournisseur

POST /v1/chat/completions
  1. création/réutilisation de la session
  2. masquage récursif du payload (messages, tools, results)
  3. transmission au fournisseur, ou écho marqué mock:true
  4. restauration de la réponse (y compris le flux SSE)
  5. audit : types, comptages, empreintes

Le code est organisé en trois modules : veilforge/detection.py (règles et protocole Detector), veilforge/vault.py (sessions, chiffrement, journal) et veilforge/main.py (routes FastAPI et passerelle).

10

Tests & Docker

python -m pytest -q
# 3 passed — détection, aller-retour masque/restauration, jetons inconnus

docker compose up --build
# service sur le port 8787, données dans le volume veilforge-data (/data)

Le conteneur expose le port 8787, place la base dans /data et redémarre automatiquement. Pensez à fournir un .env (le compose le lit) contenant les secrets décrits dans Configuration.

11

Questions fréquentes