feat: allows httpagent.call to be provided with a nonce (#983)

* feat: refactor nonce logic to prioritize options and ensure compatibility with ArrayBuffer and Uint8Array

* docs: jsdoc comments for call

Author: krpeacock

docs/CHANGELOG.md

@@ -3,6 +3,8 @@
 
 ## [Unreleased]
 
+### Changed
+
 - fix:  Bring Candid decoding of `opt` types up to Candid spec:
   In particular, when decoding at an `opt` type:
   - If the wire type is an `opt` type, decode its payload at the expected content type
@@ -19,6 +21,7 @@
 
 ### Added
 
+- feat: refactor nonce logic to prioritize options and ensure compatibility with ArrayBuffer and Uint8Array
 - test: added e2e test for CanisterStatus requesting a subnet path, as a reference for getting the subnet id of a given canister id
 
 ## [2.3.0] - 2025-02-07

packages/agent/src/agent/http/http.test.ts

@@ -240,6 +240,32 @@ test('readState should not call transformers if request is passed', async () =>
   expect(transformMock).toBeCalledTimes(1);
 });
 
+test('use provided nonce for call', async () => {
+  const mockFetch: jest.Mock = jest.fn(() => {
+    return Promise.resolve(
+      new Response(null, {
+        status: 200,
+      }),
+    );
+  });
+
+  const canisterId: Principal = Principal.fromText('2chl6-4hpzw-vqaaa-aaaaa-c');
+  const nonce = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]) as Nonce;
+
+  const httpAgent = new HttpAgent({ fetch: mockFetch, host: 'http://localhost' });
+
+  const methodName = 'greet';
+  const arg = new ArrayBuffer(32);
+
+  const callResponse = await httpAgent.call(canisterId, {
+    methodName,
+    arg,
+    nonce,
+  });
+
+  expect(callResponse?.requestDetails?.nonce).toEqual(nonce);
+});
+
 test('redirect avoid', async () => {
   function checkUrl(base: string, result: string) {
     const httpAgent = new HttpAgent({ host: base });

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

@@ -447,20 +447,33 @@ export class HttpAgent implements Agent {
     return (await this.#identity).getPrincipal();
   }
 
+  /**
+   * Makes a call to a canister method.
+   * @param canisterId - The ID of the canister to call. Can be a Principal or a string.
+   * @param options - Options for the call.
+   * @param options.methodName - The name of the method to call.
+   * @param options.arg - The argument to pass to the method, as an ArrayBuffer.
+   * @param options.effectiveCanisterId - (Optional) The effective canister ID, if different from the target canister ID.
+   * @param options.callSync - (Optional) Whether to use synchronous call mode. Defaults to true.
+   * @param options.nonce - (Optional) A unique nonce for the request. If provided, it will override any nonce set by transforms.
+   * @param identity - (Optional) The identity to use for the call. If not provided, the agent's current identity will be used.
+   * @returns A promise that resolves to the response of the call, including the request ID and response details.
+   */
   public async call(
     canisterId: Principal | string,
     options: {
       methodName: string;
       arg: ArrayBuffer;
       effectiveCanisterId?: Principal | string;
       callSync?: boolean;
+      nonce?: Uint8Array | Nonce;
     },
     identity?: Identity | Promise<Identity>,
   ): Promise<SubmitResponse> {
     await this.#rootKeyGuard();
     // TODO - restore this value
     const callSync = options.callSync ?? true;
-    const id = await (identity !== undefined ? await identity : await this.#identity);
+    const id = await(identity !== undefined ? await identity : await this.#identity);
     if (!id) {
       throw new IdentityInvalidError(
         "This identity has expired due this application's security policy. Please refresh your authentication.",
@@ -504,13 +517,31 @@ export class HttpAgent implements Agent {
       body: submit,
     })) as HttpAgentSubmitRequest;
 
-    const nonce: Nonce | undefined = transformedRequest.body.nonce
-      ? toNonce(transformedRequest.body.nonce)
-      : undefined;
+    // Determine the nonce to use for the request
+    let nonce: Nonce | undefined;
+
+    // Check if a nonce is provided in the options and convert it to the correct type
+    if (options?.nonce) {
+      nonce = toNonce(options.nonce);
+    }
+    // If no nonce is provided in the options, check the transformedRequest body
+    else if (transformedRequest.body.nonce) {
+      nonce = toNonce(transformedRequest.body.nonce);
+    }
+    // If no nonce is found, set it to undefined
+    else {
+      nonce = undefined;
+    }
 
+    // Assign the determined nonce to the submit object
     submit.nonce = nonce;
 
-    function toNonce(buf: ArrayBuffer): Nonce {
+    /**
+     * Converts an ArrayBuffer or Uint8Array to a Nonce type.
+     * @param buf - The buffer to convert.
+     * @returns The buffer as a Nonce.
+     */
+    function toNonce(buf: ArrayBuffer | Uint8Array): Nonce {
       return new Uint8Array(buf) as Nonce;
     }