@nitida/asset-client 0.18.1 → 0.19.1

package/AGENTS.md

@@ -91,6 +91,22 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
 - **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
 - **The signing key is a backend secret** — it mints URLs for every private
   asset the tenant owns.
+- **⭐ Where the signing key comes from: the response that CREATED your
+  project, once.** `POST /admin/projects` returns `signingKey` next to the
+  three API keys, and the console shows it in the same panel. Nothing else
+  hands it out — `GET /admin/projects/:code` does **not** include it. If it is
+  lost, the only endpoint that returns a key is
+  `POST /admin/projects/:code/rotate-signing-key`, which **invalidates every
+  URL already signed** and needs the system-scope key the platform operator
+  holds. A tenant with nothing signed yet can rotate for free; a live one
+  cannot, which is why you save it at creation.
+- **⭐ Already have a project and never saw a signing key?** Then you never got
+  one — projects created before 2026-08-23 were not handed it, and no endpoint
+  shows you the current one. **If you have not signed any URLs yet, ask us to
+  rotate: with nothing in flight, rotation invalidates nothing and is free.**
+  If you already have signed URLs circulating, ask us for the current key
+  instead. This is the wall the T5 agent hit, and the sentence that was
+  missing.
 
 ## The endpoint
 
@@ -101,5 +117,7 @@ was never renamed.
 
 ⚠️ `@aquienpz/asset-client` still exists on npm but is **frozen at 0.14.2 (2026-07-18)**. It
 predates `oext`, the `variants` array, and a `hasPreset` that does not claim an `original` the
-asset does not have. Install `@nitida/asset-client`. The `@aquienpz/tenant-config` and
-`@aquienpz/asset-uploader-*` packages are internal and are not on npm at all.
+asset does not have. Install `@nitida/asset-client`. `@nitida/asset-uploader-web` and
+`@nitida/asset-uploader-expo` ARE on npm since 2026-08-23 — reach for one only
+when you need an upload to survive a reload or a backgrounded app.
+`@aquienpz/tenant-config` is still internal.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Espacio Futuro LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -128,3 +128,13 @@ shape. `presets` is populated everywhere, on every version — so read existence
 
 Deeper guidance — including uploads, tenant onboarding and the CORS boundary — lives in
 `@nitida/sdk`'s `skills/nitida-sdk/SKILL.md`, which ships inside that package.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+⚠️ **The licence covers this client code, not the service.** MIT lets you use,
+modify and redistribute the SDK; it does not grant access to nitida. The
+service is governed by its own terms and plan tiers, and every call still needs
+credentials issued to your project. Same shape as every other API client you
+already depend on.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **security@espaciofuturo.io**. Please do not open a public issue — a
+public report is a disclosure, and it reaches attackers at the same moment it
+reaches us.
+
+Include what you have: the affected package and version, what you did, and what
+happened. A URL that reproduces it is worth more than a paragraph describing
+one. We will confirm receipt and tell you what we found.
+
+## What is in scope
+
+The published client packages and the service they talk to:
+
+- `@nitida/sdk`, `@nitida/asset-client`
+- `@nitida/asset-compressor-web`, `@nitida/asset-compressor-native`
+- `@nitida/asset-uploader-web`, `@nitida/asset-uploader-expo`
+- the delivery edge (`8ok.uk`) and the API (`api.nitida.gofuture.space`)
+
+## Two behaviours that look like bugs and are not
+
+Reported often enough to state up front, so a real report is not lost among
+them:
+
+**A 404 on a private asset is the feature.** An asset with
+`visibility: "private"` answers 404 on every public URL — the raw path, every
+stored variant, every `/t/` transform and every HLS segment. It is not a
+missing file. Signed access lives at `/a/{tenant}/…?exp&sig`, minted on your
+backend. See the SDK's `getPrivateAssetUrl`.
+
+**A presigned upload URL is a bearer credential, on purpose.** The browser
+uploader persists presigned R2 PUT URLs in IndexedDB, because that is what
+resuming after a reload means. They are write-only, scoped to the parts of one
+upload the holder started, expire in 60 minutes, and are deleted on complete
+and on abort.
+
+## Credentials, and the one mistake that matters
+
+An API key (`amk_rt_*`, `amk_ad_*`, `amk_ci_*`) is a **server-side** credential.
+It must never reach a browser bundle, an `NEXT_PUBLIC_*` variable, or a mobile
+app binary.
+
+The same goes for a tenant's **URL signing key**: it mints signed URLs for
+every private asset that tenant owns. Sign on your backend, or pre-sign at
+build time.
+
+The client packages are built so this is hard to get wrong — the web entrypoint
+`@nitida/sdk/web` does not accept `apiKey` or `signingKey` at all; the types
+reject them. If you find a path that leaks either one, that is exactly the
+report we want.
+
+If you believe a key has been exposed, email the address above and we will
+rotate it. Rotating a signing key invalidates every URL already signed with it,
+so tell us whether you have signed URLs in circulation.

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   PRESET_LONG: () => PRESET_LONG,
   PRESET_MAX_DIM: () => PRESET_MAX_DIM,
   PRESET_SHORT: () => PRESET_SHORT,
+  REQUESTABLE_PRESETS: () => REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS: () => TRANSFORM_WIDTHS,
   accessMessage: () => accessMessage,
   assertPublic: () => assertPublic,
@@ -54,6 +55,7 @@ __export(index_exports, {
   hasPreset: () => hasPreset,
   hlsLadderAlignment: () => hlsLadderAlignment,
   invalidateSlotCache: () => invalidateSlotCache,
+  isRequestablePreset: () => isRequestablePreset,
   iteratePaletteSwatches: () => iteratePaletteSwatches,
   pickAmbientBackground: () => pickAmbientBackground,
   relativeLuminance: () => relativeLuminance,
@@ -63,7 +65,8 @@ __export(index_exports, {
   setCdnBase: () => setCdnBase,
   setTenantId: () => setTenantId,
   signAccessUrl: () => signAccessUrl,
-  signTransformUrl: () => signTransformUrl
+  signTransformUrl: () => signTransformUrl,
+  toRequestablePresets: () => toRequestablePresets
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -130,10 +133,10 @@ async function signAccessUrl(publicUrl, signingKey, opts) {
   u.searchParams.set("sig", sig);
   return u.toString();
 }
-function assertPublic(asset, fn, escape) {
+function assertPublic(asset, fn, escapeHatch) {
   if (asset.visibility !== "private") return;
   throw new Error(
-    `${fn}: this asset is private, so a public CDN URL for it will answer 404 \u2014 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.`
+    `${fn}: this asset is private, so a public CDN URL for it will answer 404 \u2014 that is the feature, not a missing file. Mint a signed URL on your BACKEND instead: await ${escapeHatch}. Never ship the signing key to a browser.`
   );
 }
 function assertSha(asset, fn) {
@@ -503,6 +506,28 @@ function materializeResolution(dto, overridePreset) {
 }
 
 // src/index.ts
+var REQUESTABLE_PRESETS = [
+  "thumb",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "original",
+  "poster",
+  "video",
+  "aiproxy",
+  "probe"
+];
+var isRequestablePreset = (v) => REQUESTABLE_PRESETS.includes(v);
+var toRequestablePresets = (input) => {
+  const bad = input.filter((p) => !isRequestablePreset(p));
+  if (bad.length > 0) {
+    throw new Error(
+      `Cannot request ${bad.map((b) => `"${b}"`).join(", ")}. \`hls\` and \`mp3\` are things a variant can BE, not things you may ask for \u2014 the server derives them itself (hls when a video is transcoded, mp3 alongside any audio original). Requestable: ${REQUESTABLE_PRESETS.join(", ")}.`
+    );
+  }
+  return input;
+};
 var PRESET_SHORT = {
   thumb: "q",
   sm: "s",
@@ -719,6 +744,7 @@ function getAssetDimensions(asset) {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
@@ -749,6 +775,7 @@ function getAssetDimensions(asset) {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   pickAmbientBackground,
   relativeLuminance,
@@ -758,6 +785,7 @@ function getAssetDimensions(asset) {
   setCdnBase,
   setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets
 });
 //# sourceMappingURL=index.cjs.map