Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
8a55e73
docs: update moderation and release documentation with production dep…
djblackett Nov 12, 2026
f1a031a
Merge branch 'main' into dev: record Stage 2 release merge 8569834
djblackett Nov 12, 2026
4c0af25
fix(android): guard signed release inspection; drop stray blank lines
djblackett Nov 12, 2026
5db17fb
docs: current release status and phone test checklist
djblackett Nov 12, 2026
0ebef43
fix(test): restore frontend typecheck broken by 4c0af25
djblackett Nov 12, 2026
9813dd5
feat(server): daily moderation email digest on the existing cron
djblackett Nov 12, 2026
5d720ce
docs: confirm privacy contact, score retention policy, digest and UGC…
djblackett Nov 12, 2026
b7385e8
docs(privacy): Hull & Havoc public privacy page for GitHub Pages (unp…
djblackett Nov 12, 2026
7c28c2f
Merge branch 'feature/privacy-policy-page' into release/hull-and-havo…
djblackett Nov 12, 2026
06b724c
feat(branding): show the game as Hull & Havoc
djblackett Nov 12, 2026
c011258
fix(digest): carry expiry notices past undelivered days; Hull & Havoc…
djblackett Nov 12, 2026
9b428b7
docs: digest activation runbook; Hull & Havoc release status and poli…
djblackett Nov 12, 2026
d06ad4c
docs: record Hull & Havoc release-candidate verification and Play check
djblackett Nov 12, 2026
ce36fd8
feat(privacy): accurate policy wording, in-game full-policy link, exp…
djblackett Nov 12, 2026
c90bb10
docs(privacy): record remediation, date procedure and remaining decis…
djblackett Nov 12, 2026
30f663d
release(privacy): approve policy, remove in-game draft line, set dige…
djblackett Nov 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
311 changes: 311 additions & 0 deletions docs/digest-activation-runbook.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions docs/leaderboard-backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ Migrations `server/migrations/0001_init.sql` and `0002_time_limit.sql` (applied

**`rate_limits`** — `(bucket, window_start)` PK, `count`.

Indexes: partial board index `(rules_version, score DESC, completed_at ASC, id ASC) WHERE visibility='visible' AND score>0` (serves every leaderboard read) and `(rules_version, completed_at)` for weekly ranges. **Replays are not stored.** Only `replay_hash` is kept. Housekeeping (daily cron): abandoned runs a day past expiry, rejected runs after 30 days, stale rate-limit rows. Accepted runs are kept.
Indexes: partial board index `(rules_version, score DESC, completed_at ASC, id ASC) WHERE visibility='visible' AND score>0` (serves every leaderboard read) and `(rules_version, completed_at)` for weekly ranges. **Replays are not stored.** Only `replay_hash` is kept. Housekeeping (daily cron): abandoned runs a day past expiry, rejected runs after 30 days, stale rate-limit rows, reports after 30 days. Accepted runs are kept. The same cron then sends the optional [moderation digest](leaderboard-moderation.md#daily-moderation-digest) (migration 0005; disabled unless configured).

## 6. API contracts

Expand Down Expand Up @@ -310,7 +310,7 @@ One-use run ids; CSPRNG tokens and seeds; expiry; atomic state transitions; per-

Minimal logging (no IPs, nicknames or tokens): `run_rejected`, `verifier_threw`, `submit_failed`, `unhandled`, `prune`.

Moderation: use the Worker-origin `/admin` console or the authenticated APIs in the [moderation operator guide](leaderboard-moderation.md). Pending migrations 0003/0004 add private reports, reversible display names and transactional audit records. Avoid direct SQL moderation: it bypasses revision guards and audit history. Public boards/details now use `Cache-Control: no-store`.
Moderation: use the Worker-origin `/admin` console or the authenticated APIs in the [moderation operator guide](leaderboard-moderation.md). Migrations 0003/0004 (applied in production 2026-11-04) add private reports, reversible display names and transactional audit records. Avoid direct SQL moderation: it bypasses revision guards and audit history. Public boards/details now use `Cache-Control: no-store`.

## 11. What an attacker can and cannot do

Expand Down
119 changes: 108 additions & 11 deletions docs/leaderboard-moderation.md

Large diffs are not rendered by default.

5 changes: 3 additions & 2 deletions docs/play-data-inventory.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Android privacy inventory and proposed Data safety answers

Audit date: 2026-11-03; moderation follow-up 2026-11-04. Branch: `dev`. Scope: Capacitor Android application, browser code shared with it, Cloudflare Worker and D1 schema. Root Python game's scores/logging are not packaged in the Android game. No cloud account settings or production data were read or modified. Reporting, erasure and the extended moderation workflow below are implemented locally, not deployed. See [moderation audit and operator guide](leaderboard-moderation.md).
Audit date: 2026-11-03; moderation follow-up 2026-11-04. Branch: `dev`. Scope: Capacitor Android application, browser code shared with it, Cloudflare Worker and D1 schema. Root Python game's scores/logging are not packaged in the Android game. No cloud account settings or production data were read or modified. Reporting, erasure and the extended moderation workflow below were implemented locally at audit time and **have been live in production since 2026-11-04** (Worker `c2aef78f`, D1 migrations 0001-0004; see the [Stage 2 record](release-preflight.md#stage-2-production-worker-deployment-2026-11-04)). The proposed answers below are still unconfirmed against provider settings. See [moderation audit and operator guide](leaderboard-moderation.md).

## Confirmed data flows

Expand All @@ -15,6 +15,7 @@ Audit date: 2026-11-03; moderation follow-up 2026-11-04. Branch: `dev`. Scope: C
| Abuse counters | Start, submit, failed-admin and new report per-IP buckets; global buckets; hour start and count | Delete window starts older than 2 hours at daily cleanup; effective retention roughly 2–26 hours, longer if cleanup fails | `server/src/ratelimit.ts`, `worker.ts` |
| Reports (new) | POST `/scores/:id/report`: score ID, fixed reason (offensive/personal_info/suspicious_score/other), open/resolved status, salted reporter-IP hash, creation time | Private queue; one row per entry/hash. Repeats can update an open reason, not creation time; a resolved complaint cannot be reopened by the same reporter. Purged after 30 days at daily cron, or cascade on score erasure. IP rate 10/hour, global 1,000/hour | migrations 0003/0004, `moderation.ts`, `router.ts` |
| Moderation decisions (new) | Admin-only fixed action/category, time, score link, prior revision/visibility/name-override presence, open-report count. Acknowledgement flag on scores for derived rules-specific anomalies | No automatic audit expiry; erasure nulls the score link. No names, replacement text, reporter identifiers, IPs or tokens copied into the audit. Original/override names remain with the score until erasure. One shared operator credential, no new staff profiles | migration 0004, `moderation.ts`, `adminUi.ts` |
| Operator digest (implemented 2026-11-12, not deployed) | Daily cron sends the operator one email via Resend (HTTPS API) when the moderation queue is not empty: aggregate counts by report reason, integrity-flag count, expiring/expired report counts and the console URL. Recipient `privacy@davidandrea.ca` | No nickname, score ID, reporter/IP hash, token or replay leaves the Worker. `moderation_digests` (migration 0005) keeps that text and delivery status per day for 30 days. Resend's own retention of sent mail is unverified. Player data is not shared with Resend; it processes operator email only | `server/src/digest.ts`, `scheduled.ts`, migration 0005 |
| Network/request metadata | All API requests reach Cloudflare; headers include user agent, origin, URL/path, bearer token on submission, encoding/type. TLS and infrastructure necessarily process connection data. Leaderboard requests expose interest in an entry/page | Cloudflare-side retention/configuration unknown. Worker never reads `request.cf` country/location data; GET boards/details do not write application DB. Board/detail/admin responses use no-store; current clients also bypass HTTP caches. Previously cached five-second responses may outlive a rollout briefly; no explicit Cache API put | `src/ranked/api.ts`, `server/src/router.ts` |
| Application logs | Worker emits event names, run IDs, rejection codes, requested rules, URL path, exception strings, aggregate cleanup counts | No explicit IP, nickname, replay or token logging. Exceptions/paths can contain unexpected input; not a guarantee of zero personal data. Cloudflare observability/tails/log destinations need verification | `server/src/router.ts`, `runs.ts`, `worker.ts` |
| Local preferences | `asteroids.musicMuted`, `musicVolume`, `sfxVolume`, `musicTrack`, `inputMode`, `touchMovement` (legacy `touchSteering` read), `haptics` | LocalStorage under the app origin; no timed expiry or upload of preferences as such. Chosen control category/recorded movement still transmitted on ranked submission | `src/audio/audioConfig.ts`, `audioSettings.ts`, `src/input/inputMode.ts`, `movementMode.ts`, `src/haptics/hapticSettings.ts` |
Expand Down Expand Up @@ -43,7 +44,7 @@ Answer **Yes** to collection. Proposed types and purposes below cover this versi
| App activity / App interactions | Review, alongside Other actions | No tap/page analytics. Normal endpoint/request logs might expose interactions; confirm provider logging before deciding |
| Diagnostics | Provider verification required | No crash/diagnostic SDK in app; operational Worker errors/request logs may qualify depending on actual captured fields/use. Do not select Analytics just because operational metadata exists |
| Approximate location | No application geolocation; provider verification required | Worker does not infer location. If configured Cloudflare processing/logging uses IP-derived location on our behalf, disclose that use |
| Email address | No in-app field; reassess once support mailbox workflow is chosen | Voluntary external email contact is distinct from Android API collection; describe correspondence handling honestly |
| Email address | No in-app field. Public contact `privacy@davidandrea.ca` (confirmed 2026-11-12); reassess once the mailbox workflow is documented | Voluntary external email contact is distinct from Android API collection; describe correspondence handling honestly |
| Other UGC | Review only for residual content not already classified as Name | Nicknames already belong in Name; report reason is fixed selection, no free text |

No app collection found of photos, user audio, contacts, files/documents, health, finances, messages, installed apps, searches, browsing history or precise location. Audio assets are bundled music, not recordings of players.
Expand Down
64 changes: 63 additions & 1 deletion docs/play-release-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,68 @@

Prepared on `dev`, base HEAD `c1871a92c6f2a99bbac6f8dc8885691804826737`, plus the uncommitted privacy/release changes. No push, merge, deployment, production data mutation, key generation, signing or Play publication. Pre-existing Android Studio `.idea` changes and inaccessible tracked `tmp/` deletions were left alone. The Gradle settings typo seen initially was already corrected in the working tree before this task's Android edits.

## Release candidate: Hull & Havoc (2026-11-12)

Branch `release/hull-and-havoc-rc` (local only; nothing pushed, deployed, migrated or emailed). Mocked/loopback email only.

| Check | Result |
| --- | --- |
| Vitest (full) | **71 files / 1,705 tests passed** (incl. digest 25, delivery-test script 3, branding 3, privacy page 5, Android release guards) |
| Typecheck | frontend `tsc --noEmit` and server `tsc -p server/tsconfig.json`: pass |
| Production build | `npm run build`: pass; `dist/privacy/index.html` emitted; no Resend/digest strings in the client bundle |
| Android build guards | `node --test scripts/build-android.test.mjs`: 8/8 |
| Frozen rules | `rules-guard.mjs main`: 0 changes under `server/rules`; guard tests 4/4. No diff under `src/core`, `src/replay`, `src/game`, `src/scenes` vs `main` |
| Real Worker + D1 (workerd) | `server/scripts/worker-e2e.mjs`: **39/39**, incl. one digest for two same-day crons, key `hull-and-havoc-moderation-digest-YYYY-MM-DD` |
| D1 migration rehearsal | `test:release:migrations`: **43/43**, incl. additive 0005 after 0004 and the historical Worker on the 0005 schema |
| Runbook D1 blocks | [digest-activation-runbook.md](digest-activation-runbook.md) setup and steps 4-8 run verbatim against a local stand-in (only `--env production --remote` rewritten; account calls stubbed; invalid API token); all OK; step 4 correctly STOPs once 0005 is applied |
| Moderation dashboard (Chromium) | `test:moderation:admin`: **28/28** |
| Menus incl. privacy pages | `scripts/menu.mjs`: **127/127**; `HULL & HAVOC` title fits at every tested size |
| GitHub Pages subpath | `scripts/pages-check.mjs`: **35/35**, incl. `/asteroids-bootdev/privacy/` (200, heading, contact, favicon, no off-site requests, back link, no sideways scroll at 360 px) |
| Worker production dry-run | `wrangler deploy --env production --dry-run`: 151.57 KiB; bindings `DB`, `ALLOWED_ORIGINS`, `MODERATION_DIGEST_TO`, `MODERATION_DASHBOARD_URL`; no sender or key (digest stays disabled) |
| Android unsigned release | `bundleRelease assembleRelease lintRelease -PallowUnsignedRelease=true`: success. Inspector `-Unsigned`: PASS (no `.so`, no server verifier, package/SDK/debuggable/permissions), WARN draft privacy text (expected). `aapt2`: package `ca.davidandrea.spacearcade` 1.0 (1), label **Hull & Havoc**. APK `ED631C99…EF8F14`, AAB `87A2C243…EF272` |
| Sideload copy (local debug key) | `hull-and-havoc-1.0-sideload-debugkey.apk`, `08348538…C35E24`, v2/v3 verified, 16 KB aligned. Not uploadable |

**Not run:** gameplay browser suites (`ranked-ui`, `ranked`, `touch`, `keyboard`, `combat`, `coop`, `gamepad`, `replay:browser`), because no gameplay code changed. No signed build, no device install, no real Resend delivery, no production read or write.

### Google Play: focused check of this candidate

Established by inspection or test:
- Package `ca.davidandrea.spacearcade`, version 1.0 (1), rules 1.2.0 frozen; launcher label Hull & Havoc; permissions INTERNET and VIBRATE only (the digest added none).
- Privacy URL `https://djblackett.github.io/asteroids-bootdev/privacy/` is used consistently in the page, the offline screens and the Play guide. It is **not live** until a release to `main`.
- Draft gate: the policy was approved 2026-11-12 and the offline screen no longer carries `DRAFT PRIVACY POLICY - REVIEW PENDING`. The signed-mode inspector still lists both markers and refuses any build that reintroduces one. Upload-key procedure (`ASTEROIDS_UPLOAD_*`, signed-mode inspector) unchanged.
- Reporting, blocking and the `/admin` workflow pass their suites. Gameplay requests do not depend on email.

Unresolved interpretation (not established; see [UGC readiness](leaderboard-moderation.md#google-play-ugc-readiness-rechecked-2026-11-12)):
- **Rules acceptance:** submit-as-acceptance with the rules one tap away. Play asks users to accept terms before creating UGC; whether an implicit "by submitting" suffices is a reviewer judgment. The conservative option is an explicit "Accept rules & submit" label (client-only change, not made here).
- **Blocking without accounts:** name-based device-local blocking; names are shared and changeable.
- **Ongoing moderation:** depends on activating the digest and on your actual response time, not on code.
- **Data safety:** the inventory supports the rows (name, app activity, IP-derived identifier, deletion by email). Internal-only testing is exempt; answers must be final before closed/open/production tracks.

## Device-test preparation — 2026-11-12

Branch `release/android-device-prep`; packaged sources unchanged from `f1a031a` (`dev` after a no-file-change merge of `main`). No push, deploy, production write, key generation or Play upload. Production access was SELECT-only D1 (`rows_written: 0`) plus Cloudflare analytics and deployment-status reads.

| Check (from phaser-asteroids, PowerShell, JDK 21.0.5) | Result |
| --- | --- |
| `npx vitest run --maxWorkers=4` | **Passed:** 67 files / 1,669 tests (1,667 + 2 new inspector/draft-marker tests) |
| `npm run typecheck --prefix server`, `npm run test:android-build`, rules-guard/production-health tests, `node scripts/rules-guard.mjs main` | **Passed:** typecheck; 8/8; 19/19; 0 released-rules changes |
| `npm run android:sync` | **Passed:** 1.0 (1) plays frozen rules 1.2.0/schema 1; production HTTPS origin baked in |
| `gradlew :app:bundleRelease :app:assembleRelease :app:lintRelease -PallowUnsignedRelease=true` | **Passed:** BUILD SUCCESSFUL; lint 0 errors / 14 warnings (same categories as before) |
| `inspect-android-release.ps1 -Unsigned` | **Passed**, with WARN for the bundled draft privacy text. AAB `8CC0A4F8…EFB2`, APK `284F84C1…D01C`: byte-identical to 2026-11-04 |
| Inspector refusals (new) | **Verified:** signed mode on the debug-key APK + unsigned AAB lists debug key, unsigned AAB and 4 draft-marker findings; debug APK refused as debuggable; missing `app-release.apk` refused |
| Sideload APK (release APK re-signed with local debug key) | **Built:** `apk/sideload/orbital-impact-1.0-sideload-debugkey.apk`, SHA-256 `11FEB5AB…E592`, v2/v3 verified, 16 KB zip-aligned. Not uploadable |
| `gradlew :app:assembleDebug` | **Passed:** `apk/debug/app-debug.apk` `E49AC998…6093` (diagnostic only) |
| Production cron (read-only) | **Verified indirectly:** daily 07:00 UTC invocation 8/8 days, 0 errors since deploy; prune effects visible in D1. See [current status](release-preflight.md#current-status-2026-11-12) |
| ADB devices | **Not stable:** Samsung SM-S901E appeared once via a local bridge, then `offline`. Nothing installed |
| Browser suites (ranked UI, menu, worker-e2e, moderation admin, migrations) | **Not re-run:** no change to their inputs since the 2026-11-04 passes at `549729f` |
| Physical device, 16 KB runtime, signed AAB, Play-delivered install | **Not run:** require a device, an upload key and Console access |

Tooling note: from the Bash tool, whose working directory had a lowercase drive letter (`c:\`), every Vitest file failed with `Cannot read properties of undefined (reading 'config')`. Running from a `C:\` working directory passed. This was an environment artifact, not a test failure.

## Backend release — 2026-11-04 (Stage 2)

The moderation Worker is live: merge `8569834` (tree identical to `549729f`), Actions run 41887905781, Cloudflare version `c2aef78f-ec27-4118-bd2c-a13f59b7313b` at 100% on D1 0001-0004. Pre-deploy local results at `549729f` matched the table below (1,667 unit, 40/40 migrations/historical client, 33/33 worker-e2e, 28/28 admin, 99/99 ranked UI, 127/127 menu). Live public (31/31) and admin read-only (19/19) checks passed. Details and remaining gates: [Stage 2 record](release-preflight.md#stage-2-production-worker-deployment-2026-11-04). Android old-device testing is still outstanding (0 ADB devices).

## Production preparation verification — 2026-11-04

Audited `dev` at `f540cafb2da864d3d3da52619910f062acfff9c3`. The moderation implementation is committed (`91c349c`, then `f540caf`); this pass adds local tests/docs. No commit/push/merge, production backup/export/restore/migration/deployment, credentials changes, score writes or Play upload. Five existing root `tmp/` deletions were preserved. See the [current release preflight](release-preflight.md) for readiness, compatibility findings, configuration uncertainties and exact approval-only production commands. Earlier sections below are historical snapshots.
Expand Down Expand Up @@ -100,6 +162,6 @@ Toolchain: Node 26.13.0, npm 11.20.0, JDK 21.0.5, Gradle 8.14.3, AGP 8.13.0. Ins
1. Operator confirmed as David Andrea on 2026-11-04. Public privacy/security/removal/moderation mailbox intentionally deferred at David's request; return to this before distribution. Choose the address and mailbox handling/retention, final game name and effective date. Replace bundled contact placeholders and approve the public policy before distribution. Hosting proposal is in [the draft](privacy-policy-draft.md); nothing is hosted by this task.
2. Verify Cloudflare logging, request fields/location processing, security logs, backup/recovery/export retention, processing role and regions. Finalize [Data safety answers](play-data-inventory.md) using those facts. Accepted/hidden scores currently have no automatic expiry; do not promise otherwise.
3. Assign moderation coverage and review [nickname-blocking limitations](leaderboard-moderation.md) against Play's user-blocking requirement. No account or stable user identity was added.
4. Separately authorize/report the Worker migration and deployment before enabling reports for testers; implement the removal mailbox process. The new erasure route exists locally and is tested, but is not live in production.
4. ~~Separately authorize/report the Worker migration and deployment before enabling reports for testers.~~ **Done 2026-11-04** (Stage 1/2): reporting, moderation and the erasure route are live in production. Still open: implement the removal mailbox process (depends on item 1).
5. Human creates/protects the upload key or supplies an existing one; build and inspect signed artifacts and verify certificate fingerprints. Confirm Play has not already consumed version code 1; increment and append the release registry record if needed.
6. Test a Play-delivered build on a 16 KB emulator/device and Samsung/representative devices, including tablet/window behavior and backup/device transfer. No `.so` files makes ELF alignment inapplicable to the bundled app; it does not replace runtime testing. Complete the [internal-testing procedure](../phaser-asteroids/docs/google-play-release.md), target ages/content rating and branding pass before promotion.
Loading
Loading