@nitida/asset-client 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/asset-client",
-  "version": "0.21.0",
+  "version": "0.23.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,18 @@ 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,
   serializeTransform,
   signTransformUrl,
   TRANSFORM_WIDTHS,
@@ -1085,4 +1091,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 } 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,7 +92,43 @@ export type TransformOptions = {
   gravity?: TransformGravity;
   /** Output format. `auto` → the platform's policy decides. */
   format?: TransformFormat;
-  /** Output quality. `auto` → format-specific default. */
+  /**
+   * @deprecated **Do not set this.** Omit the key — that is the correct call for
+   * every surface this platform serves. Kept in the type for one narrow case
+   * (a hard, MEASURED byte budget), and struck through on purpose so reaching
+   * for it is a decision, not an accident.
+   *
+   * There are only two things you can pass, and neither is worth having:
+   *
+   * **`"auto"` is a no-op.** Byte-for-byte identical to omitting the key —
+   * measured 2026-08-31 on a production laddered asset at `width=1920`:
+   * both answered 136 680 B, sha256 `3a9ba57d…`, `x-transform-source:
+   * original`. It buys nothing but the illusion of having chosen.
+   *
+   * **A NUMBER costs you image quality.** It is not an encoder knob — it
+   * selects WHICH BYTES the server decodes. With a number in hand, `/t/`
+   * short-circuits to the smallest STORED variant that covers the request, and
+   * that variant already went through one lossy pass, so the output is a second
+   * generation. `"auto"` is a *string*, fails that `typeof` test, and therefore
+   * keeps the master path. Measured on two corpora:
+   *
+   *   - 5 photographs, `width=800` → 7–9 % smaller **and worse 5 of 5**, down
+   *     to −3.01 dB PSNR (`/guides/transform-benchmark/`).
+   *   - 5056 px architectural renders at 1280 / 1920 / 3840 — the widths that
+   *     MATCH `md`/`lg`/`xl` exactly, so no downscale hides the first pass →
+   *     **+2…+8 % HEAVIER and −0.50…−0.85 dB, 3 of 3**. Not even a byte saving
+   *     to trade for it.
+   *
+   * Raising the number does not undo it: doubly-compressed at 80 is worse than
+   * single-pass at 60, and 31 % heavier.
+   *
+   * If you truly have a byte budget, pin it AND upload that asset with
+   * `presets: ["original"]` — with no ladder there is nothing to short-circuit
+   * to, and the pin becomes an honest encoder setting again.
+   *
+   * The one-line check is on the response: `x-transform-source` names the
+   * variant the edge decoded. `original` = one pass; `md`/`lg`/`xl` = two.
+   */
   quality?: "auto" | number;
   /** Device pixel ratio. Width/height are multiplied by this before resize. */
   dpr?: 1 | 2 | 3;
@@ -116,20 +163,40 @@ 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.
+ * 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.
  *
- * 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}.
+ * 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 = Omit<TransformOptions, "width"> & {
-  /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+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 PrivateTransformOptions = Omit<TransformOptions, "width"> & {
   width?: number;
 };
+/** @deprecated internal alias kept for the builders below. */
+type AnyWidthTransformOptions = PrivateTransformOptions;
 
 /**
  * Serialize transform options into the canonical DSL path segment.
@@ -165,9 +232,11 @@ 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): string {
   const entries: Array<[string, string]> = [];
-  const keys = Object.keys(opts).sort() as Array<keyof SignedTransformOptions>;
+  const keys = Object.keys(opts).sort() as Array<
+    keyof AnyWidthTransformOptions
+  >;
   for (const k of keys) {
     const v = opts[k];
     if (v == null) continue;
@@ -177,7 +246,7 @@ export function serializeTransform(opts: SignedTransformOptions): string {
   return entries.map(([k, v]) => `${k}=${v}`).join(",");
 }
 
-function extForOptions(opts: SignedTransformOptions): string {
+function extForOptions(opts: 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 +395,7 @@ export { buildTransformUrl as getTransformUrlUnchecked };
 
 function buildTransformUrl(
   asset: Pick<AssetDTO, "sha">,
-  opts: SignedTransformOptions,
+  opts: AnyWidthTransformOptions,
 ): string | null {
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
@@ -348,12 +417,11 @@ 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}.
@@ -362,6 +430,7 @@ 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 +446,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 +520,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 +565,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();
 }