Full web : fichiers restants

docs/api-pve.md

@@ -1,12 +1,18 @@
 # API Proxmox VE 9.x utilisée par pve-confsync
 
-Vérifiée le 2026-10-13 dans les sources Proxmox (miroirs GitHub officiels), faute d'accès
+Vérifiée le 2026-10-13 (comptes : 2026-10-23) dans les sources Proxmox (miroirs GitHub officiels), faute d'accès
 à l'API viewer (https://pve.proxmox.com/pve-docs/api-viewer/) depuis l'environnement de
 développement. Versions lues : pve-manager 9.2.21, libpve-network-perl 1.6.7, pve-cluster 9.1.6.
 **À recouper avec l'API viewer et les deux clusters de labo avant la phase 1.**
 
-Toutes les routes sont relatives à `/api2/json`. Authentification : en-tête
-`Authorization: PVEAPIToken=USER@REALM!TOKENID=SECRET`. Écritures en
+Toutes les routes sont relatives à `/api2/json`. Authentification par ticket du compte
+`root@pam` : `POST /access/ticket` (`username`, `password`) renvoie `ticket` et
+`CSRFPreventionToken` ([AccessControl.pm L198](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/AccessControl.pm#L198)) ; le ticket
+est envoyé dans le cookie `PVEAuthCookie`, le jeton CSRF dans l'en-tête
+`CSRFPreventionToken` sur les écritures. Durée de vie du ticket : 2 h
+([AccessControl.pm L58](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/AccessControl.pm#L58)) ; pve-confsync se reconnecte après 90 min
+ou sur un 401. Un compte root avec TFA renvoie `NeedTFA`
+([L167](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/AccessControl.pm#L167)) : refusé. Écritures en
 `application/x-www-form-urlencoded` (tableaux = paramètre répété), suppression de champs
 via le paramètre `delete=a,b`.
 
@@ -17,7 +23,6 @@ via le paramètre `delete=a,b`.
 | GET | `/cluster/status` | nœuds en ligne | Sys.Audit sur / |
 | GET | `/nodes/{node}/version` | `version` (9.2.21), `release` (9.2) : refus si majeur ≠ 9 | — |
 | GET | `/version` | repli pour un nœud isolé ([API2.pm](https://github.com/proxmox/pve-manager/blob/9c3f5e5258f73f31e273493232a79d615fd9e072/PVE/API2.pm#L86)) | — |
-| GET | `/access/permissions` | droits effectifs du token (`check`) ([AccessControl.pm](https://github.com/proxmox/pve-access-control/blob/master/src/PVE/API2/AccessControl.pm#L510)) | — |
 | GET | `/nodes/{node}/tasks/{upid}/status` | suivi de la tâche de rechargement SDN | — |
 
 ## Options datacenter (`datacenter.cfg`)
@@ -77,9 +82,29 @@ Champs (schémas : [VlanPlugin.pm](https://github.com/proxmox/pve-network/blob/c
 - subnet : `vnet`, `gateway`, `snat`, `dnszoneprefix`, `dhcp-range` (tableau), `dhcp-dns-server`
 - calculés par PVE, ignorés : `digest`, `state`, `pending`, et pour les subnets `cidr`, `network`, `mask`, `zone`
 
-## Droits minimaux
+## Comptes du royaume pve (vérifié le 2026-10-23, pve-access-control dff26b45, pve-cluster 86d4bb9e)
 
-- **Référence** (lecture seule) : rôle avec `Sys.Audit` + `SDN.Audit` sur `/`.
-- **Clients** : `Sys.Audit` + `SDN.Audit` + `SDN.Allocate` sur `/` (ou `/sdn`) ;
-  `Sys.Modify` sur `/` uniquement si les options datacenter sont synchronisées
-  (`PUT /cluster/options` n'a pas de droit plus fin).
+| Objet | Liste / création | Élément | Notes |
+|---|---|---|---|
+| groupe | `/access/groups` ([Group.pm L26](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/Group.pm#L26)) | `/access/groups/{groupid}` | champ `comment` ; `users` calculé, ignoré |
+| rôle | `/access/roles` ([Role.pm L31](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/Role.pm#L31)) | `/access/roles/{roleid}` (PUT) | rôles `special` (intégrés) ignorés, non modifiables ([L146](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/Role.pm#L146)) ; `privs` trié |
+| utilisateur | `/access/users?full=1` ([User.pm L156](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/API2/User.pm#L156)) | `/access/users/{userid}` | seuls les `@pve` ; `tokens`, `realm-type`, champs de verrou TFA ignorés ; `groups` liste triée ; `password` jamais envoyé par l'API ; `root@pam` jamais supprimé |
+
+**Mots de passe.** L'API ne renvoie pas les hachés : ils sont dans
+`/etc/pve/priv/shadow.cfg` (lignes `user:hash:`, utilisateur sans royaume,
+[Auth/PVE.pm L13-L50](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/Auth/PVE.pm#L13)). Lecture et écriture par SSH en root :
+
+- lecture : `cat /etc/pve/priv/shadow.cfg` ;
+- écriture : script perl sous `PVE::Auth::PVE::lock_shadow_config`
+  ([L51](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/Auth/PVE.pm#L51)) avec `cfs_read_file` / `cfs_write_file`, comme
+  `store_password` ([L95-L98](https://github.com/proxmox/pve-access-control/blob/dff26b458651b4e1141ff0a41a296d2904b16228/src/PVE/Auth/PVE.pm#L95)) : le haché est recopié tel quel, sans
+  le recalculer. `cfs_read_file` sans version relit toujours le fichier
+  ([Cluster.pm](https://github.com/proxmox/pve-cluster/blob/86d4bb9efc0956311c01dbf59a38fa0583b60a19/src/PVE/Cluster.pm)).
+
+**À valider sur un vrai cluster** : script d'écriture du shadow, forme réelle de
+`/access/users?full=1`, mise à jour d'un utilisateur avec champs vidés.
+
+## Droits
+
+Accès en `root@pam` (API + SSH, même mot de passe), sans TFA. La référence (primaire)
+n'est jamais écrite. Le certificat TLS et la clé d'hôte SSH sont épinglés au premier test.