feat(world-id): verify with World ID for a keyless bucket of your own

ER
20h ago
+587-23

What

Adds firecrawl world-id (hidden for now) so keyless users can verify with World ID and get a keyless bucket keyed on their World ID instead of their IP. This is the client side of https://github.com/firecrawl/firecrawl/pull/4934.

  • firecrawl world-id verify runs the API's device flow: POST /v2/keyless/world-id/device, prints the link and code (and opens the link unless --no-browser), then polls POST /v2/keyless/world-id/token with the device_handle. It follows the RFC 8628 poll errors (authorization_pending, slow_down, access_denied, expired_token) and stores the returned fcwid_ credential in world-id.json next to credentials.json (mode 0600).
  • firecrawl world-id status and firecrawl world-id clear.
  • Every keyless request (keylessRequest, keylessGet, keyless parse and interact) sends x-firecrawl-world-id while the credential is unexpired. FIRECRAWL_WORLD_ID overrides the stored credential. Requests with an API key never send it.
  • When the API has World ID turned off the endpoints answer 404; the CLI says "World ID verification is not enabled on this Firecrawl API." and stores nothing.
  • Version 1.27.0.

The command is registered hidden, like sql, because the API side is off by default. Unhide it once World ID is enabled on the API.

Tests

  • src/__tests__/commands/world-id.test.ts: device flow to a stored credential, 404 when off, slow_down backoff and a declined approval, a World ID outside the allowlist, code expiry, the header on keyless POST and GET only while unexpired, env override, file mode.
  • pnpm test (699 passed), pnpm run type-check, pnpm run format:check.

Open in Capy

Summary by cubic

Adds firecrawl world-id so keyless users can verify with World ID and get a keyless bucket keyed on their World ID instead of their IP. The command stays hidden until the API side is enabled; version bumps to 1.27.0.

Details

  • firecrawl world-id verify runs the API device flow, shows the link and code, and opens the browser without a shell unless --no-browser; status and clear round out the command.
  • Keyless requests send the stored fcwid_ credential as x-firecrawl-world-id until it expires; FIRECRAWL_WORLD_ID overrides the stored credential, and API-key requests never send it.
  • Polling retries transient transport errors and honors slow_down backoff, refuses credentials without a valid expiry, and the browser opener rejects non-web URLs.
  • When the API has World ID disabled or the World ID isn't on its allowlist, the CLI reports it and stores nothing.