Function handleKeylessAuth

apps/api/src/controllers/auth.ts:486–628

* Keyless free tier: official MCP/CLI/SDK clients can call scrape, search, and * interact with no API key. `origin`/`integration` are client-set and spoofable, * so they're only a soft UX gate — the real abuse controls are the per-IP daily * request + credit caps plus the `keyless/consume` canoni

(
  req,
  mode: RateLimiterMode | undefined,
  allowKeyless: boolean | undefined,
)

 * Always returns an AuthResponse — handles every no-API-key request.
 */
async function handleKeylessAuth(
  req,
  mode: RateLimiterMode | undefined,
  allowKeyless: boolean | undefined,
): Promise<AuthResponse> {
  const unauthorized: AuthResponse = {
    success: false,
    error: "Unauthorized",
    status: 401,
  };

  // The keyless tier is off unless BOTH limits are configured (even to 0). When
  // unconfigured we behave exactly as before — a generic 401 — and don't reveal
  // that the tier exists.
  if (!isKeylessConfigured()) return unauthorized;

  // Configured, but this endpoint isn't part of the keyless tier: tell the user
  // they need a key (with the signup nudge) rather than a bare "Unauthorized".
  if (!allowKeyless) {
    return {
      success: false,
      error: KEYLESS_ENDPOINT_NOT_AVAILABLE_MESSAGE,
      status: 401,
    };
  }

  const origin = req.body?.origin;
  const integration = req.body?.integration;
  // No origin/surface gate: any request without an API key may use the free
  // tier on the allowlisted endpoints (the API itself is free). origin and
  // integration are still recorded below for abuse monitoring.

  // Key on the real client IP. A trusted proxy (e.g. the hosted MCP) may
  // forward the end-user's IP via x-firecrawl-keyless-ip, authenticated with a
  // shared secret — without the secret the header is ignored, so direct callers
  // can't spoof their IP to dodge the per-IP cap.
  let ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";
  if (
    config.KEYLESS_PROXY_SECRET &&
    req.headers["x-firecrawl-keyless-secret"] === config.KEYLESS_PROXY_SECRET
  ) {
    const forwarded = req.headers["x-firecrawl-keyless-ip"];
    if (typeof forwarded === "string" && forwarded.trim()) {
      ip = forwarded.trim();
    }
  }

  // Only a valid IPv4 identity gets keyless: IPv6 is too cheap to rotate for a
  // per-IP cap to mean anything, and malformed/forwarded values must not be
  // usable as arbitrary limiter buckets. Anything else falls through to 401.
  if (!isKeylessIpEligible(ip)) return unauthorized;

  // Optional Spur Context check (only when SPUR_API_KEY is set): refuse keyless
  // for IPs fronting anonymizing/rotating infrastructure (VPN/proxy/TOR), the
  // main way the per-IP caps get bypassed. Fails open on any Spur error, and
  // runs before consuming quota so a flagged IP doesn't burn a request slot.
  if (await isKeylessIpSuspicious(ip)) {
    logger.warn("Keyless request blocked: suspicious IP", {