chore(core): implement NTP midpoint candidateSkew formula

Author: siddsriv

packages-internal/core/src/submodules/httpAuthSchemes/aws_sdk/AwsSdkSigV4ASigner.ts

@@ -31,6 +31,8 @@ export class AwsSdkSigV4ASigner extends AwsSdkSigV4Signer {
     ).join(",");
 
     signingProperties._preRequestSystemClockOffset = config.systemClockOffset;
+    // Capture the raw send time (no skew applied) for the midpoint skew formula.
+    signingProperties._requestSentAt = Date.now();
     const signedRequest = await signer.sign(httpRequest, {
       signingDate: getSkewCorrectedDate(config.systemClockOffset),
       signingRegion: multiRegionOverride,

packages-internal/core/src/submodules/httpAuthSchemes/aws_sdk/AwsSdkSigV4Signer.ts

@@ -118,6 +118,8 @@ export class AwsSdkSigV4Signer implements HttpSigner {
 
     // Capture the clock offset before signing so errorHandler can detect concurrent corrections.
     signingProperties._preRequestSystemClockOffset = config.systemClockOffset;
+    // Capture the raw send time (no skew applied) for the midpoint skew formula.
+    signingProperties._requestSentAt = Date.now();
     const signedRequest = await signer.sign(httpRequest, {
       signingDate: getSkewCorrectedDate(config.systemClockOffset),
       signingRegion: signingRegion,
@@ -133,7 +135,8 @@ export class AwsSdkSigV4Signer implements HttpSigner {
       if (serverTime) {
         const config = throwSigningPropertyError("config", signingProperties.config as AwsSdkSigV4Config | undefined);
         const preRequestOffset = signingProperties._preRequestSystemClockOffset as number | undefined;
-        const newOffset = getUpdatedSystemClockOffset(serverTime, config.systemClockOffset);
+        const timeRequestSent = signingProperties._requestSentAt as number | undefined;
+        const newOffset = getUpdatedSystemClockOffset(serverTime, config.systemClockOffset, timeRequestSent);
 
         const isLocalCorrection = newOffset !== config.systemClockOffset;
         const isConcurrentCorrection = preRequestOffset !== undefined && preRequestOffset !== newOffset;
@@ -152,7 +155,8 @@ export class AwsSdkSigV4Signer implements HttpSigner {
     const dateHeader = getDateHeader(httpResponse);
     if (dateHeader) {
       const config = throwSigningPropertyError("config", signingProperties.config as AwsSdkSigV4Config | undefined);
-      config.systemClockOffset = getUpdatedSystemClockOffset(dateHeader, config.systemClockOffset);
+      const timeRequestSent = signingProperties._requestSentAt as number | undefined;
+      config.systemClockOffset = getUpdatedSystemClockOffset(dateHeader, config.systemClockOffset, timeRequestSent);
     }
   }
 }

packages-internal/core/src/submodules/httpAuthSchemes/utils/getUpdatedSystemClockOffset.spec.ts

@@ -19,21 +19,43 @@ describe(getUpdatedSystemClockOffset.name, () => {
     expect(getUpdatedSystemClockOffset(mockClockTime.toString(), mockSystemClockOffset)).toEqual(mockSystemClockOffset);
   });
 
-  describe("returns difference between serverTime and current time when clock is skewed", () => {
-    const dateDotNowFn = Date.now;
-
+  describe("legacy path (no timeRequestSent): returns serverTime - timeResponseReceived when clock is skewed", () => {
     beforeEach(() => {
       vi.mocked(isClockSkewed).mockReturnValue(true);
-      vi.spyOn(Date, "now").mockReturnValueOnce(mockClockTime.getTime());
-    });
-
-    afterEach(() => {
-      Date.now = dateDotNowFn;
+      vi.spyOn(Date, "now").mockReturnValue(mockClockTime.getTime());
     });
 
     it.each([1000, 100000])("difference: %d", (difference) => {
       const updatedClockTime = new Date(mockClockTime.getTime() + difference);
       expect(getUpdatedSystemClockOffset(updatedClockTime.toString(), mockSystemClockOffset)).toEqual(difference);
     });
   });
+
+  describe("midpoint path (with timeRequestSent): returns serverTime - midpoint when clock is skewed", () => {
+    beforeEach(() => {
+      vi.mocked(isClockSkewed).mockReturnValue(true);
+    });
+
+    it("computes candidateSkew using NTP midpoint formula", () => {
+      // timeRequestSent = T, timeResponseReceived = T + 2000 (2s round trip)
+      // serverTime = T + 1000 (server time halfway through round trip = zero drift)
+      // midpoint = (T + T+2000) / 2 = T + 1000
+      // candidateSkew = (T+1000) - (T+1000) = 0
+      const T = mockClockTime.getTime();
+      vi.spyOn(Date, "now").mockReturnValue(T + 2000); // timeResponseReceived
+      const serverTime = new Date(T + 1000);
+      expect(getUpdatedSystemClockOffset(serverTime.toUTCString(), mockSystemClockOffset, T)).toEqual(0);
+    });
+
+    it("computes positive candidateSkew when server is ahead of midpoint", () => {
+      // timeRequestSent = T, timeResponseReceived = T + 2000
+      // serverTime = T + 5 * 60 * 1000 (5 minutes ahead)
+      // midpoint = T + 1000
+      // candidateSkew = (T + 300000) - (T + 1000) = 299000
+      const T = mockClockTime.getTime();
+      vi.spyOn(Date, "now").mockReturnValue(T + 2000);
+      const serverTime = new Date(T + 300000);
+      expect(getUpdatedSystemClockOffset(serverTime.toUTCString(), mockSystemClockOffset, T)).toEqual(299000);
+    });
+  });
 });

packages-internal/core/src/submodules/httpAuthSchemes/utils/getUpdatedSystemClockOffset.ts

@@ -3,16 +3,38 @@ import { isClockSkewed } from "./isClockSkewed";
 /**
  * @internal
  *
- * If clock is skewed, it returns the difference between serverTime and current time.
- * If clock is not skewed, it returns currentSystemClockOffset.
+ * Computes an updated system clock offset from a server Date header.
  *
- * @param clockTime The string value of the server time.
- * @param currentSystemClockOffset The current system clock offset.
+ * When `timeRequestSent` is provided, uses the midpoint formula:
+ *   elapsed        = timeResponseReceived - timeRequestSent
+ *   midpoint       = (timeRequestSent + timeResponseReceived) / 2
+ *   candidateSkew  = serverTime - midpoint
+ *
+ * When `timeRequestSent` is absent (legacy callers), falls back to:
+ *   candidateSkew  = serverTime - timeResponseReceived
+ *
+ * Returns `currentSystemClockOffset` unchanged if the candidate skew does not
+ * exceed the detection threshold.
+ *
+ * @param clockTime The string value of the Date response header.
+ * @param currentSystemClockOffset The current system clock offset in milliseconds.
+ * @param timeRequestSent The raw client time (ms) at which the request was sent.
  */
-export const getUpdatedSystemClockOffset = (clockTime: string, currentSystemClockOffset: number): number => {
-  const clockTimeInMs = Date.parse(clockTime);
-  if (isClockSkewed(clockTimeInMs, currentSystemClockOffset)) {
-    return clockTimeInMs - Date.now();
+export const getUpdatedSystemClockOffset = (
+  clockTime: string,
+  currentSystemClockOffset: number,
+  timeRequestSent?: number
+): number => {
+  const serverTime = Date.parse(clockTime);
+  const timeResponseReceived = Date.now();
+
+  const candidateSkew =
+    timeRequestSent !== undefined
+      ? serverTime - (timeRequestSent + timeResponseReceived) / 2
+      : serverTime - timeResponseReceived;
+
+  if (isClockSkewed(serverTime, currentSystemClockOffset)) {
+    return candidateSkew;
   }
   return currentSystemClockOffset;
 };