utils: isomorphic Smart CDN URL signing and sha512 signParams (WebCrypto) (#477)

Move the Smart CDN URL assembly (encoding, sorted query, auth_key/exp,
sig=sha256:hex) into src/smartCdn.ts so the synchronous Node signer and
a new async WebCrypto getSignedSmartCdnUrl on the root export share it
and cannot drift. Uppy's @uppy/transloadit-storage and the Console each
carry a browser reimplementation today; this lets them depend on the
package instead. signParams/verifyWebhookSignature also accept sha512,
matching signParamsSync.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kvz

.changeset/isomorphic-smart-cdn.md

@@ -0,0 +1,8 @@
+---
+'@transloadit/utils': minor
+---
+
+Add an isomorphic `getSignedSmartCdnUrl` to the root export. It signs with WebCrypto, so browsers,
+edge runtimes and Node produce byte-identical Smart CDN URLs to the synchronous signer in
+`@transloadit/utils/node`, which now shares the same URL-building code. `signParams` and
+`verifyWebhookSignature` additionally accept `sha512`, matching `signParamsSync`.

packages/utils/README.md

@@ -10,15 +10,25 @@ npm install @transloadit/utils
 
 ## Web / Edge usage
 
+Everything in the root export runs on WebCrypto, so it works in browsers (secure origins only:
+`https://` or `localhost`), edge runtimes, and Node.
+
 ```ts
-import { signParams, verifyWebhookSignature } from '@transloadit/utils'
+import { getSignedSmartCdnUrl, signParams, verifyWebhookSignature } from '@transloadit/utils'
 
 const signature = await signParams(paramsString, authSecret)
 const verified = await verifyWebhookSignature({
   rawBody,
   signatureHeader,
   authSecret,
 })
+const url = await getSignedSmartCdnUrl({
+  workspace,
+  template,
+  input,
+  authKey,
+  authSecret,
+})
 ```
 
 ## Node usage
@@ -55,9 +65,12 @@ for (const source of imageCandidates.sources) {
 
 ## API
 
-- `signParams(paramsString, authSecret, algorithm?)`: WebCrypto-based HMAC signature for params.
+- `signParams(paramsString, authSecret, algorithm?)`: WebCrypto-based HMAC signature for params
+  (`sha1`, `sha256`, `sha384`, `sha512`).
 - `verifyWebhookSignature({ rawBody, signatureHeader, authSecret })`: validates webhook signatures.
+- `getSignedSmartCdnUrl(options)`: async, WebCrypto-based Smart CDN URL signer. Byte-identical to
+  the Node variant below.
 - `signParamsSync(paramsString, authSecret, algorithm?)`: Node-only sync signature helper.
-- `getSignedSmartCdnUrl(options)`: Node-only Smart CDN URL signer.
+- `getSignedSmartCdnUrl(options)` from `@transloadit/utils/node`: synchronous Smart CDN URL signer.
 - `getSignedSmartCdnImageCandidates(options)`: deterministic structured, signed AVIF and WebP
   candidates plus the original fallback URL.

packages/utils/src/index.ts

@@ -1,20 +1,30 @@
-export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384'
+import type { SmartCdnUrlOptions } from './smartCdn.ts'
+
+import { finishSmartCdnUrl, prepareSmartCdnUrl } from './smartCdn.ts'
+
+export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384' | 'sha512'
+
+export type { SmartCdnUrlOptions } from './smartCdn.ts'
 
 export * from './assemblyInstructionsCompiler.ts'
 
 const algorithmMap = {
   sha1: 'SHA-1',
   sha256: 'SHA-256',
   sha384: 'SHA-384',
+  sha512: 'SHA-512',
 } as const
 
 const isSignatureAlgorithm = (value: string): value is SignatureAlgorithm =>
-  value === 'sha1' || value === 'sha256' || value === 'sha384'
+  value === 'sha1' || value === 'sha256' || value === 'sha384' || value === 'sha512'
 
 const getSubtle = (): SubtleCrypto => {
   const subtle = globalThis.crypto?.subtle
   if (!subtle) {
-    throw new Error('Web Crypto is required to sign Transloadit payloads')
+    // Browsers only expose crypto.subtle on secure origins (https:// or localhost).
+    throw new Error(
+      'Web Crypto is required to sign Transloadit payloads; browsers only provide crypto.subtle on secure origins (https:// or localhost)',
+    )
   }
   return subtle
 }
@@ -89,3 +99,13 @@ export const verifyWebhookSignature = async (
   const expected = await hmacHex(normalized, options.authSecret, options.rawBody)
   return safeCompare(expected, signature)
 }
+
+/**
+ * Signs a Smart CDN URL with WebCrypto, so it works in browsers, edge runtimes and Node alike.
+ * Produces the same URL as the synchronous `getSignedSmartCdnUrl` from `@transloadit/utils/node`.
+ */
+export const getSignedSmartCdnUrl = async (opts: SmartCdnUrlOptions): Promise<string> => {
+  const prepared = prepareSmartCdnUrl(opts)
+  const signature = await hmacHex('sha256', opts.authSecret, prepared.stringToSign)
+  return finishSmartCdnUrl(prepared, signature)
+}

packages/utils/src/node.ts

@@ -1,8 +1,12 @@
 import type { SignatureAlgorithm } from './index.ts'
+import type { SmartCdnUrlOptions } from './smartCdn.ts'
 
 import { createHmac } from 'node:crypto'
 
+import { finishSmartCdnUrl, prepareSmartCdnUrl } from './smartCdn.ts'
+
 export type { SignatureAlgorithm } from './index.ts'
+export type { SmartCdnUrlOptions } from './smartCdn.ts'
 
 export type SignatureAlgorithmInput = SignatureAlgorithm | (string & {})
 
@@ -48,38 +52,6 @@ export interface SmartCdnImageCandidatesOptions {
   workspace: string
 }
 
-export type SmartCdnUrlOptions = {
-  /**
-   * Workspace slug.
-   */
-  workspace: string
-  /**
-   * Template slug or template ID.
-   */
-  template: string
-  /**
-   * Input value that is provided as `${fields.input}` in the template.
-   */
-  input: string
-  /**
-   * Additional parameters for the URL query string.
-   */
-  urlParams?: Record<string, boolean | number | string | (boolean | number | string)[]>
-  /**
-   * Expiration timestamp of the signature in milliseconds since UNIX epoch.
-   * Defaults to 1 hour from now.
-   */
-  expiresAt?: number
-  /**
-   * Transloadit auth key used to sign the URL.
-   */
-  authKey: string
-  /**
-   * Transloadit auth secret used to sign the URL.
-   */
-  authSecret: string
-}
-
 const defaultSmartCdnImageFormats: Readonly<Partial<Record<SmartCdnImageFormat, number>>> = {
   avif: 45,
   webp: 75,
@@ -155,36 +127,13 @@ export const signParamsSync = (
   return `${algorithm}:${signature}`
 }
 
+/** Synchronous Smart CDN URL signer (Node). The root export has an async WebCrypto twin. */
 export const getSignedSmartCdnUrl = (opts: SmartCdnUrlOptions): string => {
-  if (opts.workspace == null || opts.workspace === '') throw new TypeError('workspace is required')
-  if (opts.template == null || opts.template === '') throw new TypeError('template is required')
-  if (opts.input == null) throw new TypeError('input is required')
-
-  const workspaceSlug = encodeURIComponent(opts.workspace)
-  const templateSlug = encodeURIComponent(opts.template)
-  const inputField = encodeURIComponent(opts.input)
-  const expiresAt = opts.expiresAt || Date.now() + 60 * 60 * 1000
-
-  const queryParams = new URLSearchParams()
-  for (const [key, value] of Object.entries(opts.urlParams || {})) {
-    if (Array.isArray(value)) {
-      for (const val of value) {
-        queryParams.append(key, `${val}`)
-      }
-    } else {
-      queryParams.append(key, `${value}`)
-    }
-  }
-
-  queryParams.set('auth_key', opts.authKey)
-  queryParams.set('exp', `${expiresAt}`)
-  queryParams.sort()
-
-  const stringToSign = `${workspaceSlug}/${templateSlug}/${inputField}?${queryParams}`
-  const signature = createHmac('sha256', opts.authSecret).update(stringToSign).digest('hex')
-
-  queryParams.set('sig', `sha256:${signature}`)
-  return `https://${workspaceSlug}.tlcdn.com/${templateSlug}/${inputField}?${queryParams}`
+  const prepared = prepareSmartCdnUrl(opts)
+  const signature = createHmac('sha256', opts.authSecret)
+    .update(prepared.stringToSign)
+    .digest('hex')
+  return finishSmartCdnUrl(prepared, signature)
 }
 
 /**

packages/utils/src/smartCdn.ts

@@ -0,0 +1,89 @@
+/**
+ * Smart CDN URL building shared by the synchronous Node signer (`@transloadit/utils/node`) and the
+ * asynchronous WebCrypto signer (`@transloadit/utils`). Only the HMAC differs between the two, so
+ * the string-to-sign and the final URL are assembled here and cannot drift apart.
+ */
+
+export type SmartCdnUrlOptions = {
+  /**
+   * Workspace slug.
+   */
+  workspace: string
+  /**
+   * Template slug or template ID.
+   */
+  template: string
+  /**
+   * Input value that is provided as `${fields.input}` in the template.
+   */
+  input: string
+  /**
+   * Additional parameters for the URL query string.
+   */
+  urlParams?: Record<string, boolean | number | string | (boolean | number | string)[]>
+  /**
+   * Expiration timestamp of the signature in milliseconds since UNIX epoch.
+   * Defaults to 1 hour from now.
+   */
+  expiresAt?: number
+  /**
+   * Transloadit auth key used to sign the URL.
+   */
+  authKey: string
+  /**
+   * Transloadit auth secret used to sign the URL.
+   */
+  authSecret: string
+}
+
+/** A Smart CDN URL with everything but its signature in place. */
+export interface PreparedSmartCdnUrl {
+  /** `workspace/template/input?sortedQuery`, the message the auth secret signs with HMAC-SHA256. */
+  stringToSign: string
+  /** URL-encoded path segments and the sorted query (without `sig`). */
+  parts: {
+    workspaceSlug: string
+    templateSlug: string
+    inputField: string
+    queryParams: URLSearchParams
+  }
+}
+
+/** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
+export const prepareSmartCdnUrl = (opts: SmartCdnUrlOptions): PreparedSmartCdnUrl => {
+  if (opts.workspace == null || opts.workspace === '') throw new TypeError('workspace is required')
+  if (opts.template == null || opts.template === '') throw new TypeError('template is required')
+  if (opts.input == null) throw new TypeError('input is required')
+
+  const workspaceSlug = encodeURIComponent(opts.workspace)
+  const templateSlug = encodeURIComponent(opts.template)
+  const inputField = encodeURIComponent(opts.input)
+  const expiresAt = opts.expiresAt || Date.now() + 60 * 60 * 1000
+
+  const queryParams = new URLSearchParams()
+  for (const [key, value] of Object.entries(opts.urlParams || {})) {
+    if (Array.isArray(value)) {
+      for (const val of value) {
+        queryParams.append(key, `${val}`)
+      }
+    } else {
+      queryParams.append(key, `${value}`)
+    }
+  }
+
+  queryParams.set('auth_key', opts.authKey)
+  queryParams.set('exp', `${expiresAt}`)
+  queryParams.sort()
+
+  return {
+    stringToSign: `${workspaceSlug}/${templateSlug}/${inputField}?${queryParams}`,
+    parts: { workspaceSlug, templateSlug, inputField, queryParams },
+  }
+}
+
+/** Appends the `sig` parameter and returns the final `https://{workspace}.tlcdn.com/…` URL. */
+export const finishSmartCdnUrl = ({ parts }: PreparedSmartCdnUrl, signatureHex: string): string => {
+  const { workspaceSlug, templateSlug, inputField, queryParams } = parts
+  queryParams.set('sig', `sha256:${signatureHex}`)
+  return `https://${workspaceSlug}.tlcdn.com/${templateSlug}/${inputField}?${queryParams}`
+}

packages/utils/test/smartCdn.test.ts

@@ -0,0 +1,89 @@
+import { createHmac } from 'node:crypto'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { getSignedSmartCdnUrl, signParams } from '../src/index.ts'
+import { getSignedSmartCdnUrl as getSignedSmartCdnUrlSync, signParamsSync } from '../src/node.ts'
+
+const options = {
+  authKey: 'test-key',
+  authSecret: 'test-secret',
+  expiresAt: 1_900_000_000_000,
+  input: 'https://assets.example/image.jpg?version=1',
+  template: 'builtin/serve-image@0.0.1',
+  urlParams: { f: ['avif', 'webp'], fit: true, q: 75, w: 640 },
+  workspace: 'test-workspace',
+}
+
+// Computed once with the Node signer; guards both signers against drifting together.
+const knownAnswer =
+  'https://test-workspace.tlcdn.com/builtin%2Fserve-image%400.0.1/' +
+  'https%3A%2F%2Fassets.example%2Fimage.jpg%3Fversion%3D1' +
+  '?auth_key=test-key&exp=1900000000000&f=avif&f=webp&fit=true&q=75&w=640' +
+  '&sig=sha256%3A69e40bc3a447c121a08d059ad9093a39c1beaf5c107a82992d5e78e0d9686f6b'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+describe('getSignedSmartCdnUrl', () => {
+  it('matches the known answer in both the WebCrypto and the Node signer', async () => {
+    expect(getSignedSmartCdnUrlSync(options)).toBe(knownAnswer)
+    await expect(getSignedSmartCdnUrl(options)).resolves.toBe(knownAnswer)
+  })
+
+  it('signs the string to sign with HMAC-SHA256 over the sorted query', async () => {
+    const stringToSign =
+      'test-workspace/builtin%2Fserve-image%400.0.1/' +
+      'https%3A%2F%2Fassets.example%2Fimage.jpg%3Fversion%3D1' +
+      '?auth_key=test-key&exp=1900000000000&f=avif&f=webp&fit=true&q=75&w=640'
+    const expected = createHmac('sha256', options.authSecret).update(stringToSign).digest('hex')
+
+    const url = new URL(await getSignedSmartCdnUrl(options))
+    expect(url.searchParams.get('sig')).toBe(`sha256:${expected}`)
+  })
+
+  it('defaults the expiry to one hour from now in both signers', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
+    const { expiresAt: _expiresAt, ...withoutExpiry } = options
+
+    const syncUrl = getSignedSmartCdnUrlSync(withoutExpiry)
+    const asyncUrl = await getSignedSmartCdnUrl(withoutExpiry)
+
+    expect(new URL(syncUrl).searchParams.get('exp')).toBe(`${1_700_000_000_000 + 60 * 60 * 1000}`)
+    expect(asyncUrl).toBe(syncUrl)
+  })
+
+  it('rejects incomplete options the same way in both signers', async () => {
+    for (const [key, message] of [
+      ['workspace', 'workspace is required'],
+      ['template', 'template is required'],
+      ['input', 'input is required'],
+    ] as const) {
+      const broken = { ...options, [key]: undefined } as unknown as typeof options
+      expect(() => getSignedSmartCdnUrlSync(broken)).toThrow(new TypeError(message))
+      await expect(getSignedSmartCdnUrl(broken)).rejects.toThrow(new TypeError(message))
+    }
+  })
+
+  it('explains that WebCrypto needs a secure origin when crypto.subtle is missing', async () => {
+    vi.stubGlobal('crypto', undefined)
+
+    await expect(getSignedSmartCdnUrl(options)).rejects.toThrow(
+      'Web Crypto is required to sign Transloadit payloads; browsers only provide crypto.subtle on secure origins (https:// or localhost)',
+    )
+  })
+})
+
+describe('signParams', () => {
+  it('produces the same signature as signParamsSync for every supported algorithm', async () => {
+    const paramsString = JSON.stringify({ auth: { key: 'test-key' }, steps: {} })
+
+    for (const algorithm of ['sha1', 'sha256', 'sha384', 'sha512'] as const) {
+      const expected = signParamsSync(paramsString, options.authSecret, algorithm)
+      expect(expected.startsWith(`${algorithm}:`)).toBe(true)
+      await expect(signParams(paramsString, options.authSecret, algorithm)).resolves.toBe(expected)
+    }
+  })
+})