feat(keyless): forward a World ID credential on keyless requests

ER
5h ago
+97-4

What

Keyless requests can carry a World ID credential (fcwid_...) as x-firecrawl-world-id, which https://github.com/firecrawl/firecrawl/pull/4934 uses to count the request against the verified human's own keyless bucket instead of the IP.

  • stdio: FIRECRAWL_WORLD_ID sets it (new worldIdCredential server option).
  • HTTP: the authenticate wrapper copies an x-firecrawl-world-id request header onto the session (SessionData.worldIdCredential), the same way it records the client User-Agent, so embedders that admit keyless sessions forward it. A session value wins over the option.
  • Only keylessPost sends it. Requests with an API key or OAuth token never do.
  • The API ignores the header unless World ID is enabled there, so this changes nothing until then.
  • Version 3.31.0 with a CHANGELOG entry.

Tests

  • tests/server-hooks.test.mjs: a keyless session sends the header from the request, else the option; a keyed session sends neither.
  • Full node --test tests/*.test.mjs (172 passed) and pnpm run lint.

Open in Capy

Summary by cubic

Forwards a World ID credential (fcwid_...) as x-firecrawl-world-id on keyless requests so the API can count them against the verified human's own keyless bucket instead of the IP.

  • stdio servers read FIRECRAWL_WORLD_ID into the new worldIdCredential option; HTTP servers copy the x-firecrawl-world-id request header onto the session, and a session value wins over the option.
  • Only keyless requests send the header — requests with an API key or OAuth token never do, and the API ignores it unless World ID is enabled there.
  • Bumps the version to 3.34.0 with a CHANGELOG entry and tests covering header, option, keyed, and OAuth cases.