Skip to content

armgit / mso

Public Imported from GitHub
0

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

feat(app-store): read bounded MANEF catalog metadata

Rahman779bb47aef6b
diff --git a/app/api/v1/app-catalog/route.ts b/app/api/v1/app-catalog/route.ts
new file mode 100644
index 00000000..ba273f38
--- /dev/null
+++ b/app/api/v1/app-catalog/route.ts
@@ -0,0 +1,15 @@
+import { NextResponse } from "next/server";
+import { getSessionContext } from "@/lib/auth/require-session";
+import { roleAtLeast } from "@/lib/auth/roles";
+import { loadAppCatalog } from "@/lib/host/app-catalog";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+const headers = { "Cache-Control": "no-store, private" };
+
+export async function GET() {
+ const context = await getSessionContext();
+ if (!context?.session.device_id) return NextResponse.json({ error: "unauthorized" }, { status: 401, headers });
+ if (!roleAtLeast(context.role, "owner")) return NextResponse.json({ error: "owner_required" }, { status: 403, headers });
+ return NextResponse.json(await loadAppCatalog(), { headers });
+}
diff --git a/bin/mso b/bin/mso
index fa5f4968..f46aaa99 100755
--- a/bin/mso
+++ b/bin/mso
@@ -63,7 +63,7 @@
#
# Apps
# apps App-store runtime apps
-# mapp * Managed apps; shell-list / shell-save <JSON|@file> for connected apps
+# mapp * Managed apps; catalog / shell-list / shell-save <JSON|@file> for connections
# term * Interactive PTY sessions (open | input | resize | stream | close)
#
# AI + state
diff --git a/docs/CLI.md b/docs/CLI.md
index 994d832a..aa21b70b 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -103,7 +103,7 @@ Commands:
Apps
apps App-store runtime apps
- mapp * Managed apps; shell-list / shell-save <JSON|@file> for connected apps
+ mapp * Managed apps; catalog / shell-list / shell-save <JSON|@file> for connections
term * Interactive PTY sessions (open | input | resize | stream | close)
AI + state
diff --git a/docs/CONNECTED-APPS.md b/docs/CONNECTED-APPS.md
index ae71b537..5e4fdd12 100644
--- a/docs/CONNECTED-APPS.md
+++ b/docs/CONNECTED-APPS.md
@@ -46,6 +46,12 @@ The existing Owner-only POST and `mso mapp shell-save @request.json` also accept
Binding mode is explicit: the UI initializes it from presentation and lets the Owner choose a separate tab. Import reuses the same revision lock, duplicate-ID checks, cookie isolation, capacity limits and explicit confirmation as manual connections. Edits preserve the original manifest while changing instance metadata. Disconnect removes the binding and its manifest copy, leaving the external service untouched. Existing entries require no migration.
+## MANEF catalog
+
+The public `https://manef.dev/catalog/v1.json` is a versioned list of metadata. The Owner's App Store reads it through `GET /api/v1/app-catalog`, which never sends browser credentials to MANEF. The server pins the URL, rejects redirects and invalid or oversized documents, limits entries to 32, caches a validated response for 15 minutes and may show that response for up to 24 hours during an outage. A cold outage leaves the locally reviewed Managed Apps visible.
+
+Catalog managed entries can only reference the existing Hermes, OpenClaw and 9Router adapters. Selecting one opens its existing setup and host preflight. Connected entries reuse the portable manifest validator and the Owner's review form: the operator supplies an instance ID and URL before a shell connection is saved. The catalog cannot provide an installer, endpoint, command, credential or grant. The n8n entry is a connection template for an already running service.
+
## Remaining migration
-This is the first implemented registry path, not the complete [external feature target contract](./EXTERNAL-FEATURE-CONTRACT.md). Native shell features still ship with MSO. The remote manef.dev catalog, generic install recipes, generic domain provisioning, feature extraction and independent package releases remain future work. Connecting an arbitrary URL does not imply an installer, health check, SSO or AI tool grant. Existing Managed Apps retain their separate reviewed runtime and proxy boundaries.
+This implements a bounded remote discovery path, not the complete [external feature target contract](./EXTERNAL-FEATURE-CONTRACT.md). Native shell features still ship with MSO. Generic install recipes, generic domain provisioning, feature extraction and independent package releases remain future work. Connecting an arbitrary URL does not imply an installer, health check, SSO or AI tool grant. Existing Managed Apps retain their separate reviewed runtime and proxy boundaries.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 91b29dc6..b08f3077 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,7 @@
+## 2026-09-28 — Bounded MANEF application catalog
+
+Added a versioned metadata catalog to manef-web and an Owner-only MSO reader. The site PR merged, but Vercel blocked its production deployment; live publication remains pending hosting access. The remote list may order existing reviewed Managed App adapters or offer a portable connection template; it cannot authorize a new installer, command, URL, credential or grant. Selecting a managed entry follows its existing preflight and setup; selecting a connected entry still requires an instance address and explicit Owner review. The server pins the catalog URL, bounds and validates the whole response, caches a valid copy for a short outage and leaves local installers available without the site. This completes remote discovery for this profile while generic installation recipes, domains and independent package releases remain separate work.
+
## 2026-09-28 — Portable connected app manifests
Added a bounded connected-app manifest profile and Store file/paste → review → connect journey. Portable publisher/version/presentation metadata stays separate from per-instance IDs and endpoints; one definition can connect several instances. The shared validator rejects unsupported fields/versions and executable payloads in both client and server. Import uses existing Owner authority, revision locking, cookie isolation and atomic registry storage. Connection edits preserve the original manifest and disconnect never touches service data. The starter JSON and current contract document what works; the full feature loader, verified remote manef.dev catalog and generic installers remain pending. No dependency on unrelated manef-ui/manef-db is introduced.
diff --git a/frontend/slices/app-store/components/managed-apps-catalog.tsx b/frontend/slices/app-store/components/managed-apps-catalog.tsx
index 50e816bc..bb09684f 100644
--- a/frontend/slices/app-store/components/managed-apps-catalog.tsx
+++ b/frontend/slices/app-store/components/managed-apps-catalog.tsx
@@ -1,11 +1,18 @@
"use client";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
import { openWindow } from "@/features/appshell";
+import type { AppCatalogEntry } from "@/lib/contracts/app-catalog";
import type { ManagedAppView } from "@/lib/managed-apps/types";
import { Button } from "@/components/ui/button";
+import { ConnectAppForm } from "./connect-app-form";
+
+type CatalogState = { status: "remote" | "stale" | "unavailable"; entries: AppCatalogEntry[] };
export function ManagedAppsCatalog({ query }: { query: string }) {
- const [apps, setApps] = useState<ManagedAppView[]>([]), [error, setError] = useState("");
+ const [apps, setApps] = useState<ManagedAppView[]>([]);
+ const [catalog, setCatalog] = useState<CatalogState | null>(null);
+ const [selected, setSelected] = useState<Extract<AppCatalogEntry, { kind: "connected" }> | null>(null);
+ const [error, setError] = useState("");
useEffect(() => {
const controller = new AbortController();
void fetch("/api/v1/managed-apps", { cache: "no-store", signal: controller.signal }).then(async response => {
@@ -13,17 +20,43 @@ export function ManagedAppsCatalog({ query }: { query: string }) {
const data = await response.json() as { apps: ManagedAppView[] };
setApps(data.apps); setError("");
}).catch(reason => { if (!controller.signal.aborted) setError(reason instanceof Error ? reason.message : "Could not load apps."); });
+ void fetch("/api/v1/app-catalog", { cache: "no-store", signal: controller.signal }).then(async response => {
+ if (!response.ok) throw new Error("Catalog unavailable.");
+ setCatalog(await response.json() as CatalogState);
+ }).catch(() => { if (!controller.signal.aborted) setCatalog({ status: "unavailable", entries: [] }); });
return () => controller.abort();
}, []);
- return <section aria-label="Managed applications" className="space-y-3">
+
+ const managedIds = useMemo(() => catalog?.entries.filter(entry => entry.kind === "managed").map(entry => entry.id) ?? [], [catalog]);
+ const managed = apps.filter(app => (managedIds.length === 0 || managedIds.includes(app.id) || app.installed) &&
+ app.name.toLowerCase().includes(query.toLowerCase())).sort((a, b) => {
+ const left = managedIds.indexOf(a.id), right = managedIds.indexOf(b.id);
+ return (left < 0 ? managedIds.length : left) - (right < 0 ? managedIds.length : right);
+ });
+ const connected = catalog?.entries.filter((entry): entry is Extract<AppCatalogEntry, { kind: "connected" }> =>
+ entry.kind === "connected" && `${entry.manifest.title} ${entry.manifest.description}`.toLowerCase().includes(query.toLowerCase())) ?? [];
+
+ return <section aria-label="Applications from MANEF" className="space-y-3">
<h3 className="font-medium">Install and manage</h3>
+ {catalog?.status === "stale" && <p role="status" className="text-xs text-muted-foreground">Showing the last valid MANEF catalog while it is unavailable.</p>}
+ {catalog?.status === "unavailable" && <p role="status" className="text-xs text-muted-foreground">MANEF catalog is unavailable. Local reviewed installers remain available.</p>}
{error && <p role="alert" className="text-sm text-destructive">{error}</p>}
- <div className="grid gap-3 @min-[640px]:grid-cols-3">{apps.filter(app => app.name.toLowerCase().includes(query.toLowerCase())).map(app => <article key={app.id} className="min-w-0 space-y-3 rounded-xl border p-4">
+ <div className="grid gap-3 @min-[640px]:grid-cols-3">{managed.map(app => <article key={app.id} className="min-w-0 space-y-3 rounded-xl border p-4">
<h4 className="font-medium">{app.name}</h4><p className="text-xs text-muted-foreground">{app.installed ? app.state : "Not installed"}</p>
<p className="text-sm text-muted-foreground">{app.description}</p>
{app.diagnostic && <p className="text-xs text-muted-foreground">{app.diagnostic}</p>}
<Button size="sm" variant="outline" onClick={() => openWindow(app.id, app.name)}>{app.installed ? "Open and manage" : "Set up"}</Button>
</article>)}</div>
- <p className="text-xs text-muted-foreground">Setup uses the reviewed installer and checks the host before installation. Other running tools can be connected below.</p>
+ {connected.length > 0 && <div className="space-y-3">
+ <h3 className="font-medium">Connect a running tool</h3>
+ <div className="grid gap-3 @min-[640px]:grid-cols-2">{connected.map(entry => <article key={entry.manifest.id} className="min-w-0 space-y-3 rounded-xl border p-4">
+ <h4 className="font-medium">{entry.manifest.title}</h4>
+ <p className="text-sm text-muted-foreground">{entry.manifest.description}</p>
+ <p className="text-xs text-muted-foreground">MANEF catalog template · no service installed</p>
+ <Button size="sm" variant="outline" onClick={() => setSelected(entry)}>Review and connect</Button>
+ </article>)}</div>
+ </div>}
+ <p className="text-xs text-muted-foreground">Managed setup uses the reviewed installer and checks this host. Connected tools keep their own service and sign-in; a domain is optional.</p>
+ {selected && <ConnectAppForm manifest={selected.manifest} onClose={() => setSelected(null)}/>}
</section>;
}
diff --git a/lib/contracts/app-catalog.test.ts b/lib/contracts/app-catalog.test.ts
new file mode 100644
index 00000000..cede901c
--- /dev/null
+++ b/lib/contracts/app-catalog.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { APP_CATALOG_MAX_BYTES, parseAppCatalog } from "./app-catalog";
+
+const template = {
+ schema: "urn:manef:app-catalog:v1",
+ schemaVersion: 1,
+ entries: [
+ { kind: "managed", id: "hermes" },
+ { kind: "connected", manifest: {
+ schema: "urn:mso:connected-app:v1", schemaVersion: 1, id: "n8n", version: "1.0.0",
+ title: "n8n template", description: "Connect an existing instance.", publisher: "MANEF catalog", presentation: "tab",
+ } },
+ ],
+};
+
+describe("public app catalog boundary", () => {
+ it("accepts only reviewed adapter IDs and reusable connection metadata", () => {
+ expect(parseAppCatalog(JSON.stringify(template)).entries).toHaveLength(2);
+ expect(() => parseAppCatalog(JSON.stringify({ ...template, entries: [{ kind: "managed", id: "unreviewed" }] }))).toThrow("unknown managed adapter");
+ expect(() => parseAppCatalog(JSON.stringify({ ...template, entries: [{ kind: "connected", manifest: { ...template.entries[1].manifest, command: "sh install" } }] }))).toThrow("unsupported fields");
+ });
+ it("rejects collisions and unexpected authority-bearing fields", () => {
+ expect(() => parseAppCatalog(JSON.stringify({ ...template, entries: [template.entries[0], template.entries[0]] }))).toThrow("Duplicate catalog ID");
+ expect(() => parseAppCatalog(JSON.stringify({ ...template, installCommand: "curl example" }))).toThrow("unsupported fields");
+ expect(() => parseAppCatalog(JSON.stringify({ ...template, entries: [{ ...template.entries[0], endpoint: "http://127.0.0.1" }] }))).toThrow("unsupported fields");
+ });
+ it("bounds the catalog before parsing", () => {
+ expect(() => parseAppCatalog("x".repeat(APP_CATALOG_MAX_BYTES + 1))).toThrow("32 KiB");
+ });
+});
diff --git a/lib/contracts/app-catalog.ts b/lib/contracts/app-catalog.ts
new file mode 100644
index 00000000..4e913e90
--- /dev/null
+++ b/lib/contracts/app-catalog.ts
@@ -0,0 +1,54 @@
+import { validateConnectedAppManifest, type ConnectedAppManifest } from "./connected-app-manifest";
+import { MANAGED_APP_IDS, type ManagedAppId } from "@/lib/managed-apps/types";
+
+export const APP_CATALOG_URL = "https://manef.dev/catalog/v1.json";
+export const APP_CATALOG_MAX_BYTES = 32_768;
+
+export type AppCatalogEntry =
+ | { kind: "managed"; id: ManagedAppId }
+ | { kind: "connected"; manifest: ConnectedAppManifest };
+
+export type AppCatalog = {
+ schema: "urn:manef:app-catalog:v1";
+ schemaVersion: 1;
+ entries: AppCatalogEntry[];
+};
+
+function record(value: unknown, keys: string[]): Record<string, unknown> {
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Catalog entry must be an object.");
+ const candidate = value as Record<string, unknown>;
+ if (Object.keys(candidate).length !== keys.length || Object.keys(candidate).some(key => !keys.includes(key))) {
+ throw new Error("Catalog contains missing or unsupported fields.");
+ }
+ return candidate;
+}
+
+export function parseAppCatalog(raw: string): AppCatalog {
+ if (new TextEncoder().encode(raw).byteLength > APP_CATALOG_MAX_BYTES) throw new Error("Catalog exceeds 32 KiB.");
+ let input: unknown;
+ try { input = JSON.parse(raw); } catch { throw new Error("Catalog is not valid JSON."); }
+ const root = record(input, ["schema", "schemaVersion", "entries"]);
+ if (root.schema !== "urn:manef:app-catalog:v1" || root.schemaVersion !== 1) throw new Error("Unsupported catalog version.");
+ if (!Array.isArray(root.entries) || root.entries.length > 32) throw new Error("Catalog has too many entries.");
+ const ids = new Set<string>();
+ const entries: AppCatalogEntry[] = root.entries.map(value => {
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid catalog entry.");
+ const kind = (value as Record<string, unknown>).kind;
+ let entry: AppCatalogEntry;
+ if (kind === "managed") {
+ const item = record(value, ["kind", "id"]);
+ if (typeof item.id !== "string" || !(MANAGED_APP_IDS as readonly string[]).includes(item.id)) {
+ throw new Error("Catalog references an unknown managed adapter.");
+ }
+ entry = { kind: "managed", id: item.id as ManagedAppId };
+ } else if (kind === "connected") {
+ const item = record(value, ["kind", "manifest"]);
+ entry = { kind: "connected", manifest: validateConnectedAppManifest(item.manifest) };
+ } else throw new Error("Unsupported catalog entry kind.");
+ const id = entry.kind === "managed" ? entry.id : entry.manifest.id;
+ if (ids.has(id)) throw new Error("Duplicate catalog ID.");
+ ids.add(id);
+ return entry;
+ });
+ return { schema: "urn:manef:app-catalog:v1", schemaVersion: 1, entries };
+}
diff --git a/lib/host/app-catalog.test.ts b/lib/host/app-catalog.test.ts
new file mode 100644
index 00000000..a1782265
--- /dev/null
+++ b/lib/host/app-catalog.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from "vitest";
+import { APP_CATALOG_URL } from "@/lib/contracts/app-catalog";
+import { createAppCatalogLoader } from "./app-catalog";
+
+const valid = JSON.stringify({ schema: "urn:manef:app-catalog:v1", schemaVersion: 1, entries: [{ kind: "managed", id: "hermes" }] });
+const response = () => new Response(valid, { headers: { "content-type": "application/json" } });
+
+describe("MANEF catalog delivery", () => {
+ it("pins the source, omits credentials, caches success and keeps the last valid data during an outage", async () => {
+ let now = 100;
+ const fetcher = vi.fn().mockResolvedValueOnce(response()).mockRejectedValueOnce(new Error("offline")).mockRejectedValueOnce(new Error("offline"));
+ const load = createAppCatalogLoader(fetcher as typeof fetch, () => now);
+ expect((await load()).status).toBe("remote");
+ expect(fetcher).toHaveBeenCalledWith(APP_CATALOG_URL, expect.objectContaining({ credentials: "omit", redirect: "error", cache: "no-store" }));
+ expect((await load()).status).toBe("remote");
+ expect(fetcher).toHaveBeenCalledTimes(1);
+ now += 16 * 60_000;
+ expect(await load()).toMatchObject({ status: "stale", entries: [{ kind: "managed", id: "hermes" }] });
+ now += 25 * 60 * 60_000;
+ expect(await load()).toEqual({ status: "unavailable", entries: [] });
+ });
+ it("rejects oversized or non-JSON responses without exposing unvalidated entries", async () => {
+ const tooLarge = new Response("x".repeat(32_769), { headers: { "content-type": "application/json" } });
+ expect(await createAppCatalogLoader(vi.fn().mockResolvedValue(tooLarge) as typeof fetch)()).toEqual({ status: "unavailable", entries: [] });
+ expect(await createAppCatalogLoader(vi.fn().mockResolvedValue(new Response(valid, { headers: { "content-type": "text/html" } })) as typeof fetch)()).toEqual({ status: "unavailable", entries: [] });
+ });
+});
diff --git a/lib/host/app-catalog.ts b/lib/host/app-catalog.ts
new file mode 100644
index 00000000..ca6e53b6
--- /dev/null
+++ b/lib/host/app-catalog.ts
@@ -0,0 +1,65 @@
+import { APP_CATALOG_MAX_BYTES, APP_CATALOG_URL, parseAppCatalog, type AppCatalog } from "@/lib/contracts/app-catalog";
+
+const FRESH_MS = 15 * 60_000;
+const STALE_MS = 24 * 60 * 60_000;
+
+export type AppCatalogSnapshot = {
+ status: "remote" | "stale" | "unavailable";
+ entries: AppCatalog["entries"];
+};
+
+async function boundedJson(response: Response): Promise<string> {
+ if (!response.ok || !response.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
+ throw new Error("Catalog response is not JSON.");
+ }
+ const size = Number(response.headers.get("content-length"));
+ if (Number.isFinite(size) && size > APP_CATALOG_MAX_BYTES) throw new Error("Catalog is too large.");
+ if (!response.body) throw new Error("Catalog response is empty.");
+ const reader = response.body.getReader();
+ const parts: Uint8Array[] = [];
+ let total = 0;
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ total += value.byteLength;
+ if (total > APP_CATALOG_MAX_BYTES) throw new Error("Catalog is too large.");
+ parts.push(value);
+ }
+ } finally {
+ await reader.cancel().catch(() => {});
+ }
+ const bytes = new Uint8Array(total);
+ let offset = 0;
+ for (const part of parts) { bytes.set(part, offset); offset += part.byteLength; }
+ return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+
+export function createAppCatalogLoader(fetcher: typeof fetch = fetch, now: () => number = Date.now) {
+ let last: { entries: AppCatalog["entries"]; at: number } | null = null;
+ let pending: Promise<AppCatalogSnapshot> | null = null;
+ return async function load(): Promise<AppCatalogSnapshot> {
+ if (last && now() - last.at < FRESH_MS) return { status: "remote", entries: last.entries };
+ if (pending) return pending;
+ pending = (async () => {
+ try {
+ const response = await fetcher(APP_CATALOG_URL, {
+ cache: "no-store",
+ credentials: "omit",
+ redirect: "error",
+ headers: { Accept: "application/json" },
+ signal: AbortSignal.timeout(4_000),
+ });
+ const catalog = parseAppCatalog(await boundedJson(response));
+ last = { entries: catalog.entries, at: now() };
+ return { status: "remote" as const, entries: catalog.entries };
+ } catch {
+ if (last && now() - last.at < STALE_MS) return { status: "stale" as const, entries: last.entries };
+ return { status: "unavailable" as const, entries: [] };
+ } finally { pending = null; }
+ })();
+ return pending;
+ };
+}
+
+export const loadAppCatalog = createAppCatalogLoader();
diff --git a/scripts/cli/commands-runtime.sh b/scripts/cli/commands-runtime.sh
index be1edd49..c679974d 100755
--- a/scripts/cli/commands-runtime.sh
+++ b/scripts/cli/commands-runtime.sh
@@ -34,6 +34,7 @@ case "$cmd" in
mapp)
sub="${1:-list}"; shift || true
case "$sub" in
+ catalog) jget "/api/v1/app-catalog" ;;
shell-list) jget "/api/v1/shell-apps" ;;
shell-save) shell_input="${1:?JSON or @file required}"; if [ "${shell_input:0:1}" = "@" ]; then shell_input=$(cat -- "${shell_input:1}"); fi; jpost "/api/v1/shell-apps" "$shell_input" ;;
list) jget "/api/v1/managed-apps" ;;
diff --git a/scripts/cli/commands.sh b/scripts/cli/commands.sh
index 1691143a..542eebfd 100755
--- a/scripts/cli/commands.sh
+++ b/scripts/cli/commands.sh
@@ -31,7 +31,7 @@ U_channels="channels list|create --input <JSON|@file>|save <id> --revision <n> -
U_provider="provider list|show <id>|setup <provider> <user> <connection>|set <id>|rm <id>|doctor [id]|projects|zones"
U_model="model [current|list [provider]|set <provider> <model>|set <provider/model>|<model-or-ref>]"
U_agent="agent [--continue|-c|--resume|-r <latest|index|id|title>|--yolo|-yolo] | agent --oneshot <prompt> [--json] [--approve-scope read|write|exec]"
-U_mapp="mapp shell-list|shell-save <JSON|@file>|list|show|logs|backups|jobs|job <id> <jobId>|pending <id>|install|update|power <id> <act>|cancel <id> <jobId>"
+U_mapp="mapp catalog|shell-list|shell-save <JSON|@file>|list|show|logs|backups|jobs|job <id> <jobId>|pending <id>|install|update|power <id> <act>|cancel <id> <jobId>"
U_term="term open [cwd] [cols] [rows]|input <id> <text>|resize <id> <cols> <rows>|stream <id>|close <id>"
U_device="device list|pending|approve <id> [label] [--role viewer|operator|owner]|role <id> <role>|revoke <id>|revoke all --yes"
U_service="service status|start|stop|restart|logs [n]"