@nitida/sdk 0.31.6 → 0.32.0

package/skills/nitida-sdk/SKILL.md

@@ -501,6 +501,31 @@ The progressive MP4 is capped unconditionally at 1920 wide, so `getAssetUrl(sha,
 never exceeds 1080p whatever you uploaded. A rung that weighs *more* than its own source (measured:
 5090 vs 4866 kbps) is the signature of the fallback path, not of a broken ladder.
 
+### 3c. ⭐ Dedup is CROSS-TENANT, and three things follow from it
+
+The sha hashes the **bytes**, so two customers who upload the same logo, stock
+photo or placeholder share a candidate row. A `/t/…` URL names content and
+carries **no tenant segment**. Measured behaviour as of 2026-08-25:
+
+| | |
+|---|---|
+| **signed** `/t/` | the **signature** picks the tenant — it proves possession of one key, which is the identity the URL lacks. (Before this, the lowest tenant id won and a valid signature could answer `invalid_signature`.) |
+| **`strict_transforms`** | fails **closed** across every tenant sharing that sha. If any of them requires signing, the unsigned request is refused. |
+| **`visibility: "private"`** | retracts **your** row only. Another tenant's public copy of the same bytes keeps serving, and `/t/` resolves to it. |
+
+⚠️ **Do not read `private` as "these bytes are unreachable".** It means
+"reachable through me only by signature". Nothing new leaks — those bytes were
+already public via the other tenant — but the promise is narrower than it looks.
+
+⚠️ And the cost of failing closed, stated plainly: a tenant that does **not**
+use `strict_transforms` but shares content with one that does will need signed
+URLs for that sha. Failing open would let a stranger cancel someone's policy;
+a 401 you fix by signing is the cheaper of the two mistakes.
+
+⭐ **Anything unique to you has a unique sha and never collides** — a customer
+photo, a document, a render. Collisions are for generic assets, which is exactly
+the content where sharing costs you nothing.
+
 ## 4. Resolving a stored reference — `extractAssetSha`
 
 When a stored value is already an `8ok.uk` URL, pull its sha:

package/src/index.ts

@@ -1135,7 +1135,37 @@ export type UploadResult = {
    * can close (`.mpga`, `.docx`, `.m4a` all arrive as octet-stream).
    */
   oext?: string | null;
-  cdnUrl: string;
+  /**
+   * La URL pública de una variante razonable — o **`null` si el asset es
+   * privado**, que no tiene ninguna.
+   *
+   * ⭐⭐ ERA `string`, Y ESO HACÍA QUE `upload()` PERDIERA EL HANDLE
+   *
+   * Los tres retornos de `upload()` arman este campo con `urlFor`, que llama a
+   * `assertPublic` y **tira** sobre un asset privado. Medido 2026-08-25 por una
+   * auditoría externa: subir bytes que deduplican contra una fila privada hacía
+   * que `upload()` lanzara DESPUÉS del PUT — los bytes quedaban guardados y el
+   * `assetId` se perdía, porque el error es un `Error` pelado sin `assetId`, sin
+   * `sha` y sin `cause`.
+   *
+   * ⚠️ Y el mensaje nombraba `getAssetUrl` y un preset `"lg"` que el llamador
+   * nunca pidió, así que iba a buscar en su código una función que no llamó.
+   *
+   * Un asset privado **no tiene** URL pública: eso es la feature. Lo que no
+   * puede pasar es que no tenerla cueste el resultado de una subida que ya
+   * ocurrió. Para servirlo, mirá `visibility` y usá `getPrivateAssetUrl` con la
+   * signing key, en tu backend.
+   */
+  cdnUrl: string | null;
+  /**
+   * `"public"` o `"private"`, tal como quedó el asset.
+   *
+   * ⭐ Existe porque `getAssetUrl(up, …)` —el patrón que enseña toda la doc—
+   * no podía detectar un privado: el guarda mira `asset.visibility`, y este
+   * objeto no lo llevaba. El resultado era una URL pública para un asset
+   * privado, servida sin una queja, que después da 404.
+   */
+  visibility: "public" | "private";
 };
 
 async function computeSha256(
@@ -1687,7 +1717,8 @@ export class NitidaClient {
         // Same shape as the presign branch below, for the same reason. This
         // DTO does carry `sha` today — but relying on that is how the other
         // branch broke, and the value we hashed ourselves is authoritative.
-        cdnUrl: this.urlFor(
+        visibility: existing.visibility ?? "public",
+        cdnUrl: this.publicUrlOrNull(
           { ...existing, sha: sha.slice(0, 16) },
           this.bestPresetForAsset(existing, mime),
         ),
@@ -1778,7 +1809,8 @@ export class NitidaClient {
         // ACTUALLY has, now that we waited for it — not from
         // `defaultPresetForMime`, which is a guess made before anything exists.
         // Guessing was safe only while this branch never ran.
-        cdnUrl: this.urlFor(
+        visibility: settled.visibility ?? "public",
+        cdnUrl: this.publicUrlOrNull(
           { ...settled, sha: short },
           this.bestPresetForAsset(settled, mime),
         ),
@@ -1834,10 +1866,27 @@ export class NitidaClient {
       sha: sha.slice(0, 16),
       mime: final.mime ?? mime,
       oext: final.oext ?? null,
-      cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
+      visibility: final.visibility ?? "public",
+      cdnUrl: this.publicUrlOrNull(final, this.bestPresetForAsset(final, mime)),
     };
   }
 
+  /**
+   * `urlFor` sin la excepción: `null` cuando el asset es privado.
+   *
+   * `upload()` no puede fallar por no poder construir una URL pública. Los
+   * bytes ya están; el handle tiene que volver igual.
+   */
+  private publicUrlOrNull(
+    asset: Parameters<typeof getAssetUrl>[0] & {
+      visibility?: "public" | "private";
+    },
+    preset: VariantPreset,
+  ): string | null {
+    if (asset.visibility === "private") return null;
+    return this.urlFor(asset, preset);
+  }
+
   private defaultPresetForMime(mime: string): VariantPreset {
     if (mime.startsWith("video/")) return "video";
     // The `mp3` variant only exists AFTER /process transcodes it; at presign