Web UI auto-logout after ~15 minutes of inactivity

[hqhq1025]

Problem

Users are unexpectedly logged out of the HAPI web UI after a period of inactivity. Both I and another user have experienced this — we're logged in, switch to another tab or step away, and when we come back the session is gone.

Root cause

The JWT token issued at login has a hardcoded 15-minute expiration (hub/src/web/routes/auth.ts:74, hub/src/web/routes/bind.ts:54):

.setExpirationTime('15m')

The frontend does have an auto-refresh mechanism (web/src/hooks/useAuth.ts:254) that schedules a refresh 60 seconds before expiry. However, when the browser tab is in the background, the browser throttles JavaScript timers, so the scheduled refresh may not execute in time. When the user returns:

1. Token is already expired
2. Emergency refresh attempt may fail (network hiccup, race condition)
3. Frontend clears auth state → user sees login screen

Suggestion

Extend the JWT expiration to a longer duration (e.g. 7 days). HAPI is a self-hosted personal tool, not a public SaaS, so the security trade-off seems acceptable. The access token in localStorage is already long-lived — the short JWT lifetime doesn't add meaningful security since an attacker with access to the browser already has the access token.

Alternatively, the refresh mechanism could be made more robust (retry on failure instead of immediately clearing auth state).

Relevant code

• hub/src/web/routes/auth.ts:74 — setExpirationTime('15m')
• hub/src/web/routes/bind.ts:54 — setExpirationTime('15m')
• web/src/hooks/useAuth.ts:110-118 — clears auth on refresh failure when token is expired
• web/src/hooks/useAuth.ts:225-262 — auto-refresh scheduler

[github-actions]

The current code matches this report.

JWTs issued by both POST /api/auth and POST /api/bind are hardcoded to expire after 15 minutes, and I did not find a configuration option for that lifetime in the hub config. The web client tries to refresh the token 60 seconds before expiry, again when the tab becomes visible or focused, and once on 401. If a refresh attempt happens after the JWT is already expired and that refresh fails, useAuth clears the in-memory auth state; for browser login, App then renders the login screen again. For non-Telegram browser login, the underlying access token is stored in localStorage, so the short JWT is currently the only short-lived layer.

Relevant code:

• hub/src/web/routes/auth.ts:74 - /api/auth signs JWTs with .setExpirationTime('15m')
• hub/src/web/routes/bind.ts:54 - /api/bind signs JWTs with .setExpirationTime('15m')
• web/src/hooks/useAuth.ts:110 - clears token and user when refresh fails after expiry or under hard-fail conditions
• web/src/hooks/useAuth.ts:245 - scheduled refresh path; retries every 15 seconds only while the original token is still unexpired
• web/src/hooks/useAuth.ts:269 - refresh on focus and visibilitychange
• web/src/api/client.ts:106 - API client retries once on 401 through onUnauthorized
• web/src/App.tsx:314 - browser auth failure falls back to LoginPrompt
• web/src/hooks/useAuthSource.ts:42 - browser access token is persisted in localStorage

---

HAPI Bot

[hqhq1025]

@tiann I traced through the auth flow and have a few thoughts on fixing this. Wanted to discuss the approach before sending a PR.

Root cause

The 15-minute JWT expiration + browser timer throttling in background tabs = guaranteed logout for any user who switches tabs for >15 minutes. The visibility-based refresh (useAuth.ts:264-286) fires when the tab returns, but by then the token is already expired, so the server rejects the refresh request → auth state cleared → user sees login screen.

Options

Option A: Extend expiration to ~4 hours + fix visibility refresh

• Change setExpirationTime('15m') → '4h' in auth.ts:74 and bind.ts:54
• Make the visibility refresh unconditional (don't skip when TTL > 60s)
• Add retry on refresh failure instead of immediately clearing auth
• ~10 lines changed across 3 files

Option B: Just extend to 7 days

• 2-line change, simplest possible fix
• HAPI is self-hosted so the security tradeoff is arguably fine
• But long-lived tokens without revocation feels a bit loose

Option C: Add a refresh token mechanism

• Most robust long-term, but significantly more work (new endpoint, token rotation, storage)
• Probably overkill for a self-hosted tool

I lean toward Option A — 4h is long enough that background tabs won't expire during normal use, and fixing the visibility refresh adds defense in depth. What do you think?

[tiann]

@tiann I traced through the auth flow and have a few thoughts on fixing this. Wanted to discuss the approach before sending a PR.

Root cause

The 15-minute JWT expiration + browser timer throttling in background tabs = guaranteed logout for any user who switches tabs for >15 minutes. The visibility-based refresh (useAuth.ts:264-286) fires when the tab returns, but by then the token is already expired, so the server rejects the refresh request → auth state cleared → user sees login screen.

Options

Option A: Extend expiration to ~4 hours + fix visibility refresh

• Change setExpirationTime('15m') → '4h' in auth.ts:74 and bind.ts:54
• Make the visibility refresh unconditional (don't skip when TTL > 60s)
• Add retry on refresh failure instead of immediately clearing auth
• ~10 lines changed across 3 files

Option B: Just extend to 7 days

• 2-line change, simplest possible fix
• HAPI is self-hosted so the security tradeoff is arguably fine
• But long-lived tokens without revocation feels a bit loose

Option C: Add a refresh token mechanism

• Most robust long-term, but significantly more work (new endpoint, token rotation, storage)
• Probably overkill for a self-hosted tool

I lean toward Option A — 4h is long enough that background tabs won't expire during normal use, and fixing the visibility refresh adds defense in depth. What do you think?

I share your opinion

[hqhq1025]

PR submitted: #442

Went with Option A as discussed:

• JWT expiration: 15m → 4h
• Visibility refresh: conditional → forced (always re-authenticate on tab focus)

3 lines changed across 3 files.