machine-bridge-mcp 2.0.0 → 3.0.0-beta.11

package/src/local/agent-context.mjs

@@ -29,9 +29,10 @@ const MAX_INSTRUCTION_FILE_BYTES = 512 * 1024;
 const MAX_INSTRUCTION_FILES = 64;
 
 export class AgentContextManager {
-  constructor({ workspace, policy, displayPath, resolveExistingPath, throwIfCancelled = () => {}, home = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "" }) {
+  constructor({ workspace, policy, policyForContext = null, displayPath, resolveExistingPath, throwIfCancelled = () => {}, home = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "" }) {
     this.workspace = resolve(workspace);
     this.policy = policy || {};
+    this.policyForContext = typeof policyForContext === "function" ? policyForContext : () => this.policy;
     this.displayPath = displayPath;
     this.resolveExistingPath = resolveExistingPath;
     this.throwIfCancelled = throwIfCancelled;
@@ -44,23 +45,23 @@ export class AgentContextManager {
     const includeContent = args.include_instruction_content !== false;
     const skillLimit = clampInteger(args.max_skills, 100, 1, MAX_SKILL_RESULTS);
     const discoveredSkills = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
-    const contextSkills = contextSkillSummaries(discoveredSkills.skills, this.displayPath, skillLimit, MAX_CONTEXT_SKILL_SUMMARY_CHARS);
+    const contextSkills = contextSkillSummaries(discoveredSkills.skills, (value) => this.displayPath(value, context), skillLimit, MAX_CONTEXT_SKILL_SUMMARY_CHARS);
     const result = {
-      target: this.displayPath(state.target),
-      scope_root: this.displayPath(state.scopeRoot),
+      target: this.displayPath(state.target, context),
+      scope_root: this.displayPath(state.scopeRoot, context),
       precedence: "built-in defaults, automatic project facts, user-global guidance, then scope root to target directory; explicit files loaded later have higher precedence",
-      config_files: state.configFiles.map((file) => this.displayPath(file)),
+      config_files: state.configFiles.map((file) => this.displayPath(file, context)),
       builtin_instructions: publicVirtualInstruction(state.builtinInstructions, includeContent),
       automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, includeContent),
       model_instructions_file: state.modelInstructions ? {
-        path: this.displayPath(state.modelInstructions.path),
+        path: this.displayPath(state.modelInstructions.path, context),
         bytes: state.modelInstructions.bytes,
         sha256: state.modelInstructions.sha256,
         ...(includeContent ? { content: state.modelInstructions.content } : {}),
       } : null,
       instruction_files: state.instructions.map((item) => ({
         scope: item.scope,
-        path: this.displayPath(item.path),
+        path: this.displayPath(item.path, context),
         bytes: item.bytes,
         sha256: item.sha256,
         precedence: item.precedence,
@@ -68,9 +69,9 @@ export class AgentContextManager {
       })),
       skills: contextSkills.skills,
       skills_truncated: discoveredSkills.truncated || contextSkills.truncated,
-      skill_warnings: publicSkillWarnings(discoveredSkills.warnings, this.displayPath),
+      skill_warnings: publicSkillWarnings(discoveredSkills.warnings, (value) => this.displayPath(value, context)),
       instructions_truncated: state.instructionsTruncated,
-      commands: publicCommands(state.commands, this.displayPath),
+      commands: publicCommands(state.commands, (value) => this.displayPath(value, context)),
       guidance: [
         "Apply built-in instructions and automatic project context as lower-precedence defaults; explicit global/project instruction files loaded later take precedence.",
         "Treat instruction_files as authoritative workspace guidance in the returned precedence order.",
@@ -78,7 +79,7 @@ export class AgentContextManager {
         "Prefer run_local_command for registered repeatable commands. Use run_process or exec_command only when no registered command fits and policy permits it.",
       ],
     };
-    if (includeContent) result.effective_instructions = renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath);
+    if (includeContent) result.effective_instructions = renderEffectiveInstructions(effectiveInstructionItems(state), (value) => this.displayPath(value, context));
     return result;
   }
 
@@ -86,11 +87,11 @@ export class AgentContextManager {
     const state = await this.discoverState(args.path || ".", context);
     const fingerprint = capabilityFingerprint(state, []);
     return {
-      target: this.displayPath(state.target),
-      instructions: renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath),
+      target: this.displayPath(state.target, context),
+      instructions: renderEffectiveInstructions(effectiveInstructionItems(state), (value) => this.displayPath(value, context)),
       builtin_instructions: publicVirtualInstruction(state.builtinInstructions, false),
       automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, false),
-      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
+      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path, context) : null,
       capability_refresh: {
         strategy: "resolve_task_capabilities-rescans-on-every-call",
         instruction_and_command_fingerprint: fingerprint,
@@ -125,7 +126,7 @@ export class AgentContextManager {
     let selectedSkill = null;
     if (selected && args.include_selected_skill !== false) {
       const content = await readRegularUtf8(selected.entrypoint, MAX_SKILL_ENTRY_BYTES, "skill entrypoint");
-      selectedSkill = { ...publicSkill(selected, this.displayPath), instructions: content.text };
+      selectedSkill = { ...publicSkill(selected, (value) => this.displayPath(value, context)), instructions: content.text };
     }
     const recommendedTools = recommendTools(task, {
       commandsAvailable: state.commands.size > 0,
@@ -135,20 +136,20 @@ export class AgentContextManager {
     const refresh = capabilityFingerprint(state, discovered.skills);
     return {
       task,
-      target: this.displayPath(state.target),
-      effective_instructions: renderEffectiveInstructions(effectiveInstructionItems(state), this.displayPath),
+      target: this.displayPath(state.target, context),
+      effective_instructions: renderEffectiveInstructions(effectiveInstructionItems(state), (value) => this.displayPath(value, context)),
       builtin_instructions: publicVirtualInstruction(state.builtinInstructions, false),
       automatic_project_context: publicVirtualInstruction(state.automaticProjectContext, false),
-      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path) : null,
-      instruction_files: state.instructions.map((item) => ({ path: this.displayPath(item.path), scope: item.scope, bytes: item.bytes, sha256: item.sha256, precedence: item.precedence })),
+      model_instructions_file: state.modelInstructions ? this.displayPath(state.modelInstructions.path, context) : null,
+      instruction_files: state.instructions.map((item) => ({ path: this.displayPath(item.path, context), scope: item.scope, bytes: item.bytes, sha256: item.sha256, precedence: item.precedence })),
       instructions_truncated: state.instructionsTruncated,
       refresh: { strategy: "rescan-on-every-call", fingerprint: refresh, generated_at: new Date().toISOString() },
       selected_skill: selectedSkill,
-      skill_matches: skillMatches.map(({ skill, score }) => ({ ...publicSkill(skill, this.displayPath), score })),
-      command_matches: commandMatches.map(({ command, score }) => ({ ...publicCommands(new Map([[command.name, command]]), this.displayPath)[0], score })),
+      skill_matches: skillMatches.map(({ skill, score }) => ({ ...publicSkill(skill, (value) => this.displayPath(value, context)), score })),
+      command_matches: commandMatches.map(({ command, score }) => ({ ...publicCommands(new Map([[command.name, command]]), (value) => this.displayPath(value, context))[0], score })),
       recommended_tools: recommendedTools,
       host_semantics: "Machine Bridge can discover, rank, and load capabilities automatically. The MCP host remains responsible for deciding whether to call the recommended tools.",
-      warnings: publicSkillWarnings(discovered.warnings, this.displayPath),
+      warnings: publicSkillWarnings(discovered.warnings, (value) => this.displayPath(value, context)),
       truncated: discovered.truncated,
     };
   }
@@ -171,11 +172,11 @@ export class AgentContextManager {
       maxResults: clampInteger(args.max_results, 100, 1, MAX_SKILL_RESULTS),
     }, context);
     return {
-      target: this.displayPath(state.target),
-      scope_root: this.displayPath(state.scopeRoot),
-      skill_roots: state.skillRoots.map((root) => this.displayPath(root)),
-      skills: result.skills.map((skill) => publicSkill(skill, this.displayPath)),
-      warnings: publicSkillWarnings(result.warnings, this.displayPath),
+      target: this.displayPath(state.target, context),
+      scope_root: this.displayPath(state.scopeRoot, context),
+      skill_roots: state.skillRoots.map((root) => this.displayPath(root, context)),
+      skills: result.skills.map((skill) => publicSkill(skill, (value) => this.displayPath(value, context))),
+      warnings: publicSkillWarnings(result.warnings, (value) => this.displayPath(value, context)),
       truncated: result.truncated,
     };
   }
@@ -184,14 +185,14 @@ export class AgentContextManager {
     const requested = requiredString(args.skill, "skill");
     const state = await this.discoverState(args.path || ".", context);
     const result = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
-    const matches = result.skills.filter((skill) => skill.id === requested || skill.name === requested || this.displayPath(skill.entrypoint) === requested);
+    const matches = result.skills.filter((skill) => skill.id === requested || skill.name === requested || this.displayPath(skill.entrypoint, context) === requested);
     if (!matches.length) throw new Error(`local skill not found: ${requested}`);
     if (matches.length > 1) throw new Error(`local skill name is ambiguous; use its id: ${requested}`);
     const skill = matches[0];
     const content = await readRegularUtf8(skill.entrypoint, MAX_SKILL_ENTRY_BYTES, "skill entrypoint");
     const inventory = await listSkillFiles(skill.directory, clampInteger(args.max_files, 200, 1, MAX_SKILL_FILES), context, this.throwIfCancelled);
     return {
-      skill: publicSkill(skill, this.displayPath),
+      skill: publicSkill(skill, (value) => this.displayPath(value, context)),
       instructions: content.text,
       files: inventory.files,
       files_truncated: inventory.truncated,
@@ -202,9 +203,9 @@ export class AgentContextManager {
   async listLocalCommands(args = {}, context = {}) {
     const state = await this.discoverState(args.path || ".", context);
     return {
-      target: this.displayPath(state.target),
-      scope_root: this.displayPath(state.scopeRoot),
-      commands: publicCommands(state.commands, this.displayPath),
+      target: this.displayPath(state.target, context),
+      scope_root: this.displayPath(state.scopeRoot, context),
+      commands: publicCommands(state.commands, (value) => this.displayPath(value, context)),
     };
   }
 
@@ -227,14 +228,15 @@ export class AgentContextManager {
 
   async discoverState(inputPath, context = {}) {
     this.throwIfCancelled(context);
+    const effectivePolicy = this.policyForContext(context);
     this.workspace = await realpath(this.workspace);
-    const target = await realpath(await this.resolveExistingPath(inputPath));
+    const target = await realpath(await this.resolveExistingPath(inputPath, context));
     const targetInfo = await stat(target);
     const targetDir = targetInfo.isDirectory() ? target : dirname(target);
     const scopeRoot = await findScopeRoot({
       targetDir,
       workspace: this.workspace,
-      unrestricted: this.policy.unrestrictedPaths === true,
+      unrestricted: effectivePolicy.unrestrictedPaths === true,
     });
     const directories = directoriesBetween(scopeRoot, targetDir);
     const state = {
@@ -243,7 +245,7 @@ export class AgentContextManager {
       scopeRoot,
       instructionFiles: [...DEFAULT_INSTRUCTION_FILES],
       instructionMaxBytes: DEFAULT_INSTRUCTION_MAX_BYTES,
-      skillRoots: defaultSkillRoots(directories, this.home, this.codexHome, this.policy.unrestrictedPaths === true),
+      skillRoots: defaultSkillRoots(directories, this.home, this.codexHome, effectivePolicy.unrestrictedPaths === true),
       commands: new Map(),
       builtinInstructionsEnabled: true,
       automaticProjectContextEnabled: true,
@@ -264,7 +266,7 @@ export class AgentContextManager {
       const globalConfig = join(this.home, GLOBAL_CONFIG_RELATIVE_PATH);
       const config = await readOptionalConfig(globalConfig, this.home, false);
       if (config) {
-        if (this.policy.unrestrictedPaths === true) this.applyConfig(state, config, globalConfig, this.home, { global: true });
+        if (effectivePolicy.unrestrictedPaths === true) this.applyConfig(state, config, globalConfig, this.home, { global: true, unrestricted: true });
         else {
           state.configFiles.push(globalConfig);
           if (config.builtinInstructions !== null) state.builtinInstructionsEnabled = config.builtinInstructions;
@@ -284,20 +286,20 @@ export class AgentContextManager {
 
     if (this.home) {
       if (state.modelInstructionsFile) await this.collectModelInstructions(state, context);
-      if (this.policy.unrestrictedPaths === true && this.codexHome) await this.collectDirectoryInstruction(state, this.codexHome, context, "global");
+      if (effectivePolicy.unrestrictedPaths === true && this.codexHome) await this.collectDirectoryInstruction(state, this.codexHome, context, "global");
     }
 
     for (const directory of directories) {
       this.throwIfCancelled(context);
       const configPath = join(directory, CONFIG_RELATIVE_PATH);
       const config = await readOptionalConfig(configPath, directory, true);
-      if (config) this.applyConfig(state, config, configPath, directory, { global: false });
+      if (config) this.applyConfig(state, config, configPath, directory, { global: false, unrestricted: effectivePolicy.unrestrictedPaths === true });
       await this.collectDirectoryInstruction(state, directory, context, "project");
     }
     return state;
   }
 
-  applyConfig(state, config, configPath, baseDir, { global = false } = {}) {
+  applyConfig(state, config, configPath, baseDir, { global = false, unrestricted = false } = {}) {
     state.configFiles.push(configPath);
     if (config.builtinInstructions !== null) {
       if (!global) throw new Error(`builtin_instructions is only allowed in the global agent config: ${configPath}`);
@@ -317,14 +319,14 @@ export class AgentContextManager {
       if (state.instructionBytes >= state.instructionMaxBytes) state.instructionsTruncated = true;
     }
     if (config.skillRoots) {
-      state.skillRoots = config.skillRoots.map((value) => resolveConfiguredPath(value, baseDir, this.home, this.workspace, this.policy.unrestrictedPaths === true));
+      state.skillRoots = config.skillRoots.map((value) => resolveConfiguredPath(value, baseDir, this.home, this.workspace, unrestricted));
     }
     for (const [name, definition] of config.commands) {
       if (definition === null) {
         state.commands.delete(name);
         continue;
       }
-      const cwd = resolveConfiguredPath(definition.cwd, baseDir, this.home, this.workspace, this.policy.unrestrictedPaths === true);
+      const cwd = resolveConfiguredPath(definition.cwd, baseDir, this.home, this.workspace, unrestricted);
       state.commands.set(name, {
         name,
         description: definition.description,
@@ -379,13 +381,14 @@ export class AgentContextManager {
   }
 
   async discoverSkills(state, options = {}, context = {}) {
+    const effectivePolicy = this.policyForContext(context);
     return discoverLocalSkills({
       skillRoots: state.skillRoots,
       query: String(options.query || ""),
       maxResults: clampInteger(options.maxResults, 100, 1, MAX_SKILL_RESULTS),
       workspace: this.workspace,
-      unrestricted: this.policy.unrestrictedPaths === true,
-      displayPath: this.displayPath,
+      unrestricted: effectivePolicy.unrestrictedPaths === true,
+      displayPath: (value) => this.displayPath(value, context),
       context,
       throwIfCancelled: this.throwIfCancelled,
     });

package/src/local/app-automation.mjs

@@ -102,9 +102,9 @@ export class AppAutomationManager {
       if (target) argv.push(target);
       command = { cmd: "open", argv };
     } else if (this.platform === "win32") {
-      const escaped = resolvedApplication.replace(/'/g, "''");
-      const targetFragment = target ? ` -ArgumentList '${target.replace(/'/g, "''")}'` : "";
-      command = { cmd: "powershell.exe", argv: ["-NoProfile", "-NonInteractive", "-Command", `Start-Process -FilePath '${escaped}'${targetFragment}`] };
+      const fileLiteral = powershellSingleQuotedLiteral(resolvedApplication);
+      const targetFragment = target ? ` -ArgumentList ${powershellSingleQuotedLiteral(target)}` : "";
+      command = { cmd: "powershell.exe", argv: ["-NoProfile", "-NonInteractive", "-Command", `Start-Process -FilePath ${fileLiteral}${targetFragment}`] };
     } else if (resolvedApplication.toLowerCase().endsWith(".desktop")) {
       command = { cmd: "gio", argv: ["launch", resolvedApplication, ...(target ? [target] : [])] };
     } else {
@@ -113,7 +113,8 @@ export class AppAutomationManager {
         : { cmd: resolvedApplication, argv: [] };
     }
     const result = await this.runProcess(command.cmd, command.argv, clampInt(args.timeout_seconds, 30, 1, 120) * 1000, false, 256 * 1024, context, undefined, null);
-    return { application, resolved_application: resolvedApplication, target, platform: this.platform, ...result };
+    const publicResolvedApplication = /[\\/]/.test(resolvedApplication) ? this.displayPath(resolvedApplication) : resolvedApplication;
+    return { application, resolved_application: publicResolvedApplication, target, platform: this.platform, ...result };
   }
 
   async inspectApplication(args = {}, context = {}) {
@@ -417,3 +418,7 @@ function main() {
 }
 (() => { try { return JSON.stringify(main()); } catch (error) { return JSON.stringify({ error: String(error.message || error) }); } })()
 `;
+
+export function powershellSingleQuotedLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}

package/src/local/authority-context.mjs

@@ -0,0 +1,106 @@
+import { BridgeError } from "./errors.mjs";
+import { intersectPolicies, normalizePolicy, policyProfile } from "./policy.mjs";
+
+const ACCOUNT_ID = /^acct_[A-Za-z0-9_-]{20,96}$/;
+const CLIENT_ID = /^mcp_client_[A-Za-z0-9_-]{43}$/;
+const FAMILY_ID = /^mcp_family_[A-Za-z0-9_-]{43}$/;
+
+export function buildAuthorityContext({ authorization = {}, daemonPolicy, origin = "local" } = {}) {
+  if (origin !== "relay") {
+    const policy = normalizePolicy(daemonPolicy || {});
+    return Object.freeze({
+      origin: "local",
+      principal: Object.freeze({ kind: "local", role: "owner" }),
+      daemonPolicy: policy,
+      accountPolicy: policy,
+      effectivePolicy: policy,
+      owner: true,
+    });
+  }
+
+  const accountId = String(authorization.account_id || "");
+  const clientId = String(authorization.client_id || "");
+  const familyId = String(authorization.family_id || "");
+  const role = String(authorization.role || "").trim().toLowerCase();
+  const accountVersion = Number(authorization.account_version);
+  if (!ACCOUNT_ID.test(accountId) || !CLIENT_ID.test(clientId) || !FAMILY_ID.test(familyId) || !Number.isSafeInteger(accountVersion) || accountVersion <= 0) {
+    throw new BridgeError("authorization_denied", "relay operation is missing authenticated principal identity");
+  }
+  const accountPolicy = policyProfile(roleProfile(role), "explicit");
+  const normalizedDaemonPolicy = normalizePolicy(daemonPolicy || {});
+  const effectivePolicy = intersectPolicies(normalizedDaemonPolicy, accountPolicy, { origin: "effective" });
+  const principal = Object.freeze({
+    kind: "account",
+    accountId,
+    accountVersion,
+    clientId,
+    familyId,
+    role,
+  });
+  return Object.freeze({
+    origin: "relay",
+    principal,
+    daemonPolicy: normalizedDaemonPolicy,
+    accountPolicy,
+    effectivePolicy,
+    owner: role === "owner",
+  });
+}
+
+export function policyForContext(context, fallbackPolicy) {
+  return normalizePolicy(context?.authority?.effectivePolicy || fallbackPolicy || {});
+}
+
+export function principalForContext(context) {
+  const principal = context?.authority?.principal;
+  if (principal?.kind === "account") return principal;
+  return Object.freeze({ kind: "local", role: "owner" });
+}
+
+export function principalBinding(context) {
+  const principal = principalForContext(context);
+  if (principal.kind !== "account") return { owner_kind: "local" };
+  return {
+    owner_kind: "account",
+    owner_account_id: principal.accountId,
+    owner_account_version: principal.accountVersion,
+    owner_client_id: principal.clientId,
+    owner_family_id: principal.familyId,
+    owner_role: principal.role,
+  };
+}
+
+export function assertOwnedByContext(record, context, label = "object") {
+  const principal = principalForContext(context);
+  if (principal.kind !== "account" || principal.role === "owner") return;
+  if (
+    record?.owner_kind !== "account"
+    || record.owner_account_id !== principal.accountId
+    || record.owner_account_version !== principal.accountVersion
+    || record.owner_client_id !== principal.clientId
+    || record.owner_family_id !== principal.familyId
+  ) {
+    throw new BridgeError("authorization_denied", `${label} belongs to another account or an obsolete account session`);
+  }
+}
+
+export function visibleToContext(record, context) {
+  try {
+    assertOwnedByContext(record, context);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function roleProfile(role) {
+  const mapping = {
+    reviewer: "review",
+    editor: "edit",
+    operator: "agent",
+    owner: "full",
+  };
+  const profile = mapping[role];
+  if (!profile) throw new BridgeError("authorization_denied", `unknown account role: ${role}`);
+  return profile;
+}

package/src/local/browser-bridge-http.mjs

@@ -1,5 +1,6 @@
 import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
-import { isAllowedLoopbackHost, pairingHtml, securityHeaders, sendJson } from "./browser-pairing-store.mjs";
+import { EXPECTED_EXTENSION_ID } from "./browser-extension-identity.mjs";
+import { isAllowedLoopbackHost, pairingHtml, securityHeaders, sendJson } from "./browser-pairing-http.mjs";
 
 export function handleBrowserBridgeHttp(request, response, {
   port,
@@ -26,6 +27,8 @@ export function handleBrowserBridgeHttp(request, response, {
       connected: extensionConnected(),
       broker: "machine-bridge-browser",
       expected_extension_version: EXPECTED_EXTENSION_VERSION,
+      expected_extension_id: EXPECTED_EXTENSION_ID,
+      extension_id: extension?.extension_id || "",
       extension_protocol: extension?.protocol || null,
       extension_version: extension?.version || "",
       extension_capabilities: extension?.capabilities || [],

package/src/local/browser-bridge.mjs

@@ -13,6 +13,7 @@ import { BrowserRequestRegistry } from "./browser-request-registry.mjs";
 import { handleBrowserBridgeHttp } from "./browser-bridge-http.mjs";
 import { BrowserBrokerRoutes } from "./browser-broker-routes.mjs";
 import { startBrowserBrokerServer } from "./browser-broker-server.mjs";
+import { EXPECTED_EXTENSION_ID } from "./browser-extension-identity.mjs";
 
 const MAX_PORT_ATTEMPTS = 10;
 const MAX_PENDING = 32;
@@ -49,13 +50,11 @@ export class BrowserBridgeManager {
       extensionStatusInfo: () => this.extensionStatusInfo(),
       extensionReloadRequired: () => this.extensionReloadRequired(),
     });
-    // Public aliases remain for diagnostics and compatibility with existing behavioral tests.
-    this.runtimeClients = this.brokerRoutes.clients;
-    this.proxyRoutes = this.brokerRoutes.routes;
     this.startPromise = null;
     this.startGeneration = 0;
     this.port = 0;
-    this.token = "";
+    this.extensionToken = "";
+    this.runtimeToken = "";
     this.extensionPath = resolve(packageRoot, "browser-extension");
     this.operationService = new BrowserOperationService({
       authorizeTool: (tool) => this.authorizeTool(tool),
@@ -67,15 +66,19 @@ export class BrowserBridgeManager {
         extensionConnected: this.extensionConnected(),
         extensionInfo: this.extensionStatusInfo(),
         extensionReloadRequired: this.extensionReloadRequired(),
+        ...this.brokerRoutes.snapshot(),
       }),
       extensionPath: this.extensionPath,
       expectedExtensionVersion: EXPECTED_EXTENSION_VERSION,
+      expectedExtensionId: EXPECTED_EXTENSION_ID,
       runProcess: (...args) => this.runProcess(...args),
       readResourceText: (name) => this.readResourceText(name),
       readResourceBinary: (name) => this.readResourceBinary(name),
     });
   }
 
+  brokerDiagnostics() { return this.brokerRoutes.snapshot(); }
+
   status(context = {}) { return this.operationService.status(context); }
 
   pair(args = {}, context = {}) { return this.operationService.pair(args, context); }
@@ -133,14 +136,15 @@ export class BrowserBridgeManager {
     try {
       const pairing = await loadOrCreatePairing(this.stateRoot);
       this.assertStartCurrent(generation);
-      this.token = pairing.token;
+      this.extensionToken = pairing.extensionToken;
+      this.runtimeToken = pairing.runtimeToken;
       for (let offset = 0; offset < MAX_PORT_ATTEMPTS; offset += 1) {
         const port = pairing.port + offset;
         try {
           await this.listen(port);
           this.assertStartCurrent(generation);
           if (port !== pairing.port && this.stateRoot) {
-            await savePairing(this.stateRoot, { token: this.token, port });
+            await savePairing(this.stateRoot, { schemaVersion: pairing.schemaVersion, extensionToken: this.extensionToken, runtimeToken: this.runtimeToken, port });
             this.assertStartCurrent(generation);
           }
           return;
@@ -176,7 +180,8 @@ export class BrowserBridgeManager {
     this.port = port;
     const { server, wss } = await startBrowserBrokerServer({
       port,
-      token: this.token,
+      extensionToken: this.extensionToken,
+      runtimeToken: this.runtimeToken,
       maxPayload: MAX_BROWSER_MESSAGE_BYTES,
       onHttp: (request, response) => this.handleHttp(request, response),
       onSocket: (socket, role) => this.acceptSocket(socket, role),
@@ -189,7 +194,7 @@ export class BrowserBridgeManager {
     const url = `ws://127.0.0.1:${port}/runtime`;
     return new Promise((resolvePromise) => {
       let settled = false;
-      const ws = new WebSocket(url, [`mbm-runtime.${this.token}`], { maxPayload: MAX_BROWSER_MESSAGE_BYTES });
+      const ws = new WebSocket(url, [`mbm-runtime.${this.runtimeToken}`], { maxPayload: MAX_BROWSER_MESSAGE_BYTES });
       const timer = setTimeout(() => finish(false), 1500);
       timer.unref?.();
       const finish = (ok) => {
@@ -372,7 +377,7 @@ export class BrowserBridgeManager {
   handleHttp(request, response) {
     return handleBrowserBridgeHttp(request, response, {
       port: this.port,
-      token: this.token,
+      token: this.extensionToken,
       extensionConnected: () => this.extensionConnected(),
       extensionStatusInfo: () => this.extensionStatusInfo(),
       extensionReloadRequired: () => this.extensionReloadRequired(),

package/src/local/browser-broker-routes.mjs

@@ -13,6 +13,10 @@ export class BrowserBrokerRoutes {
     this.routes = new Map();
   }
 
+  snapshot() {
+    return Object.freeze({ runtime_clients: this.clients.size, routed_requests: this.routes.size });
+  }
+
   acceptClient(socket) {
     this.clients.add(socket);
     socket.on("message", (data) => this.handleClientMessage(socket, data));

package/src/local/browser-broker-server.mjs

@@ -1,8 +1,9 @@
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
-import { isAllowedExtensionOrigin, isAllowedLoopbackHost } from "./browser-pairing-store.mjs";
+import { isAllowedExtensionOrigin, isAllowedLoopbackHost } from "./browser-pairing-http.mjs";
+import { EXPECTED_EXTENSION_ID } from "./browser-extension-identity.mjs";
 
-export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp, onSocket }) {
+export async function startBrowserBrokerServer({ port, extensionToken, runtimeToken, maxPayload, onHttp, onSocket }) {
   const server = createServer(onHttp);
   const wss = new WebSocketServer({ noServer: true, maxPayload });
   server.on("upgrade", (request, socket, head) => {
@@ -16,8 +17,8 @@ export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp
       const protocol = String(request.headers["sec-websocket-protocol"] || "");
       const origin = String(request.headers.origin || "");
       let role = "";
-      if (url.pathname === "/extension" && protocol === `mbm.${token}` && isAllowedExtensionOrigin(origin)) role = "extension";
-      if (url.pathname === "/runtime" && protocol === `mbm-runtime.${token}` && !origin) role = "runtime";
+      if (url.pathname === "/extension" && protocol === `mbm.${extensionToken}` && isAllowedExtensionOrigin(origin, EXPECTED_EXTENSION_ID)) role = "extension";
+      if (url.pathname === "/runtime" && protocol === `mbm-runtime.${runtimeToken}` && !origin) role = "runtime";
       if (!role) {
         rejectUpgrade(socket, "401 Unauthorized");
         return;

package/src/local/browser-extension-identity.mjs

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { packageRoot } from "./state.mjs";
+
+const EXTENSION_ID_PATTERN = /^[a-p]{32}$/;
+const PUBLIC_KEY_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+
+const manifest = readExtensionManifest();
+export const EXPECTED_EXTENSION_PUBLIC_KEY = normalizeManifestPublicKey(manifest.key);
+export const EXPECTED_EXTENSION_ID = extensionIdFromPublicKey(EXPECTED_EXTENSION_PUBLIC_KEY);
+
+export function extensionIdFromPublicKey(value) {
+  const publicKey = normalizeManifestPublicKey(value);
+  const bytes = Buffer.from(publicKey, "base64");
+  const hexadecimal = createHash("sha256").update(bytes).digest("hex").slice(0, 32);
+  const extensionId = [...hexadecimal]
+    .map((character) => String.fromCharCode(97 + Number.parseInt(character, 16)))
+    .join("");
+  if (!EXTENSION_ID_PATTERN.test(extensionId)) throw new Error("browser extension public key produced an invalid extension id");
+  return extensionId;
+}
+
+export function normalizeExtensionId(value) {
+  const extensionId = String(value || "").trim().toLowerCase();
+  return EXTENSION_ID_PATTERN.test(extensionId) ? extensionId : "";
+}
+
+function normalizeManifestPublicKey(value) {
+  const publicKey = String(value || "").trim();
+  if (!PUBLIC_KEY_PATTERN.test(publicKey) || publicKey.length < 128 || publicKey.length > 8192) {
+    throw new Error("browser extension manifest must contain a bounded base64 public key");
+  }
+  let bytes;
+  try { bytes = Buffer.from(publicKey, "base64"); }
+  catch { throw new Error("browser extension manifest public key is invalid base64"); }
+  if (bytes.length < 96 || bytes.length > 6144 || bytes.toString("base64") !== publicKey) {
+    throw new Error("browser extension manifest public key is not canonical DER base64");
+  }
+  return publicKey;
+}
+
+function readExtensionManifest() {
+  const path = resolve(packageRoot, "browser-extension", "manifest.json");
+  const manifestValue = JSON.parse(readFileSync(path, "utf8"));
+  if (!manifestValue || typeof manifestValue !== "object" || Array.isArray(manifestValue)) {
+    throw new Error("browser extension manifest is invalid");
+  }
+  return manifestValue;
+}

package/src/local/browser-extension-protocol.mjs

@@ -3,6 +3,7 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { packageRoot } from "./state.mjs";
+import { EXPECTED_EXTENSION_ID, normalizeExtensionId } from "./browser-extension-identity.mjs";
 
 export const BROWSER_EXTENSION_PROTOCOL = 3;
 export const EXPECTED_EXTENSION_VERSION = extensionVersion();
@@ -11,13 +12,13 @@ const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
 ]);
 export const MAX_BROWSER_MESSAGE_BYTES = 8 * 1024 * 1024;
 
-/** @typedef {{protocol: number, version: string, capabilities: string[]}} ExtensionInfo */
+/** @typedef {{protocol: number, version: string, extension_id: string, capabilities: string[]}} ExtensionInfo */
 /** @typedef {{readyState: number, close: (code?: number, reason?: string) => unknown, send: (value: string) => unknown}} ProtocolSocket */
 
 /** @param {unknown} value @returns {ExtensionInfo | null} */
 export function normalizeCompatibleExtensionInfo(value) {
   const info = normalizeExtensionInfo(value);
-  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL || info.version !== EXPECTED_EXTENSION_VERSION) return null;
+  if (!info || info.protocol !== BROWSER_EXTENSION_PROTOCOL || info.version !== EXPECTED_EXTENSION_VERSION || info.extension_id !== EXPECTED_EXTENSION_ID) return null;
   if (REQUIRED_EXTENSION_CAPABILITIES.some((capability) => !info.capabilities.includes(capability))) return null;
   return info;
 }
@@ -32,6 +33,9 @@ export function parseExtensionHello(message) {
   if (info.version !== EXPECTED_EXTENSION_VERSION) {
     throw new Error(`extension version mismatch; expected ${EXPECTED_EXTENSION_VERSION}; reload the extension`);
   }
+  if (info.extension_id !== EXPECTED_EXTENSION_ID) {
+    throw new Error(`extension identity mismatch; expected ${EXPECTED_EXTENSION_ID}; reload the packaged extension`);
+  }
   const missing = REQUIRED_EXTENSION_CAPABILITIES.filter((capability) => !info.capabilities.includes(capability));
   if (missing.length) throw new Error(`extension capability mismatch; reload the extension (${missing.join(",")})`);
   return info;
@@ -77,11 +81,12 @@ function normalizeExtensionInfo(value) {
   const record = /** @type {Record<string, unknown>} */ (value);
   const protocol = Number(record.protocol);
   const version = typeof record.version === "string" && record.version.length <= 100 ? record.version : "";
+  const extension_id = normalizeExtensionId(record.extension_id);
   const capabilities = Array.isArray(record.capabilities)
     ? [...new Set(record.capabilities.filter((entry) => typeof entry === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(entry)))].slice(0, 32)
     : [];
-  if (!Number.isInteger(protocol) || protocol < 1 || !version) return null;
-  return { protocol, version, capabilities };
+  if (!Number.isInteger(protocol) || protocol < 1 || !version || !extension_id) return null;
+  return { protocol, version, extension_id, capabilities };
 }
 
 function extensionVersion() {