Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,288 @@
/**
* Public lead-capture endpoint for the marketing-funnel SDK
* (Phase 05 Task #78, layer 2).
*
* POST /api/leads/capture
*
* Accepts JSON or form-encoded body with at minimum an `email`. Optional
* profile fields (firstName, lastName, phone, company), `source` label, and
* `attribution` (utmSource, utmMedium, utmCampaign, utmTerm, utmContent,
* gclid, fbclid, referrer, landingPage). Anti-spam defence in depth:
*
* 1. Origin allowlist from `MARKETING_ALLOWED_ORIGINS` (csv with `*.host`
* wildcard support). Rejects with 403 on miss.
* 2. Honeypot field `website_url` — silent 204 when filled.
* 3. Sliding-window rate-limit: 5/min per IP, 1/min per email
* (configurable via `MARKETING_RATE_LIMIT_PER_MIN`).
* 4. Optional Cloudflare Turnstile — gated behind
* `marketing-funnel-turnstile` feature flag and the `turnstileToken`
* field in the payload.
*
* The response body is intentionally empty (200 OK with no body) regardless
* of insert-vs-update so bots cannot enumerate existing emails.
*
* CORS preflight (OPTIONS) is answered with the matching allowlist entry
* echoed in `Access-Control-Allow-Origin`. POST responses also include the
* CORS header so cross-origin browsers can read the status code.
*/
import { z } from "zod";
import { createSlidingWindowRateLimiter } from "@toolctrl/shared-store";
import { captureLead } from "~/utils/leads/captureLead.server";
import { matchAllowedOrigin, parseAllowedOrigins } from "~/utils/leads/originCheck";
import { getSharedStore } from "~/shared-store.server";
import { createScopedLogger } from "~/utils/logger.server";
import { evaluateFlagForContext } from "~/utils/services/.server/featureFlagEvaluator.server";
import { getTranslations } from "~/locale/i18next.server";
import { resolveCaptchaConfig, verifyCaptchaToken } from "@toolctrl/captcha";
const log = createScopedLogger("marketing.lead-capture");
// On a rate-limit store (Redis) outage, production fails closed so an attacker
// cannot flood this unauthenticated endpoint by knocking the store offline.
// Non-production fails open so local/dev captures aren't dropped.
function shouldFailClosedOnRateLimitInfraFailure(): boolean {
return process.env.NODE_ENV === "production";
}
const PAYLOAD_BYTE_LIMIT = 32 * 1024; // 32 KiB — leads have a tiny shape
const HONEYPOT_FIELD = "website_url";
const AttributionSchema = z
.object({
utmSource: z.string().max(200).optional().nullable(),
utmMedium: z.string().max(200).optional().nullable(),
utmCampaign: z.string().max(200).optional().nullable(),
utmTerm: z.string().max(200).optional().nullable(),
utmContent: z.string().max(200).optional().nullable(),
gclid: z.string().max(200).optional().nullable(),
fbclid: z.string().max(200).optional().nullable(),
referrer: z.string().max(2048).optional().nullable(),
landingPage: z.string().max(2048).optional().nullable(),
})
.partial();
const CaptureSchema = z.object({
email: z.string().email().max(254),
firstName: z.string().max(120).optional().nullable(),
lastName: z.string().max(120).optional().nullable(),
phone: z.string().max(60).optional().nullable(),
company: z.string().max(200).optional().nullable(),
source: z.string().max(120).optional().nullable(),
attribution: AttributionSchema.optional(),
turnstileToken: z.string().max(2048).optional().nullable(),
// Honeypot — when present-and-truthy we silently 204.
[HONEYPOT_FIELD]: z.string().optional().nullable(),
});
type CapturePayload = z.infer<typeof CaptureSchema>;
function clientIp(request: Request): string | null {
const fwd = request.headers.get("x-forwarded-for");
if (fwd) return fwd.split(",")[0]?.trim() || null;
return request.headers.get("x-real-ip");
}
function corsHeaders(origin: string | null, allowed: readonly string[]): Headers {
const h = new Headers();
if (origin && matchAllowedOrigin(origin, allowed)) {
h.set("Access-Control-Allow-Origin", origin);
h.set("Vary", "Origin");
}
h.set("Access-Control-Allow-Methods", "POST, OPTIONS");
h.set("Access-Control-Allow-Headers", "Content-Type");
h.set("Access-Control-Max-Age", "600");
return h;
}
async function parseBody(request: Request): Promise<unknown> {
const ct = (request.headers.get("content-type") ?? "").toLowerCase();
if (ct.includes("application/json")) {
return await request.json();
}
if (ct.includes("application/x-www-form-urlencoded") || ct.includes("multipart/form-data")) {
const form = await request.formData();
const obj: Record<string, unknown> = {};
for (const [k, v] of form.entries()) {
if (k === "attribution" && typeof v === "string") {
try {
obj.attribution = JSON.parse(v);
continue;
} catch {
// ignore — drop unparsable attribution
}
}
obj[k] = typeof v === "string" ? v : null;
}
return obj;
}
// Fallback — try JSON
try {
return await request.json();
} catch {
throw new Error("Unsupported Content-Type");
}
}
export async function loader({ request }: { request: Request }): Promise<Response> {
const { t } = await getTranslations(request);
return Response.json({ ok: false, error: t("api.errors.leadCapture.methodNotAllowed") }, { status: 405 });
}
export async function action({ request }: { request: Request }): Promise<Response> {
const origin = request.headers.get("origin");
const allowed = parseAllowedOrigins(process.env.MARKETING_ALLOWED_ORIGINS);
const headers = corsHeaders(origin, allowed);
if (request.method === "OPTIONS") {
return new Response(null, { status: 204, headers });
}
const { t } = await getTranslations(request);
if (request.method !== "POST") {
return Response.json({ ok: false, error: t("api.errors.leadCapture.methodNotAllowed") }, { status: 405, headers });
}
// 1. Origin allowlist — fail-closed
if (!matchAllowedOrigin(origin, allowed)) {
log.info({ op: "blocked.origin", origin }, "Lead capture origin not allowlisted");
return Response.json({ ok: false, error: t("api.errors.leadCapture.originNotAllowed") }, { status: 403, headers });
}
// 2. Payload-size cap before parsing
const contentLength = Number(request.headers.get("content-length") ?? "0");
if (Number.isFinite(contentLength) && contentLength > PAYLOAD_BYTE_LIMIT) {
return Response.json({ ok: false, error: t("api.errors.leadCapture.payloadTooLarge") }, { status: 413, headers });
}
let rawBody: unknown;
try {
rawBody = await parseBody(request);
} catch (err) {
log.info(
{ op: "parse.failed", err: err instanceof Error ? err.message : String(err) },
"Failed to parse capture payload",
);
return Response.json({ ok: false, error: t("api.errors.leadCapture.invalidPayload") }, { status: 400, headers });
}
const parsed = CaptureSchema.safeParse(rawBody);
if (!parsed.success) {
return Response.json({ ok: false, error: t("api.errors.leadCapture.invalidPayloadShape") }, { status: 400, headers });
}
const payload = parsed.data;
// 3. Honeypot — silent 204 (no body) so bots can't differentiate
const honeypotValue = payload[HONEYPOT_FIELD];
if (typeof honeypotValue === "string" && honeypotValue.trim() !== "") {
log.info({ op: "blocked.honeypot" }, "Honeypot triggered — silent drop");
return new Response(null, { status: 204, headers });
}
// 4. Rate-limit: per-IP and per-email sliding-window
const ip = clientIp(request);
const perMinLimit = Math.max(1, Number(process.env.MARKETING_RATE_LIMIT_PER_MIN ?? "5"));
try {
const store = getSharedStore();
if (ip) {
const ipLimiter = createSlidingWindowRateLimiter({
store,
max: perMinLimit,
windowSeconds: 60,
prefix: "marketing-lead-capture:rl-ip",
});
const ipDecision = await ipLimiter.consume(`ip:${ip}`);
if (!ipDecision.allowed) {
return Response.json({ ok: false, error: t("api.errors.leadCapture.tooManyRequests") }, { status: 429, headers });
}
}
// 1 capture per email per minute keeps de-dupes from flooding LeadEvent.
const emailLimiter = createSlidingWindowRateLimiter({
store,
max: 1,
windowSeconds: 60,
prefix: "marketing-lead-capture:rl-email",
});
const emailDecision = await emailLimiter.consume(`email:${payload.email.toLowerCase()}`);
if (!emailDecision.allowed) {
// Generic message — never expose "already exists" vs "rate-limited"
return new Response(null, { status: 204, headers });
}
} catch (err) {
log.warn(
{ op: "rate-limit.error", err: err instanceof Error ? err.message : String(err) },
"Rate-limit check failed",
);
if (shouldFailClosedOnRateLimitInfraFailure()) {
// Production: refuse rather than allow unbounded captures while the
// rate-limit store is unavailable. 503 lets clients retry later.
return Response.json({ ok: false, error: t("api.errors.leadCapture.tooManyRequests") }, { status: 503, headers });
}
// Non-production: fail open so local/dev captures aren't dropped.
}
// 5. Optional captcha gate (mCaptcha, feature-flag-gated)
try {
const flag = await evaluateFlagForContext("marketing-funnel-turnstile", {
flagName: "marketing-funnel-turnstile",
tenantId: null,
userId: null,
});
const captcha = resolveCaptchaConfig(process.env);
if (flag.enabled && captcha.instanceUrl && captcha.accountSecret) {
const ok = await verifyCaptchaToken({
token: payload.turnstileToken ?? null,
sitekey: captcha.sitekeys.forms,
secret: captcha.accountSecret,
instanceUrl: captcha.instanceUrl,
failOpen: captcha.failOpen,
logger: log,
});
if (!ok) {
return Response.json({ ok: false, error: t("api.errors.leadCapture.antiSpamFailed") }, { status: 403, headers });
}
}
} catch (err) {
log.warn(
{ op: "feature-flag.error", err: err instanceof Error ? err.message : String(err) },
"Feature-flag evaluation failed; skipping captcha",
);
}
// 6. Persist (idempotent on email)
try {
const result = await captureLead({
email: payload.email,
firstName: payload.firstName ?? null,
lastName: payload.lastName ?? null,
phone: payload.phone ?? null,
company: payload.company ?? null,
source: payload.source ?? null,
attribution: payload.attribution ?? undefined,
ip,
userAgent: request.headers.get("user-agent"),
});
log.info(
{ op: result.created ? "captured" : "re-captured", leadId: result.leadId, source: payload.source ?? null },
"Lead capture accepted",
);
} catch (err) {
log.error(
{ op: "persist.failed", err: err instanceof Error ? err.message : String(err) },
"Failed to persist lead",
);
return Response.json({ ok: false, error: t("api.errors.leadCapture.captureFailed") }, { status: 500, headers });
}
// Empty body to avoid email enumeration — same response shape for new and dup.
return new Response(null, { status: 200, headers });
}
// Test-only exports for unit-tests that need to drive the validator / db
// access directly without going through `action`.
export const __test__ = {
CaptureSchema,
HONEYPOT_FIELD,
clientIp,
};
export type { CapturePayload };