メインコンテンツへスキップ

Electron ヒューズ

パッケージ時の機能トグル

ヒューズとは何か？​

Electron の機能の一部については、アプリケーション全体で特定の機能を無効にすることが理にかなっています。例えば、99% のアプリケーションは `ELECTRON_RUN_AS_NODE` を使用しません。これらのアプリケーションでは、その機能を使用できないバイナリを出荷できるようにしたいと考えています。また、Electron のソースからのビルドは、膨大な技術的課題であり、時間とコストの両面で大きな負担となるため、Electron ユーザーがソースから Electron をビルドすることを望んでいません。

ヒューズはこの問題に対する解決策です。高いレベルでは、Electron バイナリ内の「魔法のビット」であり、Electron アプリのパッケージング時に切り替えて、特定の機能/制限を有効/無効にすることができます。アプリにコード署名する前にパッケージ時に切り替えられるため、OS がコード署名検証（Gatekeeper/App Locker）を介してこれらのビットが元に戻されないようにする役割を担います。

現在のヒューズ​

runAsNode​

デフォルト：有効

@electron/fuses: FuseV1Options.RunAsNode

runAsNode ヒューズは、ELECTRON_RUN_AS_NODE 環境変数が尊重されるかどうかを切り替えます。このヒューズが無効になっている場合、メインプロセスでの process.fork は、この環境変数に依存して機能するため、期待通りに機能しません。代わりに、ユーティリティプロセス を使用することをお勧めします。これは、スタンドアロンの Node.js プロセス（Sqlite サーバープロセスなど）が必要な多くのユースケースで機能します。

cookieEncryption​

デフォルト：無効

@electron/fuses: FuseV1Options.EnableCookieEncryption

cookieEncryption ヒューズは、ディスク上の Cookie ストアが OS レベルの暗号化キーを使用して暗号化されるかどうかを切り替えます。デフォルトでは、Chromium が Cookie を保存するために使用する SQLite データベースは、値をプレーンテキストで保存します。アプリの Cookie を Chrome と同じ方法で暗号化したい場合は、このヒューズを有効にする必要があります。これは一方向の移行であることに注意してください。このヒューズを有効にすると、既存の暗号化されていない Cookie は書き込み時に暗号化されますが、その後ヒューズを無効にすると、Cookie ストアは事実上破損して使用できなくなります。ほとんどのアプリでは、このヒューズを安全に有効にできます。

nodeOptions​

デフォルト：有効

@electron/fuses: FuseV1Options.EnableNodeOptionsEnvironmentVariable

nodeOptions ヒューズは、NODE_OPTIONS と NODE_EXTRA_CA_CERTS 環境変数が尊重されるかどうかを切り替えます。NODE_OPTIONS 環境変数は、あらゆる種類のカスタムオプションを Node.js ランタイムに渡すために使用でき、通常は本番環境のアプリでは使用されません。ほとんどのアプリでは、このヒューズを安全に無効にできます。

nodeCliInspect​

デフォルト：有効

@electron/fuses: FuseV1Options.EnableNodeCliInspectArguments

nodeCliInspect ヒューズは、--inspect、--inspect-brk などのフラグが尊重されるかどうかを切り替えます。無効にすると、SIGUSR1 シグナルがメインプロセスのインスペクターを初期化しないことも保証されます。ほとんどのアプリでは、このヒューズを安全に無効にできます。

embeddedAsarIntegrityValidation​

デフォルト：無効

@electron/fuses: FuseV1Options.EnableEmbeddedAsarIntegrityValidation

embeddedAsarIntegrityValidation ヒューズは、macOS で実験的な機能を切り替えます。この機能は、ロード時に `app.asar` ファイルの内容を検証します。この機能は、パフォーマンスへの影響を最小限にするように設計されていますが、`app.asar` アーカイブ内のファイルの読み込み速度をわずかに遅くする可能性があります。

ASAR 整合性検証の使用方法の詳細については、ASAR の整合性 のドキュメントを参照してください。

onlyLoadAppFromAsar​

デフォルト：無効

@electron/fuses: FuseV1Options.OnlyLoadAppFromAsar

onlyLoadAppFromAsar ヒューズは、Electron がアプリコードの場所を検索するために使用する検索システムを変更します。デフォルトでは、Electron は次の順序で検索します `app.asar` -> `app` -> `default_app.asar`。このヒューズを有効にすると、検索順序は `app.asar` になり、`embeddedAsarIntegrityValidation` ヒューズと組み合わせることで、検証されていないコードをロードできなくなります。

loadBrowserProcessSpecificV8Snapshot​

デフォルト：無効

@electron/fuses: FuseV1Options.LoadBrowserProcessSpecificV8Snapshot

loadBrowserProcessSpecificV8Snapshot ヒューズは、ブラウザープロセスで使用される V8 スナップショットファイルを変更します。デフォルトでは、Electron のプロセスはすべて同じ V8 スナップショットファイルを使用します。このヒューズを有効にすると、ブラウザープロセスは V8 スナップショットファイルとして `browser_v8_context_snapshot.bin` を使用します。他のプロセスは通常どおり V8 スナップショットファイルを使用します。

grantFileProtocolExtraPrivileges​

デフォルト：有効

@electron/fuses: FuseV1Options.GrantFileProtocolExtraPrivileges

grantFileProtocolExtraPrivileges ヒューズは、`file://` プロトコルからロードされたページが、従来のWebブラウザで受信するよりも多くの権限が付与されるかどうかを変更します。この動作は、Electron の初期バージョンでは Electron アプリの中核でしたが、アプリはカスタムプロトコルからローカルファイルを提供する必要があるため、もはや必要ありません。`file://` からページを提供していない場合は、このヒューズを無効にする必要があります。

このヒューズによって `file://` プロトコルに付与される追加の権限は、以下に不完全に文書化されています。

  • `file://` プロトコルのページは、`fetch` を使用して `file://` 経由で他のアセットをロードできます。
  • `file://` プロトコルのページは、サービスワーカーを使用できます。
  • `file://` プロトコルのページには、サンドボックス設定に関係なく、`file://` プロトコルでも実行されている子フレームへの普遍的なアクセス権が付与されます。

ヒューズの切り替え方法​

簡単な方法​

これらのヒューズの切り替えを容易にするために、便利なモジュール @electron/fuses を作成しました。使用方法と潜在的なエラーケースの詳細については、そのモジュールのREADMEを参照してください。

const { flipFuses, FuseVersion, FuseV1Options } = require('@electron/fuses')

flipFuses(
  // Path to electron
  require('electron'),
  // Fuses to flip
  {
    version: FuseVersion.V1,
    [FuseV1Options.RunAsNode]: false
  }
)

ヒューズが切り替えられたことを検証したり、任意の Electron アプリのヒューズの状態を確認するには、fuses CLI を使用できます。

npx @electron/fuses read --app /Applications/Foo.app

難しい方法​

クイック用語集​

  • ヒューズワイヤ：ヒューズを制御するために使用される Electron バイナリ内のバイトシーケンス
  • センチネル：ヒューズワイヤを見つけるために使用できる静的な既知のバイトシーケンス
  • ヒューズスキーマ：ヒューズワイヤのフォーマット/許容値

ヒューズを手動で切り替えるには、Electron バイナリを編集し、ヒューズワイヤを、目的のヒューズの状態を表すバイトシーケンスに変更する必要があります。

Electron バイナリ内のどこかには、次のようなバイトシーケンスがあります。

| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |
  • sentinel_bytes は常にこの正確な文字列 `dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX` です。
  • fuse_version は、ヒューズスキーマのバージョンを表す符号なし整数の値を持つ1バイトです。
  • fuse_wire_length は、次のヒューズワイヤ内のヒューズ数を表す符号なし整数の値を持つ1バイトです。
  • fuse_wire は N バイトのシーケンスで、各バイトは1つのヒューズとその状態を表します。
    • 「0」（0x30）はヒューズが無効になっていることを示します。
    • 「1」（0x31）はヒューズが有効になっていることを示します。
    • 「r」（0x72）はヒューズが削除されており、バイトを 1 または 0 に変更しても効果がないことを示します。

ヒューズを切り替えるには、ヒューズワイヤ内の位置を見つけて、目的の状態に応じて「0」または「1」に変更します。

現在のスキーマは こちら で確認できます。