権限のアクティベーション

仮想ディスプレイの生成、画面キャプチャ、タッチイベントの注入には Android の shell レベルの権限が必要です。Android 版には3つのアクティベーション手段が用意されていますが、内蔵 ADB によるワイヤレスペアリングを推奨します：PC や Root 権限、外部管理アプリの追加インストールが一切不要です。

方式	前提条件	端末再起動後	セキュリティ境界
内蔵 ADB	Android 11 以降（Android 9〜10 は初回のみ PC から `adb tcpip 5555`）	再アクティベートが必要	ローカルループバック接続のみ、RSA 鍵認証
Root	Root 化済み（Magisk / KernelSU 等）	通常は自動的に維持	スーパーユーザー権限の付与
外部 Shizuku	Shizuku / Sui が導入済み	マネージャーの設定に依存	既存の認可権限を流用

内置 ADB（ワイヤレスペアリング）

内蔵実装は shizuku-m（Apache-2.0）を移植したものであり、ワイヤレスペアリング、オフライン自動再接続、暗号化キーのセキュアストレージ管理機能を備えています。

Android 11 以降

開発者向けオプションの有効化

設定 → 端末情報 → 「ビルド番号」を7回連続でタップします。その後、「システム → 開発者向けオプション」を開き、ワイヤレスデバッグを有効化します。

ペアリング画面の起動

アプリ内：設定 → 実行とセキュリティ → 内蔵 Shizuku → 「ペアリングを開始」をタップします。

ペアリングコードの取得

Android システムの「ワイヤレスデバッグ」設定画面内で「ペアリングコードでデバイスをペア設定」を選択します。6桁のペアリングコードとポート番号が表示されます。

通知が利用可能な場合：アプリから送信された通知の入力欄に直接6桁のコードを入力します。
通知が利用できない場合：画面分割（スプリットスクリーン）を使用し、システムのペアリング画面とアプリを並べて表示した上で、「手動でペアリングコードを入力」を開き、ポートと6桁のコードを入力します。

USB デバッグの許可承認

システム側に「このパソコンからの USB デバッグを常に許可しますか？」というダイアログが表示された場合は、「常に許可」にチェックを入れて OK をタップしてください。この確認を見落とすと「ペアリングは完了したがサービスが起動しない」原因になります。

アクティベーション完了の確認

認証が完了するとステータスが「準備完了」に切り替わり、ペアリング用フォームは自動的に閉じられます。ペアリングコードがディスクに永続化されることはありません。

Android 9〜10

OS 側にワイヤレスデバッグのペアリング画面が備わっていないため、初回のみ PC と USB 接続して adbd を TCP モードに切り替える必要があります：

bash

adb devices            # 端末が認識されていることを確認
adb tcpip 5555         # adbd をポート 5555 でリッスンさせる

その後、アプリ内で 127.0.0.1:5555 に接続します。USB ケーブルは取り外して構いませんが、端末を再起動した際は再度このコマンドを実行する必要があります。

ネットワーク切断と自動再接続

一度アクティベートに成功すれば、**同一次の起動中（再起動するまで）**であれば、Wi-Fi が切断されたり機内モードに切り替わった場合でもローカル接続は維持されます。以下の事象が発生した場合にのみ再アクティベートが必要になります：

端末本体の再起動
開発者オプション内での「USBデバッグの認可の取り消し」
「開発者向けオプション」または「ワイヤレスデバッグ」の無効化
アプリのデータ消去

5555 ポートの開放について

システムの adbd がポート 5555 で待機している場合、同一 LAN 内からアクセス可能になるリスクがあります。本アプリは常に 127.0.0.1 にのみ接続し、adbd 側も承認済み RSA キーを要求しますが、公共の Wi-Fi 環境下で無暗にワイヤレスデバッグを有効化し続けたり、見知らぬ PC からの接続を許可しないでください。

暗号化キーの保存仕様

ADB 接続用の RSA 秘密鍵は Android Keystore の AES-GCM 鍵により暗号化され、アプリのプライベート領域に格納されます。クラウドバックアップや機種変更移行の対象外として保護されています。

Root によるアクティベーション

Root 化されたデバイスでは Root バックエンドを選択できます：

アクティベーション画面で「Root」を選択します。
スーパーユーザー権限の要求ダイアログ（Magisk / KernelSU 等）で許可を与えます。
アプリは app_process を介して特権サービスを起動し、Binder コールバック時に root/shell UID とワンタイムトークンを照合検証します。

Root 経由の実行パイプラインは通常の ADB パスから完全に独立しています。特権コンテキストは特権子プロセス内にのみ限定され、通常のアプリプロセスへ権限が漏洩することはありません。

Root は「高機能な ADB」ではありません

Root は異なる起動パイプラインとセキュリティコンテキストを提供します。ADB 経路で固有の不具合が発生した際の代替として機能する場合がありますが、自動化の動作ロジック自体が変わるわけではありません。

外部 Shizuku の利用

すでに端末に Shizuku または Sui を導入し運用している場合：

アクティベーション画面で「外部サービス」を選択します。
Shizuku マネージャーアプリが稼働しており、本アプリに権限が付与されていることを確認します。
アプリは外部 Shizuku のユーザーサービス機構をそのまま再利用します。

内蔵認証と外部認証が同時に存在する場合、SHIZUKU バックエンドは内蔵接続を優先します。

バックエンド自動選択の優先順位

text

バックエンドの選択順位
├── 内蔵 ADB がアクティベート済み → 内蔵接続を使用
├── 外部 Shizuku が認可済み → 外部サービスを使用
└── Root 権限が利用可能 → Root を使用

実際のステート管理は PermissionManager が統括し、期限切れの古い接続やプロセスの死亡コールバックは Binder ID に基づいて安全に破棄されます。

アクティベーション完了の判定基準

チェック項目	期待される状態
アクティベーション画面のステータス	「準備完了」/ Ready
周回画面	仮想ディスプレイが正常に生成され、映像が描画される
タスク実行	画面キャプチャとタップ操作が実行され、タスクが進行する
アプリログ	`Binder` のタイムアウトや `SecurityException` が記録されていないこと

トラブルシューティング

現象	主な原因	対処方法
ペアリングコード入力後も応答なし	USB デバッグの承認ダイアログが未許可	再度ペアリングを行い、システムの確認画面を承認
「ペアリング完了後もサービス未起動」	5555 ポートが未待機、またはシステムに回収された	ワイヤレスデバッグを再起動。Android 9〜10 は PC から再実行
Binder 通信タイムアウト	特権サービスプロセスがタスクキルされた	バッテリー最適化を解除して再試行
MediaTek 端末で起動時クラッシュ	`LoadedApk.makeApplication` 関連の ROM 固有挙動	本アプリは Context-only 回避済みですが、解消しない場合はログを提出
端末再起動後に権限が切れた	Android の正常な仕様	再度アクティベーションを実行してください
外部 Shizuku に接続できない	Shizuku マネージャーが停止、または認可が剥奪	マネージャーアプリを開き再認可を実行

起動失敗や Binder タイムアウトの調査には、以下のデバッグログを参照してください：

text

debug/embedded_adb_launch.log

セキュリティ境界の設計

項目	セキュリティ設計
サービスの公開範囲	内蔵パスは汎用の Shizuku サービスを公開せず、他アプリへの権限委譲を行わない
コールバック検証	root/shell UID およびワンタイムトークンのみを承認。タイムアウト時は破棄
プロセスの生存管理	アプリ本体プロセスの終了と同時に特権子プロセスも確実に破棄
接続ポートの制限	クライアントはローカルループバック（127.0.0.1）にのみ接続
機密情報の保護	ペアリングコードをログファイルやディスクに出力しない

権限のアクティベーション

内置 ADB（ワイヤレスペアリング） ​

Android 11 以降 ​

Android 9〜10 ​

ネットワーク切断と自動再接続 ​

暗号化キーの保存仕様 ​

Root によるアクティベーション ​

外部 Shizuku の利用 ​

バックエンド自動選択の優先順位 ​

アクティベーション完了の判定基準 ​

トラブルシューティング ​

セキュリティ境界の設計 ​