Capabilities und Sicherheit

Sandboxed Plugins sind standardmäßig isoliert. Um etwas über das Lesen und Schreiben ihres eigenen KV und Speichers hinaus zu tun, muss ein Plugin eine Capability deklarieren auf seinem Descriptor. Die Sandbox-Bridge sperrt jede vom Host bereitgestellte API basierend auf diesen Deklarationen – ein Plugin, das content:read nicht deklariert hat, erhält kein ctx.content, und eines, das network:request nicht deklariert hat, erhält kein ctx.http.

Diese Seite behandelt, was jede Capability gewährt, wie die Sandbox sie durchsetzt und was nicht durchsetzbar ist.

Capabilities deklarieren

Capabilities befinden sich auf dem Descriptor (der Datei, die von astro.config.mjs importiert wird), neben id, version und entrypoint:

export function helloPlugin(): PluginDescriptor {
	return {
		id: "plugin-hello",
		version: "0.1.0",
		format: "standard",
		entrypoint: "@my-org/plugin-hello/sandbox",

		capabilities: ["content:read", "network:request"],
		allowedHosts: ["api.example.com"],
	};
}

Deklarieren Sie nur, was das Plugin tatsächlich benötigt. Capability-Deklarationen sind auch das, was der Marketplace Site-Betreibern im Zustimmungsdialog anzeigt – zusätzliche Capabilities sind Reibung zum Installationszeitpunkt und ein Sicherheitsflag bei Audits.

Capability-Referenz

Ein paar wissenswerte Dinge:

• Implikationen. content:write impliziert automatisch content:read; media:write impliziert media:read; network:request:unrestricted impliziert network:request. Sie müssen nicht beide auflisten.
• network:request:unrestricted existiert für benutzerkonfigurierte URLs. Ein Webhook-Plugin, bei dem der Betreiber die Ziel-URL eingibt, muss Hosts erreichen, die nicht im Manifest stehen. Plugins, die immer bekannte APIs aufrufen, sollten network:request + allowedHosts verwenden.
• email:send wird durch Konfiguration gesperrt, nicht nur durch die Capability. Ein Plugin kann email:send deklarieren, aber ctx.email wird nur gefüllt, wenn ein anderes Plugin einen email:deliver Transport registriert hat.

Network Host Allowlists

Plugins mit network:request können nur Hosts abrufen, die in allowedHosts aufgelistet sind. Wildcards werden für Subdomains unterstützt:

capabilities: ["network:request"],
allowedHosts: [
	"api.example.com",          // exakter Host
	"*.cdn.example.com",        // jede Subdomain von cdn.example.com
],

Die Bridge überprüft den Host der Request-URL gegen die Allowlist, bevor sie die Anfrage weiterleitet. Eine Anfrage an einen Host, der nicht deklariert wurde, wirft innerhalb des Plugins, ohne jemals die Sandbox zu verlassen.

network:request:unrestricted überspringt die Allowlist-Prüfung vollständig. Es ist für Plugins gedacht, bei denen der Betreiber die Ziel-URL zur Laufzeit konfiguriert (Webhook-Sender, generische HTTP-Forwarder). Vermeiden Sie es für Plugins, bei denen das Ziel Teil des Plugin-Designs ist – deklarieren Sie stattdessen network:request mit expliziten Hosts, damit der Zustimmungsdialog den Betreibern genau sagt, wohin das Plugin aufrufen wird.

Was die Sandbox durchsetzt

Wenn ein Sandbox-Runner aktiv ist, setzt die Runtime durch:

Was die Sandbox nicht durchsetzt

Ein paar Dinge, die das Capability-System nicht abdecken kann:

• Verhalten innerhalb einer gewährten Capability. Ein Plugin mit content:write kann jeden Inhalt bearbeiten, nicht nur seinen eigenen. Capabilities sind grob – sie sagen “dieses Plugin kann Inhalte schreiben”, nicht “dieses Plugin kann nur die Inhalte schreiben, die es erstellt hat”. Audit-Zeit-Review ist die einzige Überprüfung dessen, was ein Plugin tatsächlich innerhalb seiner Berechtigung tut.
• Betreibervertrauen auf Node.js. Wenn der konfigurierte Sandbox-Runner als nicht verfügbar meldet (kein Cloudflare Worker Loader, kein Node-seitiger Runner installiert usw.), werden sandboxed: [] Plugins beim Start übersprungen. Sie können sie in plugins: [] verschieben, um sie in-process auszuführen – aber dann gibt es kein V8-Isolat, keine Ressourcenlimits, und das Plugin kann fetch() direkt aufrufen oder Umgebungsvariablen lesen. Behandeln Sie das als native-level Vertrauen.
• Side Channels. Timing, Log-Ausgabe und gespeicherte Daten sind alle für jeden mit entsprechendem Zugriff auf die Host-Umgebung sichtbar. Verwenden Sie die Sandbox nicht als Vertraulichkeitsgrenze gegen den Betreiber, der sie ausführt.

Capability-Zustimmung

Wenn ein Betreiber ein sandboxed Plugin aus dem Marketplace installiert, zeigt EmDash einen Zustimmungsdialog an, der die deklarierten Capabilities auflistet. Updates, die Capabilities hinzufügen – zum Beispiel ein Plugin, das zuvor nur Inhalte gelesen hat, jetzt aber Netzwerkanfragen stellen möchte – erscheinen als Capability-Diff und erfordern eine neue Genehmigung, bevor die neue Version wirksam wird.

Deshalb ist es wichtig, zusätzliche Capabilities zu deklarieren, auch wenn Sie sie “später vielleicht verwenden”. Sie tauchen bei jeder Installation und jedem Update als Reibung auf, und Sicherheitsaudits flaggen Plugins, die mehr verlangen, als sie offensichtlich benötigen. Listen Sie genau das auf, was das Plugin verwendet, und fügen Sie neue Capabilities in einer echten Version hinzu, wenn das Plugin sie tatsächlich zu verwenden beginnt.

Bundle-Zeit-Validierung

emdash plugin bundle und emdash plugin publish führen zusätzliche Prüfungen durch:

• Jede deklarierte Capability muss im bekannten Set sein (Tippfehler schlagen den Build fehl).
• Ein Plugin, das network:request deklariert, ohne allowedHosts zu füllen, löst eine Warnung aus – deklarieren Sie Hosts oder wechseln Sie zu network:request:unrestricted und dokumentieren Sie warum.
• Veraltete Capability-Namen lösen Warnungen während bundle/validate aus und ein hartes Fail bei publish.
• Das gebündelte backend.js kann keine Node.js-Built-ins importieren (fs, path, child_process usw.) – Sandbox-Runtimes stellen sie nicht bereit.

Siehe Bundling und Publishing für die vollständige Liste der Prüfungen.