Repository Public
1# Sécurité — MacLustr LLM API23## Surface exposée45| Élément | Exposition |6|---|---|7| `https://llm.spboucher.ai` | publique, TLS terminé par Caddy sur la passerelle du cluster (Let's Encrypt), HSTS |8| Documentation, statut (`/`, `/docs`, `/status`, `/api/status`, `/openapi.json`) | publics, sans donnée interne |9| API `/v1/*` | clé API Bearer obligatoire (ou session admin + CSRF pour le Playground) |10| Dashboard `/admin/api/*` | session Passkey obligatoire ; la coquille HTML `/admin` ne contient aucune donnée |11| Activation `/setup/<jeton>`, `/api/setup/*` | jeton à usage unique généré localement |12| Passerelle `:8810` | LAN + interface WireGuard du tunnel ; toutes ses routes sont celles ci-dessus |13| Moteur MLX `:8811` | **bouclage uniquement** (`127.0.0.1`), refus de démarrer sur une autre adresse |1415## Clés API1617- Format `mlx_sk_<8 hex>_<43 caractères>` : 256 bits d'aléa (`secrets.token_urlsafe(32)`).18- Seul un **HMAC-SHA-256 à clé serveur** est stocké (`api_keys.key_hash`) ; la clé serveur (`secret.key`, 3219 octets, mode 600) est hors dépôt et hors base. Un KDF lent n'apporterait rien pour un secret de 256 bits.20- Le secret n'est affiché qu'une fois, à la création ou à la rotation (réponse `Cache-Control: no-store`).21- Par clé : modèles et endpoints autorisés, classe de priorité, requêtes/min, tokens/min, quotas quotidien et22 mensuel, concurrence maximale, date d'expiration, désactivation, révocation, rotation atomique.23- Tentatives avec clés invalides : freinées par IP (30/min → 429 `too_many_attempts`).2425## Administration par Passkey (WebAuthn / FIDO2)2627- Aucun mot de passe, aucun code PIN applicatif, aucun nom d'utilisateur : identifiants découvrables28 (`residentKey: required`), **vérification utilisateur exigée** (`userVerification: required`) → Touch ID,29 Face ID ou code de l'appareil, gérés par le système. Le serveur ne reçoit qu'une signature et ne stocke30 qu'une clé publique ; aucune donnée biométrique ne quitte l'appareil.31- Vérifications serveur (bibliothèque `webauthn`) : défi, origine (`https://llm.spboucher.ai`), identifiant32 de partie de confiance, signature, drapeau de vérification utilisateur, compteur de signatures.33- Défis : aléatoires, liés à leur usage (activation, connexion, ré-authentification), valables 5 minutes,34 **consommés en transaction** — une réponse rejouée est refusée.35- Passkeys synchronisées (trousseau iCloud) acceptées et signalées comme telles ; plusieurs Passkeys possibles ;36 la dernière ne peut pas être supprimée.3738### Lien d'activation à usage unique3940`maclustr-llm setup-link` (à lancer sur le Mac mini) :4142- jeton de 256 bits, **stocké sous forme de condensat**, valable **15 minutes**, **usage unique** ;43- affiché dans le terminal seulement — jamais écrit dans un fichier, un journal ou Git ;44- un nouveau lien invalide les précédents ; un lien d'activation est refusé si un administrateur existe déjà ;45- l'enregistrement de la Passkey, la création de l'administrateur et l'invalidation du lien se font dans **une46 seule transaction** ; l'unicité de l'administrateur est en plus garantie par une contrainte de la base ;47- le chemin `/setup/…` est masqué dans le journal de la passerelle et exclu du journal d'accès du proxy public ;48 la page est servie avec `Cache-Control: no-store` et `Referrer-Policy: no-referrer`.4950### Récupération5152`maclustr-llm recover` — même mécanisme, exige un accès réel au Mac mini (SSH ou clavier). Le lien permet53d'ajouter une nouvelle Passkey au compte existant et **révoque toutes les sessions**. Il n'existe aucune54route web de récupération.5556## Sessions5758| Mesure | Mise en œuvre |59|---|---|60| Cookie | `__Host-mllm_session` : `HttpOnly`, `Secure`, `SameSite=Strict`, `Path=/`, sans domaine |61| Identifiant | 256 bits aléatoires, stocké haché ; **nouveau à chaque authentification** |62| Durée | 7 jours au plus, 12 h d'inactivité |63| CSRF | jeton distinct (en-tête `X-CSRF-Token`) exigé sur toute requête non-GET, renouvelé à chaque lecture de session ; `Origin` étranger refusé |64| Authentification récente | création / rotation / révocation de clé, ajout / suppression de Passkey, rechargement du moteur, révocation globale → Passkey datant de moins de 5 minutes, sinon 401 `reauth_required` |65| Révocation | déconnexion, « révoquer les autres sessions », `maclustr-llm revoke-sessions` en local |66| Force brute | routes d'authentification et d'activation freinées par IP (20 essais / 5 min) |67| Permissions | vérifiées côté serveur sur chaque route ; une clé API ne donne jamais accès à l'administration |6869## En-têtes et navigateur7071`Content-Security-Policy` stricte (`script-src 'self'`, aucun script en ligne, aucune ressource externe),72`Strict-Transport-Security`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`,73`Referrer-Policy: no-referrer`, `Permissions-Policy`. CORS ouvert **sans credentials** sur `/v1` seulement74(authentification par jeton, jamais par cookie cross-origin).7576## Protection contre les abus et la surcharge7778Taille du corps bornée (4 Mo), nombre de messages borné, fenêtre de contexte vérifiée avec le tokenizer du79modèle avant d'atteindre le moteur, `max_tokens` plafonné, délais (file, premier token, génération), file80bornée, budget de tokens en vol, garde sur la pression mémoire. Les messages d'erreur du moteur sont réduits81à leur première ligne (pas de chemin ni de trace).8283## Journalisation et conservation8485| Donnée | Où | Conservation |86|---|---|---|87| Prompts, réponses | nulle part | — |88| Journal d'accès de la passerelle (méthode, chemin sans jeton, statut, durée, identifiant) | `~/maclustr-llm-data/logs/gateway.log` | rotation 5 × 20 Mo |89| Journal du moteur (progression, sans contenu) | `logs/engine.log` | rotation 5 × 20 Mo |90| Métadonnées par requête | `request_log` | 30 jours |91| Agrégats d'usage par minute | `usage_minute` | 400 jours |92| Échantillons système | `sys_samples` | 7 jours |93| Journal d'audit administratif | `audit_log` | conservé |9495Événements audités : activation, récupération, connexions réussies et échouées, ré-authentifications,96déconnexions, ajout / suppression de Passkey, création / modification / rotation / révocation de clé,97rechargement du moteur, révocation globale, création de liens.9899## Tests de sécurité automatisés (`tests/test_auth.py`, `tests/test_api.py`)100101Dashboard fermé sans session (toutes les routes) · une clé API n'ouvre pas l'administration · lien à usage102unique, expirant, invalidé par le suivant · activation atomique · origine WebAuthn falsifiée refusée ·103signature falsifiée refusée · défi non rejouable · identifiant de session renouvelé et haché · CSRF et104`Origin` · authentification récente · cycle de vie des clés · révocation globale · récupération qui révoque105les sessions · freins anti-force-brute · **aucun secret ni prompt au repos** (base et journaux fouillés) ·106permissions des fichiers.107108## Limites connues109110- Le pare-feu applicatif de macOS est désactivé sur le nœud (état trouvé à l'audit, commun au cluster) ; la111 protection repose sur l'écoute en bouclage du moteur, l'authentification de toutes les routes de la112 passerelle et le routeur du LAN.113- Pas d'audit de sécurité indépendant ni de test d'intrusion externe.114- Le terminal TLS est la passerelle du cluster (BHS64) : le trafic y est en clair avant de repartir chiffré115 dans WireGuard vers le Mac mini.116