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.

fix(security): harden share audit and release verification

Rahmane3ba91996043
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index adb085b1..5cce8be2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -48,8 +48,17 @@ jobs:
- name: Lint
run: bun run lint
+ - name: Provision local Forge sandbox
+ run: bash scripts/provision-forge-sandbox.sh
+
- name: Tests and coverage
- run: bun run coverage
+ run: |
+ set -euo pipefail
+ test ! -e .env.local
+ umask 077
+ printf '# Synthetic denylist fixture; no credentials.\n' > .env.local
+ trap 'rm -f .env.local' EXIT
+ bun run coverage
- name: Repository checks
run: bun run check
diff --git a/.github/workflows/security-core.yml b/.github/workflows/security-core.yml
index 189bfb74..15c642da 100644
--- a/.github/workflows/security-core.yml
+++ b/.github/workflows/security-core.yml
@@ -28,11 +28,14 @@ jobs:
fetch-depth: 0
persist-credentials: false
- - name: Scan Git history
- uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- GITLEAKS_VERSION: 8.30.1
+ - name: Scan all Git history including merge diffs
+ run: |
+ docker run --rm --user "$(id -u):$(id -g)" --network=none \
+ --cap-drop=ALL --security-opt=no-new-privileges --read-only \
+ -v "$PWD:/repo:ro" \
+ zricethezav/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f \
+ git --no-banner --redact --log-opts="--all --full-history --diff-merges=first-parent" \
+ --gitleaks-ignore-path /repo/.gitleaksignore /repo
trivy:
name: Trivy filesystem
diff --git a/.gitignore b/.gitignore
index 99bc9f93..bdd76e43 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-node_modules/
+node_modules
.next/
out/
build/
diff --git a/.gitleaksignore b/.gitleaksignore
index f0b0a504..284f847c 100644
--- a/.gitleaksignore
+++ b/.gitleaksignore
@@ -1,3 +1,5 @@
+# Exact historical redaction-test fixtures only; no production credentials.
+# Do not add broad rules/path exclusions. Verify this allowlist against an unignored scan.
71a430389e0c5c2d7ba93f760e4ff7c786a412cf:lib/managed-apps/redact.test.ts:generic-api-key:39
71a430389e0c5c2d7ba93f760e4ff7c786a412cf:lib/managed-apps/redact.test.ts:generic-api-key:41
71a430389e0c5c2d7ba93f760e4ff7c786a412cf:lib/managed-apps/redact.test.ts:generic-api-key:42
diff --git a/CLAUDE.md b/CLAUDE.md
index a1eddc83..67816b18 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -309,21 +309,22 @@ to `resources/` (rr) and drive any project from one manifest:
They used to live in the untracked hook itself, which meant a fresh clone had NO
gates and an sc-git hook reinstall silently dropped the audit + build guards while
re-adding a `check-slices.mjs` line for a script deleted on 2026-08-03. Four guards
- run, ~70 s per push: sc-git `ci.js --skip build` (Guard 1, falling back to `bun run
- verify` when that shared runner is not on the machine — a fresh clone must not skip
- it silently), `check-cycles.mjs` (1b), `scripts/audit.mjs` (1c),
- `scripts/verify-build.sh` (1d). Guard 2 is a self-hosted-Convex auto-deploy that is
- a silent no-op here. A healthy push prints `audit: clean at high/critical.` and
- `build: HEAD compiles (out-of-tree).` — **if those two lines are missing, the wiring
- is gone.** The `--skip build` is deliberate safety, not laziness (see Deploy/ops).
+ run the repository-owned `bun run verify`, cycle/docs/changelog checks, the local
+ strict high/critical audit, and `scripts/verify-build.sh`. There is no external sc-git runner
+ and no Convex auto-deploy tail. Hook installation resolves Git's hook path, including
+ linked worktrees. Build verification stays out-of-tree; never bypass gates.
- **`bun run audit` ≠ `bun audit`.** The script is `scripts/audit.mjs`, which wraps
`bun audit --json` because raw `bun audit` fails CLOSED — offline it exits 1, the
same code as a real advisory, which would turn every network blip into a fake
security failure. It skips when the registry is unreachable, applies a high/critical
floor, and keeps an `IGNORE` map (keyed by GHSA, with a reason and a date) for
advisories with no upstream fix. `--json` ignores `--audit-level`/`--ignore`, so the
- filtering is done in the script. `ci.yml` runs the raw fail-closed command on
- purpose: a release gate must not pass an audit it could not perform.
+ filtering is done in the script. `bun run audit:strict` fails closed on unavailable,
+ malformed or incomplete evidence and is mandatory inside `security:ultimate`. CI also
+ runs the raw fail-closed command: an incomplete audit is never a security pass.
+- **`bun run test:features` runs test areas separately.** PASS requires executed tests;
+ PARTIAL/SKIPPED evidence exits 2 and is listed explicitly. This is unit/integration
+ coverage, not proof that every UI workflow or third-party integration works.
## MCP server (`/mcp`) — optional, OFF by default
An MCP endpoint so ChatGPT / Claude.ai / Cursor can drive the host. `lib/mcp/*`
diff --git a/README.md b/README.md
index 839dd411..cbd6a240 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,43 @@
<h1 align="center">Manef Shell OS</h1>
-
-<p align="center"><strong>Your Linux server, finally usable from your phone.</strong></p>
+<p align="center"><strong>Your Linux server. One private workspace.</strong></p>
+<p align="center">A real terminal, files, system health, and an AI assistant — from your phone or desktop.</p>
<p align="center">
- Open a real terminal, manage files, inspect system health, and use AI from one private browser workspace.
+ <a href="#install">Install</a> ·
+ <a href="./docs/media/demo.gif">Watch the demo</a> ·
+ <a href="./docs/README.md">Documentation</a> ·
+ <a href="./SECURITY.md">Security</a>
</p>
<p align="center">
- <a href="https://mso.rahmanef.com"><strong>Live instance</strong></a>
- ·
- <a href="./docs/media/demo.gif"><strong>Watch Demo</strong></a>
- ·
- <a href="#install"><strong>Install</strong></a>
+ <a href="https://github.com/rahmanef63/mso/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/rahmanef63/mso/actions/workflows/ci.yml/badge.svg" /></a>
+ <a href="https://github.com/rahmanef63/mso/actions/workflows/security-core.yml"><img alt="Security checks" src="https://github.com/rahmanef63/mso/actions/workflows/security-core.yml/badge.svg" /></a>
+ <img alt="App version" src="https://img.shields.io/github/package-json/v/rahmanef63/mso?label=app" />
+ <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue" />
+ <img alt="Public Alpha — Developer Preview" src="https://img.shields.io/badge/status-Public_Alpha-orange" />
</p>
-<p align="center">
- <a href="https://github.com/rahmanef63/mso/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rahmanef63/mso/actions/workflows/ci.yml/badge.svg" /></a>
- <a href="https://github.com/rahmanef63/mso/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/rahmanef63/mso/actions/workflows/codeql.yml/badge.svg" /></a>
- <a href="https://github.com/rahmanef63/mso/actions/workflows/security-core.yml"><img alt="Security Core" src="https://github.com/rahmanef63/mso/actions/workflows/security-core.yml/badge.svg" /></a>
- <a href="https://scorecard.dev/viewer/?uri=github.com/rahmanef63/mso"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/rahmanef63/mso/badge" /></a>
- <img alt="Open Source" src="https://img.shields.io/badge/Open%20Source-MIT-green" />
- <img alt="Self-hosted" src="https://img.shields.io/badge/Self--hosted-yes-2f7bf6" />
- <img alt="Public Alpha" src="https://img.shields.io/badge/Public%20Alpha-Developer%20Preview-f59e0b" />
- <img alt="Device roles" src="https://img.shields.io/badge/Device%20roles-Viewer%20%C2%B7%20Operator%20%C2%B7%20Owner-111827" />
- <img alt="Tailscale recommended" src="https://img.shields.io/badge/Tailscale%20recommended-VPN%20first-7c3aed" />
-</p>
-
-<p align="center">
- <img alt="version" src="https://img.shields.io/github/package-json/v/rahmanef63/mso?label=version&color=2f7bf6" />
- <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A520.9-3c873a?logo=nodedotjs&logoColor=white" />
- <img alt="Next.js" src="https://img.shields.io/badge/Next.js-16-000000?logo=nextdotjs&logoColor=white" />
- <img alt="React" src="https://img.shields.io/badge/React-19-149eca?logo=react&logoColor=white" />
- <img alt="bun" src="https://img.shields.io/badge/bun-1.3-fbf0df?logo=bun&logoColor=black" />
-</p>
-
-**Manef Shell OS** (**MSO** in the UI) is an open-source, mobile-friendly visual shell for a Linux server you own. It brings a real terminal, file manager, live system metrics, service/package visibility, device-scoped roles, and a BYOK AI assistant into one private browser workspace without running a full remote desktop.
-
-MSO is **Public Alpha / Developer Preview** software. It runs on top of Linux as a normal non-root Node process. It is not an operating system, Linux distribution, desktop environment, VPS provider, or production-grade security platform.
-
-**Version labels:** the badge and Settings → About show the MSO **app/package version**. The shell has a separately versioned **CLI contract** because older installs may receive CLI/update compatibility changes without an app-semver bump. `mso --version` labels both plus the Git build; `mso update status` uses the Git build as release authority, so commit-only updates never appear as a misleading same-version arrow.
+![MSO browser workspace on desktop and mobile](./docs/media/mso-hero.webp)
-For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy with tight access control**. Do not expose the raw app port to the public internet.
+**MSO is a self-hosted visual shell for a Linux server you own.** It runs as a normal,
+non-root Node process, without a required database or separate agent service. The browser,
+CLI, and optional MCP interface use the same guarded host capabilities.
-**Security assurance:** MSO publishes its [security policy](./SECURITY.md) and [repeatable assurance process](./docs/SECURITY-ASSURANCE.md), with CodeQL, independent SAST/dependency/secret scanners, OpenSSF Scorecard, SBOM generation, passive OWASP ZAP checks, and MSO-specific security regression tests. The evidence is intentionally presented as testing—not as a security certification.
+> **Public Alpha / Developer Preview.** An Owner session or exec-scoped agent can execute
+> commands as the service user. Use a dedicated non-root account and a VPN or tightly protected
+> HTTPS proxy. MSO is not an operating system, a multi-tenant security boundary, or a certified security product.
-## Product screenshot/video
+## What you can do
-![Manef Shell OS running as a browser workspace on desktop and mobile](./docs/media/mso-hero.webp)
+| Workspace | What it provides |
+|---|---|
+| **Operate your server** | Interactive PTY terminal, CPU/memory/disk metrics, service inventory and exact-allowlist lifecycle actions. |
+| **Work with files** | Browse, edit, upload, search, preview and organize files inside configured filesystem roots. |
+| **Work with AI** | Alfa browser cockpit, terminal agent, durable sessions, trusted skills, explicit mutation approvals and optional MCP access. |
+| **Use one responsive shell** | Desktop windows and mobile-first surfaces, media tools, a separate-origin browser and optional managed-app integrations. |
-<p align="center">
- <img src="./docs/media/demo.gif" alt="MSO demo: Spotlight opening the System Monitor" width="720" />
-</p>
-
-## What you can do
+<details>
+<summary><strong>Feature details and scoped benchmark evidence</strong></summary>
**Control** — terminal, files, services, package visibility, and system health for the server you own.
@@ -92,31 +77,34 @@ The public Cognitive Runtime claim baseline was revalidated on **2026-09-04** ag
The strongest currently revalidated MSO↔Hermes comparison is the exact P7+P8 **five-run, nine-scenario, matched `openai-codex/gpt-5.6-terra` corpus**: both agents are **5/5 perfect full runs**. On those exact runs, MSO observed **74.7% fewer normalized tokens/attempt**, **12.8% lower mean average latency**, and **34.1% lower mean per-run p50**. These are corpus-specific observations, **not** a claim that MSO is universally faster, smarter, cheaper, or more reliable. Cost is not ranked; cache-hit frequency is not ranked; OpenClaw is not ranked without an equivalent provider/model path. Older P4/P5 numeric tables remain historical release notes and are not the current public benchmark baseline because this audit could not independently revalidate the exact raw artifacts behind those specific numbers. See [Cognitive Runtime → Evidence status and claim boundaries](./docs/COGNITIVE-RUNTIME.md#evidence-status-and-claim-boundaries) and the versioned [claim-audit evidence manifest](./docs/evidence/cognitive-runtime-claim-audit-2026-09-04.json).
-## What can you do with MSO?
-
-**Fix a server issue from your phone**
-Check system health, inspect a failed unit and its logs, restart an exact allowlisted service, or open the owner terminal without opening a laptop.
+</details>
-**Manage project files visually**
-Browse, upload, rename, preview, and edit files without remembering every shell command.
+## Install
-**Work with your server in one workspace**
-Move between terminal, files, metrics, services, package updates, browser, and AI without switching between several admin tools.
+Run on your Linux server as your **normal user, not root**. Review the
+[bootstrap](./scripts/install.sh) and [installation guide](./docs/INSTALL.md) before executing:
-## Live demo
+```bash
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
+```
-The public demo should be deployed from a separate checkout with:
+The bootstrap verifies the downloaded installer core before running it. The guided setup
+handles credentials through hidden prompts; never paste secrets into chat or command arguments.
+The default bind is **127.0.0.1**. Keep the raw application port private.
```bash
-NEXT_PUBLIC_OS_DEMO=1 bun run build && bun run start
+mso doctor # verify the installation
+mso web # open the browser workspace
+mso # open the terminal agent
+mso update # update an existing installation safely
```
-Demo mode skips real login, forces mock data, blocks live host API access, and shows a permanent demo banner. Use it for Product Hunt traffic. A real owner deployment should stay behind Tailscale/VPN or a protected HTTPS proxy.
+Already installed but missing `mso update`? Re-run the official installer. It preserves
+`.env.local` and `~/.mso`, detects the existing service checkout, and refuses dirty/diverged source.
+An agent can follow the same repository-owned installation contract; no parallel setup is needed.
-- Live instance (the maintainer's own cockpit, auth-gated — not a demo): <https://mso.rahmanef.com>
-- Watch demo: [docs/media/demo.gif](./docs/media/demo.gif)
-
-## Install
+<details>
+<summary><strong>Full setup: onboarding, WSL, providers, tunnels and installer options</strong></summary>
### Install or update with an AI agent
@@ -314,10 +302,12 @@ 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
-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
```
+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 gateway domain set` updates `OS_PUBLIC_ORIGIN` atomically and prints a loopback-only ingress
example. Named mode accepts only a dedicated two-rule config (`your hostname → MSO loopback`, then
`http_status:404`) and a private owner-owned credentials file. It does not put tunnel tokens on a
@@ -368,8 +358,38 @@ the session cookie is `Secure`, so the browser cannot keep the login there. Full
TLS/VPN notes, filesystem roots, update/rollback and onboarding details live in
[docs/INSTALL.md](./docs/INSTALL.md).
+</details>
+
+## How it works
+
+```mermaid
+flowchart LR
+ USER["Browser / CLI / MCP client"] --> AUTH["Authentication + role / scope"]
+ AUTH --> MSO["MSO · Next.js / Node"]
+ MSO --> HOST["Guarded host capabilities"]
+ HOST --> FILES["Files · PTY · metrics · services"]
+ MSO --> AI["Optional model provider"]
+ MSO --> APPS["Optional managed apps · separate runtimes"]
+```
+
+Core persistence is local. Optional model-provider calls send the selected context off-host;
+**BYOK does not mean the data stays on your server**. Files and model output are untrusted input,
+not permission to execute a command. See [architecture](./docs/ARCHITECTURE.md) and
+[the AI/tool contract](./frontend/slices/assistant/CONTRACT.md).
+
## CLI
+```bash
+mso -h # discover commands
+mso stats # inspect system health
+mso ls ~/projects # browse a configured filesystem root
+mso model # select a connected model
+mso --continue # resume the latest durable agent session
+```
+
+<details>
+<summary><strong>More CLI examples and integration notes</strong></summary>
+
The browser UI is one frontend, not the product. The installer puts `mso` on your
`PATH`, and it reaches the same API — every endpoint has a named verb, and `mso api`
covers anything without one.
@@ -411,8 +431,22 @@ different secrets file. Device and service commands work even while the service
down. If you use [Claude Code](https://claude.com/claude-code), the installer also
links every committed official skill in `claude-skills/` into `~/.claude/skills/`. Create a consistent workflow skill with `bun run skill:new -- --help` and validate the catalog with `bun run skill:check`.
+</details>
+
## Security warning
+**The terminal and exec-scoped tools are not sandboxes.** Device roles narrow API access,
+but every role shares one deployment and the same underlying Unix service account.
+MCP is disabled unless explicitly enabled. Approve only trusted devices and tokens; keep
+filesystem write roots narrow and read the exact command on every approval card.
+
+Security checks are evidence at a particular revision, not a guarantee. The project has
+**not had an independent third-party security audit**. Read the [security policy](./SECURITY.md)
+and [repeatable assurance process](./docs/SECURITY-ASSURANCE.md) before exposing an instance.
+
+<details>
+<summary><strong>Full trust boundaries, provider data handling and operational controls</strong></summary>
+
An authenticated **Owner** session can read allowed files and run commands as the Unix user that owns the process. Viewer and Operator devices are server-gated to narrower surfaces, but all roles still share one MSO deployment and one underlying Unix account.
- Run as a dedicated non-root user.
@@ -437,32 +471,40 @@ An authenticated **Owner** session can read allowed files and run commands as th
More detail: [SECURITY.md](./SECURITY.md), [docs/FAQ.md](./docs/FAQ.md) and [docs/INSTALL.md](./docs/INSTALL.md).
-## How it works
+</details>
+
+## Development
-MSO is a single Next.js app that runs on your server as one non-root Node process. The app talks to host capabilities through local server routes and keeps features as vertical slices under `frontend/slices/<slug>/`.
+The reference runtime is **Node 22** (`.nvmrc`); use **Bun** for dependency installation and
+`bun.lock` for reproducibility. Run local development only on a trusted machine.
-```mermaid
-flowchart LR
- U["Phone / Browser"]
- subgraph VPS["Your Linux server"]
- APP["MSO / mso<br/>Next.js 16 · React 19"]
- HOST["Host layer<br/>fs · PTY · metrics · services · packages"]
- SLICES["Feature slices<br/>Files · Terminal · Monitor · Assistant"]
- AI["Alfa AI<br/>BYOK"]
- MANAGED["Managed apps<br/>Hermes · OpenClaw · 9Router<br/>own runtime + data"]
- end
- U -->|"HTTPS or Tailscale/VPN"| APP
- U -->|"framed dashboard, per-app origin<br/>same process, different origin"| APP
- APP --> HOST
- APP --> SLICES
- APP --> AI
- APP -->|"their CLI · loopback HTTP · systemd"| MANAGED
+```bash
+bun install --frozen-lockfile
+cp .env.example .env.local # configure local credentials; never commit this file
+bun run dev
```
-Deep dive: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
+```bash
+bun run verify # typecheck, lint, coverage, architecture/docs, local audit
+bun run test:features # separate test process for each area; reports coverage gaps
+bun run audit:strict # unavailable/malformed dependency evidence fails closed
+bash scripts/verify-build.sh # compile committed HEAD out-of-tree, not over a live build
+```
+
+`bun run test` uses Vitest. **Do not substitute `bun test`**, which uses a different runner.
+The ordinary local audit can explicitly skip an unavailable registry; it is not security proof.
+Use the strict audit and the [security lanes](./docs/SECURITY-ASSURANCE.md) for release assurance.
+
+**Version contracts are independent:** `package.json` owns the app version, `bin/mso`
+owns CLI compatibility, and `lib/mcp/toolset.ts` owns MCP server/toolset compatibility.
+`mso --version` labels app, CLI and Git build; the updater uses the exact Git build as release authority.
+A documentation/security-maintenance change does not invent a new MCP tool contract.
## Comparison
+<details>
+<summary><strong>Product scope comparison — methodology and limitations included</strong></summary>
+
<!-- comparison:start -->
**Positioning:** MSO is designed as a mobile-first, AI-native private Linux workspace for an owner or small trusted team. It does not claim to replace specialist products at their strongest specialty.
@@ -484,30 +526,13 @@ Strong = a first-class product strength · Partial = available with scope limita
Reviewed against official product documentation on **2026-08-29**. Ratings describe product scope, not benchmark scores. See [methodology, evidence, and per-cell notes](docs/COMPARISON.md) and the [execution roadmap](docs/COMPETITIVE-ROADMAP.md).
<!-- comparison:end -->
-## Development
-
-```bash
-bun install
-cp .env.example .env.local
-bun run dev
-```
-
-Quality gates:
-
-```bash
-bun run verify # typecheck + lint + test + checks + audit
-node scripts/check-docs.mjs # docs links/toolset/slice drift
-node scripts/gen-comparison.mjs --check # comparison evidence + 90-day freshness
-bash scripts/verify-build.sh # build HEAD out-of-tree — safe on the prod checkout
-bash -n scripts/install.sh && bash -n scripts/install-core.sh
-```
-
-The package manager is **bun** (`bun.lock` is committed); the **runtime stays Node 22** — `next`, `tsc`, `eslint` and `vitest` all carry a `#!/usr/bin/env node` shebang and bun honours it, and production runs `npm run start`. Use bun so the lockfile and the native `node-pty` build path stay predictable: `node-pty` has no Linux prebuild and is listed under `trustedDependencies`, without which its postinstall is skipped and the whole `/api/v1` surface fails to load.
-
-Full guide: [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md).
+</details>
## Tested platforms
+<details>
+<summary><strong>Linux / WSL deployment support and untested platforms</strong></summary>
+
Not yet formally tested across a full distro matrix.
Tested:
@@ -527,34 +552,24 @@ Not currently supported:
- Automatic service install on non-systemd hosts
- Root deployment
+</details>
+
## Documentation
-| Doc | What's in it |
+| Start here | Reference |
|---|---|
-| [docs/README.md](./docs/README.md) | Documentation map: current reference vs generated vs historical |
-| [docs/INSTALL.md](./docs/INSTALL.md) | Server install, credentials, TLS/VPN, update/rebuild, persistence |
-| [docs/CLI.md](./docs/CLI.md) | Generated `mso` command-line reference |
-| [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) | Local dev, gates and exact release flow |
-| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Current AppShell/host/MCP/managed-app architecture |
-| [docs/COGNITIVE-RUNTIME.md](./docs/COGNITIVE-RUNTIME.md) | Provider-neutral agent session/context/tool-routing architecture and benchmark contract |
-| [docs/COMPARISON.md](./docs/COMPARISON.md) | Generated comparison methodology, evidence and per-cell notes |
-| [docs/COMPETITIVE-ROADMAP.md](./docs/COMPETITIVE-ROADMAP.md) | Executed comparison plan, deliberate boundaries and next measurable investments |
-| [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, update, backup/restore and origins |
-| [docs/INFRASTRUCTURE-PROVIDERS.md](./docs/INFRASTRUCTURE-PROVIDERS.md) | MSO terminal agent and Dokploy/Cloudflare/Hostinger deployment-provider contract |
-| [docs/HERMES-INTEGRATION.md](./docs/HERMES-INTEGRATION.md) | Hermes-specific managed-app behaviour |
-| [docs/OPENCLAW-INTEGRATION.md](./docs/OPENCLAW-INTEGRATION.md) | OpenClaw-specific managed-app behaviour |
-| [docs/9ROUTER-INTEGRATION.md](./docs/9ROUTER-INTEGRATION.md) | 9Router immutable-image ownership, loopback default and explicit dashboard exposure |
-| [docs/MODELS-INTEGRATION.md](./docs/MODELS-INTEGRATION.md) | Alfa BYOK/custom/Codex model credentials |
-| [docs/MCP.md](./docs/MCP.md) | MCP/OAuth tools, discovery, workflow memory and security internals |
-| [docs/CHATGPT-PLUGIN.md](./docs/CHATGPT-PLUGIN.md) | ChatGPT Plugin/custom MCP app setup + architecture/OAuth/tool/file diagrams |
-| [docs/FAQ.md](./docs/FAQ.md) | Security, product and operator boundaries |
-| [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Current symptom → cause → supported recovery |
-| [SECURITY.md](./SECURITY.md) | Security posture and vulnerability reporting |
-
-## Status
-
-MSO is **Public Alpha / Developer Preview**. The core role-aware auth, filesystem bounds, terminal, metrics, Service Center, and slice architecture are implemented, but the project is still early and unaudited. Expect rough edges, breaking changes, and missing production hardening.
-
-## License
-
-MIT — see [LICENSE](./LICENSE).
+| Install, update, recover | [Installation](./docs/INSTALL.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md) |
+| Use the CLI or connect MCP | [Generated CLI reference](./docs/CLI.md) · [MCP](./docs/MCP.md) · [ChatGPT integration](./docs/CHATGPT-PLUGIN.md) |
+| Understand the runtime | [Architecture](./docs/ARCHITECTURE.md) · [Cognitive Runtime](./docs/COGNITIVE-RUNTIME.md) |
+| Contribute or review security | [Contributing](./CONTRIBUTING.md) · [Development](./docs/DEVELOPMENT.md) · [Security](./SECURITY.md) |
+| Browse everything | [Documentation map](./docs/README.md) · [Changelog](./docs/CHANGELOG.md) |
+
+The [maintainer's instance](https://mso.rahmanef.com) requires authentication; it is **not a public demo**.
+The [recorded demo](./docs/media/demo.gif) is available without access to a real server.
+A separate mock-only demo must keep `NEXT_PUBLIC_OS_DEMO=1` at build time and bind to loopback
+unless its owner explicitly publishes it; never enable demo mode on an owner deployment.
+
+## Status and license
+
+**Public Alpha / Developer Preview** — expect rough edges and breaking changes.
+MIT licensed; see [LICENSE](./LICENSE).
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 7d770d97..c927b267 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -4,6 +4,12 @@
Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;
this is the *what*, and it is what Settings → About shows as “What's new”.
+## 2026-09-05
+
+**Fixed**
+
+- `security` harden share audit and release verification
+
## 2026-09-04
**Added**
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index da47091c..24a6ea69 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -23,7 +23,9 @@ Every feature is a self-contained **vertical slice** under `frontend/slices/<slu
## Quality gates
```bash
-bun run verify # fast/full repository quality gate
+bun run verify # full repository quality gate
+bun run test:features # one process per area; exit 2 means skipped/incomplete evidence
+bun run audit:strict # fail closed on missing/malformed dependency evidence
bun run security:ultimate # release assurance: independent scanners + component security review + DAST
```
@@ -31,14 +33,20 @@ The **committed source of truth** for pre-push policy is `scripts/gates.sh`. The
actual `.git/hooks/pre-push` file is an intentionally tiny untracked shim; reinstall it
idempotently with `bash scripts/gates.sh --install`.
-The gate runs typecheck/lint/test (shared sc-git runner when present, otherwise the
-in-repo verify path), cycle checks, generated-changelog freshness, documentation/skill checks,
-comparison evidence/freshness, the high/critical dependency audit, and an out-of-tree production
+The gate runs the repository-owned `bun run verify`, cycle checks, generated-changelog freshness, documentation/skill checks,
+comparison evidence/freshness, the strict high/critical dependency audit, and an out-of-tree production
build.
`check-contrast.mjs` is informational. None of the build verification touches the live
checkout's `.next`. A healthy push ends with `audit: clean at high/critical.` and
`build: HEAD compiles (out-of-tree).`
+The local dependency audit may explicitly skip an unavailable registry; that is not a security pass.
+`bun run audit:strict`, the pre-push gate, and the assurance runner reject incomplete evidence. `test:features` distinguishes
+PASS, PARTIAL, SKIPPED and FAIL; slices without colocated unit tests are listed as coverage gaps,
+not invented successes. Browser rendering and live third-party operations need separate acceptance.
+The gate has no sibling-repository runner or dormant Convex deployment step. Worktree hook installation
+uses Git's shared hook path rather than assuming `.git` is a directory.
+
## Comparison governance
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 4dd03a72..6779a017 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,4 +1,5 @@
# mso — Progress Log
+- **Public-sharing security and maintenance audit (2026-09-05):** app `0.2.2` keeps the independently versioned CLI/MCP contracts unchanged. Release and assurance dependency audits now fail closed on unavailable, malformed or incomplete evidence; local developer skips are explicitly labelled, registry diagnostics do not expose raw URLs, and skipped optional scanners cannot produce an unconditional assurance PASS. Removed the dormant Convex deploy tail, fixed shared Git-hook installation and out-of-tree dependency copying for linked worktrees, and added functional regression tests. README now leads with a readable install/features/security overview and collapsible reference detail, preserving generated comparison evidence and public-alpha limits. `test:features` runs each test area in a separate process and distinguishes PASS/PARTIAL/SKIPPED/FAIL. The Forge Docker sandbox and synthetic credential-path fixture activate previously skipped security checks without using real secrets; CI now provisions the same bounded fixtures. Onboarding tests derive the app version from `package.json`; the browser suite follows the actual Activity & Runs UI, checks infrastructure deep-links, and never echoes session-cookie diagnostics. Full-history scanning now requests merge diffs explicitly in CI and the assurance runner; independent scanner outputs remain private; no genuine historical secret was identified by the configured scan, so shared history was not rewritten. Live-service deployment and remote CI status require separate exact-revision evidence and are not inferred from local tests.
- **Rahmanef-aligned MCP widget palette / Block + Page v2 (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.7` moves the two canonical ChatGPT resources to `ui://mso/block-v2.html` and `ui://mso/page-v2.html` so hosts do not reuse the old purple CSS cache key. Block and Page now share one visual-token source aligned with `rahmanef.com`: light `#f4f4f7` / `#1c1c1f`, dark `#1b1b20` / `#f2f2f5`, accent `#1f6df0`, Plus Jakarta Sans display copy, Inter body copy, fine separators, and editorial foreground/background primary-action inversion. ChatGPT theme changes propagate through `window.openai.theme` with a color-scheme fallback. Block/Page v1 and the earlier workflow/surface URIs remain readable but unlisted compatibility aliases; the headless workflow and two-surface/security contracts are unchanged.
- **Headless workflows + two-surface MCP UI contract (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.6` removes the automatic UI binding from `workflow_start`: orchestration, collision checks, tracing, evidence, and learning continue in the background without consuming the answer with a progress card. ChatGPT now has exactly two canonical MCP App resources: `ui://mso/block-v1.html` through `render_mso_block` for compact validation/action/CRUD input-output, and `ui://mso/page-v1.html` through `render_mso_page` for native operator views plus reviewed development/preview/production embeds. Block buttons send a user-approved follow-up and never execute mutations inside the widget, preserving normal scope, approval, audit, and workflow boundaries. The prior workflow/surface URIs remain non-advertised read aliases, while `workflow_status` and `render_mso_surface` remain app-only compatibility shims for cached clients. The ChatGPT transport profile is 66 tools: 64 model-visible actions (35 read / 17 write / 12 exec) plus two app-only shims; the full catalog is 90. Only Block and Page advertise a resource URI.
- **Local release audit timeout hardening (2026-09-04):** the tolerant pre-push dependency audit now caps `bun audit --json` at 15 seconds. A registry timeout is reported and skipped only in the local gate, matching its existing network-tolerant policy; CI remains the fail-closed dependency-audit authority. This prevents a slow registry request from holding GitHub's pre-push SSH session open for minutes and failing the otherwise-green release with a transport/SIGPIPE-style exit.
diff --git a/docs/SECURITY-ASSURANCE.md b/docs/SECURITY-ASSURANCE.md
index 924b2976..eec57568 100644
--- a/docs/SECURITY-ASSURANCE.md
+++ b/docs/SECURITY-ASSURANCE.md
@@ -47,10 +47,12 @@ From a clean development checkout with Docker and the normal MSO toolchain:
bun run security:ultimate
```
-The command creates a `0700` private run directory under `~/.mso/security-assurance`, snapshots **tracked files only**, and runs the repository verification plus Trivy, OSV-Scanner, Gitleaks, Semgrep, ShellCheck, the official Codex Security component scan across the full tracked repository and the passive ZAP baseline. OSV-Scanner is a version-pinned official release binary cached under owner-local MSO state and verified against its pinned SHA-256 before use; the gate does not depend on a mutable/denied GHCR image. Detailed scanner output stays outside the repository. A failing scanner produces a failing command; the script does not convert scanner outages into security passes.
+The command creates a `0700` private run directory under `~/.mso/security-assurance`, snapshots **tracked files only**, and runs the repository verification and a fail-closed `bun run audit:strict` plus Trivy, OSV-Scanner, Gitleaks, Semgrep, ShellCheck, the official Codex Security component scan across the full tracked repository and the passive ZAP baseline. OSV-Scanner is a version-pinned official release binary cached under owner-local MSO state and verified against its pinned SHA-256 before use; the gate does not depend on a mutable/denied GHCR image. Gitleaks mounts the common Git directory so linked worktrees still scan all available refs with merge diffs (`--all --full-history --diff-merges=first-parent`). Detailed scanner output stays outside the repository. A failing scanner produces a failing command; the script does not convert scanner outages into security passes.
Codex Security is intentionally not an automatic per-commit hosted gate because it consumes model/API budget. MSO uses OpenAI's official `scan-components` command because repeated monolithic Standard scans of this repository reached bounded spend limits without producing a terminal coverage result. The committed [`security/codex-components.json`](../security/codex-components.json) plan was generated by the official planner and covers all tracked files through twenty non-overlapping components. The official auto-plan was refined along subsystem boundaries after bounded trial scans proved that its two largest groups were too broad to reach a terminal result within the per-component guard. Each component receives a Standard scan, then Codex Security performs cross-component root-cause matching; incomplete component coverage or incomplete matching fails closed. The default guard is $8 **per component**, with two concurrent workers. MSO pins the component lane to `gpt-5.6-terra` with `high` reasoning because calibration on the security-critical `lib/host` component reached complete terminal coverage under that bounded budget, while `gpt-5.6-sol` at xhigh/medium repeatedly exhausted bounded spend without a terminal coverage result. Model, effort, budget and workers remain explicit overrides through `CODEX_SECURITY_MODEL`, `CODEX_SECURITY_EFFORT`, `CODEX_SECURITY_COMPONENT_MAX_COST_USD` and `CODEX_SECURITY_COMPONENT_WORKERS`. The result gate independently validates `summary.json` and the combined `findings.json`; High/Critical groups fail the run. A maintainer can explicitly skip the lane with `MSO_SECURITY_SKIP_CODEX=1`, but a run with a skipped lane must not be advertised as the full ultimate gate. ZAP is likewise skippable for offline development, but not for a published assurance run.
+The final runner message summarizes only the selected lanes; skipped Codex or ZAP lanes never become an unconditional full-assurance PASS. `bun run test:features` likewise labels partially skipped and entirely skipped test groups instead of treating a green process as executed coverage.
+
## Reviewed Gitleaks fixtures
MSO's redaction unit test intentionally contains six realistic-looking **synthetic** credential fixtures so the redactor can prove it removes secrets. Gitleaks correctly detects those patterns in the historical commit that introduced the test. The repository records six exact finding fingerprints in `.gitleaksignore` and marks the current fixture lines with `gitleaks:allow`.
diff --git a/lib/onboard-contract.test.ts b/lib/onboard-contract.test.ts
index ac7269ea..14e164aa 100644
--- a/lib/onboard-contract.test.ts
+++ b/lib/onboard-contract.test.ts
@@ -4,6 +4,8 @@ import os from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
+const appVersion: string = JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), "utf8")).version;
+
const cli = [
fs.readFileSync(path.join(__dirname, "../bin/mso"), "utf8"),
fs.readFileSync(path.join(__dirname, "../scripts/cli/onboarding.sh"), "utf8"),
@@ -47,7 +49,7 @@ describe("terminal onboarding contract", () => {
case "$*" in
*api/auth/login*) printf '{"success":true}\n200' ;;
*api/auth/me*) printf '{"role":"owner"}\n200' ;;
- *) printf '{"status":"ok","buildId":"fixture","runtimeInstanceId":"fixture","version":"0.2.1"}\n' ;;
+ *) printf '{"status":"ok","buildId":"fixture","runtimeInstanceId":"fixture","version":"${appVersion}"}\n' ;;
esac
`, { mode: 0o700 });
try {
@@ -79,7 +81,7 @@ esac
case "$*" in
*api/auth/login*) body='{"success":true}' ;;
*api/auth/me*) body='{"authenticated":true,"role":"owner"}' ;;
- *) body='{"status":"ok","service":"mso","buildId":"fixture","buildSha":"abcdef1","runtimeInstanceId":"fixture","version":"0.2.1"}' ;;
+ *) body='{"status":"ok","service":"mso","buildId":"fixture","buildSha":"abcdef1","runtimeInstanceId":"fixture","version":"${appVersion}"}' ;;
esac
case "$*" in *'-w '*) printf '%s\n200' "$body" ;; *) printf '%s' "$body" ;; esac
`, { mode: 0o700 });
diff --git a/package.json b/package.json
index cdb76999..838387f9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "mso",
- "version": "0.2.1",
+ "version": "0.2.2",
"private": true,
"engines": {
"node": ">=20.9"
@@ -38,7 +38,9 @@
"bench:corpus": "bun scripts/bench-agent-corpus.mjs",
"bench:corpus:repeat": "bun scripts/bench-agent-repeat.mjs",
"bench:cache-calibration": "bun scripts/bench-agent-cache.mjs",
- "mcp:catalog": "node scripts/gen-mcp-catalog.mjs"
+ "mcp:catalog": "node scripts/gen-mcp-catalog.mjs",
+ "audit:strict": "node scripts/audit.mjs --strict",
+ "test:features": "node scripts/test-features.mjs"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.120.0",
diff --git a/scripts/audit.mjs b/scripts/audit.mjs
index 561fa2d6..7424b0c1 100644
--- a/scripts/audit.mjs
+++ b/scripts/audit.mjs
@@ -1,91 +1,64 @@
#!/usr/bin/env node
-// Dependency audit gate — the tolerant, LOCAL half.
-//
-// Why this exists rather than just `bun audit --audit-level=high`:
-//
-// 1. `bun audit` fails CLOSED. With no network it prints "audit request failed" and
-// exits 1 — the SAME exit code as a real advisory. Wired straight into a pre-push
-// hook that turns every flaky-DNS moment into a fake security failure that blocks
-// the push. Exit code alone cannot tell the two apart; empty stdout is the only
-// discriminator (`{}` when clean, nothing at all when the request died).
-// 2. The ignore list belongs in version control. `--ignore=<id>` works, but a flag
-// buried in a script or a CI file has no room for WHY or WHEN, and nobody reviews
-// it. Here each entry carries a reason and a date and shows up in `git blame`.
-//
-// CI does NOT use this script — .github/workflows/ci.yml runs the raw fail-closed
-// command on purpose, because a release gate must never pass an audit it could not
-// actually perform.
-//
-// TRAP, learned the hard way: `--json` IGNORES both `--audit-level` and `--ignore`
-// (it dumps the raw registry response and exits 1 on any advisory at any severity).
-// So this script does its own severity + ignore filtering and never trusts bun's exit
-// code in --json mode.
-
+// Local development tolerates an unavailable registry; --strict never treats a
+// skipped/incomplete dependency audit as success. CI and security assurance use strict mode.
import { spawnSync } from "node:child_process";
const FLOOR = new Set(["high", "critical"]);
const AUDIT_TIMEOUT_MS = 15_000;
-
-// GHSA/CVE id -> why it is accepted + the date it was accepted.
-// Only for advisories with NO upstream fix. If a fix exists, take the fix (an
-// `overrides` entry in package.json counts) instead of adding an entry here.
-const IGNORE = {
- // e.g. "GHSA-xxxx-xxxx-xxxx": "no fixed release upstream; not reachable because <…>. Accepted 2026-08-03, recheck monthly.",
-};
-
-const res = spawnSync("bun", ["audit", "--json"], { encoding: "utf8", timeout: AUDIT_TIMEOUT_MS, killSignal: "SIGTERM" });
-const raw = (res.stdout ?? "").trim();
-
-if (res.error?.code === "ETIMEDOUT") {
- console.warn(`audit: registry timed out after ${AUDIT_TIMEOUT_MS / 1000}s, skipped`);
- process.exit(0);
+const STRICT = process.argv.includes("--strict");
+if (process.argv.slice(2).some((arg) => arg !== "--strict")) {
+ console.error("usage: node scripts/audit.mjs [--strict]");
+ process.exit(2);
}
-// Empty stdout = the request never completed (offline, dead registry, proxy refused).
-// Warn and pass: a broken network is not evidence of a vulnerability, and this is the
-// local gate. CI is the one that fails closed.
-if (!raw) {
- const why = (res.stderr ?? "").trim().split("\n").pop() || "no output";
- console.warn(`audit: registry unreachable, skipped — ${why}`);
- process.exit(0);
+// GHSA/CVE -> reason + acceptance date, only when no upstream fix exists.
+const IGNORE = {};
+function unavailable(reason) {
+ console.error(`audit: ${reason}; ${STRICT ? "INCOMPLETE (strict gate failed)" : "SKIPPED (not a security pass)"}`);
+ process.exit(STRICT ? 2 : 0);
}
+const res = spawnSync("bun", ["audit", "--json"], {
+ encoding: "utf8", timeout: AUDIT_TIMEOUT_MS, killSignal: "SIGTERM",
+});
+const raw = (res.stdout ?? "").trim();
+if (res.error?.code === "ETIMEDOUT") unavailable(`registry timed out after ${AUDIT_TIMEOUT_MS / 1000}s`);
+if (res.error || res.signal) unavailable("audit process did not complete");
+// Do not echo registry diagnostics: proxy URLs may carry credentials.
+if (!raw) unavailable("registry unreachable or no audit output");
+
let report;
-try {
- report = JSON.parse(raw);
-} catch {
- console.warn("audit: could not parse `bun audit --json` output, skipped");
- process.exit(0);
-}
+try { report = JSON.parse(raw); } catch { unavailable("invalid JSON response"); }
+if (!report || typeof report !== "object" || Array.isArray(report)) unavailable("invalid report shape");
+// Bun JSON mode reports every severity regardless of --audit-level/--ignore.
+// Exit 1 with valid advisories is expected; unknown process failures are not.
+if (res.status !== 0 && res.status !== 1) unavailable("unexpected audit exit status");
+if (res.status !== 0 && Object.keys(report).length === 0) unavailable("failed audit returned an empty report");
-// Shape: { "<pkg>": [ { id, severity, title, url, … } ], … }
const hits = [];
+const severities = new Set(["info", "low", "moderate", "medium", "high", "critical"]);
for (const [pkg, advisories] of Object.entries(report)) {
- for (const a of advisories ?? []) {
- if (!FLOOR.has(String(a.severity).toLowerCase())) continue;
- // bun's JSON carries only an opaque numeric `id`; the readable GHSA lives in the
- // advisory URL. Pull it out so IGNORE can be keyed on something a human recognises
- // and can look up, rather than on a bare number.
- const ghsa = /(GHSA-[a-z0-9-]+)/i.exec(a.url ?? "")?.[1];
- const ids = [ghsa, a.github_advisory_id, a.id, a.cve, ...(a.cves ?? [])].filter(Boolean).map(String);
- if (ids.some((id) => id in IGNORE)) continue;
- hits.push({ pkg, id: ghsa ?? String(a.id ?? "?"), severity: a.severity, title: a.title ?? "", url: a.url ?? "" });
+ if (!Array.isArray(advisories)) unavailable("invalid advisory list");
+ for (const advisory of advisories) {
+ if (!advisory || typeof advisory !== "object"
+ || typeof advisory.severity !== "string" || !severities.has(advisory.severity.toLowerCase())) {
+ unavailable("invalid advisory severity");
+ }
+ if (!FLOOR.has(advisory.severity.toLowerCase())) continue;
+ const ghsa = /(GHSA-[a-z0-9-]+)/i.exec(String(advisory.url ?? ""))?.[1];
+ const ids = [ghsa, advisory.github_advisory_id, advisory.id, advisory.cve,
+ ...(Array.isArray(advisory.cves) ? advisory.cves : [])].filter(Boolean).map(String);
+ if (ids.some((id) => Object.hasOwn(IGNORE, id))) continue;
+ // Print only bounded identifiers, never arbitrary registry text/URLs.
+ hits.push({ pkg: pkg.replace(/[^a-zA-Z0-9@/_.-]/g, "").slice(0, 160),
+ id: ghsa ?? "unidentified-advisory", severity: advisory.severity.toUpperCase() });
}
}
-
if (hits.length === 0) {
- console.log("audit: clean at high/critical.");
+ console.log(`audit: clean at high/critical.${STRICT ? " (strict)" : ""}`);
process.exit(0);
}
-
-console.error(`audit: ${hits.length} unignored high/critical advisor${hits.length === 1 ? "y" : "ies"}:`);
-for (const h of hits) {
- console.error(` ${h.severity.toUpperCase()} ${h.pkg} ${h.id}`);
- if (h.title) console.error(` ${h.title}`);
- if (h.url) console.error(` ${h.url}`);
-}
-console.error("");
-console.error("Fix it (prefer an `overrides` entry in package.json pinning the patched version).");
-console.error("If there is genuinely no upstream fix, add the id to IGNORE in scripts/audit.mjs");
-console.error("with a reason and a date — do NOT lower the severity floor, that disables the whole tier.");
+console.error(`audit: ${hits.length} unignored high/critical advisories:`);
+for (const hit of hits) console.error(` ${hit.severity} ${hit.pkg} ${hit.id}`);
+console.error("Upgrade the affected dependency; do not lower the severity floor.");
process.exit(1);
diff --git a/scripts/audit.test.ts b/scripts/audit.test.ts
new file mode 100644
index 00000000..266cc46e
--- /dev/null
+++ b/scripts/audit.test.ts
@@ -0,0 +1,47 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+function audit(report: string, code = 0, strict = true) {
+ const root = mkdtempSync(path.join(tmpdir(), "mso-audit-contract-"));
+ chmodSync(root, 0o700); roots.push(root);
+ const bin = path.join(root, "bin"); mkdirSync(bin);
+ writeFileSync(path.join(bin, "bun"), `#!${process.execPath}\nprocess.stdout.write(process.env.FIXTURE_REPORT ?? '');\nprocess.stderr.write('private-registry-diagnostic');\nprocess.exit(Number(process.env.FIXTURE_EXIT));\n`, { mode: 0o700 });
+ return spawnSync(process.execPath, [path.join(process.cwd(), "scripts/audit.mjs"), ...(strict ? ["--strict"] : [])], {
+ encoding: "utf8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}`,
+ FIXTURE_REPORT: report, FIXTURE_EXIT: String(code) }, timeout: 10_000,
+ });
+}
+
+describe("dependency audit evidence boundary", () => {
+ it("accepts a successful empty advisory report", () => {
+ const result = audit("{}"); expect(result.status).toBe(0); expect(result.stdout).toContain("(strict)");
+ });
+ it.each(["", "not json", "null", "[]", '{"pkg":{}}', '{"pkg":[null]}', '{"pkg":[{"severity":"unknown"}]}'])(
+ "fails strict mode for incomplete/malformed output %s", (report) => {
+ const result = audit(report); expect(result.status).toBe(2);
+ expect(result.stderr).toContain("INCOMPLETE"); expect(result.stdout).not.toContain("clean");
+ expect(result.stderr).not.toContain("private-registry-diagnostic");
+ },
+ );
+ it("rejects failed processes even if they emit an empty JSON object", () => {
+ expect(audit("{}", 1).status).toBe(2); expect(audit("{}", 7).status).toBe(2);
+ });
+ it("keeps tolerant local mode explicit about skipped evidence", () => {
+ const result = audit("", 1, false); expect(result.status).toBe(0);
+ expect(result.stderr).toContain("SKIPPED (not a security pass)");
+ });
+ it("blocks high/critical advisories without printing arbitrary registry fields", () => {
+ const result = audit(JSON.stringify({ example: [{ severity: "high", title: "private-registry-diagnostic", url: "https://github.com/advisories/GHSA-test-test-test" }] }), 1);
+ expect(result.status).toBe(1); expect(result.stderr).toContain("GHSA-test-test-test");
+ expect(result.stderr).not.toContain("private-registry-diagnostic");
+ });
+ it("applies the documented high/critical threshold to a valid lower-severity report", () => {
+ const result = audit(JSON.stringify({ example: [{ severity: "moderate", id: 1 }] }), 1);
+ expect(result.status).toBe(0); expect(result.stdout).toContain("clean at high/critical");
+ });
+});
diff --git a/scripts/e2e/shell.mjs b/scripts/e2e/shell.mjs
index cb2891fe..1f24132b 100644
--- a/scripts/e2e/shell.mjs
+++ b/scripts/e2e/shell.mjs
@@ -52,7 +52,7 @@ async function mintSession() {
if (!r.ok) throw new Error(`login failed (${r.status}) — is the device approved? ${DEVICE}`);
const raw = r.headers.get("set-cookie") ?? "";
const value = /(?:^|,\s*)session=([^;]+)/.exec(raw)?.[1];
- if (!value) throw new Error(`login 200 but no session cookie in: ${raw.slice(0, 120)}`);
+ if (!value) throw new Error("login 200 but no session cookie was returned");
sessionValue = value;
return value;
}
@@ -68,7 +68,7 @@ const TITLES = {
files: "Files", browser: "Camoufox", code: "Code", terminal: "Terminal", claude: "Claude Code",
studio: "Image Editor", reel: "Video Editor", viewer: "Preview", store: "App Store", create: "Create App",
monitor: "System Monitor", assistant: "Alfa", links: "Quicklinks", docs: "Docs", settings: "Settings",
- hermes: "Hermes", openclaw: "OpenClaw", "9router": "9Router",
+ hermes: "Hermes", openclaw: "OpenClaw", "9router": "9Router", dokploy: "Dokploy", cloudflare: "Cloudflare",
};
const IGNORE = [
@@ -171,9 +171,10 @@ async function session(browser, { width, height, label, touch = width < 768, exp
await page.goto(`${BASE}/?redirectUrl=${encodeURIComponent(chatUrl)}`, { waitUntil: "domcontentloaded" });
await page.waitForURL((url) => url.pathname === "/assistant/mcp", { timeout: 5_000 });
await page.locator("[data-window]").first().waitFor({ state: "visible", timeout: 5_000 });
- const mcpVisible = await page.getByText("MCP Activity", { exact: true }).first().isVisible().catch(() => false);
+ const activity = page.getByText("Activity & Runs", { exact: true }).first();
+ const mcpVisible = await activity.waitFor({ state: "visible", timeout: 10_000 }).then(() => true).catch(() => false);
check(page.url().includes("/assistant/mcp"), "ChatGPT Open in MSO lands on /assistant/mcp");
- check(mcpVisible, "ChatGPT Open in MSO visibly opens Alfa MCP Activity");
+ check(mcpVisible, "ChatGPT Open in MSO visibly opens Alfa Activity & Runs");
}
// ── open every app by DEEP LINK rather than by clicking the dock.
@@ -187,7 +188,7 @@ async function session(browser, { width, height, label, touch = width < 768, exp
// this app render", and conflating them made both unreliable.
const nativeSlugs = [
"files", "browser", "code", "terminal", "claude", "studio", "reel", "viewer",
- "store", "create", "monitor", "assistant", "links", "docs", "settings",
+ "store", "create", "monitor", "assistant", "links", "docs", "settings", "dokploy", "cloudflare",
];
for (const slug of nativeSlugs) {
await page.goto(`${BASE}/${slug}`, { waitUntil: "domcontentloaded" });
diff --git a/scripts/feature-test-result.test.ts b/scripts/feature-test-result.test.ts
new file mode 100644
index 00000000..64148703
--- /dev/null
+++ b/scripts/feature-test-result.test.ts
@@ -0,0 +1,22 @@
+import { spawnSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+
+describe("per-feature evidence classification", () => {
+ const cases = [
+ [0, { success: true, numTotalTests: 3, numPassedTests: 3 }, "PASS"],
+ [0, { success: true, numTotalTests: 3, numPassedTests: 0, numPendingTests: 3 }, "SKIPPED"],
+ [0, { success: true, numTotalTests: 3, numPassedTests: 2, numPendingTests: 1 }, "PARTIAL"],
+ [0, { success: true, numTotalTests: 3, numPassedTests: 2, numTodoTests: 1 }, "PARTIAL"],
+ [0, { success: true, numTotalTests: 0, numPassedTests: 0 }, "FAIL"],
+ [1, { success: false, numTotalTests: 3, numPassedTests: 2, numFailedTests: 1 }, "FAIL"],
+ [null, {}, "FAIL"],
+ [0, { success: true, numTotalTests: 3, numPassedTests: 2, numFailedTests: 1 }, "FAIL"],
+ ] as const;
+ for (const [code, result, expected] of cases) {
+ it(`classifies ${JSON.stringify(result)} as ${expected}`, () => {
+ const script = `import { classifyFeatureResult } from "./scripts/lib/feature-test-result.mjs"; console.log(classifyFeatureResult(${JSON.stringify(code)}, ${JSON.stringify(result)}));`;
+ const run = spawnSync(process.execPath, ["--input-type=module", "-e", script], { cwd: process.cwd(), encoding: "utf8" });
+ expect(run.status).toBe(0); expect(run.stdout.trim()).toBe(expected);
+ });
+ }
+});
diff --git a/scripts/gates.sh b/scripts/gates.sh
index f5108908..075ab968 100755
--- a/scripts/gates.sh
+++ b/scripts/gates.sh
@@ -31,7 +31,7 @@ while IFS= read -r git_local_var; do
done < <(git rev-parse --local-env-vars 2>/dev/null || true)
if [ "${1-}" = "--install" ]; then
- HOOK="$ROOT/.git/hooks/pre-push"
+ HOOK="$(git rev-parse --git-path hooks/pre-push)"
mkdir -p "$(dirname "$HOOK")"
printf '#!/usr/bin/env bash\n# Thin shim — the gates live in scripts/gates.sh, which is committed.\nexec bash "$(git rev-parse --show-toplevel)/scripts/gates.sh"\n' > "$HOOK"
chmod +x "$HOOK"
@@ -61,9 +61,8 @@ node scripts/check-contrast.mjs || true
# ── Guard 1c — dependency audit, high/critical only.
# Must live HERE rather than rely on an external CI wrapper. The audit wrapper
-# skips (exit 0) when the registry is unreachable, so a network blip cannot fake a
-# CVE and block a push.
-node scripts/audit.mjs || fail "audit: unignored high/critical advisory."
+# can skip locally, but a release gate must fail closed on missing evidence.
+node scripts/audit.mjs --strict || fail "audit: high/critical advisory or incomplete registry evidence."
# ── Guard 1d — build. Never build in THIS directory: `next build` wipes .next
# before compiling, while the live :4005 process may be serving from it.
@@ -71,23 +70,3 @@ node scripts/audit.mjs || fail "audit: unignored high/critical advisory."
bash scripts/verify-build.sh >/dev/null 2>&1 \
&& echo "build: HEAD compiles (out-of-tree)." \
|| fail "build failed." "reproduce: bash scripts/verify-build.sh"
-
-# ── Guard 2 — self-hosted Convex auto-deploy. A silent no-op in this repo (there is
-# no convex/ directory); kept so the file matches the shared sc-git shape and a
-# future backend does not have to rediscover the ordering rule: backend first, or
-# the frontend lands ahead of it.
-if [ -d convex ] && [ -f .env.local ] \
- && grep -q "^CONVEX_SELF_HOSTED_URL=" .env.local 2>/dev/null \
- && grep -q "^CONVEX_SELF_HOSTED_ADMIN_KEY=" .env.local 2>/dev/null; then
- LOCAL_SHA=$(git rev-parse HEAD 2>/dev/null || true)
- REMOTE_SHA=$(git rev-parse origin/main 2>/dev/null || echo "")
- if [ -n "$REMOTE_SHA" ] && [ "$LOCAL_SHA" != "$REMOTE_SHA" ] \
- && [ -n "$(git diff --name-only "$REMOTE_SHA"..HEAD -- convex/ 2>/dev/null || true)" ]; then
- echo ""
- echo "▶ convex/ changed → deploying self-hosted Convex FIRST"
- set -a; . ./.env.local; set +a
- pnpm exec convex deploy --yes \
- || fail "Convex self-hosted deploy failed." "do NOT --no-verify — the frontend would land ahead of the backend."
- echo "✓ Convex deploy complete. Continuing push."
- fi
-fi
diff --git a/scripts/lib/feature-test-result.mjs b/scripts/lib/feature-test-result.mjs
new file mode 100644
index 00000000..6e26d23d
--- /dev/null
+++ b/scripts/lib/feature-test-result.mjs
@@ -0,0 +1,8 @@
+// A green process is not proof that any test executed. Keep skipped evidence explicit.
+export function classifyFeatureResult(exitCode, result) {
+ if (exitCode !== 0 || result.success !== true || !(result.numTotalTests > 0)) return "FAIL";
+ if ((result.numFailedTests ?? 0) > 0) return "FAIL";
+ if (!(result.numPassedTests > 0)) return "SKIPPED";
+ if ((result.numPendingTests ?? 0) + (result.numTodoTests ?? 0) > 0) return "PARTIAL";
+ return "PASS";
+}
diff --git a/scripts/security-ultimate.sh b/scripts/security-ultimate.sh
index f4260f4f..565254fa 100755
--- a/scripts/security-ultimate.sh
+++ b/scripts/security-ultimate.sh
@@ -89,6 +89,7 @@ prepare_osv() {
}
run_capture "repository verify" bun run verify
+run_capture "strict dependency audit" bun run audit:strict
run_capture "installer syntax" bash -c 'bash -n scripts/install.sh && bash -n scripts/install-core.sh'
run_capture "Trivy high/critical" docker run --rm -v "$SRC:/src:ro" "$TRIVY_IMAGE" \
fs --scanners vuln,misconfig,secret --severity HIGH,CRITICAL --exit-code 1 /src
@@ -96,8 +97,11 @@ run_capture "OSV binary integrity" prepare_osv
OSV_HOME="$RUN_DIR/osv-home"
mkdir -p "$OSV_HOME"; chmod 700 "$OSV_HOME"
run_capture "OSV dependencies" env HOME="$OSV_HOME" "$OSV_BIN" scan source --recursive "$SRC"
-run_capture "Gitleaks history" docker run --rm -v "$ROOT:/repo:ro" "$GITLEAKS_IMAGE" \
- git --no-banner --redact --gitleaks-ignore-path /repo/.gitleaksignore /repo
+GIT_COMMON="$(git rev-parse --path-format=absolute --git-common-dir)"
+run_capture "Gitleaks history" docker run --rm --user "$(id -u):$(id -g)" \
+ -e GIT_DIR=/git -e GIT_WORK_TREE=/repo \
+ -v "$GIT_COMMON:/git:ro" -v "$ROOT:/repo:ro" "$GITLEAKS_IMAGE" \
+ git --no-banner --redact --log-opts="--all --full-history --diff-merges=first-parent" --gitleaks-ignore-path /repo/.gitleaksignore /repo
run_capture "Semgrep OWASP/SAST" docker run --rm -v "$SRC:/src:ro" "$SEMGREP_IMAGE" \
semgrep scan --metrics=off --config=p/javascript --config=p/typescript --config=p/owasp-top-ten --error /src
@@ -141,4 +145,4 @@ else
printf '%-28s %s\n' "OWASP ZAP baseline" SKIPPED
fi
-echo "security: ULTIMATE PASS"
+echo "security: selected lanes completed; review every PASS/SKIPPED status above"
diff --git a/scripts/test-features.mjs b/scripts/test-features.mjs
new file mode 100644
index 00000000..b3f89a92
--- /dev/null
+++ b/scripts/test-features.mjs
@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Run each test area in a separate Vitest process; never call an untested slice PASS.
+import { classifyFeatureResult } from "./lib/feature-test-result.mjs";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+if (args.length && (args.length !== 2 || args[0] !== "--output")) {
+ console.error("usage: node scripts/test-features.mjs [--output /path/to/report.json]");
+ process.exit(2);
+}
+const outputDir = mkdtempSync(join(tmpdir(), "mso-feature-tests-"));
+chmodSync(outputDir, 0o700);
+const output = args.length ? resolve(args[1]) : join(outputDir, "summary.json");
+const git = spawnSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+ cwd: root, encoding: "utf8",
+});
+if (git.status !== 0) throw new Error("Cannot enumerate repository test files");
+const allFiles = [...new Set(git.stdout.split("\0").filter(Boolean))];
+const tests = allFiles.filter((file) => /\.test\.(ts|tsx)$/.test(file)
+ && !file.split("/").some((part) => part.startsWith("zz-")));
+const groups = new Map();
+function groupFor(file) {
+ const parts = file.split("/");
+ if (file.startsWith("frontend/slices/")) return parts.slice(0, 3).join("/");
+ if (file.startsWith("lib/")) return parts.length > 2 ? parts.slice(0, 2).join("/") : "lib/root";
+ if (file.startsWith("app/api/v1/")) return parts.slice(0, 4).join("/");
+ if (file.startsWith("app/api/")) return parts.slice(0, 3).join("/");
+ if (file.startsWith("app/")) return parts.slice(0, 2).join("/");
+ if (file.startsWith("scripts/")) return parts.length > 2 ? parts.slice(0, 2).join("/") : "scripts/root";
+ return parts.length > 1 ? parts[0] : "root";
+}
+for (const file of tests) {
+ const group = groupFor(file);
+ groups.set(group, [...(groups.get(group) ?? []), file]);
+}
+const untestedSlices = readdirSync(join(root, "frontend/slices"), { withFileTypes: true })
+ .filter((item) => item.isDirectory() && !groups.has(`frontend/slices/${item.name}`))
+ .map((item) => item.name).sort();
+const report = {
+ revision: spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).stdout.trim(),
+ startedAt: new Date().toISOString(), testFiles: tests.length,
+ scope: "Repository unit/integration contracts, not live third-party or complete UI acceptance",
+ untestedSlices, groups: [],
+};
+let failed = false;
+for (const [name, files] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+ const basename = name.replaceAll("/", "-");
+ const resultFile = join(outputDir, `${basename}.json`);
+ const started = Date.now();
+ const result = spawnSync(join(root, "node_modules/.bin/vitest"), [
+ "run", ...files.sort(), "--maxWorkers=2", "--reporter=json", `--outputFile=${resultFile}`,
+ ], { cwd: root, encoding: "utf8", timeout: 240_000, maxBuffer: 10 * 1024 * 1024,
+ env: { ...process.env, CI: "1", NO_COLOR: "1" } });
+ let parsed = {};
+ try { parsed = JSON.parse(readFileSync(resultFile, "utf8")); } catch { /* reported as failure */ }
+ const row = {
+ name, files: files.length, total: parsed.numTotalTests ?? 0,
+ passed: parsed.numPassedTests ?? 0, failed: parsed.numFailedTests ?? 0,
+ skipped: (parsed.numPendingTests ?? 0) + (parsed.numTodoTests ?? 0),
+ status: classifyFeatureResult(result.status, parsed),
+ durationMs: Date.now() - started,
+ };
+ if (row.status === "FAIL") {
+ failed = true;
+ writeFileSync(join(outputDir, `${basename}.log`), `${result.stdout ?? ""}\n${result.stderr ?? ""}`, { mode: 0o600 });
+ }
+ report.groups.push(row);
+ writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+ console.log(`${row.status} ${name}: ${row.passed}/${row.total} tests, ${row.skipped} skipped (${files.length} files)`);
+}
+report.finishedAt = new Date().toISOString();
+report.success = !failed && report.groups.every((row) => row.status === "PASS");
+report.incomplete = !failed && !report.success;
+report.totals = report.groups.reduce((sum, row) => ({
+ total: sum.total + row.total, passed: sum.passed + row.passed,
+ failed: sum.failed + row.failed, skipped: sum.skipped + row.skipped,
+}), { total: 0, passed: 0, failed: 0, skipped: 0 });
+writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+console.log(`No colocated unit tests (not a PASS): ${untestedSlices.join(", ") || "none"}`);
+console.log(`Report: ${output}`);
+console.log(`Private diagnostics: ${outputDir}`);
+console.log(`Evidence: ${failed ? "FAIL" : report.incomplete ? "INCOMPLETE (skipped tests)" : "PASS"}`);
+process.exit(failed ? 1 : report.incomplete ? 2 : 0);
diff --git a/scripts/verify-build.sh b/scripts/verify-build.sh
index cc8274cd..d3aaccaa 100755
--- a/scripts/verify-build.sh
+++ b/scripts/verify-build.sh
@@ -28,7 +28,9 @@ TMP="$(mktemp -d)" # 0700
trap 'rm -rf "$TMP"' EXIT
git -C "$REPO" archive HEAD | tar -x -C "$TMP"
-cp -a "$REPO/node_modules" "$TMP/node_modules"
+# Copy the contents, resolving a worktree's top-level dependency symlink only.
+mkdir "$TMP/node_modules"
+cp -a "$REPO/node_modules/." "$TMP/node_modules/"
cd "$TMP"
# nice/ionice: this box also serves prod. A build gate must not starve :4005.
diff --git a/scripts/worktree-gates.test.ts b/scripts/worktree-gates.test.ts
new file mode 100644
index 00000000..2cbed90c
--- /dev/null
+++ b/scripts/worktree-gates.test.ts
@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+function fixture(script: string) {
+ const root = mkdtempSync(path.join(os.tmpdir(), "mso-worktree-gate-")); roots.push(root);
+ const repo = path.join(root, "repo"); mkdirSync(path.join(repo, "scripts"), { recursive: true });
+ copyFileSync(path.join(process.cwd(), "scripts", script), path.join(repo, "scripts", script));
+ const git = (...args: string[]) => {
+ const result = spawnSync("git", args, { cwd: repo, encoding: "utf8" });
+ expect(result.status, result.stderr).toBe(0); return result.stdout.trim();
+ };
+ git("init", "-q"); git("add", "scripts");
+ git("-c", "user.name=Test", "-c", "[email protected]", "commit", "-qm", "fixture");
+ return { root, repo, git };
+}
+
+describe("isolated worktree release guards", () => {
+ it("installs the shared hook from a linked worktree whose .git is a file", () => {
+ const { root, repo, git } = fixture("gates.sh"); const work = path.join(root, "linked");
+ git("worktree", "add", "-qb", "linked-test", work);
+ expect(statSync(path.join(work, ".git")).isFile()).toBe(true);
+ const run = spawnSync("bash", ["scripts/gates.sh", "--install"], { cwd: work, encoding: "utf8" });
+ expect(run.status, run.stderr).toBe(0);
+ const hook = path.join(repo, ".git/hooks/pre-push");
+ expect(readFileSync(hook, "utf8")).toContain("scripts/gates.sh");
+ expect(statSync(hook).mode & 0o111).not.toBe(0);
+ });
+
+ it("builds a committed archive with copied dependency contents and no local secrets", () => {
+ const { root, repo } = fixture("verify-build.sh");
+ const modules = path.join(root, "modules"); mkdirSync(path.join(modules, ".bin"), { recursive: true });
+ writeFileSync(path.join(modules, ".bin/next"), `const fs=require('node:fs'); if(fs.lstatSync('node_modules').isSymbolicLink()) throw Error('outside-root symlink'); if(fs.existsSync('.env.local')) throw Error('secret copied'); console.log('isolated build fixture passed');`);
+ symlinkSync(modules, path.join(repo, "node_modules"), "dir");
+ writeFileSync(path.join(repo, ".env.local"), "# synthetic local configuration\n");
+ mkdirSync(path.join(repo, ".next")); writeFileSync(path.join(repo, ".next/keep"), "live marker");
+ const run = spawnSync("bash", ["scripts/verify-build.sh"], { cwd: repo, encoding: "utf8", timeout: 10_000 });
+ expect(run.status, run.stderr).toBe(0); expect(run.stdout).toContain("isolated build fixture passed");
+ expect(readFileSync(path.join(repo, ".next/keep"), "utf8")).toBe("live marker");
+ expect(existsSync(path.join(repo, ".env.local"))).toBe(true);
+ });
+});