auth-vir 2.5.0 → 2.6.0

package/dist/auth-client/backend-auth.client.d.ts

@@ -103,12 +103,18 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      */
     userSessionIdleTimeout: Readonly<AnyDuration>;
     /**
-     * How long before a user's session times out when we should start trying to refresh their
-     * session.
+     * How long into a user's session when we should start trying to refresh their session.
      *
-     * @default {minutes: 10}
+     * @default {minutes: 2}
      */
-    sessionRefreshThreshold: Readonly<AnyDuration>;
+    sessionRefreshTimeout: Readonly<AnyDuration>;
+    /**
+     * The maximum duration a session can last, regardless of activity. After this time, the
+     * user will be logged out even if they are actively using the application.
+     *
+     * @default {weeks: 2}
+     */
+    maxSessionDuration: Readonly<AnyDuration>;
     overrides: PartialWithUndefined<{
         csrfHeaderName: CsrfHeaderName;
         assumedUserHeaderName: string;

package/dist/auth-client/backend-auth.client.js

@@ -1,5 +1,5 @@
 import { ensureArray, } from '@augment-vir/common';
-import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter } from 'date-vir';
+import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, negateDuration, } from 'date-vir';
 import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccessfulLoginHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
 import { AuthCookieName } from '../cookie.js';
 import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
@@ -7,8 +7,11 @@ import { parseJwtKeys } from '../jwt/jwt-keys.js';
 const defaultSessionIdleTimeout = {
     minutes: 20,
 };
-const defaultSessionRefreshThreshold = {
-    minutes: 10,
+const defaultSessionRefreshTimeout = {
+    minutes: 2,
+};
+const defaultMaxSessionDuration = {
+    weeks: 2,
 };
 /**
  * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
@@ -62,6 +65,22 @@ export class BackendAuthClient {
         if (isExpiredAlready) {
             return undefined;
         }
+        /**
+         * Check if the session has exceeded the max session duration. If so, don't refresh the
+         * session and let it expire naturally.
+         */
+        const maxSessionDuration = this.config.maxSessionDuration || defaultMaxSessionDuration;
+        if (userIdResult.sessionStartedAt) {
+            const sessionStartDate = createUtcFullDate(userIdResult.sessionStartedAt);
+            const maxSessionEndDate = calculateRelativeDate(sessionStartDate, maxSessionDuration);
+            const isSessionExpired = isDateAfter({
+                fullDate: now,
+                relativeTo: maxSessionEndDate,
+            });
+            if (isSessionExpired) {
+                return undefined;
+            }
+        }
         /**
          * This check performs the following: the current time + the refresh threshold > JWT
          * expiration.
@@ -77,9 +96,10 @@ export class BackendAuthClient {
          * - Y = JWT expiration within the refresh threshold: {@link isRefreshReady} = true.
          * - Z = JWT expiration outside the refresh threshold: {@link isRefreshReady} = false.
          */
+        const sessionRefreshTimeout = this.config.sessionRefreshTimeout || defaultSessionRefreshTimeout;
         const isRefreshReady = isDateAfter({
-            fullDate: calculateRelativeDate(now, this.config.sessionRefreshThreshold || defaultSessionRefreshThreshold),
-            relativeTo: userIdResult.jwtExpiration,
+            fullDate: now,
+            relativeTo: calculateRelativeDate(userIdResult.jwtExpiration, negateDuration(sessionRefreshTimeout)),
         });
         if (isRefreshReady) {
             return this.createLoginHeaders({
@@ -195,10 +215,12 @@ export class BackendAuthClient {
                 requestHeaders,
             }), this.config.overrides)
             : undefined;
+        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
+        const sessionStartedAt = existingUserIdResult?.sessionStartedAt;
         const newCookieHeaders = await generateSuccessfulLoginHeaders(userId, await this.getCookieParams({
             isSignUpCookie,
             requestHeaders,
-        }), this.config.overrides);
+        }), this.config.overrides, sessionStartedAt);
         return {
             ...newCookieHeaders,
             'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),

package/dist/auth-client/frontend-auth.client.d.ts

@@ -56,6 +56,8 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
 export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
     protected readonly config: FrontendAuthClientConfig;
     protected userCheckInterval: undefined | ReturnType<typeof createBlockingInterval>;
+    /** Used to clean up the activity listener on `.destroy()`. */
+    protected removeActivityListener: VoidFunction | undefined;
     constructor(config?: FrontendAuthClientConfig);
     /**
      * Destroys the client and performs all necessary cleanup (like clearing the user check

package/dist/auth-client/frontend-auth.client.js

@@ -12,10 +12,12 @@ import { AuthHeaderName } from '../headers.js';
 export class FrontendAuthClient {
     config;
     userCheckInterval;
+    /** Used to clean up the activity listener on `.destroy()`. */
+    removeActivityListener;
     constructor(config = {}) {
         this.config = config;
         if (config.checkUser) {
-            listenToActivity({
+            this.removeActivityListener = listenToActivity({
                 listener: async () => {
                     const response = await config.checkUser?.performCheck();
                     if (response) {
@@ -35,6 +37,7 @@ export class FrontendAuthClient {
      */
     destroy() {
         this.userCheckInterval?.clearInterval();
+        this.removeActivityListener?.();
     }
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
     async getCurrentCsrfToken() {

package/dist/auth.d.ts

@@ -3,6 +3,7 @@ import { type FullDate, type UtcTimezone } from 'date-vir';
 import { type CookieParams } from './cookie.js';
 import { AuthHeaderName } from './headers.js';
 import { type ParseJwtParams } from './jwt/jwt.js';
+import { type JwtUserData } from './jwt/user-jwt.js';
 /**
  * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
  *
@@ -18,6 +19,11 @@ export type UserIdResult<UserId extends string | number> = {
     userId: UserId;
     jwtExpiration: FullDate<UtcTimezone>;
     cookieName: string;
+    /**
+     * Unix timestamp (in milliseconds) when the session was originally started. Used to enforce max
+     * session duration.
+     */
+    sessionStartedAt: JwtUserData['sessionStartedAt'];
 };
 /**
  * Extract the user id from a request by checking both the request cookie and CSRF token. This is
@@ -48,7 +54,12 @@ export declare function generateSuccessfulLoginHeaders<CsrfHeaderName extends st
 /** The id from your database of the user you're authenticating. */
 userId: string | number, cookieConfig: Readonly<CookieParams>, overrides?: PartialWithUndefined<{
     csrfHeaderName: CsrfHeaderName;
-}>): Promise<{
+}>, 
+/**
+ * The timestamp (in seconds) when the session originally started. If not provided, the current
+ * time will be used (for new sessions).
+ */
+sessionStartedAt?: number | undefined): Promise<{
     'set-cookie': string;
 } & Record<CsrfHeaderName, string>>;
 /**

package/dist/auth.js

@@ -48,6 +48,7 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams, cookie
             userId: jwt.data.userId,
             jwtExpiration: jwt.jwtExpiration,
             cookieName,
+            sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
     catch {
@@ -76,6 +77,7 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
             userId: jwt.data.userId,
             jwtExpiration: jwt.jwtExpiration,
             cookieName,
+            sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
     catch {
@@ -89,13 +91,19 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
  */
 export async function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-userId, cookieConfig, overrides = {}) {
+userId, cookieConfig, overrides = {}, 
+/**
+ * The timestamp (in seconds) when the session originally started. If not provided, the current
+ * time will be used (for new sessions).
+ */
+sessionStartedAt) {
     const csrfToken = generateCsrfToken(cookieConfig.cookieDuration);
     const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
     return {
         'set-cookie': await generateAuthCookie({
             csrfToken: csrfToken.token,
             userId,
+            sessionStartedAt: sessionStartedAt ?? Date.now(),
         }, cookieConfig),
         [csrfHeaderName]: JSON.stringify(csrfToken),
     };

package/dist/generated/browser.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * This file should be your main import to use Prisma-related types and utilities in a browser.

package/dist/generated/client.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.

package/dist/generated/enums.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
 * This file exports all enum related types from the schema.

package/dist/generated/internal/class.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * WARNING: This is an internal file that is subject to change!
@@ -21,8 +22,8 @@ const config = {
             "fromEnvVar": null
         },
         "config": {
-            "moduleFormat": "esm",
-            "engineType": "client"
+            "engineType": "client",
+            "moduleFormat": "esm"
         },
         "binaryTargets": [
             {
@@ -39,8 +40,8 @@ const config = {
         "isCustomOutput": true
     },
     "relativePath": "../../test-files",
-    "clientVersion": "6.18.0",
-    "engineVersion": "34b5a692b7bd79939a9a2c3ef97d816e749cda2f",
+    "clientVersion": "6.19.2",
+    "engineVersion": "c2990dca591cba766e3b7ef5d9e8a84796e47ab7",
     "datasourceNames": [
         "db"
     ],

package/dist/generated/internal/prismaNamespace.d.ts

@@ -58,8 +58,8 @@ export type PrismaVersion = {
     engine: string;
 };
 /**
- * Prisma Client JS version: 6.18.0
- * Query Engine version: 34b5a692b7bd79939a9a2c3ef97d816e749cda2f
+ * Prisma Client JS version: 6.19.2
+ * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 export declare const prismaVersion: PrismaVersion;
 /**

package/dist/generated/internal/prismaNamespace.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 /*
  * WARNING: This is an internal file that is subject to change!
  *
@@ -38,12 +39,12 @@ export const skip = runtime.skip;
 export const Decimal = runtime.Decimal;
 export const getExtensionContext = runtime.Extensions.getExtensionContext;
 /**
- * Prisma Client JS version: 6.18.0
- * Query Engine version: 34b5a692b7bd79939a9a2c3ef97d816e749cda2f
+ * Prisma Client JS version: 6.19.2
+ * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 export const prismaVersion = {
-    client: "6.18.0",
-    engine: "34b5a692b7bd79939a9a2c3ef97d816e749cda2f"
+    client: "6.19.2",
+    engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 };
 export const NullTypes = {
     DbNull: runtime.objectEnumValues.classes.DbNull,

package/dist/generated/internal/prismaNamespaceBrowser.js

@@ -1,5 +1,6 @@
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * WARNING: This is an internal file that is subject to change!

package/dist/jwt/jwt.d.ts

@@ -60,6 +60,18 @@ export type CreateJwtParams = Readonly<{
      */
     notValidUntil: DateLike;
 }>>;
+/**
+ * JWT uses seconds since the epoch per RFC 7519, whereas `toTimestamp` uses milliseconds.
+ *
+ * @category Internal
+ */
+export declare function toJwtTimestamp(date: Readonly<FullDate>): number;
+/**
+ * Converts a JWT timestamp (in seconds) into a FullDate instance.
+ *
+ * @category Internal
+ */
+export declare function parseJwtTimestamp(seconds: number): FullDate<UtcTimezone>;
 /**
  * Creates a signed and encrypted JWT that contains the given data.
  *

package/dist/jwt/jwt.js

@@ -1,8 +1,24 @@
 import { assertWrap, check } from '@augment-vir/assert';
-import { calculateRelativeDate, createFullDateInUserTimezone, createUtcFullDate, getNowInUtcTimezone, isDateAfter, toTimestamp, } from 'date-vir';
+import { calculateRelativeDate, createFullDateInUserTimezone, createUtcFullDate, getNowInUtcTimezone, toTimestamp, } from 'date-vir';
 import { EncryptJWT, jwtDecrypt, jwtVerify, SignJWT } from 'jose';
 const encryptionProtectedHeader = { alg: 'dir', enc: 'A256GCM' };
 const signingProtectedHeader = { alg: 'HS512' };
+/**
+ * JWT uses seconds since the epoch per RFC 7519, whereas `toTimestamp` uses milliseconds.
+ *
+ * @category Internal
+ */
+export function toJwtTimestamp(date) {
+    return Math.floor(toTimestamp(date) / 1000);
+}
+/**
+ * Converts a JWT timestamp (in seconds) into a FullDate instance.
+ *
+ * @category Internal
+ */
+export function parseJwtTimestamp(seconds) {
+    return createUtcFullDate(seconds * 1000);
+}
 /**
  * Creates a signed and encrypted JWT that contains the given data.
  *
@@ -14,13 +30,13 @@ data, params) {
     const rawJwt = new SignJWT({ data })
         .setProtectedHeader(signingProtectedHeader)
         .setIssuedAt(params.issuedAt
-        ? toTimestamp(createFullDateInUserTimezone(params.issuedAt))
+        ? toJwtTimestamp(createFullDateInUserTimezone(params.issuedAt))
         : undefined)
         .setIssuer(params.issuer)
         .setAudience(params.audience)
-        .setExpirationTime(toTimestamp(calculateRelativeDate(getNowInUtcTimezone(), params.jwtDuration)));
+        .setExpirationTime(toJwtTimestamp(calculateRelativeDate(getNowInUtcTimezone(), params.jwtDuration)));
     if (params.notValidUntil) {
-        rawJwt.setNotBefore(toTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
+        rawJwt.setNotBefore(toJwtTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
     }
     const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
     return await new EncryptJWT({ jwt: signedJwt })
@@ -57,14 +73,8 @@ export async function parseJwt(encryptedJwt, params) {
     if (!check.deepEquals(verifiedJwt.protectedHeader, signingProtectedHeader)) {
         throw new Error('Invalid signing protected header.');
     }
-    const expirationMs = assertWrap.isDefined(verifiedJwt.payload.exp, 'JWT has no expiration.');
-    const jwtExpiration = createUtcFullDate(expirationMs);
-    if (isDateAfter({
-        fullDate: getNowInUtcTimezone(),
-        relativeTo: jwtExpiration,
-    })) {
-        throw new Error('JWT expired.');
-    }
+    const expirationSeconds = assertWrap.isDefined(verifiedJwt.payload.exp, 'JWT has no expiration.');
+    const jwtExpiration = parseJwtTimestamp(expirationSeconds);
     return {
         data: data,
         jwtExpiration,

package/dist/jwt/user-jwt.d.ts

@@ -13,6 +13,12 @@ export declare const userJwtDataShape: import("object-shape-tester").Shape<{
      * Consider using {@link generateCsrfToken} to generate this.
      */
     csrfToken: string;
+    /**
+     * Unix timestamp (in milliseconds) when the session was originally started. This is used to
+     * enforce the max session duration. If not present, the session is considered to have started
+     * when the JWT was issued.
+     */
+    sessionStartedAt: import("object-shape-tester").Shape<import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUndefined, import("@sinclair/typebox").TNumber]>>>;
 }>;
 /**
  * Data required for user JWTs.

package/dist/jwt/user-jwt.js

@@ -1,4 +1,4 @@
-import { checkValidShape, defineShape, unionShape } from 'object-shape-tester';
+import { checkValidShape, defineShape, optionalShape, unionShape } from 'object-shape-tester';
 import { createJwt, parseJwt, } from './jwt.js';
 /**
  * Shape definition and source of truth for {@link JwtUserData}.
@@ -14,6 +14,12 @@ export const userJwtDataShape = defineShape({
      * Consider using {@link generateCsrfToken} to generate this.
      */
     csrfToken: '',
+    /**
+     * Unix timestamp (in milliseconds) when the session was originally started. This is used to
+     * enforce the max session duration. If not present, the session is considered to have started
+     * when the JWT was issued.
+     */
+    sessionStartedAt: optionalShape(0, { alsoUndefined: true }),
 });
 /**
  * Creates a new signed and encrypted {@link JwtUserData} when a client (frontend) successfully

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "2.5.0",
+    "version": "2.6.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -42,18 +42,18 @@
         "test:web": "virmator test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.47.0",
-        "@augment-vir/common": "^31.47.0",
-        "date-vir": "^8.0.0",
+        "@augment-vir/assert": "^31.59.0",
+        "@augment-vir/common": "^31.59.0",
+        "date-vir": "^8.1.0",
         "detect-activity": "^0.0.1",
         "hash-wasm": "^4.12.0",
-        "jose": "^6.1.0",
-        "object-shape-tester": "^6.9.3",
-        "type-fest": "^5.1.0",
-        "url-vir": "^2.1.6"
+        "jose": "^6.1.3",
+        "object-shape-tester": "^6.11.0",
+        "type-fest": "^5.4.1",
+        "url-vir": "^2.1.7"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.47.0",
+        "@augment-vir/test": "^31.59.0",
         "@prisma/client": "^6.18.0",
         "@types/node": "^24.9.1",
         "@web/dev-server-esbuild": "^1.0.4",
@@ -63,8 +63,8 @@
         "@web/test-runner-visual-regression": "^0.10.0",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "prisma-vir": "^2.1.0",
-        "typedoc": "^0.28.14"
+        "prisma-vir": "^2.3.3",
+        "typedoc": "^0.28.16"
     },
     "engines": {
         "node": ">=22"

package/src/auth-client/backend-auth.client.ts

@@ -5,7 +5,14 @@ import {
     type MaybePromise,
     type PartialWithUndefined,
 } from '@augment-vir/common';
-import {calculateRelativeDate, getNowInUtcTimezone, isDateAfter, type AnyDuration} from 'date-vir';
+import {
+    calculateRelativeDate,
+    createUtcFullDate,
+    getNowInUtcTimezone,
+    isDateAfter,
+    negateDuration,
+    type AnyDuration,
+} from 'date-vir';
 import {type IncomingHttpHeaders, type OutgoingHttpHeaders} from 'node:http';
 import {type EmptyObject, type RequireExactlyOne, type RequireOneOrNone} from 'type-fest';
 import {
@@ -127,12 +134,18 @@ export type BackendAuthClientConfig<
          */
         userSessionIdleTimeout: Readonly<AnyDuration>;
         /**
-         * How long before a user's session times out when we should start trying to refresh their
-         * session.
+         * How long into a user's session when we should start trying to refresh their session.
+         *
+         * @default {minutes: 2}
+         */
+        sessionRefreshTimeout: Readonly<AnyDuration>;
+        /**
+         * The maximum duration a session can last, regardless of activity. After this time, the
+         * user will be logged out even if they are actively using the application.
          *
-         * @default {minutes: 10}
+         * @default {weeks: 2}
          */
-        sessionRefreshThreshold: Readonly<AnyDuration>;
+        maxSessionDuration: Readonly<AnyDuration>;
         overrides: PartialWithUndefined<{
             csrfHeaderName: CsrfHeaderName;
             assumedUserHeaderName: string;
@@ -144,8 +157,12 @@ const defaultSessionIdleTimeout: Readonly<AnyDuration> = {
     minutes: 20,
 };
 
-const defaultSessionRefreshThreshold: Readonly<AnyDuration> = {
-    minutes: 10,
+const defaultSessionRefreshTimeout: Readonly<AnyDuration> = {
+    minutes: 2,
+};
+
+const defaultMaxSessionDuration: Readonly<AnyDuration> = {
+    weeks: 2,
 };
 
 /**
@@ -246,6 +263,24 @@ export class BackendAuthClient<
             return undefined;
         }
 
+        /**
+         * Check if the session has exceeded the max session duration. If so, don't refresh the
+         * session and let it expire naturally.
+         */
+        const maxSessionDuration = this.config.maxSessionDuration || defaultMaxSessionDuration;
+        if (userIdResult.sessionStartedAt) {
+            const sessionStartDate = createUtcFullDate(userIdResult.sessionStartedAt);
+            const maxSessionEndDate = calculateRelativeDate(sessionStartDate, maxSessionDuration);
+            const isSessionExpired = isDateAfter({
+                fullDate: now,
+                relativeTo: maxSessionEndDate,
+            });
+
+            if (isSessionExpired) {
+                return undefined;
+            }
+        }
+
         /**
          * This check performs the following: the current time + the refresh threshold > JWT
          * expiration.
@@ -261,12 +296,14 @@ export class BackendAuthClient<
          * - Y = JWT expiration within the refresh threshold: {@link isRefreshReady} = true.
          * - Z = JWT expiration outside the refresh threshold: {@link isRefreshReady} = false.
          */
+        const sessionRefreshTimeout =
+            this.config.sessionRefreshTimeout || defaultSessionRefreshTimeout;
         const isRefreshReady = isDateAfter({
-            fullDate: calculateRelativeDate(
-                now,
-                this.config.sessionRefreshThreshold || defaultSessionRefreshThreshold,
+            fullDate: now,
+            relativeTo: calculateRelativeDate(
+                userIdResult.jwtExpiration,
+                negateDuration(sessionRefreshTimeout),
             ),
-            relativeTo: userIdResult.jwtExpiration,
         });
 
         if (isRefreshReady) {
@@ -471,6 +508,14 @@ export class BackendAuthClient<
               )
             : undefined;
 
+        const existingUserIdResult = await extractUserIdFromRequestHeaders<UserId>(
+            requestHeaders,
+            await this.getJwtParams(),
+            isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
+            this.config.overrides,
+        );
+        const sessionStartedAt = existingUserIdResult?.sessionStartedAt;
+
         const newCookieHeaders = await generateSuccessfulLoginHeaders(
             userId,
             await this.getCookieParams({
@@ -478,6 +523,7 @@ export class BackendAuthClient<
                 requestHeaders,
             }),
             this.config.overrides,
+            sessionStartedAt,
         );
 
         return {

package/src/auth-client/frontend-auth.client.ts

@@ -81,10 +81,12 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  */
 export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
     protected userCheckInterval: undefined | ReturnType<typeof createBlockingInterval>;
+    /** Used to clean up the activity listener on `.destroy()`. */
+    protected removeActivityListener: VoidFunction | undefined;
 
     constructor(protected readonly config: FrontendAuthClientConfig = {}) {
         if (config.checkUser) {
-            listenToActivity({
+            this.removeActivityListener = listenToActivity({
                 listener: async () => {
                     const response = await config.checkUser?.performCheck();
 
@@ -106,6 +108,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
      */
     public destroy() {
         this.userCheckInterval?.clearInterval();
+        this.removeActivityListener?.();
     }
 
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */

package/src/auth.ts

@@ -16,6 +16,7 @@ import {
 } from './csrf-token.js';
 import {AuthHeaderName} from './headers.js';
 import {type ParseJwtParams} from './jwt/jwt.js';
+import {type JwtUserData} from './jwt/user-jwt.js';
 
 /**
  * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
@@ -49,6 +50,11 @@ export type UserIdResult<UserId extends string | number> = {
     userId: UserId;
     jwtExpiration: FullDate<UtcTimezone>;
     cookieName: string;
+    /**
+     * Unix timestamp (in milliseconds) when the session was originally started. Used to enforce max
+     * session duration.
+     */
+    sessionStartedAt: JwtUserData['sessionStartedAt'];
 };
 
 function readCsrfTokenHeader(
@@ -100,6 +106,7 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
             userId: jwt.data.userId as UserId,
             jwtExpiration: jwt.jwtExpiration,
             cookieName,
+            sessionStartedAt: jwt.data.sessionStartedAt,
         };
     } catch {
         return undefined;
@@ -136,6 +143,7 @@ export async function insecureExtractUserIdFromCookieAlone<UserId extends string
             userId: jwt.data.userId as UserId,
             jwtExpiration: jwt.jwtExpiration,
             cookieName,
+            sessionStartedAt: jwt.data.sessionStartedAt,
         };
     } catch {
         return undefined;
@@ -156,6 +164,11 @@ export async function generateSuccessfulLoginHeaders<
     overrides: PartialWithUndefined<{
         csrfHeaderName: CsrfHeaderName;
     }> = {},
+    /**
+     * The timestamp (in seconds) when the session originally started. If not provided, the current
+     * time will be used (for new sessions).
+     */
+    sessionStartedAt?: number | undefined,
 ): Promise<
     {
         'set-cookie': string;
@@ -169,6 +182,7 @@ export async function generateSuccessfulLoginHeaders<
             {
                 csrfToken: csrfToken.token,
                 userId,
+                sessionStartedAt: sessionStartedAt ?? Date.now(),
             },
             cookieConfig,
         ),

package/src/generated/browser.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * This file should be your main import to use Prisma-related types and utilities in a browser. 

package/src/generated/client.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.

package/src/generated/commonInputTypes.ts

@@ -3,6 +3,7 @@ import {type UtcIsoString} from 'date-vir';
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 /*
  * This file exports various common sort, input & filter types that are not directly linked to a particular model.
  *

package/src/generated/enums.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
 * This file exports all enum related types from the schema.

package/src/generated/internal/class.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * WARNING: This is an internal file that is subject to change!
@@ -26,8 +27,8 @@ const config: runtime.GetPrismaClientConfig = {
       "fromEnvVar": null
     },
     "config": {
-      "moduleFormat": "esm",
-      "engineType": "client"
+      "engineType": "client",
+      "moduleFormat": "esm"
     },
     "binaryTargets": [
       {
@@ -44,8 +45,8 @@ const config: runtime.GetPrismaClientConfig = {
     "isCustomOutput": true
   },
   "relativePath": "../../test-files",
-  "clientVersion": "6.18.0",
-  "engineVersion": "34b5a692b7bd79939a9a2c3ef97d816e749cda2f",
+  "clientVersion": "6.19.2",
+  "engineVersion": "c2990dca591cba766e3b7ef5d9e8a84796e47ab7",
   "datasourceNames": [
     "db"
   ],

package/src/generated/internal/prismaNamespace.ts

@@ -3,6 +3,7 @@ import {type UtcIsoString} from 'date-vir';
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 /*
  * WARNING: This is an internal file that is subject to change!
  *
@@ -93,12 +94,12 @@ export type PrismaVersion = {
 }
 
 /**
- * Prisma Client JS version: 6.18.0
- * Query Engine version: 34b5a692b7bd79939a9a2c3ef97d816e749cda2f
+ * Prisma Client JS version: 6.19.2
+ * Query Engine version: c2990dca591cba766e3b7ef5d9e8a84796e47ab7
  */
 export const prismaVersion: PrismaVersion = {
-  client: "6.18.0",
-  engine: "34b5a692b7bd79939a9a2c3ef97d816e749cda2f"
+  client: "6.19.2",
+  engine: "c2990dca591cba766e3b7ef5d9e8a84796e47ab7"
 }
 
 /**

package/src/generated/internal/prismaNamespaceBrowser.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * WARNING: This is an internal file that is subject to change!

package/src/generated/models/User.ts

@@ -7,6 +7,7 @@ import {type UtcIsoString} from 'date-vir';
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 /*
  * This file exports the `User` model and its related types.
  *

package/src/generated/models.ts

@@ -1,6 +1,7 @@
 
 /* !!! This is code generated by Prisma. Do not edit directly. !!! */
 /* eslint-disable */
+// biome-ignore-all lint: generated file
 // @ts-nocheck 
 /*
  * This is a barrel export file for all models and their related types.

package/src/jwt/jwt.ts

@@ -8,7 +8,6 @@ import {
     type DateLike,
     type FullDate,
     getNowInUtcTimezone,
-    isDateAfter,
     toTimestamp,
     type UtcTimezone,
 } from 'date-vir';
@@ -81,6 +80,24 @@ export type CreateJwtParams = Readonly<{
         }>
     >;
 
+/**
+ * JWT uses seconds since the epoch per RFC 7519, whereas `toTimestamp` uses milliseconds.
+ *
+ * @category Internal
+ */
+export function toJwtTimestamp(date: Readonly<FullDate>) {
+    return Math.floor(toTimestamp(date) / 1000);
+}
+
+/**
+ * Converts a JWT timestamp (in seconds) into a FullDate instance.
+ *
+ * @category Internal
+ */
+export function parseJwtTimestamp(seconds: number): FullDate<UtcTimezone> {
+    return createUtcFullDate(seconds * 1000);
+}
+
 /**
  * Creates a signed and encrypted JWT that contains the given data.
  *
@@ -95,17 +112,17 @@ export async function createJwt<JwtData extends AnyObject = AnyObject>(
         .setProtectedHeader(signingProtectedHeader)
         .setIssuedAt(
             params.issuedAt
-                ? toTimestamp(createFullDateInUserTimezone(params.issuedAt))
+                ? toJwtTimestamp(createFullDateInUserTimezone(params.issuedAt))
                 : undefined,
         )
         .setIssuer(params.issuer)
         .setAudience(params.audience)
         .setExpirationTime(
-            toTimestamp(calculateRelativeDate(getNowInUtcTimezone(), params.jwtDuration)),
+            toJwtTimestamp(calculateRelativeDate(getNowInUtcTimezone(), params.jwtDuration)),
         );
 
     if (params.notValidUntil) {
-        rawJwt.setNotBefore(toTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
+        rawJwt.setNotBefore(toJwtTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
     }
 
     const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
@@ -170,17 +187,12 @@ export async function parseJwt<JwtData extends AnyObject = AnyObject>(
         throw new Error('Invalid signing protected header.');
     }
 
-    const expirationMs = assertWrap.isDefined(verifiedJwt.payload.exp, 'JWT has no expiration.');
-    const jwtExpiration: FullDate<UtcTimezone> = createUtcFullDate(expirationMs);
+    const expirationSeconds = assertWrap.isDefined(
+        verifiedJwt.payload.exp,
+        'JWT has no expiration.',
+    );
 
-    if (
-        isDateAfter({
-            fullDate: getNowInUtcTimezone(),
-            relativeTo: jwtExpiration,
-        })
-    ) {
-        throw new Error('JWT expired.');
-    }
+    const jwtExpiration: FullDate<UtcTimezone> = parseJwtTimestamp(expirationSeconds);
 
     return {
         data: data as JwtData,

package/src/jwt/user-jwt.ts

@@ -1,4 +1,4 @@
-import {checkValidShape, defineShape, unionShape} from 'object-shape-tester';
+import {checkValidShape, defineShape, optionalShape, unionShape} from 'object-shape-tester';
 import {type generateCsrfToken} from '../csrf-token.js';
 import {
     createJwt,
@@ -22,6 +22,12 @@ export const userJwtDataShape = defineShape({
      * Consider using {@link generateCsrfToken} to generate this.
      */
     csrfToken: '',
+    /**
+     * Unix timestamp (in milliseconds) when the session was originally started. This is used to
+     * enforce the max session duration. If not present, the session is considered to have started
+     * when the JWT was issued.
+     */
+    sessionStartedAt: optionalShape(0, {alsoUndefined: true}),
 });
 
 /**