Note d’intégration — Anti-Restriction, côté application mobile

Cette note complète CONTRAT-API-BRIDAGE (la référence complète des routes). Ici, seulement ce que l’application doit faire, dans quel ordre, et ce qu’il ne faut surtout pas faire.

Base : https://live.jmoai.net/api/v1/radius

1. Le partage des rôles, en une phrase

Le backend calcule et trace. L’application pose, depuis le LAN. Le backend reprend ensuite la main sur le routeur et le dit au gérant.

L’application est la seule à pouvoir poser ces commandes, et ce n’est pas un manque de temps côté serveur. Changer la MAC du WAN renégocie le bail DHCP : si Starlink lie la session à l’adresse, le lien tombe — et le tunnel de gestion comme la voie de secours BTH empruntent ce même lien. Le serveur perdrait le seul chemin qui lui permettrait de revenir en arrière. Depuis le LAN, vous en gardez toujours un. C’est pour ça que le serveur refuse ces écritures même à lui-même (routerWriteGuard).

1 bis. Jusqu’où le masquage porte — à lire avant de dessiner l’écran

Un MikroTik n’est pas toujours branché sur la parabole. Le cas le plus fréquent du parc : il est derrière un routeur du client (Omada, box opérateur, routeur bi-WAN). Son WAN a alors une adresse privée, et ce que le fournisseur voit, c’est la carte du routeur placé devant — jamais celle du MikroTik. Masquer sa MAC ne change alors rien côté fournisseur.

Envoyez adresse_wan (lue dans /ip dhcp-client print) et le serveur tranche :

⚠️ La CGNAT n’est PAS un routeur intermédiaire. Une parabole Starlink délivre par défaut du 100.64.0.0/10, qui n’est ni public ni privé : le routeur fait bel et bien face au fournisseur, et le masquage porte. Traiter « non publique » comme « derrière un routeur » ferait dire à l’application que la fonction ne sert à rien précisément chez les clients Starlink directs — c’est-à-dire sa cible.

On ne bloque pas : masquer un MikroTik derrière un Omada reste défendable, le gérant peut vouloir la discrétion sur son réseau intermédiaire. On le dit, il décide.

2. Avant tout : le droit

GET /bandwidth/program et GET /starlink/mac/{nasId}/consigne renvoient un objet droit :

{ "autorise": false, "motif": "STARLINK_X_REQUIRED", "enforced": false, "prix_xof": 25000 }

• enforced: false → bouton actif, même si autorise est faux. L’enforcement est en veille : griser le bouton mentirait à un gérant dont la fonction marche.
• enforced: true + autorise: false → bouton grisé + proposition d’abonnement.
• autorise: null → les droits sont indisponibles. N’affichez pas de proposition d’achat : le gérant a peut-être déjà payé. Affichez l’écran normal.

3. Préparer la pose : ce qu’il faut lire sur le routeur

L’application est sur le LAN, elle voit ce que le serveur ne voit pas. Le serveur ne devine rien de tout ceci, et c’est délibéré : se tromper d’interface coupe le gérant de son routeur.

Le WAN ne s’appelle pas toujours ether1. Relevé sur un routeur du parc : il s’appelle ether1-TP-LinkGiga. Lisez le nom, ne le supposez pas.

Un routeur peut avoir plusieurs liens fournisseur. Ce même routeur en a deux : la fibre sur ether1-TP-LinkGiga et le Starlink de secours sur ether2-Bakup. La découverte se règle globalement, donc la liste locale les couvre tous ; mais le nom d’hôte se retire client DHCP par client DHCP. Envoyez-les tous dans interfaces_wan, sinon le routeur continuera d’annoncer son identité au second fournisseur pendant que l’écran affichera « appliqué ».

interface = celui dont on masque la MAC. interfaces_wan = tous les liens fournisseur.

Envoyez la liste des ponts. Ne comptez pas sur le serveur pour les deviner : sur ce routeur ils s’appellent HOTSPOT et Container-bridge. Un gérant nomme ses ponts par leur fonction, pas par leur type — sans ponts=, l’avertissement sur la visibilité côté clients ne s’affiche pas, précisément là où il sert.

Pour les interfaces locales, le cas normal est un seul pont. Envoyez ce pont, rien d’autre : la découverte y atteint tous ses membres, ports et Wi-Fi compris.

⚠️ Vérifiez que ce pont ne contient aucun WAN (/interface bridge port print). S’il en contient un, la découverte ressortirait par le WAN — exactement ce qu’on veut empêcher. Dans ce cas, n’envoyez pas ce pont.

4. La consigne

GET /starlink/mac/{nasId}/consigne
    ?interface=ether2-Bakup
    &interfaces_wan=ether1-TP-LinkGiga
    &interfaces_locales=HOTSPOT
    &ponts=HOTSPOT,Container-bridge
    &adresse_wan=10.100.4.2/24

Consigne réellement produite pour un routeur bi-WAN du parc :

1. :if ([:len [/interface list find name=JSLOCAL]] = 0) do={/interface list add name=JSLOCAL comment=JSLOCAL}
2. :if ([:len [/interface list member find list=JSLOCAL interface=HOTSPOT]] = 0) do={/interface list member add list=JSLOCAL interface=HOTSPOT}
3. /ip neighbor discovery-settings set discover-interface-list=JSLOCAL
4. /ip dhcp-client set [find interface=ether2-Bakup] dhcp-options=clientid
5. /ip dhcp-client set [find interface=ether1-TP-LinkGiga] dhcp-options=clientid
6. /interface ethernet set [find name=ether2-Bakup] mac-address=02:20:F9:E9:9B:50   ← EN DERNIER

Ajoutez &nom_hote=box-4f21 si le gérant veut un nom d’hôte de substitution. Sans ce paramètre, aucun nom d’hôte n’est envoyé au fournisseur — c’est le réglage le plus discret.

Vous récupérez commande (la MAC), discretion.commandes (la discrétion WAN), precautions, et discretion.avertissement.

Affichez precautions avant le bouton, pas dans un écran d’aide. Et affichez discretion.avertissement quand il n’est pas null : c’est le seul moment où le gérant peut encore choisir une interface de gestion hors du pont plutôt que d’être visible de ses clients.

5. L’ORDRE de pose — le point le plus important de cette note

1. discretion.commandes   (toutes, dans l'ordre reçu)
2. commande               (la MAC)  ← EN DERNIER

La MAC se pose en dernier, et c’est la seule règle qu’il ne faut pas inverser. Les commandes de discrétion ne coupent rien : elles se posent tranquillement, sur un lien qui fonctionne. La MAC, elle, fait tomber le lien le temps de la renégociation du bail. Poser la discrétion après la MAC reviendrait à écrire sur un routeur qui est justement en train de perdre son WAN.

Les commandes de discrétion sont idempotentes : si l’une échoue, rejouez tout le bloc, rien ne sera dupliqué.

Gardez commande_retour en local, sur le téléphone, avant de poser quoi que ce soit. C’est la commande qui rétablit l’adresse d’origine. Elle doit rester lisible hors ligne : le moment où on en a besoin est précisément celui où le routeur n’a plus Internet.

5 bis. Le routeur refuse les commandes ? Les trois causes, dans l’ordre

Cause n°1 — vous envoyez du script à une API qui n’en veut pas

Les commandes de discretion.commandes sont du script RouterOS :

:if ([:len [/interface list find name=JSLOCAL]] = 0) do={/interface list add name=JSLOCAL comment=JSLOCAL}

Cette forme fonctionne en terminal — SSH, Telnet, terminal WinBox. Elle n’existe pas en API REST (/rest/...) ni en API binaire (8728) : ces deux-là ne connaissent que des ressources et des champs, pas :if, pas :len, pas do={}. Envoyer ça à REST donne une erreur de syntaxe qui n’a rien à voir avec la commande elle-même.

Si votre app parle en SSH : collez les commandes telles quelles, une par ligne. Rien à faire.

Si votre app parle en REST : il faut porter l’idempotence côté client. Une commande :if ([:len [X find …]] = 0) do={X add …} se traduit par « je fais un GET pour voir si ça existe, et je ne fais le PUT que si la liste est vide ». Le tableau du §5 ter donne la correspondance.

Cause n°2 — la cible n’existe pas, et le lot entier tombe

/ip dhcp-client set [find interface=ether1] sur une interface qui n’a pas de client DHCP fait échouer la commande. Et comme un lot fautif échoue en entier, toute la pose tombe — alors qu’il n’y avait simplement rien à masquer sur ce lien.

C’est fréquent : un WAN en PPPoE ou en IP fixe n’a pas de client DHCP. Depuis le 2026-08-29 le serveur garde donc chaque écriture sur l’existence de sa cible. Si vous aviez copié une ancienne version des commandes, redemandez la consigne : la forme actuelle est

:if ([:len [/ip dhcp-client find interface=ether1]] > 0) do={/ip dhcp-client set [find interface=ether1] dhcp-options=clientid}

Note : sur un WAN PPPoE il n’y a de toute façon pas de nom d’hôte DHCP à cacher — PPPoE s’annonce par un identifiant, pas par l’option 12.

Cause n°3 — le nom de l’interface

Un nom mal recopié fait find sur du vide, donc rien, donc l’erreur ci-dessus. Vérifié sur un routeur du parc : les noms contiennent des tirets (ether1-TP-LinkGiga), et [find name=…] les accepte tels quels sans guillemets. En revanche, un nom contenant un espace doit être entre guillemets : [find name="mon interface"].

Les messages de RouterOS, traduits

5 ter. Correspondance REST, si votre app ne passe pas par SSH

Les chemins REST exacts varient un peu selon la version de RouterOS : validez-les par un GET avant d’écrire. En cas de doute, le terminal SSH reste la voie la plus sûre — c’est celle pour laquelle les commandes sont écrites.

6. Vérifier qu’Internet est revenu — vraiment

Après la pose, attendez. Deux vérifications, les deux nécessaires :

1. :put [/ip dhcp-client get [find interface=ether1] status]     → doit valoir "bound"
2. /ping 1.1.1.1 count=3                                          → doit répondre

Le premier dit que le bail a été renégocié, le second que le trafic passe. Un bail obtenu ne prouve pas qu’Internet fonctionne.

Laissez jusqu’à 2 minutes. Au-delà, proposez la restauration (commande_retour) — ne la déclenchez pas toute seule : le gérant doit décider, il est peut-être en train de regarder la parabole.

7. Déclarer, puis suivre

POST /starlink/mac/{nasId}
{
  "resultat": "POSEE",
  "interface": "ether1",
  "mac_origine": "48:A9:8A:11:22:33",
  "mac_posee": "02:AB:CD:EF:01:02",
  "internet_confirme": true,
  "discretion_appliquee": true,
  "interfaces_locales": ["bridge-hotspot"]
}

internet_confirme n’est pas une case à cocher par principe. C’est lui qui déclenche la reprise en main côté serveur. Un true optimiste la ferait démarrer sur un routeur encore en train de renégocier son bail, et le gérant lirait un échec là où il n’y avait qu’une attente.

La réponse porte déjà service_etat: "INITIALISATION" et son titre : enchaînez sur l’écran de suivi sans second appel.

Puis sondez toutes les 5 s :

GET /starlink/mac/{nasId}/statut

• Affichez titre, jamais service_etat — la phrase vient du serveur, elle est identique dans la notification push.
• Affichez les etapes (ROUTEUR, SAUVEGARDE, PROGRAMME). IGNOREE n’est pas un problème : seule ROUTEUR est bloquante.
• Arrêtez de sonder dès que service_etat n’est plus INITIALISATION. La reprise dure typiquement moins d’une minute, sauvegarde comprise.
• Ne recalculez jamais peut_relancer. L’expiration d’une reprise interrompue est une règle serveur ; deux versions de l’app la calculeraient différemment. Quand il vaut true, montrez « Réessayer » → POST /starlink/mac/{nasId}/relancer.

En cas d’échec de pose, déclarez-le : resultat: "ECHEC", avec mac_origine quand même. C’est justement quand ça a raté qu’il faut savoir vers quoi revenir.

Pour revenir en arrière : resultat: "RESTAUREE". Le service repasse à EN_ATTENTE.

8. Les notifications

Type STARLINK_X. Elles arrivent en plus de l’écran, pour le gérant qui a quitté l’app :

Un appui dessus doit ouvrir l’écran de statut du bon nas_id (il est dans metadata).

9. Ce qu’il faut dire au gérant, et ne pas embellir

Le camouflage est bon, il n’est pas total. Quatre signaux trahissent un MikroTik ; trois sont traités :

Le champ discretion.limites porte cette liste. Affichez-la. Un camouflage annoncé comme total et qui ne l’est pas ferait prendre au gérant des risques qu’il croit couverts.

Et dites-lui aussi ce qui ne change pas : le nom du routeur (/system identity) reste le vrai. C’est ce que son technicien lit dans WinBox. Seul le nom envoyé au fournisseur est masqué.

10. Les erreurs, et ce qu’elles veulent dire pour le gérant

11. Protocole de test — les 12 routes, dans l’ordre

Toutes les routes sont sous https://live.jmoai.net/api/v1/radius. Chaque appel porte Authorization: Bearer <jeton du gérant>. Un compte client lié à un NAS est requis : requireClientRole + requireLinkedClient + requireRadiusLicense sont posés sur toutes.

Posez d’abord :

API=https://live.jmoai.net/api/v1/radius
T="Bearer <jeton>"
NAS=<uuid du NAS>

Phase 0 — les gardes (à faire une fois, sans jeton)

Un 403 en 0.1 au lieu d’un 401, ou un 200 en 0.2, sont bloquants : arrêtez la recette.

Phase 1 — lectures, sans rien changer

1.4 est le piège classique : si l’app affiche un pourcentage alors que fiabilite vaut INSUFFISANTE, c’est un défaut bloquant — elle inventerait un chiffre.

Phase 2 — la consigne, sans rien poser

2.4 est la vérification qui compte : une adresse qui change d’un appel à l’autre serait reposée à chaque passage, et changer la MAC coupe le lien à chaque fois.

Phase 3 — la pose réelle, sur un routeur d’essai, depuis le LAN

Ne faites cette phase que sur un routeur que vous pouvez atteindre physiquement.

1. Notez commande_retour — ou l’adresse d’origine — sur papier ou hors ligne.
2. Posez discretion.commandes dans l’ordre. Vérifiez : /ip neighbor discovery-settings print → discover-interface-list: JSLOCAL, /ip dhcp-client print → dhcp-options=clientid sur chaque WAN.
3. Rejouez le même bloc une seconde fois → aucune erreur, aucun doublon dans /interface list member print (les commandes sont idempotentes).
4. Posez commande (la MAC) en dernier. Attendez le bail : status: bound, puis un ping.
5. POST $API/starlink/mac/$NAS avec resultat: "POSEE", internet_confirme: true, discretion_appliquee: true, interfaces_locales.

Phase 4 — les refus

Phase 5 — reprise et retour arrière

Phase 6 — le bridage, si le gérant en a un

Ce qui doit rester vrai après toute la recette

• Aucune écriture du backend dans /interface ethernet, /ip neighbor, /ip dhcp-client ni /interface list : ces chemins sont gardés, seule l’app les pose.
• /system identity n’a pas changé : le routeur porte toujours son vrai nom dans WinBox.
• Le retrait du bridage ne vise que le commentaire JSBRIDAGE : aucune file du client, du hotspot ou d’un revendeur ne doit avoir bougé.

12. Recette — à cocher avant publication

• [ ] Le WAN est lu sur le routeur, jamais supposé ether1.
• [ ] Le pont envoyé en interfaces_locales ne contient pas le WAN.
• [ ] commande_retour est stockée avant la pose, et lisible hors ligne.
• [ ] La discrétion est posée avant la MAC.
• [ ] internet_confirme n’est envoyé qu’après les deux vérifications (bail + ping).
• [ ] L’écran affiche titre, pas service_etat.
• [ ] discretion.avertissement et discretion.limites sont affichés au gérant.
• [ ] Le bouton suit enforced, pas autorise.
• [ ] Sondage arrêté dès la sortie de INITIALISATION.
• [ ] Un appui sur la notification ouvre le bon routeur.
• [ ] masquage.avertissement est affiché quand la portée vaut ROUTEUR_INTERMEDIAIRE.
• [ ] Tous les liens fournisseur sont envoyés dans interfaces_wan, pas seulement le masqué.
• [ ] ponts= est envoyé, sans quoi l’avertissement sur la visibilité se tait.