Entwickeln Sie eine App, die zu Sovereign Workspace passt.

Was Sie bauen

Eine Sovereign-Workspace-App ist eine gewöhnliche Web-App – React, Vue, Svelte oder reines HTML, ganz wie Sie möchten –, die der Workspace in einem <iframe> mit Sandbox lädt. Sie hosten und bauen sie, wie Sie wollen. Zur Workspace-App wird sie dadurch, dass sie den Workspace über das SDK aufrufen und sein Erscheinungsbild übernehmen kann.

Weil sie in einer Sandbox läuft, kann Ihre App nicht direkt in den Workspace eingreifen. Stattdessen spricht sie über einen kleinen, validierten Nachrichtenkanal mit dem Host. Das Paket @sovereign-workspace/sdk-iframe verbirgt diesen Kanal hinter einer normalen API aus Funktionsaufrufen, sodass Sie die postMessage-Verdrahtung nie selbst schreiben.

Über das SDK kann Ihre App:

• Das Theme übernehmen – das aktive helle oder dunkle Theme lesen und Änderungen folgen.
• Benachrichtigungen im Workspace anzeigen.
• Mit anderen Apps kommunizieren – über IPC, wenn beide Seiten zustimmen.
• Laufzeitinformationen lesen – den angemeldeten Benutzer, ob es die native Desktop-Shell ist, und mehr.
• Ihr bereichsgebundenes Token abrufen – ein kurzlebiges Token, das der Workspace beim Start für Ihre App ausstellt.

Schnellstart

Installieren Sie die beiden Pakete:

npm install @sovereign-workspace/sdk-iframe @sovereign-workspace/design-tokens

Verbinden Sie sich dann im Einstiegspunkt Ihrer App mit dem Workspace, übernehmen Sie sein Theme und nutzen Sie ihn:

import { createWorkspaceSdk } from '@sovereign-workspace/sdk-iframe';
import '@sovereign-workspace/design-tokens';

const sdk = createWorkspaceSdk();

// 1. Match the workspace theme on load, and follow every switch.
const applyTheme = (theme) =>
  document.documentElement.setAttribute('data-theme', theme === 'dark' ? 'dark' : '');
applyTheme(await sdk.system.getTheme());
sdk.system.onThemeChange(applyTheme);

// 2. Use the workspace: show a notification.
await sdk.notifications.show({ title: 'Hello', body: 'from my app', variant: 'info' });

// 3. Talk to another app (delivered only on mutual manifest consent).
await sdk.ipc.send('chat', { type: 'greeting', text: 'hi' });

Das ist eine vollständige App, die dem Theme folgt. Laden Sie sie im Workspace, und sie erscheint im richtigen Theme und wechselt mit dem Workspace, wenn der Benutzer den dunklen Modus umschaltet.

Das SDK

Erstellen Sie das SDK einmal und verwenden Sie es wieder. Übergeben Sie den Origin Ihres Workspace, um die Verbindung abzusichern (in Produktion empfohlen):

const sdk = createWorkspaceSdk('https://workspace.example.org');

Aufruf	Was er tut
system.getTheme()	Das aktive Theme, 'light' oder 'dark'.
system.onThemeChange(fn)	Wird bei jedem Wechsel mit dem neuen Theme ausgelöst. Gibt eine Funktion zum Abmelden zurück.
system.getRuntimeContext()	Angemeldeter Benutzer und Details zur Laufzeit.
system.getRuntimeMode()	'standalone', wenn außerhalb des Workspace geöffnet.
system.isNativeShell()	true in der nativen Desktop-Shell.
notifications.show(payload)	Zeigt eine Workspace-Benachrichtigung an.
ipc.send(recipient, data)	Sendet eine Nachricht an eine andere App (gegenseitige Zustimmung erforderlich).
ipc.on(recipient, fn)	Empfängt Nachrichten, die an Ihre App adressiert sind.
ext.getToken()	Das beim Start für Ihre App ausgestellte bereichsgebundene Token oder null.

Der Workspace setzt Identität und Berechtigungen auf seiner Seite durch, sodass sich das SDK nicht dazu bringen lässt, mehr zu tun, als Ihre App darf. Der Host prägt bei jedem Aufruf die Identität Ihrer App auf – die Payload einer Nachricht kann sich nie als eine andere App ausgeben.

Das Theme übernehmen

Dieser Teil sorgt dafür, dass sich Ihre App nativ anfühlt. Das Paket @sovereign-workspace/design-tokens ist eine einzelne CSS-Datei mit den Farben des Workspace – Flächen, Text, Rahmen, Akzente – für den hellen und den dunklen Modus. Importieren Sie sie und gestalten Sie dann alles mit den var(--token)-Werten statt mit fest codierten Farben:

.card {
  background: var(--surface-primary);
  color: var(--text-primary);
  border: 1px solid var(--border-primary);
  border-radius: 8px;
}
.card button {
  background: var(--accent);
  color: var(--selected-text);
}

Die Tokens liefern standardmäßig eine helle Palette; data-theme="dark" auf <html> schaltet die ganze Datei auf die dunkle Palette um. Verbinden Sie das mit dem SDK, und Ihre App folgt dem Workspace automatisch – beim Laden übernehmen, bei jedem Umschalten mitgehen:

import { createWorkspaceSdk } from '@sovereign-workspace/sdk-iframe';
import '@sovereign-workspace/design-tokens';

const sdk = createWorkspaceSdk();

function applyTheme(theme) {
  // The tokens ship a light palette by default; data-theme="dark" switches it.
  document.documentElement.setAttribute('data-theme', theme === 'dark' ? 'dark' : '');
}

applyTheme(await sdk.system.getTheme());   // match on load
sdk.system.onThemeChange(applyTheme);      // …and whenever the user toggles

Die Token-Datei wird aus dem Stylesheet des Workspace selbst erzeugt, daher erhalten Sie immer die echten, aktuellen Farben – sie können nicht abweichen. Verfügbar sind unter anderem --surface-primary, --text-primary, --text-secondary, --border-primary, --accent und die semantischen --color-error / success / info / warning. Die vollständige Liste steht in der importierten Datei.

Mit anderen Apps kommunizieren

Apps können einander Nachrichten senden, aber nur, wenn beide zustimmen. Eine Nachricht Ihrer App an eine andere wird nur zugestellt, wenn Ihr Manifest diese App als Sendeziel aufführt und das Manifest dieser App Ihre App in seiner „accepts“-Liste aufführt. Alles andere wird abgelehnt und protokolliert – so kann kein Fremder einer App Nachrichten senden.

// Receive messages addressed to your app.
const unsubscribe = sdk.ipc.on('my-app', (env) => {
  console.log('from', env.sender, env.data);
});

// Send to another app. The workspace stamps YOUR identity as the sender —
// a payload cannot spoof it. The message is delivered only if both manifests
// consent: your manifest lists 'chat' as a send target, and 'chat' lists
// 'my-app' in its accepts allowlist. Otherwise the workspace denies and audits.
await sdk.ipc.send('chat', { type: 'greeting', text: 'hi' });

Wo Ihre App läuft

Ihre App ist eine Standard-Web-App, die der Workspace in einem iframe mit Sandbox einbettet. Sie müssen sie also an einem Ort bereitstellen, der über HTTPS erreichbar ist. Es gibt zwei Hosting-Modelle:

1. Selbst gehostet unter einer URL. Sie betreiben die App auf Ihrer eigenen Infrastruktur und registrieren ihre HTTPS-URL beim Workspace. Am schnellsten ausgeliefert – aber Anfragen und Nutzerdaten fließen zu Ihren Servern. Für ein zustandsloses Tool in Ordnung; weniger passend für eine datenintensive App in einem Workspace, der darauf ausgelegt ist, Daten im eigenen Haus zu behalten.

2. Als Container ausgeliefert. Sie veröffentlichen ein Docker-Image, und der Betreiber des Workspace führt es auf seiner eigenen Infrastruktur neben dem Workspace aus, sodass die Daten in seinem Netzwerk bleiben. Mehr Paketierungsaufwand für Sie, aber das richtige Modell für alles, was sensible Daten betrifft – und das Modell, das zum Souveränitätsziel des Produkts passt.

In der Desktop-App (nativ): Der Workspace läuft als native Shell und bettet Ihre App in einen Webview des Betriebssystems statt in ein HTML-iframe ein. Die obigen Framing-Header gelten dort daher nicht – Ihre App lädt auch, wenn sie das Einbetten verbietet. Eines sollten Sie wissen: Die SDK-Brücke richtet sich derzeit an den Browser-Client, und SDK-Zugriff aus dem nativen Webview der Desktop-App steht auf der Roadmap. Bauen Sie Ihre Integration so, dass sie mit eingeschränktem Funktionsumfang sauber weiterläuft, wenn das SDK nicht verfügbar ist – der eigenständige Fallback in createWorkspaceSdk() erledigt das bereits für Sie.

Offline & Caching

Weil der iframe den eigenen Origin Ihrer App behält, stehen die üblichen Speicher- und Caching-APIs des Browsers zur Verfügung:

• Registrieren Sie einen Service Worker, der die App-Shell und die Assets Ihrer App zwischenspeichert, damit die Oberfläche ohne Verbindung lädt.
• Speichern Sie Daten lokal mit IndexedDB oder localStorage.

Zwei Einschränkungen, die Sie beim Entwurf berücksichtigen sollten:

• Caching deckt Ihr Frontend ab, nicht Ihr Backend. Offline funktioniert die Oberfläche, aber Aufrufe Ihrer eigenen API setzen voraus, dass diese erreichbar ist. Hat Ihre App ein Backend, hält das Container-Modell (Option 2) es im Netzwerk des Workspace – erreichbar, auch wenn das öffentliche Internet es nicht ist.
• Dies ist keine installierbare PWA. Der Workspace ist die installierte Shell; Ihre App ist eine Oberfläche darin, daher gibt es kein eigenes Web-App-Manifest und keinen Installationsdialog auszuliefern – nutzen Sie einfach einen Service Worker und lokalen Speicher für mehr Ausfallsicherheit.

Zu beachten: Als Cross-Origin-iframe können Speicher und Service Worker Ihrer App in den Datenschutzmodi mancher Browser unter dem Top-Level-Origin des Workspace partitioniert werden. Es funktioniert, aber der Cache gilt pro Workspace – testen Sie das Offline-Verhalten mit Ihrem tatsächlichen Zielsystem.

Ihre App in einen Workspace bringen

Externe Apps fügt ein Workspace-Administrator hinzu: Er registriert die URL Ihrer App und weist sie den Benutzergruppen zu, die sie sehen sollen. Der Workspace lädt sie dann im iframe mit Sandbox, stellt beim Start ihr bereichsgebundenes Token aus und wendet die oben beschriebenen IPC-Zustimmungsregeln an.

Der Installationsablauf mit einem Klick, bei dem Sie ein Manifest einreichen, ist noch in Entwicklung. Wenn Sie heute eine App bauen, melden Sie sich bei uns: Wir helfen Ihnen, sie zu registrieren – und sagen Ihnen Bescheid, sobald die Registrierung in Selbstbedienung verfügbar ist.

Pakete

• @sovereign-workspace/sdk-iframe – das SDK: IPC, Benachrichtigungen, Systeminformationen, Theme, bereichsgebundenes Token.
• @sovereign-workspace/design-tokens – die hellen und dunklen CSS-Tokens.