Utiliser le solveur CAPTCHA dans Express

Utilisez Node.js 22 ou une version ultérieure et Express 5. Installez le SDK JavaScript officiel à partir de l’archive tarball indiquée dans la documentation, plutôt que de supposer qu’il est publié dans le registre npm. L’exemple crée un seul client Solvethree en dehors des gestionnaires.

• SOLVETHREE_API_KEY : la clé API de votre espace de travail. Conservez-la sur le serveur.
• INTEGRATION_KEY : un secret distinct pour les appelants internes de confiance. L’exemple l’exige dans l’en-tête x-integration-key ; ne le distribuez pas aux clients navigateur. Si vous disposez déjà d’un middleware d’authentification, utilisez-le à la place du contrôle par clé partagée de l’exemple.
• CAPTCHA_SITE : le nom d’hôte cible, et non une URL complète. Configurez un profil de site actif pour votre espace de travail avant de créer des tâches ; l’envoi d’un nom d’hôte n’en crée pas.
• SOLVETHREE_PROXY : le proxy pour cette cible. L’exemple fournit un seul proxy et fixe l’action à login. Modifiez cette action côté serveur si votre cible en utilise une autre.

Cette requête utilise la configuration reCAPTCHA Enterprise par défaut. Elle nécessite site, action et un proxy, et non type ou url. Consultez la configuration du profil de site si la cible n’est pas encore configurée.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

Les deux routes sont protégées par le contrôle d’authentification. Le gestionnaire POST prend le nom d’hôte, l’action et le proxy dans la configuration du serveur, et non dans le corps de la requête. Seul l’identifiant de création facultatif provient de l’appelant.

1. 1.

   Attribuez un identifiant de requête avant la création

   Envoyez x-request-id avec 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union. Conservez-le avec la requête logique afin de pouvoir récupérer la création si la connexion expire.

2. 2.

   Envoyez un seul POST à /captcha/tasks

   Le gestionnaire appelle createTask avec waitMs: 0 et renvoie la tâche. Conservez son identifiant. Une réponse réussie signifie que vous avez une tâche, pas nécessairement une solution.

3. 3.

   Récupérez le statut avec GET

   Appelez /captcha/tasks/:id. Continuez les récupérations tant que le statut est pending ou solving ; ne répétez pas le POST pour vérifier la progression. Arrêtez-vous sur ready ou failed.

4. 4.

   Utilisez uniquement une solution prête

   Envoyez le jeton avec les champs userAgent et secChUa renvoyés, en utilisant le même proxy configuré et la cible prévue. Le SDK ne l’envoie pas à votre place. Une tâche prête signifie qu’une solution a été générée, pas que la cible a accepté votre requête applicative.

L’appel POST au SDK a une limite de 20 secondes imposée par AbortSignal. GET autorise une attente de tâche de 15 secondes dans un délai limite d’appel au SDK de 25 secondes. Une réponse GET peut toujours être non terminale ; examinez son statut plutôt que de considérer la fin de l’attente comme un échec de résolution.

L’expiration d’une création ne prouve pas que solvethree a rejeté la requête. Si vous avez reçu un identifiant de tâche, récupérez-la. Sinon, répétez la création avec le même identifiant de requête et les mêmes paramètres de tâche pour récupérer la tâche existante. Réutiliser cet identifiant avec des paramètres différents provoque un conflit. Sans identifiant de requête conservé, un nouveau POST risque de créer un travail distinct.

Express 5 transmet les rejets des gestionnaires asynchrones au middleware d’erreur. L’exemple renvoie HTTP 502 pour SolvethreeError, en exposant uniquement ses identifiants de requête et de tâche, et non l’erreur brute, les identifiants d’accès ou la solution. Sa réponse de repli HTTP 400 est générique ; elle ne classe pas précisément toutes les erreurs hors SDK, y compris les erreurs de dépassement de délai.

Traitez les erreurs HTTP avant de lire les données d’une réponse réussie. Indépendamment de cela, une tâche récupérée peut avoir le statut failed : examinez ses champs errorCode et error, puis arrêtez les interrogations. Les résolutions échouées sont remboursées, mais réessayer des entrées invalides sans les modifier ne les corrigera pas. Utilisez la référence des erreurs de l’API pour diagnostiquer l’échec signalé.