iOS コンパニオンをペアリングする

接続の両端を確認してください

コンパニオンは、実行中のデスクトップ サイドカーのクライアントです。プロジェクト データベース、ジオメトリ カーネル、モデル プロバイダー、またはワークフロー ランナーをホストしません。ペアリングする前に、デスクトップがプロジェクトを開き、電話機が Wi-Fi、パーソナル ホットスポット、またはすでに設定されているオーバーレイ/VPN ネットワークを介してデスクトップにルーティングできることを確認してください。

を含むネイティブ iOS ビルドを使用します。 modules/companion-net。 Expo Go にはこのモジュールがないため、ピン接続を行うことができません。このパッケージにはブラウザ開発フォールバックもありますが、ブラウザの取得ではネイティブのピン留めポリシーが実装されていません。マニフェスト内の Android 構成は、Swift モジュールに相当する Android を提供しません。

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

iOS の run コマンドには、macOS、Xcode、および CocoaPods が必要です。物理デバイスのビルドには、信頼できるデバイスと署名チームが必要です。 bun run --cwd apps/mobile build javaScript をエクスポートします。インストール可能な IPA は作成されません。を参照してください。 モバイルリファレンス レイアウトとトランスポートの実装用。

デスクトップゲートウェイを有効にする

デスクトップの [設定] → [デバイスとそのモバイル コンパニオン] パネルを開くか、次を使用します。 /settings/companion。ゲートウェイをオンにして、名前付きペアリングを作成し、その QR コードを表示します。これは、通常のループバック API とは別のリスナーです: HTTPS on IPv4 0.0.0.0、デフォルトではポート 8443。

このサービスは整数ポート 1024 ～ 65535 を受け入れます。別のアプリケーションが選択したポートを占有している場合、有効化は失敗します。空いているポートを選択し、その結果のアドレスを使用してリンクを作成します。使用するネットワークのデスクトップ ファイアウォールを介した接続を許可します。アプリケーションはパブリック リレー、ポート転送、または VPN を作成しません。

有効な状態とポートは保持されます。サイドカーの再起動後、ローカル API の準備が整うとゲートウェイは再開を試みます。証明書と秘密キーのファイルはサイドカー データ ディレクトリの下にあります。 companion/ サブディレクトリ;秘密キーは所有者のみのアクセス許可で書き込まれます。ネイティブ アプリは、すべてのローカル証明書が安全であるという一般的な約束ではなく、ペアリングからの証明書を信頼します。

デスクトップ API を介して検査して有効化する

再現可能な開発セットアップを行うには、制御する分離されたサイドカーの起動トークンを使用します。ポート 43111 をイベント準備完了ポートに置き換えます。これらはデスクトップ管理呼び出しです。電話トークンは、独自のゲートウェイを管理することを許可されていません。

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

ステータスには、有効な状態、Null 可能なポート/フィンガープリント、推奨されるホスト、およびデバイスのエントリが含まれます。証明書が存在する前は、フィンガープリントが null になる可能性があります。一般の ヘルスプローブ ループバックプロセスの健全性を確立します。 HTTPS ゲートウェイが有効であること、到達可能であること、またはデバイス トークンを受け入れることを証明するものではありません。を使用します。 コンパニオンAPI 正確な管理スキームを実現します。

名前付きペアを 1 つ作成する

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

Replace the example host with an address the phone can reach, or omit the optional host to use discovery. The name is trimmed and must contain 1–60 characters.成功は HTTP 201 です id そして link。トークンを作成してもリスナーは有効になりません。別途有効にしてください。

このリンクには、デバイス トークン、証明書のフィンガープリント、プライマリ HTTPS オリジン、名前、およびオプションの代替ホストが含まれます。それを非公開で電話機に表示または転送する。それは資格情報です。デスクトップには、プレーンテキストではなくトークン ハッシュが保存されます。この実装ではレコードに有効期限フィールドがないため、期限切れになると想定するのではなく、古いデバイスを明示的に取り消します。

iOSにペアリングをロードする

1. インストールしたCADCAMFUNアプリの接続画面を開きます。
2. [ペアリング QR コードをスキャンしてカメラへのアクセスを許可する] を選択するか、[ペアリング リンクの貼り付け] を使用します。
3. 手動入力の場合は、接続フォームからデスクトップ アドレス、トークン、完全な証明書のフィンガープリントを入力します。
4. iOS のプロンプトが表示されたら、ローカル ネットワーク アクセスを許可します。カメラへのアクセスとネットワークへのアクセスは別の権限です。
5. ヘルス/ブートストラップ プローブが成功し、アプリがプロジェクトを開くまで待ちます。

パーサーには、ユーザー情報、パスの内容、クエリ、またはフラグメントのない HTTPS オリジンが必要です。トークンは、空白文字や制御文字を含まない 16 ～ 4096 文字である必要があります。フィンガープリントは正確に 64 個の 16 進文字です。無効なリンクはリクエストが開始される前に拒否されます。

検出された代替オリジンは重複排除されます。クライアントは候補を競い合い、最初に成功した接続を使用し、他の接続を中止して、成功したオリジンを保存します。 Discovery は、Wi-Fi、ホットスポット、Tailscale スタイルの IPv4 範囲を含む、最大 6 つの適切なプライベート IPv4 アドレスをアドバタイズします。現在の IPv4 リスナーは、検出された IPv6 ホストをアドバタイズしません。

証明書の固定チェックの内容

Swift トランスポートはエフェメラルを使用します URLSession インスタンスとカスタム信頼デリゲート。リーフ証明書の DER バイトを取得し、SHA-256 を計算し、そのハッシュがペアのフィンガープリントと等しい場合にのみ接続を受け入れます。 HTTPS が必須であり、リダイレクトは拒否されます。モジュールが見つからない場合、ネイティブ呼び出し元はサイレントに固定解除フェッチにフォールバックしません。

これにより、任意の自己署名サーバーを受け入れることなく、デスクトップの自己署名証明書がサポートされます。信頼性の決定は、ペアリングの QR/リンクから行われます。デスクトップ証明書を置き換えると、その決定が変わります。不一致を抑制するのではなく、信頼できる新しいペアを作成します。

通常のブラウザ/カールの信頼エラーは、アプリのネイティブ デリゲートのテストと同等ではありません。ブラウザーは、別の信頼ストアを使用しているため、正しく固定された自己署名サーバーを拒否する場合があります。証明書の検証をグローバルに無効にするのではなく、インストールされているアプリを通じて検証し、実際の障害を検査します。

デバイス認証が成功すると、ゲートウェイは現在のサービス状態の最後に確認されたタイムスタンプを記録します。デスクトップデバイスのステータスを更新して、認証されたトラフィックを確認します。これはトークンの使用を示します。すべてのプロジェクト アクションが成功したという証拠や、永続的なセキュリティ監査証跡ではありません。

デバイストークンのスコープを理解する

デバイス トークンは、メソッド/パス許可リストによって制限されます。これは本質的に読み取り専用ではなく、1 つのプロジェクトを選択しません。受け入れられたリクエストはデスクトップのアプリケーション ID で転送され、エンドポイントの承認の対象のままになります。ペアリングを単に受動的モニタリングを許可するものとして説明しないでください。

アシスタントの権限と保留中の質問は、別個のセッション インタラクションです。要求されたら、モバイル UI で回答します。応答エンドポイントに到達できるトークンは、すべてのツール アクションがすでに承認されていることを意味するわけではありません。

セッションを使用して接続を回復する

プロジェクトを選択して、その概要、履歴、プル、およびワークフローの実行を検査します。アシスタント セッションは、プロバイダー設定を使用してデスクトップ上で実行されます。まずそこでプロバイダーを構成します。電話機は、選択したプロジェクトと、ペアになったデスクトップのプロジェクトごとの最後のセッションを記憶します。デスクトップ ID を変更すると、そのマッピングがクリアされます。

フォアグラウンド チェックは、15 秒の予算でプローブします。失敗したチェックは最大 30 秒までバックオフされ、アプリを前進させると別のプローブがトリガーされます。バックグラウンド状態は、オフライン状態とは別に追跡されます。電話機の設定でデスクトップの行をタップして、手動で再確認します。

キューに入れられたアシスタント メッセージは最大 50 個のエントリで保持され、その制限を超えると最も古いものから削除されます。後で再試行し、セッション識別子を保持する場合があります。これは制限付きメッセージ配信のサポートであり、オフライン CAD 計算や 1 回限りの実行ではありません。書き込み/ターンが中断された後、同じ変更を繰り返す前にデスクトップ セッションとプロジェクトを検査します。

意図的に取り消すかペアリングを解除する

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"

トークンは新しいリクエストごとにチェックされるため、取り消されたトークンを使用する後続のリクエストは失敗します。取り消しによって、すでに転送されたストリームが明示的に終了されるわけではありません。ゲートウェイを無効にすると、リスナーが停止します。 POST /api/companion/disable は管理エンドポイントです。

電話設定→この電話のペアリングを解除すると、ローカルに保存されたペアリングが削除され、接続に戻ります。デスクトップ取り消しエンドポイントは呼び出しません。デバイスを廃止する場合は、両方のアクションを使用します。デバイスの資格情報のみをローテーションするには、それを取り消して、新しいペアリングを発行します。証明書全体を置き換えると、すべての電話機の PIN も変更されます。

レイヤごとに障害を診断する

ネイティブ CI は、署名されていないシミュレーター アプリを構築し、実際のゲートウェイのペアリング/プロジェクトのリストを確認します。個別の CI チェック、タイプチェック、ロジック テスト、および JavaScript エクスポート。これらは、物理デバイスの署名、TestFlight 配布、リモート ネットワーク ルーティング、または実際のモデル プロバイダーを証明するものではありません。

不正なトークンが繰り返されるとスロットリングされます。60 秒以内に 1 つの IP アドレスからの試行が 10 回失敗すると、その IP アドレスからのさらなるリクエストは、期限が切れるまで HTTP 429 を返します。再ペアリング後の 429 は、通常、古いデバイス トークンがまだ再試行されていることを意味します。

実施マップ

マネジメント契約は、 packages/api/src/groups/companion.ts。サイドカーのライフサイクルとルート ポリシーは次のとおりです。 services/companion.ts そして companion-gateway.ts。電話の解析、接続回復、ストレージ、UI が含まれています lib/pairing.ts, server.tsx, storage.ts、 そして app/connect.tsx。ネイティブの信頼デリゲートは次のとおりです。 modules/companion-net/ios/CompanionNetModule.swift.

サポート レポートの場合、アプリのバージョン、接続方法、非シークレット ゲートウェイのホスト/ポート、正確なエラー/ステータス、ネイティブ モジュールが存在するかどうかを保持します。トークン、ペアリング リンク、モデル認証情報、および秘密キーを編集します。を追加します。 システムAPI 2 つの開発プロセスを比較した場合のバージョン結果。

ペアリングされた電話で通話できるもの

ゲートウェイを経由するすべてのリクエストにはデバイス トークンが含まれており、この許可リストと一致する必要があります。認証情報、プラグイン、ファイル、請求など、その他すべて /api/companion それ自体が拒否されます。承認された要求は、アプリケーション トークンとともにループバック API に転送されますが、電話機ではこれを認識することはありません。

ペアリングリンクの構造

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

この証明書は自己署名 P-256 証明書であり、そのサブジェクトの代替名には次のものが含まれます。 localhost, 127.0.0.1、およびマシンの到達可能なプライベート アドレス。に保管されています <dataDir>/companion、そのため、ペアリングは再起動しても存続します。交換すると指紋が変更され、再度ペアリングする必要があります。

ゲートウェイ管理API

ベアラー試行の失敗は IP アドレスごとに調整されます。10 秒以内に 60 回失敗すると、ゲートウェイはウィンドウが経過するまで HTTP 429 (「失敗した試行が多すぎます」) に応答します。それ以外の場合、間違ったトークンまたは取り消されたトークンは HTTP 401 を取得します。

ゲートウェイのステータス、キャプチャ済み

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

もし host 電話機が到達できるアドレス (コンテナーや VPN インターフェイスなど) ではない場合、他のすべてが正しい場合でも、ネットワーク層でペアリングが失敗します。

3Dで