feat(pam): capture and expose a player timezone from the browser

[mp-blurify]

Summary

Captures the IANA timezone the browser reports and persists it on the player row, refreshing
it on every session-establishing route, and exposes it on the shared player read model so
consumers can render a stored UTC timestamp on the player's own clock. BF-532

Why

Nothing in the platform stored a player timezone, so a consumer's backoffice could show a chat
message's UTC timestamp but not what time it was for the player who sent it. The two columns
that look like they could answer are not honest sources: country is self-declared at
registration and large countries span several zones, and registrationIp is VPN-defeated and
less accurate than the device itself. The browser already resolves the right answer via
Intl.DateTimeFormat().resolvedOptions().timeZone, so the platform takes that and stores it.

Capture is deliberately spread across six routes rather than one. Four routes establish a
session, not one — login, verify2fa, phoneLoginVerify and verifyEmail — so extending
LoginInputSchema alone would have covered a quarter of the cases. verifyEmail is easy to
miss because it looks like an email chore, but it is where better-auth's
autoSignInAfterVerification mints a new player's first session, and it emits
identity.user.login like the rest. register is the fifth: it mints no session, but the
browser is present at sign-up, so the zone is captured then rather than waiting for a first
login that may be days away — and sign-up and verification can happen on different devices, so
neither one covers the other. profile.update is the sixth and the one that makes the feature
useful on day one: a remembered session skips login for weeks, and no existing player
re-authenticates just because a column appeared, so a login-only capture would leave most of the
book reading - for a long time.

timezoneUpdatedAt is stamped on every capture the tz database accepts, including one that
repeats the zone already stored, so it reads as last confirmed by a device. The alternative —
moving it only on a change — makes a player signing in daily from one zone for months
indistinguishable from one not seen since, which is precisely the distinction the read model
ships the timestamp to make.

The value is display metadata and is treated as such throughout. It is device-reported and
trivially spoofable, so it gates nothing, is never evidence of where a player is, and stays out
of responsible-gambling windows and audit records, which remain timezone-free and UTC on purpose.
An unrecognised zone is a silent no-op, never a request failure — a cosmetic column must not cost
a player their session. That includes the empty string a client falls back to when Intl gives
it nothing: the contract accepts it and the write drops it, rather than 400ing the login that
carried it.

Alternatives considered

• Deriving the zone from country. Rejected: self-declared, and a single country routinely
  spans several zones, so the answer is wrong for a large share of players by construction.
• IP geolocation. Rejected: costs a provider, is defeated by any VPN, and is still less
  accurate than the device that already knows.
• Attaching the zone to every request. Rejected: spoofable per request, and it invites using
  a request-scoped value to drive a stored decision.
• Riding PLAYER_ACTIVITY_TRACKER.touchLastSeen, which already fires on every authenticated
  request and is a ready-made seam. Rejected because using it would require the zone on every
  request — exactly the thing ruled out above.
• Storing the raw client string. Rejected: resolveTimezone canonicalises against the
  runtime's own tz database instead, so the column holds a zone name rather than arbitrary client
  text, and the aliases and casings different browsers report (US/Pacific, europe/warsaw)
  land on one stored spelling instead of flip-flopping between them.
• Moving timezoneUpdatedAt only when the zone changes. Rejected: it saves one write on a
  row an authenticated request touches anyway, and costs the column its only useful reading —
  see above.
• Omitting timezoneUpdatedAt from the read model. Rejected: the zone is a point-in-time,
  device-reported guess, so a player who moved — or whose last session was months ago — renders a
  plausible but wrong local time with nothing to signal it. Shipping the value without its
  staleness marker hands the reader confident-looking wrong data.

Risks

• Port change. PlayerProvisioning gains a required recordTimezone. An overlay that
  rebinds PLAYER_PROVISIONING with its own implementation will fail to compile until it adds
  the method. Deliberate over an optional member: a silently-missing implementation would look
  like a working capture that never writes.
• Migration. Two nullable ADD COLUMNs with no backfill and no index — additive, no rewrite,
  safe to roll back by ignoring the columns. An uncaptured player reads null rather than a
  guess, so the read model gains a value consumers must handle as absent.
• Silent by design. A zone the tz database does not recognise is dropped with no feedback to
  the caller, and a capture failure is logged and swallowed. That is the intended trade — it
  guarantees the feature can never fail an auth flow — but it means a client sending a
  consistently bad value sees success and stores nothing. The warn-level log is the only signal.
  The contract keeps one hard bound, a 64-character ceiling: past twice the longest real zone
  name the value is not a zone the platform failed to recognise, it is arbitrary client text.
• Deferred work. The platform half is inert until consumers send the zone: no client in this
  repo populates it, so the columns stay null on an upgrade alone. The consumer-side change
  (sending the browser zone on login and on the post-auth profile write, and rendering the
  column) is out of scope here and lands separately after a version bump.
• Scope discipline. This must not become an input to responsible-gambling evaluation or any
  session or limit window; making RG timezone-aware is a licence problem, not a feature. Nothing
  under compliance/ was touched.

Review follow-ups

Three findings from review, all fixed in fix(pam): close the timezone capture gaps found in review:

• verifyEmail carried no timezone and never captured, despite minting the first session.
  It now does, after the account gate and before the 2FA branch.
• TimezoneSchema lost its .min(1): an empty string was failing contract validation, so a
  client-side Intl fallback could 400 a login. It now reaches the same silent no-op as any
  other unrecognised zone.
• timezoneUpdatedAt refreshes on every accepted capture rather than only on a change, and the
  column is documented as last confirmed in the schema, the read model and the service.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SyLqsaeoprPoPXehsU5BbR

[zaxovaiko]

What is the purpose of the test? xD

[zaxovaiko]

Could you please remove all unnecessary comments from the code?

[klaudia-blazyczek-blurify]

apart from Volods comments lgtm

[zaxovaiko]

verify is red on notifications.router.int.test.ts (the stream test timing out), which looks unrelated to this branch. Worth a re-run anyway - check:drift only runs after the tests in pnpm verify, so it never actually executed here.

[zaxovaiko]

Hm, this one passes with the old behaviour too - if the write gets skipped then second just equals first and >= is still true, so the test can't fail on the thing it's here to catch. Let's use toBeGreaterThan. Same in __tests__/player-timezone.e2e.test.ts.

[zaxovaiko]

This is a copy of captureTimezone from service/identity.service.ts - same guard, same try/catch, same log string. Can we please extract it once and call it from both? Two copies will drift the moment one of them changes.

[zaxovaiko]

Let's use TimezoneSchema.nullable() here - it's already imported in this file for UpdatePlayerProfileInputSchema, so the read model and the input can share the one source instead of a bare z.string().

[zaxovaiko]

I was wondering about the asymmetry here - '' now goes through to the silent no-op, but 65 characters still 400s the login. resolveTimezone rejects anything the tz database doesn't know anyway, so do we need .max() at all? Dropping it would make the "a cosmetic column never costs a session" promise unconditional.

[zaxovaiko]

This is the spot I meant about the comments - most of the block is the PR description restated. Let's keep "display metadata, never gates anything" and the reason for the offset guard in resolveTimezone, and drop the rest. TimezoneSchema in schemas/common.ts is the same.