Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(api): link keyless prompts to opaque per-identity /k links (#4856)

Rakshith Ramprakash1b0904c84115
diff --git a/apps/api/.env.example b/apps/api/.env.example
index 490c8b69a..a5da41a9b 100644
--- a/apps/api/.env.example
+++ b/apps/api/.env.example
@@ -24,6 +24,11 @@ MCP_ACTION_LOG_SECRET=
# Shared only between the hosted MCP signer and Core verifier. Use 32+ random
# characters and do not reuse KEYLESS_PROXY_SECRET.
MCP_DELEGATED_CREDENTIAL_SECRET=
+# Keyless signup link keys: comma-separated base64 16-byte AES keys
+# (openssl rand -base64 16). The first encrypts the /k/<token> links in keyless
+# prompts; all are tried to decrypt. Set the same value in firecrawl-web.
+# Unset sends the regular signup link.
+KEYLESS_SIGNUP_LINK_KEYS=
# SearchApi key. Head to https://searchapi.com/ to get your API key
SEARCHAPI_API_KEY=
diff --git a/apps/api/src/__tests__/snips/v2/keyless.test.ts b/apps/api/src/__tests__/snips/v2/keyless.test.ts
index addb6b2ab..f7da83517 100644
--- a/apps/api/src/__tests__/snips/v2/keyless.test.ts
+++ b/apps/api/src/__tests__/snips/v2/keyless.test.ts
@@ -13,6 +13,7 @@ import { db } from "../../../db/connection";
import * as schema from "../../../db/schema";
import { and, desc, eq, gt } from "drizzle-orm";
import request from "supertest";
+import { decryptKeylessSignupToken } from "../../../lib/keyless-signup-link";
// The keyless tier is disabled unless both limits are configured. The harness
// passes the shell env through to the server, so we read the same env here and
@@ -40,10 +41,27 @@ async function flushKeylessBuckets() {
}
}
-// Every keyless prompt links to signup with these tags so new accounts can be
-// attributed to the keyless free tier.
+// Every keyless prompt links to signup at firecrawl.dev/k/<token>, the
+// encrypted prompt, or the regular signup link (utm_source=keyless plus the
+// surface) when the server has no KEYLESS_SIGNUP_LINK_KEYS. The URL is always
+// followed by whitespace, never punctuation.
const KEYLESS_SIGNUP_URL =
- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";
+ /https:\/\/(firecrawl\.dev\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}|www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=(api|mcp|cli))(?=\s)/;
+const KEYLESS_SIGNUP_URL_EXACT =
+ /^https:\/\/(firecrawl\.dev\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}|www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=(api|mcp|cli))$/;
+
+// The harness passes the shell env to the server, so the token can be checked
+// here when a key is set; without one the server sends the regular link.
+const SIGNUP_LINK_KEYS_SET = !!process.env.KEYLESS_SIGNUP_LINK_KEYS;
+
+/** Surface and reason a /k link carries; null for the regular signup link. */
+function signupLinkPrompt(url: unknown) {
+ const token = String(url).split("/k/")[1];
+ if (!token) return null;
+ const prompt = decryptKeylessSignupToken(token);
+ expect(prompt).not.toBeNull();
+ return { surface: prompt!.surface, reason: prompt!.reason };
+}
// Recover the loopback IP the server keyed on, so we can seed its credit counter.
async function currentKeylessIp(): Promise<string> {
@@ -112,7 +130,15 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(response.body.error).toContain(
"not supported by the keyless free tier",
);
- expect(response.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(response.body.error).toMatch(KEYLESS_SIGNUP_URL);
+ expect(response.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);
+ expect(response.body.error).toContain(response.body.signup_url);
+ if (SIGNUP_LINK_KEYS_SET) {
+ expect(signupLinkPrompt(response.body.signup_url)).toEqual({
+ surface: "api",
+ reason: "unsupported_endpoint",
+ });
+ }
expect(response.body.error).toContain("Authorization: Bearer YOUR_API_KEY");
});
@@ -163,13 +189,57 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
- expect(blocked.body.error).not.toContain(`${KEYLESS_SIGNUP_URL}.`);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");
// Out of quota β†’ emit the OAuth-discovery header so agents find the key flow.
expect(blocked.headers["www-authenticate"]).toContain("resource_metadata");
});
+ it("gives an identity the same signup link on every prompt, and a separate one per surface (429)", async () => {
+ await request(TEST_API_URL)
+ .post("/v2/scrape")
+ .set("Content-Type", "application/json")
+ .send({ origin: "mcp" });
+ const ip = await currentKeylessIp();
+ await redisRateLimitClient.set(
+ `keyless_credits:${ip}`,
+ String(KEYLESS_CREDITS_PER_DAY),
+ );
+
+ const blockedAs = (body: Record<string, unknown>) =>
+ request(TEST_API_URL)
+ .post("/v2/scrape")
+ .set("Content-Type", "application/json")
+ .send(body);
+ const mcpFirst = await blockedAs({ origin: "[email protected]" });
+ const mcpSecond = await blockedAs({ origin: "[email protected]" });
+ const cli = await blockedAs({ integration: "cli" });
+
+ for (const blocked of [mcpFirst, mcpSecond, cli]) {
+ expect(blocked.statusCode).toBe(429);
+ expect(blocked.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);
+ expect(blocked.body.error).toContain(blocked.body.signup_url);
+ // A /k link shows nothing about the caller or the surface.
+ if (String(blocked.body.signup_url).includes("/k/")) {
+ expect(blocked.body.signup_url).not.toContain("utm_");
+ }
+ expect(blocked.body.signup_url).not.toContain(ip);
+ }
+ expect(mcpSecond.body.signup_url).toBe(mcpFirst.body.signup_url);
+
+ if (SIGNUP_LINK_KEYS_SET) {
+ expect(cli.body.signup_url).not.toBe(mcpFirst.body.signup_url);
+ expect(signupLinkPrompt(mcpFirst.body.signup_url)).toEqual({
+ surface: "mcp",
+ reason: "limit",
+ });
+ expect(signupLinkPrompt(cli.body.signup_url)).toEqual({
+ surface: "cli",
+ reason: "limit",
+ });
+ }
+ });
+
it("enforces the daily credit cap with the credit signup message (429)", async () => {
// Materialize the loopback IP, then seed its credit counter to the cap.
await request(TEST_API_URL)
@@ -189,7 +259,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");
});
@@ -218,7 +288,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain("Authorization: Bearer YOUR_API_KEY");
});
@@ -261,7 +331,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.reason).toBe("credits");
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -306,7 +376,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.reason).toBe("credits");
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -348,7 +418,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -478,7 +548,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -517,7 +587,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -568,7 +638,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
.send({ origin: "mcp" });
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -691,7 +761,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
expect(blocked.statusCode).toBe(429);
expect(blocked.body.error).toContain("keyless free tier rate limit");
- expect(blocked.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(blocked.body.error).toMatch(KEYLESS_SIGNUP_URL);
expect(blocked.body.error).toContain(
"Authorization: Bearer YOUR_API_KEY",
);
@@ -811,7 +881,15 @@ describeIf(SPUR_ENABLED)("Keyless free tier β€” Spur IP reputation", () => {
expect(response.statusCode).toBe(403);
expect(response.body.success).toBe(false);
expect(response.body.error).toContain("suspicious");
- expect(response.body.error).toContain(KEYLESS_SIGNUP_URL);
+ expect(response.body.error).toMatch(KEYLESS_SIGNUP_URL);
+ expect(response.body.signup_url).toMatch(KEYLESS_SIGNUP_URL_EXACT);
+ if (SIGNUP_LINK_KEYS_SET) {
+ // Relayed with the proxy secret, so the prompt reached the user via MCP.
+ expect(signupLinkPrompt(response.body.signup_url)).toEqual({
+ surface: "mcp",
+ reason: "suspicious_ip",
+ });
+ }
// Out of the keyless path β†’ emit the OAuth-discovery header.
expect(response.headers["www-authenticate"]).toContain(
"resource_metadata",
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 1e96563eb..6d1376b55 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -110,6 +110,22 @@ const configSchema = z.object({
// existing privacy-controlled conversion pipeline. Never use the proxy or
// credential secrets here: this value is only an analytics pseudonymizer.
KEYLESS_CONVERSION_HMAC_SECRET: emptyStringAsUndefined(z.string().min(32)),
+ // AES-128 keys for keyless signup link tokens (firecrawl.dev/k/<token>):
+ // comma-separated base64, 16 bytes each. The first encrypts; every key is
+ // tried to decrypt, so keep a rotated-out key listed while its links live.
+ // Must match firecrawl-web's KEYLESS_SIGNUP_LINK_KEYS. Unset sends the
+ // regular signup link.
+ KEYLESS_SIGNUP_LINK_KEYS: emptyStringAsUndefined(
+ z
+ .string()
+ .refine(
+ value =>
+ value
+ .split(",")
+ .every(key => /^[A-Za-z0-9+/]{21}[AQgw]==$/.test(key.trim())),
+ "KEYLESS_SIGNUP_LINK_KEYS must be comma-separated base64 16-byte keys",
+ ),
+ ),
// Dedicated signer/verifier secret for short-lived MCP delegated credentials.
// Keep separate from KEYLESS_PROXY_SECRET because delegated credentials can
// authorize billed requests for a managed OAuth connection.
diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.ts
index 647a43b84..775e93ca7 100644
--- a/apps/api/src/controllers/__tests__/auth.test.ts
+++ b/apps/api/src/controllers/__tests__/auth.test.ts
@@ -19,6 +19,7 @@ import {
isKeylessConfigured,
keylessConversionCohort,
} from "../../lib/keyless";
+import { decryptKeylessSignupToken } from "../../lib/keyless-signup-link";
import { logger } from "../../lib/logger";
import { isKeylessIpSuspicious } from "../../lib/spur";
import { db } from "../../db/connection";
@@ -108,6 +109,7 @@ describe("authenticateUser", () => {
const originalIntrospectSecret = config.OAUTH_INTROSPECT_SECRET;
const originalPreviewToken = config.PREVIEW_TOKEN;
const originalAgentInteropSecret = config.AGENT_INTEROP_SECRET;
+ const originalKeylessSignupLinkKeys = config.KEYLESS_SIGNUP_LINK_KEYS;
beforeEach(() => {
vi.mocked(isKeylessConfigured).mockReturnValue(false);
@@ -127,6 +129,7 @@ describe("authenticateUser", () => {
config.OAUTH_INTROSPECT_SECRET = originalIntrospectSecret;
config.PREVIEW_TOKEN = originalPreviewToken;
config.AGENT_INTEROP_SECRET = originalAgentInteropSecret;
+ config.KEYLESS_SIGNUP_LINK_KEYS = originalKeylessSignupLinkKeys;
vi.unstubAllGlobals();
vi.clearAllMocks();
});
@@ -214,8 +217,17 @@ describe("authenticateUser", () => {
);
});
- it("links every keyless signup prompt to the keyless-tagged signup URL", async () => {
+ // The prompt a /k link carries, or null for any other link.
+ const decodedLink = (url: unknown) => {
+ const match = /^https:\/\/firecrawl\.dev\/k\/([0-9a-z]{12})$/.exec(
+ String(url),
+ );
+ return match ? decryptKeylessSignupToken(match[1]) : null;
+ };
+
+ it("links every keyless prompt to the caller's own token, tagged with the prompt reason", async () => {
config.USE_DB_AUTHENTICATION = true;
+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";
vi.mocked(isKeylessConfigured).mockReturnValue(true);
vi.mocked(consumeKeylessRequest).mockResolvedValue({
ok: false,
@@ -223,13 +235,11 @@ describe("authenticateUser", () => {
requestsUsed: 1,
creditsUsed: 100,
});
- vi.spyOn(logger, "warn").mockImplementation(() => logger);
+ const warn = vi.spyOn(logger, "warn").mockImplementation(() => logger);
const keylessRequest = () => ({
headers: {},
- socket: { remoteAddress: "203.0.113.8" },
+ socket: { remoteAddress: "::ffff:203.0.113.8" },
});
- const taggedSignupUrl =
- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";
const limited = await authenticateUser(
keylessRequest(),
@@ -251,30 +261,164 @@ describe("authenticateUser", () => {
{ allowKeyless: true },
);
- // A period right after the URL would be copied into utm_medium.
- expect(limited).toEqual(
- expect.objectContaining({
- error: expect.not.stringContaining(`${taggedSignupUrl}.`),
- }),
- );
- for (const [auth, status] of [
- [limited, 429],
- [unsupported, 401],
- [suspicious, 403],
+ for (const [auth, status, reason] of [
+ [limited, 429, "limit"],
+ [unsupported, 401, "unsupported_endpoint"],
+ [suspicious, 403, "suspicious_ip"],
] as const) {
+ const signupUrl = (auth as { signupUrl?: string }).signupUrl;
+ expect(decodedLink(signupUrl)).toEqual({
+ ipv4: "203.0.113.8",
+ surface: "api",
+ reason,
+ });
expect(auth).toEqual(
expect.objectContaining({
success: false,
status,
- // Nothing follows the URL's query, so a dropped utm_content stays out.
- error: expect.stringMatching(
- /https:\/\/www\.firecrawl\.dev\/signin\?utm_source=keyless&utm_medium=api(?![&\w])/,
+ // The URL is followed by whitespace, never punctuation.
+ error: expect.stringContaining(
+ `${signupUrl}${status === 429 ? "\n" : " "}`,
),
}),
);
+ // Nothing about the surface or the identity is visible in the link.
+ expect(signupUrl).not.toContain("utm_");
+ expect((auth as { error: string }).error).not.toContain("203.0.113.8");
+ }
+ for (const [message, auth] of [
+ ["Keyless request blocked", limited],
+ ["Keyless request blocked: suspicious IP", suspicious],
+ ] as const) {
+ expect(warn).toHaveBeenCalledWith(
+ message,
+ expect.objectContaining({
+ signupRef: (auth as { signupUrl: string }).signupUrl.split("/k/")[1],
+ }),
+ );
}
});
+ it.each([
+ [{ integration: "cli" }, {}, "cli"],
+ [{ origin: "[email protected]" }, {}, "mcp"],
+ [{}, { "x-origin": "cli" }, "cli"],
+ [{ origin: "[email protected]" }, {}, "api"],
+ ] as const)(
+ "tags the keyless limit link for body %j headers %j with the %s surface",
+ async (body, headers, surface) => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";
+ vi.mocked(isKeylessConfigured).mockReturnValue(true);
+ vi.mocked(consumeKeylessRequest).mockResolvedValue({
+ ok: false,
+ reason: "requests",
+ requestsUsed: 11,
+ creditsUsed: 0,
+ });
+ vi.spyOn(logger, "warn").mockImplementation(() => logger);
+
+ const auth = await authenticateUser(
+ { body, headers, socket: { remoteAddress: "203.0.113.8" } },
+ {},
+ RateLimiterMode.Scrape,
+ { allowKeyless: true },
+ );
+
+ expect(decodedLink((auth as { signupUrl?: string }).signupUrl)).toEqual({
+ ipv4: "203.0.113.8",
+ surface,
+ reason: "limit",
+ });
+ },
+ );
+
+ it("keys the hosted MCP's link on the forwarded end-user IP and the mcp surface", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.KEYLESS_PROXY_SECRET = "proxy-secret";
+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";
+ vi.mocked(isKeylessConfigured).mockReturnValue(true);
+ vi.mocked(consumeKeylessRequest).mockResolvedValue({
+ ok: false,
+ reason: "credits",
+ requestsUsed: 1,
+ creditsUsed: 100,
+ });
+ vi.spyOn(logger, "warn").mockImplementation(() => logger);
+
+ const auth = await authenticateUser(
+ {
+ body: { origin: "api" },
+ headers: {
+ "x-firecrawl-keyless-secret": "proxy-secret",
+ "x-firecrawl-keyless-ip": "198.51.100.7",
+ },
+ socket: { remoteAddress: "10.0.0.1" },
+ },
+ {},
+ RateLimiterMode.Search,
+ { allowKeyless: true },
+ );
+
+ expect(decodedLink((auth as { signupUrl?: string }).signupUrl)).toEqual({
+ ipv4: "198.51.100.7",
+ surface: "mcp",
+ reason: "limit",
+ });
+ });
+
+ it("falls back to the regular signup link and still returns the 429 when no key is configured", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.KEYLESS_SIGNUP_LINK_KEYS = undefined;
+ vi.mocked(isKeylessConfigured).mockReturnValue(true);
+ vi.mocked(consumeKeylessRequest).mockResolvedValue({
+ ok: false,
+ reason: "credits",
+ requestsUsed: 1,
+ creditsUsed: 100,
+ });
+ vi.spyOn(logger, "warn").mockImplementation(() => logger);
+
+ const auth = await authenticateUser(
+ { headers: {}, socket: { remoteAddress: "203.0.113.8" } },
+ {},
+ RateLimiterMode.Scrape,
+ { allowKeyless: true },
+ );
+
+ expect(auth).toEqual(
+ expect.objectContaining({
+ status: 429,
+ signupUrl:
+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
+ error: expect.stringContaining(
+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api\n",
+ ),
+ }),
+ );
+ });
+
+ it("gives a non-IPv4 caller on an unsupported endpoint the regular signup link", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";
+ vi.mocked(isKeylessConfigured).mockReturnValue(true);
+
+ const auth = await authenticateUser(
+ { headers: {}, socket: { remoteAddress: "2001:db8::1" } },
+ {},
+ RateLimiterMode.Crawl,
+ { allowKeyless: false },
+ );
+
+ expect(auth).toEqual(
+ expect.objectContaining({
+ status: 401,
+ signupUrl:
+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
+ }),
+ );
+ });
+
it("writes normal API-key ACUC entries to the general-purpose cache", async () => {
config.USE_DB_AUTHENTICATION = true;
vi.mocked(getValue).mockResolvedValue(null);
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index 61591cfc4..f9be80525 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -13,15 +13,16 @@ import {
} from "../services/rate-limiter";
import { isTrustedAgentInteropRequest } from "../lib/agent-interop";
import {
- KEYLESS_FREE_TIER_LIMIT_MESSAGE,
- KEYLESS_SIGNUP_URL,
consumeKeylessRequest,
isKeylessConfigured,
keylessExhaustionTelemetry,
isKeylessIpEligible,
+ keylessLimitPrompt,
+ keylessSignupUrlForIp,
keylessTeamId,
normalizeKeylessIpv4,
} from "../lib/keyless";
+import { keylessSignupSurface } from "../lib/keyless-signup-link";
import { isKeylessIpSuspicious } from "../lib/spur";
import { keylessAuthTotal } from "../lib/keyless-metrics";
import { checkIpRestriction } from "../lib/ip-restriction";
@@ -464,12 +465,38 @@ export async function clearACUCTeam(team_id: string): Promise<void> {
await deleteKey(`acuc_team_${team_id}`);
}
-const KEYLESS_ENDPOINT_NOT_AVAILABLE_MESSAGE = `This endpoint is not supported by the keyless free tier. Sign up for a free API key at ${KEYLESS_SIGNUP_URL} for more endpoints, more usage, and higher rate limits.
+// Both prompts end the sentence after the URL with a space, so a copied link
+// never picks up the period.
+function keylessEndpointNotAvailableMessage(signupUrl: string): string {
+ return `This endpoint is not supported by the keyless free tier. Sign up for a free API key at ${signupUrl} for more endpoints, more usage, and higher rate limits.
Then authenticate with:
Authorization: Bearer YOUR_API_KEY`;
+}
-const KEYLESS_SUSPICIOUS_IP_MESSAGE = `Unfortunately, your IP address looks suspicious, so Firecrawl can't be used without an API key from here. Sign up for a free API key at ${KEYLESS_SIGNUP_URL} for 1000 credits and higher rate limits for free. (If you're an agent, you can also use https://firecrawl.dev/auth.md)`;
+function keylessSuspiciousIpMessage(signupUrl: string): string {
+ return `Unfortunately, your IP address looks suspicious, so Firecrawl can't be used without an API key from here. Sign up for a free API key at ${signupUrl} for 1000 credits and higher rate limits for free. (If you're an agent, you can also use https://firecrawl.dev/auth.md)`;
+}
+
+/**
+ * The real client IP for keyless. 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.
+ */
+function keylessClientIp(req): string {
+ 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();
+ }
+ }
+ return ip;
+}
/**
* Keyless free tier: official MCP/CLI/SDK clients can call scrape, search, and
@@ -497,10 +524,16 @@ async function handleKeylessAuth(
// 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) {
+ const { url } = keylessSignupUrlForIp(
+ keylessClientIp(req),
+ keylessSignupSurface(req),
+ "unsupported_endpoint",
+ );
return {
success: false,
- error: KEYLESS_ENDPOINT_NOT_AVAILABLE_MESSAGE,
+ error: keylessEndpointNotAvailableMessage(url),
status: 401,
+ signupUrl: url,
};
}
@@ -508,22 +541,11 @@ async function handleKeylessAuth(
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.
+ // integration are still recorded below for abuse monitoring, and pick the
+ // surface of the signup link.
+ const signupSurface = keylessSignupSurface(req);
- // 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();
- }
- }
+ let ip = keylessClientIp(req);
// 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
@@ -540,6 +562,11 @@ async function handleKeylessAuth(
// runs before consuming quota so a flagged IP doesn't burn a request slot.
if (await isKeylessIpSuspicious(ip)) {
keylessAuthTotal.inc({ mode, outcome: "suspicious" });
+ const { url, signupRef } = keylessSignupUrlForIp(
+ ip,
+ signupSurface,
+ "suspicious_ip",
+ );
logger.warn("Keyless request blocked: suspicious IP", {
canonicalLog: "keyless/consume",
ip,
@@ -547,13 +574,15 @@ async function handleKeylessAuth(
integration: req.body?.integration,
blocked: true,
reason: "suspicious",
+ ...(signupRef ? { signupRef } : {}),
});
return {
success: false,
- error: KEYLESS_SUSPICIOUS_IP_MESSAGE,
+ error: keylessSuspiciousIpMessage(url),
status: 403,
// Tell agents where to find the key/signup flow they now need.
agentAuthDiscovery: true,
+ signupUrl: url,
};
}
@@ -599,18 +628,21 @@ async function handleKeylessAuth(
if (!result.ok) {
keylessAuthTotal.inc({ mode, outcome: result.reason ?? "error" });
+ const prompt = keylessLimitPrompt(ip, signupSurface);
logger.warn("Keyless request blocked", {
...baseLog,
blocked: true,
event: "keyless_exhausted",
reason: result.reason,
retryAfterSeconds: result.retryAfterSeconds,
+ ...(prompt.signupRef ? { signupRef: prompt.signupRef } : {}),
...keylessExhaustionTelemetry(ip),
});
return {
success: false,
- error: KEYLESS_FREE_TIER_LIMIT_MESSAGE,
+ error: prompt.error,
status: 429,
+ signupUrl: prompt.signup_url,
// Direct API callers receive discovery metadata; MCP maps this in-band.
agentAuthDiscovery: true,
keylessReason: result.reason,
diff --git a/apps/api/src/controllers/v1/scrape.ts b/apps/api/src/controllers/v1/scrape.ts
index 8e4d30d77..fdbb51132 100644
--- a/apps/api/src/controllers/v1/scrape.ts
+++ b/apps/api/src/controllers/v1/scrape.ts
@@ -225,7 +225,7 @@ async function scrapeControllerInner(
applyAgentAuthDiscoveryHeader(res);
return res
.status(429)
- .json(await keylessLimitBody(req.auth.team_id, "v1_scrape"));
+ .json(await keylessLimitBody(req.auth.team_id, "v1_scrape", req));
}
reservedKeylessCredits = projectedKeylessCredits;
}
diff --git a/apps/api/src/controllers/v1/search.ts b/apps/api/src/controllers/v1/search.ts
index ed079cd2c..88ba299d0 100644
--- a/apps/api/src/controllers/v1/search.ts
+++ b/apps/api/src/controllers/v1/search.ts
@@ -264,7 +264,7 @@ export async function searchController(
applyAgentAuthDiscoveryHeader(res);
return res
.status(429)
- .json(await keylessLimitBody(req.auth.team_id, "v1_search"));
+ .json(await keylessLimitBody(req.auth.team_id, "v1_search", req));
}
reservedKeylessCredits = projectedKeylessCredits;
}
diff --git a/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts b/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts
index fb4abcb1a..c08625173 100644
--- a/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/search-developer-ledger.test.ts
@@ -143,7 +143,12 @@ describe("developer category code_searches ledger", () => {
await searchController(req, res);
expect(res.status).toHaveBeenCalledWith(429);
- expect(mockKeylessLimitBody).toHaveBeenCalledWith(TEAM_ID, "v2_search");
+ // The request picks the utm_medium of the caller's signup link.
+ expect(mockKeylessLimitBody).toHaveBeenCalledWith(
+ TEAM_ID,
+ "v2_search",
+ req,
+ );
expect(res.json).toHaveBeenCalledWith({
success: false,
error: "keyless limit reached",
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.ts
index fbec5fad5..ee1fb71cd 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -5,6 +5,10 @@ import {
import { deleteBrowserProfile } from "../../lib/browser-sessions";
import { deleteHangarProfile } from "../../lib/hangar";
import { Response } from "express";
+import {
+ KEYLESS_FREE_TIER_LIMIT_MESSAGE,
+ keylessLimitPromptForTeam,
+} from "../../lib/keyless";
import { z } from "zod";
import { config } from "../../config";
import { RequestWithAuth } from "./types";
@@ -64,7 +68,25 @@ const browserExecuteRequestSchema = z.object({
origin: z.string().optional(),
});
-export function browserError(res: Response, error: unknown) {
+export function browserError(
+ res: Response,
+ error: unknown,
+ req?: RequestWithAuth<any, any, any>,
+) {
+ // Keyless browser budget exhaustion: give the caller its own signup link.
+ if (
+ req &&
+ error instanceof HangarError &&
+ error.status === 429 &&
+ error.message === KEYLESS_FREE_TIER_LIMIT_MESSAGE
+ ) {
+ const prompt = keylessLimitPromptForTeam(req.auth.team_id, req);
+ return res.status(429).json({
+ success: false,
+ error: prompt.error,
+ signup_url: prompt.signup_url,
+ });
+ }
return res.status(error instanceof HangarError ? error.status : 502).json({
success: false,
error:
@@ -107,7 +129,7 @@ export async function browserCreateController(
expiresAt,
});
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -165,7 +187,7 @@ export async function browserExecuteController(
: {}),
});
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -203,7 +225,7 @@ export async function browserProfileDeleteController(
"A session is currently saving to this profile. Stop that session, then delete the profile.",
});
}
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -216,7 +238,7 @@ export async function browserDeleteController(
try {
return res.json(await stopBrowserSession(session));
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -238,7 +260,7 @@ export async function browserStatusController(
error: browser.error ?? undefined,
});
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -290,7 +312,7 @@ export async function browserReplayController(
pageCount: 1,
});
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -310,6 +332,6 @@ export async function browserReplayPageController(
res.setHeader("Cache-Control", "no-store");
return res.status(200).send(recording.playlist);
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
diff --git a/apps/api/src/controllers/v2/keyless-eligibility.ts b/apps/api/src/controllers/v2/keyless-eligibility.ts
index b9eee6cfb..49f5f7f0b 100644
--- a/apps/api/src/controllers/v2/keyless-eligibility.ts
+++ b/apps/api/src/controllers/v2/keyless-eligibility.ts
@@ -1,6 +1,14 @@
import { Request, Response } from "express";
import { config } from "../../config";
-import { checkKeylessEligibility } from "../../lib/keyless";
+import {
+ checkKeylessEligibility,
+ keylessSignupUrlForIp,
+} from "../../lib/keyless";
+import {
+ type KeylessPromptReason,
+ keylessFallbackSignupUrl,
+ keylessSignupSurface,
+} from "../../lib/keyless-signup-link";
/**
* Internal endpoint for trusted proxies (the hosted MCP) to check, before a
@@ -8,6 +16,11 @@ import { checkKeylessEligibility } from "../../lib/keyless";
* 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.
*/
export async function keylessEligibilityController(
req: Request,
@@ -24,5 +37,23 @@ export async function keylessEligibilityController(
(typeof ipHeader === "string" ? ipHeader.trim() : "") || req.ip || "";
const result = await checkKeylessEligibility(ip);
- res.status(200).json(result);
+ 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.
+ const signupUrl = reason
+ ? keylessSignupUrlForIp(ip, surface, reason).url
+ : keylessFallbackSignupUrl(surface);
+ res.status(200).json({ ...result, signupUrl });
}
diff --git a/apps/api/src/controllers/v2/parse.ts b/apps/api/src/controllers/v2/parse.ts
index c70846f03..9d0b563f7 100644
--- a/apps/api/src/controllers/v2/parse.ts
+++ b/apps/api/src/controllers/v2/parse.ts
@@ -414,7 +414,7 @@ export async function parseController(
applyAgentAuthDiscoveryHeader(res);
return res
.status(429)
- .json(await keylessLimitBody(req.auth.team_id, "v2_parse"));
+ .json(await keylessLimitBody(req.auth.team_id, "v2_parse", req));
}
reservedKeylessCredits = projectedKeylessCredits;
}
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index ffd67d8fb..be49a1e34 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -258,10 +258,9 @@ export async function scrapeInteractController(
profile,
);
if (created.error === true) {
- if (
- created.status === 429 &&
- created.body.error === KEYLESS_FREE_TIER_LIMIT_MESSAGE
- ) {
+ // A keyless limit body carries the caller's own link, so match on it
+ // rather than on the message text.
+ if (created.status === 429 && "signup_url" in created.body) {
applyAgentAuthDiscoveryHeader(res);
}
return res.status(created.status).json(created.body);
@@ -331,7 +330,7 @@ export async function scrapeInteractController(
try {
await reserveBrowserPromptCredits(req, session);
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
try {
@@ -445,7 +444,7 @@ export async function scrapeStopInteractiveBrowserController(
try {
return res.json(await stopBrowserSession(session));
} catch (error) {
- return browserError(res, error);
+ return browserError(res, error, req);
}
}
@@ -487,7 +486,7 @@ async function createSessionForScrape(
: "Failed to create browser session.";
const body =
message === KEYLESS_FREE_TIER_LIMIT_MESSAGE
- ? await keylessLimitBody(req.auth.team_id, "v2_browser")
+ ? await keylessLimitBody(req.auth.team_id, "v2_browser", req)
: { success: false as const, error: message };
return { error: true as const, status, body };
}
diff --git a/apps/api/src/controllers/v2/scrape.ts b/apps/api/src/controllers/v2/scrape.ts
index 3884b47f7..03cd81884 100644
--- a/apps/api/src/controllers/v2/scrape.ts
+++ b/apps/api/src/controllers/v2/scrape.ts
@@ -268,7 +268,7 @@ export async function scrapeController(
applyAgentAuthDiscoveryHeader(res);
return res
.status(429)
- .json(await keylessLimitBody(req.auth.team_id, "v2_scrape"));
+ .json(await keylessLimitBody(req.auth.team_id, "v2_scrape", req));
}
reservedKeylessCredits = projectedKeylessCredits;
}
diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.ts
index 656d6e6c3..22e385d5e 100644
--- a/apps/api/src/controllers/v2/search.ts
+++ b/apps/api/src/controllers/v2/search.ts
@@ -385,7 +385,7 @@ async function searchControllerInner(
applyAgentAuthDiscoveryHeader(res);
return res
.status(429)
- .json(await keylessLimitBody(req.auth.team_id, "v2_search"));
+ .json(await keylessLimitBody(req.auth.team_id, "v2_search", req));
}
reservedKeylessCredits = projectedKeylessCredits;
}
diff --git a/apps/api/src/lib/keyless-signup-link.test.ts b/apps/api/src/lib/keyless-signup-link.test.ts
new file mode 100644
index 000000000..24a4dbfbc
--- /dev/null
+++ b/apps/api/src/lib/keyless-signup-link.test.ts
@@ -0,0 +1,254 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { config } from "../config";
+import { logger } from "./logger";
+import {
+ type KeylessPromptReason,
+ type KeylessSignupSurface,
+ decryptKeylessSignupToken,
+ encryptKeylessSignupToken,
+ ff1Decrypt,
+ ff1Encrypt,
+ keylessFallbackSignupUrl,
+ keylessSignupLink,
+ keylessSignupSurface,
+} from "./keyless-signup-link";
+
+// Shared with firecrawl-web lib/keyless-signup-link.test.ts: both repos must
+// produce and accept exactly this token for this key and payload.
+const CROSS_REPO_KEY = "AAECAwQFBgcICQoLDA0ODw==";
+const CROSS_REPO_PAYLOAD = {
+ ipv4: "203.0.113.8",
+ surface: "mcp",
+ reason: "limit",
+} as const;
+const CROSS_REPO_TOKEN = "hrxch5c20tcs";
+
+const KEY = Buffer.from(CROSS_REPO_KEY, "base64");
+const OTHER_KEY = Buffer.alloc(16, 7);
+const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+
+describe("FF1 (NIST SP 800-38G AES-128 samples)", () => {
+ const key = Buffer.from("2B7E151628AED2A6ABF7158809CF4F3C", "hex");
+ const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+ const toNumerals = (s: string) => [...s].map(c => alphabet.indexOf(c));
+ const fromNumerals = (n: number[]) => n.map(d => alphabet[d]).join("");
+
+ it.each([
+ ["sample 1", 10, "", "0123456789", "2433477484"],
+ ["sample 2", 10, "39383736353433323130", "0123456789", "6124200773"],
+ [
+ "sample 3",
+ 36,
+ "3737373770717273373737",
+ "0123456789abcdefghi",
+ "a9tv40mll9kdu509eum",
+ ],
+ ] as const)("%s", (_name, radix, tweakHex, plaintext, ciphertext) => {
+ const tweak = Buffer.from(tweakHex, "hex");
+ expect(
+ fromNumerals(ff1Encrypt(key, tweak, radix, toNumerals(plaintext))),
+ ).toBe(ciphertext);
+ expect(
+ fromNumerals(ff1Decrypt(key, tweak, radix, toNumerals(ciphertext))),
+ ).toBe(plaintext);
+ });
+});
+
+describe("keyless signup token", () => {
+ it("matches the cross-repo vector", () => {
+ expect(encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, KEY)).toBe(
+ CROSS_REPO_TOKEN,
+ );
+ expect(decryptKeylessSignupToken(CROSS_REPO_TOKEN, [KEY])).toEqual(
+ CROSS_REPO_PAYLOAD,
+ );
+ });
+
+ const surfaces: KeylessSignupSurface[] = ["api", "mcp", "cli"];
+ const reasons: KeylessPromptReason[] = [
+ "limit",
+ "account_only_tool",
+ "unsupported_endpoint",
+ "suspicious_ip",
+ ];
+ it.each(
+ surfaces.flatMap(surface => reasons.map(reason => [surface, reason])),
+ )("round-trips surface %s and reason %s", (surface, reason) => {
+ for (const ipv4 of ["0.0.0.0", "203.0.113.8", "255.255.255.255"]) {
+ const payload = {
+ ipv4,
+ surface: surface as KeylessSignupSurface,
+ reason: reason as KeylessPromptReason,
+ };
+ const token = encryptKeylessSignupToken(payload, KEY);
+ expect(token).toMatch(/^[0-9abcdefghjkmnpqrstvwxyz]{12}$/);
+ expect(decryptKeylessSignupToken(token!, [KEY])).toEqual(payload);
+ }
+ });
+
+ it("rejects every single-character change to a token", () => {
+ for (let i = 0; i < CROSS_REPO_TOKEN.length; i++) {
+ for (const c of TOKEN_ALPHABET) {
+ if (c === CROSS_REPO_TOKEN[i]) continue;
+ const tampered =
+ CROSS_REPO_TOKEN.slice(0, i) + c + CROSS_REPO_TOKEN.slice(i + 1);
+ expect(decryptKeylessSignupToken(tampered, [KEY])).toBeNull();
+ }
+ }
+ });
+
+ it.each([
+ "",
+ "hrxch5c20tc",
+ "hrxch5c20tcss",
+ "HRXCH5C20TCS",
+ "hrxch5c20tci",
+ "hrxch5c20tc/",
+ ])("rejects the malformed token %j", token => {
+ expect(decryptKeylessSignupToken(token, [KEY])).toBeNull();
+ });
+
+ it("decrypts a token from a rotated-out key while it stays listed", () => {
+ const oldToken = encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, OTHER_KEY)!;
+ expect(decryptKeylessSignupToken(oldToken, [KEY])).toBeNull();
+ expect(decryptKeylessSignupToken(oldToken, [KEY, OTHER_KEY])).toEqual(
+ CROSS_REPO_PAYLOAD,
+ );
+ expect(
+ decryptKeylessSignupToken(CROSS_REPO_TOKEN, [KEY, OTHER_KEY]),
+ ).toEqual(CROSS_REPO_PAYLOAD);
+ });
+
+ it("shows no IP bytes in the clear", () => {
+ // The unencrypted numerals of the IP, and the IP in hex or decimal.
+ const ipNumerals = (
+ (((203n << 24n) | (0n << 16n) | (113n << 8n) | 8n) << 28n) >>
+ 25n
+ )
+ .toString(32)
+ .padStart(7, "0");
+ const token = encryptKeylessSignupToken(CROSS_REPO_PAYLOAD, KEY)!;
+ expect(token.slice(0, 7)).not.toBe(ipNumerals);
+ for (const clear of ["cb007108", "203", "113", "cb", "71"]) {
+ expect(token).not.toContain(clear);
+ }
+ // Neighbouring IPs give unrelated tokens.
+ const next = encryptKeylessSignupToken(
+ { ...CROSS_REPO_PAYLOAD, ipv4: "203.0.113.9" },
+ KEY,
+ )!;
+ const shared = [...token].filter((c, i) => next[i] === c).length;
+ expect(shared).toBeLessThan(6);
+ });
+
+ it("gives no token for a non-IPv4 identity", () => {
+ for (const ipv4 of ["2001:db8::1", "::ffff:203.0.113.8", "unknown", ""]) {
+ expect(
+ encryptKeylessSignupToken({ ...CROSS_REPO_PAYLOAD, ipv4 }, KEY),
+ ).toBeUndefined();
+ }
+ });
+});
+
+describe("keylessSignupLink", () => {
+ const originalKeys = config.KEYLESS_SIGNUP_LINK_KEYS;
+ beforeEach(() => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = CROSS_REPO_KEY;
+ });
+ afterEach(() => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = originalKeys;
+ });
+
+ it("builds a clean /k/<token> link with no query string", () => {
+ expect(keylessSignupLink("203.0.113.8", "mcp", "limit")).toEqual({
+ url: `https://firecrawl.dev/k/${CROSS_REPO_TOKEN}`,
+ signupRef: CROSS_REPO_TOKEN,
+ });
+ });
+
+ it("encrypts with the first key and decrypts with any listed key", () => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = `${OTHER_KEY.toString("base64")}, ${CROSS_REPO_KEY}`;
+ const { signupRef } = keylessSignupLink("203.0.113.8", "mcp", "limit");
+ expect(signupRef).not.toBe(CROSS_REPO_TOKEN);
+ expect(decryptKeylessSignupToken(signupRef!, [OTHER_KEY])).toEqual(
+ CROSS_REPO_PAYLOAD,
+ );
+ expect(decryptKeylessSignupToken(CROSS_REPO_TOKEN)).toEqual(
+ CROSS_REPO_PAYLOAD,
+ );
+ });
+
+ it.each([undefined, "", "not-a-key", "AAECAwQFBgcICQoLDA0O"])(
+ "gives the regular signup link when the keys are %j",
+ keys => {
+ const warn = vi.spyOn(logger, "warn");
+ config.KEYLESS_SIGNUP_LINK_KEYS = keys;
+ expect(keylessSignupLink("203.0.113.8", "cli", "limit")).toEqual({
+ url: keylessFallbackSignupUrl("cli"),
+ });
+ // A missing key is a plain fallback, not a caught failure.
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ },
+ );
+
+ it.each([null, undefined, "", "2001:db8::1", "unknown"])(
+ "gives the regular signup link for the non-IPv4 identity %j",
+ ip => {
+ expect(keylessSignupLink(ip, "api", "unsupported_endpoint")).toEqual({
+ url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
+ });
+ },
+ );
+});
+
+describe("keylessSignupSurface", () => {
+ const originalSecret = config.KEYLESS_PROXY_SECRET;
+ afterEach(() => {
+ config.KEYLESS_PROXY_SECRET = originalSecret;
+ });
+
+ it.each([
+ [{ body: { integration: "cli" } }, "cli"],
+ [{ body: { origin: "cli" } }, "cli"],
+ [{ body: {}, headers: { "x-origin": "cli" } }, "cli"],
+ [{ body: { origin: "[email protected]" } }, "mcp"],
+ [{ body: {}, headers: { "x-origin": "[email protected]" } }, "mcp"],
+ [{ body: { origin: "api" } }, "api"],
+ [{ body: { origin: "[email protected]" } }, "api"],
+ [{ body: { origin: "website" } }, "api"],
+ [{ body: {} }, "api"],
+ [{}, "api"],
+ // Case-insensitive, like the warehouse classifier.
+ [{ body: { origin: "CLI" } }, "cli"],
+ [{ body: { integration: "Cli" } }, "cli"],
+ [{ body: { origin: "[email protected]" } }, "mcp"],
+ [{ body: {}, headers: { "x-origin": "[email protected]" } }, "mcp"],
+ // v1 schemas prefault a missing origin to "api"; the header still counts.
+ [{ body: { origin: "api" }, headers: { "x-origin": "cli" } }, "cli"],
+ [{ body: { origin: "api" }, headers: { "x-origin": "mcp-x@1" } }, "mcp"],
+ // An explicit non-default body origin still wins over the header.
+ [
+ { body: { origin: "[email protected]" }, headers: { "x-origin": "cli" } },
+ "api",
+ ],
+ ] as const)("classifies %j as %s", (req, surface) => {
+ expect(keylessSignupSurface(req as never)).toBe(surface);
+ });
+
+ it("treats a request relayed with the proxy secret as MCP", () => {
+ config.KEYLESS_PROXY_SECRET = "proxy-secret";
+ expect(
+ keylessSignupSurface({
+ body: { origin: "api" },
+ headers: { "x-firecrawl-keyless-secret": "proxy-secret" },
+ }),
+ ).toBe("mcp");
+ expect(
+ keylessSignupSurface({
+ body: { origin: "api" },
+ headers: { "x-firecrawl-keyless-secret": "wrong" },
+ }),
+ ).toBe("api");
+ });
+});
diff --git a/apps/api/src/lib/keyless-signup-link.ts b/apps/api/src/lib/keyless-signup-link.ts
new file mode 100644
index 000000000..1913c87fe
--- /dev/null
+++ b/apps/api/src/lib/keyless-signup-link.ts
@@ -0,0 +1,353 @@
+import { createCipheriv } from "node:crypto";
+import { isIPv4 } from "node:net";
+import { config } from "../config";
+import { logger } from "./logger";
+
+// Keyless prompts link to signup at https://firecrawl.dev/k/<token>. The token
+// is the prompt itself, encrypted: nothing is stored per identity, and the web
+// app decrypts it at signup to join the account to the keyless ledger.
+//
+// Token format. Keep identical to firecrawl-web lib/keyless-signup-link.ts.
+// Plaintext: a 60-bit integer, most significant bits first:
+// bits 59..28 keyless IPv4 address (a.b.c.d as a big-endian uint32)
+// bits 27..26 surface: 0 api, 1 mcp, 2 cli (3 reserved)
+// bits 25..23 prompt reason: 0 limit, 1 account_only_tool,
+// 2 unsupported_endpoint, 3 suspicious_ip (4..7 reserved)
+// bits 22..0 check: always zero
+// Written as 12 radix-32 numerals (5 bits each, most significant first) and
+// encrypted with NIST SP 800-38G FF1 over AES-128, radix 32, tweak the ASCII
+// bytes "fc-keyless-v1". The 12 output numerals are spelled in lowercase
+// Crockford base32 (0123456789abcdefghjkmnpqrstvwxyz).
+// A token is valid only if the 23 check bits decrypt to zero, so a forged or
+// mistyped token passes with odds of about 1 in 8.4 million per key.
+// Reserved surface or reason codes decode to null (a newer issuer).
+//
+// Keys: KEYLESS_SIGNUP_LINK_KEYS, comma-separated base64 16-byte AES keys. The
+// first encrypts; decryption tries each in turn, so a rotated-out key keeps its
+// links working while it stays in the list.
+const KEYLESS_SIGNUP_LINK_BASE = "https://firecrawl.dev/k";
+
+export type KeylessSignupSurface = "api" | "mcp" | "cli";
+
+export type KeylessPromptReason =
+ | "limit"
+ | "account_only_tool"
+ | "unsupported_endpoint"
+ | "suspicious_ip";
+
+// Index = code in the token. Append only.
+const SURFACE_CODES: readonly KeylessSignupSurface[] = ["api", "mcp", "cli"];
+const REASON_CODES: readonly KeylessPromptReason[] = [
+ "limit",
+ "account_only_tool",
+ "unsupported_endpoint",
+ "suspicious_ip",
+];
+
+const TOKEN_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+const TOKEN_LENGTH = 12;
+const TOKEN_PATTERN = /^[0-9abcdefghjkmnpqrstvwxyz]{12}$/;
+const TOKEN_TWEAK = Buffer.from("fc-keyless-v1", "ascii");
+const CHECK_BITS = 23n;
+const CHECK_MASK = (1n << CHECK_BITS) - 1n;
+
+/**
+ * The regular signup link, used whenever no token can be given (no key
+ * configured, or no IPv4 identity). It still tags the signup keyless with its
+ * surface through the UTMs the web app already reads, so only the per-identity
+ * join is lost, not the attribution.
+ */
+export function keylessFallbackSignupUrl(
+ surface: KeylessSignupSurface,
+): string {
+ return `https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=${surface}`;
+}
+
+// ---------------------------------------------------------------------------
+// FF1 (NIST SP 800-38G) with AES-128. Numeral strings are arrays of digits in
+// [0, radix), most significant first.
+
+function aesBlock(key: Buffer, block: Buffer): Buffer {
+ const cipher = createCipheriv("aes-128-ecb", key, null);
+ cipher.setAutoPadding(false);
+ return Buffer.concat([cipher.update(block), cipher.final()]);
+}
+
+// PRF of the spec: AES CBC-MAC with a zero IV over a whole number of blocks.
+function prf(key: Buffer, data: Buffer): Buffer {
+ const cipher = createCipheriv("aes-128-cbc", key, Buffer.alloc(16));
+ cipher.setAutoPadding(false);
+ const out = Buffer.concat([cipher.update(data), cipher.final()]);
+ return out.subarray(out.length - 16);
+}
+
+function numeralsToBigInt(numerals: number[], radix: number): bigint {
+ const r = BigInt(radix);
+ let x = 0n;
+ for (const digit of numerals) x = x * r + BigInt(digit);
+ return x;
+}
+
+function bigIntToNumerals(x: bigint, radix: number, length: number): number[] {
+ const r = BigInt(radix);
+ const out = new Array<number>(length);
+ for (let i = length - 1; i >= 0; i--) {
+ out[i] = Number(x % r);
+ x /= r;
+ }
+ return out;
+}
+
+function bigIntToBytes(x: bigint, length: number): Buffer {
+ const out = Buffer.alloc(length);
+ for (let i = length - 1; i >= 0; i--) {
+ out[i] = Number(x & 0xffn);
+ x >>= 8n;
+ }
+ return out;
+}
+
+function ff1(
+ key: Buffer,
+ tweak: Buffer,
+ radix: number,
+ input: number[],
+ encrypt: boolean,
+): number[] {
+ const n = input.length;
+ if (key.length !== 16) throw new Error("FF1 needs a 16-byte AES-128 key");
+ if (radix < 2 || radix > 65536 || n < 2) throw new Error("Bad FF1 domain");
+ if (input.some(d => !Number.isInteger(d) || d < 0 || d >= radix)) {
+ throw new Error("Numeral out of range");
+ }
+ const u = Math.floor(n / 2);
+ const v = n - u;
+ let A = input.slice(0, u);
+ let B = input.slice(u);
+ // b = ceil(ceil(v * log2(radix)) / 8), computed exactly.
+ const b = Math.ceil((BigInt(radix) ** BigInt(v) - 1n).toString(2).length / 8);
+ const d = 4 * Math.ceil(b / 4) + 4;
+ const t = tweak.length;
+ const P = Buffer.alloc(16);
+ P.set([1, 2, 1], 0);
+ P.writeUIntBE(radix, 3, 3);
+ P[6] = 10;
+ P[7] = u % 256;
+ P.writeUInt32BE(n, 8);
+ P.writeUInt32BE(t, 12);
+ const pad = (((-t - b - 1) % 16) + 16) % 16;
+ const extraBlocks = Math.ceil(d / 16) - 1;
+
+ for (let round = 0; round < 10; round++) {
+ const i = encrypt ? round : 9 - round;
+ const Q = Buffer.concat([
+ tweak,
+ Buffer.alloc(pad),
+ Buffer.from([i]),
+ bigIntToBytes(numeralsToBigInt(encrypt ? B : A, radix), b),
+ ]);
+ const R = prf(key, Buffer.concat([P, Q]));
+ const blocks = [R];
+ for (let j = 1; j <= extraBlocks; j++) {
+ const counter = bigIntToBytes(BigInt(j), 16);
+ blocks.push(aesBlock(key, Buffer.from(R.map((x, k) => x ^ counter[k]))));
+ }
+ const y = BigInt(
+ "0x" + Buffer.concat(blocks).subarray(0, d).toString("hex"),
+ );
+ const m = i % 2 === 0 ? u : v;
+ const modulus = BigInt(radix) ** BigInt(m);
+ if (encrypt) {
+ const c = (numeralsToBigInt(A, radix) + y) % modulus;
+ A = B;
+ B = bigIntToNumerals(c, radix, m);
+ } else {
+ const c =
+ (((numeralsToBigInt(B, radix) - y) % modulus) + modulus) % modulus;
+ B = A;
+ A = bigIntToNumerals(c, radix, m);
+ }
+ }
+ return [...A, ...B];
+}
+
+export function ff1Encrypt(
+ key: Buffer,
+ tweak: Buffer,
+ radix: number,
+ numerals: number[],
+): number[] {
+ return ff1(key, tweak, radix, numerals, true);
+}
+
+export function ff1Decrypt(
+ key: Buffer,
+ tweak: Buffer,
+ radix: number,
+ numerals: number[],
+): number[] {
+ return ff1(key, tweak, radix, numerals, false);
+}
+
+// ---------------------------------------------------------------------------
+// Token encode/decode.
+
+type KeylessSignupPayload = {
+ ipv4: string;
+ surface: KeylessSignupSurface | null;
+ reason: KeylessPromptReason | null;
+};
+
+// Canonical base64 of exactly 16 bytes.
+const KEY_PATTERN = /^[A-Za-z0-9+/]{21}[AQgw]==$/;
+let cachedKeys: { raw: string | undefined; keys: Buffer[] } | undefined;
+
+/** Parsed KEYLESS_SIGNUP_LINK_KEYS; malformed entries are skipped. */
+function signupLinkKeys(): Buffer[] {
+ const raw = config.KEYLESS_SIGNUP_LINK_KEYS;
+ if (cachedKeys && cachedKeys.raw === raw) return cachedKeys.keys;
+ const keys = (raw ?? "")
+ .split(",")
+ .map(entry => entry.trim())
+ .filter(entry => KEY_PATTERN.test(entry))
+ .map(entry => Buffer.from(entry, "base64"));
+ cachedKeys = { raw, keys };
+ return keys;
+}
+
+/** The 12-character token for a prompt, or undefined for a non-IPv4 identity. */
+export function encryptKeylessSignupToken(
+ payload: {
+ ipv4: string;
+ surface: KeylessSignupSurface;
+ reason: KeylessPromptReason;
+ },
+ key: Buffer,
+): string | undefined {
+ if (!isIPv4(payload.ipv4)) return undefined;
+ const ip = payload.ipv4
+ .split(".")
+ .reduce((acc, octet) => (acc << 8n) | BigInt(Number(octet)), 0n);
+ const plaintext =
+ (ip << 28n) |
+ (BigInt(SURFACE_CODES.indexOf(payload.surface)) << 26n) |
+ (BigInt(REASON_CODES.indexOf(payload.reason)) << CHECK_BITS);
+ return ff1Encrypt(
+ key,
+ TOKEN_TWEAK,
+ 32,
+ bigIntToNumerals(plaintext, 32, TOKEN_LENGTH),
+ )
+ .map(d => TOKEN_ALPHABET[d])
+ .join("");
+}
+
+/**
+ * The prompt a token carries, or null when it is malformed or no key yields
+ * zero check bits. Tries every configured key unless keys are given.
+ */
+export function decryptKeylessSignupToken(
+ token: string,
+ keys: Buffer[] = signupLinkKeys(),
+): KeylessSignupPayload | null {
+ if (!TOKEN_PATTERN.test(token)) return null;
+ const numerals = [...token].map(c => TOKEN_ALPHABET.indexOf(c));
+ for (const key of keys) {
+ const plaintext = numeralsToBigInt(
+ ff1Decrypt(key, TOKEN_TWEAK, 32, numerals),
+ 32,
+ );
+ if ((plaintext & CHECK_MASK) !== 0n) continue;
+ const ip = Number(plaintext >> 28n);
+ return {
+ ipv4: [24, 16, 8, 0].map(shift => (ip >>> shift) & 255).join("."),
+ surface: SURFACE_CODES[Number((plaintext >> 26n) & 3n)] ?? null,
+ reason: REASON_CODES[Number((plaintext >> CHECK_BITS) & 7n)] ?? null,
+ };
+ }
+ return null;
+}
+
+/**
+ * The caller's own signup link for a prompt: firecrawl.dev/k/<token> for an
+ * IPv4 identity when a key is configured, else the regular signup link. Pure
+ * CPU, no I/O, never throws. `signupRef` is the token, for logs.
+ */
+export function keylessSignupLink(
+ ipv4: string | null | undefined,
+ surface: KeylessSignupSurface,
+ reason: KeylessPromptReason,
+): { url: string; signupRef?: string } {
+ try {
+ const key = signupLinkKeys()[0];
+ const token =
+ ipv4 && key
+ ? encryptKeylessSignupToken({ ipv4, surface, reason }, key)
+ : undefined;
+ if (token) {
+ return { url: `${KEYLESS_SIGNUP_LINK_BASE}/${token}`, signupRef: token };
+ }
+ } catch (error) {
+ logger.warn("Keyless signup link encryption failed", {
+ module: "keyless-signup-link",
+ surface,
+ error,
+ });
+ }
+ return { url: keylessFallbackSignupUrl(surface) };
+}
+
+// ---------------------------------------------------------------------------
+// Surface classification.
+
+type RequestLike = {
+ body?: unknown;
+ headers?: Record<string, string | string[] | undefined>;
+};
+
+function lowerString(value: unknown): string | undefined {
+ return typeof value === "string" ? value.trim().toLowerCase() : undefined;
+}
+
+function firstHeader(req: RequestLike, name: string): string | undefined {
+ const value = req.headers?.[name];
+ if (Array.isArray(value)) return value[0];
+ return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Surface of a keyless prompt, from the same signals as the warehouse
+ * `usage_source`: CLI when origin or integration is `cli`, MCP when origin
+ * starts with `mcp` or the hosted MCP relayed the request with the proxy
+ * secret. Everything else, including requests with no origin, is `api`: the
+ * prompt reached the caller as a raw API response, which is what
+ * utm_medium=api meant before.
+ */
+export function keylessSignupSurface(req: RequestLike): KeylessSignupSurface {
+ const body =
+ req.body && typeof req.body === "object"
+ ? (req.body as Record<string, unknown>)
+ : {};
+ // v1 schemas prefault a missing body origin to "api", which would mask an
+ // x-origin header, so a bare "api" defers to the header. Classification is
+ // case-insensitive, like the warehouse's.
+ const bodyOrigin = lowerString(body.origin);
+ const headerOrigin = lowerString(firstHeader(req, "x-origin"));
+ const origin =
+ bodyOrigin && bodyOrigin !== "api"
+ ? bodyOrigin
+ : (headerOrigin ?? bodyOrigin);
+ const integration =
+ lowerString(body.integration) ??
+ lowerString(firstHeader(req, "x-integration"));
+ if (
+ config.KEYLESS_PROXY_SECRET &&
+ firstHeader(req, "x-firecrawl-keyless-secret") ===
+ config.KEYLESS_PROXY_SECRET
+ ) {
+ return "mcp";
+ }
+ if (integration === "cli" || origin === "cli") return "cli";
+ if (origin?.startsWith("mcp")) return "mcp";
+ return "api";
+}
diff --git a/apps/api/src/lib/keyless.signup-prompt.test.ts b/apps/api/src/lib/keyless.signup-prompt.test.ts
new file mode 100644
index 000000000..a373e80bd
--- /dev/null
+++ b/apps/api/src/lib/keyless.signup-prompt.test.ts
@@ -0,0 +1,317 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Importing the browser controller pulls in modules that open Redis clients.
+vi.mock("ioredis", () => ({
+ default: class {
+ on() {
+ return this;
+ }
+ },
+}));
+vi.mock("../services/rate-limiter", () => ({
+ redisRateLimitClient: { ttl: vi.fn().mockResolvedValue(-1), on: vi.fn() },
+}));
+vi.mock("./keyless", async importOriginal => {
+ const actual = await importOriginal<typeof import("./keyless")>();
+ return { ...actual, checkKeylessEligibility: vi.fn() };
+});
+
+import { config } from "../config";
+import { keylessEligibilityController } from "../controllers/v2/keyless-eligibility";
+import { browserError } from "../controllers/v2/browser";
+import { HangarError } from "./hangar";
+import {
+ KEYLESS_FREE_TIER_LIMIT_MESSAGE,
+ checkKeylessEligibility,
+ keylessLimitBody,
+ keylessSignupUrlForIp,
+ keylessTeamId,
+ keylessTeamUuid,
+} from "./keyless";
+import { decryptKeylessSignupToken } from "./keyless-signup-link";
+import { logger } from "./logger";
+
+const TEST_KEY = "AAECAwQFBgcICQoLDA0ODw==";
+const IP = "203.0.113.8";
+
+/** The prompt a /k link carries, or null for any other link. */
+function decoded(url: unknown) {
+ const match = /^https:\/\/firecrawl\.dev\/k\/([0-9a-z]{12})$/.exec(
+ String(url),
+ );
+ return match ? decryptKeylessSignupToken(match[1]) : null;
+}
+
+function fakeRes() {
+ const res: any = {};
+ res.status = vi.fn(() => res);
+ res.json = vi.fn(() => res);
+ return res;
+}
+
+const originalKeys = config.KEYLESS_SIGNUP_LINK_KEYS;
+beforeEach(() => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = TEST_KEY;
+ vi.spyOn(logger, "warn").mockImplementation(() => logger);
+});
+
+afterEach(() => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = originalKeys;
+ vi.clearAllMocks();
+ vi.restoreAllMocks();
+});
+
+describe("keylessTeamUuid", () => {
+ it("matches the cross-repo vector in firecrawl-web lib/keyless-signup-link.test.ts", () => {
+ expect(keylessTeamUuid(keylessTeamId(IP))).toBe(
+ "abd15a03-d147-557e-801b-005da8c69bbf",
+ );
+ });
+});
+
+describe("keyless limit prompt", () => {
+ it("keeps the internal marker message on the regular signup link", () => {
+ expect(KEYLESS_FREE_TIER_LIMIT_MESSAGE).toContain(
+ "create a free API key at https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api\n",
+ );
+ });
+
+ it("puts the caller's own link in the credit-limit body and log", async () => {
+ const body = await keylessLimitBody(
+ "preview_keyless_203.0.113.8",
+ "v2_search",
+ { body: { integration: "cli" } },
+ );
+
+ expect(decoded(body.signup_url)).toEqual({
+ ipv4: IP,
+ surface: "cli",
+ reason: "limit",
+ });
+ expect(body).toMatchObject({ success: false, reason: "credits" });
+ expect(body.error).toContain(`${body.signup_url}\n`);
+ expect(logger.warn).toHaveBeenCalledWith(
+ "Keyless request blocked",
+ expect.objectContaining({
+ signupRef: body.signup_url.split("/k/")[1],
+ }),
+ );
+ });
+
+ it("uses the api surface when no request is given", async () => {
+ const body = await keylessLimitBody(
+ "preview_keyless_203.0.113.8",
+ "v2_scrape",
+ );
+ expect(decoded(body.signup_url)?.surface).toBe("api");
+ });
+
+ it("gives the regular signup link when no key is configured", async () => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = undefined;
+ const body = await keylessLimitBody(
+ "preview_keyless_203.0.113.8",
+ "v2_scrape",
+ { body: { origin: "mcp-cursor@1" } },
+ );
+ expect(body.signup_url).toBe(
+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp",
+ );
+ expect(body.error).toContain(`${body.signup_url}\n`);
+ });
+
+ it("keys IPv4-mapped IPv6 on the IPv4 identity and gives other IPs the regular link", () => {
+ expect(
+ decoded(keylessSignupUrlForIp("::ffff:203.0.113.8", "mcp", "limit").url),
+ ).toEqual({ ipv4: IP, surface: "mcp", reason: "limit" });
+ expect(keylessSignupUrlForIp("2001:db8::1", "mcp", "limit")).toEqual({
+ url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp",
+ });
+ expect(keylessSignupUrlForIp("unknown", "api", "limit")).toEqual({
+ url: "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api",
+ });
+ });
+});
+
+describe("browserError", () => {
+ it("replaces the keyless browser limit text with the caller's own link", () => {
+ const res = fakeRes();
+ browserError(res, new HangarError(429, KEYLESS_FREE_TIER_LIMIT_MESSAGE), {
+ auth: { team_id: "preview_keyless_203.0.113.8" },
+ body: { origin: "cli" },
+ headers: {},
+ } as any);
+
+ expect(res.status).toHaveBeenCalledWith(429);
+ const body = res.json.mock.calls[0][0];
+ expect(decoded(body.signup_url)).toEqual({
+ ipv4: IP,
+ surface: "cli",
+ reason: "limit",
+ });
+ expect(body).toEqual({
+ success: false,
+ error: expect.stringContaining(`${body.signup_url}\n`),
+ signup_url: body.signup_url,
+ });
+ });
+
+ it("leaves other browser errors unchanged", () => {
+ const res = fakeRes();
+ browserError(res, new HangarError(409, "Session closed."), {
+ auth: { team_id: "preview_keyless_203.0.113.8" },
+ } as any);
+
+ expect(res.status).toHaveBeenCalledWith(409);
+ expect(res.json).toHaveBeenCalledWith({
+ success: false,
+ error: "Session closed.",
+ });
+ });
+});
+
+describe("keyless eligibility signup link", () => {
+ const originalSecret = config.KEYLESS_PROXY_SECRET;
+ beforeEach(() => {
+ config.KEYLESS_PROXY_SECRET = "proxy-secret";
+ });
+ afterEach(() => {
+ config.KEYLESS_PROXY_SECRET = originalSecret;
+ });
+
+ const eligibilityRequest = (query: Record<string, string> = {}, ip = IP) =>
+ ({
+ headers: {
+ "x-firecrawl-keyless-secret": "proxy-secret",
+ "x-firecrawl-keyless-ip": ip,
+ },
+ query,
+ }) as any;
+
+ const MCP_FALLBACK =
+ "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp";
+
+ it.each([
+ ["requests", "limit"],
+ ["credits", "limit"],
+ ["suspicious", "suspicious_ip"],
+ ] as const)(
+ "links an identity refused for %s to its own mcp link tagged %s",
+ async (refusal, reason) => {
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({
+ eligible: false,
+ reason: refusal,
+ });
+ const res = fakeRes();
+
+ await keylessEligibilityController(eligibilityRequest(), res);
+
+ // Refusals stay 200 so the MCP serves structured recovery, not a challenge.
+ expect(res.status).toHaveBeenCalledWith(200);
+ const body = res.json.mock.calls[0][0];
+ expect(body).toEqual({
+ eligible: false,
+ reason: refusal,
+ signupUrl: expect.any(String),
+ });
+ expect(decoded(body.signupUrl)).toEqual({
+ ipv4: IP,
+ surface: "mcp",
+ reason,
+ });
+ },
+ );
+
+ it("gives a suspicious refusal the regular mcp link when no key is configured", async () => {
+ config.KEYLESS_SIGNUP_LINK_KEYS = undefined;
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({
+ eligible: false,
+ reason: "suspicious",
+ });
+ const res = fakeRes();
+
+ await keylessEligibilityController(eligibilityRequest(), res);
+
+ expect(res.json).toHaveBeenCalledWith({
+ eligible: false,
+ reason: "suspicious",
+ signupUrl: MCP_FALLBACK,
+ });
+ });
+
+ it.each(["disabled", "error"] as const)(
+ "gives the regular signup link when the refusal is %s",
+ async reason => {
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({
+ eligible: false,
+ reason,
+ });
+ const res = fakeRes();
+
+ await keylessEligibilityController(eligibilityRequest(), res);
+
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith({
+ eligible: false,
+ reason,
+ signupUrl: MCP_FALLBACK,
+ });
+ },
+ );
+
+ it("gives a non-IPv4 caller the regular signup link", async () => {
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({
+ eligible: false,
+ reason: "ineligible_ip",
+ });
+ const res = fakeRes();
+
+ await keylessEligibilityController(
+ eligibilityRequest({ signup_link: "1" }, "2001:db8::1"),
+ res,
+ );
+
+ expect(res.json).toHaveBeenCalledWith({
+ eligible: false,
+ reason: "ineligible_ip",
+ signupUrl: MCP_FALLBACK,
+ });
+ });
+
+ it("omits the link for an eligible IP unless asked", async () => {
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({ eligible: true });
+ const res = fakeRes();
+
+ await keylessEligibilityController(eligibilityRequest(), res);
+ await keylessEligibilityController(
+ eligibilityRequest({ signup_link: "1" }),
+ res,
+ );
+
+ expect(res.status.mock.calls).toEqual([[200], [200]]);
+ expect(res.json.mock.calls[0]).toEqual([{ eligible: true }]);
+ const asked = res.json.mock.calls[1][0];
+ expect(asked).toEqual({ eligible: true, signupUrl: expect.any(String) });
+ expect(decoded(asked.signupUrl)).toEqual({
+ ipv4: IP,
+ surface: "mcp",
+ reason: "account_only_tool",
+ });
+ });
+
+ it("tags the account-only link with that reason even when the IP is also refused", async () => {
+ vi.mocked(checkKeylessEligibility).mockResolvedValue({
+ eligible: false,
+ reason: "credits",
+ });
+ const res = fakeRes();
+
+ await keylessEligibilityController(
+ eligibilityRequest({ signup_link: "1" }),
+ res,
+ );
+
+ expect(decoded(res.json.mock.calls[0][0].signupUrl)?.reason).toBe(
+ "account_only_tool",
+ );
+ });
+});
diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.ts
index bc619786a..8c79df4f4 100644
--- a/apps/api/src/lib/keyless.ts
+++ b/apps/api/src/lib/keyless.ts
@@ -11,6 +11,13 @@ import {
keylessCreditBlocksTotal,
keylessCreditsTotal,
} from "./keyless-metrics";
+import {
+ type KeylessPromptReason,
+ type KeylessSignupSurface,
+ keylessFallbackSignupUrl,
+ keylessSignupLink,
+ keylessSignupSurface,
+} from "./keyless-signup-link";
// Keyless free tier: scrape, search, and interact can be used without an API key
// from the official MCP server, CLI, or SDKs. It's gated per-IP/day by TWO
@@ -23,17 +30,21 @@ import {
const KEYLESS_REQUESTS_PER_DAY = config.KEYLESS_REQUESTS_PER_DAY;
const KEYLESS_CREDITS_PER_DAY = config.KEYLESS_CREDITS_PER_DAY;
-// Signup link for every keyless prompt. The UTM tags attribute the new account
-// to the keyless free tier; the CLI swaps utm_medium to `cli` before printing.
-export const KEYLESS_SIGNUP_URL =
- "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=api";
-
-// Shared 429 copy for both keyless request-cap and credit-cap failures. The URL
-// ends the sentence without a period so a copied link keeps a clean utm_medium.
-export const KEYLESS_FREE_TIER_LIMIT_MESSAGE = `You've hit Firecrawl's keyless free tier rate limit. To continue now, create a free API key at ${KEYLESS_SIGNUP_URL}
+// Keyless prompts link to signup at firecrawl.dev/k/<token>, where <token>
+// is the encrypted prompt (see keyless-signup-link.ts). The constant uses the
+// regular signup link and stays the marker for internal equality checks;
+// responses swap in the caller's own link where they leave the API. The URL
+// ends its line, so a copied link never picks up punctuation.
+function keylessFreeTierLimitMessage(signupUrl: string): string {
+ return `You've hit Firecrawl's keyless free tier rate limit. To continue now, create a free API key at ${signupUrl}
Then authenticate with:
Authorization: Bearer YOUR_API_KEY`;
+}
+
+export const KEYLESS_FREE_TIER_LIMIT_MESSAGE = keylessFreeTierLimitMessage(
+ keylessFallbackSignupUrl("api"),
+);
// The tier is "configured" when BOTH limits are set β€” even to 0. Unset means the
// feature is off (callers get a plain Unauthorized); 0 means it's on but the
@@ -156,14 +167,56 @@ async function retryAfterSecondsFor(key: string): Promise<number | undefined> {
}
}
+/**
+ * Signup link for a keyless prompt: the caller's own /k/<token> link for a
+ * valid IPv4 identity, the regular signup link for anything else.
+ */
+export function keylessSignupUrlForIp(
+ ip: string | null | undefined,
+ surface: KeylessSignupSurface,
+ reason: KeylessPromptReason,
+): { url: string; signupRef?: string } {
+ return keylessSignupLink(
+ ip && isKeylessIpEligible(ip) ? normalizeKeylessIpv4(ip) : null,
+ surface,
+ reason,
+ );
+}
+
+/** The caller's own signup link and the limit message that carries it. */
+export function keylessLimitPrompt(
+ ip: string | null | undefined,
+ surface: KeylessSignupSurface,
+): { error: string; signup_url: string; signupRef?: string } {
+ const { url, signupRef } = keylessSignupUrlForIp(ip, surface, "limit");
+ return {
+ error: keylessFreeTierLimitMessage(url),
+ signup_url: url,
+ ...(signupRef ? { signupRef } : {}),
+ };
+}
+
+/** keylessLimitPrompt for a keyless team id; the regular signup link for other teams. */
+export function keylessLimitPromptForTeam(
+ teamId: string,
+ req: Parameters<typeof keylessSignupSurface>[0],
+): ReturnType<typeof keylessLimitPrompt> {
+ return keylessLimitPrompt(
+ keylessIpFromTeamId(teamId),
+ keylessSignupSurface(req),
+ );
+}
+
/** Structured response for projected-credit reservation exhaustion. */
export async function keylessLimitBody(
teamId: string,
mode: string,
+ req?: Parameters<typeof keylessSignupSurface>[0],
): Promise<{
success: false;
error: string;
reason: "credits";
+ signup_url: string;
retry_after_seconds?: number;
}> {
const ip = keylessIpFromTeamId(teamId);
@@ -176,6 +229,10 @@ export async function keylessLimitBody(
// The reservation already proved the limit; missing TTL must not turn its
// controlled 429 into a server error.
}
+ const prompt = keylessLimitPrompt(
+ ip,
+ req ? keylessSignupSurface(req) : "api",
+ );
logger.warn("Keyless request blocked", {
canonicalLog: "keyless/consume",
event: "keyless_exhausted",
@@ -183,12 +240,14 @@ export async function keylessLimitBody(
reason: "credits",
mode,
retryAfterSeconds,
+ ...(prompt.signupRef ? { signupRef: prompt.signupRef } : {}),
...keylessExhaustionTelemetry(ip ?? ""),
});
return {
success: false,
- error: KEYLESS_FREE_TIER_LIMIT_MESSAGE,
+ error: prompt.error,
reason: "credits",
+ signup_url: prompt.signup_url,
...(retryAfterSeconds ? { retry_after_seconds: retryAfterSeconds } : {}),
};
}
diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.ts
index ec3253280..070be93d6 100644
--- a/apps/api/src/routes/shared.ts
+++ b/apps/api/src/routes/shared.ts
@@ -320,6 +320,7 @@ export function authMiddleware(
...(auth.retryAfterSeconds
? { retry_after_seconds: auth.retryAfterSeconds }
: {}),
+ ...(auth.signupUrl ? { signup_url: auth.signupUrl } : {}),
});
} else {
return;
diff --git a/apps/api/src/types.ts b/apps/api/src/types.ts
index bf216cffc..4a72a6c68 100644
--- a/apps/api/src/types.ts
+++ b/apps/api/src/types.ts
@@ -182,6 +182,8 @@ export type AuthResponse =
// Machine-readable keyless quota details for trusted MCP recovery.
keylessReason?: "requests" | "credits";
retryAfterSeconds?: number;
+ // Keyless prompts: the signup link in `error`, for clients that relay it.
+ signupUrl?: string;
};
export enum NotificationType {