/** * 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; 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 { 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 = {}; 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 { 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 { 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 };