Merge pull request #91: v4.1.0 — verification gate, readable chart tooltips, changelog split [skip-discuss]

Release 4.1.0: Turnstile verification gate (inert until its secrets exist), readable chart tooltips, changelog split into changelog/, legal and docs refresh.
This commit is contained in:
poli0981 authored and GitHub committed 2026-09-24 18:22:02 +07:00
commit 08dd4b6172
88 files changed
+2752 -1069

No files matched your search

+1 -1
View File
@@ -34,7 +34,7 @@ body:
attributes:
label: Version
description: Shown on the About page (website and apps). For the desktop/Android app, the release you installed.
placeholder: e.g. 4.0.0
placeholder: e.g. 4.1.0
- type: input
id: environment
+5 -4
View File
@@ -2,9 +2,9 @@ name: Announce to Discussion
# Two triggers, two destinations:
# 1. release:published → Announcements category
# 2. push touching CHANGELOG.md → General (docs-only edits no longer post;
# put user-facing changes in the changelog). Add `[skip-discuss]` to the
# head-commit message to opt out.
# 2. push touching the changelog (CHANGELOG.md index or changelog/**) →
# General (docs-only edits don't post; put user-facing changes in the
# changelog). Add `[skip-discuss]` to the head-commit message to opt out.
#
# No pre-flight needed — repo ID and category IDs are auto-discovered at
# runtime via GraphQL (by category slug: "announcements" / "general").
@@ -17,6 +17,7 @@ on:
branches: [main]
paths:
- 'CHANGELOG.md'
- 'changelog/**'
workflow_dispatch:
inputs:
mode:
@@ -163,7 +164,7 @@ jobs:
id: changes
run: |
set -euo pipefail
git diff --name-only HEAD^ HEAD -- CHANGELOG.md > changed.txt || true
git diff --name-only HEAD^ HEAD -- CHANGELOG.md changelog/ > changed.txt || true
if [ ! -s changed.txt ]; then
echo "no-docs-changed=true" >> "$GITHUB_OUTPUT"
fi
+54 -803
View File
@@ -1,805 +1,56 @@
# Changelog
All notable changes to this project will be documented here.
## [4.0.0] - 2026-09-18 (freeitchgames.win on Cloudflare: read-only site, review queue, new design)
Version 4 moves the website to **https://freeitchgames.win** on Cloudflare, makes it read-only for
everyone (no sign-in), adds a maintainer-only admin with a review queue for new games, replaces the
failing data crawls with a rotating refresh, and splits the licenses (code MIT, data and docs
CC BY 4.0).
### Upgrade notes
- **The web app no longer signs in or edits.** The GitHub-token (PAT) sign-in, in-app editing, the
Add / Workflows pages and GPG commit signing are gone; on first load the app deletes the
encrypted token and key it stored before. Suggest games at https://freeitchgames.win/suggest.
- **Old links keep working**: `…github.io/free-games-itchio-list/#/x` redirects to the new site,
and `#/x` links become `/x`.
- **Desktop and Android apps** are read-only viewers too; they read the catalog from
freeitchgames.win. Install 4.0.0 over 3.x as usual.
- **New legal terms** (ToS, Privacy Policy, EULA for the apps only, Disclaimer): the site asks you to
accept them again once.
### New design
- A clean, table-first interface under the name **Free Itch Games**: a top navigation bar with a
global search (press `/`) and a display menu (theme, language, density, 18+) replaces the
sidebar, and a **Welcome** page at `/` (catalog status, recently added games) replaces the
dashboard.
- **Games**: search plus filters for genre, platform, status, tags, language, input, engine,
minimum rating and "plays in browser", each showing how many games it would match. The search,
filters, sort and page are kept in the URL, so a filtered list can be bookmarked or shared. Phones
get a list layout.
- A new game page (cover, key facts, tags that open the matching list, "Report a problem"), a
searchable removed-games page and a simpler Settings page.
- The first-visit legal gate is now a dialog over the page, so a shared link opens where it
pointed once the terms are accepted.
- Tailwind CSS 4, the self-hosted Geist typefaces, new icons and social preview image; numbers and
dates follow the chosen language.
### Website & Worker
- The site is served by a Cloudflare Worker with static assets ([`webapp/wrangler.jsonc`](webapp/wrangler.jsonc),
[`webapp/worker/`](webapp/worker)) and the catalog JSON is bundled into every build (`/data/*`,
plus a sitemap), so each data commit republishes the site; the desktop/Android apps read the same
files. Real URL paths instead of `#/` routes, per-page canonical URLs, and real 404s for unknown
pages and missing files (a stale script after a deploy can no longer be cached as HTML).
- **Cover images** are resized once to small WebP copies (Cloudflare Image Transformations + R2)
and served from `/img/…` — about 4 KB instead of up to 3 MB per cover. Only catalog covers are
served.
- **18+ games are hidden by default**; a visitor can show them (Settings or the display menu) after
confirming they are 18 or older (stored only in their browser). The removed-games page is now
`/removed` (`/deleted` redirects there). Aggregate, cookieless Cloudflare Web Analytics.
- Enforced Content-Security-Policy and security headers; faster first load (~175 KB gzip, charts
load only when opened); browser floor Safari/iOS 15.4.
- React Router 8, React 19.3, Vite 8 (rolldown), vitest; unused sign-in dependencies (Octokit,
OpenPGP.js) removed; Tauri drops its HTTP plugin and `Cargo.lock` is committed.
### Adding games: review queue
- **Suggest page** (`/suggest`): anyone can send an itch.io link (+ optional note); protected by
Cloudflare Turnstile and a rate limit.
- **Browser extension API** (`POST /api/ingest`, Cloudflare Access service token, idempotent) —
the extension no longer needs a GitHub token.
- **RSS discovery**: every 4 hours the Worker reads one itch.io "new & popular free" feed.
- Everything lands in a **review queue** (Cloudflare D1). The maintainer approves or rejects it in
the new **admin** (`/admin`, Cloudflare Access), which also edits the three maintainer fields,
removes games with a public reason (deleting their resized covers) and restores removed games.
Approved games are committed by a GitHub App (verified commits) and scraped by the pipeline.
### Licenses & legal
- Code stays **MIT** (`LICENSE`, now "2025-2026 poli0981 (SkullMute)"); the catalog data
([`data_game/LICENSE.md`](data_game/LICENSE.md)) and the documentation are **CC BY 4.0**
([`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt)); creators' descriptions, cover images and
trademarks are excluded. [`NOTICE.md`](NOTICE.md) sums it up: not affiliated with itch.io.
- Rewritten Terms of Use (with a content-removal process), Privacy Policy (Cloudflare as
processor, exact browser storage, retention, rights under Vietnam's Law No. 91/2025/QH15 and the
GDPR), Disclaimer, Security Policy and Code of Conduct, in English and Vietnamese. The EULA now
covers only the desktop and Android apps. Contact addresses: legal@, privacy@, security@ and
takedown@freeitchgames.win.
- Issue templates: "Add games" points to the Suggest page, "Remove a game" gained a
rights-holder section; `CODEOWNERS` added.
### Fixed
- **freeitchgames.win served the unbuilt `webapp/` source tree** (blank page; `/package.json`,
`/src/*` publicly readable). The Vite web build now goes to `webapp/dist`, which
[`webapp/wrangler.jsonc`](webapp/wrangler.jsonc) deploys (`workers_dev`/`preview_urls` off).
- **All 15 Dependabot alerts / npm audit** — lockfile refreshed in-range (vite 8.3.0,
react-router-dom 7.18.4, postcss 8.5.28, patched transitive deps); `npm audit` reports 0.
- **Android release workflow** moved off Node 20 actions (setup-java v6, upload-artifact v7,
setup-android v4, checkout/setup-node v7), SHA-pinned, with a timeout and the tag passed via env.
- **`.gitattributes`** — `* text = auto` / `* eol = lf` were invalid (spaces around `=`); now
`* text=auto eol=lf` with binary rules, and legal/policy docs ship in source archives again.
- OG image, manifest (`start_url`/`scope`/`id` = `/`), canonical/og URLs, sitemap and robots now
point at freeitchgames.win; OG title no longer overflows.
### Data pipeline (rewrite)
- **One rotating refresh replaces four failing crawls.** `check_paid` / `check_alive` /
`update_reviews` / `update_status` each fetched all 2,600+ pages sequentially, overran their
job timeouts and — saving only at the end — lost every run since late June (with no alert,
because a timeout ends as *cancelled*). The new [`scripts/refresh.py`](scripts/refresh.py)
(`refresh.yml`, daily) checks one seventh of the catalog with **one request per game**, so every
game is re-checked weekly (~86% fewer requests to itch.io), and updates alive / paid / rating /
status (+ backfills release date, thumbnail, `updated_at`) from that single page.
- **Safer removals:** a game is removed only when the same 404/410 or paid status is seen again at
least 20 hours after it was first seen (single flaky responses no longer delete games). A
mass-change guard withholds removals — and alerts — when a run would remove or newly strike more
than max(10, 10%) of the games it checked (the signature of an itch.io markup change rather than
a real wave of paid games); withheld games stay withheld in later runs until a healthy check or
an explicit `allow_mass_removal` dispatch, checkpoints of an interrupted scan never remove games,
and `apply_patch.py` re-checks the limits. Overlapping scans can no longer undo each other's
newer checks.
- **Scan → patch → apply:** scanners emit a URL-keyed patch; [`apply_patch.py`](scripts/apply_patch.py)
applies it to the latest `main`, validates, and [`bash/commit_push.sh`](bash/commit_push.sh)
retries on push races. Concurrent writers (extension, workflows, future admin) no longer clobber
each other; checkpoints + an in-script deadline keep partial work.
- **Ingest** (`update.yml`, now runs as soon as the queue changes): canonical URLs, skips games in
the deleted log (the removed-then-re-added bug), retries transient failures (3 attempts at least
6 hours apart; rate limiting never counts) instead of dropping them, stamps `added_at`, and never
wipes links queued meanwhile. A dispatched `url` is processed first and kept in the queue until it
reaches a final outcome, and queued runs wait in FIFO order (`queue: max`) instead of replacing
each other.
- `force_update.yml` runs `refresh.py --full` in rotating batches (a full re-scrape no longer times out).
- Honest `FreeItchGamesBot` User-Agent, explicit 429 / Retry-After handling (capped), unbuffered
logs, run summaries, Discord alerts on failure / cancel / rate limit.
- `data_store.py` keeps games in their chunk and only writes changed bytes; `index.json` /
`count_history.json` change only when data does — no more no-op commits.
- New [`validate.py`](scripts/validate.py) (schema, canonical URLs, duplicates, index consistency)
gates every pipeline commit and runs in the new Python CI with a network-free pytest suite.
Normalized one invalid `safe_virus` value (`"y"` → `"Yes"`).
### Removed
- `lists/*.md` genre tables, `generate_md.py`, `generate_table.yml`, `deleted_games.txt`,
`log_deleted.*` — the catalog is web-only (freeitchgames.win).
- Telegram bot ingest (`bot-ingest.yml`, `game_via_bot` issue template) — retired.
- The web app's sign-in, editing, Add and Workflows pages, GPG signing, and the GitHub Pages
deployment (`deploy_webapp.yml`, `notify-deploy.yml`, `pages-redirect/`; Pages keeps serving the
redirect stub it last published).
- `notify-ci-failure.yml` (replaced by in-workflow notifications) and the old per-task bash wrappers.
### CI / security
- All actions SHA-pinned at current majors; `permissions: {}` by default with per-job grants;
reusable workflows pinned by SHA with only the secrets they need; script-injection patterns in
`announce-discussion.yml` fixed (and it now posts only for `CHANGELOG.md` changes).
- Release: one `create-release` job makes the draft that desktop (tauri-action v1, `releaseId`) and
Android upload into; release builds use no dependency caches. Publish with
`gh release edit vX --draft=false`.
- `.github/dependabot.yml` (npm / pip / actions / cargo), Python and web-app PR checks, and an
hourly check of main's latest Cloudflare Workers Build that posts each failed build to Discord
once (a `check_run` relay would miss the pipeline's own data commits).
- One refresh pipeline (scan → apply) runs at a time, so overlapping refresh / force-update runs
can't undo each other.
- Cancelling a refresh / force-update or a desktop release run now really stops it (`!cancelled()`
instead of `always()` on the push / build jobs).
### Changed
- The old GitHub Pages address serves a redirect stub that forwards to freeitchgames.win
(keeping `#/` routes) and deletes the old app's token and key storage on that origin.
- Security headers in [`webapp/public/_headers`](webapp/public/_headers) (CSP, Referrer-Policy,
frame denial, Permissions-Policy, COOP) and immutable caching for hashed `/assets/*`.
- Pipeline logs are unbuffered UTF-8.
## [3.9.0] - 2026-06-15 (Android minSdk → 11 / API 30)
### Changed
- **Android APK floor raised from API 24 (Android 7.0) to API 30 (Android 11).**
`minSdkVersion` in [`webapp/src-tauri/tauri.conf.json`](webapp/src-tauri/tauri.conf.json)
`bundle.android` is now `30`. Because Android's package installer refuses any APK whose
`minSdkVersion` exceeds the device API level, this **is** the install block — the app simply
can't install on Android < 11 ("app not installed / incompatible"); no runtime check by design.
Rationale, stated honestly:
- **Not a JS-feature floor** — the System WebView is independently updatable down to API 24, so
SubtleCrypto / OpenPGP.js / IndexedDB / ES2020 already work on older OSes. That's not the
binding constraint.
- **Security + patch availability** — Android 11 added scoped-storage enforcement, one-time /
auto-reset permissions, and a tighter sandbox; pre-11 releases are also off Google's AOSP
monthly Security Bulletins (Android 10 ended 2023-03-06, Android 11 ended 2024-02-05; only
14 / 15 / 16 remain as of mid-2026).
- **Tested range** — we validate only on Android 11+ (emulator 11 → latest; real phone
vivo 1907 / Android 12 — see [`docs/pc_spec.md`](docs/pc_spec.md)). Shipping an untested floor
was the real risk.
- **Reach cost is small** — API 30+ ≈ 86.9% of active devices (was 96.6% at API 24); only the
pre-2020 long tail is dropped.
Data sources: [endoflife.date/android](https://endoflife.date/android),
[Android Security Bulletins](https://source.android.com/docs/security/bulletin),
[StatCounter version share](https://gs.statcounter.com/android-version-market-share/mobile/worldwide/) (May 2026),
[apilevels.com](https://apilevels.com/) (StatCounter cumulative distribution, Apr 2026).
### Notes
- `versionCode` re-derives to `3009000` (gotcha #18). The web and desktop builds are unaffected by
the Android floor. The `about.ts` version bump busts the IndexedDB catalog cache (harmless).
## [3.8.0] - 2026-06-15 (Android APK target 📱)
### Added
- **Android APK build & packaging via Tauri mobile.** The same React + Tauri app now ships as a
sideloadable **arm64-v8a `.apk`** (no Play Store), built and **post-signed** (`zipalign` →
`apksigner`) by [`.github/workflows/release_android.yml`](.github/workflows/release_android.yml)
and attached to the same draft Release as the desktop installers (manual `workflow_dispatch`
uploads it as a downloadable workflow artifact instead). `gen/android` stays gitignored — signing
is a post-build step, not a Gradle edit. New repo secrets: `ANDROID_KEYSTORE_BASE64` /
`ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. Full build/signing docs in
[`webapp/TAURI.md`](webapp/TAURI.md).
- **Mobile UX** — the Android hardware / gesture back button is wired to in-app router history
(`useBackButton`), safe-area insets are respected, and the sidebar shows a platform-aware badge
("Mobile app" / "Desktop app").
- Added dependency: `@tauri-apps/api`.
### Changed
- **Bundle `identifier` is now alphanumeric** — `com.poli0981.freegamesitchio` (was the hyphenated
`com.poli0981.free-games-itchio-webapp`). Android rejects hyphens in the app id (`android init`
panics) and Tauri's validator rejects underscores, so alphanumeric is the only form valid on
both. Tauri uses one identifier across all platforms, so this also changed the **desktop** bundle
ID (a one-time OS-level reinstall).
- **Realigned versions** — `tauri.conf.json` / `Cargo.toml` / `about.ts` set to `3.8.0` (was a
long-standing `0.1.1` vs `3.x` drift), so `versionCode` / `versionName` are sensible and
monotonic.
### Notes
- CI: the Android JDK setup must **not** use `cache: gradle` — `gen/android` is gitignored and
generated mid-job, so there are no gradle files at checkout to key on (it hard-fails). rust-cache
+ npm cache still apply.
## [3.7.1] - 2026-06-14 (Hotfix — desktop build vs invalid Tauri NSIS license key)
### Fixed
- **v3.7.0's desktop installers never built.** The NSIS EULA was wired via
`bundle.windows.nsis.license`, but `@tauri-apps/cli` 2.11.0's `NsisConfig`
has no `license` key (it was added in a later release), so every platform
failed config validation at the `Build Tauri app` step. Switched to the
top-level `bundle.licenseFile` (valid in 2.11.0) pointing at an **RTF** EULA
([`webapp/src-tauri/installer/EULA.rtf`](webapp/src-tauri/installer/EULA.rtf)).
RTF satisfies **both** Windows bundlers — WiX (`.msi`) requires RTF and NSIS
(`.exe`) auto-detects it — so both installers show the "I Agree" page. The
previous plain-text `EULA.txt` would also have broken the WiX/`.msi` build.
### Notes
- Web feature set is identical to v3.7.0 (which deployed fine); this tag exists
to produce the desktop installers. `about.ts` version bump also busts the
IndexedDB catalog cache, which is harmless. No Tauri version bump
(`tauri.conf.json` stays `0.1.1`).
## [3.7.0] - 2026-06-14 (Legal-acceptance gates + per-tab chart lazy-loading)
### Added
- **First-launch legal-acceptance gate** — on first visit (and in every fresh
incognito session, since `localStorage` starts empty there) the app shows a
full-screen, non-dismissible gate before the main UI. It links the License,
EULA, Privacy Policy, Disclaimer, Terms of Use, Code of Conduct, and Security
Policy (reusing `LEGAL_LINKS`), and requires ticking a checkbox to continue.
New component [`webapp/src/components/legal-gate.tsx`](webapp/src/components/legal-gate.tsx),
built on raw Radix Dialog primitives (focus-trapped, no close-X, Esc /
outside-click disabled). Acceptance persists as `acceptedLegalVersion` in the
existing `webapp.prefs` localStorage blob — **no cookie** (consistent with the
"no cookies" privacy stance). A `LEGAL_VERSION` constant
([`webapp/src/stores/prefs.ts`](webapp/src/stores/prefs.ts)) lets a future
policy edit re-prompt every user with a one-line bump.
- **Windows installer EULA page** — both Windows installers (the NSIS `.exe`
and the WiX `.msi`) now show an "I Agree" license step before installing,
wired via the top-level `bundle.licenseFile` →
[`webapp/src-tauri/installer/EULA.rtf`](webapp/src-tauri/installer/EULA.rtf).
RTF is used so both bundlers render it (WiX requires RTF; NSIS auto-detects
it). The in-app gate above covers first-run consent on macOS / Linux, whose
installers have no equivalent step.
### Changed
- **Charts route split into four lazy per-tab chunks**
([`webapp/src/components/charts/tabs/`](webapp/src/components/charts/tabs)).
Each tab imports its chart components directly (the `charts/index.ts` barrel
was removed so the bundler keeps each tab's components in its own chunk).
Result: only the default **Overview** tab's components load when `/charts`
opens; the Reach / Quality / Discovery component code downloads on first
click. Recharts itself (the ~380 KB `vendor-charts` chunk) still loads with
Overview — unavoidable since the default tab renders charts — but it was
already deferred to the lazy `/charts` route, so it never touches app startup.
- `about.ts` version → 3.7.0 (also busts the IndexedDB catalog cache, harmless);
Claude Code co-author credit updated to Opus 4.8.
### Notes
- Images, routes, and OpenPGP were already lazy-loaded; this release closes the
remaining gap (charts). No Tauri version bump (`tauri.conf.json` stays
`0.1.1`) — the NSIS license is a bundler-config addition, not a binary change.
## [3.6.1] - 2026-06-12 (Hotfix — desktop build vs broken `time` 0.3.48)
### Fixed
- **v3.6.0's desktop installers never built**: `time` 0.3.48 (released
2026-06-12, hours before the v3.6.0 tag) fails to compile inside
`tauri-utils` with `E0119: conflicting implementations of trait From<…>`
([time-rs/time#783](https://github.com/time-rs/time/issues/783)). Since no
`Cargo.lock` is committed, CI resolved the broken release fresh.
`webapp/src-tauri/Cargo.toml` now pins `time = "=0.3.47"` (the version every
release through v3.5.2 built with) — remove the pin once the upstream fix
ships.
### Notes
- Web feature set is identical to v3.6.0; this tag exists to produce the
desktop installers. `about.ts` version bump also busts the new IndexedDB
catalog cache, which is harmless.
- No Tauri version bump (`Cargo.toml` / `tauri.conf.json` stay `0.1.1`) — a
dependency pin to the previously-resolved version changes no binary
behavior.
## [3.6.0] - 2026-06-12 (i18n EN/VI + offline cache + custom error pages)
### Added
- **Bilingual UI (English / Tiếng Việt)** — a minimal typed i18n layer
([`webapp/src/lib/i18n/`](webapp/src/lib/i18n)) with ~340 keys covering every
route, dialog, chart, and toast. The Vietnamese dictionary is a **lazy-loaded
chunk**: it is only downloaded the first time the language is switched to VI
(or on startup when VI is the persisted preference). Switcher lives in
Settings → Appearance; the preference persists in `webapp.prefs`.
- **Offline-first catalog cache** — the react-query cache for the public
catalog queries (`db`, `deleted`, `count-history`) now persists to
**IndexedDB** (`@tanstack/react-query-persist-client` +
`@tanstack/query-async-storage-persister` + `idb-keyval`). Revisits paint
instantly from cache (~2 MB of JSON no longer re-downloaded cold) and
revalidate in the background. Cache busts automatically on each release
(`buster = APP.version`, `maxAge` 7 days). PAT-gated data is never persisted.
- **Custom error pages** — a status-aware
[`ErrorPage`](webapp/src/components/error-page.tsx) (400, 401, 403, 404, 408,
419, 429, 500, 502, 503, 504, offline, unknown) wired into every route's
error branch with the *real* HTTP status (`fetchRaw` now throws a typed
`HttpError`), plus:
- a route-level **ErrorBoundary** that detects stale-chunk failures after a
redeploy and offers a one-click reload ("New version available"),
- a hidden `/#/errors/:code` preview route,
- a static `webapp/public/404.html` served by
GitHub Pages for bad path URLs (bilingual, dark-mode aware, zero JS).
### Changed
- `ReactQueryDevtools` is now explicitly gated behind `import.meta.env.DEV`.
- Game thumbnails render through a shared
[`GameThumb`](webapp/src/components/game-thumb.tsx) that falls back to the
muted placeholder when a cover 404s; the Settings avatar is now lazy-loaded.
- `idb-keyval` returns (removed as unused in v3.5.2 — it has a real consumer
now); `THIRD_PARTY` in `about.ts` lists the three new data-layer deps.
### Notes
- The About page's legal/credits data intentionally stays English (controlling
language for legal interpretation); Vietnamese policy docs remain under
[`docs/i18n/vi/`](docs/i18n/vi).
- No Tauri / Rust binary boundary change — `Cargo.toml` / `tauri.conf.json`
stay at `0.1.1`.
## [3.5.2] - 2026-05-23 (Dead-code cleanup — knip + vulture)
### Added
- **knip** (v6) wired into the webapp as the unused-files / exports /
dependencies detector — config in [`webapp/knip.json`](webapp/knip.json),
run via `cd webapp && npm run knip`.
- **vulture** configured for the Python pipeline (`[tool.vulture]` in
[`pyproject.toml`](pyproject.toml)) — it catches dead functions, classes, and
attributes that ruff's `F` rules don't.
- **[`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md)** — a new doc attributing the
dev-only tooling (knip, vulture, ruff, ESLint, TypeScript), cross-linked from
[`docs/ACKNOWLEDGEMENTS.md`](docs/ACKNOWLEDGEMENTS.md).
### Removed
- **8 unused webapp dependencies**: `react-hook-form`, `@hookform/resolvers`,
`zod`, `idb-keyval`, `@radix-ui/react-dropdown-menu`,
`@radix-ui/react-tooltip`, `@tauri-apps/plugin-http`, `@tauri-apps/api`.
- **The unwired Tauri Phase-8b scrape-preview scaffold** —
`webapp/src/lib/tauri-scrape.ts` and `getRuntimeInfo` / `RuntimeInfo` in
[`runtime.ts`](webapp/src/lib/runtime.ts). It was documented but never wired
into any UI; [`webapp/TAURI.md`](webapp/TAURI.md) was trimmed to match.
- **~20 unused webapp exports / types** — dead helpers (`findChunkFor`,
`indexByUrl`, `rawUrl`, `useIndex`, `isIdleExpired`, …), the unused
`EDITABLE_FIELDS` / `READONLY_FIELDS` constants, and 7 unused shadcn/ui
primitive exports. Exports used only inside their own module were demoted
from `export` rather than deleted.
### Changed
- `webapp/src/lib/about.ts` `THIRD_PARTY` array trimmed to match the removed
dependencies.
### Notes
- DX / code-quality only — no runtime behaviour change. `isIdleExpired` was
already dead (nothing called it), so PAT idle auto-lock is unchanged — still
not enforced.
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json`
stay at `0.1.1`. The Rust `tauri-plugin-http` crate is now unreferenced from
the front-end — a candidate for a future Rust-side cleanup.
- knip + vulture join `npm run lint`, `ruff check`, and `npm audit` as the
standing pre-release QA pass.
## [3.5.1] - 2026-05-20 (Lint cleanup — zero ESLint problems)
### Changed
- **`npm run lint` now runs clean — 0 errors, 0 warnings** (down from 17 errors + 5 warnings, all pre-existing; v3.5.0 added none).
- [`webapp/eslint.config.js`](webapp/eslint.config.js): `react-refresh/only-export-components` is turned off for `src/components/ui/**` — the vendored shadcn primitives intentionally mix component and variant/constant exports and cannot satisfy the rule without forking upstream. The rule stays on for all other app code.
- `react-hooks/incompatible-library` is turned off — it only flagged TanStack Table's `useReactTable`, whose API is not React-Compiler-memoizable by design (not actionable).
- **`SortableHeader` extracted** into its own [`webapp/src/components/data-table/sortable-header.tsx`](webapp/src/components/data-table/sortable-header.tsx); [`columns.tsx`](webapp/src/components/data-table/columns.tsx) is now a pure column-definition module.
### Fixed
- **`react-hooks/exhaustive-deps`** in [`routes/games.tsx`](webapp/src/routes/games.tsx) and [`data-table/faceted-filter.tsx`](webapp/src/components/data-table/faceted-filter.tsx): values built with `?? []` created a fresh array every render, defeating the `useMemo`s that depended on them. `data` is now wrapped in `useMemo`; the faceted-filter `selected` memo was restructured to depend on a stable value.
### Notes
- DX / code-quality only — no runtime behaviour change. No Tauri / Rust binary change (`Cargo.toml` / `tauri.conf.json` stay `0.1.1`); no `THIRD_PARTY` change.
---
## [3.5.0] - 2026-05-20 (Charts expansion + game-count history + pipeline cleanup)
### Added
- **Six new charts on `/charts`.**
- **Game count over time** — a `LineChart` of the catalog size by day, backed by a new `data_game/count_history.json` (date-keyed `{date, total}` series). [`scripts/data_store.py`](scripts/data_store.py) `_append_count_history()` upserts today's total on every catalog write (last-write-wins per UTC day). `scripts/backfill_count_history.py` is a one-time dev tool that reconstructs the series from git history (`data_game/index.json`, plus the pre-refactor `scripts/game_info.json`). The webapp loads it via `loadCountHistory` / `useCountHistory`.
- **Genre treemap** — a Recharts `Treemap` with a custom cell renderer that hides labels on rectangles too small to fit them, so it stays legible on mobile.
- **KPI summary cards** — total games / online / NSFW / deleted / average rating, above the Overview grid.
- **Deletions over time** (bar, by month), **Deletion reasons** (pie: became-paid vs page-removed), and **Most rated games** (top 10 by `rating_count`).
- **Scroll-to-top button** — a floating bottom-right button that appears after scrolling the main pane. New [`webapp/src/components/scroll-to-top.tsx`](webapp/src/components/scroll-to-top.tsx).
- **Python linting** — `ruff` config in a new root `pyproject.toml`; run `ruff check scripts/`.
### Changed
- **`charts.tsx` split into a module.** The monolith is now a `webapp/src/components/charts/` folder — one file per chart, a shared `chart-card.tsx` (`ChartCard` + `PALETTE`), and an `index.ts` barrel. 16 charts across the 4 tabs.
- **`scripts/json_io.py`** — new shared module. `load_json` / `save_json` (previously copy-pasted into both `check_alive.py` and `check_paid.py`) live here now, alongside `dedup_deleted`.
- README + README.vi badges bumped to `3.5.0`.
### Fixed
- **The deleted-games log can no longer accumulate duplicate URLs.** `check_alive.py` and `check_paid.py` appended to `scripts/deleted_games.json` with no guard — a game removed, re-added by the scraper, then removed again would be logged twice. The new `dedup_deleted()` (keyed by URL, keeping the earliest `deleted_at`) runs on every write and inside `log_deleted.py`. Two genuinely different games that share a title but have different urls are kept separate.
### Notes
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no `THIRD_PARTY` entries change (Recharts already shipped; `Treemap` / `LineChart` need no new dependency).
- `data_game/count_history.json` is auto-committed by the scrape workflows — the bash wrappers already `git add data_game/` wholesale, so no workflow changes were needed.
- The dead-code sweep found the project already tidy (TS strict mode + ESLint catch unused webapp code). `webapp/src/lib/tauri-scrape.ts` `tauriScrapePreview` was reviewed and intentionally kept as a Phase-8b stub.
---
## [3.4.1] - 2026-05-17 (Hotfix: DataTable column alignment + Discussion-announce auto-discovery)
### Fixed
- **DataTable columns misaligned at desktop widths.** Header used native table-layout (`<table className="w-full">` + `<th style={{width}}>`) while body rows used flex layout (`position: absolute` + `flex w-full`, cells with `flex: 0 0 Npx` / `1 1 0`). Native table-layout stretched the 8 size-less columns to fill the container based on content, but the absolutely-positioned body `<tr>` never participated in table layout — so its flex children stayed at their fixed flex-basis. Result: at the Tauri default 1280×800 window (and any viewport wider than the natural sum of header content widths) header columns drifted off the cells below them. [`webapp/src/components/data-table/data-table.tsx`](webapp/src/components/data-table/data-table.tsx) now renders the header `<tr>` with `flex w-full` and each `<th>` with `flex h-10 items-center` + the same `flex: 0 0 Npx` / `1 1 0` style block as the body `<td>` — header and body now compute width identically. Helper `priorityHeaderClass` (which emitted `table-cell` variants) is gone; the existing `priorityClass` (`flex` variants) now drives both. No change to column definitions in [`columns.tsx`](webapp/src/components/data-table/columns.tsx).
- **`announce-discussion.yml` was a silent no-op since v3.2.0.** Both jobs (`announce-release`, `announce-docs`) gated on three repo variables (`DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID`) that had never been configured — the validation step printed `::warning::… Skipping.` and `exit 0`, so every release silently failed to post to Discussions without surfacing a failed run. Replaced the two validation steps with a `Discover Discussion IDs` step that queries `gh api graphql` for `repository.id` and looks up the category by slug (`announcements` / `general`). Zero config now — works on any repo with Discussions enabled. Fails loudly with a clear `::error::` message if Discussions isn't enabled or the expected category is missing. Dropped the dependency on `vars.DISCUSSION_*` and removed every `if: steps.validate.outputs.ids_ok == 'true'` gate.
### Changed
- **README + README.vi badges** bumped to `3.4.1`.
### Notes
- This is a webapp + CI hotfix. No Python pipeline changes, no Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no THIRD_PARTY entries change.
- The leftover `DISCUSSION_REPO_ID` / `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID` / `DISCUSSION_GENERAL_CATEGORY_ID` repo variables (if you set them earlier) are now unused and can be removed from Settings → Variables.
---
## [3.4.0] - 2026-05-16 (Periodic refresh workflows + UTF-8 round-trip fix)
### Added
- **Update reviews — bi-weekly workflow.** New `scripts/update_reviews.py`, wrapper `bash/update_reviews.sh`, and `.github/workflows/update_reviews.yml` re-scrape every existing game's itch.io page on the 1st and 15th of each month (05:00 UTC) and write fresh `rating` + `rating_count`. Network errors / 404 keep the old values. Touches only those two fields — everything else (annotations, metadata) is left alone.
- **Update status — monthly workflow.** New `scripts/update_status.py`, `bash/update_status.sh`, and `.github/workflows/update_status.yml` refresh the `status` field on the 1st of each month (06:00 UTC). Same skip-on-error semantics.
- **Force update — manual emergency button.** New `scripts/force_update.py`, `bash/force_update.sh`, and [`.github/workflows/force_update.yml`](.github/workflows/force_update.yml) accept an optional `url` input. Empty input re-scrapes every game; a single URL targets just that one. `workflow_dispatch` only — no schedule. Every run preserves the three user-editable annotations (`safe_virus`, `notes`, `nsfw`) per the read/write field convention in [CLAUDE.md](CLAUDE.md). Doubles as the canonical repair tool for mojibake left by older webapp commits — re-scrape pulls clean UTF-8 from itch.io.
- **`generate_table.yml` chained on the three new workflows** so `lists/*.md` stay in sync after any data mutation.
### Fixed
- **UTF-8 mojibake on webapp commits.** `webapp/src/lib/github/contents.ts` `readFileWithSha` and `webapp/src/lib/github/git-data.ts` `bulkDeleteGames` were decoding GitHub's base64 content with `atob` alone, producing a Latin-1 binary string. Multi-byte UTF-8 sequences (e.g. Vietnamese `ã` = `0xC3 0xA3`) became two Latin-1 code points (`ã`); the next write re-encoded them as UTF-8 bytes, double-corrupting on every edit. Confirmed live damage in `data_game/game_info_002.json` (`BotÃÂão Esquerdo` was originally `Botão Esquerdo`). Extracted a shared helper `webapp/src/lib/github/encoding.ts` (`base64ToUtf8` / `utf8ToBase64`) that uses `TextDecoder('utf-8')` / `TextEncoder` and routes both call sites through it. Write path was already correct.
### Notes
- **Repair existing mojibake**: after this release deploys, run `Force update` once via `workflow_dispatch` with no input. It re-scrapes every game (~15–25 min) and writes back clean UTF-8 while preserving manual annotations. `generate_table.yml` will then auto-regenerate the markdown lists.
- **Browser cache**: anyone editing via the webapp should hard-refresh once after the new build lands so they're not using the pre-fix bundle (which would continue to mangle non-Latin chars on the next edit).
- **README + README.vi badges** bumped to `3.4.0`. No Tauri / Rust binary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`.
---
## [3.3.0] - 2026-05-16 (Mobile polish + Settings + in-browser GPG commit signing)
### Added
- **In-browser GPG commit signing.** Every write the webapp makes (single-file edits, bulk edit/delete, queueing URLs) can now be GPG-signed client-side. New `webapp/src/lib/gpg/` module: `canonicalize.ts` builds the exact byte string Git would hash, `sign.ts` lazy-imports `openpgp` and exposes `loadPrivateKey` / `signCommit` / `verifyDetached`, `storage.ts` wraps localStorage helpers. Verified byte-for-byte against `git cat-file commit <sha>` so the signed canonical exactly matches what GitHub will recompute (no trailing-newline drift). Private keys are decrypted once at import and re-encrypted with the webapp passphrase (AES-GCM, same scheme as the PAT) — `openpgp` is loaded only when the Commit Signing card is opened or a commit is being signed (`vendor-openpgp` chunk, ~129 KB gz, lazy).
- **Settings → Commit signing card.** New `webapp/src/components/settings/gpg-card.tsx` — three states (not configured / locked / unlocked) with Import (paste armored or upload `.asc`), Unlock, Test sign (round-trip verify), Copy public key, Lock, Remove. Shows the imported key's UIDs as badges and flags a clear mismatch warning if the configured commit-author email isn't in the key's UID list (the most common cause of GitHub's "Someone may be trying to trick you" warning). After import, primary UID email auto-populates Commit author so commits Verify on the first try.
- **Settings Phase A — Appearance / Session / Commit author / Notifications cards.** [`webapp/src/routes/settings.tsx`](webapp/src/routes/settings.tsx) gained four new cards backed by extended preferences in [`webapp/src/stores/prefs.ts`](webapp/src/stores/prefs.ts): theme picker (Light / Dark / System), layout density (Normal / Compact), sidebar collapse mirror, idle-timeout slider (5 / 15 / 30 / 60 / 120 min — replaces the hard-coded 30-min constant in `auth.ts`), commit-author name/email override, toast enable + duration. Density applies via `html[data-density='compact']` rules in [`index.css`](webapp/src/index.css); toasts are gated through a new [`AppToaster`](webapp/src/components/app-toaster.tsx) wrapper that reads prefs.
- **Mobile card view for the games table.** New [`webapp/src/lib/use-is-mobile.ts`](webapp/src/lib/use-is-mobile.ts) (`matchMedia('(max-width: 767px)')`) and [`webapp/src/components/data-table/mobile-card-list.tsx`](webapp/src/components/data-table/mobile-card-list.tsx). Below the `md` breakpoint, [`DataTable`](webapp/src/components/data-table/data-table.tsx) renders a stacked card list (thumbnail + name + dev + genre/status/NSFW/safe badges, tap-to-detail, selection checkbox) instead of the 9-column virtualized table that overflowed at 430 px. Pagination is shared between both views.
- **Workflows route mobile fallback.** `workflows.tsx` now dual-renders the action picker — a `<Select>` dropdown below `md`, the existing `TabsList` at `md` and above. Fixes the overflow from five `whitespace-nowrap` triggers in an `inline-flex` TabsList at 430 px viewport.
### Changed
- **All write paths route through the Git Data API.** `webapp/src/lib/github/contents.ts` `putFile` (`PUT /repos/.../contents/{path}`) is gone — that endpoint authors commits as the PAT and never accepts a `signature` field. Replaced with `commitSingleFile` which delegates to `atomicCommit` so single-file edits (game annotations, `temp_link.json` queue) get the same signer plumbing as bulk operations. `atomicCommit` gained an optional `signer` parameter (defaulting to `getSignerIfEnabled()`) that, when present, builds the canonical commit object, signs detached binary-mode via openpgp, and passes `author` / `committer` / `signature` to `git.createCommit`. Commit author identity falls back through prefs override → imported key's primary UID email → GitHub user.
- **About page** lists `OpenPGP.js` 6.3 under Data dependencies; the [`webapp/vite.config.ts`](webapp/vite.config.ts) `manualChunks` rule emits a dedicated `vendor-openpgp` chunk so the cost is only paid when a user opens the signing card.
- **README + README.vi badges** bumped to `3.3.0`.
### Fixed
- **Workflows `/workflows` tabs no longer overflow on mobile.** Pre-fix: five `whitespace-nowrap` triggers in an `inline-flex` TabsList blew past a 430 px viewport.
- **DataTable no longer overflows on mobile.** Pre-fix: nine fixed-width columns minus three responsive-hidden ones still exceeded 430 px.
---
## [3.2.1] - 2026-05-11 (Hotfix: single-instance enforcement on desktop)
### Fixed
- **Desktop app spawned a new process on every launch.** Each double-click of the installed app added another `free-games-itchio-webapp.exe` (Windows) / equivalent on macOS+Linux to the task list instead of focusing the existing window. Added [`tauri-plugin-single-instance`](https://tauri.app/plugin/single-instance/) v2 in [`webapp/src-tauri/src/lib.rs`](webapp/src-tauri/src/lib.rs) — second launch now unminimizes + focuses the running window and exits its own process before creating a duplicate. Plugin registered first in the builder chain per Tauri 2 docs so duplicate processes die before initializing HTTP/opener plugins. Gated by `#[cfg(desktop)]` + matching `cfg(not(android, ios))` in [`Cargo.toml`](webapp/src-tauri/Cargo.toml). Desktop binary boundary change → bumped [`Cargo.toml`](webapp/src-tauri/Cargo.toml) and [`tauri.conf.json`](webapp/src-tauri/tauri.conf.json) from `0.1.0` to `0.1.1` (first time these have moved since v3.0.0).
### Changed
- **README + README.vi badges** bumped to `3.2.1`.
- **About page** lists `tauri-plugin-single-instance` v2 under Desktop dependencies.
---
## [3.2.0] - 2026-05-10 (CI cleanup + mobile + SEO + Telegram bot path + auto-discussion)
### Added
- **Mobile drawer navigation.** New [`webapp/src/components/ui/sheet.tsx`](webapp/src/components/ui/sheet.tsx) (shadcn pattern over the existing `@radix-ui/react-dialog`) and a `MobileTopBar` in [`webapp/src/components/sidebar.tsx`](webapp/src/components/sidebar.tsx). Below `md`, the sidebar collapses behind a hamburger; above, the desktop sidebar behaves as before. Touch targets in the nav now meet the 44pt iOS HIG minimum on small screens.
- **DataTable column priorities.** Each column declares `meta.priority: 1 | 2 | 3` in [`columns.tsx`](webapp/src/components/data-table/columns.tsx). [`data-table.tsx`](webapp/src/components/data-table/data-table.tsx) hides priority 2 below `md` and priority 3 below `lg`, so the table is usable on a phone without horizontal scrolling through every column.
- **PWA manifest + icons.** [`webapp/public/manifest.webmanifest`](webapp/public/manifest.webmanifest), [`icon-192.png`](webapp/public/icon-192.png), [`icon-512.png`](webapp/public/icon-512.png) — Add to Home Screen on iOS without a service worker. Generator script: [`webapp/scripts/gen_assets.py`](webapp/scripts/gen_assets.py).
- **SEO infrastructure.** [`webapp/index.html`](webapp/index.html) now ships description, theme-color (per scheme), Open Graph (title/description/image/url/type/locale), Twitter card (`summary_large_image`), `canonical`, `apple-touch-icon`, `manifest`, and `preconnect` to `img.itch.zone` + `raw.githubusercontent.com`. [`robots.txt`](webapp/public/robots.txt) and `sitemap.xml` added under `webapp/public/`.
- **OG image.** [`webapp/public/og.png`](webapp/public/og.png) (1200×630) + [`og.webp`](webapp/public/og.webp) generated by `gen_assets.py`. Brand-coloured (`#863bff` purple, cyan accent) with project name, tagline, and URL.
- **Per-route titles.** New [`useDocumentTitle`](webapp/src/hooks/useDocumentTitle.ts) hook (no `react-helmet-async` dependency). Each route now sets a contextual title (`Charts — Itch.io Free Games Database`, etc.); game-detail uses the game name.
- **Hash-anchor scroll.** [`App.tsx`](webapp/src/App.tsx) now wires a `ScrollToHash` listener so links like `/about#support` scroll to the matching element under HashRouter.
- **About page Telegram entries.** New `messaging` social group with **Telegram (DM)** and **Telegram bot (game submission)** plus a privacy reminder to never paste a numeric ID into public channels. About also surfaces all five FUNDING.yml destinations (GitHub Sponsors, Patreon, Ko-fi, Buy Me a Coffee, PayPal) with a footnote on PayPal explaining the legal-name receipt.
- **Sidebar Support link.** Persistent heart-icon link from the sidebar (collapsed and expanded) to `/about#support`.
- **Telegram bot contribution flow.** `CONTRIBUTING.md §1b` describes the bot path (DM owner → numeric ID added to local whitelist → bot dispatches `bot-ingest.yml`). Cross-linked from [README.md](README.md), [README.vi.md](README.vi.md), and the new issue template `game_via_bot.yml`. Vietnamese mirror in [`docs/i18n/vi/CONTRIBUTING.md`](docs/i18n/vi/CONTRIBUTING.md).
- **Privacy + ToS clauses for the bot path.** [`docs/ToS.md §14`](docs/ToS.md) and [`docs/PrivacyPolicy.md §15`](docs/PrivacyPolicy.md) (plus VI mirrors) document Telegram-ID handling: opt-in, operator-side whitelist only, never committed to this repo, removable on DM.
- **`docs/pc_spec.md` + `docs/dev_env.md` (EN + VI).** Maintainer hardware spec, mobile test devices (iPhone 14 Pro / 13 Pro Max, iOS 26.x on Chrome + Brave), and dev-env toolchain (Python 3.12, Node ≥ 22, Rust stable, JetBrains 2026.x). Cross-linked from README and CONTRIBUTING.
- **Auto-create GitHub Discussion workflow.** [`announce-discussion.yml`](.github/workflows/announce-discussion.yml) — on `release: published` posts to the **Announcements** category; on push to `docs/**` / `CHANGELOG.md` / `README*.md` posts to **General**, gated by `[skip-discuss]` in the head-commit message and a quiet skip on `bot-ingest:` commits. Uses `gh api graphql` directly (no third-party action). Setup: configure repo variables `DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID` (run the GraphQL pre-flight query in the workflow header to fetch them).
### Changed
- **CI notify wrappers.** `notify-ci-failure.yml`, `notify-deploy.yml`, and [`notify-release-pipeline.yml`](.github/workflows/notify-release-pipeline.yml) replace `workflows: ["*"]` with explicit allowlists. Every workflow run no longer fans out to all three wrappers; the Actions tab is much quieter and the per-event reusable filtering is what it always should have been.
- **`bot-ingest.yml` cleanup.** Removed a dead final step that referenced a non-existent `${{ secrets.BOT_TOKEN }}` and a `result.txt` file. The Python `success`/`failure` Telegram callback steps above already handle both outcomes.
- **Image hints.** Game thumbnails in [`columns.tsx`](webapp/src/components/data-table/columns.tsx) and the hero in [`game-detail.tsx`](webapp/src/routes/game-detail.tsx) now declare `width`/`height` (CLS), `decoding="async"`, and `fetchPriority` (high for hero, low for table rows). itch.io thumbnails remain external — full WebP recompression is intentionally deferred (would require an image proxy).
- **About support card** mirrors `.github/FUNDING.yml` exactly: 5 entries (GitHub Sponsors, Patreon, Ko-fi, BMC, PayPal).
- **README + README.vi badges** bumped to `3.2.0`.
### Fixed
- **Bot ingest workflow** had a broken final telegram callback step (wrong secret name + missing input file). Removed; the working callback steps above are unaffected.
### Setup notes for maintainers (one-time, post-merge)
To enable the auto-discussion workflow, run once:
```sh
gh api graphql -f query='query{repository(owner:"poli0981",name:"free-games-itchio-list"){
id
discussionCategories(first:20){nodes{id slug name}}
}}'
```
Then in repo Settings → Secrets and variables → Actions → Variables, add:
- `DISCUSSION_REPO_ID` — the `repository.id` from the response.
- `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID` — the `id` of the Announcements category.
- `DISCUSSION_GENERAL_CATEGORY_ID` — the `id` of the General category.
Without these set, the workflow runs but no-ops with a warning (safe default).
---
## [3.1.4] - 2026-05-05 (Legal docs rewrite + Vietnamese i18n + Legal Card + UI polish)
### Added
- **Vietnamese translations** under [`docs/i18n/vi/`](docs/i18n/vi/) — full
translations of the four legal docs (DISCLAIMER, EULA, ToS, PrivacyPolicy)
plus CONTRIBUTING, CODE_OF_CONDUCT, and SECURITY. Each file notes that the
English version is the controlling text for legal interpretation.
- **`README.vi.md`** at repo root — Vietnamese mirror of the main README, with a
language badge and a link back to the English version.
- **About page → "Legal & policies" Card** — single place to access all policy
files (Disclaimer, EULA, ToS, Privacy, Code of Conduct, Security, License,
Changelog) plus a pointer to the Vietnamese translations.
- **`webapp/src/lib/about.ts`**: `LegalLink` interface + `LEGAL_LINKS` array +
`LEGAL_VI_INDEX_URL`. Same structured pattern as `THIRD_PARTY` and
`SOCIAL_LINKS`.
### Changed
- **`docs/DISCLAIMER.md`, `docs/EULA.md`, `docs/ToS.md`, `docs/PrivacyPolicy.md`**:
rewritten to be tighter and more enforceable while keeping the project's voice.
Each doc now has a TL;DR, numbered sections, definitions, severability,
governing law (Socialist Republic of Vietnam), explicit "not legal advice"
notice, and a removal-request path. Privacy Policy adds a per-storage table
for what the webapp persists locally and a step-by-step PAT lifecycle.
- **`README.md`** version badge → 3.1.4 plus a Vietnamese language badge and a
short pointer to `README.vi.md` and `docs/i18n/vi/`.
### Optional UI
- **Tauri desktop**: maximize button is now disabled (`maximizable: false` in
`webapp/src-tauri/tauri.conf.json`). Window is still resizable; only the
full-window-maximize action is locked.
- **DataTable**: scrollbar hidden via a new `.scrollbar-hide` Tailwind utility
added to `webapp/src/index.css`. Scrolling still works; the chrome is gone.
---
## [3.1.3] - 2026-05-05 (Credit Claude Code as AI co-author)
### Added
- **About page**: new **"AI co-authors"** Card listing both Grok (xAI) and
Claude Code (Anthropic — Claude Opus 4.7, 1M context) with their roles
in the repo's history. Each entry is linked + tagged with vendor and model.
- `webapp/src/lib/about.ts`: new `AiTool` interface + `AI_TOOLS` array so the
AI credit data is structured the same way as `THIRD_PARTY` and `SOCIAL_LINKS`.
### Changed
- **`docs/ACKNOWLEDGEMENTS.md`, `docs/My_Stuff.md`, `CONTRIBUTING.md`**:
surface Claude Code alongside Grok wherever the existing AI credit lived.
Grok references stay — both buddies share the workload now (Grok carried the
Python pipeline + v2.0.0 rewrite; Claude Code drove v3.0.0 webapp/Tauri and
v3.1.2). `My_Stuff.md` "The Real MVP" is now plural.
- `DEV.blurb` on the About page reflects the two-buddy reality.
---
## [3.1.2] - 2026-05-05 (Offline link fix + About expansion + docs sweep)
### Fixed
- **Tauri desktop**: external links (itch.io, GitHub, third-party home pages) now
open in the user's default browser instead of doing nothing. Added
`tauri-plugin-opener` (Rust + JS) and a scoped `opener:allow-open-url`
capability locked to `https://*` (no `file://` / `javascript:` schemes).
### Added
- **About page**: three new sections — Developer card, "Found a bug?" CTA that
opens the bug-report issue template, and "Find me elsewhere" with X, YouTube,
two Discord servers (Repo discussion / Game chat), Patreon, Ko-fi, Steam,
Bluesky, and Mastodon.
- **`<ExtLink>`** ([`webapp/src/components/ext-link.tsx`](webapp/src/components/ext-link.tsx))
— runtime-aware external-link wrapper used app-wide so the offline link bug
can't recur. On web it renders a plain `<a target="_blank">`; on Tauri it
routes through `tauri-plugin-opener`. All existing external `<a>` tags in
About, the sidebar footer, and Game Detail now use it.
### Changed
- **`webapp/README.md`**: rewritten from Vite boilerplate to actual webapp docs
(routes, dev/build commands, code-split layout, deploy, Tauri reference).
- **`CONTRIBUTING.md`, `docs/ACKNOWLEDGEMENTS.md`, `docs/My_Stuff.md`,
`README.md`**: refreshed contact / social handles. The "if I ever make a
Discord" line is finally obsolete — both servers exist.
---
## [3.0.0] - 2026-05-04 (Webapp + Desktop 🖥️📊)
A React + TypeScript SPA on top of the same JSON catalog, plus a Tauri 2 desktop wrapper.
The Python pipeline from 2.0.0 is untouched and still drives the daily data updates.
### Added (Webapp)
- **`webapp/`** — Vite + React 19 + TypeScript 6 + Tailwind v3 + shadcn/ui (Radix primitives).
Code-split, ~163 KB gzip initial load. Reads from `raw.githubusercontent.com` (public, no auth);
writes use a fine-grained GitHub PAT held only in memory after passphrase unlock.
- **8 routes**: Dashboard (KPIs), Games (virtualized DataTable + faceted filters), Game Detail
(23-field read view + edit form for `safe_virus` / `notes` / `nsfw`), Add (single URL +
bulk), Charts (9 Recharts visualizations in 4 tabs), Workflows (run history + Dispatch),
Deleted (tombstone log), Settings (PAT + theme), About (license attribution).
- **PAT encryption** — AES-GCM 256-bit, PBKDF2-SHA256 (100k iterations) with per-token salt.
Encrypted blob in localStorage; decrypted token in memory only.
- **Atomic bulk operations** — Bulk edit / delete via GitHub Git Data API (single commit for N
files), 20-entry undo stack with one-click revert.
- **Workflow dispatch from UI** — Add a single URL or queue a bulk batch directly to
`update.yml` via `workflow_dispatch`. Polls run status every 5 s and refreshes the table on
completion.
- **Sync button + manual refresh** — invalidate all data queries on demand; spinner reflects
in-flight state.
- **Collapsible sidebar** with rail mode (240 px ↔ 56 px).
- **Dark / Light / System theme** with `prefers-color-scheme` listener.
- **About page** — third-party license attribution by category, app version + build date.
### Added (Desktop wrapper)
- **`webapp/src-tauri/`** — Tauri 2 scaffold (Rust + WebView). Same React build, ~10 MB
installer.
- **`tauri-plugin-http`** scoped to `*.itch.io`, `img.itch.zone`, `api.github.com`,
`raw.githubusercontent.com`. Lets the desktop bypass CORS for direct itch.io previews.
- **`webapp/TAURI.md`** — local prerequisites (rustup + platform deps), dev/build commands,
roadmap to a full Rust scrape (Phase 8b).
### Added (CI)
- **`.github/workflows/deploy_webapp.yml`** — build `webapp/` and publish `docs/app/` to
GitHub Pages on push to `main` that touches `webapp/`. One-time setup: repo Settings →
Pages → Source = "GitHub Actions".
- **`.github/workflows/release_desktop.yml`** — multi-platform Tauri build via
`tauri-apps/tauri-action` on tag `v*`. Uploads `.msi` / `.dmg` / `.AppImage` to a draft
GitHub Release.
### Changed (Python pipeline)
- **`scripts/update_info.py`** now reads an optional `INPUT_URL` env var (forwarded by
`update.yml` from `workflow_dispatch.inputs.url`) and appends it to the queue. Backwards
compatible: the daily cron still processes `temp_link.json` exactly as before.
- **`.github/workflows/update.yml`** gains `workflow_dispatch.inputs.url` so the webapp can
trigger a single-URL scrape.
---
## [2.0.0] - 2026-03-26 (Major Rewrite 🔧⭐)
### Rewritten
- **`scraper.py`** — new shared module extracted from `update_info.py`. All scraping logic, session management, rate-limiting, and parsing utilities live here. Used by every script that touches itch.io.
- **`update_info.py`** — fully rewritten. Uses `scraper.py` module, `requests.Session` with automatic retry (backoff on 429/5xx), and random delays between requests.
- **`generate_md.py`** — fully rewritten with pipe-character escaping and all new data fields.
### Added
- **Free game detection** — `update_info.py` now checks if a game is free before scraping. Paid games are skipped automatically. Detection logic parses `div.buy_row` for price tags and button text.
- **`check_paid.py`** — new script. Re-checks every game in the list to see if it became paid. Paid games are removed and logged to `deleted_games.json` with reason and timestamp.
- **`check_alive.py`** — new script. Verifies that all game URLs still exist. Pages returning 404 or 410 are removed and logged. Transient errors (403, 5xx, timeouts) are kept.
- **`log_deleted.py`** — new script. Converts `deleted_games.json` → `deleted_games.txt` (human-readable log sorted by date).
- **`deleted_games.json`** — structured log of all removed games with URL, name, reason, and deletion timestamp.
- **New data fields** scraped from itch.io info table: `status`, `platforms`, `publisher`, `release_date`, `made_with`, `rating`, `rating_count`, `average_session`, `languages`, `inputs`. All fields default to `N/A` when not found.
- **Author/Authors handling** — scraper now checks both `Author` and `Authors` keys (itch.io uses either depending on the page).
- **Release date parsing** — extracted from `<abbr title="...">` for full datetime instead of abbreviated text.
- **NSFW detection** expanded — now also checks game description text and adds `sexual` keyword.
### Added (GitHub Actions)
- **`check_paid.yml`** — runs every 2 days at 04:00 UTC. Removes games that became paid.
- **`check_alive.yml`** — runs every 2 days at 07:00 UTC (staggered 3h after check_paid). Removes dead links.
- **`log_deleted.yml`** — runs after check_paid or check_alive completes. Exports deletion log.
- **`generate_table.yml`** — now triggers after update, check_paid, and check_alive workflows (not just update).
- **`update_csv.yml`** — now triggers after table generation (chained workflow).
### Improved
- **Rate limiting** — random delays (2.5–5s between requests, 15–30s batch pause every 20 requests) to avoid itch.io IP bans. Lighter delays (1–2.5s) for HEAD/status checks.
- **Retry logic** — `requests.Session` with `HTTPAdapter` + `Retry` (3 attempts, exponential backoff 2→4→8s) on 429/500/502/503/504.
- **Network error safety** — games are never deleted on transient network failures. Only confirmed 404/410 or confirmed paid status triggers removal.
- **Markdown table integrity** — pipe characters (`|`) in game data are escaped to prevent table breakage.
- **All fields use `N/A` consistently** — replaced mixed `""`, `"Unknown"`, `"No description"` with uniform `N/A` fallback.
### Changed
- Markdown table columns expanded: added Genre, Tags, Status, Platforms, Publisher, Release Date, Made With, Rating, Session, Languages, Inputs.
- README rewritten with updated architecture diagram, project structure, field documentation.
- Workflow action versions updated to `actions/checkout@v6` and `actions/setup-python@v6` with Python 3.14.
---
## [1.0.5] - 2026-01-12 (Hotfix 🔧)
### Fixed
- UTF-8 decode issue when running `scripts/update_info.py`. See [#16](https://github.com/poli0981/free-games-itchio-list/issues/16).
## [1.0.4] - 2026-01-11 (Added Games + New Features ⭐)
### Added Games
Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/issues/22) and [#23](https://github.com/poli0981/free-games-itchio-list/issues/23).
### New Features
- Delete game with correct link in `delete_game.py`. See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20).
- Export JSON → `.csv`/`.xlsx` in `export_csv.py`. See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21).
- Check duplicate data in JSON file in `check_duplicate.py`. See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19).
## [1.0.3] - Date unknown (Improvements ⚙️)
### Improved
- Optimized workflow scheduling.
## [1.0.2] - Date unknown (Hotfix 🔧)
### Fixed
- `temp_link.json` not resetting to `[]` after GitHub Actions run.
## [1.0.1] - 2025-12-31 (Hotfix 🔧)
### Fixed
- Rewrote and added 2 issue templates.
- Updated [CONTRIBUTING](CONTRIBUTING.md).
## [1.0.0] - 2025-12-28 (Initial Release 🚀)
### Added
- Full curated list of free itch.io games with auto-daily updates via GitHub Actions.
- Scraping script ([`update_info.py`](scripts/update_info.py)): add links → scrape title, dev, genre, description, NSFW flag, thumbnail.
- MD table generator (`generate_md.py`): split by genre, 300 max per file, in `/lists/`.
- Columns: No | Thumb | Name | Dev | Short Desc | Link | Safe | Notes | NSFW.
- [`temp_link.json`](/scripts/temp_link.json) for easy manual adds (Actions process daily).
- Full docs: [DISCLAIMER](/docs/DISCLAIMER.md), [PRIVACY](/docs/PrivacyPolicy.md), [TERMS](/docs/ToS.md), [EULA](/docs/EULA.md), [SECURITY](SECURITY.md), [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md), [CONTRIBUTING](CONTRIBUTING.md), [ACKNOWLEDGEMENTS](/docs/ACKNOWLEDGEMENTS.md).
- Issue and PR templates for bugs, features, and game submissions.
- Badges, TOC, and example table in [README](README.md).
### Fixed
- Multiple scrape bugs (itch.io HTML structure changes).
- Description length overflow → truncated to first sentence + "(see more on itch.io)".
- Table numbering resets per file, primary genre used for grouping.
All notable changes to this project, newest first. The notes of each release live in
[`changelog/`](changelog/), one file per minor version: `changelog/<major>.x/ver<major>.<minor>.x.md`.
**Latest release: [4.1.0](changelog/4.x/ver4.1.x.md#410---2026-09-24-verification-check-readable-charts-changelog-folder) (2026-09-24) — Verification check, readable charts, changelog folder.**
## 4.x
| Version | Date | Highlights |
|---|---|---|
| [4.1.0](changelog/4.x/ver4.1.x.md#410---2026-09-24-verification-check-readable-charts-changelog-folder) | 2026-09-24 | Verification check, readable charts, changelog folder |
| <a name="400---2026-09-18-freeitchgameswin-on-cloudflare-read-only-site-review-queue-new-design"></a>[4.0.0](changelog/4.x/ver4.0.x.md#400---2026-09-18-freeitchgameswin-on-cloudflare-read-only-site-review-queue-new-design) | 2026-09-18 | freeitchgames.win on Cloudflare: read-only site, review queue, new design |
## 3.x
| Version | Date | Highlights |
|---|---|---|
| <a name="390---2026-06-15-android-minsdk--11--api-30"></a>[3.9.0](changelog/3.x/ver3.9.x.md#390---2026-06-15-android-minsdk--11--api-30) | 2026-06-15 | Android minSdk → 11 / API 30 |
| <a name="380---2026-06-15-android-apk-target-"></a>[3.8.0](changelog/3.x/ver3.8.x.md#380---2026-06-15-android-apk-target-) | 2026-06-15 | Android APK target 📱 |
| <a name="371---2026-06-14-hotfix--desktop-build-vs-invalid-tauri-nsis-license-key"></a>[3.7.1](changelog/3.x/ver3.7.x.md#371---2026-06-14-hotfix--desktop-build-vs-invalid-tauri-nsis-license-key) | 2026-06-14 | Hotfix — desktop build vs invalid Tauri NSIS license key |
| <a name="370---2026-06-14-legal-acceptance-gates--per-tab-chart-lazy-loading"></a>[3.7.0](changelog/3.x/ver3.7.x.md#370---2026-06-14-legal-acceptance-gates--per-tab-chart-lazy-loading) | 2026-06-14 | Legal-acceptance gates + per-tab chart lazy-loading |
| <a name="361---2026-06-12-hotfix--desktop-build-vs-broken-time-0348"></a>[3.6.1](changelog/3.x/ver3.6.x.md#361---2026-06-12-hotfix--desktop-build-vs-broken-time-0348) | 2026-06-12 | Hotfix — desktop build vs broken `time` 0.3.48 |
| <a name="360---2026-06-12-i18n-envi--offline-cache--custom-error-pages"></a>[3.6.0](changelog/3.x/ver3.6.x.md#360---2026-06-12-i18n-envi--offline-cache--custom-error-pages) | 2026-06-12 | i18n EN/VI + offline cache + custom error pages |
| <a name="352---2026-05-23-dead-code-cleanup--knip--vulture"></a>[3.5.2](changelog/3.x/ver3.5.x.md#352---2026-05-23-dead-code-cleanup--knip--vulture) | 2026-05-23 | Dead-code cleanup — knip + vulture |
| <a name="351---2026-05-20-lint-cleanup--zero-eslint-problems"></a>[3.5.1](changelog/3.x/ver3.5.x.md#351---2026-05-20-lint-cleanup--zero-eslint-problems) | 2026-05-20 | Lint cleanup — zero ESLint problems |
| <a name="350---2026-05-20-charts-expansion--game-count-history--pipeline-cleanup"></a>[3.5.0](changelog/3.x/ver3.5.x.md#350---2026-05-20-charts-expansion--game-count-history--pipeline-cleanup) | 2026-05-20 | Charts expansion + game-count history + pipeline cleanup |
| <a name="341---2026-05-17-hotfix-datatable-column-alignment--discussion-announce-auto-discovery"></a>[3.4.1](changelog/3.x/ver3.4.x.md#341---2026-05-17-hotfix-datatable-column-alignment--discussion-announce-auto-discovery) | 2026-05-17 | Hotfix: DataTable column alignment + Discussion-announce auto-discovery |
| <a name="340---2026-05-16-periodic-refresh-workflows--utf-8-round-trip-fix"></a>[3.4.0](changelog/3.x/ver3.4.x.md#340---2026-05-16-periodic-refresh-workflows--utf-8-round-trip-fix) | 2026-05-16 | Periodic refresh workflows + UTF-8 round-trip fix |
| <a name="330---2026-05-16-mobile-polish--settings--in-browser-gpg-commit-signing"></a>[3.3.0](changelog/3.x/ver3.3.x.md#330---2026-05-16-mobile-polish--settings--in-browser-gpg-commit-signing) | 2026-05-16 | Mobile polish + Settings + in-browser GPG commit signing |
| <a name="321---2026-05-11-hotfix-single-instance-enforcement-on-desktop"></a>[3.2.1](changelog/3.x/ver3.2.x.md#321---2026-05-11-hotfix-single-instance-enforcement-on-desktop) | 2026-05-11 | Hotfix: single-instance enforcement on desktop |
| <a name="320---2026-05-10-ci-cleanup--mobile--seo--telegram-bot-path--auto-discussion"></a>[3.2.0](changelog/3.x/ver3.2.x.md#320---2026-05-10-ci-cleanup--mobile--seo--telegram-bot-path--auto-discussion) | 2026-05-10 | CI cleanup + mobile + SEO + Telegram bot path + auto-discussion |
| <a name="314---2026-05-05-legal-docs-rewrite--vietnamese-i18n--legal-card--ui-polish"></a>[3.1.4](changelog/3.x/ver3.1.x.md#314---2026-05-05-legal-docs-rewrite--vietnamese-i18n--legal-card--ui-polish) | 2026-05-05 | Legal docs rewrite + Vietnamese i18n + Legal Card + UI polish |
| <a name="313---2026-05-05-credit-claude-code-as-ai-co-author"></a>[3.1.3](changelog/3.x/ver3.1.x.md#313---2026-05-05-credit-claude-code-as-ai-co-author) | 2026-05-05 | Credit Claude Code as AI co-author |
| <a name="312---2026-05-05-offline-link-fix--about-expansion--docs-sweep"></a>[3.1.2](changelog/3.x/ver3.1.x.md#312---2026-05-05-offline-link-fix--about-expansion--docs-sweep) | 2026-05-05 | Offline link fix + About expansion + docs sweep |
| [3.1.1](changelog/3.x/ver3.1.x.md#311---2026-05-04-cross-compile-macos-x86_64-from-apple-silicon) | 2026-05-04 | Cross-compile macOS x86_64 from Apple Silicon |
| [3.1.0](changelog/3.x/ver3.1.x.md#310---2026-05-04-macos-dmg-fix--pkg-installer--pagination) | 2026-05-04 | macOS DMG fix + .pkg installer + pagination |
| [3.0.1](changelog/3.x/ver3.0.x.md#301---2026-05-04-tauri-icons--fine-grained-pat-fix) | 2026-05-04 | Tauri icons + fine-grained PAT fix |
| <a name="300---2026-05-04-webapp--desktop-️"></a>[3.0.0](changelog/3.x/ver3.0.x.md#300---2026-05-04-webapp--desktop-️) | 2026-05-04 | Webapp + Desktop 🖥️📊 |
## 2.x
| Version | Date | Highlights |
|---|---|---|
| <a name="200---2026-03-26-major-rewrite-"></a>[2.0.0](changelog/2.x/ver2.0.x.md#200---2026-03-26-major-rewrite-) | 2026-03-26 | Major Rewrite 🔧⭐ |
## 1.x
| Version | Date | Highlights |
|---|---|---|
| <a name="105---2026-01-12-hotfix-"></a>[1.0.5](changelog/1.x/ver1.0.x.md#105---2026-01-12-hotfix-) | 2026-01-12 | Hotfix 🔧 |
| <a name="104---2026-01-11-added-games--new-features-"></a>[1.0.4](changelog/1.x/ver1.0.x.md#104---2026-01-11-added-games--new-features-) | 2026-01-11 | Added Games + New Features ⭐ |
| <a name="103---date-unknown-improvements-️"></a>[1.0.3](changelog/1.x/ver1.0.x.md#103---2026-01-01-improvements-️) | 2026-01-01 | Improvements ⚙️ |
| <a name="102---date-unknown-hotfix-"></a>[1.0.2](changelog/1.x/ver1.0.x.md#102---2026-01-01-hotfix-) | 2026-01-01 | Hotfix 🔧 |
| <a name="101---2025-12-31-hotfix-"></a>[1.0.1](changelog/1.x/ver1.0.x.md#101---2025-12-31-hotfix-) | 2025-12-31 | Hotfix 🔧 |
| <a name="100---2025-12-28-initial-release-"></a>[1.0.0](changelog/1.x/ver1.0.x.md#100---2025-12-28-initial-release-) | 2025-12-28 | Initial Release 🚀 |
+19 -11
View File
@@ -8,7 +8,7 @@ A curated, auto-updating catalog of free itch.io games, published at **https://f
everyone; the old github.io URL only redirects). Three layers share one JSON catalog:
1. **Python pipeline** — the data layer (GitHub Actions).
- `data_game/game_info_NNN.json` — chunked records, max 500 per file, 2,681 games as of Sept 2026. Serialization is fixed: `json.dumps(..., ensure_ascii=False, indent=4)`, no trailing newline (`json_io.dumps`) — the Worker port (`webapp/worker/catalog.ts`) emits identical bytes (`tests/fixtures/golden/`).
- `data_game/game_info_NNN.json` — chunked records, max 500 per file, 2,811 games on 2026-09-24. Serialization is fixed: `json.dumps(..., ensure_ascii=False, indent=4)`, no trailing newline (`json_io.dumps`) — the Worker port (`webapp/worker/catalog.ts`) emits identical bytes (`tests/fixtures/golden/`).
- `data_game/index.json` — chunk manifest (total + per-file counts). `data_game/count_history.json` — date-keyed `{date,total}` series ("games over time" chart). `scripts/deleted_games.json` — removal log (public "Removed" page). `scripts/temp_link.json` — ingest queue.
- `scripts/` — scanners never write the catalog: `update_info.py` (queued URLs) and `refresh.py` (rotating 1/7-per-day check; `--full` re-scrape) emit a URL-keyed **patch** (`patch.py`); `apply_patch.py` applies it to the latest `main` and runs `validate.py`; `bash/commit_push.sh` does fetch → reset → apply → commit → push with retries. Shared: `scraper.py` (session, `Pacer` + 429 back-off, parsing), `data_store.py` (chunks stay in place, rebalance only past thresholds, write-if-changed), `json_io.py`, `canonical.py` (canonical itch.io URL; vectors in `tests/fixtures/url_vectors.json`, shared with the Worker). Pipeline bookkeeping lives in `scripts/state/` (not published). Tests: `pytest` (network blocked). Lint: `ruff check scripts tests webapp/scripts`, `ruff format`, `vulture` (config in root `pyproject.toml`). Local env: `python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt` (Windows: run with `PYTHONUTF8=1`).
2. **Cloudflare Worker + static assets** — `webapp/worker/` + `webapp/wrangler.jsonc`, deployed by **Cloudflare Workers Builds** from `main` (root dir `webapp`, build `npm run build`, deploy `npx wrangler deploy`; no deploy workflow). The catalog JSON is bundled into the site at build time (`vite-plugins/catalog-data.ts` → `dist/data/*`, plus `data/urls.json` and `sitemap.xml`), so every data commit rebuilds the site.
@@ -35,27 +35,29 @@ npm run tauri -- android init # generate src-tauri/gen/androi
npm run tauri -- android build --apk --target aarch64 # arm64-v8a release APK (unsigned; CI post-signs)
```
Local admin without Access: put `DEV_ADMIN_EMAIL=you@example.com` in `webapp/.dev.vars` — honoured only when the host is localhost. Turnstile test keys work locally (`TURNSTILE_SITEKEY=1x00000000000000000000AA`, `TURNSTILE_SECRET=1x0000000000000000000000000000000AA`, `SITE_ORIGIN=http://localhost:<port>` in `.dev.vars`). Android details live in `webapp/TAURI.md` → **Android APK**. Path alias: `@/*` → `webapp/src/*`.
Local admin without Access: put `DEV_ADMIN_EMAIL=you@example.com` in `webapp/.dev.vars` — honoured only when the host is localhost. Turnstile test keys work locally (`TURNSTILE_SITEKEY=1x00000000000000000000AA`, `TURNSTILE_SECRET=1x0000000000000000000000000000000AA`, `SITE_ORIGIN=http://localhost:<port>` in `.dev.vars`); add a 32+ character `GATE_SECRET` to try the verification gate under `npx wrangler dev` (on localhost the cookie is `fig_gate` without `Secure`, and no bot token is needed). `npm run dev` never sees the gate — except that its `/img` proxy to `wrangler dev` does. Android details live in `webapp/TAURI.md` → **Android APK**. Path alias: `@/*` → `webapp/src/*`.
## Worker (`webapp/worker/`)
- `index.ts` routes: `/img/*` (img.ts), `/api/health`, `/api/suggest` (suggest.ts), `/api/ingest` (ingest.ts), `/api/admin/*` + `/admin*` (admin.ts), everything else that misses an asset → `spa.ts`. `scheduled()` (cron `23 */4 * * *`): `discover.ts` (one itch.io RSS feed per run, 6 h back-off on 429) → `QueueStore.reconcile` (queued → ingested / failed after 3 days) → `purge` (idempotency 7 d, Suggest notes 180 d).
- `index.ts` routes: `/img/*` (img.ts, behind the gate), `/api/health`, `/api/verify` (gate.ts), `/api/suggest` (suggest.ts), `/api/ingest` (ingest.ts), `/api/admin/*` + `/admin*` (admin.ts), everything else that misses an asset → `spa.ts`. `run_worker_first` also lists `/` (otherwise served straight from `dist/index.html`) so the gate sees it. `scheduled()` (cron `23 */4 * * *`): `discover.ts` (one itch.io RSS feed per run, 6 h back-off on 429) → `QueueStore.reconcile` (queued → ingested / failed after 3 days) → `purge` (idempotency 7 d, Suggest notes 180 d).
- `img.ts`: `/img/<160|640>/<path on img.itch.zone>` — allow-listed against `data/urls.json`, edge cache → R2 `THUMBS` (`w{w}/<sha256>.webp`) → `cf.image` transform (stored once) → fallback streams the original with a 1-day cache (quota error 9422). Upstream errors → controlled 502.
- `spa.ts`: `not_found_handling` is `"none"`, so misses reach the Worker: `/assets/*`, `/data/*` and file-like paths get a real 404 (`no-store`); app routes get the shell with 200; unknown paths and game slugs not in the catalog get the shell with **404**. Keep its `ROUTES` in sync with `src/App.tsx` and `src/hooks/useSeoHead.ts`.
- `spa.ts`: `not_found_handling` is `"none"`, so misses reach the Worker: `/assets/*`, `/data/*` and file-like paths get a real 404 (`no-store`); app routes get the shell with 200; unknown paths and game slugs not in the catalog get the shell with **404**; with the gate on, a visitor without a pass gets the verification page instead (checked before the shell is fetched, so never a 304). Keep its `ROUTES` in sync with `src/App.tsx` and `src/hooks/useSeoHead.ts`.
- `gate.ts` + `gate-page.ts`: the **verification gate** (web only). App pages and `/img` need a pass: the `__Host-fig_gate` cookie (HMAC of its issue time, HttpOnly, `BOT_GATE_TTL_HOURS`, default 48) set by `POST /api/verify` after a Turnstile check (action `gate`, `RL_GATE`, same-origin); `GET /api/verify` reports `{enabled, valid, via, ttl}`. The page is self-contained (inline CSS/JS with a per-response CSP nonce, EN/VI, the site's og tags, 200 + noindex). Verified bots pass with `x-fig-known-bot: <GATE_BOT_TOKEN>` from a zone Transform Rule; clients that only claim to be a crawler get 503. `/assets`, `/data`, `/api/*`, `/admin*` and the other static files stay open. `turnstile.ts`: siteverify shared with Suggest (hostname + action checked; the test secrets skip both).
- `access.ts`: verifies `Cf-Access-Jwt-Assertion` with jose (issuer + AUD). Maintainer = email in secret `ADMIN_EMAILS` + same-origin writes; ingest = service-token `common_name`.
- `admin.ts`: API (queue list / approve / reject / add / edit the 3 fields / delete with reason + R2 cleanup / restore) and the `/admin` shell with its own CSP. The maintainer's email goes only to the D1 audit log, never into a commit (the repo is public).
- `repo.ts` + `github.ts` + `catalog.ts`: writes as a **GitHub App** (installation token, cached per isolate) with GraphQL `createCommitOnBranch` + `expectedHeadOid` (verified commits; `commitWithRetry` rebuilds from the new head on a race). Reads use the raw media type (no base64/UTF-8 mojibake). `catalog.ts` ports `data_store.py` byte-for-byte (golden fixtures).
- `queue.ts`: URL classification (catalog → blocklist → pending → previously deleted) + the D1 store (`worker/migrations/`, additive only — never edit an applied migration). `data.ts`: catalog facts read from the site's own `/data` via `env.ASSETS`, cached per isolate (loaded values only — see gotchas).
- Configuration: non-secret settings are `vars` in `wrangler.jsonc` (empty until setup); secrets (`GH_APP_PRIVATE_KEY` — the PEM GitHub downloads (PKCS#1) or PKCS#8; `github.ts` converts, `ADMIN_EMAILS`, `TURNSTILE_SECRET`) via `wrangler secret put`, typed in `worker/env.ts` as optional. A feature whose settings are missing answers **503**; the public site needs none of them. `env.staging` = Worker `free-games-itchio-list-staging` on `staging.freeitchgames.win` (no cron, own R2/D1/rate-limit namespaces).
- Configuration: non-secret settings are `vars` in `wrangler.jsonc` (empty until setup); secrets (`GH_APP_PRIVATE_KEY` — the PEM GitHub downloads (PKCS#1) or PKCS#8; `github.ts` converts, `ADMIN_EMAILS`, `TURNSTILE_SECRET`, `GATE_SECRET`, `GATE_BOT_TOKEN`) via `wrangler secret put`, typed in `worker/env.ts` as optional. A feature whose settings are missing answers **503** (the gate just stays off); the public site needs none of them. `env.staging` = Worker `free-games-itchio-list-staging` on `staging.freeitchgames.win` (no cron, own R2/D1/rate-limit namespaces).
## Web app structure (`webapp/src/`)
- `routes/*.tsx` — one file per route (`/`, `/games`, `/games/:slug`, `/charts`, `/removed` (`/deleted` redirects), `/suggest`, `/settings`, `/about`, `/errors/:code`); `App.tsx` wires them; `components/app-router.tsx` picks **BrowserRouter on the web, HashRouter in Tauri**. `lib/legacy.ts` rewrites v3 `#/x` links to `/x` (crafted hashes go home) and deletes v3 PAT/GPG storage keys.
- Data: `lib/config.ts` (`DATA_BASE` = `/data` on the web, `https://freeitchgames.win/data` in Tauri), `lib/data/*`, `hooks/useGames.ts`. react-query cache persisted to IndexedDB (`webapp.query-cache`, 7 days); `CACHE_BUSTER = ${APP.version}:data-v1`. **`gcTime` must stay >= persist `maxAge`.**
- Layout: `components/site/*` (sticky top nav + global search with the `/` shortcut + display menu + phone sheet menu; footer) — the window scrolls, not `<main>`. `/` is the Welcome page (`routes/welcome.tsx`).
- `/games`: search, filters, sort and page live in the URL — `lib/game-filters.ts` (`parseQuery` / `toParams` drop defaults; params `q genre platform status tag lang input engine rating browser sort page`; unit-tested) — rendered by `components/games/*` (filter chips with facet counts that ignore their own filter, a desktop ARIA table / phone list chosen by `useIsMobile`, 100 per page; the detail page's breadcrumb links back to the same list via router state). Counts show the whole catalog ("2,602 of 2,681") because 18+ games are hidden by default.
- `components/charts/` (16 charts, 4 lazy tabs, **no barrel `index.ts`**), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (a non-dismissable Radix dialog **over** the page, so deep links land where they pointed; links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes; no "Leave" button in Tauri).
- `/games`: search, filters, sort and page live in the URL — `lib/game-filters.ts` (`parseQuery` / `toParams` drop defaults; params `q genre platform status tag lang input engine rating browser sort page`; unit-tested) — rendered by `components/games/*` (filter chips with facet counts that ignore their own filter, a desktop ARIA table / phone list chosen by `useIsMobile`, 100 per page; the detail page's breadcrumb links back to the same list via router state). Counts show the whole catalog ("2,729 of 2,811") because 18+ games are hidden by default.
- `components/charts/` (16 charts, 4 lazy tabs, **no barrel `index.ts`**; every Recharts tooltip/cursor comes from `chart-theme.ts` + `chart-tooltip.tsx`), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (a non-dismissable Radix dialog **over** the page, so deep links land where they pointed; links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes; no "Leave" button in Tauri).
- Styling: **Tailwind v4** via `@tailwindcss/vite` (no PostCSS, no `tailwind.config`); tokens are hex CSS variables in `src/index.css` (`:root` / `.dark`, `@theme inline`; `--brand-soft`, `--thumb`, `--success` besides the shadcn set) and must match the approved mockup. Self-hosted Geist / Geist Mono (`@fontsource-variable/*`, CSP `font-src 'self'`). Numbers and dates go through `lib/format.ts` (`useFormat`: en-GB / vi-VN). `webapp/scripts/gen_assets.py` redraws favicon, PWA icons and `og.png` from the same tokens and the Geist fonts in `node_modules`.
- `lib/gate.ts` (web only): when a tab comes back into view or a cover fails and the verification pass may have run out (`webapp.gate` hint), it asks `GET /api/verify` and reloads into the verification page; `lib/reload.ts` is the shared at-most-every-30-s reload guard.
- `hooks/useSeoHead.ts` sets canonical + robots per route (index.html has no static canonical/og:url on purpose).
- `lib/i18n/` — `en.ts` is the source of truth; `vi.ts` is `Record<MessageKey, string>` and must never be static-imported (lazy chunk).
- `stores/` — Zustand: `prefs` (`webapp.prefs`: language, density, legal acceptance…), `theme` (`webapp.theme`).
@@ -76,9 +78,10 @@ Each game has **20** fields (plus optional `added_at` / `updated_at`, appended b
| `notify-failure.yml` | `workflow_call` | Discord (`DISCORD_CI_WEBHOOK`) on failure / **cancelled** (job-level timeouts end as cancelled) / rate-limited / mass change / failed Cloudflare build. |
| `python-ci.yml` / `webapp-ci.yml` | PRs (+ pushes for Python) | ruff + format + vulture + pytest + `validate.py` / `npm run cf:types -- --check` + lint + knip + vitest + build + `wrangler deploy --dry-run --env=""`. |
| `deploy-status.yml` | Hourly + manual | Not a deploy. `bash/cf_build_status.sh` walks main's first-parent history to the latest finished `Workers Builds: free-games-itchio-list` check run (Cloudflare posts it only when a build ends; branch commits carry preview builds under the same name) and alerts once per failed build (cache key per check-run id, saved after the Discord post). Scheduled because GitHub never starts `check_run` workflows for `GITHUB_TOKEN` pushes (the data commits). |
| `release_desktop.yml` | Tag `v*` push, or manual | `create-release` makes the single draft (id passed to tauri-action v1 `releaseId`); release builds use **no** npm/cargo caches (cache-poisoning). Win + macOS aarch64 + macOS x86_64 (cross-compile) + Linux (`ubuntu-22.04` for a low glibc floor). Uploads `.dmg` / `.app.tar.gz` / `.pkg` (macOS), `.msi` / `.exe` (Windows), `.deb` / `.AppImage` (Linux). macOS `.pkg` `--identifier` reads `tauri.conf.json`. |
| `release_desktop.yml` | Tag `v*` push, or manual | `create-release` makes the single draft (id passed to tauri-action v1 `releaseId`); release builds use **no** npm/cargo caches (cache-poisoning). Win + macOS aarch64 + macOS x86_64 (cross-compile) + Linux (`ubuntu-22.04` for a low glibc floor). Uploads `.dmg` / `.app.tar.gz` / `.pkg` (macOS), `.msi` / `.exe` (Windows), `.deb` / `.rpm` / `.AppImage` (Linux). macOS `.pkg` `--identifier` reads `tauri.conf.json`. |
| `release_android.yml` | Tag `v*` push, or manual | Tauri **Android** build → arm64-v8a APK, **post-signed** with `zipalign`+`apksigner` (gen/ stays gitignored). Tag → attaches to the same draft Release; manual dispatch → workflow artifact. Secrets: `ANDROID_KEYSTORE_BASE64` / `ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. |
| `announce-*.yml`, `notify-release-pipeline.yml` | Release published / pipeline runs | Reusable workflows from `poli0981/.github`, SHA-pinned — but at that pin they still check out their notifier script from that repo's `main`. |
| `announce-release.yml`, `notify-release-pipeline.yml` | Release published / pipeline runs | Reusable workflows from `poli0981/.github`, SHA-pinned — but at that pin they still check out their notifier script from that repo's `main`. |
| `announce-discussion.yml` | Release published; push to `main` touching `CHANGELOG.md` / `changelog/**` | Local. The release goes to Discussions → Announcements, a changelog push to → General unless the head commit says `[skip-discuss]`. |
All workflows: `permissions: {}` at the top, per-job grants, actions pinned by commit SHA.
@@ -93,7 +96,7 @@ git push origin vX.Y.Z
gh release edit vX.Y.Z --draft=false
```
Draft-first: **never** `gh release create` by hand before CI — tauri-action v1 refuses to upload into a published release, and announcements would go out before installers exist. Merge PRs into `main` with squash or a merge commit, never by fast-forward pushing a branch: its commits' preview-build check runs would then sit on main's own line and confuse `deploy-status.yml`. Tag from `main` only. Versions live in `webapp/src/lib/about.ts` (`APP.version`), `webapp/package.json`, `webapp/src-tauri/tauri.conf.json` and `Cargo.toml` (+ `Cargo.lock`) — keep them equal. GPG signing is wired through gpg-agent (`commit.gpgsign=true`, so `git tag -s` and `git commit` both sign; the pinentry must be answered — in unattended sessions commits fail rather than going unsigned). The historical key `03F965C2E2DB5C6B` was exposed in the browser extension's storage (Sept 2026) and is being replaced — use the maintainer's current key.
Draft-first: **never** `gh release create` by hand before CI — tauri-action v1 refuses to upload into a published release, and announcements would go out before installers exist. Merge PRs into `main` with squash or a merge commit, never by fast-forward pushing a branch: its commits' preview-build check runs would then sit on main's own line and confuse `deploy-status.yml`. Tag from `main` only. Release notes go to `changelog/<major>.x/ver<major>.<minor>.x.md` plus a row in the `CHANGELOG.md` index (each row keeps the anchor of the old single-file heading as `<a name>`: published release notes link to them). Versions live in `webapp/src/lib/about.ts` (`APP.version`), `webapp/package.json`, `webapp/src-tauri/tauri.conf.json` and `Cargo.toml` (+ `Cargo.lock`) — keep them equal. GPG signing is wired through gpg-agent (`commit.gpgsign=true`, so `git tag -s` and `git commit` both sign; the pinentry must be answered — in unattended sessions commits fail rather than going unsigned). The historical key `03F965C2E2DB5C6B` was exposed in the browser extension's storage (Sept 2026) and is being replaced — use the maintainer's current key.
## Licenses & policies
@@ -123,6 +126,9 @@ Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contri
20. **D1 migrations are applied by hand** (`npx wrangler d1 migrations apply freeitchgames --remote`), never in the build — and before deploying code that needs them. Production `freeitchgames` was created by command (APAC); its `database_id` is in `wrangler.jsonc` (not a secret). **R2 must be enabled on the account** (dashboard, payment method) before `wrangler r2 bucket create`; a deploy whose bucket is missing fails.
21. **React Router 8 wraps navigations in `startTransition` by default**: `useSearchParams` then returns the previous URL until the transition commits, so URL-driven state (the Games filters) overwrote itself on quick clicks. Both routers in `components/app-router.tsx` pass `useTransitions={false}`.
22. **`window.confirm` / `alert` / `prompt` do nothing in the macOS app** (wry's WebKit answers "Cancel"). Use in-app dialogs (`components/nsfw-dialog.tsx` + `requestNsfw()` in `lib/nsfw.ts`).
23. **The design tokens are hex: write `var(--x)`, never `hsl(var(--x))`.** The invalid colour painted the Recharts hover band black and left tooltips transparent (fixed in 4.1.0).
24. **Recharts 3 makes charts focusable** (`accessibilityLayer`, plus `tabindex` on inner `<g>`s): a mouse click focused the SVG, Chromium drew its black focus ring and the tooltip stuck on the first item. `ChartCard` keeps mouse clicks from moving focus; keyboard focus keeps the `--ring` outline.
25. **The verification gate fails open, and its off switch is deleting `GATE_SECRET`** (`BOT_GATE` changed in the dashboard is undone by the next deploy). It also needs `GATE_BOT_TOKEN` + the zone Transform Rule — without them Google would get the challenge; a client that only claims to be a crawler gets a 503, never the noindex page. Don't gate `/data`: the apps and CC BY reuse read it.
## Safe-edit rules
@@ -133,4 +139,6 @@ Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contri
## Current state (Sept 2026)
**v4 is live** (2026-09-18): Phase 0 (#81) and Phase 1 (#82) were squash-merged, then PR **#88** merged branch `v4` (phases 2–5 and the approved Phase 3 redesign) with a merge commit (`a872644`); Workers Builds deployed it and https://freeitchgames.win serves the Worker. D1 `freeitchgames` and R2 `freeitchgames-thumbs` exist, Image Transformations are on for the zone (source `img.itch.zone`). **Still open (owner):** Cloudflare Access apps + the `ACCESS_*` vars, the GitHub App (`GH_APP_*` vars + `GH_APP_PRIVATE_KEY`), Turnstile (`TURNSTILE_SITEKEY` + secret), `ADMIN_EMAILS`, Web Analytics token, Email Routing — admin, ingest and Suggest answer 503 until then (`docs/operations.md` section 1); tagging `v4.0.0` (draft-first release); the legal-text review items; a new GPG signing key (commits are still signed with the exposed `03F965C2E2DB5C6B`).
**v4.1.0** (2026-09-24): the Turnstile verification gate for the web app, readable chart tooltips, the changelog split into `changelog/`, a docs refresh, updated Privacy/ToS/EULA (`LEGAL_VERSION` 2026-09-24). The gate ships switched on in `wrangler.jsonc` but stays inert until `GATE_BOT_TOKEN`, the Transform Rule and `GATE_SECRET` are in place (`docs/operations.md` §1 step 14) — `curl -s https://freeitchgames.win/api/verify` says `"enabled"`.
**v4.0.0** (2026-09-18) moved the site to the Cloudflare Worker at https://freeitchgames.win (PRs #81, #82, #88). The whole chain is live: Access for `/admin`, the GitHub App (verified commits to `scripts/temp_link.json` → `update.yml`), Turnstile, `ADMIN_EMAILS`; D1 `freeitchgames`, R2 `freeitchgames-thumbs`, Image Transformations (source `img.itch.zone`); Web Analytics is injected by the zone. `/api/ingest` stays unused — the browser extension is archived. **Still open (owner):** Email Routing; the legal-text review items; a new GPG signing key (commits are still signed with the exposed `03F965C2E2DB5C6B`); deleting the unused repo secrets `GH_TOKEN`, `TELEGRAM_BOT_TOKEN`, `DISCUSSION_*`.
+1 -1
View File
@@ -68,7 +68,7 @@ Details live in the [Terms of Use](docs/ToS.md) and the [Disclaimer](docs/DISCLA
**PR rules** (the non-negotiable part):
- **CI must pass.** Python CI (ruff check + format, vulture, pytest, `validate.py`) and Webapp CI (type generation check, lint, knip, tests, build, `wrangler deploy --dry-run`) both run on PRs. Red CI = no merge.
- **PRs are squash-merged**: one PR becomes one commit on `main`, so make the PR title a good commit message (the repo uses the `type(scope): summary` style, e.g. `fix(web): …`).
- **PRs are merged with squash** (one PR becomes one commit on `main`) **or a merge commit, never by fast-forward**, so make the PR title a good commit message (the repo uses the `type(scope): summary` style, e.g. `fix(web): …`).
- **Licensing is inbound = outbound.** By opening a PR you agree that your contribution is licensed under the same license as the part it changes: **MIT** for code, **CC BY 4.0** for catalog data and documentation (see [README → License](README.md#license)). Only submit work you have the right to submit.
- **Never commit secrets**: no tokens, API keys, `.dev.vars` / `.env` files, private keys (such as the GitHub App key) or signing keystores. If you pushed one by accident, report it privately (security@freeitchgames.win) and rotate it; deleting the commit is not enough.
- **Don't edit `data_game/` by hand.** Data changes go through the pipeline (a patch + `apply_patch.py`, which runs `validate.py`), so concurrent writers never clobber each other.
+12 -7
View File
@@ -1,6 +1,6 @@
# Free Itch.io Games List
[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/poli0981/free-games-itchio-list/releases/latest)
[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](https://github.com/poli0981/free-games-itchio-list/releases/latest)
[![Website](https://img.shields.io/badge/website-freeitchgames.win-purple.svg)](https://freeitchgames.win)
[![Stars](https://img.shields.io/github/stars/poli0981/free-games-itchio-list?style=social)](https://github.com/poli0981/free-games-itchio-list/stargazers)
[![Forks](https://img.shields.io/github/forks/poli0981/free-games-itchio-list?style=social)](https://github.com/poli0981/free-games-itchio-list/network/members)
@@ -34,11 +34,14 @@ read-only for everyone: no accounts, no sign-in, no comments, no ads, no payment
Everything lives on the website, **<https://freeitchgames.win>**:
- **Games**: the whole catalog in one fast table (cards on phones), with filters for genre, platform,
- **Games**: the whole catalog in one fast table (a compact list on phones), with filters for genre, platform,
status and more, plus a detail page for every game.
- **Charts**: how the catalog breaks down, and how it has grown over time.
- **Removed**: every game dropped from the catalog, with the reason
(<https://freeitchgames.win/removed>).
- **A quick check first.** Your first visit, then about once every 48 hours, starts with a short
Cloudflare Turnstile check that keeps bots out. It usually passes by itself and then opens the page
you asked for. The catalog data under `/data` and the apps don't need it.
- **18+ content is hidden by default.** Games flagged `nsfw: Yes` stay hidden (covers included) unless
you opt in under Settings after confirming you are 18 or older. That choice is stored only in your
browser.
@@ -62,7 +65,7 @@ from the latest [GitHub Release](https://github.com/poli0981/free-games-itchio-l
|---|---|
| Windows | `.msi` or `.exe` installer |
| macOS | `.dmg`, `.pkg` or `.app.tar.gz` (needs Safari/WebKit 16.4 or newer) |
| Linux | `.deb` or `.AppImage` |
| Linux | `.deb`, `.rpm` or `.AppImage` |
| Android 11+ (arm64-v8a) | `.apk` (sideloaded, see below) |
The apps download the catalog JSON from <https://freeitchgames.win/data> and load cover images directly
@@ -150,9 +153,9 @@ The pipeline is polite to itch.io: it identifies itself as
## Under the hood
- **Web app** ([`webapp/src/`](webapp/src/)): React + TypeScript + Vite + Tailwind CSS, TanStack
Query / Table / Virtual, React Router, Zustand. English and Vietnamese UI.
- **Cloudflare Worker** ([`webapp/worker/`](webapp/worker/)): serves the site and `/data`, the image proxy
(`/img`, resized WebP covers stored on Cloudflare R2), the Suggest and ingest APIs, the review queue
Query, React Router, Zustand. English and Vietnamese UI.
- **Cloudflare Worker** ([`webapp/worker/`](webapp/worker/)): serves the site and `/data`, the verification gate
(Cloudflare Turnstile), the image proxy (`/img`, resized WebP covers stored on Cloudflare R2), the Suggest and ingest APIs, the review queue
(Cloudflare D1), the admin API and the RSS discovery schedule. Config:
[`webapp/wrangler.jsonc`](webapp/wrangler.jsonc).
- **Admin app** ([`webapp/admin/`](webapp/admin/)): the Maintainer-only review screen at `/admin`, behind
@@ -199,6 +202,7 @@ scripts/
└── state/ # Pipeline bookkeeping (last check, strikes, retries), not published
bash/commit_push.sh # fetch main → apply patch → validate → commit → push (with retries)
bash/cf_build_status.sh # main's latest Cloudflare Workers Build → Discord on failure (deploy-status.yml)
tests/ # pytest suite (no network) + fixtures shared with the Worker
webapp/
@@ -223,8 +227,9 @@ docs/ # Policies, dev environment, third-party list (+ Vietnam
| Refresh (`refresh.yml`) | Daily 02:47 UTC | Re-check 1/7 of the catalog: dead links, now-paid games, rating, status |
| Force update (`force_update.yml`) | Manual | Re-scrape every field (one URL or the next batch); keeps `safe_virus` / `notes` / `nsfw` |
| RSS discovery (Cloudflare Worker) | Every 4 hours | Poll one itch.io feed per run; new games go to the review queue |
| Python CI / Webapp CI | Pull requests | Lint, tests, data validation / type-check, tests, build |
| Python CI / Webapp CI | Pull requests (Python CI also on pushes to `main` that touch it) | Lint, tests, data validation / type-check, tests, build |
| Deploy website | On push to `main` | Cloudflare Workers Builds (`webapp/wrangler.jsonc`) → freeitchgames.win |
| Build monitor (`deploy-status.yml`) | Hourly | Posts each failed Workers Build of `main` to Discord, once |
| Release desktop / Android | On `v*` tag push | Tauri installers (Win/macOS/Linux) and signed APK → draft Release |
Network errors are treated as transient; a game is removed only after the same 404/410 or paid status is
+10 -7
View File
@@ -1,6 +1,6 @@
# Danh sách Game Itch.io Miễn Phí
[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/poli0981/free-games-itchio-list/releases/latest)
[![Version](https://img.shields.io/badge/version-4.1.0-blue.svg)](https://github.com/poli0981/free-games-itchio-list/releases/latest)
[![Website](https://img.shields.io/badge/website-freeitchgames.win-purple.svg)](https://freeitchgames.win)
[![Stars](https://img.shields.io/github/stars/poli0981/free-games-itchio-list?style=social)](https://github.com/poli0981/free-games-itchio-list/stargazers)
[![Forks](https://img.shields.io/github/forks/poli0981/free-games-itchio-list?style=social)](https://github.com/poli0981/free-games-itchio-list/network/members)
@@ -9,7 +9,7 @@
[![Data & docs: CC BY 4.0](https://img.shields.io/badge/data%20%26%20docs-CC%20BY%204.0-lightgrey.svg)](data_game/LICENSE.md)
[![English](https://img.shields.io/badge/lang-English-blue.svg)](README.md)
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
>
> Bản tiếng Anh tại [`README.md`](README.md) là bản chính thức. Bản dịch tiếng Việt của các tài liệu chính sách nằm trong [`docs/i18n/vi/`](docs/i18n/vi/).
@@ -34,9 +34,10 @@ Một danh mục được tuyển chọn và tự động cập nhật gồm **h
Mọi thứ nằm trên website **<https://freeitchgames.win>**:
- **Danh sách game**: toàn bộ danh mục trong một bảng chạy nhanh (dạng thẻ trên điện thoại), lọc theo thể loại, nền tảng, trạng thái và nhiều thứ khác, cùng một trang chi tiết cho từng game.
- **Danh sách game**: toàn bộ danh mục trong một bảng chạy nhanh (dạng danh sách gọn trên điện thoại), lọc theo thể loại, nền tảng, trạng thái và nhiều thứ khác, cùng một trang chi tiết cho từng game.
- **Biểu đồ**: danh mục được chia ra sao, và đã lớn lên thế nào theo thời gian.
- **Đã gỡ** (Removed): mọi game bị loại khỏi danh mục, kèm lý do (<https://freeitchgames.win/removed>).
- **Kiểm tra nhanh trước.** Lần đầu vào, rồi khoảng mỗi 48 giờ, trang sẽ chạy một bước kiểm tra Cloudflare Turnstile ngắn để chặn bot. Thường nó tự qua rồi mở đúng trang bạn cần. Dữ liệu trong `/data` và các ứng dụng không cần bước này.
- **Nội dung 18+ bị ẩn theo mặc định.** Game được đánh dấu `nsfw: Yes` sẽ bị ẩn (kể cả ảnh bìa) trừ khi bạn tự bật trong Settings sau khi xác nhận mình đủ 18 tuổi. Lựa chọn đó chỉ được lưu trong trình duyệt của bạn.
Mọi link đều dẫn tới trang riêng của game trên itch.io. Ảnh bìa trên website là bản thu nhỏ do freeitchgames.win phục vụ, nên trình duyệt của bạn không kết nối tới itch.io cho tới khi bạn bấm vào một link.
@@ -53,7 +54,7 @@ Cùng một app cũng được phát hành dưới dạng **ứng dụng native
|---|---|
| Windows | Trình cài đặt `.msi` hoặc `.exe` |
| macOS | `.dmg`, `.pkg` hoặc `.app.tar.gz` (cần Safari/WebKit 16.4 trở lên) |
| Linux | `.deb` hoặc `.AppImage` |
| Linux | `.deb`, `.rpm` hoặc `.AppImage` |
| Android 11+ (arm64-v8a) | `.apk` (cài tay, xem bên dưới) |
Các app tải JSON danh mục từ <https://freeitchgames.win/data> và tải ảnh bìa trực tiếp từ CDN ảnh của itch.io (`img.itch.zone`); bấm vào một game sẽ mở itch.io trong trình duyệt của bạn. Không có telemetry. Cập nhật thủ công: khi có bản mới thì tải bản mới về. Cài app đồng nghĩa với việc chấp nhận [EULA](docs/i18n/vi/EULA.md) ([EN](docs/EULA.md)).
@@ -106,8 +107,8 @@ Pipeline cư xử lịch sự với itch.io: nó tự xưng danh là `FreeItchGa
## Bên trong dự án
- **Web app** ([`webapp/src/`](webapp/src/)): React + TypeScript + Vite + Tailwind CSS, TanStack Query / Table / Virtual, React Router, Zustand. Giao diện tiếng Anh và tiếng Việt.
- **Cloudflare Worker** ([`webapp/worker/`](webapp/worker/)): phục vụ website và `/data`, proxy ảnh (`/img`, ảnh bìa WebP đã thu nhỏ lưu trên Cloudflare R2), API Suggest và ingest, hàng chờ duyệt (Cloudflare D1), API quản trị và lịch phát hiện qua RSS. Cấu hình: [`webapp/wrangler.jsonc`](webapp/wrangler.jsonc).
- **Web app** ([`webapp/src/`](webapp/src/)): React + TypeScript + Vite + Tailwind CSS, TanStack Query, React Router, Zustand. Giao diện tiếng Anh và tiếng Việt.
- **Cloudflare Worker** ([`webapp/worker/`](webapp/worker/)): phục vụ website và `/data`, cổng xác minh (Cloudflare Turnstile), proxy ảnh (`/img`, ảnh bìa WebP đã thu nhỏ lưu trên Cloudflare R2), API Suggest và ingest, hàng chờ duyệt (Cloudflare D1), API quản trị và lịch phát hiện qua RSS. Cấu hình: [`webapp/wrangler.jsonc`](webapp/wrangler.jsonc).
- **App quản trị** ([`webapp/admin/`](webapp/admin/)): màn hình duyệt chỉ dành cho Maintainer tại `/admin`, đứng sau Cloudflare Access. Nó ghi vào repo này dưới danh nghĩa một GitHub App.
- **Vỏ native** ([`webapp/src-tauri/`](webapp/src-tauri/)): Tauri 2 cho Windows, macOS, Linux và Android. Xem [`webapp/TAURI.md`](webapp/TAURI.md).
- **Pipeline dữ liệu** ([`scripts/`](scripts/), Python 3.14): scraper, refresh, patch/apply và validate, chạy bằng GitHub Actions.
@@ -147,6 +148,7 @@ scripts/
└── state/ # Sổ sách của pipeline (lần kiểm tra cuối, strike, lần thử lại), không công khai
bash/commit_push.sh # fetch main → áp patch → validate → commit → push (có thử lại)
bash/cf_build_status.sh # Workers Build mới nhất của main → báo Discord khi lỗi (deploy-status.yml)
tests/ # Bộ test pytest (không dùng mạng) + fixture dùng chung với Worker
webapp/
@@ -171,8 +173,9 @@ docs/ # Chính sách, môi trường dev, danh sách bên th
| Refresh (`refresh.yml`) | Hằng ngày 02:47 UTC | Kiểm tra lại 1/7 danh mục: link chết, game chuyển sang trả phí, rating, trạng thái |
| Force update (`force_update.yml`) | Thủ công | Cào lại mọi trường (một URL hoặc lô tiếp theo); giữ nguyên `safe_virus` / `notes` / `nsfw` |
| Phát hiện qua RSS (Cloudflare Worker) | Mỗi 4 giờ | Đọc một feed itch.io mỗi lượt; game mới vào hàng chờ duyệt |
| Python CI / Webapp CI | Pull request | Lint, test, validate dữ liệu / type-check, test, build |
| Python CI / Webapp CI | Pull request (Python CI còn chạy khi push vào `main` chạm tới phần Python) | Lint, test, validate dữ liệu / type-check, test, build |
| Deploy website | Khi push vào `main` | Cloudflare Workers Builds (`webapp/wrangler.jsonc`) → freeitchgames.win |
| Theo dõi build (`deploy-status.yml`) | Mỗi giờ | Báo mỗi Workers Build lỗi của `main` lên Discord, một lần |
| Release desktop / Android | Khi push tag `v*` | Trình cài đặt Tauri (Win/macOS/Linux) và APK đã ký → draft Release |
Lỗi mạng được coi là tạm thời; game chỉ bị gỡ khi cùng lỗi 404/410 hoặc trạng thái trả phí được thấy lại ít nhất 20 giờ sau lần đầu. Lỗi, lượt bị hủy, bị giới hạn tốc độ và thay đổi hàng loạt đáng ngờ được báo về Discord của dự án dưới dạng thông báo tự động.
+60
View File
@@ -0,0 +1,60 @@
# Changelog — 1.0.x
Release notes for 1.0.0 – 1.0.5, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [1.0.5] - 2026-01-12 (Hotfix 🔧)
### Fixed
- UTF-8 decode issue when running `scripts/update_info.py`. See [#16](https://github.com/poli0981/free-games-itchio-list/issues/16).
---
## [1.0.4] - 2026-01-11 (Added Games + New Features ⭐)
### Added Games
Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/issues/22) and [#23](https://github.com/poli0981/free-games-itchio-list/issues/23).
### New Features
- Delete game with correct link in `delete_game.py`. See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20).
- Export JSON → `.csv`/`.xlsx` in `export_csv.py`. See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21).
- Check duplicate data in JSON file in `check_duplicate.py`. See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19).
---
## [1.0.3] - 2026-01-01 (Improvements ⚙️)
### Improved
- Optimized workflow scheduling.
---
## [1.0.2] - 2026-01-01 (Hotfix 🔧)
### Fixed
- `temp_link.json` not resetting to `[]` after GitHub Actions run.
---
## [1.0.1] - 2025-12-31 (Hotfix 🔧)
### Fixed
- Rewrote and added 2 issue templates.
- Updated [CONTRIBUTING](../../CONTRIBUTING.md).
---
## [1.0.0] - 2025-12-28 (Initial Release 🚀)
### Added
- Full curated list of free itch.io games with auto-daily updates via GitHub Actions.
- Scraping script ([`update_info.py`](../../scripts/update_info.py)): add links → scrape title, dev, genre, description, NSFW flag, thumbnail.
- MD table generator (`generate_md.py`): split by genre, 300 max per file, in `/lists/`.
- Columns: No | Thumb | Name | Dev | Short Desc | Link | Safe | Notes | NSFW.
- [`temp_link.json`](/scripts/temp_link.json) for easy manual adds (Actions process daily).
- Full docs: [DISCLAIMER](/docs/DISCLAIMER.md), [PRIVACY](/docs/PrivacyPolicy.md), [TERMS](/docs/ToS.md), [EULA](/docs/EULA.md), [SECURITY](../../SECURITY.md), [CODE_OF_CONDUCT](../../CODE_OF_CONDUCT.md), [CONTRIBUTING](../../CONTRIBUTING.md), [ACKNOWLEDGEMENTS](/docs/ACKNOWLEDGEMENTS.md).
- Issue and PR templates for bugs, features, and game submissions.
- Badges, TOC, and example table in [README](../../README.md).
### Fixed
- Multiple scrape bugs (itch.io HTML structure changes).
- Description length overflow → truncated to first sentence + "(see more on itch.io)".
- Table numbering resets per file, primary genre used for grouping.
+40
View File
@@ -0,0 +1,40 @@
# Changelog — 2.0.x
Release notes for 2.0.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [2.0.0] - 2026-03-26 (Major Rewrite 🔧⭐)
### Rewritten
- **`scraper.py`** — new shared module extracted from `update_info.py`. All scraping logic, session management, rate-limiting, and parsing utilities live here. Used by every script that touches itch.io.
- **`update_info.py`** — fully rewritten. Uses `scraper.py` module, `requests.Session` with automatic retry (backoff on 429/5xx), and random delays between requests.
- **`generate_md.py`** — fully rewritten with pipe-character escaping and all new data fields.
### Added
- **Free game detection** — `update_info.py` now checks if a game is free before scraping. Paid games are skipped automatically. Detection logic parses `div.buy_row` for price tags and button text.
- **`check_paid.py`** — new script. Re-checks every game in the list to see if it became paid. Paid games are removed and logged to `deleted_games.json` with reason and timestamp.
- **`check_alive.py`** — new script. Verifies that all game URLs still exist. Pages returning 404 or 410 are removed and logged. Transient errors (403, 5xx, timeouts) are kept.
- **`log_deleted.py`** — new script. Converts `deleted_games.json` → `deleted_games.txt` (human-readable log sorted by date).
- **`deleted_games.json`** — structured log of all removed games with URL, name, reason, and deletion timestamp.
- **New data fields** scraped from itch.io info table: `status`, `platforms`, `publisher`, `release_date`, `made_with`, `rating`, `rating_count`, `average_session`, `languages`, `inputs`. All fields default to `N/A` when not found.
- **Author/Authors handling** — scraper now checks both `Author` and `Authors` keys (itch.io uses either depending on the page).
- **Release date parsing** — extracted from `<abbr title="...">` for full datetime instead of abbreviated text.
- **NSFW detection** expanded — now also checks game description text and adds `sexual` keyword.
### Added (GitHub Actions)
- **`check_paid.yml`** — runs every 2 days at 04:00 UTC. Removes games that became paid.
- **`check_alive.yml`** — runs every 2 days at 07:00 UTC (staggered 3h after check_paid). Removes dead links.
- **`log_deleted.yml`** — runs after check_paid or check_alive completes. Exports deletion log.
- **`generate_table.yml`** — now triggers after update, check_paid, and check_alive workflows (not just update).
- **`update_csv.yml`** — now triggers after table generation (chained workflow).
### Improved
- **Rate limiting** — random delays (2.5–5s between requests, 15–30s batch pause every 20 requests) to avoid itch.io IP bans. Lighter delays (1–2.5s) for HEAD/status checks.
- **Retry logic** — `requests.Session` with `HTTPAdapter` + `Retry` (3 attempts, exponential backoff 2→4→8s) on 429/500/502/503/504.
- **Network error safety** — games are never deleted on transient network failures. Only confirmed 404/410 or confirmed paid status triggers removal.
- **Markdown table integrity** — pipe characters (`|`) in game data are escaped to prevent table breakage.
- **All fields use `N/A` consistently** — replaced mixed `""`, `"Unknown"`, `"No description"` with uniform `N/A` fallback.
### Changed
- Markdown table columns expanded: added Genre, Tags, Status, Platforms, Publisher, Release Date, Made With, Rating, Session, Languages, Inputs.
- README rewritten with updated architecture diagram, project structure, field documentation.
- Workflow action versions updated to `actions/checkout@v6` and `actions/setup-python@v6` with Python 3.14.
+58
View File
@@ -0,0 +1,58 @@
# Changelog — 3.0.x
Release notes for 3.0.0 – 3.0.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.0.1] - 2026-05-04 (Tauri icons + fine-grained PAT fix)
This release has no changelog entry of its own; its notes are on GitHub: <https://github.com/poli0981/free-games-itchio-list/releases/tag/v3.0.1>.
---
## [3.0.0] - 2026-05-04 (Webapp + Desktop 🖥️📊)
A React + TypeScript SPA on top of the same JSON catalog, plus a Tauri 2 desktop wrapper.
The Python pipeline from 2.0.0 is untouched and still drives the daily data updates.
### Added (Webapp)
- **`webapp/`** — Vite + React 19 + TypeScript 6 + Tailwind v3 + shadcn/ui (Radix primitives).
Code-split, ~163 KB gzip initial load. Reads from `raw.githubusercontent.com` (public, no auth);
writes use a fine-grained GitHub PAT held only in memory after passphrase unlock.
- **8 routes**: Dashboard (KPIs), Games (virtualized DataTable + faceted filters), Game Detail
(23-field read view + edit form for `safe_virus` / `notes` / `nsfw`), Add (single URL +
bulk), Charts (9 Recharts visualizations in 4 tabs), Workflows (run history + Dispatch),
Deleted (tombstone log), Settings (PAT + theme), About (license attribution).
- **PAT encryption** — AES-GCM 256-bit, PBKDF2-SHA256 (100k iterations) with per-token salt.
Encrypted blob in localStorage; decrypted token in memory only.
- **Atomic bulk operations** — Bulk edit / delete via GitHub Git Data API (single commit for N
files), 20-entry undo stack with one-click revert.
- **Workflow dispatch from UI** — Add a single URL or queue a bulk batch directly to
`update.yml` via `workflow_dispatch`. Polls run status every 5 s and refreshes the table on
completion.
- **Sync button + manual refresh** — invalidate all data queries on demand; spinner reflects
in-flight state.
- **Collapsible sidebar** with rail mode (240 px ↔ 56 px).
- **Dark / Light / System theme** with `prefers-color-scheme` listener.
- **About page** — third-party license attribution by category, app version + build date.
### Added (Desktop wrapper)
- **`webapp/src-tauri/`** — Tauri 2 scaffold (Rust + WebView). Same React build, ~10 MB
installer.
- **`tauri-plugin-http`** scoped to `*.itch.io`, `img.itch.zone`, `api.github.com`,
`raw.githubusercontent.com`. Lets the desktop bypass CORS for direct itch.io previews.
- **`webapp/TAURI.md`** — local prerequisites (rustup + platform deps), dev/build commands,
roadmap to a full Rust scrape (Phase 8b).
### Added (CI)
- **`.github/workflows/deploy_webapp.yml`** — build `webapp/` and publish `docs/app/` to
GitHub Pages on push to `main` that touches `webapp/`. One-time setup: repo Settings →
Pages → Source = "GitHub Actions".
- **`.github/workflows/release_desktop.yml`** — multi-platform Tauri build via
`tauri-apps/tauri-action` on tag `v*`. Uploads `.msi` / `.dmg` / `.AppImage` to a draft
GitHub Release.
### Changed (Python pipeline)
- **`scripts/update_info.py`** now reads an optional `INPUT_URL` env var (forwarded by
`update.yml` from `workflow_dispatch.inputs.url`) and appends it to the queue. Backwards
compatible: the daily cron still processes `temp_link.json` exactly as before.
- **`.github/workflows/update.yml`** gains `workflow_dispatch.inputs.url` so the webapp can
trigger a single-URL scrape.
+95
View File
@@ -0,0 +1,95 @@
# Changelog — 3.1.x
Release notes for 3.1.0 – 3.1.4, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.1.4] - 2026-05-05 (Legal docs rewrite + Vietnamese i18n + Legal Card + UI polish)
### Added
- **Vietnamese translations** under [`docs/i18n/vi/`](../../docs/i18n/vi/) — full
translations of the four legal docs (DISCLAIMER, EULA, ToS, PrivacyPolicy)
plus CONTRIBUTING, CODE_OF_CONDUCT, and SECURITY. Each file notes that the
English version is the controlling text for legal interpretation.
- **`README.vi.md`** at repo root — Vietnamese mirror of the main README, with a
language badge and a link back to the English version.
- **About page → "Legal & policies" Card** — single place to access all policy
files (Disclaimer, EULA, ToS, Privacy, Code of Conduct, Security, License,
Changelog) plus a pointer to the Vietnamese translations.
- **`webapp/src/lib/about.ts`**: `LegalLink` interface + `LEGAL_LINKS` array +
`LEGAL_VI_INDEX_URL`. Same structured pattern as `THIRD_PARTY` and
`SOCIAL_LINKS`.
### Changed
- **`docs/DISCLAIMER.md`, `docs/EULA.md`, `docs/ToS.md`, `docs/PrivacyPolicy.md`**:
rewritten to be tighter and more enforceable while keeping the project's voice.
Each doc now has a TL;DR, numbered sections, definitions, severability,
governing law (Socialist Republic of Vietnam), explicit "not legal advice"
notice, and a removal-request path. Privacy Policy adds a per-storage table
for what the webapp persists locally and a step-by-step PAT lifecycle.
- **`README.md`** version badge → 3.1.4 plus a Vietnamese language badge and a
short pointer to `README.vi.md` and `docs/i18n/vi/`.
### Optional UI
- **Tauri desktop**: maximize button is now disabled (`maximizable: false` in
`webapp/src-tauri/tauri.conf.json`). Window is still resizable; only the
full-window-maximize action is locked.
- **DataTable**: scrollbar hidden via a new `.scrollbar-hide` Tailwind utility
added to `webapp/src/index.css`. Scrolling still works; the chrome is gone.
---
## [3.1.3] - 2026-05-05 (Credit Claude Code as AI co-author)
### Added
- **About page**: new **"AI co-authors"** Card listing both Grok (xAI) and
Claude Code (Anthropic — Claude Opus 4.7, 1M context) with their roles
in the repo's history. Each entry is linked + tagged with vendor and model.
- `webapp/src/lib/about.ts`: new `AiTool` interface + `AI_TOOLS` array so the
AI credit data is structured the same way as `THIRD_PARTY` and `SOCIAL_LINKS`.
### Changed
- **`docs/ACKNOWLEDGEMENTS.md`, `docs/My_Stuff.md`, `CONTRIBUTING.md`**:
surface Claude Code alongside Grok wherever the existing AI credit lived.
Grok references stay — both buddies share the workload now (Grok carried the
Python pipeline + v2.0.0 rewrite; Claude Code drove v3.0.0 webapp/Tauri and
v3.1.2). `My_Stuff.md` "The Real MVP" is now plural.
- `DEV.blurb` on the About page reflects the two-buddy reality.
---
## [3.1.2] - 2026-05-05 (Offline link fix + About expansion + docs sweep)
### Fixed
- **Tauri desktop**: external links (itch.io, GitHub, third-party home pages) now
open in the user's default browser instead of doing nothing. Added
`tauri-plugin-opener` (Rust + JS) and a scoped `opener:allow-open-url`
capability locked to `https://*` (no `file://` / `javascript:` schemes).
### Added
- **About page**: three new sections — Developer card, "Found a bug?" CTA that
opens the bug-report issue template, and "Find me elsewhere" with X, YouTube,
two Discord servers (Repo discussion / Game chat), Patreon, Ko-fi, Steam,
Bluesky, and Mastodon.
- **`<ExtLink>`** ([`webapp/src/components/ext-link.tsx`](../../webapp/src/components/ext-link.tsx))
— runtime-aware external-link wrapper used app-wide so the offline link bug
can't recur. On web it renders a plain `<a target="_blank">`; on Tauri it
routes through `tauri-plugin-opener`. All existing external `<a>` tags in
About, the sidebar footer, and Game Detail now use it.
### Changed
- **`webapp/README.md`**: rewritten from Vite boilerplate to actual webapp docs
(routes, dev/build commands, code-split layout, deploy, Tauri reference).
- **`CONTRIBUTING.md`, `docs/ACKNOWLEDGEMENTS.md`, `docs/My_Stuff.md`,
`README.md`**: refreshed contact / social handles. The "if I ever make a
Discord" line is finally obsolete — both servers exist.
---
## [3.1.1] - 2026-05-04 (Cross-compile macOS x86_64 from Apple Silicon)
This release has no changelog entry of its own; its notes are on GitHub: <https://github.com/poli0981/free-games-itchio-list/releases/tag/v3.1.1>.
---
## [3.1.0] - 2026-05-04 (macOS DMG fix + .pkg installer + pagination)
This release has no changelog entry of its own; its notes are on GitHub: <https://github.com/poli0981/free-games-itchio-list/releases/tag/v3.1.0>.
+65
View File
@@ -0,0 +1,65 @@
# Changelog — 3.2.x
Release notes for 3.2.0 – 3.2.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.2.1] - 2026-05-11 (Hotfix: single-instance enforcement on desktop)
### Fixed
- **Desktop app spawned a new process on every launch.** Each double-click of the installed app added another `free-games-itchio-webapp.exe` (Windows) / equivalent on macOS+Linux to the task list instead of focusing the existing window. Added [`tauri-plugin-single-instance`](https://tauri.app/plugin/single-instance/) v2 in [`webapp/src-tauri/src/lib.rs`](../../webapp/src-tauri/src/lib.rs) — second launch now unminimizes + focuses the running window and exits its own process before creating a duplicate. Plugin registered first in the builder chain per Tauri 2 docs so duplicate processes die before initializing HTTP/opener plugins. Gated by `#[cfg(desktop)]` + matching `cfg(not(android, ios))` in [`Cargo.toml`](../../webapp/src-tauri/Cargo.toml). Desktop binary boundary change → bumped [`Cargo.toml`](../../webapp/src-tauri/Cargo.toml) and [`tauri.conf.json`](../../webapp/src-tauri/tauri.conf.json) from `0.1.0` to `0.1.1` (first time these have moved since v3.0.0).
### Changed
- **README + README.vi badges** bumped to `3.2.1`.
- **About page** lists `tauri-plugin-single-instance` v2 under Desktop dependencies.
---
## [3.2.0] - 2026-05-10 (CI cleanup + mobile + SEO + Telegram bot path + auto-discussion)
### Added
- **Mobile drawer navigation.** New [`webapp/src/components/ui/sheet.tsx`](../../webapp/src/components/ui/sheet.tsx) (shadcn pattern over the existing `@radix-ui/react-dialog`) and a `MobileTopBar` in [`webapp/src/components/sidebar.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/sidebar.tsx). Below `md`, the sidebar collapses behind a hamburger; above, the desktop sidebar behaves as before. Touch targets in the nav now meet the 44pt iOS HIG minimum on small screens.
- **DataTable column priorities.** Each column declares `meta.priority: 1 | 2 | 3` in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/columns.tsx). [`data-table.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/data-table.tsx) hides priority 2 below `md` and priority 3 below `lg`, so the table is usable on a phone without horizontal scrolling through every column.
- **PWA manifest + icons.** [`webapp/public/manifest.webmanifest`](../../webapp/public/manifest.webmanifest), [`icon-192.png`](../../webapp/public/icon-192.png), [`icon-512.png`](../../webapp/public/icon-512.png) — Add to Home Screen on iOS without a service worker. Generator script: [`webapp/scripts/gen_assets.py`](../../webapp/scripts/gen_assets.py).
- **SEO infrastructure.** [`webapp/index.html`](../../webapp/index.html) now ships description, theme-color (per scheme), Open Graph (title/description/image/url/type/locale), Twitter card (`summary_large_image`), `canonical`, `apple-touch-icon`, `manifest`, and `preconnect` to `img.itch.zone` + `raw.githubusercontent.com`. [`robots.txt`](../../webapp/public/robots.txt) and `sitemap.xml` added under `webapp/public/`.
- **OG image.** [`webapp/public/og.png`](../../webapp/public/og.png) (1200×630) + [`og.webp`](../../webapp/public/og.webp) generated by `gen_assets.py`. Brand-coloured (`#863bff` purple, cyan accent) with project name, tagline, and URL.
- **Per-route titles.** New [`useDocumentTitle`](../../webapp/src/hooks/useDocumentTitle.ts) hook (no `react-helmet-async` dependency). Each route now sets a contextual title (`Charts — Itch.io Free Games Database`, etc.); game-detail uses the game name.
- **Hash-anchor scroll.** [`App.tsx`](../../webapp/src/App.tsx) now wires a `ScrollToHash` listener so links like `/about#support` scroll to the matching element under HashRouter.
- **About page Telegram entries.** New `messaging` social group with **Telegram (DM)** and **Telegram bot (game submission)** plus a privacy reminder to never paste a numeric ID into public channels. About also surfaces all five FUNDING.yml destinations (GitHub Sponsors, Patreon, Ko-fi, Buy Me a Coffee, PayPal) with a footnote on PayPal explaining the legal-name receipt.
- **Sidebar Support link.** Persistent heart-icon link from the sidebar (collapsed and expanded) to `/about#support`.
- **Telegram bot contribution flow.** `CONTRIBUTING.md §1b` describes the bot path (DM owner → numeric ID added to local whitelist → bot dispatches `bot-ingest.yml`). Cross-linked from [README.md](../../README.md), [README.vi.md](../../README.vi.md), and the new issue template `game_via_bot.yml`. Vietnamese mirror in [`docs/i18n/vi/CONTRIBUTING.md`](../../docs/i18n/vi/CONTRIBUTING.md).
- **Privacy + ToS clauses for the bot path.** [`docs/ToS.md §14`](../../docs/ToS.md) and [`docs/PrivacyPolicy.md §15`](../../docs/PrivacyPolicy.md) (plus VI mirrors) document Telegram-ID handling: opt-in, operator-side whitelist only, never committed to this repo, removable on DM.
- **`docs/pc_spec.md` + `docs/dev_env.md` (EN + VI).** Maintainer hardware spec, mobile test devices (iPhone 14 Pro / 13 Pro Max, iOS 26.x on Chrome + Brave), and dev-env toolchain (Python 3.12, Node ≥ 22, Rust stable, JetBrains 2026.x). Cross-linked from README and CONTRIBUTING.
- **Auto-create GitHub Discussion workflow.** [`announce-discussion.yml`](../../.github/workflows/announce-discussion.yml) — on `release: published` posts to the **Announcements** category; on push to `docs/**` / `CHANGELOG.md` / `README*.md` posts to **General**, gated by `[skip-discuss]` in the head-commit message and a quiet skip on `bot-ingest:` commits. Uses `gh api graphql` directly (no third-party action). Setup: configure repo variables `DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID` (run the GraphQL pre-flight query in the workflow header to fetch them).
### Changed
- **CI notify wrappers.** `notify-ci-failure.yml`, `notify-deploy.yml`, and [`notify-release-pipeline.yml`](../../.github/workflows/notify-release-pipeline.yml) replace `workflows: ["*"]` with explicit allowlists. Every workflow run no longer fans out to all three wrappers; the Actions tab is much quieter and the per-event reusable filtering is what it always should have been.
- **`bot-ingest.yml` cleanup.** Removed a dead final step that referenced a non-existent `${{ secrets.BOT_TOKEN }}` and a `result.txt` file. The Python `success`/`failure` Telegram callback steps above already handle both outcomes.
- **Image hints.** Game thumbnails in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.2.0/webapp/src/components/data-table/columns.tsx) and the hero in [`game-detail.tsx`](../../webapp/src/routes/game-detail.tsx) now declare `width`/`height` (CLS), `decoding="async"`, and `fetchPriority` (high for hero, low for table rows). itch.io thumbnails remain external — full WebP recompression is intentionally deferred (would require an image proxy).
- **About support card** mirrors `.github/FUNDING.yml` exactly: 5 entries (GitHub Sponsors, Patreon, Ko-fi, BMC, PayPal).
- **README + README.vi badges** bumped to `3.2.0`.
### Fixed
- **Bot ingest workflow** had a broken final telegram callback step (wrong secret name + missing input file). Removed; the working callback steps above are unaffected.
### Setup notes for maintainers (one-time, post-merge)
To enable the auto-discussion workflow, run once:
```sh
gh api graphql -f query='query{repository(owner:"poli0981",name:"free-games-itchio-list"){
id
discussionCategories(first:20){nodes{id slug name}}
}}'
```
Then in repo Settings → Secrets and variables → Actions → Variables, add:
- `DISCUSSION_REPO_ID` — the `repository.id` from the response.
- `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID` — the `id` of the Announcements category.
- `DISCUSSION_GENERAL_CATEGORY_ID` — the `id` of the General category.
Without these set, the workflow runs but no-ops with a warning (safe default).
+24
View File
@@ -0,0 +1,24 @@
# Changelog — 3.3.x
Release notes for 3.3.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.3.0] - 2026-05-16 (Mobile polish + Settings + in-browser GPG commit signing)
### Added
- **In-browser GPG commit signing.** Every write the webapp makes (single-file edits, bulk edit/delete, queueing URLs) can now be GPG-signed client-side. New `webapp/src/lib/gpg/` module: `canonicalize.ts` builds the exact byte string Git would hash, `sign.ts` lazy-imports `openpgp` and exposes `loadPrivateKey` / `signCommit` / `verifyDetached`, `storage.ts` wraps localStorage helpers. Verified byte-for-byte against `git cat-file commit <sha>` so the signed canonical exactly matches what GitHub will recompute (no trailing-newline drift). Private keys are decrypted once at import and re-encrypted with the webapp passphrase (AES-GCM, same scheme as the PAT) — `openpgp` is loaded only when the Commit Signing card is opened or a commit is being signed (`vendor-openpgp` chunk, ~129 KB gz, lazy).
- **Settings → Commit signing card.** New `webapp/src/components/settings/gpg-card.tsx` — three states (not configured / locked / unlocked) with Import (paste armored or upload `.asc`), Unlock, Test sign (round-trip verify), Copy public key, Lock, Remove. Shows the imported key's UIDs as badges and flags a clear mismatch warning if the configured commit-author email isn't in the key's UID list (the most common cause of GitHub's "Someone may be trying to trick you" warning). After import, primary UID email auto-populates Commit author so commits Verify on the first try.
- **Settings Phase A — Appearance / Session / Commit author / Notifications cards.** [`webapp/src/routes/settings.tsx`](../../webapp/src/routes/settings.tsx) gained four new cards backed by extended preferences in [`webapp/src/stores/prefs.ts`](../../webapp/src/stores/prefs.ts): theme picker (Light / Dark / System), layout density (Normal / Compact), sidebar collapse mirror, idle-timeout slider (5 / 15 / 30 / 60 / 120 min — replaces the hard-coded 30-min constant in `auth.ts`), commit-author name/email override, toast enable + duration. Density applies via `html[data-density='compact']` rules in [`index.css`](../../webapp/src/index.css); toasts are gated through a new [`AppToaster`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/app-toaster.tsx) wrapper that reads prefs.
- **Mobile card view for the games table.** New [`webapp/src/lib/use-is-mobile.ts`](../../webapp/src/lib/use-is-mobile.ts) (`matchMedia('(max-width: 767px)')`) and [`webapp/src/components/data-table/mobile-card-list.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/data-table/mobile-card-list.tsx). Below the `md` breakpoint, [`DataTable`](https://github.com/poli0981/free-games-itchio-list/blob/v3.3.0/webapp/src/components/data-table/data-table.tsx) renders a stacked card list (thumbnail + name + dev + genre/status/NSFW/safe badges, tap-to-detail, selection checkbox) instead of the 9-column virtualized table that overflowed at 430 px. Pagination is shared between both views.
- **Workflows route mobile fallback.** `workflows.tsx` now dual-renders the action picker — a `<Select>` dropdown below `md`, the existing `TabsList` at `md` and above. Fixes the overflow from five `whitespace-nowrap` triggers in an `inline-flex` TabsList at 430 px viewport.
### Changed
- **All write paths route through the Git Data API.** `webapp/src/lib/github/contents.ts` `putFile` (`PUT /repos/.../contents/{path}`) is gone — that endpoint authors commits as the PAT and never accepts a `signature` field. Replaced with `commitSingleFile` which delegates to `atomicCommit` so single-file edits (game annotations, `temp_link.json` queue) get the same signer plumbing as bulk operations. `atomicCommit` gained an optional `signer` parameter (defaulting to `getSignerIfEnabled()`) that, when present, builds the canonical commit object, signs detached binary-mode via openpgp, and passes `author` / `committer` / `signature` to `git.createCommit`. Commit author identity falls back through prefs override → imported key's primary UID email → GitHub user.
- **About page** lists `OpenPGP.js` 6.3 under Data dependencies; the [`webapp/vite.config.ts`](../../webapp/vite.config.ts) `manualChunks` rule emits a dedicated `vendor-openpgp` chunk so the cost is only paid when a user opens the signing card.
- **README + README.vi badges** bumped to `3.3.0`.
### Fixed
- **Workflows `/workflows` tabs no longer overflow on mobile.** Pre-fix: five `whitespace-nowrap` triggers in an `inline-flex` TabsList blew past a 430 px viewport.
- **DataTable no longer overflows on mobile.** Pre-fix: nine fixed-width columns minus three responsive-hidden ones still exceeded 430 px.
+40
View File
@@ -0,0 +1,40 @@
# Changelog — 3.4.x
Release notes for 3.4.0 – 3.4.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.4.1] - 2026-05-17 (Hotfix: DataTable column alignment + Discussion-announce auto-discovery)
### Fixed
- **DataTable columns misaligned at desktop widths.** Header used native table-layout (`<table className="w-full">` + `<th style={{width}}>`) while body rows used flex layout (`position: absolute` + `flex w-full`, cells with `flex: 0 0 Npx` / `1 1 0`). Native table-layout stretched the 8 size-less columns to fill the container based on content, but the absolutely-positioned body `<tr>` never participated in table layout — so its flex children stayed at their fixed flex-basis. Result: at the Tauri default 1280×800 window (and any viewport wider than the natural sum of header content widths) header columns drifted off the cells below them. [`webapp/src/components/data-table/data-table.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.4.1/webapp/src/components/data-table/data-table.tsx) now renders the header `<tr>` with `flex w-full` and each `<th>` with `flex h-10 items-center` + the same `flex: 0 0 Npx` / `1 1 0` style block as the body `<td>` — header and body now compute width identically. Helper `priorityHeaderClass` (which emitted `table-cell` variants) is gone; the existing `priorityClass` (`flex` variants) now drives both. No change to column definitions in [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.4.1/webapp/src/components/data-table/columns.tsx).
- **`announce-discussion.yml` was a silent no-op since v3.2.0.** Both jobs (`announce-release`, `announce-docs`) gated on three repo variables (`DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID`) that had never been configured — the validation step printed `::warning::… Skipping.` and `exit 0`, so every release silently failed to post to Discussions without surfacing a failed run. Replaced the two validation steps with a `Discover Discussion IDs` step that queries `gh api graphql` for `repository.id` and looks up the category by slug (`announcements` / `general`). Zero config now — works on any repo with Discussions enabled. Fails loudly with a clear `::error::` message if Discussions isn't enabled or the expected category is missing. Dropped the dependency on `vars.DISCUSSION_*` and removed every `if: steps.validate.outputs.ids_ok == 'true'` gate.
### Changed
- **README + README.vi badges** bumped to `3.4.1`.
### Notes
- This is a webapp + CI hotfix. No Python pipeline changes, no Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no THIRD_PARTY entries change.
- The leftover `DISCUSSION_REPO_ID` / `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID` / `DISCUSSION_GENERAL_CATEGORY_ID` repo variables (if you set them earlier) are now unused and can be removed from Settings → Variables.
---
## [3.4.0] - 2026-05-16 (Periodic refresh workflows + UTF-8 round-trip fix)
### Added
- **Update reviews — bi-weekly workflow.** New `scripts/update_reviews.py`, wrapper `bash/update_reviews.sh`, and `.github/workflows/update_reviews.yml` re-scrape every existing game's itch.io page on the 1st and 15th of each month (05:00 UTC) and write fresh `rating` + `rating_count`. Network errors / 404 keep the old values. Touches only those two fields — everything else (annotations, metadata) is left alone.
- **Update status — monthly workflow.** New `scripts/update_status.py`, `bash/update_status.sh`, and `.github/workflows/update_status.yml` refresh the `status` field on the 1st of each month (06:00 UTC). Same skip-on-error semantics.
- **Force update — manual emergency button.** New `scripts/force_update.py`, `bash/force_update.sh`, and [`.github/workflows/force_update.yml`](../../.github/workflows/force_update.yml) accept an optional `url` input. Empty input re-scrapes every game; a single URL targets just that one. `workflow_dispatch` only — no schedule. Every run preserves the three user-editable annotations (`safe_virus`, `notes`, `nsfw`) per the read/write field convention in [CLAUDE.md](../../CLAUDE.md). Doubles as the canonical repair tool for mojibake left by older webapp commits — re-scrape pulls clean UTF-8 from itch.io.
- **`generate_table.yml` chained on the three new workflows** so `lists/*.md` stay in sync after any data mutation.
### Fixed
- **UTF-8 mojibake on webapp commits.** `webapp/src/lib/github/contents.ts` `readFileWithSha` and `webapp/src/lib/github/git-data.ts` `bulkDeleteGames` were decoding GitHub's base64 content with `atob` alone, producing a Latin-1 binary string. Multi-byte UTF-8 sequences (e.g. Vietnamese `ã` = `0xC3 0xA3`) became two Latin-1 code points (`ã`); the next write re-encoded them as UTF-8 bytes, double-corrupting on every edit. Confirmed live damage in `data_game/game_info_002.json` (`BotÃÂão Esquerdo` was originally `Botão Esquerdo`). Extracted a shared helper `webapp/src/lib/github/encoding.ts` (`base64ToUtf8` / `utf8ToBase64`) that uses `TextDecoder('utf-8')` / `TextEncoder` and routes both call sites through it. Write path was already correct.
### Notes
- **Repair existing mojibake**: after this release deploys, run `Force update` once via `workflow_dispatch` with no input. It re-scrapes every game (~15–25 min) and writes back clean UTF-8 while preserving manual annotations. `generate_table.yml` will then auto-regenerate the markdown lists.
- **Browser cache**: anyone editing via the webapp should hard-refresh once after the new build lands so they're not using the pre-fix bundle (which would continue to mangle non-Latin chars on the next edit).
- **README + README.vi badges** bumped to `3.4.0`. No Tauri / Rust binary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`.
+97
View File
@@ -0,0 +1,97 @@
# Changelog — 3.5.x
Release notes for 3.5.0 – 3.5.2, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.5.2] - 2026-05-23 (Dead-code cleanup — knip + vulture)
### Added
- **knip** (v6) wired into the webapp as the unused-files / exports /
dependencies detector — config in [`webapp/knip.json`](../../webapp/knip.json),
run via `cd webapp && npm run knip`.
- **vulture** configured for the Python pipeline (`[tool.vulture]` in
[`pyproject.toml`](../../pyproject.toml)) — it catches dead functions, classes, and
attributes that ruff's `F` rules don't.
- **[`docs/THIRD_PARTY.md`](../../docs/THIRD_PARTY.md)** — a new doc attributing the
dev-only tooling (knip, vulture, ruff, ESLint, TypeScript), cross-linked from
[`docs/ACKNOWLEDGEMENTS.md`](../../docs/ACKNOWLEDGEMENTS.md).
### Removed
- **8 unused webapp dependencies**: `react-hook-form`, `@hookform/resolvers`,
`zod`, `idb-keyval`, `@radix-ui/react-dropdown-menu`,
`@radix-ui/react-tooltip`, `@tauri-apps/plugin-http`, `@tauri-apps/api`.
- **The unwired Tauri Phase-8b scrape-preview scaffold** —
`webapp/src/lib/tauri-scrape.ts` and `getRuntimeInfo` / `RuntimeInfo` in
[`runtime.ts`](../../webapp/src/lib/runtime.ts). It was documented but never wired
into any UI; [`webapp/TAURI.md`](../../webapp/TAURI.md) was trimmed to match.
- **~20 unused webapp exports / types** — dead helpers (`findChunkFor`,
`indexByUrl`, `rawUrl`, `useIndex`, `isIdleExpired`, …), the unused
`EDITABLE_FIELDS` / `READONLY_FIELDS` constants, and 7 unused shadcn/ui
primitive exports. Exports used only inside their own module were demoted
from `export` rather than deleted.
### Changed
- `webapp/src/lib/about.ts` `THIRD_PARTY` array trimmed to match the removed
dependencies.
### Notes
- DX / code-quality only — no runtime behaviour change. `isIdleExpired` was
already dead (nothing called it), so PAT idle auto-lock is unchanged — still
not enforced.
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json`
stay at `0.1.1`. The Rust `tauri-plugin-http` crate is now unreferenced from
the front-end — a candidate for a future Rust-side cleanup.
- knip + vulture join `npm run lint`, `ruff check`, and `npm audit` as the
standing pre-release QA pass.
---
## [3.5.1] - 2026-05-20 (Lint cleanup — zero ESLint problems)
### Changed
- **`npm run lint` now runs clean — 0 errors, 0 warnings** (down from 17 errors + 5 warnings, all pre-existing; v3.5.0 added none).
- [`webapp/eslint.config.js`](../../webapp/eslint.config.js): `react-refresh/only-export-components` is turned off for `src/components/ui/**` — the vendored shadcn primitives intentionally mix component and variant/constant exports and cannot satisfy the rule without forking upstream. The rule stays on for all other app code.
- `react-hooks/incompatible-library` is turned off — it only flagged TanStack Table's `useReactTable`, whose API is not React-Compiler-memoizable by design (not actionable).
- **`SortableHeader` extracted** into its own [`webapp/src/components/data-table/sortable-header.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/sortable-header.tsx); [`columns.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/columns.tsx) is now a pure column-definition module.
### Fixed
- **`react-hooks/exhaustive-deps`** in [`routes/games.tsx`](../../webapp/src/routes/games.tsx) and [`data-table/faceted-filter.tsx`](https://github.com/poli0981/free-games-itchio-list/blob/v3.5.1/webapp/src/components/data-table/faceted-filter.tsx): values built with `?? []` created a fresh array every render, defeating the `useMemo`s that depended on them. `data` is now wrapped in `useMemo`; the faceted-filter `selected` memo was restructured to depend on a stable value.
### Notes
- DX / code-quality only — no runtime behaviour change. No Tauri / Rust binary change (`Cargo.toml` / `tauri.conf.json` stay `0.1.1`); no `THIRD_PARTY` change.
---
## [3.5.0] - 2026-05-20 (Charts expansion + game-count history + pipeline cleanup)
### Added
- **Six new charts on `/charts`.**
- **Game count over time** — a `LineChart` of the catalog size by day, backed by a new `data_game/count_history.json` (date-keyed `{date, total}` series). [`scripts/data_store.py`](../../scripts/data_store.py) `_append_count_history()` upserts today's total on every catalog write (last-write-wins per UTC day). `scripts/backfill_count_history.py` is a one-time dev tool that reconstructs the series from git history (`data_game/index.json`, plus the pre-refactor `scripts/game_info.json`). The webapp loads it via `loadCountHistory` / `useCountHistory`.
- **Genre treemap** — a Recharts `Treemap` with a custom cell renderer that hides labels on rectangles too small to fit them, so it stays legible on mobile.
- **KPI summary cards** — total games / online / NSFW / deleted / average rating, above the Overview grid.
- **Deletions over time** (bar, by month), **Deletion reasons** (pie: became-paid vs page-removed), and **Most rated games** (top 10 by `rating_count`).
- **Scroll-to-top button** — a floating bottom-right button that appears after scrolling the main pane. New [`webapp/src/components/scroll-to-top.tsx`](../../webapp/src/components/scroll-to-top.tsx).
- **Python linting** — `ruff` config in a new root `pyproject.toml`; run `ruff check scripts/`.
### Changed
- **`charts.tsx` split into a module.** The monolith is now a `webapp/src/components/charts/` folder — one file per chart, a shared `chart-card.tsx` (`ChartCard` + `PALETTE`), and an `index.ts` barrel. 16 charts across the 4 tabs.
- **`scripts/json_io.py`** — new shared module. `load_json` / `save_json` (previously copy-pasted into both `check_alive.py` and `check_paid.py`) live here now, alongside `dedup_deleted`.
- README + README.vi badges bumped to `3.5.0`.
### Fixed
- **The deleted-games log can no longer accumulate duplicate URLs.** `check_alive.py` and `check_paid.py` appended to `scripts/deleted_games.json` with no guard — a game removed, re-added by the scraper, then removed again would be logged twice. The new `dedup_deleted()` (keyed by URL, keeping the earliest `deleted_at`) runs on every write and inside `log_deleted.py`. Two genuinely different games that share a title but have different urls are kept separate.
### Notes
- No Tauri / Rust binary boundary change — `Cargo.toml` and `tauri.conf.json` stay at `0.1.1`, no `THIRD_PARTY` entries change (Recharts already shipped; `Treemap` / `LineChart` need no new dependency).
- `data_game/count_history.json` is auto-committed by the scrape workflows — the bash wrappers already `git add data_game/` wholesale, so no workflow changes were needed.
- The dead-code sweep found the project already tidy (TS strict mode + ESLint catch unused webapp code). `webapp/src/lib/tauri-scrape.ts` `tauriScrapePreview` was reviewed and intentionally kept as a Phase-8b stub.
+72
View File
@@ -0,0 +1,72 @@
# Changelog — 3.6.x
Release notes for 3.6.0 – 3.6.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.6.1] - 2026-06-12 (Hotfix — desktop build vs broken `time` 0.3.48)
### Fixed
- **v3.6.0's desktop installers never built**: `time` 0.3.48 (released
2026-06-12, hours before the v3.6.0 tag) fails to compile inside
`tauri-utils` with `E0119: conflicting implementations of trait From<…>`
([time-rs/time#783](https://github.com/time-rs/time/issues/783)). Since no
`Cargo.lock` is committed, CI resolved the broken release fresh.
`webapp/src-tauri/Cargo.toml` now pins `time = "=0.3.47"` (the version every
release through v3.5.2 built with) — remove the pin once the upstream fix
ships.
### Notes
- Web feature set is identical to v3.6.0; this tag exists to produce the
desktop installers. `about.ts` version bump also busts the new IndexedDB
catalog cache, which is harmless.
- No Tauri version bump (`Cargo.toml` / `tauri.conf.json` stay `0.1.1`) — a
dependency pin to the previously-resolved version changes no binary
behavior.
---
## [3.6.0] - 2026-06-12 (i18n EN/VI + offline cache + custom error pages)
### Added
- **Bilingual UI (English / Tiếng Việt)** — a minimal typed i18n layer
([`webapp/src/lib/i18n/`](../../webapp/src/lib/i18n)) with ~340 keys covering every
route, dialog, chart, and toast. The Vietnamese dictionary is a **lazy-loaded
chunk**: it is only downloaded the first time the language is switched to VI
(or on startup when VI is the persisted preference). Switcher lives in
Settings → Appearance; the preference persists in `webapp.prefs`.
- **Offline-first catalog cache** — the react-query cache for the public
catalog queries (`db`, `deleted`, `count-history`) now persists to
**IndexedDB** (`@tanstack/react-query-persist-client` +
`@tanstack/query-async-storage-persister` + `idb-keyval`). Revisits paint
instantly from cache (~2 MB of JSON no longer re-downloaded cold) and
revalidate in the background. Cache busts automatically on each release
(`buster = APP.version`, `maxAge` 7 days). PAT-gated data is never persisted.
- **Custom error pages** — a status-aware
[`ErrorPage`](../../webapp/src/components/error-page.tsx) (400, 401, 403, 404, 408,
419, 429, 500, 502, 503, 504, offline, unknown) wired into every route's
error branch with the *real* HTTP status (`fetchRaw` now throws a typed
`HttpError`), plus:
- a route-level **ErrorBoundary** that detects stale-chunk failures after a
redeploy and offers a one-click reload ("New version available"),
- a hidden `/#/errors/:code` preview route,
- a static `webapp/public/404.html` served by
GitHub Pages for bad path URLs (bilingual, dark-mode aware, zero JS).
### Changed
- `ReactQueryDevtools` is now explicitly gated behind `import.meta.env.DEV`.
- Game thumbnails render through a shared
[`GameThumb`](../../webapp/src/components/game-thumb.tsx) that falls back to the
muted placeholder when a cover 404s; the Settings avatar is now lazy-loaded.
- `idb-keyval` returns (removed as unused in v3.5.2 — it has a real consumer
now); `THIRD_PARTY` in `about.ts` lists the three new data-layer deps.
### Notes
- The About page's legal/credits data intentionally stays English (controlling
language for legal interpretation); Vietnamese policy docs remain under
[`docs/i18n/vi/`](../../docs/i18n/vi).
- No Tauri / Rust binary boundary change — `Cargo.toml` / `tauri.conf.json`
stay at `0.1.1`.
+70
View File
@@ -0,0 +1,70 @@
# Changelog — 3.7.x
Release notes for 3.7.0 – 3.7.1, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.7.1] - 2026-06-14 (Hotfix — desktop build vs invalid Tauri NSIS license key)
### Fixed
- **v3.7.0's desktop installers never built.** The NSIS EULA was wired via
`bundle.windows.nsis.license`, but `@tauri-apps/cli` 2.11.0's `NsisConfig`
has no `license` key (it was added in a later release), so every platform
failed config validation at the `Build Tauri app` step. Switched to the
top-level `bundle.licenseFile` (valid in 2.11.0) pointing at an **RTF** EULA
([`webapp/src-tauri/installer/EULA.rtf`](../../webapp/src-tauri/installer/EULA.rtf)).
RTF satisfies **both** Windows bundlers — WiX (`.msi`) requires RTF and NSIS
(`.exe`) auto-detects it — so both installers show the "I Agree" page. The
previous plain-text `EULA.txt` would also have broken the WiX/`.msi` build.
### Notes
- Web feature set is identical to v3.7.0 (which deployed fine); this tag exists
to produce the desktop installers. `about.ts` version bump also busts the
IndexedDB catalog cache, which is harmless. No Tauri version bump
(`tauri.conf.json` stays `0.1.1`).
---
## [3.7.0] - 2026-06-14 (Legal-acceptance gates + per-tab chart lazy-loading)
### Added
- **First-launch legal-acceptance gate** — on first visit (and in every fresh
incognito session, since `localStorage` starts empty there) the app shows a
full-screen, non-dismissible gate before the main UI. It links the License,
EULA, Privacy Policy, Disclaimer, Terms of Use, Code of Conduct, and Security
Policy (reusing `LEGAL_LINKS`), and requires ticking a checkbox to continue.
New component [`webapp/src/components/legal-gate.tsx`](../../webapp/src/components/legal-gate.tsx),
built on raw Radix Dialog primitives (focus-trapped, no close-X, Esc /
outside-click disabled). Acceptance persists as `acceptedLegalVersion` in the
existing `webapp.prefs` localStorage blob — **no cookie** (consistent with the
"no cookies" privacy stance). A `LEGAL_VERSION` constant
([`webapp/src/stores/prefs.ts`](../../webapp/src/stores/prefs.ts)) lets a future
policy edit re-prompt every user with a one-line bump.
- **Windows installer EULA page** — both Windows installers (the NSIS `.exe`
and the WiX `.msi`) now show an "I Agree" license step before installing,
wired via the top-level `bundle.licenseFile` →
[`webapp/src-tauri/installer/EULA.rtf`](../../webapp/src-tauri/installer/EULA.rtf).
RTF is used so both bundlers render it (WiX requires RTF; NSIS auto-detects
it). The in-app gate above covers first-run consent on macOS / Linux, whose
installers have no equivalent step.
### Changed
- **Charts route split into four lazy per-tab chunks**
([`webapp/src/components/charts/tabs/`](../../webapp/src/components/charts/tabs)).
Each tab imports its chart components directly (the `charts/index.ts` barrel
was removed so the bundler keeps each tab's components in its own chunk).
Result: only the default **Overview** tab's components load when `/charts`
opens; the Reach / Quality / Discovery component code downloads on first
click. Recharts itself (the ~380 KB `vendor-charts` chunk) still loads with
Overview — unavoidable since the default tab renders charts — but it was
already deferred to the lazy `/charts` route, so it never touches app startup.
- `about.ts` version → 3.7.0 (also busts the IndexedDB catalog cache, harmless);
Claude Code co-author credit updated to Opus 4.8.
### Notes
- Images, routes, and OpenPGP were already lazy-loaded; this release closes the
remaining gap (charts). No Tauri version bump (`tauri.conf.json` stays
`0.1.1`) — the NSIS license is a bundler-config addition, not a binary change.
+37
View File
@@ -0,0 +1,37 @@
# Changelog — 3.8.x
Release notes for 3.8.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.8.0] - 2026-06-15 (Android APK target 📱)
### Added
- **Android APK build & packaging via Tauri mobile.** The same React + Tauri app now ships as a
sideloadable **arm64-v8a `.apk`** (no Play Store), built and **post-signed** (`zipalign` →
`apksigner`) by [`.github/workflows/release_android.yml`](../../.github/workflows/release_android.yml)
and attached to the same draft Release as the desktop installers (manual `workflow_dispatch`
uploads it as a downloadable workflow artifact instead). `gen/android` stays gitignored — signing
is a post-build step, not a Gradle edit. New repo secrets: `ANDROID_KEYSTORE_BASE64` /
`ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. Full build/signing docs in
[`webapp/TAURI.md`](../../webapp/TAURI.md).
- **Mobile UX** — the Android hardware / gesture back button is wired to in-app router history
(`useBackButton`), safe-area insets are respected, and the sidebar shows a platform-aware badge
("Mobile app" / "Desktop app").
- Added dependency: `@tauri-apps/api`.
### Changed
- **Bundle `identifier` is now alphanumeric** — `com.poli0981.freegamesitchio` (was the hyphenated
`com.poli0981.free-games-itchio-webapp`). Android rejects hyphens in the app id (`android init`
panics) and Tauri's validator rejects underscores, so alphanumeric is the only form valid on
both. Tauri uses one identifier across all platforms, so this also changed the **desktop** bundle
ID (a one-time OS-level reinstall).
- **Realigned versions** — `tauri.conf.json` / `Cargo.toml` / `about.ts` set to `3.8.0` (was a
long-standing `0.1.1` vs `3.x` drift), so `versionCode` / `versionName` are sensible and
monotonic.
### Notes
- CI: the Android JDK setup must **not** use `cache: gradle` — `gen/android` is gitignored and
generated mid-job, so there are no gradle files at checkout to key on (it hard-fails). rust-cache
+ npm cache still apply.
+36
View File
@@ -0,0 +1,36 @@
# Changelog — 3.9.x
Release notes for 3.9.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [3.9.0] - 2026-06-15 (Android minSdk → 11 / API 30)
### Changed
- **Android APK floor raised from API 24 (Android 7.0) to API 30 (Android 11).**
`minSdkVersion` in [`webapp/src-tauri/tauri.conf.json`](../../webapp/src-tauri/tauri.conf.json)
`bundle.android` is now `30`. Because Android's package installer refuses any APK whose
`minSdkVersion` exceeds the device API level, this **is** the install block — the app simply
can't install on Android < 11 ("app not installed / incompatible"); no runtime check by design.
Rationale, stated honestly:
- **Not a JS-feature floor** — the System WebView is independently updatable down to API 24, so
SubtleCrypto / OpenPGP.js / IndexedDB / ES2020 already work on older OSes. That's not the
binding constraint.
- **Security + patch availability** — Android 11 added scoped-storage enforcement, one-time /
auto-reset permissions, and a tighter sandbox; pre-11 releases are also off Google's AOSP
monthly Security Bulletins (Android 10 ended 2023-03-06, Android 11 ended 2024-02-05; only
14 / 15 / 16 remain as of mid-2026).
- **Tested range** — we validate only on Android 11+ (emulator 11 → latest; real phone
vivo 1907 / Android 12 — see [`docs/pc_spec.md`](../../docs/pc_spec.md)). Shipping an untested floor
was the real risk.
- **Reach cost is small** — API 30+ ≈ 86.9% of active devices (was 96.6% at API 24); only the
pre-2020 long tail is dropped.
Data sources: [endoflife.date/android](https://endoflife.date/android),
[Android Security Bulletins](https://source.android.com/docs/security/bulletin),
[StatCounter version share](https://gs.statcounter.com/android-version-market-share/mobile/worldwide/) (May 2026),
[apilevels.com](https://apilevels.com/) (StatCounter cumulative distribution, Apr 2026).
### Notes
- `versionCode` re-derives to `3009000` (see the Android `versionCode` gotcha in [CLAUDE.md](../../CLAUDE.md)). The web and desktop builds are unaffected by
the Android floor. The `about.ts` version bump busts the IndexedDB catalog cache (harmless).
+167
View File
@@ -0,0 +1,167 @@
# Changelog — 4.0.x
Release notes for 4.0.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [4.0.0] - 2026-09-18 (freeitchgames.win on Cloudflare: read-only site, review queue, new design)
Version 4 moves the website to **https://freeitchgames.win** on Cloudflare, makes it read-only for
everyone (no sign-in), adds a maintainer-only admin with a review queue for new games, replaces the
failing data crawls with a rotating refresh, and splits the licenses (code MIT, data and docs
CC BY 4.0).
### Upgrade notes
- **The web app no longer signs in or edits.** The GitHub-token (PAT) sign-in, in-app editing, the
Add / Workflows pages and GPG commit signing are gone; on first load the app deletes the
encrypted token and key it stored before. Suggest games at https://freeitchgames.win/suggest.
- **Old links keep working**: `…github.io/free-games-itchio-list/#/x` redirects to the new site,
and `#/x` links become `/x`.
- **Desktop and Android apps** are read-only viewers too; they read the catalog from
freeitchgames.win. Install 4.0.0 over 3.x as usual.
- **New legal terms** (ToS, Privacy Policy, EULA for the apps only, Disclaimer): the site asks you to
accept them again once.
### New design
- A clean, table-first interface under the name **Free Itch Games**: a top navigation bar with a
global search (press `/`) and a display menu (theme, language, density, 18+) replaces the
sidebar, and a **Welcome** page at `/` (catalog status, recently added games) replaces the
dashboard.
- **Games**: search plus filters for genre, platform, status, tags, language, input, engine,
minimum rating and "plays in browser", each showing how many games it would match. The search,
filters, sort and page are kept in the URL, so a filtered list can be bookmarked or shared. Phones
get a list layout.
- A new game page (cover, key facts, tags that open the matching list, "Report a problem"), a
searchable removed-games page and a simpler Settings page.
- The first-visit legal gate is now a dialog over the page, so a shared link opens where it
pointed once the terms are accepted.
- Tailwind CSS 4, the self-hosted Geist typefaces, new icons and social preview image; numbers and
dates follow the chosen language.
### Website & Worker
- The site is served by a Cloudflare Worker with static assets ([`webapp/wrangler.jsonc`](../../webapp/wrangler.jsonc),
[`webapp/worker/`](../../webapp/worker)) and the catalog JSON is bundled into every build (`/data/*`,
plus a sitemap), so each data commit republishes the site; the desktop/Android apps read the same
files. Real URL paths instead of `#/` routes, per-page canonical URLs, and real 404s for unknown
pages and missing files (a stale script after a deploy can no longer be cached as HTML).
- **Cover images** are resized once to small WebP copies (Cloudflare Image Transformations + R2)
and served from `/img/…` — about 4 KB instead of up to 3 MB per cover. Only catalog covers are
served.
- **18+ games are hidden by default**; a visitor can show them (Settings or the display menu) after
confirming they are 18 or older (stored only in their browser). The removed-games page is now
`/removed` (`/deleted` redirects there). Aggregate, cookieless Cloudflare Web Analytics.
- Enforced Content-Security-Policy and security headers; faster first load (~175 KB gzip, charts
load only when opened); browser floor Safari/iOS 15.4.
- React Router 8, React 19.3, Vite 8 (rolldown), vitest; unused sign-in dependencies (Octokit,
OpenPGP.js) removed; Tauri drops its HTTP plugin and `Cargo.lock` is committed.
### Adding games: review queue
- **Suggest page** (`/suggest`): anyone can send an itch.io link (+ optional note); protected by
Cloudflare Turnstile and a rate limit.
- **Browser extension API** (`POST /api/ingest`, Cloudflare Access service token, idempotent) —
the extension no longer needs a GitHub token.
- **RSS discovery**: every 4 hours the Worker reads one itch.io "new & popular free" feed.
- Everything lands in a **review queue** (Cloudflare D1). The maintainer approves or rejects it in
the new **admin** (`/admin`, Cloudflare Access), which also edits the three maintainer fields,
removes games with a public reason (deleting their resized covers) and restores removed games.
Approved games are committed by a GitHub App (verified commits) and scraped by the pipeline.
### Licenses & legal
- Code stays **MIT** (`LICENSE`, now "2025-2026 poli0981 (SkullMute)"); the catalog data
([`data_game/LICENSE.md`](../../data_game/LICENSE.md)) and the documentation are **CC BY 4.0**
([`LICENSES/CC-BY-4.0.txt`](../../LICENSES/CC-BY-4.0.txt)); creators' descriptions, cover images and
trademarks are excluded. [`NOTICE.md`](../../NOTICE.md) sums it up: not affiliated with itch.io.
- Rewritten Terms of Use (with a content-removal process), Privacy Policy (Cloudflare as
processor, exact browser storage, retention, rights under Vietnam's Law No. 91/2025/QH15 and the
GDPR), Disclaimer, Security Policy and Code of Conduct, in English and Vietnamese. The EULA now
covers only the desktop and Android apps. Contact addresses: legal@, privacy@, security@ and
takedown@freeitchgames.win.
- Issue templates: "Add games" points to the Suggest page, "Remove a game" gained a
rights-holder section; `CODEOWNERS` added.
### Fixed
- **freeitchgames.win served the unbuilt `webapp/` source tree** (blank page; `/package.json`,
`/src/*` publicly readable). The Vite web build now goes to `webapp/dist`, which
[`webapp/wrangler.jsonc`](../../webapp/wrangler.jsonc) deploys (`workers_dev`/`preview_urls` off).
- **All 15 Dependabot alerts / npm audit** — lockfile refreshed in-range (vite 8.3.0,
react-router-dom 7.18.4, postcss 8.5.28, patched transitive deps); `npm audit` reports 0.
- **Android release workflow** moved off Node 20 actions (setup-java v6, upload-artifact v7,
setup-android v4, checkout/setup-node v7), SHA-pinned, with a timeout and the tag passed via env.
- **`.gitattributes`** — `* text = auto` / `* eol = lf` were invalid (spaces around `=`); now
`* text=auto eol=lf` with binary rules, and legal/policy docs ship in source archives again.
- OG image, manifest (`start_url`/`scope`/`id` = `/`), canonical/og URLs, sitemap and robots now
point at freeitchgames.win; OG title no longer overflows.
### Data pipeline (rewrite)
- **One rotating refresh replaces four failing crawls.** `check_paid` / `check_alive` /
`update_reviews` / `update_status` each fetched all 2,600+ pages sequentially, overran their
job timeouts and — saving only at the end — lost every run since late June (with no alert,
because a timeout ends as *cancelled*). The new [`scripts/refresh.py`](../../scripts/refresh.py)
(`refresh.yml`, daily) checks one seventh of the catalog with **one request per game**, so every
game is re-checked weekly (~86% fewer requests to itch.io), and updates alive / paid / rating /
status (+ backfills release date, thumbnail, `updated_at`) from that single page.
- **Safer removals:** a game is removed only when the same 404/410 or paid status is seen again at
least 20 hours after it was first seen (single flaky responses no longer delete games). A
mass-change guard withholds removals — and alerts — when a run would remove or newly strike more
than max(10, 10%) of the games it checked (the signature of an itch.io markup change rather than
a real wave of paid games); withheld games stay withheld in later runs until a healthy check or
an explicit `allow_mass_removal` dispatch, checkpoints of an interrupted scan never remove games,
and `apply_patch.py` re-checks the limits. Overlapping scans can no longer undo each other's
newer checks.
- **Scan → patch → apply:** scanners emit a URL-keyed patch; [`apply_patch.py`](../../scripts/apply_patch.py)
applies it to the latest `main`, validates, and [`bash/commit_push.sh`](../../bash/commit_push.sh)
retries on push races. Concurrent writers (extension, workflows, future admin) no longer clobber
each other; checkpoints + an in-script deadline keep partial work.
- **Ingest** (`update.yml`, now runs as soon as the queue changes): canonical URLs, skips games in
the deleted log (the removed-then-re-added bug), retries transient failures (3 attempts at least
6 hours apart; rate limiting never counts) instead of dropping them, stamps `added_at`, and never
wipes links queued meanwhile. A dispatched `url` is processed first and kept in the queue until it
reaches a final outcome, and queued runs wait in FIFO order (`queue: max`) instead of replacing
each other.
- `force_update.yml` runs `refresh.py --full` in rotating batches (a full re-scrape no longer times out).
- Honest `FreeItchGamesBot` User-Agent, explicit 429 / Retry-After handling (capped), unbuffered
logs, run summaries, Discord alerts on failure / cancel / rate limit.
- `data_store.py` keeps games in their chunk and only writes changed bytes; `index.json` /
`count_history.json` change only when data does — no more no-op commits.
- New [`validate.py`](../../scripts/validate.py) (schema, canonical URLs, duplicates, index consistency)
gates every pipeline commit and runs in the new Python CI with a network-free pytest suite.
Normalized one invalid `safe_virus` value (`"y"` → `"Yes"`).
### Removed
- `lists/*.md` genre tables, `generate_md.py`, `generate_table.yml`, `deleted_games.txt`,
`log_deleted.*` — the catalog is web-only (freeitchgames.win).
- Telegram bot ingest (`bot-ingest.yml`, `game_via_bot` issue template) — retired.
- The web app's sign-in, editing, Add and Workflows pages, GPG signing, and the GitHub Pages
deployment (`deploy_webapp.yml`, `notify-deploy.yml`, `pages-redirect/`; Pages keeps serving the
redirect stub it last published).
- `notify-ci-failure.yml` (replaced by in-workflow notifications) and the old per-task bash wrappers.
### CI / security
- All actions SHA-pinned at current majors; `permissions: {}` by default with per-job grants;
reusable workflows pinned by SHA with only the secrets they need; script-injection patterns in
`announce-discussion.yml` fixed (and it now posts only for `CHANGELOG.md` changes).
- Release: one `create-release` job makes the draft that desktop (tauri-action v1, `releaseId`) and
Android upload into; release builds use no dependency caches. Publish with
`gh release edit vX --draft=false`.
- `.github/dependabot.yml` (npm / pip / actions / cargo), Python and web-app PR checks, and an
hourly check of main's latest Cloudflare Workers Build that posts each failed build to Discord
once (a `check_run` relay would miss the pipeline's own data commits).
- One refresh pipeline (scan → apply) runs at a time, so overlapping refresh / force-update runs
can't undo each other.
- Cancelling a refresh / force-update or a desktop release run now really stops it (`!cancelled()`
instead of `always()` on the push / build jobs).
### Changed
- The old GitHub Pages address serves a redirect stub that forwards to freeitchgames.win
(keeping `#/` routes) and deletes the old app's token and key storage on that origin.
- Security headers in [`webapp/public/_headers`](../../webapp/public/_headers) (CSP, Referrer-Policy,
frame denial, Permissions-Policy, COOP) and immutable caching for hashed `/assets/*`.
- Pipeline logs are unbuffered UTF-8.
+52
View File
@@ -0,0 +1,52 @@
# Changelog — 4.1.x
Release notes for 4.1.0, newest first. Every version: [CHANGELOG.md](../../CHANGELOG.md).
## [4.1.0] - 2026-09-24 (Verification check, readable charts, changelog folder)
Version 4.1 puts a quick Cloudflare Turnstile check in front of the website, makes the charts'
hover tooltips readable again, and moves this changelog into one file per version.
### Upgrade notes
- **Updated Privacy Policy, Terms of Use and EULA** (the new verification cookie; `.rpm` listed):
the site and the apps ask you to accept them again once.
- **Website**: the first visit, then about once every 48 hours, shows a short "Quick check" page run
by Cloudflare Turnstile. It usually passes by itself, and the page you opened loads right after.
- **Desktop and Android apps** have no check. Install 4.1.0 over 4.0.0 as usual.
### Added
- **Verification gate** (web only). Until a browser passes a Turnstile check, the Worker answers app
pages with a self-contained verification page ([`webapp/worker/gate-page.ts`](../../webapp/worker/gate-page.ts))
and `/img` covers with 403, so nothing of the site loads before the check. Passing sets
`__Host-fig_gate` (HttpOnly, host-only, an HMAC-signed issue time) for `BOT_GATE_TTL_HOURS` (48),
and the page reloads into the link that was asked for. `/data`, `/assets`, robots, sitemap, the
social image, `/api/*` and `/admin*` stay open. Verified search and link-preview bots pass with the
token a Cloudflare Transform Rule adds; clients that only claim to be a crawler get a 503. The gate
stays off until it is configured, and deleting `GATE_SECRET` switches it off at once
([`webapp/worker/gate.ts`](../../webapp/worker/gate.ts), [`docs/operations.md`](../../docs/operations.md)).
- `GET /api/verify` reports the pass. A tab whose pass ran out checks again when it is shown (or when a
cover fails) and reloads into the verification page.
### Fixed
- **Chart hover was hard to read**: the band behind the hovered bar was black and tooltips had no
background, because the chart colours wrapped the hex design tokens in `hsl()`. Tooltips now use the
popover colours, translated series names ("Games" instead of `count`), locale-formatted numbers,
each slice's share on the pies that cover the whole, and formatted dates on the game-count chart.
Clicking a chart no longer draws a black focus ring or pins the tooltip on the first item; keyboard
focus keeps the purple ring. Pie seams and treemap cells follow the theme.
- **Suggest form**: the Turnstile check now also requires this site's hostname and the `suggest`
action (a token from one page can't be spent on another), and answers 503 instead of "failed" when
Turnstile is unreachable.
- **Admin approvals** (live since 2026-09-20): the Worker accepts the GitHub App private key as GitHub
downloads it (PKCS#1), not only PKCS#8.
### Changed
- The changelog is split per version under [`changelog/`](../); [`CHANGELOG.md`](../../CHANGELOG.md)
is now the index, and old links to its entries still land on the right row.
- Docs brought up to date: the operations runbook (verification gate setup, Web Analytics injected by
the zone, a release checklist), the development setup, the READMEs, `CLAUDE.md` and the Tauri notes.
- [`webapp/public/_headers`](../../webapp/public/_headers): caching for the favicon and the web manifest.
+3 -3
View File
@@ -1,10 +1,10 @@
# End-User License Agreement (EULA)
Last updated: 2026-09-18
Last updated: 2026-09-24
Applies from: the release of version 4.0.0.
Applies from: the release of version 4.1.0.
This EULA applies **only to the desktop and Android apps** of Itch.io Free Games DB: the installers (`.msi`, `.exe`, `.dmg`, `.pkg`, `.app.tar.gz`, `.deb`, `.AppImage`) and the Android `.apk` published on GitHub Releases. It does **not** cover:
This EULA applies **only to the desktop and Android apps** of Itch.io Free Games DB: the installers (`.msi`, `.exe`, `.dmg`, `.pkg`, `.app.tar.gz`, `.deb`, `.rpm`, `.AppImage`) and the Android `.apk` published on GitHub Releases. It does **not** cover:
- the website <https://freeitchgames.win>, which is covered by the [Terms of Use](ToS.md);
- the source code, which is under the [MIT License](../LICENSE);
+12 -7
View File
@@ -1,8 +1,8 @@
# Privacy Policy
Last updated: 2026-09-18
Last updated: 2026-09-24
Applies from: the release of version 4.0.0.
Applies from: the release of version 4.1.0.
This Privacy Policy explains what personal data the `free-games-itchio-list` project processes, why, who helps process it, how long it is kept, and what rights you have. It covers the website **https://freeitchgames.win**, the desktop and Android apps, the public catalog data and the repository. The short version: there are no accounts, no ads and no tracking cookies. The Project keeps as little as it can, and most of what exists stays in your own browser.
@@ -12,6 +12,7 @@ A Vietnamese translation is available at [`docs/i18n/vi/PrivacyPolicy.md`](i18n/
>
> - No accounts, no sign-in, no ads, no selling of data, no profiling. The Apps have no telemetry.
> - The Website runs on Cloudflare, which processes standard request data (IP address, browser, URL, time) to deliver and protect the site and to count visits in aggregate, without cookies. The Project's own code never saves your IP address.
> - To keep bots out, your browser passes a quick Cloudflare Turnstile check before the Website loads, about once every 48 hours; one strictly necessary cookie remembers that you passed.
> - Your settings (theme, language, 18+ choice, accepted terms) and a cache of the public catalog stay in your browser and are never sent to the Project.
> - If you use the Suggest page, the Maintainer receives the game link, your optional note (deleted after 180 days) and the time. Please don't put personal data in the note.
> - Questions or requests: **privacy@freeitchgames.win**.
@@ -42,6 +43,7 @@ This Policy does not cover services that handle data on their own account: itch.
### 2.1 Visiting the Website
- **Request data.** The Website is hosted on Cloudflare. When your browser loads a page, a file or an image, Cloudflare processes standard request data: your IP address, user agent (browser and device type), the requested URL, the referrer and the time. This is needed to deliver the site, to protect it (TLS, firewall, bot and denial-of-service protection) and to limit abuse.
- **Verification check.** Before the Website's pages and cover images load, your browser passes a Cloudflare Turnstile check, which processes signals about your device and browser to tell people from bots; it usually completes without any action from you. To check the result, the Website sends the Turnstile token and your IP address to Cloudflare's verification service, then sets the `__Host-fig_gate` cookie (section 3.2) so that the check is not repeated for 48 hours. Search-engine and link-preview bots that Cloudflare has verified skip the check. The catalog data under `/data` stays available without it.
- **Aggregate statistics.** The Website uses Cloudflare Web Analytics, which loads a small script from Cloudflare and counts visits in aggregate, without cookies and, according to Cloudflare, without fingerprinting. The Maintainer sees only totals (such as page views), not individual visitors. The Project runs no other analytics.
- **Server logs.** Requests handled by the Website's server code (Cloudflare Workers) are recorded by Cloudflare Workers Logs on a 10% sample and kept for about 7 days, to find bugs and investigate abuse.
- **Network error reports.** Cloudflare may add Network Error Logging (NEL) headers, which ask your browser to report connection errors to Cloudflare.
@@ -91,7 +93,7 @@ Issues, pull requests, discussions and comments are public on GitHub under your
### 2.8 What the Project does not do
- No accounts or sign-in for the public, no comments, no ads and no payments.
- No cookies set by the Project's own code on the public Website.
- No cookies set by the Project's own code on the public Website, except the verification cookie, which identifies no one (section 3.2).
- No selling or sharing of personal data, for advertising or any other purpose.
- No profiling and no automated decisions with legal or similarly significant effects on you.
- No telemetry in the Apps, and no analytics other than Cloudflare Web Analytics on the Website.
@@ -106,25 +108,26 @@ The Website and the Apps keep the following items on your device only. None of t
|---|---|---|---|
| `localStorage` | `webapp.prefs` | Interface preferences such as language and layout density, your 18+ (NSFW) content choice, and the version of the legal documents you accepted | You clear it |
| `localStorage` | `webapp.theme` | Theme: `light`, `dark` or `system` | You clear it |
| `localStorage` | `webapp.gate` | When your current verification pass (section 3.2) runs out, so an open tab can check again in time | Replaced by the next check; you can clear it |
| IndexedDB (via `idb-keyval`) | `webapp.query-cache` | A cache of the public Catalog JSON, for fast loading and limited offline use | At most 7 days, then refreshed or discarded |
| `sessionStorage` | `reloaded-after-deploy` | A timestamp, so the page reloads at most once after a site update | The tab is closed |
On first load, the Website and the Apps also delete the entries that the old v3 app left in browser storage (an encrypted GitHub access token and commit-signing key data). v4 does not use them.
These items are strictly necessary for features you use (keeping your settings, loading the site quickly, recovering after an update), so they don't need consent under the EU ePrivacy rules or the UK PECR. You can delete them at any time with your browser's "Clear site data" option for `freeitchgames.win`, or inspect them in your browser's developer tools. In the Apps, uninstalling removes them; if a desktop uninstaller leaves the App's data folder (`com.poli0981.freegamesitchio`) behind, you can delete that folder yourself. On Android you can also clear the app's storage in the system settings.
These items are strictly necessary for features you use (keeping your settings, loading the site quickly, recovering after an update, not repeating the verification check), so they don't need consent under the EU ePrivacy rules or the UK PECR. You can delete them at any time with your browser's "Clear site data" option for `freeitchgames.win`, or inspect them in your browser's developer tools. In the Apps, uninstalling removes them; if a desktop uninstaller leaves the App's data folder (`com.poli0981.freegamesitchio`) behind, you can delete that folder yourself. On Android you can also clear the app's storage in the system settings.
### 3.2 Cookies
- The Project's own code sets **no cookies** on the public Website.
- The Project's own code sets **one cookie** on the public Website: `__Host-fig_gate`, after you pass the verification check (section 2.1). It holds only the time it was issued and a signature, identifies no one, lasts **48 hours**, and is sent only to freeitchgames.win (`HttpOnly`, `Secure`, `SameSite=Lax`). It is strictly necessary to keep automated traffic out, so it needs no consent under the EU ePrivacy rules or the UK PECR. If you block it, the check runs again on every visit.
- Cloudflare may set strictly necessary security cookies, such as `__cf_bm` or `cf_clearance`, when its bot or challenge protections run. They serve security only.
- The Suggest page uses Cloudflare Turnstile (section 2.3); see Cloudflare's Turnstile privacy addendum (section 4).
- The verification check and the Suggest page use Cloudflare Turnstile (sections 2.1 and 2.3); see Cloudflare's Turnstile privacy addendum (section 4).
- The admin area uses the Cloudflare Access session cookie `CF_Authorization`, which exists only in the Maintainer's browser.
## 4. Service providers and other parties
| Party | Role and what it does | Data involved | Privacy policy |
|---|---|---|---|
| **Cloudflare** | Processor for the Website: DNS, CDN, firewall and TLS; Workers (the site's server code) and static assets; R2 (resized cover images); D1 (the review queue); Images (resizing); Turnstile (Suggest page only); Web Analytics; Workers Logs; Access (admin login only); Rate Limiting; Email Routing (forwards the Project's contact addresses) | Request data, Suggest submissions, the review queue, forwarded emails | <https://www.cloudflare.com/privacypolicy/> · Turnstile: <https://www.cloudflare.com/turnstile-privacy-policy/> |
| **Cloudflare** | Processor for the Website: DNS, CDN, firewall and TLS; Workers (the site's server code) and static assets; R2 (resized cover images); D1 (the review queue); Images (resizing); Turnstile (the verification check and the Suggest page); Web Analytics; Workers Logs; Access (admin login only); Rate Limiting; Email Routing (forwards the Project's contact addresses) | Request data, Suggest submissions, the review queue, forwarded emails | <https://www.cloudflare.com/privacypolicy/> · Turnstile: <https://www.cloudflare.com/turnstile-privacy-policy/> |
| **GitHub** | Hosts the code, the Catalog data, issues and discussions, the data pipeline (GitHub Actions) and the release downloads. Independent controller for your GitHub account and activity | Your public contributions; request data when you visit GitHub or download a release | <https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement> |
| **itch.io** | Independent platform, not affiliated with the Project. Source of the game data; every game link and download goes there; the Apps load covers from img.itch.zone | What your browser or the Apps send when you visit itch.io or load covers from it. The pipeline sends nothing about you | <https://itch.io/docs/legal/privacy-policy> |
| **Discord** | Receives automated build and release notifications from GitHub Actions | No visitor data | — |
@@ -147,6 +150,7 @@ Cloudflare may process data anywhere on its global network (see section 9). The
| Emails, including removal and copyright requests | As long as needed to handle the request |
| GitHub contributions | On GitHub, until you or GitHub remove them |
| Browser storage | See section 3.1 |
| `__Host-fig_gate` verification cookie | **48 hours** (section 3.2) |
| `CF_Authorization` cookie (Maintainer only) | For the duration of the Cloudflare Access session |
## 6. Legal bases
@@ -213,6 +217,7 @@ Under the GDPR and the UK GDPR, you can also ask for processing to be restricted
## 10. Security
- The Website is served only over HTTPS.
- Automated traffic has to pass a Cloudflare Turnstile check before the Website's pages and cover images load (section 2.1).
- Data minimization: no accounts, no IP addresses stored by the Project's code, Suggest notes deleted after 180 days, duplicate-submission records after 7 days.
- The admin area and the ingest API are protected by Cloudflare Access, and the Website's server code verifies the Access token itself on every protected request.
- Secrets (such as the GitHub App's private key) are kept in Cloudflare's secret storage, never in the Repository. The admin area writes to the Repository as a GitHub App, with verified commits.
+6 -5
View File
@@ -13,8 +13,9 @@ change them.
[`webapp/src-tauri/Cargo.toml`](../webapp/src-tauri/Cargo.toml),
[`requirements.txt`](../requirements.txt) and [`requirements-dev.txt`](../requirements-dev.txt).
Exact versions, including dependencies of dependencies, are pinned in
[`webapp/package-lock.json`](../webapp/package-lock.json) (npm) and resolved at build time for Rust and
Python (`npm ls`, `cargo tree` and `pip list` show the full trees).
[`webapp/package-lock.json`](../webapp/package-lock.json) (npm) and
[`webapp/src-tauri/Cargo.lock`](../webapp/src-tauri/Cargo.lock) (Rust); Python dependencies are
resolved at install time (`npm ls`, `cargo tree` and `pip list` show the full trees).
- The runtime libraries are also listed on the [About page](https://freeitchgames.win/about), which reads
the `THIRD_PARTY` array in [`webapp/src/lib/about.ts`](../webapp/src/lib/about.ts).
@@ -56,8 +57,8 @@ requests to third-party font services. The fonts are licensed under the SIL Open
The Worker runs on Cloudflare's Workers runtime and uses Cloudflare services (R2, D1, Images, Rate
Limiting, Access). Two scripts come from Cloudflare instead of the site's own bundle: the Web Analytics
beacon (`static.cloudflareinsights.com`) and, on the Suggest page only, the Turnstile widget
(`challenges.cloudflare.com`). These are Cloudflare services under Cloudflare's own terms, not open-source
beacon (`static.cloudflareinsights.com`) and, on the verification page and the Suggest page, the
Turnstile widget (`challenges.cloudflare.com`). These are Cloudflare services under Cloudflare's own terms, not open-source
components. Section 7 lists every service the project uses.
## 3. Desktop and Android apps (Rust crates)
@@ -130,7 +131,7 @@ distributed with the project; each one is under the license in its own repositor
| Service | What it does for the project |
|---|---|
| **Cloudflare** | DNS, CDN, WAF, TLS; Workers and static assets (the website); R2 (resized cover images); D1 (the review queue); Images (resizing); Turnstile (Suggest page); Web Analytics (cookieless, aggregate); Workers Logs; Access (admin login); Rate Limiting; Email Routing (the project's contact addresses) |
| **Cloudflare** | DNS, CDN, WAF, TLS; Workers and static assets (the website); R2 (resized cover images); D1 (the review queue); Images (resizing); Turnstile (the verification page and the Suggest page); Web Analytics (cookieless, aggregate); Workers Logs; Access (admin login); Rate Limiting; Email Routing (the project's contact addresses) |
| **GitHub** | Code, catalog data, issues and discussions, Actions (the pipeline), release downloads |
| **itch.io** | Where the games live; the pipeline and RSS discovery read public itch.io pages and feeds |
| **Discord** | Receives automated CI and release notifications only |
+3 -3
View File
@@ -1,8 +1,8 @@
# Terms of Use
Last updated: 2026-09-18
Last updated: 2026-09-24
Applies from: the release of version 4.0.0.
Applies from: the release of version 4.1.0.
These Terms of Use ("Terms") govern your use of the website **https://freeitchgames.win**, the desktop and Android apps, and the public catalog data of `free-games-itchio-list`. They are written in plain language, but they are a real agreement. They replace the older Terms and also cover what the old web-app "EULA" used to say; the [EULA](EULA.md) now covers only the app installers and the Android APK.
@@ -63,7 +63,7 @@ You agree **not** to:
1. **Bulk-scrape** the Website or its API beyond the published `/data` files. Use the `/data` JSON files or the Repository instead; it is cheaper for everyone.
2. **Abuse the image proxy** (`/img`): it exists only to show cover images on the Website. Don't hotlink `/img` URLs from other sites or apps, and don't use it to fetch images in bulk.
3. **Access restricted areas without authorization**: `/admin`, the admin API (`/api/admin/…`) and the ingest API (`/api/ingest`) are for the Maintainer only. Good-faith security research is welcome under the rules of the [Security Policy](../SECURITY.md).
4. **Spam the Suggest form**, or circumvent Turnstile or the rate limits (for example with scripts or rotating IP addresses).
4. **Spam the Suggest form**, or circumvent the Website's verification check, Turnstile or the rate limits (for example with scripts, shared verification cookies or rotating IP addresses).
5. **Submit links to malware**, scams, phishing, or illegal content, anywhere in the Project.
6. **Misrepresent affiliation**: don't claim to be the Maintainer or the Project, don't present a fork or copy as the official Project, don't claim that the Project is run or endorsed by itch.io, and don't use the names "poli0981" or "SkullMute" to endorse your own work without prior written permission.
7. **Disrupt the Project**: don't attempt to overload, break or impair the Website (for example by denial-of-service), and don't use the Project to put unreasonable load on itch.io. If you run the pipeline code yourself, you are responsible for complying with itch.io's terms and for keeping its request pacing.
+7 -3
View File
@@ -112,15 +112,19 @@ DEV_ADMIN_EMAIL=you@example.com
SITE_ORIGIN=http://localhost:5173
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA
# Only to try the verification gate under `npx wrangler dev` (http://localhost:8787):
# GATE_SECRET=<32+ random characters, e.g. `openssl rand -hex 32`>
```
| Key | Kind | What it does |
|---|---|---|
| `DEV_ADMIN_EMAIL` | local only, optional | Lets you into the admin without Cloudflare Access. Honoured only when the host is `localhost`, `127.0.0.1` or `[::1]`; ignored everywhere else |
| `ADMIN_EMAILS` | secret | Comma-separated admin allow-list, checked behind Access. Not needed locally with `DEV_ADMIN_EMAIL` |
| `TURNSTILE_SECRET` | secret | Suggest form, together with the `TURNSTILE_SITEKEY` var |
| `GH_APP_PRIVATE_KEY` | secret | GitHub App private key (PKCS#8 PEM) for admin writes, together with the `GH_APP_ID` and `GH_APP_INSTALLATION_ID` vars |
| `SITE_ORIGIN` | var override | The Suggest form only accepts POSTs whose `Origin` equals it |
| `TURNSTILE_SECRET` | secret | Suggest form and verification gate, together with the `TURNSTILE_SITEKEY` var |
| `GATE_SECRET` | secret | Signs the verification-gate cookie (32+ characters). Without it the gate stays off. Locally, set `SITE_ORIGIN=http://localhost:8787` and open the site through `wrangler dev`; the cookie is `fig_gate` there (no `Secure`) |
| `GATE_BOT_TOKEN` | secret | The value the zone's Transform Rule sends for verified bots (32+ characters). Required in production, not on localhost |
| `GH_APP_PRIVATE_KEY` | secret | GitHub App private key for admin writes — the PEM as GitHub downloads it (PKCS#1) or PKCS#8, together with the `GH_APP_ID` and `GH_APP_INSTALLATION_ID` vars |
| `SITE_ORIGIN` | var override | The Suggest form and the verification gate only accept POSTs whose `Origin` equals it |
A feature whose settings are missing answers `503`; the public site needs none of them. The two
Turnstile values above are Cloudflare's always-pass test keys
+2 -2
View File
@@ -1,6 +1,6 @@
# Hướng dẫn đóng góp
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
>
> Bản tiếng Anh tại [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) là bản chính thức.
@@ -72,7 +72,7 @@ Chi tiết có trong [Điều khoản sử dụng](ToS.md) và [Tuyên bố mi
**Quy tắc PR** (phần không thương lượng):
- **CI phải pass.** Python CI (ruff check + format, vulture, pytest, `validate.py`) và Webapp CI (kiểm tra type sinh ra, lint, knip, test, build, `wrangler deploy --dry-run`) đều chạy trên PR. CI đỏ = không merge.
- **PR được squash-merge**: một PR thành một commit trên `main`, nên hãy đặt tiêu đề PR như một commit message tốt (repo dùng kiểu `type(scope): tóm tắt`, ví dụ `fix(web): …`).
- **PR được merge bằng squash** (một PR thành một commit trên `main`) **hoặc merge commit, không bao giờ fast-forward**, nên hãy đặt tiêu đề PR như một commit message tốt (repo dùng kiểu `type(scope): tóm tắt`, ví dụ `fix(web): …`).
- **Giấy phép theo nguyên tắc inbound = outbound.** Khi mở PR, bạn đồng ý rằng đóng góp của mình được cấp phép theo cùng giấy phép với phần mà nó thay đổi: **MIT** cho mã nguồn, **CC BY 4.0** cho dữ liệu danh mục và tài liệu (xem [README → Giấy phép](../../../README.vi.md#giấy-phép)). Chỉ gửi những gì bạn có quyền gửi.
- **Không bao giờ commit secret**: không token, API key, file `.dev.vars` / `.env`, private key (chẳng hạn khóa của GitHub App) hay keystore dùng để ký. Nếu lỡ push một cái, hãy báo riêng (security@freeitchgames.win) và thay mới (rotate) nó; chỉ xóa commit là không đủ.
- **Không sửa tay `data_game/`.** Thay đổi dữ liệu phải đi qua pipeline (một patch + `apply_patch.py`, có chạy `validate.py`), để các tiến trình ghi đồng thời không đè lên nhau.
+4 -4
View File
@@ -1,14 +1,14 @@
# Thỏa thuận cấp phép cho người dùng cuối (EULA)
Cập nhật lần cuối: 2026-09-18
Cập nhật lần cuối: 2026-09-24
Áp dụng từ: khi phát hành phiên bản 4.0.0.
Áp dụng từ: khi phát hành phiên bản 4.1.0.
Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
> Bản tiếng Anh: [`docs/EULA.md`](../../EULA.md).
EULA này **chỉ áp dụng cho ứng dụng desktop và ứng dụng Android** của Itch.io Free Games DB: các bộ cài (`.msi`, `.exe`, `.dmg`, `.pkg`, `.app.tar.gz`, `.deb`, `.AppImage`) và file `.apk` Android được phát hành trên GitHub Releases. EULA này **không** áp dụng cho:
EULA này **chỉ áp dụng cho ứng dụng desktop và ứng dụng Android** của Itch.io Free Games DB: các bộ cài (`.msi`, `.exe`, `.dmg`, `.pkg`, `.app.tar.gz`, `.deb`, `.rpm`, `.AppImage`) và file `.apk` Android được phát hành trên GitHub Releases. EULA này **không** áp dụng cho:
- website <https://freeitchgames.win>, được điều chỉnh bởi [Điều khoản sử dụng](ToS.md);
- mã nguồn, theo [Giấy phép MIT](../../../LICENSE);
+13 -8
View File
@@ -1,10 +1,10 @@
# Chính sách quyền riêng tư (Privacy Policy)
Cập nhật lần cuối: 2026-09-18
Cập nhật lần cuối: 2026-09-24
Áp dụng từ: khi phát hành phiên bản 4.0.0.
Áp dụng từ: khi phát hành phiên bản 4.1.0.
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên. Bản gốc: [`docs/PrivacyPolicy.md`](../../PrivacyPolicy.md).
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên. Bản gốc: [`docs/PrivacyPolicy.md`](../../PrivacyPolicy.md).
Chính sách quyền riêng tư này giải thích dự án `free-games-itchio-list` xử lý những dữ liệu cá nhân nào, vì sao, ai hỗ trợ xử lý, dữ liệu được lưu trong bao lâu và bạn có những quyền gì. Chính sách áp dụng cho website **https://freeitchgames.win**, các ứng dụng desktop và Android, dữ liệu danh mục công khai và repository. Nói ngắn gọn: không có tài khoản, không quảng cáo, không cookie theo dõi. Dự án giữ ít dữ liệu nhất có thể, và phần lớn những gì tồn tại chỉ nằm trong trình duyệt của chính bạn.
@@ -12,6 +12,7 @@ Chính sách quyền riêng tư này giải thích dự án `free-games-itchio-l
>
> - Không tài khoản, không đăng nhập, không quảng cáo, không bán dữ liệu, không lập hồ sơ (profiling). Các Ứng dụng không có telemetry.
> - Website chạy trên Cloudflare. Cloudflare xử lý dữ liệu request tiêu chuẩn (địa chỉ IP, trình duyệt, URL, thời gian) để phân phối và bảo vệ trang, và để đếm lượt truy cập ở dạng tổng hợp, không dùng cookie. Mã nguồn của chính Dự án không bao giờ lưu địa chỉ IP của bạn.
> - Để chặn bot, trình duyệt của bạn qua một bước kiểm tra nhanh của Cloudflare Turnstile trước khi Website tải, khoảng 48 giờ một lần; một cookie thật sự cần thiết ghi nhớ rằng bạn đã qua.
> - Cài đặt của bạn (giao diện sáng/tối, ngôn ngữ, lựa chọn 18+, phiên bản điều khoản đã chấp nhận) và bản cache của danh mục công khai nằm trong trình duyệt của bạn và không bao giờ được gửi về Dự án.
> - Nếu bạn dùng trang Suggest, Người duy trì nhận được link game, ghi chú tùy chọn của bạn (bị xóa sau 180 ngày) và thời điểm gửi. Vui lòng không đưa dữ liệu cá nhân vào ghi chú.
> - Câu hỏi hoặc yêu cầu: **privacy@freeitchgames.win**.
@@ -42,6 +43,7 @@ Chính sách này không áp dụng cho các dịch vụ tự xử lý dữ li
### 2.1 Khi truy cập Website
- **Dữ liệu request.** Website được host trên Cloudflare. Khi trình duyệt của bạn tải một trang, một file hay một hình ảnh, Cloudflare xử lý dữ liệu request tiêu chuẩn: địa chỉ IP, user agent (loại trình duyệt và thiết bị), URL được yêu cầu, referrer và thời gian. Việc này cần thiết để phân phối trang, bảo vệ trang (TLS, tường lửa, chống bot và chống tấn công từ chối dịch vụ) và hạn chế lạm dụng.
- **Bước xác minh.** Trước khi các trang và ảnh bìa của Website được tải, trình duyệt của bạn qua một bước kiểm tra của Cloudflare Turnstile. Turnstile xử lý các tín hiệu về thiết bị và trình duyệt để phân biệt người thật với bot; thường bước này tự hoàn tất mà bạn không phải làm gì. Để kiểm tra kết quả, Website gửi token Turnstile và địa chỉ IP của bạn tới dịch vụ xác minh của Cloudflare, rồi đặt cookie `__Host-fig_gate` (mục 3.2) để không phải kiểm tra lại trong 48 giờ. Bot của công cụ tìm kiếm và bot tạo bản xem trước link đã được Cloudflare xác minh thì bỏ qua bước này. Dữ liệu danh mục trong `/data` vẫn truy cập được mà không cần bước này.
- **Thống kê tổng hợp.** Website dùng Cloudflare Web Analytics: một script nhỏ được tải từ Cloudflare để đếm lượt truy cập ở dạng tổng hợp, không dùng cookie và, theo Cloudflare, không dùng fingerprinting. Người duy trì chỉ thấy số liệu tổng (như số lượt xem trang), không thấy từng người truy cập. Dự án không chạy công cụ analytics nào khác.
- **Log máy chủ.** Các request do mã máy chủ của Website (Cloudflare Workers) xử lý được Cloudflare Workers Logs ghi lại theo mẫu 10% và lưu khoảng 7 ngày, để tìm lỗi và điều tra hành vi lạm dụng.
- **Báo cáo lỗi mạng.** Cloudflare có thể thêm header Network Error Logging (NEL), yêu cầu trình duyệt của bạn báo các lỗi kết nối về Cloudflare.
@@ -91,7 +93,7 @@ Issue, pull request, discussion và bình luận đều công khai trên GitHub
### 2.8 Những điều Dự án không làm
- Không có tài khoản hay đăng nhập cho công chúng, không bình luận, không quảng cáo và không thanh toán.
- Mã nguồn của chính Dự án không đặt cookie nào trên Website công khai.
- Mã nguồn của chính Dự án không đặt cookie nào trên Website công khai, ngoại trừ cookie xác minh, vốn không nhận diện bất kỳ ai (mục 3.2).
- Không bán hay chia sẻ dữ liệu cá nhân, dù cho quảng cáo hay bất kỳ mục đích nào khác.
- Không lập hồ sơ (profiling) và không ra quyết định tự động gây hệ quả pháp lý hoặc ảnh hưởng đáng kể tương tự đối với bạn.
- Không có telemetry trong các Ứng dụng, và không có analytics nào ngoài Cloudflare Web Analytics trên Website.
@@ -106,25 +108,26 @@ Website và các Ứng dụng chỉ lưu các mục sau trên thiết bị của
|---|---|---|---|
| `localStorage` | `webapp.prefs` | Tùy chọn giao diện như ngôn ngữ và mật độ hiển thị, lựa chọn nội dung 18+ (NSFW) của bạn, và phiên bản các văn bản pháp lý bạn đã chấp nhận | Bạn xóa nó |
| `localStorage` | `webapp.theme` | Giao diện: `light`, `dark` hoặc `system` | Bạn xóa nó |
| `localStorage` | `webapp.gate` | Thời điểm lượt xác minh hiện tại (mục 3.2) hết hạn, để tab đang mở kịp kiểm tra lại | Bị thay bởi lần kiểm tra sau; bạn có thể xóa nó |
| IndexedDB (qua `idb-keyval`) | `webapp.query-cache` | Bản cache của JSON Danh mục công khai, để tải nhanh và dùng offline ở mức hạn chế | Tối đa 7 ngày, sau đó được làm mới hoặc bị bỏ đi |
| `sessionStorage` | `reloaded-after-deploy` | Một mốc thời gian, để trang chỉ tự tải lại tối đa một lần sau khi site được cập nhật | Tab được đóng |
Ở lần tải đầu tiên, Website và các Ứng dụng cũng xóa các mục mà ứng dụng v3 cũ để lại trong bộ nhớ trình duyệt (một GitHub access token đã mã hóa và dữ liệu khóa ký commit). v4 không dùng tới các mục này.
Các mục trên là thật sự cần thiết cho những tính năng bạn dùng (giữ cài đặt, tải trang nhanh, phục hồi sau khi site cập nhật), nên không cần sự đồng ý theo các quy định ePrivacy của EU hay PECR của Vương quốc Anh. Bạn có thể xóa chúng bất kỳ lúc nào bằng tùy chọn "Clear site data" (xóa dữ liệu trang web) của trình duyệt cho `freeitchgames.win`, hoặc xem chúng trong công cụ dành cho nhà phát triển (developer tools) của trình duyệt. Với các Ứng dụng, gỡ cài đặt sẽ xóa chúng; nếu trình gỡ cài đặt trên desktop để sót lại thư mục dữ liệu của Ứng dụng (`com.poli0981.freegamesitchio`), bạn có thể tự xóa thư mục đó. Trên Android, bạn cũng có thể xóa bộ nhớ của ứng dụng trong phần cài đặt hệ thống.
Các mục trên là thật sự cần thiết cho những tính năng bạn dùng (giữ cài đặt, tải trang nhanh, phục hồi sau khi site cập nhật, không phải xác minh lặp lại), nên không cần sự đồng ý theo các quy định ePrivacy của EU hay PECR của Vương quốc Anh. Bạn có thể xóa chúng bất kỳ lúc nào bằng tùy chọn "Clear site data" (xóa dữ liệu trang web) của trình duyệt cho `freeitchgames.win`, hoặc xem chúng trong công cụ dành cho nhà phát triển (developer tools) của trình duyệt. Với các Ứng dụng, gỡ cài đặt sẽ xóa chúng; nếu trình gỡ cài đặt trên desktop để sót lại thư mục dữ liệu của Ứng dụng (`com.poli0981.freegamesitchio`), bạn có thể tự xóa thư mục đó. Trên Android, bạn cũng có thể xóa bộ nhớ của ứng dụng trong phần cài đặt hệ thống.
### 3.2 Cookie
- Mã nguồn của chính Dự án **không đặt cookie nào** trên Website công khai.
- Mã nguồn của chính Dự án đặt **một cookie** trên Website công khai: `__Host-fig_gate`, sau khi bạn qua bước xác minh (mục 2.1). Cookie này chỉ chứa thời điểm cấp và một chữ ký, không nhận diện ai, tồn tại **48 giờ** và chỉ được gửi tới freeitchgames.win (`HttpOnly`, `Secure`, `SameSite=Lax`). Cookie này thật sự cần thiết để chặn truy cập tự động, nên không cần sự đồng ý theo các quy định ePrivacy của EU hay PECR của Vương quốc Anh. Nếu bạn chặn nó, bước kiểm tra sẽ chạy lại ở mỗi lần truy cập.
- Cloudflare có thể đặt các cookie bảo mật thật sự cần thiết, như `__cf_bm` hoặc `cf_clearance`, khi cơ chế chống bot hoặc thử thách (challenge) của họ hoạt động. Các cookie này chỉ phục vụ mục đích bảo mật.
- Trang Suggest dùng Cloudflare Turnstile (mục 2.3); xem phụ lục quyền riêng tư Turnstile của Cloudflare (mục 4).
- Bước xác minh và trang Suggest dùng Cloudflare Turnstile (mục 2.1 và 2.3); xem phụ lục quyền riêng tư Turnstile của Cloudflare (mục 4).
- Khu vực quản trị dùng cookie phiên `CF_Authorization` của Cloudflare Access, cookie này chỉ tồn tại trong trình duyệt của Người duy trì.
## 4. Nhà cung cấp dịch vụ và các bên khác
| Bên | Vai trò và công việc | Dữ liệu liên quan | Chính sách quyền riêng tư |
|---|---|---|---|
| **Cloudflare** | Bên xử lý dữ liệu cho Website: DNS, CDN, tường lửa và TLS; Workers (mã máy chủ của site) và static assets; R2 (ảnh bìa đã thu nhỏ); D1 (hàng chờ duyệt); Images (thu nhỏ ảnh); Turnstile (chỉ trang Suggest); Web Analytics; Workers Logs; Access (chỉ cho đăng nhập quản trị); Rate Limiting; Email Routing (chuyển tiếp các địa chỉ liên hệ của Dự án) | Dữ liệu request, đề xuất từ trang Suggest, hàng chờ duyệt, email được chuyển tiếp | <https://www.cloudflare.com/privacypolicy/> · Turnstile: <https://www.cloudflare.com/turnstile-privacy-policy/> |
| **Cloudflare** | Bên xử lý dữ liệu cho Website: DNS, CDN, tường lửa và TLS; Workers (mã máy chủ của site) và static assets; R2 (ảnh bìa đã thu nhỏ); D1 (hàng chờ duyệt); Images (thu nhỏ ảnh); Turnstile (bước xác minh và trang Suggest); Web Analytics; Workers Logs; Access (chỉ cho đăng nhập quản trị); Rate Limiting; Email Routing (chuyển tiếp các địa chỉ liên hệ của Dự án) | Dữ liệu request, đề xuất từ trang Suggest, hàng chờ duyệt, email được chuyển tiếp | <https://www.cloudflare.com/privacypolicy/> · Turnstile: <https://www.cloudflare.com/turnstile-privacy-policy/> |
| **GitHub** | Host mã nguồn, dữ liệu Danh mục, issue và discussion, pipeline dữ liệu (GitHub Actions) và các bản phát hành để tải về. Là bên kiểm soát độc lập đối với tài khoản và hoạt động GitHub của bạn | Các đóng góp công khai của bạn; dữ liệu request khi bạn truy cập GitHub hoặc tải bản phát hành | <https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement> |
| **itch.io** | Nền tảng độc lập, không liên kết với Dự án. Là nguồn dữ liệu game; mọi link game và lượt tải đều dẫn tới đó; các Ứng dụng tải ảnh bìa từ img.itch.zone | Những gì trình duyệt của bạn hoặc các Ứng dụng gửi đi khi bạn truy cập itch.io hoặc tải ảnh bìa từ đó. Pipeline không gửi thông tin nào về bạn | <https://itch.io/docs/legal/privacy-policy> |
| **Discord** | Nhận thông báo build và phát hành tự động từ GitHub Actions | Không có dữ liệu người truy cập | — |
@@ -147,6 +150,7 @@ Cloudflare có thể xử lý dữ liệu ở bất kỳ đâu trên mạng lư
| Email, bao gồm yêu cầu gỡ game và yêu cầu liên quan đến bản quyền | Trong thời gian cần thiết để xử lý yêu cầu |
| Đóng góp trên GitHub | Trên GitHub, cho tới khi bạn hoặc GitHub xóa |
| Lưu trữ trên trình duyệt | Xem mục 3.1 |
| Cookie xác minh `__Host-fig_gate` | **48 giờ** (mục 3.2) |
| Cookie `CF_Authorization` (chỉ Người duy trì) | Trong thời gian của phiên Cloudflare Access |
## 6. Cơ sở pháp lý
@@ -213,6 +217,7 @@ Theo GDPR và UK GDPR, bạn cũng có thể yêu cầu hạn chế việc xử
## 10. Bảo mật
- Website chỉ được phục vụ qua HTTPS.
- Truy cập tự động phải qua bước kiểm tra Cloudflare Turnstile trước khi các trang và ảnh bìa của Website được tải (mục 2.1).
- Tối thiểu hóa dữ liệu: không tài khoản, mã nguồn của Dự án không lưu địa chỉ IP, ghi chú Suggest bị xóa sau 180 ngày, bản ghi chống gửi trùng bị xóa sau 7 ngày.
- Khu vực quản trị và API ingest được bảo vệ bằng Cloudflare Access, và mã máy chủ của Website tự xác minh token Access ở mọi request được bảo vệ.
- Các thông tin bí mật (như private key của GitHub App) được giữ trong kho lưu trữ bí mật của Cloudflare, không bao giờ nằm trong Repository. Khu vực quản trị ghi vào Repository dưới danh nghĩa một GitHub App, với các commit đã được xác minh (verified).
+4 -4
View File
@@ -1,10 +1,10 @@
# Điều khoản sử dụng (Terms of Use)
Cập nhật lần cuối: 2026-09-18
Cập nhật lần cuối: 2026-09-24
Áp dụng từ: khi phát hành phiên bản 4.0.0.
Áp dụng từ: khi phát hành phiên bản 4.1.0.
Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
Bản tiếng Anh: [`docs/ToS.md`](../../ToS.md).
@@ -67,7 +67,7 @@ Bạn đồng ý **không**:
1. **Scrape hàng loạt** Website hoặc API của nó, ngoài các file `/data` đã được công bố. Hãy dùng các file JSON trong `/data` hoặc Repository; cách đó tốn ít tài nguyên hơn cho tất cả mọi người.
2. **Lạm dụng image proxy** (`/img`): proxy này chỉ để hiển thị ảnh bìa trên Website. Đừng hotlink các URL `/img` từ website hay ứng dụng khác, và đừng dùng nó để tải ảnh hàng loạt.
3. **Truy cập trái phép các khu vực bị hạn chế**: `/admin`, API quản trị (`/api/admin/…`) và API ingest (`/api/ingest`) chỉ dành cho Người duy trì. Nghiên cứu bảo mật thiện chí luôn được hoan nghênh, theo các quy tắc trong [Security Policy](SECURITY.md).
4. **Spam form Suggest**, hoặc tìm cách vượt qua Turnstile hay giới hạn tần suất (ví dụ bằng script hoặc xoay vòng địa chỉ IP).
4. **Spam form Suggest**, hoặc tìm cách vượt qua bước xác minh của Website, Turnstile hay giới hạn tần suất (ví dụ bằng script, dùng chung cookie xác minh hoặc xoay vòng địa chỉ IP).
5. **Gửi liên kết tới malware**, lừa đảo, phishing hoặc nội dung bất hợp pháp, ở bất kỳ đâu trong Dự án.
6. **Mạo nhận liên kết**: đừng tự nhận là Người duy trì hay là Dự án, đừng giới thiệu một bản fork hay bản sao như thể đó là Dự án chính thức, đừng nói rằng Dự án do itch.io vận hành hoặc bảo trợ, và đừng dùng tên "poli0981" hay "SkullMute" để quảng bá sản phẩm của bạn khi chưa có sự cho phép trước bằng văn bản.
7. **Gây gián đoạn Dự án**: đừng tìm cách làm quá tải, phá hỏng hoặc làm suy giảm hoạt động của Website (ví dụ bằng tấn công từ chối dịch vụ), và đừng dùng Dự án để tạo tải bất hợp lý lên itch.io. Nếu bạn tự chạy code pipeline, bạn tự chịu trách nhiệm tuân thủ điều khoản của itch.io và giữ nguyên nhịp giãn cách request của nó.
+8 -4
View File
@@ -1,6 +1,6 @@
# Môi trường phát triển
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-18 (English source revision 2026-09-18). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
> Bản dịch từ bản tiếng Anh cập nhật ngày 2026-09-24 (English source revision 2026-09-24). Nếu có khác biệt, bản tiếng Anh được ưu tiên.
> Bản gốc: [`dev_env.md`](../../dev_env.md).
Bộ công cụ Maintainer dùng để viết và kiểm thử code trong repo này, và cách chạy từng phần trên máy.
@@ -115,15 +115,19 @@ DEV_ADMIN_EMAIL=you@example.com
SITE_ORIGIN=http://localhost:5173
TURNSTILE_SITEKEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA
# Chỉ khi muốn thử cổng xác minh qua `npx wrangler dev` (http://localhost:8787):
# GATE_SECRET=<32+ ký tự ngẫu nhiên, ví dụ `openssl rand -hex 32`>
```
| Key | Loại | Tác dụng |
|---|---|---|
| `DEV_ADMIN_EMAIL` | chỉ local, tùy chọn | Vào admin mà không cần Cloudflare Access. Chỉ có hiệu lực khi host là `localhost`, `127.0.0.1` hoặc `[::1]`; bị bỏ qua ở mọi nơi khác |
| `ADMIN_EMAILS` | secret | Danh sách email admin (phân cách bằng dấu phẩy), được kiểm tra sau Access. Không cần khi chạy local với `DEV_ADMIN_EMAIL` |
| `TURNSTILE_SECRET` | secret | Form Suggest, đi cùng var `TURNSTILE_SITEKEY` |
| `GH_APP_PRIVATE_KEY` | secret | Private key của GitHub App (PEM PKCS#8) cho các thao tác ghi của admin, đi cùng var `GH_APP_ID` và `GH_APP_INSTALLATION_ID` |
| `SITE_ORIGIN` | ghi đè var | Form Suggest chỉ nhận POST có `Origin` trùng với giá trị này |
| `TURNSTILE_SECRET` | secret | Form Suggest và cổng xác minh, đi cùng var `TURNSTILE_SITEKEY` |
| `GATE_SECRET` | secret | Ký cookie của cổng xác minh (32+ ký tự). Thiếu nó thì cổng tắt. Khi chạy local, đặt `SITE_ORIGIN=http://localhost:8787` và mở site qua `wrangler dev`; ở đó cookie tên `fig_gate` (không có `Secure`) |
| `GATE_BOT_TOKEN` | secret | Giá trị mà Transform Rule của zone gửi kèm cho bot đã xác minh (32+ ký tự). Bắt buộc trên production, không cần trên localhost |
| `GH_APP_PRIVATE_KEY` | secret | Private key của GitHub App cho các thao tác ghi của admin — file PEM đúng như GitHub tải về (PKCS#1) hoặc PKCS#8, đi cùng var `GH_APP_ID` và `GH_APP_INSTALLATION_ID` |
| `SITE_ORIGIN` | ghi đè var | Form Suggest và cổng xác minh chỉ nhận POST có `Origin` trùng với giá trị này |
Tính năng nào thiếu cấu hình sẽ trả về `503`; trang công khai không cần cấu hình nào trong số này.
Hai giá trị Turnstile ở trên là test key luôn-thành-công của Cloudflare
+75 -28
View File
@@ -8,25 +8,26 @@ secret: secrets are only ever typed into Cloudflare (`wrangler secret put`) or a
| Piece | Where | What it does |
|---|---|---|
| Worker `free-games-itchio-list` | Cloudflare Workers, custom domain `freeitchgames.win` | Serves the built app + `/data` (static assets), `/img` (resized covers), `/api/suggest`, `/api/ingest`, `/api/admin/*`, `/admin`, and runs the RSS cron. Config: [`webapp/wrangler.jsonc`](../webapp/wrangler.jsonc). |
| Worker `free-games-itchio-list` | Cloudflare Workers, custom domain `freeitchgames.win` | Serves the built app + `/data` (static assets), `/img` (resized covers), the verification gate (`/api/verify`), `/api/suggest`, `/api/ingest`, `/api/admin/*`, `/admin`, and runs the RSS cron. Config: [`webapp/wrangler.jsonc`](../webapp/wrangler.jsonc). |
| Workers Builds | Cloudflare dashboard → the Worker → Settings → Build | Builds and deploys `main` on every push (data commits included). |
| R2 `freeitchgames-thumbs` | Cloudflare R2 | Resized WebP covers (`w160/…`, `w640/…`). |
| D1 `freeitchgames` | Cloudflare D1 | Review queue, feed state, audit log, idempotency keys ([`webapp/worker/migrations/`](../webapp/worker/migrations)). |
| Access apps "Admin" / "Ingest" | Cloudflare Zero Trust | Login for `/admin` + `/api/admin/*`; service token for `/api/ingest` (browser extension). |
| Turnstile widget | Cloudflare Turnstile | Anti-spam on `/suggest`. |
| Turnstile widget | Cloudflare Turnstile | The verification gate in front of the web app (action `gate`) and anti-spam on `/suggest` (action `suggest`). |
| Transform Rule "Verified bots skip the gate" | Cloudflare → Rules → Transform Rules | Adds `x-fig-known-bot: <GATE_BOT_TOKEN>` to requests from Cloudflare-verified bots, so search engines and link previews skip the gate (section 1, step 14). |
| GitHub App | GitHub → Settings → Developer settings | The Worker's identity for commits (queue approvals, edits, removals). |
| GitHub Actions | [`.github/workflows/`](../.github/workflows) | Data pipeline (`refresh.yml`, `update.yml`, `force_update.yml`), CI, releases, build monitor. |
| Staging Worker `free-games-itchio-list-staging` | `staging.freeitchgames.win` (whole host behind Access) | Pre-release checks of branch `v4` (`wrangler.jsonc` → `env.staging`). |
| Staging Worker `free-games-itchio-list-staging` | `staging.freeitchgames.win` (whole host behind Access) | Optional pre-release checks, deployed by hand from any branch with `npx wrangler deploy --env staging` (`wrangler.jsonc` → `env.staging`). |
## 1. Cloudflare
Do these once (and again with the `-staging` names for the staging Worker).
1. **Build settings** (Worker → Settings → Build): root directory `webapp`; build command
`npm run build`; deploy command `npx wrangler deploy` (staging: `npx wrangler deploy --env staging`,
production branch `v4`); build variables `NODE_VERSION=24` and, once Web Analytics exists,
`VITE_CF_BEACON_TOKEN=<token>`. Builds for non-production branches: turn them **off** for the
staging Worker (otherwise every push to `main` also gets a preview build there).
`npm run build`; deploy command `npx wrangler deploy`; build variable `NODE_VERSION=24` (no
`VITE_CF_BEACON_TOKEN`: the zone injects Web Analytics, step 10). The staging Worker, if you use
it, is deployed by hand (`npx wrangler deploy --env staging`); turn its builds for non-production
branches **off** (otherwise every push to `main` also gets a preview build there).
2. **Domains & routes** (Worker → Settings → Domains & Routes): keep the custom domains
`freeitchgames.win` and `www.freeitchgames.win`; delete any `*freeitchgames.win/*` route; a Redirect
Rule sends `www` to the apex. `workers.dev` and preview URLs stay off (`wrangler.jsonc` sets them;
@@ -51,7 +52,10 @@ Do these once (and again with the `-staging` names for the staging Worker).
(Access → Service credentials) named e.g. `itch-f2p-extension`, with an expiry; copy the AUD tag.
The extension sends `CF-Access-Client-Id` / `CF-Access-Client-Secret`.
- Staging: one self-hosted app covering all of `staging.freeitchgames.win`.
7. **Turnstile**: add a widget (Managed) for `freeitchgames.win` and `staging.freeitchgames.win`.
7. **Turnstile**: add a widget (Managed) for `freeitchgames.win` and `staging.freeitchgames.win`. The
same widget serves the verification gate (action `gate`) and the Suggest form (action `suggest`);
the Worker checks the token, the hostname and the action, so a token from one can't be used for
the other.
8. **Fill in `wrangler.jsonc` vars** (not secret) and commit: `ACCESS_TEAM_DOMAIN`
(`https://<team>.cloudflareaccess.com`, no trailing slash), `ACCESS_AUD_ADMIN`, `ACCESS_AUD_INGEST`,
`GH_APP_ID`, `GH_APP_INSTALLATION_ID`, `TURNSTILE_SITEKEY` — in both the top level and
@@ -64,19 +68,57 @@ Do these once (and again with the `-staging` names for the staging Worker).
npx wrangler secret put GH_APP_PRIVATE_KEY < app.private-key.pem
npx wrangler secret put ADMIN_EMAILS # comma-separated
npx wrangler secret put TURNSTILE_SECRET
npx wrangler secret put GATE_BOT_TOKEN # the verification gate, step 14
openssl rand -base64 48 | npx wrangler secret put GATE_SECRET # last: this switches the gate on
```
Until a feature's settings exist it answers 503; the public site works without any of them.
10. **Web Analytics**: add the site with *manual* setup (automatic injection off) and put the token in
the `VITE_CF_BEACON_TOKEN` build variable.
Until a feature's settings exist it answers 503 (the gate simply stays off); the public site works
without any of them.
10. **Web Analytics**: the site uses the **automatic** setup — the zone injects the beacon into every
HTML response (checked on 2026-09-24), so the build needs no token. Don't also set
`VITE_CF_BEACON_TOKEN`: every page view would count twice. The CSPs of the app, the admin page and
the verification page allow the beacon.
11. **Email Routing**: create `legal@`, `privacy@`, `security@`, `takedown@freeitchgames.win` and forward
them to your mailbox (the policies publish these addresses).
12. **Zone settings**: SSL/TLS Full (strict), Always Use HTTPS, minimum TLS 1.2, TLS 1.3 on; Smart
Tiered Cache; Browser Cache TTL "Respect existing headers"; Rocket Loader and Email Obfuscation
**off** (they rewrite HTML and break the CSP); WAF managed rules on; one rate-limiting rule for
`/api/*`; Bot Fight Mode **off** (it can't be skipped for the extension or the apps). Keep HSTS
`/api/*`; Bot Fight Mode **off** (it can't be skipped for the extension or the apps; the
verification gate covers the web app instead). Keep HSTS
`preload` only if every subdomain (including `staging`) will always be HTTPS.
13. **Notifications**: enable the Workers Builds failure notification (independent of
`deploy-status.yml`).
14. **Verification gate** ([`webapp/worker/gate.ts`](../webapp/worker/gate.ts)). A visitor must pass a
Turnstile check before the app shell and `/img` are served; the pass is an HttpOnly cookie good for
`BOT_GATE_TTL_HOURS` (1–168, default 48; lowering it also shortens passes already given out).
`/data`, `/assets`, robots, sitemap, the social image, `/api/*` and `/admin*` stay open, and the
desktop/Android apps are not affected. `BOT_GATE` is `"on"` in `wrangler.jsonc`, but the gate
stays off (fails open) until both secrets below exist. In this order:
1. Check the Workers plan: `/` now runs the Worker too (on the Free plan, Worker-first paths answer
429 once the day's 100,000 requests are used up; `/img` already uses most of them).
2. Generate the bot token (`openssl rand -hex 32`), keep it in your password manager, and
`npx wrangler secret put GATE_BOT_TOKEN` it.
3. Rules → Transform Rules → **Modify Request Header** → create "Verified bots skip the gate":
custom filter `(cf.client.bot)` — or `(cf.client.bot and not cf.verified_bot_category in
{"AI Crawler"})` to keep AI crawlers out — then *Set static* header `x-fig-known-bot` to the token.
4. Check that the header reaches the Worker: add a temporary rule `(ip.src eq <your IP>)` that sets
the same header, then `curl -s https://freeitchgames.win/api/verify` must say `"via":"bot"`.
Delete the temporary rule. If it doesn't say so, stop here and don't set `GATE_SECRET`.
5. `openssl rand -base64 48 | npx wrangler secret put GATE_SECRET` — the gate is on.
6. Smoke test: `curl -sI https://freeitchgames.win/` shows `x-robots-tag: noindex, nofollow` and
`cache-control: no-store` (the verification page); `/img/160/x` answers 403;
`/data/index.json` answers 200 with `access-control-allow-origin: *`;
`curl -sI -A 'Googlebot/2.1' https://freeitchgames.win/` answers 503 (only verified bots, via
the rule, get through); a real browser passes and lands on the page it opened; Search Console →
URL Inspection → *Test live URL* renders the real app. Watch Security → Events and Search
Console for a week.
**Off switch:** `npx wrangler secret delete GATE_SECRET` turns the gate off at once, and
data-commit deploys don't bring it back; to keep it off, set `BOT_GATE` to `"off"` in
`wrangler.jsonc`. Staging: set `TURNSTILE_SITEKEY` and `BOT_GATE: "on"` under `env.staging` and add
both secrets with `--env staging`. Locally: put the Turnstile test keys,
`SITE_ORIGIN=http://localhost:8787` and a 32+ character `GATE_SECRET` in `webapp/.dev.vars`, then
`npm run build && npx wrangler dev` (on localhost the cookie is `fig_gate`, without `Secure`, and
no bot token is needed).
## 2. GitHub
@@ -88,25 +130,27 @@ Do these once (and again with the `-staging` names for the staging Worker).
Dependabot security updates on; CodeQL default setup and secret scanning if you want them (the
policies don't claim them). Rulesets: target the default branch (block deletion and force
pushes); protect tags `v*`. Merge PRs with squash or a merge commit — never fast-forward.
3. **Secrets**: keep `DISCORD_CI_WEBHOOK`, the release webhooks and the Android keystore secrets;
delete `GH_TOKEN`, `TELEGRAM_BOT_TOKEN` and `DISCUSSION_*` once nothing uses them.
3. **Secrets**: keep `DISCORD_CI_WEBHOOK`, the release webhooks and the Android keystore secrets.
`GH_TOKEN`, `TELEGRAM_BOT_TOKEN` and the three `DISCUSSION_*` secrets are still set but no workflow
uses them any more (checked 2026-09-24): delete them.
4. **Signing key**: the old key `03F965C2E2DB5C6B` was exposed; sign with the replacement key.
## 3. Release order for v4
## 3. Releasing a version
1. Merge PR #81 (Phase 0), then PR #82 (Phase 1). Dispatch **Refresh catalog** once with a small
`budget` (e.g. 50) and check the run summary.
2. Rebase `v4` on `main`, push it, open the v4 PR. Set up the staging Worker (1.1, 1.3–1.9 with the
staging names) and check `staging.freeitchgames.win`: covers load through `/img`, `/admin` asks
for login (also in a private window), a Suggest submission appears in the admin queue, approving
it creates a verified commit on a scratch branch or `main`, the Web Analytics beacon and Turnstile
raise no CSP errors.
3. Production: complete section 1 for the production names, apply the D1 migrations, then merge the v4
PR (squash or merge commit). Watch the Workers Build; roll back from Workers → Deployments if
needed.
4. Tag `v4.0.0` from `main` (see the release process in [`CLAUDE.md`](../CLAUDE.md)), wait for the
desktop + Android assets on the draft, publish it.
5. Switch the browser extension to `/api/ingest` with the service token, then revoke its old PAT.
1. Bump the version everywhere it lives: `webapp/src/lib/about.ts` (`APP.version`),
`webapp/package.json` + `package-lock.json` (`npm version X.Y.Z --no-git-tag-version`),
`webapp/src-tauri/tauri.conf.json`, `webapp/src-tauri/Cargo.toml` + `Cargo.lock`, and the version
badges of `README.md` / `README.vi.md`. Write the notes in
`changelog/<major>.x/ver<major>.<minor>.x.md` and add the row to [`CHANGELOG.md`](../CHANGELOG.md).
2. Open a PR; when CI is green, merge it with squash or a merge commit — never fast-forward. A push
that touches the changelog posts to Discussions → General unless the head commit says
`[skip-discuss]` (the release announcement usually covers it).
3. Apply any new D1 migration and set any new secret **before** the merge deploys code that needs them.
4. Tag from `main`: `git fetch origin && git tag -s vX.Y.Z origin/main -m "…"`, then
`git push origin vX.Y.Z`. `release_desktop.yml` opens one draft release and the desktop and Android
jobs upload into it (12 assets for 4.x). Never create the release by hand first.
5. When every asset is there, edit the title and notes (from the changelog), then
`gh release edit vX.Y.Z --draft=false` — that fires the Discord and Discussions announcements.
## 4. Routine
@@ -121,3 +165,6 @@ Do these once (and again with the `-staging` names for the staging Worker).
site keeps serving the previous deployment meanwhile.
- **New D1 migration**: add `webapp/worker/migrations/000N_*.sql` (never edit applied ones), apply it
to staging and production by hand, then deploy.
- **Verification gate misbehaving** (visitors stuck on the check, crawl errors in Search Console):
`npx wrangler secret delete GATE_SECRET` turns it off at once; then look at `npx wrangler tail` and
`curl -s https://freeitchgames.win/api/verify`.
+6 -1
View File
@@ -104,7 +104,12 @@ Tauri apps use hash routes (`HashRouter`) on their custom protocol
([`src/components/app-router.tsx`](src/components/app-router.tsx)). The Worker serves the app shell
with `200` for known routes, `404` for anything else and a `301` for renamed routes
(`/deleted` → `/removed`), so [`worker/spa.ts`](worker/spa.ts) must be kept in sync with `App.tsx`.
Every route except `/`, `/games`, `/removed` and the Not Found page is `React.lazy`.
Every route except `/`, `/games` and the Not Found page is `React.lazy`.
With the verification gate on, a visitor who has not passed the Turnstile check gets the
verification page instead of the shell on every app route (and `403` on `/img`); see
[`worker/gate.ts`](worker/gate.ts) and the setup in
[`docs/operations.md`](../docs/operations.md) (section 1, step 14).
## Admin (`/admin/`)
+2 -2
View File
@@ -73,7 +73,7 @@ npm run tauri:build
- Windows: `webapp/src-tauri/target/release/bundle/msi/*.msi` and `nsis/*.exe`
- macOS: `webapp/src-tauri/target/release/bundle/dmg/*.dmg` and `macos/*.app`
- Linux: `webapp/src-tauri/target/release/bundle/{appimage,deb}/*`
- Linux: `webapp/src-tauri/target/release/bundle/{appimage,deb,rpm}/*`
### Installer license page
@@ -89,7 +89,7 @@ only the desktop and Android apps.
push (or `workflow_dispatch`). Its `create-release` job opens **one draft** GitHub Release; the build
jobs (Windows, macOS aarch64 + x86_64 cross-compiled from an Apple Silicon runner, Linux) upload into
it: `.msi` / `.exe`, `.dmg` / `.app.tar.gz` / `.pkg` (built with `pkgbuild`, identifier read from
`tauri.conf.json`), `.deb` / `.AppImage`. Release builds use no npm / cargo caches. The Android job
`tauri.conf.json`), `.deb` / `.rpm` / `.AppImage`. Release builds use no npm / cargo caches. The Android job
([below](#ci)) attaches the APK to the same draft; the Maintainer publishes it once every asset is
there (release steps: [`CLAUDE.md`](../CLAUDE.md#release--tag-process)).
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "webapp",
"version": "4.0.0",
"version": "4.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "webapp",
"version": "4.0.0",
"version": "4.1.0",
"license": "MIT",
"dependencies": {
"@fontsource-variable/geist": "^5.3.0",
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "webapp",
"private": true,
"version": "4.0.0",
"version": "4.1.0",
"license": "MIT",
"type": "module",
"engines": {
+13 -4
View File
@@ -1,9 +1,12 @@
# Cloudflare Workers static-asset headers (files in dist/ only — responses the
# Worker builds itself set their own, see worker/http.ts).
# Cloudflare Workers static-asset headers: files in dist/, served directly or
# fetched by the Worker through env.ASSETS (the app shell). Responses the Worker
# builds itself set their own — JSON and /img in worker/http.ts, the
# verification page (its own CSP with a nonce) in worker/gate-page.ts.
# HSTS and X-Content-Type-Options are already sent by the zone.
#
# CSP: everything is same-origin (/data catalog, /img covers). The Cloudflare
# Web Analytics beacon and Turnstile (Suggest form) are the only third parties.
# CSP: everything is same-origin (/data catalog, /img covers). The only third
# parties are the Cloudflare Web Analytics beacon, which the zone injects into
# every HTML response, and Turnstile (the Suggest form).
# style-src needs 'unsafe-inline' (Radix and Recharts set inline styles at runtime).
/*
Referrer-Policy: strict-origin-when-cross-origin
@@ -28,5 +31,11 @@
/icon-*
Cache-Control: public, max-age=604800
/favicon.svg
Cache-Control: public, max-age=604800
/manifest.webmanifest
Cache-Control: public, max-age=86400
/.well-known/security.txt
Cache-Control: public, max-age=86400
+1 -1
View File
@@ -1057,7 +1057,7 @@ dependencies = [
[[package]]
name = "free-games-itchio-webapp"
version = "4.0.0"
version = "4.1.0"
dependencies = [
"serde",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "free-games-itchio-webapp"
version = "4.0.0"
version = "4.1.0"
description = "Itch.io free games catalog viewer"
authors = ["poli0981"]
license = "MIT"
+3 -3
View File
@@ -2,10 +2,10 @@
\viewkind4\uc1\pard\f0\fs18
{\b\fs22 END-USER LICENSE AGREEMENT (EULA)}\par
Itch.io Free Games DB - desktop and Android apps\par
Last updated: 2026-09-18\par
Applies from: the release of version 4.0.0.\par
Last updated: 2026-09-24\par
Applies from: the release of version 4.1.0.\par
\par
This EULA applies only to the desktop and Android apps of Itch.io Free Games DB: the installers (.msi, .exe, .dmg, .pkg, .app.tar.gz, .deb, .AppImage) and the Android .apk published on GitHub Releases. It does NOT cover:\par
This EULA applies only to the desktop and Android apps of Itch.io Free Games DB: the installers (.msi, .exe, .dmg, .pkg, .app.tar.gz, .deb, .rpm, .AppImage) and the Android .apk published on GitHub Releases. It does NOT cover:\par
- the website https://freeitchgames.win, which is covered by the Terms of Use;\par
- the source code, which is under the MIT License (the LICENSE file in the Repository);\par
- the catalog data, which is under CC BY 4.0 (see data_game/LICENSE.md and LICENSES/CC-BY-4.0.txt in the Repository);\par
+1 -1
View File
@@ -1,7 +1,7 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "Itch.io Free Games DB",
"version": "4.0.0",
"version": "4.1.0",
"identifier": "com.poli0981.freegamesitchio",
"build": {
"beforeDevCommand": "npm run dev",
@@ -4,6 +4,8 @@ import { countBy, topN } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function AvgSessionChart({ games }: { games: Game[] }) {
@@ -16,11 +18,8 @@ export function AvgSessionChart({ games }: { games: Game[] }) {
<CartesianGrid strokeDasharray="3 3" />
<XAxis dataKey="key" tick={{ fontSize: 10 }} interval={0} angle={-20} textAnchor="end" height={60} />
<YAxis />
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[6]} radius={[4, 4, 0, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.games')} fill={PALETTE[6]} radius={[4, 4, 0, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
+6 -1
View File
@@ -15,7 +15,12 @@ export function ChartCard({ title, description, children }: ChartCardProps) {
<p className="text-xs text-muted-foreground">{description}</p>
)}
</CardHeader>
<CardContent className="h-72">{children}</CardContent>
{/* Recharts 3 makes the chart focusable (keyboard navigation). A mouse
click would focus it too, drawing the browser's focus ring and
pinning the tooltip on the first item; keep clicks from moving focus. */}
<CardContent className="h-72" onMouseDown={(e) => e.preventDefault()}>
{children}
</CardContent>
</Card>
)
}
@@ -0,0 +1,18 @@
// Shared Recharts props. The design tokens in index.css are hex colours, so
// reference them as `var(--x)` — `hsl(var(--x))` is an invalid colour, which
// SVG paints black and CSS drops (a transparent tooltip).
/** Every <Tooltip>: no slide-in animation, no focus outline, above the legend. */
export const TOOLTIP_BASE = {
isAnimationActive: false,
wrapperStyle: { outline: 'none', zIndex: 10 },
} as const
/** Hover band behind the active bar. */
export const BAR_CURSOR = { fill: 'var(--accent)' }
/** Hover guide on line charts. */
export const LINE_CURSOR = { stroke: 'var(--muted-foreground)', strokeDasharray: '3 3' }
/** Seams between pie slices in the card colour (Recharts draws white seams by default). */
export const SLICE_STROKE = 'var(--card)'
@@ -0,0 +1,43 @@
import type { TooltipContentProps, TooltipPayloadEntry } from 'recharts'
import { useFormat } from '@/lib/format'
interface ChartTooltipContentProps extends Partial<Pick<TooltipContentProps, 'active' | 'payload' | 'label'>> {
/** Sum of all slices of a pie whose slices cover the whole: adds each value's share. */
total?: number
/** Formats the heading (the category or x value), e.g. an ISO date. */
labelFormat?: (label: string) => string
/** Swatch colour when the entry carries none (the treemap colours its cells itself). */
colorOf?: (entry: TooltipPayloadEntry) => string | undefined
}
/**
* Tooltip body for every chart: popover colours from the theme tokens, a swatch
* per series, and numbers formatted for the chosen language. Pass it as
* `content={<ChartTooltipContent />}`; Recharts fills in active/payload/label.
*/
export function ChartTooltipContent({ active, payload, label, total, labelFormat, colorOf }: ChartTooltipContentProps) {
const fmt = useFormat()
if (!active || !payload?.length) return null
const heading = label === undefined || label === '' ? '' : labelFormat ? labelFormat(String(label)) : String(label)
return (
<div className="min-w-36 rounded-md border bg-popover px-3 py-2 text-xs text-popover-foreground shadow-md">
{heading && <p className="mb-1.5 font-medium">{heading}</p>}
<ul className="space-y-1">
{payload.map((entry, i) => {
const value = Number(entry.value)
const color = colorOf?.(entry) ?? entry.color ?? entry.fill
return (
<li key={`${String(entry.name)}-${i}`} className="flex items-center gap-2">
<span aria-hidden="true" className="size-2.5 shrink-0 rounded-[3px]" style={{ background: color }} />
<span className="text-muted-foreground">{entry.name}</span>
<span className="ml-auto pl-4 font-mono font-medium tabular-nums">
{Number.isFinite(value) ? fmt.number(value) : String(entry.value ?? '')}
{total && Number.isFinite(value) ? ` (${fmt.percent(value / total)})` : null}
</span>
</li>
)
})}
</ul>
</div>
)
}
@@ -4,26 +4,32 @@ import { deletionReasonCounts } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { DeletedGameEntry } from '@/types/game'
import { ChartCard } from './chart-card'
import { SLICE_STROKE, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function DeletionReasonsChart({ deleted }: { deleted: DeletedGameEntry[] }) {
const t = useT()
const data = useMemo(() => deletionReasonCounts(deleted), [deleted])
const total = data.reduce((sum, d) => sum + d.count, 0)
return (
<ChartCard title={t('charts.deletionReasons.title')} description={t('charts.deletionReasons.desc')}>
<ResponsiveContainer width="100%" height="100%">
<PieChart>
<Pie data={data} dataKey="count" nameKey="key" innerRadius="50%" outerRadius="80%" paddingAngle={2}>
<Pie
data={data}
dataKey="count"
nameKey="key"
innerRadius="50%"
outerRadius="80%"
paddingAngle={2}
stroke={SLICE_STROKE}
>
{data.map((_, i) => (
<Cell key={i} fill={PALETTE[i % PALETTE.length]} />
))}
</Pie>
<Tooltip
contentStyle={{
background: 'hsl(var(--popover))',
border: '1px solid hsl(var(--border))',
}}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent total={total} />} />
<Legend />
</PieChart>
</ResponsiveContainer>
@@ -4,6 +4,8 @@ import { deletionsByMonth } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { DeletedGameEntry } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function DeletionsOverTimeChart({ deleted }: { deleted: DeletedGameEntry[] }) {
@@ -16,11 +18,8 @@ export function DeletionsOverTimeChart({ deleted }: { deleted: DeletedGameEntry[
<CartesianGrid strokeDasharray="3 3" />
<XAxis dataKey="key" tick={{ fontSize: 10 }} interval={0} angle={-25} textAnchor="end" height={60} />
<YAxis allowDecimals={false} />
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[1]} radius={[4, 4, 0, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.removed')} fill={PALETTE[1]} radius={[4, 4, 0, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
@@ -1,11 +1,15 @@
import { CartesianGrid, Line, LineChart, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts'
import { useFormat } from '@/lib/format'
import { useT } from '@/lib/i18n'
import type { CountHistoryPoint } from '@/types/game'
import { ChartCard } from './chart-card'
import { LINE_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function GameCountChart({ history }: { history: CountHistoryPoint[] }) {
const t = useT()
const fmt = useFormat()
return (
<ChartCard title={t('charts.gameCount.title')} description={t('charts.gameCount.desc')}>
{history.length === 0 ? (
@@ -19,10 +23,18 @@ export function GameCountChart({ history }: { history: CountHistoryPoint[] }) {
<XAxis dataKey="date" tick={{ fontSize: 10 }} minTickGap={24} />
<YAxis tick={{ fontSize: 11 }} width={48} allowDecimals={false} domain={['auto', 'auto']} />
<Tooltip
cursor={{ stroke: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
{...TOOLTIP_BASE}
cursor={LINE_CURSOR}
content={<ChartTooltipContent labelFormat={fmt.date} />}
/>
<Line
type="monotone"
dataKey="total"
name={t('charts.series.games')}
stroke={PALETTE[0]}
strokeWidth={2}
dot={false}
/>
<Line type="monotone" dataKey="total" stroke={PALETTE[0]} strokeWidth={2} dot={false} />
</LineChart>
</ResponsiveContainer>
)}
+4 -5
View File
@@ -4,6 +4,8 @@ import { countBy, topN } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function GenreChart({ games }: { games: Game[] }) {
@@ -16,11 +18,8 @@ export function GenreChart({ games }: { games: Game[] }) {
<CartesianGrid horizontal={false} strokeDasharray="3 3" />
<XAxis type="number" />
<YAxis dataKey="key" type="category" width={120} tick={{ fontSize: 12 }} />
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[0]} radius={[0, 4, 4, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.games')} fill={PALETTE[0]} radius={[0, 4, 4, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
@@ -1,9 +1,11 @@
import { useMemo } from 'react'
import { ResponsiveContainer, Tooltip, Treemap } from 'recharts'
import { ResponsiveContainer, Tooltip, Treemap, type TooltipPayloadEntry } from 'recharts'
import { genreTreemapData } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
interface TreemapCellProps {
@@ -29,11 +31,11 @@ function TreemapCell(props: TreemapCellProps) {
width={width}
height={height}
fill={PALETTE[index % PALETTE.length]}
stroke="hsl(var(--background))"
stroke="var(--background)"
strokeWidth={2}
/>
{width > 56 && height > 24 && (
<text x={x + 6} y={y + 18} fill="hsl(var(--background))" fontSize={12} fontWeight={600}>
<text x={x + 6} y={y + 18} fill="var(--background)" fontSize={12} fontWeight={600}>
{name}
</text>
)}
@@ -41,6 +43,12 @@ function TreemapCell(props: TreemapCellProps) {
)
}
// Tooltip entries carry no colour of their own here: use the cell's.
function cellColor(entry: TooltipPayloadEntry): string {
const index = (entry.payload as { index?: number } | undefined)?.index ?? 0
return PALETTE[index % PALETTE.length]
}
export function GenreTreemapChart({ games }: { games: Game[] }) {
const t = useT()
const data = useMemo(() => genreTreemapData(games, 12), [games])
@@ -51,9 +59,7 @@ export function GenreTreemapChart({ games }: { games: Game[] }) {
<ChartCard title={t('charts.genreTreemap.title')} description={t('charts.genreTreemap.desc')}>
<ResponsiveContainer width="100%" height="100%">
<Treemap data={treemapData} dataKey="size" nameKey="name" content={<TreemapCell />}>
<Tooltip
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent colorOf={cellColor} />} />
</Treemap>
</ResponsiveContainer>
</ChartCard>
@@ -4,6 +4,8 @@ import { countByArray, topN } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function LanguagesChart({ games }: { games: Game[] }) {
@@ -16,11 +18,8 @@ export function LanguagesChart({ games }: { games: Game[] }) {
<CartesianGrid strokeDasharray="3 3" />
<XAxis dataKey="key" tick={{ fontSize: 11 }} interval={0} angle={-25} textAnchor="end" height={60} />
<YAxis />
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[4]} radius={[4, 4, 0, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.games')} fill={PALETTE[4]} radius={[4, 4, 0, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
@@ -4,6 +4,8 @@ import { topMadeWith } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { SLICE_STROKE, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function MadeWithChart({ games }: { games: Game[] }) {
@@ -13,17 +15,20 @@ export function MadeWithChart({ games }: { games: Game[] }) {
<ChartCard title={t('charts.madeWith.title')} description={t('charts.madeWith.desc')}>
<ResponsiveContainer width="100%" height="100%">
<PieChart>
<Pie data={data} dataKey="count" nameKey="key" innerRadius="50%" outerRadius="80%" paddingAngle={2}>
<Pie
data={data}
dataKey="count"
nameKey="key"
innerRadius="50%"
outerRadius="80%"
paddingAngle={2}
stroke={SLICE_STROKE}
>
{data.map((_, i) => (
<Cell key={i} fill={PALETTE[i % PALETTE.length]} />
))}
</Pie>
<Tooltip
contentStyle={{
background: 'hsl(var(--popover))',
border: '1px solid hsl(var(--border))',
}}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent />} />
<Legend />
</PieChart>
</ResponsiveContainer>
@@ -4,6 +4,8 @@ import { classifyOnline } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { SLICE_STROKE, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function OnlineOfflineChart({ games }: { games: Game[] }) {
@@ -17,16 +19,11 @@ export function OnlineOfflineChart({ games }: { games: Game[] }) {
<ChartCard title={t('charts.onlineOffline.title')} description={t('charts.onlineOffline.desc')}>
<ResponsiveContainer width="100%" height="100%">
<PieChart>
<Pie data={data} dataKey="count" nameKey="key" innerRadius="50%" outerRadius="80%">
<Pie data={data} dataKey="count" nameKey="key" innerRadius="50%" outerRadius="80%" stroke={SLICE_STROKE}>
<Cell fill={PALETTE[2]} />
<Cell fill={PALETTE[3]} />
</Pie>
<Tooltip
contentStyle={{
background: 'hsl(var(--popover))',
border: '1px solid hsl(var(--border))',
}}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent total={split.online + split.offline} />} />
<Legend />
</PieChart>
</ResponsiveContainer>
@@ -4,6 +4,8 @@ import { countByArray } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { SLICE_STROKE, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function PlatformChart({ games }: { games: Game[] }) {
@@ -20,17 +22,13 @@ export function PlatformChart({ games }: { games: Game[] }) {
innerRadius="50%"
outerRadius="80%"
paddingAngle={2}
stroke={SLICE_STROKE}
>
{data.map((_, i) => (
<Cell key={i} fill={PALETTE[i % PALETTE.length]} />
))}
</Pie>
<Tooltip
contentStyle={{
background: 'hsl(var(--popover))',
border: '1px solid hsl(var(--border))',
}}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent />} />
<Legend />
</PieChart>
</ResponsiveContainer>
@@ -4,6 +4,8 @@ import { ratingHistogram } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function RatingChart({ games }: { games: Game[] }) {
@@ -16,11 +18,8 @@ export function RatingChart({ games }: { games: Game[] }) {
<CartesianGrid strokeDasharray="3 3" />
<XAxis dataKey="key" tick={{ fontSize: 10 }} />
<YAxis />
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[5]} radius={[4, 4, 0, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.games')} fill={PALETTE[5]} radius={[4, 4, 0, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
@@ -4,26 +4,24 @@ import { countBy } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { SLICE_STROKE, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function StatusChart({ games }: { games: Game[] }) {
const t = useT()
const data = useMemo(() => countBy(games, 'status'), [games])
const total = data.reduce((sum, d) => sum + d.count, 0)
return (
<ChartCard title={t('charts.status.title')} description={t('charts.status.desc')}>
<ResponsiveContainer width="100%" height="100%">
<PieChart>
<Pie data={data} dataKey="count" nameKey="key" outerRadius="80%">
<Pie data={data} dataKey="count" nameKey="key" outerRadius="80%" stroke={SLICE_STROKE}>
{data.map((_, i) => (
<Cell key={i} fill={PALETTE[i % PALETTE.length]} />
))}
</Pie>
<Tooltip
contentStyle={{
background: 'hsl(var(--popover))',
border: '1px solid hsl(var(--border))',
}}
/>
<Tooltip {...TOOLTIP_BASE} content={<ChartTooltipContent total={total} />} />
<Legend />
</PieChart>
</ResponsiveContainer>
@@ -4,6 +4,8 @@ import { topByRatingCount } from '@/lib/analytics'
import { useT } from '@/lib/i18n'
import type { Game } from '@/types/game'
import { ChartCard } from './chart-card'
import { BAR_CURSOR, TOOLTIP_BASE } from './chart-theme'
import { ChartTooltipContent } from './chart-tooltip'
import { PALETTE } from './palette'
export function TopRatedCountChart({ games }: { games: Game[] }) {
@@ -22,11 +24,8 @@ export function TopRatedCountChart({ games }: { games: Game[] }) {
tick={{ fontSize: 11 }}
tickFormatter={(v: string) => (v.length > 20 ? `${v.slice(0, 19)}…` : v)}
/>
<Tooltip
cursor={{ fill: 'hsl(var(--accent))' }}
contentStyle={{ background: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }}
/>
<Bar dataKey="count" fill={PALETTE[3]} radius={[0, 4, 4, 0]} />
<Tooltip {...TOOLTIP_BASE} cursor={BAR_CURSOR} content={<ChartTooltipContent />} />
<Bar dataKey="count" name={t('charts.series.ratings')} fill={PALETTE[3]} radius={[0, 4, 4, 0]} />
</BarChart>
</ResponsiveContainer>
</ChartCard>
+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}
/>
)
+6
View File
@@ -153,6 +153,12 @@
}
}
/* Charts: Chromium's SVG stylesheet outlines any focused element, mouse focus
included. Keep the ring for keyboard focus only (the :focus-visible rule above). */
.recharts-wrapper :focus:not(:focus-visible) {
outline: none;
}
/* index.html's static fallback shows only if the app hasn't started after a moment. */
[data-static-fallback] {
animation: static-fallback 0s 1.5s both;
+1 -1
View File
@@ -8,7 +8,7 @@ export interface ThirdParty {
export const APP = {
name: 'Free Itch Games',
version: '4.0.0',
version: '4.1.0',
repo: 'https://github.com/poli0981/free-games-itchio-list',
license: 'code MIT · data CC BY 4.0',
} as const
+4
View File
@@ -8,6 +8,8 @@ export interface Formatters {
number: (n: number) => string
/** 4.9 → "4.9" (en) / "4,9" (vi), always one decimal. */
rating: (n: number) => string
/** 0.631 → "63.1%" (en) / "63,1%" (vi), at most one decimal. */
percent: (ratio: number) => string
/** ISO date/time → "17 Aug 2026" (en) / "17 thg 8, 2026" (vi); '' when invalid. */
date: (iso: string | undefined) => string
}
@@ -19,10 +21,12 @@ export function useFormat(): Formatters {
const locale = LOCALES[language]
const numbers = new Intl.NumberFormat(locale)
const ratings = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 })
const percents = new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 })
const dates = new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' })
return {
number: (n) => numbers.format(n),
rating: (n) => ratings.format(n),
percent: (n) => percents.format(n),
date: (iso) => {
const at = iso ? Date.parse(iso) : Number.NaN
return Number.isNaN(at) ? '' : dates.format(at)
+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()
})
}
+4 -1
View File
@@ -71,7 +71,7 @@ export const en = {
"about.bug.openTemplate": "Open bug report template",
"about.bug.title": "Found a bug?",
"about.developer.title": "Developer",
"about.legal.desc": "All policies are Markdown files in the repository — plain language, full terms. Updated 2026-09-18.",
"about.legal.desc": "All policies are Markdown files in the repository — plain language, full terms. Updated 2026-09-24.",
"about.legal.title": "Legal & policies",
"about.legal.viNote": "— Vietnamese translations of the policies above (community-readable, English remains the controlling version for legal interpretation).",
"about.social.desc": "DMs open on most. Replies slow (introvert max level). Pick whichever channel fits.",
@@ -119,6 +119,9 @@ export const en = {
"charts.recentDeleted.desc": "Last {shown} of {total} total",
"charts.recentDeleted.empty": "No deletions logged.",
"charts.recentDeleted.title": "Recent Deletions",
"charts.series.games": "Games",
"charts.series.ratings": "Ratings",
"charts.series.removed": "Removed",
"charts.status.desc": "Released vs prototype/in-progress",
"charts.status.title": "Status Mix",
"charts.tabs.discovery": "Discovery",
+4 -1
View File
@@ -73,7 +73,7 @@ export const vi: Record<MessageKey, string> = {
"about.bug.openTemplate": "Mở mẫu báo cáo bug",
"about.bug.title": "Phát hiện bug?",
"about.developer.title": "Nhà phát triển",
"about.legal.desc": "Tất cả chính sách là file Markdown trong repo — dễ hiểu, đầy đủ điều khoản. Cập nhật 2026-09-18.",
"about.legal.desc": "Tất cả chính sách là file Markdown trong repo — dễ hiểu, đầy đủ điều khoản. Cập nhật 2026-09-24.",
"about.legal.title": "Pháp lý & chính sách",
"about.legal.viNote": "— bản dịch tiếng Việt của các chính sách trên (để cộng đồng dễ đọc; bản tiếng Anh vẫn là bản có hiệu lực khi diễn giải pháp lý).",
"about.social.desc": "DM mở trên hầu hết các kênh. Trả lời chậm (hướng nội cấp tối đa). Chọn kênh nào tiện cho bạn.",
@@ -121,6 +121,9 @@ export const vi: Record<MessageKey, string> = {
"charts.recentDeleted.desc": "{shown} mục mới nhất trong tổng số {total}",
"charts.recentDeleted.empty": "Chưa ghi nhận lượt xoá nào.",
"charts.recentDeleted.title": "Xoá gần đây",
"charts.series.games": "Số game",
"charts.series.ratings": "Lượt đánh giá",
"charts.series.removed": "Đã gỡ",
"charts.status.desc": "Đã phát hành so với prototype/đang phát triển",
"charts.status.title": "Tỷ lệ trạng thái",
"charts.tabs.discovery": "Khám phá",
+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
}
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Cloudflare Turnstile, loaded on demand (only the Suggest page needs it; the
* Cloudflare Turnstile, loaded on demand (in the app only the Suggest page needs it; the
* site CSP allows its script and frame). Explicit rendering, so the widget
* mounts and unmounts with the React component.
*/
+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()
+1 -1
View File
@@ -9,7 +9,7 @@ type Language = 'en' | 'vi'
* policy in docs/) to re-prompt every user once. Kept in sync with the
* "Updated …" date in `about.legal.desc`. Stored value !== this → gate shows.
*/
export const LEGAL_VERSION = '2026-09-18'
export const LEGAL_VERSION = '2026-09-24'
interface PrefsStore {
density: Density
+6 -4
View File
@@ -138,10 +138,12 @@ export function buildInfo(): Plugin {
}
/**
* Cloudflare Web Analytics beacon (cookieless), web build only, and only when
* the build has a token (Workers Builds variable VITE_CF_BEACON_TOKEN; set up
* the site as "manual" with automatic injection off). Never on the admin page,
* whose CSP allows only its own scripts. The site CSP allows the beacon.
* Cloudflare Web Analytics beacon (cookieless) for a *manual* Web Analytics
* setup: web build only, only when the build has a token (Workers Builds
* variable VITE_CF_BEACON_TOKEN), never on the admin page. freeitchgames.win
* uses the automatic setup instead — the zone injects the beacon into every
* HTML response — so the token stays unset; setting it too would count every
* page view twice. The site CSP allows the beacon either way.
*/
export function analyticsBeacon(token: string | undefined): Plugin {
return {
+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"
}
}
}