Aller au contenu

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.

À 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.

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.

  • 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_SCOPE avec reason: "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-Plugin envoyé avec une clé est refusé.

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.

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 .js chargés en module, jamais dans <script> ou onclick= ;
  • embarquez vos polices et images dans le paquet (pas de Google Fonts ni de CDN) ;
  • un lien <a href> ou location.href qui 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 # ou kiwidesk.navigate() ;
  • la page de votre serveur appelée par fetch reçoit l’origine null : répondez-lui avec Access-Control-Allow-Origin: * et authentifiez autrement qu’avec des cookies.

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).