machine-bridge-mcp 0.4.0 → 0.5.0

package/docs/LOGGING.md

@@ -0,0 +1,80 @@
+# Logging and observability
+
+## Goals
+
+Operational logs should answer four questions without becoming a transcript of user activity:
+
+1. Did deployment and relay connection succeed?
+2. Is the daemon reconnecting, superseded, or unhealthy?
+3. Did a tool call fail, time out, or become unusually slow?
+4. Which component and coarse error class should be investigated?
+
+Logs are not a command history, content audit trail, or substitute for MCP client approvals.
+
+## Levels
+
+The CLI accepts:
+
+```text
+--log-level error|warn|info|debug
+--quiet      # alias for error
+--verbose    # alias for debug
+```
+
+The default foreground level is `info`. Platform autostart services use `warn`.
+
+| Level | Intended events |
+|---|---|
+| `error` | Broken request handlers, relay transport errors, unrecoverable local failures |
+| `warn` | Failed tool calls, disconnections, malformed/oversized relay messages, superseded daemons |
+| `info` | Deployment/startup transitions, successful relay connection, successful calls slower than 30 seconds |
+| `debug` | Routine successful calls, shortened correlation IDs, reconnect timing, cancellation correlation |
+
+Routine successful calls are deliberately absent from `info`. A normal sequence of hundreds of tool invocations should not fill the user's terminal or service logs.
+
+## Event fields
+
+Default warning/error and slow-call events may include:
+
+- component;
+- tool name;
+- duration in milliseconds;
+- coarse error class;
+- relay close code;
+- bounded reconnect delay.
+
+Shortened random call identifiers are debug-only. They are useful only for correlating adjacent local events and are not stable audit identifiers.
+
+The implementation intentionally omits:
+
+- tool arguments;
+- command text or argv;
+- stdin, stdout, and stderr;
+- file, patch, or image content;
+- OAuth request bodies;
+- connection passwords, daemon secrets, authorization codes, and access tokens.
+
+Unexpected daemon and Worker failures are reduced to coarse error classes in normal logs. Client-facing tool errors may contain more detail according to the active path-display policy, but those details are not copied into normal operational logs.
+
+## Bounding and redaction
+
+Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters are neutralized. Fields with secret-like names and known token formats are recursively redacted.
+
+This is defense in depth, not content classification. A previously unknown secret format embedded in an ordinary non-secret-named field may evade pattern redaction. For that reason, tool arguments and outputs are omitted rather than merely filtered.
+
+## Files
+
+Autostart logs are stored below the state root:
+
+```text
+logs/daemon.out.log
+logs/daemon.err.log
+```
+
+They are owner-only where the platform supports Unix-style permissions. Existing files are tail-trimmed on UTF-8/line boundaries before daemon startup. Because background services use `warn`, normal successful tool traffic should not cause sustained log growth.
+
+## MCP host boundary
+
+Machine Bridge does not classify filenames as sensitive and does not block `.env`, password, key, or credential-looking names. The active local policy and operating-system permissions determine what the server itself can read.
+
+An MCP host, model provider, desktop application, or platform execution layer may independently deny a request involving credentials or sensitive files. Such a denial occurs before or outside Machine Bridge's file resolver and cannot be disabled by selecting the local `full` profile. Use `server_info`, `machine-mcp status`, and `machine-mcp doctor` to distinguish the active local policy from host-side enforcement.

package/docs/OPERATIONS.md

@@ -14,24 +14,20 @@ machine-mcp service status
 
 Remote autostart logs are stored under the state root in `logs/daemon.out.log` and `logs/daemon.err.log`. Files are owner-only where supported and tail-trimmed before daemon startup.
 
-Structured operational events may include:
+Logging is level-based:
 
-- component and severity;
-- tool name;
-- shortened random call identifier;
-- duration and success/failure;
-- coarse error class;
-- connection/reconnect status.
+```text
+error  unrecoverable local/transport failures
+warn   failed calls, disconnects, malformed relay events
+info   startup/deploy/connect transitions and calls slower than 30 seconds
+debug  routine successful calls, shortened correlation IDs, cancellation/reconnect details
+```
 
-They intentionally omit:
+Foreground mode defaults to `info`; autostart uses `warn`. Use `--verbose` or `--log-level debug` only for diagnosis. `--quiet` is an alias for `--log-level error`.
 
-- file contents and image data;
-- write, edit, or patch payloads;
-- command argv, shell text, stdin, stdout, and stderr;
-- MCP connection passwords, daemon secrets, authorization codes, and access tokens;
-- full request bodies.
+Normal logs intentionally omit tool arguments, file/patch/image content, command text and argv, stdin/stdout/stderr, OAuth request bodies, connection credentials, authorization codes, and tokens. Unexpected daemon and Worker failures use coarse error classes rather than raw exception messages. Messages and structured fields are bounded and secret-like fields/token formats are redacted.
 
-Unexpected Worker failures log endpoint path and error class rather than raw exception messages. Cloudflare observability is sampled and is not a complete audit log.
+See [LOGGING.md](LOGGING.md) for the event contract and MCP-host boundary. Cloudflare observability is sampled and is not a complete audit log.
 
 ## Reconnect and replacement
 
@@ -62,20 +58,32 @@ Defense-in-depth limits include:
 
 ## Upgrade behavior
 
-Version 0.4 changes the default for newly selected workspaces to `review`. Existing state retains its previous write and execution settings. To intentionally migrate an old profile:
+Version 0.5 records policy origin and revision. A state entry matching the exact legacy implicit-default shape—write enabled, shell enabled, workspace-confined paths, isolated environment, and relative output—is migrated once to the current `full` default. Explicit named profiles and identified custom policies are preserved.
+
+`full` enables writes, direct processes, process sessions, shell execution, unrestricted direct filesystem paths, absolute path output, and the complete parent environment. It does not override operating-system access controls or independent MCP-host/platform policy.
+
+Inspect effective policy with:
+
+```sh
+machine-mcp status
+machine-mcp doctor
+```
+
+Select a policy explicitly with:
 
 ```sh
+machine-mcp --workspace /path/to/project --profile full
 machine-mcp --workspace /path/to/project --profile agent
 ```
 
-A remote policy change is saved locally, propagated in the daemon handshake, and persisted in the autostart definition.
+A remote policy change is saved locally, propagated in the daemon handshake, and loaded by autostart from owner-only state.
 
 ## Incident response
 
 After suspected credential or client compromise:
 
 1. stop foreground and autostart daemons;
-2. run `machine-mcp rotate-secrets --no-print-credentials`;
+2. run `machine-mcp rotate-secrets`;
 3. restart without broad flags and redeploy;
 4. inspect Cloudflare account access, Worker configuration, local state permissions, and service logs;
 5. remove the Worker and local state if continued remote access is unnecessary.

package/docs/TESTING.md

@@ -24,8 +24,9 @@ The suite includes:
 - isolated command HOME/temp/cache behavior;
 - one-shot timeout, descendant termination, cancellation, and process-session interaction;
 - daemon/startup locking and state corruption recovery;
-- guarded state-root removal and legacy-state migration;
-- log redaction, control-character handling, and service-log trimming;
+- guarded state-root removal, schema migration, policy-origin persistence, and legacy implicit-default migration;
+- no filename-based sensitive-file denial under unrestricted policy;
+- log redaction, control-character handling, message/field bounds, default success-log suppression, and service warning-level configuration;
 - CLI parsing, policy profiles, and client configuration boundaries;
 - live stdio MCP initialization, discovery, calls, rich content, sessions, cancellation, and continued responsiveness;
 - live local Worker OAuth registration, consent, PKCE, token replay rejection, throttling, CORS, protocol negotiation, dynamic tool advertisement, rich content, daemon replacement, and cancellation.
@@ -34,12 +35,13 @@ The suite includes:
 
 ```sh
 npm run worker:dry-run
+npm audit --audit-level=high
 npm audit --omit=dev --audit-level=high
 npm pack --dry-run
 npm run version:check
 ```
 
-The repository includes `docs/examples/github-actions-ci.yml`, a ready-to-enable matrix for Linux, macOS, and Windows. Node 22 and 24 are covered on Linux; Node 22 is covered on macOS and Windows. It must be copied to `.github/workflows/ci.yml` with a GitHub credential authorized to modify workflow files. Dependency and GitHub Actions updates are monitored by Dependabot after activation.
+GitHub Actions executes the main suite on Linux, macOS, and Windows. Node 22 and 24 are covered on Linux; Node 22 is covered on macOS and Windows. A separate package-audit job audits both the complete dependency graph and the production-only graph, then performs a dry-run package build. Dependency and GitHub Actions updates are monitored by Dependabot.
 
 ## Test design rules
 
@@ -48,4 +50,5 @@ The repository includes `docs/examples/github-actions-ci.yml`, a ready-to-enable
 - Every bounded resource needs an over-limit test.
 - Every multi-stage mutation needs a no-partial-commit test.
 - Every remote call correlation change needs daemon replacement and cancellation coverage.
-- Logs and public metadata should be tested for absence of sensitive fields, not only presence of expected fields.
+- Logs and public metadata should be tested for absence of sensitive fields, arguments, outputs, and routine success noise—not only presence of expected fields.
+- Cross-platform tests must avoid shell syntax, URL-path conversion, and executable-shim assumptions specific to one operating system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cross-client MCP bridge for policy-controlled local files, Git, images, patches, and processes over stdio or OAuth-protected remote relay.",
   "type": "module",
   "license": "MIT",
@@ -50,12 +50,12 @@
     "catalog:test": "node tests/catalog-test.mjs"
   },
   "dependencies": {
-    "wrangler": "^4.110.0",
-    "ws": "^8.18.3"
+    "wrangler": "4.110.0",
+    "ws": "8.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "keywords": [
     "mcp",