
2026/04/20 20:51
Firefox の WebUSB エグステンション
RSS: https://news.ycombinator.com/rss
要約▶
Japanese Translation:
Firefox の WebUSB 拡張機能は、デスクトップオペレーティングシステム(Windows、macOS、およびさまざまな Linux ディストリビューション)で専用ネイティブヘルパープログラムである「stub」を利用して、直接の USB ハードウェアアクセスを提供します。この実装では標準的なブラウザ API と異なり、メインページスレッドだけで動作し、Android やバックグラウンド Web Worker をサポートしません。インストールには、プリビルトバイナリのダウンロードまたはソースからのビルド(x86_64、ARM64/aarch64 に対応)を行い、その後ネイティブマニフェスト JSON ファイルを登録するためのインストーラースクリプト(例:
install.sh または install.bat)を実行する必要があります。Windows の場合、特定のレジストリキーを設定する必要があります。stub は Rust で書かれておりクロスコンパイルをサポートしていますが、利用者は以下のシステム要件に注意する必要があります:macOS 10.15 以上、Windows 10 以上、Linux カーネル 4.8 以上です。開発者が直面する可能性のある制限としては、Windows での MSVC ツールチェーンの非対応(mingw-w64 を推奨)、macOS でのベンダ SDK に関するリンク問題、Linux での未テスト Glibc ビルドなどがあります。また、インストーラーは異なる CPU アーキテクチャ間での共有ホームディレクトリのような uncommon な構成で失敗する可能性もあります。したがって、この解決策は Chrome の実装に似た強力な接続性を提供しますが、標準的な Web 機能とは異なる設定プロセスが必要であり、アーキテクチャドキュメントに詳述された特定の展開制約を課します。本文
Firefox の WebUSB 拡張機能
本拡張機能はネイティブメッセージングを活用することで、Firefox に WebUSB の機能を追加します。この機能を利用するには、ブラウザ内に拡張機能をインストールするのと同時に、お使いのコンピューターにブラウザとは別個の小型プログラムをインストールする必要があります。この追加プログラムは「ネイティブスタブ」と呼ばれます。
対応機能
本拡張機能は Chrome の実装と互換性があることを目指して開発されています。ソフトウェアが正常に動作しない原因となった差異については、必ずご報告いただけますようお願い申し上げます。ただし、Chrome とは異なり、この API はメインページのみで公開されており、Web Worker からは利用できません。また、Android ではネイティブメッセージングの機能がないため対応することはできません。
インストール手順
本拡張機能は、GitHub の「Releases」セクション(右側のカラム)からバイナリをダウンロードするか、ソースから自分でビルドすることでインストールできます。
拡張機能のインストール
署名されたバージョンの拡張機能をインストールするには、.xpi ファイルをダウンロードし、それを Firefox で開きます。Firefox Developer Edition にテスト用のバージョンをロードするには、「about:debugging」を開き、左側のリストで「この Firefox」を選択した後、「Load Temporary Add-on…(仮加載…)」をクリックし、拡張機能/ ディレクトリ内の manifest.json ファイルを指定します。
ネイティブスタブのインストール
事前構築済みバイナリを使用している場合は、すべてのファイルを解凍した上で、Linux/macOS では ./install.sh、Windows では install.bat を実行してください。これらのインストーラーは、適切と思われる場所に相关文件を自動的にコピーし、ブラウザがそれを見つけるようネイティブマニフェストを設定します。
以下のプラットフォームに対して事前構築済みバイナリを提供しています:
- macOS x86_64 および ARM64
- Linux x86_64 および aarch64
- Windows AMD64 および ARM64
事前構築済みバイナリを使用しない場合は、以下をご覧ください。
「特殊な」構成
デフォルトのインストーラーは、以下のような不寻常な構成では問題が生じることが確認されています:
- 異なる CPU アーキテクチャを持つ複数のコンピューターで共有されている *nix ホームディレクトリ
- 異なる CPU アーキテクチャを持つ複数のコンピューター間で roaming ユーザープロファイルを使用している Windows など
根本原因は、「ネイティブマニフェスト」メカニズムが絶対パスなどの理由により、これらの状況を十分に考慮していない設計になっていることです。こうした状況に該当する場合は残念ながら、適応的なワークアラウンド策を自分で考案する必要があります。
システム要件
このネイティブスタブは何もしすぎないように心がけていますが、開発およびテストのリソース制約のため、「比較的新しい」デスクトッププラットフォームに焦点を当てています。
macOS
Firefox のシステム要件に合わせ、macOS 10.15(Catalina)以降が必要です。ただし、より古いシステムについては十分に検証されておらず、macOS 12(Monterey)以上の環境を基準とすると実用上かなり合理的でしょう。
Windows
Rust プラットフォームのサポート要件により、Windows 10 以降が必要です。これ 또한 Firefox のシステム要件とも一致しています。Windows 8/8.1 へのポートバックは理論上可能かもしれませんが、それ以前は WinUSB の制限により動作しないことが想定されます。
Linux
Linux カーネル バージョン 4.8 以降が必要です(より具体的には、コミット 5cce438 および USBDEVFS_CAP_REAP_AFTER_DISCONNECT を含むカーネルと、USBDEVFS_DISCONNECT_CLAIM をサポートするカーネルの両方が強く推奨され、かつ /dev および /sys がマウントされている必要があります)。USB デバイスの接続を検出するためには、udev またはそれと互換のあるデーモンが動作するユーザースペースが必要です。具体的には、NETLINK_KOBJECT_UEVENT グループ 2 で 0xfeedcafe フォーマットの手書きメッセージをブロードキャストするデーモンが必要です。
ソースからのコンパイル
原則として、このネイティブスタブは完全に Rust で書かれており、native-stub ディレクトリ内で cargo build を実行することでビルドできます。クロスコンパイルもサポートされており、対応プラットフォームではデフォルトで構成されています。
これが「ただ動作しない」という場合は、以下の注記が役立ちます:
macOS
このシステムであればほぼ問題なく動作するはずです。リポジトリには最終バイナリをリンクするために必要なすべての .tbd ファイルのバインド済みコピーが含まれています。それでも何らかの問題を引き起こす場合、.cargo/config.toml の該当するエントリを無効にしてください(その場合は macOS SDK がインストールされている必要があることにご注意ください)。
Linux
Linux の事前構築済みバイナリは、Rust のデフォルトである静的リンキングを使用するように musl libc を設定されています。目的はどのディストロでも動作するバイナリを生成することです。これを望まない場合、適切な RUSTFLAGS を変更する必要があるかもしれません。glibc ビルドも動作する可能性がありますが、テストされていません。
Windows
Windows の事前構築済みバイナリは、UCRT をターゲットとした mingw-w64 を使用してビルドするように設定されています。これは Rust における *-windows-gnullvm ターゲットに対応します。Windows では主に Windows 以外のプラットフォームからクロスビルドしてテストされており、Windows 上での直接ビルドも理論上は動作するはずです。ただし、rust-mingw コンポーネントの追加が必要になる場合があります。詳細については rustc のドキュメントを参照してください。Windows 以外のシステムからビルドする場合は、mingw-w64 .lib ファイルを取得する必要があります(Dockerfile 内の手順をたどるなど)。.cargo/config.toml にハードコードされたパスを確認・変更し、これらのライブラリを見つける必要があります。MSVC ツールチェーンを使用したビルドはサポートしていません(根本的な問題があるわけではなく、単にテストされていないだけです)。
ネイティブマニフェストの設定
ブラウザがコンパイルされたバイナリを見つけるためには、コンピューターの特定の場所に「マニフェスト」ファイルをインストールする必要があります。マニフェストとは、オペレーティングシステムに応じて特定のパターンを持つ短い JSON(JavaScript -object-notation)ファイルです。以下にドキュメントに関連する行を繰り返します:
macOS
- /Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json(グローバル)
- ~/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json(ユーザーローカル)
Linux
- /usr/lib/mozilla/native-messaging-hosts/awawausb_native_stub.json(グローバル)
- /usr/lib64/mozilla/native-messaging-hosts/awawausb_native_stub.json(グローバル)
- ~/.mozilla/native-messaging-hosts/awawausb_native_stub.json(ユーザーローカル)
Windows
マニフェストファイルはどこに置くこともできますが、レジストリキーを設定してそれへの参照を指す必要があります。レジストリキーは次の通りです:
- HKLM\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub(グローバル)
- HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub(ユーザーローカル)
以下のスクリーンショットは、正しく構成されたレジストリエントリの例を示しています:
ネイティブマニフェストの内容
JSON ファイルには以下の内容を含める必要があります:
{ "name": "awawausb_native_stub", "description": "Allows WebUSB extension to access USB devices", "path": "/path/to/awawausb-native-stub", "type": "stdio", "allowed_extensions": ["awawausb@arcanenibble.com"] }
ただし、Windows 上では完全なパスではなく、ファイル名のみ(例:"awawausb-native-stub.exe")でも十分です。
開発者向けドキュメント
概要を得るには、「Documentation/architecture.md」を参照してください。