Permissions et sécurité
Un plugin est conçu pour être sûr par construction : il ne peut faire que ce qu’on lui a accordé, et chaque action reste traçable. Cette page décrit précisément les règles, pour écrire un plugin qui marche du premier coup et pour expliquer à un administrateur ce qu’il accepte.
Les droits d’un plugin
Section intitulée « Les droits d’un plugin »À l’installation, le super administrateur accepte la liste des permissions du manifeste et choisit les boutiques autorisées (certaines, ou Toutes les boutiques, y compris les futures). Ensuite :
| Qui appelle | Droits effectifs |
|---|---|
| Une page du plugin (SDK) | Les permissions de l’utilisateur connecté dans la boutique active, réduites à celles accordées au plugin. Jamais super administrateur. Rien dans une boutique non autorisée |
Le serveur du plugin (jeton plg_live_) |
Les permissions accordées au plugin, dans ses boutiques autorisées |
Un plugin désactivé perd tout aussitôt : ses emplacements disparaissent, son jeton est refusé et ses webhooks sont suspendus.
Un emplacement qui demande des permissions n’est montré qu’aux utilisateurs qui les détiennent.
kiwidesk.can() et context.permissions donnent, dans la page, l’intersection calculée.
Les routes ouvertes
Section intitulée « Les routes ouvertes »Un plugin n’atteint que son environnement (/api/plugin-runtime/... : réglages et stockage)
et les routes explicitement ouvertes aux plugins. Toute autre route répond :
{ "statusCode": 403, "code": "PLUGIN_SCOPE", "message": "Cette action n'est pas accessible aux plugins", "details": { "reason": "NOT_OPENED" }}Routes ouvertes dans cette version (sans le préfixe /api) :
| Permission | Routes |
|---|---|
core:customers:read |
GET /customers, GET /customers/:id |
core:customers:write |
POST /customers, PATCH /customers/:id |
core:devices:read |
GET /devices, GET /devices/lookup, GET /devices/:id |
core:devices:write |
POST /devices, PATCH /devices/:id |
core:catalog:read |
GET /catalog/categories, /catalog/brands, /catalog/models et leurs fiches /:id |
repair:tickets:read |
GET /repair/tickets, GET /repair/tickets/:id |
repair:tickets:status |
POST /repair/tickets/:id/status |
repair:tickets:write |
POST /repair/tickets/:id/notes |
billing:invoices:read ou billing:pos:use |
GET /billing/invoices, GET /billing/invoices/:id |
inventory:items:read |
GET /inventory/items, GET /inventory/items/:id |
refurbishing:units:read |
GET /refurbishing/units, GET /refurbishing/units/:id |
plugin:storage |
GET /plugin-runtime/storage, GET, PUT, DELETE /plugin-runtime/storage/item |
| (aucune) | GET /plugin-runtime/me |
La route garde sa propre permission : le plugin et l’utilisateur (pour une page) doivent
l’avoir. Une route ouverte en lecture ne répond qu’en GET. L’écran de revue de l’installation
affiche, pour chaque permission demandée, les routes qu’elle ouvre ; dans le document OpenAPI,
l’extension x-kiwidesk-plugin-access marque ces routes.
Une permission qui n’ouvre aucune route (par exemple repair:passcode:view) ne sert qu’à montrer
un emplacement ou à recevoir des événements.
Ce qui est toujours refusé
Section intitulée « Ce qui est toujours refusé »- Permissions jamais accordées : clés API (
core:api_keys:manage,core:api_keys:personal), webhooks (core:webhooks:manage), rôles (core:roles:manage), utilisateurs (core:users:manage), modification du profil (core:profile:edit_email,edit_name,edit_phone). Un manifeste qui les demande est refusé. - Zones interdites par le SDK avant même l’API (
HostError NOT_ALLOWED) :/auth,/account,/api-keys,/webhooks,/plugins,/plugin-ui,/users/me,/hardware-bridge,/public. - Routes publiques (suivi client, signature, discussion) :
403 PLUGIN_SCOPEavecreason: "PUBLIC_ROUTE". Un plugin ne peut jamais agir « comme le client ». - Identifiants durables : un plugin ne peut créer ni appairage, ni jeton d’écran, ni code de déverrouillage, ni clé. Son jeton et son webhook lui appartiennent et sont révoqués à la désinstallation.
- En-tête plugin avec une clé API : une page de plugin passe toujours par la session de
l’utilisateur ; l’en-tête
X-KiwiDesk-Pluginenvoyé avec une clé est refusé.
Données retirées des réponses
Section intitulée « Données retirées des réponses »Sur les routes ouvertes, KiwiDesk retire des réponses les champs sensibles avant de les donner à un plugin : liens et codes de suivi client, liens de signature, d’approbation de devis et de partage, codes d’appairage, jetons, secrets, codes PIN et de déverrouillage. Ne comptez pas sur eux dans un plugin.
Isolement des pages
Section intitulée « Isolement des pages »Les fichiers du plugin sont servis par KiwiDesk sous /api/plugin-ui/<id>/<version>/... avec une
politique de sécurité (CSP) propre :
| Règle | Effet |
|---|---|
sandbox allow-scripts allow-forms |
Origine opaque : aucun accès aux cookies, au stockage ni à la page de KiwiDesk, même si la page est ouverte directement. Pas de fenêtres modales ni de pop-up |
script-src 'self' |
Scripts du paquet seulement : aucun script en ligne, aucun CDN |
style-src 'self' 'unsafe-inline' |
Feuilles du paquet et styles en ligne |
img-src, font-src, media-src 'self' data: blob: |
Images, polices et médias du paquet, ou générés |
connect-src = origine du serveur |
fetch vers le serveur du plugin seulement ('none' sans serveur) |
frame-src, worker-src, object-src 'none' |
Pas de cadre imbriqué, de worker ni d’objet |
form-action 'none', base-uri 'none' |
Un formulaire ne peut pas être envoyé ailleurs |
frame-ancestors 'self' |
Affichable seulement dans KiwiDesk |
Conséquences pratiques :
- mettez le code dans des fichiers
.jschargés en module, jamais dans<script>ouonclick=; - embarquez vos polices et images dans le paquet (pas de Google Fonts ni de CDN) ;
- un lien
<a href>oulocation.hrefqui charge un autre document ferme le cadre : Plugin arrêté, et la tentative est inscrite au journal d’audit (core.plugin.frame_navigated). Changez d’écran avec une ancre#oukiwidesk.navigate(); - la page de votre serveur appelée par
fetchreçoit l’originenull: répondez-lui avecAccess-Control-Allow-Origin: *et authentifiez autrement qu’avec des cookies.
Traçabilité
Section intitulée « Traçabilité »Le journal d’audit (préréglage Sécurité) garde l’installation, la mise à jour, les droits
accordés, l’activation, la désactivation, la désinstallation et la régénération des identifiants
(core.plugin.*). Chaque écriture faite par une page de plugin est tracée
(core.plugin.api_call, une ligne par minute pour les écritures dans le stockage) avec
l’utilisateur pour qui elle agissait ; toute entrée du journal écrite pendant un appel de plugin
porte le nom du plugin (metadata.plugin).