Navin SM

La page Navin SM (/admin/navin-sm) remet le Navin (poste de travail et CLI) à votre personnel : elle rédige le fichier d'organisation que chaque poste lit, conserve les paquets de la version à distribuer, émet les clés virtuelles LiteLLM du personnel et suit leur usage. Navin SM ne tourne sur aucun nœud du cluster : c'est un logiciel de poste de travail (service navin-sm du catalogue, livraison « Distribuer aux postes de travail »), qui ne parle qu'à la passerelle LiteLLM de l'organisation. Les onglets Profils et Distribution demandent settings:manage ; choisir l'entrée du coffre d'une clé partagée ou d'un jeton GitHub demande aussi vault:manage ; les onglets Accès et Suivi demandent navin_sm:keys (rôles admin et security_admin). Les routes sont décrites dans la référence de l'API, étiquette navin-sm.

Les quatre onglets

Onglet	Ce qu'il fait	Permission
Profils	une ligne par organisation : nom et identifiant, passerelle, authentification, modèles et modèle par défaut, Exclusif ou non, Lié à le service LiteLLM installé. Éditeur, Aperçu, Exporter, Télécharger le bundle par système, Supprimer	settings:manage
Distribution	la version de Navin SM que nomme le catalogue, ses paquets (SHA256 publié, copie stockée, taille, Télécharger), Charger SHA256SUMS, Déposer un paquet, Récupérer depuis GitHub, les dernières récupérations et les chemins de déploiement	settings:manage (vault:manage pour GitHub)
Accès	les clés virtuelles LiteLLM d'un profil : titulaire, statut, modèles, budget, limites ; Émettre une clé, Modifier les limites, Bloquer, Débloquer, Révoquer, Tout révoquer	navin_sm:keys
Suivi	dépense, jetons, appels, erreurs et dernier usage des clés d'un profil sur une période, par clé et par modèle, lus depuis le proxy	navin_sm:keys

Chaque enregistrement, export, découverte, dépôt de paquet et opération sur une clé est écrit dans le journal d'audit (navin_sm.*, navin_sm.key.*, navin_sm.package.*), refus compris, jamais avec une clé ni un jeton.

Profils

Un profil est le managed-settings.json du contrat de passerelle d'organisation (version 1) : l'organisation (nom de 120 caractères au plus, contact du support de 200), la passerelle (adresse http ou https sans /chat/completions, authentification, en-têtes, autorité de certification), de 1 à 200 modèles (identifiant de 200 caractères au plus, libellé de 120), le modèle par défaut, les routes, le mode exclusif et la politique que Navin applique. Ces limites sont celles du lecteur de Navin : un profil que le Manager accepte est un fichier que Navin accepte.

• Lier à un LiteLLM installé reprend l'adresse d'un service LiteLLM installé par le Manager et garde le lien (litellm_cluster_id, litellm_service). Découvrir lit alors /v1/models et /model/info avec la clé maître du service, qui reste dans le serveur ; sans lien, saisissez une clé virtuelle utilisée pour ce seul appel. Le lien est aussi ce qui permet d'émettre les clés virtuelles (onglet Accès) et de lire le suivi.
• Utiliser l'autorité de certification du Manager fait pointer gateway.caBundle vers /etc/navin/navin-sm-ca.pem, /Library/Application Support/Navin/navin-sm-ca.pem ou C:\ProgramData\Navin\navin-sm-ca.pem, et le bundle embarque le PEM ; l'aperçu et l'export demandent alors le système cible. Exclusif avec un chemin de CA saisi.
• Aperçu montre le fichier tel que l'export l'écrira, vérifié par le contrat, sans sa clé (une clé partagée apparaît comme le nom de son entrée du coffre), avec les problèmes signalés et les chemins du fichier et de l'autorité pour le système choisi. Rien ne sort du serveur : l'aperçu n'est pas audité.
• Exporter télécharge le fichier ; la clé partagée n'est lue dans le coffre qu'à ce moment.

Authentification de la passerelle : Clé de chaque utilisateur (user_key, chaque poste saisit la clé virtuelle remise par l'onglet Accès), Clé partagée (shared_key, une seule clé pour tous, prise dans le coffre, écrite dans le fichier à l'export : déployez-le avec des droits restreints) ou Aucune (none, le proxy authentifie par le réseau).

Distribution et déploiement

Les paquets sont les fichiers de la version GitHub nommée par le catalogue (dépôt Navinspire-ia/navin-sm, étiquette v<version>) : RPM et DEB (bureau et CLI) pour Linux, DMG Apple silicon et Intel pour macOS, MSI (GPO, Intune) et setup.exe pour Windows, archives CLI par système. Un paquet n'est conservé que si son SHA256 est celui publié avec la version ; un fichier différent est refusé, supprimé et audité (navin_sm.package.store refusé). Au téléchargement, le Manager recalcule le SHA256 de la copie stockée : un fichier altéré sur son disque est retiré et refusé (navin_sm_package_corrupt, audit navin_sm.package.download refusé) ; redéposez-le ou récupérez-le de nouveau.

Deux chemins d'entrée :

1. Hors ligne : Charger SHA256SUMS (collez les lignes <sha256> <fichier> des fichiers SHA256SUMS et .sha256 de la version), puis Déposer un paquet fichier par fichier. Sans SHA256 publié chargé, donnez le SHA256 du fichier au dépôt.
2. Depuis GitHub : Récupérer depuis GitHub avec une entrée du coffre dont la clé API est un jeton GitHub lisant le dépôt. Le Manager télécharge les fichiers de sommes puis chaque paquet non encore stocké, chacun vérifié ; le jeton reste dans le serveur. L'onglet suit l'état de la récupération (en cours, terminée, échouée) fichier par fichier.

Le bundle d'un profil (bouton par système sur la ligne du profil) est un zip navin-sm-<org_id>-<os>.zip à traiter comme confidentiel (il peut contenir la clé partagée) :

Système	Contenu du bundle	Déploiement
Linux	README.md, managed-settings.json, navin-manager-ca.pem (si l'autorité du Manager est embarquée), install.sh (RPM ou DEB trouvé à côté), ansible/playbook.yml, ansible/inventory.ini	Ansible : ansible-playbook -i ansible/inventory.ini ansible/playbook.yml avec les paquets à côté du bundle ; ou install.sh en root
macOS	README.md, managed-settings.json, navin-manager-ca.pem (si embarquée), install.sh (DMG de l'architecture du Mac), mdm/README.md	MDM (Jamf Pro, Intune, Kandji, Mosyle) : paquet DMG et install.sh en script post-installation, ou distribution du fichier en /Library/Application Support/Navin/managed-settings.json
Windows	README.md, managed-settings.json, navin-manager-ca.pem (si embarquée), install.ps1 (MSI), gpo/README.md	GPO : installation logicielle assignée du MSI et préférence Fichiers vers C:\ProgramData\Navin\managed-settings.json ; Intune : application Win32 avec install.ps1

Chemins du fichier d'organisation : /etc/navin/managed-settings.json (Linux), /Library/Application Support/Navin/managed-settings.json (macOS), %ProgramData%\Navin\managed-settings.json (Windows). Un fichier déployé avec les droits du système ne peut pas être retiré par l'utilisateur et impose la politique. Sans déploiement par un administrateur, chaque utilisateur importe le fichier dans Navin, Réglages > Organisation > Importer (ou navin org import <fichier>) : seules l'organisation et la passerelle s'appliquent alors. Navin SM n'a ni télémétrie ni mise à jour automatique : une nouvelle version se déploie de la même façon.

Accès : cycle de vie d'une clé

L'onglet Accès demande un profil lié à un LiteLLM installé par le Manager : chaque appel au proxy porte la clé maître du service, lue dans le coffre par le serveur.

1. Émettre une clé à un utilisateur du Manager (recherche par nom, nom affiché ou courriel) ou à un groupe du fournisseur d'identité, avec les modèles permis (aucun coché : tous ceux du profil), un budget et sa période de remise à zéro (30d, 1mo), des jetons et des requêtes par minute. Le proxy crée la clé (/key/generate) ; sa valeur est montrée une seule fois : copiez-la et remettez-la par un canal sûr. Le Manager ne garde que l'alias (navin-sm.<org_id>.<titulaire>.<aléa>) et le sha256 de la clé, jamais la clé.
2. Modifier les limites change modèles, budget et limites au proxy (/key/update) puis dans le Manager.
3. Bloquer (/key/block) : le proxy refuse la clé aussitôt ; Débloquer la rend active.
4. Révoquer (/key/delete) : la clé est supprimée au proxy immédiatement et conservée ici comme révoquée, avec sa date. Tout révoquer le fait pour toutes les clés actives ou bloquées du profil en un appel.

Une clé que le proxy ne connaît plus est enregistrée comme révoquée et l'action est refusée (navin_sm_key_gone). Chaque opération est auditée (navin_sm.key.create|update|block|unblock|revoke|revoke_all) avec l'identifiant et l'alias de la clé, jamais sa valeur.

Suivi et ses limites

L'onglet Suivi lit le proxy par le serveur, sur la période choisie (1 à 366 jours, 30 par défaut) : pour chaque clé son état au proxy (/key/info : dépense, budget, remise à zéro, bloquée, supprimée), et sur la période ses appels, jetons, erreurs, modèles et dernier usage (/spend/logs) ; les mêmes chiffres par modèle et au total. La dépense est le chiffre que LiteLLM rapporte, dans son unité.

• Suivi indisponible : quand le profil n'est pas lié, que la clé maître manque ou que le proxy est injoignable, l'onglet le dit avec la raison et n'affiche aucun chiffre ; aucun zéro n'est inventé.
• Plafond de 10000 lignes : /spend/logs renvoie au plus 10000 lignes ; au-delà, l'onglet signale que les chiffres de la période sont un minimum. Réduisez la période pour un relevé complet.
• Les journaux sont ceux du proxy : une clé révoquée garde ses appels passés, une clé supprimée au proxy hors du Manager apparaît « supprimée au proxy ».

Vérifié contre LiteLLM

Le test tests/test_navin_sm_litellm_real.py démarre un vrai proxy LiteLLM OSS 1.106.5 avec sa base PostgreSQL et ses migrations, une clé maître aléatoire et un modèle factice (mock_response, sans amont), puis pilote une clé par le client du Manager. Il prouve que :

• /key/generate accepte le corps construit par le Manager (modèles, budget, budget_duration, jetons et requêtes par minute, métadonnées) et que le sha256 de la clé est bien le token que LiteLLM enregistre dans sa table ; la clé en clair n'y figure pas. Un alias en double et un budget négatif sont refusés (400) ; LiteLLM ne vérifie pas les modèles d'une clé contre sa liste, c'est le Manager qui le fait ;
• /key/update applique les nouvelles limites, et un null explicite les retire ;
• après /key/block, le proxy refuse la clé (401 sur /v1/models et /v1/chat/completions) ; après /key/unblock, il l'accepte de nouveau ;
• /key/generate ne crée pas l'utilisateur LiteLLM du titulaire : /user/info répond 404 tant que /user/new ne l'a pas créé ;
• /spend/logs rend une liste de lignes rattachées au sha256 de la clé ; les appels refusés y figurent aussi, avec le statut failure, et le Suivi les compte comme erreurs (un refus hors modèle, sur /v1/models, est compté sous sa route) ;
• /key/delete supprime les clés connues et renvoie la liste demandée, même avec un sha256 inconnu (404 seulement quand aucune n'existe) ; une clé supprimée reste lisible par /key/info avec le statut deleted, et tout autre appel sur elle répond 404, ce que le Manager lit comme « le proxy ne connaît plus la clé ».

Tâches courantes

1. Remettre Navin au personnel avec votre seule passerelle. Onglet Profils, Nouveau profil, Lier à un LiteLLM installé, Découvrir, choix des modèles et du modèle par défaut, Passerelle exclusive activée, Enregistrer, Aperçu pour le système cible, puis Télécharger le bundle.
2. Stocker les paquets. Onglet Distribution, Récupérer depuis GitHub (ou Charger SHA256SUMS puis Déposer un paquet hors ligne) ; placez les paquets téléchargés à côté des scripts du bundle.
3. Donner l'accès à une personne. Onglet Accès, profil, Émettre une clé, copie de la clé, remise par un canal sûr ; la personne la saisit dans Navin (mode user_key).
4. Retirer un accès. Onglet Accès, Bloquer (réversible) ou Révoquer ; Tout révoquer au départ d'une équipe ou en cas de fuite.

À décider côté Navin

Rien de ce qui suit n'est implémenté : c'est une proposition de contrat pour un inventaire des postes, à décider par l'équipe Navin. Aujourd'hui Navin n'a aucune télémétrie et aucune mise à jour automatique ; le Manager ne sait des postes que ce que LiteLLM rapporte des clés.

• Ce que Navin signalerait (et rien d'autre) : identifiant de l'organisation du fichier lu, version de Navin SM, système et architecture, empreinte SHA256 du managed-settings.json appliqué (pour détecter un fichier périmé), horodatage du dernier démarrage. Aucun contenu de conversation, aucun chemin de projet, aucune clé.
• Vers quel point d'accès : une route du Manager à créer, POST /api/v1/navin-sm/inventory (corps {org_id, version, os, arch, settings_sha256, started_at}), dont l'adresse serait écrite dans le fichier d'organisation par une nouvelle clé organization.inventoryUrl (version 2 du contrat, ignorée par les Navin actuels).
• Avec quelle identité : la clé virtuelle du poste (mode user_key), présentée au Manager qui la vérifie auprès de LiteLLM par son sha256 ; ou, en mode shared_key ou none, un certificat de poste émis par l'autorité du Manager. Jamais la clé maître.
• Activation : opt-in par l'organisation, dans le profil (Inventaire des postes désactivé par défaut) et donc dans le fichier déployé ; un Navin sans cette clé n'envoie rien. L'écran afficherait une ligne par poste (dernier signalement, version, fichier à jour ou non) et marquerait les postes silencieux depuis plus de 30 jours.