Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

Keyless: per-human bucket for World ID verified callers (#4934)

Erik Engervall1006903e5df0
diff --git a/apps/api/package.json b/apps/api/package.json
index 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.yaml
index 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.12
version: 1.0.12
+ jose:
+ specifier: ^6.2.12
+ version: 6.2.12
jsdom:
specifier: ^29.1.1
version: 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:
+
dependencies:
config-chain: 1.1.13
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 the
diff --git a/apps/api/src/lib/world-id.ts b/apps/api/src/lib/world-id.ts
new file mode 100644
index 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.ts
index 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),