Sicherheit und CSP

Origin-Allowlist#

Die Einbettung schlägt standardmäßig fehl (Fail-Closed), sofern sie nicht aktiviert ist und die exakte übergeordnete Origin des Browsers zugelassen wurde. Eine Origin hat das Format scheme://hostname[:port]; Pfade und Query-Strings gehören nicht dazu.

Fügen Sie Produktions-, Vorschau- und lokale Origins jeweils separat hinzu. Fügen Sie keinen Platzhalter (Wildcard) hinzu, um einen Installationsfehler zu beheben: Andernfalls könnte jeder, der einen öffentlichen Slug kopiert, den Agent einbetten und die Credits der Website verbrauchen.

Content Security Policy#

Der Loader benötigt die Berechtigung für Skripte, das Widget die Berechtigung für Frames, und die Erscheinungsbild-Anfrage des Loaders benötigt unter Umständen die Berechtigung für Verbindungen. Führen Sie diese Quellen mit den bestehenden Direktiven des Hosts zusammen; ersetzen Sie eine ausgereifte Richtlinie nicht durch dieses minimale Beispiel.

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;

Wenn die Website script-src-elem verwendet, fügen Sie https://makeagent.fast auch dort hinzu. Der externe Loader benötigt kein unsafe-inline, das Framework des Hosts kann jedoch eigene Anforderungen an Nonces oder Hashes haben. Während der Tests ist eine Report-Only-Richtlinie hilfreich:

Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;

Wenn die Browser-Konsole einen CSP-Verstoß meldet, ändern Sie die genannte Direktive – nicht pauschal default-src – und testen Sie die öffentliche Seite erneut.

Mikrofon und Browser-Berechtigungen#

Der Loader erstellt das iframe mit allow="microphone; autoplay; clipboard-write". Eine strengere Permissions Policy auf Host-Ebene kann diese Berechtigung dennoch überschreiben. Wenn Sprache aktiviert ist, erlauben Sie die Frame-Origin von Make Agent Fast in der Antwort des Hosts:

Permissions-Policy: microphone=(self "https://makeagent.fast")

Der Besucher muss außerdem den Mikrofonzugriff im Browser gewähren. Testen Sie über HTTPS; Browser schränken den Mikrofonzugriff auf unsicheren öffentlichen Origins in der Regel ein. Der Text-Chat benötigt keine Mikrofonberechtigung.

Grenze für Nachrichten und Frames#

Der Loader akzeptiert nur maf:ready, maf:open, maf:close sowie Theme-Lebenszyklusnachrichten, die dem aktuellen Site-Slug zugeordnet sind. Eingehende Frame-Nachrichten werden gegen https://makeagent.fast geprüft. Kopieren Sie den Loader nicht in Ihr eigenes Bundle und entfernen Sie diese Origin-Validierung nicht.

Code auf der Host-Seite sollte nicht versuchen, auf das DOM des iframes zuzugreifen. Der Frame ist bewusst Cross-Origin; die unterstützte Integrationsschnittstelle besteht aus dem Loader, seinen dokumentierten data-*-Attributen und den unten beschriebenen Identitätsmethoden.

Geheimnisse und Besucheridentität#

Der Site-Slug und die Loader-URL sind öffentlich. Alles andere gehört nicht in den Seitenquelltext:

• Fügen Sie dem Snippet niemals einen MAF-API-Schlüssel, OAuth-Token, KI-Anbieter-Schlüssel, Connector-Token oder ein Webhook-Geheimnis hinzu.
• Binden Sie niemals ein Geheimnis in ein JavaScript-Bundle ein und machen Sie es nicht über NEXT_PUBLIC_*, VITE_* oder ähnliche Umgebungsvariablen im Browser zugänglich.
• Verwenden Sie eine serverseitige API-Integration, wenn Ihre Anwendung Sites erstellen, Agents aktualisieren oder private Workspace-Daten abrufen muss.
• Legen Sie keine E-Mail-Adressen, Konto-IDs oder anderen Besucherdaten in data-label, data-locale oder Query-Parametern ab.

Angemeldete Kunden identifizieren#

Erstellen Sie unter Agent → Aktionen → Angemeldete Kunden ein Geheimnis und kopieren Sie es, sobald es angezeigt wird. Speichern Sie es ausschließlich auf Ihrem Server als MAF_SECRET_KEY; legen Sie es niemals in Browser-Code, öffentlichen Umgebungsvariablen oder einem Repository ab. Dieses Agent-Geheimnis ist von einem Workspace-API-Schlüssel getrennt. Eine Rotation macht alte Tokens ungültig und ändert den Signaturschlüssel für Lookups; das Entfernen deaktiviert die verifizierte Kundenidentität und Lookups, bis erneut ein Geheimnis konfiguriert wird.

Verwenden Sie in Ihrem bestehenden Snippet die aktualisierte Loader-URL https://makeagent.fast/embed.js?v=20261022-open. Ältere versionierte URLs können bis zu einem Jahr im Cache bleiben und stellen dieses SDK nicht bereit. Behalten Sie Ihre Origin-Allowlist und die CSP-Schutzmaßnahmen bei.

Ihr authentifizierter Server sollte das Token anhand des Kunden aus seiner eigenen Sitzung ausstellen. Akzeptieren Sie niemals eine beliebige Kunden-ID aus dem Browser als zu signierende Identität. Dieser Helper läuft ausschließlich auf dem Server:

import { createHmac } from "node:crypto";

export function signCustomerIdentity(customer) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const now = Math.floor(Date.now() / 1000);
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    sub: customer.id,
    email: customer.email,
    name: customer.name,
    iat: now,
    exp: now + 3600,
  });
  const body = `${header}.${payload}`;
  const signature = createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}

Der Header muss alg: "HS256" und typ: "JWT" enthalten. sub ist ein stabiler, nicht leerer String mit bis zu 128 Zeichen; exp ist ein ganzzahliger Unix-Zeitstempel in Sekunden, der in der Zukunft liegt und höchstens 24 Stunden voraus ist. Das optionale iat ist eine ganze Zahl; das optionale email muss gültig sein und darf höchstens 160 Zeichen lang sein; das optionale name darf höchstens 120 Zeichen lang sein. Das vollständige Token darf höchstens 2.048 Zeichen umfassen. Lassen Sie optionale Claims weg, die Sie nicht benötigen. JWT-Payloads sind signiert, aber nicht verschlüsselt.

Geben Sie das Token ausschließlich über HTTPS und mit Cache-Control: no-store an diese authentifizierte Browsersitzung zurück. Protokollieren Sie es nicht, fügen Sie es nicht zu URLs hinzu und speichern Sie es nicht in localStorage. Übergeben Sie nach dem Laden von embed.js das Token aus dieser Antwort an das Widget:

window.MakeAgentFast.identify(token);

Für die Initialisierung, bevor der Loader ausgeführt wird, setzen Sie stattdessen window.MakeAgentFastSettings = { identityToken: token } im Bootstrap Ihrer Anwendung. Der Loader behält das aktuelle Token im Arbeitsspeicher und leitet es weiter, sobald der Frame bereit ist. Erneuern Sie das Token von Ihrem authentifizierten Server vor Ablauf und rufen Sie identify erneut auf. Jede Chat-Anfrage enthält es; Konversationsanfragen verwenden x-maf-identity. Eine verifizierte Host-Identität stützt sich nie auf ein af_xid-Cookie.

Wenn sich Ihre Anwendung abmeldet, rufen Sie Folgendes auf, bevor der Chat eines anderen Kontos angezeigt wird, und löschen Sie jedes Bootstrap-Token, das Ihre Anwendung zwischengespeichert hat:

window.MakeAgentFast.logout();

Dadurch werden die Widget-Identität und der lokale Konversations-Cache zurückgesetzt; der Kunde wird dadurch nicht aus Ihrer eigenen Anwendung abgemeldet und ein kopiertes Token wird nicht widerrufen. Auch das sub eines anderen Kunden leert den Widget-Cache. Ungültige, abgelaufene oder für einen anderen Agent ausgestellte Tokens können nicht auf den Verlauf dieses angemeldeten Kunden zugreifen und fallen auf den normalen Besucherpfad zurück. Verwenden Sie kurze Ablaufzeiten und halten Sie die Geheimnisse der einzelnen Agents getrennt. Die Owner-Probe ignoriert Identitäts-Tokens; prüfen Sie die Isolierung in der tatsächlichen Einbettung mit zwei separaten Testkonten.

Einwilligung, Datenschutz und Aufbewahrung#

Stufen Sie die Einbettung gemäß Ihrer Datenschutz- und Einwilligungsrichtlinie ein. Wenn Ihr Consent-Manager nicht notwendige Skripte von Drittanbietern blockiert, laden Sie embed.js erst nach der entsprechenden Einwilligung. Zeigen Sie bis dahin einen normalen Link oder einen deaktivierten Platzhalter an, anstatt den Manager zu umgehen.

Informieren Sie Besucher, wenn die Anwendung KI, Mikrofonaufnahme, Lead-Erfassung, Analysen oder einen externen Messaging-Anbieter nutzt, soweit dies Ihre Richtlinie und das geltende Recht verlangen. Klären Sie vor dem Start den Prozess für die Aufbewahrung und Löschung von Konversationen auf Ihrer Website; das Trennen oder Entfernen der Einbettung löscht bestehende Konversationen nicht von selbst.

Sicherheits-Checkliste für den Livegang#

• Die Kunden-Website ist bereitgestellt, und der eingebettete Agent ist aktiviert und getestet.
• Nur exakte, vorgesehene übergeordnete Origins stehen in der Allowlist.
• Die CSP des Hosts erlaubt das Skript, den Frame und die Erscheinungsbild-Anfrage ohne breite Platzhalter.
• Das Mikrofon ist nur erlaubt, wenn Sprache aktiviert und über HTTPS getestet wurde.
• Kein Zugangsdatum und kein privater Besucherwert erscheint in HTML, Bundle-Ausgabe oder Browser-Logs.
• Das Verhalten des Consent-Managers wurde vor und nach der Einwilligung getestet.
• Ein kopiertes Snippet schlägt auf einer Origin fehl, die nicht in der Allowlist steht.