Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Développeurs

Fichiers /.well-known d'une application

Publier un fichier statique sous /.well-known/ depuis le dossier www/.well-known d'une application, par exemple un jeton de vérification de domaine.

Fichiers /.well-known d'une application

Une application installée peut publier des fichiers statiques sous l'adresse /.well-known/ du site. C'est utile pour une vérification de domaine : un service externe demande un fichier à une adresse fixe pour s'assurer que vous contrôlez le site.

Prérequis

  • Une application installée sur le site.
  • Un accès au code de l'application.

Publier un fichier

  1. Dans le dossier du module Python de l'application (celui qui contient hooks.py), créez le dossier www/.well-known/.
  2. Placez-y le fichier. Vous pouvez créer des sous-dossiers.
  3. Mettez à jour le code de l'application sur le serveur, puis demandez l'adresse /.well-known/<chemin du fichier> en GET.

Le fichier est lu sur le disque à chaque requête. Aucun cache ne le conserve. Une mise à jour du code suffit : un redémarrage, une migration ou un vidage du cache ne sont pas nécessaires. De même, un fichier modifié ou supprimé est pris en compte dès la requête suivante.

L'application doit être installée sur le site (bench --site <site> install-app <app>). Le fichier d'une application présente sur le serveur mais pas installée sur le site n'est pas servi.

Le chemin demandé après /.well-known/ est cherché dans le dossier www/.well-known/ de chaque application installée. Dodock sert le premier fichier trouvé, puis s'arrête. Si deux applications publient le même chemin, seul le fichier de la première application qui le contient est servi.

Réponse du serveur

SituationRéponse
Le fichier existeSon contenu, avec le type de contenu déduit de l'extension (.json donne application/json)
Le fichier n'a pas d'extension reconnueSon contenu, avec le type text/plain
Le chemin n'existe dans aucune application, ou désigne un dossierErreur 404
Le chemin sort du dossier www/.well-known/ (par exemple /.well-known/../hooks.py)Erreur 404

Adresses déjà prises en charge par Dodock

Ces adresses sont traitées avant la recherche d'un fichier d'application :

  • /.well-known/security.txt : contenu du document Paramètres de sécurité, servi uniquement en HTTPS.
  • /.well-known/openid-configuration : configuration OpenID du site (voir OAuth).
  • /.well-known/oauth-authorization-server et /.well-known/oauth-protected-resource : métadonnées OAuth, tant qu'elles sont activées sur le site.

Si les métadonnées OAuth ne sont pas activées, un fichier d'application peut occuper ces deux dernières adresses.

Exemple

Exemple fictif. Un service tiers demande un fichier de vérification de domaine nommé openai-apps-challenge. Votre application s'appelle mon_app.

  1. Créez le fichier mon_app/www/.well-known/openai-apps-challenge (dans le dossier du module mon_app) avec pour seul contenu jeton-exemple-123.
  2. Mettez à jour le code de l'application sur le serveur. Aucun redémarrage n'est nécessaire.
  3. Ouvrez https://votre-site.example.com/.well-known/openai-apps-challenge.

Le navigateur affiche jeton-exemple-123 avec le type text/plain. Un fichier mon_app/www/.well-known/mcp/server-card.json serait servi à l'adresse /.well-known/mcp/server-card.json avec le type application/json.

Limites

  • Seules les requêtes GET sont traitées.
  • Les fichiers sont publics : n'y placez aucun secret.
  • Avec la configuration nginx générée par bench, les adresses /.well-known/acme-challenge/ sont réservées aux certificats Let's Encrypt. Un fichier d'application placé à ce chemin n'est pas servi.