@nitida/asset-client 0.17.0 → 0.18.1

package/src/access.ts

@@ -0,0 +1,232 @@
+/**
+ * Signed URLs for PRIVATE assets — the `/a/{tenant}/…?exp&sig` tree.
+ *
+ * ## Who calls this, and who must not
+ *
+ * The tenant's BACKEND, which knows who the viewer is and holds the signing
+ * key. Never a browser: shipping the signing key to the client would let any
+ * visitor mint URLs for any private asset of that tenant, which is the whole
+ * property the tree exists to provide. This module is deliberately importable
+ * from anywhere — it runs on WebCrypto, so browsers, Node, Bun and Workers all
+ * work — and that convenience is exactly why the warning is here rather than
+ * in a doc nobody reads at the call site.
+ *
+ * ## Not the same signature as `signTransformUrl`
+ *
+ * `signTransformUrl` vouches for a WIDTH; this vouches for a VIEWER, until
+ * `exp`. They come from the same `signing_key` but not the same key material:
+ * the access key is derived (`HMAC(signing_key, "nitida/access/v1")`) so that
+ * no crafted transform path can be replayed as an access signature. The full
+ * argument lives beside the server implementation in `access-signing.ts`; the
+ * short version is that a shared payload with a prefix separator IS
+ * collidable, because both fields of the transform message are
+ * attacker-influenced path segments.
+ *
+ * ## `exp` is mandatory
+ *
+ * A signed URL that never expires is a public URL as soon as someone forwards
+ * it. There is no "no expiry" option here, and there will not be one.
+ */
+
+const ACCESS_KEY_INFO = "nitida/access/v1";
+
+async function hmac(
+  key: ArrayBuffer | Uint8Array,
+  message: string,
+): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key as unknown as ArrayBuffer,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  return new Uint8Array(
+    await crypto.subtle.sign(
+      "HMAC",
+      cryptoKey,
+      new TextEncoder().encode(message),
+    ),
+  );
+}
+
+const toHex = (b: Uint8Array) =>
+  [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+
+/**
+ * The per-tenant access key, derived from `signing_key`. Same value the origin
+ * computes and hands the edge — nothing needs to be stored or synchronised.
+ */
+export async function deriveAccessKey(signingKey: string): Promise<Uint8Array> {
+  return hmac(new TextEncoder().encode(signingKey), ACCESS_KEY_INFO);
+}
+
+/**
+ * The signed message. Byte-identical to the server's `accessMessage` and the
+ * worker's — three implementations of one string, which is why all three pin
+ * the exact bytes in a test.
+ *
+ * `tenantPrefix` is the base36 segment as it appears in the URL, not the
+ * decimal id: tenant 10 lives at `/a/a/`, and the thing being vouched for is a
+ * path.
+ */
+export function accessMessage(
+  tenantPrefix: string,
+  exp: number,
+  resourcePath: string,
+): string {
+  return `${tenantPrefix}\n${exp}\n${resourcePath.replace(/^\/+/, "")}`;
+}
+
+export type SignAccessOptions = {
+  /** Lifetime in seconds. Required — see the header. */
+  expiresInSeconds: number;
+  /** Injectable clock, for tests that need a URL already dead on arrival. */
+  nowSeconds?: number;
+};
+
+/**
+ * Turn a PUBLIC-tree URL into a signed PRIVATE-tree URL.
+ *
+ *   https://8ok.uk/5/v/<sha16>-lg.webp
+ *     → https://8ok.uk/a/5/v/<sha16>-lg.webp?exp=…&sig=…
+ *
+ * Accepts a URL that is already under `/a/` and re-signs it, so calling twice
+ * is not an error and does not produce `/a/a/`.
+ */
+export async function signAccessUrl(
+  publicUrl: string,
+  signingKey: string,
+  opts: SignAccessOptions,
+): Promise<string> {
+  if (!Number.isFinite(opts.expiresInSeconds) || opts.expiresInSeconds <= 0) {
+    throw new Error(
+      "signAccessUrl: `expiresInSeconds` must be a positive number — 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);
+  // ⚠️ `a` is BOTH the private tree's prefix and tenant 10 in base36, so
+  // "starts with /a/ ⇒ already signed" would eat tenant 10's own segment and
+  // sign `/a/v/…` as if `v` were the tenant. What tells them apart is the
+  // resource kind, always `v` or `r` directly after the tenant: the private
+  // tree is `/a/<tenant>/<v|r>/…`, and tenant 10's public `/a/v/<sha>-lg.webp`
+  // is not. Same base36 trap that makes `/10/` the platform's favourite 404.
+  // `[vrt]`, not `[vr]`: `t` joined the private tree when transforms did, and
+  // this line was left behind — so re-signing `/a/5/t/<dsl>/<sha>.webp` read
+  // `a` as the tenant and `5` as the resource kind, and threw. The check two
+  // dozen lines below already said `[vrt]`; a regex that disagrees with its own
+  // file is the shape this bug always takes.
+  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}`,
+    );
+  }
+  // ⭐ The segment after the tenant is ALWAYS the resource kind. Checking it is
+  // not pedantry — it catches the one mistake this signature shape invites.
+  //
+  // `/t/<dsl>/<sha>.webp` is a real, valid public transform URL, and it is the
+  // obvious thing to hand this function. Without this check `t` is read as the
+  // TENANT (29 in base36) and the result is `/a/t/<dsl>/…`: a URL that is
+  // perfectly signed, structurally plausible, and 404s for a reason nobody can
+  // see. Found by using it, 2026-08-22, on the very first private transform.
+  //
+  // A transform needs its tenant prepended first — which is exactly what
+  // `getPrivateTransformUrl` does, so the fix is almost always to call that.
+  if (!/^[vrt]$/.test(segments[0]!)) {
+    throw new Error(
+      `signAccessUrl: expected /<tenant>/<v|r|t>/… 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> — 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() / 1000);
+  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();
+}
+
+/** What every URL builder accepts so it can refuse a doomed URL. */
+export type VisibilityHint = { visibility?: "public" | "private" };
+
+/**
+ * Refuse to build a public URL for a private asset.
+ *
+ * Doctrine of the house: **a silence reads as "you can't"**. Returning
+ * `https://8ok.uk/5/v/<sha>-lg.webp` for a private asset is not a smaller
+ * failure than throwing — it is a URL that answers 404, in a platform where a
+ * 404 has always meant "that file does not exist". The caller then debugs the
+ * wrong thing.
+ *
+ * Only refuses when it was actually TOLD. A caller passing `{ sha }` carries no
+ * visibility, and guessing would break every existing call site to protect
+ * assets that are not there.
+ */
+export function assertPublic(
+  asset: VisibilityHint,
+  fn: string,
+  /**
+   * The call to make instead — declared per call site, not guessed.
+   *
+   * It matters which one: `getPrivateAssetUrl` signs a STORED preset, and
+   * pointing a transform caller at it sends them to a function that cannot do
+   * what they asked for. The first version of this message named
+   * `getPrivateAssetUrl` for all seven builders; a test caught it.
+   */
+  escape: string,
+): void {
+  if (asset.visibility !== "private") return;
+  throw new Error(
+    `${fn}: this asset is private, so a public CDN URL for it will answer 404 — 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.",
+  );
+}
+
+/**
+ * Refuse a value whose `sha` is missing or malformed, instead of interpolating
+ * it into a URL.
+ *
+ * ## Found by a Haiku agent, 2026-08-23
+ *
+ * It did the most natural thing there is — passed the result of `upload()`
+ * straight to `transform()` — and got:
+ *
+ *     https://8ok.uk/t/width=1280/undefined.webp
+ *
+ * `UploadResult` carries `sha256`; every URL builder wants `sha`. TypeScript
+ * catches the mismatch, but an agent running through `bun` (or anyone in plain
+ * JS) sees no error at all: just a 200-shaped URL with the word `undefined` in
+ * it, which 404s later and somewhere else.
+ *
+ * The house rule applies exactly as it does to private assets: **a silence
+ * reads as "you can't"**. A builder that cannot name the asset must say so at
+ * the call site, not hand back a string that will fail far from here.
+ */
+export function assertSha(asset: { sha?: unknown }, fn: string): void {
+  const sha = asset?.sha;
+  if (typeof sha === "string" && /^[0-9a-f]{16,64}$/i.test(sha)) return;
+  const hint =
+    asset && typeof asset === "object" && "sha256" in asset
+      ? " The value you passed has `sha256` but not `sha` — that is the shape `upload()` returns. Use `{ sha: result.sha256.slice(0, 16) }`, or fetch the DTO with `assets.get(id)`."
+      : ` Got ${JSON.stringify(sha)}.`;
+  throw new Error(
+    `${fn}: no usable \`sha\` on the value you passed, so the URL would contain "undefined" and 404 somewhere else.${hint}`,
+  );
+}

package/src/index.ts

@@ -337,6 +337,23 @@ export type AssetDTO = {
    */
   presets: string;
   status: "processing" | "ready" | "failed";
+  /**
+   * Who may fetch the bytes.
+   *
+   *   - `"public"` — the CDN serves it to anyone with the URL. The default,
+   *     and what all 27 484 assets were until this field existed.
+   *   - `"private"` — every public door answers **404**: the stored variants,
+   *     the raw original, the HLS ladder and `/t/`. The bytes are reachable
+   *     only through a signed URL under `/a/{tenant}/…?exp&sig`, which your
+   *     BACKEND mints with {@link getPrivateAssetUrl}.
+   *
+   * Optional so an older server that does not send it is read as `"public"` —
+   * which is what such a server means.
+   *
+   * ⚠️ A 404 on a private asset is not a missing file. It is the feature
+   * working. See {@link getPrivateAssetUrl}.
+   */
+  visibility?: "public" | "private";
   /** Soft-delete timestamp (ISO). Hidden from catalog when set. */
   deletedAt?: string | null;
   /**
@@ -354,6 +371,15 @@ export type AssetDTO = {
   oext?: string | null;
 };
 
+export {
+  accessMessage,
+  assertPublic,
+  assertSha,
+  deriveAccessKey,
+  type SignAccessOptions,
+  signAccessUrl,
+  type VisibilityHint,
+} from "./access";
 export type {
   AssetPalette,
   PaletteSwatch,
@@ -371,7 +397,18 @@ export {
   relativeLuminance,
 } from "./palette";
 
+import {
+  assertPublic,
+  assertSha,
+  type SignAccessOptions,
+  signAccessUrl,
+  type VisibilityHint,
+} from "./access";
 import type { AssetPalette } from "./palette";
+import {
+  getTransformUrlUnchecked,
+  type SignedTransformOptions,
+} from "./transform";
 
 // ---------------------------------------------------------------------------
 // CDN base
@@ -517,9 +554,88 @@ type OriginalHints = {
  * ```
  */
 export function getAssetUrl(
+  asset: Pick<AssetDTO, "sha"> & OriginalHints & VisibilityHint,
+  preset: VariantPreset,
+): string {
+  // Refuses rather than returning a URL that 404s. See `assertPublic`.
+  assertSha(asset, "getAssetUrl");
+  assertPublic(
+    asset,
+    "getAssetUrl",
+    `getPrivateAssetUrl(asset, "${preset}", signingKey, { expiresInSeconds: 300 })`,
+  );
+  // ⭐ THE TWO DEFAULTS DID NOT COMPOSE, AND THIS IS THE SEAM
+  //
+  // `upload()` defaults to `presets: ["original"]` — deliberately, so a bare
+  // upload never silently spends the storage budget. `urlFor()` defaults to
+  // `lg`. Put together, the obvious two-line program a programmatic caller
+  // writes —upload, then ask for a URL— produced a **404**, because `lg` was
+  // never generated. Measured 2026-08-22: 1 290 assets are in exactly that
+  // state, 228 of them in a production tenant.
+  //
+  // So when the DTO TELLS us the preset was never materialised, fall back to
+  // the transform route, which generates it on demand and caches it. The
+  // caller gets optimised bytes instead of a dead link, the raw stays
+  // untouched, and no storage is spent on sizes nobody asked for — measured on
+  // the same tenant, the stored ladder is 79% of raw, so pre-materialising
+  // everything would be ~9 GB for sizes that may never be requested.
+  //
+  // Same discipline as `assertPublic`: this only fires when we were TOLD.
+  // `Pick<AssetDTO,"sha">` carries no `presets`, so the common call is
+  // untouched and no existing behaviour changes.
+  const fallback = transformFallbackFor(asset, preset);
+  if (fallback) return fallback;
+  return buildPublicAssetUrl(asset, preset);
+}
+
+/**
+ * The `/t/` URL that stands in for a preset the asset does not have, or `null`
+ * when there is nothing to stand in for.
+ *
+ * ⚠️ It can be over-eager, and that is the honest trade. Measured 2026-08-22:
+ * an asset whose row lists only `original` served `-l.webp` with a 200 — the
+ * `variants` column under-reports (the contamination behind doc 240 §4.3b), so
+ * the fallback sometimes pays for a transform of a rendition that already
+ * exists. Both answers are correct bytes; one costs an encode. That is a much
+ * smaller wrong than the 404 it replaces, and it heals itself as rows are
+ * reconciled — but it is a reason to fix the rows, not to trust them more.
+ *
+ * Returns null — i.e. keeps the old behaviour — when the DTO does not say what
+ * it has, when the preset IS present, or when the preset has no pixel ceiling
+ * to translate into a width (`original`, `poster`, `video`, `hls`, `mp3`);
+ * those are stored objects, not renditions, and inventing a transform for them
+ * would trade a 404 for a wrong answer.
+ */
+function transformFallbackFor(
+  asset: Pick<AssetDTO, "sha"> & Partial<Pick<AssetDTO, "presets">>,
+  preset: VariantPreset,
+): string | null {
+  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`;
+}
+
+/**
+ * The public-tree URL, with no visibility check.
+ *
+ * Split out because `getPrivateAssetUrl` needs exactly this and must NOT be
+ * refused by the guard: the private tree is the same path with `/a/` in front
+ * and a signature behind, so the builder that mints a legitimate private URL
+ * would otherwise be blocked by the check that exists to send callers to it.
+ */
+function buildPublicAssetUrl(
   asset: Pick<AssetDTO, "sha"> & OriginalHints,
   preset: VariantPreset,
 ): string {
+  // The guard lives HERE and not only in `getAssetUrl`, because
+  // `getPrivateAssetUrl` reaches this function directly. Without it, passing an
+  // upload result produced `/a/5/v/undefined-l.webp?exp=…&sig=…` — a URL with a
+  // **cryptographically valid signature over a path containing `undefined`**.
+  // That is strictly worse than the public case: the signature makes it look
+  // authoritative, and it passes shape checks at the edge before 404ing.
+  assertSha(asset, "getPrivateAssetUrl");
   if (preset === "original") {
     // The stored URL beats every derivation, because it IS the key. Only fall
     // through to a guess when the caller gave us the sha and nothing else.
@@ -544,6 +660,89 @@ export function getAssetUrl(
   return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
 
+/**
+ * The signed URL for one preset of a PRIVATE asset — what every refusal above
+ * points at.
+ *
+ * ```ts
+ * // On your BACKEND, once you have decided this viewer may see it:
+ * const url = await getPrivateAssetUrl(asset, "lg", tenantSigningKey, {
+ *   expiresInSeconds: 300,
+ * });
+ * ```
+ *
+ * It works on a public asset too — `/a/` is a different door onto the same
+ * object — but there is no reason to pay for it: a public URL is cacheable at
+ * the edge and costs nothing, a signed one is neither.
+ *
+ * ⚠️ **Backend only.** Handing the signing key to a browser lets any visitor
+ * mint URLs for every private asset the tenant owns, which is the whole
+ * property the private tree exists to provide.
+ *
+ * ⚠️ Needs {@link setTenantId} (or a `NitidaClient` with `tenantId`), like
+ * every variant URL builder: the tenant segment is base36 and part of what the
+ * signature covers, so a missing tenant does not produce a wrong URL — it
+ * produces an unsignable one.
+ */
+export async function getPrivateAssetUrl(
+  asset: Pick<AssetDTO, "sha"> & OriginalHints,
+  preset: VariantPreset,
+  signingKey: string,
+  opts: SignAccessOptions,
+): Promise<string> {
+  return signAccessUrl(buildPublicAssetUrl(asset, preset), signingKey, opts);
+}
+
+/**
+ * The signed URL for a TRANSFORM of a private asset — an arbitrary width, crop
+ * or format, not just the sizes that happen to be materialised.
+ *
+ * ```ts
+ * const url = await getPrivateTransformUrl(
+ *   asset,
+ *   { width: 1280, format: "webp" },
+ *   tenantSigningKey,
+ *   { expiresInSeconds: 300 },
+ * );
+ * // → https://8ok.uk/a/5/t/format=webp,width=1280/<sha>.webp?exp=…&sig=…
+ * ```
+ *
+ * Why this exists at all: a private asset that can only be served at the sizes
+ * someone already generated is barely a product. The signed tree mirrors the
+ * public one, transforms included.
+ *
+ * Returns `null` when `opts` serialize to an empty DSL — same contract as
+ * {@link getTransformUrl}, because "no transform requested" is not an error,
+ * it just means you wanted {@link getPrivateAssetUrl}.
+ *
+ * ⚠️ **Backend only**, like every signer here. And note the width is a plain
+ * `number`: a signed URL is a trusted caller, so the edge ladder does not
+ * apply — the same rule `getSignedTransformUrl` already follows.
+ */
+export async function getPrivateTransformUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: SignedTransformOptions,
+  signingKey: string,
+  signOpts: SignAccessOptions,
+): Promise<string | null> {
+  const url = getTransformUrlUnchecked(asset, opts);
+  if (!url) return null;
+  // `/t/<dsl>/<file>` has no tenant in it — the private tree needs one, and it
+  // is the same process-global the variant builders use.
+  const tid = getTenantId();
+  if (tid == null) {
+    throw new Error(
+      "getPrivateTransformUrl: no tenant is configured. Call setTenantId(id) (or construct a NitidaClient with `tenantId`) — 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,
+  );
+}
+
 /**
  * Did the processor actually generate this preset?
  *
@@ -614,8 +813,27 @@ function stripMultiCharTokens(presets: string): string {
  */
 const IMAGE_PRESETS: VariantPreset[] = ["thumb", "sm", "md", "lg", "xl"];
 export function getAssetSrcSet(
-  asset: Pick<AssetDTO, "sha" | "presets">,
+  asset: Pick<AssetDTO, "sha" | "presets"> & VisibilityHint,
 ): string {
+  // ⚠️ NOT given the transform fallback that `getAssetUrl` has, on purpose.
+  //
+  // A srcSet is a set of PROMISES about pixel width, and the fallback cannot
+  // keep them. `/t/width=3840/` on a 900 px source returns 900 px — sharp runs
+  // `withoutEnlargement: true` — so the candidate would advertise 3840w and
+  // deliver 900, and the browser would pick it for a large viewport and get
+  // the small image. That is worse than the empty srcSet it replaces: an empty
+  // srcSet degrades to `src`, which now resolves through the fallback and
+  // works. A lying srcSet degrades to a wrong choice, silently.
+  //
+  // Doing this properly means capping the rungs by the asset's real width, and
+  // this signature does not carry it (`Pick<AssetDTO,"sha"|"presets">`). Worth
+  // doing; not worth guessing.
+  assertSha(asset, "getAssetSrcSet");
+  assertPublic(
+    asset,
+    "getAssetSrcSet",
+    "getPrivateAssetUrl(asset, preset, signingKey, { expiresInSeconds: 300 }) per preset",
+  );
   return IMAGE_PRESETS.filter(
     (p) => hasPreset(asset, p) && PRESET_MAX_DIM[p] != null,
   )

package/src/transform.ts

@@ -18,6 +18,7 @@
  * request's Accept header.
  */
 
+import { assertPublic, assertSha, type VisibilityHint } from "./access";
 import type { AssetDTO } from "./index";
 import { getCdnBase } from "./index";
 
@@ -227,9 +228,15 @@ function extForOptions(opts: SignedTransformOptions): string {
  *          autoPlay muted loop playsInline />
  */
 export function getVideoTransformUrl(
-  asset: Pick<AssetDTO, "sha">,
+  asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: TransformOptions,
 ): string | null {
+  assertSha(asset, "getVideoTransformUrl");
+  assertPublic(
+    asset,
+    "getVideoTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })",
+  );
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
   const ext = opts.format === "webm" ? "webm" : "mp4";
@@ -295,9 +302,15 @@ export function getVideoTransformUrl(
  * capped at 1920 wide. `getAssetUrl(sha, "video")` is always <= 1080p.
  */
 export function getHlsStreamingUrl(
-  asset: Pick<AssetDTO, "sha">,
+  asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: Omit<TransformOptions, "format"> = {},
 ): string {
+  assertSha(asset, "getHlsStreamingUrl");
+  assertPublic(
+    asset,
+    "getHlsStreamingUrl",
+    'getPrivateAssetUrl(asset, "hls", signingKey, { expiresInSeconds: 300 }) — the worker re-signs the playlist children',
+  );
   // Always serialize with format=hls so the server routes correctly.
   const merged: TransformOptions = { ...opts, format: "hls" };
   const dsl = serializeTransform(merged);
@@ -309,6 +322,8 @@ export function getHlsStreamingUrl(
  * callers should prefer the existing variant URL builder in that case so
  * the request hits a pre-generated variant instead of an on-the-fly encode.
  */
+export { buildTransformUrl as getTransformUrlUnchecked };
+
 function buildTransformUrl(
   asset: Pick<AssetDTO, "sha">,
   opts: SignedTransformOptions,
@@ -320,9 +335,15 @@ function buildTransformUrl(
 }
 
 export function getTransformUrl(
-  asset: Pick<AssetDTO, "sha">,
+  asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: TransformOptions,
 ): string | null {
+  assertSha(asset, "getTransformUrl");
+  assertPublic(
+    asset,
+    "getTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })",
+  );
   return buildTransformUrl(asset, opts);
 }
 
@@ -338,10 +359,22 @@ export function getTransformUrl(
  * requested) — same contract as {@link getTransformUrl}.
  */
 export function getSignedTransformUrl(
-  asset: Pick<AssetDTO, "sha">,
+  asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: SignedTransformOptions,
   signingKey: string,
 ): Promise<string> | null {
+  // ⭐ The guard belongs here MOST of all, and it was the one place it was
+  // missing. A `?sig=` on `/t/` is a WIDTH permit, not access: on a private
+  // asset the URL it produces is a perfectly signed 404. And this is exactly
+  // where a backend developer holding a signing key and a private asset ends
+  // up — so without this, the same call site throws when unsigned and returns
+  // a doomed URL when signed, which is the worst of both.
+  assertSha(asset, "getSignedTransformUrl");
+  assertPublic(
+    asset,
+    "getSignedTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })",
+  );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
   return signTransformUrl(url, signingKey);
@@ -405,10 +438,16 @@ async function hmacSha256Hex(key: string, message: string): Promise<string> {
  *   />
  */
 export function getTransformSrcSet(
-  asset: Pick<AssetDTO, "sha">,
+  asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   widths: number[],
   extraOpts: Omit<TransformOptions, "width"> = {},
 ): string {
+  assertSha(asset, "getTransformSrcSet");
+  assertPublic(
+    asset,
+    "getTransformSrcSet",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 }) per width",
+  );
   return widths
     .map((w) => {
       // Build via the internal (number-width) builder: `widths` is an explicit