@nitida/asset-client 0.21.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/asset-client",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "description": "nitida URL builders — construct image, video and HLS URLs for the nitida CDN. No network, no key, no config beyond a tenant id.",
   "private": false,
   "publishConfig": {

package/src/access.ts

@@ -92,8 +92,23 @@ export function accessMessage(
   return `${tenantPrefix}\n${exp}\n${resourcePath.replace(/^\/+/, "")}`;
 }
 
+/**
+ * The longest life a signed URL may claim: **7 days**.
+ *
+ * ⚠️ Must equal `MAX_SIGNED_TRANSFORM_TTL_SECONDS` on the origin and
+ * `MAX_SIGNED_URL_TTL_SECONDS` in the CDN worker — one policy, three runtimes,
+ * pinned in all three suites. Both verifiers refuse anything longer, so a
+ * bigger number here would only mint a URL that 401s.
+ *
+ * Why there is a ceiling at all: `expiresInSeconds` was validated as
+ * "> 0" and nothing else, so `{ expiresInSeconds: 315_360_000 }` produced a
+ * ten-year link that every check called valid. "Has an expiry" and "expires"
+ * are different properties, and only the second makes a leaked link die.
+ */
+export const MAX_SIGNED_URL_TTL_SECONDS = 7 * 24 * 60 * 60; // 604 800
+
 export type SignAccessOptions = {
-  /** Lifetime in seconds. Required — see the header. */
+  /** Lifetime in seconds, 1 .. 604 800. Required — see the header. */
   expiresInSeconds: number;
   /** Injectable clock, for tests that need a URL already dead on arrival. */
   nowSeconds?: number;
@@ -118,6 +133,11 @@ export async function signAccessUrl(
       "signAccessUrl: `expiresInSeconds` must be a positive number — 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);
   // ⚠️ `a` is BOTH the private tree's prefix and tenant 10 in base36, so

package/src/index.ts

@@ -68,25 +68,37 @@ export type VariantPreset =
  * **`probe` is requestable and was not on `VariantPreset` at all**, so the type
  * forbade a request the server has always accepted.
  *
- * Verified 2026-08-21 against the Elysia schemas of all four write routes —
- * `/assets/process`, the presign route, `/assets/:id/regenerate` and both
- * multipart routes. All four accept exactly this list and nothing else, with
- * no drift between them.
+ * Generated from the Elysia schemas of all four write routes — `/assets/process`,
+ * the presign route, `/assets/:id/regenerate` and both multipart routes —
+ * by `scripts/gen-docs.ts` (doc derivar WS-4). `bun run gen:docs` rewrites it;
+ * `--check` fails the build if a route's schema drifts and nobody reran it.
+ * `probe` is still frames at evenly spaced offsets, stored under indexed keys
+ * (`-pr0.jpg`, `-pr1.jpg`, …) — requestable, and deliberately absent from the
+ * compact `presets` wire string, so it is here and not on `VariantPreset`.
  */
-export type RequestablePreset =
-  | Exclude<VariantPreset, "hls" | "mp3">
-  // Still frames at evenly spaced offsets, stored under indexed keys
-  // (`-pr0.jpg`, `-pr1.jpg`, …). Requestable, and deliberately absent from the
-  // compact `presets` wire string — so it is here and not on VariantPreset.
-  | "probe";
+// BEGIN GENERATED: requestable-preset · bun run gen:docs
+export const REQUESTABLE_PRESETS = [
+  "aiproxy",
+  "lg",
+  "md",
+  "original",
+  "poster",
+  "probe",
+  "sm",
+  "thumb",
+  "video",
+  "xl",
+] as const;
+export type RequestablePreset = (typeof REQUESTABLE_PRESETS)[number];
+// END GENERATED: requestable-preset
 
 /**
- * The same set as {@link RequestablePreset}, at RUNTIME.
- *
- * The type stops the mistake in TypeScript. It cannot stop it anywhere else,
- * and "anywhere else" is where it keeps happening: a preset list assembled
- * from config, from a route body, from JSON, or from a script's argv arrives
- * as `string[]`, and the only way past the type was a cast.
+ * `REQUESTABLE_PRESETS` (above) is the same set as `RequestablePreset`, at
+ * RUNTIME. The type stops the mistake in TypeScript. It cannot stop it
+ * anywhere else, and "anywhere else" is where it keeps happening: a preset
+ * list assembled from config, from a route body, from JSON, or from a
+ * script's argv arrives as `string[]`, and the only way past the type was a
+ * cast.
  *
  * Measured in neo-real-estate on 2026-08-23, in THREE independent files:
  *
@@ -98,18 +110,6 @@ export type RequestablePreset =
  *
  * So the narrowing lives here, once, instead of being re-invented per repo.
  */
-export const REQUESTABLE_PRESETS: readonly RequestablePreset[] = [
-  "thumb",
-  "sm",
-  "md",
-  "lg",
-  "xl",
-  "original",
-  "poster",
-  "video",
-  "aiproxy",
-  "probe",
-] as const;
 
 /** Type guard for a single value. */
 export const isRequestablePreset = (v: string): v is RequestablePreset =>
@@ -446,6 +446,7 @@ export {
   assertPublic,
   assertSha,
   deriveAccessKey,
+  MAX_SIGNED_URL_TTL_SECONDS,
   type SignAccessOptions,
   signAccessUrl,
   type VisibilityHint,
@@ -477,7 +478,7 @@ import {
 import type { AssetPalette } from "./palette";
 import {
   getTransformUrlUnchecked,
-  type SignedTransformOptions,
+  type PrivateTransformOptions,
 } from "./transform";
 
 // ---------------------------------------------------------------------------
@@ -881,7 +882,7 @@ export async function getPrivateAssetUrl(
  */
 export async function getPrivateTransformUrl(
   asset: Pick<AssetDTO, "sha">,
-  opts: SignedTransformOptions,
+  opts: PrivateTransformOptions,
   signingKey: string,
   signOpts: SignAccessOptions,
 ): Promise<string | null> {
@@ -1069,13 +1070,20 @@ export {
 // ---------------------------------------------------------------------------
 
 export {
+  deriveTransformKid,
   extractAssetSha,
   getHlsStreamingUrl,
   getSignedTransformUrl,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
+  type PrivateTransformOptions,
   type SignedTransformOptions,
+  type SignTransformOptions,
+  getByteBudgetTransformUrl,
+  hasSizeLadder,
   serializeTransform,
   signTransformUrl,
   TRANSFORM_WIDTHS,
@@ -1085,4 +1093,5 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  transformMessage,
 } from "./transform";

package/src/transform.ts

@@ -20,23 +20,34 @@
 
 import { assertPublic, assertSha, type VisibilityHint } from "./access";
 import type { AssetDTO } from "./index";
-import { getCdnBase } from "./index";
+import { getCdnBase, getTenantId, hasPreset } from "./index";
 
 /**
  * Widths the CDN edge whitelists (DoS guard).
  * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
  * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
  * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
+ *
+ * ⭐ **180 es el `apple-touch-icon`, y está acá por eso.** Apple pide 180×180 para
+ * el icono de pantalla de inicio en un iPhone 3×, y el monorepo de neo ya lo
+ * estandarizó: `webapp-storefront` commitea un `apple-icon.png` de 180×180 por
+ * tenant. Sin este escalón, una app que sirve el icono desde el CDN tiene que
+ * elegir entre 160 (iOS lo agranda, sale borroso) y 240 (lo achica, sale bien
+ * pero pesa de más). Medido 2026-08-29 sobre la foto de un agente: 240² en PNG
+ * son 57,5 KB contra 6,5 KB del WebP a 400², así que el tamaño de más no es
+ * gratis. El caso real: `apps/bio-web/src/lib/seo/favicon.ts`, que sirve **la
+ * foto del propio negocio** como icono de su página.
  */
 export const TRANSFORM_WIDTHS = [
-  96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280,
-  1440, 1600, 1920, 2560, 3840,
+  96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200,
+  1280, 1440, 1600, 1920, 2560, 3840,
 ] as const;
 /**
  * A CDN-whitelisted transform width — the only widths `TransformOptions.width`
  * accepts. Off-ladder widths are a compile error; for signed URLs that need a
- * custom width, use {@link SignedTransformOptions} (number) via
- * {@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`.
+ * signature, use {@link getSignedTransformUrl} /
+ * `aq.transform(asset, opts, { sign: true, expiresInSeconds })` — which names
+ * the caller but does NOT widen the ladder.
  */
 export type TransformWidth = (typeof TRANSFORM_WIDTHS)[number];
 
@@ -68,9 +79,9 @@ export type TransformOptions = {
   /**
    * Target max-side width in CSS pixels (multiplied by `dpr` server-side).
    * MUST be a {@link TRANSFORM_WIDTHS} value — off-ladder widths are rejected
-   * (HTTP 400) by the edge whitelist for unsigned URLs, so the type forbids
-   * them at compile time. For SIGNED URLs with a custom width, use
-   * {@link SignedTransformOptions} (which widens this to `number`).
+   * (HTTP 400) by the edge whitelist, so the type forbids them at compile
+   * time. Signing does NOT lift this: since doc blindaje WS-6 the edge
+   * validates signed and unsigned requests identically.
    */
   width?: TransformWidth;
   /** Target max-side height. Multiplied by `dpr` server-side. */
@@ -81,8 +92,37 @@ export type TransformOptions = {
   gravity?: TransformGravity;
   /** Output format. `auto` → the platform's policy decides. */
   format?: TransformFormat;
-  /** Output quality. `auto` → format-specific default. */
-  quality?: "auto" | number;
+  /**
+   * ⛔ **`quality` no existe en este tipo, y eso es deliberado.**
+   *
+   * No es un dial del encoder: elige QUÉ BYTES decodifica el servidor. Con un
+   * número, `/t/` salta a la variante almacenada más chica que cubra el pedido
+   * — que ya pasó por una compresión — y la salida es una segunda generación.
+   * Sobre un asset CON escalera eso es pérdida pura (medido: +2…+8 % de peso y
+   * −0,50…−0,85 dB). Y `"auto"` era un no-op: byte a byte idéntico a omitir la
+   * clave, mismo sha256.
+   *
+   * El único uso legítimo —un presupuesto de bytes medido, sobre un asset SIN
+   * escalera— tiene su propia puerta, que no se puede llamar a ciegas:
+   * {@link getByteBudgetTransformUrl}.
+   *
+   * ## Por qué no alcanzaba con documentarlo
+   *
+   * Estuvo `@deprecated` con la medición al lado durante exactamente una
+   * versión, y eso ya era mejor que nada. Pero un aviso **avisa**; no impide.
+   * `getTransformUrl` recibe un `Pick<AssetDTO, "sha">` —un sha y nada más—,
+   * así que un `quality: 75` en el call site era **ciego**: nadie ahí, humano o
+   * modelo, podía saber si ese asset tenía escalera. La misma línea era
+   * correcta o dañina según un dato que no estaba en la llamada.
+   *
+   * Y hay un llamador que no lee tildados: **un modelo generando código.**
+   * `quality` es el parámetro que todo el mundo espera encontrar en una API de
+   * imágenes, así que se escribe solo. Next.js llegó a la misma conclusión por
+   * el mismo camino y dejó de recomendar `quality` por imagen: la configuración
+   * ya decide, y un valor por llamada sólo agrega formas de equivocarse.
+   *
+   * ⇒ El parámetro no se documenta como peligroso. **No se puede escribir.**
+   */
   /** Device pixel ratio. Width/height are multiplied by this before resize. */
   dpr?: 1 | 2 | 3;
   /**
@@ -116,21 +156,49 @@ export type TransformOptions = {
 };
 
 /**
- * Like {@link TransformOptions} but with `width` widened to any `number` —
- * the escape hatch for SIGNED URLs that need an off-ladder custom width.
- *
- * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
- * `?sig=` earns the whitelist bypass at the edge (the server still
- * does the real HMAC check). So a custom width is ONLY safe when the URL is
- * signed — hence this type is accepted exclusively by the signing helpers
- * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
- * never by the plain unsigned {@link getTransformUrl}.
+ * Options for a SIGNED transform URL.
+ *
+ * ⚠️ **`width` is the same ladder as unsigned**, since `@nitida/asset-client`
+ * 0.22.0. This type used to widen it to any `number`, because a valid `?sig=`
+ * made the CDN edge skip its whitelist entirely — so a signature bought an
+ * off-ladder size. It does not any more: the edge validates every `/t/`
+ * request identically and answers 400 for an off-ladder width whether or not
+ * it is signed (doc blindaje WS-6). Keeping the wide type would only let
+ * TypeScript bless a URL that 400s.
+ *
+ * A signature now buys IDENTITY: which tenant asked, proven with its key, until
+ * `exp`. That is what a strict tenant and the paid-effect cost guard require.
+ */
+export type SignedTransformOptions = TransformOptions;
+
+/**
+ * `width` widened to any `number` — the PRIVATE tree's option type.
+ *
+ * ⚠️ Not an escape hatch for the public tree: `/t/` answers 400 for an
+ * off-ladder width, signed or not (doc blindaje WS-6). What this is for is the
+ * `/a/<tenant>/t/…` tree, where the ladder deliberately does NOT apply — the
+ * request arrives HMAC-verified against the tenant's key, so only a key-holder
+ * can ask, and "any width/crop/format, not just the materialised ones" is the
+ * written promise of `getPrivateTransformUrl`.
+ *
+ * Also used by the two builders that take an explicit ladder the caller chose
+ * (`getTransformSrcSet`) or that are documented as unchecked
+ * (`getTransformUrlUnchecked`).
  */
-export type SignedTransformOptions = Omit<TransformOptions, "width"> & {
-  /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+export type PrivateTransformOptions = Omit<TransformOptions, "width"> & {
   width?: number;
 };
 
+/**
+ * `TransformOptions` + el `quality` que el tipo público ya no admite.
+ *
+ * INTERNO. Existe porque el serializador tiene que poder emitir `quality=` para
+ * {@link getByteBudgetTransformUrl}; no porque un llamador deba construirlo.
+ */
+type WithPinnedQuality<T> = T & { quality: number };
+/** @deprecated internal alias kept for the builders below. */
+type AnyWidthTransformOptions = PrivateTransformOptions;
+
 /**
  * Serialize transform options into the canonical DSL path segment.
  * Empty options return an empty string (caller should fall back to a
@@ -165,11 +233,13 @@ export function extractAssetSha(url: string | null | undefined): string | null {
   return m ? m[1]! : null;
 }
 
-export function serializeTransform(opts: SignedTransformOptions): string {
+export function serializeTransform(
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
+): string {
   const entries: Array<[string, string]> = [];
-  const keys = Object.keys(opts).sort() as Array<keyof SignedTransformOptions>;
+  const keys = Object.keys(opts).sort();
   for (const k of keys) {
-    const v = opts[k];
+    const v = (opts as Record<string, unknown>)[k];
     if (v == null) continue;
     const serialized = typeof v === "string" ? v.toLowerCase() : String(v);
     entries.push([k, serialized]);
@@ -177,7 +247,9 @@ export function serializeTransform(opts: SignedTransformOptions): string {
   return entries.map(([k, v]) => `${k}=${v}`).join(",");
 }
 
-function extForOptions(opts: SignedTransformOptions): string {
+function extForOptions(
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
+): string {
   // effect=removebg forces PNG output server-side (needs alpha).
   if (opts.effect === "removebg") return "png";
   // effect=genfill defaults to WebP (12× lighter than the raw generated
@@ -326,7 +398,7 @@ export { buildTransformUrl as getTransformUrlUnchecked };
 
 function buildTransformUrl(
   asset: Pick<AssetDTO, "sha">,
-  opts: SignedTransformOptions,
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
 ): string | null {
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
@@ -348,20 +420,133 @@ export function getTransformUrl(
 }
 
 /**
- * Build AND sign a transform URL, allowing an off-ladder custom `width`.
+ * Build AND sign a transform URL.
  *
- * This is the escape hatch for {@link SignedTransformOptions}: off-ladder
- * widths only pass the edge whitelist when the URL is signed, so building one
- * and signing it must happen together. For on-ladder widths prefer the plain
- * {@link getTransformUrl} (+ {@link signTransformUrl} if you need a signature).
+ * A signature names the caller — it is what a `strict_transforms` tenant
+ * requires and what the paid-effect (`effect=genfill`) cost guard requires. It
+ * does NOT widen the ladder; see {@link SignedTransformOptions}.
  *
  * Returns `null` only when `opts` serialize to an empty DSL (no transform
  * requested) — same contract as {@link getTransformUrl}.
  */
+/**
+ * Los presets de TAMAÑO — los únicos cuya existencia convierte un `quality`
+ * pinneado en una segunda compresión.
+ *
+ * `original`, `poster`, `video`, `aiproxy`, `hls` y `mp3` NO cuentan: `/t/`
+ * nunca los usa como fuente de una imagen redimensionada.
+ */
+const LADDER_PRESETS = ["thumb", "sm", "md", "lg", "xl"] as const;
+
+/**
+ * ¿Este asset tiene variantes de tamaño almacenadas, o sea algo a lo que `/t/`
+ * pueda saltar?
+ *
+ * `null` cuando **no se sabe** — un DTO sin `presets` no dice que no las tenga,
+ * dice que no lo trae. Tres estados, tres respuestas: un booleano acá mentiría
+ * en un tercio de los casos, y mentiría hacia el lado inseguro.
+ *
+ * ⚠️ **Se pregunta con `hasPreset`, JAMÁS con `presets.includes("s")`.** La
+ * cadena lleva tokens de varias letras —`transform-<hex>`, `upscale_…`, `pr`—
+ * que donan `s`, `m`, `l` y `o` de regalo. Ese es el falso positivo que
+ * `test/presets-false-positives.test.ts` existe para cazar.
+ */
+export function hasSizeLadder(asset: {
+  presets?: string | null;
+}): boolean | null {
+  const raw = asset.presets;
+  if (raw == null || raw.trim() === "") return null;
+  return LADDER_PRESETS.some((preset) => hasPreset(asset, preset));
+}
+
+/**
+ * ⭐ **La ÚNICA puerta por la que se puede pinnear un `quality` numérico** —
+ * y está construida para que no se pueda usar mal.
+ *
+ * ## El problema que resuelve
+ *
+ * `getTransformUrl` recibe un `Pick<AssetDTO, "sha">`: **un sha y nada más.**
+ * Con eso, un `quality: 75` en el call site es CIEGO — la misma línea es un
+ * ajuste honesto del encoder sobre un asset sin escalera, y una segunda
+ * compresión silenciosa sobre uno con escalera. Nada en el tipo, en el nombre
+ * ni en el editor distinguía los dos casos. Un aviso avisa; esto impide.
+ *
+ * ## Las dos barreras
+ *
+ * 1. **En COMPILACIÓN**: el parámetro exige `presets: string`. Un
+ *    `{ sha }` pelado —la llamada ciega— ya no compila. Para pasar por acá hay
+ *    que tener el DTO en la mano, y tener el DTO es saber la respuesta.
+ * 2. **En EJECUCIÓN**: si el asset tiene cualquier preset de tamaño, **tira**.
+ *    Si `presets` no vino, **tira** — «no sé» nunca se resuelve como «dale».
+ *
+ * ## Cuándo es legítimo, con el número
+ *
+ * Un presupuesto de bytes que alguien MIDIÓ, sobre un asset subido con
+ * `presets: ["original"]`. Ahí no hay a qué saltar y el pin hace lo que su
+ * nombre dice. Medido 2026-08-31 contra producción, ancho 1 920, las seis
+ * respuestas `x-transform-source: original`:
+ *
+ * | quality | bytes | vs auto | PSNR |
+ * |---|---|---|---|
+ * | 40 | 82 112 | **−33,6 %** | 35,32 dB |
+ * | 60 | 106 892 | −13,5 % | 36,85 dB |
+ * | *(auto)* | 123 614 | — | 37,65 dB |
+ * | 90 | 269 026 | +117,6 % | 41,46 dB |
+ *
+ * Monótona y sin sorpresas: −33,6 % de peso por −2,32 dB. **Eso sí es un
+ * intercambio**, y es la razón por la que el parámetro no se borró del todo.
+ *
+ * @throws si el asset tiene escalera, si no se sabe si la tiene, o si
+ *   `quality` no está en 1..100.
+ */
+export function getByteBudgetTransformUrl(
+  asset: Pick<AssetDTO, "sha"> & { presets: string } & VisibilityHint,
+  opts: WithPinnedQuality<TransformOptions>,
+): string | null {
+  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 — 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 — 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);
+}
+
 export function getSignedTransformUrl(
   asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: SignedTransformOptions,
   signingKey: string,
+  signOpts: SignTransformOptions,
 ): 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
@@ -377,12 +562,73 @@ export function getSignedTransformUrl(
   );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
-  return signTransformUrl(url, signingKey);
+  return signTransformUrl(url, signingKey, signOpts);
+}
+
+/** Domain separator for the v2 transform message. */
+const TRANSFORM_SIG_DOMAIN = "nitida/transform/v2";
+/** Domain separator for `kid` derivation. */
+const KID_INFO = "nitida/kid/v1";
+
+/**
+ * The longest life a signed transform URL may claim: **7 days**.
+ *
+ * ⚠️ Must equal `MAX_SIGNED_TRANSFORM_TTL_SECONDS` on the origin
+ * (`transform.signing.ts`), which enforces it on every verify — asking for
+ * more here would only build a URL the platform answers 401 to, which is why
+ * this throws instead.
+ */
+export const MAX_SIGNED_TRANSFORM_TTL_SECONDS = 7 * 24 * 60 * 60; // 604 800
+
+/**
+ * The shortest, so that the minute-rounding below can never mint a dead URL.
+ * 120 s = two rounding steps of headroom.
+ */
+export const MIN_SIGNED_TRANSFORM_TTL_SECONDS = 120;
+
+export type SignTransformOptions = {
+  /**
+   * Lifetime in seconds, 120 .. 604 800. Required — there is no "forever"
+   * option, for the same reason `signAccessUrl` has none: a signed URL that
+   * never expires is a public URL the moment someone forwards it.
+   */
+  expiresInSeconds: number;
+  /**
+   * The tenant this signature speaks for. Defaults to the process-global
+   * (`setTenantId`, or a `NitidaClient` with `tenantId`) — the tenant is part
+   * of the signed message, so it cannot be guessed from the asset.
+   */
+  tenantId?: number;
+  /** Injectable clock, for tests that need a URL already dead on arrival. */
+  nowSeconds?: number;
+};
+
+/**
+ * The public name of a signing key, derived from the key itself, so a signer
+ * never has to be told a second value. Byte-identical to the origin's
+ * `deriveKid`.
+ */
+export async function deriveTransformKid(signingKey: string): Promise<string> {
+  return (await hmacSha256Hex(signingKey, KID_INFO)).slice(0, 8);
+}
+
+/**
+ * The signed message. Byte-identical to the origin's `transformMessage`.
+ *
+ *     nitida/transform/v2 \n <tenantPrefix> \n <exp> \n <dsl>/<filename>
+ */
+export function transformMessage(args: {
+  tenantPrefix: string;
+  exp: number;
+  canonicalDsl: string;
+  filename: string;
+}): string {
+  return `${TRANSFORM_SIG_DOMAIN}\n${args.tenantPrefix}\n${args.exp}\n${args.canonicalDsl}/${args.filename}`;
 }
 
 /**
  * Sign a transform URL with the tenant's HMAC signing key. Appends
- * `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).
+ * `?kid=<8 hex>&exp=<unix seconds>&sig=<64 hex>`.
  *
  * Must agree byte-for-byte with the server's `verifyTransformSignature`.
  * Uses WebCrypto, so works in browsers, Node ≥ 16, Bun, and Workers.
@@ -390,11 +636,40 @@ export function getSignedTransformUrl(
  * The canonical DSL is the one already produced by `serializeTransform`
  * (sort keys + lowercase strings), so signing a URL built by `getTransformUrl`
  * is automatic — the same canonical form is in the URL path.
+ *
+ * ## ⚠️ `exp` IS ROUNDED DOWN TO THE MINUTE, AND THAT IS LOAD-BEARING
+ *
+ * The edge cache key for `/t/` is the FULL URL. A per-request `exp` would make
+ * every render of the same image a distinct cache entry — turning a path that
+ * reaches the origin roughly never into one that reaches it on every view.
+ * Rounding down to the minute means every renderer signing the same URL in the
+ * same minute produces the same bytes, so the entry is shared. Down, never up,
+ * so the URL never outlives the lifetime the caller asked for.
+ *
+ * A build-time signer that wants ONE stable URL per deploy should pass a fixed
+ * `nowSeconds` (the build timestamp) rather than a longer lifetime.
  */
 export async function signTransformUrl(
   unsignedUrl: string,
   signingKey: string,
+  opts: SignTransformOptions,
 ): Promise<string> {
+  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`) — the tenant is part of what the signature covers, so this cannot be guessed.",
+    );
+  }
   const u = new URL(unsignedUrl);
   // Path shape: /t/<dsl>/<filename>
   const parts = u.pathname.split("/").filter(Boolean);
@@ -406,8 +681,19 @@ export async function signTransformUrl(
   }
   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() / 1000);
+  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();
 }