Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
import { Request, Response } from "express";
import { config } from "../../config";
import { timingSafeSecretEqual } from "../../lib/secret-compare";
import {
checkKeylessEligibility,
keylessSignupUrlForIp,
keylessWorldIdIdentity,
reportKeylessPromptShown,
} from "../../lib/keyless";
import {
type KeylessPromptReason,
keylessFallbackSignupUrl,
keylessSignupSurface,
} from "../../lib/keyless-signup-link";
import { verifyWorldIdCredential } from "../../lib/world-id";
/**
* Internal endpoint for trusted proxies (the hosted MCP) to check, before a
* keyless tool call, whether a client IP can currently use the tier — without
* consuming quota. Gated by the shared KEYLESS_PROXY_SECRET; the client IP is
* supplied via x-firecrawl-keyless-ip. Lets the MCP serve keyless when eligible
* and return a structured recovery action when the IP is not eligible.
*
* An ineligible result carries `signupUrl`, the caller's own signup link, which
* the MCP relays in its recovery message. `?signup_link=1` asks for the link on
* any result, for the account-only tool prompt (a tool keyless sessions cannot
* use), and tags it with that reason whatever the eligibility.
*
* A forwarded `x-firecrawl-world-id` credential is checked against the
* verified human's own bucket instead of the IP, as auth does.
*/
export async function keylessEligibilityController(
req: Request,
res: Response,
): Promise<void> {
const secret = req.headers["x-firecrawl-keyless-secret"];
if (!timingSafeSecretEqual(secret, config.KEYLESS_PROXY_SECRET)) {
res.status(401).json({ eligible: false, error: "Unauthorized" });
return;
}
const ipHeader = req.headers["x-firecrawl-keyless-ip"];
const ip =
(typeof ipHeader === "string" ? ipHeader.trim() : "") || req.ip || "";
const worldIdSubject = verifyWorldIdCredential(
req.headers["x-firecrawl-world-id"],
);
const result = await checkKeylessEligibility(
ip,
worldIdSubject ? keylessWorldIdIdentity(worldIdSubject) : undefined,
);
const accountOnlyTool = req.query?.signup_link === "1";
if (result.eligible && !accountOnlyTool) {
res.status(200).json(result);
return;
}
const surface = keylessSignupSurface(req);
const reason: KeylessPromptReason | undefined = accountOnlyTool
? "account_only_tool"
: result.reason === "requests" || result.reason === "credits"
? "limit"
: result.reason === "suspicious"
? "suspicious_ip"
: undefined;
// A tier that is off or a limiter that is down is not a prompt about this
// identity, so it gets the regular signup link.
let signupUrl = keylessFallbackSignupUrl(surface);
if (reason) {
// A World ID caller isn't keyed on the IP, so it gets no IP-bound link
// or funnel report, as in auth.
const promptIp = worldIdSubject ? null : ip;
const link = keylessSignupUrlForIp(promptIp, surface, reason);
signupUrl = link.url;
// The hosted MCP relays this link as the prompt; this check answers 200.
reportKeylessPromptShown(promptIp, surface, reason, 200, link.signupRef);
}
res.status(200).json({ ...result, signupUrl });
}