Skip to content

Collapse tool profiles to observe and owner; browser belongs to owner #59

Closed

Description

@chaodu-agent

Status: approved by owner; implementation to follow as a separate PR.

Problem

The profile model has three accepted names (owner, desktop, observe) plus the refused legacy name sandbox, and the boundary between them is unclear.

The browser (@playwright/mcp) and the shell are both shell-equivalent. desktop blocks exec* and limits the browser to a 15-tool allowlist, but #45 and #46 established that it is still shell-equivalent through GUI control. The Oracle VM (PR #58) runs the browser under desktop, so the browser inherits the shell-equivalent trust level without an explicit decision. See also #45 (browser tier egress).

Decision (owner)

Two profiles only. The desktop profile is removed entirely.

  • observe: exactly sys_info and screenshot. No shell-class tool, no browser.
  • owner: the full local and upstream tool set, shell-equivalent. This includes the shell class and every browser_* tool.

The browser is owner-level, not isolated. This applies to the current browser, which uses this computer's persistent profile and network. It does not rule out the isolated browser tier planned in tool-profiles.md / #45. That tier can be added later as a new profile or a proxy, once it has a real boundary (throwaway profile, egress block, or separate VM).

desktop is not an alias of owner

desktop is no longer a profile. A desktop value, whether requested by an attach call or stored in a persisted grant, resolves to observe. It never resolves to owner. This fails closed.

Why map instead of refuse like sandbox (#46): sandbox was never a granted profile, so refusing it loses nothing. desktop grants exist in the wild and sit in persisted state. A hard refusal would fail every existing attach call and would leave stored rows that cannot be served. Mapping to observe keeps the attach working, widens nothing, and makes the change visible to the granter.

Why not owner: today desktop blocks every exec* tool and excludes browser_evaluate, browser_run_code_unsafe, upload/PDF, and network inspection (ToolProfile.swift:84-106). An alias to owner would grant all of these, including arbitrary JavaScript in the logged-in browser profile.

Default profile is observe

When an attach request has no profile, both daemons use observe. This is the single default for Swift and Linux. Today Swift defaults to desktop (MCPHTTPEndpoint.swift:115) and Linux defaults to owner (poc/reverse-attach-linux/src/http.rs, handle_attach). Both change to observe.

Migration (breaking change)

This is a breaking change for anyone who used desktop for the browser. After it lands, that browser access is gone until an owner grant is issued. Nothing in the migration issues owner.

  • Requested desktop: the attach call succeeds with effective profile observe. The response carries profile: observe, requested_profile: desktop, and a warning field. The daemon log and an audit log entry record the mapping too, but the log is not the only signal.
  • Stored desktop grant: on resume (daemon start) the row is kept, its effective profile is observe, and the row is not upgraded and not deleted. GET /attach (the attach list) and grant.json show profile: observe, requested_profile: desktop, and a warning, so the granter sees it the next time they look at the list.
  • Re-enabling shell or browser access requires an explicit owner grant from the person who holds the machine.
  • sandbox: unchanged from fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46. Persisted sandbox grants are still dropped on resume, and sandbox requests are still refused. Whether those drops should also keep the row and report it is not decided here.
  • Commit with !. The release note has a migration section that states the mapping above.
  • Open a client companion issue (as fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46 did). Clients stop sending desktop. Clients that want browser access request owner explicitly.
  • Use one rejection message on both platforms for unknown profiles: 400 profile must be one of [owner, observe].

Work

The list below comes from grep -rni desktop on a fresh clone of origin/main at f456d047823572acae7110447ad39f1f7f8dde6c. That gives 42 files. Each hit is first classified: a profile name changes, while a desktop-session or GUI wording stays unless it names the profile.

Swift core (Sources/InstanceMCPCore)

  • ToolProfile.swift (13 hits): remove case desktop and desktopBrowserTools. Keep ToolClass and localToolClass, because they enforce the observe boundary. owner includes all browser_* tools.
  • MCPHTTPEndpoint.swift (line 115): default profile observe. Map a requested desktop to observe with a warning. Reject other unknown values with the 400 message above.
  • AttachManager.swift (5 hits): resume keeps a persisted desktop row, resolves its effective profile to observe, and reports the warning. Remove desktopInstructions. sandbox handling is unchanged.
  • Switchboard.swift (2 hits, instructions()): remove desktop.
  • PermissionStatus.swift, Tools/OsascriptTool.swift, Tools/ScreenshotTool.swift (1 hit each): wording check, change only profile references.

Swift app (Sources/oab-instance-mcp)

  • main.swift (6 hits): --switchboard-profile help text and validation accept owner and observe only.
  • PermissionSetupWindowController.swift (2 hits), StatusItemController.swift (1 hit): remove desktop.

Swift tests (Tests/InstanceMCPCoreTests)

  • ProfileBoundaryTests.swift (12 hits), ReverseAttachTests.swift (11), SwitchboardTests.swift (6), UpstreamMCPTests.swift (5), GrantPersistenceTests.swift (3), ConformanceVectorTests.swift (1): update to two profiles and add the tests in the Tests section.

Linux (poc/reverse-attach-linux)

  • src/mcp.rs (17 hits): remove DESKTOP_BROWSER_TOOLS and every desktop branch in tool_list, profile_is_shell_equivalent, local_tool_allowed, upstream_tool_allowed, and handle_tool_call. Keep OBSERVE_TOOLS and the tool classification. Replace the hardcoded ["owner", "desktop", "observe"] list (mcp.rs:518) with a single source constant.
  • src/http.rs (line 579 message, handle_attach default): default observe, same mapping and 400 message as Swift.
  • src/attach/store.rs (1 hit, normalize_profile): a stored desktop row resolves to observe with a warning and is kept.
  • src/tools/input.rs (4), src/tools/screen.rs (1), src/tools/sysinfo.rs (1): wording check.
  • src/platform/desktop.rs (13), src/platform/mod.rs (5), src/platform/linux/seat.rs (12), src/platform/linux/wlroots.rs (13): desktop-session wording. Change only if a line names the profile.
  • smoke.sh (10 hits): add the desktop maps to observe with warning check, and update the other profile assertions.
  • pw-mcp.sh (1 hit), README.md (8 hits): two profiles.

Docs

  • README.md (17 hits), docs/tool-profiles.md (14 hits), docs/linux-setup.md (12 hits): two profiles, observe default, desktop mapped to observe.
  • docs/adr/reverse-attach.md (4), docs/adr/linux-rust-port.md (4): add an ADR entry for this decision and the alternatives below. Update the existing profile text.
  • docs/requirements/reverse-attach.md (1), docs/requirements/connect-closed-loop.md (1): two profiles.
  • docs/releasing.md (1): release note migration section.
  • poc/pw-mcp/README.md (1): browser runs under owner.

Scripts

  • scripts/install-linux.sh (8 hits), scripts/install-prebuilt.sh (1), scripts/pkg/postinstall (2), scripts/test-packaging.sh (2): default profile and profile wording.

Conformance (new vectors, see Tests)

  • conformance/profile_vectors.json (new), conformance/README.md (update the list of vectors).

Tests

Local tools (ProfileBoundaryTests and the Rust profile tests)

  • Every local tool is checked under observe and under owner. Under observe, only sys_info and screenshot are allowed. Under owner, every local tool is allowed. A new local tool with no classification fails the test.

Browser tools (new file, separate from ProfileBoundaryTests; Rust equivalent in the Linux test module)

  • Against an upstream fixture that lists the full browser_* tool set: under owner every tool is allowed, none is skipped. Under observe none is allowed.
  • A new upstream tool that is not in the fixture is denied under observe.
  • owner reaches bash and browser_* through the real tools/call path, not only through the allowlist function.

Call path

  • A tool hidden from the profile, called directly through tools/call, returns unknown tool (Swift scoped(to:), Linux handle_tool_call).

Grants and attach

  • A stored desktop grant resolves to observe, emits a warning, the row is kept, and GET /attach and grant.json report the effective and requested profile.
  • An attach request with desktop gets observe with a warning. It never gets owner.
  • An attach request with no profile gets observe.
  • Unknown names (browser, sandbox, OWNER) return the 400 message.

Shared conformance vectors (F6)

  • Add conformance/profile_vectors.json next to the existing auth_vectors.json and reverse_attach_vectors.json. Each vector has: input profile, accepted or rejected, effective profile, warning required, persisted-grant behavior, local tools, upstream tools, and shell-equivalent.
  • Swift runs it in ConformanceVectorTests, which the existing swift test --skip OsascriptToolTests step in ci.yml already runs on macOS.
  • Linux runs it in cargo test --release (ci.yml, "Unit + conformance tests"), with the same include pattern as auth.rs.
  • Edit a vector only when the change is intended on both sides.
  • The upstream fixture in the vector is the full browser tool list, so both platforms check the same set.
  • Known gap, not in scope: OsascriptToolTests is skipped in CI (ADR: sandbox adapter — backend-agnostic sandbox_* tools (OrbStack first; k3s / Lambda MicroVMs later) #1). The osascript path stays untested end to end.

Acceptance

On both macOS and Linux. Tools are grouped by class, not by name alone.

  • Observe class ({sys_info, screenshot}): observe serves exactly these two tools. It serves no shell-class tool and no upstream tool.
  • Shell class (macOS: exec, exec_start, osascript, key, mouse; Linux: bash, key, mouse; any future tool classified as shell): served only by owner. Under observe each one is hidden and returns unknown tool on a direct call.
  • Browser class (every browser_* upstream tool): served only by owner. Under observe each one is hidden and returns unknown tool on a direct call.
  • Unclassified tool: fails the test. A tool with no class is never served under observe.
  • owner serves the full local tool set and the full upstream tool set.
  • A requested desktop resolves to observe with a warning, and never widens to owner.
  • A stored desktop grant is kept on resume, resolves to observe, and is reported in GET /attach and grant.json.
  • Unknown names (for example browser, sandbox, OWNER) are rejected with 400 profile must be one of [owner, observe].
  • An attach request without a profile gets observe.
  • grant.json and GET /attach report the effective profile and the requested profile.
  • Shared conformance vectors pass on both platforms in CI.
  • Linux smoke test covers "desktop maps to observe with a warning".
  • macOS swift test and Linux cargo test (with conformance) and smoke are green in CI.

Ordering

  1. Implement and test this issue. It lands before PR docs: Oracle Cloud reference architecture for instance-mcp #58 is finalised.
  2. Update PR docs: Oracle Cloud reference architecture for instance-mcp #58 (Oracle VM refarch) to describe two profiles only: profile table, tool counts, attach examples. No desktop in the text.
  3. Merge PR docs: Oracle Cloud reference architecture for instance-mcp #58 only after this issue is done, so main never publishes deployment guidance that refers to desktop. If docs: Oracle Cloud reference architecture for instance-mcp #58 must merge first, mark it transitional and make this issue a hard gate for the same release.
  4. This decision covers only the current shared-profile browser. The isolated browser tier planned in tool-profiles.md / Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45 is not blocked. It can be added later as a new profile or as a proxy in front of the browser.

Alternatives considered

  • Alias desktop to owner with a warning. Rejected: silent widening of live and persisted grants.
  • Refuse desktop with a 400, like sandbox. Rejected: fails existing attach calls and leaves stored rows that cannot be served. Mapping to observe keeps the attach working and fails closed.
  • Alias with explicit client-side opt-in. Rejected: adds a consent flow to keep a name that is going away. An explicit owner grant gives the same consent with less code.
  • Keep desktop as a named preset (GUI plus restricted browser, no direct shell, no arbitrary JS). It reduces accidental misuse, but it keeps the three-name confusion this issue removes. Revisit as a custom policy if needed.
  • Build the isolated browser tier (Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45) first, then collapse. Not required: the collapse is reversible, and the isolated tier can be added later as a subset of owner or as a separate profile.

Related

Activity

  1. chaodu-agent commented on Oct 29, 2026

    @chaodu-agent
    ContributorAuthor

    Important

    CHANGES REQUESTED ⚠️ - Two profiles is the right model, but the Migration section would silently widen existing desktop grants to owner. The issue needs a decided migration contract and tighter acceptance criteria before implementation starts.

    What This Issue Proposes

    Collapse the tool profiles to observe (sys_info, screenshot) and owner (everything, including all browser_*), and remove desktop or turn it into an alias of owner. The goal is a profile model whose names match the real trust boundary: shell-equivalent or not.

    How It Would Work

    Findings

    # Severity Finding Location
    1 🔴 Work and Migration contradict each other, and the alias path reverses the sandbox precedent without a stated reason Issue body: Work, Migration
    2 🔴 desktop -> owner widens live and persisted grants, and a warning in the daemon log does not reach the granter ToolProfile.swift:84-106, AttachManager.resume, Linux store::load
    3 🔴 The default profile differs between platforms, and the issue does not define the new default MCPHTTPEndpoint.swift:115, http.rs:557
    4 🟡 Acceptance names tools (bash) and omits mouse, key, osascript, exec*. It should be stated by tool class Issue body: Acceptance
    5 🟡 "ProfileBoundaryTests covers every tool" only holds for local tools. Upstream browser_* and call-path behavior need their own tests ProfileBoundaryTests, mcp.rs tests
    6 🟡 Swift and Linux have no shared profile conformance vectors, so the two policies can drift CI conformance suite
    7 🟡 The Work list misses most of the code and docs that reference desktop About 40 files on main
    8 🟡 Breaking change with no release-note, ! commit, or client companion plan Issue body
    9 🟡 Ordering with PR #58 is unstated, and the wording could close off the planned isolated browser tier (#45) Issue body: Related
    10 🟢 Two profiles matches the real boundary. Putting the shared-profile browser in owner is the honest choice -
    Finding Details

    🔴 F1: Decide the migration contract

    Work says "remove desktop, or make it an alias of owner". Migration says desktop must map to owner with a warning. Only one of these can ship.

    The repository already made this decision once. #46/#48 changed sandbox from an alias to a hard refusal (ToolProfile.swift:24: "The old name sandbox is not accepted"). If desktop becomes an alias, the issue should explain why that reasoning does not apply here.

    Requested change: Choose one option and record the reason:

    • (a) Refuse desktop with a 400 like sandbox, and drop stored desktop grants. This is the recommended option.
    • (b) Accept desktop only as a transitional alias that requires explicit client-side consent (see F2).

    🔴 F2: Aliasing desktop to owner widens grants without consent

    Today desktop blocks every exec* tool (ToolProfile.swift:86). It allows only 15 browser tools, and the list explicitly excludes browser_evaluate, browser_run_code_unsafe, upload/PDF, and network inspection (ToolProfile.swift:96-106). Linux has the matching test desktop_never_gets_arbitrary_javascript.

    An alias would give existing desktop clients:

    • exec / exec_start (macOS) or bash (Linux);
    • arbitrary JavaScript in the persistent, logged-in browser profile;
    • file upload, PDF, and network inspection tools.

    The threat model already treats desktop as shell-equivalent, so this is not a new privilege class. It does remove the guard against accidental misuse that the allowlist provides.

    The persisted-grant path is the most serious case. Swift AttachManager.resume and Linux store::load both normalize the stored profile. Linux normalize_profile also feeds attach validation, local_tool_allowed, and upstream_tool_allowed, so changing that one function widens three paths at once. After a daemon upgrade and restart, a grant lent as desktop would come back as owner. A warning on stderr does not reach the person who granted it: POST /attach still returns success.

    Requested change: Handle new requests and stored grants separately. Stored desktop grants must be dropped and re-granted, never upgraded in the background. If option (b) from F1 is chosen, the attach response must return the effective profile (owner) and the requested value (desktop), show a warning the user can see, and write an audit log entry.

    🔴 F3: Define the default profile

    When the request has no profile, Swift POST /attach defaults to desktop (MCPHTTPEndpoint.swift:115) and Linux defaults to owner (http.rs:557). Once desktop is gone, the macOS default changes implicitly, and under an alias a bare attach would gain exec* and the full browser.

    Requested change: Set one explicit default on both platforms. observe is the fail-closed choice.

    🟡 F4: State Acceptance by tool class

    Acceptance says observe cannot reach bash or browser_*. bash is the Linux name. The macOS shell-class tools are exec, exec_start, osascript, key, and mouse. mouse and key are missing on both platforms.

    Requested change: Replace the wording with:

    • observe serves exactly {sys_info, screenshot} and no .shell-class tool, on both platforms;
    • owner serves the full local and upstream tool set;
    • a hidden tool called directly through tools/call returns unknown tool (Swift scoped(to:), Linux handle_tool_call);
    • unknown profiles (sandbox, Desktop, browser, and others) are still rejected and never widen;
    • grant.json and GET /attach report the effective profile, not the requested alias;
    • the behavior for desktop requests and for persisted desktop/sandbox grants is covered by tests.

    🟡 F5: Test coverage beyond local tools

    ProfileBoundaryTests and the Linux LOCAL_TOOL_CLASS checks cover local tools completely. Upstream browser_* tools are dynamic: the Linux served() helper excludes them, and the Swift browser test checks only a few hardcoded names.

    Requested change: Add tests against an upstream fixture: owner gets all of it, observe gets none of it, and an unknown new upstream tool is denied under observe. Keep the "unclassified tool fails" behavior. Replace the hardcoded ["owner", "desktop", "observe"] list in the Linux test (mcp.rs:518) with a single source constant, as Swift already does with allCases.

    🟡 F6: Shared conformance vectors

    CI runs swift test on macOS and cargo test plus conformance on Linux, but no shared vector defines profile -> tools. This change is a good time to add one, with fields for input profile, accepted/rejected, canonical profile, warning required, persisted-grant behavior, local tools, upstream tools, and shell-equivalence. Run it on both platforms, ideally with a mock upstream that serves the full browser tool list.

    Also note that OsascriptToolTests is skipped in CI (#1). The Swift profile boundary is covered, but the end-to-end osascript path is not.

    🟡 F7: Complete the Work list

    The Work list names ToolProfile.swift, three Linux symbols, ProfileBoundaryTests, and docs/linux-setup.md. About 40 files on main reference desktop, including:

    • Linux: normalize_profile, upstream_tool_allowed, DESKTOP_BROWSER_TOOLS, OBSERVE_TOOLS, handle_tool_call;
    • Swift: Switchboard.instructions(), AttachManager.desktopInstructions, --switchboard-profile help and validation in main.swift, PermissionSetupWindowController, StatusItemController;
    • tests (GrantPersistenceTests and others), scripts/install-*.sh, README, tool-profiles.md, ADRs, and docs/requirements/*.

    If desktop is refused, remove both browser allowlists rather than leaving dead code. Keep the ToolClass / LOCAL_TOOL_CLASS machinery, because it is what enforces the observe boundary.

    🟡 F8: Treat this as a breaking change

    Profile behavior changes for existing clients. Plan a ! commit, a release-note migration section, and a client companion issue, as #46 had with the client-side changes. Use the same rejection message on both platforms (for example profile must be one of [owner, observe]), and add a smoke test that checks desktop is rejected.

    🟡 F9: PR #58 ordering and #45

    PR #58 (Oracle VM docs) uses desktop throughout its profile table, tool counts, and attach examples. If it merges first, main will publish deployment guidance that is about to become wrong, and people follow these docs to decide what to grant.

    Requested change: Decide the #59 contract first, then update #58 to the two-profile model before it merges. If #58 must merge first, mark it as transitional and make #59 a hard gate for the same release. Also add one sentence saying this decision covers only the current shared-profile browser, and that the isolated browser tier planned in tool-profiles.md / #45 can still be added later as a subset of owner.

    🟢 F10: The core decision holds

    The privilege structure is binary: shell-equivalent or not. #45 showed that a browser using the shared persistent profile and the host network can reach localhost, the tailnet, file://, and logged-in services, so labeling it owner is honest. Collapsing profiles can be undone later. The migration semantics cannot, which is why F1-F3 block.

    Baseline Check
    Alternatives the issue should address

    The issue has no alternatives section. It should at least explain why it does not choose:

    1. Refusing desktop like sandbox (no alias).
    2. Keeping desktop as an explicitly named preset (GUI plus restricted browser, no direct shell, no arbitrary JS) on top of a two-level boundary. This fits the custom-policy item on the roadmap.
    3. Building the isolated browser tier from Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45 first, then collapsing.

    5. Three Reasons We Might Not Need This Change

    1. fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46 already fixed the security misunderstanding. desktop is already documented as shell-equivalent. What remains is mostly naming and maintenance cleanup, not a new boundary.
    2. desktop reduces accidents. A confused or weak agent cannot run a shell or browser_evaluate by mistake, because those tools are not listed. After the collapse, any grant above observe is full owner, so the usual lend gets more exposure.
    3. Client churn. Clients still send old profile values (as fix(profile): desktop (was sandbox) is shell-equivalent; add observe; document profiles #46 found). Another breaking rename before clients default to observe adds churn. Deprecating desktop in docs and deleting it later is a cheaper path, though it keeps the three-name confusion this issue wants to remove.
  2. chaodu-agent commented on Oct 29, 2026

    @chaodu-agent
    ContributorAuthor

    Revised the issue body. Point by point:

    • F1: Decision → "desktop is not an alias of owner" and Migration. Chose mapping desktop to observe (fail closed), with the reason for not refusing like sandbox.
    • F2: Migration → "Requested desktop" and "Stored desktop grant". The row is kept, the effective profile is observe, and GET /attach and grant.json show it. Re-enabling needs an explicit owner grant.
    • F3: Decision → "Default profile is observe" (one default for Swift and Linux, with both current defaults named).
    • F4: Acceptance → observe class, shell class, and browser class, each stated separately.
    • F5: Tests → "Browser tools" (own tests against an upstream fixture) and "Call path".
    • F6: Tests → "Shared conformance vectors": conformance/profile_vectors.json, run by swift test and cargo test in CI.
    • F7: Work → full list from a fresh clone of origin/main (42 files), grouped by area.
    • F8: Migration → breaking change, ! commit, release note, client companion issue, and the 400 message.
    • F9: Ordering → the issue lands before PR docs: Oracle Cloud reference architecture for instance-mcp #58 is finalised, and Planned restricted tiers (isolated browser, typed app control, custom policies, VM): acceptance criteria #45 stays possible later as a new profile or proxy.
    • F10: Decision → two profiles kept, and the browser stays in owner.
  3. added
    p2Priority 2: real bug or scoped planned work
    on Oct 30, 2026
  4. added a commit that references this issue on Nov 9, 2026
    7fdf8ff
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestp2Priority 2: real bug or scoped planned work

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions