Emparelhe o companheiro iOS

Verifique as duas extremidades da conexão

O companheiro é um cliente de um sidecar de desktop em execução. Ele não hospeda o banco de dados do projeto, o kernel de geometria, o provedor de modelo ou o executor de fluxo de trabalho. Antes de emparelhar, confirme se a área de trabalho abre seus projetos e se o telefone pode rotear para a área de trabalho por meio de Wi-Fi, ponto de acesso pessoal ou uma rede de sobreposição/VPN já configurada.

Use uma versão nativa do iOS contendo modules/companion-net. Expo Go não possui este módulo e não pode fazer a conexão fixada. O pacote também possui um substituto para o desenvolvimento do navegador, mas a busca do navegador não implementa a política de fixação nativa. A configuração do Android no manifesto não fornece um equivalente Android do módulo Swift.

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

O comando de execução do iOS requer macOS, Xcode e CocoaPods. Uma construção de dispositivo físico requer um dispositivo confiável e uma equipe de assinatura. bun run --cwd apps/mobile build exporta JavaScript; ele não cria um IPA instalável. Veja o referência móvel para layout e implementação de transporte.

Habilite o gateway da área de trabalho

Abra Configurações da área de trabalho → Dispositivos e seu painel complementar móvel ou use /settings/companion. Ligue o gateway, crie um emparelhamento nomeado e mostre seu código QR. Este é um ouvinte separado da API de loopback comum: HTTPS em IPv4 0.0.0.0, porta 8443 por padrão.

O serviço aceita portas inteiras 1024–65535. Se outro aplicativo ocupar a porta selecionada, a ativação falhará; escolha uma porta livre e crie um link com o endereço resultante. Permita a conexão através do firewall de desktop da rede que você pretende usar. O aplicativo não cria uma retransmissão pública, encaminhamento de porta ou VPN.

O estado e a porta ativados são persistentes. Após a reinicialização do sidecar, o gateway tenta retomar quando a API local estiver pronta. Os arquivos de certificado e chave privada ficam no diretório de dados secundários companion/ subdiretório; a chave privada é escrita com permissões exclusivas do proprietário. O aplicativo nativo confia no certificado para emparelhamento, e não em uma promessa genérica de que todo certificado local é seguro.

Inspecione e ative por meio da API de desktop

Para uma configuração de desenvolvimento reproduzível, use o token de inicialização de um sidecar isolado que você controla. Substitua a porta 43111 pela porta do evento pronto. Estas são chamadas de gerenciamento de desktop; o token do telefone não tem permissão para administrar seu próprio gateway.

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

O status contém estado ativado, porta/impressão digital anulável, host sugerido e entradas de dispositivo. A impressão digital pode ser nula antes que exista um certificado. Um público sonda de saúde estabelece a integridade do processo de loopback; isso não prova que o gateway HTTPS esteja habilitado, acessível ou aceitando um token de dispositivo. Use o API complementar para esquemas de gerenciamento exatos.

Crie um emparelhamento nomeado

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

Substitua o host de exemplo por um endereço que o telefone possa alcançar ou omita o host opcional para usar a descoberta. O nome é cortado e deve conter 1–60 caracteres. O sucesso é HTTP 201 com id e link. A criação de um token não habilita o ouvinte; habilite-o separadamente.

O link carrega o token do dispositivo, a impressão digital do certificado, a origem HTTPS primária, o nome e hosts alternativos opcionais. Exibir ou transferi-lo de forma privada para o telefone; é uma credencial. A área de trabalho armazena o hash do token em vez do texto simples. O registro não tem campo de expiração nesta implementação, portanto, revogue explicitamente um dispositivo obsoleto, em vez de presumir que ele irá expirar.

Carregue o emparelhamento no iOS

1. Abra a tela Connect do aplicativo CADCAMFUN instalado.
2. Escolha Digitalizar o código QR de emparelhamento e conceder acesso à câmera ou use Colar um link de emparelhamento.
3. Para entrada manual, forneça o endereço da área de trabalho, o token e a impressão digital completa do certificado por meio do formulário de conexão.
4. Permitir acesso à rede local quando o iOS solicitar. O acesso à câmera e o acesso à rede são permissões separadas.
5. Aguarde até que a investigação de integridade/inicialização seja bem-sucedida e o aplicativo abra Projetos.

O analisador requer uma origem HTTPS sem informações do usuário, conteúdo do caminho, consulta ou fragmento. Os tokens devem ter 16–4096 caracteres sem espaços em branco/caracteres de controle; as impressões digitais são exatamente 64 caracteres hexadecimais. Links inválidos são recusados antes do início das solicitações.

As origens alternativas descobertas são desduplicadas. O cliente corre com os candidatos, usa a primeira conexão bem-sucedida, aborta as outras e salva a origem bem-sucedida. O Discovery anuncia até seis endereços IPv4 privados adequados, incluindo Wi-Fi, ponto de acesso e intervalos IPv4 estilo Tailscale; o ouvinte IPv4 atual não anuncia hosts IPv6 descobertos.

Quais verificações de fixação de certificado

O transporte Swift usa efêmero URLSession instâncias e um delegado de confiança personalizado. Ele obtém os bytes DER do certificado folha, calcula SHA-256 e aceita a conexão somente quando esse hash for igual à impressão digital emparelhada. HTTPS é necessário e os redirecionamentos são recusados. Os chamadores nativos não retornam silenciosamente para a busca desafixada se o módulo estiver faltando.

Isso oferece suporte ao certificado autoassinado do desktop sem aceitar servidores autoassinados arbitrários. A decisão de confiança vem do QR/link de emparelhamento. A substituição do certificado de desktop altera essa decisão; crie um novo emparelhamento confiável em vez de suprimir a incompatibilidade.

Erros comuns de confiança do navegador/curl não são equivalentes a testar o delegado nativo do aplicativo. Um navegador pode rejeitar um servidor autoassinado corretamente fixado porque ele usa um armazenamento confiável diferente. Verifique por meio do aplicativo instalado e inspecione a falha real em vez de desabilitar a validação do certificado globalmente.

Após a autenticação bem-sucedida do dispositivo, o gateway registra um carimbo de data/hora visto pela última vez para seu estado de serviço atual. Atualize o status do dispositivo desktop para confirmar o tráfego autenticado. Isto indica o uso de token; não é uma prova de que todas as ações do projeto foram bem-sucedidas ou uma trilha de auditoria de segurança durável.

Entenda o escopo do token do dispositivo

O token do dispositivo é limitado pela lista de permissões de método/caminho. Não é inerentemente somente leitura e não seleciona um projeto. As solicitações aceitas são encaminhadas sob a identidade do aplicativo do desktop e permanecem sujeitas à autorização do endpoint. Nunca descreva o emparelhamento como uma mera concessão de monitoramento passivo.

As permissões do assistente e as perguntas pendentes são interações de sessão separadas. Responda-as na interface móvel quando solicitado. Um token que pode atingir o endpoint de resposta não significa que todas as ações da ferramenta já foram aprovadas.

Use sessões e recupere a conectividade

Escolha um projeto para inspecionar sua visão geral, histórico, pulls e execuções de fluxo de trabalho. As sessões do assistente são executadas na área de trabalho com as configurações do provedor. Configure o provedor primeiro. O telefone lembra um projeto selecionado e a última sessão por projeto para o desktop emparelhado; alterar a identidade da área de trabalho limpa esse mapeamento.

Sondagem de verificações em primeiro plano com um orçamento de 15 segundos. As verificações com falha são desativadas em até 30 segundos e o avanço do aplicativo aciona outra investigação. O estado em segundo plano é rastreado separadamente do estado offline. Toque na linha da área de trabalho nas configurações do telefone para verificar novamente manualmente.

As mensagens do assistente na fila são mantidas com no máximo 50 entradas, descartando as mais antigas além desse limite. Eles tentam novamente mais tarde e podem reter o identificador de sessão. Este é o suporte limitado à entrega de mensagens, não à computação CAD off-line ou à execução exatamente uma vez. Após uma gravação/rotação interrompida, inspecione a sessão da área de trabalho e o projeto antes de repetir a mesma alteração.

Revogar ou desemparelhar 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"

Os tokens são verificados a cada nova solicitação, portanto, as solicitações subsequentes que usam o token revogado falham. A revogação não encerra explicitamente um fluxo já encaminhado. Desativar o gateway interrompe o ouvinte; POST /api/companion/disable é o terminal administrativo.

Configurações do telefone → Desemparelhar este telefone exclui o emparelhamento local salvo e retorna para Conectar. Ele não chama o endpoint de revogação da área de trabalho. Use ambas as ações ao desativar um dispositivo. Para rotacionar apenas a credencial do dispositivo, revogue-a e emita um novo pareamento; substituir todo o certificado também altera o PIN de cada telefone.

Diagnosticar falhas por camada

O Native CI cria um aplicativo simulador não assinado e verifica o emparelhamento real do gateway/listagem de projetos. Verificações de CI separadas, verificação de tipo, testes lógicos e exportação de JavaScript. Isso não prova assinatura de dispositivo físico, distribuição TestFlight, roteamento de rede remota ou um provedor de modelo real.

Tokens inválidos repetidos são limitados: dez tentativas fracassadas de um endereço IP em 60 segundos fazem com que novas solicitações retornem HTTP 429 até que a janela expire. Um 429 após o novo emparelhamento geralmente significa que um token de dispositivo antigo ainda está sendo tentado novamente.

Mapa de implementação

O contrato de gestão é packages/api/src/groups/companion.ts. O ciclo de vida do sidecar e a política de rota estão em services/companion.ts e companion-gateway.ts. Análise de telefone, recuperação de conexão, armazenamento e UI estão em lib/pairing.ts, server.tsx, storage.ts, e app/connect.tsx. O delegado de confiança nativo é modules/companion-net/ios/CompanionNetModule.swift.

Para obter um relatório de suporte, guarde a versão do aplicativo, o método de conexão, o host/porta do gateway não secreto, o erro/status exato e se o módulo nativo está presente. Edite tokens, links de emparelhamento, credenciais de modelo e chaves privadas. Adicione o API do sistema resultado da versão ao comparar dois processos de desenvolvimento.

O que um telefone emparelhado pode ligar

Cada solicitação através do gateway deve conter um token de dispositivo e corresponder a esta lista de permissões. Todo o resto, incluindo credenciais, plug-ins, arquivos, cobrança e /api/companion em si, é recusado. As solicitações admitidas são encaminhadas para a API de loopback com o token do aplicativo, que o telefone nunca vê.

Anatomia do link de emparelhamento

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

O certificado é um certificado P-256 autoassinado cujos nomes alternativos de entidade incluem localhost, 127.0.0.1e os endereços privados acessíveis da máquina. É mantido em <dataDir>/companion, para que os emparelhamentos sobrevivam às reinicializações. Substituí-lo altera a impressão digital e requer emparelhamento novamente.

API de administração de gateway

As tentativas de portador com falha são limitadas por endereço IP: após 10 falhas em 60 segundos, o gateway responde HTTP 429 ("Muitas tentativas com falha") até que a janela passe. Caso contrário, um token errado ou revogado receberá HTTP 401.

Status do gateway, capturado

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

Se host não for o endereço que seu telefone pode alcançar (por exemplo, um contêiner ou interface VPN), o emparelhamento falhará na camada de rede, mesmo que todo o resto esteja correto.

Em 3D