Périmètre sûr : ce guide vise vos propres applications, ou des systèmes pour lesquels vous avez une autorisation écrite. Ni automatisation de sites tiers, ni anti-détection.
Une clé API CaptchaAI laissée en clair dans un .env versionné est presque toujours le premier incident de sécurité d'un projet d'automatisation, bien avant le premier CAPTCHA raté. age y répond avec un binaire, une paire de clés et un fichier .age versionnable, déchiffré au démarrage du worker.
Pourquoi age plutôt qu'un coffre complet
Un coffre managé s'impose dès que plusieurs équipes partagent des dizaines de secrets. Pour trois personnes qui exploitent un pool de workers sur OVHcloud ou Scaleway, il ajoute surtout une dépendance réseau.
| Approche | Coût d'exploitation | Cas où elle convient |
|---|---|---|
| Coffre managé (Vault) | Serveur à administrer | Dizaines de secrets partagés |
| Variables protégées de CI | Nul | Un seul runner |
age |
Un binaire, une paire de clés | Secret versionné avec le code |
Le secret chiffré voyage avec le dépôt ; seule la clé privée est distribuée.
Étape 1 : générer la paire de clés
Sur un poste de confiance, age-keygen -o key.txt produit une clé privée (AGE-SECRET-KEY-1…) et affiche la publique. La publique va dans vos scripts de chiffrement ; la privée ne quitte le poste que pour être injectée en variable protégée de votre CI. Une clé publique ed25519 existante fait aussi office de destinataire.
Étape 2 : chiffrer la clé API CaptchaAI
Placez la clé dans un fichier d'environnement local, puis chiffrez-le : age -r age1… -o captchaai.env.age captchaai.env. Supprimez la version en clair. Le binaire obtenu est committable et copiable dans une image. Listez tous les destinataires légitimes : un fichier chiffré pour une seule personne finit par circuler autrement.
Étape 3 : déchiffrer au démarrage du worker
Le déchiffrement a lieu une fois, au lancement : age -d -i key.txt captchaai.env.age réinjecte les variables, et le code ne connaît plus que process.env.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;
}
Effet secondaire : le jour où vous quittez BASIC ($15/mois, 5 threads) pour une formule supérieure, vous remplacez le fichier .age et vous redémarrez.
Cloisonner les environnements
Utilisez une paire de clés et un fichier par environnement : captchaai.dev.env.age, captchaai.prod.env.age. Un runner de préproduction ne peut alors pas déchiffrer le secret de production, même si tout le dépôt fuite.
Observer sans journaliser le secret
Instrumentez les appels — durée d'obtention du token, code retour HTTP — mais filtrez la clé dans vos logs. Ne la passez jamais en argument de ligne de commande : elle apparaîtrait dans ps et dans l'historique du shell. Côté RGPD, ce réflexe rejoint la minimisation des données.
Rotation : le seul test qui compte vraiment
Planifiez un exercice trimestriel : nouvelle clé dans le tableau de bord, re-chiffrement, déploiement, vérification qu'un worker redémarré résout bien un défi CAPTCHA, révocation de l'ancienne.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
no identity matched any of the recipients |
Fichier chiffré pour une autre clé | Re-chiffrez avec -r répété |
ERROR_WRONG_USER_KEY au démarrage |
Saut de ligne capturé dans la valeur | Écrivez la variable sans retour à la ligne |
| Worker démarré sans la clé | Fichier de clé privée supprimé trop tôt | Déchiffrez avant l'export |
Liste de contrôle avant mise en production
- Aucune clé en clair dans le dépôt, l'historique Git ou une image.
- Une paire de clés
agepar environnement, privée en variable protégée. - Fichier
.agechiffré pour tous les destinataires légitimes. - Secret injecté par variable d'environnement, jamais en argument.
- Rotation testée de bout en bout, ancienne clé révoquée.
FAQ
age remplace-t-il GPG pour ce cas d'usage ?
Pour un secret d'application, oui : options réduites, aucun trousseau à gérer. GPG garde l'avantage s'il vous faut des signatures.
Où stocker la clé privée age dans une chaîne CI ?
Dans une variable protégée et masquée (GitLab CI, GitHub Actions, Jenkins), écrite dans un fichier temporaire puis supprimée en fin de job.
Puis-je publier un fichier .age dans un dépôt public ?
Techniquement oui. En pratique, réservez-le aux dépôts privés : un fichier publié expose sa taille, sa date et son nombre de destinataires, pour un bénéfice nul.
Que faire si la clé a déjà été poussée en clair ?
Considérez-la comme compromise. Générez-en une nouvelle dans le tableau de bord CaptchaAI, révoquez l'ancienne, puis nettoyez l'historique — dans cet ordre : les clones existants contiennent encore l'ancienne clé.
Guides connexes
- Le démarrage rapide CaptchaAI
- Résolution CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Résolution CAPTCHA en chaîne CI
- Résoudre reCAPTCHA v2 via l'API
Un secret bien chiffré coûte dix minutes ; un secret fuité coûte une rotation dans l'urgence. – Obtenez votre clé CaptchaAI.
