feat: add url signing and test cases

manu4543 · manu4543 · commit b1594d8e0e41 · 2025-09-01T13:27:56.000+05:30
diff --git a/src/lib/crypto-utils.ts b/src/lib/crypto-utils.ts
@@ -0,0 +1,37 @@
+/**
+ * Simple synchronous crypto utilities for ImageKit SDK
+ *
+ * This module provides HMAC-SHA1 functionality using Node.js crypto module.
+ * URL signing is only supported in Node.js runtime.
+ */
+
+import { ImageKitError } from '../core/error';
+
+/**
+ * Creates an HMAC-SHA1 hash using Node.js crypto module
+ *
+ * @param key - The secret key for HMAC generation
+ * @param data - The data to be signed
+ * @returns Hex-encoded HMAC-SHA1 hash
+ * @throws ImageKitError if crypto module is not available or operation fails
+ */
+export function createHmacSha1(key: string, data: string): string {
+  let crypto: any;
+
+  try {
+    crypto = require('crypto');
+  } catch (err) {
+    throw new ImageKitError(
+      'URL signing requires Node.js crypto module which is not available in this runtime. ' +
+        'Please use Node.js environment for URL signing functionality.',
+    );
+  }
+
+  try {
+    return crypto.createHmac('sha1', key).update(data, 'utf8').digest('hex');
+  } catch (error) {
+    throw new ImageKitError(
+      `Failed to generate HMAC-SHA1 signature: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    );
+  }
+}
diff --git a/src/lib/transformation-utils.ts b/src/lib/transformation-utils.ts
@@ -54,6 +54,7 @@ export const supportedTransforms: { [key: string]: string } = {
   aiChangeBackground: 'e-changebg',
   aiRemoveBackground: 'e-bgremove',
   aiRemoveBackgroundExternal: 'e-removedotbg',
+  aiEdit: 'e-edit',
   contrastStretch: 'e-contrast',
   shadow: 'e-shadow',
   sharpen: 'e-sharpen',
@@ -86,9 +87,6 @@ export const supportedTransforms: { [key: string]: string } = {
 
   // Raw pass-through
   raw: 'raw',
-
-  // Additional missing mappings from JS SDK
-  aiEdit: 'e-edit',
 };
 
 export default {
diff --git a/src/resources/helper.ts b/src/resources/helper.ts
@@ -13,11 +13,127 @@ import type {
   SolidColorOverlay,
 } from './shared';
 import transformationUtils, { safeBtoa } from '../lib/transformation-utils';
+import { createHmacSha1 } from '../lib/crypto-utils';
 
 const TRANSFORMATION_PARAMETER = 'tr';
+const SIGNATURE_PARAMETER = 'ik-s';
+const TIMESTAMP_PARAMETER = 'ik-t';
+const DEFAULT_TIMESTAMP = 9999999999;
 const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._/ ]*$');
 const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._ ]*$');
 
+export class Helper extends APIResource {
+  constructor(client: ImageKit) {
+    super(client);
+  }
+
+  /**
+   * Builds a source URL with the given options.
+   *
+   * @param opts - The options for building the source URL.
+   * @returns The constructed source URL.
+   */
+  buildSrc(opts: SrcOptions): string {
+    opts.urlEndpoint = opts.urlEndpoint || '';
+    opts.src = opts.src || '';
+    opts.transformationPosition = opts.transformationPosition || 'query';
+
+    if (!opts.src) {
+      return '';
+    }
+
+    const isAbsoluteURL = opts.src.startsWith('http://') || opts.src.startsWith('https://');
+
+    var urlObj, isSrcParameterUsedForURL, urlEndpointPattern;
+
+    try {
+      if (!isAbsoluteURL) {
+        urlEndpointPattern = new URL(opts.urlEndpoint).pathname;
+        urlObj = new URL(pathJoin([opts.urlEndpoint.replace(urlEndpointPattern, ''), opts.src]));
+      } else {
+        urlObj = new URL(opts.src!);
+        isSrcParameterUsedForURL = true;
+      }
+    } catch (e) {
+      return '';
+    }
+
+    for (var i in opts.queryParameters) {
+      urlObj.searchParams.append(i, String(opts.queryParameters[i]));
+    }
+
+    var transformationString = this.buildTransformationString(opts.transformation);
+
+    if (transformationString && transformationString.length) {
+      if (!transformationUtils.addAsQueryParameter(opts) && !isSrcParameterUsedForURL) {
+        urlObj.pathname = pathJoin([
+          TRANSFORMATION_PARAMETER + transformationUtils.getChainTransformDelimiter() + transformationString,
+          urlObj.pathname,
+        ]);
+      }
+    }
+
+    if (urlEndpointPattern) {
+      urlObj.pathname = pathJoin([urlEndpointPattern, urlObj.pathname]);
+    } else {
+      urlObj.pathname = pathJoin([urlObj.pathname]);
+    }
+
+    // First, build the complete URL with transformations
+    let finalUrl = urlObj.href;
+
+    // Add transformation parameter manually to avoid URL encoding
+    // URLSearchParams.set() would encode commas and colons in transformation string,
+    // It would work correctly but not very readable e.g., "w-300,h-400" is better than "w-300%2Ch-400"
+    if (transformationString && transformationString.length) {
+      if (transformationUtils.addAsQueryParameter(opts) || isSrcParameterUsedForURL) {
+        const separator = urlObj.searchParams.toString() ? '&' : '?';
+        finalUrl = `${finalUrl}${separator}${TRANSFORMATION_PARAMETER}=${transformationString}`;
+      }
+    }
+
+    // Then sign the URL if needed
+    if (opts.signed === true || (opts.expiresIn && opts.expiresIn > 0)) {
+      const expiryTimestamp = getSignatureTimestamp(opts.expiresIn);
+
+      const urlSignature = getSignature({
+        privateKey: this._client.privateAPIKey,
+        url: finalUrl,
+        urlEndpoint: opts.urlEndpoint,
+        expiryTimestamp,
+      });
+
+      // Add signature parameters to the final URL
+      // Use URL object to properly determine if we need ? or & separator
+      const finalUrlObj = new URL(finalUrl);
+      const hasExistingParams = finalUrlObj.searchParams.toString().length > 0;
+      const separator = hasExistingParams ? '&' : '?';
+      let signedUrl = finalUrl;
+
+      if (expiryTimestamp && expiryTimestamp !== DEFAULT_TIMESTAMP) {
+        signedUrl += `${separator}${TIMESTAMP_PARAMETER}=${expiryTimestamp}`;
+        signedUrl += `&${SIGNATURE_PARAMETER}=${urlSignature}`;
+      } else {
+        signedUrl += `${separator}${SIGNATURE_PARAMETER}=${urlSignature}`;
+      }
+
+      return signedUrl;
+    }
+
+    return finalUrl;
+  }
+
+  /**
+   * Builds a transformation string from the given transformations.
+   *
+   * @param transformation - The transformations to apply.
+   * @returns The constructed transformation string.
+   */
+  buildTransformationString(transformation: Transformation[] | undefined): string {
+    return buildTransformationString(transformation);
+  }
+}
+
 function removeTrailingSlash(str: string): string {
   if (typeof str == 'string' && str[str.length - 1] == '/') {
     str = str.substring(0, str.length - 1);
@@ -231,7 +347,7 @@ function buildTransformationString(transformation: Transformation[] | undefined)
       } else if (key === 'raw') {
         parsedTransformStep.push(currentTransform[key] as string);
       } else {
-        if (transformKey === 'di') {
+        if (transformKey === 'di' || transformKey === 'ff') {
           value = removeTrailingSlash(removeLeadingSlash((value as string) || ''));
           value = value.replace(/\//g, '@@');
         }
@@ -256,84 +372,46 @@ function buildTransformationString(transformation: Transformation[] | undefined)
   return parsedTransforms.join(transformationUtils.getChainTransformDelimiter());
 }
 
-export class Helper extends APIResource {
-  constructor(client: ImageKit) {
-    super(client);
-  }
+/**
+ * Calculates the expiry timestamp for URL signing
+ *
+ * @param seconds - Number of seconds from now when the URL should expire
+ * @returns Unix timestamp for expiry, or DEFAULT_TIMESTAMP if invalid/not provided
+ */
+function getSignatureTimestamp(seconds: number | undefined): number {
+  if (!seconds || seconds <= 0) return DEFAULT_TIMESTAMP;
 
-  /**
-   * Builds a source URL with the given options.
-   *
-   * @param opts - The options for building the source URL.
-   * @returns The constructed source URL.
-   */
-  buildSrc(opts: SrcOptions): string {
-    opts.urlEndpoint = opts.urlEndpoint || '';
-    opts.src = opts.src || '';
-    opts.transformationPosition = opts.transformationPosition || 'query';
+  const sec = parseInt(String(seconds), 10);
+  if (!sec || isNaN(sec)) return DEFAULT_TIMESTAMP;
 
-    if (!opts.src) {
-      return '';
-    }
-
-    const isAbsoluteURL = opts.src.startsWith('http://') || opts.src.startsWith('https://');
-
-    var urlObj, isSrcParameterUsedForURL, urlEndpointPattern;
-
-    try {
-      if (!isAbsoluteURL) {
-        urlEndpointPattern = new URL(opts.urlEndpoint).pathname;
-        urlObj = new URL(pathJoin([opts.urlEndpoint.replace(urlEndpointPattern, ''), opts.src]));
-      } else {
-        urlObj = new URL(opts.src!);
-        isSrcParameterUsedForURL = true;
-      }
-    } catch (e) {
-      return '';
-    }
-
-    for (var i in opts.queryParameters) {
-      urlObj.searchParams.append(i, String(opts.queryParameters[i]));
-    }
-
-    var transformationString = this.buildTransformationString(opts.transformation);
-
-    if (transformationString && transformationString.length) {
-      if (!transformationUtils.addAsQueryParameter(opts) && !isSrcParameterUsedForURL) {
-        urlObj.pathname = pathJoin([
-          TRANSFORMATION_PARAMETER + transformationUtils.getChainTransformDelimiter() + transformationString,
-          urlObj.pathname,
-        ]);
-      }
-    }
-
-    if (urlEndpointPattern) {
-      urlObj.pathname = pathJoin([urlEndpointPattern, urlObj.pathname]);
-    } else {
-      urlObj.pathname = pathJoin([urlObj.pathname]);
-    }
+  const currentTimestamp = Math.floor(new Date().getTime() / 1000);
+  return currentTimestamp + sec;
+}
 
-    if (transformationString && transformationString.length) {
-      if (transformationUtils.addAsQueryParameter(opts) || isSrcParameterUsedForURL) {
-        if (urlObj.searchParams.toString() !== '') {
-          // In 12 node.js .size was not there. So, we need to check if it is an object or not.
-          return `${urlObj.href}&${TRANSFORMATION_PARAMETER}=${transformationString}`;
-        } else {
-          return `${urlObj.href}?${TRANSFORMATION_PARAMETER}=${transformationString}`;
-        }
-      }
-    }
+/**
+ * Generates an HMAC-SHA1 signature for URL signing
+ *
+ * @param opts - Options containing private key, URL, endpoint, and expiry timestamp
+ * @returns Hex-encoded signature, or empty string if required params missing
+ */
+function getSignature(opts: {
+  privateKey: string;
+  url: string;
+  urlEndpoint: string;
+  expiryTimestamp: number;
+}): string {
+  if (!opts.privateKey || !opts.url || !opts.urlEndpoint) return '';
+
+  // Create the string to sign: relative path + expiry timestamp
+  const stringToSign =
+    opts.url.replace(addTrailingSlash(opts.urlEndpoint), '') + String(opts.expiryTimestamp);
+
+  return createHmacSha1(opts.privateKey, stringToSign);
+}
 
-    return urlObj.href;
-  }
-
-  /**
-   * Builds a transformation string from the given transformations.
-   *
-   * @param transformation - The transformations to apply.
-   * @returns The constructed transformation string.
-   */
-  buildTransformationString(transformation: Transformation[] | undefined): string {
-    return buildTransformationString(transformation);
+function addTrailingSlash(str: string): string {
+  if (typeof str === 'string' && str[str.length - 1] !== '/') {
+    str = str + '/';
   }
+  return str;
 }
diff --git a/tests/url-generation/overlay.test.ts b/tests/url-generation/overlay.test.ts
@@ -414,6 +414,30 @@ describe('Overlay encoding test cases', function () {
     expect(url).toBe(`https://ik.imagekit.io/demo/tr:l-text,i-Manu,l-end/medium_cafe_B1iTdD0C.jpg`);
   });
 
+  it('Handle slash in fontFamily in case of custom fonts', function () {
+    const url = client.helper.buildSrc({
+      transformationPosition: 'path',
+      urlEndpoint: 'https://ik.imagekit.io/demo',
+      src: '/medium_cafe_B1iTdD0C.jpg',
+      transformation: [
+        {
+          overlay: {
+            type: 'text',
+            text: 'Manu',
+            transformation: [
+              {
+                fontFamily: 'nested-path/Poppins-Regular_Q15GrYWmL.ttf',
+              },
+            ],
+          },
+        },
+      ],
+    });
+    expect(url).toBe(
+      `https://ik.imagekit.io/demo/tr:l-text,i-Manu,ff-nested-path@@Poppins-Regular_Q15GrYWmL.ttf,l-end/medium_cafe_B1iTdD0C.jpg`,
+    );
+  });
+
   it('Simple text overlay with spaces and other safe characters, should use i instead of ie', function () {
     const url = client.helper.buildSrc({
       transformationPosition: 'path',
diff --git a/tests/url-generation/signing.test.ts b/tests/url-generation/signing.test.ts
