NestJS Captcha-Service: Ein Modul, das Turnstile löst

Die meisten Suchen nach einem NestJS Captcha wollen eine Nest-Seite damit schützen. Diese Anleitung behandelt die andere Richtung: Ein Service von Ihnen muss ein Cloudflare Turnstile-Widget auf einer Seite passieren, die Sie automatisieren dürfen, und braucht dafür ein Token. Sie verpacken das Paket capskip in einem dynamic module, wandeln seine Fehler in HTTP-Status um und testen es mit Vitest und supertest. Das Lösen übernimmt der CapSkip Turnstile Solver auf einem Windows-PC, der Ihnen gehört, ohne Gebühr pro Lösung. Eine Warteschlange kommt nicht vor; Lösungen, die in eine gehören, behandelt der BullMQ-Worker-Leitfaden.
Was Sie brauchen
- CapSkip auf einem Ihrer Windows-PCs. Wo es lauscht, legen Sie im Abschnitt Verbindungseinstellungen der Einrichtungsanleitung: Local mode hält es auf 127.0.0.1, und Server mode öffnet es für Ihr Netzwerk.
- Node.js 24.15 oder neuer in der 24er-Reihe, oder 26. Der Scaffold-Generator verlangt 22.22.3, 24.15 oder 26, Vite 8 samt Bundler 20.19 oder 22.12, und Nest 12 selbst 20. Ich habe das Projekt, vom Scaffold bis zu den Tests, auf 24.22.0 und 25.2.1 laufen lassen, wo npm eine Engine-Warnung für @nestjs/schematics ausgab. Auf 20.11.1 schlagen der Scaffold-Befehl und Vitest fehl.
- Nest 12 (hier 12.4.2) mit @nestjs/config 12.1.1 und capskip 1.7.0. Der Scaffold ist nur ESM (Importpfade enden auf .js) und testet mit Vitest, daher sind Mocks vi.fn.
Jeder Lauf unten nutzte einen von mir geschriebenen Mock von in.php und res.php sowie das echte Paket capskip 1.7.0. Keine Aufgabe erreichte ein echtes CapSkip, daher nenne ich keine Lösungszeit, und jede Verzögerung und Antwort folgt einer Regel des Mocks.
Schritt 1: Das Projekt und die Einstellungen anlegen
Führen Sie das in PowerShell aus. Es erzeugt die App per Scaffold, installiert die beiden Pakete, löscht die vier Beispieldateien, die das neue Layout ersetzt, und legt den Ordner für das Modul an.
# Scaffold the app, then npm install capskip @nestjs/config npx @nestjs/cli new capskip-nest --package-manager npm --skip-git cd capskip-nest npm install capskip @nestjs/config Remove-Item src/app.controller.ts, src/app.controller.spec.ts, src/app.service.ts, test/app.e2e-spec.ts New-Item -ItemType Directory src/capskip | Out-Null
Führen Sie den nächsten Block im Projektordner aus. Er schreibt .env und .gitignore ohne Editor, sodass die Datei nicht als .env.txt endet. Ein Scaffold ohne git hat keine .gitignore, und .env enthält Ihren Key, tragen Sie sie also dort ein, bevor Sie git das erste Mal nutzen. Das SDK liest selbst keine Umgebungsvariablen, deshalb liest die Factory in Schritt 2 diese. CAPSKIP_API_KEY ist nur relevant, wenn API Key Validation in CapSkip eingeschaltet ist; fehlt er, sendet das SDK den Key capskip.
# Create .env and .gitignore without an editor @' CAPSKIP_HOST=127.0.0.1 CAPSKIP_PORT=8080 CAPSKIP_API_KEY=YOUR_API_KEY CAPSKIP_TIMEOUT=20 TARGET_HOSTS=example.com '@ | Set-Content -Path .env -Encoding ascii Set-Content -Path .gitignore -Value '.env', 'node_modules', 'dist' -Encoding ascii
Schritt 2: Das Modul bauen
Die Optionen, einmal beschrieben
Speichern Sie den nächsten Block als src/capskip/capskip.options.ts. Nest liefert einen ConfigurableModuleBuilder mit, der die statischen Methoden forRoot und forRootAsync sowie ein Injection-Token für die Optionen erzeugt. Das Argument extras fügt ein isGlobal-Flag hinzu, das am Modul bleibt und nicht in den Optionen steht. Mehr zum Builder steht im Nest-Kapitel zu Dynamic Modules.
// src/capskip/capskip.options.ts
import { ConfigurableModuleBuilder } from '@nestjs/common';
export interface CapSkipModuleOptions {
host?: string;
port?: number;
apiKey?: string;
/** Seconds the SDK may poll for one solve. */
timeoutSeconds?: number;
}
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
new ConfigurableModuleBuilder<CapSkipModuleOptions>()
.setClassMethodName('forRoot')
.setExtras({ isGlobal: false }, (definition, extras) => ({
...definition,
global: extras.isGlobal,
}))
.build();Der Service, mit dem Client hinter einem Token
Speichern Sie dies als src/capskip/capskip.service.ts. Der SDK-Client wird nicht im Service erzeugt. Er kommt über das Token CAPSKIP_CLIENT herein, typisiert als die eine SDK-Methode, die der Service nutzt, sodass ein Test eine einzelne Funktion übergeben kann und der Compiler ihre Signatur trotzdem prüft.
// src/capskip/capskip.service.ts
import { Inject, Injectable } from '@nestjs/common';
import { TimeoutException, type CapSkip } from 'capskip';
import { MODULE_OPTIONS_TOKEN, type CapSkipModuleOptions } from './capskip.options.js';
export const CAPSKIP_CLIENT = Symbol('CAPSKIP_CLIENT');
/** The one SDK method this service calls, so a test double stays small. */
export type TurnstileClient = Pick<CapSkip, 'turnstile'>;
export interface TurnstileToken {
token: string;
/** Submit the token with this User-Agent when CapSkip reports one. */
userAgent?: string;
}
@Injectable()
export class CapSkipService {
constructor(
@Inject(CAPSKIP_CLIENT) private readonly client: TurnstileClient,
@Inject(MODULE_OPTIONS_TOKEN) private readonly options: CapSkipModuleOptions,
) {}
async solveTurnstile(sitekey: string, url: string): Promise<TurnstileToken> {
const seconds = this.options.timeoutSeconds ?? 60;
// The SDK sets no timeout on its HTTP calls and checks its deadline only
// between polls, so a CapSkip that stops answering would hold this call
// forever. The race ends it 6 seconds after the SDK deadline at the latest.
let timer: NodeJS.Timeout | undefined;
const giveUp = new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new TimeoutException(`no answer from CapSkip within ${seconds + 6} s`)),
(seconds + 6) * 1000,
);
});
try {
const result = await Promise.race([
this.client.turnstile(sitekey, url, { timeout: seconds }),
giveUp,
]);
if (typeof result.code !== 'string') {
throw new Error('Unexpected CapSkip result for turnstile');
}
return { token: result.code, userAgent: result.userAgent };
} finally {
clearTimeout(timer);
}
}
}Turnstile ist das Beispiel, weil sein Ergebnis einen User-Agent trägt, den laut den SDK-Typen zu verwenden ist, wenn Sie das Token einreichen. Der Service gibt ihn mit dem Token als kleines Objekt zurück, nicht als rohes SDK-Ergebnis, dessen Feld code als String oder Objekt typisiert ist und hier abgelehnt wird, wenn es kein String ist. Andere Typen folgen derselben Form: Fügen Sie je eine Methode für recaptcha, hcaptcha oder mtcaptcha hinzu und übergeben Sie das Timeout, aus dem Grund in Schritt 3. Die Felder, die jeder Typ annimmt, stehen in der API-Dokumentation.
SDK-Fehler als HTTP-Status
Das SDK hat vier Exception-Klassen, die alle CapSkipError erweitern: ValidationException, NetworkException, ApiException und TimeoutException. Eine ApiException trägt als Nachricht nur den Antworttext von CapSkip, ohne code-Feld, deshalb liest die Zuordnung den ERROR_-Code aus der Nachricht. Speichern Sie dies als src/capskip/capskip.errors.ts.
// src/capskip/capskip.errors.ts
import { Catch, HttpException, HttpStatus, Logger, type ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';
import {
ApiException,
CapSkipError,
NetworkException,
TimeoutException,
ValidationException,
} from 'capskip';
const BAD_INPUT = /ERROR_(RECAPTCHA_INVALID_(SITEKEY|DOMAIN)|BAD_PARAMETERS|PAGEURL)/;
const BAD_CREDENTIALS = /ERROR_(KEY_DOES_NOT_EXIST|WRONG_USER_KEY|ZERO_BALANCE)/;
export function toHttpException(err: CapSkipError): HttpException {
const code = /ERROR_[A-Z_]+/.exec(err.message)?.[0];
const body = (status: HttpStatus, error: string) => ({
statusCode: status,
error,
code: code ?? err.name,
});
if (err instanceof TimeoutException) {
return new HttpException(body(HttpStatus.GATEWAY_TIMEOUT, 'Solver timeout'), 504);
}
if (err instanceof NetworkException) {
return new HttpException(body(HttpStatus.SERVICE_UNAVAILABLE, 'Solver unreachable'), 503);
}
if (err instanceof ApiException && BAD_INPUT.test(err.message)) {
return new HttpException(body(HttpStatus.BAD_REQUEST, 'Solver refused the task'), 400);
}
if (err instanceof ApiException && code === 'ERROR_CAPTCHA_UNSOLVABLE') {
return new HttpException(body(HttpStatus.UNPROCESSABLE_ENTITY, 'Not solved, retry'), 422);
}
if (err instanceof ValidationException) {
// The SDK refused a task this service built: a bug here, not the caller's.
return new HttpException(body(HttpStatus.INTERNAL_SERVER_ERROR, 'Task refused by the SDK'), 500);
}
// Wrong key, empty balance or anything else: our side of the link, not the caller's.
const error = err instanceof ApiException && BAD_CREDENTIALS.test(err.message)
? 'Solver credentials rejected'
: 'Solver error';
return new HttpException(body(HttpStatus.BAD_GATEWAY, error), 502);
}
@Catch(CapSkipError)
export class CapSkipExceptionFilter extends BaseExceptionFilter {
private readonly logger = new Logger(CapSkipExceptionFilter.name);
override catch(err: CapSkipError, host: ArgumentsHost) {
// The SDK message is the reply text of CapSkip and never holds the key.
this.logger.warn(`${err.name} ${err.message}`);
super.catch(toHttpException(err), host);
}
}Der Filter erweitert BaseExceptionFilter und delegiert, wie es das Nest-Kapitel zu Exception Filters zeigt, daher funktioniert er mit jedem HTTP-Adapter. Er fängt nur CapSkipError, protokolliert eine Warnung mit Fehlername und Nachricht (dem Antworttext von CapSkip, nie Ihr Key) und hält diese rohe Nachricht aus der Antwort heraus.
| Was das SDK ausgelöst hat | HTTP | Warum dieser Status |
|---|---|---|
| TimeoutException | 504 | Kein Token innerhalb des Timeouts. Auch ein CapSkip, das zwischen den Abfragen verstummt, endet hier |
| NetworkException | 503 | CapSkip war beim Senden der Aufgabe nicht erreichbar |
| ApiException mit ERROR_CAPTCHA_UNSOLVABLE | 422 | Nicht gelöst. Die API-Dokumentation von CapSkip empfiehlt, eine neue Aufgabe zu senden |
| ApiException mit ERROR_RECAPTCHA_INVALID_SITEKEY, ERROR_RECAPTCHA_INVALID_DOMAIN, ERROR_BAD_PARAMETERS oder ERROR_PAGEURL | 400 | Der Aufrufer hat einen sitekey oder eine Seitenadresse gesendet, die CapSkip ablehnt |
| ApiException mit ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_USER_KEY oder ERROR_ZERO_BALANCE | 502 | Das Problem ist der eigene Key Ihres Service, nicht die Eingabe des Aufrufers |
| ValidationException | 500 | Das SDK hat eine Aufgabe abgelehnt, die dieser Service selbst gebaut hat. Das ist hier ein Bug |
Jede andere ApiException wird zu einem 502. Das Modul registriert den Filter mit APP_FILTER, sodass jede App, die das Modul importiert, die Zuordnung erhält.
Das Modul, die App und ein Controller
Speichern Sie das Modul als src/capskip/capskip.module.ts. Es baut den Client aus den Optionen in einem Factory-Provider, fügt den Service hinzu und registriert den Filter.
// src/capskip/capskip.module.ts
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { CapSkip } from 'capskip';
import { CapSkipExceptionFilter } from './capskip.errors.js';
import {
ConfigurableModuleClass,
MODULE_OPTIONS_TOKEN,
type CapSkipModuleOptions,
} from './capskip.options.js';
import { CAPSKIP_CLIENT, CapSkipService } from './capskip.service.js';
@Module({
providers: [
{
provide: CAPSKIP_CLIENT,
inject: [MODULE_OPTIONS_TOKEN],
useFactory: ({ host, port, apiKey }: CapSkipModuleOptions) =>
new CapSkip({ host, port, apiKey }),
},
CapSkipService,
{ provide: APP_FILTER, useClass: CapSkipExceptionFilter },
],
exports: [CapSkipService],
})
export class CapSkipModule extends ConfigurableModuleClass {}Ersetzen Sie src/app.module.ts durch den nächsten Block. forRootAsync führt die Factory mit allem aus, was Sie in inject auflisten. ConfigModule ist hier global, daher findet CapSkipModule ConfigService, ohne ihn zu importieren.
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { CapSkipModule } from './capskip/capskip.module.js';
import { TurnstileController } from './turnstile.controller.js';
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
CapSkipModule.forRootAsync({
inject: [ConfigService],
useFactory: (config: ConfigService) => ({
host: config.get<string>('CAPSKIP_HOST', '127.0.0.1'),
port: Number(config.get('CAPSKIP_PORT', 8080)),
apiKey: config.get<string>('CAPSKIP_API_KEY'),
timeoutSeconds: Number(config.get('CAPSKIP_TIMEOUT', 60)),
}),
}),
],
controllers: [TurnstileController],
})
export class AppModule {}Speichern Sie zuletzt src/turnstile.controller.ts. Die url bestimmt, für welche Seite CapSkip löst, eine offene Route ließe also jeden Ihren Solver verbrauchen. Die Prüfung gegen TARGET_HOSTS ist das Minimum: Sie akzeptiert nur https-Adressen, trimmt die Liste und lehnt jede Anfrage ab, wenn die Liste leer oder nicht gesetzt ist. Setzen Sie Ihren eigenen Authentifizierungs-Guard davor.
// src/turnstile.controller.ts
import { BadRequestException, Body, Controller, Post } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { CapSkipService } from './capskip/capskip.service.js';
@Controller('captcha')
export class TurnstileController {
constructor(
private readonly capskip: CapSkipService,
private readonly config: ConfigService,
) {}
@Post('turnstile')
solve(@Body() body: { sitekey?: unknown; url?: unknown }) {
const hosts = this.config
.get<string>('TARGET_HOSTS', '')
.split(',')
.map((host) => host.trim())
.filter(Boolean);
const page =
typeof body.url === 'string' && URL.canParse(body.url) ? new URL(body.url) : null;
if (
typeof body.sitekey !== 'string' ||
!body.sitekey ||
!page ||
page.protocol !== 'https:' ||
!hosts.includes(page.host)
) {
throw new BadRequestException('sitekey or url missing, or host not allowed');
}
return this.capskip.solveTurnstile(body.sitekey, page.href);
}
}Schritt 3: Das Anfrage-Timeout und die SDK-Deadline
Ich habe in Nest kein Timeout gesetzt, und die Anfragen unten warteten ihre vollen 7,8 Sekunden, die SDK-Deadline ist hier also die einzige. Sie wird in Sekunden gezählt und verhält sich auf vier Arten, die für eine wartende Anfrage zählen.
Erstens wird die Deadline geprüft, wenn der nächste Poll fällig ist, nicht wenn sie abläuft. Das SDK fragt bei etwa 0, 0,25, 0,75, 1,75 und 3,75 Sekunden ab, dann bei 7,75 und danach alle 5 Sekunden, ein Timeout von 5 endet also bei etwa 7,8. Gemessen gegen einen Mock, der nie antwortet, auf Node.js 24.22.0 (20.11.1 stimmte bei allen vier Zeilen auf 0,1 Sekunden überein):
| Timeout-Option | TimeoutException nach |
|---|---|
| 5 Sekunden | 7,82 Sekunden |
| 10 Sekunden | 12,83 Sekunden |
| 20 Sekunden | 22,82 Sekunden |
| 30 Sekunden | 32,86 Sekunden |
Geben Sie daher jedem Aufrufer und jedem vorgeschalteten Proxy ein Timeout vom SDK-Wert plus mindestens 5 Sekunden. Über Nest antwortete CAPSKIP_TIMEOUT 5 nach 7,84 Sekunden mit 504.
Zweitens nutzt turnstile() das defaultTimeout des Clients, 120 Sekunden, nicht recaptchaTimeout, obwohl ein Kommentar in den SDK-Typdefinitionen Turnstile unter recaptchaTimeout aufführt. Mit defaultTimeout 3 und recaptchaTimeout 30 endete es nach 3,81 Sekunden; vertauscht, nach 32,87. Laut Quellcode liest recaptcha recaptchaTimeout und mtcaptcha defaultTimeout, deshalb übergibt der Service die Option timeout bei jedem Aufruf.
Drittens stoppt ein Aufrufer, der aufgibt, das Lösen nicht: Das SDK nimmt kein AbortSignal, und Nest bricht einen Handler beim Trennen nicht ab. Auf einen supertest-Client, der nach 3,0 Sekunden ging, folgte ein fünfter Poll bei 3,79 Sekunden. Ein kurzes Timeout ist die einzige Bremse, daher bleibt CAPSKIP_TIMEOUT klein.
Viertens, und am schlimmsten: Das SDK setzt kein Timeout auf seine HTTP-Anfragen und prüft die Deadline nur zwischen den Polls. Nimmt CapSkip einen Poll an und antwortet nie, weil der PC im Ruhezustand ist oder eine Firewall Pakete verwirft, wird die Deadline nie geprüft. Gegen einen Mock, der das tat, war das SDK mit Timeout 5 nach 30 Sekunden noch offen. Deshalb lässt der Service den SDK-Aufruf gegen einen eigenen Timer laufen, 6 Sekunden nach der SDK-Deadline: Mit CAPSKIP_TIMEOUT 5 wurde der hängende Poll nach 11,0 Sekunden zu einem 504. Der aufgegebene SDK-Aufruf bleibt offen, halten Sie also das Race und ein kurzes Timeout zusammen.
Schritt 4: Tests für den NestJS Captcha-Service
Ein Unit-Test mit gemocktem Client
Speichern Sie dies als src/capskip/capskip.service.spec.ts. Test.createTestingModule baut ein Modul aus dem echten Service und zwei einfachen Werten: einem Fake-Client und Fake-Optionen. Das Skript npm test des Scaffolds führt ihn aus. Er deckt auch ein Ergebnis ohne String und den hängenden CapSkip-Timer ab.
// src/capskip/capskip.service.spec.ts
import { HttpException } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { ApiException, NetworkException, TimeoutException, ValidationException } from 'capskip';
import { toHttpException } from './capskip.errors.js';
import { MODULE_OPTIONS_TOKEN } from './capskip.options.js';
import { CAPSKIP_CLIENT, CapSkipService } from './capskip.service.js';
describe('CapSkipService', () => {
const turnstile = vi.fn();
let service: CapSkipService;
beforeEach(async () => {
turnstile.mockReset();
const moduleRef = await Test.createTestingModule({
providers: [
CapSkipService,
{ provide: CAPSKIP_CLIENT, useValue: { turnstile } },
{ provide: MODULE_OPTIONS_TOKEN, useValue: { timeoutSeconds: 20 } },
],
}).compile();
service = moduleRef.get(CapSkipService);
});
it('passes the timeout and returns token and User-Agent', async () => {
turnstile.mockResolvedValue({ captchaId: '7', code: 'tok', userAgent: 'UA' });
await expect(service.solveTurnstile('0xKEY', 'https://example.com/')).resolves.toEqual({
token: 'tok',
userAgent: 'UA',
});
expect(turnstile).toHaveBeenCalledWith('0xKEY', 'https://example.com/', { timeout: 20 });
});
afterEach(() => vi.useRealTimers());
it('refuses a result whose code is not a string', async () => {
turnstile.mockResolvedValue({ captchaId: '7', code: { token: 'x' } });
await expect(service.solveTurnstile('0xKEY', 'https://example.com/')).rejects.toThrow(
'Unexpected CapSkip result',
);
});
it('gives up 6 seconds after the SDK deadline when CapSkip never answers', async () => {
vi.useFakeTimers();
turnstile.mockReturnValue(new Promise(() => {}));
const outcome = expect(service.solveTurnstile('0xKEY', 'https://example.com/')).rejects.toBeInstanceOf(
TimeoutException,
);
await vi.advanceTimersByTimeAsync(26_000);
await outcome;
});
it.each([
[new TimeoutException('timeout 20 exceeded'), 504],
[new NetworkException('connect ECONNREFUSED'), 503],
[new ApiException('ERROR_CAPTCHA_UNSOLVABLE'), 422],
[new ApiException('ERROR_RECAPTCHA_INVALID_SITEKEY'), 400],
[new ApiException('ERROR_WRONG_USER_KEY'), 502],
[new ValidationException('Unsupported parameters'), 500],
])('maps %s to HTTP %i', (err, status) => {
const mapped = toHttpException(err);
expect(mapped).toBeInstanceOf(HttpException);
expect(mapped.getStatus()).toBe(status);
});
});Der Controller bekommt einen eigenen Spec, src/turnstile.controller.spec.ts, weil der Fall der leeren Liste keine laufende App braucht.
// src/turnstile.controller.spec.ts
import { BadRequestException } from '@nestjs/common';
import { TurnstileController } from './turnstile.controller.js';
describe('TurnstileController', () => {
const solveTurnstile = vi.fn().mockResolvedValue({ token: 'tok' });
const controller = (hosts?: string) =>
new TurnstileController(
{ solveTurnstile } as never,
{ get: (_name: string, fallback: string) => hosts ?? fallback } as never,
);
const page = { sitekey: '0xKEY', url: 'https://example.com/login' };
beforeEach(() => solveTurnstile.mockClear());
it.each([undefined, '', ' , '])('refuses every request when TARGET_HOSTS is %j', (hosts) => {
expect(() => controller(hosts).solve(page)).toThrow(BadRequestException);
expect(solveTurnstile).not.toHaveBeenCalled();
});
it('accepts a listed host and passes the parsed address on', async () => {
await controller(' example.com , ').solve(page);
expect(solveTurnstile).toHaveBeenCalledWith('0xKEY', 'https://example.com/login');
});
});Ein E2E-Test gegen einen Mock von CapSkip
Ein NestJS Captcha-Service sollte ohne ein echtes CapSkip getestet werden, daher steht dieser Mock für in.php und res.php. Er lauscht auf Port 0, sodass das System einen freien Port wählt, und protokolliert, was er empfängt. Seine Antworten und Verzögerungen sind meine Regeln, nicht das Verhalten eines echten CapSkip. Speichern Sie ihn als test/mock-capskip.ts.
// test/mock-capskip.ts
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
// A stand-in for CapSkip's in.php and res.php. Not the real app: the
// delay and the replies below are this file's own rules.
export async function startMock(listenPort = 0) {
const mock = {
port: 0,
solveMs: 0, // how long a task stays "not ready"
submitReply: '', // set to ERROR_... to refuse every submit
pollReply: '', // set to ERROR_... to fail every poll
hangPolls: false, // accept a poll and never answer it
submits: [] as Record<string, string>[],
polls: [] as number[], // Date.now() of each res.php call
close: () => {
server.closeAllConnections();
return new Promise<void>((done) => server.close(() => done()));
},
};
let submittedAt = 0;
const server = createServer((req, res) => {
const url = new URL(req.url!, 'http://mock');
let raw = '';
req.on('data', (chunk) => (raw += chunk));
req.on('end', () => {
if (url.pathname === '/in.php') {
mock.submits.push(Object.fromEntries(new URLSearchParams(raw)));
submittedAt = Date.now();
res.end(mock.submitReply || 'OK|7');
} else if (url.pathname === '/res.php') {
mock.polls.push(Date.now());
if (mock.hangPolls) return;
const waiting = Date.now() - submittedAt < mock.solveMs;
if (mock.pollReply) res.end(JSON.stringify({ status: 0, request: mock.pollReply }));
else if (waiting) res.end(JSON.stringify({ status: 0, request: 'CAPCHA_NOT_READY' }));
else res.end(JSON.stringify({ status: 1, request: '0.mock-token', useragent: 'Mock UA' }));
} else {
res.statusCode = 404;
res.end();
}
});
});
await new Promise<void>((ready) => server.listen(listenPort, '127.0.0.1', ready));
mock.port = (server.address() as AddressInfo).port;
return mock;
}Der E2E-Spec startet das echte AppModule, richtet die Umgebungsvariablen auf den Mock und sendet Anfragen mit supertest. Speichern Sie ihn als test/turnstile.e2e-spec.ts und führen Sie npm run test:e2e aus. Variablen, die schon in der Umgebung stehen, haben Vorrang vor .env, daher kann der Spec sie überschreiben.
// test/turnstile.e2e-spec.ts
import { Logger, type INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { AppModule } from '../src/app.module.js';
import { startMock } from './mock-capskip.js';
describe('POST /captcha/turnstile', () => {
let app: INestApplication;
let mock: Awaited<ReturnType<typeof startMock>>;
const body = { sitekey: '0xKEY', url: 'https://example.com/login' };
beforeAll(async () => {
mock = await startMock();
process.env.CAPSKIP_HOST = '127.0.0.1';
process.env.CAPSKIP_PORT = String(mock.port);
process.env.CAPSKIP_TIMEOUT = '5';
process.env.TARGET_HOSTS = ' example.com, '; // spaces and a trailing comma are harmless
const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
app = moduleRef.createNestApplication();
await app.init();
});
afterAll(async () => {
await app.close();
await mock.close();
});
beforeEach(() => {
Object.assign(mock, { solveMs: 0, submitReply: '', pollReply: '', hangPolls: false, submits: [], polls: [] });
});
it('returns the token and sends a turnstile task', async () => {
const res = await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(201);
expect(res.body).toEqual({ token: '0.mock-token', userAgent: 'Mock UA' });
expect(mock.submits[0]).toMatchObject({ method: 'turnstile', sitekey: '0xKEY', pageurl: body.url });
});
it('refuses a host that is not on the list, before CapSkip is called', async () => {
await request(app.getHttpServer())
.post('/captcha/turnstile')
.send({ ...body, url: 'https://evil.test/' })
.expect(400);
expect(mock.submits).toHaveLength(0);
});
it.each([
{ sitekey: '0xKEY', url: 'http://example.com/login' },
{ sitekey: '0xKEY', url: 'file:///C:/Windows/win.ini' },
{ sitekey: '0xKEY', url: 'not a url' },
{ sitekey: { a: 1 }, url: 'https://example.com/login' },
{ url: 'https://example.com/login' },
])('refuses %j before CapSkip is called', async (bad) => {
await request(app.getHttpServer()).post('/captcha/turnstile').send(bad).expect(400);
expect(mock.submits).toHaveLength(0);
});
it('maps an unsolvable task to 422 and logs one warning', async () => {
const warn = vi.spyOn(Logger.prototype, 'warn');
mock.pollReply = 'ERROR_CAPTCHA_UNSOLVABLE';
const res = await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(422);
expect(res.body).toMatchObject({ code: 'ERROR_CAPTCHA_UNSOLVABLE' });
expect(warn).toHaveBeenCalledWith(expect.stringContaining('ERROR_CAPTCHA_UNSOLVABLE'));
warn.mockRestore();
});
it('maps a refused key to 502', async () => {
mock.submitReply = 'ERROR_WRONG_USER_KEY';
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(502);
});
it('answers 504 after the timeout of 5 seconds, not before it', async () => {
mock.solveMs = 60_000;
const started = Date.now();
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(504);
const seconds = (Date.now() - started) / 1000;
expect(seconds).toBeGreaterThan(5);
expect(seconds).toBeLessThan(9);
}, 15_000);
it('answers 504 when CapSkip accepts a poll and never replies', async () => {
mock.hangPolls = true;
const started = Date.now();
await request(app.getHttpServer()).post('/captcha/turnstile').send(body).expect(504);
const seconds = (Date.now() - started) / 1000;
expect(seconds).toBeGreaterThan(10.5);
expect(seconds).toBeLessThan(13);
}, 20_000);
});Das sind die Ergebnisse, mit dem Mock und capskip 1.7.0, unter Windows 11:
| Laufzeit | Unit-Tests | E2E-Tests |
|---|---|---|
| Node.js 24.22.0 | 13 bestanden in 2 Dateien | 11 bestanden, etwa 19 s |
| Node.js 25.2.1 | 13 bestanden in 2 Dateien | 11 bestanden, etwa 19 s |
| Node.js 20.11.1 | Der Scaffold-Befehl und Vitest schlagen fehl | Der Scaffold-Befehl und Vitest schlagen fehl |
Unter 20.11.1 brechen der Scaffold-Befehl und Vitest mit dem Fehler ab, dass node:util keinen Export namens styleText hat, den diese Version nicht bereitstellt.
Auf einem anderen Rechner ausführen: Server mode
Ein Nest-Service läuft selten auf dem PC, auf dem CapSkip läuft. Tragen Sie die Adresse dieses PCs in CAPSKIP_HOST ein, dann ändert sich sonst nichts. CapSkip muss dann im Server mode laufen, beschrieben im Abschnitt Verbindungseinstellungen der Einrichtungsanleitung, laut der Server mode voraussetzt, dass CapSkip als Administrator läuft. Das SDK spricht reines http und sendet den Key im Query-String jedes res.php-Aufrufs, halten Sie diese Verbindung also in einem privaten Netzwerk.
CapSkip öffnet seinen Port für alle Adressen, sobald Server mode startet. Um ihn auf die erwarteten Rechner zu beschränken, fügen Sie eine Block-Regel der Windows-Firewall für die übrigen hinzu und schalten Sie API Key Validation ein, damit CAPSKIP_API_KEY etwas bedeutet. Läuft CapSkip nicht, scheitert das Einreichen mit einer NetworkException (in meinem Lauf eine verweigerte Verbindung auf 127.0.0.1), und der Filter antwortet mit 503. Eine nicht routbare Adresse (192.0.2.1) ließ das SDK nach 21,1 Sekunden aufgeben, der Service antwortete also bei Timeout 20 nach etwa 21 Sekunden mit 503; bei Timeout 5 antwortete das Race nach 11,0 Sekunden mit 504. Diese Läufe nutzten den Mock und Node.js 24.22.0.
Häufige Fehler
| Was Sie sehen | Ursache | Beheben |
|---|---|---|
| Nest can’t resolve dependencies of the CapSkipService, argument Symbol(CAPSKIP_CLIENT) at index [0] | Ein Testmodul listet den Service, aber nicht das Client-Token | Fügen Sie einen Provider für CAPSKIP_CLIENT mit einem Fake hinzu |
| Nest can’t resolve dependencies of the CONFIGURABLE_MODULE_OPTIONS provider, argument ConfigService | forRootAsync injiziert ConfigService, aber ConfigModule ist weder global noch importiert | Übergeben Sie imports mit ConfigModule oder setzen Sie isGlobal in ConfigModule.forRoot |
TypeError: Cannot read properties of undefined (reading "get") | Die Factory hat einen Parameter config, aber forRootAsync hat keine inject-Liste | Fügen Sie inject mit ConfigService hinzu |
| Nest can’t resolve dependencies of the Symbol(CAPSKIP_CLIENT) provider, argument CONFIGURABLE_MODULE_OPTIONS | CapSkipModule wurde ohne forRoot oder forRootAsync importiert | Importieren Sie das Ergebnis eines dieser beiden Aufrufe |
| HTTP 502 mit code ERROR_WRONG_USER_KEY oder ERROR_KEY_DOES_NOT_EXIST | API Key Validation ist in CapSkip eingeschaltet. Der erste Code bedeutet, der Key fehlt oder ist leer, der zweite, dass er ungültig ist | Setzen Sie CAPSKIP_API_KEY auf einen gültigen Key und starten Sie den Service neu |
| HTTP 504, lange nachdem Sie aufgegeben haben | Das SDK pollt weiter bis zu seiner eigenen Deadline, oder das Race hat ein stummes CapSkip aufgegeben | Senken Sie CAPSKIP_TIMEOUT und lesen Sie Schritt 3 |
Die vier Nest-Meldungen sind der echte Wortlaut von Nest 12.4.2, wie mein Testmodul sie ausgibt, gekürzt. Die CapSkip-Fehlercodes stehen in der API-Dokumentation.
FAQ
Kann ein NestJS Captcha-Service auf einem anderen Rechner laufen als CapSkip?
Ja. Setzen Sie CAPSKIP_HOST auf die Adresse des CapSkip-PCs und schalten Sie CapSkip auf Server mode. Server mode lässt CapSkip Verbindungen auf jeder Adresse annehmen, fügen Sie daher eine Block-Regel der Windows-Firewall für Rechner hinzu, die Sie nicht erwarten, und schalten Sie API Key Validation ein. Eine Codeänderung ist nicht nötig.
Wann sollte ich eine Queue statt eines Controllers nutzen?
Wenn der Aufrufer nicht auf eine Lösung warten kann oder viele gleichzeitig eintreffen. Ein Controller hält die Anfrage für das gesamte Lösen offen, was bei ein oder zwei gleichzeitig in Ordnung ist. Ein Queue-Prozessor kann dasselbe CapSkipModule importieren, und der BullMQ-Worker-Leitfaden behandelt diese Seite.
Warum gibt der Service einen User-Agent neben dem Token zurück?
Laut den SDK-Typen ist bei Turnstile der User-Agent des Ergebnisses der, den Sie beim Einreichen des Tokens verwenden sollen, und er ist nur vorhanden, wenn CapSkip einen meldet. Der Service reicht ihn weiter, damit der Aufrufer ihn senden kann.
Ein NestJS Captcha-Service, der Turnstile passieren muss, braucht drei Dinge an der richtigen Stelle: den Client hinter einem Token, damit er sich fälschen lässt, eine Stelle, die SDK-Fehler in Status umwandelt, und ein Timeout bei jedem Aufruf plus ein Race für den stummen Fall. CapSkip ist ein unbegrenzter Captcha-Löser auf Hardware in Ihrem Besitz. Ein Retry oder ein fehlschlagender Testlauf taucht deshalb nie auf einer Rechnung auf. Das Lösen der anderen Captcha-Typen mit Node.js behandelt die Node.js-Captcha-Solver-Seite.
