@transloadit/utils 4.5.1 → 4.7.0

package/README.md

@@ -10,8 +10,18 @@ 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,
+  getSmartCdnUrl,
+  parseSmartCdnUrl,
+  signParams,
+  stripSmartCdnAuth,
+  verifyWebhookSignature,
+} from '@transloadit/utils'
 
 const signature = await signParams(paramsString, authSecret)
 const verified = await verifyWebhookSignature({
@@ -19,8 +29,38 @@ const verified = await verifyWebhookSignature({
   signatureHeader,
   authSecret,
 })
+const url = await getSignedSmartCdnUrl({
+  workspace,
+  template,
+  input,
+  authKey,
+  authSecret,
+})
 ```
 
+### Smart CDN URL grammar
+
+The URL builders and parser share one grammar, so a URL built here parses back into the options
+that built it (and vice versa):
+
+```ts
+// Unsigned, for workspaces that do not require signature authentication.
+const publicUrl = getSmartCdnUrl({ workspace, template, input, urlParams: { w: 640 } })
+
+// Inverse of the builders: percent-decodes once, keeps repeated params as arrays,
+// and returns `auth_key`/`exp`/`sig` separately as `auth`.
+const { workspace, template, input, urlParams, auth } = parseSmartCdnUrl(url)
+
+// Drops `auth_key`, `exp`, `sig` (and api2's `hsh`), leaving every other byte untouched.
+const unsigned = stripSmartCdnAuth(url)
+```
+
+Both builders accept a `baseUrl` that replaces `https://{workspace}.tlcdn.com`, for example a local
+api2's URL Transform endpoint `https://api2-devdock.transloadit.dev/file/{workspace}` (a literal
+`{workspace}` is substituted). The signature does not cover the host, so treat `baseUrl` as trusted
+configuration and never derive it from user input. Pass the same `baseUrl` to `parseSmartCdnUrl` to
+parse URLs built with it.
+
 ## Node usage
 
 ```ts
@@ -55,9 +95,17 @@ 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.
+- `getSmartCdnUrl(options)`: unsigned Smart CDN URL builder (same options minus credentials/expiry).
+- `parseSmartCdnUrl(url, { baseUrl?, workspace? })`: parses a Smart CDN URL into
+  `{ workspace, template, input, urlParams, auth?, baseUrl? }`; throws on anything else.
+- `stripSmartCdnAuth(url)`: removes the signature parameters, byte-for-byte otherwise.
+- `baseUrl` (option of both builders): trusted replacement for `https://{workspace}.tlcdn.com`.
 - `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.

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384';
+import type { SmartCdnUrlOptions } from './smartCdn.ts';
+export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384' | 'sha512';
+export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
 export * from './assemblyInstructionsCompiler.ts';
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
 export declare const signParams: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithm) => Promise<string>;
 export type VerifyWebhookSignatureOptions = {
     rawBody: string;
@@ -7,4 +10,9 @@ export type VerifyWebhookSignatureOptions = {
     authSecret: string;
 };
 export declare const verifyWebhookSignature: (options: VerifyWebhookSignatureOptions) => Promise<boolean>;
+/**
+ * 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 declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => Promise<string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7D,cAAc,mCAAmC,CAAA;AAiDjD,eAAO,MAAM,UAAU,GACrB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,kBAA6B,KACvC,OAAO,CAAC,MAAM,CAOhB,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,6BAA6B,KACrC,OAAO,CAAC,OAAO,CAkBjB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAIvD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAExE,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAEtB,cAAc,mCAAmC,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAqDnF,eAAO,MAAM,UAAU,GACrB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,kBAA6B,KACvC,OAAO,CAAC,MAAM,CAOhB,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,6BAA6B,KACrC,OAAO,CAAC,OAAO,CAkBjB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,kBAAkB,KAAG,OAAO,CAAC,MAAM,CAInF,CAAA"}

package/dist/index.js

@@ -1,14 +1,18 @@
+import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
 export * from "./assemblyInstructionsCompiler.js";
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
 const algorithmMap = {
     sha1: 'SHA-1',
     sha256: 'SHA-256',
     sha384: 'SHA-384',
+    sha512: 'SHA-512',
 };
-const isSignatureAlgorithm = (value) => value === 'sha1' || value === 'sha256' || value === 'sha384';
+const isSignatureAlgorithm = (value) => value === 'sha1' || value === 'sha256' || value === 'sha384' || value === 'sha512';
 const getSubtle = () => {
     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;
 };
@@ -55,3 +59,12 @@ export const verifyWebhookSignature = async (options) => {
     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) => {
+    const prepared = prepareSmartCdnUrl(opts);
+    const signature = await hmacHex('sha256', opts.authSecret, prepared.stringToSign);
+    return finishSmartCdnUrl(prepared, signature);
+};

package/dist/node.d.ts

@@ -1,5 +1,8 @@
 import type { SignatureAlgorithm } from './index.ts';
+import type { SmartCdnUrlOptions } from './smartCdn.ts';
 export type { SignatureAlgorithm } from './index.ts';
+export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
 export type SignatureAlgorithmInput = SignatureAlgorithm | (string & {});
 /** Image formats supported by the responsive-image Built-in. */
 export type SmartCdnImageFormat = 'avif' | 'png' | 'webp';
@@ -38,38 +41,8 @@ export interface SmartCdnImageCandidatesOptions {
     /** Workspace slug. */
     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;
-};
 export declare const signParamsSync: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithmInput) => string;
+/** Synchronous Smart CDN URL signer (Node). The root export has an async WebCrypto twin. */
 export declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => string;
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAIpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7C,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CACxC;AAED,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAChE,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;IACrF;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAkED,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MA8B/D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,uBAAuB,CAsDzB"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAMvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEnF,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7C,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CACxC;AAED,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAChE,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAkED,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MAM/D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,uBAAuB,CAsDzB"}

package/dist/node.js

@@ -1,4 +1,6 @@
 import { createHmac } from 'node:crypto';
+import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
 const defaultSmartCdnImageFormats = {
     avif: 45,
     webp: 75,
@@ -57,35 +59,13 @@ export const signParamsSync = (paramsString, authSecret, algorithm = 'sha384') =
         .digest('hex');
     return `${algorithm}:${signature}`;
 };
+/** Synchronous Smart CDN URL signer (Node). The root export has an async WebCrypto twin. */
 export const getSignedSmartCdnUrl = (opts) => {
-    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);
 };
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.

package/dist/smartCdn.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Smart CDN URL grammar shared by the synchronous Node signer (`@transloadit/utils/node`) and the
+ * asynchronous WebCrypto signer (`@transloadit/utils`): building (signed and unsigned), parsing,
+ * and stripping signature parameters. Only the HMAC differs between the two signers, so the
+ * string-to-sign and the final URL are assembled here and cannot drift apart.
+ */
+export type SmartCdnUrlParams = Record<string, boolean | number | string | (boolean | number | 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?: SmartCdnUrlParams;
+    /**
+     * 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;
+    /**
+     * Base URL that replaces `https://{workspace}.tlcdn.com`, e.g. a local api2's URL Transform
+     * endpoint `https://api2-devdock.transloadit.dev/file/{workspace}`. A literal `{workspace}` is
+     * substituted with the encoded workspace slug; a trailing slash is ignored.
+     *
+     * **Trusted configuration only.** The signature does not cover the host, so a base URL taken from
+     * user input would let anyone redirect a signed URL (auth key included) to an origin of their
+     * choosing. Never derive it from request data.
+     */
+    baseUrl?: string;
+};
+/** Options for an unsigned Smart CDN URL: the signed options without credentials or expiry. */
+export type SmartCdnUnsignedUrlOptions = Omit<SmartCdnUrlOptions, 'authKey' | 'authSecret' | 'expiresAt'>;
+/** 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;
+        /** Resolved origin + path prefix that precedes `/{template}/{input}`. */
+        baseUrl: string;
+    };
+}
+/** The components of a Smart CDN URL, as produced by `parseSmartCdnUrl`. */
+export interface ParsedSmartCdnUrl {
+    workspace: string;
+    template: string;
+    input: string;
+    /** Every query parameter except the signature ones; repeated parameters become arrays. */
+    urlParams: Record<string, string | string[]>;
+    /** Present when the URL carries `auth_key`, `exp` and `sig`. */
+    auth?: {
+        key: string;
+        /** Milliseconds since UNIX epoch. */
+        expiresAt: number;
+        /** The `sig` value, e.g. `sha256:…`. */
+        signature: string;
+    };
+    /** Only set when the URL was parsed against a custom `baseUrl`; feeds straight back into the builders. */
+    baseUrl?: string;
+}
+export interface ParseSmartCdnUrlOptions {
+    /**
+     * The same trusted `baseUrl` the URL was built with (with or without `{workspace}`). Without it
+     * only `https://{workspace}.tlcdn.com/…` URLs are accepted.
+     */
+    baseUrl?: string;
+    /** Workspace slug for a `baseUrl` without a `{workspace}` placeholder, where the URL cannot tell. */
+    workspace?: string;
+}
+/** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
+export declare const prepareSmartCdnUrl: (opts: SmartCdnUrlOptions) => PreparedSmartCdnUrl;
+/** Appends the `sig` parameter and returns the final `https://{workspace}.tlcdn.com/…` URL. */
+export declare const finishSmartCdnUrl: ({ parts }: PreparedSmartCdnUrl, signatureHex: string) => string;
+/**
+ * Builds an unsigned Smart CDN URL (`https://{workspace}.tlcdn.com/{template}/{input}?sortedQuery`)
+ * for workspaces that do not require signature authentication.
+ */
+export declare const getSmartCdnUrl: (opts: SmartCdnUnsignedUrlOptions) => string;
+/**
+ * Removes the signature parameters (`auth_key`, `exp`, `sig`, and api2's `hsh`) from a Smart CDN
+ * URL. Every other byte of the URL is left untouched, so the result stays comparable with URLs
+ * produced elsewhere. Idempotent.
+ */
+export declare const stripSmartCdnAuth: (url: string) => string;
+/**
+ * Parses a Smart CDN URL back into the options that built it: the inverse of `getSmartCdnUrl` and
+ * `getSignedSmartCdnUrl`. Path segments are percent-decoded exactly once; query parameters are
+ * decoded by `URLSearchParams` semantics; `auth_key`/`exp`/`sig` are returned separately as `auth`.
+ */
+export declare const parseSmartCdnUrl: (url: string, options?: ParseSmartCdnUrlOptions) => ParsedSmartCdnUrl;
+//# sourceMappingURL=smartCdn.d.ts.map

package/dist/smartCdn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smartCdn.d.ts","sourceRoot":"","sources":["../src/smartCdn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CACpC,MAAM,EACN,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAC1D,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,kBAAkB,EAClB,SAAS,GAAG,YAAY,GAAG,WAAW,CACvC,CAAA;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAA;QACrB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,eAAe,CAAA;QAC5B,yEAAyE;QACzE,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IAC5C,gEAAgE;IAChE,IAAI,CAAC,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,qCAAqC;QACrC,SAAS,EAAE,MAAM,CAAA;QACjB,wCAAwC;QACxC,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,0GAA0G;IAC1G,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyCD,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,GAAI,MAAM,kBAAkB,KAAG,mBAuB7D,CAAA;AAED,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,GAAI,WAAW,mBAAmB,EAAE,cAAc,MAAM,KAAG,MAIxF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,0BAA0B,KAAG,MAWjE,CAAA;AAUD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,MAsB/C,CAAA;AAwDD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,UAAS,uBAA4B,KACpC,iBAiDF,CAAA"}

package/dist/smartCdn.js

@@ -0,0 +1,226 @@
+/**
+ * Smart CDN URL grammar shared by the synchronous Node signer (`@transloadit/utils/node`) and the
+ * asynchronous WebCrypto signer (`@transloadit/utils`): building (signed and unsigned), parsing,
+ * and stripping signature parameters. Only the HMAC differs between the two signers, so the
+ * string-to-sign and the final URL are assembled here and cannot drift apart.
+ */
+const SMART_CDN_HOST_SUFFIX = '.tlcdn.com';
+const WORKSPACE_PLACEHOLDER = '{workspace}';
+/** Query parameters that carry the signature; `hsh` is an api2-side hash that is stripped too. */
+const SIGNATURE_PARAMS = new Set(['auth_key', 'exp', 'sig']);
+const STRIPPED_PARAMS = new Set([...SIGNATURE_PARAMS, 'hsh']);
+const validateRequired = (opts) => {
+    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 resolveBaseUrl = (baseUrl, workspaceSlug) => {
+    if (baseUrl == null)
+        return `https://${workspaceSlug}${SMART_CDN_HOST_SUFFIX}`;
+    const resolved = baseUrl.replace(/\/+$/, '').split(WORKSPACE_PLACEHOLDER).join(workspaceSlug);
+    let parsed;
+    try {
+        parsed = new URL(resolved);
+    }
+    catch {
+        throw new TypeError(`baseUrl must be an absolute URL, got '${baseUrl}'`);
+    }
+    if (parsed.search !== '' || parsed.hash !== '') {
+        throw new TypeError('baseUrl must not contain a query string or fragment');
+    }
+    return resolved;
+};
+const buildQueryParams = (urlParams) => {
+    const queryParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(urlParams || {})) {
+        if (Array.isArray(value)) {
+            for (const val of value) {
+                queryParams.append(key, `${val}`);
+            }
+        }
+        else {
+            queryParams.append(key, `${value}`);
+        }
+    }
+    return queryParams;
+};
+/** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
+export const prepareSmartCdnUrl = (opts) => {
+    validateRequired(opts);
+    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 = buildQueryParams(opts.urlParams);
+    queryParams.set('auth_key', opts.authKey);
+    queryParams.set('exp', `${expiresAt}`);
+    queryParams.sort();
+    return {
+        stringToSign: `${workspaceSlug}/${templateSlug}/${inputField}?${queryParams}`,
+        parts: {
+            workspaceSlug,
+            templateSlug,
+            inputField,
+            queryParams,
+            baseUrl: resolveBaseUrl(opts.baseUrl, workspaceSlug),
+        },
+    };
+};
+/** Appends the `sig` parameter and returns the final `https://{workspace}.tlcdn.com/…` URL. */
+export const finishSmartCdnUrl = ({ parts }, signatureHex) => {
+    const { baseUrl, templateSlug, inputField, queryParams } = parts;
+    queryParams.set('sig', `sha256:${signatureHex}`);
+    return `${baseUrl}/${templateSlug}/${inputField}?${queryParams}`;
+};
+/**
+ * Builds an unsigned Smart CDN URL (`https://{workspace}.tlcdn.com/{template}/{input}?sortedQuery`)
+ * for workspaces that do not require signature authentication.
+ */
+export const getSmartCdnUrl = (opts) => {
+    validateRequired(opts);
+    const workspaceSlug = encodeURIComponent(opts.workspace);
+    const templateSlug = encodeURIComponent(opts.template);
+    const inputField = encodeURIComponent(opts.input);
+    const queryParams = buildQueryParams(opts.urlParams);
+    queryParams.sort();
+    const query = queryParams.toString();
+    return `${resolveBaseUrl(opts.baseUrl, workspaceSlug)}/${templateSlug}/${inputField}${query === '' ? '' : `?${query}`}`;
+};
+const decodeOnce = (value, what) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new TypeError(`Not a Smart CDN URL: malformed percent-encoding in ${what}`);
+    }
+};
+/**
+ * Removes the signature parameters (`auth_key`, `exp`, `sig`, and api2's `hsh`) from a Smart CDN
+ * URL. Every other byte of the URL is left untouched, so the result stays comparable with URLs
+ * produced elsewhere. Idempotent.
+ */
+export const stripSmartCdnAuth = (url) => {
+    const hashIndex = url.indexOf('#');
+    const fragment = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const withoutFragment = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const queryIndex = withoutFragment.indexOf('?');
+    if (queryIndex === -1)
+        return url;
+    const path = withoutFragment.slice(0, queryIndex);
+    const kept = withoutFragment
+        .slice(queryIndex + 1)
+        .split('&')
+        .filter((pair) => {
+        if (pair === '')
+            return false;
+        const rawName = pair.slice(0, pair.indexOf('=') === -1 ? pair.length : pair.indexOf('='));
+        let name = rawName;
+        try {
+            name = decodeURIComponent(rawName.replace(/\+/g, ' '));
+        }
+        catch {
+            // An undecodable name is never one of ours; keep it.
+        }
+        return !STRIPPED_PARAMS.has(name);
+    });
+    return `${path}${kept.length === 0 ? '' : `?${kept.join('&')}`}${fragment}`;
+};
+const notSmartCdnUrl = (detail) => new TypeError(`Not a Smart CDN URL: ${detail} (expected https://{workspace}.tlcdn.com/{template}/{input}, or the configured baseUrl)`);
+/** Splits `origin + pathname` into the workspace slug and the `{template}/{input}` remainder. */
+const locateSmartCdnPath = (parsed, options) => {
+    const full = `${parsed.origin}${parsed.pathname}`;
+    if (options.baseUrl == null) {
+        const match = /^([^.]+)\.tlcdn\.com$/i.exec(parsed.hostname);
+        if (match?.[1] == null || parsed.protocol !== 'https:') {
+            throw notSmartCdnUrl(`unexpected origin '${parsed.origin}'`);
+        }
+        return { workspaceSlug: match[1], remainder: parsed.pathname.slice(1) };
+    }
+    const template = options.baseUrl.replace(/\/+$/, '');
+    const placeholderIndex = template.indexOf(WORKSPACE_PLACEHOLDER);
+    if (placeholderIndex === -1) {
+        const prefix = `${template}/`;
+        if (!full.startsWith(prefix))
+            throw notSmartCdnUrl(`'${full}' is not under baseUrl '${template}'`);
+        const hostMatch = /^([^.]+)\.tlcdn\.com$/i.exec(parsed.hostname);
+        const workspaceSlug = options.workspace != null ? encodeURIComponent(options.workspace) : hostMatch?.[1];
+        if (workspaceSlug == null) {
+            throw notSmartCdnUrl('the workspace cannot be determined; pass `workspace` next to a baseUrl without {workspace}');
+        }
+        return { workspaceSlug, remainder: full.slice(prefix.length), baseUrl: template };
+    }
+    const before = template.slice(0, placeholderIndex);
+    const after = template.slice(placeholderIndex + WORKSPACE_PLACEHOLDER.length);
+    if (!full.startsWith(before))
+        throw notSmartCdnUrl(`'${full}' is not under baseUrl '${template}'`);
+    const rest = full.slice(before.length);
+    const slashIndex = rest.indexOf('/');
+    const workspaceSlug = slashIndex === -1 ? rest : rest.slice(0, slashIndex);
+    const afterPart = slashIndex === -1 ? '' : rest.slice(slashIndex);
+    if (workspaceSlug === '' || !afterPart.startsWith(`${after}/`)) {
+        throw notSmartCdnUrl(`'${full}' does not match baseUrl '${template}'`);
+    }
+    return {
+        workspaceSlug,
+        remainder: afterPart.slice(after.length + 1),
+        baseUrl: `${before}${workspaceSlug}${after}`,
+    };
+};
+/**
+ * Parses a Smart CDN URL back into the options that built it: the inverse of `getSmartCdnUrl` and
+ * `getSignedSmartCdnUrl`. Path segments are percent-decoded exactly once; query parameters are
+ * decoded by `URLSearchParams` semantics; `auth_key`/`exp`/`sig` are returned separately as `auth`.
+ */
+export const parseSmartCdnUrl = (url, options = {}) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw notSmartCdnUrl(`'${url}' is not an absolute URL`);
+    }
+    const { workspaceSlug, remainder, baseUrl } = locateSmartCdnPath(parsed, options);
+    const slashIndex = remainder.indexOf('/');
+    if (slashIndex === -1)
+        throw notSmartCdnUrl('missing the input segment');
+    const templateSlug = remainder.slice(0, slashIndex);
+    if (templateSlug === '')
+        throw notSmartCdnUrl('missing the template segment');
+    const urlParams = {};
+    const signature = {};
+    for (const [key, value] of new URLSearchParams(parsed.search)) {
+        if (SIGNATURE_PARAMS.has(key)) {
+            signature[key] = value;
+            continue;
+        }
+        const existing = urlParams[key];
+        if (existing === undefined)
+            urlParams[key] = value;
+        else if (Array.isArray(existing))
+            existing.push(value);
+        else
+            urlParams[key] = [existing, value];
+    }
+    let auth;
+    const present = Object.keys(signature).length;
+    if (present > 0) {
+        if (present !== SIGNATURE_PARAMS.size) {
+            throw notSmartCdnUrl('incomplete signature parameters; expected auth_key, exp and sig together');
+        }
+        const expiresAt = Number(signature.exp);
+        if (!Number.isInteger(expiresAt))
+            throw notSmartCdnUrl(`exp '${signature.exp}' is not a timestamp`);
+        auth = { key: signature.auth_key, expiresAt, signature: signature.sig };
+    }
+    return {
+        workspace: decodeOnce(workspaceSlug, 'the workspace'),
+        template: decodeOnce(templateSlug, 'the template'),
+        input: decodeOnce(remainder.slice(slashIndex + 1), 'the input'),
+        urlParams,
+        ...(auth && { auth }),
+        ...(baseUrl != null && { baseUrl }),
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transloadit/utils",
-  "version": "4.5.1",
+  "version": "4.7.0",
   "description": "Transloadit shared utilities",
   "type": "module",
   "license": "MIT",