feat(worker): Turnstile verification gate for the web app

Until a visitor passes a Cloudflare Turnstile check, app pages ("/" is
now Worker-first too) answer with a self-contained verification page and
/img covers with 403, so a browser loads nothing of the site before the
check. Passing sets an HttpOnly, host-only cookie (HMAC of its issue
time) good for BOT_GATE_TTL_HOURS (48). The page then reloads into the
link that was asked for, and the legal gate follows as before.

- /assets, /data (desktop/Android apps, CC BY reuse), robots, sitemap,
  og image, /api/* and /admin* stay ungated.
- Verified bots pass with the token a zone Transform Rule adds
  (x-fig-known-bot); clients that only claim to be a search crawler get
  a 503, never the noindex page.
- Fails open: it needs BOT_GATE="on", the Turnstile keys, GATE_SECRET
  and GATE_BOT_TOKEN; deleting GATE_SECRET switches it off at once.
- POST /api/verify: same-origin, RL_GATE (IPv4 / IPv6 /64), siteverify
  with action "gate". GET reports the pass for the page and the SPA.
- turnstile.ts: siteverify shared with Suggest, which now also checks
  the hostname and action (a token from one page can't be spent on the
  other) and answers 503 when Turnstile is unreachable.
- SPA: a tab whose pass ran out re-checks when shown again or when a
  cover fails, and reloads into the verification page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-09-24 17:56:33 +07:00
1 parent 3ce23dec17
commit 2c2d990f33
23 files changed
+1387 -65

No files matched your search

+7 -1
View File
@@ -1,5 +1,7 @@
import { useState } from 'react'
import type { ImgHTMLAttributes } from 'react'
import { recheckGate } from '@/lib/gate'
import { isTauri } from '@/lib/runtime'
import { thumbUrl, type ThumbWidth } from '@/lib/thumbnail'
import { cn } from '@/lib/utils'
@@ -26,7 +28,11 @@ export function GameThumb({ src, size = 160, alt = '', className, ...rest }: Gam
alt={alt}
className={className}
referrerPolicy="no-referrer"
onError={() => setFailedSrc(src)}
onError={() => {
setFailedSrc(src)
// Covers answer 403 once the verification pass ran out (lib/gate.ts).
if (!isTauri()) void recheckGate()
}}
{...rest}
/>
)
+24
View File
@@ -0,0 +1,24 @@
import { describe, expect, it } from 'vitest'
import { readHint, shouldReload } from './gate'
describe('readHint', () => {
it.each([
[null, null],
['', null],
['{', null],
['null', null],
['{"until":"soon"}', null],
['{"until":1790000000000}', 1790000000000],
])('%j → %j', (raw, until) => {
expect(readHint(raw)).toBe(until)
})
})
describe('shouldReload', () => {
it('reloads only when the gate is on and this browser has no pass', () => {
expect(shouldReload({ enabled: true, valid: false, ttl: 0 })).toBe(true)
expect(shouldReload({ enabled: true, valid: true, ttl: 60 })).toBe(false)
expect(shouldReload({ enabled: false, valid: true, ttl: 0 })).toBe(false)
expect(shouldReload({ enabled: false, valid: false, ttl: 0 })).toBe(false)
})
})
+86
View File
@@ -0,0 +1,86 @@
/**
* Web only. The Worker serves the app only to visitors who passed its
* verification check (worker/gate.ts); a pass lasts BOT_GATE_TTL_HOURS. A tab
* kept open past that — or opened before the gate was switched on — would see
* its covers fail with 403. So when the tab comes back into view (or a cover
* fails) and the pass may be over, ask the Worker, and reload into the
* verification page if the pass is gone.
*/
import { guardedReload } from './reload'
/** localStorage: `{until}` (ms), when the current pass runs out; written by the verification page too. */
const HINT_KEY = 'webapp.gate'
const MIN_GAP = 5 * 60_000
export interface GateStatus {
enabled: boolean
valid: boolean
/** Seconds the pass has left. */
ttl: number
}
export function readHint(raw: string | null): number | null {
if (!raw) return null
try {
const until: unknown = (JSON.parse(raw) as { until?: unknown } | null)?.until
return typeof until === 'number' && Number.isFinite(until) ? until : null
} catch {
return null
}
}
export function shouldReload(status: GateStatus): boolean {
return status.enabled && !status.valid
}
function storage(): Storage | null {
try {
return window.localStorage
} catch {
return null
}
}
let lastCheck = 0
/** Ask the Worker whether this browser still has a pass (at most once per 5 minutes). */
export async function recheckGate(): Promise<void> {
const now = Date.now()
if (now - lastCheck < MIN_GAP) return
lastCheck = now
let status: GateStatus
try {
const res = await fetch('/api/verify', { cache: 'no-store', credentials: 'same-origin' })
if (!res.ok) return
status = (await res.json()) as GateStatus
} catch {
return
}
const store = storage()
if (shouldReload(status)) {
store?.removeItem(HINT_KEY)
guardedReload()
return
}
// Gate off, or a pass by other means than the cookie: look again in a while.
const until = status.enabled && status.ttl > 0 ? now + status.ttl * 1000 : now + MIN_GAP
try {
store?.setItem(HINT_KEY, JSON.stringify({ until }))
} catch {
/* storage full or blocked: we'll just ask again next time */
}
}
/** Re-check when the tab is shown again (or restored from the back/forward cache) and the pass may be over. */
export function watchGate(): void {
const check = () => {
const until = readHint(storage()?.getItem(HINT_KEY) ?? null)
if (until === null || Date.now() >= until) void recheckGate()
}
document.addEventListener('visibilitychange', () => {
if (document.visibilityState === 'visible') check()
})
window.addEventListener('pageshow', (event) => {
if (event.persisted) check()
})
}
+18
View File
@@ -0,0 +1,18 @@
const RELOAD_KEY = 'reloaded-after-deploy'
/**
* Reload the page, at most once per 30 s: if the reload doesn't fix things the
* page shows its error instead of looping. Without sessionStorage there is no
* loop guard, so no automatic reload either. Returns whether it reloaded.
*/
export function guardedReload(): boolean {
try {
const last = Number(sessionStorage.getItem(RELOAD_KEY)) || 0
if (Date.now() - last < 30_000) return false
sessionStorage.setItem(RELOAD_KEY, String(Date.now()))
} catch {
return false
}
window.location.reload()
return true
}
+8 -13
View File
@@ -8,9 +8,11 @@ import { get, set, del } from 'idb-keyval'
import App from './App'
import { AppRouter } from './components/app-router'
import { APP } from './lib/about'
import { watchGate } from './lib/gate'
import { initI18n } from './lib/i18n'
import { isTauri } from './lib/runtime'
import { clearLegacyCredentials, redirectLegacyHashRoute } from './lib/legacy'
import { guardedReload } from './lib/reload'
import '@fontsource-variable/geist'
import '@fontsource-variable/geist-mono'
import './index.css'
@@ -49,24 +51,17 @@ const PERSISTED_KEYS = new Set(['db', 'deleted', 'count-history'])
const CACHE_BUSTER = `${APP.version}:data-v1`
clearLegacyCredentials()
if (!isTauri()) redirectLegacyHashRoute()
if (!isTauri()) {
redirectLegacyHashRoute()
watchGate()
}
// A deploy replaces hashed chunk files; a tab opened before it would fail to
// lazy-load a route. Reload to pick up the new build — at most once per 30 s,
// so a chunk that still fails after the reload shows the error page (with its
// Reload button) instead of looping. Without storage there is no loop guard,
// so no automatic reload either.
const RELOAD_KEY = 'reloaded-after-deploy'
// Reload button) instead of looping.
window.addEventListener('vite:preloadError', (event) => {
try {
const last = Number(sessionStorage.getItem(RELOAD_KEY)) || 0
if (Date.now() - last < 30_000) return
sessionStorage.setItem(RELOAD_KEY, String(Date.now()))
} catch {
return
}
event.preventDefault()
window.location.reload()
if (guardedReload()) event.preventDefault()
})
initI18n()
+8 -2
View File
@@ -1,11 +1,12 @@
/* eslint-disable */
// Generated by Wrangler by running `wrangler types --env-file=types.env --strict-vars=false` (hash: f483b1f0658395bde79d44bd8ede839a)
// Generated by Wrangler by running `wrangler types --env-file=types.env --strict-vars=false` (hash: 46b8bf594a62e9471799a0f004146e00)
// Runtime types generated with workerd@1.20260917.1 2026-09-15
interface __BaseEnv_Env {
THUMBS: R2Bucket;
DB: D1Database;
RL_SUGGEST: RateLimit;
RL_INGEST: RateLimit;
RL_GATE: RateLimit;
ASSETS: Fetcher;
SITE_ORIGIN: string;
GITHUB_REPO: string;
@@ -16,6 +17,8 @@ interface __BaseEnv_Env {
ACCESS_AUD_ADMIN: string;
ACCESS_AUD_INGEST: string;
TURNSTILE_SITEKEY: string;
BOT_GATE: string;
BOT_GATE_TTL_HOURS: string;
}
declare namespace Cloudflare {
interface GlobalProps {
@@ -26,6 +29,7 @@ declare namespace Cloudflare {
DB: D1Database;
RL_SUGGEST: RateLimit;
RL_INGEST: RateLimit;
RL_GATE: RateLimit;
ASSETS: Fetcher;
SITE_ORIGIN: string;
GITHUB_REPO: string;
@@ -36,6 +40,8 @@ declare namespace Cloudflare {
ACCESS_AUD_ADMIN: string;
ACCESS_AUD_INGEST: string;
TURNSTILE_SITEKEY: string;
BOT_GATE: string;
BOT_GATE_TTL_HOURS: string;
}
interface Env extends __BaseEnv_Env {}
}
@@ -44,7 +50,7 @@ type StringifyValues<EnvType extends Record<string, unknown>> = {
[Binding in keyof EnvType]: EnvType[Binding] extends string ? EnvType[Binding] : string;
};
declare namespace NodeJS {
interface ProcessEnv extends StringifyValues<Pick<Cloudflare.Env, "SITE_ORIGIN" | "GITHUB_REPO" | "BOT_UA" | "GH_APP_ID" | "GH_APP_INSTALLATION_ID" | "ACCESS_TEAM_DOMAIN" | "ACCESS_AUD_ADMIN" | "ACCESS_AUD_INGEST" | "TURNSTILE_SITEKEY">> {}
interface ProcessEnv extends StringifyValues<Pick<Cloudflare.Env, "SITE_ORIGIN" | "GITHUB_REPO" | "BOT_UA" | "GH_APP_ID" | "GH_APP_INSTALLATION_ID" | "ACCESS_TEAM_DOMAIN" | "ACCESS_AUD_ADMIN" | "ACCESS_AUD_INGEST" | "TURNSTILE_SITEKEY" | "BOT_GATE" | "BOT_GATE_TTL_HOURS">> {}
}
// Begin runtime types
+1 -3
View File
@@ -23,7 +23,7 @@ import { catalogUrls, deletedGames, type DataSource } from './data'
import { ACCESS_CONFIG, GITHUB_CONFIG, missingConfig, type WorkerEnv } from './env'
import { GitHubError } from './github'
import type { GitHubEnv } from './github'
import { HttpError, SECURITY_HEADERS, errorResponse, isObject, json, readJson } from './http'
import { HttpError, LOCAL_HOSTS, SECURITY_HEADERS, errorResponse, isObject, json, readJson } from './http'
import { r2Key } from './img'
import { autoFlags, classify, type CandidateRow, type CandidateStatus, type QueueStore } from './queue'
import { editCatalog, queueForIngest, type CatalogEditResult } from './repo'
@@ -74,8 +74,6 @@ function githubRepo(env: WorkerEnv): RepoOps | null {
}
}
const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]'])
async function maintainer(request: Request, env: WorkerEnv): Promise<string> {
// `wrangler dev` only: Access does not run on localhost. Set DEV_ADMIN_EMAIL
// in .dev.vars; it is ignored for every other host.
+4
View File
@@ -9,6 +9,10 @@ interface Secrets {
GH_APP_PRIVATE_KEY?: string // GitHub App PEM (PKCS#1 as downloaded, or PKCS#8)
ADMIN_EMAILS?: string // comma-separated maintainer emails
TURNSTILE_SECRET?: string
/** 32+ random characters: signs the verification-gate cookie (gate.ts). */
GATE_SECRET?: string
/** 32+ random characters: the value the zone's Transform Rule sends for verified bots (gate.ts). */
GATE_BOT_TOKEN?: string
/** Local `wrangler dev` only (admin without Access); ignored off localhost. */
DEV_ADMIN_EMAIL?: string
}
+110
View File
@@ -0,0 +1,110 @@
import { describe, expect, it } from 'vitest'
import indexHtml from '../index.html?raw'
import { challengePage, crawlerUnavailable, gateCsp, pickLanguage, renderChallenge, SOCIAL_TAGS } from './gate-page'
const OPTIONS = { sitekey: '0x4AAA-site', ttlHours: 48 }
function page(path = '/games', init: RequestInit = {}) {
return challengePage(new Request(`https://freeitchgames.win${path}`, init), OPTIONS)
}
function nonceOf(res: Response): string {
const m = /'nonce-([^']+)'/.exec(res.headers.get('content-security-policy') ?? '')
if (!m) throw new Error('no nonce in the CSP')
return m[1]
}
describe('challengePage', () => {
it('is a no-store, noindex HTML page with the security headers', () => {
const res = page()
expect(res.status).toBe(200)
expect(res.headers.get('content-type')).toBe('text/html; charset=utf-8')
expect(res.headers.get('cache-control')).toBe('no-store')
expect(res.headers.get('x-robots-tag')).toBe('noindex, nofollow')
expect(res.headers.get('x-frame-options')).toBe('DENY')
expect(res.headers.get('cross-origin-opener-policy')).toBe('same-origin')
expect(res.headers.get('x-content-type-options')).toBe('nosniff')
expect(res.headers.get('etag')).toBeNull()
})
it('gives every response its own nonce, on each script it runs', async () => {
const a = page()
const b = page()
expect(nonceOf(a)).not.toBe(nonceOf(b))
const html = await a.text()
expect(html.split(`nonce="${nonceOf(a)}"`)).toHaveLength(4) // head script, main script, Turnstile api.js
expect(html).toContain('https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&amp;onload=onGateTurnstile')
})
it('keeps host sources working (no strict-dynamic) and inline styles allowed (no style nonce)', () => {
const csp = gateCsp('abc')
expect(csp).not.toContain('strict-dynamic')
expect(csp).toContain("style-src 'unsafe-inline'")
expect(csp).toContain("script-src 'nonce-abc' https://challenges.cloudflare.com https://static.cloudflareinsights.com")
expect(csp).toContain('frame-src https://challenges.cloudflare.com')
expect(csp).toContain("frame-ancestors 'none'")
})
it('answers HEAD without a body', async () => {
const res = page('/', { method: 'HEAD' })
expect(res.status).toBe(200)
expect(await res.text()).toBe('')
})
it('never reflects the request path or query', async () => {
const html = await page('/games/%3Cscript%3Ealert(1)%3C/script%3E?q=%3Cimg%20src%3Dx%3E').text()
expect(html).not.toContain('alert(1)')
expect(html).not.toContain('<img')
})
it('carries the og: and twitter: tags of index.html, so link previews keep working', () => {
const tags = [...indexHtml.matchAll(/<meta (property|name)="((?:og|twitter):[^"]+)" content="([^"]*)"/g)].map(
(m) => [m[1], m[2], m[3]],
)
expect(tags.length).toBeGreaterThan(10)
expect(SOCIAL_TAGS).toEqual(tags)
})
it('embeds the site key as JSON and scripts that compile', () => {
const html = renderChallenge('en', { ...OPTIONS, nonce: 'n' })
const config = /<script type="application\/json" id="gate-config">([\s\S]*?)<\/script>/.exec(html)
expect(JSON.parse(config?.[1] ?? '{}')).toMatchObject({ sitekey: '0x4AAA-site' })
const scripts = [...html.matchAll(/<script nonce="n">([\s\S]*?)<\/script>/g)].map((m) => m[1])
expect(scripts).toHaveLength(2)
for (const source of scripts) expect(() => new Function(source)).not.toThrow()
})
it('renders both languages and picks the first one from Accept-Language', async () => {
const vi = await challengePage(
new Request('https://freeitchgames.win/', { headers: { 'accept-language': 'vi-VN,vi;q=0.9,en;q=0.8' } }),
OPTIONS,
).text()
expect(vi).toContain('<html lang="vi">')
expect(vi).toContain('Kiểm tra nhanh trước khi vào trang')
expect(vi).toContain('Quick check before you continue')
expect(vi).toContain('48 giờ')
})
})
describe('pickLanguage', () => {
it.each([
[null, 'en'],
['vi-VN,vi;q=0.9,en-US;q=0.8,en;q=0.7', 'vi'],
['en-US,en;q=0.9,vi;q=0.8', 'en'],
['fr-FR,fr;q=0.9,vi;q=0.5', 'vi'],
['fr', 'en'],
['vi;q=0.2, en;q=0.9', 'en'],
])('%j → %s', (header, lang) => {
expect(pickLanguage(header)).toBe(lang)
})
})
describe('crawlerUnavailable', () => {
it('is a temporary 503 (not a noindex page), so a broken bypass never de-indexes the site', () => {
const res = crawlerUnavailable(new Request('https://freeitchgames.win/games'))
expect(res.status).toBe(503)
expect(res.headers.get('retry-after')).toBe('3600')
expect(res.headers.get('cache-control')).toBe('no-store')
expect(res.headers.get('x-robots-tag')).toBeNull()
})
})
+280
View File
@@ -0,0 +1,280 @@
/**
* The verification page of the bot gate (gate.ts). Self-contained: inline CSS
* and scripts, system fonts, the logo inline — nothing of the app loads before
* the visitor passes. Built by the Worker, so it sets its own security headers
* (public/_headers only covers static assets).
*
* Status 200 with noindex: link-preview bots still read the site's og: tags,
* search engines don't index the page. Verified crawlers never see it (gate.ts);
* anything else that claims to be a search crawler gets a 503 instead, so a
* broken bypass rule makes the site look briefly down to Google, not noindexed.
*/
import { PAGE_HEADERS } from './http'
type Lang = 'en' | 'vi'
const PRIVACY = {
en: 'https://github.com/poli0981/free-games-itchio-list/blob/main/docs/PrivacyPolicy.md',
vi: 'https://github.com/poli0981/free-games-itchio-list/blob/main/docs/i18n/vi/PrivacyPolicy.md',
}
// Static text of the page, both languages rendered, CSS shows the one in <html lang>.
const TEXT = {
heading: { en: 'Quick check before you continue', vi: 'Kiểm tra nhanh trước khi vào trang' },
lead: {
en: 'Free Itch Games uses Cloudflare Turnstile to keep automated traffic out. It usually finishes by itself in a few seconds.',
vi: 'Free Itch Games dùng Cloudflare Turnstile để chặn truy cập tự động. Thường chỉ mất vài giây và tự hoàn tất.',
},
note: {
en: 'This browser will not be asked again for {hours} hours.',
vi: 'Trình duyệt này sẽ không phải kiểm tra lại trong {hours} giờ.',
},
privacy: { en: 'Privacy Policy', vi: 'Chính sách quyền riêng tư' },
retry: { en: 'Try again', vi: 'Thử lại' },
noscript: {
en: 'Please enable JavaScript: the site and this check need it.',
vi: 'Vui lòng bật JavaScript: trang web và bước kiểm tra này cần nó.',
},
}
// Messages the script shows while and after checking.
const STATUS: Record<Lang, Record<string, string>> = {
en: {
working: 'Verifying…',
done: 'Verified. Loading the site…',
failed: 'The check did not pass. Please try again.',
unavailable: 'The verification service is not responding. Try again in a minute.',
limited: 'Too many attempts. Wait a minute, then try again.',
cookies: 'Your browser blocked the cookie that remembers this check. Allow cookies for this site, then try again.',
blocked:
'The check could not load. If you use an ad or script blocker, allow challenges.cloudflare.com on this site.',
},
vi: {
working: 'Đang xác minh…',
done: 'Đã xác minh. Đang tải trang…',
failed: 'Kiểm tra chưa thành công. Vui lòng thử lại.',
unavailable: 'Dịch vụ xác minh chưa phản hồi. Hãy thử lại sau một phút.',
limited: 'Thử quá nhiều lần. Đợi một phút rồi thử lại.',
cookies: 'Trình duyệt đã chặn cookie ghi nhớ bước kiểm tra này. Hãy cho phép cookie cho trang này rồi thử lại.',
blocked:
'Không tải được bước kiểm tra. Nếu bạn dùng trình chặn quảng cáo hoặc script, hãy cho phép challenges.cloudflare.com trên trang này.',
},
}
const TITLE: Record<Lang, string> = { en: 'Verifying — Free Itch Games', vi: 'Đang xác minh — Free Itch Games' }
/** The site-wide og:/twitter: tags of index.html (gate-page.test.ts keeps them equal). */
export const SOCIAL_TAGS: ReadonlyArray<readonly ['property' | 'name', string, string]> = [
['property', 'og:type', 'website'],
['property', 'og:site_name', 'Free Itch Games'],
['property', 'og:title', 'Free Itch Games'],
['property', 'og:description', 'A curated, auto-updating catalog of 2,600+ free games on itch.io. Browse, filter, and analyze.'],
['property', 'og:image', 'https://freeitchgames.win/og.png'],
['property', 'og:image:type', 'image/png'],
['property', 'og:image:width', '1200'],
['property', 'og:image:height', '630'],
['property', 'og:image:alt', 'Free Itch Games — 2,600+ free itch.io games, kept fresh'],
['property', 'og:locale', 'en_US'],
['property', 'og:locale:alternate', 'vi_VN'],
['name', 'twitter:card', 'summary_large_image'],
['name', 'twitter:site', '@SkullMute0011'],
['name', 'twitter:creator', '@SkullMute0011'],
['name', 'twitter:title', 'Free Itch Games'],
['name', 'twitter:description', 'A curated, auto-updating catalog of 2,600+ free games on itch.io.'],
['name', 'twitter:image', 'https://freeitchgames.win/og.png'],
]
const LOGO =
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" aria-hidden="true"><rect width="32" height="32" rx="8" fill="#7c5cff"/><path d="M13 2 4 14h7l-1 8 9-12h-7l1-8z" fill="#fff" transform="translate(7.375 7) scale(.75)"/></svg>'
const CSS = `
:root{--bg:#fafaf9;--fg:#17171a;--card:#fff;--border:#e4e4e0;--muted:#5e5e66;--primary:#7c5cff;--danger:#dc2626;--ok:#16a34a;color-scheme:light}
@media (prefers-color-scheme:dark){:root:not(.light){--bg:#0b0b0c;--fg:#ededef;--card:#111114;--border:#232328;--muted:#9b9ba4;--danger:#ef4444;--ok:#22c55e;color-scheme:dark}}
:root.dark{--bg:#0b0b0c;--fg:#ededef;--card:#111114;--border:#232328;--muted:#9b9ba4;--danger:#ef4444;--ok:#22c55e;color-scheme:dark}
html[lang=en] [lang=vi],html[lang=vi] [lang=en]{display:none}
*{box-sizing:border-box}
body{margin:0;min-height:100vh;min-height:100dvh;display:grid;place-items:center;padding:24px 16px;background:var(--bg);color:var(--fg);font:15px/1.55 ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,sans-serif;-webkit-font-smoothing:antialiased}
main{width:100%;max-width:440px;background:var(--card);border:1px solid var(--border);border-radius:14px;padding:28px}
.brand{display:flex;align-items:center;gap:10px;font-weight:600;margin-bottom:22px}
.brand svg{width:28px;height:28px}
h1{font-size:20px;line-height:1.3;margin:0 0 8px;letter-spacing:-.01em}
.lead{margin:0 0 20px;color:var(--muted)}
.widget{min-height:65px}
.status{min-height:1.55em;margin:12px 0 0;font-size:14px;color:var(--muted)}
.status.error{color:var(--danger)}
.status.ok{color:var(--ok)}
button{margin-top:12px;font:inherit;font-size:14px;font-weight:500;padding:8px 16px;border:0;border-radius:8px;background:var(--primary);color:#fff;cursor:pointer}
button:focus-visible,a:focus-visible{outline:2px solid var(--primary);outline-offset:2px}
.foot{margin:22px 0 0;padding-top:16px;border-top:1px solid var(--border);font-size:12.5px;color:var(--muted)}
.foot a{color:inherit;text-underline-offset:2px}
`
// Before first paint: the app's saved theme and language (stores/theme.ts, stores/prefs.ts).
const HEAD_SCRIPT = `(function(){var r=document.documentElement,t='system',l=null;
try{t=JSON.parse(localStorage.getItem('webapp.theme')).state.theme||t}catch(e){}
try{l=JSON.parse(localStorage.getItem('webapp.prefs')).state.language}catch(e){}
var d=t==='dark'||(t!=='light'&&window.matchMedia('(prefers-color-scheme: dark)').matches);
r.classList.add(d?'dark':'light');
if(l==='en'||l==='vi'){r.lang=l;document.title=${JSON.stringify(TITLE).replace(/</g, '\\u003c')}[l]}})();`
// The check itself: render the widget, trade its token for the cookie, make
// sure the cookie stuck, then reload into the page that was asked for.
const MAIN_SCRIPT = `(function(){
var cfg=JSON.parse(document.getElementById('gate-config').textContent);
var root=document.documentElement,status=document.getElementById('status'),retry=document.getElementById('retry');
var widget=null,loaded=false;
function say(key,tone){status.textContent=key?cfg.text[root.lang==='vi'?'vi':'en'][key]:'';status.className='status'+(tone?' '+tone:'')}
function fail(key){say(key,'error');retry.hidden=false}
function check(){return fetch('/api/verify',{credentials:'same-origin',cache:'no-store'}).then(function(r){return r.json()})}
function enter(ttl){
try{localStorage.setItem('webapp.gate',JSON.stringify({until:Date.now()+ttl*1000}))}catch(e){}
say('done','ok');location.reload()}
function verify(token){
say('working');retry.hidden=true;
fetch('/api/verify',{method:'POST',credentials:'same-origin',headers:{'Content-Type':'application/json'},body:JSON.stringify({token:token})})
.then(function(r){
if(!r.ok){fail(r.status===429?'limited':r.status===503?'unavailable':'failed');return}
return r.json().then(function(b){return check().then(function(s){if(s.valid)enter(b.ttl);else fail('cookies')})})})
.catch(function(){fail('unavailable')})}
window.onGateTurnstile=function(){
if(loaded)return;
loaded=true;say('');retry.hidden=true;
widget=window.turnstile.render('#widget',{sitekey:cfg.sitekey,action:'gate',
theme:root.classList.contains('dark')?'dark':'light',language:root.lang==='vi'?'vi':'en',
appearance:'always',size:'flexible',callback:verify,
'error-callback':function(){fail('failed')},
'expired-callback':function(){window.turnstile.reset(widget)},
'timeout-callback':function(){window.turnstile.reset(widget)}})};
retry.addEventListener('click',function(){
retry.hidden=true;say('');
if(window.turnstile&&widget!==null)window.turnstile.reset(widget);else location.reload()});
setTimeout(function(){if(!loaded)fail('blocked')},10000);
window.addEventListener('storage',function(e){
if(e.key==='webapp.gate')check().then(function(s){if(s.valid)location.reload()}).catch(function(){})});
})();`
const TURNSTILE_SRC = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&onload=onGateTurnstile'
const ATTR_ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
function esc(text: string): string {
return text.replace(/[&<>"']/g, (c) => ATTR_ESCAPES[c])
}
function both(pair: Record<Lang, string>, vars: Record<string, string> = {}): string {
const fill = (s: string) => esc(s.replace(/\{(\w+)\}/g, (_, k: string) => vars[k] ?? `{${k}}`))
return `<span lang="en">${fill(pair.en)}</span><span lang="vi">${fill(pair.vi)}</span>`
}
/** The visitor's language for the first paint, from Accept-Language (the script then prefers the app's setting). */
export function pickLanguage(acceptLanguage: string | null): Lang {
const ranked = (acceptLanguage ?? '')
.split(',')
.map((part, i) => {
const [tag, ...params] = part.trim().toLowerCase().split(';')
const q = params.map((p) => /^\s*q=([\d.]+)\s*$/.exec(p)?.[1]).find(Boolean)
return { lang: tag.split('-')[0], q: q === undefined ? 1 : Number(q), i }
})
.filter((e) => e.lang === 'en' || e.lang === 'vi')
.sort((a, b) => b.q - a.q || a.i - b.i)
return ranked[0]?.lang === 'vi' ? 'vi' : 'en'
}
/**
* CSP of the page. No 'strict-dynamic': it would switch off the host sources,
* and the Web Analytics beacon the zone injects into every HTML response has no
* nonce. No nonce in style-src either: it would disable 'unsafe-inline', which
* the page's and Turnstile's style attributes need.
*/
export function gateCsp(nonce: string): string {
return [
"default-src 'none'",
`script-src 'nonce-${nonce}' https://challenges.cloudflare.com https://static.cloudflareinsights.com`,
"style-src 'unsafe-inline'",
"img-src 'self' data:",
"connect-src 'self' https://cloudflareinsights.com",
'frame-src https://challenges.cloudflare.com',
"base-uri 'none'",
"form-action 'none'",
"frame-ancestors 'none'",
].join('; ')
}
function newNonce(): string {
const bytes = crypto.getRandomValues(new Uint8Array(16))
return btoa(String.fromCharCode(...bytes))
}
export interface ChallengeOptions {
sitekey: string
ttlHours: number
/** Tests pass a fixed one; otherwise a fresh random nonce per response. */
nonce?: string
}
/** The HTML of the page; never includes anything from the request but its language. */
export function renderChallenge(lang: Lang, opts: ChallengeOptions & { nonce: string }): string {
const hours = String(opts.ttlHours)
const config = JSON.stringify({ sitekey: opts.sitekey, text: STATUS }).replace(/</g, '\\u003c')
const social = SOCIAL_TAGS.map(([attr, key, content]) => `<meta ${attr}="${key}" content="${esc(content)}">`).join('\n')
return `<!doctype html>
<html lang="${lang}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="robots" content="noindex, nofollow">
<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="#0b0b0c" media="(prefers-color-scheme: dark)">
<meta name="theme-color" content="#fafaf9" media="(prefers-color-scheme: light)">
<title>${esc(TITLE[lang])}</title>
${social}
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<style>${CSS}</style>
<script nonce="${opts.nonce}">${HEAD_SCRIPT}</script>
</head>
<body>
<main>
<div class="brand">${LOGO}<span>Free Itch Games</span></div>
<h1>${both(TEXT.heading)}</h1>
<p class="lead">${both(TEXT.lead)}</p>
<div id="widget" class="widget"></div>
<p id="status" class="status" role="status" aria-live="polite"></p>
<button id="retry" type="button" hidden>${both(TEXT.retry)}</button>
<noscript><p class="status error">${both(TEXT.noscript)}</p></noscript>
<p class="foot">${both(TEXT.note, { hours })} <a lang="en" href="${PRIVACY.en}" rel="noopener">${esc(TEXT.privacy.en)}</a><a lang="vi" href="${PRIVACY.vi}" rel="noopener">${esc(TEXT.privacy.vi)}</a></p>
</main>
<script type="application/json" id="gate-config">${config}</script>
<script nonce="${opts.nonce}">${MAIN_SCRIPT}</script>
<script nonce="${opts.nonce}" src="${esc(TURNSTILE_SRC)}" async defer></script>
</body>
</html>
`
}
/** The verification page for an app page request that has not passed yet. */
export function challengePage(request: Request, opts: ChallengeOptions): Response {
const nonce = opts.nonce ?? newNonce()
const lang = pickLanguage(request.headers.get('accept-language'))
return new Response(request.method === 'HEAD' ? null : renderChallenge(lang, { ...opts, nonce }), {
status: 200,
headers: {
...PAGE_HEADERS,
'Content-Type': 'text/html; charset=utf-8',
'Cache-Control': 'no-store',
'X-Robots-Tag': 'noindex, nofollow',
'Content-Security-Policy': gateCsp(nonce),
},
})
}
/** For a client that claims to be a search crawler but did not come through the verified-bot rule. */
export function crawlerUnavailable(request: Request): Response {
return new Response(request.method === 'HEAD' ? null : 'Temporarily unavailable. Please retry later.\n', {
status: 503,
headers: {
...PAGE_HEADERS,
'Content-Type': 'text/plain; charset=utf-8',
'Cache-Control': 'no-store',
'Retry-After': '3600',
},
})
}
+211
View File
@@ -0,0 +1,211 @@
import { describe, expect, it, vi } from 'vitest'
import type { WorkerEnv } from './env'
import { botPass, checkPass, gateConfig, handleVerify, passCookie, type Gate } from './gate'
import { fakeLimiter, ORIGIN } from './test/fakes'
const SECRET = 's'.repeat(40)
const BOT = 'b'.repeat(40)
const NOW = Date.UTC(2026, 8, 24, 12, 0, 0)
const HOUR = 3600 * 1000
const SITE = new URL(`${ORIGIN}/`)
function env(over: Record<string, unknown> = {}): WorkerEnv {
return {
SITE_ORIGIN: ORIGIN,
TURNSTILE_SITEKEY: '0x4AAA-site',
TURNSTILE_SECRET: 'turnstile-secret',
BOT_GATE: 'on',
BOT_GATE_TTL_HOURS: '48',
GATE_SECRET: SECRET,
GATE_BOT_TOKEN: BOT,
...over,
} as unknown as WorkerEnv
}
function gate(over: Record<string, unknown> = {}, url = SITE): Gate {
const g = gateConfig(env(over), url)
if (!g) throw new Error('gate is off')
return g
}
const request = (headers: Record<string, string> = {}, path = '/games') => new Request(new URL(path, ORIGIN), { headers })
/** The name=value part of a Set-Cookie header, as the browser sends it back. */
const sent = (setCookie: string) => setCookie.split(';')[0]
describe('gateConfig', () => {
it('is on with every setting, for 48 hours', () => {
expect(gate()).toMatchObject({ ttl: 48 * 3600, local: false, sitekey: '0x4AAA-site', siteOrigin: ORIGIN })
})
it.each([
['BOT_GATE off', { BOT_GATE: 'off' }],
['no Turnstile secret', { TURNSTILE_SECRET: undefined }],
['no site key', { TURNSTILE_SITEKEY: '' }],
['no GATE_SECRET', { GATE_SECRET: undefined }],
['a short GATE_SECRET', { GATE_SECRET: 'short' }],
['no GATE_BOT_TOKEN', { GATE_BOT_TOKEN: undefined }],
['a short GATE_BOT_TOKEN', { GATE_BOT_TOKEN: 'short' }],
])('is off (fails open) with %s', (_name, over) => {
vi.spyOn(console, 'warn').mockImplementation(() => {})
expect(gateConfig(env(over), SITE)).toBeNull()
})
it('needs no bot token on localhost', () => {
const local = new URL('http://localhost:8787/')
expect(gateConfig(env({ GATE_BOT_TOKEN: undefined, SITE_ORIGIN: local.origin }), local)).toMatchObject({ local: true })
})
it.each([
['', 48],
['abc', 48],
['0', 48],
['-5', 48],
['0.5', 1],
['24', 24],
['1000', 168],
])('reads BOT_GATE_TTL_HOURS %j as %i hours', (value, hours) => {
expect(gate({ BOT_GATE_TTL_HOURS: value }).ttl).toBe(hours * 3600)
})
})
describe('pass cookie', () => {
it('is a signed, host-only, HttpOnly cookie that passes the gate', async () => {
const setCookie = await passCookie(gate(), NOW)
expect(setCookie).toMatch(
/^__Host-fig_gate=v1\.\d{10}\.[\w-]{43}; Path=\/; Max-Age=172800; Secure; HttpOnly; SameSite=Lax$/,
)
const pass = await checkPass(request({ cookie: `theme=dark; ${sent(setCookie)}` }), gate(), NOW + 1000)
expect(pass).toEqual({ via: 'cookie', remaining: 48 * 3600 - 1 })
})
it('is plain (no Secure, no __Host-) on http://localhost', async () => {
const local = new URL('http://localhost:8787/')
const g = gate({ SITE_ORIGIN: local.origin }, local)
const setCookie = await passCookie(g, NOW)
expect(setCookie).toMatch(/^fig_gate=v1\..*; HttpOnly; SameSite=Lax$/)
expect(setCookie).not.toContain('Secure')
expect((await checkPass(request({ cookie: sent(setCookie) }), g, NOW)).via).toBe('cookie')
})
it.each([
['once the TTL is over', async () => sent(await passCookie(gate(), NOW)), NOW + 48 * HOUR],
['with a tampered signature', async () => sent(await passCookie(gate(), NOW)).replace(/.$/, (c) => (c === 'A' ? 'B' : 'A')), NOW],
['with a tampered issue time', async () => sent(await passCookie(gate(), NOW)).replace(/v1\.(\d+)/, (_, t: string) => `v1.${Number(t) + 60}`), NOW],
['signed with another secret', async () => sent(await passCookie(gate({ GATE_SECRET: 'x'.repeat(40) }), NOW)), NOW],
['issued in the future', async () => sent(await passCookie(gate(), NOW + 10 * 60_000)), NOW],
['in another format', async () => '__Host-fig_gate=v2.1790000000.abc', NOW],
['under another name', async () => sent(await passCookie(gate(), NOW)).replace('__Host-fig_gate', 'fig_gate'), NOW],
])('does not pass %s', async (_name, cookie, at) => {
expect(await checkPass(request({ cookie: await cookie() }), gate(), at)).toEqual({ via: null, remaining: 0 })
})
it('stops passing at once when the TTL is lowered', async () => {
const cookie = sent(await passCookie(gate(), NOW))
expect((await checkPass(request({ cookie }), gate(), NOW + 30 * HOUR)).via).toBe('cookie')
expect((await checkPass(request({ cookie }), gate({ BOT_GATE_TTL_HOURS: '24' }), NOW + 30 * HOUR)).via).toBeNull()
})
it('accepts any valid copy when the cookie is sent twice', async () => {
const cookie = `__Host-fig_gate=v1.1000000000.${'A'.repeat(43)}; ${sent(await passCookie(gate(), NOW))}`
expect((await checkPass(request({ cookie }), gate(), NOW)).via).toBe('cookie')
})
})
describe('verified bots', () => {
it('pass with the token from the Transform Rule', async () => {
expect(await checkPass(request({ 'x-fig-known-bot': BOT }), gate(), NOW)).toEqual({ via: 'bot', remaining: 48 * 3600 })
})
it.each([
['a wrong token', { 'x-fig-known-bot': 'x'.repeat(40) }],
['an empty header', { 'x-fig-known-bot': '' }],
['no header', {}],
])('do not pass with %s', async (_name, headers) => {
expect((await checkPass(request(headers), gate(), NOW)).via).toBeNull()
})
it('never match an empty or short configured token', async () => {
expect(await botPass(request({ 'x-fig-known-bot': '' }), '')).toBe(false)
expect(await botPass(request({ 'x-fig-known-bot': 'abc' }), 'abc')).toBe(false)
})
})
describe('/api/verify', () => {
const VERIFY = new URL(`${ORIGIN}/api/verify`)
const siteverify = (body: unknown) => vi.fn(async () => Response.json(body))
const solved = () => siteverify({ success: true, hostname: 'freeitchgames.win', action: 'gate' })
const post = (body: unknown = { token: 't' }, headers: Record<string, string> = {}) =>
new Request(VERIFY, {
method: 'POST',
headers: { 'content-type': 'application/json', origin: ORIGIN, 'cf-connecting-ip': '203.0.113.9', ...headers },
body: typeof body === 'string' ? body : JSON.stringify(body),
})
const deps = (over: Record<string, unknown> = {}) => ({
fetch: solved() as unknown as typeof fetch,
limiter: fakeLimiter(),
now: () => NOW,
...over,
})
it('trades a Turnstile token for a pass cookie', async () => {
const fetch = solved()
const res = await handleVerify(post(), VERIFY, env(), deps({ fetch }))
expect(res.status).toBe(200)
expect(await res.json()).toEqual({ ttl: 48 * 3600 })
expect(res.headers.get('cache-control')).toBe('no-store')
const setCookie = res.headers.get('set-cookie') ?? ''
expect((await checkPass(request({ cookie: sent(setCookie) }), gate(), NOW)).via).toBe('cookie')
const form = (fetch.mock.calls[0] as unknown as [string, RequestInit])[1].body as FormData
expect(form.get('remoteip')).toBe('203.0.113.9')
})
it.each([
['a cross-site post', post({ token: 't' }, { origin: 'https://evil.example' }), {}, 403],
['a post without Origin', new Request(VERIFY, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"token":"t"}' }), {}, 403],
['a form post', post('token=t', { 'content-type': 'application/x-www-form-urlencoded' }), {}, 415],
['an oversized body', post({ token: 'x'.repeat(5000) }), {}, 413],
['no token', post({}), {}, 400],
['an over-long token', post({ token: 'x'.repeat(2049) }), {}, 400],
['the rate limit', post(), { limiter: fakeLimiter(0) }, 429],
['a failed challenge', post(), { fetch: siteverify({ success: false }) }, 403],
['a token from the Suggest form', post(), { fetch: siteverify({ success: true, hostname: 'freeitchgames.win', action: 'suggest' }) }, 403],
['an unreachable siteverify', post(), { fetch: vi.fn(async () => new Response(null, { status: 500 })) }, 503],
])('refuses %s without a cookie', async (_name, req, over, status) => {
const res = await handleVerify(req, VERIFY, env(), deps(over))
expect(res.status).toBe(status)
expect(res.headers.get('set-cookie')).toBeNull()
})
it('answers 503 while the gate is off and 405 to other methods', async () => {
expect((await handleVerify(post(), VERIFY, env({ BOT_GATE: 'off' }), deps())).status).toBe(503)
expect((await handleVerify(new Request(VERIFY, { method: 'PUT' }), VERIFY, env(), deps())).status).toBe(405)
})
it('rate-limits an IPv6 client by its /64', async () => {
const limiter = fakeLimiter()
await handleVerify(post({ token: 't' }, { 'cf-connecting-ip': '2001:db8:1:2:3:4:5:6' }), VERIFY, env(), deps({ limiter }))
expect(limiter.keys).toEqual(['2001:db8:1:2::/64'])
})
describe('GET (status)', () => {
const status = async (headers: Record<string, string>, e = env()) =>
(await handleVerify(new Request(VERIFY, { headers }), VERIFY, e, deps())).json()
it('reports a valid cookie and how long it has left', async () => {
const cookie = sent(await passCookie(gate(), NOW - HOUR))
expect(await status({ cookie })).toEqual({ enabled: true, valid: true, via: 'cookie', ttl: 47 * 3600 })
})
it('reports a verified bot, and a visitor without a pass', async () => {
expect(await status({ 'x-fig-known-bot': BOT })).toEqual({ enabled: true, valid: true, via: 'bot', ttl: 48 * 3600 })
expect(await status({})).toEqual({ enabled: true, valid: false, via: null, ttl: 0 })
})
it('says the gate is off, and still reports the bot header so the rule can be checked first', async () => {
const off = env({ GATE_SECRET: undefined })
vi.spyOn(console, 'warn').mockImplementation(() => {})
expect(await status({}, off)).toEqual({ enabled: false, valid: true, via: null, ttl: 0 })
expect(await status({ 'x-fig-known-bot': BOT }, off)).toEqual({ enabled: false, valid: true, via: 'bot', ttl: 0 })
})
})
})
+228
View File
@@ -0,0 +1,228 @@
/**
* Bot verification gate (web only). Until a visitor passes a Cloudflare
* Turnstile check, app pages answer with the verification page
* (gate-page.ts) and /img covers with 403. Passing sets an HttpOnly cookie
* that is good for BOT_GATE_TTL_HOURS (default 48).
*
* Not gated: /assets, /data and the other static files (the desktop/Android
* apps and CC BY reuse read /data; a browser only finds the bundles through
* the gated app shell), /api/* and /admin* (Access).
*
* Verified bots (Cloudflare's `cf.client.bot`) pass: a zone Request Header
* Transform Rule sends `x-fig-known-bot: <GATE_BOT_TOKEN>` for them.
*
* Fails open. Nothing is gated unless BOT_GATE is "on" and TURNSTILE_SITEKEY,
* TURNSTILE_SECRET, GATE_SECRET and GATE_BOT_TOKEN (not needed on localhost)
* are all set; `wrangler secret delete GATE_SECRET` is the instant off switch.
*
* GET /api/verify {enabled, valid, via: 'bot'|'cookie'|null, ttl}
* POST /api/verify {token} → {ttl} + Set-Cookie
*/
import { missingConfig, type WorkerEnv } from './env'
import { challengePage, crawlerUnavailable } from './gate-page'
import { HttpError, LOCAL_HOSTS, errorResponse, isObject, json, rateKey, readJson } from './http'
import { siteverify } from './turnstile'
const COOKIE = '__Host-fig_gate'
// http://localhost (wrangler dev) cannot hold a Secure cookie, so no __Host- prefix there.
const LOCAL_COOKIE = 'fig_gate'
const BOT_HEADER = 'x-fig-known-bot'
const MIN_SECRET = 32
const DEFAULT_TTL_HOURS = 48
const MAX_TTL_HOURS = 168
// A cookie issued up to this many seconds "in the future" still counts (clock drift between edges).
const CLOCK_SKEW = 300
const COOKIE_VALUE = /^v1\.(\d{10})\.([A-Za-z0-9_-]{43})$/
// Clients that say they are a search crawler get a 503 rather than the (noindex) page.
const CRAWLER_UA = /googlebot|bingbot|applebot|duckduckbot|yandex|baiduspider|coccocbot/i
export interface Gate {
secret: string
botToken: string
/** Seconds a pass lasts. */
ttl: number
sitekey: string
turnstileSecret: string
siteOrigin: string
local: boolean
}
export type PassVia = 'bot' | 'cookie'
let warned = false
/** The gate's settings, or null when it is off (then nothing is gated). */
export function gateConfig(env: WorkerEnv, url: URL): Gate | null {
if (env.BOT_GATE !== 'on') return null
const local = LOCAL_HOSTS.has(url.hostname)
const missing: string[] = missingConfig(env, ['TURNSTILE_SITEKEY', 'TURNSTILE_SECRET', 'SITE_ORIGIN', 'GATE_SECRET'])
if (!local && !env.GATE_BOT_TOKEN) missing.push('GATE_BOT_TOKEN')
if (env.GATE_SECRET && env.GATE_SECRET.length < MIN_SECRET) missing.push('GATE_SECRET (too short)')
if (!local && env.GATE_BOT_TOKEN && env.GATE_BOT_TOKEN.length < MIN_SECRET) missing.push('GATE_BOT_TOKEN (too short)')
if (missing.length > 0) {
if (!warned) console.warn(`gate: off, not configured (${missing.join(', ')})`)
warned = true
return null
}
const hours = Number(env.BOT_GATE_TTL_HOURS)
const ttlHours = hours > 0 ? Math.min(Math.max(hours, 1), MAX_TTL_HOURS) : DEFAULT_TTL_HOURS
return {
secret: env.GATE_SECRET as string,
botToken: env.GATE_BOT_TOKEN ?? '',
ttl: Math.round(ttlHours * 3600),
sitekey: env.TURNSTILE_SITEKEY,
turnstileSecret: env.TURNSTILE_SECRET as string,
siteOrigin: env.SITE_ORIGIN,
local,
}
}
// ── Cookie ───────────────────────────────────────────────────────────────────
const encoder = new TextEncoder()
// The imported key, cached once it exists (only resolved values are shared
// between requests, never a pending promise).
let hmac: { secret: string; key: CryptoKey } | undefined
async function macKey(secret: string): Promise<CryptoKey> {
if (hmac?.secret === secret) return hmac.key
const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
'sign',
'verify',
])
hmac = { secret, key }
return key
}
const macInput = (iat: number) => encoder.encode(`fig-gate|v1|${iat}`)
function toBase64Url(bytes: ArrayBuffer): string {
return btoa(String.fromCharCode(...new Uint8Array(bytes)))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '')
}
function fromBase64Url(text: string): Uint8Array {
const b64 = text.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (text.length % 4)) % 4)
return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))
}
function cookieValues(request: Request, name: string): string[] {
const header = request.headers.get('cookie') ?? ''
const values: string[] = []
for (const part of header.split(';')) {
const eq = part.indexOf('=')
if (eq > 0 && part.slice(0, eq).trim() === name) values.push(part.slice(eq + 1).trim())
}
return values
}
/** The Set-Cookie value for a visitor who just passed. */
export async function passCookie(gate: Gate, now = Date.now()): Promise<string> {
const iat = Math.floor(now / 1000)
const mac = toBase64Url(await crypto.subtle.sign('HMAC', await macKey(gate.secret), macInput(iat)))
const flags = gate.local ? 'HttpOnly; SameSite=Lax' : 'Secure; HttpOnly; SameSite=Lax'
return `${gate.local ? LOCAL_COOKIE : COOKIE}=v1.${iat}.${mac}; Path=/; Max-Age=${gate.ttl}; ${flags}`
}
async function sha256(text: string): Promise<Uint8Array> {
return new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(text)))
}
/** The request carries the verified-bot header with the right token (compared in constant time). */
export async function botPass(request: Request, token: string): Promise<boolean> {
const sent = request.headers.get(BOT_HEADER)
if (!sent || token.length < MIN_SECRET) return false
const [a, b] = await Promise.all([sha256(sent), sha256(token)])
let diff = 0
for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i]
return diff === 0
}
/**
* Whether the request has passed: as a verified bot, or with a pass cookie
* that is still valid. `remaining` is how many seconds the pass has left.
* The cookie holds its issue time, so lowering the TTL shortens passes
* already given out.
*/
export async function checkPass(
request: Request,
gate: Gate,
now = Date.now(),
): Promise<{ via: PassVia | null; remaining: number }> {
if (await botPass(request, gate.botToken)) return { via: 'bot', remaining: gate.ttl }
const nowSec = Math.floor(now / 1000)
for (const value of cookieValues(request, gate.local ? LOCAL_COOKIE : COOKIE)) {
const m = COOKIE_VALUE.exec(value)
if (!m) continue
const iat = Number(m[1])
if (nowSec - iat >= gate.ttl || iat > nowSec + CLOCK_SKEW) continue
const ok = await crypto.subtle.verify('HMAC', await macKey(gate.secret), fromBase64Url(m[2]), macInput(iat))
if (ok) return { via: 'cookie', remaining: Math.min(gate.ttl, gate.ttl - (nowSec - iat)) }
}
return { via: null, remaining: 0 }
}
// ── Responses ────────────────────────────────────────────────────────────────
/** /img without a pass. */
export function gateRequired(): Response {
return json({ error: 'verification_required' }, 403)
}
/** An app page request: null when it has passed, else the verification page (503 for crawler look-alikes). */
export async function gateNavigation(request: Request, gate: Gate): Promise<Response | null> {
if ((await checkPass(request, gate)).via) return null
if (CRAWLER_UA.test(request.headers.get('user-agent') ?? '')) return crawlerUnavailable(request)
return challengePage(request, { sitekey: gate.sitekey, ttlHours: gate.ttl / 3600 })
}
export interface VerifyDeps {
fetch: typeof fetch
limiter: Pick<RateLimit, 'limit'> | undefined
now?: () => number
}
/** GET: the caller's pass status (the SPA and the page check it). POST: Turnstile token → pass cookie. */
export async function handleVerify(request: Request, url: URL, env: WorkerEnv, deps: VerifyDeps): Promise<Response> {
try {
const gate = gateConfig(env, url)
const now = deps.now?.() ?? Date.now()
if (request.method === 'GET' || request.method === 'HEAD') {
if (!gate) {
// Still report the bot header, so the Transform Rule can be checked before the gate is on.
const bot = await botPass(request, env.GATE_BOT_TOKEN ?? '')
return json({ enabled: false, valid: true, via: bot ? 'bot' : null, ttl: 0 })
}
const pass = await checkPass(request, gate, now)
return json({ enabled: true, valid: pass.via !== null, via: pass.via, ttl: pass.remaining })
}
if (request.method !== 'POST') throw new HttpError(405, 'method_not_allowed')
if (!gate) throw new HttpError(503, 'unavailable')
if (request.headers.get('origin') !== gate.siteOrigin) throw new HttpError(403, 'bad_origin')
if (deps.limiter && !(await deps.limiter.limit({ key: rateKey(request) })).success) {
throw new HttpError(429, 'rate_limited')
}
const body = await readJson(request, 4096)
if (!isObject(body) || typeof body.token !== 'string' || !body.token || body.token.length > 2048) {
throw new HttpError(400, 'invalid_body')
}
const verdict = await siteverify(
{
secret: gate.turnstileSecret,
token: body.token,
ip: request.headers.get('cf-connecting-ip') ?? '',
action: 'gate',
hostname: new URL(gate.siteOrigin).hostname,
},
deps.fetch,
)
if (verdict === 'unavailable') throw new HttpError(503, 'challenge_unavailable')
if (verdict === 'rejected') throw new HttpError(403, 'challenge_failed')
return json({ ttl: gate.ttl }, 200, { 'Set-Cookie': await passCookie(gate, now) })
} catch (e) {
return errorResponse(e)
}
}
+27
View File
@@ -0,0 +1,27 @@
import { describe, expect, it } from 'vitest'
import { rateKey } from './http'
const request = (ip?: string) =>
new Request('https://freeitchgames.win/api/verify', { headers: ip === undefined ? {} : { 'cf-connecting-ip': ip } })
describe('rateKey', () => {
it.each([
['203.0.113.9', '203.0.113.9'],
['2001:db8:1234:5678:9abc:def0:1:2', '2001:db8:1234:5678::/64'],
['2001:DB8:0:0012::1', '2001:db8:0:12::/64'],
['2001:db8::1', '2001:db8:0:0::/64'],
['::1', '0:0:0:0::/64'],
['::ffff:198.51.100.7', '198.51.100.7'],
])('%s → %s', (ip, key) => {
expect(rateKey(request(ip))).toBe(key)
})
it('puts every address of one IPv6 /64 in the same bucket', () => {
expect(rateKey(request('2001:db8:aa:bb:1::1'))).toBe(rateKey(request('2001:db8:aa:bb:ffff:ffff:ffff:ffff')))
})
it('uses one shared key when the address is missing', () => {
expect(rateKey(request())).toBe('unknown')
expect(rateKey(request(''))).toBe('unknown')
})
})
+31
View File
@@ -6,6 +6,37 @@ export const SECURITY_HEADERS: Record<string, string> = {
'Cross-Origin-Resource-Policy': 'same-site',
}
// HTML pages the Worker builds (the verification page): the rest of what
// public/_headers gives the app's pages.
export const PAGE_HEADERS: Record<string, string> = {
...SECURITY_HEADERS,
'X-Frame-Options': 'DENY',
'Cross-Origin-Opener-Policy': 'same-origin',
'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
}
/** Hosts of `wrangler dev`, where Access does not run and cookies can't be Secure. */
export const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]'])
/**
* Rate-limit key for the client: its IPv4 address, or the /64 of an IPv6 one
* (a single host can rotate through its whole /64).
*/
export function rateKey(request: Request): string {
const ip = (request.headers.get('cf-connecting-ip') ?? '').trim().toLowerCase()
if (!ip) return 'unknown'
const v4 = /(\d{1,3}(?:\.\d{1,3}){3})$/.exec(ip)
if (v4) return v4[1] // IPv4, also IPv4-mapped IPv6
const [head, tail] = ip.split('::')
const left = head ? head.split(':') : []
const right = tail === undefined ? [] : tail ? tail.split(':') : []
const groups = tail === undefined ? left : [...left, ...Array(Math.max(8 - left.length - right.length, 0)).fill('0'), ...right]
return `${groups
.slice(0, 4)
.map((g) => g.replace(/^0+(?=.)/, ''))
.join(':')}::/64`
}
export function json(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
return new Response(JSON.stringify(body), {
status,
+99
View File
@@ -0,0 +1,99 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { resetDataCache } from './data'
import type { WorkerEnv } from './env'
import worker from './index'
import { ORIGIN } from './test/fakes'
const SHELL = '<!doctype html><div id="root"></div>'
const BOT = 'b'.repeat(40)
function env(over: Record<string, unknown> = {}) {
const assets = {
fetch: vi.fn(async (req: Request) => {
const { pathname } = new URL(req.url)
if (pathname === '/') return new Response(SHELL, { headers: { 'content-type': 'text/html' } })
if (pathname === '/data/urls.json') return Response.json({})
return new Response(null, { status: 404 })
}),
}
const thumbs = { get: vi.fn(), put: vi.fn(), head: vi.fn() }
return {
ASSETS: assets,
THUMBS: thumbs,
SITE_ORIGIN: ORIGIN,
TURNSTILE_SITEKEY: '0x4AAA-site',
TURNSTILE_SECRET: 'turnstile-secret',
BOT_GATE: 'on',
BOT_GATE_TTL_HOURS: '48',
GATE_SECRET: 'g'.repeat(40),
GATE_BOT_TOKEN: BOT,
...over,
} as unknown as WorkerEnv & { THUMBS: typeof thumbs }
}
const ctx = { waitUntil: () => {}, passThroughOnException: () => {} } as unknown as ExecutionContext
const cache = { match: vi.fn(), put: vi.fn() }
function run(path: string, headers: Record<string, string> = {}, e: WorkerEnv = env()) {
const request = new Request(new URL(path, ORIGIN), { headers }) as Parameters<NonNullable<typeof worker.fetch>>[0]
return worker.fetch!(request, e, ctx)
}
beforeEach(() => {
resetDataCache()
cache.match.mockReset()
vi.stubGlobal('caches', { default: cache })
vi.spyOn(console, 'error').mockImplementation(() => {})
})
afterEach(() => vi.unstubAllGlobals())
describe('router, gate on', () => {
it('answers app pages, "/" included, with the verification page', async () => {
for (const path of ['/', '/games', '/charts?tab=quality']) {
const res = await run(path)
expect(res.status).toBe(200)
expect(res.headers.get('x-robots-tag')).toBe('noindex, nofollow')
expect(await res.text()).toContain('id="gate-config"')
}
})
it('refuses /img without touching the edge cache or R2', async () => {
const e = env()
const res = await run('/img/160/abc/original/x.png', {}, e)
expect(res.status).toBe(403)
expect(await res.json()).toEqual({ error: 'verification_required' })
expect(cache.match).not.toHaveBeenCalled()
expect((e as ReturnType<typeof env>).THUMBS.get).not.toHaveBeenCalled()
})
it('lets verified bots through to the app shell', async () => {
expect(await (await run('/games', { 'x-fig-known-bot': BOT })).text()).toBe(SHELL)
})
it('gives clients that only claim to be a search crawler a 503', async () => {
const res = await run('/games', { 'user-agent': 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)' })
expect(res.status).toBe(503)
})
it('keeps the API, the admin app and /data outside the gate', async () => {
expect((await run('/api/health')).status).toBe(200)
expect(await (await run('/api/verify')).json()).toMatchObject({ enabled: true, valid: false })
const admin = await run('/admin/')
expect([admin.status, admin.headers.get('content-type')]).toEqual([503, 'text/plain; charset=utf-8'])
const data = await run('/data/nope.json')
expect([data.status, data.headers.get('access-control-allow-origin')]).toEqual([404, '*'])
})
})
describe('router, gate off', () => {
it('serves the app shell as before', async () => {
expect(await (await run('/games', {}, env({ BOT_GATE: 'off' }))).text()).toBe(SHELL)
})
it('serves covers without asking for a pass', async () => {
const e = env({ BOT_GATE: 'off' })
const res = await run('/img/160/abc/original/x.png', {}, e)
// Past the gate: the image handler answers (the cover is not in this empty catalog).
expect(res.status).not.toBe(403)
})
})
+16 -6
View File
@@ -1,10 +1,13 @@
/**
* Worker for freeitchgames.win. Existing static assets (the app, /data/*) are
* served by the assets layer without invoking this script. It runs for the
* paths in wrangler.jsonc `assets.run_worker_first`, and for every request
* that matches no asset (`not_found_handling: "none"`, see spa.ts).
* Worker for freeitchgames.win. Existing static assets (the app bundles,
* /data/*) are served by the assets layer without invoking this script. It
* runs for the paths in wrangler.jsonc `assets.run_worker_first` ("/" among
* them), and for every request that matches no asset (`not_found_handling:
* "none"`, see spa.ts).
*
* /img/* resized covers (img.ts)
* app pages the shell, once the visitor has passed the gate (spa.ts, gate.ts)
* /img/* resized covers, gated too (img.ts)
* /api/verify verification gate status + Turnstile check (gate.ts)
* /api/suggest public suggestion form (suggest.ts)
* /api/ingest browser extension, Access service token (ingest.ts)
* /api/admin/* maintainer API, Access + JWT check (admin.ts)
@@ -16,6 +19,7 @@ import { handleAdminApi, serveAdminApp } from './admin'
import { catalogUrls } from './data'
import { discover } from './discover'
import type { WorkerEnv } from './env'
import { checkPass, gateConfig, gateNavigation, gateRequired, handleVerify } from './gate'
import { json } from './http'
import { handleImg } from './img'
import { accessService, handleIngest } from './ingest'
@@ -32,8 +36,11 @@ export default {
const url = new URL(request.url)
const path = url.pathname
const data = { assets: env.ASSETS, origin: url.origin }
const gate = gateConfig(env, url)
if (path.startsWith('/img/')) {
// Before the edge cache and R2: a visitor without a pass costs nothing.
if (gate && !(await checkPass(request, gate)).via) return gateRequired()
return handleImg(request, url, {
assets: env.ASSETS,
bucket: env.THUMBS,
@@ -43,6 +50,9 @@ export default {
})
}
if (path === '/api/health') return json({ ok: true })
if (path === '/api/verify') {
return handleVerify(request, url, env, { fetch: (input, init) => fetch(input, init), limiter: env.RL_GATE })
}
if (path === '/api/suggest') {
return handleSuggest(request, env, {
store: queueStore(env),
@@ -63,7 +73,7 @@ export default {
if (path.startsWith('/api/')) return json({ error: 'not_found' }, 404)
if (path === '/admin' || path.startsWith('/admin/')) return serveAdminApp(request, url, env)
return handleMiss(request, url, env.ASSETS)
return handleMiss(request, url, env.ASSETS, gate ? (r) => gateNavigation(r, gate) : undefined)
},
async scheduled(_controller, env: WorkerEnv): Promise<void> {
+33 -3
View File
@@ -1,6 +1,6 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { resetDataCache } from './data'
import { handleMiss } from './spa'
import { handleMiss, type PageGate } from './spa'
const ORIGIN = 'https://freeitchgames.win'
const SHELL = '<!doctype html><div id="root"></div>'
@@ -18,9 +18,9 @@ function assets(urls: Record<string, string> | 'down' = { 'https://dev.itch.io/c
} as unknown as Fetcher
}
async function miss(path: string, init: RequestInit = {}, binding = assets()) {
async function miss(path: string, init: RequestInit = {}, binding = assets(), gate?: PageGate) {
const url = new URL(path, ORIGIN)
return handleMiss(new Request(url, init), url, binding)
return handleMiss(new Request(url, init), url, binding, gate)
}
beforeEach(() => resetDataCache())
@@ -73,3 +73,33 @@ describe('renamed routes', () => {
expect((await miss('/removed')).status).toBe(200)
})
})
describe('with the verification gate', () => {
const VERIFY_PAGE = '<!doctype html><title>verify</title>'
const blocking = () => vi.fn<PageGate>(async () => new Response(VERIFY_PAGE, { headers: { 'cache-control': 'no-store' } }))
const passing = () => vi.fn<PageGate>(async () => null)
it('answers app pages with the verification page, without fetching the shell', async () => {
const binding = assets()
const res = await miss('/games', { headers: { 'if-none-match': '"shell-etag"' } }, binding, blocking())
expect(res.status).toBe(200) // never a 304 for a cached shell
expect(await res.text()).toBe(VERIFY_PAGE)
expect(binding.fetch).not.toHaveBeenCalled()
})
it('does not consult it for missing files, /data (CORS kept), renamed routes or other methods', async () => {
const gate = blocking()
expect((await miss('/assets/x-OLD.js', {}, assets(), gate)).status).toBe(404)
const data = await miss('/data/nope.json', {}, assets(), gate)
expect([data.status, data.headers.get('access-control-allow-origin')]).toEqual([404, '*'])
expect((await miss('/deleted', {}, assets(), gate)).status).toBe(301)
expect((await miss('/games', { method: 'POST' }, assets(), gate)).status).toBe(405)
expect(gate).not.toHaveBeenCalled()
})
it('serves the shell (or the 404 shell) once the request has passed', async () => {
expect(await (await miss('/charts', {}, assets(), passing())).text()).toBe(SHELL)
const unknown = await miss('/unknown', {}, assets(), passing())
expect([unknown.status, await unknown.text()]).toEqual([404, SHELL])
})
})
+10 -1
View File
@@ -8,6 +8,8 @@
* - App routes get the shell (index.html) with 200; unknown paths and game
* slugs that are not in the catalog get the same shell with 404, so the SPA
* still renders its Not Found page but crawlers see a real 404.
* - With the verification gate on, a visitor who has not passed gets the
* verification page instead of the shell (gate.ts).
*/
import { catalogUrls, type DataSource } from './data'
import { json } from './http'
@@ -53,7 +55,10 @@ async function isAppRoute(pathname: string, src: DataSource): Promise<boolean> {
return game !== null && (await isGameSlug(game[1], src))
}
export async function handleMiss(request: Request, url: URL, assets: Fetcher): Promise<Response> {
/** Answers an app page request that may not see the shell yet; null lets it through (gate.ts). */
export type PageGate = (request: Request) => Promise<Response | null>
export async function handleMiss(request: Request, url: URL, assets: Fetcher, gate?: PageGate): Promise<Response> {
if (request.method !== 'GET' && request.method !== 'HEAD') {
return json({ error: 'method_not_allowed' }, 405, { Allow: 'GET, HEAD' })
}
@@ -65,6 +70,10 @@ export async function handleMiss(request: Request, url: URL, assets: Fetcher): P
}
const moved = MOVED[url.pathname.replace(/\/+$/, '')]
if (moved) return Response.redirect(new URL(moved + url.search, url).toString(), 301)
// Before the shell is fetched, so a conditional request (If-None-Match)
// without a pass gets the verification page, never a 304 for a cached shell.
const blocked = await gate?.(request)
if (blocked) return blocked
// "/" rather than "/index.html": auto-trailing-slash would redirect the latter.
const shell = await assets.fetch(new Request(new URL('/', url), request))
if (shell.status !== 200 || (await isAppRoute(url.pathname, { assets, origin: url.origin }))) {
+15 -22
View File
@@ -10,10 +10,10 @@
import { canonicalize } from './canonical'
import { catalogUrls, deletedGames, type DataSource } from './data'
import { missingConfig, type WorkerEnv } from './env'
import { HttpError, errorResponse, isObject, json, readJson } from './http'
import { HttpError, errorResponse, isObject, json, rateKey, readJson } from './http'
import { autoFlags, classify, type Outcome, type QueueStore } from './queue'
import { siteverify } from './turnstile'
const SITEVERIFY = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
const MAX_NOTE = 500
type SuggestStatus = 'received' | 'already_listed' | 'already_suggested' | 'not_accepted'
@@ -37,23 +37,6 @@ function enabled(env: WorkerEnv, deps: SuggestDeps): boolean {
return missingConfig(env, ['TURNSTILE_SECRET', 'TURNSTILE_SITEKEY', 'SITE_ORIGIN']).length === 0 && deps.store !== null
}
async function verifyTurnstile(env: WorkerEnv, deps: SuggestDeps, token: string, ip: string): Promise<boolean> {
const form = new FormData()
form.set('secret', env.TURNSTILE_SECRET ?? '')
form.set('response', token)
if (ip) form.set('remoteip', ip)
try {
const res = await deps.fetch(SITEVERIFY, { method: 'POST', body: form })
const outcome = (await res.json()) as { success?: boolean; hostname?: string }
if (!outcome.success) return false
const expected = new URL(env.SITE_ORIGIN).hostname
// Turnstile's test keys answer with a placeholder hostname; only local dev uses them.
return !outcome.hostname || outcome.hostname === expected || expected === 'localhost'
} catch {
return false
}
}
export async function handleSuggest(request: Request, env: WorkerEnv, deps: SuggestDeps): Promise<Response> {
try {
if (request.method === 'GET') {
@@ -64,8 +47,7 @@ export async function handleSuggest(request: Request, env: WorkerEnv, deps: Sugg
if (!enabled(env, deps) || !deps.store) throw new HttpError(503, 'unavailable')
if (request.headers.get('origin') !== env.SITE_ORIGIN) throw new HttpError(403, 'bad_origin')
const ip = request.headers.get('cf-connecting-ip') ?? ''
if (deps.limiter && !(await deps.limiter.limit({ key: ip || 'unknown' })).success) {
if (deps.limiter && !(await deps.limiter.limit({ key: rateKey(request) })).success) {
throw new HttpError(429, 'rate_limited')
}
const body = await readJson(request, 4096)
@@ -76,7 +58,18 @@ export async function handleSuggest(request: Request, env: WorkerEnv, deps: Sugg
if (note.length > MAX_NOTE) throw new HttpError(400, 'note_too_long')
const url = canonicalize(body.url)
if (!url) throw new HttpError(400, 'invalid_url')
if (!(await verifyTurnstile(env, deps, body.token, ip))) throw new HttpError(403, 'challenge_failed')
const verdict = await siteverify(
{
secret: env.TURNSTILE_SECRET ?? '',
token: body.token,
ip: request.headers.get('cf-connecting-ip') ?? '',
action: 'suggest',
hostname: new URL(env.SITE_ORIGIN).hostname,
},
deps.fetch,
)
if (verdict === 'unavailable') throw new HttpError(503, 'challenge_unavailable')
if (verdict === 'rejected') throw new HttpError(403, 'challenge_failed')
const [catalog, deleted, known] = await Promise.all([
catalogUrls(deps.data),
+4 -2
View File
@@ -28,8 +28,8 @@ const env = {
TURNSTILE_SECRET: 'secret',
} as unknown as WorkerEnv
function siteverify(success: boolean, hostname = 'freeitchgames.win') {
return vi.fn(async () => Response.json({ success, hostname }))
function siteverify(success: boolean, hostname = 'freeitchgames.win', action = 'suggest') {
return vi.fn(async () => Response.json({ success, hostname, action }))
}
function suggestRequest(body: unknown, headers: Record<string, string> = {}) {
@@ -84,6 +84,8 @@ describe('POST /api/suggest', () => {
it.each([
['a failed challenge', suggestRequest({ url: 'https://dev.itch.io/x', token: 't' }), { fetch: siteverify(false) }, 403],
['a token for another site', suggestRequest({ url: 'https://dev.itch.io/x', token: 't' }), { fetch: siteverify(true, 'evil.example') }, 403],
['a token minted by the verification gate', suggestRequest({ url: 'https://dev.itch.io/x', token: 't' }), { fetch: siteverify(true, 'freeitchgames.win', 'gate') }, 403],
['an unreachable siteverify', suggestRequest({ url: 'https://dev.itch.io/x', token: 't' }), { fetch: vi.fn(async () => new Response(null, { status: 502 })) }, 503],
['a cross-site post', suggestRequest({ url: 'https://dev.itch.io/x', token: 't' }, { origin: 'https://evil.example' }), {}, 403],
['a non-itch URL', suggestRequest({ url: 'https://example.com/game', token: 't' }), {}, 400],
['an over-long note', suggestRequest({ url: 'https://dev.itch.io/x', note: 'x'.repeat(501), token: 't' }), {}, 400],
+80
View File
@@ -0,0 +1,80 @@
import { describe, expect, it, vi } from 'vitest'
import { isTestSecret, siteverify, type SiteverifyInput } from './turnstile'
const input: SiteverifyInput = {
secret: '0x4AAAAAAAreal-secret',
token: 'tok',
ip: '203.0.113.9',
action: 'gate',
hostname: 'freeitchgames.win',
}
const answer = (body: unknown) => vi.fn(async () => Response.json(body))
const run = (fetch: unknown, over: Partial<SiteverifyInput> = {}, timeoutMs?: number) =>
siteverify({ ...input, ...over }, fetch as typeof globalThis.fetch, timeoutMs)
describe('siteverify', () => {
it('accepts a token solved on our host for the same action', async () => {
const fetch = answer({ success: true, hostname: 'freeitchgames.win', action: 'gate' })
expect(await run(fetch)).toBe('ok')
const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit]
expect(url).toBe('https://challenges.cloudflare.com/turnstile/v0/siteverify')
const form = init.body as FormData
expect([form.get('secret'), form.get('response'), form.get('remoteip')]).toEqual([input.secret, 'tok', '203.0.113.9'])
})
it('leaves remoteip out when the IP is unknown', async () => {
const fetch = answer({ success: true, hostname: 'freeitchgames.win', action: 'gate' })
await run(fetch, { ip: '' })
expect(((fetch.mock.calls[0] as unknown as [string, RequestInit])[1].body as FormData).has('remoteip')).toBe(false)
})
it.each([
['a failed challenge', { success: false, 'error-codes': ['invalid-input-response'] }],
['a spent token', { success: false, 'error-codes': ['timeout-or-duplicate'] }],
['a token from another host', { success: true, hostname: 'evil.example', action: 'gate' }],
['a token for another action', { success: true, hostname: 'freeitchgames.win', action: 'suggest' }],
['a token without an action', { success: true, hostname: 'freeitchgames.win' }],
['a token without a hostname', { success: true, action: 'gate' }],
['a malformed answer', null],
])('rejects %s', async (_name, body) => {
expect(await run(answer(body))).toBe('rejected')
})
it.each([
['a 5xx', () => new Response('bad gateway', { status: 502 })],
['a non-JSON body', () => new Response('<html>', { status: 200 })],
['a network error', () => Promise.reject(new TypeError('fetch failed'))],
['an internal error', () => Response.json({ success: false, 'error-codes': ['internal-error'] })],
['a refused secret key', () => Response.json({ success: false, 'error-codes': ['invalid-input-secret'] })],
])('reports %s as unavailable', async (_name, reply) => {
vi.spyOn(console, 'error').mockImplementation(() => {})
expect(await run(vi.fn(async () => reply()))).toBe('unavailable')
})
it('gives up after the timeout', async () => {
const fetch = vi.fn(
(_url: string, init: RequestInit) =>
new Promise<Response>((_resolve, reject) => init.signal?.addEventListener('abort', () => reject(init.signal?.reason))),
)
expect(await run(fetch, {}, 20)).toBe('unavailable')
})
it('skips the host and action checks for the test secrets', async () => {
const fetch = answer({ success: true, hostname: 'example.com', action: '' })
expect(await run(fetch, { secret: '1x0000000000000000000000000000000AA' })).toBe('ok')
expect(await run(answer({ success: false }), { secret: '2x0000000000000000000000000000000AA' })).toBe('rejected')
})
})
describe('isTestSecret', () => {
it.each([
['1x0000000000000000000000000000000AA', true],
['2x0000000000000000000000000000000AA', true],
['3x0000000000000000000000000000000AA', true],
['0x4AAAAAAAreal-secret', false],
['1x0000000000000000000000000000000AB', false],
])('%s → %s', (secret, expected) => {
expect(isTestSecret(secret)).toBe(expected)
})
})
+62
View File
@@ -0,0 +1,62 @@
/**
* Cloudflare Turnstile's server-side check (siteverify), shared by the Suggest
* form and the verification gate. A token is single-use and valid for 300 s.
* The widget's `action` must match, so a token minted on one page cannot be
* spent on the other, and the hostname must be ours.
*/
const SITEVERIFY = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
type TurnstileAction = 'gate' | 'suggest'
/**
* - ok: a person passed the widget on our site, for this action.
* - rejected: the token is invalid, spent, or was issued elsewhere.
* - unavailable: siteverify could not answer (timeout, 5xx, bad secret).
*/
export type SiteverifyOutcome = 'ok' | 'rejected' | 'unavailable'
export interface SiteverifyInput {
secret: string
token: string
/** The visitor's IP (cf-connecting-ip), '' when unknown. */
ip: string
action: TurnstileAction
/** Hostname the widget must have run on (SITE_ORIGIN's). */
hostname: string
}
/** Turnstile's documented test secrets (1x… always passes, 2x… fails, 3x… "already spent"). */
export function isTestSecret(secret: string): boolean {
return /^[123]x0+AA$/.test(secret)
}
export async function siteverify(
input: SiteverifyInput,
fetcher: typeof fetch,
timeoutMs = 5000,
): Promise<SiteverifyOutcome> {
const form = new FormData()
form.set('secret', input.secret)
form.set('response', input.token)
if (input.ip) form.set('remoteip', input.ip)
let outcome: { success?: unknown; hostname?: unknown; action?: unknown; 'error-codes'?: unknown }
try {
const res = await fetcher(SITEVERIFY, { method: 'POST', body: form, signal: AbortSignal.timeout(timeoutMs) })
if (!res.ok) return 'unavailable'
outcome = await res.json()
} catch {
return 'unavailable'
}
if (outcome?.success !== true) {
const codes = Array.isArray(outcome?.['error-codes']) ? (outcome['error-codes'] as unknown[]) : []
if (codes.some((c) => c === 'missing-input-secret' || c === 'invalid-input-secret')) {
console.error('turnstile: the secret key was refused')
return 'unavailable'
}
return codes.includes('internal-error') ? 'unavailable' : 'rejected'
}
// The test secrets answer with placeholder hostname and action values.
if (isTestSecret(input.secret)) return 'ok'
return outcome.hostname === input.hostname && outcome.action === input.action ? 'ok' : 'rejected'
}
+25 -12
View File
@@ -6,8 +6,9 @@
//
// Secrets are NOT in this file: `npx wrangler secret put <NAME>` (and
// webapp/.dev.vars for `wrangler dev`) — GH_APP_PRIVATE_KEY, ADMIN_EMAILS,
// TURNSTILE_SECRET. Until a feature's settings are filled in, its routes
// answer 503 (see worker/env.ts); the public site works without any of them.
// TURNSTILE_SECRET, GATE_SECRET, GATE_BOT_TOKEN. Until a feature's settings are
// filled in, its routes answer 503 and the verification gate stays off (see
// worker/env.ts, worker/gate.ts); the public site works without any of them.
// After editing this file run `npm run cf:types`.
{
"$schema": "./node_modules/wrangler/config-schema.json",
@@ -30,8 +31,10 @@
"not_found_handling": "none",
"html_handling": "auto-trailing-slash",
// Existing assets never invoke the Worker (free, cached); these paths always
// do — /admin so its shell is only ever served after the Access JWT check.
"run_worker_first": ["/img/*", "/api/*", "/admin", "/admin/*"]
// do — "/" (served from dist/index.html otherwise) so the verification gate
// sees it like every other app page, /admin so its shell is only ever served
// after the Access JWT check.
"run_worker_first": ["/", "/img/*", "/api/*", "/admin", "/admin/*"]
},
// Resized cover images, written once per image + width by worker/img.ts.
"r2_buckets": [{ "binding": "THUMBS", "bucket_name": "freeitchgames-thumbs" }],
@@ -47,10 +50,13 @@
"migrations_dir": "./worker/migrations"
}
],
// Per-key limits (IP for the Suggest form, service-token id for ingest).
// Per-key limits (IP for the Suggest form and the verification gate — an IPv6
// client by its /64 — and the service-token id for ingest). The gate's limit
// is higher: carrier-grade NAT puts many phones behind one address.
"ratelimits": [
{ "name": "RL_SUGGEST", "namespace_id": "1001", "simple": { "limit": 5, "period": 60 } },
{ "name": "RL_INGEST", "namespace_id": "1002", "simple": { "limit": 20, "period": 60 } }
{ "name": "RL_INGEST", "namespace_id": "1002", "simple": { "limit": 20, "period": 60 } },
{ "name": "RL_GATE", "namespace_id": "1003", "simple": { "limit": 20, "period": 60 } }
],
// RSS discovery (one feed per run) + queue bookkeeping, worker/index.ts scheduled().
"triggers": { "crons": ["23 */4 * * *"] },
@@ -65,15 +71,19 @@
"ACCESS_TEAM_DOMAIN": "https://polished-hall-48fd.cloudflareaccess.com", // no trailing slash
"ACCESS_AUD_ADMIN": "fc4d79904ffb90f7405cabb0135e15940c7bad48ba344309adc085d71622f482", // "Admin" Access app
"ACCESS_AUD_INGEST": "85662a9f2112d3c5912699f10a59ad9702ef44c05f4e186eb4f550bf1b163ff6", // "Ingest" Access app
"TURNSTILE_SITEKEY": "0x4AAAAAAE7oBxYiQZ_lVEBW"
"TURNSTILE_SITEKEY": "0x4AAAAAAE7oBxYiQZ_lVEBW",
// Verification gate (worker/gate.ts). "on" still needs the GATE_SECRET and
// GATE_BOT_TOKEN secrets; the instant off switch is deleting GATE_SECRET.
"BOT_GATE": "on",
"BOT_GATE_TTL_HOURS": "48"
},
"observability": { "enabled": true, "head_sampling_rate": 0.1 },
"upload_source_maps": false,
"env": {
// Pre-release checks of the v4 branch: Worker "free-games-itchio-list-staging",
// deployed with `npx wrangler deploy --env staging`, whole host behind Access.
// Bindings and vars are not inherited, so every one is repeated here.
// Pre-release checks: Worker "free-games-itchio-list-staging", deployed by hand
// from any branch with `npx wrangler deploy --env staging`, whole host behind
// Access. Bindings and vars are not inherited, so every one is repeated here.
"staging": {
"workers_dev": false,
"preview_urls": false,
@@ -84,7 +94,8 @@
],
"ratelimits": [
{ "name": "RL_SUGGEST", "namespace_id": "2001", "simple": { "limit": 5, "period": 60 } },
{ "name": "RL_INGEST", "namespace_id": "2002", "simple": { "limit": 20, "period": 60 } }
{ "name": "RL_INGEST", "namespace_id": "2002", "simple": { "limit": 20, "period": 60 } },
{ "name": "RL_GATE", "namespace_id": "2003", "simple": { "limit": 20, "period": 60 } }
],
// No RSS polling from staging: production is the only itch.io client.
"triggers": { "crons": [] },
@@ -97,7 +108,9 @@
"ACCESS_TEAM_DOMAIN": "",
"ACCESS_AUD_ADMIN": "",
"ACCESS_AUD_INGEST": "",
"TURNSTILE_SITEKEY": ""
"TURNSTILE_SITEKEY": "",
"BOT_GATE": "off",
"BOT_GATE_TTL_HOURS": "48"
}
}
}