Clés et environnements de test

Ce qu’il y a à connaître

Clé de site

32 caractères alphanumériques. Publique : elle va dans l’attribut data-site de la balise. Le tableau de bord la montre sous le nom « Identifiant public du site ».

Secret de vérification

64 caractères alphanumériques. Il va dans le champ secret de /v1/siteverify, côté serveur uniquement. Dans le tableau de bord, c’est une clé d’usage « Vérification serveur ».

Le même secret sert, sans en-tête Authorization, à remonter l’issue réelle d’une tentative par /v1/feedback (voir la vérification). Un secret de test y reçoit la réponse d’un signalement pris, sans rien enregistrer.

Clé d’évaluation

64 caractères aussi, d’usage « Évaluation (kit signé) ». Elle sert au SDK Node, qui sera publié sur npm avec sa documentation ; il n’est pas encore publié. Elle n’est pas un secret de vérification : siteverify la refuse avec invalid-input-secret, comme /v1/feedback sans en-tête Authorization.

Créer, copier, révoquer

• Onglet Clés du site, « Créer une clé » : choisissez l’environnement (Production ou Test) et l’usage. La clé est montrée une seule fois, à sa création. Copiez-la alors dans votre gestionnaire de secrets ou vos variables d’environnement.
• La liste montre ensuite les quatre premiers caractères de chaque clé, sa date de création, son dernier usage et son état. Si vous perdez un secret, créez-en un autre.
• « Révoquer » demande une confirmation. Une clé révoquée est refusée dans les 10 secondes qui suivent (Antisy garde les clés valides en mémoire ce temps-là) : la vérification répond alors invalid-input-secret.
• Antisy ne journalise jamais un secret au-delà de ses quatre premiers caractères.

Changer un secret sans coupure

1. Créez un nouveau secret de vérification, sans révoquer l’ancien.
2. Déployez-le sur votre serveur.
3. Vérifiez qu’il fonctionne : « dernier usage » de la nouvelle clé se met à jour.
4. Révoquez l’ancien.

Si un secret a fuité, révoquez-le sans attendre : un secret révoqué ne sert plus à rien, et vous en créez un autre.

Clés de test

Pour une intégration continue ou un développement local, Antisy fournit des clés et des jetons factices.

Clés de site factices

Deux clés publiques fixes, de la forme d’une vraie clé de site. Chacune donne le verdict de son nom.

• allow : TestAllow00000000000000000000000
• deny : TestDeny000000000000000000000000

Secret de test

Une clé créée avec l’environnement « Test » et l’usage « Vérification serveur ». Un site en porte au plus 2 à la fois. Elle n’est pas comptée dans les statistiques. Les clés de test de toute l’organisation, tous sites confondus, partagent 1 000 appels par jour (jour UTC) et, à ce jour, 2 500 par mois (mois UTC). Au-delà de l’un ou de l’autre : 429, jusqu’au minuit UTC suivant ou jusqu’au premier du mois UTC suivant.

Dans une page de développement

Mettez une clé de site factice dans l’attribut data-site de la balise. Le script fait tout son parcours, comme avec une vraie clé, et le champ antisy-token comme antisy.token() reçoivent le jeton fixe de cette clé. Votre serveur le vérifie avec un secret de test et obtient le verdict de la clé factice.

• Aucun nom d’hôte à déclarer : une clé factice n’en a pas, et, à ce jour, Antisy ne contrôle pas l’origine de la page pour elle. localhost, 127.0.0.1 ou un serveur de préproduction en HTTPS reçoivent le même jeton. Votre site de production garde sa liste de noms, sans localhost.
• Le jeton est toujours le même, et public : il ne dit rien du visiteur. Ce que la page de développement montre, c’est que le script tourne : une politique CSP incomplète, par exemple, s’y voit avant la production.

Sans navigateur (intégration continue)

On obtient d’abord un jeton fixe en déposant sur une clé de site factice, puis on le vérifie avec un secret de test. Le dépôt n’attend ni jeton de tentative, ni mesure du navigateur : une enveloppe quelconque commençant par ae2. convient, et la réponse porte le jeton en clair.

# 1. Un jeton de test : la clé de site factice « allow », une enveloppe quelconque.
TOKEN=$(curl -sS https://api.antisy.com/v1/collect \
  -H 'content-type: application/json' \
  -d '{"site":"TestAllow00000000000000000000000","envelope":"ae2.test"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

# 2. Sa vérification, avec un secret de test (par l'entrée standard, pas en argument).
printf 'secret=%s' "$ANTISY_TEST_SECRET" | curl -sS https://api.antisy.com/v1/siteverify \
  -d @- \
  --data-urlencode response="$TOKEN"

La réponse porte le verdict de la clé factice, l’indicateur test_key, et rien dans challenge_ts, hostname et action, que le jeton fixe vienne de la CI ou d’une page : aucun jeton réel n’a été déposé.

{"success":true,"verdict":"allow","flags":["test_key"],"error-codes":[],"challenge_ts":null,"hostname":null,"action":null,"event_id":"evt_…"}

• Avec un secret de production, un jeton fixe n’est qu’un jeton inconnu : invalid-input-response. Aucun trafic réel ne peut donc passer par eux.

Ne mettez jamais une clé de test en production

Les jetons fixes sont publics. Avec un secret de test, n’importe qui peut envoyer le jeton « allow » et être accepté : un robot y passe. Une clé de test posée par erreur en production laisse donc passer les robots, sans rien casser en apparence.

• Le tableau de bord marque « Test » chaque clé de test, dans la liste comme à la création, avec cet avertissement.
• Quand une clé de test reçoit du trafic qui ressemble à du trafic réel, Antisy écrit à l’adresse des alertes du compte (réglage « Adresse des alertes »), au plus une fois par semaine. Sans adresse enregistrée, aucun message n’est envoyé.
• Puisqu’aucun préfixe ne les distingue, gardez vos secrets de test dans des variables d’environnement nommées comme tels, et séparées de celles de la production.
• Ne laissez pas de clé factice dans data-site en production : avec le secret de production de votre site, chaque jeton fixe rend invalid-input-response, donc chaque envoi est refusé.

Pour la suite, voir la vérification côté serveur.