Capacités et sécurité

Les plugins sandboxés sont isolés par défaut. Pour faire quoi que ce soit au-delà de la lecture et l’écriture de son propre KV et stockage, un plugin doit déclarer une capacité dans son manifeste. Le pont de la sandbox contrôle chaque API fournie par l’hôte en fonction de ces déclarations — un plugin qui n’a pas déclaré content:read n’obtient pas ctx.content, et un qui n’a pas déclaré network:request n’obtient pas ctx.http.

Cette page couvre ce que chaque capacité accorde, comment la sandbox les applique et ce qui n’est pas applicable.

Déclarer des capacités

Les capacités se trouvent dans emdash-plugin.jsonc, aux côtés de slug et du reste du contrat de confiance :

{
	"slug": "plugin-hello",
	// ...identité + profil...

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

Ne déclare que ce dont le plugin a réellement besoin. Les déclarations de capacités sont aussi ce que le Marketplace montre aux opérateurs dans le dialogue de consentement — des capacités supplémentaires sont de la friction à l’installation et un signal de sécurité lors des audits.

Référence des capacités

Quelques points à noter :

• Implications. content:write implique automatiquement content:read ; media:write implique media:read ; network:request:unrestricted implique network:request. Tu n’as pas besoin de lister les deux.
• Les taxonomies sont une surface séparée en lecture seule. taxonomies:read accorde l’accès aux définitions de taxonomies, leurs termes et les termes assignés à une entrée via ctx.taxonomies. C’est indépendant de content:read — déclare les deux si le plugin lit du contenu et sa classification. Il n’y a pas d’accès en écriture aux taxonomies depuis les plugins.
• network:request:unrestricted existe pour les URLs configurées par l’utilisateur. Un plugin webhook où l’opérateur saisit l’URL de destination doit atteindre des hôtes qui ne sont pas dans le manifeste. Les plugins qui appellent toujours des APIs connues devraient utiliser network:request + allowedHosts.
• email:send est contrôlé par la configuration, pas seulement par la capacité. Un plugin peut déclarer email:send, mais ctx.email n’est rempli que si un autre plugin a enregistré un transport email:deliver.

Listes d’hôtes autorisés pour le réseau

Les plugins avec network:request ne peuvent récupérer que les hôtes listés dans allowedHosts. Les caractères génériques sont pris en charge pour les sous-domaines :

"capabilities": ["network:request"],
"allowedHosts": [
	"api.example.com",     // hôte exact
	"*.cdn.example.com"    // tout sous-domaine de cdn.example.com
]

Le pont vérifie l’hôte de l’URL de la requête par rapport à la liste autorisée avant de transmettre la requête. Une requête vers un hôte non déclaré lance une exception à l’intérieur du plugin sans jamais quitter la sandbox.

network:request:unrestricted contourne entièrement la vérification de la liste autorisée. C’est destiné aux plugins où l’opérateur configure l’URL de destination au moment de l’exécution (émetteurs de webhook, redirecteurs HTTP génériques). Évite-le pour les plugins où la destination fait partie de la conception du plugin — déclare plutôt network:request avec des hôtes explicites pour que le dialogue de consentement indique aux opérateurs exactement où le plugin appellera.

Ce que la sandbox applique

Lorsqu’un runner de sandbox est actif, le runtime applique :

Ce que la sandbox n’applique pas

Certaines choses que le système de capacités ne couvre pas et ne peut pas couvrir :

• Comportement au sein d’une capacité accordée. Un plugin avec content:write peut modifier n’importe quel contenu, pas seulement le sien. Les capacités sont à gros grain — elles disent « ce plugin peut écrire du contenu », pas « ce plugin ne peut écrire que le contenu qu’il a créé ». La revue au moment de l’audit est la seule vérification de ce qu’un plugin fait réellement au sein de sa concession.
• Confiance de l’opérateur sur Node.js. Si le runner de sandbox configuré signale qu’il n’est pas disponible (pas de Cloudflare Worker Loader, pas de runner côté Node installé, etc.), les plugins sandboxed: [] sont ignorés au démarrage. Tu peux les déplacer vers plugins: [] pour les exécuter en processus — mais alors il n’y a pas d’isolat V8, pas de limites de ressources, et le plugin peut appeler fetch() directement ou lire les variables d’environnement. Considère cela comme une confiance au niveau natif.
• Canaux auxiliaires. La temporisation, la sortie des logs et les données stockées sont visibles pour quiconque a un accès raisonnable à l’environnement hôte. N’utilise pas la sandbox comme frontière de confidentialité contre l’opérateur qui l’exécute.

Consentement aux capacités

Lorsqu’un opérateur installe un plugin sandboxé depuis le Marketplace, EmDash affiche un dialogue de consentement avec les capacités déclarées. Les mises à jour qui ajoutent des capacités — par exemple, un plugin qui ne faisait que lire du contenu et qui veut maintenant faire des requêtes réseau — sont affichées comme un diff de capacités et nécessitent une nouvelle approbation avant que la nouvelle version ne prenne effet.

C’est pourquoi il est important de déclarer des capacités supplémentaires même si tu « pourrais en avoir besoin plus tard ». Elles apparaissent comme de la friction à chaque installation et mise à jour, et les audits de sécurité signalent les plugins qui demandent plus que ce dont ils ont manifestement besoin. Liste exactement ce que le plugin utilise et ajoute de nouvelles capacités dans une vraie version quand le plugin commence réellement à les utiliser.

Validation au moment du build

emdash-plugin bundle et emdash-plugin publish exécutent des vérifications supplémentaires :

• Chaque capacité déclarée doit être dans l’ensemble reconnu (les fautes de frappe font échouer le build).
• network:request nécessite un allowedHosts non vide ; network:request:unrestricted nécessite qu’il soit vide. Voir la référence du manifeste.
• Le backend.js empaquetée ne peut pas importer les built-ins Node.js (fs, path, child_process, etc.) — les runtimes de sandbox ne les fournissent pas.

Voir Empaqueter et publier pour la liste complète des vérifications.