Auslieferung und Sicherheit des Widgets

Das Widget besteht aus einem kleinen Lader auf Ihrer Seite und einem Chatfenster, das in einem eigenen Rahmen läuft. Hier steht, wie beide ausgeliefert werden, welche Köpfe sie tragen, mit welchen Prüfsummen das Chatfenster seine Teile lädt, wie die Schnittstelle einen Widgetschlüssel prüft und welche Grenzen je Besucher gelten. Wie Sie das Widget einbauen, beschreibt Widget einbauen.

Die Dateien des Widgets

Die Auslieferung unter https://cdn.xicbot.de kennt genau vier Dateien. Liefern Sie das Widget über Ihre eigene Domain aus, stehen dieselben Dateien unter Ihrem Pfad, siehe Eigener Pfad auf Ihrer Domain.

• Die Wurzel / liefert rahmen.html.
• Eine Anfrage mit HEAD erhält dieselben Köpfe, aber keinen Inhalt.
• Jeder andere Name, auch eine veraltete Fassung, erhält Status 404 mit dem Text nicht gefunden.

Fassungsnamen und Zwischenspeicher

Jede Datei ist unter zwei Namen erreichbar: unter ihrem Einstiegsnamen, etwa rahmen.js, und unter einem Fassungsnamen wie rahmen.1a2b3c4d5e.js. Die zehn Hexadezimalzeichen sind der Anfang der SHA-256-Summe des ausgelieferten Inhalts; ändert sich die Datei, ändert sich ihr Fassungsname. Bei rahmen.html wird die Summe erst gebildet, nachdem die Verweise auf die beiden anderen Teile eingesetzt sind. Eine neue Fassung von rahmen.css oder rahmen.js ergibt deshalb auch eine neue Fassung des Gerüsts.

• Ausgeliefert wird nur die geltende Fassung. Passt die Kennung in einem Fassungsnamen nicht zum aktuellen Inhalt, antwortet die Auslieferung mit 404 nicht gefunden, statt unter dem alten Namen still einen neuen Inhalt zu liefern.
• Jede Datei nennt ihre Fassung im Kopf X-Xicbot-Version.
• Der Einbaucode verweist auf den Einstiegsnamen einbetten.js. Eine neue Widgetfassung erreicht Ihre Seite deshalb ohne Änderung am Einbaucode, sobald die fünf Minuten des Zwischenspeichers abgelaufen sind.

Prüfsummen im Chatfenster

Im Quelltext verweist rahmen.html auf die Einstiegsnamen rahmen.css und rahmen.js. Beim Ausliefern ersetzt die Auslieferung beide Verweise durch die Fassungsnamen und setzt die SHA-384-Summe des jeweiligen Inhalts als integrity dazu. Der Browser lädt die Teile damit aus dem Zwischenspeicher, solange die Fassung gilt, und verwirft eine Datei, deren Inhalt nicht zur Summe passt.

<link rel="stylesheet" href="rahmen.<fassung>.css" integrity="sha384-…" crossorigin="anonymous">
<script src="rahmen.<fassung>.js" integrity="sha384-…" crossorigin="anonymous"></script>

crossorigin="anonymous" ist dabei nötig. Das Chatfenster hat einen undurchsichtigen Ursprung, jede seiner Anfragen gilt als herkunftsfremd. Ohne das Attribut bliebe die Antwort für den Browser verschlossen und die Prüfung schlüge fehl. Damit die Teile trotzdem geladen werden, sendet die Auslieferung zu jeder Datei Access-Control-Allow-Origin: * und Cross-Origin-Resource-Policy: cross-origin.

Übersicht der Fassungen

/version.json listet die geltenden Fassungen aller vier Dateien. Die Antwort wird nicht zwischengespeichert (no-store) und darf von jeder Seite gelesen werden (Access-Control-Allow-Origin: *).

# Geltende Fassungen abrufen
curl -s https://cdn.xicbot.de/version.json
# Köpfe des Laders ansehen
curl -sI https://cdn.xicbot.de/einbetten.js

Sicherheitsrichtlinie des Chatfensters

rahmen.html kommt mit einer eigenen Richtlinie im Kopf Content-Security-Policy. Sie gilt nur im Chatfenster, nicht auf Ihrer Seite; was Ihre eigene Richtlinie erlauben muss, steht unter Sicherheitsrichtlinie Ihrer Seite. Die Adressen darin sind die Basis, von der das Chatfenster geladen wird, und die Adresse der Schnittstelle, beim eigenen Pfad also Ihre Domain.

• Der Schrägstrich am Ende begrenzt die Erlaubnis auf den Pfad der Basis. Beim eigenen Pfad https://example.com/chat gilt sie für https://example.com/chat/, nicht für den Rest der Domain.
• Die Trennung von Ihrer Seite leistet die Sandbox des Rahmens, nicht frame-ancestors, siehe Abschottung von Ihrer Seite.

Antwortköpfe

Jede der vier Dateien kommt mit diesen Köpfen:

• Vary ist nötig, weil die Richtlinie an den Köpfen X-Xicbot-Base und X-Xicbot-Api hängt. Ohne ihn könnte ein Zwischenspeicher das Gerüst mit der Richtlinie eines Kunden an den nächsten ausliefern.
• X-Frame-Options fehlt mit Absicht. Ein solcher Kopf würde das Einbetten in Ihre Seite verhindern.
• Unter cdn.xicbot.de kommen Strict-Transport-Security: max-age=31536000; includeSubDomains und X-Robots-Tag: noindex, nofollow hinzu, siehe Die beiden Einbauwege. Das noindex im Gerüst rahmen.html gilt auf beiden Wegen, auch über Ihren eigenen Pfad.
• version.json trägt nur Content-Type, X-Content-Type-Options, Access-Control-Allow-Origin und Cache-Control.

Adressen in den Köpfen

Beim eigenen Pfad setzt Ihr Server die Köpfe X-Xicbot-Base und X-Xicbot-Api, siehe Was Ihr Server weiterreicht. Unter cdn.xicbot.de setzt XICBOT sie selbst und ersetzt dabei jeden gleichnamigen Kopf, den ein Besucher mitschickt. Aus diesen Adressen entstehen die Richtlinie des Chatfensters und die Felder origin und api in version.json.

• Erlaubt ist http:// oder https://, ein Rechnername aus Kleinbuchstaben, Ziffern, Punkt und Bindestrich, optional ein Port und ein Pfad aus Buchstaben, Ziffern und den Zeichen ., _, ~ und -.
• Höchstens 200 Zeichen. Leerraum am Rand wird entfernt, ebenso ein Schrägstrich am Ende.
• Die Prüfung ist streng, weil die Adresse in die Richtlinie wandert: Ein Semikolon oder Leerzeichen darin ergäbe eine zusätzliche Anweisung.
• Ein gesetzter, aber unbrauchbarer Kopf ergibt Status 400 mit dem Text kopf ungueltig, statt still auf die Standardadresse zurückzufallen.
• Fehlt X-Xicbot-Api, gilt X-Xicbot-Base auch für die Schnittstelle.

Abschottung von Ihrer Seite

Im Abschnitt Chatfenster auf Ihrer Website steht in der App: Das Chatfenster läuft in einem eigenen Rahmen. Es kann die Seite, auf der es liegt, weder lesen noch verändern. Umgesetzt ist das so:

• Der Rahmen trägt sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox" ohne allow-same-origin, dazu referrerpolicy="no-referrer", loading="eager" und den Titel Chat.
• Ohne allow-same-origin hat das Chatfenster einen undurchsichtigen Ursprung. Ihre Seite kann seinen Inhalt nicht lesen und das Chatfenster Ihren nicht. Den Verlauf schützt das allein nicht: Wer die Gesprächskennung aus dem Speicher Ihrer Seite kennt, kann ihn über die Schnittstelle abrufen.
• Der Lader übergibt seine Angaben im Fragment der Rahmenadresse hinter #: Schlüssel, Adresse der Schnittstelle, Ursprung Ihrer Seite, Position, Sprache, Darstellung, die Kennung eines laufenden Gesprächs sowie Schriftart, Kantenrundung und Markenfarbe Ihrer Seite. Ein Fragment geht an keinen Server und steht deshalb in keinem Zugriffsprotokoll.
• Der Lader selbst stellt keine Anfrage ans Netz. Alles, was Daten holt, läuft im Chatfenster.
• Das Chatfenster fragt die Schnittstelle ohne Cookies und ohne Anmeldung ab (credentials: omit) und nennt dabei keine Herkunftsseite.
• Freigabeköpfe für herkunftsfremde Anfragen sendet die Schnittstelle nur unter /api/v1/public/: für den Ursprung null, den ein solcher Rahmen sendet, für die eigenen Ursprünge von App und Auslieferung sowie für Ursprünge, die XICBOT ausdrücklich zulässt. Erlaubt sind GET, POST, DELETE und OPTIONS mit den Köpfen Content-Type und Accept. Lesbar ist der Kopf Retry-After, eine Vorabfrage gilt 600 Sekunden, Anfragen mit Zugangsdaten gibt sie nicht frei.
• Nachrichten zwischen Lader und Chatfenster prüfen beide Seiten auf Absender und Ursprung, siehe Prüfungen auf beiden Seiten.
• Der Rahmen wird erst gebaut, wenn Ihre Seite fertig geladen ist. Ist das Einwilligungstor gesetzt, wartet er auf die Zustimmung, siehe Einwilligung und Besucherrechte.
• Ohne data-xicbot baut der Lader nichts. Ein zweiter Lader auf derselben Seite bleibt ohne Wirkung.

Schlüsselprüfung der Schnittstelle

Jede Anfrage unter /api/v1/public/widget/{key}/ prüft zuerst den öffentlichen Schlüssel des Assistenten. Am Assistenten entscheiden zwei getrennte Schalter: Er muss auf aktiv stehen, und Chatfenster freigeben muss eingeschaltet sein. Ein unbekannter, ein abgeschalteter, ein pausierter und ein noch im Entwurf stehender Assistent antworten gleich, damit sich durch Raten nicht erkennen lässt, ob ein Schlüssel stimmt.

Nur unknown_widget und demo_expired lassen das Chatfenster verschwinden: Es meldet dem Lader, dass der Assistent nicht mehr da ist, und der Lader entfernt Auslöser, Sprechblase und Rahmen von Ihrer Seite. Ein 404 ohne einen dieser Codes stammt in der Regel von einer falschen Adresse, etwa data-api mit dem falschen Rechner, und gilt als Störung.

Beim Gesprächsbeginn nennt das Chatfenster den Ursprung Ihrer Seite, wie ihn der Lader übergeben hat. Verglichen wird der Rechnername in Kleinbuchstaben, gekürzt auf 120 Zeichen. Ein Eintrag in Erlaubte Domains schließt seine Unterdomains ein; ist die Liste leer, kann auf jeder Website ein Gespräch beginnen. Mehr dazu unter Erlaubte Domains.

Grenzen je Besucher

Als ein Besucher gilt eine Herkunftsadresse zusammen mit dem Widgetschlüssel. IPv4-Adressen zählen einzeln, IPv6-Adressen je /64-Netz, weil ein Anschluss dort ein ganzes Netz erhält. Eine IPv4-Adresse in IPv6-Schreibweise zählt als IPv4-Adresse. Der Schlüssel allein ließe einen einzelnen Besucher die Grenze für alle aufbrauchen. Besucher hinter einem gemeinsamen Ausgang, etwa im Netz einer Firma, im Mobilfunk oder im selben /64-Netz, gelten dagegen als ein Besucher und teilen sich die Grenzen dieses Widgets.

• Die ersten beiden Grenzen gelten für alle Konten gleich. Die beiden anderen nehmen ihre Werte aus Ihrem Konto, gezählt wird aber ebenfalls je Besucher und Schlüssel: Ein Besucher, der viel schreibt, bremst niemanden an einer anderen Adresse oder, bei IPv6, in einem anderen /64-Netz.
• Jede Grenze nach Ihrem Konto hat einen Minutenwert gegen den Ansturm und einen Tageswert gegen Dauerlast.
• Gehört ein Aufruf zu einem Gespräch, zählt neben der Adresse auch das Gespräch, mit denselben Werten. Jeder der beiden Zähler kann abweisen, erhöht werden sie nur, wenn keiner abgewiesen hat. Der Zähler des Gesprächs hebt die gemeinsame Grenze einer Adresse nicht auf.
• Den Minutenwert für Aufrufe legt Ihr Paket fest, siehe Pakete und Kontingente. Die Werte für Fragen stellt XICBOT für Ihr Konto ein.
• Ein Wert unter 1 schaltet eine Grenze nach Ihrem Konto ab.
• Anhänge zählen nur gegen die ersten beiden Grenzen.

Antwort bei Überschreitung

Eine Grenze nach Ihrem Konto antwortet mit Status 429, dem Kopf Retry-After und diesem Rumpf. wait nennt die Wartezeit in Sekunden, dieselbe Zahl wie Retry-After; die beiden Grenzwerte sind die Ihres Kontos.

{
  "error": "too_many_requests",
  "limit_per_min": 10,
  "limit_per_day": 200,
  "wait": 42
}

Die Grenzen widget und widget-send antworten ebenfalls mit 429 und Retry-After, aber ohne wait im Rumpf. Allgemeine Grenzen der Schnittstelle stehen unter API-Grenzen, die Endpunkte selbst unter API: Widget.

Verhalten des Chatfensters bei Störungen

Nach einem 429 wartet das Chatfenster so lange, wie wait im Rumpf nennt. Fehlt wait, liest es Retry-After, sonst gilt ein Ersatzwert. Die Wartezeit liegt zwischen einer Sekunde und einer Stunde; ab 90 Sekunden zeigt das Fenster sie in Minuten an. Die Wortlaute aller Meldungen stehen unter Meldungen.

Prüfung der Auslieferung in der App

Bei jedem Abruf des Einbaucodes prüft XICBOT neu, ob die ausgelieferte Datei einbetten.js lesbar ist, statt sich auf einen gespeicherten Wert zu verlassen. Ist sie es nicht, erscheint unter Einbaucode über unsere Adresse die Meldung Die ausgelieferte Widgetdatei ließ sich nicht lesen. Der Einbaucode steht, aber die Auslieferung selbst sollte geprüft werden. Der Einbaucode bleibt kopierbar. Geben Sie uns in diesem Fall unter mail@xicbot.de Bescheid.

Über die Schnittstelle liefert GET /api/v1/assistants/{id}/embed dazu das Feld reason: file_missing, wenn die Datei fehlt oder nicht zum Lesen zugänglich ist, file_unreadable, wenn das Einlesen trotzdem scheitert, sonst null.

Weiterlesen

• Widget einbauen: Einbaucode, eigener Pfad, erlaubte Domains und Meldungen.
• JavaScript und Speicher: die Schnittstelle des Laders auf Ihrer Seite.
• Einwilligung und Besucherrechte: Einwilligungstor und Widerruf.
• API: Widget: die öffentlichen Endpunkte des Chatfensters.
• API-Grenzen: Grenzen der übrigen Schnittstelle.
• Pakete und Kontingente: was Ihr Paket festlegt.
• Datensicherheit: wie XICBOT Daten schützt.

Häufige Fragen