feat(fides-auth-next): add useHeartbeat hook and handleHeartbeat handler by losolio · Pull Request #1473 · losol/eventuras

losolio · 2026-05-21T20:55:52Z

Summary

Activity-driven session keepalive on top of the createActivityTracker primitive landed in #1470.

useHeartbeat — React hook that ticks every 5 min, gated on user activity within the last 2 min. Pauses on hidden tabs, beats immediately on tab refocus after a long away, and emits onSessionExpired when the refresh endpoint returns 401.
handleHeartbeat — Next.js route-handler factory that runs refreshCurrentSession and returns 401 when the refresh token is gone. Rate-limited via the existing globalPOSTRateLimit.
New subpath exports: @eventuras/fides-auth-next/store (adds useHeartbeat) and @eventuras/fides-auth-next/heartbeat-handler.

Part 2/3 of the session heartbeat work:

feat(fides-auth): add createActivityTracker #1470 — fides-auth: activity tracker primitive (merged)
This PR — fides-auth-next: hook + handler
PR Added appsettings #3 (next) — apps/web: route + provider wiring

No app behavior change in this PR — these are unused exports until wired up in PR #3.

Motivation

Auth0 idle refresh-token lifetime kicks in even for active users who don't navigate — e.g. long form editing. This is the bridge between "user is interacting" (PR #1) and "tokens get refreshed" (PR #3).

Design notes

5 min interval / 2 min idle threshold chosen so a user typing continuously never lets the access token (15 min default) get within close range of the Auth0 idle refresh window (typically 30+ min)
Tab visibility check prevents background tabs from indefinitely extending sessions
Callbacks are kept in a ref so re-renders don't restart the timer
No unit tests in this PR — libs/fides-auth-next has no vitest setup yet; planned as a follow-up (logged separately)

Test plan

pnpm --filter @eventuras/fides-auth-next build emits dist/heartbeat-handler.{js,d.ts} and dist/store/use-heartbeat.{js,d.ts}
Changeset present (.changeset/fides-auth-next-heartbeat.md)
Type-check clean

🤖 Generated with Claude Code

Copilot

Pull request overview

Adds the missing “heartbeat” layer to @eventuras/fides-auth-next, enabling activity-gated session refresh via a client hook and a Next.js route handler (to be wired into apps/web in the follow-up PR).

Changes:

Added useHeartbeat client hook that periodically POSTs a refresh endpoint only when the user has been recently active and the tab is visible.
Added handleHeartbeat Next.js route-handler helper that refreshes the current session and returns 401 when refresh is no longer possible.
Updated library build/exports and added a changeset for a minor release.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
libs/fides-auth-next/vite.config.ts	Adds `heartbeat-handler` as a build entrypoint.
libs/fides-auth-next/src/store/use-heartbeat.ts	New client hook implementing activity-driven keepalive logic.
libs/fides-auth-next/src/store/index.ts	Re-exports `useHeartbeat` and `HeartbeatConfig` from the store subpath.
libs/fides-auth-next/src/index.ts	Re-exports the heartbeat handler from the package root.
libs/fides-auth-next/src/heartbeat-handler.ts	New server-side helper to rate-limit and refresh the current session on POST.
libs/fides-auth-next/package.json	Adds `./heartbeat-handler` export map entry.
.changeset/fides-auth-next-heartbeat.md	Declares a minor version bump for the new hook + handler.

losolio · 2026-05-21T21:04:24Z

+        const response = await fetch(endpoint, {
+          method: 'POST',
+          credentials: 'same-origin',
+          headers: { 'content-type': 'application/json' },
+        });
+
+        if (response.status === 401) {
+          logger.info('Heartbeat returned 401 — session expired');
+          callbacksRef.current.onSessionExpired?.();
+          stopped = true;
+          return;
+        }
+
+        if (!response.ok) {
+          throw new Error(`Heartbeat failed with status ${response.status}`);
+        }
+
+        logger.debug('Heartbeat refresh succeeded');
+        callbacksRef.current.onRefreshed?.();
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        logger.warn({ error: err.message }, 'Heartbeat tick failed');
+        callbacksRef.current.onError?.(err);


Good catch — added an AbortController that's aborted in the teardown, plus a stopped re-check after the await fetch(...) so callbacks can't fire after unmount or after a 401. Extracted the cleanup into a teardown() helper that the 401 branch now calls eagerly, so the visibility listener and tracker don't linger after the session is known dead. The catch block also short-circuits on stopped so an aborted fetch doesn't surface as an onError.

losolio · 2026-05-21T21:04:26Z

+      // Tab regained focus. If we've been away longer than one tick, beat now.
+      const sinceLast = Date.now() - lastTickAt;
+      if (sinceLast >= intervalMs) {
+        logger.debug({ sinceLast }, 'Tab regained focus after long away, beating now');
+        void sendBeat();
+      }


Right — onVisibilityChange now clears the pending timeoutId before triggering the immediate beat, and chains scheduleNext after the beat resolves so the next tick is measured from now rather than firing back-to-back.

losolio · 2026-05-21T21:04:27Z

+  config: HeartbeatHandlerConfig,
+): Promise<Response> {
+  if (request.method !== 'POST') {
+    return new Response(null, { status: 405, headers: { allow: 'POST' } });


Fixed — using Allow (conventional title-case) on the 405.

losolio · 2026-05-21T21:04:29Z

+  return Response.json({
+    accessTokenExpiresAt: updated.tokens?.accessTokenExpiresAt ?? null,
+  });


Good defense-in-depth — added Cache-Control: private, no-store on the 200 success response. (401s aren't cacheable by default per RFC 7234, so leaving those as-is.)

In fides-auth-next: activity-driven session keepalive on top of @eventuras/fides-auth's createActivityTracker. Refreshes access tokens while the user is actually interacting, so long form-editing sessions don't hit the idle refresh-token cut-off. - useHeartbeat: React hook that ticks every 5 min, gated on activity within the last 2 min, pauses in hidden tabs, beats immediately on tab refocus - handleHeartbeat: Next route-handler factory that runs server-side refresh and returns 401 when the refresh token is gone Part 2/3 of the heartbeat work. PR #3 wires this into apps/web. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

sonarqubecloud · 2026-05-21T21:05:39Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Wires the heartbeat from @eventuras/fides-auth-next into apps/web: - New `/api/auth/heartbeat` POST route that delegates to the `handleHeartbeat` factory with the app's `oauthConfig` - `useHeartbeat` hook invoked from the root `Providers` so every authenticated user benefits — dispatches `sessionExpired` to the auth store on 401 Final 3/3 of the heartbeat work. Together with #1470 and #1473, this should stop the "logged out while typing" reports for active users. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings May 21, 2026 20:55

github-project-automation Bot added this to Eventuras backlog May 21, 2026

github-project-automation Bot moved this to 🆕 New in Eventuras backlog May 21, 2026

Copilot started reviewing on behalf of losolio May 21, 2026 20:56 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

losolio force-pushed the feat/auth-heartbeat-lib branch from 2e8666f to d9121c3 Compare May 21, 2026 21:04

losolio merged commit e275a40 into main May 21, 2026
6 checks passed

losolio deleted the feat/auth-heartbeat-lib branch May 21, 2026 21:08

github-project-automation Bot moved this from 🆕 New to ✅ Done in Eventuras backlog May 21, 2026

This was referenced May 21, 2026

feat(web): enable activity-driven session heartbeat #1474

Merged

test(fides-auth): set up vitest in fides-auth-next with heartbeat tests #1475

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(fides-auth-next): add useHeartbeat hook and handleHeartbeat handler#1473

feat(fides-auth-next): add useHeartbeat hook and handleHeartbeat handler#1473
losolio merged 1 commit into
mainfrom
feat/auth-heartbeat-lib

losolio commented May 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

losolio May 21, 2026

Uh oh!

losolio May 21, 2026

Uh oh!

losolio May 21, 2026

Uh oh!

losolio May 21, 2026

Uh oh!

sonarqubecloud Bot commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

losolio commented May 21, 2026

Summary

Motivation

Design notes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

losolio May 21, 2026

Choose a reason for hiding this comment

Uh oh!

losolio May 21, 2026

Choose a reason for hiding this comment

Uh oh!

losolio May 21, 2026

Choose a reason for hiding this comment

Uh oh!

losolio May 21, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented May 21, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants