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/trackrecords a deduplicated click for a tool inCLICK_DATA.GET /api/tool-statsreads click and rating aggregates for a tool fromCLICK_DATA.POST /api/voteupdates a session-scoped rating and aggregate rating counters inCLICK_DATA.POST /api/reportrecords a session-scoped report, and after enough unique reports may call the GitHub Issues API usingenv.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 theCLICK_DATAKV binding.
Coupling
- If wrangler.jsonc changes the
mainentrypoint, verify the replacement still exports a default object withfetch(request, env)and still falls back toenv.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 CloudflareASSETSbinding. - If the
CLICK_DATAbinding name changes in wrangler.jsonc, update everyenv.CLICK_DATAaccess 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/reportrequiretool_idandsession_hash,/api/voteonly accepts half-star numeric ratings from0through5ornull, and/api/reportonly acceptsdead_link,paywalled, orincorrect_info. - If deployment relies on automated community reports, configure the
GITHUB_TOKENsecret alongside the Worker; src/worker.js silently skips GitHub issue creation whenenv.GITHUB_TOKENis absent even after the report threshold is reached.
Risks
- src/worker.js updates counters in
CLICK_DATAwith read-modify-write sequences rather than atomic increments. If multiple requests for the sametool_idor report type arrive concurrently, click, rating, or report counts can lose updates. - src/worker.js treats every
OPTIONSrequest as a successful CORS preflight before route matching. If a future non-CORSOPTIONSendpoint is added under the same Worker, it will be shadowed unless the top-level preflight handling is narrowed.