fix: enable certificate freshness check in canister status request

CHANGELOG.md

@@ -15,6 +15,7 @@
 - feat: adds the `hasSyncedTime` method to the `HttpAgent` class, which returns `true` if the time has been synced at least once with the IC network, `false` otherwise.
 - fix: use the effective canister id to delete the node keys from the local cache.
 - docs: add DFINITY Starlight theme to the docs
+- feat: adds the `disableCertificateTimeVerification` optional field to the `CanisterStatus.request` function argument, which allows you to control the `disableTimeVerification` option for the internal `Certificate.create` call.
 
 ## [3.1.0] - 2025-07-24
 

e2e/node/basic/canisterStatus.test.ts

@@ -1,12 +1,23 @@
-import { AgentError, CanisterStatus, HttpAgent } from '@icp-sdk/core/agent';
+import {
+  AgentError,
+  CanisterStatus,
+  CertificateTimeErrorCode,
+  HttpAgent,
+  TrustError,
+} from '@icp-sdk/core/agent';
 import { Principal } from '@icp-sdk/core/principal';
 import { makeAgent } from '../utils/agent.ts';
-import { describe, it, afterEach, expect } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { getCanisterId } from '../utils/canisterid.ts';
+import {
+  MockReplica,
+  mockSyncTimeResponse,
+  prepareV2ReadStateSubnetResponse,
+} from '../utils/mock-replica.ts';
+import { randomIdentity, randomKeyPair } from '../utils/identity.ts';
+
+const MINUTE_TO_MSECS = 60 * 1000;
 
-afterEach(async () => {
-  await Promise.resolve();
-});
 describe('canister status', () => {
   it('should fetch successfully', async () => {
     const counterCanisterId = getCanisterId('counter');
@@ -22,7 +33,7 @@ describe('canister status', () => {
   });
   it('should throw an error if fetchRootKey has not been called', async () => {
     const counterCanisterId = getCanisterId('counter');
-    const agent = new HttpAgent({
+    const agent = HttpAgent.createSync({
       host: `http://127.0.0.1:${process.env.REPLICA_PORT ?? 4943}`,
       verifyQuerySignatures: false,
     });
@@ -54,4 +65,135 @@ describe('canister status', () => {
     const principal = Principal.fromText(subnet.subnetId);
     expect(principal).toBeDefined();
   });
+
+  describe('certificate freshness', () => {
+    const now = new Date('2025-07-25T12:34:56.789Z');
+    const canisterId = Principal.fromText('uxrrr-q7777-77774-qaaaq-cai');
+
+    const subnetKeyPair = randomKeyPair();
+    const nodeIdentity = randomIdentity();
+    const identity = randomIdentity();
+
+    let mockReplica: MockReplica;
+
+    beforeEach(async () => {
+      mockReplica = await MockReplica.create();
+
+      vi.setSystemTime(now);
+    });
+
+    it('should sync time and throw an error if the certificate is not fresh', async () => {
+      const timeDiffMsecs = -(6 * MINUTE_TO_MSECS);
+      const replicaDate = new Date(now.getTime() + timeDiffMsecs);
+
+      const agent = await HttpAgent.create({
+        host: mockReplica.address,
+        rootKey: subnetKeyPair.publicKeyDer,
+        identity,
+      });
+
+      const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
+        nodeIdentity,
+        canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
+        keyPair: subnetKeyPair,
+        date: replicaDate,
+      });
+      // first try, fails
+      mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
+        res.status(200).send(subnetResponseBody);
+      });
+      // syncs time
+      await mockSyncTimeResponse({
+        mockReplica,
+        keyPair: subnetKeyPair,
+        canisterId,
+        date: now, // simulate a replica time that is different from the certificate time
+      });
+
+      expect.assertions(4);
+
+      try {
+        await CanisterStatus.request({
+          canisterId,
+          agent,
+          paths: ['subnet'],
+        });
+      } catch (e) {
+        expect(e).toBeInstanceOf(TrustError);
+        const err = e as TrustError;
+        expect(err.cause.code).toBeInstanceOf(CertificateTimeErrorCode);
+        expect(err.message).toContain('Certificate is signed more than 5 minutes in the past');
+      }
+      expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(4);
+    });
+
+    it('should sync time and succeed if the certificate is not fresh', async () => {
+      const timeDiffMsecs = -(6 * MINUTE_TO_MSECS);
+      const replicaDate = new Date(now.getTime() + timeDiffMsecs);
+
+      const agent = await HttpAgent.create({
+        host: mockReplica.address,
+        rootKey: subnetKeyPair.publicKeyDer,
+        identity,
+      });
+
+      const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
+        nodeIdentity,
+        canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
+        keyPair: subnetKeyPair,
+        date: replicaDate,
+      });
+      // first try, fails
+      mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
+        res.status(200).send(subnetResponseBody);
+      });
+      // sync time, we return the replica date to make the agent sync time properly
+      await mockSyncTimeResponse({
+        mockReplica,
+        keyPair: subnetKeyPair,
+        canisterId,
+        date: new Date(now.getTime() - 4 * MINUTE_TO_MSECS),
+      });
+
+      await expect(
+        CanisterStatus.request({
+          canisterId,
+          agent,
+          paths: ['subnet'],
+        }),
+      ).resolves.not.toThrow();
+      expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(4);
+    });
+
+    it('should not sync time and succeed if the certificate is not fresh and disableTimeVerification is true', async () => {
+      const timeDiffMsecs = -(6 * MINUTE_TO_MSECS);
+      const replicaDate = new Date(now.getTime() + timeDiffMsecs);
+
+      const agent = await HttpAgent.create({
+        host: mockReplica.address,
+        rootKey: subnetKeyPair.publicKeyDer,
+        identity,
+      });
+
+      const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
+        nodeIdentity,
+        canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
+        keyPair: subnetKeyPair,
+        date: replicaDate,
+      });
+      mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
+        res.status(200).send(subnetResponseBody);
+      });
+
+      await expect(
+        CanisterStatus.request({
+          canisterId,
+          agent,
+          paths: ['subnet'],
+          disableCertificateTimeVerification: true,
+        }),
+      ).resolves.not.toThrow();
+      expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(1);
+    });
+  });
 });

e2e/node/basic/queryExpiry.test.ts

@@ -1,15 +1,16 @@
 import { beforeEach, describe, it, vi, expect } from 'vitest';
 import {
   MockReplica,
+  mockSyncTimeResponse,
   prepareV2QueryResponse,
   prepareV2ReadStateSubnetResponse,
-  prepareV2ReadStateTimeResponse,
 } from '../utils/mock-replica.ts';
 import { IDL } from '@icp-sdk/core/candid';
 import { Principal } from '@icp-sdk/core/principal';
-import { KeyPair, randomIdentity, randomKeyPair } from '../utils/identity.ts';
+import { randomIdentity, randomKeyPair } from '../utils/identity.ts';
 import {
   CertificateOutdatedErrorCode,
+  CertificateTimeErrorCode,
   HttpAgent,
   requestIdOf,
   TrustError,
@@ -84,6 +85,12 @@ describe('queryExpiry', () => {
   });
 
   it('should fail if the timestamp is outside the max ingress expiry (no retry)', async () => {
+    const timeDiffMsecs = 6 * MINUTE_TO_MSECS;
+    const futureDate = new Date(now.getTime() + timeDiffMsecs);
+
+    // advance to go over the max ingress expiry (5 minutes)
+    advanceTimeByMilliseconds(timeDiffMsecs);
+
     const agent = await HttpAgent.create({
       host: mockReplica.address,
       rootKey: subnetKeyPair.publicKeyDer,
@@ -105,21 +112,17 @@ describe('queryExpiry', () => {
     mockReplica.setV2QuerySpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(responseBody);
     });
-
-    // advance to go over the max ingress expiry (5 minutes)
-    advanceTimeByMilliseconds(6 * MINUTE_TO_MSECS);
-
     const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
       nodeIdentity,
       canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
       keyPair: subnetKeyPair,
-      date: now,
+      date: futureDate, // make sure the certificate is fresh for this call
     });
     mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(subnetResponseBody);
     });
 
-    expect.assertions(5);
+    expect.assertions(4);
 
     try {
       await actor[greetMethodName](greetReq);
@@ -128,10 +131,12 @@ describe('queryExpiry', () => {
     }
 
     expect(mockReplica.getV2QuerySpy(canisterId.toString())).toHaveBeenCalledTimes(1);
-    expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(0);
   });
 
   it('should retry and fail if the timestamp is outside the max ingress expiry (with retry)', async () => {
+    const timeDiffMsecs = 6 * MINUTE_TO_MSECS;
+    const futureDate = new Date(now.getTime() + timeDiffMsecs);
+
     const agent = await HttpAgent.create({
       host: mockReplica.address,
       rootKey: subnetKeyPair.publicKeyDer,
@@ -153,39 +158,41 @@ describe('queryExpiry', () => {
     mockReplica.setV2QuerySpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(responseBody);
     });
-    mockReplica.setV2QuerySpyImplOnce(canisterId.toString(), (_req, res) => {
-      res.status(200).send(responseBody);
-    });
-    mockReplica.setV2QuerySpyImplOnce(canisterId.toString(), (_req, res) => {
-      res.status(200).send(responseBody);
-    });
-    mockReplica.setV2QuerySpyImplOnce(canisterId.toString(), (_req, res) => {
-      res.status(200).send(responseBody);
-    });
 
     // advance to go over the max ingress expiry (5 minutes)
-    advanceTimeByMilliseconds(6 * MINUTE_TO_MSECS);
+    advanceTimeByMilliseconds(timeDiffMsecs);
 
     const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
       nodeIdentity,
       canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
       keyPair: subnetKeyPair,
       date: now,
     });
+    // fetch subnet keys, fails for certificate freshness checks
     mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(subnetResponseBody);
     });
+    // sync time, keeping a date in the future to make sure the agent still has outdated time
+    await mockSyncTimeResponse({
+      mockReplica,
+      keyPair: subnetKeyPair,
+      date: futureDate,
+      canisterId,
+    });
 
     expect.assertions(5);
 
     try {
       await actor[greetMethodName](greetReq);
     } catch (e) {
-      expectCertificateOutdatedError(e);
+      expect(e).toBeInstanceOf(TrustError);
+      const err = e as TrustError;
+      expect(err.cause.code).toBeInstanceOf(CertificateTimeErrorCode);
+      expect(err.message).toContain('Certificate is signed more than 5 minutes in the past.');
     }
 
-    expect(mockReplica.getV2QuerySpy(canisterId.toString())).toHaveBeenCalledTimes(4);
-    expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(1);
+    expect(mockReplica.getV2QuerySpy(canisterId.toString())).toHaveBeenCalledTimes(1);
+    expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(4);
   });
 
   it('should not retry if the timestamp is outside the max ingress expiry (verifyQuerySignatures=false)', async () => {
@@ -233,7 +240,12 @@ describe('queryExpiry', () => {
     'should account for local clock drift (more than 5 minutes in the %s)',
     async (_, timeDiffMsecs) => {
       const replicaDate = new Date(now.getTime() + timeDiffMsecs);
-      await mockSyncTimeResponse({ mockReplica, keyPair: subnetKeyPair, date: replicaDate });
+      await mockSyncTimeResponse({
+        mockReplica,
+        keyPair: subnetKeyPair,
+        date: replicaDate,
+        canisterId: ICP_LEDGER,
+      });
 
       const agent = await HttpAgent.create({
         host: mockReplica.address,
@@ -308,16 +320,6 @@ describe('queryExpiry', () => {
       res.status(200).send(responseBody);
     });
 
-    const { responseBody: subnetResponseBody } = await prepareV2ReadStateSubnetResponse({
-      nodeIdentity,
-      canisterRanges: [[canisterId.toUint8Array(), canisterId.toUint8Array()]],
-      keyPair: subnetKeyPair,
-      date: replicaDate,
-    });
-    mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
-      res.status(200).send(subnetResponseBody);
-    });
-
     expect.assertions(4);
 
     try {
@@ -366,6 +368,12 @@ describe('queryExpiry', () => {
     mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(subnetResponseBody);
     });
+    await mockSyncTimeResponse({
+      mockReplica,
+      keyPair: subnetKeyPair,
+      date: replicaDate,
+      canisterId,
+    });
     mockReplica.setV2ReadStateSpyImplOnce(canisterId.toString(), (_req, res) => {
       res.status(200).send(subnetResponseBody);
     });
@@ -374,7 +382,7 @@ describe('queryExpiry', () => {
 
     expect(actorResponse).toEqual(greetRes);
     expect(mockReplica.getV2QuerySpy(canisterId.toString())).toHaveBeenCalledTimes(1);
-    expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(1);
+    expect(mockReplica.getV2ReadStateSpy(canisterId.toString())).toHaveBeenCalledTimes(4);
 
     const req = mockReplica.getV2QueryReq(canisterId.toString(), 0);
     expect(requestIdOf(req.content)).toEqual(requestId);
@@ -392,30 +400,3 @@ function expectCertificateOutdatedError(e: unknown) {
   expect(err.cause.code).toBeInstanceOf(CertificateOutdatedErrorCode);
   expect(err.message).toContain('Certificate is stale');
 }
-
-async function mockSyncTimeResponse({
-  mockReplica,
-  keyPair,
-  date,
-  canisterId,
-}: {
-  mockReplica: MockReplica;
-  keyPair: KeyPair;
-  date?: Date;
-  canisterId?: Principal | string;
-}) {
-  canisterId = Principal.from(canisterId ?? ICP_LEDGER).toText();
-  const { responseBody: timeResponseBody } = await prepareV2ReadStateTimeResponse({
-    keyPair,
-    date,
-  });
-  mockReplica.setV2ReadStateSpyImplOnce(canisterId, (_req, res) => {
-    res.status(200).send(timeResponseBody);
-  });
-  mockReplica.setV2ReadStateSpyImplOnce(canisterId, (_req, res) => {
-    res.status(200).send(timeResponseBody);
-  });
-  mockReplica.setV2ReadStateSpyImplOnce(canisterId, (_req, res) => {
-    res.status(200).send(timeResponseBody);
-  });
-}