codex-control-chrome-mcp 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [Unreleased]
+
+## [1.1.0] - 2026-06-27
+
+### Added
+
+- Self-healing native host registration: the MCP stdio server re-asserts the manifest on startup when a Codex update reverts it (opt out with `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1`).
+- Robust identification of OpenAI's genuine host via stable signals (manifest name + extension origin, bundle path, binary format, and the macOS OpenAI code signature) instead of the binary filename.
+- `status` now reports `registered` and a `classification` of the live manifest/host.
+
+### Fixed
+
+- Proxy target resolution preferred a stale recorded path over the live manifest, so a renamed/removed official host (e.g. `extension-host` → `Codex for Chrome`) could be recorded as the proxy target. It now prefers the live official manifest and skips paths that no longer exist.
+
+## [1.0.1] - 2026-06-26
+
+### Added
+
+- Open source governance files.
+- CI and npm trusted publishing workflows.
+- Node.js test coverage for framing, RPC, and installer behavior.
+
+### Changed
+
+- Runtime package name and version are now read from `package.json` instead of being hard-coded in implementation files.
+
+## [1.0.0] - 2026-06-26
+
+### Added
+
+- Initial npm package.
+- MCP stdio server.
+- Chrome Native Messaging host bridge.
+- Native host install and uninstall commands with manifest backup.
+- Basic Chrome tab, navigation, screenshot, CDP, and event MCP tools.
+- Skill documentation for Agent tool usage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iola1999
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,55 +1,167 @@
 # Codex Control Chrome MCP
 
-Expose the Codex Chrome extension flow to other Agent tools through MCP.
+[![npm version](https://img.shields.io/npm/v/codex-control-chrome-mcp.svg)](https://www.npmjs.com/package/codex-control-chrome-mcp)
+[![CI](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Expose the Codex Chrome Extension flow to other Agent tools through MCP.
+
+This project lets MCP clients control the user's normal Chrome profile through the installed [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg). It is useful when an Agent needs existing tabs, cookies, logged-in sessions, installed extensions, screenshots, console/network events, or raw Chrome DevTools Protocol commands.
+
+This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.
 
 - NPM: [codex-control-chrome-mcp](https://www.npmjs.com/package/codex-control-chrome-mcp)
 - GitHub: [iola1999/codex-control-chrome-mcp](https://github.com/iola1999/codex-control-chrome-mcp)
 - Chrome Extension: [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)
 - Skill: [`skills/codex-control-chrome-mcp/SKILL.md`](./skills/codex-control-chrome-mcp/SKILL.md)
 
-Current implementation is an early Node.js prototype with:
+## Status
+
+The current implementation provides:
 
 - official `@modelcontextprotocol/sdk` stdio server
 - Chrome Native Messaging host mode
-- MCP stdio server mode
 - install/uninstall commands with manifest backup
 - JSON-RPC bridge socket under `/tmp/codex-browser-use`
-- basic Chrome tab/CDP MCP tools
+- Chrome tab, navigation, screenshot, CDP, and event MCP tools
+- bundled skill documentation for Agent tool ordering
 
-Install the Chrome native host:
+## Platform Support
 
-```bash
-npx -y codex-control-chrome-mcp@latest install-native-host
-```
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Tested | Primary supported platform. |
+| Linux | Experimental | Manifest path targets Google Chrome under `~/.config/google-chrome`. |
+| Windows | Unsupported | Native Messaging registration uses registry keys on Windows and is not implemented yet. |
 
-The user must also have the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) installed and enabled in the Chrome profile they want to automate.
+Node.js 20 or newer is required. npm Trusted Publishing for releases uses Node.js 24 in GitHub Actions.
 
-Uninstall and restore the previous Codex native host manifest:
+## Quick Start
+
+Install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome profile you want to automate.
+
+Install the Chrome native host:
 
 ```bash
-npx -y codex-control-chrome-mcp@latest uninstall-native-host
+npx -y codex-control-chrome-mcp@latest install-native-host
 ```
 
-Intended Agent config:
+Configure your Agent to use the MCP stdio server:
 
 ```json
 {
   "type": "stdio",
   "command": "npx",
-  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"]
+  "args": ["-y", "codex-control-chrome-mcp@latest", "--stdio"],
+  "startup_timeout_sec": 30
 }
 ```
 
+Check status:
+
+```bash
+npx -y codex-control-chrome-mcp@latest status
+```
+
+Uninstall and restore the previous Codex native host manifest:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+## Agent Skill
+
 If your Agent supports skills, install or reference the bundled skill folder:
 
 ```text
 skills/codex-control-chrome-mcp
 ```
 
-The skill documents the recommended MCP tool order for status checks, tab claiming, CDP commands, screenshots, events, and tab finalization.
+The skill documents the recommended MCP tool order for:
+
+- status checks
+- tab listing and claiming
+- CDP attach and command execution
+- screenshots
+- network and console event reads
+- tab finalization
 
-Read:
+## Security Notes
+
+This project controls the user's normal Chrome profile. MCP clients connected to it can inspect page contents and send raw CDP commands to claimed tabs.
+
+Only install and run it on machines and Chrome profiles you own or are explicitly authorized to automate. Do not send browser cookies, password stores, profile databases, tokens, or private session files in issues or logs.
+
+See [SECURITY.md](./SECURITY.md) for the security model and reporting process.
+
+## How It Works
+
+The Codex Chrome Extension does not need an external Chrome remote debugging port. It uses Chrome Native Messaging and the extension's `chrome.debugger` permission:
+
+```text
+Chrome extension
+  -> chrome.runtime.connectNative("com.openai.codexextension")
+  -> codex-control-chrome-mcp native host
+  -> local MCP bridge socket
+  -> chrome.debugger.attach / chrome.debugger.sendCommand
+  -> CDP
+```
+
+Because the control entrypoint is inside the normal Chrome profile, existing cookies, logged-in sessions, tabs, and extensions can be reused.
+
+Read more:
 
 - [Architecture](./docs/architecture.md)
 - [Install And Uninstall](./docs/install.md)
 - [Official Socket Probe Notes](./docs/socket-probe.md)
+- [Release Process](./docs/release.md)
+
+## Development
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Run checks:
+
+```bash
+npm run ci
+```
+
+Run the MCP server locally:
+
+```bash
+node ./bin/codex-control-chrome-mcp.js --stdio
+```
+
+Run native host mode locally for development:
+
+```bash
+node ./bin/codex-control-chrome-mcp.js --native-host
+```
+
+## Troubleshooting
+
+`status` reports a `registered` flag and a `classification` of the live manifest. When `registered` is `false` and `classification.kind` is `official-openai`, a Codex update has reclaimed the manifest (see below). `classification` identifies OpenAI's genuine host by stable signals — the `com.openai.codexextension` name, the official extension origin, the bundle path, the binary format, and (on macOS) the OpenAI code signature — not by filename.
+
+### A Codex update stopped the bridge
+
+Codex App/extension updates re-register their own `com.openai.codexextension` native-messaging manifest, which overwrites this project's proxy registration (the bundled host binary has even been renamed across releases). The symptom is `status` showing `sockets: []`, `registered: false`, and a manifest `path` back inside the Codex bundle.
+
+The MCP stdio server now **self-heals**: on startup it re-asserts the manifest when it detects it was reverted, so you usually do not need to re-run `install-native-host`. Because Chrome only reads the manifest when the extension reconnects, **reload the Codex Chrome Extension (or restart Chrome) once** after a Codex update to bring the bridge back. Set `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1` to disable the auto re-register.
+
+If `status` shows no bridge sockets, reload Chrome or the Codex Chrome Extension after installing the native host.
+
+If Codex App integration stops working, uninstall this native host to restore the backed-up manifest:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+If tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest published npm version.
+
+## Reporting a Vulnerability
+
+Please report security issues privately by emailing `iola1999@foxmail.com`.
+
+Include:
+
+- affected version
+- operating system
+- Chrome version and profile type
+- MCP client name and version
+- reproduction steps
+- relevant `codex-control-chrome-mcp status` output with sensitive paths or data redacted
+
+Do not include browser cookies, password-store data, session databases, or other private Chrome profile files in reports.
+
+## Security Model
+
+This project controls the user's normal Chrome profile through the Codex Chrome Extension and Chrome DevTools Protocol. That can expose sensitive browser state, including logged-in sessions and page contents.
+
+The trusted boundary is the local user account. Only install and run this tool on machines and Chrome profiles you own or are explicitly authorized to automate.
+
+This project is not affiliated with OpenAI, Codex, Google, or Chrome. It reuses the installed Codex Chrome Extension native messaging host name so the extension can connect to this local bridge.
+
+## Known Security Tradeoffs
+
+- The native host manifest for `com.openai.codexextension` is replaced during install and restored during uninstall.
+- The local bridge socket is intended for same-user local access only.
+- MCP clients connected to this server can send raw CDP commands to claimed tabs.
+- The project does not attempt to enforce per-site or per-command policy.
+
+For operational details, see `docs/architecture.md` and `docs/install.md`.

package/docs/install.md

@@ -17,6 +17,16 @@ The current implementation provides:
 
 Do not run install on a machine where Codex Chrome integration is important unless you are ready to test proxy mode or restore from backup.
 
+This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.
+
+## Platform Support
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Tested | Primary supported platform. |
+| Linux | Experimental | Uses the Google Chrome user-level Native Messaging host directory. |
+| Windows | Unsupported | Chrome Native Messaging registration uses registry keys on Windows and is not implemented yet. |
+
 ## Install
 
 First install and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome profile you want to automate.
@@ -43,6 +53,22 @@ The installer:
 2. Backs it up in the same directory with a timestamped suffix.
 3. Writes a new manifest pointing to this project's CLI.
 4. Records restore metadata in `~/.codex-control-chrome-mcp/install-state.json`.
+5. Records the genuine OpenAI host path for proxy mode when available.
+
+### Identifying the official host
+
+The installer identifies OpenAI's genuine host with stable signals instead of the
+binary filename (OpenAI has renamed it across releases, e.g. `extension-host` →
+`Codex for Chrome`):
+
+- the manifest `name` (`com.openai.codexextension`) and the official extension origin,
+- the bundle directory structure (`.../openai-bundled/.../extension-host/...`),
+- the binary format (a compiled Mach-O/ELF executable, not a shell script),
+- on macOS, the OpenAI code signature (Developer ID Team `2DC432GLL2`).
+
+When choosing the proxy target it prefers the **live** manifest (most up to date) and
+skips paths that no longer exist, so a renamed or removed host is never recorded as the
+official target. `status` reports these signals under `classification`.
 
 Example manifest path on macOS:
 
@@ -50,6 +76,12 @@ Example manifest path on macOS:
 ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.openai.codexextension.json
 ```
 
+Example manifest path on Linux:
+
+```text
+~/.config/google-chrome/NativeMessagingHosts/com.openai.codexextension.json
+```
+
 ## MCP Client Config
 
 Use stdio mode from other Agent tools:
@@ -112,8 +144,40 @@ This prints:
 
 Chrome launches the native host only when the extension connects. If no bridge socket is visible, reload Chrome or the Codex extension after installing the manifest.
 
+### Auto re-register after Codex updates
+
+A Codex App/extension update re-registers its own `com.openai.codexextension` manifest and reverts this project's proxy registration. To avoid a manual repair each time, the MCP stdio server re-asserts the manifest on startup when it detects it was reverted (only if it was installed before — it never bootstraps a fresh install silently). Logs go to stderr only.
+
+Re-asserting the manifest takes effect on the extension's **next** Native Messaging connection, so reload the Codex Chrome Extension or restart Chrome once after a Codex update. Disable this behavior with:
+
+```bash
+CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1
+```
+
 If the extension is missing, install the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) from Chrome Web Store and enable it in the target Chrome profile.
 
 Stopping the MCP stdio process does not uninstall the native host. Uninstall explicitly to restore the original manifest.
 
 The MCP stdio server uses the official `@modelcontextprotocol/sdk` package and must not write logs to stdout. Use stderr for diagnostics.
+
+## Troubleshooting
+
+If `status` shows no sockets:
+
+1. Confirm Chrome is running with the profile where the extension is installed.
+2. Reload or disable/enable the Codex Chrome Extension.
+3. Run `npx -y codex-control-chrome-mcp@latest status`.
+4. Check `registered`. If it is `false` and `classification.kind` is `official-openai`, a Codex update reclaimed the manifest. The stdio server re-asserts it on next startup; reload the extension or restart Chrome to reconnect (or run `install-native-host` to repair immediately).
+5. When `registered` is `true`, the active manifest points to `~/.codex-control-chrome-mcp/native-host-launcher` (or your local launcher) and the extension just needs to connect.
+
+If Codex App integration is affected, uninstall this project:
+
+```bash
+npx -y codex-control-chrome-mcp@latest uninstall-native-host
+```
+
+If the recorded backup is stale or manually changed, inspect the manifest and use `--force` only when you intentionally want to restore/remove the current project manifest.
+
+## Publishing
+
+This package is published from GitHub Actions through npm Trusted Publishing. See [Release Process](./release.md).

package/docs/release.md

@@ -0,0 +1,54 @@
+# Release Process
+
+Releases are published from GitHub Actions through npm Trusted Publishing.
+
+## Trusted Publishing Setup
+
+Configure the npm package settings:
+
+- Package: `codex-control-chrome-mcp`
+- Publisher: GitHub Actions
+- Organization or user: `iola1999`
+- Repository: `codex-control-chrome-mcp`
+- Workflow filename: `publish.yml`
+- Environment name: leave blank unless you add a GitHub deployment environment
+- Allowed action: `npm publish`
+
+Trusted Publishing requires a GitHub-hosted runner, OIDC permission, npm CLI 11.5.1 or newer, and Node.js 22.14.0 or newer. The publish workflow uses Node.js 24 and installs the latest npm before publishing.
+
+## Publish A New Version
+
+1. Update `package.json` version.
+2. Update `CHANGELOG.md`.
+3. Run checks locally:
+
+```bash
+npm run ci
+```
+
+4. Commit and push to `main`.
+5. Create and push a matching tag:
+
+```bash
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+The tag must match the package version exactly. For example, `package.json` version `1.0.1` must use tag `v1.0.1`.
+
+## What The Workflow Does
+
+The `publish.yml` workflow:
+
+1. Installs dependencies with `npm ci`.
+2. Verifies the tag matches `package.json`.
+3. Runs `npm run ci`.
+4. Publishes with `npm publish`.
+
+No long-lived `NPM_TOKEN` is required.
+
+## GitHub Release
+
+After the npm publish workflow succeeds, create a GitHub Release from the same tag and copy the relevant section from `CHANGELOG.md` into the release notes.
+
+Do not create a new GitHub Release for a tag if the npm publish failed.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "codex-control-chrome-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "codex-control-chrome-mcp": "bin/codex-control-chrome-mcp.js"
@@ -32,13 +33,18 @@
     "src",
     "docs",
     "skills",
-    "README.md"
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "start": "node ./bin/codex-control-chrome-mcp.js --stdio",
     "native-host": "node ./bin/codex-control-chrome-mcp.js --native-host",
     "status": "node ./bin/codex-control-chrome-mcp.js status",
-    "check": "node --check ./bin/codex-control-chrome-mcp.js && node --check ./src/*.js"
+    "check": "node --check ./bin/codex-control-chrome-mcp.js && node --check ./src/*.js && node --check ./test/*.test.js",
+    "test": "node --test",
+    "ci": "npm run check && npm test && npm pack --dry-run"
   },
   "engines": {
     "node": ">=20"

package/src/host-identity.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { APP_STATE_DIR, CODEX_EXTENSION_ID, CODEX_NATIVE_HOST_NAME } from "./constants.js";
+
+// Description we stamp on manifests we own. Used as one (not the only) signal.
+export const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
+
+/** A manifest this project wrote (description marker, or path inside our state dir). */
+export function isProjectManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") return false;
+  if (manifest.description === MANIFEST_DESCRIPTION) return true;
+  return isOurLauncherPath(manifest.path);
+}
+
+/** True when a host path points at a launcher we generated under APP_STATE_DIR. */
+export function isOurLauncherPath(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) return false;
+  const resolved = path.resolve(hostPath);
+  const stateRoot = path.resolve(APP_STATE_DIR) + path.sep;
+  return resolved === path.resolve(APP_STATE_DIR) || resolved.startsWith(stateRoot);
+}
+
+/**
+ * Positive identification of OpenAI's genuine Codex native-host *manifest*,
+ * using stable identifiers (host name + the official extension id) rather than
+ * the binary filename (which OpenAI has renamed across releases).
+ */
+export function isOfficialCodexManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") return false;
+  if (isProjectManifest(manifest)) return false;
+  if (manifest.name !== CODEX_NATIVE_HOST_NAME) return false;
+  const origins = Array.isArray(manifest.allowed_origins) ? manifest.allowed_origins : [];
+  return origins.some((origin) => originMatchesCodexExtension(origin));
+}
+
+function originMatchesCodexExtension(origin) {
+  return typeof origin === "string" && origin.includes(`chrome-extension://${CODEX_EXTENSION_ID}`);
+}
+
+/** Stable directory-structure signature of the bundled Codex host (filename-agnostic). */
+export function hostPathLooksOfficial(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) return false;
+  const normalized = path.resolve(hostPath).split(path.sep).join("/").toLowerCase();
+  return normalized.includes("/openai-bundled/") && normalized.includes("/extension-host/");
+}
+
+const MAGIC = {
+  "7f454c46": "elf", // ELF
+  feedface: "macho", // Mach-O 32 LE
+  feedfacf: "macho", // Mach-O 64 LE
+  cefaedfe: "macho", // Mach-O 32 BE
+  cffaedfe: "macho", // Mach-O 64 BE
+  cafebabe: "macho", // universal (fat) — also Java .class, acceptable for a host binary
+  bebafeca: "macho",
+};
+
+/** Inspect the host file: does it exist, is it a compiled binary or a shell script? */
+export async function inspectHostBinary(hostPath) {
+  if (typeof hostPath !== "string" || hostPath.length === 0) {
+    return { exists: false, kind: "missing", executable: false };
+  }
+  let handle;
+  try {
+    const stat = await fs.stat(hostPath);
+    if (!stat.isFile()) return { exists: true, kind: "unknown", executable: false };
+    handle = await fs.open(hostPath, "r");
+    const buf = Buffer.alloc(4);
+    const { bytesRead } = await handle.read(buf, 0, 4, 0);
+    const head = buf.subarray(0, bytesRead);
+    let kind = "unknown";
+    if (head.length >= 2 && head[0] === 0x23 && head[1] === 0x21) kind = "script"; // #!
+    else if (head.length === 4 && MAGIC[head.toString("hex")]) kind = MAGIC[head.toString("hex")];
+    else if (head.length >= 2 && head[0] === 0x4d && head[1] === 0x5a) kind = "pe"; // MZ
+    return { exists: true, kind, executable: (stat.mode & 0o111) !== 0 };
+  } catch {
+    return { exists: false, kind: "missing", executable: false };
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/** Best-effort macOS code-signature check; the strongest OpenAI signal when available. */
+export function verifyOpenAiCodesign(hostPath) {
+  if (process.platform !== "darwin" || typeof hostPath !== "string" || !hostPath) {
+    return Promise.resolve({ available: false });
+  }
+  return new Promise((resolve) => {
+    execFile("codesign", ["-dvvv", hostPath], { timeout: 4000 }, (error, stdout, stderr) => {
+      const out = `${stdout || ""}${stderr || ""}`; // codesign -d writes to stderr
+      if (!out) return resolve({ available: false, error: error?.message });
+      const teamId = (out.match(/TeamIdentifier=(\S+)/) || [])[1] || null;
+      const authority = (out.match(/Authority=([^\r\n]+)/) || [])[1] || null;
+      const openai = /openai/i.test(out);
+      resolve({ available: true, signed: Boolean(authority), openai, teamId, authority });
+    });
+  });
+}
+
+/**
+ * Full classification of a (manifest, hostPath) pair against stable signals.
+ * `trustedOfficial` means: looks like OpenAI's real host and is safe to back up /
+ * proxy to. We require the manifest-level identity plus at least one host-level
+ * signal (bundle path, compiled binary, or an OpenAI code signature).
+ */
+export async function classifyHost({ manifest, hostPath } = {}) {
+  const resolvedPath = hostPath ?? manifest?.path ?? null;
+  const ours = isProjectManifest(manifest) || isOurLauncherPath(resolvedPath);
+  const officialManifest = isOfficialCodexManifest(manifest);
+  const pathOfficial = hostPathLooksOfficial(resolvedPath);
+  const binary = await inspectHostBinary(resolvedPath);
+  const codesign = await verifyOpenAiCodesign(resolvedPath);
+
+  const hostSignal = pathOfficial || codesign.openai === true || binary.kind === "macho" || binary.kind === "elf";
+  const trustedOfficial = !ours && officialManifest && hostSignal;
+
+  return {
+    ours,
+    officialManifest,
+    pathOfficial,
+    binary,
+    codesign,
+    trustedOfficial,
+    kind: ours ? "ours" : trustedOfficial ? "official-openai" : "unknown",
+  };
+}

package/src/installer.js

@@ -8,19 +8,26 @@ import {
   INSTALL_STATE_PATH,
   nativeHostManifestPath,
 } from "./constants.js";
-
-const PACKAGE_NAME = "codex-control-chrome-mcp";
-const PACKAGE_VERSION = "1.0.0";
-const MANIFEST_DESCRIPTION = "Codex Control Chrome MCP native messaging host";
-
-export async function installNativeHost({ binPath, proxy = true } = {}) {
-  const manifestPath = nativeHostManifestPath();
+import {
+  MANIFEST_DESCRIPTION,
+  classifyHost,
+  inspectHostBinary,
+  isOfficialCodexManifest,
+  isOurLauncherPath,
+  isProjectManifest,
+} from "./host-identity.js";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
+
+export async function installNativeHost({ binPath, proxy = true, paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, appStateDir, configPath, installStatePath } = paths;
   await fs.mkdir(path.dirname(manifestPath), { recursive: true });
-  await fs.mkdir(APP_STATE_DIR, { recursive: true });
+  await fs.mkdir(appStateDir, { recursive: true });
 
-  const hostPath = binPath ? await createLocalLauncher(path.resolve(binPath)) : await createNpxLauncher();
+  const hostPath = binPath
+    ? await createLocalLauncher(path.resolve(binPath), appStateDir)
+    : await createNpxLauncher(appStateDir);
   const existing = await readJsonIfExists(manifestPath);
-  const previousState = await readJsonIfExists(INSTALL_STATE_PATH);
+  const previousState = await readJsonIfExists(installStatePath);
   const previousBackup = previousState?.backupPath
     ? await readJsonIfExists(previousState.backupPath)
     : null;
@@ -33,23 +40,9 @@ export async function installNativeHost({ binPath, proxy = true } = {}) {
     backupPath = previousState.backupPath;
   }
 
-  let officialHostPath = null;
-  if (proxy && previousBackup?.path && !previousBackupIsOurs) {
-    officialHostPath = previousBackup.path;
-  } else if (
-    proxy &&
-    typeof previousState?.officialHostPath === "string" &&
-    path.resolve(previousState.officialHostPath) !== path.resolve(hostPath)
-  ) {
-    officialHostPath = previousState.officialHostPath;
-  } else if (
-    proxy &&
-    existing?.path &&
-    !existingIsOurs &&
-    path.resolve(existing.path) !== path.resolve(hostPath)
-  ) {
-    officialHostPath = existing.path;
-  }
+  const officialHostPath = proxy
+    ? await resolveOfficialHostPath({ existing, existingIsOurs, previousState, previousBackup, hostPath })
+    : null;
 
   const manifest = {
     allowed_origins: [`chrome-extension://${CODEX_EXTENSION_ID}/`],
@@ -64,19 +57,96 @@ export async function installNativeHost({ binPath, proxy = true } = {}) {
     installedAt: new Date().toISOString(),
     manifestPath,
     hostPath,
+    binPath: binPath ? path.resolve(binPath) : null,
     launchMode: binPath ? "direct-bin" : "npx-launcher",
     backupPath,
     officialHostPath,
     proxy,
   };
-  await fs.writeFile(APP_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-  await fs.writeFile(INSTALL_STATE_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.writeFile(installStatePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
   return config;
 }
 
-export async function uninstallNativeHost({ force = false } = {}) {
-  const manifestPath = nativeHostManifestPath();
-  const state = await readJsonIfExists(INSTALL_STATE_PATH);
+/**
+ * Resolve the genuine OpenAI host to proxy to. Authority order:
+ *   1. the live manifest, when it is verifiably OpenAI's (most up to date),
+ *   2. the previously recorded official host,
+ *   3. the backed-up manifest's path.
+ * Self-references and our own launcher are dropped, and a candidate whose file
+ * still exists is preferred so a renamed/removed host (e.g. after a Codex
+ * update) never gets recorded as the official target.
+ */
+async function resolveOfficialHostPath({ existing, existingIsOurs, previousState, previousBackup, hostPath }) {
+  const candidates = [];
+  if (existing?.path && !existingIsOurs && isOfficialCodexManifest(existing)) {
+    candidates.push(existing.path);
+  }
+  if (typeof previousState?.officialHostPath === "string") {
+    candidates.push(previousState.officialHostPath);
+  }
+  if (previousBackup?.path && !isProjectManifest(previousBackup)) {
+    candidates.push(previousBackup.path);
+  }
+
+  const seen = new Set();
+  const unique = [];
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (resolved === path.resolve(hostPath) || isOurLauncherPath(candidate) || seen.has(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    unique.push(candidate);
+  }
+
+  for (const candidate of unique) {
+    if ((await inspectHostBinary(candidate)).exists) return candidate;
+  }
+  // None of the candidates exist on disk; fall back to the most authoritative
+  // one (the live official manifest) for diagnostics rather than inventing null.
+  return unique[0] ?? null;
+}
+
+/**
+ * Idempotently re-assert a previously-established install. Used on stdio
+ * startup so a Codex update that reclaims the manifest self-heals without a
+ * manual `install-native-host`. Never bootstraps a fresh install silently.
+ */
+export async function ensureNativeHostRegistered({ paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, installStatePath } = paths;
+  const state = await readJsonIfExists(installStatePath);
+  if (!state || typeof state.hostPath !== "string") {
+    return { action: "skip", reason: "not-installed" };
+  }
+
+  const manifest = await readJsonIfExists(manifestPath);
+  const pointsToUs =
+    isProjectManifest(manifest) &&
+    typeof manifest?.path === "string" &&
+    path.resolve(manifest.path) === path.resolve(state.hostPath);
+  const launcherExists = (await inspectHostBinary(state.hostPath)).exists;
+  if (pointsToUs && launcherExists) {
+    return { action: "ok", reason: "already-registered" };
+  }
+
+  const result = await installNativeHost({
+    binPath: state.launchMode === "direct-bin" ? state.binPath ?? undefined : undefined,
+    proxy: state.proxy !== false,
+    paths,
+  });
+  return {
+    action: "re-registered",
+    reason: launcherExists ? "manifest-reverted" : "launcher-missing",
+    manifestPath,
+    hostPath: result.hostPath,
+    officialHostPath: result.officialHostPath,
+  };
+}
+
+export async function uninstallNativeHost({ force = false, paths = defaultInstallPaths() } = {}) {
+  const { manifestPath, installStatePath } = paths;
+  const state = await readJsonIfExists(installStatePath);
   const manifest = await readJsonIfExists(manifestPath);
 
   if (!manifest && !state?.backupPath) {
@@ -99,10 +169,25 @@ export async function uninstallNativeHost({ force = false } = {}) {
 }
 
 export async function nativeHostInstallStatus() {
-  const manifestPath = nativeHostManifestPath();
+  const { manifestPath, installStatePath } = defaultInstallPaths();
   const manifest = await readJsonIfExists(manifestPath);
-  const state = await readJsonIfExists(INSTALL_STATE_PATH);
-  return { manifestPath, manifest, state };
+  const state = await readJsonIfExists(installStatePath);
+  const classification = await classifyHost({ manifest, hostPath: manifest?.path });
+  const registered =
+    isProjectManifest(manifest) &&
+    typeof state?.hostPath === "string" &&
+    typeof manifest?.path === "string" &&
+    path.resolve(manifest.path) === path.resolve(state.hostPath);
+  return { manifestPath, manifest, state, registered, classification };
+}
+
+function defaultInstallPaths() {
+  return {
+    manifestPath: nativeHostManifestPath(),
+    appStateDir: APP_STATE_DIR,
+    configPath: APP_CONFIG_PATH,
+    installStatePath: INSTALL_STATE_PATH,
+  };
 }
 
 async function backupManifest(manifestPath) {
@@ -115,11 +200,11 @@ async function backupManifest(manifestPath) {
   return backupPath;
 }
 
-async function createNpxLauncher() {
+async function createNpxLauncher(appStateDir) {
   if (process.platform === "win32") {
     throw new Error("NPX native host launcher installation is not implemented for Windows yet.");
   }
-  const launcherPath = path.join(APP_STATE_DIR, "native-host-launcher");
+  const launcherPath = path.join(appStateDir, "native-host-launcher");
   const script = `#!/usr/bin/env sh
 exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host "$@"
 `;
@@ -128,18 +213,14 @@ exec npx -y ${PACKAGE_NAME}@${PACKAGE_VERSION} --native-host "$@"
   return launcherPath;
 }
 
-function isProjectManifest(manifest) {
-  return manifest?.description === MANIFEST_DESCRIPTION;
-}
-
-async function createLocalLauncher(binPath) {
+async function createLocalLauncher(binPath, appStateDir) {
   if (process.platform === "win32") {
     return binPath;
   }
   if (!binPath.endsWith(".js")) {
     return binPath;
   }
-  const launcherPath = path.join(APP_STATE_DIR, "native-host-local-launcher");
+  const launcherPath = path.join(appStateDir, "native-host-local-launcher");
   const script = `#!/usr/bin/env sh
 exec ${shellQuote(process.execPath)} ${shellQuote(binPath)} "$@"
 `;

package/src/mcp-server.js

@@ -4,12 +4,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { connectBridge, listBridgeSockets } from "./bridge-client.js";
 import { nativeHostManifestPath } from "./constants.js";
+import { ensureNativeHostRegistered } from "./installer.js";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 
 export async function runMcpServer() {
+  await autoRegisterNativeHost();
   const runtime = new ChromeUseRuntime();
   const server = new McpServer({
-    name: "codex-control-chrome-mcp",
-    version: "1.0.0",
+    name: PACKAGE_NAME,
+    version: PACKAGE_VERSION,
   });
 
   registerTools(server, runtime);
@@ -18,6 +21,32 @@ export async function runMcpServer() {
   await server.connect(transport);
 }
 
+/**
+ * On stdio startup, re-assert our native-host manifest if a Codex update (or
+ * anything else) reverted it. Best-effort and silent: it only logs to stderr
+ * (stdout is the MCP JSON-RPC channel) and never blocks server startup.
+ * Opt out with CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1.
+ *
+ * Note: re-asserting the manifest only takes effect on the Chrome extension's
+ * next Native Messaging connection (reload the extension or restart Chrome).
+ */
+async function autoRegisterNativeHost() {
+  if (process.env.CODEX_CONTROL_CHROME_NO_AUTO_REGISTER === "1") return;
+  try {
+    const result = await ensureNativeHostRegistered();
+    if (result.action === "re-registered") {
+      process.stderr.write(
+        `[codex-control-chrome-mcp] native host manifest was ${result.reason}; re-registered it. ` +
+          "Reload the Codex Chrome extension (or restart Chrome) to reconnect the bridge.\n",
+      );
+    }
+  } catch (error) {
+    process.stderr.write(
+      `[codex-control-chrome-mcp] auto-register skipped: ${error?.message ?? error}\n`,
+    );
+  }
+}
+
 class ChromeUseRuntime {
   constructor() {
     this.sessionId = `codex-control-chrome-mcp-${crypto.randomUUID()}`;

package/src/package-meta.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+export const PACKAGE_NAME = packageJson.name;
+export const PACKAGE_VERSION = packageJson.version;