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
Opening and closing
Section titled “Opening and closing”- Flag. With
petition_pcoff,apps/web/src/proxy.tsreturns a real HTTP 404 for every petition path, before anything renders. That includes the OG and story images and the legacy/petitionpcpaths.signandverifyTokenthrowNOT_FOUND, and the sitemap leaves the page out.getStatsand 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#tokenfragment survives the redirect.
Signing
Section titled “Signing”petition.sign in createOrResendSignature:
- Bot traps. A filled
websitehoneypot, or a form submitted under 2 s after render, returnsoksilently 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 inweb.rate_limitotherwise. The keys are HMACs, never raw addresses. - Consent integrity. The form submits the
privacyNoticeVersionIdit was rendered with. If a newer notice was published since, the call fails withNotice 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.
Confirming
Section titled “Confirming”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.
Share images and the forgery fix
Section titled “Share images and the forgery fix”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.
Public stats
Section titled “Public stats”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: Content → Petition
Section titled “Admin: Content → Petition”/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).
Privacy notice v1
Section titled “Privacy notice v1”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.
Retention
Section titled “Retention”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.
Meta server-side conversions
Section titled “Meta server-side conversions”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.
