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

package/docs/LOCAL_AUTHORIZATION.md

@@ -1,111 +1,154 @@
-# Local transaction authorization
+# Local authorization model
 
-Machine Bridge separates **available capability** from **current remote authority**.
+Machine Bridge treats **capability**, **identity**, and **object ownership** as separate controls. A tool is executable only when every control permits it.
 
-The canonical `full` profile still exposes the complete tool catalog, unrestricted local-user paths, shell execution, browser and application automation, managed jobs, absolute paths, and the complete parent environment. It remains the default for a trusted owner. Version 2.0 does not redefine or narrow that profile.
+For a remote request, effective authority is:
 
-An authenticated `owner` account activates the capabilities permitted by the daemon policy ceiling without a second terminal approval step. This preserves uninterrupted owner automation while retaining OAuth identity binding, account-version revocation, device authentication, and the daemon policy as hard boundaries.
-
-For delegated `reviewer`, `editor`, and `operator` accounts, the local daemon applies a final transaction gate after the Worker and local runtime have checked the account role and daemon policy. Ordinary project work remains automatic; an operation that crosses a consequential boundary requires a short-lived local capability lease.
-
-Local stdio calls are not affected by this remote transaction gate. They remain governed by the selected local policy and the MCP host's own approval model.
-
-## What remains automatic
-
-Remote calls do not require a lease for:
+```text
+daemon capability ceiling
+∩ authenticated account role
+∩ trusted OAuth client binding
+∩ current account version and refresh-token family
+∩ per-object ownership checks
+```
 
-- project discovery, status, diagnostics, ordinary metadata, and owner-configured Machine Bridge Agent guidance intended for MCP clients;
-- reads inside the selected workspace, except credential-sensitive paths;
-- ordinary source and configuration writes inside the selected workspace, excluding credential- and persistence-sensitive targets;
-- transactional patches whose source, destination, and move targets remain inside the selected workspace and outside sensitive targets;
-- Git inspection;
-- browser broker status without reading profile content;
-- installed-application discovery without inspecting an application UI;
-- registered-resource metadata inspection.
+No approval record, token refresh, client reconnect, or local command can expand the account role. A narrower layer always wins.
 
-This is the normal delegated-account coding and review path. A trusted owner is not interrupted by local approval prompts. For non-owner browser work, one reusable profile-session lease covers the session rather than prompting per page read, field, or click.
+Local stdio does not use remote OAuth accounts. It runs as the local owner under the selected local policy and remains subject to the MCP host and operating-system controls.
 
-## What requires a lease
+## Account roles
 
-The daemon requests local authorization for these remote effects:
+| Role | Effective purpose | Important limits |
+|---|---|---|
+| `reviewer` | Read-only inspection of the selected workspace | No mutation or process execution |
+| `editor` | Workspace reads and deterministic file mutation | No process execution |
+| `operator` | Workspace-confined editing and direct process execution | No unrestricted paths, credentials, browser/desktop control, or persistent job creation |
+| `owner` | Complete bridge authority within the daemon policy ceiling | Generic path-based tools cannot target Machine Bridge control-plane state; owner shell remains OS-user authority |
 
-| Scope | Examples |
-|---|---|
-| `shell` | shell commands, direct process launch, process output continuation, interactive process input or termination, registered local commands |
-| `external-read` | reading, searching, imaging, or inspecting a path outside the selected workspace |
-| `sensitive-read` | reading credential-sensitive locations or names such as SSH/AWS/Keychain state, `.env`, tokens, secrets, or private keys |
-| `external-write` | writing, editing, patching, or moving a patch target outside the selected workspace |
-| `sensitive-write` | writing credentials, live `.env` files, SSH/privilege files, shell startup files, Git hooks, LaunchAgents/LaunchDaemons, or other persistence-sensitive paths even when they are inside the selected workspace |
-| `browser-session` | listing or reading tabs, source, screenshots, waits, navigation, form input, clicks, submission, tab management, or extension pairing in the existing browser profile |
-| `data-export` | uploading a file, inserting a registered local resource into a browser or desktop application, or filling an explicitly sensitive browser field |
-| `persistent-job` | staging, starting, listing, reading output from, or cancelling a managed job |
-| `application-control` | opening, inspecting, or operating a desktop application |
-| `credential-operation` | generating an SSH key resource |
-| `full` | all of the above for one explicit temporary automation window |
+The daemon may advertise the complete catalog as its capability ceiling. The Worker filters `tools/list` by account role, and the local runtime independently recomputes and validates the same role boundary before dispatch.
 
-Classification uses canonicalized paths and bounded operation metadata. A single operation may require more than one scope: for example, a browser upload requires both `browser-session` and `data-export`, and an external credential read requires both `external-read` and `sensitive-read`. Existing leases may satisfy those scopes independently. A pending approval contains only the scopes still missing, and approving it creates one compound lease for those missing scopes. Pending records contain a SHA-256 target digest, not command text, file contents, form values, or uploaded bytes.
+## Trusted OAuth clients
 
-Write targets are canonicalized through their nearest existing ancestor even under `full`. A path that enters an in-workspace symbolic-link directory is classified by the real destination, while overwriting a final symbolic link is rejected. Patch `Move to` destinations are classified alongside add/update/delete paths. This preserves unrestricted-path capability without allowing path aliases to weaken the lease boundary.
+Dynamic OAuth registration creates an untrusted client record. The first successful account authorization binds that client to:
 
-The browser boundary is intentionally session-granular. The packaged extension controls whichever Chromium profile the user loaded it into; Machine Bridge cannot prove that the profile is isolated. Requiring one `browser-session` lease protects tab metadata and authenticated page content without degrading into per-click prompts. Once granted, ordinary browser reads, navigation, filling, and clicks proceed continuously until expiry. Exporting registered local data remains separately gated.
+- one account ID;
+- the account version at authorization time;
+- the account role;
+- the OAuth client ID.
 
-## Optional delegated-account approval flow
+A client cannot silently switch to another account. Account disablement, role changes, password rotation, client revocation, token-version rotation, and refresh-token replay invalidate the relevant credentials.
 
-Owner requests never create pending approval IDs. When a lease is missing for a non-owner account, the tool call fails with `local_approval_required` and a command containing a random pending approval ID. List pending requests and active leases locally:
+Inspect trusted clients locally:
 
 ```sh
-machine-mcp --workspace /path/to/project approval list
+machine-mcp account clients --workspace /path/to/project
 ```
 
-Approve only the requested scope for one hour:
+Revoke one client and all of its authorization codes, access tokens, and refresh tokens:
 
 ```sh
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --duration 1h
+machine-mcp account revoke-client CLIENT_ID --workspace /path/to/project
 ```
 
-Then retry the original task. Further matching operations from the same account and OAuth client run without interruption until the lease expires.
+Account-management requests are signed by a root-certified ephemeral device session. Machine Bridge does not deploy or retain a long-lived account-administration bearer or HMAC secret.
 
-For a trusted, intensive automation session, convert the same pending request into an explicit temporary `full` window:
+## Automatic execution
 
-```sh
-machine-mcp --workspace /path/to/project approval approve APPROVAL_ID --full
-```
+There is no per-operation approval prompt in the current runtime.
 
-`--full` defaults to eight hours and cannot exceed eight hours. It is local, account-bound, client-bound, time-bounded, and revocable. It does not change the saved policy profile or extend itself remotely.
+Within the effective role and daemon ceiling, calls execute automatically. Outside that intersection, calls fail immediately with `authorization_denied`; the response does not contain an approval ID or a command to retry.
 
-A specific scope can also be granted in advance. Account and OAuth client IDs are available from `approval list --json` after the client has produced a pending request. Wildcards are supported only when entered explicitly:
+Examples:
 
-```sh
-machine-mcp --workspace /path/to/project approval grant shell \
-  --account ACCOUNT_ID --client CLIENT_ID --duration 2h
-```
+- a reviewer may inspect files inside the selected workspace;
+- an editor may update ordinary workspace files;
+- an operator may run a workspace-confined process only when the delegated process sandbox is behaviorally verified;
+- an owner may use shell, unrestricted paths, browser/application automation, resources, and managed jobs when enabled by the daemon policy.
 
-## Revocation
+Risk classification still runs for every consequential request. It supplies structured audit metadata and enforces hard boundaries; it is not a mechanism for temporary privilege escalation.
 
-Revoke one lease:
+## Hard boundaries
 
-```sh
-machine-mcp --workspace /path/to/project approval revoke LEASE_ID
-```
+### Machine Bridge control plane
 
-Revoke every active remote capability lease for the workspace:
+Generic path-based file, image, search, and patch tools cannot target Machine Bridge state, device-root metadata, account-management state, audit-chain state, service metadata, or other protected roots. This applies to `owner` as well as delegated accounts.
 
-```sh
-machine-mcp --workspace /path/to/project approval clear
-```
+This is an application-level path boundary, not an arbitrary-code sandbox. An authorized `owner` shell or interpreter has the daemon OS user's ambient filesystem authority. Control-plane administration uses local CLI interfaces; mutually untrusted owner execution requires external OS isolation.
+
+### Sensitive and persistent targets
+
+Non-owner accounts cannot access credential- or persistence-sensitive targets, including live environment files, private keys, token stores, shell startup files, Git hooks, privilege configuration, LaunchAgents, LaunchDaemons, and equivalent persistence locations.
+
+Final symbolic-link overwrites are rejected. Existing ancestors and patch move destinations are canonicalized before classification so a workspace alias cannot conceal an external or sensitive destination.
+
+### Browser, desktop, and data export
+
+Only `owner` may control the existing browser profile or desktop applications, upload local files, or inject registered resources into an interactive session. Browser and application actions operate on the user's logged-in session and therefore are not delegated to lower roles.
+
+### Persistent jobs
 
-Stopping the daemon prevents execution while it is offline, but leases remain in owner-only state until expiry or explicit revocation. Incident response should therefore stop the daemon, clear leases, revoke or rotate affected OAuth credentials, and inspect account/client state.
+Only `owner` may create persistent execution plans with `start_job` or non-executing drafts with `stage_job`.
 
-## Binding and storage
+`stage_job` does not execute and is not an approval workflow. The removed `machine-mcp job approve` path cannot turn a draft into a running job. Execution requires a trusted owner request through `start_job`, or an explicit local `job submit` operation performed by the machine operator.
 
-Every lease binds:
+## Delegated process isolation
+
+An `operator` process is not accepted merely because its current directory and environment are restricted. Machine Bridge requires a behaviorally verified OS sandbox that:
+
+- exposes the selected workspace and an isolated runtime directory;
+- blocks the real user home and Machine Bridge state;
+- blocks Keychain and desktop automation access;
+- preserves the minimum system runtime needed by ordinary tools.
+
+The probe is fail-closed. The presence of a sandbox executable is not sufficient.
+
+On platforms where the negative security boundary cannot be verified, delegated process execution is unavailable. Owner execution remains governed by the selected daemon policy. For mutually untrusted workloads, use a separate OS account, container, or VM.
+
+Implementation-owned metadata probes are a separate boundary from delegated arbitrary execution. `project_overview` and the read-only Git tools use fixed argv selected by Machine Bridge, never a caller-provided executable or shell string. Those probes run with a minimal isolated environment, bounded output and deadlines, cancellation/process-tree tracking, and the request’s path-visibility rules. They do not grant `run_process`, registered-command, or shell authority to reviewer/editor accounts.
+
+## Object ownership
+
+Long-lived runtime objects bind to the principal that created them:
 
 - account ID;
+- account version;
 - OAuth client ID;
-- one or more explicitly approved scopes, or the standalone `full` scope;
-- creation and expiration times;
-- an optional source pending-approval ID.
+- refresh-token family ID.
+
+The binding applies to interactive processes, retained command-output sessions, and managed jobs. Another account, client, or refresh family cannot read, continue, send input to, cancel, or terminate those objects.
+
+## Device-root authorization
+
+The default root on every platform is a portable owner-only P-256 key. It signs the 24-hour ephemeral session certificate without Keychain access or a user-presence prompt. On macOS, `MBM_MACOS_TRUST_BROKER` may explicitly select a separately provisioned app-like broker; only after its code signature, Team ID, canonical non-symlink path with no group/other write access, and real Secure Enclave key probe validate does a non-exportable root replace the portable provider. That provider requests user presence once when signing the daemon session certificate. The private session key remains in memory and handles WebSocket preflight, challenge authentication, reconnects, and local account administration for that daemon lifetime.
+
+Expected interaction frequency:
+
+- ordinary tool calls: no local prompt;
+- portable-root daemon startup: no prompt;
+- provisioned Secure Enclave daemon startup: one user-presence prompt;
+- network reconnect: no prompt;
+- an independent account-management command: no prompt with a portable root, or one prompt with a provisioned Secure Enclave root;
+- root rotation: one explicit operation, with user presence only when the provisioned broker requires it.
+
+Every platform uses the portable P-256 provider unless an explicitly configured non-exportable platform provider has been installed and validated. `server_info.security.device_root` reports the active provider and whether the root key is exportable.
+
+## DPoP
+
+OAuth clients that support DPoP may bind access and refresh tokens to their own P-256 key. The Worker validates the proof method, URL, timestamp, nonce identifier, access-token hash, and key thumbprint. A copied token is insufficient without the client private key.
+
+Bearer remains available for MCP hosts that do not implement DPoP. Client trust, account versioning, refresh-family rotation, and role ceilings still apply.
+
+## Audit and incident response
+
+The local security audit is a bounded SHA-256 hash chain. It records operation class, outcome, duration, byte counts, target digest, and salted principal references. It does not record command text, file paths, file contents, form values, or tool output.
+
+For incident response:
 
-Normal scopes may last at most twelve hours. `full` may last at most eight hours. Pending requests expire after ten minutes. Lease and pending files are size-bounded, owner-only, atomically replaced, schema-validated, and validated record by record. Daemon-created pending requests and separate CLI approval/revocation processes serialize mutations through an owner-only process-identity lock, preventing lost updates during concurrent use. Malformed state or lock metadata fails closed.
+1. stop the daemon;
+2. revoke the affected OAuth client or disable the account;
+3. rotate the account password or global token version when appropriate;
+4. rotate the device root when device identity may be compromised;
+5. inspect the audit-chain health and local endpoint logs;
+6. restart and reconnect only trusted clients.
 
-This is an application-level control, not an OS sandbox. A process already running as the same OS user can interfere with local files and memory. Use a separate OS account, VM, or container when the client, repository, or instructions are mutually untrusted.
+Legacy capability-lease files from version 2 may still be listed, revoked, or cleared by the local CLI for migration cleanup. The version 3 runtime never consumes them and never creates pending approval IDs.

package/docs/LOGGING.md

@@ -12,7 +12,7 @@ Logs should answer:
 4. Is an infrastructure, protocol, deployment, or local service problem requiring action?
 5. When debug logging is explicitly enabled, which bounded implementation event should be correlated?
 
-Logs are not a command history or content audit trail. Local capability-lease state provides authorization evidence without recording command text or content, but it is not a tamper-proof forensic ledger and is not a substitute for OS isolation.
+Logs are not a command history or content transcript. The local security audit provides a bounded SHA-256 hash chain over coarse operation metadata without recording command text, paths, contents, form values, or output. It detects local alteration but is not a remote immutable ledger and is not a substitute for OS isolation.
 
 ## Levels
 
@@ -25,6 +25,7 @@ The CLI accepts:
 ```
 
 Foreground mode defaults to `info` and human-readable text. Platform autostart services use `warn` with newline-delimited JSON. Foreground operators can select JSON explicitly with `--log-format json`.
+In JSON mode, every logger entry point—including direct level methods and the persistent daemon-ready transition—emits exactly one timestamped JSON object per line. No operational method may silently fall back to the human formatter.
 
 Human mode treats the message as the primary interface: it uses a natural-language explanation and includes only bounded diagnostic fields that add meaning. It does not repeat the machine event key. JSON mode retains the stable `event` field for ingestion and correlation. Event identifiers such as `relay.tool_result.discarded` are implementation contracts for structured logs, not text that should be shown as the warning itself.
 
@@ -93,7 +94,7 @@ The implementation omits:
 - stdin, stdout, and stderr;
 - file, patch, image, and temporary-file content;
 - OAuth request bodies;
-- account passwords, account-administration HMAC keys/signatures, daemon device private keys/signatures, authorization codes, access tokens, refresh tokens, and capability-lease target material;
+- account passwords, root/session signatures, device private keys, authorization codes, access tokens, refresh tokens, DPoP proofs, and legacy-lease target material;
 - registered resource values and source paths;
 - browser pairing tokens, page URLs/source, DOM metadata, form values, uploaded file bytes, and screenshots;
 - application names, Accessibility trees, selectors, and entered values;
@@ -136,9 +137,17 @@ The log format has an explicit schema marker. If the marker differs from the cur
 
 Each managed job has owner-only runner diagnostic logs. Child-step output is retained only in bounded, redacted job results according to `capture_output`; it is not copied into daemon or runner operational logs.
 
+## Relay outage records
+
+`network_route` describes only Machine Bridge's application-level proxy decision. `system-network-stack` does **not** mean a direct physical path: an operating-system VPN, TUN, packet tunnel, DNS interceptor, or endpoint-security product may still carry the connection. `network_route_scope` therefore remains `application-proxy-selection-only`.
+
+During an outage, `server_info.runtime.relay` and `diagnose_runtime` expose bounded operational fields: outage count/start/duration, last close category/code, coarse transport error class, last disconnect/ready time, prior ready duration, and next retry timing. `relay.outage.active` and `relay.outage.recovered` carry the same safe fields. Raw WebSocket close reasons, IP addresses, proxy endpoints/credentials, DNS answers, tool arguments, and results are not promoted to default logs.
+
+Schema 4 is strict NDJSON. Before daemon startup, both active log files are opened as owner-only regular single-link files. A schema change clears both only after validation and commits the marker only after the transition succeeds. A symlink, multiple-hard-link inode, permission error, or marker-write failure blocks startup rather than mixing formats or repeatedly erasing evidence.
+
 ## MCP host boundary
 
-Canonical `full` does not remove tools based on filenames. For remote execution, the transaction classifier treats credential-sensitive path segments and basenames as a lease boundary while preserving the underlying capability. An MCP host, connector, model provider, desktop application, operating system, or endpoint-security layer may independently reject a request before it reaches Machine Bridge.
+Canonical `full` does not remove tools based on filenames. For remote execution, the operation classifier treats credential-sensitive paths and persistence targets as hard authorization boundaries: delegated roles are denied, while owner requests remain risk-classified and audited. An MCP host, connector, model provider, desktop application, operating system, or endpoint-security layer may independently reject a request before it reaches Machine Bridge.
 
 Use `server_info`, `project_overview`, `machine-mcp status`, `machine-mcp doctor`, and `diagnose_runtime` to distinguish local policy from host-side enforcement. Capability-routing status is returned on demand rather than written as task logs; it stores a runtime-keyed task fingerprint, not raw task text. Changing the Machine Bridge profile cannot override another layer.
 

package/docs/MANAGED_JOBS.md

@@ -113,6 +113,14 @@ Environment injection is convenient but may expose a value to same-user process
 
 At job acceptance, referenced resources are reopened, bounded, hashed, and recorded in the owner-only active plan. The runner reopens and verifies the hash before copying. A changed resource causes the job to fail rather than silently using different content.
 
+## Terminal persistence and sensitive-plan cleanup
+
+A job terminal transition is not a single best-effort write. The runner first attempts the bounded `result.json`, then persists a conservative terminal `status.json` with cleanup pending, then removes the private runtime directory, active plan, PID claim, cancellation marker, and transition/recovery artifacts, and finally confirms cleanup state. A result-write failure is visible as `result_persisted=false`; a status-write failure leaves every recovery artifact intact. Artifact removal failures remain visible as `artifact_cleanup_pending` and are retried by later read/list/prune operations.
+
+If the runner writes a valid terminal result but exits before terminal status is committed, the manager reconstructs status from that result before considering recovery. This prevents a completed finally sequence from being replayed merely because the status write was interrupted. If no valid terminal result exists, recovery may still repeat finally work, so finally steps must remain idempotent.
+
+Unexecuted staged plans can contain stdin, environment values, and temporary scripts. They expire after 24 hours and are converted to a non-executing terminal record; ordinary completed-job metadata may remain under the separate seven-day retention policy. A minimal-environment plan also launches its detached runner with a minimal control environment. Full parent-environment inheritance occurs only when the accepted plan explicitly captured that policy.
+
 ## Job-scoped temporary files
 
 Do not create ad hoc helpers in the workspace when the file exists only for one operation. Include it in the job:
@@ -191,35 +199,26 @@ Finally steps are attempted after success, failure, timeout, or cancellation. Ca
 
 Automatic dead-runner recovery is attempted at most three times; persistent failure becomes `recovery_exhausted` to avoid an endless restart loop. Cleanup is best effort, not mathematically guaranteed. Power loss, disk failure, permanent account loss, or a local security product that denies the cleanup executable can still prevent it. Finally steps should therefore be idempotent and safe to run more than once.
 
-## Two-phase local approval
+## Non-executing staged drafts
 
-If the MCP host rejects execution-class tools but still allows state changes, use:
+`stage_job` performs the same schema, cwd, resource, size, and permission validation as `start_job`, but records status `staged` and launches no process.
 
-```text
-stage_job
-```
+A staged record is a review artifact, not an authorization request:
 
-This performs the same schema, cwd, resource, size, and permission validation as `start_job`, but records status `staged` and launches no process. The response includes the local approval command:
+- it contains no executable approval token;
+- it cannot be promoted by `machine-mcp job approve`;
+- no main or finally step runs;
+- no registered resource is copied into a runtime directory;
+- cancellation produces `cancelled_before_start` and removes the plan.
 
-```sh
-machine-mcp job inspect JOB_ID
-machine-mcp job approve JOB_ID
-# or after a separate review, non-interactively:
-machine-mcp job approve JOB_ID --yes
-```
-
-`job inspect` displays the reviewable plan, including argv, ordinary environment overrides, stdin, temporary helper content, and finally steps, while omitting registered resource source paths and per-resource hashes. The overall `plan_sha256` is displayed for review and is revalidated atomically during approval and again by the runner before execution. A modified staged plan is rejected.
+Use `machine-mcp job inspect JOB_ID` to review the stored plan. The projection includes argv, ordinary environment overrides, stdin, temporary helper content, and finally steps while omitting registered resource source paths and per-resource hashes. The overall `plan_sha256` is displayed and remains integrity-checked.
 
-Local approval is a new operator authorization. It intentionally does not depend on the current MCP execution profile: a plan staged under a write-capable profile can be reviewed and approved from the terminal even when the connector is not allowed to execute. The plan retains the filesystem scope and environment mode captured when it was staged.
+Execution requires a separate authority-bearing action:
 
-Before approval:
+- a trusted owner submits the plan through `start_job`; or
+- the local machine operator submits a reviewed JSON plan with `machine-mcp job submit PLAN.json`.
 
-- no main step runs;
-- no finally step runs;
-- no resource is copied into a runtime directory;
-- cancelling produces `cancelled_before_start` and deletes the plan.
-
-Staged plans count toward the 50-item retention limit and expire with the seven-day job retention policy. They are not considered active processes and do not independently block uninstall after the normal uninstall confirmation.
+The current runtime does not implement copy-an-ID, approve, and retry workflows. Staged drafts count toward the 50-item retention limit and expire with the seven-day retention policy. They are not active processes and do not independently block uninstall after normal confirmation.
 
 ## Submit and inspect
 
@@ -233,21 +232,17 @@ read_job
 cancel_job
 ```
 
-From the local terminal, including after an MCP host blocks further execution calls:
+From the local terminal:
 
 ```sh
 machine-mcp job list
 machine-mcp job inspect JOB_ID
-machine-mcp job approve JOB_ID [--yes]
 machine-mcp job cancel JOB_ID
-```
-
-A local JSON fallback is also available:
-
-```sh
 machine-mcp job submit plan.json
 ```
 
+`job submit` is an explicit local operator action; it does not consume or promote a staged MCP draft.
+
 The plan format is the same object accepted by `start_job`.
 
 ## Output and secret handling

package/docs/MULTI_ACCOUNT.md

@@ -2,30 +2,34 @@
 
 ## What isolation means
 
-Machine Bridge remote mode supports several named accounts on one workspace Worker. Each account has an independent password, role, active state, version, OAuth authorization codes, access tokens, and refresh tokens. Account changes revoke only that account's outstanding credentials.
+Remote mode supports several named accounts on one workspace Worker. Each account has an independent password verifier, role, active state, version, authorization codes, access tokens, and refresh-token families.
 
-This is application-level authorization, not operating-system isolation. All accounts ultimately reach one local daemon running as one OS user. Roles limit which Machine Bridge tools can be listed and invoked; they do not create separate filesystems, browser profiles, process namespaces, keychains, network identities, or kernel security boundaries.
+This is application-level authorization, not operating-system multi-tenancy. All accounts ultimately reach one daemon running as one OS user. Roles do not create separate filesystems, browser profiles, process namespaces, Keychains, network identities, or kernel boundaries.
 
-Use separate OS accounts, containers, VMs, state roots, Workers, and workspaces when users are mutually untrusted or require hard isolation.
+Use separate OS accounts, containers, VMs, state roots, Workers, and workspaces when users are mutually untrusted or require hard tenant isolation.
 
 ## Roles
 
-| Role | Effective local profile | Typical use |
+| Role | Effective local profile | Purpose |
 |---|---|---|
-| `reviewer` | `review` | Read-only workspace, Git, image, resource, and job inspection |
-| `editor` | `edit` | Reviewer access plus deterministic file mutation |
-| `operator` | `agent` | Editor access plus workspace-confined direct process execution and sessions |
-| `owner` | `full` | Complete capability ceiling; high-impact remote transactions additionally consume a local account/client-bound lease |
+| `reviewer` | `review` | Read-only selected-workspace inspection |
+| `editor` | `edit` | Reviewer access plus deterministic workspace file mutation |
+| `operator` | `agent` | Editor access plus behaviorally sandboxed workspace-confined direct execution |
+| `owner` | `full` | Complete bridge authority within the daemon capability ceiling |
 
-The effective tool set is the intersection of:
+Effective authority is the intersection of:
 
-1. the account role;
-2. the policy advertised by the connected local daemon;
-3. the tools actually available from that daemon.
+1. the daemon policy and available tools;
+2. the account role;
+3. the trusted OAuth client binding;
+4. the current account version and refresh-token family;
+5. ownership of any long-lived process, output session, or job.
 
-For execution, a fourth local layer distinguishes trusted owner automation from delegated access. An authenticated owner may use the daemon policy ceiling directly. A high-impact call from a reviewer, editor, or operator must also match an active capability lease bound to its `account_id` and OAuth `client_id`. This transaction layer does not remove tools from canonical `full`; it preserves least privilege for delegated credentials without interrupting the owner workflow. The Worker filters `tools/list` and rejects unauthorized calls before relay. Every accepted relay call carries `account_id`, `account_version`, `client_id`, and `role`; the local runtime validates them again before dispatch. See [LOCAL_AUTHORIZATION.md](LOCAL_AUTHORIZATION.md).
+There is no temporary elevation path. A `reviewer`, `editor`, or `operator` cannot acquire `owner` capability through a local lease, approval ID, token refresh, or reconnect.
 
-Authenticated `server_info` deliberately reports both layers. `authorization.effective_policy` and `authorization.effective_tools` are authoritative for the current account. The nested `daemon.policy` and `daemon.tools` fields are only the local capability ceiling before account-role filtering; a `full` daemon does not make an `editor` account full. Remote `project_overview` uses the effective values at top-level `policy` and `tools` and preserves the daemon values as `daemonPolicy` and `daemonTools`.
+The Worker filters `tools/list` and rejects unauthorized calls before relay. Every accepted call carries account ID, account version, OAuth client ID, refresh-family ID, and role. The local runtime validates those values again before dispatch.
+
+Authenticated `server_info.authorization.effective_policy` and `effective_tools` describe the current account. `daemon.policy` and `daemon.tools` describe only the local capability ceiling; a `full` daemon does not make an `editor` account full.
 
 ## Account lifecycle
 
@@ -35,7 +39,7 @@ List accounts:
 machine-mcp account list
 ```
 
-Create an account. The generated password is displayed once and is not stored locally:
+Create an account. The generated password is displayed once:
 
 ```sh
 machine-mcp account add alice reviewer
@@ -50,28 +54,50 @@ machine-mcp account disable build-bot
 machine-mcp account enable build-bot
 ```
 
-Rotate one account's password:
+Rotate a password or remove an account:
 
 ```sh
 machine-mcp account rotate-password alice
+machine-mcp account remove alice --yes
 ```
 
-Remove an account:
+The final active owner cannot be disabled, demoted, or removed.
+
+Account disablement, role changes, password rotation, and removal revoke that account's credentials by changing or deleting its account version.
+
+## Trusted OAuth clients
+
+An OAuth `client_id` identifies client software and redirect URIs. Registration alone has no authority.
+
+The first successful account authorization binds the client to:
+
+- account ID;
+- account version;
+- role;
+- authorization time.
+
+A client cannot later authorize as a different account without first being revoked and registered again. This prevents one public client record from becoming a silent cross-account identity switch.
+
+List clients:
 
 ```sh
-machine-mcp account remove alice
-machine-mcp account remove alice --yes
+machine-mcp account clients
 ```
 
-The final active owner cannot be disabled, demoted, or removed. This prevents an accidental administrative lockout.
+Revoke one client and all of its codes, access tokens, and refresh tokens:
+
+```sh
+machine-mcp account revoke-client CLIENT_ID
+machine-mcp account revoke-client CLIENT_ID --yes
+```
 
-## OAuth model
+One account may still authorize several distinct client records. Each record is independently visible and revocable.
 
-An OAuth `client_id` identifies client software and its registered redirect URIs. It is not an account. One OAuth client may be authorized by several Machine Bridge accounts, and one account may authorize several OAuth clients.
+## OAuth tokens
 
-An authorization code records:
+Authorization codes bind:
 
-- OAuth client ID;
+- client ID;
 - account ID and account version;
 - role;
 - redirect URI;
@@ -79,33 +105,68 @@ An authorization code records:
 - scope and protected resource;
 - expiration.
 
-An access-token record contains the same account binding plus the deployment-wide token version and refresh-family identity. Token values are stored only as SHA-256 lookup keys. Access tokens last fifteen minutes. Refresh tokens rotate on every use, have a fourteen-day idle limit and thirty-day family limit, and leave a bounded consumed-token marker; replay of a consumed token revokes every remaining refresh and access token in that family. Account passwords are CLI-generated 256-bit tokens. The Worker stores independent salted HMAC-SHA-256 verifiers and rejects arbitrary human-chosen passwords; the token entropy, rather than a CPU-intensive dictionary-hardening loop, provides offline-guessing resistance within the Worker CPU budget.
+Access and refresh tokens additionally bind to the deployment token version and refresh-family ID. Token values are stored as SHA-256 lookup keys.
+
+Access tokens last fifteen minutes. Refresh tokens rotate on every use, have a fourteen-day idle limit and thirty-day family limit, and leave bounded replay markers. Reuse of a consumed refresh token revokes the complete family, including active access tokens.
 
-At each authenticated request, the Worker verifies that the account still exists, is active, and has the same version and role recorded in the token. A password rotation, role change, suspension, or removal increments or removes that account state and invalidates only its codes and tokens.
+A refresh request also verifies that the client remains bound to the current account version and role.
 
-`machine-mcp rotate-secrets` is intentionally broader. It rotates the account-administration HMAC key, daemon device identity, and deployment-wide token version, invalidating every account token, requiring all clients to authorize again, and requiring the matching Worker/daemon deployment to converge.
+### DPoP
+
+A capable client may bind the token family to a P-256 DPoP key. The Worker verifies the proof and requires the same key thumbprint for refresh. A copied token cannot be used without the client private key.
+
+Bearer remains available for hosts that do not implement DPoP.
+
+## Object ownership
+
+Interactive processes, retained output sessions, and managed jobs bind to:
+
+- account ID;
+- account version;
+- OAuth client ID;
+- refresh-token family ID.
+
+A different account, client, or token family cannot inspect, continue, send input to, cancel, or terminate the object.
+
+This binding prevents horizontal control between two clients authorized for the same account as well as between different accounts.
 
 ## Administrative boundary
 
-Account administration is not exposed as an MCP tool. It uses an owner-only local HMAC key to sign each CLI request over method, path, body SHA-256, timestamp, and random nonce. The key is stored only in owner-protected local state and Cloudflare Worker secrets and is never transmitted as a network bearer. The Worker consumes each nonce once through bounded Durable Object transaction state and rejects replay or malformed state. The key is never printed by `status`, sent through MCP, or used as an account password.
+Account and client administration is not exposed as an MCP tool and does not use a long-lived administration secret.
 
-The first start of a new deployment creates an `owner` account automatically and prints its generated password once. Subsequent starts do not display account passwords.
+The local CLI creates a root-certified ephemeral P-256 session. Each request signs the Worker origin, HTTP method, path, body hash, session key ID, timestamp, and nonce. The Worker verifies the root certificate, session signature, body, timestamp, and nonce replay state.
+
+The default root is portable owner-only P-256 material, including on macOS, so independent account commands do not normally prompt. When a separately provisioned broker has explicitly enrolled a Secure Enclave root, an independent account command may request user presence once. During normal daemon startup, the same in-memory session is reused for initial owner creation and relay authentication.
+
+The first start of a new deployment creates an owner account automatically and prints its generated password once. Subsequent starts do not display passwords.
+
+## Delegated execution
+
+`operator` direct execution requires a behaviorally verified OS sandbox. The sandbox must expose the selected workspace while denying the real user home, Machine Bridge state, Keychain, and desktop automation.
+
+When the platform cannot prove that boundary, operator process execution is unavailable. The runtime does not fall back to a path blacklist that only appears isolated.
+
+Browser/application control, local data export, credential operations, persistent job creation, sensitive targets, and unrestricted paths remain owner-only.
 
 ## Concurrency and revocation
 
-Pending calls remain bound to the OAuth access token and JSON-RPC request ID. Duplicate in-flight IDs under one token are rejected. Account revocation blocks new requests immediately; calls already relayed remain subject to ordinary cancellation, deadlines, local role validation, and the bounded same-daemon reconnect state machine. A replacement process cannot inherit a detached call.
+MCP sessions provide a request-ID namespace and cancellation boundary. Pending calls are bound to the authenticated token and session.
 
-A relay interruption keeps ordinary relay-owned calls alive only inside the bounded same-daemon reconnect window. Reconciliation or grace expiry cancels calls that no longer have a remote receiver and terminates their child process trees. Process promises settle on cancellation even when a child does not emit `close`; process ownership remains tracked until actual exit.
+A brief relay interruption preserves an ordinary call only within the same-daemon reconnect grace period. Reconciliation or expiry cancels calls without a receiver and terminates their child process trees. A replacement daemon process cannot claim a detached call.
+
+Revoking an account, client, or refresh family blocks new requests immediately. Already-relayed work remains subject to local ownership, cancellation, timeout, daemon lifecycle, and process cleanup.
 
 ## Audit and privacy
 
-Operational metrics identify tools and stable error classes, not account passwords, bearer tokens, arguments, command text, file content, or results. `server_info` may return the authenticated account ID, role, and version to that account so the client can verify its authorization context.
+Operational logs and the local security audit do not contain account passwords, tokens, command text, file content, form values, or results.
+
+The audit chain records salted principal references, so repeated activity can be correlated locally without storing raw account/client identifiers in each entry. `server_info` may return the current authenticated account ID, role, and version to that account.
 
-Account names and display names are operator-selected metadata. Do not use secrets, email addresses, customer identifiers, or other unnecessary personal data in account names.
+Do not use secrets, email addresses, customer identifiers, or unnecessary personal data in account names and display names.
 
 ## Deployment topology
 
-One workspace normally maps to one Worker name, one Durable Object instance, one local state profile, and one active daemon. Multiple accounts share this topology and its OS trust boundary.
+One workspace normally maps to one Worker, one Durable Object instance, one local profile, and one active daemon. Accounts share that topology and OS trust boundary.
 
 Use a separate deployment when any of these differ:
 
@@ -116,10 +177,10 @@ Use a separate deployment when any of these differ:
 - billing or incident-response boundary;
 - requirement for hard tenant isolation.
 
-Do not place several unrelated machines or mutually untrusted teams behind one broad owner deployment merely to reduce administration.
+Do not place unrelated machines or mutually untrusted teams behind one broad owner deployment merely to reduce administration.
 
 ## Security limits
 
-A `reviewer` cannot invoke mutation or process tools through Machine Bridge, but data readable by the local OS user may still be exposed by a bug, compromised dependency, or incorrectly broad workspace. An `operator` can run interpreters, package managers, compilers, and repository scripts; direct argv execution therefore remains powerful even without a shell. An `owner` has effectively the authority of the local OS user and any browser or Accessibility permissions granted to the runtime.
+A reviewer is restricted by Machine Bridge, but a bug or compromised dependency remains possible. An operator can execute interpreters and repository code inside the verified sandbox and can still damage the selected workspace. An owner has effectively the authority of the local OS user and granted browser or Accessibility permissions.
 
-Roles are useful defense in depth and targeted revocation. They are not substitutes for least-privilege OS design, sandboxing, endpoint security, Cloudflare account protection, or careful review of untrusted repositories and instructions.
+Roles, client binding, DPoP, object ownership, and targeted revocation are defense in depth. They do not replace least-privilege OS design, endpoint security, Cloudflare account protection, and careful review of untrusted repositories and instructions.