@nitida/asset-client 0.17.0 → 0.18.0

package/AGENTS.md

@@ -66,6 +66,32 @@ now emits only the 1-char vocabulary, and `hasPreset` strips multi-char tokens b
 either half covers you — a hand-rolled `includes` covers neither. **`mp3` is a deliberate multi-char
 token that stays in the vocabulary**, so a naive test also reads its `m` as `md`.
 
+
+## Private assets — `visibility`
+
+Default is `"public"`. Set `private` and **every public door answers 404** —
+stored variants, the raw original, the HLS ladder, and `/t/` (including the
+poster frame of a private video). The bytes come back only through a signed URL
+that expires.
+
+```ts
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+// ON YOUR BACKEND, once you decided this viewer may see it:
+await getPrivateAssetUrl(asset, "lg", signingKey, { expiresInSeconds: 300 });
+await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeconds: 300 });
+```
+
+- **A 404 on a private asset is NOT a missing file.** Check `visibility` on the
+  DTO before you check storage. It is the number-one support question.
+- **Seven URL builders throw** rather than hand you a doomed URL — `getAssetUrl`,
+  `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+  `getVideoTransformUrl`, `getHlsStreamingUrl`, `getSignedTransformUrl` — but
+  only when the value you pass carries `visibility`. `{ sha }` alone is never
+  refused.
+- **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
+- **The signing key is a backend secret** — it mints URLs for every private
+  asset the tenant owns.
+
 ## The endpoint
 
 The API this client's URLs belong to is `https://api.nitida.gofuture.space`. An older, longer

package/README.md

@@ -44,7 +44,7 @@ getTransformSrcSet({ sha }, [640, 960, 1280], { format: "webp" });
 ```
 
 ⚠️ **Widths must be on the unsigned ladder** `TRANSFORM_WIDTHS`
-(`160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840`). Anything else
+(`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.
 
@@ -62,7 +62,10 @@ getAssetUrl({ sha }, "video");   // → https://8ok.uk/<tenantId base36>/v/<sha1
 `getAssetUrl` build the path.
 
 ⚠️ **Never `getVideoTransformUrl` for a stored video.** That builds a `/t/…` transform URL, which
-**410s** for a stored video sha. It is for on-the-fly re-encodes, a different feature.
+does NOT give you the video. On a video sha it transforms the **poster frame**
+and answers `200 image/webp` (`x-transform-source: poster`) — useful, but an
+image. If that video has no poster it answers `410`. Either way you never get
+playable video out of `/t/`; use `getAssetUrl(asset, "video")`.
 
 ## The `original` variant
 
@@ -119,7 +122,7 @@ shape. `presets` is populated everywhere, on every version — so read existence
 | Symptom | Cause |
 |---|---|
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` |
-| **410** on a video URL | used `/t/` (transform) for a stored video |
+| **410** on a video `/t/` URL | that video has no `poster` variant. With one, `/t/` returns the poster as an image — never the video. Use `getAssetUrl(asset, "video")` |
 | **404** on a video URL | decimal tenant prefix instead of base36 |
 | `original` 404s | no `mime` passed, or the stored ext came from the filename (`-o.jpg` vs `-o.jpeg`), or it was never written |
 

package/dist/index.cjs

@@ -25,10 +25,13 @@ __export(index_exports, {
   PRESET_MAX_DIM: () => PRESET_MAX_DIM,
   PRESET_SHORT: () => PRESET_SHORT,
   TRANSFORM_WIDTHS: () => TRANSFORM_WIDTHS,
+  accessMessage: () => accessMessage,
+  assertPublic: () => assertPublic,
   bestTextContrast: () => bestTextContrast,
   computeVariantDimensions: () => computeVariantDimensions,
   configureSlotResolver: () => configureSlotResolver,
   contrastRatio: () => contrastRatio,
+  deriveAccessKey: () => deriveAccessKey,
   extractAssetSha: () => extractAssetSha,
   getAmbientGradient: () => getAmbientGradient,
   getAssetDimensions: () => getAssetDimensions,
@@ -39,6 +42,8 @@ __export(index_exports, {
   getHlsStreamingUrl: () => getHlsStreamingUrl,
   getPaletteBlurBackground: () => getPaletteBlurBackground,
   getPaletteCssVars: () => getPaletteCssVars,
+  getPrivateAssetUrl: () => getPrivateAssetUrl,
+  getPrivateTransformUrl: () => getPrivateTransformUrl,
   getSignedTransformUrl: () => getSignedTransformUrl,
   getTenantId: () => getTenantId,
   getTextColorForBackground: () => getTextColorForBackground,
@@ -56,10 +61,81 @@ __export(index_exports, {
   serializeTransform: () => serializeTransform,
   setCdnBase: () => setCdnBase,
   setTenantId: () => setTenantId,
+  signAccessUrl: () => signAccessUrl,
   signTransformUrl: () => signTransformUrl
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/access.ts
+var ACCESS_KEY_INFO = "nitida/access/v1";
+async function hmac(key, message) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return new Uint8Array(
+    await crypto.subtle.sign(
+      "HMAC",
+      cryptoKey,
+      new TextEncoder().encode(message)
+    )
+  );
+}
+var toHex = (b) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+async function deriveAccessKey(signingKey) {
+  return hmac(new TextEncoder().encode(signingKey), ACCESS_KEY_INFO);
+}
+function accessMessage(tenantPrefix, exp, resourcePath) {
+  return `${tenantPrefix}
+${exp}
+${resourcePath.replace(/^\/+/, "")}`;
+}
+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."
+    );
+  }
+  const u = new URL(publicUrl);
+  const segments = u.pathname.split("/").filter(Boolean);
+  if (segments[0] === "a" && segments[2] && /^[vrt]$/.test(segments[2])) {
+    segments.shift();
+  }
+  const tenantPrefix = segments.shift();
+  if (!tenantPrefix || segments.length === 0) {
+    throw new Error(
+      `signAccessUrl: expected a tenant-prefixed CDN path like /<tenant>/v/<sha>-<preset>.<ext>, got ${u.pathname}`
+    );
+  }
+  if (!/^[vrt]$/.test(segments[0])) {
+    throw new Error(
+      `signAccessUrl: expected /<tenant>/<v|r|t>/\u2026 but the segment after the tenant is "${segments[0]}". ` + (segments[0]?.includes("=") ? `That looks like a transform DSL, so the path is probably /t/<dsl>/<sha>.<ext> \u2014 which has no tenant in it (\`t\` here was read as tenant ${Number.parseInt(tenantPrefix, 36)}). Use getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds }) instead.` : `Got ${u.pathname}.`)
+    );
+  }
+  const resourcePath = segments.join("/");
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = now + Math.floor(opts.expiresInSeconds);
+  const sig = toHex(
+    await hmac(
+      await deriveAccessKey(signingKey),
+      accessMessage(tenantPrefix, exp, resourcePath)
+    )
+  );
+  u.pathname = `/a/${tenantPrefix}/${resourcePath}`;
+  u.searchParams.set("exp", String(exp));
+  u.searchParams.set("sig", sig);
+  return u.toString();
+}
+function assertPublic(asset, fn, escape) {
+  if (asset.visibility !== "private") return;
+  throw new Error(
+    `${fn}: this asset is private, so a public CDN URL for it will answer 404 \u2014 that is the feature, not a missing file. Mint a signed URL on your BACKEND instead: await ${escape}. Never ship the signing key to a browser.`
+  );
+}
+
 // src/palette.ts
 function resolveSwatch(palette, ...keys) {
   if (!palette) return null;
@@ -77,9 +153,9 @@ function pickAmbientBackground(palette) {
 function getAmbientGradient(palette, opts = {}) {
   if (!palette) return void 0;
   const fromHex = palette[opts.from ?? "lm"] ?? palette.m ?? palette.d;
-  const toHex = palette[opts.to ?? "m"] ?? palette.dm ?? palette.d;
-  if (!fromHex || !toHex) return void 0;
-  return `linear-gradient(${opts.angle ?? "135deg"}, ${fromHex}, ${toHex})`;
+  const toHex2 = palette[opts.to ?? "m"] ?? palette.dm ?? palette.d;
+  if (!fromHex || !toHex2) return void 0;
+  return `linear-gradient(${opts.angle ?? "135deg"}, ${fromHex}, ${toHex2})`;
 }
 function getTextColorForBackground(swatch) {
   if (!swatch) return "#000000";
@@ -164,102 +240,6 @@ function getPaletteBlurBackground(palette) {
   return layers.length > 0 ? `${layers.join(", ")}, ${base}` : base;
 }
 
-// src/slots.ts
-var DEFAULT_TTL_MS = 6e4;
-var cache = /* @__PURE__ */ new Map();
-var endpoint = "https://api.nitida.gofuture.space";
-var apiKey = null;
-var tenantCode = null;
-function configureSlotResolver(opts) {
-  if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
-  if (opts.apiKey !== void 0) apiKey = opts.apiKey;
-  if (opts.tenantCode !== void 0) tenantCode = opts.tenantCode;
-}
-function invalidateSlotCache(slotKey) {
-  if (slotKey === void 0) cache.clear();
-  else
-    for (const k of cache.keys())
-      if (k.endsWith(`:${slotKey}`)) cache.delete(k);
-}
-var baseHeaders = () => {
-  const h = {};
-  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
-  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
-  return h;
-};
-async function fetchSlot(slotKey) {
-  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
-    headers: baseHeaders()
-  });
-  if (r.status === 404) return null;
-  if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
-  return await r.json();
-}
-async function fetchSlotsBulk(slotKeys) {
-  if (slotKeys.length === 0) return {};
-  const r = await fetch(`${endpoint}/slots/resolve`, {
-    method: "POST",
-    headers: { ...baseHeaders(), "Content-Type": "application/json" },
-    body: JSON.stringify({ keys: slotKeys })
-  });
-  if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
-  const body = await r.json();
-  return body.resolved;
-}
-async function resolveSlot(slotKey, opts = {}) {
-  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
-  const now = Date.now();
-  let dto;
-  const hit = cache.get(cacheKey);
-  if (hit && now - hit.fetchedAt < ttl) {
-    dto = hit.value;
-  } else {
-    dto = await fetchSlot(slotKey);
-    cache.set(cacheKey, { fetchedAt: now, value: dto });
-  }
-  return materializeResolution(dto, opts.preset);
-}
-async function resolveSlots(slotKeys, opts = {}) {
-  if (slotKeys.length === 0) return {};
-  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const now = Date.now();
-  const missing = [];
-  const out = {};
-  for (const k of slotKeys) {
-    const cacheKey = `${tenantCode ?? "_"}:${k}`;
-    const hit = cache.get(cacheKey);
-    if (hit && now - hit.fetchedAt < ttl) {
-      out[k] = materializeResolution(hit.value, opts.preset);
-    } else {
-      missing.push(k);
-    }
-  }
-  if (missing.length > 0) {
-    const resolved = await fetchSlotsBulk(missing);
-    for (const k of missing) {
-      const dto = resolved[k] ?? null;
-      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
-      out[k] = materializeResolution(dto, opts.preset);
-    }
-  }
-  return out;
-}
-function defaultPresetFor(asset) {
-  if (!asset) return "lg";
-  return asset.kind === "video" ? "video" : "lg";
-}
-function materializeResolution(dto, overridePreset) {
-  if (!dto) return { slot: null, preset: overridePreset ?? "lg", url: null };
-  const effective = overridePreset ?? dto.preset ?? defaultPresetFor(dto.asset);
-  const finalPreset = hasPreset(dto.asset, effective) ? effective : defaultPresetFor(dto.asset);
-  return {
-    slot: dto,
-    preset: finalPreset,
-    url: getAssetUrl(dto.asset, finalPreset)
-  };
-}
-
 // src/transform.ts
 var TRANSFORM_WIDTHS = [
   96,
@@ -331,12 +311,22 @@ function extForOptions(opts) {
   }
 }
 function getVideoTransformUrl(asset, opts) {
+  assertPublic(
+    asset,
+    "getVideoTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
   const ext = opts.format === "webm" ? "webm" : "mp4";
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getHlsStreamingUrl(asset, opts = {}) {
+  assertPublic(
+    asset,
+    "getHlsStreamingUrl",
+    'getPrivateAssetUrl(asset, "hls", signingKey, { expiresInSeconds: 300 }) \u2014 the worker re-signs the playlist children'
+  );
   const merged = { ...opts, format: "hls" };
   const dsl = serializeTransform(merged);
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.m3u8`;
@@ -348,9 +338,19 @@ function buildTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getTransformUrl(asset, opts) {
+  assertPublic(
+    asset,
+    "getTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   return buildTransformUrl(asset, opts);
 }
 function getSignedTransformUrl(asset, opts, signingKey) {
+  assertPublic(
+    asset,
+    "getSignedTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
   return signTransformUrl(url, signingKey);
@@ -381,12 +381,113 @@ async function hmacSha256Hex(key, message) {
   return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function getTransformSrcSet(asset, widths, extraOpts = {}) {
+  assertPublic(
+    asset,
+    "getTransformSrcSet",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 }) per width"
+  );
   return widths.map((w) => {
     const url = buildTransformUrl(asset, { ...extraOpts, width: w });
     return url ? `${url} ${w}w` : null;
   }).filter((s) => s != null).join(", ");
 }
 
+// src/slots.ts
+var DEFAULT_TTL_MS = 6e4;
+var cache = /* @__PURE__ */ new Map();
+var endpoint = "https://api.nitida.gofuture.space";
+var apiKey = null;
+var tenantCode = null;
+function configureSlotResolver(opts) {
+  if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
+  if (opts.apiKey !== void 0) apiKey = opts.apiKey;
+  if (opts.tenantCode !== void 0) tenantCode = opts.tenantCode;
+}
+function invalidateSlotCache(slotKey) {
+  if (slotKey === void 0) cache.clear();
+  else
+    for (const k of cache.keys())
+      if (k.endsWith(`:${slotKey}`)) cache.delete(k);
+}
+var baseHeaders = () => {
+  const h = {};
+  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
+  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
+  return h;
+};
+async function fetchSlot(slotKey) {
+  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
+    headers: baseHeaders()
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
+  return await r.json();
+}
+async function fetchSlotsBulk(slotKeys) {
+  if (slotKeys.length === 0) return {};
+  const r = await fetch(`${endpoint}/slots/resolve`, {
+    method: "POST",
+    headers: { ...baseHeaders(), "Content-Type": "application/json" },
+    body: JSON.stringify({ keys: slotKeys })
+  });
+  if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
+  const body = await r.json();
+  return body.resolved;
+}
+async function resolveSlot(slotKey, opts = {}) {
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
+  const now = Date.now();
+  let dto;
+  const hit = cache.get(cacheKey);
+  if (hit && now - hit.fetchedAt < ttl) {
+    dto = hit.value;
+  } else {
+    dto = await fetchSlot(slotKey);
+    cache.set(cacheKey, { fetchedAt: now, value: dto });
+  }
+  return materializeResolution(dto, opts.preset);
+}
+async function resolveSlots(slotKeys, opts = {}) {
+  if (slotKeys.length === 0) return {};
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const now = Date.now();
+  const missing = [];
+  const out = {};
+  for (const k of slotKeys) {
+    const cacheKey = `${tenantCode ?? "_"}:${k}`;
+    const hit = cache.get(cacheKey);
+    if (hit && now - hit.fetchedAt < ttl) {
+      out[k] = materializeResolution(hit.value, opts.preset);
+    } else {
+      missing.push(k);
+    }
+  }
+  if (missing.length > 0) {
+    const resolved = await fetchSlotsBulk(missing);
+    for (const k of missing) {
+      const dto = resolved[k] ?? null;
+      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
+      out[k] = materializeResolution(dto, opts.preset);
+    }
+  }
+  return out;
+}
+function defaultPresetFor(asset) {
+  if (!asset) return "lg";
+  return asset.kind === "video" ? "video" : "lg";
+}
+function materializeResolution(dto, overridePreset) {
+  if (!dto) return { slot: null, preset: overridePreset ?? "lg", url: null };
+  const effective = overridePreset ?? dto.preset ?? defaultPresetFor(dto.asset);
+  const finalPreset = hasPreset(dto.asset, effective) ? effective : defaultPresetFor(dto.asset);
+  return {
+    slot: dto,
+    preset: finalPreset,
+    url: getAssetUrl(dto.asset, finalPreset)
+  };
+}
+
 // src/index.ts
 var PRESET_SHORT = {
   thumb: "q",
@@ -513,6 +614,23 @@ function originalExtForMime(mime) {
   return (mime ? ORIGINAL_EXT_BY_MIME[mime] : void 0) ?? PRESET_EXT.original;
 }
 function getAssetUrl(asset, preset) {
+  assertPublic(
+    asset,
+    "getAssetUrl",
+    `getPrivateAssetUrl(asset, "${preset}", signingKey, { expiresInSeconds: 300 })`
+  );
+  const fallback = transformFallbackFor(asset, preset);
+  if (fallback) return fallback;
+  return buildPublicAssetUrl(asset, preset);
+}
+function transformFallbackFor(asset, preset) {
+  if (typeof asset.presets !== "string") return null;
+  if (hasPreset({ presets: asset.presets }, preset)) return null;
+  const maxDim = PRESET_MAX_DIM[preset];
+  if (maxDim == null) return null;
+  return `${cdnBaseUrl}/t/format=webp,width=${maxDim}/${asset.sha}.webp`;
+}
+function buildPublicAssetUrl(asset, preset) {
   if (preset === "original") {
     const stored = asset.variants?.find((v) => v.preset === "original")?.url;
     if (stored) return stored;
@@ -526,6 +644,25 @@ function getAssetUrl(asset, preset) {
   }
   return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
+async function getPrivateAssetUrl(asset, preset, signingKey, opts) {
+  return signAccessUrl(buildPublicAssetUrl(asset, preset), signingKey, opts);
+}
+async function getPrivateTransformUrl(asset, opts, signingKey, signOpts) {
+  const url = buildTransformUrl(asset, opts);
+  if (!url) return null;
+  const tid = getTenantId();
+  if (tid == null) {
+    throw new Error(
+      "getPrivateTransformUrl: 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(url);
+  return signAccessUrl(
+    `${u.origin}/${tid.toString(36)}${u.pathname}`,
+    signingKey,
+    signOpts
+  );
+}
 function hasPreset(asset, preset) {
   if (preset === "mp3") return asset.presets.includes("mp3");
   return stripMultiCharTokens(asset.presets).includes(PRESET_SHORT[preset]);
@@ -535,6 +672,11 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertPublic(
+    asset,
+    "getAssetSrcSet",
+    "getPrivateAssetUrl(asset, preset, signingKey, { expiresInSeconds: 300 }) per preset"
+  );
   return IMAGE_PRESETS.filter(
     (p) => hasPreset(asset, p) && PRESET_MAX_DIM[p] != null
   ).map((p) => `${getAssetUrl(asset, p)} ${PRESET_MAX_DIM[p]}w`).join(", ");
@@ -561,10 +703,13 @@ function getAssetDimensions(asset) {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   TRANSFORM_WIDTHS,
+  accessMessage,
+  assertPublic,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -575,6 +720,8 @@ function getAssetDimensions(asset) {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -592,6 +739,7 @@ function getAssetDimensions(asset) {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl
 });
 //# sourceMappingURL=index.cjs.map