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
Keyless: per-human bucket for World ID verified callers (#4934)
Erik Engervall1006903e5df0
diff --git a/apps/api/package.json b/apps/api/package.jsonindex 6f7d4a1cf..589ca8f1c 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -122,6 +122,7 @@"ioredis": "^5.6.1","ipaddr.js": "^2.2.0","joplin-turndown-plugin-gfm": "^1.0.12",+ "jose": "^6.2.12","jsdom": "^29.1.1","jsonrepair": "^3.14.0","koffi": "^2.9.0",diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yamlindex 9d72c7509..dce6fb1e2 100644--- a/apps/api/pnpm-lock.yaml+++ b/apps/api/pnpm-lock.yaml@@ -214,6 +214,9 @@ importers:joplin-turndown-plugin-gfm:specifier: ^1.0.12version: 1.0.12+ jose:+ specifier: ^6.2.12+ version: 6.2.12jsdom:specifier: ^29.1.1version: 29.1.1(@noble/[email protected])@@ -3391,6 +3394,9 @@ packages:resolution: {integrity: sha512-qL4+1iycQjZ1fs8zk3jSRk7cg3ROBUHk7GKtiLAQLFzLPKErnILUvz5DLszSQvz3s1sTjPbywLDISVUtBY6HaA==}+ resolution: {integrity: sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==}+resolution: {integrity: sha512-ESjNzSlt/sWE8sciZH8kBF8BPlwXPwhR6pWKAw8bw4Bwj+iZcnKW6ONWUutJ7eObuBZQpiIb8S7OYspWrKt7rA==}engines: {node: '>=14'}@@ -7455,6 +7461,8 @@ snapshots:+ [email protected]: {}+dependencies:config-chain: 1.1.13diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex 4d555094a..88f1dde25 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -16,6 +16,19 @@ const emptyStringAsUndefined = <T extends z.ZodTypeAny>(schema: T) =>const emptyStringAsDefault = <T extends z.ZodTypeAny>(schema: T) =>z.preprocess(value => (value === "" ? undefined : value), schema);+const worldIdSubjectList = (name: string) =>+ emptyStringAsUndefined(+ z+ .string()+ .refine(+ value =>+ value+ .split(",")+ .every(entry => /^[A-Za-z0-9_-]{43}$/.test(entry.trim())),+ `${name} must be comma-separated subject hashes`,+ ),+ );+// Trim strings and treat blank ones as unset (optional or default schemas).const blankStringAsUnset = <T extends z.ZodTypeAny>(schema: T) =>z.preprocess(@@ -147,6 +160,34 @@ const configSchema = z.object({// Keep separate from KEYLESS_PROXY_SECRET because delegated credentials can// authorize billed requests for a managed OAuth connection.MCP_DELEGATED_CREDENTIAL_SECRET: emptyStringAsUndefined(z.string().min(32)),+ // World ID verified-human keyless bucket. The issuer defaults to World's; the+ // feature is off unless the client ID, client secret, credential secret and+ // subject secret are set.+ WORLD_ID_ISSUER: emptyStringAsDefault(+ z+ .string()+ .trim()+ .url()+ .refine(+ value => value.startsWith("https://"),+ "WORLD_ID_ISSUER must be an https URL",+ )+ .default("https://auth.world.org"),+ ),+ WORLD_ID_CLIENT_ID: emptyStringAsUndefined(z.string().trim().min(1)),+ WORLD_ID_CLIENT_SECRET: emptyStringAsUndefined(z.string().trim().min(1)),+ WORLD_ID_CREDENTIAL_SECRET: emptyStringAsUndefined(z.string().trim().min(32)),+ // Keys the subject hashes (bucket ids, allow and deny lists). Kept apart+ // from the credential secret so rotating that one revokes credentials+ // without resetting buckets or the lists.+ WORLD_ID_SUBJECT_SECRET: emptyStringAsUndefined(z.string().trim().min(32)),+ // Optional comma-separated allowlist of subject hashes. When set, only these+ // verified humans are issued a credential; unset issues one to anyone who+ // verifies.+ WORLD_ID_ALLOWED_SUBJECTS: worldIdSubjectList("WORLD_ID_ALLOWED_SUBJECTS"),+ // Optional comma-separated subject hashes that are refused: no new+ // credential, and their existing credentials stop working.+ WORLD_ID_DENIED_SUBJECTS: worldIdSubjectList("WORLD_ID_DENIED_SUBJECTS"),// Optional Spur Context API token (https://docs.spur.us/context-api). When// set, keyless requests have their client IP checked against Spur and are// refused if the IP fronts anonymizing/rotating infrastructure (VPN/proxy/diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.tsindex 156d33c14..5d52d1cd7 100644--- a/apps/api/src/controllers/__tests__/auth.test.ts+++ b/apps/api/src/controllers/__tests__/auth.test.ts@@ -23,6 +23,7 @@ import { decryptKeylessSignupToken } from "../../lib/keyless-signup-link";import { logger } from "../../lib/logger";import { isKeylessIpSuspicious } from "../../lib/spur";import { trackKeylessPromptShown } from "../../lib/keyless-prompt-analytics";+import { mintWorldIdCredential, worldIdSubjectHash } from "../../lib/world-id";import { db } from "../../db/connection";import { autumnService } from "../../services/autumn/autumn.service";@@ -130,6 +131,13 @@ describe("authenticateUser", () => {const originalPreviewToken = config.PREVIEW_TOKEN;const originalAgentInteropSecret = config.AGENT_INTEROP_SECRET;const originalKeylessSignupLinkKeys = config.KEYLESS_SIGNUP_LINK_KEYS;+ const originalWorldId = {+ WORLD_ID_ISSUER: config.WORLD_ID_ISSUER,+ WORLD_ID_CLIENT_ID: config.WORLD_ID_CLIENT_ID,+ WORLD_ID_CLIENT_SECRET: config.WORLD_ID_CLIENT_SECRET,+ WORLD_ID_CREDENTIAL_SECRET: config.WORLD_ID_CREDENTIAL_SECRET,+ WORLD_ID_SUBJECT_SECRET: config.WORLD_ID_SUBJECT_SECRET,+ };beforeEach(() => {vi.mocked(isKeylessConfigured).mockReturnValue(false);@@ -150,6 +158,7 @@ describe("authenticateUser", () => {config.PREVIEW_TOKEN = originalPreviewToken;config.AGENT_INTEROP_SECRET = originalAgentInteropSecret;config.KEYLESS_SIGNUP_LINK_KEYS = originalKeylessSignupLinkKeys;+ Object.assign(config, originalWorldId);vi.unstubAllGlobals();vi.clearAllMocks();});@@ -396,6 +405,164 @@ describe("authenticateUser", () => {});});+ describe("World ID keyless credential", () => {+ const allowed = {+ ok: true,+ requestsUsed: 1,+ creditsUsed: 0,+ } as const;+ const enableWorldId = () => {+ config.USE_DB_AUTHENTICATION = true;+ config.WORLD_ID_ISSUER = "https://issuer.test";+ config.WORLD_ID_CLIENT_ID = "app_test";+ config.WORLD_ID_CLIENT_SECRET = "client-secret";+ config.WORLD_ID_CREDENTIAL_SECRET = "c".repeat(32);+ config.WORLD_ID_SUBJECT_SECRET = "s".repeat(32);+ vi.mocked(isKeylessConfigured).mockReturnValue(true);+ vi.mocked(consumeKeylessRequest).mockResolvedValue(allowed);+ };++ it("gets its own bucket and skips the IP checks", async () => {+ enableWorldId();+ const hash = worldIdSubjectHash("https://issuer.test", "human-1");+ const { credential } = mintWorldIdCredential(hash);++ const auth = await authenticateUser(+ {+ body: { origin: "cli" },+ headers: { "x-firecrawl-world-id": credential },+ // IPv6 is refused on the IP path; a verified human isn't keyed on it.+ socket: { remoteAddress: "2001:db8::1" },+ },+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(auth).toMatchObject({+ success: true,+ team_id: `preview_keyless_wid_${hash}`,+ });+ expect(consumeKeylessRequest).toHaveBeenCalledWith(`wid_${hash}`);+ expect(isKeylessIpSuspicious).not.toHaveBeenCalled();+ });++ it("falls back to the IP bucket when the credential is invalid", async () => {+ enableWorldId();++ const auth = await authenticateUser(+ {+ body: { origin: "cli" },+ headers: { "x-firecrawl-world-id": "fcwid_forged.credential" },+ socket: { remoteAddress: "203.0.113.8" },+ },+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(auth).toMatchObject({+ success: true,+ team_id: "preview_keyless_203.0.113.8",+ });+ expect(consumeKeylessRequest).toHaveBeenCalledWith("203.0.113.8");+ expect(isKeylessIpSuspicious).toHaveBeenCalledWith("203.0.113.8");+ });++ it("is ignored while World ID is not configured", async () => {+ enableWorldId();+ const { credential } = mintWorldIdCredential("h".repeat(43));+ config.WORLD_ID_CLIENT_SECRET = undefined;++ const auth = await authenticateUser(+ {+ body: { origin: "cli" },+ headers: { "x-firecrawl-world-id": credential },+ socket: { remoteAddress: "2001:db8::1" },+ },+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(auth).toMatchObject({ success: false, status: 401 });+ expect(consumeKeylessRequest).not.toHaveBeenCalled();+ });++ const ipv4Request = (headers: Record<string, string> = {}) => ({+ body: { origin: "cli" },+ headers,+ socket: { remoteAddress: "203.0.113.8" },+ });++ it("keeps IPv4 callers on the IP bucket and prompt whether or not it is configured", async () => {+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";+ enableWorldId();+ vi.mocked(consumeKeylessRequest).mockResolvedValue({+ ok: false,+ reason: "credits",+ requestsUsed: 1,+ creditsUsed: 100,+ });+ const { credential } = mintWorldIdCredential(+ worldIdSubjectHash("https://issuer.test", "human-1"),+ );+ const run = (headers: Record<string, string> = {}) =>+ authenticateUser(ipv4Request(headers), {}, RateLimiterMode.Scrape, {+ allowKeyless: true,+ });++ const configured = await run();+ const forged = await run({+ "x-firecrawl-world-id": "fcwid_forged.credential",+ });+ config.WORLD_ID_CLIENT_ID = undefined;+ config.WORLD_ID_CLIENT_SECRET = undefined;+ config.WORLD_ID_CREDENTIAL_SECRET = undefined;+ config.WORLD_ID_SUBJECT_SECRET = undefined;+ const unset = await run();+ const unsetWithCredential = await run({+ "x-firecrawl-world-id": credential,+ });++ const links = [configured, forged, unset, unsetWithCredential].map(+ auth => {+ expect(auth).toMatchObject({ success: false, status: 429 });+ return decodedLink((auth as { signupUrl?: string }).signupUrl);+ },+ );+ expect(links[0]).toMatchObject({ ipv4: "203.0.113.8", reason: "limit" });+ expect(links).toEqual(Array(4).fill(links[0]));+ expect(vi.mocked(consumeKeylessRequest).mock.calls).toEqual(+ Array(4).fill(["203.0.113.8"]),+ );+ expect(vi.mocked(isKeylessIpSuspicious).mock.calls).toEqual(+ Array(4).fill(["203.0.113.8"]),+ );+ });++ it("authenticates a credential without calling the issuer", async () => {+ enableWorldId();+ const fetch = vi.fn().mockRejectedValue(new TypeError("fetch failed"));+ vi.stubGlobal("fetch", fetch);+ const hash = worldIdSubjectHash("https://issuer.test", "human-1");+ const { credential } = mintWorldIdCredential(hash);++ const auth = await authenticateUser(+ ipv4Request({ "x-firecrawl-world-id": credential }),+ {},+ RateLimiterMode.Scrape,+ { allowKeyless: true },+ );++ expect(auth).toMatchObject({+ success: true,+ team_id: `preview_keyless_wid_${hash}`,+ });+ expect(fetch).not.toHaveBeenCalled();+ });+ });+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;diff --git a/apps/api/src/controllers/__tests__/keyless-world-id.test.ts b/apps/api/src/controllers/__tests__/keyless-world-id.test.tsnew file mode 100644index 000000000..14022a3d9--- /dev/null+++ b/apps/api/src/controllers/__tests__/keyless-world-id.test.ts@@ -0,0 +1,198 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import type { Request, Response } from "express";++const { consume, client } = vi.hoisted(() => ({+ consume: vi.fn(),+ client: { ip: "203.0.113.8" },+}));++vi.mock("rate-limiter-flexible", async importOriginal => ({+ ...(await importOriginal<typeof import("rate-limiter-flexible")>()),+ RateLimiterRedis: class {+ keyPrefix: string;+ constructor(options: { keyPrefix: string }) {+ this.keyPrefix = options.keyPrefix;+ }+ consume(key: string) {+ return consume(this.keyPrefix, key);+ }+ },+}));+vi.mock("../../services/rate-limiter", () => ({ redisRateLimitClient: {} }));+vi.mock("../../db/connection", () => ({ db: {}, dbRr: {}, dbIndex: {} }));+vi.mock("../auth", () => ({ keylessClientIp: () => client.ip }));++import { RateLimiterRes } from "rate-limiter-flexible";+import { config } from "../../config";+import { sealDeviceCode } from "../../lib/world-id";+import {+ keylessWorldIdDeviceController,+ keylessWorldIdTokenController,+} from "../v2/keyless-world-id";++const original = {+ WORLD_ID_ISSUER: config.WORLD_ID_ISSUER,+ WORLD_ID_CLIENT_ID: config.WORLD_ID_CLIENT_ID,+ WORLD_ID_CLIENT_SECRET: config.WORLD_ID_CLIENT_SECRET,+ WORLD_ID_CREDENTIAL_SECRET: config.WORLD_ID_CREDENTIAL_SECRET,+ WORLD_ID_SUBJECT_SECRET: config.WORLD_ID_SUBJECT_SECRET,+};++function configure() {+ config.WORLD_ID_ISSUER = "https://auth.world.org";+ config.WORLD_ID_CLIENT_ID = "app_test";+ config.WORLD_ID_CLIENT_SECRET = "client-secret";+ config.WORLD_ID_CREDENTIAL_SECRET = "c".repeat(32);+ config.WORLD_ID_SUBJECT_SECRET = "s".repeat(32);+}++async function call(+ controller: typeof keylessWorldIdDeviceController,+ body: Record<string, unknown> = {},+) {+ const res = {+ status: vi.fn(),+ setHeader: vi.fn(),+ json: vi.fn(),+ };+ res.status.mockReturnValue(res);+ res.setHeader.mockReturnValue(res);+ res.json.mockReturnValue(res);+ await controller(+ { body, headers: {} } as unknown as Request,+ res as unknown as Response,+ );+ return {+ status: res.status.mock.calls[0]?.[0],+ body: res.json.mock.calls[0]?.[0],+ headers: Object.fromEntries(res.setHeader.mock.calls),+ };+}++const poll = (controller = keylessWorldIdTokenController) =>+ call(controller, { device_handle: sealDeviceCode("device-code") });++describe("World ID keyless endpoints", () => {+ let fetch: ReturnType<typeof vi.fn>;++ beforeEach(() => {+ configure();+ client.ip = "203.0.113.8";+ consume.mockResolvedValue(undefined);+ fetch = vi.fn();+ vi.stubGlobal("fetch", fetch);+ });++ afterEach(() => {+ Object.assign(config, original);+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ vi.clearAllMocks();+ });++ it("answers 404 without touching the issuer or the throttle while not configured", async () => {+ const handle = sealDeviceCode("device-code");+ config.WORLD_ID_CLIENT_ID = undefined;+ config.WORLD_ID_CLIENT_SECRET = undefined;+ config.WORLD_ID_CREDENTIAL_SECRET = undefined;+ config.WORLD_ID_SUBJECT_SECRET = undefined;++ for (const result of [+ await call(keylessWorldIdDeviceController),+ await call(keylessWorldIdTokenController, { device_handle: handle }),+ ]) {+ expect(result).toMatchObject({+ status: 404,+ body: { success: false, error: "Not found" },+ });+ }+ expect(fetch).not.toHaveBeenCalled();+ expect(consume).not.toHaveBeenCalled();+ });++ it("calls World's default issuer with a 10s timeout", async () => {+ const timeout = vi.spyOn(AbortSignal, "timeout");+ fetch.mockResolvedValue(+ Response.json({+ device_code: "device-code",+ user_code: "ABCD-EFGH",+ verification_uri: "https://world.org/verify",+ }),+ );++ expect(await call(keylessWorldIdDeviceController)).toMatchObject({+ status: 200,+ body: { success: true, user_code: "ABCD-EFGH" },+ });+ expect(fetch).toHaveBeenCalledWith(+ "https://auth.world.org/api/v1/device_authorization",+ expect.objectContaining({ signal: timeout.mock.results[0].value }),+ );+ expect(timeout).toHaveBeenCalledExactlyOnceWith(10_000);+ });++ it.each([+ ["unreachable", () => Promise.reject(new TypeError("fetch failed"))],+ [+ "timing out",+ () => Promise.reject(new DOMException("timed out", "TimeoutError")),+ ],+ [+ "erroring",+ () => Promise.resolve(new Response("unavailable", { status: 503 })),+ ],+ ])(+ "answers 502 without a credential while the issuer is %s",+ async (_, issuer) => {+ fetch.mockImplementation(issuer);+ const unavailable = {+ status: 502,+ body: { success: false, error: "temporarily_unavailable" },+ };++ expect(await call(keylessWorldIdDeviceController)).toMatchObject(+ unavailable,+ );+ expect(await poll()).toMatchObject(unavailable);+ },+ );++ it.each([+ [+ "an IPv4 caller in its own bucket",+ "::ffff:203.0.113.8",+ "",+ "203.0.113.8",+ ],+ [+ "a non-IPv4 caller in the shared bucket",+ "2001:db8::1",+ "_shared",+ "shared",+ ],+ ])("throttles %s", async (_, ip, suffix, key) => {+ client.ip = ip;+ fetch.mockRejectedValue(new TypeError("fetch failed"));++ await call(keylessWorldIdDeviceController);+ await poll();++ expect(consume.mock.calls).toEqual([+ [`keyless_world_id_start${suffix}`, key],+ [`keyless_world_id_poll${suffix}`, key],+ ]);+ });++ it("answers 429 before calling the issuer once a caller is out of starts or polls", async () => {+ consume.mockRejectedValue(new RateLimiterRes(0, 5_000));+ const throttled = {+ status: 429,+ body: { success: false, error: "slow_down" },+ headers: { "Retry-After": 5 },+ };++ expect(await call(keylessWorldIdDeviceController)).toEqual(throttled);+ expect(await poll()).toEqual(throttled);+ expect(fetch).not.toHaveBeenCalled();+ });+});diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.tsindex 9b352f34a..f112baf70 100644--- a/apps/api/src/controllers/auth.ts+++ b/apps/api/src/controllers/auth.ts@@ -20,11 +20,13 @@ import {keylessLimitPrompt,keylessSignupUrlForIp,keylessTeamId,+ keylessWorldIdIdentity,normalizeKeylessIpv4,reportKeylessPromptShown,} from "../lib/keyless";import { keylessSignupSurface } from "../lib/keyless-signup-link";import { isKeylessIpSuspicious } from "../lib/spur";+import { verifyWorldIdCredential } from "../lib/world-id";import { keylessAuthTotal } from "../lib/keyless-metrics";import { checkIpRestriction } from "../lib/ip-restriction";import { checkKeyEndpointRestriction } from "../lib/key-restriction";@@ -562,7 +564,7 @@ function keylessSuspiciousIpMessage(signupUrl: string): string {* 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 {+export function keylessClientIp(req): string {let ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";if (config.KEYLESS_PROXY_SECRET &&@@ -636,10 +638,20 @@ async function handleKeylessAuth(let ip = keylessClientIp(req);+ // A World ID verified human (a valid `fcwid_` credential) gets their own+ // bucket keyed on their World ID instead of the IP, so the IP checks below+ // don't apply. A missing or invalid credential falls back to the IP bucket.+ const worldIdSubject = verifyWorldIdCredential(+ req.headers["x-firecrawl-world-id"],+ );+ const worldIdIdentity = worldIdSubject+ ? keylessWorldIdIdentity(worldIdSubject)+ : null;+// 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)) {+ if (!worldIdIdentity && !isKeylessIpEligible(ip)) {return denied(req, "keyless_ip_ineligible", unauthorized);}@@ -651,7 +663,7 @@ async function handleKeylessAuth(// 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)) {+ if (!worldIdIdentity && (await isKeylessIpSuspicious(ip))) {keylessAuthTotal.inc({ mode, outcome: "suspicious" });const { url, signupRef } = keylessSignupUrlForIp(ip,@@ -684,7 +696,9 @@ async function handleKeylessAuth(});}- const teamId = keylessTeamId(ip);+ // The quota bucket and team id. Logs keep the client IP either way.+ const identity = worldIdIdentity ?? ip;+ const teamId = keylessTeamId(identity);const modeLabel =mode === RateLimiterMode.Search? "search"@@ -700,7 +714,7 @@ async function handleKeylessAuth(let result: Awaited<ReturnType<typeof consumeKeylessRequest>>;try {- result = await consumeKeylessRequest(ip);+ result = await consumeKeylessRequest(identity);} catch (error) {keylessAuthTotal.inc({ mode, outcome: "error" });// Limiter store (Redis) unavailable — fail closed with a controlled auth@@ -722,13 +736,17 @@ async function handleKeylessAuth(integration,mode: modeLabel,teamId,+ worldId: worldIdIdentity !== null,requestsUsed: result.requestsUsed,creditsUsed: result.creditsUsed,};if (!result.ok) {keylessAuthTotal.inc({ mode, outcome: result.reason ?? "error" });- const prompt = keylessLimitPrompt(ip, signupSurface);+ const prompt = keylessLimitPrompt(+ worldIdIdentity ? null : ip,+ signupSurface,+ );logger.warn("Keyless request blocked", {...baseLog,blocked: true,@@ -736,7 +754,7 @@ async function handleKeylessAuth(reason: result.reason,retryAfterSeconds: result.retryAfterSeconds,...(prompt.signupRef ? { signupRef: prompt.signupRef } : {}),- ...keylessExhaustionTelemetry(ip),+ ...keylessExhaustionTelemetry(identity),});return {success: false,diff --git a/apps/api/src/controllers/v2/keyless-eligibility.ts b/apps/api/src/controllers/v2/keyless-eligibility.tsindex c4df9eb2f..f97ce99ea 100644--- a/apps/api/src/controllers/v2/keyless-eligibility.ts+++ b/apps/api/src/controllers/v2/keyless-eligibility.ts@@ -3,6 +3,7 @@ import { config } from "../../config";import {checkKeylessEligibility,keylessSignupUrlForIp,+ keylessWorldIdIdentity,reportKeylessPromptShown,} from "../../lib/keyless";import {@@ -10,6 +11,7 @@ import {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@@ -22,6 +24,9 @@ import {* 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,@@ -37,7 +42,13 @@ export async function keylessEligibilityController(const ip =(typeof ipHeader === "string" ? ipHeader.trim() : "") || req.ip || "";- const result = await checkKeylessEligibility(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);@@ -55,10 +66,13 @@ export async function keylessEligibilityController(// identity, so it gets the regular signup link.let signupUrl = keylessFallbackSignupUrl(surface);if (reason) {- const link = keylessSignupUrlForIp(ip, surface, 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(ip, surface, reason, 200, link.signupRef);+ reportKeylessPromptShown(promptIp, surface, reason, 200, link.signupRef);}res.status(200).json({ ...result, signupUrl });}diff --git a/apps/api/src/controllers/v2/keyless-world-id.ts b/apps/api/src/controllers/v2/keyless-world-id.tsnew file mode 100644index 000000000..f44203f25--- /dev/null+++ b/apps/api/src/controllers/v2/keyless-world-id.ts@@ -0,0 +1,132 @@+import { Request, Response } from "express";+import { RateLimiterRedis, RateLimiterRes } from "rate-limiter-flexible";+import { redisRateLimitClient } from "../../services/rate-limiter";+import { isKeylessIpEligible, normalizeKeylessIpv4 } from "../../lib/keyless";+import {+ isWorldIdConfigured,+ pollWorldIdDeviceFlow,+ startWorldIdDeviceFlow,+} from "../../lib/world-id";+import { keylessClientIp } from "../auth";++// Starts and polls call the World ID issuer with our client credentials,+// which carry a per-client limit, so one caller must not be able to use it up.+// Callers are keyed like the keyless tier: one bucket per canonical IPv4, and+// one shared, larger bucket for every other address (IPv6 rotates too cheaply+// to key on). A poll budget covers one full attempt at the issuer's 5s+// interval over the 20 minutes a device code lives.+const limiter = (keyPrefix: string, points: number, duration: number) =>+ new RateLimiterRedis({+ storeClient: redisRateLimitClient,+ keyPrefix,+ points,+ duration,+ });+const throttles = {+ start: {+ ipv4: limiter("keyless_world_id_start", 10, 3600),+ shared: limiter("keyless_world_id_start_shared", 100, 3600),+ },+ poll: {+ ipv4: limiter("keyless_world_id_poll", 300, 1200),+ shared: limiter("keyless_world_id_poll_shared", 3000, 1200),+ },+};++/** Consumes one point for the caller; answers 429 and returns false when out. */+async function throttle(+ req: Request,+ res: Response,+ kind: keyof typeof throttles,+): Promise<boolean> {+ const ip = keylessClientIp(req);+ const ipv4 = isKeylessIpEligible(ip);+ try {+ await (ipv4 ? throttles[kind].ipv4 : throttles[kind].shared).consume(+ ipv4 ? normalizeKeylessIpv4(ip) : "shared",+ );+ return true;+ } catch (error) {+ if (error instanceof RateLimiterRes) {+ res+ .status(429)+ .setHeader("Retry-After", Math.ceil(error.msBeforeNext / 1000))+ .json({ success: false, error: "slow_down" });+ return false;+ }+ throw error;+ }+}++/**+ * Start World ID verification for the keyless tier (OIDC device flow). The+ * response carries the code and link to show the human, plus an opaque+ * `device_handle` to poll /v2/keyless/world-id/token with.+ */+export async function keylessWorldIdDeviceController(+ req: Request,+ res: Response,+): Promise<void> {+ if (!isWorldIdConfigured()) {+ res.status(404).json({ success: false, error: "Not found" });+ return;+ }++ if (!(await throttle(req, res, "start"))) return;++ const start = await startWorldIdDeviceFlow();+ if (!start.ok) {+ res.status(start.status).json({ success: false, error: start.error });+ return;+ }+ res.status(200).json({+ success: true,+ device_handle: start.deviceHandle,+ user_code: start.userCode,+ verification_uri: start.verificationUri,+ ...(start.verificationUriComplete+ ? { verification_uri_complete: start.verificationUriComplete }+ : {}),+ expires_in: start.expiresIn,+ interval: start.interval,+ });+}++/**+ * Poll a World ID verification. Pending and terminal states use the RFC 8628+ * error codes (`authorization_pending`, `slow_down`, `access_denied`,+ * `expired_token`, ...). On approval it returns the `fcwid_` credential to+ * send as `x-firecrawl-world-id` on keyless requests.+ */+export async function keylessWorldIdTokenController(+ req: Request,+ res: Response,+): Promise<void> {+ if (!isWorldIdConfigured()) {+ res.status(404).json({ success: false, error: "Not found" });+ return;+ }++ if (!(await throttle(req, res, "poll"))) return;++ const result = await pollWorldIdDeviceFlow(req.body?.device_handle);+ switch (result.outcome) {+ case "approved":+ res.status(200).json({+ success: true,+ credential: result.credential,+ expires_at: new Date(result.expiresAt * 1000).toISOString(),+ });+ return;+ case "not_allowed":+ res.status(403).json({+ success: false,+ error: "subject_not_allowed",+ subject_hash: result.subjectHash,+ });+ return;+ case "error":+ res.status(result.status).json({ success: false, error: result.error });+ return;+ }+}diff --git a/apps/api/src/lib/__tests__/keyless-usage-log.test.ts b/apps/api/src/lib/__tests__/keyless-usage-log.test.tsindex 461481334..e2502637c 100644--- a/apps/api/src/lib/__tests__/keyless-usage-log.test.ts+++ b/apps/api/src/lib/__tests__/keyless-usage-log.test.ts@@ -39,6 +39,7 @@ import {chargeKeylessCredits,keylessTeamId,keylessTeamUuid,+ keylessWorldIdIdentity,logKeylessCreditUsage,} from "../keyless";import { logger } from "../logger";@@ -130,6 +131,21 @@ describe("logKeylessCreditUsage", () => {expect(dbInsert).not.toHaveBeenCalled();});+ it("keeps a World ID bucket out of the raw-IP records", async () => {+ const info = vi.spyOn(logger, "info").mockImplementation(() => logger);+ const team = keylessTeamId(keylessWorldIdIdentity("h".repeat(43)));++ await logKeylessCreditUsage(team, 3);++ expect(dbInsert).not.toHaveBeenCalled();+ expect(info).toHaveBeenCalledWith("Keyless World ID usage", {+ canonicalLog: "keyless/usage",+ teamId: keylessTeamUuid(team),+ worldId: true,+ creditsUsed: 3,+ });+ });+it("swallows insert failures so the request is unaffected", async () => {insertValues.mockRejectedValue(new Error("db down"));diff --git a/apps/api/src/lib/__tests__/keyless-world-id-limits.test.ts b/apps/api/src/lib/__tests__/keyless-world-id-limits.test.tsnew file mode 100644index 000000000..ae14fef56--- /dev/null+++ b/apps/api/src/lib/__tests__/keyless-world-id-limits.test.ts@@ -0,0 +1,117 @@+import { describe, expect, it, vi } from "vitest";++// keyless.ts reads its daily limits at import, so set them first.+const { redis } = vi.hoisted(() => {+ process.env.KEYLESS_REQUESTS_PER_DAY = "10";+ process.env.KEYLESS_CREDITS_PER_DAY = "100";+ return {+ redis: {+ incr: vi.fn(),+ expire: vi.fn().mockResolvedValue(1),+ get: vi.fn().mockResolvedValue("0"),+ ttl: vi.fn().mockResolvedValue(-1),+ pttl: vi.fn().mockResolvedValue(-1),+ eval: vi.fn().mockResolvedValue([1, 1]),+ },+ };+});++vi.mock("../../services/rate-limiter", () => ({ redisRateLimitClient: redis }));+vi.mock("../../db/connection", () => ({ db: {}, dbRr: {}, dbIndex: {} }));++import { config } from "../../config";+import {+ consumeKeylessRequest,+ keylessLimitBody,+ keylessTeamId,+ keylessWorldIdIdentity,+ reserveKeylessCredits,+} from "../keyless";+import { keylessFallbackSignupUrl } from "../keyless-signup-link";+import { logger } from "../logger";++const WORLD_ID = keylessWorldIdIdentity("h".repeat(43));++describe("keyless limits for a World ID identity", () => {+ it("allows 20% more requests than the per-IP tier", async () => {+ redis.incr.mockResolvedValue(12);+ expect((await consumeKeylessRequest(WORLD_ID)).ok).toBe(true);+ expect((await consumeKeylessRequest("203.0.113.8")).ok).toBe(false);++ redis.incr.mockResolvedValue(13);+ expect(await consumeKeylessRequest(WORLD_ID)).toMatchObject({+ ok: false,+ reason: "requests",+ });+ });++ it("leaves the per-IP tier at its configured limits", async () => {+ const ip = "203.0.113.8";+ redis.incr.mockResolvedValue(10);+ expect((await consumeKeylessRequest(ip)).ok).toBe(true);+ redis.incr.mockResolvedValue(11);+ expect(await consumeKeylessRequest(ip)).toMatchObject({+ ok: false,+ reason: "requests",+ });+ expect(redis.incr).toHaveBeenLastCalledWith(`keyless_requests:${ip}`);++ await reserveKeylessCredits(keylessTeamId(ip), 5);+ expect(redis.eval).toHaveBeenLastCalledWith(+ expect.any(String),+ 1,+ `keyless_credits:${ip}`,+ 5,+ 100,+ 86400,+ );+ });++ it("keeps its own request bucket, apart from any IP", async () => {+ redis.incr.mockResolvedValue(1);+ await consumeKeylessRequest(WORLD_ID);+ expect(redis.incr).toHaveBeenLastCalledWith(`keyless_requests:${WORLD_ID}`);+ });++ it("reserves credits against 20% more than the per-IP tier", async () => {+ const result = await reserveKeylessCredits(keylessTeamId(WORLD_ID), 5);+ expect(result.limit).toBe(120);+ expect(redis.eval).toHaveBeenLastCalledWith(+ expect.any(String),+ 1,+ `keyless_credits:${WORLD_ID}`,+ 5,+ 120,+ 86400,+ );++ expect(+ (await reserveKeylessCredits(keylessTeamId("203.0.113.8"), 5)).limit,+ ).toBe(100);+ });++ it("answers credit exhaustion without IP-keyed links or telemetry", async () => {+ config.KEYLESS_CONVERSION_HMAC_SECRET = "k".repeat(32);+ config.KEYLESS_SIGNUP_LINK_KEYS = "AAECAwQFBgcICQoLDA0ODw==";+ redis.pttl.mockResolvedValue(3_600_000);+ const warn = vi.spyOn(logger, "warn").mockImplementation(() => logger);++ const body = await keylessLimitBody(keylessTeamId(WORLD_ID), "v2_scrape");++ expect(body).toMatchObject({+ success: false,+ reason: "credits",+ signup_url: keylessFallbackSignupUrl("api"),+ retry_after_seconds: 3600,+ });+ expect(redis.pttl).toHaveBeenLastCalledWith(`keyless_credits:${WORLD_ID}`);+ expect(warn).toHaveBeenCalledWith(+ "Keyless request blocked",+ expect.not.objectContaining({ conversionCohort: expect.anything() }),+ );+ expect(warn).toHaveBeenCalledWith(+ "Keyless request blocked",+ expect.not.objectContaining({ signupRef: expect.anything() }),+ );+ });+});diff --git a/apps/api/src/lib/__tests__/world-id-config.test.ts b/apps/api/src/lib/__tests__/world-id-config.test.tsnew file mode 100644index 000000000..9deb9ed66--- /dev/null+++ b/apps/api/src/lib/__tests__/world-id-config.test.ts@@ -0,0 +1,35 @@+import { afterEach, describe, expect, it, vi } from "vitest";++async function loadIssuer(value: string | undefined): Promise<string> {+ vi.stubEnv("WORLD_ID_ISSUER", value);+ vi.resetModules();+ const { config } = await import("../../config.js");+ return config.WORLD_ID_ISSUER;+}++describe("WORLD_ID_ISSUER config", () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ vi.resetModules();+ });++ it("defaults to World's issuer when unset", async () => {+ expect(await loadIssuer(undefined)).toBe("https://auth.world.org");+ });++ it("defaults to World's issuer when empty", async () => {+ expect(await loadIssuer("")).toBe("https://auth.world.org");+ });++ it("uses the env value when set", async () => {+ expect(await loadIssuer("https://issuer.example")).toBe(+ "https://issuer.example",+ );+ });++ it("rejects a non-https issuer", async () => {+ await expect(loadIssuer("http://issuer.example")).rejects.toThrow(+ "WORLD_ID_ISSUER must be an https URL",+ );+ });+});diff --git a/apps/api/src/lib/__tests__/world-id.test.ts b/apps/api/src/lib/__tests__/world-id.test.tsnew file mode 100644index 000000000..417d44967--- /dev/null+++ b/apps/api/src/lib/__tests__/world-id.test.ts@@ -0,0 +1,278 @@+import {+ afterEach,+ beforeAll,+ beforeEach,+ describe,+ expect,+ it,+ vi,+} from "vitest";+import { createHmac } from "node:crypto";+import { exportJWK, generateKeyPair, SignJWT, type JWK } from "jose";+import { config } from "../../config";+import {+ mintWorldIdCredential,+ openDeviceHandle,+ pollWorldIdDeviceFlow,+ sealDeviceCode,+ startWorldIdDeviceFlow,+ verifyWorldIdCredential,+ worldIdSubjectHash,+} from "../world-id";++const ISSUER = "https://issuer.test";+const CLIENT_ID = "app_test";+const ORB_ACR = "https://world.org/oidc/acr/orb-v3";++let privateKey: CryptoKey;+let publicJwk: JWK;++beforeAll(async () => {+ const pair = await generateKeyPair("RS256");+ privateKey = pair.privateKey;+ publicJwk = { ...(await exportJWK(pair.publicKey)), kid: "k1", alg: "RS256" };+});++beforeEach(() => {+ config.WORLD_ID_ISSUER = ISSUER;+ config.WORLD_ID_CLIENT_ID = CLIENT_ID;+ config.WORLD_ID_CLIENT_SECRET = "client-secret";+ config.WORLD_ID_CREDENTIAL_SECRET = "c".repeat(32);+ config.WORLD_ID_SUBJECT_SECRET = "s".repeat(32);+ config.WORLD_ID_ALLOWED_SUBJECTS = undefined;+ config.WORLD_ID_DENIED_SUBJECTS = undefined;+});++afterEach(() => {+ vi.unstubAllGlobals();+});++async function idToken(claims: Record<string, unknown> = {}, iss = ISSUER) {+ return new SignJWT({ acr: ORB_ACR, amr: ["pop"], ...claims })+ .setProtectedHeader({ alg: "RS256", kid: "k1" })+ .setIssuer(iss)+ .setAudience(CLIENT_ID)+ .setSubject("human-1")+ .setIssuedAt()+ .setExpirationTime("5m")+ .sign(privateKey);+}++/** Fakes the issuer: its JWKS, plus the given token endpoint response. */+function stubIssuer(token: { status: number; body: unknown }) {+ const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {+ const href = String(url);+ if (href === `${ISSUER}/.well-known/jwks.json`) {+ return new Response(JSON.stringify({ keys: [publicJwk] }), {+ headers: { "content-type": "application/json" },+ });+ }+ if (href === `${ISSUER}/api/v1/token`) {+ return new Response(JSON.stringify(token.body), {+ status: token.status,+ headers: { "content-type": "application/json" },+ });+ }+ if (href === `${ISSUER}/api/v1/device_authorization`) {+ return new Response(+ JSON.stringify({+ device_code: "device-secret",+ user_code: "ABCD-EFGH",+ verification_uri: `${ISSUER}/device`,+ verification_uri_complete: `${ISSUER}/device?user_code=ABCD-EFGH`,+ expires_in: 1200,+ interval: 5,+ }),+ { headers: { "content-type": "application/json" } },+ );+ }+ throw new Error(`unexpected fetch ${href} ${init?.method}`);+ });+ vi.stubGlobal("fetch", fetchMock);+ return fetchMock;+}++describe("World ID credential", () => {+ // The subject hash is keyed by config, which beforeEach sets.+ let hash: string;+ beforeEach(() => {+ hash = worldIdSubjectHash(ISSUER, "human-1");+ });++ it("verifies a credential it minted and returns the subject hash", () => {+ const { credential } = mintWorldIdCredential(hash);+ expect(credential.startsWith("fcwid_")).toBe(true);+ expect(verifyWorldIdCredential(credential)).toBe(hash);+ });++ it("rejects expired, tampered, foreign-key and malformed credentials", () => {+ const now = Math.floor(Date.now() / 1000);+ const expired = mintWorldIdCredential(hash, now - 31 * 86400).credential;+ expect(verifyWorldIdCredential(expired, now)).toBeNull();++ const { credential } = mintWorldIdCredential(hash);+ const [payload, signature] = credential.slice(6).split(".");+ const forged = Buffer.from(+ JSON.stringify({ v: 1, sub: "x".repeat(43), iat: now, exp: now + 60 }),+ ).toString("base64url");+ expect(verifyWorldIdCredential(`fcwid_${forged}.${signature}`)).toBeNull();++ const otherKey = createHmac("sha256", "d".repeat(32))+ .update(payload)+ .digest("base64url");+ expect(verifyWorldIdCredential(`fcwid_${payload}.${otherKey}`)).toBeNull();++ for (const bad of [+ undefined,+ 42,+ "",+ "fcwid_",+ "fcmcp_a.b",+ `${credential}.x`,+ ]) {+ expect(verifyWorldIdCredential(bad)).toBeNull();+ }+ });++ it("stops accepting a denied subject's credential", () => {+ const { credential } = mintWorldIdCredential(hash);+ config.WORLD_ID_DENIED_SUBJECTS = hash;+ expect(verifyWorldIdCredential(credential)).toBeNull();+ });++ it("keeps subject hashes when the credential secret rotates", () => {+ const before = worldIdSubjectHash(ISSUER, "human-1");+ const { credential } = mintWorldIdCredential(before);+ config.WORLD_ID_CREDENTIAL_SECRET = "r".repeat(32);+ expect(worldIdSubjectHash(ISSUER, "human-1")).toBe(before);+ expect(verifyWorldIdCredential(credential)).toBeNull();+ });++ it("ignores every credential while World ID is not configured", () => {+ const { credential } = mintWorldIdCredential(hash);+ config.WORLD_ID_CLIENT_SECRET = undefined;+ expect(verifyWorldIdCredential(credential)).toBeNull();+ });+});++describe("ID token verification outages", () => {+ it("reports an unreachable JWKS as unavailable, not a rejected token", async () => {+ // A fresh issuer so the JWKS cache from earlier tests isn't reused.+ const down = "https://issuer-down.test";+ config.WORLD_ID_ISSUER = down;+ const token = await idToken({ auth_time: 1 }, down);+ vi.stubGlobal(+ "fetch",+ vi.fn(async (url: string | URL) => {+ if (String(url) === `${down}/api/v1/token`) {+ return new Response(JSON.stringify({ id_token: token }), {+ headers: { "content-type": "application/json" },+ });+ }+ return new Response("upstream down", { status: 503 });+ }),+ );+ expect(+ await pollWorldIdDeviceFlow(sealDeviceCode("device-secret")),+ ).toEqual({+ outcome: "error",+ status: 502,+ error: "temporarily_unavailable",+ });+ });+});++describe("device handle", () => {+ it("round-trips the device code and rejects a tampered handle", () => {+ const handle = sealDeviceCode("device-secret");+ expect(handle).not.toContain("device-secret");+ expect(openDeviceHandle(handle)).toBe("device-secret");++ const bytes = Buffer.from(handle, "base64url");+ bytes[bytes.length - 1] ^= 1;+ expect(openDeviceHandle(bytes.toString("base64url"))).toBeNull();+ expect(openDeviceHandle("not a handle")).toBeNull();+ });+});++describe("device flow", () => {+ it("starts with the client credentials and hides the device code", async () => {+ const fetchMock = stubIssuer({ status: 400, body: {} });+ const start = await startWorldIdDeviceFlow();++ expect(start).toMatchObject({+ ok: true,+ userCode: "ABCD-EFGH",+ expiresIn: 1200,+ interval: 5,+ });+ if (!start.ok) throw new Error("expected a start");+ expect(openDeviceHandle(start.deviceHandle)).toBe("device-secret");++ const [, init] = fetchMock.mock.calls[0];+ expect(init?.body).toBe("scope=openid");+ expect((init?.headers as Record<string, string>).Authorization).toBe(+ `Basic ${Buffer.from("app_test:client-secret").toString("base64")}`,+ );+ });++ it("mints a credential for a valid Orb-verified ID token", async () => {+ stubIssuer({+ status: 200,+ body: { id_token: await idToken({ auth_time: 1 }) },+ });+ const result = await pollWorldIdDeviceFlow(sealDeviceCode("device-secret"));++ expect(result.outcome).toBe("approved");+ if (result.outcome !== "approved") throw new Error("expected approval");+ expect(verifyWorldIdCredential(result.credential)).toBe(+ worldIdSubjectHash(ISSUER, "human-1"),+ );+ });++ it("refuses an ID token without the Orb authentication class", async () => {+ stubIssuer({+ status: 200,+ body: { id_token: await idToken({ auth_time: 1, acr: "other" }) },+ });+ expect(+ await pollWorldIdDeviceFlow(sealDeviceCode("device-secret")),+ ).toEqual({ outcome: "error", status: 400, error: "invalid_grant" });+ });++ it("issues credentials only to allowed subjects when the allowlist is set", async () => {+ config.WORLD_ID_ALLOWED_SUBJECTS = "someone-else";+ stubIssuer({+ status: 200,+ body: { id_token: await idToken({ auth_time: 1 }) },+ });+ expect(+ await pollWorldIdDeviceFlow(sealDeviceCode("device-secret")),+ ).toEqual({+ outcome: "not_allowed",+ subjectHash: worldIdSubjectHash(ISSUER, "human-1"),+ });+ });++ it("passes pending and terminal poll errors through", async () => {+ stubIssuer({ status: 400, body: { error: "authorization_pending" } });+ expect(+ await pollWorldIdDeviceFlow(sealDeviceCode("device-secret")),+ ).toEqual({+ outcome: "error",+ status: 400,+ error: "authorization_pending",+ });++ stubIssuer({ status: 400, body: { error: "access_denied" } });+ expect(+ await pollWorldIdDeviceFlow(sealDeviceCode("device-secret")),+ ).toEqual({ outcome: "error", status: 400, error: "access_denied" });++ expect(await pollWorldIdDeviceFlow("forged")).toEqual({+ outcome: "error",+ status: 400,+ error: "invalid_request",+ });+ });+});diff --git a/apps/api/src/lib/keyless.signup-prompt.test.ts b/apps/api/src/lib/keyless.signup-prompt.test.tsindex 99474b003..8111080d1 100644--- a/apps/api/src/lib/keyless.signup-prompt.test.ts+++ b/apps/api/src/lib/keyless.signup-prompt.test.ts@@ -36,6 +36,7 @@ import {import { trackKeylessPromptShown } from "./keyless-prompt-analytics";import { decryptKeylessSignupToken } from "./keyless-signup-link";import { logger } from "./logger";+import { mintWorldIdCredential } from "./world-id";const TEST_KEY = "AAECAwQFBgcICQoLDA0ODw==";const IP = "203.0.113.8";@@ -336,6 +337,42 @@ describe("keyless eligibility signup link", () => {expect(trackKeylessPromptShown).not.toHaveBeenCalled();});+ it("checks a forwarded World ID credential only while World ID is configured", async () => {+ const original = {+ WORLD_ID_CLIENT_ID: config.WORLD_ID_CLIENT_ID,+ WORLD_ID_CLIENT_SECRET: config.WORLD_ID_CLIENT_SECRET,+ WORLD_ID_CREDENTIAL_SECRET: config.WORLD_ID_CREDENTIAL_SECRET,+ WORLD_ID_SUBJECT_SECRET: config.WORLD_ID_SUBJECT_SECRET,+ };+ try {+ config.WORLD_ID_CLIENT_ID = "app_test";+ config.WORLD_ID_CLIENT_SECRET = "client-secret";+ config.WORLD_ID_CREDENTIAL_SECRET = "c".repeat(32);+ config.WORLD_ID_SUBJECT_SECRET = "s".repeat(32);+ const hash = "h".repeat(43);+ const { credential } = mintWorldIdCredential(hash);+ vi.mocked(checkKeylessEligibility).mockResolvedValue({ eligible: true });+ const request = () => {+ const req = eligibilityRequest();+ req.headers["x-firecrawl-world-id"] = credential;+ return req;+ };++ await keylessEligibilityController(request(), fakeRes());+ await keylessEligibilityController(eligibilityRequest(), fakeRes());+ config.WORLD_ID_CLIENT_SECRET = undefined;+ await keylessEligibilityController(request(), fakeRes());++ expect(vi.mocked(checkKeylessEligibility).mock.calls).toEqual([+ [IP, `wid_${hash}`],+ [IP, undefined],+ [IP, undefined],+ ]);+ } finally {+ Object.assign(config, original);+ }+ });+it("omits the link for an eligible IP unless asked", async () => {vi.mocked(checkKeylessEligibility).mockResolvedValue({ eligible: true });const res = fakeRes();diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.tsindex da3aa9dff..0d779b740 100644--- a/apps/api/src/lib/keyless.ts+++ b/apps/api/src/lib/keyless.ts@@ -63,6 +63,32 @@ export function isKeylessConfigured(): boolean {const DAY_SECONDS = 86400;+// A World ID verified human gets their own bucket, keyed on a hash of their+// World ID subject instead of the client IP, with 20% more requests and+// credits than the per-IP tier.+const WORLD_ID_IDENTITY_PREFIX = "wid_";+const WORLD_ID_LIMIT_MULTIPLIER = 1.2;++export function keylessWorldIdIdentity(subjectHash: string): string {+ return `${WORLD_ID_IDENTITY_PREFIX}${subjectHash}`;+}++/** Daily limits for a keyless identity (a client IP or a World ID identity). */+function keylessLimitsFor(identity: string): {+ requests: number;+ credits: number;+} {+ const requests = KEYLESS_REQUESTS_PER_DAY ?? 0;+ const credits = KEYLESS_CREDITS_PER_DAY ?? 0;+ if (!identity.startsWith(WORLD_ID_IDENTITY_PREFIX)) {+ return { requests, credits };+ }+ return {+ requests: Math.floor(requests * WORLD_ID_LIMIT_MULTIPLIER),+ credits: Math.floor(credits * WORLD_ID_LIMIT_MULTIPLIER),+ };+}+// This value is emitted only on quota exhaustion. It is a versioned, keyed// pseudonym—not an IP address—so analytics can join the event to the existing// privacy-controlled signup/OAuth matching pipeline without expanding raw-IP@@ -91,18 +117,29 @@ export function keylessConversionCohort(ip: string): string | undefined {}export function keylessExhaustionTelemetry(ip: string): Record<string, string> {+ // The conversion cohort joins on a client IP; a World ID bucket has none.+ if (ip.startsWith(WORLD_ID_IDENTITY_PREFIX)) return {};const conversionCohort = keylessConversionCohort(ip);return conversionCohort ? { conversionCohort } : {};}export { keylessTeamId, keylessTeamUuid };+// The keyless identity (quota bucket) of a team: a client IP or a World ID+// identity. Quota keys take it as is; prompts take keylessPromptIp.function keylessIpFromTeamId(teamId: string): string | null {return teamId.startsWith(KEYLESS_TEAM_PREFIX)? teamId.slice(KEYLESS_TEAM_PREFIX.length): null;}+/** The client IP a signup prompt may key on: none for a World ID bucket. */+function keylessPromptIp(identity: string | null): string | null {+ return identity && !identity.startsWith(WORLD_ID_IDENTITY_PREFIX)+ ? identity+ : null;+}+/*** Keyless is allowed only for a *valid IPv4* client identity. This both:* - denies IPv6 (a single client controls a huge block — a /64 is ~18@@ -217,7 +254,7 @@ export function keylessLimitPromptForTeam(req: Parameters<typeof keylessSignupSurface>[0],): ReturnType<typeof keylessLimitPrompt> {return keylessLimitPrompt(- keylessIpFromTeamId(teamId),+ keylessPromptIp(keylessIpFromTeamId(teamId)),keylessSignupSurface(req),);}@@ -245,7 +282,7 @@ export async function keylessLimitBody(// controlled 429 into a server error.}const prompt = keylessLimitPrompt(- ip,+ keylessPromptIp(ip),req ? keylessSignupSurface(req) : "api",);logger.warn("Keyless request blocked", {@@ -281,8 +318,7 @@ type KeylessCreditReservationResult = {export async function consumeKeylessRequest(ip: string,): Promise<KeylessConsumeResult> {- const requestLimit = KEYLESS_REQUESTS_PER_DAY ?? 0;- const creditLimit = KEYLESS_CREDITS_PER_DAY ?? 0;+ const { requests: requestLimit, credits: creditLimit } = keylessLimitsFor(ip);const rKey = requestsKey(ip);const requestsUsed = await redisRateLimitClient.incr(rKey);@@ -325,7 +361,7 @@ export async function reserveKeylessCredits(projectedCredits: number,): Promise<KeylessCreditReservationResult> {const ip = keylessIpFromTeamId(teamId);- const limit = KEYLESS_CREDITS_PER_DAY ?? 0;+ const limit = ip ? keylessLimitsFor(ip).credits : 0;if (!ip || !Number.isFinite(projectedCredits) || projectedCredits <= 0) {return { ok: true, creditsUsed: 0, limit };}@@ -443,7 +479,7 @@ export async function updateKeylessBrowserCredits(Date.now(),Math.ceil(credits),finalize ? "1" : "0",- KEYLESS_CREDITS_PER_DAY ?? 0,+ keylessLimitsFor(ip).credits,);if (result !== 1 && !finalize) keylessCreditBlocksTotal.inc();return result === 1;@@ -453,8 +489,13 @@ export async function updateKeylessBrowserCredits(* Read-only check of whether an IP could currently use the keyless tier (no* consumption). Used by the hosted MCP before a keyless tool call so an* ineligible caller receives structured recovery without an OAuth challenge.+ * A World ID identity is checked against its own bucket and skips the IP+ * checks, as it does in auth.*/-export async function checkKeylessEligibility(ip: string): Promise<{+export async function checkKeylessEligibility(+ ip: string,+ worldIdIdentity?: string,+): Promise<{eligible: boolean;reason?:| KeylessQuotaReason@@ -465,23 +506,29 @@ export async function checkKeylessEligibility(ip: string): Promise<{retryAfterSeconds?: number;}> {if (!isKeylessConfigured()) return { eligible: false, reason: "disabled" };- if (!ip || !isKeylessIpEligible(ip)) {- return { eligible: false, reason: "ineligible_ip" };- }- // Key the Spur cache and quota buckets below off the canonical IPv4 form.- ip = normalizeKeylessIpv4(ip);- // Optional Spur Context check (only when SPUR_API_KEY is set): treat IPs on- // anonymizing/rotating infrastructure as ineligible so the hosted MCP can- // return a bounded recovery result instead of serving a request auth rejects.- if (await isKeylessIpSuspicious(ip)) {- return { eligible: false, reason: "suspicious" };+ if (worldIdIdentity) {+ ip = worldIdIdentity;+ } else {+ if (!ip || !isKeylessIpEligible(ip)) {+ return { eligible: false, reason: "ineligible_ip" };+ }+ // Key the Spur cache and quota buckets below off the canonical IPv4 form.+ ip = normalizeKeylessIpv4(ip);+ // Optional Spur Context check (only when SPUR_API_KEY is set): treat IPs on+ // anonymizing/rotating infrastructure as ineligible so the hosted MCP can+ // return a bounded recovery result instead of serving a request auth+ // rejects.+ if (await isKeylessIpSuspicious(ip)) {+ return { eligible: false, reason: "suspicious" };+ }}+ const limits = keylessLimitsFor(ip);try {const requestsUsed = parseInt((await redisRateLimitClient.get(requestsKey(ip))) ?? "0",10,);- if (requestsUsed >= (KEYLESS_REQUESTS_PER_DAY ?? 0)) {+ if (requestsUsed >= limits.requests) {return {eligible: false,reason: "requests",@@ -493,7 +540,7 @@ export async function checkKeylessEligibility(ip: string): Promise<{(await redisRateLimitClient.get(creditKey)) ?? "0",10,);- if (creditsUsed >= (KEYLESS_CREDITS_PER_DAY ?? 0)) {+ if (creditsUsed >= limits.credits) {return {eligible: false,reason: "credits",@@ -544,6 +591,21 @@ export async function logKeylessCreditUsage(if (config.USE_DB_AUTHENTICATION !== true) return;keylessCreditsTotal.inc(creditsUsed);++ // `keyless_credit_usage.ip` and the zero-credit line hold the raw client+ // IP, which a World ID bucket isn't keyed on. Its usage goes to the same+ // canonical log under the team id instead; the client IP of each World ID+ // request is already on its `keyless/consume` line.+ if (ip.startsWith(WORLD_ID_IDENTITY_PREFIX)) {+ logger.info("Keyless World ID usage", {+ canonicalLog: "keyless/usage",+ teamId: teamUuid,+ worldId: true,+ creditsUsed,+ });+ return;+ }+if (creditsUsed <= 0) {// TODO(firecrawl-db): switch to a `keyless_credit_usage` row once the// zero-credit usage migration is merged. The IP is repeated in thediff --git a/apps/api/src/lib/world-id.ts b/apps/api/src/lib/world-id.tsnew file mode 100644index 000000000..bca5807ed--- /dev/null+++ b/apps/api/src/lib/world-id.ts@@ -0,0 +1,376 @@+import {+ createCipheriv,+ createDecipheriv,+ createHmac,+ randomBytes,+ timingSafeEqual,+} from "node:crypto";+import { createRemoteJWKSet, errors, jwtVerify } from "jose";+import { config } from "../config";++// World ID verified-human keyless bucket.+//+// World ID ID tokens are short-lived and come without a refresh token, so they+// can't ride along on every keyless request. Instead the API runs the OIDC+// device flow on the caller's behalf (the client secret and the device code+// stay server-side), validates the ID token once, and mints its own `fcwid_`+// credential, which keyless requests send in `x-firecrawl-world-id`. The+// credential carries only a keyed hash of the World ID subject.++const CREDENTIAL_PREFIX = "fcwid_";+const CREDENTIAL_TTL_SECONDS = 30 * 86400;+const MAX_CREDENTIAL_LENGTH = 512;+const MAX_FUTURE_IAT_SECONDS = 30;+const MAX_DEVICE_HANDLE_LENGTH = 2_048;+const SUBJECT_HASH_PATTERN = /^[A-Za-z0-9_-]{43}$/;+const ORB_ACR = "https://world.org/oidc/acr/orb-v3";+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";+const REQUEST_TIMEOUT_MS = 10_000;++export function isWorldIdConfigured(): boolean {+ return Boolean(+ config.WORLD_ID_CLIENT_ID &&+ config.WORLD_ID_CLIENT_SECRET &&+ config.WORLD_ID_CREDENTIAL_SECRET &&+ config.WORLD_ID_SUBJECT_SECRET,+ );+}++function issuer(): string {+ return config.WORLD_ID_ISSUER.replace(/\/+$/, "");+}++// One key per purpose (credential signing, device handles), derived from+// WORLD_ID_CREDENTIAL_SECRET. Subject hashes use WORLD_ID_SUBJECT_SECRET.+function derivedKey(purpose: string): Buffer {+ return createHmac("sha256", config.WORLD_ID_CREDENTIAL_SECRET!)+ .update(`world-id:${purpose}`)+ .digest();+}++function decodeCanonicalBase64Url(segment: string): Buffer | null {+ if (!segment || !/^[A-Za-z0-9_-]+$/.test(segment)) return null;+ const decoded = Buffer.from(segment, "base64url");+ return decoded.toString("base64url") === segment ? decoded : null;+}++/** Keyed, stable pseudonym for a World ID account: the only form we keep. */+export function worldIdSubjectHash(iss: string, sub: string): string {+ return createHmac("sha256", config.WORLD_ID_SUBJECT_SECRET!)+ .update(`${iss}\n${sub}`)+ .digest("base64url");+}++function listsSubject(list: string | undefined, subjectHash: string): boolean {+ return (list ?? "")+ .split(",")+ .map(entry => entry.trim())+ .includes(subjectHash);+}++export function isWorldIdSubjectDenied(subjectHash: string): boolean {+ return listsSubject(config.WORLD_ID_DENIED_SUBJECTS, subjectHash);+}++export function isWorldIdSubjectAllowed(subjectHash: string): boolean {+ if (isWorldIdSubjectDenied(subjectHash)) return false;+ const allowed = config.WORLD_ID_ALLOWED_SUBJECTS;+ return !allowed || listsSubject(allowed, subjectHash);+}++export function mintWorldIdCredential(+ subjectHash: string,+ nowSeconds = Math.floor(Date.now() / 1000),+): { credential: string; expiresAt: number } {+ const expiresAt = nowSeconds + CREDENTIAL_TTL_SECONDS;+ const payload = Buffer.from(+ JSON.stringify({ v: 1, sub: subjectHash, iat: nowSeconds, exp: expiresAt }),+ ).toString("base64url");+ const signature = createHmac("sha256", derivedKey("credential"))+ .update(payload)+ .digest("base64url");+ return {+ credential: `${CREDENTIAL_PREFIX}${payload}.${signature}`,+ expiresAt,+ };+}++/**+ * The subject hash a valid, unexpired `fcwid_` credential carries, or null.+ * Always null while World ID is not configured, so the header is ignored.+ */+export function verifyWorldIdCredential(+ token: unknown,+ nowSeconds = Math.floor(Date.now() / 1000),+): string | null {+ if (+ !isWorldIdConfigured() ||+ typeof token !== "string" ||+ token.length > MAX_CREDENTIAL_LENGTH ||+ !token.startsWith(CREDENTIAL_PREFIX)+ ) {+ return null;+ }++ const [payloadSegment, signatureSegment, ...rest] = token+ .slice(CREDENTIAL_PREFIX.length)+ .split(".");+ if (rest.length > 0 || !payloadSegment || !signatureSegment) return null;+ const payloadBytes = decodeCanonicalBase64Url(payloadSegment);+ const signature = decodeCanonicalBase64Url(signatureSegment);+ if (!payloadBytes || !signature || signature.length !== 32) return null;++ const expected = createHmac("sha256", derivedKey("credential"))+ .update(payloadSegment)+ .digest();+ if (!timingSafeEqual(signature, expected)) return null;++ let payload: Record<string, unknown>;+ try {+ payload = JSON.parse(payloadBytes.toString("utf8"));+ } catch {+ return null;+ }+ if (+ payload === null ||+ typeof payload !== "object" ||+ Object.keys(payload).sort().join(",") !== "exp,iat,sub,v" ||+ payload.v !== 1 ||+ typeof payload.sub !== "string" ||+ !SUBJECT_HASH_PATTERN.test(payload.sub) ||+ !Number.isInteger(payload.iat) ||+ !Number.isInteger(payload.exp)+ ) {+ return null;+ }+ const iat = payload.iat as number;+ const exp = payload.exp as number;+ if (iat > nowSeconds + MAX_FUTURE_IAT_SECONDS) return null;+ if (exp <= nowSeconds || exp - iat > CREDENTIAL_TTL_SECONDS) return null;+ if (isWorldIdSubjectDenied(payload.sub)) return null;+ return payload.sub;+}++// The device code must stay out of client hands (whoever holds it can redeem+// the approval with our client credentials), so the client polls with an+// encrypted handle instead and the API needs no state between calls.+export function sealDeviceCode(deviceCode: string): string {+ const iv = randomBytes(12);+ const cipher = createCipheriv("aes-256-gcm", derivedKey("device"), iv);+ const ciphertext = Buffer.concat([+ cipher.update(deviceCode, "utf8"),+ cipher.final(),+ ]);+ return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString(+ "base64url",+ );+}++export function openDeviceHandle(handle: unknown): string | null {+ if (typeof handle !== "string" || handle.length > MAX_DEVICE_HANDLE_LENGTH) {+ return null;+ }+ const bytes = decodeCanonicalBase64Url(handle);+ if (!bytes || bytes.length <= 28) return null;+ try {+ const decipher = createDecipheriv(+ "aes-256-gcm",+ derivedKey("device"),+ bytes.subarray(0, 12),+ );+ decipher.setAuthTag(bytes.subarray(12, 28));+ return Buffer.concat([+ decipher.update(bytes.subarray(28)),+ decipher.final(),+ ]).toString("utf8");+ } catch {+ return null;+ }+}++// CEILING: endpoint paths are fixed rather than read from the issuer's+// discovery document; they are the same on every World ID issuer today. Read+// `.well-known/openid-configuration` if an issuer ever differs.+let jwks: {+ issuer: string;+ set: ReturnType<typeof createRemoteJWKSet>;+} | null = null;++function issuerJwks(): ReturnType<typeof createRemoteJWKSet> {+ if (jwks?.issuer !== issuer()) {+ jwks = {+ issuer: issuer(),+ set: createRemoteJWKSet(new URL(`${issuer()}/.well-known/jwks.json`)),+ };+ }+ return jwks.set;+}++async function postToIssuer(+ path: string,+ params: Record<string, string>,+): Promise<{ status: number; body: Record<string, unknown> }> {+ const basic = Buffer.from(+ `${encodeURIComponent(config.WORLD_ID_CLIENT_ID!)}:${encodeURIComponent(+ config.WORLD_ID_CLIENT_SECRET!,+ )}`,+ ).toString("base64");+ const res = await fetch(`${issuer()}${path}`, {+ method: "POST",+ headers: {+ Authorization: `Basic ${basic}`,+ "Content-Type": "application/x-www-form-urlencoded",+ Accept: "application/json",+ },+ body: new URLSearchParams(params).toString(),+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),+ });+ let body: Record<string, unknown> = {};+ try {+ const parsed = await res.json();+ if (parsed && typeof parsed === "object") body = parsed;+ } catch {+ // Non-JSON bodies are handled by status.+ }+ return { status: res.status, body };+}++export type WorldIdDeviceStart =+ | {+ ok: true;+ deviceHandle: string;+ userCode: string;+ verificationUri: string;+ verificationUriComplete?: string;+ expiresIn: number;+ interval: number;+ }+ | { ok: false; status: number; error: string };++export async function startWorldIdDeviceFlow(): Promise<WorldIdDeviceStart> {+ let res: Awaited<ReturnType<typeof postToIssuer>>;+ try {+ res = await postToIssuer("/api/v1/device_authorization", {+ scope: "openid",+ });+ } catch {+ return { ok: false, status: 502, error: "temporarily_unavailable" };+ }+ const { body } = res;+ if (+ res.status !== 200 ||+ typeof body.device_code !== "string" ||+ typeof body.user_code !== "string" ||+ typeof body.verification_uri !== "string"+ ) {+ return res.status === 429+ ? { ok: false, status: 429, error: "slow_down" }+ : { ok: false, status: 502, error: "temporarily_unavailable" };+ }+ return {+ ok: true,+ deviceHandle: sealDeviceCode(body.device_code),+ userCode: body.user_code,+ verificationUri: body.verification_uri,+ ...(typeof body.verification_uri_complete === "string"+ ? { verificationUriComplete: body.verification_uri_complete }+ : {}),+ expiresIn: typeof body.expires_in === "number" ? body.expires_in : 1200,+ interval: typeof body.interval === "number" ? body.interval : 5,+ };+}++export type WorldIdDevicePoll =+ | { outcome: "approved"; credential: string; expiresAt: number }+ | { outcome: "not_allowed"; subjectHash: string }+ | { outcome: "error"; status: number; error: string };++// The verification failures that mean the token itself is bad. Anything else+// (a JWKS fetch that times out, errors or returns garbage) is the issuer being+// unavailable and must not be reported as a rejected token.+const TOKEN_REJECTIONS = [+ errors.JWTClaimValidationFailed,+ errors.JWTExpired,+ errors.JWTInvalid,+ errors.JWSInvalid,+ errors.JWSSignatureVerificationFailed,+ errors.JOSEAlgNotAllowed,+ errors.JOSENotSupported,+ errors.JWKSNoMatchingKey,+ errors.JWKSMultipleMatchingKeys,+];++/**+ * Validates a World ID ID token and returns its subject hash, or null when the+ * token is rejected. Throws when the issuer's keys can't be fetched.+ */+export async function verifyWorldIdIdToken(+ idToken: string,+): Promise<string | null> {+ try {+ const { payload } = await jwtVerify(idToken, issuerJwks(), {+ issuer: issuer(),+ audience: config.WORLD_ID_CLIENT_ID!,+ algorithms: ["RS256"],+ requiredClaims: ["sub", "exp", "auth_time"],+ });+ if (payload.acr !== ORB_ACR || typeof payload.sub !== "string") {+ return null;+ }+ return worldIdSubjectHash(issuer(), payload.sub);+ } catch (error) {+ if (TOKEN_REJECTIONS.some(rejection => error instanceof rejection)) {+ return null;+ }+ throw error;+ }+}++export async function pollWorldIdDeviceFlow(+ deviceHandle: unknown,+): Promise<WorldIdDevicePoll> {+ const deviceCode = openDeviceHandle(deviceHandle);+ if (!deviceCode) {+ return { outcome: "error", status: 400, error: "invalid_request" };+ }++ let res: Awaited<ReturnType<typeof postToIssuer>>;+ try {+ res = await postToIssuer("/api/v1/token", {+ grant_type: DEVICE_CODE_GRANT,+ device_code: deviceCode,+ });+ } catch {+ return { outcome: "error", status: 502, error: "temporarily_unavailable" };+ }++ if (res.status === 200 && typeof res.body.id_token === "string") {+ let subjectHash: string | null;+ try {+ subjectHash = await verifyWorldIdIdToken(res.body.id_token);+ } catch {+ return {+ outcome: "error",+ status: 502,+ error: "temporarily_unavailable",+ };+ }+ if (!subjectHash) {+ return { outcome: "error", status: 400, error: "invalid_grant" };+ }+ if (isWorldIdSubjectDenied(subjectHash)) {+ return { outcome: "error", status: 403, error: "access_denied" };+ }+ if (!isWorldIdSubjectAllowed(subjectHash)) {+ return { outcome: "not_allowed", subjectHash };+ }+ return { outcome: "approved", ...mintWorldIdCredential(subjectHash) };+ }++ // RFC 8628 poll errors pass through so the client can follow its stop rules+ // (authorization_pending and slow_down keep polling, the rest stop).+ if (res.status === 400 && typeof res.body.error === "string") {+ return { outcome: "error", status: 400, error: res.body.error };+ }+ return { outcome: "error", status: 502, error: "temporarily_unavailable" };+}diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex feeaebbeb..5bbe43e89 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -13,6 +13,10 @@ import { feedbackController } from "../controllers/v2/feedback/controller";import { searchFeedbackController } from "../controllers/v2/search-feedback";import { scrapeController } from "../controllers/v2/scrape";import { keylessEligibilityController } from "../controllers/v2/keyless-eligibility";+import {+ keylessWorldIdDeviceController,+ keylessWorldIdTokenController,+} from "../controllers/v2/keyless-world-id";import {parseController,parseMultipartPayloadMiddleware,@@ -184,6 +188,11 @@ v2Router.use(requestTimingMiddleware("v2"));// inside the controller; no auth middleware.v2Router.get("/keyless/eligibility", wrap(keylessEligibilityController));+// World ID verification for the keyless tier: a device flow that ends in a+// credential for the x-firecrawl-world-id header. 404 unless configured.+v2Router.post("/keyless/world-id/device", wrap(keylessWorldIdDeviceController));+v2Router.post("/keyless/world-id/token", wrap(keylessWorldIdTokenController));+registerMcpActionLogReadRoute(v2Router,authMiddleware(RateLimiterMode.Account),