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(store): import portable connected app manifests

Rahman7e069847a511
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 0044501d..5ada18ed 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 → Account → About shows as “What's new”.
+## 2026-09-28
+
+**Added**
+
+- `store` import portable connected app manifests
+
## 2026-09-27
**Added**
diff --git a/docs/CONNECTED-APPS.md b/docs/CONNECTED-APPS.md
index 1c275b67..ae71b537 100644
--- a/docs/CONNECTED-APPS.md
+++ b/docs/CONNECTED-APPS.md
@@ -10,10 +10,42 @@ A subdomain is optional. HTTPS addresses can be embedded when the application pe
## Current API and lifecycle
-Owner-only `GET /api/v1/shell-apps` returns schemaVersion 1, a revision, configurability and app views. `POST` accepts schemaVersion 1, action add/update/remove, expectedRevision, confirm true, and app metadata or the removed ID. App metadata contains id, title, description, url and mode (embed/tab). Concurrent updates return conflict and require a fresh review. The CLI exposes `mso mapp shell-list` and `mso mapp shell-save @request.json`.
+Owner-only `GET /api/v1/shell-apps` returns schemaVersion 1, a revision, configurability and app views. `POST` accepts schemaVersion 1, action add/update/remove/import, expectedRevision, confirm true, and app metadata or the removed ID. App metadata contains id, title, description, url and mode (embed/tab). Concurrent updates return conflict and require a fresh review. The CLI exposes `mso mapp shell-list` and `mso mapp shell-save @request.json`.
Entries share the surface registry, its atomic locking, 16-entry/16-KiB limits and environment-managed read-only mode. Shell placement never grants MCP Page access. New shell entries cannot overwrite Workflow or Page entries. Legacy local HTML manifests must resolve to a reviewed shell connection before rendering. The shared iframe renderer is also used by n8n.
+## Portable manifest import
+
+App Store → Apps → Import manifest accepts a local JSON file or pasted JSON, up to 8 KiB. The next form shows publisher/version and asks for the instance ID and URL. Review and Connect applies the server mutation; selecting or reviewing a file has no side effect. A manifest can be reused for several installations with different instance IDs. Publisher names are self-declared, not verified provenance. Original manifest metadata is retained separately from editable connection metadata and shown after reload.
+
+The implemented connected-app profile is `urn:mso:connected-app:v1`. It is intentionally smaller than the proposed general feature definition: schemaVersion 1, id, semantic version, title, description, publisher and presentation (`embed`/`tab`). All fields are required; unknown fields and schema versions are rejected. IDs are at most 64 lowercase letters/digits/hyphens; title/publisher are at most 120 characters, description 240, version 128. Metadata is plain text. The starter file is [`templates/connected-app/manifest.json`](../templates/connected-app/manifest.json); the shared browser/server validator is `lib/contracts/connected-app-manifest.ts`.
+
+Endpoints belong to bindings and never to this portable manifest. It cannot declare commands, imports, environment variables, secrets, MCP grants, native components or shell slots. Schema v1 identifies the supported connection API; the manifest's semantic version identifies developer metadata, not the running service version. Imports do not fetch remote documents or verify package signatures, dependencies or application health.
+
+The existing Owner-only POST and `mso mapp shell-save @request.json` also accept:
+
+```json
+{
+ "schemaVersion": 1,
+ "action": "import",
+ "expectedRevision": "revision-from-shell-list",
+ "confirm": true,
+ "manifest": {
+ "schema": "urn:mso:connected-app:v1",
+ "schemaVersion": 1,
+ "id": "custom-editor",
+ "version": "1.0.0",
+ "title": "Custom editor",
+ "description": "Open a running editor",
+ "publisher": "Your project",
+ "presentation": "embed"
+ },
+ "binding": { "id": "editor-home", "url": "https://editor.example.test/", "mode": "embed" }
+}
+```
+
+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.
+
## 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.
diff --git a/docs/EXTERNAL-FEATURE-CONTRACT.md b/docs/EXTERNAL-FEATURE-CONTRACT.md
index 5ff11912..bfb54016 100644
--- a/docs/EXTERNAL-FEATURE-CONTRACT.md
+++ b/docs/EXTERNAL-FEATURE-CONTRACT.md
@@ -1,7 +1,7 @@
# 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.
+> The general v1 loader/schema below is not implemented. The narrower [connected-app manifest profile](./CONNECTED-APPS.md#portable-manifest-import) supports reviewed connections only.
> 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).
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 214b2ad6..eef330c2 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,7 @@
+## 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.
+
## 2026-09-27 — External feature contract and registry audit
## 2026-09-27 — Readable Settings action labels
diff --git a/frontend/slices/app-store/components/connect-app-form.tsx b/frontend/slices/app-store/components/connect-app-form.tsx
index 7a703d67..2ab75fc9 100644
--- a/frontend/slices/app-store/components/connect-app-form.tsx
+++ b/frontend/slices/app-store/components/connect-app-form.tsx
@@ -5,31 +5,33 @@ import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Button } from "@/components/ui/button";
import { Switch } from "@/components/ui/switch";
+import type { ConnectedAppManifest } from "@/lib/contracts/connected-app-manifest";
import type { ShellAppDefinition } from "@/lib/contracts/shell-app";
import { useShellApps } from "../lib/shell-apps";
-export function ConnectAppForm({ existing, onClose }: { existing?: ShellAppDefinition; onClose: () => void }) {
+export function ConnectAppForm({ existing, manifest, onClose }: { existing?: ShellAppDefinition; manifest?: ConnectedAppManifest; onClose: () => void }) {
const prefix = useId(), { mutate } = useShellApps();
- const [app, setApp] = useState<ShellAppDefinition>(existing ?? { id: "", title: "", description: "", url: "", mode: "embed" });
+ const [app, setApp] = useState<ShellAppDefinition>(existing ?? { id: manifest?.id ?? "", title: manifest?.title ?? "", description: manifest?.description ?? "", url: "", mode: manifest?.presentation ?? "embed" });
const [busy, setBusy] = useState(false), [error, setError] = useState("");
const change = (key: keyof ShellAppDefinition, value: string) => setApp(current => ({ ...current, [key]: value }));
const submit = async (event: FormEvent) => {
event.preventDefault(); if (busy) return;
setBusy(true); setError("");
- try { await mutate({ action: existing ? "update" : "add", app }); onClose(); }
+ try { await mutate(manifest ? { action: "import", manifest, binding: { id: app.id, url: app.url, mode: app.mode } } : { action: existing ? "update" : "add", app }); onClose(); }
catch (reason) { setError(reason instanceof Error ? reason.message : "Could not connect app."); }
finally { setBusy(false); }
};
return <FormDrawer open onOpenChange={open => { if (!open && !busy) onClose(); }} size="md">
<FormDrawer.Header><FormDrawer.Title>{existing ? "Edit connected app" : "Connect a running app"}</FormDrawer.Title><FormDrawer.Description>Add your own tool or an existing service to this shell. The application keeps running on its host.</FormDrawer.Description></FormDrawer.Header>
<form onSubmit={submit} className="min-h-0 space-y-4 overflow-y-auto px-4 pb-4">
- <div className="space-y-1.5"><Label htmlFor={`${prefix}-name`}>App name</Label><Input id={`${prefix}-name`} value={app.title} maxLength={120} required onChange={event => {
+ {manifest && <div className="space-y-1 rounded-lg border p-3 text-sm"><p>Manifest: {manifest.id} · {manifest.version}</p><p>Publisher: {manifest.publisher} (self-declared)</p><p className="text-xs text-muted-foreground">Review this source before connecting. Use a different App ID for each instance. No tools or credentials are granted.</p></div>}
+ <div className="space-y-1.5"><Label htmlFor={`${prefix}-name`}>App name</Label><Input id={`${prefix}-name`} value={app.title} readOnly={Boolean(manifest)} maxLength={120} required onChange={event => {
const title = event.target.value;
setApp(current => ({ ...current, title, ...(!existing && (!current.id || current.id === current.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")) ? { id: title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 64) } : {}) }));
}}/></div>
<div className="space-y-1.5"><Label htmlFor={`${prefix}-id`}>App ID</Label><Input id={`${prefix}-id`} value={app.id} readOnly={Boolean(existing)} pattern="[a-z0-9][a-z0-9-]{0,63}" maxLength={64} required onChange={event => change("id", event.target.value)} /><p className="text-xs text-muted-foreground">A unique name using lowercase letters, numbers and hyphens.</p></div>
<div className="space-y-1.5"><Label htmlFor={`${prefix}-url`}>App URL</Label><Input id={`${prefix}-url`} type="url" value={app.url} placeholder="https://your-app.example or http://192.168.1.10:5678" maxLength={2048} required onChange={event => change("url", event.target.value)} /><p className="text-xs text-muted-foreground">Use an address reachable from this browser. A domain is optional. HTTP addresses open in a separate tab. Do not include tokens or passwords.</p></div>
- <div className="space-y-1.5"><Label htmlFor={`${prefix}-description`}>Description</Label><Input id={`${prefix}-description`} value={app.description} maxLength={240} onChange={event => change("description", event.target.value)} /></div>
+ <div className="space-y-1.5"><Label htmlFor={`${prefix}-description`}>Description</Label><Input id={`${prefix}-description`} value={app.description} readOnly={Boolean(manifest)} maxLength={240} onChange={event => change("description", event.target.value)} /></div>
<div className="flex items-center gap-2"><Switch aria-label="Embed HTTPS app inside MSO" checked={app.mode === "embed"} onCheckedChange={checked => change("mode", checked === true ? "embed" : "tab")} /><span className="text-sm">Embed HTTPS app inside MSO</span></div>
<p className="text-xs text-muted-foreground">The app keeps its own sign-in. Some apps block embedding; Open in new tab remains available. Connecting does not install or stop a service.</p>
{error && <p role="alert" className="text-sm text-destructive">{error}</p>}
diff --git a/frontend/slices/app-store/components/connected-apps-panel.tsx b/frontend/slices/app-store/components/connected-apps-panel.tsx
index a81a5426..5e2fb05d 100644
--- a/frontend/slices/app-store/components/connected-apps-panel.tsx
+++ b/frontend/slices/app-store/components/connected-apps-panel.tsx
@@ -8,10 +8,12 @@ import { Input } from "@/components/ui/input";
import { ScrollArea } from "@/components/ui/scroll-area";
import { useShellApps } from "../lib/shell-apps";
import { ConnectAppForm } from "./connect-app-form";
+import { ImportAppManifest } from "./import-app-manifest";
import { ManagedAppsCatalog } from "./managed-apps-catalog";
export default function ConnectedAppsPanel() {
const { active, snapshot, loading, error, refresh, mutate } = useShellApps();
+ const [importing, setImporting] = useState(false);
const [query, setQuery] = useState("");
const [editing, setEditing] = useState<ShellAppDefinition | "new" | null>(null);
const [removing, setRemoving] = useState<ShellAppDefinition | null>(null);
@@ -30,12 +32,13 @@ export default function ConnectedAppsPanel() {
{error && <p role="alert" className="text-sm text-destructive">{error}</p>}
<ManagedAppsCatalog query={query}/>
<section className="space-y-3" aria-label="Connected apps">
- <div className="flex flex-wrap items-center gap-2"><h3 className="mr-auto font-medium">Connected apps</h3><Button onClick={() => setEditing("new")} disabled={!snapshot.configurable || loading}><Plus className="size-4"/>Connect app</Button></div>
+ <div className="flex flex-wrap items-center gap-2"><h3 className="mr-auto font-medium">Connected apps</h3><Button variant="outline" disabled={!snapshot.configurable || loading} onClick={() => setImporting(true)}>Import manifest</Button><Button onClick={() => setEditing("new")} disabled={!snapshot.configurable || loading}><Plus className="size-4"/>Connect app</Button></div>
<Input aria-label="Search connected apps" placeholder="Search connected apps" value={query} onChange={event => setQuery(event.target.value)}/>
{!snapshot.configurable && !loading && !error && <p className="text-xs text-muted-foreground">This registry is managed by deployment configuration.</p>}
{loading && !snapshot.revision ? <p role="status" className="text-sm text-muted-foreground">Loading apps…</p> : apps.length === 0 ? <p className="rounded-xl border border-dashed p-6 text-sm text-muted-foreground">{query ? "No matching apps." : "No connected apps yet. Add the address of n8n or your own tool to open it from the shell."}</p> : <div className="grid gap-3 @min-[640px]:grid-cols-2">
{apps.map(app => <article key={app.id} className="min-w-0 space-y-3 rounded-xl border p-4">
<div className="flex items-center gap-2"><Globe className="size-5 shrink-0"/><h4 className="truncate font-medium">{app.title}</h4></div>
+ {app.manifest && <p className="break-words text-xs text-muted-foreground">{app.manifest.id} · {app.manifest.version} · {app.manifest.publisher} (self-declared)</p>}
{app.description && <p className="text-sm text-muted-foreground">{app.description}</p>}
<p className="break-all text-xs text-muted-foreground">{app.origin}</p>
<p className="text-xs text-muted-foreground">{app.blocked ? app.reason : app.renderer === "iframe" ? "Embedded app · service managed separately" : app.reason || "Opens in a separate tab"}</p>
@@ -43,6 +46,7 @@ export default function ConnectedAppsPanel() {
</article>)}
</div>}
</section>
+ {importing && <ImportAppManifest onClose={() => setImporting(false)}/>}
{editing && <ConnectAppForm existing={editing === "new" ? undefined : editing} onClose={() => setEditing(null)}/>}
<FormDrawer open={Boolean(removing)} onOpenChange={open => { if (!open && !busy) setRemoving(null); }} size="sm">
<FormDrawer.Header><FormDrawer.Title>Disconnect {removing?.title}?</FormDrawer.Title><FormDrawer.Description>This removes its shell entry. The application keeps running and its data is untouched.</FormDrawer.Description></FormDrawer.Header>
diff --git a/frontend/slices/app-store/components/import-app-manifest.tsx b/frontend/slices/app-store/components/import-app-manifest.tsx
new file mode 100644
index 00000000..5f4d07fe
--- /dev/null
+++ b/frontend/slices/app-store/components/import-app-manifest.tsx
@@ -0,0 +1,39 @@
+"use client";
+import { useId, useState } from "react";
+import { FormDrawer } from "@/features/appshell";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import { CONNECTED_APP_MANIFEST_MAX_BYTES, parseConnectedAppManifest, type ConnectedAppManifest } from "@/lib/contracts/connected-app-manifest";
+import { ConnectAppForm } from "./connect-app-form";
+
+export function ImportAppManifest({ onClose }: { onClose: () => void }) {
+ const prefix = useId();
+ const [raw, setRaw] = useState("");
+ const [error, setError] = useState("");
+ const [reading, setReading] = useState(false);
+ const [manifest, setManifest] = useState<ConnectedAppManifest | null>(null);
+ const readFile = async (file?: File) => {
+ if (!file) return;
+ setRaw(""); setError(""); setReading(true);
+ try {
+ if (file.size > CONNECTED_APP_MANIFEST_MAX_BYTES) throw new Error("Manifest exceeds the 8 KiB limit.");
+ setRaw(await file.text());
+ } catch (reason) { setError(reason instanceof Error ? reason.message : "Could not read this file."); }
+ finally { setReading(false); }
+ };
+ if (manifest) return <ConnectAppForm manifest={manifest} onClose={onClose}/>;
+ return <FormDrawer open onOpenChange={open => { if (!open && !reading) onClose(); }} size="md">
+ <FormDrawer.Header><FormDrawer.Title>Import app manifest</FormDrawer.Title><FormDrawer.Description>Choose a connected app JSON file from its developer, or paste it below. You will review the app and enter your instance address next.</FormDrawer.Description></FormDrawer.Header>
+ <div className="min-h-0 space-y-4 overflow-y-auto px-4 pb-4">
+ <div className="space-y-1.5"><Label htmlFor={`${prefix}-file`}>Manifest file</Label><Input id={`${prefix}-file`} type="file" accept=".json,application/json" disabled={reading} onChange={event => void readFile(event.target.files?.[0])}/></div>
+ <div className="space-y-1.5"><Label htmlFor={`${prefix}-json`}>Manifest JSON</Label><Textarea id={`${prefix}-json`} value={raw} disabled={reading} maxLength={CONNECTED_APP_MANIFEST_MAX_BYTES} rows={8} onChange={event => { setRaw(event.target.value); setError(""); }}/></div>
+ <p className="text-xs text-muted-foreground">Publisher names are self-declared. Importing connects a running application; it does not install code or grant access to MSO tools or credentials.</p>
+ {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+ <div className="flex justify-end gap-2"><Button variant="ghost" disabled={reading} onClick={onClose}>Cancel</Button><Button disabled={reading || !raw.trim()} onClick={() => {
+ try { setManifest(parseConnectedAppManifest(raw)); } catch (reason) { setError(reason instanceof Error ? reason.message : "Invalid manifest."); }
+ }}>Review app</Button></div>
+ </div>
+ </FormDrawer>;
+}
diff --git a/frontend/slices/app-store/lib/shell-apps.tsx b/frontend/slices/app-store/lib/shell-apps.tsx
index 0bbfc113..bd84a8cf 100644
--- a/frontend/slices/app-store/lib/shell-apps.tsx
+++ b/frontend/slices/app-store/lib/shell-apps.tsx
@@ -3,16 +3,18 @@
import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
import { Globe } from "lucide-react";
import type { AppDescriptor } from "@/features/appshell";
-import { shellAppId, type ShellAppMutation, type ShellAppSnapshot } from "@/lib/contracts/shell-app";
+import { shellAppId, type ShellAppChange, type ShellAppSnapshot } from "@/lib/contracts/shell-app";
const EMPTY: ShellAppSnapshot = { schemaVersion: 1, revision: "", configurable: false, apps: [] };
type ShellAppsContext = {
active: boolean; loading: boolean; error: string; snapshot: ShellAppSnapshot;
refresh: () => Promise<void>;
- mutate: (value: Pick<ShellAppMutation, "action" | "app" | "id">) => Promise<void>;
+ mutate: (value: ShellAppChange) => Promise<void>;
};
const Context = createContext<ShellAppsContext>({ active: false, loading: false, error: "", snapshot: EMPTY, refresh: async () => {}, mutate: async () => { throw new Error("Owner access required."); } });
const errors: Record<string, string> = {
+ surface_registry_capacity: "The shared app registry is full. Disconnect an unused entry before adding another app.",
+ invalid_app_manifest: "This app manifest is unsupported or invalid. Review the file before connecting.",
app_id_exists: "That app ID is already registered. Choose another ID.",
app_cookie_scope_conflict: "This address shares MSO's login cookies. Use a different host address, not just a different port.",
plain_app_url_required: "Use an HTTP or HTTPS address without credentials, query parameters or fragments.",
@@ -48,7 +50,7 @@ export function ShellAppsProvider({ active, children }: { active: boolean; child
window.addEventListener("focus", focus);
return () => { invalidate(); cancelAnimationFrame(frame); clearInterval(poll); window.removeEventListener("focus", focus); };
}, [active, refresh, invalidate]);
- const mutate = useCallback(async (value: Pick<ShellAppMutation, "action" | "app" | "id">) => {
+ const mutate = useCallback(async (value: ShellAppChange) => {
if (!active || !snapshot.configurable) throw new Error("Owner access to a configurable app registry is required.");
const response = await fetch("/api/v1/shell-apps", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ ...value, schemaVersion: 1, expectedRevision: snapshot.revision, confirm: true }) });
const data = await response.json() as { error?: string };
diff --git a/lib/contracts/connected-app-manifest.test.ts b/lib/contracts/connected-app-manifest.test.ts
new file mode 100644
index 00000000..c3139cc8
--- /dev/null
+++ b/lib/contracts/connected-app-manifest.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { parseConnectedAppManifest, validateConnectedAppManifest } from "./connected-app-manifest";
+import template from "@/templates/connected-app/manifest.json";
+const manifest = { schema: "urn:mso:connected-app:v1", schemaVersion: 1, id: "custom-editor", version: "1.0.0", title: "Custom editor", description: "My tool", publisher: "Example developer", presentation: "embed" };
+describe("portable connected app manifest", () => {
+ it("accepts the published starter template", () => { expect(validateConnectedAppManifest(template)).toEqual(template); });
+ it("normalizes plain metadata without adding endpoints or authority", () => {
+ expect(parseConnectedAppManifest(JSON.stringify({ ...manifest, title: " Editor " }))).toEqual({ ...manifest, title: "Editor" });
+ });
+ it.each(["0.0.0", "1.2.3-rc.1+build.7", "1.2.3-alpha-beta.0", "10.20.30+001"])("accepts semantic version %s", version => {
+ expect(validateConnectedAppManifest({ ...manifest, version }).version).toBe(version);
+ });
+ it.each(["v1.0.0", "01.0.0", "1.0", "1.0.0-01", "1.0.0-", "1.0.0+", "1.0.0-..", "1.0.0 "])("rejects malformed version %s", version => {
+ expect(() => validateConnectedAppManifest({ ...manifest, version })).toThrow();
+ });
+ it.each([
+ { schemaVersion: 2 }, { schema: "urn:mso:feature:v1" }, { id: "../tool" }, { id: "A" },
+ { title: "<script>run()</script>" }, { publisher: "line\nbreak" }, { presentation: "native" },
+ { url: "https://developer.example.test" }, { secret: "not-allowed" }, { command: "run-tool" },
+ { actions: ["exec"] }, { title: "x".repeat(121) }, { version: "1".repeat(129) },
+ ])("rejects unsupported or executable metadata %j", change => {
+ expect(() => validateConnectedAppManifest({ ...manifest, ...change })).toThrow();
+ });
+ it("rejects missing fields, arrays, invalid JSON and excessive UTF-8 input", () => {
+ const missing: Record<string, unknown> = { ...manifest }; delete missing.publisher;
+ expect(() => validateConnectedAppManifest(missing)).toThrow();
+ expect(() => validateConnectedAppManifest([])).toThrow();
+ expect(() => parseConnectedAppManifest("{broken")).toThrow("valid JSON");
+ expect(() => parseConnectedAppManifest(JSON.stringify(manifest) + " ".repeat(8192))).toThrow("8 KiB");
+ expect(() => parseConnectedAppManifest("界".repeat(3000))).toThrow("8 KiB");
+ });
+});
diff --git a/lib/contracts/connected-app-manifest.ts b/lib/contracts/connected-app-manifest.ts
new file mode 100644
index 00000000..ff3178fe
--- /dev/null
+++ b/lib/contracts/connected-app-manifest.ts
@@ -0,0 +1,35 @@
+/** Portable discovery metadata. Endpoints and permissions belong to each binding. */
+export type ConnectedAppManifest = {
+ schema: "urn:mso:connected-app:v1";
+ schemaVersion: 1;
+ id: string;
+ version: string;
+ title: string;
+ description: string;
+ publisher: string;
+ presentation: "embed" | "tab";
+};
+export const CONNECTED_APP_MANIFEST_MAX_BYTES = 8192;
+const KEYS = ["schema", "schemaVersion", "id", "version", "title", "description", "publisher", "presentation"];
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
+const plain = (value: unknown, max: number, empty = false): value is string =>
+ typeof value === "string" && value.length <= max && (empty || value.trim().length > 0) && !/[<>\u0000-\u001f\u007f]/.test(value);
+
+export function validateConnectedAppManifest(value: unknown): ConnectedAppManifest {
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Manifest must be a JSON object.");
+ const record = value as Record<string, unknown>;
+ if (Object.keys(record).length !== KEYS.length || Object.keys(record).some(key => !KEYS.includes(key))) throw new Error("Manifest contains missing or unsupported fields.");
+ if (record.schema !== "urn:mso:connected-app:v1" || record.schemaVersion !== 1) throw new Error("Unsupported connected app manifest version.");
+ if (typeof record.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(record.id)) throw new Error("Manifest ID must use lowercase letters, numbers and hyphens.");
+ if (typeof record.version !== "string" || record.version.length > 128 || !VERSION.test(record.version)) throw new Error("Manifest needs a semantic version, such as 1.0.0.");
+ if (!plain(record.title, 120) || !plain(record.description, 240, true) || !plain(record.publisher, 120)) throw new Error("Manifest title, description and publisher must be bounded plain text.");
+ if (record.presentation !== "embed" && record.presentation !== "tab") throw new Error("Manifest presentation must be embed or tab.");
+ return { schema: record.schema, schemaVersion: 1, id: record.id, version: record.version,
+ title: record.title.trim(), description: record.description.trim(), publisher: record.publisher.trim(), presentation: record.presentation };
+}
+export function parseConnectedAppManifest(raw: string): ConnectedAppManifest {
+ if (new TextEncoder().encode(raw).byteLength > CONNECTED_APP_MANIFEST_MAX_BYTES) throw new Error("Manifest exceeds the 8 KiB limit.");
+ let value: unknown;
+ try { value = JSON.parse(raw); } catch { throw new Error("Manifest is not valid JSON."); }
+ return validateConnectedAppManifest(value);
+}
diff --git a/lib/contracts/shell-app.ts b/lib/contracts/shell-app.ts
index afa81cb3..96b8aa30 100644
--- a/lib/contracts/shell-app.ts
+++ b/lib/contracts/shell-app.ts
@@ -1,3 +1,4 @@
+import type { ConnectedAppManifest } from "./connected-app-manifest";
import type { WorkflowEmbed } from "./surface-app";
export type ShellAppDefinition = {
@@ -7,19 +8,20 @@ export type ShellAppDefinition = {
url: string;
mode: "embed" | "tab";
};
-export type ShellAppView = WorkflowEmbed & { definition: ShellAppDefinition };
+export type ShellAppView = WorkflowEmbed & { definition: ShellAppDefinition; manifest?: ConnectedAppManifest };
export type ShellAppSnapshot = {
schemaVersion: 1;
revision: string;
configurable: boolean;
apps: ShellAppView[];
};
-export type ShellAppMutation = {
+export type ShellAppChange =
+ | { action: "add" | "update"; app: ShellAppDefinition }
+ | { action: "remove"; id: string }
+ | { action: "import"; manifest: ConnectedAppManifest; binding: Pick<ShellAppDefinition, "id" | "url" | "mode"> };
+export type ShellAppMutation = ShellAppChange & {
schemaVersion: 1;
- action: "add" | "update" | "remove";
expectedRevision: string;
confirm: true;
- app?: ShellAppDefinition;
- id?: string;
};
export const shellAppId = (id: string) => `external-${id}`;
diff --git a/lib/surfaces/shell-apps.test.ts b/lib/surfaces/shell-apps.test.ts
index 67889ef8..c496e09d 100644
--- a/lib/surfaces/shell-apps.test.ts
+++ b/lib/surfaces/shell-apps.test.ts
@@ -96,4 +96,26 @@ describe("server-owned connected applications", () => {
await expect(manageShellApp({ ...base, schemaVersion: 2 }, origin)).rejects.toThrow("invalid_shell_request");
await expect(manageShellApp({ ...base, confirm: false }, origin)).rejects.toThrow("invalid_shell_request");
});
+ it("imports one manifest into independent bindings and preserves provenance on edit", async () => {
+ const manifest = { schema: "urn:mso:connected-app:v1", schemaVersion: 1, id: "tool", version: "1.0.0", title: "Template tool", description: "", publisher: "Local developer", presentation: "embed" };
+ const request = async (id: string, url = app.url, extra = {}) => manageShellApp({ schemaVersion: 1, action: "import", manifest, binding: { id, url, mode: "embed" }, expectedRevision: (await shellAppSettings(origin)).revision, confirm: true, ...extra }, origin);
+ await request("first"); await request("second", "http://192.0.2.10:5678/");
+ let snapshot = await shellAppSettings(origin);
+ expect(snapshot.apps.map(row => row.definition.id)).toEqual(["first", "second"]);
+ expect(snapshot.apps.map(row => row.manifest)).toEqual([manifest, manifest]);
+ expect(snapshot.apps[1].renderer).toBe("remote");
+ await save({ id: "first", title: "Instance name" }, "update");
+ snapshot = await shellAppSettings(origin);
+ expect(snapshot.apps[0].manifest).toEqual(manifest);
+ expect(snapshot.apps[0].title).toBe("Instance name");
+ const before = await fs.readFile(file, "utf8");
+ await expect(request("first")).rejects.toThrow("app_id_exists");
+ await expect(request("third", origin)).rejects.toThrow("app_cookie_scope_conflict");
+ await expect(request("third", app.url, { manifest: { ...manifest, command: "run-tool" } })).rejects.toThrow("invalid_app_manifest");
+ await expect(request("third", app.url, { app })).rejects.toThrow("invalid_shell_request");
+ await expect(request("third", app.url, { binding: { id: "third", url: app.url, mode: "embed", token: "not-allowed" } })).rejects.toThrow("invalid_shell_request");
+ await expect(request("third", app.url, { confirm: false })).rejects.toThrow("invalid_shell_request");
+ expect(await fs.readFile(file, "utf8")).toBe(before);
+ });
+
});
diff --git a/lib/surfaces/shell-apps.ts b/lib/surfaces/shell-apps.ts
index 9d655ec5..f65359e9 100644
--- a/lib/surfaces/shell-apps.ts
+++ b/lib/surfaces/shell-apps.ts
@@ -1,3 +1,4 @@
+import { validateConnectedAppManifest, type ConnectedAppManifest } from "@/lib/contracts/connected-app-manifest";
import type { ShellAppDefinition, ShellAppSnapshot, ShellAppView } from "@/lib/contracts/shell-app";
import type { SurfaceApp } from "@/lib/contracts/surface-app";
import { configuredSurfaceApps } from "./config";
@@ -39,19 +40,32 @@ function view(app: SurfaceApp, requestOrigin: string): ShellAppView {
return { ...base, url, renderer: insecure ? "remote" : app.renderer,
...(insecure ? { reason: "HTTP apps open separately. Use an HTTPS address to embed this app." } : {}) };
}
+function storedManifest(value: unknown): ConnectedAppManifest | undefined {
+ try { return validateConnectedAppManifest(value); } catch { return undefined; }
+}
export async function shellAppSettings(requestOrigin: string): Promise<ShellAppSnapshot> {
const state = await readSurfaceRegistry();
const apps = await configuredSurfaceApps(state.raw);
+ let entries: Array<Record<string, unknown>> = [];
+ try { const raw = JSON.parse(state.raw); if (Array.isArray(raw)) entries = raw.filter(entry => object(entry)); } catch { /* Registry admission remains authoritative. */ }
return { schemaVersion: 1, revision: registryRevision(state.raw), configurable: !state.managedByEnvironment,
- apps: apps.filter(app => app.placements?.includes("shell")).map(app => view(app, requestOrigin)) };
+ apps: apps.filter(app => app.placements?.includes("shell")).map(app => ({ ...view(app, requestOrigin), manifest: storedManifest(entries.find(entry => entry.id === app.id)?.manifest) })) };
}
export async function manageShellApp(input: Record<string, unknown>, requestOrigin: string) {
if (input.schemaVersion !== 1 || input.confirm !== true ||
- Object.keys(input).some(key => !["schemaVersion", "action", "expectedRevision", "confirm", "app", "id"].includes(key)) ||
- !["add", "update", "remove"].includes(String(input.action))) throw new SurfaceConfigError("invalid_shell_request");
+ Object.keys(input).some(key => !["schemaVersion", "action", "expectedRevision", "confirm", "app", "id", "manifest", "binding"].includes(key)) ||
+ !["add", "update", "remove", "import"].includes(String(input.action))) throw new SurfaceConfigError("invalid_shell_request");
+ const importing = input.action === "import";
+ let manifest: ConnectedAppManifest | undefined;
+ if (importing) {
+ if (input.app !== undefined || input.id !== undefined || !object(input.binding) ||
+ Object.keys(input.binding).some(key => !["id", "url", "mode"].includes(key))) throw new SurfaceConfigError("invalid_shell_request");
+ try { manifest = validateConnectedAppManifest(input.manifest); } catch { throw new SurfaceConfigError("invalid_app_manifest"); }
+ } else if (input.manifest !== undefined || input.binding !== undefined) throw new SurfaceConfigError("invalid_shell_request");
const removing = input.action === "remove";
+ const adding = input.action === "add" || importing;
if ((removing && input.app !== undefined) || (!removing && input.id !== undefined)) throw new SurfaceConfigError("invalid_shell_request");
- const app = removing ? undefined : definition(input.app);
+ const app = removing ? undefined : definition(manifest ? { ...(input.binding as object), title: manifest.title, description: manifest.description } : input.app);
const id = app?.id ?? input.id;
if (typeof id !== "string" || !ID.test(id)) throw new SurfaceConfigError("invalid_shell_app");
const url = app ? new URL(app.url) : undefined;
@@ -64,11 +78,11 @@ export async function manageShellApp(input: Record<string, unknown>, requestOrig
if (row && (await configuredSurfaceApps(JSON.stringify([row]))).length !== 1) throw new SurfaceConfigError("invalid_shell_app");
const result = await mutateSurfaceRegistry(input.expectedRevision, async entries => {
const matches = entries.filter(entry => entry.id === id);
- if (input.action === "add" && matches.length) throw new SurfaceConfigError("app_id_exists", 409);
- if (input.action !== "add" && matches.length !== 1) throw new SurfaceConfigError("app_not_found_or_ambiguous", 409);
+ if (adding && matches.length) throw new SurfaceConfigError("app_id_exists", 409);
+ if (!adding && matches.length !== 1) throw new SurfaceConfigError("app_not_found_or_ambiguous", 409);
if (matches.some(entry => !Array.isArray(entry.placements) || entry.placements.length !== 1 || entry.placements[0] !== "shell")) throw new SurfaceConfigError("app_owned_by_another_surface", 409);
if (removing) return entries.filter(entry => entry.id !== id);
- return input.action === "add" ? [...entries, row!] : entries.map(entry => entry.id === id ? row! : entry);
+ return adding ? [...entries, { ...row!, ...(manifest ? { manifest } : {}) }] : entries.map(entry => entry.id === id ? { ...row!, ...(entry.manifest ? { manifest: entry.manifest } : {}) } : entry);
});
return { ...result, id, schemaVersion: 1 };
}
diff --git a/scripts/e2e/shell-apps.mjs b/scripts/e2e/shell-apps.mjs
index 7c1d3103..6dc6c8d1 100644
--- a/scripts/e2e/shell-apps.mjs
+++ b/scripts/e2e/shell-apps.mjs
@@ -1,6 +1,6 @@
#!/usr/bin/env node
import { chromium, expect } from "@playwright/test";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
import path from "node:path";
import { releaseFixture } from "./release-fixture.mjs";
@@ -67,11 +67,47 @@ try {
await expect(page.getByRole("dialog")).toHaveCount(0);
await expect(card).toHaveCount(0);
expect(JSON.parse(await readFile(path.join(fixture.dir, "surface-apps.json"), "utf8"))).toEqual([]);
+ const manifest = { schema: "urn:mso:connected-app:v1", schemaVersion: 1, id: "custom-editor", version: "1.0.0-rc.1", title: "Imported tool", description: "External service", publisher: "Fixture developer", presentation: "embed" };
+ await page.getByRole("button", { name: "Import manifest", exact: true }).click();
+ await form.getByLabel("Manifest JSON", { exact: true }).fill(JSON.stringify({ ...manifest, command: "unsupported" }));
+ await form.getByRole("button", { name: "Review app", exact: true }).click();
+ await expect(form.getByRole("alert")).toContainText("unsupported fields");
+ expect(JSON.parse(await readFile(path.join(fixture.dir, "surface-apps.json"), "utf8"))).toEqual([]);
+ if (viewport.width === 1280) {
+ await form.getByLabel("Manifest file", { exact: true }).setInputFiles({ name: "app.json", mimeType: "application/json", buffer: Buffer.from(JSON.stringify(manifest)) });
+ await expect(form.getByLabel("Manifest JSON", { exact: true })).toHaveValue(JSON.stringify(manifest));
+ } else await form.getByLabel("Manifest JSON", { exact: true }).fill(JSON.stringify(manifest));
+ await form.getByRole("button", { name: "Review app", exact: true }).click();
+ await expect(form.getByText("Publisher: Fixture developer (self-declared)")).toBeVisible();
+ await expect(form.getByLabel("App name", { exact: true })).toHaveAttribute("readonly", "");
+ await form.getByLabel("App ID", { exact: true }).fill("imported-instance");
+ await form.getByLabel("App URL", { exact: true }).fill("https://tool.example.test/editor");
+ await form.locator("form").hover(); await page.mouse.wheel(0, 1200);
+ await expect(form.getByRole("button", { name: "Connect app", exact: true })).toBeInViewport({ ratio: 1 });
+ await form.getByRole("button", { name: "Connect app", exact: true }).click();
+ await expect(form).toHaveCount(0);
+ const imported = page.getByRole("article").filter({ has: page.getByRole("heading", { name: "Imported tool", exact: true }) });
+ await expect(imported).toContainText("Fixture developer (self-declared)");
+ await page.reload();
+ await expect(imported).toBeVisible();
+ const row = JSON.parse(await readFile(path.join(fixture.dir, "surface-apps.json"), "utf8"))[0];
+ expect(row.id).toBe("imported-instance"); expect(row.manifest).toEqual(manifest);
+ if (process.env.MSO_SCREENSHOT_DIR) {
+ await mkdir(process.env.MSO_SCREENSHOT_DIR, { recursive: true });
+ await page.screenshot({ path: path.join(process.env.MSO_SCREENSHOT_DIR, `connected-manifest-${viewport.width}x${viewport.height}.png`) });
+ }
+ await imported.getByRole("button", { name: "Open", exact: true }).click();
+ await expect(page.frameLocator('iframe[title="Imported tool application"]').getByRole("heading", { name: "Custom tool" })).toBeVisible();
+ await page.goto(fixture.base + "/store");
+ await imported.getByRole("button", { name: "Disconnect", exact: true }).click();
+ await form.getByRole("button", { name: "Disconnect", exact: true }).click();
+ await expect(form).toHaveCount(0); await expect(imported).toHaveCount(0);
+ expect(JSON.parse(await readFile(path.join(fixture.dir, "surface-apps.json"), "utf8"))).toEqual([]);
await fixture.setRole("viewer");
expect(await page.evaluate(async () => (await fetch("/api/v1/shell-apps")).status)).toBe(403);
await fixture.setRole("owner");
expect(errors).toEqual([]);
await context.close();
- console.log(`PASS connected app CRUD, embed draft retention, persistence, IP fallback and authorization ${viewport.width}x${viewport.height}`);
+ console.log(`PASS manifest file/paste review, import/reload/removal, connected app CRUD, embed draft retention, persistence, IP fallback and authorization ${viewport.width}x${viewport.height}`);
}
} finally { await browser?.close(); await fixture.close(); }
diff --git a/templates/connected-app/manifest.json b/templates/connected-app/manifest.json
new file mode 100644
index 00000000..4740aaea
--- /dev/null
+++ b/templates/connected-app/manifest.json
@@ -0,0 +1,10 @@
+{
+ "schema": "urn:mso:connected-app:v1",
+ "schemaVersion": 1,
+ "id": "custom-editor",
+ "version": "1.0.0",
+ "title": "Custom editor",
+ "description": "Open your running editor in MSO",
+ "publisher": "Your project",
+ "presentation": "embed"
+}