feat(utilities): add Node-less implementations of signature functions (#563)

Adds runtime-independent implementations of `createHmacSignature` and
`createStorageContentSignature` functions. Those use native
methods/objects instead of Node-specific constructs (`node:crypto`,
`Buffer`).

This allows us to omit polyfills for those modules in downstream
projects, which e.g. shrinks the bundle sizes significantly

See e.g. `apify-client` browser bundle size:

|before|after|
|---|---|
|<img width="392" height="207" alt="image"
src="https://github.com/user-attachments/assets/13eb7dc8-2a43-4374-9eaf-fcc81c64b82e"
/> | <img width="368" height="196" alt="image"
src="https://github.com/user-attachments/assets/ecfb32a4-1541-422c-bbce-136030931a14"
/>|

Related to #537

Author: barjin

packages/utilities/src/hmac.ts

@@ -25,6 +25,8 @@ function encodeBase62(num: bigint) {
  * @param secretKey {string} Secret key used for signing signatures
  * @param message {string} Message to be signed
  * @returns string
+ * @deprecated Use {@link createHmacSignatureAsync} instead, which uses Web Crypto API and
+ * is available in both Node.js and browsers without the need for polyfills.
  */
 export function createHmacSignature(secretKey: string, message: string): string {
     const signature = crypto.createHmac('sha256', secretKey)
@@ -34,3 +36,45 @@ export function createHmacSignature(secretKey: string, message: string): string
 
     return encodeBase62(BigInt(`0x${signature}`));
 }
+
+let webcrypto = globalThis.crypto?.subtle;
+
+async function ensureCryptoSubtleExists() {
+    // this might happen in Node.js versions < 19
+    webcrypto ??= (await import('node:crypto')).webcrypto.subtle as typeof webcrypto;
+}
+
+/**
+ * Generates an HMAC signature and encodes it using Base62.
+ * Base62 encoding reduces the signature length.
+ *
+ * @param secretKey {string} Secret key used for signing signatures
+ * @param message {string} Message to be signed
+ * @returns Promise<string>
+ */
+export async function createHmacSignatureAsync(secretKey: string, message: string): Promise<string> {
+    await ensureCryptoSubtleExists();
+    const encoder = new TextEncoder();
+
+    const key = await webcrypto.importKey(
+        'raw',
+        encoder.encode(secretKey),
+        { name: 'HMAC', hash: 'SHA-256' },
+        false,
+        ['sign'],
+    );
+
+    const signatureBuffer = await webcrypto.sign(
+        'HMAC',
+        key,
+        encoder.encode(message),
+    );
+
+    const signatureArray = new Uint8Array(signatureBuffer);
+    const signatureHex = Array.from(signatureArray)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('')
+        .substring(0, 30);
+
+    return encodeBase62(BigInt(`0x${signatureHex}`));
+}

packages/utilities/src/storages.ts

@@ -1,11 +1,14 @@
-import { createHmacSignature } from './hmac';
+import { createHmacSignature, createHmacSignatureAsync } from './hmac';
 
 /**
  * Creates a secure signature for a resource like a dataset or key-value store.
  * This signature is used to generate a signed URL for authenticated access, which can be expiring or permanent.
  * The signature is created using HMAC with the provided secret key and includes the resource ID, expiration time, and version.
  *
- * Note: expirationMillis is optional. If not provided, the signature will not expire.
+ * Note: expiresInMillis is optional. If not provided, the signature will not expire.
+ *
+ * @deprecated Use {@link createStorageContentSignatureAsync} instead, which uses Web Crypto API and
+ * is available in both Node.js and browsers without the need for polyfills.
  */
 export function createStorageContentSignature({
     resourceId,
@@ -22,3 +25,35 @@ export function createStorageContentSignature({
     const hmac = createHmacSignature(urlSigningSecretKey, `${version}.${expiresAt}.${resourceId}`);
     return Buffer.from(`${version}.${expiresAt}.${hmac}`).toString('base64url');
 }
+
+function typedArrayToBase64Url(typedArray: Uint8Array): string {
+    let binary = '';
+    for (let i = 0; i < typedArray.length; i++) {
+        binary += String.fromCharCode(typedArray[i]);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Creates a secure signature for a resource like a dataset or key-value store.
+ * This signature is used to generate a signed URL for authenticated access, which can be expiring or permanent.
+ * The signature is created using HMAC with the provided secret key and includes the resource ID, expiration time, and version.
+ *
+ * Note: expiresInMillis is optional. If not provided, the signature will not expire.
+ */
+export async function createStorageContentSignatureAsync({
+    resourceId,
+    urlSigningSecretKey,
+    expiresInMillis,
+    version = 0,
+}: {
+    resourceId: string;
+    urlSigningSecretKey: string;
+    expiresInMillis?: number;
+    version?: number;
+}): Promise<string> {
+    const expiresAt = expiresInMillis ? new Date().getTime() + expiresInMillis : 0;
+    const hmac = await createHmacSignatureAsync(urlSigningSecretKey, `${version}.${expiresAt}.${resourceId}`);
+    return typedArrayToBase64Url(new TextEncoder().encode(`${version}.${expiresAt}.${hmac}`));
+}

test/hmac.test.ts

@@ -1,4 +1,4 @@
-import { createHmacSignature } from '@apify/utilities';
+import { createHmacSignature, createHmacSignatureAsync, cryptoRandomObjectId } from '@apify/utilities';
 
 describe('createHmacSignature()', () => {
     it('should create a valid HMAC signature', () => {
@@ -15,3 +15,31 @@ describe('createHmacSignature()', () => {
         }
     });
 });
+
+describe('createHmacSignatureAsync()', () => {
+    it('should create a valid HMAC signature', async () => {
+        const secretKey = 'hmac-secret-key';
+        const message = 'hmac-message-to-be-authenticated';
+        await expect(createHmacSignatureAsync(secretKey, message)).resolves.toBe('pcVagAsudj8dFqdlg7mG');
+    });
+
+    it('should create same HMAC signature, when secretKey and message are same', async () => {
+        const secretKey = 'hmac-same-secret-key';
+        const message = 'hmac-same-message-to-be-authenticated';
+        for (let i = 0; i < 5; i++) {
+            await expect(createHmacSignatureAsync(secretKey, message)).resolves.toBe('FYMcmTIm3idXqleF1Sw5');
+        }
+    });
+
+    it('should create same HMAC signature for same inputs', async () => {
+        for (let i = 0; i < 1e3; i++) {
+            const secretKey = cryptoRandomObjectId();
+            const message = cryptoRandomObjectId();
+
+            const syncHmac = createHmacSignature(secretKey, message);
+            const asyncHmac = await createHmacSignatureAsync(secretKey, message);
+
+            expect(syncHmac).toBe(asyncHmac);
+        }
+    });
+});

test/storages.test.ts

@@ -1,4 +1,4 @@
-import { createStorageContentSignature } from '@apify/utilities';
+import { createStorageContentSignature, createStorageContentSignatureAsync, cryptoRandomObjectId } from '@apify/utilities';
 
 describe('createStorageContentSignature()', () => {
     it('should set expiresAt to 0 for a non-expiring signature', () => {
@@ -32,3 +32,59 @@ describe('createStorageContentSignature()', () => {
         expect(expiresAt).not.toBe('0');
     });
 });
+
+describe('createStorageContentSignatureAsync()', () => {
+    it('should set expiresAt to 0 for a non-expiring signature', async () => {
+        const secretKey = 'hmac-secret-key';
+        const message = 'resource-id';
+
+        const signature = await createStorageContentSignatureAsync({
+            resourceId: message,
+            urlSigningSecretKey: secretKey,
+        });
+
+        const [version, expiresAt, hmac] = Buffer.from(signature, 'base64url').toString('utf8').split('.');
+        expect(signature).toBe('MC4wLjNUd2ZFRTY1OXVmU05zbVM0N2xS');
+        expect(version).toBe('0');
+        expect(expiresAt).toBe('0');
+        expect(hmac).toBe('3TwfEE659ufSNsmS47lR');
+    });
+
+    it('should create a signature with a future expiration timestamp when expiresInMillis is provided', async () => {
+        const secretKey = 'hmac-secret-key';
+        const message = 'resource-id';
+
+        const signature = await createStorageContentSignatureAsync({
+            resourceId: message,
+            urlSigningSecretKey: secretKey,
+            expiresInMillis: 10000,
+        });
+
+        const [version, expiresAt] = Buffer.from(signature, 'base64url').toString('utf8').split('.');
+        expect(version).toBe('0');
+        expect(expiresAt).not.toBe('0');
+    });
+
+    it('should create same storage signature for same inputs', async () => {
+        for (let i = 0; i < 1e3; i++) {
+            const secretKey = cryptoRandomObjectId();
+            const resourceId = cryptoRandomObjectId();
+
+            jest.useFakeTimers().setSystemTime(Date.now());
+
+            const syncSignature = createStorageContentSignature({
+                resourceId,
+                urlSigningSecretKey: secretKey,
+                expiresInMillis: 5000,
+            });
+            const asyncSignature = await createStorageContentSignatureAsync({
+                resourceId,
+                urlSigningSecretKey: secretKey,
+                expiresInMillis: 5000,
+            });
+
+            jest.useRealTimers();
+            expect(syncSignature).toBe(asyncSignature);
+        }
+    });
+});