refactor: rename certificate arg and helper function

Author: ilbertt

CHANGELOG.md

@@ -6,8 +6,9 @@
 - fix: pick the expiry rounding strategy based on the delta, without adding the clock drift to the delta.
 - feat: adds a `clockDriftMs` optional parameter to `Expiry.fromDeltaInMilliseconds` to add to the current time, typically used to specify the clock drift between the client's clock and the IC network clock.
 - fix: account for clock drift when verifying the certificate freshness.
-- feat: adds the `timeDiffMsecs` optional field to the `CreateCertificateOptions` interface, which allows you to adjust the current time when verifying the certificate freshness.
-- feat: adds the `getTimeDiffMsecs` function to the `HttpAgent` class, which returns the time difference in milliseconds between the client's clock and the IC network clock. It also adds the `getTimeDiffMsecs` function to handle the case where the agent is not an instance of `HttpAgent`.
+- feat: adds the `currentTime` optional field to the `CreateCertificateOptions` interface, which allows you to override the current time when verifying the certificate freshness.
+- feat: adds the `getTimeDiffMsecs` function to the `HttpAgent` class, which returns the time difference in milliseconds between the client's clock and the IC network clock.
+- feat: adds the `getAdjustedCurrentTime` to compute the current time adjusted by the input agent's time difference in milliseconds, if the agent is an instance of `HttpAgent`.
 
 ## [3.1.0] - 2025-07-24
 

packages/agent/src/actor.ts

@@ -20,7 +20,7 @@ import { IDL } from '@dfinity/candid';
 import { pollForResponse, type PollingOptions, DEFAULT_POLLING_OPTIONS } from './polling/index.ts';
 import { Principal } from '@dfinity/principal';
 import { Certificate, type CreateCertificateOptions, lookupResultToBuffer } from './certificate.ts';
-import { getTimeDiffMsecs, HttpAgent } from './agent/http/index.ts';
+import { getAdjustedCurrentTime, HttpAgent } from './agent/http/index.ts';
 import { utf8ToBytes } from '@noble/hashes/utils';
 
 /**
@@ -427,7 +427,7 @@ function _createActorMethod(
           rootKey: agent.rootKey,
           canisterId: Principal.from(canisterId),
           blsVerify,
-          timeDiffMsecs: getTimeDiffMsecs(agent),
+          currentTime: getAdjustedCurrentTime(agent),
         });
         const path = [utf8ToBytes('request_status'), requestId];
         const status = new TextDecoder().decode(

packages/agent/src/agent/http/index.ts

@@ -1415,15 +1415,15 @@ export function calculateIngressExpiry(
 }
 
 /**
- * Retrieves the time difference in milliseconds between the client's clock and the IC network clock.
- * See {@link HttpAgent.getTimeDiffMsecs} for more details.
+ * Computes the current time adjusted by the time difference in milliseconds returned by {@link HttpAgent.getTimeDiffMsecs}.
  * @param agent The agent to retrieve the `timeDiffMsecs` property from.
- * @returns The time difference in milliseconds between the client's clock and the IC network clock,
- * if the agent is an {@link HttpAgent} instance. `undefined` otherwise.
+ * @returns The current time adjusted by the agent's time difference in milliseconds. If the agent is not an {@link HttpAgent} instance, fallbacks to the system's current timestamp.
  */
-export function getTimeDiffMsecs(agent: Agent | HttpAgent): number | undefined {
+export function getAdjustedCurrentTime(agent: Agent | HttpAgent): Date {
+  let timestamp = Date.now();
   if ('getTimeDiffMsecs' in agent) {
-    return agent.getTimeDiffMsecs();
+    const timeDiffMsecs = agent.getTimeDiffMsecs();
+    timestamp += timeDiffMsecs;
   }
-  return undefined;
+  return new Date(timestamp);
 }

packages/agent/src/certificate.test.ts

@@ -669,7 +669,7 @@ test('certificate verification passes if the time of the certificate is > 5 minu
     rootKey: hexToBytes(IC_ROOT_KEY),
     canisterId: Principal.fromText('ivg37-qiaaa-aaaab-aaaga-cai'),
     blsVerify: async () => true,
-    timeDiffMsecs,
+    currentTime: new Date(Date.now() + timeDiffMsecs),
   });
   expect(cert).toBeInstanceOf(Cert.Certificate);
 });
@@ -691,7 +691,7 @@ test('certificate verification fails if the time of the certificate is > max age
       canisterId: Principal.fromText('ivg37-qiaaa-aaaab-aaaga-cai'),
       blsVerify: async () => true,
       maxAgeInMinutes,
-      timeDiffMsecs,
+      currentTime: new Date(Date.now() + timeDiffMsecs),
     });
   } catch (error) {
     expect(error).toBeInstanceOf(TrustError);
@@ -729,7 +729,7 @@ test('certificate verification fails if the time of the certificate is > 5 minut
     rootKey: hexToBytes(IC_ROOT_KEY),
     canisterId: Principal.fromText('ivg37-qiaaa-aaaab-aaaga-cai'),
     blsVerify: async () => true,
-    timeDiffMsecs,
+    currentTime: new Date(Date.now() + timeDiffMsecs),
   });
   expect(cert).toBeInstanceOf(Cert.Certificate);
 });

packages/agent/src/certificate.ts

@@ -177,11 +177,10 @@ export interface CreateCertificateOptions {
   disableTimeVerification?: boolean;
 
   /**
-   * The time difference in milliseconds between the client's clock and the IC network clock.
-   * This is used to adjust the current time when verifying the certificate freshness.
-   * @default 0
+   * The current time to use when verifying the certificate freshness.
+   * @default `new Date()`
    */
-  timeDiffMsecs?: number;
+  currentTime?: Date;
 }
 
 export class Certificate {
@@ -196,7 +195,7 @@ export class Certificate {
   public static async create(options: CreateCertificateOptions): Promise<Certificate> {
     const cert = Certificate.createUnverified(options);
 
-    await cert.verify(options.timeDiffMsecs ?? 0);
+    await cert.verify(options.currentTime ?? new Date());
     return cert;
   }
 
@@ -241,9 +240,9 @@ export class Certificate {
     return lookup_subtree(path, this.cert.tree);
   }
 
-  private async verify(timeDiffMsecs: number): Promise<void> {
+  private async verify(currentTime: Date): Promise<void> {
     const rootHash = await reconstruct(this.cert.tree);
-    const derKey = await this._checkDelegationAndGetKey(this.cert.delegation, timeDiffMsecs);
+    const derKey = await this._checkDelegationAndGetKey(this.cert.delegation, currentTime);
     const sig = this.cert.signature;
     const key = extractDER(derKey);
     const msg = concatBytes(domain_sep('ic-state-root'), rootHash);
@@ -259,10 +258,9 @@ export class Certificate {
     // Certificate time verification checks
     if (!this.#disableTimeVerification) {
       const maxAgeInMsec = this._maxAgeInMinutes * MINUTES_TO_MSEC;
-      const now = Date.now();
-      const adjustedNow = now + timeDiffMsecs;
-      const earliestCertificateTime = adjustedNow - maxAgeInMsec;
-      const latestCertificateTime = adjustedNow + FIVE_MINUTES_IN_MSEC;
+      const currentTimestamp = currentTime.getTime();
+      const earliestCertificateTime = currentTimestamp - maxAgeInMsec;
+      const latestCertificateTime = currentTimestamp + FIVE_MINUTES_IN_MSEC;
 
       const certTime = decodeTime(lookupTime);
 
@@ -271,14 +269,20 @@ export class Certificate {
           new CertificateTimeErrorCode(
             this._maxAgeInMinutes,
             certTime,
-            new Date(now),
-            timeDiffMsecs,
+            new Date(),
+            currentTimestamp - Date.now(),
             'past',
           ),
         );
       } else if (certTime.getTime() > latestCertificateTime) {
         throw TrustError.fromCode(
-          new CertificateTimeErrorCode(5, certTime, new Date(now), timeDiffMsecs, 'future'),
+          new CertificateTimeErrorCode(
+            5,
+            certTime,
+            new Date(),
+            currentTimestamp - Date.now(),
+            'future',
+          ),
         );
       }
     }
@@ -297,7 +301,7 @@ export class Certificate {
 
   private async _checkDelegationAndGetKey(
     d: Delegation | undefined,
-    timeDiffMsecs: number,
+    currentTime: Date,
   ): Promise<Uint8Array> {
     if (!d) {
       return this._rootKey;
@@ -315,7 +319,7 @@ export class Certificate {
       throw ProtocolError.fromCode(new CertificateHasTooManyDelegationsErrorCode());
     }
 
-    await cert.verify(timeDiffMsecs);
+    await cert.verify(currentTime);
 
     if (this._canisterId.toString() !== MANAGEMENT_CANISTER_ID) {
       const canisterInRange = check_canister_ranges({

packages/agent/src/polling/index.ts

@@ -21,7 +21,7 @@ import {
 export * as strategy from './strategy.ts';
 import { defaultStrategy } from './strategy.ts';
 import { ReadRequestType, type ReadStateRequest } from '../agent/http/types.ts';
-import { getTimeDiffMsecs, RequestStatusResponseStatus } from '../agent/index.ts';
+import { getAdjustedCurrentTime, RequestStatusResponseStatus } from '../agent/index.ts';
 import { utf8ToBytes } from '@noble/hashes/utils';
 export { defaultStrategy } from './strategy.ts';
 
@@ -161,7 +161,7 @@ export async function pollForResponse(
     rootKey: agent.rootKey,
     canisterId: canisterId,
     blsVerify: options.blsVerify,
-    timeDiffMsecs: getTimeDiffMsecs(agent),
+    currentTime: getAdjustedCurrentTime(agent),
   });
 
   const maybeBuf = lookupResultToBuffer(cert.lookup_path([...path, utf8ToBytes('status')]));