@nitida/asset-client 0.20.4 → 0.23.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,6 +37,7 @@ __export(index_exports, {
   configureSlotResolver: () => configureSlotResolver,
   contrastRatio: () => contrastRatio,
   deriveAccessKey: () => deriveAccessKey,
+  deriveTransformKid: () => deriveTransformKid,
   extractAssetSha: () => extractAssetSha,
   getAmbientGradient: () => getAmbientGradient,
   getAssetDimensions: () => getAssetDimensions,
@@ -66,7 +70,8 @@ __export(index_exports, {
   setTenantId: () => setTenantId,
   signAccessUrl: () => signAccessUrl,
   signTransformUrl: () => signTransformUrl,
-  toRequestablePresets: () => toRequestablePresets
+  toRequestablePresets: () => toRequestablePresets,
+  transformMessage: () => transformMessage
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -97,12 +102,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 +269,7 @@ var TRANSFORM_WIDTHS = [
   96,
   128,
   160,
+  180,
   240,
   256,
   320,
@@ -361,7 +373,7 @@ function getTransformUrl(asset, opts) {
   );
   return buildTransformUrl(asset, opts);
 }
-function getSignedTransformUrl(asset, opts, signingKey) {
+function getSignedTransformUrl(asset, opts, signingKey, signOpts) {
   assertSha(asset, "getSignedTransformUrl");
   assertPublic(
     asset,
@@ -370,9 +382,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 +417,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 +556,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) => {
@@ -687,6 +735,11 @@ function buildPublicAssetUrl(asset, preset, caller) {
   if (preset === "hls") {
     const stored = asset.variants?.find((v) => v.preset === "hls")?.url;
     if (stored) return stored;
+    if (asset.kind != null && asset.kind !== "video") {
+      throw new Error(
+        `${caller}: this asset is \`${asset.kind}\`, and only a video has an HLS ladder. Asking for \`hls\` here would build \`/t/format=hls/<sha>.m3u8\`, which does NOT 404 \u2014 the edge answers 200 with the image bytes under an .m3u8 name, so a player fails with no way to see why. For an image use a size preset (\`${caller}(asset, "md")\`) or a transform (\`getTransformUrl\`); for audio use \`mp3\`.`
+      );
+    }
     return `${cdnBaseUrl}/t/format=hls/${asset.sha}.m3u8`;
   }
   return `${cdnBaseUrl}/${variantPrefix(caller)}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
@@ -751,6 +804,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,
@@ -765,6 +821,7 @@ function getAssetDimensions(asset) {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -797,6 +854,7 @@ function getAssetDimensions(asset) {
   setTenantId,
   signAccessUrl,
   signTransformUrl,
-  toRequestablePresets
+  toRequestablePresets,
+  transformMessage
 });
 //# sourceMappingURL=index.cjs.map