Contrat API - assistance admin VPN depuis l’app SSH

Date : 2026-09-17 Pour : app SSH / portail d’assistance admin Statut : admin uniquement, derriere requireAdminAuth.

1. Objectif

L’app SSH peut proposer un mode admin pour rechercher un client, voir ses slots VPN et ouvrir le bundle d’assistance d’un slot precis.

Le serveur garantit que le script est toujours derive d’un allocation_id exact. Le router_serial n’est jamais une source de verite pour servir un script admin, car un client peut deplacer son routeur entre plusieurs slots.

2. Recherche parc

Route existante :

GET /admin/api/accounts?search=<email-ou-nom>&limit=50

La reponse expose users[]. Pour chaque client, les allocations VPN sont dans user.vpns[] et dans user.resources[] avec type: "VPN".

Champs a consommer cote app SSH :

{
  "id": "allocation-id",
  "type": "VPN",
  "name": "MikroTik VPN",
  "host": "vpn.mikhmoai.com",
  "status": "ACTIVE",
  "tunnel_status": "CONNECTED",
  "router_tunnel_ip": "10.255.x.x",
  "locked_router_identity": "Router",
  "locked_router_model": "hAP ax3",
  "locked_router_serial": "SERIAL",
}

3. Bundle d’assistance par slot

GET /admin/api/catalog/remote-access/{allocationId}/assistance-bundle
GET /admin/api/catalog/remote-access/{allocationId}/assistance-bundle?include_script=1

Sans include_script=1, le serveur renvoie seulement un apercu masque. Avec include_script=1, le champ script.content contient le script RouterOS complet pour intervention manuelle. Cette action est tracee par evenement ADMIN_ASSISTANCE_BUNDLE_SERVED.

Le portail utilise POST /admin/api/catalog/remote-access/{allocationId}/manual-script pour WireGuard RouterOS v7. Cet endpoint fournit un bootstrap admin à coller une fois sur le routeur cible. Il transfère explicitement l’allocation, renouvelle son pair WG et libère les associations de serial concurrentes ; il peut couper l’ancien routeur lié au slot. Voir le contrat de reprise manuelle pour ses garanties et limites.

Reponse :

{
  "success": true,
  "data": {
    "allocation_id": "uuid",
    "client_id": "uuid",
    "bundle_version": "2026-09-06",
    "active_transport": "WIREGUARD",
    "primary_protocol": "WIREGUARD",
    "selected_protocol": "WIREGUARD",
    "public_host": "vpn.mikhmoai.com",
    "endpoint": { "host": "vpn.mikhmoai.com", "port": 51820 },
    "peer_public_key_fingerprint": "sha256-prefix",
    "tunnel": {
      "router_tunnel_ip": "10.255.x.x",
      "status": "CONNECTED",
      "last_seen_at": "date-ou-null",
    },
    "router_lock": {
      "identity": "nom-routeur",
      "serial": "serial",
      "model": "modele",
      "is_locked": true,
    },
    "protocols": [
      {
        "profile_id": "uuid",
        "protocol": "WIREGUARD",
        "status": "ACTIVE",
        "has_routeros_script": true,
        "has_configuration_blob": true,
        "has_credentials": true,
        "transport_plane": "INDUSTRIAL_WG",
      },
    ],
    "script": {
      "protocol": "WIREGUARD",
      "available": true,
      "redacted": ":interface wireguard add private-key=\"***\" ...",
      "content": null,
      "revealed": false,
    },
  },
}

4. Garanties serveur

Le bundle d’assistance est relu a la demande; il ne vient pas d’un cache de portail.
Le slot est selectionne par allocation_id; aucune fusion par serial, IP ou peer n’est autorisee.
Les listes admin ne contiennent pas de cle privee, PSK, mot de passe SSTP ou script brut.
Le script complet n’est servi que sur action admin explicite include_script=1.
L’evenement d’audit ne journalise jamais le script, les cles ou les mots de passe.

5. Cas non erreurs

Un client sans VPN actif donne une liste vpns: [].
Un slot sans script pret renvoie script.available: false, pas une erreur HTTP.
Un tunnel DISCONNECTED peut quand meme fournir un script d’assistance; c’est justement un cas de support manuel.

6. Deviations assumees

Le backend ne cree pas une nouvelle route de recherche dediee a l’app SSH. La recherche reutilise /admin/api/accounts, deja protegee par la session admin et deja alignee avec le panneau web.