How Motrix Installs Native Messaging Extensions for Browser Integration

Motrix installs native messaging extensions by generating a platform-specific host manifest from a static allow-list JSON file and registering it with Chrome, Chromium, and Firefox during application startup.

Motrix is an open-source download manager built with Electron that integrates with web browsers via the Native Messaging API. Understanding how native messaging extensions are installed for browser integration with Motrix requires examining the bridge layer in the main process, which automates manifest generation and registration across operating systems.

Architecture Overview

Native messaging allows browser extensions to communicate securely with the host operating system. Motrix implements this through a dedicated bridge module that writes a JSON manifest to browser-specific directories or registry keys. This process ensures only authorized extensions listed in the repository's configuration can connect to the native host binary.

The Extension Allow-List Configuration

Before installation occurs, Motrix defines which browser extensions are permitted to communicate with the application. This security boundary is enforced through a static configuration file.

Defining Authorized Extensions

The file src/shared/config/native-messaging-extensions.json contains the canonical list of allowed extension IDs:

{
  "chromium": ["ibpkjhgpbidfmbmomagmldcdlpbmchgi"],
  "firefox": ["motrix-bridge@motrix.app"]
}

During the build process, this JSON is imported by the installer module to populate the allowed_origins field of the native host manifest.

Manifest Generation and Installation Logic

The core installation logic resides in src/main/bridge/native-messaging-installer.ts. This TypeScript module constructs the manifest data structure and handles the physical installation across platforms.

Creating the Host Manifest

The installer dynamically generates a manifest object conforming to the Chromium and Firefox Native Messaging specifications. The manifest specifies the binary path and authorized extension origins:

import nativeMessagingExtensions from '@shared/config/native-messaging-extensions.json';
import { getNativeHostPath } from './native-host-path';

function createManifest(): object {
  return {
    name: 'com.motrix.native_host',
    description: 'Motrix native messaging host',
    path: getNativeHostPath(),
    type: 'stdio',
    allowed_origins: [
      ...nativeMessagingExtensions.chromium.map(id => `chrome-extension://${id}/`),
      ...nativeMessagingExtensions.firefox.map(id => `moz-extension://${id}/`)
    ]
  };
}

Writing Configuration Files

For Unix-like systems, the installer uses Node.js filesystem utilities to write the manifest to the appropriate directories. On Windows, it creates registry entries pointing to the manifest file location.

Platform-Specific Installation Paths

Motrix adapts its installation strategy based on the host operating system, ensuring compatibility with standard browser discovery mechanisms.

Linux and macOS Directories

On Linux and macOS, browsers scan specific directories for native messaging manifests. The installer copies the generated JSON to:

• Chrome/Chromium: $XDG_CONFIG_HOME/google-chrome/NativeMessagingHosts/ and $XDG_CONFIG_HOME/chromium/NativeMessagingHosts/
• Firefox: $XDG_CONFIG_HOME/mozilla/native-messaging-hosts/

These paths are resolved at runtime by src/main/bridge/native-host-path.ts.

Windows Registry Keys

Windows browsers locate native messaging hosts through the registry. Motrix writes the following keys:

• HKCU\Software\Google\Chrome\NativeMessagingHosts\com.motrix.native_host
• HKCU\Software\Mozilla\NativeMessagingHosts\com.motrix.native_host

Each key's default value points to the absolute path of the com.motrix.native_host.json manifest file.

Startup Integration and Security

The installation process is not manual; it executes automatically whenever Motrix launches.

Automatic Installation at Startup

The src/main/bridge/bridge-manager.ts module orchestrates the initialization sequence. During the application's startup phase, it invokes the installer's registration functions to ensure the manifest is current, even after application updates relocate the native host binary.

Security Validation

When a browser extension attempts to connect, the browser validates the extension's ID against the allowed_origins array in the manifest. Because Motrix generates this array exclusively from the static native-messaging-extensions.json file, unauthorized extensions cannot establish a connection, preventing arbitrary code execution by malicious browser add-ons.

Summary

• Motrix maintains an allow-list of extension IDs in src/shared/config/native-messaging-extensions.json.
• The installer in src/main/bridge/native-messaging-installer.ts generates a JSON manifest mapping authorized extensions to the native host binary.
• Platform-specific logic in src/main/bridge/native-host-path.ts determines whether to write to filesystem directories (Linux/macOS) or registry keys (Windows).
• src/main/bridge/bridge-manager.ts triggers installation automatically during application startup.
• The allowed_origins restriction ensures only official Motrix browser extensions can communicate with the host process.

Frequently Asked Questions

Where does Motrix store the native messaging manifest on Windows?

On Windows, Motrix stores the manifest file in the application directory and registers its path in the Windows Registry under HKCU\Software\Google\Chrome\NativeMessagingHosts\com.motrix.native_host for Chrome and HKCU\Software\Mozilla\NativeMessagingHosts\com.motrix.native_host for Firefox. Browsers read these registry keys to locate the manifest.

How does Motrix prevent unauthorized extensions from connecting?

Motrix prevents unauthorized connections by generating a static allowed_origins list in the native host manifest based solely on the IDs defined in native-messaging-extensions.json. The browser enforces this policy natively, rejecting connection attempts from any extension not explicitly listed in this configuration.

Why does Motrix reinstall the native messaging host on every startup?

Motrix reinstalls the native messaging host during every startup to ensure the manifest path remains accurate after application updates or changes to the user's home directory. This guarantees that browser integrations continue functioning without requiring manual reconfiguration when the application moves or upgrades.

Which browsers are officially supported for native messaging integration?

According to the source configuration, Motrix officially supports Google Chrome, Chromium, and Firefox through their respective native messaging APIs. The installer registers the host manifest for all three browsers simultaneously when available on the system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}