Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(install): enable MCP exec + document stable Cloudflare tunnel defaults

Rahman63321a98ed94
diff --git a/.env.example b/.env.example
index 07324b44..30914cea 100644
--- a/.env.example
+++ b/.env.example
@@ -119,7 +119,10 @@ OS_SESSION_SECRET=
# HERMES_HOME=/home/you/.hermes
# Public origin the BROWSER uses, e.g. https://mso.example.com. Only the scheme
-# + host + port are read. The managed-app proxy scopes its Content-Security-Policy
+# + host + port are read. Set this only to the deployment's stable HTTPS hostname
+# (normally with `mso gateway domain set https://mso.example.com`). Never use a
+# random *.trycloudflare.com Quick Tunnel URL as OS_PUBLIC_ORIGIN.
+# The managed-app proxy scopes its Content-Security-Policy
# to this origin; without it the origin is inferred from the Host header and then
# from X-Forwarded-Host, and the latter is client-settable — set this whenever the
# app sits behind a reverse proxy so the policy can't be steered by a request.
@@ -311,13 +314,15 @@ OS_SESSION_SECRET=
# NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=
# ── MCP server (control this VPS from ChatGPT / Claude.ai / Cursor) ──────────
-# OFF by default. While unset, /mcp and the OAuth discovery documents return 404 —
-# there is no MCP surface at all, not an unauthenticated one.
-# OS_MCP_ENABLED=1
-# Highest tier the consent screen may grant. read | write | exec. Default: exec,
-# and the consent screen preselects that highest allowed tier. Set read or write to
-# opt down. `exec` means a leaked bearer runs any command on this box as you.
-# OS_MCP_MAX_SCOPE=exec
+# Fresh installs enable the OAuth-protected MCP surface by default. /mcp still
+# requires explicit OAuth consent and a bearer; this does NOT make host tools public.
+OS_MCP_ENABLED=1
+# Highest tier the consent screen may grant. read | write | exec. Fresh-install
+# default: exec, and consent preselects that highest allowed tier. Lower this to
+# read/write before connecting a client that does not need shell access.
+# SECURITY: an `exec` bearer is equivalent to remote command execution as the MSO
+# service user. Protect, rotate and revoke bearer credentials accordingly.
+OS_MCP_MAX_SCOPE=exec
# Where clients/codes/tokens live. Default ~/.mso/mcp.json (0600). Only sha256 of
# each code and token is ever written.
# OS_MCP_STORE=/home/you/.mso/mcp.json
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 7b04bcd9..aa577942 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -147,11 +147,11 @@ MSO uses Streamable HTTP JSON-RPC over `POST /mcp`.
## Setup / refresh sequence
-1. Deploy MSO over reachable HTTPS and enable MCP (`OS_MCP_ENABLED=1`).
-2. Set the maximum bearer scope intentionally with `OS_MCP_MAX_SCOPE=read|write|exec`.
+1. Deploy MSO over a stable reachable HTTPS origin. Fresh installs already write `OS_MCP_ENABLED=1`; existing installs preserve their current MCP setting during update.
+2. Set the maximum bearer scope intentionally with `OS_MCP_MAX_SCOPE=read|write|exec`. Fresh installs default to `exec`; lower it when a connector needs less privilege.
3. In ChatGPT Developer Mode / Apps, create or edit the MSO custom MCP app using the `/mcp` URL.
4. Choose OAuth and complete the MSO consent flow on an approved owner device.
-5. Select the lowest useful MSO tier.
+5. Select the lowest useful MSO tier. After changing `OS_MCP_MAX_SCOPE`, rebuild/restart MSO and repeat consent so the connector receives the new ceiling.
6. Run **Scan Tools / Refresh** in ChatGPT.
7. Verify that the action snapshot corresponds to the 66-tool transport profile (64 model-visible actions + app-only `workflow_status` and `render_mso_surface`) in the generated catalog.
8. Start a new chat when testing a newly scanned draft/action snapshot.
diff --git a/docs/INFRASTRUCTURE-PROVIDERS.md b/docs/INFRASTRUCTURE-PROVIDERS.md
index e41de592..e746b388 100644
--- a/docs/INFRASTRUCTURE-PROVIDERS.md
+++ b/docs/INFRASTRUCTURE-PROVIDERS.md
@@ -42,6 +42,17 @@ selects, and **Esc** cancels. Provider/model selection never falls back to a num
The connection choices are OpenAI ChatGPT/Codex device OAuth plus the built-in API-key providers documented in
[`INSTALL.md`](./INSTALL.md).
+Infrastructure secrets belong only in `mso provider set ...` hidden prompts/private provider state;
+do not commit them or paste real values into model prompts. Environment-shaped examples are placeholders
+for operator runbooks only:
+
+```dotenv
+HOSTINGER_API_TOKEN=<hostinger-api-token>
+CLOUDFLARE_API_TOKEN=<cloudflare-api-token>
+CLOUDFLARE_ACCOUNT_ID=<cloudflare-account-id>
+CLOUDFLARE_ZONE_ID=<cloudflare-zone-id>
+```
+
The terminal UI intentionally follows the useful *shape* of mature agent CLIs such as
Hermes — large identity banner, selected model, tool/skill/provider summary, then an
interactive prompt — but uses original MSO ASCII artwork and MSO's own tool/runtime stack.
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 3f548fa3..1042274c 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -51,7 +51,9 @@ The installer core:
self-update, validates every owned gateway fallback, quiesces an active service only when it belongs to
this checkout, then quiesces gateway-owned fallback runtimes while preserving their public tunnels;
5. installs Bun/dependencies as needed;
-6. creates private owner auth configuration when missing;
+6. creates private owner auth configuration when missing; a fresh `.env.local` also enables the
+ OAuth-protected MCP surface with `OS_MCP_ENABLED=1` and an `exec` consent ceiling, while an
+ existing `.env.local` is never rewritten during update;
7. runs the production build through `node node_modules/next/dist/bin/next build`, bypassing Bun's
package-bin remapper; if the Next package payload itself is absent, it performs one bounded
`bun install --force` repair before failing;
@@ -270,7 +272,7 @@ Do not add the random Quick Tunnel URL to `OS_PUBLIC_ORIGIN`: that variable is d
for stable MCP/share/CSP URLs. If a stable value is already configured, temporary mode leaves it
untouched and warns that generated links may continue to name the stable origin.
-### Stable custom domain / named Cloudflare Tunnel
+### Stable custom domain / named Cloudflare Tunnel (recommended public path)
```bash
mso gateway domain set https://mso.example.com
@@ -282,22 +284,43 @@ Cloudflare tunnel/DNS credentials using Cloudflare's official CLI, then start it
token on the command line:
```bash
-mso gateway start --config ~/.cloudflared/config.yml --tunnel mso
+mso gateway start --config ~/.cloudflared/config.yml --tunnel <tunnel-id-or-name>
+mso web
+```
If another gateway is already active, stop it first with `mso gateway stop`. MSO refuses to silently ignore explicit named-tunnel arguments or switch tunnel modes underneath an active endpoint.
-mso web
+
+Use a dedicated named tunnel config with placeholders only:
+
+```yaml
+tunnel: <tunnel-uuid>
+credentials-file: /home/<user>/.cloudflared/<tunnel-uuid>.json
+ingress:
+ - hostname: mso.<your-domain>
+ service: http://127.0.0.1:4005
+ - service: http_status:404
```
-The config must be a regular file owned by the current user and must not be group/world-writable.
-MSO parses it before launch and requires exactly one ingress hostname matching `OS_PUBLIC_ORIGIN`
-that points to the configured MSO loopback port, followed by `http_status:404`; its
-`credentials-file` must be a private owner-owned regular file. This prevents a config intended for
-MSO from silently publishing other laptop services. For a permanent Internet-facing control plane,
-add Cloudflare Access/WAF policy (or equivalent) in front of MSO in addition to MSO's password +
-approved-device gate. Rebuild/restart MSO after
-changing stable origin or split-host environment configuration.
+Make `~/.cloudflared/config.yml` and the credentials JSON owner-only. The config must be a regular
+file owned by the current user and must not be group/world-writable. MSO parses it before launch and
+requires exactly one ingress hostname matching `OS_PUBLIC_ORIGIN` that points to the configured MSO
+loopback port, followed by `http_status:404`; its `credentials-file` must be a private owner-owned
+regular file. This prevents a config intended for MSO from silently publishing other laptop services.
-### Tailscale (recommended)
+For Cloudflare DNS, route `<mso-subdomain>.<your-domain>` to
+`<tunnel-uuid>.cfargotunnel.com` as a **proxied** CNAME. During a nameserver cutover, it is valid to
+upsert the same CNAME temporarily at the old registrar/DNS provider so the stable hostname continues
+to resolve while NS propagation completes; move the domain nameservers to Cloudflare for reliable
+edge TLS/custom-hostname operation. Do not proxy mail records: MX/TXT records and mail-related CNAMEs
+such as `autoconfig`, `autodiscover`, and provider DKIM targets must remain **DNS-only** so importing a
+zone does not break the mail provider.
+
+For a permanent Internet-facing control plane, add Cloudflare Access/WAF policy (or equivalent) in
+front of MSO in addition to MSO's password + approved-device gate. Rebuild/restart MSO after changing
+stable origin or split-host environment configuration. Never set `OS_PUBLIC_ORIGIN` to a
+`*.trycloudflare.com` preview URL.
+
+### Tailscale (private-network alternative)
Keep MSO on loopback and publish it with Tailscale Serve so the browser reaches an HTTPS
origin.
@@ -326,15 +349,22 @@ Open the browser on its final login origin **before** pairing: HTTPS in producti
server IP and then switch to an HTTPS hostname; the Secure session cookie cannot persist on the first
origin, and the hostname change has a different browser-scoped device identity.
-The first correct login from a browser creates a **pending device**. Bootstrap an Owner from the
-server, then approve additional devices from Settings → Devices or the CLI:
+The local CLI device created by `mso onboard`/`mso doctor --fix` is approved as **Owner** on the
+host and remains the recovery path. The first correct login from a browser creates a **pending
+device**. Bootstrap the browser with the role you intend, then approve additional devices from
+Settings → Devices or the CLI:
```bash
mso device approve <device-id> "owner laptop" --role owner
mso device approve <device-id> "read-only tablet" --role viewer
mso device role <device-id> operator
+mso device role <device-id> owner # promote a browser first approved as Viewer
```
+Changing from localhost to the final custom HTTPS origin creates a different browser-scoped device
+identity, so that browser must be approved again on the new origin. Web approvals may start as
+Viewer; use `mso device role <id> owner` only after verifying the intended device.
+
Viewer is read-oriented; Operator adds bounded managed-app/Camoufox/service operations; Owner has
write, Terminal/exec, credential, device, MCP and update authority. Web approvals default to Viewer.
Role changes are resolved from the private device store on every request, so they do not wait for the
@@ -405,8 +435,10 @@ and binary overrides are documented in `.env.example`; normal installations shou
## 6. Optional Browser app — Camoufox
-The current Browser app is **Camoufox**, not the retired Playwright browser daemon.
-`scripts/camoufox-vnc-service` launches:
+The current Browser app is **Camoufox**, not the retired Playwright browser daemon. Host dependencies
+include `xvfb`, `x11vnc`, `novnc`, `matchbox-window-manager`, and `websockify`; install the Camoufox
+browser through its isolated Python venv/official fetch path rather than committing browser
+binaries into MSO. `scripts/camoufox-vnc-service` launches:
```text
Xvfb -> matchbox window manager -> Camoufox -> x11vnc -> websockify/noVNC
@@ -474,25 +506,41 @@ about automatically executing an unpinned remote installer and editing shell pro
MSO wrapper only teaches use of an already-installed RTK binary and requires a separate
explicit request for system installation/hooks.
-## 9. Optional MCP / ChatGPT custom app
+## 9. MCP / ChatGPT custom app
-MCP is **off by default**. Enable it only for a deployment that needs external AI clients:
+Fresh installs enable the OAuth-protected MCP surface and permit consent up to `exec`:
```dotenv
OS_MCP_ENABLED=1
-OS_MCP_MAX_SCOPE=read # raise to write/exec only when required
+OS_MCP_MAX_SCOPE=exec # lower to write/read when full host execution is not required
```
-Use `docs/CHATGPT-PLUGIN.md` for ChatGPT setup and diagrams, and `docs/MCP.md` for the
-complete protocol/security model. After changing the MCP toolset, refresh/re-scan the
-ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgement.
+This does not create an open endpoint: `/mcp` and OAuth discovery are live, but operational calls
+still require OAuth consent and a bearer. The advertised scopes are `read`, `write`, `exec`, and
+`offline_access`. **Security default change:** compromise of an `exec` bearer permits remote command
+execution as the MSO service user. Existing installs keep their current `.env.local` unchanged on
+update, so administrators who previously disabled or capped MCP remain opted down until they choose
+otherwise.
+
+Use `docs/CHATGPT-PLUGIN.md` for ChatGPT setup and diagrams, and `docs/MCP.md` for the complete
+protocol/security model. After changing `OS_MCP_MAX_SCOPE`, rebuild/restart the runtime and repeat the
+client consent/authorization flow so ChatGPT receives the new ceiling; changing a file does not alter
+an already-running process or previously minted token. After changing the MCP toolset, refresh/re-scan
+the ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgement.
## 10. Optional managed-app dashboards
-Hermes, OpenClaw and 9Router lifecycle management works without a domain. A configured 9Router
-application URL is preferred for its in-shell UI. Without one, 9Router stays loopback-only unless
-the owner explicitly sets `NINE_ROUTER_EXPOSE_PUBLIC=1` and accepts the firewall/authentication
-consequences. Hermes/OpenClaw remain loopback-only unless an operator adds an external route.
+Hermes, OpenClaw and 9Router lifecycle management works without a domain. Docker does not require
+systemd for 9Router; on hosts without systemd, start Docker by the host-supported/manual method first,
+then use `scripts/managed-app-9router install` or `mso mapp install 9router`. The managed container
+publishes only `127.0.0.1:20128` by default. Do **not** default `NINE_ROUTER_EXPOSE_PUBLIC=1`.
+
+Hermes/OpenClaw use user systemd units. Their prerequisite is a working user manager/bus: systemd,
+linger, and a valid `XDG_RUNTIME_DIR=/run/user/<uid>`. If that bus is unavailable, fix the prerequisite
+rather than accepting a half-installed app. A configured 9Router application URL is preferred for its
+in-shell UI. Without one, 9Router stays loopback-only unless the owner explicitly sets
+`NINE_ROUTER_EXPOSE_PUBLIC=1` and accepts the firewall/authentication consequences. Hermes/OpenClaw
+remain loopback-only unless an operator adds an external route.
The safe default is no vendor dashboard on the **MSO cockpit origin**. To opt into
split-origin embedding, configure:
diff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.md
index 85eaa378..863c667b 100644
--- a/docs/MANAGED-APPS.md
+++ b/docs/MANAGED-APPS.md
@@ -41,8 +41,15 @@ systemd bus, it reports that uncertainty instead of silently treating a running
9Router upstream publishes **both** an npm CLI and Docker images. MSO deliberately manages
the Docker distribution on servers/VPSes; this matches upstream's server/VPS quick start and
-avoids starting a second 9Router process on the same port. The repo-owned
-`scripts/managed-app-9router` is an MSO lifecycle/update adapter, not the upstream CLI.
+avoids starting a second 9Router process on the same port. Docker may need to be started manually
+on hosts without systemd; MSO does not widen 9Router just to compensate. The repo-owned
+`scripts/managed-app-9router` is an MSO lifecycle/update adapter, not the upstream CLI. Install with
+`scripts/managed-app-9router install` or `mso mapp install 9router`; the safe bind remains
+`127.0.0.1:20128` unless the owner explicitly opts into `NINE_ROUTER_EXPOSE_PUBLIC=1`.
+
+Hermes and OpenClaw depend on a working user systemd bus. Ensure linger, `XDG_RUNTIME_DIR`, and the
+user manager are healthy before install; do not treat a partially available bus as a successful
+half-install.
## 2. User experience
diff --git a/docs/MCP.md b/docs/MCP.md
index e4291eb8..dad158ca 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -14,9 +14,10 @@ mso ships an MCP server so an AI client can call the same host operations the we
UI does: list and read files, write them, check CPU/memory/disk, list processes and
managed apps, and — if you grant it — run shell commands.
-It is **off by default**. While `OS_MCP_ENABLED` is unset, `/mcp` and both OAuth
-discovery documents return 404. There is no MCP surface at all, not an
-unauthenticated one.
+Fresh installs write `OS_MCP_ENABLED=1`, so `/mcp` and OAuth discovery are available for connector
+setup by default. They are still protected: OAuth consent and a bearer are required for operational
+calls. If an administrator unsets/disables MCP, `/mcp` and both OAuth discovery documents return 404;
+demo mode also forces MCP off. Existing installs keep their current `.env.local` unchanged on update.
## Settings navigation
@@ -24,17 +25,27 @@ Settings → MCP opens a task index: **Connect an app**, **Connected apps**, **R
Anonymous visitors see an Owner sign-in entry, not private API requests or an endless loading state. Failed settings/activity loads expose a retry action; activity failures never become an empty-success state. The public `/settings?section=mcp` deep link returns sign-in users to MCP.
-## Turn it on
+## Fresh-install defaults and opt-down
```bash
-# .env.local
+# .env.local generated by a fresh install
OS_MCP_ENABLED=1
-OS_MCP_MAX_SCOPE=read # read | write | exec; default ceiling is exec
+OS_MCP_MAX_SCOPE=exec # read | write | exec
```
-After changing deployment environment, use the normal MSO update/rebuild path (Settings →
-About or `mso update --rebuild`). A Git push or editing `.env.local` does not change the
-running service by itself.
+`exec` is a powerful ceiling: if that bearer leaks, the holder can run remote commands as the MSO
+service user. Lower `OS_MCP_MAX_SCOPE` to `write` or `read` before connecting clients that do not need
+shell execution. Existing `.env.local` files are preserved during update rather than rewritten to
+these new defaults.
+
+For a public connector use a stable HTTPS origin, normally a named Cloudflare Tunnel backed by
+`http://127.0.0.1:4005`; set it with `mso gateway domain set https://mso.example.com`. Never use a
+random `*.trycloudflare.com` Quick Tunnel URL as `OS_PUBLIC_ORIGIN`.
+
+After changing deployment environment or `OS_MCP_MAX_SCOPE`, use the normal MSO update/rebuild path
+(Settings → About or `mso update --rebuild`), then repeat/refresh the OAuth consent flow in ChatGPT so
+the connector receives the new scope ceiling. A Git push or editing `.env.local` does not change the
+running service by itself, and existing tokens are not magically widened.
## Connect an MCP client
@@ -75,7 +86,10 @@ active in the **running** process (demo mode also forces MCP off).
## The three scopes
-Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`. The highest allowed tier is preselected (`exec` on a default install); lower it before Allow when a client does not need full host access.
+Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`. The fresh-install ceiling is
+`exec`, so the highest tier is available/preselected unless the administrator lowers it. The OAuth
+discovery metadata advertises `read`, `write`, `exec`, and `offline_access`; lowering the ceiling does
+not remove the protocol vocabulary, it prevents consent from granting a higher operational tier.
| Scope | Meaning |
|---|---|
diff --git a/docs/reference/WORKSPACE-GUIDE.md b/docs/reference/WORKSPACE-GUIDE.md
index 8feee9af..bbd34523 100644
--- a/docs/reference/WORKSPACE-GUIDE.md
+++ b/docs/reference/WORKSPACE-GUIDE.md
@@ -304,11 +304,17 @@ For a stable domain, keep MSO on loopback and make the public origin explicit:
```bash
mso gateway domain set https://mso.example.com
# create/configure the named Cloudflare Tunnel using the example printed above, then:
-mso gateway start --config ~/.cloudflared/config.yml --tunnel mso
-
+mso gateway start --config ~/.cloudflared/config.yml --tunnel <tunnel-id-or-name>
mso web
```
+The named tunnel config uses an owner-only credentials file, one hostname ingress to
+`http://127.0.0.1:4005`, and a final `http_status:404`. Route the public hostname to
+`<tunnel-uuid>.cfargotunnel.com` with a proxied Cloudflare CNAME. During nameserver cutover the same
+CNAME may temporarily exist at the old DNS provider, but mail MX/TXT plus `autoconfig`,
+`autodiscover`, and DKIM CNAMEs remain DNS-only. A Quick Tunnel is never a valid
+`OS_PUBLIC_ORIGIN`.
+
If another gateway is already active, stop it first with `mso gateway stop`. MSO refuses to silently ignore explicit named-tunnel arguments or switch tunnel modes underneath an active endpoint.
@@ -472,7 +478,7 @@ An authenticated **Owner** session can read allowed files and run commands as th
- Treat any file Alfa reads as untrusted input. The approval card is the only thing between text hidden inside a file and an `exec.run`. Read the command on the card, not Alfa's summary of it.
- Agents and Skills group tools for your own convenience. They are not a permission boundary: every agent can call every tool.
- `exec.run` is not sandboxed. Its cwd is bounded to your write roots, but the command itself runs in your login shell as the service user. The destructive-command denylist is a short accident tripwire, not a guard.
-- The MCP server is off unless `OS_MCP_ENABLED=1`. When on, a bearer token is a standing credential with whatever scope you granted it: at `exec` it runs any command on the box as you, and every call and result goes to the client's provider. The consent screen preselects the server ceiling (`exec` by default), so lower it before Allow when a client needs less; cap all tokens with `OS_MCP_MAX_SCOPE`, and treat anything the model reads as untrusted — scope is what stops a prompt-injected file talking it into a write. See [docs/MCP.md](../MCP.md).
+- Fresh installs write `OS_MCP_ENABLED=1`; existing installs preserve their current setting during update, and disabling it still removes the MCP/OAuth surface. A bearer token is a standing credential with whatever scope you granted it: at `exec` it runs commands as the MSO service user, and every call/result goes to the client provider. Fresh installs set the consent ceiling to `exec`, so lower it before Allow when a client needs less; cap all tokens with `OS_MCP_MAX_SCOPE`, and treat anything the model reads as untrusted — scope is what stops a prompt-injected file talking it into a write. See [docs/MCP.md](../MCP.md).
- MSO has not had a third-party security audit.
More detail: [SECURITY.md](../../SECURITY.md), [docs/FAQ.md](../FAQ.md) and [docs/INSTALL.md](../INSTALL.md).
diff --git a/frontend/slices/os-settings/components/mcp-section.tsx b/frontend/slices/os-settings/components/mcp-section.tsx
index 80310e57..80d886a8 100644
--- a/frontend/slices/os-settings/components/mcp-section.tsx
+++ b/frontend/slices/os-settings/components/mcp-section.tsx
@@ -50,8 +50,8 @@ function OwnerMcpSection() {
<SettingsSection icon={<Plug />} title="MCP is off">
<SettingsBlock className="space-y-3 py-4">
<p className="text-sm">Enable MCP on this host before connecting an AI app.</p>
- <McpCopyField label="Starting configuration in .env.local" value={"OS_MCP_ENABLED=1\nOS_MCP_MAX_SCOPE=read"} multiline />
- <p className="text-sm text-muted-foreground">Apply with <code>mso update --rebuild</code>. Start with read access and expand permissions only when needed.</p>
+ <McpCopyField label="Fresh-install configuration in .env.local" value={"OS_MCP_ENABLED=1\nOS_MCP_MAX_SCOPE=exec"} multiline />
+ <p className="text-sm text-muted-foreground">Apply with <code>mso update --rebuild</code>. Fresh installs allow consent up to exec; lower the ceiling to read/write before connecting clients that do not need remote command execution.</p>
</SettingsBlock>
</SettingsSection>
);
diff --git a/lib/install-contract.test.ts b/lib/install-contract.test.ts
index e9e66f56..a945fa68 100644
--- a/lib/install-contract.test.ts
+++ b/lib/install-contract.test.ts
@@ -99,6 +99,20 @@ describe("one-line installer contract", () => {
}
});
+ it("writes secure MCP defaults only when creating a fresh private env file", () => {
+ const src = installerSource();
+ const create = src.indexOf('if [ ! -f .env.local ]; then');
+ const preserve = src.indexOf('.env.local exists — left untouched (existing secrets preserved)');
+ expect(create).toBeGreaterThan(0);
+ expect(preserve).toBeGreaterThan(create);
+ expect(src).toContain('OS_LOGIN_PASSWORD=$GEN_PW');
+ expect(src).toContain('OS_SESSION_SECRET=$SECRET');
+ expect(src).toContain('OS_MCP_ENABLED=1');
+ expect(src).toContain('OS_MCP_MAX_SCOPE=exec');
+ expect(src).toContain('( umask 077');
+ expect(src).toContain('chmod 600 .env.local');
+ });
+
it("uses the controlling tty after curl|bash and never stdin for onboarding", () => {
const src = installerSource();
expect(src).toContain("[ -r /dev/tty ] && [ -w /dev/tty ]");
diff --git a/lib/install-docs-contract.test.ts b/lib/install-docs-contract.test.ts
index 8c9e0a19..29920126 100644
--- a/lib/install-docs-contract.test.ts
+++ b/lib/install-docs-contract.test.ts
@@ -53,9 +53,24 @@ describe("installer documentation contract", () => {
expect(detect).toBeLessThan(checkout);
expect(core).toContain('info "found existing service → updating $DIR"');
expect(core).toContain('if [ ! -f .env.local ]; then');
+ expect(core).toContain('OS_LOGIN_PASSWORD=$GEN_PW');
+ expect(core).toContain('OS_SESSION_SECRET=$SECRET');
+ expect(core).toContain('OS_MCP_ENABLED=1');
+ expect(core).toContain('OS_MCP_MAX_SCOPE=exec');
+ expect(core).toContain('chmod 600 .env.local');
expect(core).toContain('.env.local exists — left untouched (existing secrets preserved)');
});
+ it("documents the safe fresh-install MCP and stable-origin defaults", () => {
+ expect(INSTALL).toContain("OS_MCP_ENABLED=1");
+ expect(INSTALL).toContain("OS_MCP_MAX_SCOPE=exec");
+ expect(INSTALL).toContain("mso gateway domain set https://mso.example.com");
+ expect(INSTALL).toContain("http://127.0.0.1:4005");
+ expect(INSTALL).toContain("cfargotunnel.com");
+ expect(INSTALL).toContain("DNS-only");
+ expect(INSTALL).not.toMatch(/OS_PUBLIC_ORIGIN=https:\/\/[A-Za-z0-9-]+\.trycloudflare\./);
+ });
+
it("prints modern update surfaces plus a legacy fallback after installation", () => {
expect(core).toContain("Update: mso update");
expect(core).toContain("Settings → About");
diff --git a/lib/mcp/oauth-discovery-contract.test.ts b/lib/mcp/oauth-discovery-contract.test.ts
new file mode 100644
index 00000000..736e4cc0
--- /dev/null
+++ b/lib/mcp/oauth-discovery-contract.test.ts
@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const AUTHORIZATION_SERVER = fs.readFileSync(
+ path.join(__dirname, "../../app/.well-known/oauth-authorization-server/route.ts"),
+ "utf8",
+);
+const PROTECTED_RESOURCE = fs.readFileSync(
+ path.join(__dirname, "../../app/.well-known/oauth-protected-resource/route.ts"),
+ "utf8",
+);
+
+const EXPECTED_SCOPES = '["read", "write", "exec", "offline_access"]';
+
+describe("OAuth discovery contract", () => {
+ it("keeps discovery behind the MCP enable gate", () => {
+ for (const source of [AUTHORIZATION_SERVER, PROTECTED_RESOURCE]) {
+ expect(source).toContain("if (!mcpEnabled()) return new Response(\"Not Found\", { status: 404 });");
+ }
+ });
+
+ it("advertises the complete consent vocabulary including exec and offline access", () => {
+ for (const source of [AUTHORIZATION_SERVER, PROTECTED_RESOURCE]) {
+ expect(source).toContain(`scopes_supported: ${EXPECTED_SCOPES}`);
+ }
+ });
+});
diff --git a/scripts/install/finalize.sh b/scripts/install/finalize.sh
index fd933fb2..8e3c6d5d 100755
--- a/scripts/install/finalize.sh
+++ b/scripts/install/finalize.sh
@@ -99,6 +99,8 @@ cat <<EOF
Logs: $LOG_STATUS
Doctor: mso doctor (or: mso doctor --fix for safe local repairs)
Onboard: mso onboard
+ Public: mso gateway domain set https://mso.example.com (replace with your stable HTTPS hostname)
+ then use a named Cloudflare Tunnel; Quick Tunnel is preview-only and never OS_PUBLIC_ORIGIN
Update: mso update (or Settings → About in the web UI)
Legacy: re-run the official one-line installer to upgrade/recover an older install
Uninstall: re-run the installer with --uninstall
diff --git a/scripts/install/runtime-build.sh b/scripts/install/runtime-build.sh
index dda56acb..2e0c66b1 100755
--- a/scripts/install/runtime-build.sh
+++ b/scripts/install/runtime-build.sh
@@ -30,6 +30,10 @@ if [ ! -f .env.local ]; then
# mso — generated by install.sh. Private; NEVER commit.
OS_LOGIN_PASSWORD=$GEN_PW
OS_SESSION_SECRET=$SECRET
+# OAuth-protected MCP is available on fresh installs; consent/bearer auth still gates every call.
+OS_MCP_ENABLED=1
+# SECURITY: exec bearer compromise means remote command execution as this service user.
+OS_MCP_MAX_SCOPE=exec
# SESSION_EXPIRY_HOURS=24
# OS_FS_READ_ROOTS=~:~/projects
# OS_FS_WRITE_ROOTS=~:~/projects
@@ -37,7 +41,7 @@ OS_SESSION_SECRET=$SECRET
EOF
)
chmod 600 .env.local
- ok "wrote .env.local (login password + session secret generated)"
+ ok "wrote .env.local (login password + session secret generated; OAuth MCP enabled with exec ceiling)"
else
info ".env.local exists — left untouched (existing secrets preserved)"
fi