muse-protocol — muse.aiの登録・コード引き換え手順を解析したPython実装
duwqijlk/muse-protocol
★ 1,029 ・ Python
概要
duwqijlk/muse-protocol は、動画プラットフォームやAI関連サービスを提供する「muse.ai」のアカウント登録および招待コード引き換えの通信手順を解析し、PythonのHTTPクライアントとして実装したリサーチ目的のプロジェクトです。
Webブラウザ(Headlessブラウザなど)を自動操作するのではなく、ブラウザが行うHTTPリクエストとレスポンスをパケットキャプチャによってフィールド単位で精査し、純粋なHTTPリクエストのみで一連のフローを完結させている点が特徴です。Webサービスの認証・セッション管理の仕組みを調査したい開発者や、プロトコル解析の手法を学びたいエンジニアに向いている資料となっています。
主な特徴
- ブラウザ非依存の純粋なHTTP実装: SeleniumやPuppeteerといったブラウザ自動化ツールを使わず、HTTPリクエストのみで登録と招待コードの適用を完結させています。
- 詳細な通信シーケンスのドキュメント化: 最初のCookie取得からCSRFトークン発行、ワンタイムパスワード(OTP)検証、利用規約(TOS)の動的取得と同意、セッションブートストラップまでの流れが整理されています。
- 堅牢なOTPポーリング機構: 認証コードの取得に際し、送信リクエスト以降に発行された最新のコードのみを冪等に取得するロジック(
otp.py)を備えています。 - プロキシと連携したバッチ実行スケジューラ: 複数アカウントの処理を行うランナー(
runner.py)が含まれており、固定(Sticky)プロキシの排他制御やIPごとの成功上限カウント、エラー時の停止制御が設計されています。 - 任意設定可能なトラッキング(テレメトリ)の再現: クライアント側のパフォーマンス計測用エンドポイント(Falco)や、登録ファネルイベント(CAA)の送信ロジックが独立したモジュールとして実装されています。
使い方
READMEには、環境構築と単一アカウントでの実行、および複数アカウントの一括実行の手順が記載されています。
依存パッケージの導入と設定
まず、必要な依存ライブラリをインストールし、設定ファイルのひな形を複製して必要な情報を設定します。
pip install -r requirements.txt
cp config.example.json config.json # メールアドレスやプロキシ(任意)を設定
単一アカウントの実行
設定完了後、単一アカウントの登録・交換フローを実行するスクリプトを呼び出します。
python example_register.py
バッチ処理の実行
複数アカウントをまとめて処理する場合は、アカウント数(オプション)を指定してバッチ用スクリプトを実行します。
python example_batch.py [count]
バッチ処理で使用する設定項目(メールリスト、プロキシプール、招待コード一覧など)は config.json 内で指定可能です。
技術的なポイント
READMEに記載されているプロトコル解析結果から、muse.ai側の複雑な認証フローと、それをHTTPクライアントで忠実に再現するためのポイントがいくつか読み取れます。
プロトコルの全体フロー
登録からコード引き換えまでの通信は、大きく分けて以下のステップで進行します。
- 初期CookieおよびCSRFトークンの取得(
GET /,POST /api/auth/native/restart) - OTPの送信と検証(
POST /api/auth/native/send-otp,POST /api/auth/native/confirm-otp) - 基本情報登録とMetaセッショントークン発行(
POST /api/auth/native/register-completion) auth.meta.com経由のセッションブートストラップ(30xリダイレクト追従)- 動的開示情報(Disclosure)の解析と利用規約への同意(
POST /api/hatch/accept-tos) - 仮想環境の起動トリガー(
POST /api/hatch/vm/wake) - 招待コードの引き換え(
POST /api/hatch/invite-code/redeem) - 自身のアカウント用招待コードの取得(
POST /api/hatch/invite)
実装上の注意点と落とし穴の分析
READMEでは、プロトコルを再現する際にエラーを引き起こしやすい箇所が詳細に列挙されています。
- OTP確認パラメータ:
confirm-otpのリクエストボディには、supports_muse_link_transparency: trueを含める必要があります。 - 氏名フィールドと年齢制限:
register-completionでは、first_name(名)とlast_name(姓)が一般的な直感と逆に扱われる仕様になっています。また、生年月日(date_of_birth)がおよそ18歳未満になる値の場合、HTTP 403が返されるバリデーションが存在します。 - Metaセッションのブートストラップと動的TOS: 登録完了後、
auth.meta.com/hatch/session/bootstrap/にfrl_access_tokenをPOSTしてリダイレクトを処理し、最終的なmuse.aiのHTMLドキュメント(Next Flight形式のシリアライズデータ)を取得する必要があります。そのHTML内に含まれる動的な開示テキスト(disclosureTextやdisclosureVersion)を抽出し、accept-tosのボディにそのまま渡す必要があります(固定値のハードコードでは拒否されます)。 - 仮想環境の起動(
vm/wake)の呼び出し: 有効な招待コードであっても、事前にログイン後HTMLから正規表現でvmIdを抽出し、vm/wakeエンドポイントを叩いておかないと、「無効な招待コード」という誤ったエラーが返却されます。
バッチ実行エンジンの設計
musepy/runner.py では、大量リクエストによる遮断や不整合を防ぐため、以下のような制御設計が施されています。
- Stickyプロキシの排他制御: 1つのプロキシ行を同一時刻には1つのワーカーのみが専有して使用します。
- IPごとの検証成功数制限: 1つのプロキシにつき設定された成功上限(デフォルト6回)に達すると、そのプロキシを解放して別のプロキシへ切り替えます。
- OTP送信前の再試行: メール送信前の通信失敗であれば同一メールアドレスのままプロキシを変えて最大3回まで再試行します。
- エラー時の即時停止: サービス側の明示的な拒否やOTP送信後の失敗が発生した場合は、無駄な試行を防ぐためにバッチ全体を安全に停止します。
- 機密情報のメモリ保持: 取得した認証トークン(
frl_access_tokenやhatch_sess)はディスクに保存せず、メモリ内でのみ扱われます。
注意点
- ライセンスと利用範囲: READMEには「MITなどのオープンソースライセンスは採用していない」と明記されており、個人利用および非商用の学習・研究目的に限定されています。商用利用や再配布は禁止されています。
- 地域制限(ジオブロッキング): README冒頭に「日本(JP)のノードを利用すること」という注記があります。ブートストラップ後にサービス側から
resolvedDestination == "waitlist"やisGeoGated == trueと判定された場合は地域制限がかかり、登録自体は完了しても待機リスト扱いになります。 - 利用規約の遵守: 外部サービスのプロトコルを直接呼び出す実装であるため、対象サービスの利用規約や関連法令に抵触しないよう留意が必要です。
まとめ
muse-protocol は、Webフロントエンドとバックエンドの間で交わされる複雑なAPIシーケンスを丹念に紐解いたリバースエンジニアリングの成果物です。SPAや各種認証基盤が絡み合う近年のWebサービスにおいて、どのようなパラメータ検証やセッション引き継ぎが行われているのかを学ぶ上で、実践的な教材となるリポジトリです。





