Virtneu Auth Docs

Browser session renewal

Keep users signed in across visits with persistent cookies and low-frequency, explicit renewal.

Use a persistent browser session when users should return the next morning without entering their credentials again. The application backend keeps the Auth token protected and renews it only when the user actually returns or interacts. An idle page needs no heartbeat.

Choose a seven-day session window, a minimum renewal interval of one day, and a 30-day absolute limit for this pattern. These are application choices, not a universal security policy. Confirm the actual policy in each app environment. Existing sessions keep their creation-time policy.

The application cookie must expire no later than both Auth's expires_at and absolute_expires_at. If the application independently limits its cookie to eight hours, the user can be signed out overnight even while the upstream session remains active. Update both sides together.

On the next real foreground visit after the renewal interval, call the application's protected renewal endpoint. That backend calls refreshSession and updates the cookie from the returned expiry. Record the last confirmed successful renewal, not the last validation or a throttled request. Keep GET session reads free of expiry writes.

The 24-hour gate uses timestamps in the currently validated sealed cookie. It is a throttle for normal client-session traffic, not a global distributed limit, and does not prevent replay of older cookies that remain valid. Cross-tab locking reduces normal duplicates. Auth's independent app/environment request-admission limits remain in force.

For an existing short session, renew earlier when it approaches expiry. A useful schedule is min(lastRenewedAt + 24h, effectiveExpiry - min(30min, issuedLifetime / 4)). Stop rescheduling when the session cannot extend past its original absolute limit. A revoked or expired session requires fresh authentication.

Read the session and profile together

The API provides POST /v1/sessions/context with { "session_token": "..." }. It requires all of sessions:validate, users:read, and metadata:read. It returns either { active: false } or { active: true, session, user, metadata }, using the existing session, user and metadata projections. This replaces three backend HTTP calls with one, without caching successful authorization.

Use getSessionContext(token) in SDK 0.4.0. The immutable 0.3.0 package does not include this method. Deploy the matching API first, then upgrade the backend dependency and its lockfile; confirm the registry release before installing the new version. Do not publish modified SDK contents under an existing version.

The response never contains the session token, service key, passwords or internal safety fields. If your application requires verified email, continue checking user.email_verified. Unknown, expired, revoked, disabled and security-invalid sessions return only active: false. Database and service failures return errors, rather than pretending the user signed out. Context reads never refresh expiry.

Browser coordination and recovery

Return non-secret effective expiry, renewal time and server time from the application backend. On initial visits and foreground returns, coalesce adjacent focus, visibility and pageshow events and recheck the session online. Background freezing can drop broadcasts, so broadcasts are advisory. For ordinary user input, check timing locally before making extra requests. Only when renewal is due, acquire a short cross-tab lock, re-read the current session and call the renewal endpoint. Broadcast status and time only. Coordinate sign-in, sign-out and account changes so an old response cannot restore the previous identity.

Keep the token in a protected HttpOnly, Secure, SameSite cookie or backend session. Preserve Origin and CSRF checks for renewal. A transport or 503 error should preserve the screen and unsaved work; the backend must still validate every protected action. Respect rate limits. Never replay business writes automatically.

Retry the same uncertain renewal with the same operation key within the 60-second recovery window, then stop retrying that old operation. A successful foreground GET session check establishes only that the current cookie/session remains valid. It does not establish whether the old renewal succeeded, failed, or delivered its cookie response, and must not advance lastRenewedAt on that assumption.

After this live confirmation, the next genuine user action may start a distinct logical renewal with a new operation key if renewal is still due. This is a new activity-triggered operation, not a re-keyed retry of the unresolved old request. Timers must not reset keys or silently create fresh attempts while a result is unknown. If confirmation fails, preserve the failure state; require sign-in after confirmed expiry or invalidation.

Validate next-day return, one renewal per interval across tabs, no idle heartbeat, short-session transition, revocation, account switching and the absolute deadline. Measure the actual HTTP-call and database costs separately; three calls combined into one is not evidence of three times the throughput.

On this page