Make session-expiry checks tolerant of client clock skew (derive a server-time offset)

[valpet]

Problem

When a user's device clock is wrong, auth-js becomes unusable, and there's no
way for the client to compensate.

Every session-expiry decision compares the server-issued expires_at against the
local device clock (Date.now()). If the device clock runs ahead by more than
roughly the token lifetime, each freshly-issued access token is judged "already
expired," so the client refreshes immediately, gets another token it also thinks
is expired, and loops — until the per-IP refresh rate limit returns 429 and the
session wedges. To the user it just looks like "I can't log in," with no hint that
their clock is the cause.

We hit this in production: one user with a misconfigured OS clock generated
288 refresh tokens across 13 sessions in ~36 minutes, reproduced in two
browsers on the same machine. Resyncing their OS clock fixed it.

The User sessions docs already
acknowledge this ("user devices … can sometimes be off by minutes or even hours"),
but the only suggested mitigation is "don't use a short JWT expiry" — there's no
way to make the client itself robust to skew.

Root cause (auth-js 2.108.0)

Expiry is evaluated against Date.now() in several spots, e.g.:

• GoTrueClient.__loadSession() — expires_at * 1000 - Date.now() < EXPIRY_MARGIN_MS
  (so even getSession() triggers a refresh on a skewed clock)
• GoTrueClient._autoRefreshTokenTick()
• lib/helpers.ts expiresAt() — Math.round(Date.now()/1000) + expiresIn

There's no option to override the time source, and nothing derives an offset from
the server. (The library already detects skew in one place — it logs "issued in
the future? Check the device clock for skew" — but only warns.)

Proposed solution

Let the client compensate for a known offset. A freshly-minted token's iat is
effectively the server's "now," so at each sign-in/refresh the client can compute
offset = localNow - iat and apply it wherever expiry is evaluated
(localNow - offset instead of raw localNow). With the offset applied, a wrong
device clock no longer mis-triggers refresh.

Either form would work:

• Automatic — derive/store the offset from iat (or the response Date
  header) and use it internally in all expiry comparisons; or
• Configurable — expose a pluggable time source / clockTolerance option in
  GoTrueClientOptions.

Alternatives considered

• Warn the user ("your clock looks off") — helps, but doesn't make it work.
• autoRefreshToken: false + reactive refresh — doesn't help: getSession()
  still refreshes against Date.now() on reads.
• Patching the comparison sites locally (patch-package) — works, but is a
  maintained monkeypatch against internal code.

Related (not duplicates)

• Critical Clock Skew Issue - PostgREST 15+ Hours Ahead of Auth Server #41294 — Critical Clock Skew Issue: PostgREST ahead of Auth
  Server. Same family but server-side skew (infra), not the user's device.
• supabase discussion Default Access token emmited with 20s expiration #42133 — Default Access token emitted with 20s expiration.
  Touches expiry timing; not clock-skew tolerance.
• Precedent from another auth SDK: FR: Token verification clock skew firebase/firebase-admin-go#210 — FR: Token
  verification clock skew. Clock-skew tolerance is a normal feature for an auth
  SDK to offer.

Additional context

supabase-js / auth-js 2.108.0. Server-side validation already uses the server
clock, so a token the client thinks is "expired" is in fact still valid
server-side — the disagreement is purely the client's local-clock comparison,
which an offset resolves.

[VectorPeak]

Thanks for the detailed write-up - this does look like a real client-side robustness issue, not just a docs/UX problem around short JWT expiries.

The proposed offset approach makes sense to me. If the client can derive “server now” from a freshly issued token or response metadata, then expiry checks should consistently compare against that adjusted time instead of raw Date.now(). That would prevent the bad loop where every newly refreshed session is immediately treated as expired on machines with clocks far in the future.

A few implementation details seem important:

• The offset should be recomputed on every sign-in and refresh, not treated as a permanent setting.
• It should be applied consistently anywhere auth-js evaluates expiry: __loadSession(), _autoRefreshTokenTick(), helper methods like expiresAt(), and any related refresh scheduling.
• It should handle clock correction gracefully. If the user fixes their OS clock while the app is running, the next successful auth response should bring the offset back toward zero.
• It may be worth bounding or sanity-checking the offset so a malformed token or unexpected response does not poison session handling.

Using iat is probably good enough for this because it comes from the server-issued JWT and matches the server’s view of issuance time. The response Date header would also be attractive if it is reliably available in the environments auth-js supports, but iat has the advantage of already being part of the session payload.

A configurable time source could still be useful for tests or advanced integrations, but I would not want that to be the only fix. The failure mode affects normal users who will not know they need to configure anything, so automatic skew compensation seems like the better default behavior.

One subtle point: a plain clockTolerance option helps with small drift, but it does not really solve the production case you described where the device is off by minutes or hours. An offset-derived “effective now” seems more solid than increasing the expiry margin globally.

This feels like a reasonable change to auth-js as long as it is centralized and covered with regression tests for clocks ahead/behind the server. A good test case would be: local clock ahead by more than the JWT lifetime, sign in succeeds, getSession() does not immediately refresh-loop, and the auto-refresh timer schedules from adjusted server time rather than local wall-clock time.

---

If my answer solved your problem, you can click answered the question. I'm really here to help, and along the way I'm also collecting Galaxy Brain badges haha 😆

[harrysun2006]

This is a well-researched writeup — and the root cause you've traced is accurate: auth-js evaluates expiry against Date.now() in __loadSession, _autoRefreshTokenTick, and expiresAt(), so a device clock running fast enough makes every fresh token look pre-expired, and you get the refresh storm → 429 → wedged session. The 288 refreshes/36 min repro is a pretty damning illustration.

A server-time-offset approach (derive skew from a server-provided timestamp — e.g. the Date response header or the token's iat vs local clock at receipt — and apply it to the expiry math) is the right shape for a fix, since it makes the client self-correcting without weakening security.

The awkward part today is there's no clean injection point: EXPIRY_MARGIN_MS isn't configurable, and the expiry checks are internal, so you can't work around it purely from userland without patching auth-js. The best interim mitigation I've found is detection rather than correction — watch for the signature (rapid successive refreshes / a 429 from the token endpoint) and surface an explicit "your device clock looks off, please enable automatic date & time" message, so the user isn't staring at a generic "can't log in". Not a fix, but it turns an invisible failure into an actionable one.

Definitely worth filing on the auth-js repo (supabase/auth-js) in addition to here, given you've already localized it to specific functions and versions — that's most of the work a maintainer would need to scope a getServerTimeOffset-style change. I'd upvote it.