289 lines
11 KiB
TypeScript
289 lines
11 KiB
TypeScript
/**
|
|
* 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 };
|