Skip to content

Petition flow

/petition/pokemon-center collects public signatures asking for a Pokémon Center in Malaysia. A signature counts only after the signer confirms it from their email. People sign anonymously, and the page shows totals per Malaysian state. The feature flag petition_pc gates the whole thing.

Primary code: packages/core/src/server/petition.ts (sign, verify, stats, moderation), packages/core/src/server/trpc/routers/petition.ts, packages/core/src/lib/petition-jwt.ts, and the pages under apps/web/src/app/[locale]/(main)/petition/pokemon-center/.

sequenceDiagram
    participant S as Signer
    participant W as petition.sign
    participant E as Email
    participant V as petition.verifyToken
    S->>W: name, email, state, age, consent, notice version
    W->>W: honeypot / rate limits / notice version check
    W->>W: insert (or resend) pending row, store token HASH
    W->>E: verify link (#token=...)
    S->>V: opens link
    V->>V: lock row, per-state advisory lock, mark verified, rank
    V->>S: signed receipt {state, rank}
    S->>S: story PNG from the receipt
  • Flag. With petition_pc off, apps/web/src/proxy.ts returns a real HTTP 404 for every petition path, before anything renders. That includes the OG and story images and the legacy /petitionpc paths. sign and verifyToken throw NOT_FOUND, and the sitemap leaves the page out. getStats and the approved comment wall still answer. Turning the flag off keeps the signatures already collected.
  • Dates. INTAKE_CLOSES_AT (2026-11-10 23:59 MYT) ends signing. VERIFY_CLOSES_AT (2026-11-17 23:59 MYT) ends confirmations.
  • Legacy URL. Once the flag is on, /petitionpc/* redirects (308) to /petition/pokemon-center/*. That covers QR codes printed before the move, and the #token fragment survives the redirect.

petition.sign in createOrResendSignature:

  • Bot traps. A filled website honeypot, or a form submitted under 2 s after render, returns ok silently and stores nothing.
  • Rate limits (packages/core/src/server/petition-rate-limit.ts): 5 per email and 120 per IP per minute. The IP limit is high on purpose, because venue wifi and mobile carrier NAT put many real signers behind one IP. On top, a site-wide cap allows 2,000 verify emails an hour, and Sentry gets a warning the first time the cap trips in a window. Counters sit in Redis on the API and in web.rate_limit otherwise. The keys are HMACs, never raw addresses.
  • Consent integrity. The form submits the privacyNoticeVersionId it was rendered with. If a newer notice was published since, the call fails with Notice updated, so consent is never recorded against a notice the signer did not see.
  • One row per email. A second submission from a pending email resends the link. It replaces the earlier declarations, because a resend confirms this submission and not an earlier unconfirmed one. Resends are capped at 5, at least 60 s apart, under a row lock. Verified rows are never touched.
  • Token at rest. The verify JWT carries only the signature id and a nonce, never an email. The database stores only its SHA-256 hash.
  • Email failure. The send is wrapped in captureEmailFailure. If it fails, the row goes back to the link and choices it had before, but only if no newer resend or verification has happened since.

Signers under 18 sign with a guardian (minor_with_guardian). The newsletter opt-in syncs to Autosend only for adults.

verifySignature locks the row and then takes pg_advisory_xact_lock(hashtext('petition-rank:<state>')). It marks the row verified, but only if the stored token hash still matches. It then counts verified rows for that state, and that count becomes the signer’s rank, so two confirmations at the same moment can never get the same number. A confirmation clears any earlier withdrawal tombstone (petition_suppressions) for that email. Only the mailbox owner can do that, never an unauthenticated sign.

The keepsake story image (/petition/pokemon-center/story?r=…&lang=…) takes rank and state only from a signed receipt JWT (audience petition-receipt, 30-day expiry). A verify token or a newsletter token cannot stand in for one. Before the fix, the URL itself said what to print, so anyone could forge a “signer #1” image. The route rejects any other query parameter, contains no signer identity, and is cached publicly for a day.

getStats groups confirmed signatures by state. Any state with 1–9 signatures shows as “under 10”, never as an exact count. The petition page caches its data for 30 s, because the web app has no Redis.

/admin/petition (needs manage_news): comment moderation in Pending, Approved and Hidden tabs. Approve or hide is audited (resource petition_signature). A comment reaches the public wall only once it is approved, and only if the signer ticked public consent. The page also shows how many newsletter syncs failed, with a Retry sync button (audited).

The legal page petitionpc-privacy-notice is defined in apps/web/src/lib/legal-content.ts. It is published as v1 and served at /legal/petitionpc-privacy-notice. It names the processors (Neon in Singapore; Hetzner in Singapore, plus Germany for error logs; Cloudflare; Autosend), the s.129 basis, and [email protected] as the DPO contact. Sign fails with Petition notice not published until a version exists in that environment.

Publish or update it from the code copy with apps/web/scripts/republish-legal-pages.ts --slug petitionpc-privacy-notice. Add --create for the first publish to an environment and --reason "..." for the audit row. Without --commit the script is a dry run.

POST /api/cron/petition-retention (packages/core/src/http/cron/petition-retention.ts) keeps the deletion promises the notice makes. It runs daily at 18:30 UTC (02:30 MYT), it is idempotent, and it authenticates with CRON_SECRET.

When What happens
14 days after signing Unconfirmed (pending) signatures are deleted
30 days after signing IP hash and user agent are cleared
90 days after the report (PETITION_REPORT_SENT_AT, 2026-11-20) Final totals are saved to site_settings petition_pc.final_totals, then every signature and withdrawal marker is deleted

If the report goes out late, move PETITION_REPORT_SENT_AT. Otherwise the purge runs early, and the data cannot be recovered after it.

petition_pc_meta_capi (Campaigns → Petition: Meta CAPI conversions) is off by default in every environment. When enabled, adult signatures send:

  • Lead after a brand-new pending signature commits and its verification email sends successfully; event ID pc_lead_<signature id>.
  • CompleteRegistration after a pending signature commits as verified; event ID pc_verified_<signature id>. Repeated verification sends nothing.

Resends, bot traps, cooldowns, send caps, already-verified submissions, failed email sends, and minor/guardian signatures do not send Lead. Minor/guardian verification does not send CompleteRegistration either. Flag or CAPI failures never fail signing or verification.

Matching data is limited to that request’s _fbp / _fbc cookies, resolved client IP and user agent; the verify request may come from a different device. This matching context is not persisted. No email, name, phone, state, comment, favourite Pokémon, guardian details or verify token is sent. Custom data is content_name: "petition-pc" and content_category: "petition".

Both events use action_source: "website". Source URLs are fixed to https://tcgkl.com/petition/pokemon-center (Lead) and https://tcgkl.com/petition/pokemon-center/verify (CompleteRegistration), never request URLs, query strings or token fragments. The existing Meta CAPI credentials and non-production test-event safeguards still apply; no browser pixel or GTM code is added.