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.

docs(features): define modular external feature contract

Rahmanc0517861ed39
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index d9e24831..95cbf8aa 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -22,6 +22,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Docs**
+- `features` define modular external feature contract
- `release` record Windows taskbar fidelity
## 2026-09-26
diff --git a/docs/EXTERNAL-FEATURE-AUDIT-2026-09-27.md b/docs/EXTERNAL-FEATURE-AUDIT-2026-09-27.md
new file mode 100644
index 00000000..8cbed792
--- /dev/null
+++ b/docs/EXTERNAL-FEATURE-AUDIT-2026-09-27.md
@@ -0,0 +1,80 @@
+# External feature registry audit — 2026-09-27
+
+> **Historical source audit.** Baseline: `330d0cb45539088e0cd9add712c408c38ef91181`.
+> This review examines source boundaries; it does not reproduce a browser exploit or
+> certify every third-party deployment. Target rules: [contract v1](./EXTERNAL-FEATURE-CONTRACT.md).
+> Deliverable: architecture contract and migration backlog, not an implemented plugin engine.
+
+## Inventory and findings
+
+| ID / priority | Evidence at baseline | Finding and required change |
+|---|---|---|
+| A01 / P1 | [ShellManifest and FeatureDescriptor](../frontend/slices/appshell/registry/types.ts), [AppDescriptor](../frontend/slices/appshell/lib/types.ts) | Good dependency injection seam, but descriptors contain React components/functions and no schema version. Keep executable descriptors internal; add a validated serializable definition plus resolver. |
+| A02 / P1 | [App registry](../frontend/slices/appshell/lib/registry.tsx), [composition](../app/os-root.tsx) | Built-ins and dynamic apps concatenate; Map registration uses last ID wins. Reject collisions in the assembled snapshot, including slugs and aliases. This is a collision risk at the assembly boundary; upstream creation constraints were not exhaustively audited. |
+| A03 / P1 | [Shell registry](../frontend/slices/appshell/registry/shells.tsx), [registration](../frontend/slices/appshell/registry/register-shells.tsx) | registerShell is extensible in shape, but ShellId, display order and desktop/mobile preference allowlists are fixed. Derive enumeration and preference validation from reviewed descriptors before advertising dynamic shells. |
+| A04 / P1 | [Feature slots](../frontend/slices/appshell/registry/feature-registry.tsx), [provider composition](../frontend/slices/appshell/provider/app-shell.tsx) | Slots render in manifest order; no slot cardinality/dependency validation here. Feature providers wrap the entire desktop. Live provider changes can remount descendants; define reload/cleanup and local failure boundaries before dynamic activation. |
+| A05 / P0 before external catalogs | [Runtime manifest](../frontend/slices/app-store/components/runtime-app-types.ts), [renderer](../frontend/slices/app-store/components/runtime-app.tsx), [console](../frontend/slices/app-store/components/app-console.tsx) | One string entry means URL or host command. Execution requires Run and the existing exec API; this is not evidence of unauthenticated execution. Imported feature definitions must instead reference reviewed adapters/actions. Preserve explicit owner custom scripts as a separate advanced capability. |
+| A06 / P0 before external catalogs | [Runtime HTML renderer](../frontend/slices/app-store/components/runtime-app.tsx), [n8n admission](../lib/host/workflow-embeds-api.ts), [cookie policy](../lib/surfaces/cookie-policy.ts) | Runtime HTML accepts HTTP(S) entry directly with scripts + same-origin sandbox and does not call the reviewed cookie/origin policy. n8n has a separate stricter path. Unify admission for external frames; test actual CSP, cookies and redirects before calling this exploitable. |
+| A07 / P1 | [Surface contract](../lib/contracts/surface-app.ts), [config](../lib/surfaces/config.ts), [owner mutation](../lib/surfaces/manage.ts) | Already dynamic per request, bounded and owner-revision-guarded on save. Yet unversioned; placements limited to workflows/n8n/mcp-page, HTTPS-only; parse drops invalid rows. Add version migration and diagnostics without weakening Page approval. |
+| A08 / P1 | [Managed types](../lib/managed-apps/types.ts), [catalog](../lib/managed-apps/catalog.ts), [host support](../lib/managed-apps/host-compatibility.ts) | Three static IDs, declared Docker/systemd backends and live preflight are useful foundations. Host needs, adapter versions, bindings and contribution references are not a generic manifest yet. Preserve reviewed installers while extracting metadata. |
+| A09 / P1 | [Managed origin](../lib/managed-apps/origin.ts), [external panel](../frontend/slices/managed-apps/feature-app.tsx) | Managed frames already use a separate app namespace and refuse same-origin fallback. Origin template uses NEXT_PUBLIC configuration, unlike the runtime SurfaceApp registry. Dynamic routing/CSP must be added server-side before promising no-rebuild managed origins. |
+| A10 / P2 | [Installed app resolver](../frontend/slices/app-store/lib/use-installed-apps.ts) | Descriptor memo signature omits source although the resolved manifest reads it. Future revision-based snapshots avoid stale metadata; preserve stable component identity to prevent remount churn. |
+| A11 / P1 | [Project Plugin manifest](../lib/plugins/manifest.ts), [extension taxonomy](./ARCHITECTURE.md) | Existing strict versioned plugin validator is a useful pattern, but that package owns project skills/MCP, not shell/runtime authority. Do not overload it with install commands or embed grants. |
+| A12 / P1 | [n8n panel](../frontend/slices/n8n/components/n8n-embed-panel.tsx), [Managed jobs](../lib/managed-apps/types.ts) | Frame loading and service/job readiness are different observations. Use common readiness reasons and receipts; iframe onLoad alone cannot prove editor login or health. |
+
+P0 here means a prerequisite for accepting externally supplied catalogs, not a verified
+critical vulnerability in the deployed installation. Existing safeguards must remain in place.
+
+## Decisions
+
+1. Use one portable feature definition identity with separate server-owned binding/grant/state.
+ Generate presentation projections from it; do not merge credentials, MCP authority,
+ shell preferences and service ownership into a single writable registry.
+2. Support external products as apps, views inside other apps, API-only integrations,
+ or managed runtimes. Those contributions can coexist without forcing every product
+ to implement every lifecycle operation.
+3. Keep AppShell generic. Consumer adapters supply MSO policy through existing seams.
+4. Runtime JSON may configure reviewed implementations; it cannot load arbitrary JS,
+ create shell providers or introduce a new privileged installer.
+5. Domain is optional. Hosting on a capable tablet is distinct from using a mobile shell.
+ Origin isolation and backend capability still determine which contributions can run.
+6. Preserve existing feature IDs, routes, saved layouts and connection identities during migration.
+7. Do not claim Orca/Termul adapters until their exact upstream identities are established.
+
+## Ordered implementation plan
+
+| Phase | Work and ownership | Exit evidence |
+|---|---|---|
+| 0 — Contract (this change) | Document envelope, authority, embedded-view and shell contracts; classify source gaps | Linked contract and audit; documentation/architecture checks pass |
+| 1 — Admission | lib/contracts owns wire DTO/schema; lib/surfaces owns reviewed frame admission; add collision/reason diagnostics | Negative schema/collision/cookie/origin tests; legacy apps keep working; no imported command execution |
+| 2 — Registry snapshots | Consumer resolver produces AppDescriptor/FeatureDescriptor; server stores revisioned bindings/grants; reviewed shell metadata drives enumeration | Multiple bindings, atomic activation, missing dependency/cycle refusal; migration keeps routes/layout; failed activation retains previous snapshot |
+| 3 — External views | n8n and Managed App presentation consume the shared resolved-view contract; retain separate proxy versus direct-frame trust paths | Mobile/desktop login and direct-open tests; CSP/cookie/redirect rejection; disabled/revoked view stops bridge access |
+| 4 — Lifecycle adapters | Move Hermes/OpenClaw/9Router metadata behind reviewed adapter descriptors; Integrations references replace portable secrets | Backend preflight, per-binding ownership/idempotency, interrupted job reconciliation, backup/restore and uninstall-preserves-data tests |
+| 5 — Shell features | Slots gain cardinality/order/surface/dependency rules; add local failure containment and controlled provider reload | Shell switching, focus/keyboard/touch, disable/re-enable and recovery tests; one broken feature does not blank shell |
+| 6 — Catalog expansion | Add reviewed n8n lifecycle and other identified upstream adapters, then host/device portability trials | Real install/update/restart/restore on each claimed host/backend; independently report unsupported combinations |
+
+Do not gate phase 1 on a full marketplace or multi-host scheduler. First migrate existing
+definitions and consumers. Multi-host placement can later reuse hostRef and capability
+requirements without introducing a second registry.
+
+## Migration and rollback procedure
+
+- Export the old configuration/layout version and preserve server registry bytes before conversion.
+- Give built-in definitions stable IDs; namespace new imported IDs and detect slug aliases.
+- Convert SurfaceApp entries into endpoint bindings plus their existing approved placements.
+ Legacy missing placements retain only their current reviewed Page semantics; do not broaden access.
+- Convert local App Store HTML entries into unapproved presentation candidates; require endpoint
+ review before granting a trusted frame. Keep custom commands in the explicit owner-script path.
+- Preserve managed runtime ownership; detection of a service does not adopt it.
+- Stage a full converted snapshot, validate, then atomically change the active revision.
+ Failed conversion keeps the prior runtime available and returns per-entry diagnostics.
+- Roll back configuration using the preserved snapshot/revision. Runtime/data migration rollback
+ remains adapter-specific and must be verified independently.
+- Remove old tables only after consumers and parity tests use the canonical projection.
+
+## Required implementation artifacts
+
+Future implementation PRs must include: the versioned schema and validator, reviewed adapter
+registry, definition/binding resolver, migration fixtures, permission/embedding negative tests,
+operational receipts, compatibility diagnostics and UI/API/CLI/MCP parity notes where applicable.
+The contract's JSON example is intentionally illustrative; no runtime accepts that format yet.
diff --git a/docs/EXTERNAL-FEATURE-CONTRACT.md b/docs/EXTERNAL-FEATURE-CONTRACT.md
new file mode 100644
index 00000000..5ff11912
--- /dev/null
+++ b/docs/EXTERNAL-FEATURE-CONTRACT.md
@@ -0,0 +1,128 @@
+# External feature contract v1
+
+> **Design contract, 2026-09-27.** Normative requirements for new modular feature work.
+> This document does not claim a v1 loader or schema validator is implemented.
+> Current implementation and gaps: [registry audit](./EXTERNAL-FEATURE-AUDIT-2026-09-27.md).
+> Existing authority: [architecture](./ARCHITECTURE.md), [Managed Apps](./MANAGED-APPS.md),
+> [Integrations](./INTEGRATIONS.md), [platforms](./PLATFORMS.md).
+
+## 1. Terms and authority
+
+An external product may contribute several features. Installing a feature in the workspace does not mean installing that product's runtime on the machine.
+
+| Object | Owns | Never grants |
+|---|---|---|
+| FeatureDefinition | Portable identity, presentation, requirements and adapter references | Credentials, host execution or origin trust |
+| FeatureBinding | Exact installation/project/host, selected connection and endpoint references | Permission to adopt an existing service |
+| FeatureGrant | Owner-reviewed origin, action, placement and permission policy | Arbitrary executable code |
+| FeatureState | Desired enablement, observed readiness, job and health evidence | Authority inferred from browser storage |
+| Reviewed adapter | Bundled executable implementation and typed inputs | Permission beyond the caller's live policy |
+
+Keep these records separate. A canonical definition resolves into AppDescriptor, FeatureDescriptor and managed-runtime views; it must not replace their security authorities. Project Plugin, Skill, Integration and MCP retain their existing meanings.
+
+## 2. Portable definition envelope
+
+Proposed wire format: JSON, schema identifier `urn:mso:feature:v1`. Reject unknown schema majors, unknown keys and malformed fields before any side effect. v1 maximums: 64 KiB per definition, 128 contributions, 32 dependencies, 128 action references. Identifiers use lowercase letters, digits and hyphens, at most 64 characters. Existing built-in IDs/slugs remain stable through explicit migration aliases.
+
+| Required field | Contract |
+|---|---|
+| schemaVersion | Integer `1`; independent from product and adapter versions |
+| id | Globally unique feature ID within the installation; duplicate registration is an error |
+| version | Semantic version of the definition; prerelease/build suffixes supported |
+| metadata | Plain-text title, description, publisher, optional reviewed homepage; no raw HTML |
+| compatibility | Supported MSO and adapter API version ranges; unknown/incompatible fails closed |
+| dependencies | Required/optional feature IDs with version ranges; cycles and missing required dependencies fail |
+| contributions | Discriminated list described below; each has a unique local ID |
+| actions | References to registered typed capabilities; empty is valid |
+| requirements | Required/optional host and client capabilities with explicit constraints |
+
+Executable adapters, component loaders, icon keys, action IDs and slots are resolved from reviewed code registries. No import URL, JavaScript source, shell command, environment variables, credential values or arbitrary filesystem path belongs here. Publisher text and a digest alone do not establish trust; activation requires a reviewed local definition or verified package provenance under an explicit installation policy.
+
+### Contribution variants
+
+| kind | Required payload | Runtime rules |
+|---|---|---|
+| app | slug, title, iconKey, renderer | Opens an AppShell window; renderer is native, external-frame, external-tab or api-only |
+| shell-feature | slots, componentKey, optional providerKey | Trusted bundled code only; provider topology is fixed for the current shell session |
+| shell | surface, componentKey, supportedSlots, windowed | Trusted bundled chrome; reuses window store, routing and accessibility services |
+| managed-runtime | adapterKey, backend alternatives, lifecycle action refs | Server adapter controls installation; host requirements checked live |
+| embedded-view | targetFeatureId, placement, renderer | Adds an external view inside an existing feature, e.g. n8n inside Workflows |
+
+Each renderer is a tagged object. `native` requires componentKey; `external-frame` and `external-tab` require endpointRef; `api-only` has no window component. No implicit fallback from missing native code to executing a URL or command. Frames declare a sandboxProfileKey and fallback policy. A target feature explicitly accepts an embedded-view placement; a definition cannot invent new shell slots or attach to privileged chrome.
+
+### Illustrative external n8n definition
+
+This is a target-format example, not input for today's SurfaceApp registry. The named renderer/profile implementations must be reviewed before activation.
+
+```json
+{
+ "schemaVersion": 1,
+ "id": "n8n-editor",
+ "version": "1.0.0",
+ "metadata": {
+ "title": "n8n editor",
+ "description": "Open a connected n8n editor",
+ "publisher": "installation-owner"
+ },
+ "compatibility": { "mso": ">=0.2.23 <1.0.0", "adapterApi": "^1.0.0" },
+ "dependencies": [],
+ "contributions": [{
+ "id": "editor",
+ "kind": "embedded-view",
+ "targetFeatureId": "workflows",
+ "placement": "editor",
+ "renderer": {
+ "kind": "external-frame",
+ "endpointRef": "editor",
+ "sandboxProfileKey": "external-editor-v1",
+ "fallback": "external-tab"
+ }
+ }],
+ "actions": [],
+ "requirements": { "host": [], "client": ["browser.iframe"] }
+}
+```
+
+## 3. Binding and installation state
+
+A FeatureBinding has bindingId, featureId, definitionVersion, revision, scope (host or exact project), hostRef, ownership (managed or connected), endpoint references and explicit connection references (credential owner → provider → named connection). Endpoints are installation state, never maintainer domains baked into portable source. Support multiple bindings of one definition without ID, storage or port collisions. The example above uses connected ownership and needs no lifecycle adapter.
+
+A browser receives only a sanitized resolved view. Server persistence is owner-local, atomic, revision-guarded and redacted. Browser storage contains layout/preferences only. Changing an origin, credential owner, adapter or permission invalidates the old approval. Removing a connection revokes dependent action readiness; do not silently select another.
+
+State axes are independent: installed definition, enabled presentation, owned runtime, runtime health, endpoint reachability and authorization. Use explicit reason codes such as unsupported_host, missing_connection, origin_blocked, dependency_missing, version_incompatible and runtime_unhealthy. A hidden app may still have a running service.
+
+## 4. Host lifecycle contract
+
+Reviewed adapters expose describe, probe, plan and execute through existing bounded host APIs. Plans identify target host/binding, ownership, backend, version, resource needs, changes, data impact, required permission and rollback/compensation before execution. Recheck authorization, revision, actual host requirements and service ownership at execution. Backend alternatives must list OS/runtime, CPU, supervisor/container support, RAM, free disk, ports and required tooling. Unknown measurements are reported, never assumed passed. Client OS and host runtime are distinct: a tablet may host MSO, but a visual shell selection does not make Docker/systemd available.
+
+Install, start, stop, restart, update, backup, restore and uninstall are separate capabilities. Unsupported operations return a reason; an adapter need not implement all of them. Connected services default to probe/open only; management requires explicit adoption. Long operations have jobId, idempotency key, per-binding lock, bounded redacted logs, progress, timeout, terminal outcome and postcondition evidence. Duplicate requests must not repeat side effects. On interruption, reconcile observed state before retry; do not claim cancellation if the child continues running.
+
+Updates pin reviewed artifacts/digests, check compatibility and backup before state migration. Restore validates ownership, backup format/version and target compatibility. Uninstall preserves user data by default; purge is a separately authorized operation. A rollback is claimed only for steps that actually support it; irreversible migrations need a restore path and explicit data-loss implications.
+
+## 5. Embedding and communication contract
+
+Three distinct trust paths remain explicit:
+- Native components are reviewed MSO code.
+- Direct external frames must be outside cockpit cookie scope and use approved exact origins.
+- Managed proxy frames may use MSO gateway authentication, but the proxy must strip cockpit
+ credentials upstream and restrict the app host to that app's routes. They never expose the cockpit.
+
+Resolve endpoints server-side with exact origin/path and redirect policy. Server-side probes/proxies also enforce SSRF and bounded network policy, including DNS rebinding checks. No wildcard origin approval, same-origin vendor fallback, token in URL or secret in manifest. Different ports on one hostname do not isolate cookies. IP/LAN/no-domain access is valid; if safe framing cannot be established, return an explained external-tab or management-only view. Existing direct SurfaceApp admission currently requires HTTPS; HTTP/IP support is separate implementation work, not permission to weaken that gate.
+
+Sandbox/Permissions Policy is selected from reviewed profiles with minimum capabilities. Preserve CSP and upstream framing/auth rules. Use no-referrer and noopener links. A frame load event proves navigation only, not authenticated readiness or healthy service. Show loading, timeout, blocked, login-required and direct-open fallback states. Do not remove vendor frame restrictions merely to make an editor appear embedded.
+
+Optional bridge v1 uses explicit messages: ready, resize, theme, locale, navigate-request and capability-request. Validate exact event.origin AND event.source, protocol version, binding/session nonce, requestId, payload schema and size/rate limits. Reply only to the exact approved origin. Reject replay, stale/unmounted sessions and unknown messages. No wildcard targetOrigin, eval or generic exec bridge. Every capability-request passes the server's live permission/connection policy; a handshake or user gesture never supplies authority. Unsupported bridge = no bridge. An opaque-origin srcDoc app receives no privileged bridge.
+
+## 6. Shell and activation contract
+
+Slot definitions declare supported surfaces, cardinality (single/multiple), ordering and fallback. Single-slot collisions fail before activation; multi-slot order is priority then stable ID. Apps declare single/multi-window policy, payload schema, default size and deep-link validation. Menus/shortcuts reference registered actions; global shortcut conflicts are diagnosed. Shell chrome reuses the existing store and supports keyboard, focus restoration, close guards, touch, reduced motion and narrow/landscape layouts.
+
+Validate definition → resolve dependencies/adapters → evaluate binding/grants → stage complete registry snapshot → activate atomically. Keep the last valid snapshot on failure. Discovery never installs, enables or executes. Optional dependency failure degrades explicitly. Disabling/removing a feature closes its views through close guards, revokes bridge sessions and cleans subscriptions/timers. It does not stop/purge a managed service. Provider topology changes require a controlled shell reload with saved layout until a tested provider lifecycle exists. Each app/slot needs a local error boundary so failures do not blank the entire shell. Essential navigation/recovery cannot be disabled without a safe alternative.
+
+Dynamic declarative configuration can activate without a rebuild. New native components, shell chrome and lifecycle adapters require a reviewed code release in v1. Remote executable modules are outside v1. Do not describe lazy loading as hot installation.
+
+## 7. Acceptance and migration
+
+All surfaces use the same resolved binding and capability semantics. API/CLI/MCP retain their own authentication and transport schemas; do not auto-publish tools from untrusted JSON. Contract tests cover invalid schemas, duplicate IDs/slugs, dependency cycles, revoked grants, concurrent revision conflict, forged bridge events, cookie/redirect isolation and permission denial. Operational tests cover interrupted install/update, rollback/restore, preserved uninstall data, multiple bindings and unsupported host diagnostics. Browser tests cover shells, mobile, blocked frames, login fallback, feature failure and disable/re-enable without state loss.
+
+Implement in the ordered phases and measurable gates in the [audit](./EXTERNAL-FEATURE-AUDIT-2026-09-27.md). Until each gate is proven, report it as pending rather than claiming fully dynamic plugins.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 545f9525..0dc17378 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,13 @@
+## 2026-09-27 — External feature contract and registry audit
+
+Defined the v1 design contract for portable feature definitions, separate installation
+bindings and grants, embedded views, reviewed adapters, shell slots and lifecycle
+verification. Audited the existing AppShell, runtime App Store, SurfaceApp and Managed
+App registries against baseline 330d0cb4, with twelve findings and ordered migration
+gates. This documentation does not implement a dynamic plugin loader or broaden
+existing execution/embed permissions. The documentation map explicitly separates
+the proposed contract from current runtime references.
+
## 2026-09-27 — Managed app host compatibility preflight
Managed app definitions now declare the installer backends they actually support:
diff --git a/docs/README.md b/docs/README.md
index 5c8f7df3..84555ba0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -75,6 +75,12 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`../CLAUDE.md`](../CLAUDE.md) | Repository/operator implementation rules |
| [`../skills/README.md`](../skills/README.md) | Skill catalog, trust and discovery semantics |
+## Design contracts awaiting implementation
+
+| Document | Status |
+|---|---|
+| [`EXTERNAL-FEATURE-CONTRACT.md`](./EXTERNAL-FEATURE-CONTRACT.md) | v1 target contract for modular shell/external features; implementation status is explicit |
+
## Generated/current records
| Document | Source |
@@ -92,6 +98,7 @@ source comments. They are **not current implementation contracts**.
| Document | Status |
|---|---|
+| [`EXTERNAL-FEATURE-AUDIT-2026-09-27.md`](./EXTERNAL-FEATURE-AUDIT-2026-09-27.md) | Registry/manifest/embed source audit at 330d0cb4; migration phases remain pending |
| [`AUDIT-2026-08-24.md`](./AUDIT-2026-08-24.md) | Fable/Ultracode + dynamic security audit at its named commit; includes reproduced findings and release remediation |
| [`AUDIT-2026-06-11.md`](./AUDIT-2026-06-11.md) | Archived audit at its named date; later fixes changed many findings |
| [`SHELL-FIDELITY-PLAN.md`](./SHELL-FIDELITY-PLAN.md) | Historical design backlog/baseline; current shell design lives in code + architecture |