@transloadit/utils 4.1.5

package/README.md

@@ -0,0 +1,44 @@
+# @transloadit/utils
+
+Shared runtime helpers used across Transloadit JavaScript SDKs.
+
+## Install
+
+```bash
+npm install @transloadit/utils
+```
+
+## Web / Edge usage
+
+```ts
+import { signParams, verifyWebhookSignature } from '@transloadit/utils'
+
+const signature = await signParams(paramsString, authSecret)
+const verified = await verifyWebhookSignature({
+  rawBody,
+  signatureHeader,
+  authSecret,
+})
+```
+
+## Node usage
+
+```ts
+import { signParamsSync, getSignedSmartCdnUrl } from '@transloadit/utils/node'
+
+const signature = signParamsSync(paramsString, authSecret)
+const url = getSignedSmartCdnUrl({
+  workspace,
+  template,
+  input,
+  authKey,
+  authSecret,
+})
+```
+
+## API
+
+- `signParams(paramsString, authSecret, algorithm?)`: WebCrypto-based HMAC signature for params.
+- `verifyWebhookSignature({ rawBody, signatureHeader, authSecret })`: validates webhook signatures.
+- `signParamsSync(paramsString, authSecret, algorithm?)`: Node-only sync signature helper.
+- `getSignedSmartCdnUrl(options)`: Node-only Smart CDN URL signer.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384';
+export declare const signParams: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithm) => Promise<string>;
+export type VerifyWebhookSignatureOptions = {
+    rawBody: string;
+    signatureHeader?: string;
+    authSecret: string;
+};
+export declare const verifyWebhookSignature: (options: VerifyWebhookSignatureOptions) => Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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;AAiD7D,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"}

package/dist/index.js

@@ -0,0 +1,56 @@
+const algorithmMap = {
+    sha1: 'SHA-1',
+    sha256: 'SHA-256',
+    sha384: 'SHA-384',
+};
+const isSignatureAlgorithm = (value) => value === 'sha1' || value === 'sha256' || value === 'sha384';
+const getSubtle = () => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error('Web Crypto is required to sign Transloadit payloads');
+    }
+    return subtle;
+};
+const hmacHex = async (algorithm, key, data) => {
+    const subtle = getSubtle();
+    const encoder = new TextEncoder();
+    const cryptoKey = await subtle.importKey('raw', encoder.encode(key), { name: 'HMAC', hash: { name: algorithmMap[algorithm] } }, false, ['sign']);
+    const signature = await subtle.sign('HMAC', cryptoKey, encoder.encode(data));
+    const bytes = new Uint8Array(signature);
+    return Array.from(bytes)
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+};
+const safeCompare = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+};
+export const signParams = async (paramsString, authSecret, algorithm = 'sha384') => {
+    const normalized = algorithm.toLowerCase();
+    if (!isSignatureAlgorithm(normalized)) {
+        throw new Error(`Unsupported signature algorithm: ${algorithm}`);
+    }
+    const signature = await hmacHex(normalized, authSecret, paramsString);
+    return `${normalized}:${signature}`;
+};
+export const verifyWebhookSignature = async (options) => {
+    if (!options.signatureHeader)
+        return false;
+    const signatureHeader = options.signatureHeader.trim();
+    if (!signatureHeader)
+        return false;
+    const separatorIndex = signatureHeader.indexOf(':');
+    const prefix = separatorIndex === -1 ? 'sha1' : signatureHeader.slice(0, separatorIndex);
+    const signature = separatorIndex === -1 ? signatureHeader : signatureHeader.slice(separatorIndex + 1);
+    const normalized = prefix.toLowerCase();
+    if (!isSignatureAlgorithm(normalized)) {
+        return false;
+    }
+    const expected = await hmacHex(normalized, options.authSecret, options.rawBody);
+    return safeCompare(expected, signature);
+};

package/dist/node.d.ts

@@ -0,0 +1,37 @@
+import type { SignatureAlgorithm } from './index.ts';
+export type { SignatureAlgorithm } from './index.ts';
+export type SignatureAlgorithmInput = SignatureAlgorithm | (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;
+export declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => string;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,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;AAED,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"}

package/dist/node.js

@@ -0,0 +1,37 @@
+import { createHmac } from 'node:crypto';
+export const signParamsSync = (paramsString, authSecret, algorithm = 'sha384') => {
+    const signature = createHmac(algorithm, authSecret)
+        .update(Buffer.from(paramsString, 'utf-8'))
+        .digest('hex');
+    return `${algorithm}:${signature}`;
+};
+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}`;
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@transloadit/utils",
+  "version": "4.1.5",
+  "description": "Transloadit shared utilities",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transloadit/node-sdk",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "lint:ts": "../../node_modules/.bin/tsc --build tsconfig.build.json",
+    "build": "../../node_modules/.bin/tsc --build tsconfig.build.json",
+    "check": "yarn lint:ts",
+    "prepack": "yarn build"
+  },
+  "publishConfig": {
+    "tag": "experimental"
+  }
+}