Emparejar el compañero de iOS

Verifique los dos extremos de la conexión.

El compañero es un cliente de un sidecar de escritorio en ejecución. No aloja la base de datos del proyecto, el núcleo de geometría, el proveedor de modelos ni el ejecutor del flujo de trabajo. Antes de realizar el emparejamiento, confirme que el escritorio abra sus proyectos y que el teléfono pueda enrutarse al escritorio a través de Wi-Fi, un punto de acceso personal o una red superpuesta/VPN ya configurada.

Utilice una compilación nativa de iOS que contenga modules/companion-net. Expo Go carece de este módulo y no puede realizar la conexión fija. El paquete también tiene un respaldo de desarrollo del navegador, pero la recuperación del navegador no implementa la política de fijación nativa. La configuración de Android en el manifiesto no proporciona un equivalente de Android del módulo Swift.

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

El comando de ejecución de iOS requiere macOS, Xcode y CocoaPods. La construcción de un dispositivo físico requiere un dispositivo confiable y un equipo de firma. bun run --cwd apps/mobile build exporta JavaScript; no crea una IPA instalable. Ver el referencia movil para el diseño y la implementación del transporte.

Habilite la puerta de enlace de escritorio

Abra Configuración de escritorio → Dispositivos y su panel complementario Móvil, o use /settings/companion. Encienda la puerta de enlace, luego cree un emparejamiento con nombre y muestre su código QR. Este es un escucha independiente de la API de bucle invertido normal: HTTPS en IPv4 0.0.0.0, puerto 8443 de forma predeterminada.

El servicio acepta puertos enteros 1024–65535. Si otra aplicación ocupa el puerto seleccionado, la habilitación falla; elija un puerto libre y cree un enlace con la dirección resultante. Permita la conexión a través del firewall del escritorio para la red que desea utilizar. La aplicación no crea una retransmisión pública, reenvío de puertos ni una VPN.

El estado y el puerto habilitados se conservan. Después de reiniciar el sidecar, la puerta de enlace intenta reanudarse una vez que la API local esté lista. Los archivos de certificado y clave privada se encuentran en el directorio de datos del sidecar. companion/ subdirectorio; la clave privada se escribe con permisos exclusivos del propietario. La aplicación nativa confía en el certificado para el emparejamiento, no en una promesa genérica de que todos los certificados locales son seguros.

Inspeccionar y habilitar a través de la API de escritorio

Para una configuración de desarrollo reproducible, utilice el token de lanzamiento de un sidecar aislado que controle. Reemplace el puerto 43111 con su puerto de evento listo. Estas son llamadas de administración de escritorio; el token del teléfono no puede administrar su propia puerta de enlace.

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}'

El estado contiene entradas de estado habilitado, puerto/huella digital que acepta valores NULL, host sugerido y entradas de dispositivo. La huella digital puede ser nula antes de que exista un certificado. un publico sonda de salud establece el estado del proceso de loopback; no prueba que la puerta de enlace HTTPS esté habilitada, sea accesible o acepte un token de dispositivo. Utilice el API complementaria para esquemas de gestión exactos.

Crea un emparejamiento con nombre

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")

Reemplace el host de ejemplo con una dirección a la que pueda llegar el teléfono u omita el host opcional para usar el descubrimiento. El nombre está recortado y debe contener 1–60 caracteres. El éxito es HTTP 201 con id y link. La creación de un token no habilita al oyente; habilitarlo por separado.

El enlace lleva el token del dispositivo, la huella digital del certificado, el origen HTTPS principal, el nombre y hosts alternativos opcionales. Muéstralo o transfiérelo de forma privada al teléfono; es una credencial. El escritorio almacena el hash del token en lugar de su texto sin formato. El registro no tiene ningún campo de caducidad en esta implementación, por lo que se debe revocar explícitamente un dispositivo obsoleto en lugar de asumir que caducará.

Cargar el emparejamiento en iOS

1. Abra la pantalla Conectar de la aplicación CADCAMFUN instalada.
2. Elija Escanear el código QR de emparejamiento y otorgar acceso a la cámara, o use Pegar un enlace de emparejamiento.
3. Para la entrada manual, proporcione la dirección del escritorio, el token y la huella digital completa del certificado a través del formulario de conexión.
4. Permita el acceso a la red local cuando iOS lo solicite. El acceso a la cámara y el acceso a la red son permisos separados.
5. Espere a que la sonda de salud/arranque se realice correctamente y que la aplicación abra Proyectos.

El analizador requiere un origen HTTPS sin información de usuario, contenido de ruta, consulta o fragmento. Los tokens deben tener 16–4096 caracteres sin espacios en blanco ni caracteres de control; Las huellas digitales son exactamente 64 caracteres hexadecimales. Los enlaces no válidos se rechazan antes de que comiencen las solicitudes.

Los orígenes alternativos descubiertos se deduplican. El cliente compite con candidatos, utiliza la primera conexión exitosa, aborta las demás y guarda el origen exitoso. Discovery anuncia hasta seis direcciones IPv4 privadas adecuadas, incluidos Wi-Fi, hotspot y rangos de IPv4 estilo Tailscale; el oyente IPv4 actual no anuncia hosts IPv6 descubiertos.

¿Qué comprobaciones de fijación de certificados?

El transporte Swift utiliza lo efímero. URLSession instancias y un delegado de confianza personalizado. Obtiene los bytes DER del certificado hoja, calcula SHA-256 y acepta la conexión solo cuando ese hash es igual a la huella digital emparejada. Se requiere HTTPS y se rechazan las redirecciones. Las personas que llaman nativas no recurren silenciosamente a la recuperación sin fijar si falta el módulo.

Esto admite el certificado autofirmado del escritorio sin aceptar servidores autofirmados arbitrarios. La decisión de confianza surge del emparejamiento QR/enlace. Reemplazar el certificado de escritorio cambia esa decisión; cree un nuevo emparejamiento confiable en lugar de suprimir la discrepancia.

Los errores comunes de confianza de navegador/curl no equivalen a probar el delegado nativo de la aplicación. Un navegador puede rechazar un servidor autofirmado fijado correctamente porque utiliza un almacén de confianza diferente. Verifique a través de la aplicación instalada e inspeccione la falla real en lugar de deshabilitar la validación de certificados globalmente.

Después de una autenticación exitosa del dispositivo, la puerta de enlace registra una marca de tiempo vista por última vez para su estado de servicio actual. Actualice el estado del dispositivo de escritorio para confirmar el tráfico autenticado. Esto indica el uso de tokens; no es una prueba de que cada acción del proyecto tuvo éxito ni una pista de auditoría de seguridad duradera.

Comprender el alcance del token del dispositivo

El token del dispositivo está limitado por la lista permitida de método/ruta. No es inherentemente de solo lectura y no selecciona un proyecto. Las solicitudes aceptadas se reenvían bajo la identidad de la aplicación del escritorio y permanecen sujetas a la autorización del terminal. Nunca describa el emparejamiento como simplemente otorgar monitoreo pasivo.

Los permisos del asistente y las preguntas pendientes son interacciones de sesión separadas. Respóndelas en la interfaz de usuario móvil cuando se te solicite. Un token que puede llegar al punto final de respuesta no significa que ya se hayan aprobado todas las acciones de la herramienta.

Usar sesiones y recuperar conectividad

Elija un proyecto para inspeccionar su descripción general, historial, extracciones y ejecuciones de flujo de trabajo. Las sesiones del asistente se ejecutan en el escritorio con la configuración de su proveedor. Configure el proveedor allí primero. El teléfono recuerda un proyecto seleccionado y la última sesión por proyecto para el escritorio emparejado; cambiar la identidad del escritorio borra esa asignación.

Las comprobaciones en primer plano sondean con un presupuesto de 15 segundos. Las comprobaciones fallidas se retrasan hasta 30 segundos y al avanzar la aplicación se activa otra sonda. El estado en segundo plano se rastrea por separado del estado fuera de línea. Toque la fila del escritorio en la Configuración del teléfono para volver a verificar manualmente.

Los mensajes del asistente en cola se conservan con un máximo de 50 entradas, dejando las más antiguas más allá de ese límite. Lo vuelven a intentar más tarde y es posible que conserven su identificador de sesión. Se trata de soporte de entrega de mensajes limitado, no de cálculo CAD fuera de línea o ejecución exactamente una vez. Después de una escritura/turno interrumpido, inspeccione la sesión de escritorio y el proyecto antes de repetir el mismo cambio.

Revocar o desvincular deliberadamente

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"

Los tokens se verifican en cada nueva solicitud, por lo que las solicitudes posteriores que utilizan el token revocado fallan. La revocación no finaliza explícitamente una secuencia ya reenviada. Deshabilitar la puerta de enlace detiene al oyente; POST /api/companion/disable es el punto final administrativo.

Configuración del teléfono → Desvincular este teléfono elimina el emparejamiento guardado local y regresa a Connect. No llama al punto final de revocación del escritorio. Utilice ambas acciones al retirar un dispositivo. Para rotar solo la credencial del dispositivo, revocarla y emitir un nuevo emparejamiento; reemplazar todo el certificado también cambia el pin de cada teléfono.

Diagnosticar fallas por capa

Native CI crea una aplicación de simulador sin firmar y verifica el emparejamiento de puertas de enlace/lista de proyectos reales. Verificaciones de CI separadas, verificación de tipos, pruebas lógicas y exportación de JavaScript. Estos no prueban la firma de dispositivos físicos, la distribución de TestFlight, el enrutamiento de redes remotas ni un proveedor de modelos real.

Los tokens incorrectos repetidos se limitan: diez intentos fallidos desde una dirección IP en 60 segundos hacen que más solicitudes devuelvan HTTP 429 hasta que expire la ventana. Un 429 después de la reparación generalmente significa que todavía se está reintentando un token de dispositivo antiguo.

Mapa de implementación

El contrato de gestión es packages/api/src/groups/companion.ts. El ciclo de vida del sidecar y la política de ruta están en services/companion.ts y companion-gateway.ts. El análisis del teléfono, la recuperación de la conexión, el almacenamiento y la interfaz de usuario están en lib/pairing.ts, server.tsx, storage.ts, y app/connect.tsx. El delegado de confianza nativo es modules/companion-net/ios/CompanionNetModule.swift.

Para obtener un informe de soporte, conserve la versión de la aplicación, el método de conexión, el host/puerto de la puerta de enlace no secreta, el error/estado exacto y si el módulo nativo está presente. Redactar tokens, enlaces de emparejamiento, credenciales de modelo y claves privadas. Añade el API del sistema resultado de la versión al comparar dos procesos de desarrollo.

¿Qué puede llamar un teléfono emparejado?

Cada solicitud a través de la puerta de enlace debe llevar un token de dispositivo y coincidir con esta lista de permitidos. Todo lo demás, incluidas credenciales, complementos, archivos, facturación y /api/companion en sí, es rechazada. Las solicitudes admitidas se reenvían a la API de loopback con el token de la aplicación, que el teléfono nunca ve.

Anatomía del enlace de emparejamiento

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

El certificado es un certificado P-256 autofirmado cuyos nombres alternativos de sujeto incluyen localhost, 127.0.0.1y las direcciones privadas accesibles de la máquina. se mantiene en <dataDir>/companion, por lo que los emparejamientos sobreviven a los reinicios. Reemplazarlo cambia la huella digital y requiere emparejamiento nuevamente.

API de administración de puerta de enlace

Los intentos fallidos de portador se limitan por dirección IP: después de 10 fallas en 60 segundos, la puerta de enlace responde HTTP 429 ("Demasiados intentos fallidos") hasta que pase la ventana. De lo contrario, un token incorrecto o revocado obtiene HTTP 401.

Estado de la puerta de enlace, capturado

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

Si host no es la dirección a la que puede llegar su teléfono (por ejemplo, un contenedor o una interfaz VPN), el emparejamiento fallará en la capa de red aunque todo lo demás sea correcto.

En 3D