Associez le compagnon iOS

Vérifiez les deux extrémités de la connexion

Le compagnon est un client d’un sidecar de bureau en cours d’exécution. Il n'héberge pas la base de données du projet, le noyau géométrique, le fournisseur de modèles ou l'exécuteur de flux de travail. Avant le couplage, vérifiez que le bureau ouvre ses projets et que le téléphone peut accéder au bureau via Wi-Fi, un point d'accès personnel ou un réseau superposé/VPN déjà configuré.

Utilisez une version iOS native contenant modules/companion-net. Expo Go ne dispose pas de ce module et ne peut pas établir la connexion épinglée. Le package dispose également d'une solution de secours pour le développement du navigateur, mais la récupération du navigateur n'implémente pas la politique d'épinglage native. La configuration Android dans le manifeste ne fournit pas d'équivalent Android du module Swift.

bun install
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd apps/mobile ios

La commande d'exécution iOS nécessite macOS, Xcode et CocoaPods. La création d'un appareil physique nécessite un appareil de confiance et une équipe de signature. bun run --cwd apps/mobile build exporte JavaScript ; il ne crée pas d'IPA installable. Voir le référence mobile pour l'aménagement et la mise en œuvre des transports.

Activer la passerelle de bureau

Ouvrez Paramètres du bureau → Appareils et son panneau compagnon mobile, ou utilisez /settings/companion. Allumez la passerelle, puis créez un appariement nommé et affichez son code QR. Il s'agit d'un écouteur distinct de l'API de bouclage ordinaire : HTTPS sur IPv4 0.0.0.0, port 8443 par défaut.

Le service accepte les ports entiers 1024–65535. Si une autre application occupe le port sélectionné, l'activation échoue ; choisissez un port libre et créez un lien avec l'adresse obtenue. Autorisez la connexion via le pare-feu du bureau pour le réseau que vous souhaitez utiliser. L'application ne crée pas de relais public, de redirection de port ou de VPN.

L’état et le port activés sont conservés. Après un redémarrage sidecar, la passerelle tente de reprendre une fois que l'API locale est prête. Les fichiers de certificat et de clé privée se trouvent dans le répertoire de données sidecar companion/ sous-répertoire ; la clé privée est écrite avec des autorisations réservées au propriétaire. L'application native fait confiance au certificat issu du couplage, et non à une promesse générique selon laquelle chaque certificat local est sécurisé.

Inspecter et activer via l'API de bureau

Pour une configuration de développement reproductible, utilisez le jeton de lancement d'un sidecar isolé que vous contrôlez. Remplacez le port 43111 par son port d'événement prêt. Il s'agit d'appels de gestion de bureau ; le jeton téléphonique n'est pas autorisé à administrer sa propre passerelle.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token
CADCAM_PAIR_DIR=$(mktemp -d /tmp/cadcamfun-pair-guide.XXXXXX)

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/enable"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"port":18443}'

L’état contient l’état activé, le port/empreinte digitale nullable, l’hôte suggéré et les entrées de périphérique. L'empreinte digitale peut être nulle avant qu'un certificat existe. Un public sonde de santé établit la santé du processus de bouclage ; cela ne prouve pas que la passerelle HTTPS est activée, accessible ou qu'elle accepte un jeton d'appareil. Utilisez le API compagnon pour des schémas de gestion précis.

Créer une association nommée

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/pair"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Workshop iPhone","host":"192.168.1.20"}'   -o "$CADCAM_PAIR_DIR/pairing.json"

CADCAM_DEVICE_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_PAIR_DIR/pairing.json")

Remplacez l'exemple d'hôte par une adresse que le téléphone peut atteindre, ou omettez l'hôte facultatif pour utiliser la découverte. Le nom est tronqué et doit contenir 1–60 caractères. Le succès est HTTP 201 avec id et link. La création d'un jeton n'active pas l'écouteur ; activez-le séparément.

Le lien contient le jeton de l'appareil, l'empreinte digitale du certificat, l'origine HTTPS principale, le nom et les hôtes alternatifs facultatifs. Affichez-le ou transférez-le en privé sur le téléphone ; c'est un titre de compétence. Le bureau stocke le hachage du jeton plutôt que son texte brut. L'enregistrement n'a pas de champ d'expiration dans cette implémentation, donc révoquez explicitement un périphérique obsolète plutôt que de supposer qu'il va expirer.

Charger l'appairage sur iOS

1. Ouvrez l'écran Connect de l'application CADCAMFUN installée.
2. Choisissez Scanner le code QR de couplage et accorder l'accès à la caméra, ou utilisez Coller un lien de couplage.
3. Pour une saisie manuelle, fournissez l'adresse du bureau, le jeton et l'empreinte digitale complète du certificat via le formulaire de connexion.
4. Autorisez l’accès au réseau local lorsque iOS vous y invite. L'accès à la caméra et l'accès au réseau sont des autorisations distinctes.
5. Attendez que la sonde d'intégrité/d'amorçage réussisse et que l'application ouvre les projets.

L'analyseur nécessite une origine HTTPS sans informations utilisateur, contenu de chemin, requête ou fragment. Les jetons doivent contenir de 16 à 4096 caractères sans espaces/caractères de contrôle ; les empreintes digitales sont exactement 64 caractères hexadécimaux. Les liens invalides sont refusés avant le début des requêtes.

Les origines alternatives découvertes sont dédupliquées. Le client fait la course avec les candidats, utilise la première connexion réussie, abandonne les autres et enregistre l'origine réussie. Discovery annonce jusqu'à six adresses IPv privées4 appropriées, y compris les plages Wi-Fi, hotspot et IPv de type Tailscale4 ; l'écouteur IPv4 actuel n'annonce pas les hôtes IPv6 découverts.

Quels certificats vérifient l'épinglage

Le transport Swift utilise l'éphémère URLSession instances et un délégué de confiance personnalisé. Il obtient les octets DER du certificat feuille, calcule SHA-256 et accepte la connexion uniquement lorsque ce hachage est égal à l'empreinte digitale associée. HTTPS est requis et les redirections sont refusées. Les appelants natifs ne reviennent pas silencieusement à la récupération non épinglée si le module est manquant.

Cela prend en charge le certificat auto-signé du bureau sans accepter de serveurs auto-signés arbitraires. La décision de confiance vient du couplage QR/lien. Le remplacement du certificat de bureau modifie cette décision ; créez un nouveau couplage de confiance au lieu de supprimer la discordance.

Les erreurs ordinaires de confiance navigateur/curl ne équivalent pas au test du délégué natif de l’application. Un navigateur peut rejeter un serveur auto-signé correctement épinglé car il utilise un magasin de confiance différent. Vérifiez via l'application installée et inspectez l'échec réel plutôt que de désactiver la validation du certificat globalement.

Une fois l'authentification réussie de l'appareil, la passerelle enregistre un horodatage de dernière visite pour son état de service actuel. Actualisez l’état de l’appareil de bureau pour confirmer le trafic authentifié. Cela indique l'utilisation d'un jeton ; cela ne constitue pas une preuve que chaque action du projet a réussi ni une piste d'audit de sécurité durable.

Comprendre la portée du jeton d'appareil

Le jeton de périphérique est limité par la liste autorisée de méthode/chemin. Il n'est pas intrinsèquement en lecture seule et ne sélectionne pas un seul projet. Les demandes acceptées sont transmises sous l'identité de l'application du poste de travail et restent soumises à l'autorisation du point de terminaison. Ne décrivez jamais le couplage comme un simple accord de surveillance passive.

Les autorisations de l'assistant et les questions en attente sont des interactions de session distinctes. Répondez-y dans l’interface utilisateur mobile lorsque cela vous est demandé. Un jeton pouvant atteindre le point de terminaison de réponse ne signifie pas que chaque action de l'outil a déjà été approuvée.

Utiliser des sessions et récupérer la connectivité

Choisissez un projet pour inspecter sa présentation, son historique, ses extractions et ses exécutions de flux de travail. Les sessions de l'Assistant s'exécutent sur le bureau avec les paramètres de son fournisseur. Configurez d'abord le fournisseur ici. Le téléphone mémorise un projet sélectionné et la dernière session par projet pour le bureau couplé ; la modification de l'identité du bureau efface ce mappage.

Sonde de vérifications au premier plan avec un budget de 15 secondes. Les vérifications échouées reculent jusqu'à 30 secondes et le fait d'avancer l'application déclenche une autre sonde. L’état d’arrière-plan est suivi séparément de l’état hors ligne. Appuyez sur la ligne du bureau dans les paramètres du téléphone pour revérifier manuellement.

Les messages de l'assistant en file d'attente sont conservés avec un maximum de 50 entrées, les plus anciennes étant supprimées au-delà de cette limite. Ils réessayent plus tard et peuvent conserver leur identifiant de session. Il s'agit d'une prise en charge limitée de la livraison de messages, et non d'un calcul CAO hors ligne ou d'une exécution unique. Après une écriture/un tour interrompu, inspectez la session de bureau et le projet avant de répéter la même modification.

Révoquer ou dissocier délibérément

curl --fail-with-body -X DELETE   "$CADCAM_URL/api/companion/devices/$CADCAM_DEVICE_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

Les jetons sont vérifiés à chaque nouvelle demande, de sorte que les demandes suivantes utilisant le jeton révoqué échouent. La révocation ne met pas explicitement fin à un flux déjà transmis. La désactivation de la passerelle arrête l'écouteur ; POST /api/companion/disable est le point final administratif.

Paramètres du téléphone → Dissocier ce téléphone supprime le couplage enregistré localement et revient à Connect. Il n’appelle pas le point de terminaison de révocation du bureau. Utilisez les deux actions lors du retrait d’un appareil. Pour faire pivoter uniquement les informations d'identification de l'appareil, révoquez-les et effectuez un nouveau couplage ; le remplacement de l'intégralité du certificat modifie également le code PIN de chaque téléphone.

Diagnostiquer les pannes par couche

Native CI crée une application de simulation non signée et vérifie la véritable liste de couplage/projet de passerelle. Séparez la vérification du type des contrôles CI, les tests logiques et l'exportation JavaScript. Ceux-ci ne prouvent pas la signature de périphériques physiques, la distribution TestFlight, le routage de réseau distant ou un véritable fournisseur de modèles.

Les mauvais jetons répétés sont limités : dix tentatives infructueuses à partir d'une adresse IP dans un délai de 60 secondes font que d'autres requêtes de celle-ci renvoient HTTP 429 jusqu'à l'expiration de la fenêtre. Un 429 après le nouveau couplage signifie généralement qu'un ancien jeton d'appareil est toujours en cours de tentative.

Carte de mise en œuvre

Le contrat de gestion est packages/api/src/groups/companion.ts. Le cycle de vie du sidecar et la politique d'itinéraire sont en place services/companion.ts et companion-gateway.ts. L'analyse du téléphone, la récupération de connexion, le stockage et l'interface utilisateur sont disponibles lib/pairing.ts, server.tsx, storage.ts, et app/connect.tsx. Le délégué de confiance natif est modules/companion-net/ios/CompanionNetModule.swift.

Pour un rapport d'assistance, conservez la version de l'application, la méthode de connexion, l'hôte/le port de passerelle non secret, l'erreur/le statut exact et si le module natif est présent. Rédigez les jetons, les liens d'appariement, les informations d'identification du modèle et les clés privées. Ajoutez le API système résultat de la version lors de la comparaison de deux processus de développement.

Ce qu'un téléphone couplé peut appeler

Chaque demande via la passerelle doit contenir un jeton d'appareil et correspondre à cette liste verte. Tout le reste, y compris les informations d'identification, les plugins, les fichiers, la facturation et /api/companion lui-même, est refusé. Les demandes admises sont transmises à l'API de bouclage avec le jeton d'application, que le téléphone ne voit jamais.

Anatomie du lien d'appariement

cadcamfun://pair?host=https%3A%2F%2F192.168.1.20%3A8443&token=<43-char base64url>&fp=<sha256 hex>&name=Ada%27s+iPhone&hosts=https%3A%2F%2F100.64.0.7%3A8443

Le certificat est un certificat P-256 auto-signé dont les noms alternatifs d'objet incluent localhost, 127.0.0.1, et les adresses privées accessibles de la machine. Il est conservé dans <dataDir>/companion, donc les appariements survivent aux redémarrages. Son remplacement modifie l'empreinte digitale et nécessite un nouveau couplage.

API d'administration de passerelle

Les tentatives de support infructueuses sont limitées par adresse IP : après 10 échecs dans un délai de 60 secondes, la passerelle répond HTTP 429 ("Trop de tentatives infructueuses") jusqu'à ce que la fenêtre passe. Un jeton incorrect ou révoqué obtient sinon HTTP 401.

État de la passerelle, capturé

{ "enabled": false, "port": null, "fingerprint": null, "host": "172.30.0.2", "devices": [] }

Si host n'est pas l'adresse que votre téléphone peut atteindre (par exemple un conteneur ou une interface VPN), le couplage échouera au niveau de la couche réseau même si tout le reste est correct.

En 3D