utils: Smart CDN URL grammar — parse, unsigned build, strip auth, trusted baseUrl (#479)

getSignedSmartCdnUrl already lived here; the rest of the grammar did not,
so the Console carried four copies (parser, unsigned builder, auth
stripper, dev-origin rewrite) and Uppy a fifth. Add getSmartCdnUrl,
parseSmartCdnUrl and stripSmartCdnAuth on the shared prepare/finish
core, plus a trusted baseUrl option on both builders (documented: the
host is not signed, so it must come from configuration). Round-trip and
edge-case vectors; the 4.6.0 known answer is unchanged.

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

Author: kvz

.changeset/smart-cdn-grammar.md

@@ -0,0 +1,11 @@
+---
+"@transloadit/utils": minor
+---
+
+Add the rest of the Smart CDN URL grammar next to `getSignedSmartCdnUrl`, so applications stop
+carrying their own copies: `getSmartCdnUrl` (unsigned builder), `parseSmartCdnUrl` (the inverse of
+the builders — decodes once, keeps repeated query parameters, returns `auth_key`/`exp`/`sig` as
+`auth`) and `stripSmartCdnAuth` (removes the signature parameters byte-for-byte otherwise). Both
+builders accept a trusted `baseUrl` option (for example a local api2's URL Transform endpoint with
+a `{workspace}` placeholder); the signature does not cover the host, so it must come from
+configuration, never from user input. Exported from the root and the `./node` entry.

packages/utils/README.md

@@ -14,7 +14,14 @@ Everything in the root export runs on WebCrypto, so it works in browsers (secure
 `https://` or `localhost`), edge runtimes, and Node.
 
 ```ts
-import { getSignedSmartCdnUrl, 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({
@@ -31,6 +38,29 @@ const url = await getSignedSmartCdnUrl({
 })
 ```
 
+### 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
@@ -70,6 +100,11 @@ for (const source of imageCandidates.sources) {
 - `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)` from `@transloadit/utils/node`: synchronous Smart CDN URL signer.
 - `getSignedSmartCdnImageCandidates(options)`: deterministic structured, signed AVIF and WebP

packages/utils/src/index.ts

@@ -4,9 +4,16 @@ import { finishSmartCdnUrl, prepareSmartCdnUrl } from './smartCdn.ts'
 
 export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384' | 'sha512'
 
-export type { SmartCdnUrlOptions } from './smartCdn.ts'
+export type {
+  ParsedSmartCdnUrl,
+  ParseSmartCdnUrlOptions,
+  SmartCdnUnsignedUrlOptions,
+  SmartCdnUrlOptions,
+  SmartCdnUrlParams,
+} from './smartCdn.ts'
 
 export * from './assemblyInstructionsCompiler.ts'
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts'
 
 const algorithmMap = {
   sha1: 'SHA-1',

packages/utils/src/node.ts

@@ -6,7 +6,15 @@ 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 {
+  ParsedSmartCdnUrl,
+  ParseSmartCdnUrlOptions,
+  SmartCdnUnsignedUrlOptions,
+  SmartCdnUrlOptions,
+  SmartCdnUrlParams,
+} from './smartCdn.ts'
+
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts'
 
 export type SignatureAlgorithmInput = SignatureAlgorithm | (string & {})