@hostily/captcha
v0.1.0
Published
Server-side client for hostily Captcha (captcha.hostily.de): verify the token of a submitted form.
Maintainers
Readme
@hostily/captcha (Node.js / TypeScript)
Deutsch
Kleiner Client für hostily Captcha. Node ≥ 18, nur das eingebaute fetch, ESM und CommonJS, Typen inklusive.
npm install @hostily/captchaimport { Client, UnavailableError } from "@hostily/captcha";
const captcha = new Client(process.env.HOSTILY_CAPTCHA_SECRET!); // Secret nur auf dem Server!
try {
const result = await captcha.verifyForm(req.body, req.ip); // Objekt, FormData oder URLSearchParams
if (!result.success) { /* result.gruende, result.punkte */ }
} catch (err) {
if (err instanceof UnavailableError) { /* Dienst nicht erreichbar: blockieren oder durchlassen */ }
else throw err;
}verify(token, { remoteip, formular });verifyForm(form, remoteip, sendContent = true)holt Token (hostily-captcha-token, sonstg-recaptcha-response) und Inhalt aus dem Formular.tokenFrom(form)undformContent(form): Letzteres entfernt Passwortfelder, Secrets, CSRF-Token, Kartencodes und die Token-Felder. Passwörter werden nie mitgeschickt.- Ergebnis:
success,gruende,punkte,errorCodes,hostname,challengeTs,isConfigurationError. - Optionen:
new Client(secret, { endpoint, timeoutMs = 5000, fetch }). Ohne Token wird der Dienst nicht gefragt (token_fehlt). Ein Token gilt nur für eine Prüfung. - Tests:
npm install && npm test(node:test).
English
Small client for hostily Captcha. Node ≥ 18, uses only the built-in fetch, ESM and CommonJS, types included.
Install and use as above.
verify(token, { remoteip, formular });verifyForm(form, remoteip, sendContent = true)takes the token (hostily-captcha-token, elseg-recaptcha-response) and the content from the form (plain object,FormData,URLSearchParams).tokenFrom(form)andformContent(form); the latter drops password fields, secrets, CSRF tokens, card codes and the token fields. Passwords are never sent.- Result:
success,gruende,punkte,errorCodes,hostname,challengeTs,isConfigurationError. UnavailableErroris thrown when the service is unreachable, times out, answers HTTP 5xx/429 or non-JSON: you decide to block or let pass.- Options:
new Client(secret, { endpoint, timeoutMs = 5000, fetch }). Without a token the service is not called (token_fehlt). A token is valid for one check only. Tests:npm install && npm test(node:test).
MIT License.
