#Connexion

Le CLI ne connaît pas les cookies de ton navigateur. Il s’authentifie avec une clé d’API : une chaîne qui commence par wc_, qui se crée dans le CMS, et qui s’enregistre une fois par machine. Cette page décrit le parcours complet — créer, enregistrer, vérifier, révoquer — et où la clé vit ensuite.

#Créer une clé

Ouvrir Réglages → Clés d’API
Dans le CMS, sur cms.webcosa.com. Une clé appartient à ton compte, pas à un site : elle atteint tous les sites auxquels tu as accès, et un seul écran les liste toutes.
Lui donner un nom qui dit où elle vit
« portable de Marc », « serveur de déploiement ». Le jour où quelque chose cloche, c’est ce nom qui te dira où aller débrancher. « clé-2 » ne te dira rien dans six mois, et une clé qu’on n’ose plus révoquer est une clé qui ne sert plus qu’à l’attaquant.
Choisir la portée
Deux valeurs, décrites plus bas. En cas de doute, lecture : une clé qui ne peut rien casser ne casse rien.
Fixer une expiration, ou pas
Un nombre de jours, de 1 à 365. Vide = la clé ne périme pas, ce qui est le bon défaut pour un poste de travail — une expiration surprise au milieu d’un déploiement rend le produit incompréhensible. Pour une clé d’intégration continue, en revanche, mets-en une : c’est celle qui traîne le plus longtemps dans le plus d’endroits.
Copier le secret
Il s’affiche dans un encadré ambre, en tête de l’écran, et ne se ferme que par un clic explicite.

Attention

Le secret ne s’affiche qu’une fois. La base n’en garde que le SHA-256 : personne, pas même nous, ne peut te le rendre. Ce n’est pas une précaution décorative — c’est le seul comportement honnête, puisque prétendre pouvoir le réafficher voudrait dire qu’on l’a gardé quelque part.

Si tu quittes l’écran sans avoir copié, il n’y a rien à récupérer : révoque la clé et crée-en une autre. C’est la bonne issue, la seule qui ne suppose pas qu’une copie du secret existe ailleurs.

#Les deux portées

Portée	Libellé dans le CMS	Ce qu’elle permet
`lecture`	Lecture seule	`lister`, `recuperer`
`themes`	Lecture et modification	tout, y compris `pousser`, `suivre` et `publier`

themes couvre lecture ; l’inverse est faux. Une clé lecture sur une écriture reçoit un 403 :

Sortie du CLIbash

✗ Cette clé n'a pas la portée nécessaire pour écrire (403).
  Une clé de portée « lecture » ne peut que lister et récupérer. Crée-en une de portée « themes ».

Note

La granularité est volontairement grossière. Une matrice de permissions fine que personne ne comprend produit des clés « tout cocher » — donc moins de sécurité réelle qu’un choix binaire que l’on fait correctement.

Le défaut du formulaire, côté API, est themes, parce que l’usage écrasant est le CLI de thèmes : une clé en lecture seule qui refuse un pousser produit un message d’erreur que personne ne relie à une portée choisie trois semaines plus tôt.

#Enregistrer la clé sur ta machine

$node scripts/theme.mjs connexion

La commande demande l’adresse du CMS, puis la clé — sans l’afficher. Le terminal passe en mode brut et lit les touches une à une : c’est la seule façon d’avoir un écho vraiment absent. Sans cela, la clé resterait en clair dans le défilement du terminal, puis dans les journaux de la session.

$node scripts/theme.mjs connexion

Connexion à Webcosa

Une clé d'API se crée dans le CMS : Réglages → Clés d'API
Choisis la portée « themes » pour pouvoir pousser, « lecture » pour
seulement lister et récupérer. Le secret ne s'affiche qu'une fois.

Adresse du CMS [http://localhost:3000] https://cms.webcosa.com
Clé d'API (elle ne s'affichera pas) :
Vérification…

✓ Clé enregistrée dans /Users/marc/.webcosa/config.json (0600)
https://cms.webcosa.com — site Menuiserie Dubois (dubois), 2 thèmes visibles.
Aucun site n'a été précisé : c'est celui-ci qui sera visé.
Fige-le avec --site=dubois si ton compte en a plusieurs.
Thème publié : Origo

connexion est la seule commande qui n’exige pas de clé pour démarrer : c’est elle qui en pose une. Toutes les autres refusent d’aller plus loin sans.

#La clé est vérifiée avant d’être écrite

La commande appelle GET /api/themes avec le secret saisi, et n’écrit rien si l’appel échoue. Enregistrer une clé qui ne marche pas, c’est reporter la découverte du problème à la troisième commande, quand plus personne ne fait le lien avec connexion.

C’est aussi le seul moment où l’on peut constater que la clé ouvre un autre site que celui qu’on avait en tête — d’où le nom du site atteint dans la sortie, plutôt qu’un vague « site par défaut du compte ».

Astuce

Si ton compte a plusieurs sites, fige-en un dès la connexion :

bash

node scripts/theme.mjs connexion --site=dubois

Sans désignation, c’est le premier site accessible qui est visé — et cet ordre change dès qu’un site s’ajoute au compte.

#Sans terminal

connexion a besoin d’un terminal pour poser ses questions. En intégration continue, il n’y en a pas. Deux voies :

bash

echo "$CLE" | node scripts/theme.mjs connexion --depuis-stdin --url=https://cms.webcosa.com

--depuis-stdin supprime les deux questions : l’adresse vient de --url (ou de WEBCOSA_URL), la clé de l’entrée standard. Le fichier de configuration est écrit normalement.

bash

WEBCOSA_CLE=wc_… node scripts/theme.mjs pousser

La voie recommandée en CI : aucun fichier n’est écrit, la clé ne survit pas au processus. Voir Configuration.

#Où la clé est stockée

~/.webcosa/config.jsonjson

{
  "url": "https://cms.webcosa.com",
  "cle": "wc_A5nR2xK..."
}

~/.webcosa/dossierdéfaut : 0700

Créé par connexion s’il n’existe pas, et remis en 0700 à chaque écriture.

~/.webcosa/config.jsonfichierdéfaut : 0600

Lisible et modifiable par toi seul. Le mode est réappliqué par un chmod explicite après l’écriture : le mode: passé à writeFile ne vaut que pour une création, et un fichier déjà présent en 0644 le serait resté, avec la nouvelle clé dedans.

Si le fichier devient lisible par d’autres comptes de la machine, le CLI le dit à chaque commande, sans y toucher :

Sortie du CLIbash

! /Users/marc/.webcosa/config.json est lisible par d'autres comptes de cette
  machine (mode 644). Il contient ta clé : `chmod 600 /Users/marc/.webcosa/config.json`.

Il avertit plutôt que de corriger : changer les permissions d’un fichier sous le dos de son propriétaire est le genre de service qu’on ne rend pas. Une nouvelle connexion, elle, réécrit correctement.

Danger

La clé ne va jamais dans un fichier versionné. .webcosa.json, posé dans le dossier du thème, dit quel site et quel thème — jamais la clé, et le CLI ne l’y lit même pas. Un fichier de projet qui contiendrait le secret finirait poussé sur GitHub le jour même.

Il n’existe pas non plus d’option --cle= : une clé passée sur la ligne de commande entre dans l’historique du shell et dans la liste des processus, où n’importe quel autre compte de la machine peut la lire.

#Vérifier, changer, révoquer

Vérifier qu’une clé répond
$node scripts/theme.mjs lister
C’est le test le plus court : la commande n’écrit rien, et elle échoue tout de suite si la clé est refusée.
Changer de clé, ou de CMS
Relance connexion. Le fichier est réécrit entièrement, pas fusionné.
Le CLI signale d’ailleurs le désaccord le plus fréquent — une clé enregistrée pour une adresse, une commande lancée sur une autre — mais seulement en --verbeux :
bash
```
· la clé enregistrée l'a été pour https://cms.webcosa.com, et on appelle
  http://localhost:3000 — elle sera probablement refusée.
```
Révoquer
Dans le CMS, Réglages → Clés d’API, la corbeille en bout de ligne. L’effet est immédiat : l’outil qui s’en sert cesse de fonctionner à l’appel suivant, avec un 401.
Une clé révoquée reste affichée, grisée et datée. La question qu’on se pose après une fuite n’est pas « quelles clés me restent » mais « est-ce que celle-là est bien morte » — et une ligne qui disparaît ne répond pas à cette question.

Note

Deux choses que la liste des clés te dit et qu’on ne trouve nulle part ailleurs : la dernière utilisation de chaque clé, qui dit si une clé compromise a servi après la fuite, et son préfixe visible (wc_A5nR2xK…), qui permet de reconnaître laquelle traîne dans quel fichier sans avoir à comparer des secrets.

#Ce qu’une clé ne peut pas faire

Elle ne peut pas en fabriquer d’autres. Les routes /api/cles refusent l’authentification par clé, et le font avant même de regarder les cookies. Si une clé pouvait appeler POST /api/cles, son porteur s’en fabriquerait dix autres en une seconde, chacune avec sa propre empreinte : le jour où l’on repère la fuite et où l’on révoque la clé compromise, les dix autres continueraient de fonctionner. Le vol deviendrait permanent.

Elle n’ouvre pas plus de sites que son porteur. Une clé hérite des droits du compte au moment de l’appel, pas au moment de sa création : retirer un site à une agence retire du même coup l’accès de toutes ses clés. L’en-tête qui désigne le site est revalidé à chaque requête — il désigne, il n’autorise pas. Voir Authentification.

Elle ne survit pas à son expiration. Une clé périmée est refusée exactement comme une clé révoquée, et le serveur ne dit pas laquelle des deux : lui dire renseignerait quelqu’un qui teste des clés volées.

#Connexion

#Créer une clé

Ouvrir Réglages → Clés d’API

Lui donner un nom qui dit où elle vit

Choisir la portée

Fixer une expiration, ou pas

Copier le secret

#Les deux portées

#Enregistrer la clé sur ta machine

#La clé est vérifiée avant d’être écrite

#Sans terminal

#Où la clé est stockée

#Vérifier, changer, révoquer

Vérifier qu’une clé répond

Changer de clé, ou de CMS

Révoquer

#Ce qu’une clé ne peut pas faire