Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -1,5 +1,5 @@
import { describe, it, expect } from "vitest";
import { resolveCaptchaConfig, getSitekey, isCaptchaConfigured } from "./config.js";
import { resolveCaptchaConfig, getSecret, getSitekey, isCaptchaConfigured } from "./config.js";
describe("resolveCaptchaConfig", () => {
it("maps env vars to config", () => {
@@ -14,6 +14,25 @@ describe("resolveCaptchaConfig", () => {
expect(cfg.instanceUrl).toBe("https://captcha.tool-ctrl.de");
expect(getSitekey(cfg, "login")).toBe("login-key");
expect(getSitekey(cfg, "booking")).toBe("booking-key");
expect(getSecret(cfg, "forms")).toBe("secret");
expect(isCaptchaConfigured(cfg)).toBe(true);
});
it("maps Cap env vars to config", () => {
const cfg = resolveCaptchaConfig({
CAPTCHA_PROVIDER: "cap",
CAP_INSTANCE_URL: "https://captcha.hivegrid.de",
CAP_SITE_SECRET: "shared-secret",
CAP_SITE_SECRET_LOGIN: "login-secret",
CAP_SITEKEY_LOGIN: "login-key",
CAP_SITEKEY_FORMS: "forms-key",
CAP_SITEKEY_BOOKING: "booking-key",
});
expect(cfg.provider).toBe("cap");
expect(cfg.instanceUrl).toBe("https://captcha.hivegrid.de");
expect(getSitekey(cfg, "login")).toBe("login-key");
expect(getSecret(cfg, "login")).toBe("login-secret");
expect(getSecret(cfg, "forms")).toBe("shared-secret");
expect(isCaptchaConfigured(cfg)).toBe(true);
});
@@ -1,4 +1,4 @@
import type { CaptchaConfig, CaptchaSurface } from "./types.js";
import type { CaptchaConfig, CaptchaProvider, CaptchaSurface } from "./types.js";
type EnvLike = Record<string, string | undefined>;
@@ -8,28 +8,68 @@ function present(value: string | undefined): string | undefined {
}
/**
* Resolves the captcha config from env. mCaptcha is the only provider
* (see HiveGrid docs/ARCHITECTURE-DECISIONS.md AD-7).
* Resolves the captcha config from env. mCaptcha remains the default provider
* for compatibility; set CAPTCHA_PROVIDER=cap to use Cap.
*
* CAPTCHA_PROVIDER=mcaptcha|cap
* MCAPTCHA_INSTANCE_URL=https://captcha.tool-ctrl.de
* MCAPTCHA_ACCOUNT_SECRET=<dashboard account secret>
* MCAPTCHA_SITEKEY_LOGIN / _FORMS / _BOOKING=<public sitekeys>
*
* CAP_INSTANCE_URL=https://captcha.hivegrid.de
* CAP_SITE_SECRET=<fallback site secret>
* CAP_SITE_SECRET_LOGIN / _FORMS / _BOOKING=<per-surface site secrets>
* CAP_SITEKEY_LOGIN / _FORMS / _BOOKING=<public sitekeys>
*
* CAPTCHA_FAIL_OPEN=true|false (default true)
*/
export function resolveCaptchaConfig(env: EnvLike): CaptchaConfig {
const provider = resolveProvider(env);
if (provider === "cap") {
const sharedSecret = present(env.CAP_SITE_SECRET);
return {
provider,
instanceUrl: present(env.CAP_INSTANCE_URL),
accountSecret: sharedSecret,
sitekeys: {
login: present(env.CAP_SITEKEY_LOGIN),
forms: present(env.CAP_SITEKEY_FORMS),
booking: present(env.CAP_SITEKEY_BOOKING),
},
secrets: {
login: present(env.CAP_SITE_SECRET_LOGIN) ?? sharedSecret,
forms: present(env.CAP_SITE_SECRET_FORMS) ?? sharedSecret,
booking: present(env.CAP_SITE_SECRET_BOOKING) ?? sharedSecret,
},
failOpen: present(env.CAPTCHA_FAIL_OPEN) !== "false",
};
}
const accountSecret = present(env.MCAPTCHA_ACCOUNT_SECRET);
return {
provider: "mcaptcha",
provider,
instanceUrl: present(env.MCAPTCHA_INSTANCE_URL),
accountSecret: present(env.MCAPTCHA_ACCOUNT_SECRET),
accountSecret,
sitekeys: {
login: present(env.MCAPTCHA_SITEKEY_LOGIN),
forms: present(env.MCAPTCHA_SITEKEY_FORMS),
booking: present(env.MCAPTCHA_SITEKEY_BOOKING),
},
secrets: {
login: accountSecret,
forms: accountSecret,
booking: accountSecret,
},
failOpen: present(env.CAPTCHA_FAIL_OPEN) !== "false",
};
}
function resolveProvider(env: EnvLike): CaptchaProvider {
const explicit = present(env.CAPTCHA_PROVIDER)?.toLowerCase();
if (explicit === "cap") return "cap";
return "mcaptcha";
}
export function getSitekey(
config: CaptchaConfig,
surface: CaptchaSurface,
@@ -37,7 +77,14 @@ export function getSitekey(
return config.sitekeys[surface];
}
/** True when the instance + account secret are present (sitekeys checked per-surface). */
export function getSecret(
config: CaptchaConfig,
surface: CaptchaSurface,
): string | undefined {
return config.secrets[surface] ?? config.accountSecret;
}
/** True when the instance + at least one secret are present (sitekeys checked per-surface). */
export function isCaptchaConfigured(config: CaptchaConfig): boolean {
return Boolean(config.instanceUrl && config.accountSecret);
return Boolean(config.instanceUrl && (config.accountSecret || Object.values(config.secrets).some(Boolean)));
}
@@ -2,4 +2,4 @@ export type { CaptchaSurface, CaptchaLogger, CaptchaConfig } from "./types.js";
export { CAPTCHA_SURFACES } from "./types.js";
export { verifyCaptchaToken } from "./verify.js";
export type { VerifyCaptchaArgs } from "./verify.js";
export { resolveCaptchaConfig, getSitekey, isCaptchaConfigured } from "./config.js";
export { resolveCaptchaConfig, getSecret, getSitekey, isCaptchaConfigured } from "./config.js";
@@ -1,21 +1,25 @@
// Captcha surfaces — one mCaptcha sitekey per surface so difficulty/rate-limit
// can be tuned independently (see infra/mcaptcha/README.md).
// Captcha surfaces — one sitekey per surface so difficulty/rate-limit can be
// tuned independently (see infra/mcaptcha/README.md and infra/cap/README.md).
export type CaptchaSurface = "login" | "forms" | "booking";
export const CAPTCHA_SURFACES: readonly CaptchaSurface[] = ["login", "forms", "booking"];
export type CaptchaProvider = "mcaptcha" | "cap";
export type CaptchaLogger = {
warn: (metadata: Record<string, unknown>, message: string) => void;
};
export type CaptchaConfig = {
provider: "mcaptcha";
/** Public base URL of the self-hosted mCaptcha instance, e.g. https://captcha.tool-ctrl.de */
provider: CaptchaProvider;
/** Public base URL of the self-hosted captcha instance, e.g. https://captcha.hivegrid.de */
instanceUrl: string | undefined;
/** mCaptcha dashboard account secret used for server-side siteverify. */
/** Legacy/shared secret used for server-side siteverify. Prefer `secrets` for new Cap keys. */
accountSecret: string | undefined;
/** Public sitekey per surface (created in the mCaptcha dashboard). */
sitekeys: Record<CaptchaSurface, string | undefined>;
/** Server-side secret per surface. mCaptcha uses the same account secret for every surface. */
secrets: Record<CaptchaSurface, string | undefined>;
/**
* When the instance is unreachable/misconfigured: true = let the request
* through (fail-open, default), false = block it (fail-closed). A missing
@@ -32,6 +32,26 @@ describe("verifyCaptchaToken", () => {
expect(calledBody).toEqual({ token: "pow-token", key: "site-key", secret: "account-secret" });
});
it("returns true when Cap reports success", async () => {
let calledUrl = "";
let calledBody: unknown = null;
const fetchImpl = (async (url: string, init?: RequestInit) => {
calledUrl = url;
calledBody = JSON.parse(String(init?.body));
return jsonResponse({ success: true });
}) as unknown as typeof fetch;
const ok = await verifyCaptchaToken({ ...base, provider: "cap", fetchImpl });
expect(ok).toBe(true);
expect(calledUrl).toBe("https://captcha.example.test/site-key/siteverify");
expect(calledBody).toEqual({ response: "pow-token", secret: "account-secret" });
});
it("returns false when Cap reports failure", async () => {
const fetchImpl = (async () => jsonResponse({ success: false })) as unknown as typeof fetch;
expect(await verifyCaptchaToken({ ...base, provider: "cap", fetchImpl })).toBe(false);
});
it("returns false when mCaptcha reports invalid", async () => {
const fetchImpl = (async () => jsonResponse({ valid: false })) as unknown as typeof fetch;
expect(await verifyCaptchaToken({ ...base, fetchImpl })).toBe(false);
@@ -1,17 +1,18 @@
import type { CaptchaLogger } from "./types.js";
import type { CaptchaLogger, CaptchaProvider } from "./types.js";
const DEFAULT_TIMEOUT_MS = 3_000;
const SITEVERIFY_PATH = "/api/v1/pow/siteverify";
const MCAPTCHA_SITEVERIFY_PATH = "/api/v1/pow/siteverify";
export type VerifyCaptchaArgs = {
/** PoW solution token produced by the mCaptcha widget. */
/** Challenge token produced by the captcha widget. */
token: string | null | undefined;
/** Public sitekey for the surface being protected. */
sitekey: string | undefined;
/** mCaptcha account secret (server-side only). */
/** Server-side site/account secret. */
secret: string | undefined;
/** Base URL of the mCaptcha instance. */
/** Base URL of the captcha instance. */
instanceUrl: string | undefined;
provider?: CaptchaProvider;
/** Outage/misconfig policy: true (default) lets the request through. */
failOpen?: boolean;
logger?: CaptchaLogger;
@@ -20,10 +21,15 @@ export type VerifyCaptchaArgs = {
};
/**
* Verifies an mCaptcha proof-of-work token against a self-hosted instance.
* Verifies a captcha token against a self-hosted provider.
*
* POST {instanceUrl}/api/v1/pow/siteverify body: { token, key, secret }
* response: { valid: boolean }
* mCaptcha:
* POST {instanceUrl}/api/v1/pow/siteverify body: { token, key, secret }
* response: { valid: boolean }
*
* Cap:
* POST {instanceUrl}/{sitekey}/siteverify body: { response, secret }
* response: { success: boolean }
*
* Semantics:
* - missing token -> false (real client failure, never fail-open)
@@ -35,6 +41,7 @@ export async function verifyCaptchaToken({
sitekey,
secret,
instanceUrl,
provider = "mcaptcha",
failOpen = true,
logger,
fetchImpl = fetch,
@@ -49,43 +56,73 @@ export async function verifyCaptchaToken({
hasSitekey: Boolean(sitekey),
failOpen,
},
"mCaptcha not configured — applying fail policy",
"captcha not configured — applying fail policy",
);
return failOpen;
}
if (!token) return false;
const url = instanceUrl.replace(/\/+$/, "") + SITEVERIFY_PATH;
const url = buildSiteverifyUrl({ provider, instanceUrl, sitekey });
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 }),
body: JSON.stringify(buildSiteverifyBody({ provider, token, 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",
{ op: "captcha.http_error", provider, status: res.status, failOpen },
"captcha siteverify returned non-OK — applying fail policy",
);
return failOpen;
}
const data = (await res.json()) as { valid?: boolean };
return data.valid === true;
const data = (await res.json()) as { valid?: boolean; success?: boolean };
return provider === "cap" ? data.success === true : data.valid === true;
} catch (err) {
logger?.warn(
{
op: "captcha.error",
provider,
err: err instanceof Error ? err.message : String(err),
failOpen,
},
"mCaptcha verification failed — applying fail policy",
"captcha verification failed — applying fail policy",
);
return failOpen;
} finally {
clearTimeout(timeout);
}
}
function buildSiteverifyUrl({
provider,
instanceUrl,
sitekey,
}: {
provider: CaptchaProvider;
instanceUrl: string;
sitekey: string;
}): string {
const base = instanceUrl.replace(/\/+$/, "");
if (provider === "cap") return `${base}/${encodeURIComponent(sitekey)}/siteverify`;
return base + MCAPTCHA_SITEVERIFY_PATH;
}
function buildSiteverifyBody({
provider,
token,
sitekey,
secret,
}: {
provider: CaptchaProvider;
token: string;
sitekey: string;
secret: string;
}): Record<string, string> {
if (provider === "cap") return { response: token, secret };
return { token, key: sitekey, secret };
}