Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,91 @@
import type { CaptchaLogger } from "./types.js";
const DEFAULT_TIMEOUT_MS = 3_000;
const SITEVERIFY_PATH = "/api/v1/pow/siteverify";
export type VerifyCaptchaArgs = {
/** PoW solution token produced by the mCaptcha widget. */
token: string | null | undefined;
/** Public sitekey for the surface being protected. */
sitekey: string | undefined;
/** mCaptcha account secret (server-side only). */
secret: string | undefined;
/** Base URL of the mCaptcha instance. */
instanceUrl: string | undefined;
/** Outage/misconfig policy: true (default) lets the request through. */
failOpen?: boolean;
logger?: CaptchaLogger;
fetchImpl?: typeof fetch;
timeoutMs?: number;
};
/**
* Verifies an mCaptcha proof-of-work token against a self-hosted instance.
*
* POST {instanceUrl}/api/v1/pow/siteverify body: { token, key, secret }
* response: { valid: boolean }
*
* Semantics:
* - missing token -> false (real client failure, never fail-open)
* - misconfigured / outage -> `failOpen` (default true), with a warn log
* - valid:true -> true, otherwise false
*/
export async function verifyCaptchaToken({
token,
sitekey,
secret,
instanceUrl,
failOpen = true,
logger,
fetchImpl = fetch,
timeoutMs = DEFAULT_TIMEOUT_MS,
}: VerifyCaptchaArgs): Promise<boolean> {
if (!instanceUrl || !secret || !sitekey) {
logger?.warn(
{
op: "captcha.misconfigured",
hasInstance: Boolean(instanceUrl),
hasSecret: Boolean(secret),
hasSitekey: Boolean(sitekey),
failOpen,
},
"mCaptcha not configured — applying fail policy",
);
return failOpen;
}
if (!token) return false;
const url = instanceUrl.replace(/\/+$/, "") + SITEVERIFY_PATH;
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetchImpl(url, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ token, key: sitekey, secret }),
signal: controller.signal,
});
if (!res.ok) {
logger?.warn(
{ op: "captcha.http_error", status: res.status, failOpen },
"mCaptcha siteverify returned non-OK — applying fail policy",
);
return failOpen;
}
const data = (await res.json()) as { valid?: boolean };
return data.valid === true;
} catch (err) {
logger?.warn(
{
op: "captcha.error",
err: err instanceof Error ? err.message : String(err),
failOpen,
},
"mCaptcha verification failed — applying fail policy",
);
return failOpen;
} finally {
clearTimeout(timeout);
}
}