Turnstile migration (#663)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: fangge518 <fangge518@gmail.com>

Author: 3 people

.agents/AGENTS.md

@@ -114,7 +114,7 @@ Agents should read the relevant guide(s) before making changes:
 - [`learn-map-lifecycle`](./skills/project/learn-map-lifecycle/SKILL.md) - map data lifecycle: imports, shatter setup, edges, graph linkage
 - [`learn-pipelines`](./skills/project/learn-pipelines/SKILL.md) - tiles/tabular/transforms pipeline contracts and toolchain requirements
 - [`learn-cms-moderation`](./skills/project/learn-cms-moderation/SKILL.md) - CMS editing/review and moderation workflows
-- [`learn-auth-share`](./skills/project/learn-auth-share/SKILL.md) - Auth0 scopes, recaptcha, and share/edit token security
+- [`learn-auth-share`](./skills/project/learn-auth-share/SKILL.md) - Auth0 scopes, Turnstile captcha, and share/edit token security
 
 ### Guide Selection Rules
 

.agents/ARCHITECTURE.md

@@ -128,7 +128,7 @@ IndexedDB serves as offline cache and conflict resolution source. Debounced writ
 - **Bulk assignments**: `PUT /api/assignments` uses PostgreSQL COPY for performance with optimistic concurrency
 - **Shatter operations**: `PATCH /api/assignments/{doc_id}/shatter` handles parent → child decomposition
 - **Contiguity**: Graph-based checking via NetworkX
-- **Auth**: Auth0 JWT with scopes (default/editor/admin), reCAPTCHA for public forms
+- **Auth**: Auth0 JWT with scopes (default/editor/admin), Cloudflare Turnstile for public forms
 
 ### Database Design
 

.agents/skills/project/learn-auth-share/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: learn-auth-share
-description: Auth0 scopes, recaptcha verification, and share/edit token security patterns
+description: Auth0 scopes, Turnstile captcha verification, and share/edit token security patterns
 user-invocable: false
 ---
 
 # Auth & Share Security
 
-Authentication/authorization and share-security behavior across Auth0 scopes, recaptcha verification, and map share/edit-access tokens.
+Authentication/authorization and share-security behavior across Auth0 scopes, Turnstile captcha verification, and map share/edit-access tokens.
 
 ## When To Use
 - You are changing protected endpoints, scopes, or role behavior.
@@ -26,7 +26,7 @@ Authentication/authorization and share-security behavior across Auth0 scopes, re
 ## Hard Invariants
 - Protected backend routes must enforce required scopes via `auth.verify`.
 - Auth0 token validation must preserve audience/issuer/algorithm constraints.
-- Recaptcha-gated flows must verify token server-side.
+- Captcha-gated flows must verify token server-side.
 - Share-token payload and password behavior must remain compatible with frontend share/edit flows.
 - Public document access must not expose private document identifiers.
 
@@ -38,14 +38,14 @@ Authentication/authorization and share-security behavior across Auth0 scopes, re
 
 ## Anti-Patterns
 - Broadening scopes or bypassing route security checks for convenience.
-- Performing recaptcha checks only in frontend.
+- Performing captcha checks only in frontend.
 - Logging sensitive token/password data.
 - Returning internal IDs/secrets in public route responses.
 
 ## Change Checklist
 1. Verify scope enforcement on all touched protected routes.
 2. Verify token verification config (audience/issuer/algorithms) is unchanged or intentionally updated.
-3. Verify recaptcha validation still runs for relevant form endpoints.
+3. Verify captcha validation still runs for relevant form endpoints.
 4. Verify share/password flow works for read/edit transitions.
 5. Verify no sensitive data is exposed in logs/responses.
 
@@ -57,4 +57,4 @@ Authentication/authorization and share-security behavior across Auth0 scopes, re
 - 401/403 regressions from missing scopes in frontend-acquired tokens.
 - Broken admin pages from session/token wiring drift.
 - Password-protected map edit failures due to token/payload mismatch.
-- False recaptcha failures from env/config mistakes.
+- False captcha failures from env/config mistakes.

.github/workflows/deploy-app.yml

@@ -54,8 +54,8 @@ jobs:
         working-directory: app
         run: |
           cat <<'EOF' > .env.production
-          NEXT_PUBLIC_RECAPTCHA_SITE_KEY=${{ secrets.RECAPTCHA_SITE_KEY }}
-          NEXT_PUBLIC_RECAPTCHA_V3_SITE_KEY=${{ secrets.RECAPTCHA_V3_SITE_KEY }}
+          NEXT_PUBLIC_TURNSTILE_SITE_KEY=${{ secrets.TURNSTILE_SITE_KEY }}
+          NEXT_PUBLIC_TURNSTILE_SESSION_SITE_KEY=${{ secrets.TURNSTILE_SESSION_SITE_KEY }}
           NEXT_PUBLIC_MAPTILER_API_KEY=${{ secrets.NEXT_PUBLIC_MAPTILER_API_KEY }}
           NEXT_PUBLIC_S3_BUCKET_URL=https://tilesets1.cdn.districtr.org
           NEXT_PUBLIC_S3_BUCKET_URL_MIRROR1=https://tilesets2.cdn.districtr.org

.github/workflows/fly-deploy-api.yml

@@ -23,6 +23,27 @@ jobs:
             echo "app_name=districtr-v2-api" >> $GITHUB_OUTPUT
           fi
       - uses: superfly/flyctl-actions/setup-flyctl@1.5
+      # Turnstile cutover: the backend no longer reads RECAPTCHA_*, so stage
+      # the renamed secrets from GH secrets and drop the old ones; --stage
+      # means both land atomically with the deploy below. No-op once the
+      # cutover is done.
+      - name: Stage Turnstile secrets
+        env:
+          FLY_API_TOKEN: ${{ github.ref_name == 'dev' && secrets.FLY_API_DEV_TOKEN || secrets.FLY_API_TOKEN }}
+          APP: ${{ steps.deploy-env.outputs.app_name }}
+          TURNSTILE_SECRET_KEY: ${{ secrets.TURNSTILE_SECRET_KEY }}
+          TURNSTILE_SESSION_SECRET_KEY: ${{ secrets.TURNSTILE_SESSION_SECRET_KEY }}
+        run: |
+          set -euo pipefail
+          args=()
+          if [ -n "${TURNSTILE_SECRET_KEY:-}" ];         then args+=( TURNSTILE_SECRET_KEY="$TURNSTILE_SECRET_KEY" ); fi
+          if [ -n "${TURNSTILE_SESSION_SECRET_KEY:-}" ]; then args+=( TURNSTILE_SESSION_SECRET_KEY="$TURNSTILE_SESSION_SECRET_KEY" ); fi
+          if [ "${#args[@]}" -gt 0 ]; then
+            flyctl secrets set --stage -a "$APP" "${args[@]}"
+          else
+            echo "::warning::TURNSTILE_* GitHub secrets are unset; deploying without captcha secrets"
+          fi
+          flyctl secrets unset --stage -a "$APP" RECAPTCHA_SECRET_KEY RECAPTCHA_V3_SECRET_KEY || true
       - name: Deploy (dev)
         if: github.ref_name == 'dev'
         run: flyctl deploy --remote-only --app ${{ steps.deploy-env.outputs.app_name }}

.github/workflows/fly-deploy-app.yml

@@ -27,7 +27,7 @@ jobs:
       - name: Write .env.production
         run: |
           cat <<EOF > .env.production
-            NEXT_PUBLIC_RECAPTCHA_SITE_KEY=${{ secrets.RECAPTCHA_SITE_KEY }}
+            NEXT_PUBLIC_TURNSTILE_SITE_KEY=${{ secrets.TURNSTILE_SITE_KEY }}
             NEXT_PUBLIC_MAPTILER_API_KEY=${{ secrets.NEXT_PUBLIC_MAPTILER_API_KEY }}
             NEXT_PUBLIC_S3_BUCKET_URL=https://tilesets1.cdn.districtr.org
             NEXT_PUBLIC_S3_BUCKET_URL_MIRROR1=https://tilesets2.cdn.districtr.org

.github/workflows/fly-preview.yml

@@ -15,9 +15,9 @@ name: Fly Preview
 # Required repo VARS:    FLY_ORG, DEV_PG_APP, R2_BUCKET_NAME
 # Required repo SECRETS: FLY_PREVIEW_API_TOKEN (org-scoped: `fly tokens create org`),
 #   AUTH0_SECRET, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_DOMAIN, AUTH0_API_AUDIENCE,
-#   RECAPTCHA_SITE_KEY, NEXT_PUBLIC_MAPTILER_API_KEY, SENTRY_AUTH_TOKEN (optional);
+#   TURNSTILE_SITE_KEY, NEXT_PUBLIC_MAPTILER_API_KEY, SENTRY_AUTH_TOKEN (optional);
 #   fullstack also needs: PREVIEW_DB_USER/PASSWORD/NAME, BE_SECRET_KEY, AUTH0_ISSUER,
-#   AUTH0_ALGORITHMS, and optionally RECAPTCHA_SECRET_KEY, AWS_ACCESS_KEY_ID/SECRET, R2_ACCOUNT_ID.
+#   AUTH0_ALGORITHMS, and optionally TURNSTILE_SECRET_KEY, AWS_ACCESS_KEY_ID/SECRET, R2_ACCOUNT_ID.
 # One-time: create the two labels, and set BACKEND_CORS_ORIGIN_REGEX on the dev backend
 #   so FE-only previews are allowed cross-origin (see PR description / config.py).
 
@@ -114,7 +114,7 @@ jobs:
           AUTH0_API_AUDIENCE: ${{ secrets.AUTH0_API_AUDIENCE }}
           AUTH0_ISSUER: ${{ secrets.AUTH0_ISSUER }}
           AUTH0_ALGORITHMS: RS256
-          RECAPTCHA_SECRET_KEY: ${{ secrets.RECAPTCHA_SECRET_KEY }}
+          TURNSTILE_SECRET_KEY: ${{ secrets.TURNSTILE_SECRET_KEY }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
@@ -175,7 +175,7 @@ jobs:
             AUTH0_ALGORITHMS="$AUTH0_ALGORITHMS"
           )
           # Optional secrets — only set when provided.
-          if [ -n "${RECAPTCHA_SECRET_KEY:-}" ];   then args+=( RECAPTCHA_SECRET_KEY="$RECAPTCHA_SECRET_KEY" ); fi
+          if [ -n "${TURNSTILE_SECRET_KEY:-}" ];   then args+=( TURNSTILE_SECRET_KEY="$TURNSTILE_SECRET_KEY" ); fi
           if [ -n "${AWS_ACCESS_KEY_ID:-}" ];      then args+=( AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" ); fi
           if [ -n "${AWS_SECRET_ACCESS_KEY:-}" ];  then args+=( AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" ); fi
           if [ -n "${R2_ACCOUNT_ID:-}" ];          then args+=( ACCOUNT_ID="$R2_ACCOUNT_ID" ); fi
@@ -212,7 +212,7 @@ jobs:
           FE_URL: ${{ steps.setup.outputs.fe_url }}
           API_URL: ${{ steps.setup.outputs.api_url }}
           SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
-          RECAPTCHA_SITE_KEY: ${{ secrets.RECAPTCHA_SITE_KEY }}
+          TURNSTILE_SITE_KEY: ${{ secrets.TURNSTILE_SITE_KEY }}
           NEXT_PUBLIC_MAPTILER_API_KEY: ${{ secrets.NEXT_PUBLIC_MAPTILER_API_KEY }}
           AUTH0_SECRET: ${{ secrets.AUTH0_SECRET }}
           AUTH0_CLIENT_ID: ${{ secrets.AUTH0_CLIENT_ID }}
@@ -226,7 +226,7 @@ jobs:
 
           # Build-time public env (baked into the image; Dockerfile COPYs this in).
           cat > app/.env.production <<EOF
-          NEXT_PUBLIC_RECAPTCHA_SITE_KEY=${RECAPTCHA_SITE_KEY}
+          NEXT_PUBLIC_TURNSTILE_SITE_KEY=${TURNSTILE_SITE_KEY}
           NEXT_PUBLIC_MAPTILER_API_KEY=${NEXT_PUBLIC_MAPTILER_API_KEY}
           NEXT_PUBLIC_S3_BUCKET_URL=https://tilesets1.cdn.districtr.org
           NEXT_PUBLIC_S3_BUCKET_URL_MIRROR1=https://tilesets2.cdn.districtr.org

app/.env.docker.example

@@ -17,7 +17,11 @@ AUTH0_SECRET="fill-me" # Added by `npx auth`. Read more: https://cli.authjs.dev
 # Feedback form
 NEXT_PUBLIC_FEEDBACK_FORM="fill-me-optionally"
 
-NEXT_PUBLIC_RECAPTCHA_SITE_KEY="fill-me-optionally"
+# Cloudflare Turnstile. The values below are Cloudflare's public dummy keys
+# (always pass); swap in real widget site keys to test actual challenges, or
+# use 3x00000000000000000000FF to force the interactive session fallback.
+NEXT_PUBLIC_TURNSTILE_SITE_KEY="1x00000000000000000000AA"
+NEXT_PUBLIC_TURNSTILE_SESSION_SITE_KEY="1x00000000000000000000AA"
 
 # MapTiler API key for Streets/Satellite basemaps and geocoding search (optional)
 NEXT_PUBLIC_MAPTILER_API_KEY="fill-me-optionally"

app/Dockerfile

@@ -16,7 +16,7 @@ ENV NODE_ENV="production"
 FROM base as build
 ARG NEXT_PUBLIC_API_URL
 ARG NEXT_PUBLIC_S3_BUCKET_URL
-ARG NEXT_PUBLIC_RECAPTCHA_V3_SITE_KEY
+ARG NEXT_PUBLIC_TURNSTILE_SESSION_SITE_KEY
 
 # Install packages needed to build node modules
 RUN apt-get update -qq && \
@@ -32,7 +32,7 @@ RUN bun install --include=dev
 RUN echo NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL && \
     echo "NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL" > .env.production && \
     echo "NEXT_PUBLIC_S3_BUCKET_URL=$NEXT_PUBLIC_S3_BUCKET_URL" >> .env.production && \
-    echo "NEXT_PUBLIC_RECAPTCHA_V3_SITE_KEY=$NEXT_PUBLIC_RECAPTCHA_V3_SITE_KEY" >> .env.production
+    echo "NEXT_PUBLIC_TURNSTILE_SESSION_SITE_KEY=$NEXT_PUBLIC_TURNSTILE_SESSION_SITE_KEY" >> .env.production
 
 # Copy application code
 COPY --link . .