@nitida/asset-client 0.21.0 → 0.23.0

package/dist/index.d.cts

@@ -56,8 +56,22 @@ declare function deriveAccessKey(signingKey: string): Promise<Uint8Array>;
  * path.
  */
 declare function accessMessage(tenantPrefix: string, exp: number, resourcePath: string): string;
+/**
+ * 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.
+ */
+declare const MAX_SIGNED_URL_TTL_SECONDS: number;
 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;
@@ -248,13 +262,24 @@ declare function getPaletteBlurBackground(palette: AssetPalette | null | undefin
  * 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.
  */
-declare const TRANSFORM_WIDTHS: readonly [96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
+declare const TRANSFORM_WIDTHS: readonly [96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
 /**
  * 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.
  */
 type TransformWidth = (typeof TRANSFORM_WIDTHS)[number];
 type TransformFit = "cover" | "contain" | "fill" | "inside" | "outside";
@@ -265,9 +290,9 @@ 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. */
@@ -278,7 +303,43 @@ 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;
@@ -312,20 +373,39 @@ type TransformOptions = {
     duration?: number;
 };
 /**
- * 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.
  */
-type SignedTransformOptions = Omit<TransformOptions, "width"> & {
-    /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+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`).
+ */
+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.
  * Empty options return an empty string (caller should fall back to a
@@ -352,7 +432,7 @@ type SignedTransformOptions = Omit<TransformOptions, "width"> & {
  * to be an aquienpz asset.
  */
 declare function extractAssetSha(url: string | null | undefined): string | null;
-declare function serializeTransform(opts: SignedTransformOptions): string;
+declare function serializeTransform(opts: AnyWidthTransformOptions): string;
 /**
  * Build a transform URL for a VIDEO asset. Same DSL shape as image
  * transforms; the server branches on the asset's `kind` column. Video
@@ -426,20 +506,66 @@ declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHin
 
 declare function getTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: TransformOptions): string | null;
 /**
- * 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}.
  */
-declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string): Promise<string> | null;
+declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string, signOpts: SignTransformOptions): Promise<string> | null;
+/**
+ * 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.
+ */
+declare const MAX_SIGNED_TRANSFORM_TTL_SECONDS: number;
+/**
+ * The shortest, so that the minute-rounding below can never mint a dead URL.
+ * 120 s = two rounding steps of headroom.
+ */
+declare const MIN_SIGNED_TRANSFORM_TTL_SECONDS = 120;
+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`.
+ */
+declare function deriveTransformKid(signingKey: string): Promise<string>;
+/**
+ * The signed message. Byte-identical to the origin's `transformMessage`.
+ *
+ *     nitida/transform/v2 \n <tenantPrefix> \n <exp> \n <dsl>/<filename>
+ */
+declare function transformMessage(args: {
+    tenantPrefix: string;
+    exp: number;
+    canonicalDsl: string;
+    filename: string;
+}): string;
 /**
  * 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.
@@ -447,8 +573,20 @@ declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & Visibility
  * 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.
  */
-declare function signTransformUrl(unsignedUrl: string, signingKey: string): Promise<string>;
+declare function signTransformUrl(unsignedUrl: string, signingKey: string, opts: SignTransformOptions): Promise<string>;
 /**
  * Build a responsive `srcSet` string by generating one transform URL per
  * width. All other options apply to every URL.
@@ -583,19 +721,23 @@ type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster"
  * **`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`.
  */
-type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
+declare const REQUESTABLE_PRESETS: readonly ["aiproxy", "lg", "md", "original", "poster", "probe", "sm", "thumb", "video", "xl"];
+type RequestablePreset = (typeof REQUESTABLE_PRESETS)[number];
 /**
- * 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:
  *
@@ -607,7 +749,6 @@ type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
  *
  * So the narrowing lives here, once, instead of being re-invented per repo.
  */
-declare const REQUESTABLE_PRESETS: readonly RequestablePreset[];
 /** Type guard for a single value. */
 declare const isRequestablePreset: (v: string) => v is RequestablePreset;
 /**
@@ -957,7 +1098,7 @@ declare function getPrivateAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints
  * `number`: a signed URL is a trusted caller, so the edge ladder does not
  * apply — the same rule `getSignedTransformUrl` already follows.
  */
-declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signingKey: string, signOpts: SignAccessOptions): Promise<string | null>;
+declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: PrivateTransformOptions, signingKey: string, signOpts: SignAccessOptions): Promise<string | null>;
 /**
  * Did the processor actually generate this preset?
  *
@@ -995,4 +1136,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type PrivateTransformOptions, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignTransformOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage };