webmcp_everywhere 0.1.0

package/install_the_native_messaging_host.mjs

@@ -0,0 +1,327 @@
+// tools/release_installer_entry.ts
+import Path3 from "node:path";
+
+// tools/install_native_host.ts
+import Fs2 from "node:fs";
+import Os from "node:os";
+import Path2 from "node:path";
+
+// tools/generate_extension_key.ts
+import Crypto from "node:crypto";
+import Fs from "node:fs";
+import Path from "node:path";
+var __filename = import.meta.filename;
+var __dirname = import.meta.dirname;
+var GenerateExtensionKey = class _GenerateExtensionKey {
+  /**
+   * Derives Chrome's extension identifier from a public key.
+   *
+   * Chrome takes the SHA-256 of the DER-encoded public key, keeps the first sixteen bytes, and maps
+   * each of the thirty-two nibbles onto the letters `a` to `p`.
+   *
+   * @param publicKeyDer - The DER-encoded SubjectPublicKeyInfo.
+   * @returns The thirty-two character extension identifier.
+   */
+  static identifierFromPublicKey(publicKeyDer) {
+    const digest = Crypto.createHash("sha256").update(publicKeyDer).digest();
+    let identifier = "";
+    for (const byte of digest.subarray(0, 16)) {
+      identifier += String.fromCharCode(97 + (byte >> 4));
+      identifier += String.fromCharCode(97 + (byte & 15));
+    }
+    return identifier;
+  }
+  /**
+   * Generates a key pair, writes the public half into the manifest, and reports the identifier.
+   *
+   * @returns What was generated and where the private half went.
+   */
+  static run() {
+    const manifestPath = Path.join(__dirname, "..", "src", "chrome_extension", "manifest.json");
+    const manifest = JSON.parse(Fs.readFileSync(manifestPath, "utf8"));
+    if (manifest.key !== void 0) {
+      const identifier = _GenerateExtensionKey.identifierFromPublicKey(
+        Buffer.from(manifest.key, "base64")
+      );
+      return {
+        identifier,
+        privateKeyPath: "unchanged, the manifest already carries a key"
+      };
+    }
+    const { publicKey, privateKey } = Crypto.generateKeyPairSync("rsa", {
+      modulusLength: 2048
+    });
+    const publicKeyDer = publicKey.export({
+      type: "spki",
+      format: "der"
+    });
+    manifest.key = publicKeyDer.toString("base64");
+    Fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, "	") + "\n");
+    const privateKeyPath = Path.join(__dirname, "..", "extension_private_key.pem");
+    Fs.writeFileSync(
+      privateKeyPath,
+      privateKey.export({
+        type: "pkcs8",
+        format: "pem"
+      })
+    );
+    return {
+      identifier: _GenerateExtensionKey.identifierFromPublicKey(publicKeyDer),
+      privateKeyPath
+    };
+  }
+  /**
+   * Reads the extension identifier the manifest currently pins.
+   *
+   * @returns The extension identifier.
+   * @throws When the manifest carries no key.
+   */
+  static currentIdentifier(manifestPath) {
+    const readFrom = manifestPath ?? Path.join(__dirname, "..", "src", "chrome_extension", "manifest.json");
+    const manifest = JSON.parse(Fs.readFileSync(readFrom, "utf8"));
+    if (manifest.key === void 0) {
+      throw new Error('the manifest has no key; run "node tools/generate_extension_key_entry.ts" first');
+    }
+    return _GenerateExtensionKey.identifierFromPublicKey(Buffer.from(manifest.key, "base64"));
+  }
+};
+
+// tools/install_native_host.ts
+var __filename2 = import.meta.filename;
+var __dirname2 = import.meta.dirname;
+var InstallNativeHost = class _InstallNativeHost {
+  static {
+    /** The host name the extension asks for, which must match the manifest file name. */
+    this.HOST_NAME = "com.webmcp_everywhere.host";
+  }
+  /**
+   * Works out what an installation would write, without writing any of it.
+   *
+   * This exists so that the installation can say what it is about to do to the user's machine before it
+   * does it. Writing a file into a browser the user installed is not something to announce afterwards.
+   *
+   * @param options - Where the installation would write.
+   * @returns The files the installation would write.
+   */
+  static plan(options = {}) {
+    const identifier = GenerateExtensionKey.currentIdentifier(options.extensionManifestPath);
+    const launcher = _InstallNativeHost._resolveLauncher(options.launcherPath);
+    return {
+      identifier,
+      launcher,
+      manifests: _InstallNativeHost.manifestPaths(options)
+    };
+  }
+  /**
+   * Names every manifest file the installation writes, without reading anything else.
+   *
+   * The installation, the uninstallation and the command that copies a release somewhere stable all
+   * need this same list, and a file name spelled in three places is spelled wrong in one of them
+   * eventually. It reads no launcher and no extension manifest, so it also answers before an
+   * installation exists, which is what lets a command name the files it is about to write.
+   *
+   * @param options - Which directories to cover.
+   * @returns The manifest files, in the order they are written.
+   */
+  static manifestPaths(options = {}) {
+    return _InstallNativeHost.manifestDirectories(options).map((directory) => {
+      return Path2.join(directory, `${_InstallNativeHost.HOST_NAME}.json`);
+    });
+  }
+  /**
+   * Writes the launcher and the manifest.
+   *
+   * @param options - Where to install.
+   * @returns What was written.
+   */
+  static run(options = {}) {
+    const planned = _InstallNativeHost.plan(options);
+    const manifest = _InstallNativeHost._renderManifest(
+      planned.launcher,
+      planned.identifier,
+      options.templateDir
+    );
+    for (const manifestPath of planned.manifests) {
+      Fs2.mkdirSync(Path2.dirname(manifestPath), {
+        recursive: true
+      });
+      Fs2.writeFileSync(manifestPath, manifest);
+    }
+    return planned;
+  }
+  /**
+   * Lists every directory Chrome might read host manifests from.
+   *
+   * The everyday Chrome reads them from its own support directory. A Chrome started with a custom
+   * `--user-data-dir`, which is what `LaunchChrome` and the verification runners use, reads them from
+   * inside that directory instead and never looks at the everyday one, which is why a throwaway profile
+   * can be covered without touching the browser the user installed.
+   *
+   * This is public because the uninstallation has to remove a manifest from exactly the directories the
+   * installation writes one into, and two lists that have to agree are one list.
+   *
+   * @param options - Which directories to cover.
+   * @returns The directories that hold a manifest, the everyday Chrome first when it is covered.
+   */
+  static manifestDirectories(options = {}) {
+    const directories = [];
+    if (options.isEverydayChromeCovered !== false) {
+      directories.push(_InstallNativeHost.everydayChromeDirectory());
+    }
+    for (const userDataDir of options.userDataDirs ?? []) {
+      directories.push(Path2.join(userDataDir, "NativeMessagingHosts"));
+    }
+    return directories;
+  }
+  /**
+   * Names the directory the everyday Chrome, the one the user installed, reads host manifests from.
+   *
+   * @param homeDir - The home folder to read it out of, for a runner installing into a throwaway one.
+   * @returns The absolute path of that directory on this platform.
+   */
+  static everydayChromeDirectory(homeDir = Os.homedir()) {
+    if (process.platform === "darwin") {
+      return Path2.join(homeDir, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+    }
+    return Path2.join(homeDir, ".config", "google-chrome", "NativeMessagingHosts");
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Fills the host manifest template in with this installation's values.
+   *
+   * The manifest lives in `data/native_messaging_template/com.webmcp_everywhere.host.json` rather than in
+   * this file, so that the shape Chrome reads can be looked at and edited as the JSON document it is. It
+   * is read every time instead of being cached, because an installation runs once and then exits. Every
+   * placeholder has to be replaced, so an unreplaced one is an error rather than something written out
+   * to Chrome, which would refuse the manifest with no useful message.
+   *
+   * @param launcher - The absolute path to the executable file Chrome starts.
+   * @param identifier - The extension identifier the manifest allows to connect.
+   * @param templateDir - The folder holding the template, or nothing for this working copy's.
+   * @returns The manifest text to write, ending in a newline.
+   */
+  static _renderManifest(launcher, identifier, templateDir) {
+    const folder = templateDir ?? Path2.join(__dirname2, "..", "data", "native_messaging_template");
+    const templatePath = Path2.join(folder, `${_InstallNativeHost.HOST_NAME}.json`);
+    if (Fs2.existsSync(templatePath) === false) {
+      throw new Error(`host manifest template is missing: ${templatePath}`);
+    }
+    const template = Fs2.readFileSync(templatePath, "utf8");
+    const values = {
+      hostName: _InstallNativeHost.HOST_NAME,
+      launcherPath: launcher,
+      extensionIdentifier: identifier
+    };
+    let rendered = template;
+    for (const [placeholder, value] of Object.entries(values)) {
+      rendered = rendered.split(`{{${placeholder}}}`).join(value);
+    }
+    const leftover = rendered.match(/\{\{[^}]*\}\}/);
+    if (leftover !== null) {
+      throw new Error(`host manifest template has an unknown placeholder: ${leftover[0]}`);
+    }
+    JSON.parse(rendered);
+    return rendered.endsWith("\n") === true ? rendered : rendered + "\n";
+  }
+  /**
+   * Locates the executable Chrome actually launches.
+   *
+   * Chrome runs the path in the manifest directly, so it has to be an executable file rather than a
+   * script it would have to know how to interpret. `bin/webmcp_native_host.sh` is that file, it is
+   * kept in the repository, and it works out the rest of the paths on its own, so this only has to
+   * check that it is there and that it is executable.
+   *
+   * @param named - A launcher to use instead of this working copy's, such as a packaged release's.
+   * @returns The absolute path to the launcher.
+   * @throws When the launcher is not there.
+   */
+  static _resolveLauncher(named) {
+    const repoRoot = Path2.join(__dirname2, "..");
+    const launcher = named === void 0 ? Path2.join(repoRoot, "bin", "webmcp_native_host.sh") : Path2.resolve(named);
+    if (Fs2.existsSync(launcher) === false) {
+      throw new Error(`launcher is missing: ${launcher}`);
+    }
+    Fs2.chmodSync(launcher, 493);
+    return launcher;
+  }
+};
+
+// tools/release_layout.ts
+var ReleaseLayout = class {
+  static {
+    /** The bundled native messaging host, one file with its dependencies inlined. */
+    this.HOST_BUNDLE = "webmcp_native_host.mjs";
+  }
+  static {
+    /** The launcher Chrome starts, which finds a Node.js and runs the bundle beside it. */
+    this.LAUNCHER = "webmcp_native_host.sh";
+  }
+  static {
+    /** The installer that registers that launcher with Chrome. */
+    this.INSTALLER = "install_the_native_messaging_host.mjs";
+  }
+  static {
+    /** The command an `npx webmcp_everywhere` run starts, which the `bin` field of the manifest names. */
+    this.COMMAND = "webmcp_everywhere.mjs";
+  }
+  static {
+    /** The manifest npm publishes the folder with. */
+    this.PACKAGE_MANIFEST = "package.json";
+  }
+  static {
+    /** The folder a person loads at `chrome://extensions`. */
+    this.EXTENSION_DIR = "chrome_extension";
+  }
+  static {
+    /** The folder holding the host manifest template the installer fills in. */
+    this.TEMPLATE_DIR = "native_messaging_template";
+  }
+  static {
+    /** The extension manifest inside the extension folder, which pins the extension identifier. */
+    this.EXTENSION_MANIFEST = "manifest.json";
+  }
+};
+
+// tools/release_installer_entry.ts
+var __filename3 = import.meta.filename;
+var __dirname3 = import.meta.dirname;
+var ReleaseInstallerEntry = class {
+  /**
+   * Announces every file, then writes them.
+   *
+   * @returns Nothing.
+   */
+  static run() {
+    const options = {
+      launcherPath: Path3.join(__dirname3, ReleaseLayout.LAUNCHER),
+      templateDir: Path3.join(__dirname3, ReleaseLayout.TEMPLATE_DIR),
+      extensionManifestPath: Path3.join(__dirname3, ReleaseLayout.EXTENSION_DIR, ReleaseLayout.EXTENSION_MANIFEST)
+    };
+    const planned = InstallNativeHost.plan(options);
+    console.log("This registers WebMCP Everywhere with Google Chrome. It is about to write:");
+    for (const manifestPath of planned.manifests) {
+      console.log(`  ${manifestPath}`);
+    }
+    console.log("");
+    console.log(`Each of those tells Chrome to start: ${planned.launcher}`);
+    console.log(`and to let only the extension ${planned.identifier} talk to it.`);
+    console.log("");
+    console.log("Chrome will start that program outside the browser sandbox, with your rights.");
+    console.log("To undo this, delete the files listed above.");
+    console.log("");
+    const written = InstallNativeHost.run(options);
+    for (const manifestPath of written.manifests) {
+      console.log(`wrote ${manifestPath}`);
+    }
+    console.log("");
+    console.log(`Now load the ${ReleaseLayout.EXTENSION_DIR} folder at chrome://extensions, with Developer mode on.`);
+  }
+};
+ReleaseInstallerEntry.run();
+export {
+  ReleaseInstallerEntry
+};

package/native_messaging_template/CONTEXT.md

@@ -0,0 +1,16 @@
+# Directory Context: `/data/native_messaging_template`
+
+## Purpose
+Holds the template for the Chrome native messaging host manifest, the JSON file that tells Chrome which program to start and which extension may connect to it.
+
+## Key Exports & Entry Points
+- `com.webmcp_everywhere.host.json`: the template. `tools/install_native_host.ts` reads it, replaces the placeholders, and writes the result into every Chrome native messaging host directory.
+- Command to write the manifests: `npm run install:host`
+
+## Rules
+- The placeholders are `{{hostName}}`, `{{launcherPath}}`, and `{{extensionIdentifier}}`. Adding a placeholder here without adding its value in `InstallNativeHost._renderManifest` fails the installation, on purpose.
+- Never write the host name, the launcher path, or the extension identifier here as a literal value. Each of those has one authoritative place in the TypeScript, and a second copy here would disagree with it.
+- The field names are Chrome's, not this project's: `name`, `description`, `path`, `type`, and `allowed_origins`. Chrome refuses a manifest with any other spelling and reports nothing useful when it does.
+
+## Background
+- Chrome's native messaging documentation defines the manifest and the directories it is read from — see [issue #2](https://github.com/jeromeetienne/webmcp_everywhere/issues/2).

package/native_messaging_template/com.webmcp_everywhere.host.json

@@ -0,0 +1,9 @@
+{
+	"name": "{{hostName}}",
+	"description": "WebMCP Everywhere — serves the extension tools over Model Context Protocol",
+	"path": "{{launcherPath}}",
+	"type": "stdio",
+	"allowed_origins": [
+		"chrome-extension://{{extensionIdentifier}}/"
+	]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "webmcp_everywhere",
+	"version": "0.1.0",
+	"license": "MIT",
+	"description": "A community-maintained library of WebMCP adapters that register tools into sites that have not shipped their own.",
+	"keywords": [
+		"webmcp",
+		"model context protocol",
+		"chrome extension",
+		"browser agent",
+		"site adapter"
+	],
+	"homepage": "https://github.com/jeromeetienne/webmcp_everywhere#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeromeetienne/webmcp_everywhere.git"
+	},
+	"bugs": {
+		"url": "https://github.com/jeromeetienne/webmcp_everywhere/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"bin": {
+		"webmcp_everywhere": "./webmcp_everywhere.mjs"
+	}
+}