# Enigma native host install guide

This public guide explains how to register the local Enigma native messaging host for a browser extension without publishing private extension IDs, local usernames, bundle contents, secrets, raw memory plaintext, or internal runbooks.

## What the native host does

The Enigma browser extension talks to a local native messaging host named:

```text
com.enigma.native_host
```

The host runs on the user's machine, reads the local Enigma bundle selected by `ENIGMA_BUNDLE`, and returns transient context plus receipt metadata to the extension after explicit user action and explicit user approval. The extension must ask the user before requesting context and again before inserting returned context into a provider page.

The host is a local bridge, not a provider-memory eraser. Provider-native memory remains cache only. Enigma can verify Enigma-controlled vault state and receipts; it cannot prove that a closed provider deleted hidden copies, disabled personalization, or made a model forget.

## Publication-safety boundaries

Reviewers should treat this page as the public installation checklist:

- Do not publish real extension IDs. Use placeholders until a signed/reviewed extension build is ready.
- Do not publish local account names, private install paths, bundle contents, secrets, API tokens, or enterprise policy values.
- Do not put raw memory plaintext in receipts, relay records, witness checkpoints, SIEM events, screenshots, or public proof artifacts.
- Keep raw memory in the local Enigma bundle. Browser records should stay limited to target metadata, insertion counts, timestamps, and receipt metadata.
- Keep any wrapper script owner-writable only. A process that can replace the host executable, wrapper, manifest, or `ENIGMA_BUNDLE` path can change what the extension receives.

## Prerequisites

1. Install or build Enigma so the host executable is available as `enigma-native-host`.
2. Create a local bundle and set `ENIGMA_BUNDLE` to its absolute path.

   macOS/Linux:

   ```sh
   mkdir -p "$HOME/.enigma"
   enigma init --bundle "$HOME/.enigma/bundle.json" --subject local-user --display-name "Local user"
   export ENIGMA_BUNDLE="$HOME/.enigma/bundle.json"
   ```

   Windows PowerShell:

   ```powershell
   New-Item -ItemType Directory -Force "$HOME\.enigma"
   enigma init --bundle "$HOME\.enigma\bundle.json" --subject local-user --display-name "Local user"
   [Environment]::SetEnvironmentVariable('ENIGMA_BUNDLE', "$HOME\.enigma\bundle.json", 'User')
   $env:ENIGMA_BUNDLE="$HOME\.enigma\bundle.json"
   ```

3. Resolve the absolute path to the host executable. Native messaging manifests do not expand `~`, `$HOME`, `%USERPROFILE%`, shell aliases, `PATH` lookups, or command arguments. Use the full executable or wrapper path.

   Example placeholders:

   - macOS/Linux: `/ABSOLUTE/PATH/TO/enigma-native-host`
   - Windows: `C:\\ABSOLUTE\\PATH\\TO\\enigma-native-host.cmd`

   Useful checks: `command -v enigma-native-host` on macOS/Linux, or `(Get-Command enigma-native-host.cmd).Source` in Windows PowerShell. If you use a wrapper to set `ENIGMA_BUNDLE`, resolve the wrapper's absolute path instead.

4. If the browser does not inherit the `ENIGMA_BUNDLE` environment variable, create a small local wrapper that sets `ENIGMA_BUNDLE` and then execs the absolute host executable path. Point the native messaging manifest `path` at that wrapper.

## Generate a manifest

Use the CLI generator instead of hand-editing JSON:

```sh
enigma native-host manifest \
  --browser chrome \
  --host-path "/absolute/path/to/enigma-native-host" \
  --extension-id "REPLACE_WITH_CHROME_EXTENSION_ID" \
  --out ./com.enigma.native_host.json
```

Windows PowerShell example:

```powershell
enigma native-host manifest `
  --browser edge `
  --host-path "C:\ABSOLUTE\PATH\TO\enigma-native-host.cmd" `
  --extension-id "REPLACE_WITH_EDGE_EXTENSION_ID" `
  --out .\com.enigma.native_host.json
```

Use `--browser chrome`, `--browser edge`, or `--browser firefox`. `--host-path` must be an absolute path to the host executable or to a local wrapper that sets `ENIGMA_BUNDLE` and then launches `enigma-native-host`; native messaging manifests do not expand `~`, `$HOME`, `%USERPROFILE%`, shell aliases, `PATH`, or command arguments. Without `--out`, the generator prints manifest JSON to stdout. With `--out`, it writes the manifest file and reports `{ ok, path }`. It does not copy the manifest into browser directories and does not write Windows registry keys.

Find the unpacked extension ID before running the command. Chrome and Edge native-host manifests require the 32-character lowercase ID shown by the browser:

- Chrome: open `chrome://extensions`, enable Developer mode, load `apps/browser-extension` unpacked, open the Enigma card details, and copy the ID.
- Edge: open `edge://extensions`, enable Developer mode, load `apps/browser-extension` unpacked, open the Enigma card details, and copy the ID.
- Firefox: open `about:debugging#/runtime/this-firefox`, load the extension temporarily, and use the listed extension ID. For repeatable development, set a stable `browser_specific_settings.gecko.id` in the extension manifest or use the ID assigned by the signed build, then pass the same value to `--extension-id`.

Keep `ENIGMA_BUNDLE` configured for the browser-launched process. GUI-launched browsers may not inherit shell environment variables; when in doubt, point `--host-path` at a wrapper that sets `ENIGMA_BUNDLE` to an absolute bundle path before launching the host.

## Manual template fallback

If you cannot use the generator, create one browser-specific `com.enigma.native_host.json` file from the source template and replace only these placeholders:

- `path` with the absolute executable or wrapper path.
- Chrome `REPLACE_WITH_CHROME_EXTENSION_ID` with the unpacked Chrome extension ID from `chrome://extensions` > Enigma > Details.
- Edge `REPLACE_WITH_EDGE_EXTENSION_ID` with the unpacked Edge extension ID from `edge://extensions` > Enigma > Details.
- Firefox `REPLACE_WITH_FIREFOX_EXTENSION_ID` with the Firefox add-on ID from `about:debugging#/runtime/this-firefox`, a stable development `browser_specific_settings.gecko.id`, or the installed/signed add-on ID.

Do not add command-line arguments to `path`. Browsers launch native messaging hosts through stdio using the executable path only.

### Chrome template shape

```json
{
  "name": "com.enigma.native_host",
  "description": "Enigma local native messaging host",
  "path": "/ABSOLUTE/PATH/TO/enigma-native-host",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://REPLACE_WITH_CHROME_EXTENSION_ID/"
  ]
}
```

### Edge template shape

```json
{
  "name": "com.enigma.native_host",
  "description": "Enigma local native messaging host",
  "path": "/ABSOLUTE/PATH/TO/enigma-native-host",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://REPLACE_WITH_EDGE_EXTENSION_ID/"
  ]
}
```

### Firefox template shape

```json
{
  "name": "com.enigma.native_host",
  "description": "Enigma local native messaging host",
  "path": "/ABSOLUTE/PATH/TO/enigma-native-host",
  "type": "stdio",
  "allowed_extensions": [
    "REPLACE_WITH_FIREFOX_EXTENSION_ID"
  ]
}
```

## Install locations

Save the filled manifest as `com.enigma.native_host.json`, then place or register it for the browser under test.

### Chrome

macOS per-user:

```sh
mkdir -p "$HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts"
cp com.enigma.native_host.json "$HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.enigma.native_host.json"
```

macOS all users:

```sh
sudo mkdir -p "/Library/Google/Chrome/NativeMessagingHosts"
sudo cp com.enigma.native_host.json "/Library/Google/Chrome/NativeMessagingHosts/com.enigma.native_host.json"
```

Linux per-user:

```sh
mkdir -p "$HOME/.config/google-chrome/NativeMessagingHosts"
cp com.enigma.native_host.json "$HOME/.config/google-chrome/NativeMessagingHosts/com.enigma.native_host.json"
```

Linux all users:

```sh
sudo mkdir -p /etc/opt/chrome/native-messaging-hosts
sudo cp com.enigma.native_host.json /etc/opt/chrome/native-messaging-hosts/com.enigma.native_host.json
```

Windows per-user registry entry:

```powershell
$manifest='C:\Users\REPLACE_WITH_USER\AppData\Local\Enigma\NativeMessagingHosts\com.enigma.native_host.json'
New-Item -Path 'HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.enigma.native_host' -Force | Out-Null
Set-Item -Path 'HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.enigma.native_host' -Value $manifest
```

Use `HKLM:\Software\Google\Chrome\NativeMessagingHosts\com.enigma.native_host` for an all-users install.

### Microsoft Edge

macOS per-user:

```sh
mkdir -p "$HOME/Library/Application Support/Microsoft Edge/NativeMessagingHosts"
cp com.enigma.native_host.json "$HOME/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.enigma.native_host.json"
```

macOS all users:

```sh
sudo mkdir -p "/Library/Microsoft/Edge/NativeMessagingHosts"
sudo cp com.enigma.native_host.json "/Library/Microsoft/Edge/NativeMessagingHosts/com.enigma.native_host.json"
```

Linux per-user:

```sh
mkdir -p "$HOME/.config/microsoft-edge/NativeMessagingHosts"
cp com.enigma.native_host.json "$HOME/.config/microsoft-edge/NativeMessagingHosts/com.enigma.native_host.json"
```

Linux all users:

```sh
sudo mkdir -p /etc/opt/edge/native-messaging-hosts
sudo cp com.enigma.native_host.json /etc/opt/edge/native-messaging-hosts/com.enigma.native_host.json
```

Windows per-user registry entry:

```powershell
$manifest='C:\Users\REPLACE_WITH_USER\AppData\Local\Enigma\NativeMessagingHosts\com.enigma.native_host.json'
New-Item -Path 'HKCU:\Software\Microsoft\Edge\NativeMessagingHosts\com.enigma.native_host' -Force | Out-Null
Set-Item -Path 'HKCU:\Software\Microsoft\Edge\NativeMessagingHosts\com.enigma.native_host' -Value $manifest
```

Use `HKLM:\Software\Microsoft\Edge\NativeMessagingHosts\com.enigma.native_host` for an all-users install.

### Firefox

macOS per-user:

```sh
mkdir -p "$HOME/Library/Application Support/Mozilla/NativeMessagingHosts"
cp com.enigma.native_host.json "$HOME/Library/Application Support/Mozilla/NativeMessagingHosts/com.enigma.native_host.json"
```

macOS all users:

```sh
sudo mkdir -p "/Library/Application Support/Mozilla/NativeMessagingHosts"
sudo cp com.enigma.native_host.json "/Library/Application Support/Mozilla/NativeMessagingHosts/com.enigma.native_host.json"
```

Linux per-user:

```sh
mkdir -p "$HOME/.mozilla/native-messaging-hosts"
cp com.enigma.native_host.json "$HOME/.mozilla/native-messaging-hosts/com.enigma.native_host.json"
```

Linux all users:

```sh
sudo mkdir -p /usr/lib/mozilla/native-messaging-hosts
sudo cp com.enigma.native_host.json /usr/lib/mozilla/native-messaging-hosts/com.enigma.native_host.json
```

Windows per-user registry entry:

```powershell
$manifest='C:\Users\REPLACE_WITH_USER\AppData\Local\Enigma\NativeMessagingHosts\com.enigma.native_host.json'
New-Item -Path 'HKCU:\Software\Mozilla\NativeMessagingHosts\com.enigma.native_host' -Force | Out-Null
Set-Item -Path 'HKCU:\Software\Mozilla\NativeMessagingHosts\com.enigma.native_host' -Value $manifest
```

Use `HKLM:\Software\Mozilla\NativeMessagingHosts\com.enigma.native_host` for an all-users install.

## Load and test the extension

1. Generate `com.enigma.native_host.json` with `enigma native-host manifest`, or fill the manual template fallback for the browser being tested.
2. Install or register that manifest at the browser/OS location above.
3. Open the browser extension management page.
4. Enable developer mode for an unpacked local build, or install the signed/reviewed extension build.
5. Confirm the extension ID matches the generated manifest allowlist.
6. Visit a supported provider page.
7. Use the Enigma control to request local context. The extension should ask the native host only after user action and should insert returned context only after user approval.

If the browser reports that the host is not found, re-check the manifest install location, registry key, manifest filename, host `name`, absolute executable path, executable permissions, environment inheritance or wrapper behavior, and extension ID allowlist.