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

Révision 2026-09-17 — camouflage Standalone : aucune association NAS/RADIUS n’est requise pour le camouflage manuel. Sans nas_id ou sans activation volontaire de la gestion Cloud, l’application applique et vérifie le changement de MAC localement, sans aucun appel aux routes Starlink MAC ou bridage. Les sections Cloud de ce document, y compris les consignes, déclarations, statuts et calendriers, ne s’appliquent qu’à un NAS existant que le gérant a choisi de gérer. L’application ne crée jamais un NAS pour lever un blocage de camouflage.

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

router_serial est obligatoire pour chaque appel de camouflage. Si l’application ne parvient pas à le lire, elle envoie UNKNOWN-SERIAL : le backend l’accepte sans 400, résout la série canonique si possible et garde sinon une identité interne stable par NAS.

{ "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
    &router_serial=HH40AF7YVNP
    &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.

Ajoutez &masquer_ttl=true pour effacer la trace du NAT. Chaque routeur traversé décrémente le TTL d’un paquet : un fournisseur qui voit arriver un TTL de 63 sait qu’un routeur se cache derrière. Avec ce paramètre, discretion.commandes contient une règle mangle de plus qui réécrit le TTL sortant à 64 sur chaque lien fournisseur — le MikroTik redevient un appareil comme les autres. C’est le seul des quatre signaux qui révèle la NATURE de l’appareil ; la MAC ne révèle que sa marque.

⚠️ Opt-in, et pour une raison. Réécrire le TTL casse le traceroute DEPUIS le LAN vers l’extérieur (les sauts ne se comptent plus). N’envoyez masquer_ttl=true que si le gérant veut la discrétion maximale, et dites-le-lui. Le champ de retour discretion.ttl_masque confirme si la règle est dans le lot. La règle porte le commentaire JSTTL — rejouable sans créer de doublon.

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}
{
  "router_serial": "HH40AF7YVNP",
  "resultat": "POSEE",
  "interface": "ether1",
  "mac_origine": "48:A9:8A:11:22:33",
  "camouflage_mac": "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?router_serial=HH40AF7YVNP

• 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.
• Le sondage de statut est une lecture dédiée : la cadence normale de 12 requêtes/minute ne doit pas être traitée comme un abus ni produire un 429.
• Un 429 est une protection d’infrastructure : stoppez immédiatement la boucle et affichez l’erreur, sans répétition locale. Un second appui pendant l’initialisation reçoit 409 MAC_ALREADY_IN_PROGRESS avec le message « Un camouflage est déjà en cours d’application. » : conservez alors l’écran de suivi déjà ouvert.
• 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. Cinq signaux trahissent un MikroTik ; quatre sont traités depuis le 2026-08-31 :

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

Déviation documentée

UNKNOWN-SERIAL est accepté afin qu’une lecture RouterOS indisponible ne bloque pas le gérant. Le serveur résout d’abord la série canonique du NAS. S’il ne peut pas encore le faire, il utilise une identité stable propre à ce NAS pour éviter qu’une même MAC soit attribuée à tous les routeurs en repli. Cette identité ne prouve pas le matériel : l’application doit transmettre la vraie série dès qu’elle est lisible, afin que la reprise distante puisse cibler le routeur.

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

La MAC est désormais produite par l’app puis réservée par le serveur à la déclaration ; un 409 MAC_COLLISION impose de générer une nouvelle valeur avant le retry.

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.