Chiffrer vos secrets CaptchaAI dans un YAML avec SOPS

Périmètre sûr : ce guide couvre vos propres applications et les environnements pour lesquels vous détenez une autorisation écrite. Il ne traite pas de l'automatisation de sites tiers.

Une clé API CaptchaAI laissée en clair dans un dépôt Git survit aux forks, aux miroirs et aux sauvegardes longtemps après sa rotation. SOPS supprime ce risque : le YAML reste versionné et lisible en diff, mais la valeur du secret est chiffrée avec une clé age (ou un KMS) que seuls vos workers et votre CI peuvent ouvrir.

Pourquoi chiffrer les secrets CaptchaAI plutôt que les exporter à la main

Les variables d'environnement posées à la main tiennent tant qu'une seule personne déploie. Dès que trois développeurs, un runner CI et un cron partagent la clé, personne ne sait plus quelle valeur est active. Un YAML chiffré redonne un point de vérité unique : la rotation devient un commit daté.

Étape 1 : préparez la clé age et le fichier .sops.yaml

Tout commence par une paire de clés age par environnement — jamais une clé unique pour la QA et la production.

1. Générez une paire age par environnement ; la privée de production ne quitte jamais le coffre.
2. Déclarez dans .sops.yaml la règle qui associe secrets/*.yaml aux destinataires autorisés.
3. Ajoutez tout de suite le destinataire du runner CI : c'est l'oubli classique qui bloque une mise en production.

Étape 2 : chiffrez la clé API dans le YAML

Placez la clé dans un fichier dédié, avec une seule entrée captchaai_api_key, puis chiffrez-le.

• Les valeurs sont chiffrées ; les noms de champs restent lisibles.
• Une revue de code voit donc qu'un secret a changé, sans voir lequel.

Étape 3 : déchiffrez à l'exécution, jamais sur disque

Au démarrage du worker, laissez SOPS injecter le secret dans l'environnement du processus plutôt que d'écrire un fichier. Votre code ne connaît qu'une variable, CAPTCHAAI_KEY :

import fetch from 'node-fetch';

const API_KEY = process.env.CAPTCHAAI_KEY;

export async function createTurnstileTask(siteKey, pageUrl) {
  const res = await fetch('https://api.captchaai.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientKey: API_KEY,
      task: {
        type: 'TurnstileTaskProxyless',
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const data = await res.json();
  return data.taskId;
}

Le token renvoyé pour ce défi Cloudflare Turnstile est ensuite vérifié par votre backend, dans la session qui l'a déclenché.

Un cas concret : une équipe QA entre Lyon et Casablanca

Cinq personnes lancent leurs tests de bout en bout sur des runners OVHcloud, avec une préproduction sur AWS eu-west-3 (Paris). L'équipe partage un plan BASIC ($15/mois, 5 threads), facturé au thread simultané en dollars US : la clé commune est aussi un budget commun. La clé age de production reste dans le coffre du runner, les développeurs n'ouvrent que le secret de QA, et les jeux de test n'embarquent aucune donnée personnelle réelle : c'est le réflexe RGPD de base.

Observabilité : tracer l'intégration sans tracer le secret

• Durée d'obtention du token, code retour HTTP et identifiant de tâche.
• L'empreinte courte du secret déchiffré : les huit premiers caractères d'un hachage, jamais la clé.
• L'environnement d'exécution, pour repérer un runner resté sur l'ancienne clé.

Liste de contrôle : vos secrets avant la fusion

1. Aucune clé API en clair dans le dépôt, l'historique ou les exemples.
2. Une paire de clés age par environnement, la privée hors des postes.
3. La règle .sops.yaml inclut le destinataire du runner CI.
4. Le déchiffrement reste en mémoire, sans fichier temporaire persistant.
5. La rotation est un commit daté, suivi d'un redéploiement.

Dépannage

FAQ

SOPS chiffre-t-il l'intégralité du fichier YAML ?

Non. SOPS chiffre les valeurs et laisse la structure lisible : vos diffs montrent quel champ a changé sans exposer son contenu.

Faut-il préférer SOPS aux secrets natifs de la CI ?

Les deux se complètent : le secret CI stocke la clé de déchiffrement age, SOPS gère le reste avec un historique versionné.

Comment faire la rotation de la clé CaptchaAI sans casser la production ?

Générez la nouvelle clé depuis le tableau de bord, rechiffrez le YAML, déployez, puis désactivez l'ancienne une fois les workers redémarrés. Garder les deux clés actives pendant la bascule évite les erreurs sur les tâches en vol.

Ce dispositif suffit-il à mes obligations RGPD ?

Non : chiffrer un secret est une mesure technique utile, pas une conformité. Documentez qui accède aux clés et limitez les données personnelles de vos journaux.

Guides connexes

• Le démarrage rapide CaptchaAI
• Tester en environnement autorisé
• Valider l'endpoint sur vos formulaires
• La résolution CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Un secret chiffré vaut mieux qu'un secret caché. – Obtenez votre clé CaptchaAI.