Schreibzeug in Kontext¶
Kontext (Mail, Kalender, Kontakte, Aufgaben und Chat auf
Stalwart) zeigt Schreibzeug als sein Modul „Dokumente“. Beide bleiben eigene Dienste, jeder mit
eigenen Sitzungen, Daten und Releases; sie treffen sich nur über Standards: OpenID Connect für die
Anmeldung, HTTP mit Bearer-Tokens zwischen den Servern und postMessage zwischen den beiden Seiten.
Ohne Kontext ändert sich nichts: Schreibzeug sieht aus und funktioniert wie für sich allein.
kontext.firma.de (Kontext) ── frame ──▶ dokumente.firma.de (Schreibzeug) postMessage both ways
Schreibzeug ── OpenID Connect ──▶ Kontext's provider (/api/auth) the sign-in
Kontext's server ── bearer token ──▶ Schreibzeug's API (/api/nodes, /api/files) files
Beide laufen unter einer Site (kontext.firma.de, dokumente.firma.de), sodass die Cookies von
Schreibzeug im Frame von Kontext zählen (SameSite=Lax) und keine Drittanbieter-Cookies nötig sind.
Anmelden über Kontext¶
Kontext ist ein OpenID-Connect-Anbieter (@better-auth/oauth-provider von Better Auth), Schreibzeug
sein Client (das Generic-OAuth-Plugin von Better Auth, apps/server/src/auth/auth.ts): Discovery
unter <OIDC_ISSUER>/.well-known/openid-configuration, der Code-Flow mit PKCE, das Client-Secret im
Header Authorization (client_secret_basic), das ID-Token gegen die Schlüssel des Anbieters
geprüft. Der Callback ist /api/auth/callback/oidc (/callback/:id von Better Auth), also
registriert Kontext <SCHREIBZEUG_URL>/api/auth/callback/oidc.
- Die Anmeldeseite zeigt Anmelden mit Kontext (
OIDC_NAME) über E-Mail und Passwort. - Im Frame von Kontext wird jemand ohne Sitzung angemeldet, ohne gefragt zu werden: Die App
versucht es einmal mit
prompt=none(signInSilentlyinapps/web/src/router.tsx). Mit einer Sitzung bei Kontext kommt der Browser direkt zurück; ohne eine antwortet Kontextlogin_required, und die Anmeldeseite erscheint. Der Versuch wird für den Frame gemerkt (sessionStorage), sodass er nie in eine Schleife gerät; öffnet Kontext den Frame neu (?embedded=kontext), ist der nächste erlaubt. - Eine neue Person bekommt ein Konto; eine Adresse, die eines hat, wird damit verknüpft, siehe Konten.
Dasselbe funktioniert mit anderen Anbietern (Microsoft Entra, Google, Keycloak): Issuer, Client-ID und Secret sind alles, was es braucht.
Eingebettet¶
Kontext öffnet den Frame unter <page>?embedded=kontext. Schreibzeug gilt nur in einem Frame als
eingebettet, nur wenn SCHREIBZEUG_EMBED_ORIGIN gesetzt ist, und merkt es sich für den Frame
(apps/web/src/embed/). Dann:
- zeigt die Shell keinen Namen, kein Kontofeld und keine Abmeldung (die hat Kontext); Dateiseiten und der Editor füllen den Frame; der Editor hat In neuem Tab öffnen;
- folgen hell oder dunkel Kontext (
data-themeauf<html>; ohne Kontext setztindex.htmles nach dem Gerät); - erlaubt der Server das Einbetten in einen Frame nur sich selbst und diesem Origin:
Content-Security-Policy: frame-ancestors 'self' <SCHREIBZEUG_EMBED_ORIGIN>(apps/server/src/web.ts).
Nachrichten¶
Jede Nachricht ist { source, type, … }. Schreibzeug nimmt sie nur von seinem Elternfenster unter
SCHREIBZEUG_EMBED_ORIGIN an und schickt sie nur dorthin (embed/messages.ts); Kontext prüft
dasselbe in die andere Richtung (src/features/documents/messages.ts in Kontext).
| Von | type |
Was |
|---|---|---|
| Schreibzeug | ready |
Die App läuft; Kontext schickt das Design |
| Schreibzeug | route |
Die gezeigte Seite (path), für die Adressleiste von Kontext (/documents/edit/…) |
| Schreibzeug | title |
Der Name des offenen Dokuments, null, wenn keins offen ist |
| Schreibzeug | unsaved |
Änderungen, die der Server noch nicht hat; Kontext markiert das Modul |
| Schreibzeug | shortcut |
Eine der Tasten von Kontext (1–9, ?), außerhalb eines Felds gedrückt; im Dokument behält der Frame der Engine die Tasten |
| Schreibzeug | signed-out |
Die Antwort auf logout |
| Kontext | theme |
light oder dark |
| Kontext | navigate |
Eine Seite der App öffnen (path; nur Pfade der App, nie eine andere Site) |
| Kontext | logout |
Kontext meldet ab: Schreibzeug ebenfalls, bevor Kontext den Frame entfernt |
Tokens von Kontext¶
Wo sich Mail und Dokumente berühren (ein Anhang in einen Ordner, ein Dokument an eine Mail), ruft
der Server von Kontext die API von Schreibzeug selbst auf, nie über den Browser. Er schickt
Authorization: Bearer <token>: ein JWT, das Kontext mit seinen Anbieterschlüsseln für eine Person
signiert, fünf Minuten gültig, mit Kontext als Issuer und SCHREIBZEUG_URL als Audience. Ein
ID-Token nennt die Client-ID als Audience und wird abgelehnt. apps/server/src/auth/bearer.ts
prüft es gegen die Schlüssel aus dem Discovery-Dokument des Anbieters: signiert mit einem
asymmetrischen Algorithmus (EdDSA, ES, RS, PS*), mit sub, iat und exp und nicht älter als
zehn Minuten; ein Token, das einen Client nennt (azp oder client_id), muss OIDC_CLIENT_ID
nennen, sodass ein Token, das der Anbieter für einen anderen Client erstellt hat, abgelehnt wird.
Es findet die Person über sub (das Konto, das die Anmeldung behält), sonst über die Adresse, sonst
legt es sie an; die Anfrage hat dann genau die Rechte dieser Person. Über die Adresse nur so, wie
Better Auth eine Anmeldung verknüpft: Die Adresse des Kontos muss bestätigt sein, das Token muss
sie ebenfalls bestätigen (email_verified: true), und das Konto darf nicht schon zu einem anderen
sub gehören. Ein neues Konto aus einem Token hat seine Adresse bestätigt und bekommt, was mit ihr
geteilt wurde, ebenfalls nur mit email_verified: true; eines, das unbestätigt angelegt wurde,
wird durch das erste spätere Token, das es sagt, bestätigt und bekommt, was auf seine Adresse
gewartet hat. Ein Konto, das jemand mit Passwort unter der Adresse einer Kollegin registriert hat,
wird abgelehnt, ebenso eine neue Person bei Kontext, die die Adresse eines früheren Kollegen
bekommen hat; das erste Konto aus einem Token übernimmt die Dateien aus der Zeit vor den Konten,
wie bei einer Registrierung.
DELETE /api/sessions mit einem solchen Token meldet diese Person hier überall ab (ihre Sitzungen
und ihre persönlichen Zugriffstokens für MCP-Clients, MCP-Server,
verschwinden, und die Sockets ihrer offenen Editoren schließen: Der Editor hört auf weiterzuleiten
und zeigt, dass die Sitzung beendet ist). Kontext ruft es auf, wenn jemand die Firma verlässt oder
gesperrt wird, sodass Dokumente mit Kontext schließt. Für jemanden ohne Konto hier tut es nichts und
legt keins an.
Dateien in Kontext¶
Kontext legt Dateien aus Dokumente dorthin, wo sie hingehören: als Karte in seinen Chat, verknüpft
mit einer Aufgabe, angehängt an einen Termin. Jede öffnet /documents/edit/<id> im Modul. Damit die
Leute dort sie öffnen dürfen, teilt der Server von Kontext die Datei mit ihnen zum Ansehen, als ihr
Eigentümer, mit dem Token des Eigentümers (PUT /api/nodes/:id/shares). Kollegen, die Dokumente nie
geöffnet haben, haben noch kein Konto; ihre Freigabe wartet auf ihre Adresse und gilt ab ihrer
ersten Anmeldung über Kontext (Konten).
Ein geteiltes Postfach von Kontext (info@, rechnung@) ist hier ebenfalls eine Person: Kontext
schickt Tokens dafür (Subject mailbox:<account id>, die Adresse des Postfachs), es bekommt also
ein eigenes Konto mit einem Ordner, der nach seiner Adresse benannt ist. Kontext hält diesen Ordner
mit den Leuten des Postfachs geteilt (Mitglieder edit, Leser view) und nimmt die Freigabe
zurück, wenn jemand ausscheidet; sie finden ihn unter „Für mich freigegeben“. Niemand meldet sich
als das Postfach an: Es hat kein Passwort und keine Anmeldung über Kontext.
Einstellungen¶
| Variable | |
|---|---|
SCHREIBZEUG_URL |
Wo Browser Schreibzeug erreichen (https://dokumente.firma.de): die Basis-URL von Better Auth (der Callback) und die Audience der Tokens von Kontext. Pflicht mit den OIDC-Einstellungen: Der Server startet nicht ohne sie, damit der Callback nie dem Host folgt, den eine Anfrage nennt |
OIDC_ISSUER |
Der Issuer des Anbieters, für Kontext https://kontext.firma.de/api/auth |
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET |
Wie beim Anbieter registriert; Kontext: schreibzeug und sein SCHREIBZEUG_CLIENT_SECRET |
OIDC_NAME |
Der Name auf dem Button, Standard Kontext |
SCHREIBZEUG_EMBED_ORIGIN |
Der eine Origin, der Schreibzeug in einem Frame zeigen darf (https://kontext.firma.de) |
Die Anmeldung über den Anbieter braucht Issuer, Client-ID und Secret; ohne sie gibt es nur E-Mail
und Passwort. Mit ihnen braucht sie auch SCHREIBZEUG_URL, sonst startet der Server nicht: Sonst
würde Better Auth seine Basis-URL, und damit die redirect_uri der Anmeldung, aus dem Host jeder
Anfrage nehmen (apps/server/src/config.ts). Die deploy/compose.yaml von Kontext betreibt
Schreibzeug mit dem Profil documents, aus dem Image tristanteu/schreibzeug
(docker/Dockerfile; Release veröffentlicht es auf Docker Hub und GHCR, wenn ein v*-Tag
gepusht wird, Installation).
Tests¶
apps/server/test/pending-shares.test.ts: Eine Freigabe an eine Adresse, die wartet, gilt, sobald
die Person über Kontext kommt, geht nie an eine Registrierung mit Passwort (auch nicht an eine, die
vor der Freigabe angelegt wurde), gilt aber, sobald dieses Konto mit Kontext verbunden ist, wartet
bei einem Token ohne email_verified und kann zurückgenommen werden.
apps/server/test/bearer.test.ts: Tokens, nach Subject zugeordnet, über eine bestätigte Adresse
gefunden, nie für ein Passwort-Konto unter der Adresse eines anderen oder für ein zweites Subject,
ein neues Konto, die Dateien aus der Zeit vor den Konten, das Beenden der Sitzungen einer Person,
email_verified, abgelehnte Audience, Issuer, Subject, andere Clients (azp, client_id),
fehlender Ablauf, Alter und Datenmüll; apps/server/test/web.test.ts: frame-ancestors;
apps/web/src/embed/messages.test.ts: Prüfungen von Origin und Fenster, wann die App als
eingebettet gilt, Pfade und Tasten. e2e/kontext.spec.ts läuft gegen einen Ersatz für Kontext
(e2e/fake-kontext.ts: Discovery, Authorize mit PKCE und prompt=none, Token, Userinfo,
Schlüssel und eine Seite mit dem Frame) und einen eigenen Server, der sich darüber anmeldet
(e2e/kontext-server.ts): Anmelden mit Kontext, der Frame mit stiller Anmeldung, Design,
Navigation und Abmeldung, die Anmeldeseite, wenn bei Kontext niemand angemeldet ist, ein Konto mit
Passwort, das nach der Anmeldung mit dem Passwort verbunden wird, und der Parameter ohne Frame.