Introducing a new way to review your PRs.

Read the announcement

lockfale / osint-framework

OSINT Framework

View on GitHub

8 documents · Updated Nov 16, 2026

docs / cloudflare-worker-runtime

Cloudflare Worker Runtime

Overview

The Cloudflare Worker runtime for the OSINT Framework site is configured in wrangler.jsonc and enters through src/worker.js. wrangler.jsonc names the Worker osint-framework, sets main to src/worker.js, pins compatibility_date to 2025-09-27, enables observability, turns on nodejs_compat, binds static assets from the public directory, and binds the CLICK_DATA KV namespace used by the API routes.

Every request reaches the default export's fetch(request, env) handler in src/worker.js. The handler first handles any OPTIONS request as a CORS preflight, returning 204 with the allowlist-derived CORS headers. It then matches four API routes exactly:

  • POST /api/track records a deduplicated click for a tool in CLICK_DATA.
  • GET /api/tool-stats reads click and rating aggregates for a tool from CLICK_DATA.
  • POST /api/vote updates a session-scoped rating and aggregate rating counters in CLICK_DATA.
  • POST /api/report records a session-scoped report, and after enough unique reports may call the GitHub Issues API using env.GITHUB_TOKEN.

All other paths fall through to env.ASSETS.fetch(request) in src/worker.js, so the Worker owns both the API surface and static file serving for the public site. The static asset source is public via wrangler.jsonc; changes to the generated or committed public site/data are served only through this assets binding unless they call one of the exact /api/* routes above.

API responses are JSON produced by jsonResponse() in src/worker.js, which always attaches CORS headers. The allowed origins are https://osintframework.com, https://www.osintframework.com, and any origin ending in .osintframework.com; other origins receive https://osintframework.com as the allow-origin value rather than being reflected. The Worker does not set cookies or store IP addresses. Client identity is represented by a client-supplied session_hash, which is validated with tool_id and then used in KV keys for rate limiting, deduplication, ratings, and reports.

CLICK_DATA is the state store for runtime interaction data. src/worker.js writes click counters under clicks:<tool_id>, one-hour click deduplication under dedup:<session_hash>:<tool_id>, per-minute rate limits under ratelimit:<session_hash>:<minute>, rating aggregates under ratings:sum:<tool_id> and ratings:count:<tool_id>, user ratings under rating:<session_hash>:<tool_id>, report counters under reportcount:<tool_id>:<report_type>, seven-day report deduplication under reported:<session_hash>:<tool_id>:<report_type>, and report notification markers under github_issue_created:<tool_id>:<report_type>. wrangler.jsonc binds this namespace as CLICK_DATA with the production namespace id cdb975e31e58416ba9476c38897fa61c.

Routing / Ownership

  • src/worker.js: Worker request entrypoint, exact API route dispatch, CORS handling, KV-backed click/rating/report behavior, GitHub issue creation, and final fallback to env.ASSETS.fetch(request).
  • wrangler.jsonc: deployment/runtime configuration for the Worker entrypoint, Cloudflare compatibility settings, observability, static asset directory (public), and the CLICK_DATA KV binding.

Coupling

  • If wrangler.jsonc changes the main entrypoint, verify the replacement still exports a default object with fetch(request, env) and still falls back to env.ASSETS.fetch(request) for non-API paths; otherwise the static public site will stop being served by the Worker.
  • If wrangler.jsonc changes the assets.directory, verify the public site build/data output still lands in that directory; src/worker.js has no alternate static-file lookup and delegates unmatched requests only to the Cloudflare ASSETS binding.
  • If the CLICK_DATA binding name changes in wrangler.jsonc, update every env.CLICK_DATA access in src/worker.js; route handlers do not guard for a missing binding before calling KV methods.
  • If client-side code changes API request shapes, keep src/worker.js validators in sync: /api/track, /api/vote, and /api/report require tool_id and session_hash, /api/vote only accepts half-star numeric ratings from 0 through 5 or null, and /api/report only accepts dead_link, paywalled, or incorrect_info.
  • If deployment relies on automated community reports, configure the GITHUB_TOKEN secret alongside the Worker; src/worker.js silently skips GitHub issue creation when env.GITHUB_TOKEN is absent even after the report threshold is reached.

Risks

  • src/worker.js updates counters in CLICK_DATA with read-modify-write sequences rather than atomic increments. If multiple requests for the same tool_id or report type arrive concurrently, click, rating, or report counts can lose updates.
  • src/worker.js treats every OPTIONS request as a successful CORS preflight before route matching. If a future non-CORS OPTIONS endpoint is added under the same Worker, it will be shadowed unless the top-level preflight handling is narrowed.