auth-vir 2.4.2 → 2.6.0

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

@@ -58,6 +58,13 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      */
     isDev: boolean;
 } & PartialWithUndefined<{
+    /**
+     * Optionally generate a service origin from request headers. The generated origin is used
+     * for set-cookie headers.
+     */
+    generateServiceOrigin(params: {
+        requestHeaders: Readonly<IncomingHttpHeaders>;
+    }): MaybePromise<undefined | string>;
     /**
      * Set this to allow specific users (determined by `canAssumeUser`) to assume the identity
      * of other users. This should only be used for admins so that they can troubleshoot user
@@ -96,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: 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;
@@ -119,7 +132,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
     constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams, CsrfHeaderName>);
     /** Get all the parameters used for cookie generation. */
-    protected getCookieParams({ isSignUpCookie, serviceOrigin, }: {
+    protected getCookieParams({ isSignUpCookie, requestHeaders, }: {
         /**
          * Set this to `true` when we are setting the initial cookie right after a user signs up.
          * This allows them to auto-authorize when they verify their email address.
@@ -127,8 +140,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
          * This should only be set to `true` when a new user is signing up.
          */
         isSignUpCookie: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
+        requestHeaders: Readonly<IncomingHttpHeaders> | undefined;
     }): Promise<Readonly<CookieParams>>;
     /** Calls the provided `getUserFromDatabase` config. */
     protected getDatabaseUser({ isSignUpCookie, userId, assumingUser, }: {
@@ -137,10 +149,9 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         isSignUpCookie: boolean;
     }): Promise<undefined | DatabaseUser>;
     /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
-    protected createCookieRefreshHeaders({ userIdResult, serviceOrigin, }: {
+    protected createCookieRefreshHeaders({ userIdResult, requestHeaders, }: {
         userIdResult: Readonly<UserIdResult<UserId>>;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<OutgoingHttpHeaders | undefined>;
     /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
     protected getAssumedUser({ headers, user, }: {
@@ -148,7 +159,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         headers: IncomingHttpHeaders;
     }): Promise<DatabaseUser | undefined>;
     /** Securely extract a user from their request headers. */
-    getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, serviceOrigin, }: {
+    getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }: {
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
         /**
@@ -157,8 +168,6 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
          * with the frontend auth client's `checkUser.performCheck` callback.
          */
         allowUserAuthRefresh: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<GetUserResult<DatabaseUser> | undefined>;
     /**
      * Get all the JWT params used when creating the auth cookie, in case you need them for
@@ -176,12 +185,10 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         'set-cookie': string[];
     }>;
     /** Use these headers to log a user in. */
-    createLoginHeaders({ userId, requestHeaders, isSignUpCookie, serviceOrigin, }: {
+    createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }: {
         userId: UserId;
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<OutgoingHttpHeaders>;
     /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
     getInsecureOrSecureUser(params: {
@@ -210,7 +217,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
      *   where JavaScript cannot be used to attach the CSRF token header to the request (like when
      *   opening a PDF file). Use `.getSecureUser()` instead, whenever possible.
      */
-    getInsecureUser({ requestHeaders, allowUserAuthRefresh, serviceOrigin, }: {
+    getInsecureUser({ requestHeaders, allowUserAuthRefresh, }: {
         requestHeaders: IncomingHttpHeaders;
         /**
          * If true, this method will generate headers to refresh the user's auth session. This
@@ -218,7 +225,5 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
          * with the frontend auth client's `checkUser.performCheck` callback.
          */
         allowUserAuthRefresh: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<GetUserResult<DatabaseUser> | undefined>;
 }

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
@@ -24,7 +27,10 @@ export class BackendAuthClient {
         this.config = config;
     }
     /** Get all the parameters used for cookie generation. */
-    async getCookieParams({ isSignUpCookie, serviceOrigin, }) {
+    async getCookieParams({ isSignUpCookie, requestHeaders, }) {
+        const serviceOrigin = requestHeaders
+            ? await this.config.generateServiceOrigin?.({ requestHeaders })
+            : undefined;
         return {
             cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
             hostOrigin: serviceOrigin || this.config.serviceOrigin,
@@ -49,7 +55,7 @@ export class BackendAuthClient {
         return authenticatedUser;
     }
     /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
-    async createCookieRefreshHeaders({ userIdResult, serviceOrigin, }) {
+    async createCookieRefreshHeaders({ userIdResult, requestHeaders, }) {
         const now = getNowInUtcTimezone();
         /** Double check that the JWT hasn't already expired. */
         const isExpiredAlready = isDateAfter({
@@ -59,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.
@@ -74,16 +96,16 @@ 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({
-                requestHeaders: {},
+                requestHeaders,
                 userId: userIdResult.userId,
                 isSignUpCookie: userIdResult.cookieName === AuthCookieName.SignUp,
-                serviceOrigin,
             });
         }
         else {
@@ -111,7 +133,7 @@ export class BackendAuthClient {
         return assumedUser;
     }
     /** Securely extract a user from their request headers. */
-    async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, serviceOrigin, }) {
+    async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
         const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
         if (!userIdResult) {
             return undefined;
@@ -130,7 +152,7 @@ export class BackendAuthClient {
         });
         const cookieRefreshHeaders = (await this.createCookieRefreshHeaders({
             userIdResult,
-            serviceOrigin,
+            requestHeaders,
         })) || {};
         return {
             user: assumedUser || user,
@@ -162,13 +184,13 @@ export class BackendAuthClient {
         const signUpCookieHeaders = params.allCookies || params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: true,
-                serviceOrigin: params.serviceOrigin,
+                requestHeaders: undefined,
             }), this.config.overrides)
             : undefined;
         const authCookieHeaders = params.allCookies || !params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: false,
-                serviceOrigin: params.serviceOrigin,
+                requestHeaders: undefined,
             }), this.config.overrides)
             : undefined;
         const setCookieHeader = {
@@ -184,19 +206,21 @@ export class BackendAuthClient {
         };
     }
     /** Use these headers to log a user in. */
-    async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, serviceOrigin, }) {
+    async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }) {
         const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
         const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
         const discardOppositeCookieHeaders = hasExistingOppositeCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: !isSignUpCookie,
-                serviceOrigin,
+                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,
-            serviceOrigin,
-        }), this.config.overrides);
+            requestHeaders,
+        }), this.config.overrides, sessionStartedAt);
         return {
             ...newCookieHeaders,
             'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),
@@ -222,7 +246,7 @@ export class BackendAuthClient {
      *   where JavaScript cannot be used to attach the CSRF token header to the request (like when
      *   opening a PDF file). Use `.getSecureUser()` instead, whenever possible.
      */
-    async getInsecureUser({ requestHeaders, allowUserAuthRefresh, serviceOrigin, }) {
+    async getInsecureUser({ requestHeaders, allowUserAuthRefresh, }) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
         if (!userIdResult) {
@@ -239,7 +263,7 @@ export class BackendAuthClient {
         const refreshHeaders = allowUserAuthRefresh &&
             (await this.createCookieRefreshHeaders({
                 userIdResult,
-                serviceOrigin,
+                requestHeaders,
             }));
         return {
             user,

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.4.2",
+    "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 {
@@ -78,6 +85,13 @@ export type BackendAuthClientConfig<
          */
         isDev: boolean;
     } & PartialWithUndefined<{
+        /**
+         * Optionally generate a service origin from request headers. The generated origin is used
+         * for set-cookie headers.
+         */
+        generateServiceOrigin(params: {
+            requestHeaders: Readonly<IncomingHttpHeaders>;
+        }): MaybePromise<undefined | string>;
         /**
          * Set this to allow specific users (determined by `canAssumeUser`) to assume the identity
          * of other users. This should only be used for admins so that they can troubleshoot user
@@ -120,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;
@@ -137,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,
 };
 
 /**
@@ -168,7 +192,7 @@ export class BackendAuthClient<
     /** Get all the parameters used for cookie generation. */
     protected async getCookieParams({
         isSignUpCookie,
-        serviceOrigin,
+        requestHeaders,
     }: {
         /**
          * Set this to `true` when we are setting the initial cookie right after a user signs up.
@@ -177,9 +201,12 @@ export class BackendAuthClient<
          * This should only be set to `true` when a new user is signing up.
          */
         isSignUpCookie: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
+        requestHeaders: Readonly<IncomingHttpHeaders> | undefined;
     }): Promise<Readonly<CookieParams>> {
+        const serviceOrigin = requestHeaders
+            ? await this.config.generateServiceOrigin?.({requestHeaders})
+            : undefined;
+
         return {
             cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
             hostOrigin: serviceOrigin || this.config.serviceOrigin,
@@ -219,11 +246,10 @@ export class BackendAuthClient<
     /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
     protected async createCookieRefreshHeaders({
         userIdResult,
-        serviceOrigin,
+        requestHeaders,
     }: {
         userIdResult: Readonly<UserIdResult<UserId>>;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<OutgoingHttpHeaders | undefined> {
         const now = getNowInUtcTimezone();
 
@@ -237,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.
@@ -252,20 +296,21 @@ 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) {
             return this.createLoginHeaders({
-                requestHeaders: {},
+                requestHeaders,
                 userId: userIdResult.userId,
                 isSignUpCookie: userIdResult.cookieName === AuthCookieName.SignUp,
-                serviceOrigin,
             });
         } else {
             return undefined;
@@ -313,7 +358,6 @@ export class BackendAuthClient<
         requestHeaders,
         isSignUpCookie,
         allowUserAuthRefresh,
-        serviceOrigin,
     }: {
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
@@ -323,8 +367,6 @@ export class BackendAuthClient<
          * with the frontend auth client's `checkUser.performCheck` callback.
          */
         allowUserAuthRefresh: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         const userIdResult = await extractUserIdFromRequestHeaders<UserId>(
             requestHeaders,
@@ -354,7 +396,7 @@ export class BackendAuthClient<
         const cookieRefreshHeaders =
             (await this.createCookieRefreshHeaders({
                 userIdResult,
-                serviceOrigin,
+                requestHeaders,
             })) || {};
 
         return {
@@ -408,7 +450,7 @@ export class BackendAuthClient<
                 ? (generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: true,
-                          serviceOrigin: params.serviceOrigin,
+                          requestHeaders: undefined,
                       }),
                       this.config.overrides,
                   ) satisfies Record<CsrfHeaderName, string>)
@@ -418,7 +460,7 @@ export class BackendAuthClient<
                 ? (generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: false,
-                          serviceOrigin: params.serviceOrigin,
+                          requestHeaders: undefined,
                       }),
                       this.config.overrides,
                   ) satisfies Record<CsrfHeaderName, string>)
@@ -448,13 +490,10 @@ export class BackendAuthClient<
         userId,
         requestHeaders,
         isSignUpCookie,
-        serviceOrigin,
     }: {
         userId: UserId;
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<OutgoingHttpHeaders> {
         const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
         const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
@@ -463,19 +502,28 @@ export class BackendAuthClient<
             ? generateLogoutHeaders(
                   await this.getCookieParams({
                       isSignUpCookie: !isSignUpCookie,
-                      serviceOrigin,
+                      requestHeaders,
                   }),
                   this.config.overrides,
               )
             : 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({
                 isSignUpCookie,
-                serviceOrigin,
+                requestHeaders,
             }),
             this.config.overrides,
+            sessionStartedAt,
         );
 
         return {
@@ -536,7 +584,6 @@ export class BackendAuthClient<
     public async getInsecureUser({
         requestHeaders,
         allowUserAuthRefresh,
-        serviceOrigin,
     }: {
         requestHeaders: IncomingHttpHeaders;
         /**
@@ -545,8 +592,6 @@ export class BackendAuthClient<
          * with the frontend auth client's `checkUser.performCheck` callback.
          */
         allowUserAuthRefresh: boolean;
-        /** Overrides the client's already established `serviceOrigin`. */
-        serviceOrigin?: string | undefined;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone<UserId>(
@@ -573,7 +618,7 @@ export class BackendAuthClient<
             allowUserAuthRefresh &&
             (await this.createCookieRefreshHeaders({
                 userIdResult,
-                serviceOrigin,
+                requestHeaders,
             }));
 
         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}),
 });
 
 /**