@nitida/asset-client 0.21.0 → 0.24.0

package/AGENTS.md

@@ -47,6 +47,13 @@ schemas, not against a hand-kept list.
    *guesses* — the server keys the original off the **uploaded filename**, which the mime does not
    determine — and with neither it emits the `-o.bin` sentinel and 404s forever.
 
+The ladder itself — **generated from `TRANSFORM_WIDTHS`, do not edit by hand.**
+`bun run gen:docs` rewrites it; `--check` fails the build if it drifts:
+
+<!-- BEGIN GENERATED: transform-widths · bun run gen:docs -->
+`96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 21 widths.
+<!-- END GENERATED: transform-widths -->
+
 ## Existence checks
 
 Use `hasPreset(asset, preset)` against `dto.presets` (the compact code string). It is on every

package/README.md

@@ -43,10 +43,15 @@ getTransformUrl({ sha }, { format: "webp", width: 640 });
 getTransformSrcSet({ sha }, [640, 960, 1280], { format: "webp" });
 ```
 
-⚠️ **Widths must be on the unsigned ladder** `TRANSFORM_WIDTHS`
-(`96,128,160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840` — 20 widths). Anything else
-is **HTTP 400** at the edge — it is a DoS guard, not a bug. Import the `TransformWidth` type and an
-off-ladder number becomes a compile error instead of a runtime 400.
+⚠️ **Widths must be on the unsigned ladder** `TRANSFORM_WIDTHS` — generated from the source, do not
+edit by hand:
+
+<!-- BEGIN GENERATED: transform-widths · bun run gen:docs -->
+`96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 21 widths.
+<!-- END GENERATED: transform-widths -->
+
+Anything else is **HTTP 400** at the edge — it is a DoS guard, not a bug. Import the `TransformWidth`
+type and an off-ladder number becomes a compile error instead of a runtime 400.
 
 ## Video — the stored variant, not a transform
 

package/dist/index.cjs

@@ -20,6 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS: () => MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS: () => MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS: () => MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   PRESET_EXT: () => PRESET_EXT,
   PRESET_LONG: () => PRESET_LONG,
   PRESET_MAX_DIM: () => PRESET_MAX_DIM,
@@ -34,11 +37,13 @@ __export(index_exports, {
   configureSlotResolver: () => configureSlotResolver,
   contrastRatio: () => contrastRatio,
   deriveAccessKey: () => deriveAccessKey,
+  deriveTransformKid: () => deriveTransformKid,
   extractAssetSha: () => extractAssetSha,
   getAmbientGradient: () => getAmbientGradient,
   getAssetDimensions: () => getAssetDimensions,
   getAssetSrcSet: () => getAssetSrcSet,
   getAssetUrl: () => getAssetUrl,
+  getByteBudgetTransformUrl: () => getByteBudgetTransformUrl,
   getCdnBase: () => getCdnBase,
   getHlsLadder: () => getHlsLadder,
   getHlsStreamingUrl: () => getHlsStreamingUrl,
@@ -53,6 +58,7 @@ __export(index_exports, {
   getTransformUrl: () => getTransformUrl,
   getVideoTransformUrl: () => getVideoTransformUrl,
   hasPreset: () => hasPreset,
+  hasSizeLadder: () => hasSizeLadder,
   hlsLadderAlignment: () => hlsLadderAlignment,
   invalidateSlotCache: () => invalidateSlotCache,
   isRequestablePreset: () => isRequestablePreset,
@@ -66,7 +72,8 @@ __export(index_exports, {
   setTenantId: () => setTenantId,
   signAccessUrl: () => signAccessUrl,
   signTransformUrl: () => signTransformUrl,
-  toRequestablePresets: () => toRequestablePresets
+  toRequestablePresets: () => toRequestablePresets,
+  transformMessage: () => transformMessage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -97,12 +104,18 @@ function accessMessage(tenantPrefix, exp, resourcePath) {
 ${exp}
 ${resourcePath.replace(/^\/+/, "")}`;
 }
+var MAX_SIGNED_URL_TTL_SECONDS = 7 * 24 * 60 * 60;
 async function signAccessUrl(publicUrl, signingKey, opts) {
   if (!Number.isFinite(opts.expiresInSeconds) || opts.expiresInSeconds <= 0) {
     throw new Error(
       "signAccessUrl: `expiresInSeconds` must be a positive number \u2014 a signed URL without an expiry is a public URL the moment it is forwarded."
     );
   }
+  if (opts.expiresInSeconds > MAX_SIGNED_URL_TTL_SECONDS) {
+    throw new Error(
+      `signAccessUrl: \`expiresInSeconds\` may not exceed ${MAX_SIGNED_URL_TTL_SECONDS} (7 days). Both verifiers refuse a longer one, so this would build a URL that 401s. An expiry that never arrives is not an expiry.`
+    );
+  }
   const u = new URL(publicUrl);
   const segments = u.pathname.split("/").filter(Boolean);
   if (segments[0] === "a" && segments[2] && /^[vrt]$/.test(segments[2])) {
@@ -258,6 +271,7 @@ var TRANSFORM_WIDTHS = [
   96,
   128,
   160,
+  180,
   240,
   256,
   320,
@@ -361,7 +375,38 @@ function getTransformUrl(asset, opts) {
   );
   return buildTransformUrl(asset, opts);
 }
-function getSignedTransformUrl(asset, opts, signingKey) {
+var LADDER_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
+function hasSizeLadder(asset) {
+  const raw = asset.presets;
+  if (raw == null || raw.trim() === "") return null;
+  return LADDER_PRESETS.some((preset) => hasPreset(asset, preset));
+}
+function getByteBudgetTransformUrl(asset, opts) {
+  assertSha(asset, "getByteBudgetTransformUrl");
+  assertPublic(
+    asset,
+    "getByteBudgetTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
+  if (!Number.isInteger(opts.quality) || opts.quality < 1 || opts.quality > 100) {
+    throw new Error(
+      `getByteBudgetTransformUrl: quality must be an integer 1..100, got ${String(opts.quality)}. If you do not have a measured byte budget, use getTransformUrl and omit quality entirely.`
+    );
+  }
+  const ladder = hasSizeLadder(asset);
+  if (ladder === null) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} carries no 'presets', so whether a pinned quality would re-compress it is UNKNOWN \u2014 and unknown is not permission. Fetch the full DTO (assets.get / assets.byHash) and pass it, or use getTransformUrl with no quality.`
+    );
+  }
+  if (ladder) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} has stored size variants (presets="${asset.presets}"). A pinned quality there does not set the encoder \u2014 it makes /t/ decode one of those already-compressed variants, so the output is a SECOND lossy generation: measured +2..+8% HEAVIER and -0.50..-0.85 dB. Use getTransformUrl with no quality (one pass from the master), or upload this asset with presets: ["original"] if the byte budget is real.`
+    );
+  }
+  return buildTransformUrl(asset, opts);
+}
+function getSignedTransformUrl(asset, opts, signingKey, signOpts) {
   assertSha(asset, "getSignedTransformUrl");
   assertPublic(
     asset,
@@ -370,9 +415,34 @@ function getSignedTransformUrl(asset, opts, signingKey) {
   );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
-  return signTransformUrl(url, signingKey);
-}
-async function signTransformUrl(unsignedUrl, signingKey) {
+  return signTransformUrl(url, signingKey, signOpts);
+}
+var TRANSFORM_SIG_DOMAIN = "nitida/transform/v2";
+var KID_INFO = "nitida/kid/v1";
+var MAX_SIGNED_TRANSFORM_TTL_SECONDS = 7 * 24 * 60 * 60;
+var MIN_SIGNED_TRANSFORM_TTL_SECONDS = 120;
+async function deriveTransformKid(signingKey) {
+  return (await hmacSha256Hex(signingKey, KID_INFO)).slice(0, 8);
+}
+function transformMessage(args) {
+  return `${TRANSFORM_SIG_DOMAIN}
+${args.tenantPrefix}
+${args.exp}
+${args.canonicalDsl}/${args.filename}`;
+}
+async function signTransformUrl(unsignedUrl, signingKey, opts) {
+  const ttl = Math.floor(opts.expiresInSeconds);
+  if (!Number.isFinite(ttl) || ttl < MIN_SIGNED_TRANSFORM_TTL_SECONDS || ttl > MAX_SIGNED_TRANSFORM_TTL_SECONDS) {
+    throw new Error(
+      `signTransformUrl: \`expiresInSeconds\` must be between ${MIN_SIGNED_TRANSFORM_TTL_SECONDS} and ${MAX_SIGNED_TRANSFORM_TTL_SECONDS}. The platform refuses a longer one on every verify, so a bigger number here just builds a URL that 401s.`
+    );
+  }
+  const tid = opts.tenantId ?? getTenantId();
+  if (tid == null) {
+    throw new Error(
+      "signTransformUrl: no tenant is configured. Call setTenantId(id) (or construct a NitidaClient with `tenantId`) \u2014 the tenant is part of what the signature covers, so this cannot be guessed."
+    );
+  }
   const u = new URL(unsignedUrl);
   const parts = u.pathname.split("/").filter(Boolean);
   if (parts[0] !== "t" || parts.length < 3) {
@@ -380,8 +450,19 @@ async function signTransformUrl(unsignedUrl, signingKey) {
   }
   const filename = parts[parts.length - 1];
   const dsl = parts.slice(1, -1).join("/");
-  const message = `${dsl}/${filename}`;
-  const sig = await hmacSha256Hex(signingKey, message);
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = Math.floor((now + ttl) / 60) * 60;
+  const sig = await hmacSha256Hex(
+    signingKey,
+    transformMessage({
+      tenantPrefix: tid.toString(36),
+      exp,
+      canonicalDsl: dsl,
+      filename
+    })
+  );
+  u.searchParams.set("kid", await deriveTransformKid(signingKey));
+  u.searchParams.set("exp", String(exp));
   u.searchParams.set("sig", sig);
   return u.toString();
 }
@@ -508,16 +589,16 @@ function materializeResolution(dto, overridePreset) {
 
 // src/index.ts
 var REQUESTABLE_PRESETS = [
-  "thumb",
-  "sm",
-  "md",
+  "aiproxy",
   "lg",
-  "xl",
+  "md",
   "original",
   "poster",
+  "probe",
+  "sm",
+  "thumb",
   "video",
-  "aiproxy",
-  "probe"
+  "xl"
 ];
 var isRequestablePreset = (v) => REQUESTABLE_PRESETS.includes(v);
 var toRequestablePresets = (input) => {
@@ -756,6 +837,9 @@ function getAssetDimensions(asset) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
@@ -770,11 +854,13 @@ function getAssetDimensions(asset) {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl,
@@ -789,6 +875,7 @@ function getAssetDimensions(asset) {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,
@@ -802,6 +889,7 @@ function getAssetDimensions(asset) {
   setTenantId,
   signAccessUrl,
   signTransformUrl,
-  toRequestablePresets
+  toRequestablePresets,
+  transformMessage
 });
 //# sourceMappingURL=index.cjs.map