feat: syncs time with Authorization Server date header

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okta/okta-client-js",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "private": true,
   "packageManager": "yarn@1.22.19",
   "engines": {

packages/auth-foundation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okta/auth-foundation",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "type": "module",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",

packages/auth-foundation/src/oauth2/client.ts

@@ -28,6 +28,7 @@ import { UserInfo } from './requests/UserInfo.ts';
 import { PromiseQueue } from '../utils/PromiseQueue.ts';
 import { EventEmitter } from '../utils/EventEmitter.ts';
 import { hasSameValues } from '../utils/index.ts';
+import TimeCoordinator, { Timestamp } from '../utils/TimeCoordinator.ts';
 
 
 // ref: https://developer.okta.com/docs/reference/api/oidc/
@@ -100,9 +101,32 @@ export class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.Events> e
   }
 
   /** @internal */
-  protected async prepareDPoPNonceRetry (request: APIRequest, nonce: string): Promise<void> {
+  protected async prepareDPoPNonceRetry (request: APIRequest): Promise<void> {
+    return this.signTokenRequestWithDPoP(request);
+  }
+
+  protected async signTokenRequestWithDPoP (request: APIRequest, nonce?: string): Promise<void> {
     const { dpopPairId } = request.context;
-    await this.dpopSigningAuthority.sign(request, { keyPairId: dpopPairId, nonce });
+    // dpop nonce may not be available for this request (undefined), this is expected
+    const dpopNonce = nonce ?? await this.getDPoPNonceFromCache(request);
+    await this.dpopSigningAuthority.sign(request, { keyPairId: dpopPairId, nonce: dpopNonce });
+  }
+
+  protected async processResponse(response: Response, request: APIRequest): Promise<void> {
+    await super.processResponse(response, request);
+
+    if (this.configuration.syncClockWithAuthorizationServer) {
+      // NOTE: this logic will not work on CORS requests, the Date header needs to be allowlisted via access-control-expose-headers
+      const dateHeader = response.headers.get('date');
+      if (dateHeader) {
+        const parsedDate = new Date(dateHeader);
+        if (parsedDate.toString() !== 'Invalid Date') {
+          const serverTime = Timestamp.from(parsedDate);
+          const skew = Math.round(serverTime.timeSince(Date.now() / 1000));
+          TimeCoordinator.clockSkew = skew;
+        }
+      }
+    }
   }
 
   /** @internal */
@@ -170,16 +194,34 @@ export class OAuth2Client<E extends OAuth2Client.Events = OAuth2Client.Events> e
     const { acrValues, maxAge } = tokenRequest;
 
     if (this.configuration.dpop) {
-      // dpop nonce may not be available for this request (undefined), this is expected
-      const nonce = await this.getDPoPNonceFromCache(request);
-      await this.dpopSigningAuthority.sign(request, { keyPairId: dpopPairId, nonce });
+      request.context.dpopPairId = dpopPairId;
+      await this.signTokenRequestWithDPoP(request);
     }
 
     const response = await this.send(request);
-    const json = await response.json();
+    let json = await response.json();
 
     if (isOAuth2ErrorResponse(json)) {
-      return json;
+      if (
+        // proper error is returned from AS
+        OAuth2Client.isDPoPProofClockSkewError(json) &&
+        // request hasn't been retried too many times previously
+        request.canRetry() &&
+        // (heuristic) the TimeCoordinator updated with a meaningful time difference (~2.5 mintues)
+        Math.abs(Date.now() - TimeCoordinator.clockSkew) >= 150
+      ) {
+        // If a JWT (DPoP Proof) clock skew error is returned we can retry the request.
+        // The `Date` header of the /token response will be have been processed, hopefully
+        // this will align the client's clock with the Authorization Server's
+        await this.signTokenRequestWithDPoP(request);     // re-sign request (with new `TimeCoordinator.now()`)
+        const retryReponse = await this.retry(request);   // trigger retry
+        json = await retryReponse.json();
+      }
+
+      // redundant, but handles scenario where retry returns error
+      if (isOAuth2ErrorResponse(json)) {
+        return json;
+      }
     }
 
     const tokenContext: Token.Context = {
@@ -549,4 +591,11 @@ export namespace OAuth2Client {
   export type GetJsonOptions = {
     skipCache?: boolean;
   };
+
+  export function isDPoPProofClockSkewError (error: OAuth2ErrorResponse) {
+    return error.error === 'invalid_dpop_proof' && (
+      error.error_description === 'The DPoP proof JWT is issued in the future.' ||
+      error.error_description === 'The DPoP proof JWT is issued more than five minutes in the past.'
+    );
+  }
 }

packages/auth-foundation/src/oauth2/configuration.ts

@@ -24,7 +24,8 @@ export type OAuth2ClientConfigurations = DiscrimUnion<OAuth2Params & {
 export type OAuth2ClientOptions = {
   authentication?: ClientAuthentication;
   allowHTTP?: boolean;
-}
+  syncClockWithAuthorizationServer?: boolean;
+};
 
 /**
  * @group Configuration
@@ -45,10 +46,25 @@ export class Configuration extends APIClient.Configuration implements APIClientC
    * When `true`, issuer and other .well-known endpoints can be HTTP. Defaults to `false`
    */
   public allowHTTP: boolean = false;
+  /**
+   * When `true`, the `Date` header from HTTP requests made to the Authorization Server will be
+   * used to calculate a clock skew between the Authorization Server and the system clock. This is
+   * useful for situations when the client's system clock is set to something other than the "true time".
+   *
+   * Defaults to `true`.
+   *
+   * @remarks
+   * By default, the `Date` header is not safelisted for CORS requests. The Authorization Server will need
+   * to include the `Date` header in the `allow-control-exppose-headers` for this feature to work properly.
+   *
+   * Reference: https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header
+   */
+  public syncClockWithAuthorizationServer: boolean = true;
 
   public static DefaultOptions: Required<OAuth2ClientOptions> & typeof APIClient.Configuration.DefaultOptions = {
     ...APIClient.Configuration.DefaultOptions,
     allowHTTP: false,
+    syncClockWithAuthorizationServer: true,
     authentication: 'none'
   };
 
@@ -61,7 +77,8 @@ export class Configuration extends APIClient.Configuration implements APIClientC
       scopes,
       authentication,
       dpop,
-      allowHTTP
+      allowHTTP,
+      syncClockWithAuthorizationServer
     } = { ...Configuration.DefaultOptions, ...params };
     const url = issuer ?? baseURL;            // one of them must be defined via Discriminated Union
     if (!validateURL(url, allowHTTP)) {
@@ -77,6 +94,7 @@ export class Configuration extends APIClient.Configuration implements APIClientC
     // default values are set in `static DefaultOptions`
     this.authentication = authentication;
     this.allowHTTP = allowHTTP;
+    this.syncClockWithAuthorizationServer = syncClockWithAuthorizationServer;
   }
 
   /**
@@ -112,15 +130,16 @@ export class Configuration extends APIClient.Configuration implements APIClientC
   }
 
   toJSON (): JsonRecord {
-    const { issuer, discoveryURL, clientId, scopes, authentication, allowHTTP } = this;
+    const { issuer, discoveryURL, clientId, scopes, authentication, allowHTTP, syncClockWithAuthorizationServer } = this;
     return {
       ...super.toJSON(),
       issuer: issuer.href,
       discoveryURL: discoveryURL.href,
       clientId,
       scopes,
       authentication,
-      allowHTTP
+      allowHTTP,
+      syncClockWithAuthorizationServer
     };
   }
 }

packages/auth-foundation/src/utils/TimeCoordinator.ts

@@ -81,18 +81,24 @@ export class Timestamp {
 /**
  * @group TimeCoordinator
  */
-// TODO: implement (post beta)
 class TimeCoordinator {
+  #skew = 0;
+  static #tolerance = 0;
 
-  // TODO: adjust from http time headers
-  // (backend change needed to allow Date header in CORS requests)
-  get clockSkew () {
-    return 0;
+  get clockSkew (): Seconds {
+    return this.#skew;
   }
 
-  // TODO: accept via config option
-  static get clockTolerance () {
-    return 0;
+  set clockSkew (skew: Seconds) {
+    this.#skew = skew;
+  }
+
+  static get clockTolerance (): Seconds {
+    return TimeCoordinator.#tolerance;
+  }
+
+  static set clockTolerance (tolerance: Seconds) {
+    TimeCoordinator.#tolerance = tolerance;
   }
 
   now (): Timestamp {