machine-bridge-mcp 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.17.1 - 2026-07-14
+
+### Installation and first use
+
+- Add an end-to-end installation and first-use guide covering transport selection, authority profiles, prerequisites, released and source installation, first remote deployment, current ChatGPT developer-mode connection, stdio configuration, existing-profile browser pairing, verification, routine operation, multi-workspace use, upgrades, layered troubleshooting, and fail-closed removal.
+- Link the detailed guide from the README while retaining the compact command reference, and clarify how to distinguish package, Cloudflare, daemon, MCP-host, operating-system, and browser failures.
+
+### Multi-client and multi-account boundary
+
+- Document that the existing Worker supports multiple OAuth client registrations and access tokens but does not provide isolated human/service accounts: all successful authorizations use one per-workspace connection password and share the same policy and daemon authority.
+- Define a principal-aware evolution path that keeps OAuth clients separate from principals, memberships, and named grants; uses capability intersection and dual Worker/local enforcement; adds targeted revocation and per-principal quotas; and retains one bridge/Durable Object per workspace or trust domain.
+- Make the security and architecture contracts explicit: mutually untrusted users require separate bridge instances and preferably separate low-privilege OS, container, or VM boundaries because application-level roles cannot isolate local process, shell, browser, or credential-store authority.
+
 ## 0.17.0 - 2026-07-13
 
 ### Project governance and contribution flow

package/README.md

@@ -23,6 +23,8 @@ Local clients such as Claude Desktop, Cursor, and Codex CLI
 
 The remote Worker authenticates and relays calls. It cannot directly read local files or start local processes. File, Git, image, patch, process, diagnostic, and managed-job operations execute in the local runtime.
 
+New users should follow the end-to-end [installation and first-use guide](docs/GETTING_STARTED.md). Before sharing a deployment or connecting several accounts, read [multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md).
+
 ## Default behavior and policy profiles
 
 A newly selected workspace starts with the maximum-permission `full` profile for low-friction operation:
@@ -45,6 +47,8 @@ This default prioritizes usability, not least privilege. `run_process` and proce
 
 ## Install
 
+For prerequisites, first remote deployment, ChatGPT connection, stdio configuration, browser pairing, upgrades, troubleshooting, and removal, follow [Installation and first use](docs/GETTING_STARTED.md). The commands below are the compact installation reference.
+
 Node.js 26 or newer and npm 12 or newer are required. The repository pins the active development versions in `.node-version`, `.nvmrc`, and `packageManager`; project installs fail on older Node runtimes.
 
 Use a new temporary directory for the bootstrap. The existing `npm`/`npx` front-end may inspect nearby project metadata before it launches the requested npm version; starting from an empty directory prevents an unrelated legacy `devEngines` declaration from blocking the bootstrap. The actual installation is then executed by the pinned npm 12 CLI rather than whichever npm happens to be first on `PATH`.
@@ -126,6 +130,12 @@ MCP connection password: mcp_password_...
 
 The remote authorization flow uses an authorization code, PKCE S256, exact redirect/resource binding, expiring access tokens stored as hashes, and a token-version value for bulk revocation. After password approval, the Worker constructs the registered callback with the URL API and returns `303 See Other`, so OAuth response parameters are encoded and the browser performs a GET to the callback.
 
+### Multiple clients and accounts
+
+One Worker can hold several OAuth client registrations and access tokens, so the same trusted owner or team can connect more than one MCP application or ChatGPT account. This is **multi-client access, not isolated multi-account tenancy**: the current release uses one workspace connection password, one workspace policy, and one active daemon authority. It has no principal records, per-account roles, targeted account revocation, or account-specific audit boundary.
+
+Do not share a `full` bridge with mutually untrusted users. Use a separate bridge and preferably a separate low-privilege OS account, container, or VM for each trust domain. See [Multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md) for the current support matrix and the proposed principal/grant design.
+
 ## Optional local stdio MCP
 
 stdio is a local transport, not a model provider. Claude Desktop, Cursor, Codex CLI, ChatGPT Desktop, or another MCP host supplies its own model/session and launches `machine-bridge-mcp` as a subprocess. The MCP server only exposes tools and returns their results; it does not borrow the model running in ChatGPT web.
@@ -480,7 +490,7 @@ npm pack --dry-run
 
 `npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, recursively discovered JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, concurrent lock/atomic-replacement/PID-reuse fixtures, fail-closed service lifecycle tests, descendant process-tree termination, local path/write/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/mode/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), the generated [MCP tool reference](docs/TOOL_REFERENCE.md), and [SECURITY.md](SECURITY.md).
+The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md), [docs/MULTI_ACCOUNT.md](docs/MULTI_ACCOUNT.md), [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), the generated [MCP tool reference](docs/TOOL_REFERENCE.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/SECURITY.md

@@ -36,6 +36,14 @@ An authorized client can invoke every tool exposed by the selected profile and r
 
 The Worker is a remote authentication and relay boundary. The local runtime is the filesystem and process boundary. Stdio bypasses the Worker and relies on local process/configuration trust.
 
+### Multiple clients are not isolated accounts
+
+The current remote design accepts multiple OAuth client registrations and can issue multiple access tokens, but it has one per-workspace connection password and one workspace policy. An OAuth `client_id` identifies client software and redirect URIs; it is not a human or service principal. Different ChatGPT accounts or MCP applications that authorize with the same password therefore enter the same trust domain and receive the same Machine Bridge authority.
+
+The current release has no per-account role, suspension, membership expiry, targeted principal revocation, or account-specific audit boundary. Secret rotation invalidates all outstanding access tokens for the workspace. Do not present this behavior as multi-user tenancy.
+
+Mutually untrusted users must use separate bridge instances and external isolation appropriate to the authority exposed: a dedicated low-privilege OS account, container, or VM, a narrow workspace, an independent state root and Worker credential set, and the narrowest useful profile. Worker-side account records alone cannot isolate direct processes, shells, browser sessions, Accessibility actions, credential stores, or network authority inherited from the local OS user. See [Multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md).
+
 ## Profiles are capability sets, not sandboxes
 
 The default for newly selected workspaces is `full`, which prioritizes ease of use over least privilege. Named profiles are canonical capability contracts. A stored `full` label is repaired on load to the complete maximum-permission field set and tool catalog; a deliberate per-capability override is represented as `custom`, not as a partially restricted `full`.
@@ -152,7 +160,7 @@ Runner diagnostic logs are owner-only and do not receive child stdout/stderr. St
 
 ## OAuth and public endpoints
 
-Remote mode uses authorization code flow with PKCE S256, exact redirect/resource/client binding, expiring authorization codes and access tokens, hashed token storage, token-version revocation, and bounded dynamic client registration. Successful consent constructs the registered callback through the URL API and returns `303 See Other`; response parameters are encoded rather than concatenated into an unchecked header string.
+Remote mode uses authorization code flow with PKCE S256, exact redirect/resource/client binding, expiring authorization codes and access tokens, hashed token storage, token-version revocation, and bounded dynamic client registration. Client registrations and tokens may coexist, but all authorizations currently share one workspace credential and authority; there is no principal-aware account model. Successful consent constructs the registered callback through the URL API and returns `303 See Other`; response parameters are encoded rather than concatenated into an unchecked header string.
 
 The authorization page displays the validated client name and redirect URI. Enter the connection password only after initiating the connection and recognizing both values.
 

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.17.0"
+  "version_name": "0.17.1"
 }

package/docs/ARCHITECTURE.md

@@ -109,6 +109,8 @@ All requests for a deployed Worker route to one named Durable Object. It owns:
 
 The Worker verifies OAuth, validates MCP envelopes and optional protocol headers, converts `tools/call` into WebSocket messages, correlates cancellation by access-token hash and JSON-RPC ID, and formats text/structured/image results. It has no local filesystem or process API.
 
+The current OAuth store is multi-client but not principal-aware. `client_id` identifies an MCP application/installation; it does not identify a human or service account. Every successful authorization uses the same per-workspace connection password and receives the same workspace policy ceiling. Isolated account support therefore requires explicit principals, memberships, named grants, targeted revocation, and dual Worker/local enforcement rather than treating client registrations as users. The recommended design retains one bridge-specific Durable Object and one local runtime per workspace/trust domain; see [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md).
+
 The daemon attachment deliberately omits workspace path/name/hash and process ID. Explicit authenticated tools may return workspace metadata according to local path-display policy.
 
 ### Autostart layer
@@ -138,7 +140,7 @@ flowchart LR
   CLI --> S[Autostart provider]
 ```
 
-Remote OAuth determines which client may call tools. Local stdio access relies on the local process and configuration boundary. Policy determines which tools the local daemon and relay advertise. A connector host can independently present a smaller tool subset to a session; this post-relay filtering is outside the protocol state visible to Machine Bridge. Canonical resolution limits direct filesystem tools. Processes retain local-user authority and can escape workspace constraints through their own code or system calls.
+Remote OAuth currently determines which registered client token may call tools; it does not distinguish independently authorized human principals. Local stdio access relies on the local process and configuration boundary. Policy determines which tools the local daemon and relay advertise. A connector host can independently present a smaller tool subset to a session; this post-relay filtering is outside the protocol state visible to Machine Bridge. Canonical resolution limits direct filesystem tools. Processes retain local-user authority and can escape workspace constraints through their own code or system calls.
 
 ## Remote request lifecycle
 
@@ -258,4 +260,4 @@ Third-party workflow actions are pinned to immutable commit SHAs. Dependabot pro
 - model-level prompt-injection prevention or semantic validation of browser/application actions;
 - universal desktop UI automation beyond the implemented OS Accessibility backend;
 - scripting browser-internal/enterprise-blocked pages or inaccessible cross-origin frames;
-- multi-user tenancy in one Worker deployment.
+- isolated multi-user tenancy or per-principal authorization in one Worker deployment; multiple OAuth client registrations currently share one workspace authority.

package/docs/CLIENTS.md

@@ -124,6 +124,8 @@ machine-mcp --workspace /path/to/project
 
 Enter the printed `/mcp` URL in the remote MCP connector. During OAuth authorization, verify the displayed client name and redirect URI before entering the connection password.
 
+Several OAuth clients and access tokens can coexist, but the current release does not model separate human/service principals. Every authorization that uses the shared workspace password receives the same workspace authority. Do not treat separate ChatGPT accounts as isolated Machine Bridge accounts; see [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md).
+
 ## Profile guidance
 
 - `full` is the default and prioritizes immediate usability. It is a canonical contract exposing every catalog tool, shell execution, unrestricted direct filesystem paths, absolute path output, and the full parent environment. Any individual narrowing is represented as `custom`.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,400 @@
+# Installation and first-use guide
+
+This guide covers a clean installation, the first remote ChatGPT connection, local stdio clients, browser setup, routine operation, upgrades, troubleshooting, and removal.
+
+## 1. Decide which connection mode you need
+
+Machine Bridge has two transports. Choose one before installing:
+
+| Requirement | Use | Cloudflare required | Process that must remain available |
+|---|---|---:|---|
+| ChatGPT web, a hosted agent, or another device must reach this computer | Remote HTTPS/OAuth | Yes | Machine Bridge daemon or installed login service |
+| Claude Desktop, Cursor, Codex, ChatGPT Desktop, or another local host runs on this computer | Local stdio | No | The MCP host launches Machine Bridge as a subprocess |
+| The local coding client already has equivalent file, Git, patch, and terminal tools | Neither | No | None |
+
+Remote and stdio modes use the same local runtime and policy model. The remote Worker authenticates and relays calls; it does not read files or execute processes by itself.
+
+## 2. Understand the authority you are granting
+
+A new workspace uses the `full` profile unless another profile is selected explicitly. `full` exposes the complete tool catalog, shell execution, paths outside the selected workspace, absolute paths, and the complete parent process environment. It is intended for a trusted owner using a trusted MCP host.
+
+For a first connection to an unfamiliar host, start with a narrower profile:
+
+```sh
+machine-mcp --workspace /path/to/project --profile review
+```
+
+Profiles:
+
+| Profile | Reads | File changes | Direct processes | Shell | Direct filesystem scope |
+|---|---:|---:|---:|---:|---|
+| `full` | Yes | Yes | Yes | Yes | Unrestricted |
+| `agent` | Yes | Yes | Yes | No | Selected workspace |
+| `edit` | Yes | Yes | No | No | Selected workspace |
+| `review` | Yes | No | No | No | Selected workspace |
+
+A profile is a Machine Bridge policy ceiling. The MCP host, operating system, endpoint-security software, container, and cloud platform may impose additional restrictions.
+
+## 3. Prerequisites
+
+Required for every installation:
+
+- Node.js 26 or newer;
+- npm 12 or newer;
+- macOS, Linux, or Windows;
+- a local user account permitted to read or modify the selected workspace.
+
+Remote mode additionally requires:
+
+- a Cloudflare account permitted to deploy Workers and Durable Objects;
+- a browser available for Wrangler sign-in;
+- outbound HTTPS and WebSocket access from the computer running the daemon.
+
+Browser automation additionally requires:
+
+- a Chromium-based browser that can load an unpacked Manifest V3 extension;
+- the extension loaded into the browser profile whose tabs and login state should be controlled.
+
+Check the installed runtimes:
+
+```sh
+node --version
+npm --version
+```
+
+Do not continue with an older runtime. This repository intentionally rejects unsupported Node/npm versions.
+
+## 4. Install the released package
+
+Use a temporary package-free directory. An older npm front-end can inspect metadata in the current directory before it launches npm 12; the isolated bootstrap prevents an unrelated project configuration from breaking installation.
+
+### macOS and Linux
+
+```sh
+install_dir="$(mktemp -d)"
+(
+  cd "$install_dir"
+  npx --yes npm@12.0.1 install --global npm@12.0.1
+  npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+)
+rm -rf "$install_dir"
+
+npm --version
+machine-mcp doctor
+```
+
+### Windows Command Prompt
+
+```bat
+set "MBM_INSTALL_DIR=%TEMP%\machine-bridge-mcp-install-%RANDOM%-%RANDOM%"
+mkdir "%MBM_INSTALL_DIR%"
+pushd "%MBM_INSTALL_DIR%"
+npx --yes npm@12.0.1 install --global npm@12.0.1
+npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+popd
+rmdir /s /q "%MBM_INSTALL_DIR%"
+
+npm --version
+machine-mcp doctor
+```
+
+Reopen the terminal if `npm --version` still resolves to an older global installation.
+
+### Run from a source checkout
+
+macOS/Linux:
+
+```sh
+git clone https://github.com/YuLeiFuYun/machine-bridge-mcp.git
+cd machine-bridge-mcp
+npm install
+./mbm
+```
+
+Windows Command Prompt:
+
+```bat
+git clone https://github.com/YuLeiFuYun/machine-bridge-mcp.git
+cd machine-bridge-mcp
+npm install
+.\mbm.cmd
+```
+
+Source installs are for development or review. Released installations should normally use the global package command above.
+
+## 5. Interpret the initial doctor result
+
+Run:
+
+```sh
+machine-mcp doctor
+```
+
+The command checks the local runtime, package layout, Wrangler availability, Cloudflare login state, and known Worker health. Before the first remote deployment, a missing Cloudflare login or Worker is expected; local runtime failures are not.
+
+Common installation failures:
+
+| Message or symptom | Meaning | Corrective action |
+|---|---|---|
+| `Unknown cli config "--allow-scripts"` | npm 11 or older executed the install | Repeat the isolated npm 12 bootstrap |
+| `Invalid property "node"` or `Invalid property "devEngines.node"` | An old npm parser inspected incompatible project metadata | Run the install from a new empty temporary directory |
+| `machine-mcp: command not found` | The global npm binary directory is not on `PATH` | Reopen the terminal, inspect `npm prefix -g`, and add its binary directory to `PATH` |
+| Native package install warning | npm did not approve reviewed native build scripts | Use the documented `--allow-scripts` and `--omit=optional` command exactly |
+
+## 6. First remote start
+
+Choose the exact workspace to expose. Prefer an explicit path rather than relying on the current directory:
+
+```sh
+machine-mcp --workspace /path/to/project
+```
+
+For a narrower first run:
+
+```sh
+machine-mcp --workspace /path/to/project --profile review
+```
+
+The first start performs these operations:
+
+1. canonicalizes and remembers the workspace;
+2. creates owner-only per-workspace state and credentials;
+3. opens the Wrangler/Cloudflare sign-in flow when required;
+4. deploys a Worker and Durable Object for that workspace;
+5. installs a platform-native login service unless `--no-autostart` is supplied;
+6. starts an outbound authenticated WebSocket from the local daemon to the Worker;
+7. prints the remote `/mcp` URL and a connection password.
+
+The foreground command remains attached to the terminal. Keep it running while testing. The remote Worker cannot execute local tools when no authenticated daemon is connected.
+
+To run only in the background after setup:
+
+```sh
+machine-mcp service start
+machine-mcp service status
+```
+
+To avoid installing autostart during a temporary test:
+
+```sh
+machine-mcp --workspace /path/to/project --no-autostart
+```
+
+## 7. Connect ChatGPT
+
+Machine Bridge prints values in this form:
+
+```text
+MCP Server URL: https://<worker>.<account>.workers.dev/mcp
+MCP connection password: mcp_password_...
+```
+
+Treat the connection password as a credential. Do not place it in a repository, issue, screenshot, chat message, shell history note, or shared document.
+
+Current ChatGPT developer-mode flow, as documented in OpenAI's [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) guide:
+
+1. Open ChatGPT settings.
+2. Under **Security and login**, enable **Developer mode** if the account or workspace permits it.
+3. Open **Plugins** and create a developer-mode app.
+4. Enter a descriptive name and the exact printed `/mcp` URL.
+5. Start the connection.
+6. On the Machine Bridge authorization page, verify the displayed client name, redirect URI, and resource.
+7. Enter the printed connection password only after those values are recognized.
+8. Create a new chat and enable the app for that conversation.
+
+ChatGPT navigation labels can change. The invariant is that the client must connect to the public `/mcp` endpoint and complete the OAuth authorization page served by the Worker.
+
+## 8. Verify the first connection
+
+Ask the MCP host to call these tools in order:
+
+1. `server_info` — proves the request reached the Worker and reports whether a daemon is authenticated;
+2. `project_overview` — proves the relay reached the selected local runtime;
+3. `diagnose_runtime` — runs fixed policy, filesystem, process, shell, managed-job, and resource probes permitted by the active profile.
+
+For an explicit local acceptance test of the canonical `full` profile:
+
+```sh
+machine-mcp full-test --workspace /path/to/project
+```
+
+A successful local test does not prove that a hosted MCP client exposes every advertised tool. Hosts can independently hide tools or require approvals.
+
+## 9. Configure a local stdio client
+
+Generate configurations rather than manually guessing the Node path or package entrypoint:
+
+```sh
+machine-mcp client-config --client all --workspace /path/to/project
+```
+
+Use a narrower policy when appropriate:
+
+```sh
+machine-mcp client-config --client all --workspace /path/to/project --profile agent
+machine-mcp client-config --client all --workspace /path/to/project --profile edit
+machine-mcp client-config --client all --workspace /path/to/project --profile review
+```
+
+The generated command uses absolute executable paths so GUI applications do not depend on a shell-specific `PATH`.
+
+A generic stdio invocation is:
+
+```sh
+machine-mcp stdio --workspace /path/to/project --profile full
+```
+
+The host owns the model, conversation, tool-selection loop, and approvals. Machine Bridge supplies tools; it is not a model provider.
+
+## 10. Enable existing-browser automation
+
+Run once after installation:
+
+```sh
+machine-mcp browser setup
+machine-mcp browser status
+```
+
+Then:
+
+1. Open the extensions page in the Chromium profile you actually use.
+2. Enable Developer mode.
+3. Load the unpacked extension directory printed by `browser setup`.
+4. Complete the local pairing page.
+5. Confirm that `machine-mcp browser status` reports the expected packaged version, protocol, and an authenticated connection.
+
+Machine Bridge does not launch a separate browser profile. The extension controls the profile into which it was loaded, including its open tabs and logged-in sessions. Reload the unpacked extension after every Machine Bridge upgrade.
+
+## 11. Routine commands
+
+```sh
+machine-mcp status
+machine-mcp doctor
+machine-mcp workspace show
+machine-mcp service status
+machine-mcp browser status
+machine-mcp --print-mcp-credentials
+```
+
+Useful operational actions:
+
+```sh
+machine-mcp service stop
+machine-mcp service start
+machine-mcp rotate-secrets
+machine-mcp resource list
+machine-mcp job list
+```
+
+`rotate-secrets` invalidates previously issued OAuth access tokens and requires clients to reconnect. It is a whole-workspace revocation mechanism in the current release.
+
+## 12. Work with more than one workspace
+
+Each canonical workspace receives independent state, policy, credentials, Worker name, resource registry, job directory, startup lock, and daemon lock. Select workspaces explicitly:
+
+```sh
+machine-mcp --workspace /path/to/project-a
+machine-mcp --workspace /path/to/project-b
+```
+
+Do not point two logical trust domains at one broad parent directory merely to reduce configuration. A workspace is an authorization boundary for confined profiles and an operational identity even when `full` permits paths outside it.
+
+## 13. Upgrade
+
+Repeat the isolated global installation, then start Machine Bridge in the target workspace:
+
+```sh
+install_dir="$(mktemp -d)"
+(
+  cd "$install_dir"
+  npx --yes npm@12.0.1 install --global npm@12.0.1
+  npx --yes npm@12.0.1 install --global --omit=optional --allow-scripts=esbuild,workerd,sharp,fsevents machine-bridge-mcp@latest
+)
+rm -rf "$install_dir"
+
+machine-mcp --workspace /path/to/project --verbose
+```
+
+The foreground start performs bounded takeover of an old verified daemon when safe. If it refuses:
+
+```sh
+machine-mcp service status
+machine-mcp service stop
+machine-mcp --workspace /path/to/project --verbose
+```
+
+After upgrading, reload the unpacked browser extension before relying on browser tools.
+
+## 14. Troubleshooting by layer
+
+Use the first failing layer rather than changing unrelated settings.
+
+### Package or runtime layer
+
+```sh
+node --version
+npm --version
+which machine-mcp       # macOS/Linux
+where machine-mcp       # Windows
+machine-mcp doctor
+```
+
+### Cloudflare/deployment layer
+
+```sh
+machine-mcp doctor
+machine-mcp status
+machine-mcp --workspace /path/to/project --force-worker --verbose
+```
+
+A forced deployment changes cloud state. Use it only when the normal deployment hash/health reconciliation is insufficient.
+
+### Local service/daemon layer
+
+```sh
+machine-mcp service status
+machine-mcp service stop
+machine-mcp service start
+```
+
+A connected Worker with no authenticated daemon can authorize OAuth successfully but cannot execute local tools.
+
+### MCP-host layer
+
+If `server_info` or `project_overview` never returns a structured Machine Bridge result, the host may not have delivered the call. Check the host's plugin/app enablement, tool permissions, approval UI, and connection status.
+
+### Operating-system layer
+
+If `diagnose_runtime` reaches the daemon but a probe fails, inspect filesystem permissions, macOS TCC/SIP, Windows ACLs, endpoint-security policy, shell availability, or container restrictions. Changing Machine Bridge to `full` cannot override the operating system.
+
+### Browser layer
+
+```sh
+machine-mcp browser status
+machine-mcp browser setup
+```
+
+Verify that the extension is loaded in the intended profile, its version matches the installed package, and its badge reports authenticated readiness.
+
+For detailed recovery procedures, see [OPERATIONS.md](OPERATIONS.md).
+
+## 15. Remove Machine Bridge
+
+Remove the selected deployment, service, and local state:
+
+```sh
+machine-mcp uninstall
+npm uninstall -g machine-bridge-mcp
+```
+
+Keep the deployed Worker while removing local state and autostart:
+
+```sh
+machine-mcp uninstall --keep-worker
+```
+
+Uninstall is fail-closed. If a verified daemon, active managed job, unreadable lock, or service removal cannot be resolved safely, Machine Bridge retains state for diagnosis instead of deleting only part of the installation.
+
+## 16. Before sharing access
+
+The current release supports multiple OAuth client registrations but not isolated multi-user tenancy. Different ChatGPT accounts can technically authorize against the same Worker if they know the shared connection password, but they receive the same workspace authority and cannot be managed as independent principals. Read [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md) before sharing a deployment.

package/docs/MULTI_ACCOUNT.md

@@ -0,0 +1,406 @@
+# Multi-client, multi-account, and tenancy architecture
+
+## The actual question
+
+The important question is not whether several OAuth clients can obtain tokens. The important question is:
+
+> Can independently managed principals share one Machine Bridge deployment without inheriting the same local-machine authority or being able to affect one another?
+
+The current release answers **no**. It supports multiple client registrations and multiple access tokens, but it does not model human or service accounts as independent security principals. Anyone who completes authorization with the shared workspace connection password receives the same workspace-level Machine Bridge authority.
+
+This distinction must remain explicit because an OAuth `client_id` identifies client software, not the person or service using it.
+
+## Terms
+
+| Term | Meaning in this document |
+|---|---|
+| OAuth client | A registered MCP host/application with redirect URIs and a `client_id` |
+| Principal/account | A human or service identity that may receive authority |
+| Grant | A named, versioned set of capabilities assigned to a principal for one bridge |
+| Bridge | One canonical workspace, local runtime, Worker, Durable Object, policy ceiling, and credential set |
+| Trust domain | Principals that may safely share the same local OS/runtime authority |
+| Tenant | An independently administered trust domain requiring isolation from other tenants |
+
+## Current behavior
+
+| Scenario | Current support | Security meaning |
+|---|---:|---|
+| Several MCP applications or installations connect to one Worker | Yes | Each can register a client and receive separate tokens |
+| Several ChatGPT accounts connect using the same connection password | Technically yes | They receive the same workspace authority; no account isolation |
+| Several active OAuth tokens for one client | Yes | Tokens are distinct but share the same authorization semantics |
+| Per-account roles, capability grants, suspension, or revocation | No | Only workspace-wide policy and token-version revocation exist |
+| Revoke one principal while preserving all others | No | The current emergency mechanism rotates the workspace token version and invalidates all access tokens |
+| Several independent workspaces | Yes | Each canonical workspace has independent state, policy, Worker name, secrets, resources, jobs, and locks |
+| Several mutually untrusted users in one local runtime | No | Process and browser authority remain local-user authority |
+| Multi-user tenancy in one Worker deployment | No | The architecture currently has one shared password, one policy, one active daemon, and one default Durable Object route |
+
+Relevant current implementation:
+
+- `src/worker/oauth-state.ts` stores OAuth clients, authorization codes, and tokens by `client_id` but has no principal or membership record.
+- `src/worker/index.ts` accepts one `MCP_OAUTH_PASSWORD`, validates one `OAUTH_TOKEN_VERSION`, routes the deployment to the Durable Object named `default`, and selects one authenticated daemon.
+- `src/local/state.mjs` creates independent credentials and state per canonical workspace.
+- [ARCHITECTURE.md](ARCHITECTURE.md) explicitly excludes multi-user tenancy in one Worker deployment.
+
+## Safe deployment choices today
+
+### Same owner and same trust domain
+
+Use one bridge and authorize multiple MCP clients. This is appropriate when every client/account is controlled by the same person or team and all may receive the same workspace authority.
+
+Examples:
+
+- the same owner connects ChatGPT web and a local Codex client;
+- one trusted team uses several MCP host installations with an identical role;
+- a user reconnects after replacing a device.
+
+The separate tokens improve protocol hygiene and cancellation correlation, but they are not separate authorization domains.
+
+### Different workspaces with the same owner
+
+Run one bridge identity per canonical workspace. This preserves independent state, credentials, Workers, policies, resources, and jobs. It is preferable to exposing one broad parent directory solely for convenience.
+
+### Different trust domains or mutually untrusted users
+
+Do not share one `full` runtime. Use a separate bridge instance per trust domain, preferably with:
+
+1. a dedicated low-privilege OS account, container, or VM;
+2. a narrow workspace mounted or accessible only to that identity;
+3. an independent state root and Worker credential set;
+4. a separate Worker/deployment identity where administrative separation matters;
+5. a profile no broader than the required workflow.
+
+This external boundary is necessary because direct processes, package scripts, shells, browser sessions, Accessibility actions, credential stores, and network access inherit the local user's authority. A per-account row in Worker storage cannot turn Node.js process execution into an OS sandbox.
+
+## Recommended future architecture
+
+The least coupled design is **principal-aware authorization inside one bridge, while retaining one bridge per workspace/trust domain**. Do not begin by turning the Worker into a global router for every workspace, machine, and tenant.
+
+```text
+MCP host / OAuth client
+        |
+        | authorization code + PKCE
+        v
+Principal authentication
+        |
+        v
+Bridge membership ------> named grant + revision
+        |
+        v
+OAuth code/token bound to principal + grant + resource
+        |
+        v
+Worker authorization gate
+        |
+        | bounded auth context + tool call
+        v
+Local daemon authorization gate
+        |
+        v
+Workspace / process / browser operation
+```
+
+The design has five distinct concepts:
+
+1. **Client registration** identifies the MCP application and its redirect URIs.
+2. **Principal authentication** establishes the human or service identity.
+3. **Membership** says that a principal may access one bridge.
+4. **Grant** defines the exact capabilities and constraints available to that membership.
+5. **OAuth tokens** carry a revocable reference to the principal, membership, grant revision, and protected resource.
+
+Keeping these concepts separate prevents `client_id`, email address, connection password, and policy profile from becoming overloaded pseudo-identities.
+
+## Data model
+
+A minimal Worker-side model can remain inside the existing per-bridge Durable Object:
+
+```text
+principals
+  principal_id
+  display_label
+  status
+  authentication_method
+  credential_reference_or_subject
+  revocation_version
+  created_at
+  last_authenticated_at
+
+memberships
+  membership_id
+  principal_id
+  bridge_id
+  grant_id
+  grant_revision
+  status
+  expires_at
+  created_at
+
+clients
+  client_id
+  client_name
+  redirect_uris
+  registration_identity
+  created_at
+  last_used_at
+
+authorization_codes
+  code_hash
+  client_id
+  principal_id
+  membership_id
+  grant_id
+  grant_revision
+  redirect_uri
+  code_challenge
+  scope
+  resource
+  expires_at
+
+access_tokens
+  token_hash
+  client_id
+  principal_id
+  membership_id
+  grant_id
+  grant_revision
+  principal_revocation_version
+  scope
+  resource
+  expires_at
+```
+
+Use random opaque identifiers. Do not use an email address, OAuth source address, client name, or browser fingerprint as the primary authorization key.
+
+The current `OAuthClient`, `OAuthCode`, and `OAuthToken` records can be migrated by adding optional principal/grant fields and treating legacy records as the single-owner principal until reauthorization. Avoid a flag day that silently changes existing users' authority.
+
+## Grant model
+
+A grant should reference capabilities rather than duplicate an arbitrary list of tool names. The current shared policy contract already provides the correct vocabulary and compound requirements.
+
+Example conceptual grants:
+
+| Grant | Capabilities | Typical use |
+|---|---|---|
+| `reviewer` | read-only, workspace-confined | inspection and review |
+| `editor` | read/write, no process execution | deterministic file changes |
+| `agent` | workspace-confined writes and direct processes, isolated environment | trusted coding automation |
+| `operator` | canonical `full` | single-owner or highly trusted administration |
+
+The effective authorization must be the intersection of all applicable ceilings:
+
+```text
+local workspace policy ceiling
+AND principal membership grant
+AND OAuth scopes/resource binding
+AND any MCP-host-side restrictions
+```
+
+A grant must never widen the locally selected workspace policy. For example, assigning `operator` cannot make a daemon started under `review` execute a process.
+
+Do not create a second independently maintained permission matrix. Grant resolution should consume the same shared capability contract used by local policy, Worker tool advertisement, and runtime execution.
+
+## Dual enforcement without two sources of truth
+
+Worker-only filtering is insufficient because a protocol bug, stale token, alternate transport, or compromised relay must not bypass local authority. Local-only filtering is also insufficient because unauthorized tools should not be advertised or relayed.
+
+Use the following contract:
+
+1. The local daemon owns the machine policy ceiling and the canonical grant catalog it is willing to honor.
+2. On authenticated `hello`, the daemon advertises a bounded grant-catalog revision/digest plus the policy ceiling and tool catalog.
+3. The Worker owns principals, memberships, OAuth codes, and access tokens for that bridge.
+4. A membership references only a grant ID/revision present in the daemon-advertised catalog.
+5. The Worker filters `tools/list` and rejects `tools/call` using the membership grant.
+6. Every relayed call includes a bounded authorization context containing opaque principal, membership, grant, and revision identifiers plus scopes.
+7. The local daemon independently resolves the grant and rechecks the operation against the current local ceiling before execution.
+8. A missing grant, stale revision, digest mismatch, suspended membership, or revoked principal fails closed.
+
+This is not duplicated policy: the shared contract defines capability semantics; the Worker and daemon enforce the same resolved grant at separate trust boundaries.
+
+## Authentication choices
+
+Authentication should be an adapter behind the principal model, not embedded in tool authorization.
+
+Reasonable progression:
+
+1. **Compatibility mode:** retain the existing shared connection password and map it to one owner principal.
+2. **Local managed accounts:** create separate high-entropy one-time invitations or passkey/WebAuthn credentials for principals.
+3. **External identity provider:** accept OIDC identities from a configured issuer and map stable issuer/subject pairs to principals.
+4. **Service principals:** use separately rotated non-human credentials with narrow grants and explicit expiry.
+
+Do not issue one static password per person while leaving tokens unbound to a principal. That changes credential distribution but does not create account semantics.
+
+For external identity, key principals by the pair `(issuer, subject)`, not by mutable email or display name. Keep identity-provider integration optional so a self-hosted single-owner installation remains simple.
+
+## OAuth and MCP authorization rules
+
+A principal-aware implementation should preserve the current authorization-code and PKCE flow and add these rules:
+
+- the authorization code is bound to the authenticated principal, membership, client, redirect URI, PKCE challenge, scope, and resource;
+- access tokens are audience/resource restricted to the exact bridge `/mcp` endpoint;
+- tokens contain no raw credentials and are stored only as hashes;
+- requested scopes are intersected with the membership grant rather than accepted as authority by themselves;
+- dynamic client registration limits remain independent of principal limits;
+- token and authorization-code quotas are enforced per principal and client as well as globally;
+- cancellation/request correlation includes the token identity but never treats it as the principal database key;
+- token validation checks principal status, membership status/expiry, principal revocation version, grant revision, token expiry, and resource binding.
+
+The MCP authorization specification uses OAuth protected-resource metadata and resource indicators; OAuth security best practice requires exact redirect matching, PKCE, and audience-restricted tokens. Preserve those properties when adding identity rather than inventing a parallel session protocol.
+
+## Revocation
+
+The current `OAUTH_TOKEN_VERSION` is useful as an emergency whole-bridge kill switch but too coarse for ordinary account management.
+
+Add four independent revocation levels:
+
+1. revoke one access token/session;
+2. revoke all tokens issued to one OAuth client for a principal;
+3. increment one principal's revocation version or suspend the principal;
+4. change or revoke one membership/grant revision.
+
+Keep whole-bridge secret rotation for suspected deployment compromise. Ordinary account removal should not disconnect every other principal.
+
+Managed jobs require separate treatment: a running job snapshots authority at acceptance and can outlive an MCP token. Revoking an account should block new calls immediately and provide an explicit option to cancel active jobs accepted by that membership. Silent automatic cancellation may be unsafe when cleanup/finally steps are required.
+
+## Administration surface
+
+Account management is an operator function, not an ordinary MCP tool available to every account. A future CLI could expose:
+
+```text
+machine-mcp account invite
+machine-mcp account list
+machine-mcp account show ACCOUNT_ID
+machine-mcp account set-grant ACCOUNT_ID GRANT
+machine-mcp account suspend ACCOUNT_ID
+machine-mcp account revoke ACCOUNT_ID
+machine-mcp account sessions ACCOUNT_ID
+machine-mcp account revoke-session SESSION_ID
+```
+
+These names are a design proposal, not current commands.
+
+Administrative mutations should require local operator access or a separately protected admin plane. Do not let a normal `full` MCP session implicitly create additional principals merely because it can execute shell commands; that would make account administration indistinguishable from local-machine takeover.
+
+## Concurrency and quotas
+
+The existing global bounds should remain. Add fair per-principal limits for:
+
+- concurrent relay calls;
+- OAuth clients and active tokens;
+- authorization failures;
+- process sessions;
+- accepted managed jobs;
+- response bytes and rate windows where needed.
+
+A principal limit must not replace a global limit. Otherwise many accounts can exhaust one daemon collectively.
+
+A single local daemon still serializes or coordinates operations that mutate shared workspace state. Account support does not make concurrent Git operations, patches, browser actions, or service changes conflict-free. Existing mutation locks and transactional checks remain authoritative.
+
+## Audit and privacy
+
+Operational logs must continue to omit credentials, tool arguments, file contents, process output, browser content, and personal identifiers.
+
+For account diagnosis, log only bounded pseudonymous identifiers such as an HMAC-derived principal handle, grant ID/revision, event class, and outcome. Store a separate owner-only administrative audit record only when there is a concrete operator requirement, with explicit retention and access controls.
+
+Do not expose account lists, emails, identity-provider subjects, or session inventories through ordinary `server_info`. A principal may see its own effective grant and token expiry; only the local administrator should see cross-account inventory.
+
+## Cloudflare Durable Object topology
+
+Retain one Durable Object instance per bridge/workspace. It already provides a serializable state and WebSocket coordination boundary for that bridge.
+
+Avoid these two extremes:
+
+- **One Durable Object per access token:** this fragments the one-daemon call registry and complicates global limits, cancellation, and grant updates.
+- **One global Durable Object for every workspace and tenant:** this increases blast radius, couples unrelated deployments, creates a central routing/credential registry, and makes local lifecycle operations harder to reason about.
+
+If a future shared control plane is required, keep it limited to account discovery/invitations and route each request to the bridge-specific Durable Object. Local tool calls should still terminate at the bridge boundary.
+
+## Rejected designs
+
+### Treat `client_id` as the account
+
+Rejected because one application may serve many users and one user may use many applications. Client rotation or reinstall would also appear to create a new person.
+
+### Give each user a different connection password only
+
+Rejected because credentials, tokens, grants, revocation, quotas, and audit events still lack a stable principal binding.
+
+### Enforce grants only in the Worker
+
+Rejected because the local runtime is the final filesystem/process boundary and must fail closed independently.
+
+### Enforce grants only in the daemon
+
+Rejected because the Worker would advertise and relay tools to unauthorized callers, increasing leakage and attack surface.
+
+### Put all machines and workspaces behind one tenant router immediately
+
+Rejected as unnecessary coupling. The existing per-workspace lifecycle is a useful security and operational boundary.
+
+### Share `full` among mutually untrusted accounts
+
+Rejected because `full` exposes local-user process, shell, browser, and filesystem authority. Application-level role checks cannot provide OS isolation.
+
+## Incremental delivery plan
+
+### Phase 0: make the boundary explicit
+
+- document current multi-client behavior and lack of account isolation;
+- recommend separate bridge/OS boundaries for different trust domains;
+- keep current behavior unchanged.
+
+### Phase 1: principal records and targeted revocation
+
+- add owner principal migration;
+- bind codes/tokens to principal and membership IDs;
+- add per-principal suspension and revocation version;
+- preserve one common grant initially;
+- add migration, expiry, quota, and revocation tests.
+
+### Phase 2: named grants and dual enforcement
+
+- derive grant capabilities from the shared policy contract;
+- advertise grant catalog revision/digest in the daemon handshake;
+- filter tool lists/calls in the Worker and recheck locally;
+- add stale-revision, reconnect, policy-narrowing, cancellation, and managed-job tests.
+
+### Phase 3: operator account lifecycle
+
+- add invitation, list, suspension, grant, and session-revocation CLI commands;
+- add owner-only persistence and administrative audit retention;
+- add concurrent and fault-injection tests for account mutations.
+
+### Phase 4: optional external identity
+
+- add passkey/WebAuthn or configured OIDC adapters only after the principal/grant model is stable;
+- keep single-owner password compatibility simple;
+- do not require a central SaaS account service.
+
+## Acceptance criteria for claiming multi-account support
+
+The project should not advertise isolated multi-account support until tests prove all of the following:
+
+- two principals can authorize through the same client and receive different grants;
+- one principal can use two clients without becoming two accounts;
+- revoking one principal leaves another principal's sessions valid;
+- narrowing the local policy immediately prevents a broader account grant from executing;
+- a stale grant revision fails in both Worker and daemon paths;
+- `tools/list` and `tools/call` enforce the same effective grant;
+- disconnect, daemon replacement, token expiry, and secret rotation converge safely;
+- account quotas cannot bypass global bounds;
+- managed jobs are attributed to a membership and have an explicit revocation/cancellation policy;
+- logs and public status do not expose personal identifiers or credentials;
+- different trust domains remain externally isolated when process/browser authority is available.
+
+Until those conditions are implemented, the accurate product statement is:
+
+> Machine Bridge supports multiple OAuth clients and tokens for one trusted workspace owner or trust domain. It does not yet provide isolated multi-user tenancy in one deployment.
+
+## Standards and implementation references
+
+- [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+- [OAuth 2.0 Security Best Current Practice (RFC 9700)](https://www.rfc-editor.org/rfc/rfc9700)
+- [OAuth 2.0 Authorization Server Issuer Identification (RFC 9207)](https://www.rfc-editor.org/rfc/rfc9207)
+- [OAuth 2.0 Resource Indicators (RFC 8707)](https://www.rfc-editor.org/rfc/rfc8707)
+- [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://www.rfc-editor.org/rfc/rfc9728)
+- [Cloudflare Durable Objects documentation](https://developers.cloudflare.com/durable-objects/)
+- [Security policy](../SECURITY.md)
+- [Architecture](ARCHITECTURE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",

package/src/worker/index.ts

@@ -17,7 +17,7 @@ import {
 } from "./http";
 
 const SERVER_NAME = String(serverMetadata.name);
-const SERVER_VERSION = "0.17.0";
+const SERVER_VERSION = "0.17.1";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";