feat: add threshold in DateProvider

lib/ts/claims/primitiveArrayClaim.ts

@@ -33,6 +33,11 @@ export class PrimitiveArrayClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),
@@ -75,6 +80,11 @@ export class PrimitiveArrayClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),
@@ -121,6 +131,11 @@ export class PrimitiveArrayClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),
@@ -164,6 +179,11 @@ export class PrimitiveArrayClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),
@@ -211,6 +231,11 @@ export class PrimitiveArrayClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),

lib/ts/claims/primitiveClaim.ts

@@ -33,6 +33,11 @@ export class PrimitiveClaim<ValueType> {
             id?: string
         ): SessionClaimValidator => {
             const DateProvider = DateProviderReference.getReferenceOrThrow().dateProvider;
+            if (maxAgeInSeconds && maxAgeInSeconds < DateProvider.getThresholdInSeconds()) {
+                throw new Error(
+                    `maxAgeInSeconds must be greater than the DateProvider threshold value -> ${DateProvider.getThresholdInSeconds()}`
+                );
+            }
             return {
                 id: id !== undefined ? id : this.id,
                 refresh: ctx => this.refresh(ctx),

lib/ts/utils/dateProvider/defaultImplementation.ts

@@ -19,6 +19,9 @@ export class DateProvider {
     private static instance?: DateProvider;
     public static readonly CLOCK_SKEW_KEY = "__st_clockSkewInMillis";
     private clockSkewInMillis: number = 0;
+    // Ensure a meaningful clock skew value by setting a threshold. Omitting a threshold would invariably lead to some
+    // clock skew due to server-client latency, arising from the time it takes for the token to arrive after being issued.
+    private thresholdInSeconds = 7;
 
     // The static init method is used to create a singleton instance of DateProvider,
     // as we require access to localStorage for initializing clockSkewInMillis.
@@ -56,8 +59,12 @@ export class DateProvider {
         return DateProvider.instance;
     }
 
+    getThresholdInSeconds(): number {
+        return this.thresholdInSeconds;
+    }
+
     setClientClockSkewInMillis(clockSkewInMillis: number): void {
-        this.clockSkewInMillis = clockSkewInMillis;
+        this.clockSkewInMillis = Math.abs(clockSkewInMillis) > this.thresholdInSeconds * 1000 ? clockSkewInMillis : 0;
         const localStorage = WindowHandlerReference.getReferenceOrThrow().windowHandler.localStorage;
         localStorage.setItemSync(DateProvider.CLOCK_SKEW_KEY, String(clockSkewInMillis));
     }

lib/ts/utils/dateProvider/index.ts

@@ -29,16 +29,14 @@ export default class DateProviderReference {
     dateProvider: DateProviderInterface;
 
     constructor(dateProviderInput?: DateProviderInput) {
-        let dateProviderFunc: DateProviderInput = original => original;
         if (dateProviderInput !== undefined) {
-            dateProviderFunc = dateProviderInput;
+            this.dateProvider = dateProviderInput();
+        } else {
+            // Initialize the DateProvider implementation by calling the init method.
+            // This is done to ensure that the WindowHandler is initialized before we instantiate the DateProvider.
+            DateProvider.init();
+            this.dateProvider = DateProvider.getReferenceOrThrow();
         }
-
-        // Initialize the DateProvider implementation by calling the init method.
-        // This is done to ensure that the WindowHandler is initialized before we instantiate the DateProvider.
-        DateProvider.init();
-        const defaultDateProviderImplementation = DateProvider.getReferenceOrThrow();
-        this.dateProvider = dateProviderFunc(defaultDateProviderImplementation);
     }
 
     static init(dateProviderInput?: DateProviderInput): void {

lib/ts/utils/dateProvider/types.ts

@@ -14,9 +14,10 @@
  */
 
 export interface DateProviderInterface {
+    getThresholdInSeconds(): number;
     now(): number;
     setClientClockSkewInMillis(clockSkewInMillis: number): void;
     getClientClockSkewInMillis(): number;
 }
 
-export type DateProviderInput = (original: DateProviderInterface) => DateProviderInterface;
+export type DateProviderInput = () => DateProviderInterface;

test/interception.claims.test.js

@@ -194,7 +194,7 @@ addGenericTestCases((name, transferMethod, setupFunc, setupArgs = []) => {
             }
         });
 
-        it("should call the claim refresh endpoint once for multiple `shouldRefresh` calls with adjusted clock skew", async function () {
+        it("should call the claim refresh endpoint once for multiple `shouldRefresh` calls with adjusted clock skew (client clock ahead)", async function () {
             await startST(2 * 60 * 60); // setting accessTokenValidity to 2 hours to avoid refresh issues due to clock skew
             try {
                 let customClaimRefreshCalledCount = 0;
@@ -266,6 +266,78 @@ addGenericTestCases((name, transferMethod, setupFunc, setupArgs = []) => {
             }
         });
 
+        it("should call the claim refresh endpoint once for multiple `shouldRefresh` calls with adjusted clock skew (client clock behind)", async function () {
+            await startST(2 * 60 * 60); // setting accessTokenValidity to 2 hours to avoid refresh issues due to clock skew
+            try {
+                let customClaimRefreshCalledCount = 0;
+
+                // Override Date.now() to return the current time minus 1 hour
+                await page.evaluate(() => {
+                    globalThis.originalNow = Date.now;
+                    Date.now = function () {
+                        return originalNow() - 60 * 60 * 1000;
+                    };
+                });
+
+                await page.setRequestInterception(true);
+
+                page.on("request", req => {
+                    if (req.url() === `${BASE_URL}/update-jwt`) {
+                        customClaimRefreshCalledCount++;
+                    }
+                    req.continue();
+                });
+
+                await page.evaluate(async () => {
+                    const userId = "testing-supertokens-website";
+
+                    // Create a session
+                    const loginResponse = await toTest({
+                        url: `${BASE_URL}/login`,
+                        method: "post",
+                        headers: {
+                            Accept: "application/json",
+                            "Content-Type": "application/json"
+                        },
+                        body: JSON.stringify({ userId })
+                    });
+
+                    assertEqual(loginResponse.responseText, userId);
+
+                    const customSessionClaim = new supertokens.BooleanClaim({
+                        id: "st-custom",
+                        refresh: async () => {
+                            const resp = await toTest({
+                                url: `${BASE_URL}/update-jwt`,
+                                method: "post",
+                                headers: {
+                                    Accept: "application/json",
+                                    "Content-Type": "application/json"
+                                },
+                                body: JSON.stringify({
+                                    "st-custom": {
+                                        v: true,
+                                        t: originalNow()
+                                    }
+                                })
+                            });
+                        },
+                        defaultMaxAgeInSeconds: 300 /* 300 seconds */
+                    });
+
+                    const customSessionClaimValidator = customSessionClaim.validators.isTrue();
+
+                    await supertokens.validateClaims(() => [customSessionClaimValidator]);
+                    await supertokens.validateClaims(() => [customSessionClaimValidator]);
+                    await supertokens.validateClaims(() => [customSessionClaimValidator]);
+                });
+
+                assert.strictEqual(customClaimRefreshCalledCount, 1);
+            } finally {
+                await browser.close();
+            }
+        });
+
         it("should call getClockSkewInMillis with appropriate headers", async function () {
             await startST();
             let clockSkewParams = [];