@transloadit/utils 4.7.0 → 4.8.0

package/README.md

@@ -55,6 +55,9 @@ const { workspace, template, input, urlParams, auth } = parseSmartCdnUrl(url)
 const unsigned = stripSmartCdnAuth(url)
 ```
 
+`auth_key`, `exp`, and `sig` are reserved: signed builders replace them and the unsigned builder
+omits them. Other fields, including `hsh`, round-trip through the builders and parser.
+
 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
@@ -83,7 +86,12 @@ const imageCandidates = getSignedSmartCdnImageCandidates({
   authSecret,
   // Reuse one absolute expiry across a build instead of recomputing it per request.
   expiresAt,
-  input: 'https://example.com/image.jpg',
+  // The browser fallback is independent from the Template's input grammar.
+  fallbackUrl: '/images/photo.jpg',
+  // This workspace Template pins https://example.com/ and accepts a relative path.
+  input: 'images/photo.jpg',
+  sourceDimensions: { height: 1600, width: 2400 },
+  template: 'website-images',
   widths: [320, 640, 960],
   workspace,
 })
@@ -108,4 +116,12 @@ for (const source of imageCandidates.sources) {
 - `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
-  candidates plus the original fallback URL.
+  candidates plus an explicit browser fallback. `template` is mandatory: use a trusted workspace
+  Template that owns its source policy. `fallbackUrl` is deliberately separate from `input`, which
+  may use a Template-specific grammar such as a relative origin-pinned path. Supply
+  `sourceDimensions` to prevent upscaling and keep both output dimensions within backend limits.
+- `createSmartCdnImageCandidates(options, sign)` from `@transloadit/utils`: the same deterministic
+  image policy with an injected synchronous signer, for framework and package adapters that own
+  their credential boundary.
+- `resolveSmartCdnImageFormats(formats)` and `resolveSmartCdnImageWidths(widths, maximumWidth?)`:
+  shared validation and normalization for adapters that use a different image Built-in.

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import type { SmartCdnUrlOptions } from './smartCdn.ts';
 export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384' | 'sha512';
 export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
+export type { SignSmartCdnImageRequest, SmartCdnImageCandidate, SmartCdnImageCandidates, SmartCdnImageFormat, SmartCdnImageFormatQuality, SmartCdnImageFormats, SmartCdnImagePolicyOptions, SmartCdnImageSignRequest, SmartCdnImageSource, SmartCdnImageSourceDimensions, } from './smartCdnImage.ts';
 export * from './assemblyInstructionsCompiler.ts';
 export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
+export { createSmartCdnImageCandidates, resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from './smartCdnImage.ts';
 export declare const signParams: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithm) => Promise<string>;
 export type VerifyWebhookSignatureOptions = {
     rawBody: string;
@@ -15,4 +17,6 @@ export declare const verifyWebhookSignature: (options: VerifyWebhookSignatureOpt
  * Produces the same URL as the synchronous `getSignedSmartCdnUrl` from `@transloadit/utils/node`.
  */
 export declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => Promise<string>;
+export type { StorageGrantClaims, StorageGrantScope } from './storageGrant.ts';
+export { decodeStorageGrant, normalizeStorageGrantPrefix, parseStorageGrantClaims, STORAGE_GRANT_SCOPES, } from './storageGrant.ts';
 //# 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,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"}
+{"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;AACtB,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAA;AAE3B,cAAc,mCAAmC,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAA;AAqD3B,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;AAED,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -1,6 +1,7 @@
 import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
 export * from "./assemblyInstructionsCompiler.js";
 export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
+export { createSmartCdnImageCandidates, resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from "./smartCdnImage.js";
 const algorithmMap = {
     sha1: 'SHA-1',
     sha256: 'SHA-256',
@@ -68,3 +69,4 @@ export const getSignedSmartCdnUrl = async (opts) => {
     const signature = await hmacHex('sha256', opts.authSecret, prepared.stringToSign);
     return finishSmartCdnUrl(prepared, signature);
 };
+export { decodeStorageGrant, normalizeStorageGrantPrefix, parseStorageGrantClaims, STORAGE_GRANT_SCOPES, } from "./storageGrant.js";

package/dist/node.d.ts

@@ -1,43 +1,19 @@
 import type { SignatureAlgorithm } from './index.ts';
 import type { SmartCdnUrlOptions } from './smartCdn.ts';
+import type { SmartCdnImageCandidates, SmartCdnImagePolicyOptions } from './smartCdnImage.ts';
+import type { StorageGrantClaims, StorageGrantScope } from './storageGrant.ts';
 export type { SignatureAlgorithm } from './index.ts';
 export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
+export type { SignSmartCdnImageRequest, SmartCdnImageCandidate, SmartCdnImageCandidates, SmartCdnImageFormat, SmartCdnImageFormatQuality, SmartCdnImageFormats, SmartCdnImagePolicyOptions, SmartCdnImageSignRequest, SmartCdnImageSource, SmartCdnImageSourceDimensions, } from './smartCdnImage.ts';
 export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
+export { resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from './smartCdnImage.ts';
 export type SignatureAlgorithmInput = SignatureAlgorithm | (string & {});
-/** Image formats supported by the responsive-image Built-in. */
-export type SmartCdnImageFormat = 'avif' | 'png' | 'webp';
-/** One signed Smart CDN rendition at a specific intrinsic width. */
-export interface SmartCdnImageCandidate {
-    url: string;
-    width: number;
-}
-/** Ordered candidates for one image format and quality. */
-export interface SmartCdnImageSource {
-    candidates: readonly SmartCdnImageCandidate[];
-    format: SmartCdnImageFormat;
-    quality: number;
-}
-/** Structured data for rendering a responsive image. */
-export interface SmartCdnImageCandidates {
-    fallbackUrl: string;
-    sources: readonly SmartCdnImageSource[];
-}
 /** Options for deterministic, server-generated Smart CDN image candidates. */
-export interface SmartCdnImageCandidatesOptions {
+export interface SmartCdnImageCandidatesOptions extends SmartCdnImagePolicyOptions {
     /** Transloadit auth key used to sign every candidate URL. */
     authKey: string;
     /** Transloadit auth secret used to sign every candidate URL. */
     authSecret: string;
-    /** One absolute expiry in milliseconds since UNIX epoch, shared by every candidate. */
-    expiresAt: number;
-    /** Formats and their quality values. Defaults to AVIF 45 and WebP 75. */
-    formats?: Readonly<Partial<Record<SmartCdnImageFormat, number>>>;
-    /** Absolute HTTP(S) source URL accepted by the responsive-image Template. */
-    input: string;
-    /** Compatible Template override. Defaults to `builtin/serve-image@0.0.1`. */
-    template?: string;
-    /** Up to 32 intrinsic widths. Each value must be an integer from 1 through 8000. */
-    widths: readonly number[];
     /** Workspace slug. */
     workspace: string;
 }
@@ -47,8 +23,39 @@ export declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => string;
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.
  *
- * Width descriptors are only accurate when callers do not request widths above the source image's
- * intrinsic width. The helper deliberately keeps the Built-in in width-only `fit` mode.
+ * Pass `sourceDimensions` when known so width descriptors remain truthful without producing a
+ * rendition above the backend's width or derived-height limits.
  */
 export declare function getSignedSmartCdnImageCandidates(opts: SmartCdnImageCandidatesOptions): SmartCdnImageCandidates;
+export type { StorageGrantClaims, StorageGrantScope } from './storageGrant.ts';
+export { decodeStorageGrant, normalizeStorageGrantPrefix, parseStorageGrantClaims, STORAGE_GRANT_SCOPES, } from './storageGrant.ts';
+export type SignStorageGrantOptions = {
+    /** The workspace slug ("bucket" in S3 terms). */
+    bucket: string;
+    /** Key prefix to confine the session to. Default: the whole workspace. */
+    prefix?: string;
+    /** Default: read-only. */
+    scopes?: StorageGrantScope[];
+    /** Who the grant is minted for (informational). */
+    sub?: string;
+    /** Grant lifetime. Default: 900 (15 minutes). */
+    expiresInSeconds?: number;
+    /** Clock override for tests. */
+    nowMs?: number;
+};
+/**
+ * Mints a storage grant: an HS256 JWT with the v1 claim set, byte-compatible
+ * with api2's `StorageGrantManager` (same header, claim order and encoding).
+ */
+export declare const signStorageGrant: (options: SignStorageGrantOptions, secret: string) => {
+    grant: string;
+    claims: StorageGrantClaims;
+};
+/**
+ * Verifies a storage grant: HS256 signature (timing-safe), strict v1 claim
+ * shape, and expiry. Throws with a stable message on any failure.
+ */
+export declare const verifyStorageGrant: (token: string, secret: string, { nowMs }?: {
+    nowMs?: number;
+}) => StorageGrantClaims;
 //# sourceMappingURL=node.d.ts.map

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;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"}
+{"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;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAA;AAC7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAS9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,8EAA8E;AAC9E,MAAM,WAAW,8BAA+B,SAAQ,0BAA0B;IAChF,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,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,CAsBzB;AAID,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAK1B,MAAM,MAAM,uBAAuB,GAAG;IACpC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0BAA0B;IAC1B,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,uBAAuB,EAChC,QAAQ,MAAM,KACb;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAiB7C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,YAAwB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,KAC9C,kBA6BF,CAAA"}

package/dist/node.js

@@ -1,58 +1,10 @@
-import { createHmac } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
+import { createSmartCdnImageCandidates } from "./smartCdnImage.js";
+import { parseStorageGrantClaims } from "./storageGrant.js";
 export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
-const defaultSmartCdnImageFormats = {
-    avif: 45,
-    webp: 75,
-};
-const defaultSmartCdnImageTemplate = 'builtin/serve-image@0.0.1';
-const smartCdnImageFormats = ['avif', 'webp', 'png'];
-const smartCdnImageMaxDimension = 8000;
-const smartCdnImageMaxWidths = 32;
-function isSmartCdnImageFormat(value) {
-    return value === 'avif' || value === 'png' || value === 'webp';
-}
-function validateSmartCdnImageDimension(width) {
-    if (!Number.isInteger(width) || width < 1 || width > smartCdnImageMaxDimension) {
-        throw new RangeError(`width must be an integer from 1 through ${smartCdnImageMaxDimension}`);
-    }
-}
-function validateSmartCdnImageQuality(quality) {
-    if (!Number.isInteger(quality) || quality < 1 || quality > 100) {
-        throw new RangeError('quality must be an integer from 1 through 100');
-    }
-}
-function validateSmartCdnImageInput(input) {
-    if (typeof input !== 'string' || input.trim() !== input || input.includes('|')) {
-        throw new TypeError('input must be a single HTTP or HTTPS URL string');
-    }
-    if (!URL.canParse(input)) {
-        throw new TypeError('input must be an HTTP or HTTPS URL');
-    }
-    const protocol = new URL(input).protocol;
-    if (protocol !== 'http:' && protocol !== 'https:') {
-        throw new TypeError('input must be an HTTP or HTTPS URL');
-    }
-}
-function validateSmartCdnImageFormats(formats) {
-    for (const format of Object.keys(formats)) {
-        if (!isSmartCdnImageFormat(format)) {
-            throw new TypeError(`Unsupported Smart CDN image format: ${format}`);
-        }
-    }
-    let formatCount = 0;
-    for (const format of smartCdnImageFormats) {
-        const quality = formats[format];
-        if (quality == null) {
-            continue;
-        }
-        validateSmartCdnImageQuality(quality);
-        formatCount += 1;
-    }
-    if (formatCount === 0) {
-        throw new TypeError('formats must contain at least one value');
-    }
-}
+export { resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from "./smartCdnImage.js";
 export const signParamsSync = (paramsString, authSecret, algorithm = 'sha384') => {
     const signature = createHmac(algorithm, authSecret)
         .update(Buffer.from(paramsString, 'utf-8'))
@@ -70,56 +22,83 @@ export const getSignedSmartCdnUrl = (opts) => {
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.
  *
- * Width descriptors are only accurate when callers do not request widths above the source image's
- * intrinsic width. The helper deliberately keeps the Built-in in width-only `fit` mode.
+ * Pass `sourceDimensions` when known so width descriptors remain truthful without producing a
+ * rendition above the backend's width or derived-height limits.
  */
 export function getSignedSmartCdnImageCandidates(opts) {
-    if (typeof opts.authKey !== 'string' || opts.authKey === '') {
+    const authKey = opts.authKey;
+    const authSecret = opts.authSecret;
+    const workspace = opts.workspace;
+    if (typeof authKey !== 'string' || authKey === '') {
         throw new TypeError('authKey is required');
     }
-    if (typeof opts.authSecret !== 'string' || opts.authSecret === '') {
+    if (typeof authSecret !== 'string' || authSecret === '') {
         throw new TypeError('authSecret is required');
     }
-    if (!Number.isSafeInteger(opts.expiresAt) || opts.expiresAt <= 0) {
-        throw new RangeError('expiresAt must be a positive safe integer');
-    }
-    if (!Array.isArray(opts.widths) || opts.widths.length === 0) {
-        throw new TypeError('widths must contain at least one value');
-    }
-    if (opts.widths.length > smartCdnImageMaxWidths) {
-        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} values`);
-    }
-    validateSmartCdnImageInput(opts.input);
-    const widths = [...new Set(opts.widths)];
-    if (widths.length > smartCdnImageMaxWidths) {
-        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} unique values`);
-    }
-    for (const width of widths) {
-        validateSmartCdnImageDimension(width);
-    }
-    const formats = opts.formats ?? defaultSmartCdnImageFormats;
-    validateSmartCdnImageFormats(formats);
-    widths.sort((left, right) => left - right);
-    const sources = [];
-    for (const format of smartCdnImageFormats) {
-        const quality = formats[format];
-        if (quality == null) {
-            continue;
-        }
-        const candidates = [];
-        for (const width of widths) {
-            const url = getSignedSmartCdnUrl({
-                authKey: opts.authKey,
-                authSecret: opts.authSecret,
-                expiresAt: opts.expiresAt,
-                input: opts.input,
-                template: opts.template ?? defaultSmartCdnImageTemplate,
-                urlParams: { f: format, q: quality, r: 'fit', w: width },
-                workspace: opts.workspace,
-            });
-            candidates.push({ url, width });
-        }
-        sources.push({ candidates, format, quality });
-    }
-    return { fallbackUrl: opts.input, sources };
+    return createSmartCdnImageCandidates(opts, (request) => getSignedSmartCdnUrl({
+        authKey,
+        authSecret,
+        expiresAt: request.expiresAt,
+        input: request.input,
+        template: request.template,
+        urlParams: { ...request.urlParams },
+        workspace,
+    }));
 }
+export { decodeStorageGrant, normalizeStorageGrantPrefix, parseStorageGrantClaims, STORAGE_GRANT_SCOPES, } from "./storageGrant.js";
+const base64url = (value) => (typeof value === 'string' ? Buffer.from(value) : value).toString('base64url');
+/**
+ * Mints a storage grant: an HS256 JWT with the v1 claim set, byte-compatible
+ * with api2's `StorageGrantManager` (same header, claim order and encoding).
+ */
+export const signStorageGrant = (options, secret) => {
+    const { bucket, prefix = '', scopes = ['read'], sub, expiresInSeconds = 900 } = options;
+    const iat = Math.floor((options.nowMs ?? Date.now()) / 1000);
+    const claims = {
+        v: 1,
+        bucket,
+        prefix,
+        scopes: [...new Set(scopes)],
+        ...(sub === undefined ? {} : { sub }),
+        iat,
+        exp: iat + expiresInSeconds,
+    };
+    const signingInput = `${base64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))}.${base64url(JSON.stringify(claims))}`;
+    const signature = base64url(createHmac('sha256', secret).update(signingInput).digest());
+    return { grant: `${signingInput}.${signature}`, claims };
+};
+/**
+ * Verifies a storage grant: HS256 signature (timing-safe), strict v1 claim
+ * shape, and expiry. Throws with a stable message on any failure.
+ */
+export const verifyStorageGrant = (token, secret, { nowMs = Date.now() } = {}) => {
+    const [headerPart, payloadPart, signaturePart, ...rest] = token.split('.');
+    if (!headerPart || !payloadPart || !signaturePart || rest.length > 0) {
+        throw new Error('Invalid storage grant');
+    }
+    const expected = createHmac('sha256', secret).update(`${headerPart}.${payloadPart}`).digest();
+    const actual = Buffer.from(signaturePart, 'base64url');
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        throw new Error('Invalid storage grant signature');
+    }
+    let header;
+    let payload;
+    try {
+        header = JSON.parse(Buffer.from(headerPart, 'base64url').toString('utf8'));
+        payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('Invalid storage grant');
+    }
+    if (typeof header !== 'object' ||
+        header === null ||
+        header.alg !== 'HS256') {
+        throw new Error('Invalid storage grant algorithm');
+    }
+    const claims = parseStorageGrantClaims(payload);
+    if (claims === null)
+        throw new Error('Invalid storage grant claims');
+    if (claims.exp <= Math.floor(nowMs / 1000))
+        throw new Error('The storage grant has expired');
+    return claims;
+};

package/dist/smartCdn.d.ts

@@ -19,7 +19,8 @@ export type SmartCdnUrlOptions = {
      */
     input: string;
     /**
-     * Additional parameters for the URL query string.
+     * Additional parameters for the URL query string. `auth_key`, `exp`, and `sig` are reserved:
+     * signed builders replace them and unsigned builders omit them.
      */
     urlParams?: SmartCdnUrlParams;
     /**
@@ -67,7 +68,7 @@ export interface ParsedSmartCdnUrl {
     workspace: string;
     template: string;
     input: string;
-    /** Every query parameter except the signature ones; repeated parameters become arrays. */
+    /** Every query parameter except auth fields; repeated parameters become arrays. */
     urlParams: Record<string, string | string[]>;
     /** Present when the URL carries `auth_key`, `exp` and `sig`. */
     auth?: {

package/dist/smartCdn.d.ts.map

@@ -1 +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"}
+{"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;;;OAGG;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,mFAAmF;IACnF,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,mBAyB7D,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,MAajE,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,iBA4DF,CAAA"}

package/dist/smartCdn.js

@@ -55,6 +55,8 @@ export const prepareSmartCdnUrl = (opts) => {
     const inputField = encodeURIComponent(opts.input);
     const expiresAt = opts.expiresAt || Date.now() + 60 * 60 * 1000;
     const queryParams = buildQueryParams(opts.urlParams);
+    // Keep accepting legacy values: the signer safely replaces its own authentication fields.
+    queryParams.delete('sig');
     queryParams.set('auth_key', opts.authKey);
     queryParams.set('exp', `${expiresAt}`);
     queryParams.sort();
@@ -85,6 +87,9 @@ export const getSmartCdnUrl = (opts) => {
     const templateSlug = encodeURIComponent(opts.template);
     const inputField = encodeURIComponent(opts.input);
     const queryParams = buildQueryParams(opts.urlParams);
+    // An unsigned builder must not emit fields that make the URL look partially or fully signed.
+    for (const param of SIGNATURE_PARAMS)
+        queryParams.delete(param);
     queryParams.sort();
     const query = queryParams.toString();
     return `${resolveBaseUrl(opts.baseUrl, workspaceSlug)}/${templateSlug}/${inputField}${query === '' ? '' : `?${query}`}`;
@@ -190,10 +195,20 @@ export const parseSmartCdnUrl = (url, options = {}) => {
     if (templateSlug === '')
         throw notSmartCdnUrl('missing the template segment');
     const urlParams = {};
-    const signature = {};
+    let authKey;
+    let expiration;
+    let signatureValue;
     for (const [key, value] of new URLSearchParams(parsed.search)) {
-        if (SIGNATURE_PARAMS.has(key)) {
-            signature[key] = value;
+        if (key === 'auth_key') {
+            authKey = value;
+            continue;
+        }
+        if (key === 'exp') {
+            expiration = value;
+            continue;
+        }
+        if (key === 'sig') {
+            signatureValue = value;
             continue;
         }
         const existing = urlParams[key];
@@ -205,15 +220,15 @@ export const parseSmartCdnUrl = (url, options = {}) => {
             urlParams[key] = [existing, value];
     }
     let auth;
-    const present = Object.keys(signature).length;
+    const present = [authKey, expiration, signatureValue].filter((value) => value !== undefined).length;
     if (present > 0) {
-        if (present !== SIGNATURE_PARAMS.size) {
+        if (authKey === undefined || expiration === undefined || signatureValue === undefined) {
             throw notSmartCdnUrl('incomplete signature parameters; expected auth_key, exp and sig together');
         }
-        const expiresAt = Number(signature.exp);
+        const expiresAt = Number(expiration);
         if (!Number.isInteger(expiresAt))
-            throw notSmartCdnUrl(`exp '${signature.exp}' is not a timestamp`);
-        auth = { key: signature.auth_key, expiresAt, signature: signature.sig };
+            throw notSmartCdnUrl(`exp '${expiration}' is not a timestamp`);
+        auth = { key: authKey, expiresAt, signature: signatureValue };
     }
     return {
         workspace: decodeOnce(workspaceSlug, 'the workspace'),

package/dist/smartCdnImage.d.ts

@@ -0,0 +1,68 @@
+/** Maximum requested width or height accepted by the responsive-image Built-ins. */
+export declare const smartCdnImageMaxDimension = 8000;
+/** Image formats supported by the responsive-image Built-in. */
+export type SmartCdnImageFormat = 'avif' | 'png' | 'webp';
+/** Formats and their format-specific quality values. */
+export type SmartCdnImageFormats = Readonly<Partial<Record<SmartCdnImageFormat, number>>>;
+/** One responsive-image candidate at a specific intrinsic width. */
+export interface SmartCdnImageCandidate {
+    url: string;
+    width: number;
+}
+/** Ordered candidates for one image format and quality. */
+export interface SmartCdnImageSource {
+    candidates: readonly SmartCdnImageCandidate[];
+    format: SmartCdnImageFormat;
+    quality: number;
+}
+/** One validated format and its encoding quality, in browser preference order. */
+export interface SmartCdnImageFormatQuality {
+    format: SmartCdnImageFormat;
+    quality: number;
+}
+/** Structured data for rendering a responsive image. */
+export interface SmartCdnImageCandidates {
+    fallbackUrl: string;
+    sources: readonly SmartCdnImageSource[];
+}
+/** Intrinsic dimensions used to prevent upscaling or an oversized derived height. */
+export interface SmartCdnImageSourceDimensions {
+    height: number;
+    width: number;
+}
+/** One rendition request passed to an injected Smart CDN signer. */
+export interface SmartCdnImageSignRequest {
+    expiresAt: number;
+    input: string;
+    template: string;
+    urlParams: Readonly<Record<string, boolean | number | string>>;
+}
+/** Injected signer that keeps responsive-image policy independent from credentials and runtimes. */
+export type SignSmartCdnImageRequest = (request: SmartCdnImageSignRequest) => string;
+/** Framework-neutral options for deterministic Smart CDN image candidates. */
+export interface SmartCdnImagePolicyOptions {
+    /** One absolute expiry in milliseconds since UNIX epoch, shared by every candidate. */
+    expiresAt: number;
+    /** Browser-safe fallback URL, kept separate from the Template-specific input value. */
+    fallbackUrl: string;
+    /** Formats and their quality values. Defaults to AVIF 45 and WebP 75. */
+    formats?: SmartCdnImageFormats;
+    /** One source value accepted by the explicitly selected responsive-image Template. */
+    input: string;
+    /** Intrinsic dimensions, when known, used to keep generated output within backend limits. */
+    sourceDimensions?: SmartCdnImageSourceDimensions;
+    /** Trusted Template whose source policy is controlled by the caller's workspace. */
+    template: string;
+    /** Up to 32 intrinsic widths. Each value must be an integer from 1 through 8000. */
+    widths: readonly number[];
+}
+/** Resolves and validates format-specific qualities in deterministic browser preference order. */
+export declare function resolveSmartCdnImageFormats(formats: SmartCdnImageFormats | undefined): SmartCdnImageFormatQuality[];
+/** Validates, caps, deduplicates, and sorts requested responsive-image widths. */
+export declare function resolveSmartCdnImageWidths(widths: readonly number[], maximumWidth?: number): number[];
+/**
+ * Creates signed responsive-image candidates while leaving credential storage and HMAC choice to
+ * the injected signer.
+ */
+export declare function createSmartCdnImageCandidates(options: SmartCdnImagePolicyOptions, sign: SignSmartCdnImageRequest): SmartCdnImageCandidates;
+//# sourceMappingURL=smartCdnImage.d.ts.map

package/dist/smartCdnImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smartCdnImage.d.ts","sourceRoot":"","sources":["../src/smartCdnImage.ts"],"names":[],"mappings":"AAKA,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAE7C,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,wDAAwD;AACxD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAEzF,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,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,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,qFAAqF;AACrF,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAA;CAC/D;AAED,oGAAoG;AACpG,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,MAAM,CAAA;AAEpF,8EAA8E;AAC9E,MAAM,WAAW,0BAA0B;IACzC,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,6BAA6B,CAAA;IAChD,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AA0CD,kGAAkG;AAClG,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,0BAA0B,EAAE,CAkB9B;AAqBD,kFAAkF;AAClF,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,YAAY,SAA4B,GACvC,MAAM,EAAE,CAeV;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,wBAAwB,GAC7B,uBAAuB,CAgDzB"}

package/dist/smartCdnImage.js

@@ -0,0 +1,137 @@
+const defaultSmartCdnImageFormats = { avif: 45, webp: 75 };
+const minimumMillisecondTimestamp = 1_000_000_000_000;
+const smartCdnImageFormats = ['avif', 'webp', 'png'];
+const smartCdnImageMaxWidths = 32;
+/** Maximum requested width or height accepted by the responsive-image Built-ins. */
+export const smartCdnImageMaxDimension = 8000;
+function isSmartCdnImageFormat(value) {
+    return value === 'avif' || value === 'png' || value === 'webp';
+}
+function validatePositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+function validateSmartCdnImageDimension(value, name) {
+    if (!Number.isInteger(value) || value < 1 || value > smartCdnImageMaxDimension) {
+        throw new RangeError(`${name} must be an integer from 1 through ${smartCdnImageMaxDimension}`);
+    }
+}
+function validateSmartCdnImageQuality(quality) {
+    if (!Number.isInteger(quality) || quality < 1 || quality > 100) {
+        throw new RangeError('quality must be an integer from 1 through 100');
+    }
+}
+function validateSmartCdnImageInput(input) {
+    if (typeof input !== 'string' || input === '' || input.trim() !== input || input.includes('|')) {
+        throw new TypeError('input must be one non-empty Template input string');
+    }
+}
+function validateSmartCdnImageFallbackUrl(fallbackUrl) {
+    if (typeof fallbackUrl !== 'string' || fallbackUrl === '' || fallbackUrl.trim() !== fallbackUrl) {
+        throw new TypeError('fallbackUrl must be a non-empty string without surrounding whitespace');
+    }
+}
+function validateSmartCdnImageTemplate(template) {
+    if (typeof template !== 'string' || template === '' || template.trim() !== template) {
+        throw new TypeError('template must be a non-empty string without surrounding whitespace');
+    }
+}
+/** Resolves and validates format-specific qualities in deterministic browser preference order. */
+export function resolveSmartCdnImageFormats(formats) {
+    const resolved = formats ?? defaultSmartCdnImageFormats;
+    for (const format of Object.keys(resolved)) {
+        if (!isSmartCdnImageFormat(format)) {
+            throw new TypeError(`Unsupported Smart CDN image format: ${format}`);
+        }
+    }
+    const selected = [];
+    for (const format of smartCdnImageFormats) {
+        if (!Object.hasOwn(resolved, format))
+            continue;
+        const quality = resolved[format];
+        if (quality === undefined)
+            continue;
+        validateSmartCdnImageQuality(quality);
+        selected.push({ format, quality });
+    }
+    if (selected.length === 0)
+        throw new TypeError('formats must contain at least one value');
+    return selected;
+}
+function getMaximumCandidateWidth(sourceDimensions) {
+    if (sourceDimensions === undefined)
+        return smartCdnImageMaxDimension;
+    validatePositiveSafeInteger(sourceDimensions.width, 'sourceDimensions.width');
+    validatePositiveSafeInteger(sourceDimensions.height, 'sourceDimensions.height');
+    const heightLimitedWidth = Number((BigInt(smartCdnImageMaxDimension) * BigInt(sourceDimensions.width)) /
+        BigInt(sourceDimensions.height));
+    if (heightLimitedWidth < 1) {
+        // Even a one-pixel-wide rendition would exceed the backend height limit; no truthful candidate
+        // can preserve this aspect ratio.
+        throw new RangeError('sourceDimensions aspect ratio cannot fit within backend dimensions');
+    }
+    return Math.min(smartCdnImageMaxDimension, sourceDimensions.width, heightLimitedWidth);
+}
+/** Validates, caps, deduplicates, and sorts requested responsive-image widths. */
+export function resolveSmartCdnImageWidths(widths, maximumWidth = smartCdnImageMaxDimension) {
+    if (!Array.isArray(widths) || widths.length === 0) {
+        throw new TypeError('widths must contain at least one value');
+    }
+    if (widths.length > smartCdnImageMaxWidths) {
+        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} values`);
+    }
+    validateSmartCdnImageDimension(maximumWidth, 'maximumWidth');
+    const candidates = new Set();
+    for (const [index, width] of widths.entries()) {
+        validateSmartCdnImageDimension(width, `widths[${index}]`);
+        candidates.add(Math.min(width, maximumWidth));
+    }
+    return [...candidates].sort((left, right) => left - right);
+}
+/**
+ * Creates signed responsive-image candidates while leaving credential storage and HMAC choice to
+ * the injected signer.
+ */
+export function createSmartCdnImageCandidates(options, sign) {
+    const expiresAt = options.expiresAt;
+    const fallbackUrl = options.fallbackUrl;
+    const formatOptions = options.formats;
+    const formatsSnapshot = formatOptions === undefined ? undefined : { ...formatOptions };
+    const input = options.input;
+    const sourceDimensionOptions = options.sourceDimensions;
+    const sourceDimensions = sourceDimensionOptions === undefined
+        ? undefined
+        : { height: sourceDimensionOptions.height, width: sourceDimensionOptions.width };
+    const template = options.template;
+    const widthOptions = options.widths;
+    const widthsSnapshot = Array.isArray(widthOptions) ? [...widthOptions] : widthOptions;
+    validatePositiveSafeInteger(expiresAt, 'expiresAt');
+    if (expiresAt < minimumMillisecondTimestamp) {
+        throw new RangeError('expiresAt must be a millisecond timestamp');
+    }
+    validateSmartCdnImageFallbackUrl(fallbackUrl);
+    validateSmartCdnImageInput(input);
+    validateSmartCdnImageTemplate(template);
+    if (typeof sign !== 'function')
+        throw new TypeError('sign must be a function');
+    const formats = resolveSmartCdnImageFormats(formatsSnapshot);
+    const widths = resolveSmartCdnImageWidths(widthsSnapshot, getMaximumCandidateWidth(sourceDimensions));
+    const sources = [];
+    for (const { format, quality } of formats) {
+        sources.push({
+            candidates: widths.map((width) => ({
+                url: sign({
+                    expiresAt,
+                    input,
+                    template,
+                    urlParams: { f: format, q: quality, r: 'fit', w: width },
+                }),
+                width,
+            })),
+            format,
+            quality,
+        });
+    }
+    return { fallbackUrl, sources };
+}

package/dist/storageGrant.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Transloadit Storage grant: a short-lived HS256 JWT an integrator's
+ * server mints (or api2's `POST /storage/grants` mints for it) and
+ * Companion's S3 provider verifies. This module is the one wire contract —
+ * claim shape, decoding, and (in `@transloadit/utils/node`) minting and
+ * verification — so the implementations cannot drift apart.
+ *
+ * Everything in this file is browser-safe: the client may *read* a grant's
+ * claims to decide what UI to show, but verification is the server's job.
+ */
+export declare const STORAGE_GRANT_SCOPES: readonly ["read", "write"];
+export type StorageGrantScope = (typeof STORAGE_GRANT_SCOPES)[number];
+export type StorageGrantClaims = {
+    v: 1;
+    /** The workspace slug ("bucket" in S3 terms). */
+    bucket: string;
+    /** Key prefix the session is confined to; may be empty. */
+    prefix: string;
+    scopes: StorageGrantScope[];
+    /** Who the grant was minted for (informational). */
+    sub?: string;
+    /** Unix seconds. */
+    iat?: number;
+    /** Unix seconds. */
+    exp: number;
+};
+/**
+ * Validates a decoded JWT payload against the grant contract. Returns the
+ * claims (scopes deduplicated) or null when the shape is not a v1 grant.
+ */
+export declare const parseStorageGrantClaims: (payload: unknown) => StorageGrantClaims | null;
+/** Companion's prefix policy: no leading slashes, a trailing slash unless empty. */
+export declare const normalizeStorageGrantPrefix: (prefix: string) => string;
+/**
+ * Reads a grant's payload without verifying the signature — for clients that
+ * only need to know what the session will be allowed to do. Returns null for
+ * anything that does not decode to a v1 grant.
+ */
+export declare const decodeStorageGrant: (token: string) => StorageGrantClaims | null;
+//# sourceMappingURL=storageGrant.d.ts.map

package/dist/storageGrant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageGrant.d.ts","sourceRoot":"","sources":["../src/storageGrant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,oBAAoB,4BAA6B,CAAA;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAA;AAErE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,EAAE,CAAC,CAAA;IACJ,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAKD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,OAAO,KAAG,kBAAkB,GAAG,IAyB/E,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,2BAA2B,GAAI,QAAQ,MAAM,KAAG,MAG5D,CAAA;AASD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,kBAAkB,GAAG,IAQvE,CAAA"}

package/dist/storageGrant.js

@@ -0,0 +1,64 @@
+/**
+ * The Transloadit Storage grant: a short-lived HS256 JWT an integrator's
+ * server mints (or api2's `POST /storage/grants` mints for it) and
+ * Companion's S3 provider verifies. This module is the one wire contract —
+ * claim shape, decoding, and (in `@transloadit/utils/node`) minting and
+ * verification — so the implementations cannot drift apart.
+ *
+ * Everything in this file is browser-safe: the client may *read* a grant's
+ * claims to decide what UI to show, but verification is the server's job.
+ */
+export const STORAGE_GRANT_SCOPES = ['read', 'write'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Validates a decoded JWT payload against the grant contract. Returns the
+ * claims (scopes deduplicated) or null when the shape is not a v1 grant.
+ */
+export const parseStorageGrantClaims = (payload) => {
+    if (!isRecord(payload) ||
+        payload.v !== 1 ||
+        typeof payload.bucket !== 'string' ||
+        payload.bucket.length === 0 ||
+        typeof payload.prefix !== 'string' ||
+        !Array.isArray(payload.scopes) ||
+        !payload.scopes.every((scope) => typeof scope === 'string' && STORAGE_GRANT_SCOPES.includes(scope)) ||
+        typeof payload.exp !== 'number') {
+        return null;
+    }
+    return {
+        v: 1,
+        bucket: payload.bucket,
+        prefix: payload.prefix,
+        scopes: [...new Set(payload.scopes)],
+        ...(typeof payload.sub === 'string' && { sub: payload.sub }),
+        ...(typeof payload.iat === 'number' && { iat: payload.iat }),
+        exp: payload.exp,
+    };
+};
+/** Companion's prefix policy: no leading slashes, a trailing slash unless empty. */
+export const normalizeStorageGrantPrefix = (prefix) => {
+    const cleaned = prefix.replace(/^\/+/, '');
+    return cleaned.length === 0 || cleaned.endsWith('/') ? cleaned : `${cleaned}/`;
+};
+const decodeBase64UrlToUtf8 = (input) => {
+    const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+};
+/**
+ * Reads a grant's payload without verifying the signature — for clients that
+ * only need to know what the session will be allowed to do. Returns null for
+ * anything that does not decode to a v1 grant.
+ */
+export const decodeStorageGrant = (token) => {
+    try {
+        const payload = token.split('.')[1];
+        if (payload === undefined || payload.length === 0)
+            return null;
+        return parseStorageGrantClaims(JSON.parse(decodeBase64UrlToUtf8(payload)));
+    }
+    catch {
+        return null;
+    }
+};

package/package.json

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