@ultimat3/storage 19.2.0 → 19.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.2.0"
+    "@ultimat3/core": "19.3.1"
   }
 }

package/src/errors.ts

@@ -179,6 +179,27 @@ export const contentTypeMismatch = (key: string, declared: string, sniffed: stri
     meta: { key, declared, sniffed },
   });
 
+/**
+ * The bytes match NO rule at all, under a type a signature could have confirmed. Its own
+ * constructor rather than `contentTypeMismatch` with a placeholder, because that error's `fix:`
+ * offers the sniffed type as the one to re-declare and here there is no such type — the whole
+ * finding is that nothing recognised these bytes. Same shipped code: what a client retries on is
+ * unchanged.
+ *
+ * The `fix:` names the CALL and the key, never "upload a genuine file". There is exactly one
+ * remedy — re-run the same validation over different bytes — and the reader's problem is which
+ * bytes, so the line has to name the operation it is re-running and the object it is re-running it
+ * for. `upload a genuine <type> file` restated the type the caller had already declared and gave a
+ * CLI, an MCP tool or an agent nothing to do.
+ */
+export const contentTypeUnrecognised = (key: string, declared: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared}, and its first bytes match no known signature — every ${declared} carries one`,
+    fix: `re-send "${key}" through validateUpload(candidate, policy) with the bytes of a real ${declared}: the ones sent open with no ${declared} signature, so they are another format or truncated`,
+    meta: { key, declared },
+  });
+
 export const checksumMismatch = (key: string, declared: string, actual: string): StorageError =>
   new StorageError({
     code: 'X_STORAGE_CHECKSUM_MISMATCH',

package/src/index.ts

@@ -73,6 +73,7 @@ export {
   checksumMismatch,
   contentTypeMismatch,
   contentTypeNotAllowed,
+  contentTypeUnrecognised,
   deleteFailed,
   diskUnknown,
   isStorageError,

package/src/upload.ts

@@ -2,11 +2,20 @@
 // allowlist, checksum — and the content-type sniff that enforces it.
 // WHY sniff: `Content-Type` is attacker-controlled. A `.png` that is really an HTML document
 // is a stored-XSS delivery vehicle the moment any surface serves it back with the declared
-// type, so the magic bytes decide and a contradiction is rejected outright.
+// type, so the magic bytes decide and a contradiction is rejected outright — including the
+// contradiction of NO answer at all, where the declared type is one a signature could have
+// confirmed. A type no rule can ever confirm (`text/csv`, `application/json`) is still accepted
+// on the client's word: there is nothing to compare it against.
 
 import { finiteCount } from '@ultimat3/core';
 import { sha256Base64 } from './driver';
-import { checksumMismatch, contentTypeMismatch, contentTypeNotAllowed, tooLarge } from './errors';
+import {
+  checksumMismatch,
+  contentTypeMismatch,
+  contentTypeNotAllowed,
+  contentTypeUnrecognised,
+  tooLarge,
+} from './errors';
 import { assertSafeKey } from './path';
 
 export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
@@ -182,6 +191,17 @@ export function contentTypeMatches(declared: string, sniffed: string): boolean {
   return false;
 }
 
+/**
+ * Whether the magic bytes could ever CONFIRM this declared type — the question a `undefined`
+ * sniff has to be read against. Through `contentTypeMatches` rather than an equality on
+ * `rule.type`, so the zip containers ride along: no rule names a `.docx`, but every OOXML
+ * document is a zip and `application/zip` is a rule, so an unrecognisable body under that type is
+ * as provably wrong as one under `image/png`.
+ */
+function hasSignature(declared: string): boolean {
+  return MAGIC_RULES.some((rule) => contentTypeMatches(declared, rule.type));
+}
+
 /**
  * Throws the first violated constraint, in this order: key, size, type, checksum. The key comes
  * before the size because a key nothing may store makes the other three moot, and which
@@ -200,7 +220,13 @@ export function validateUpload(
     throw contentTypeNotAllowed(key, declared, policy.allowedContentTypes);
   }
   const sniffed = sniffContentType(candidate.bytes);
-  if (sniffed !== undefined && !contentTypeMatches(declared, sniffed)) {
+  if (sniffed === undefined) {
+    // `undefined` is "no rule recognised it", never "it is fine" — `sniffContentType`'s own doc
+    // says so and this branch read it the other way, so any body the sniffer bailed on (one
+    // control byte, one non-UTF-8 sequence) skipped the guard entirely. Measured: an HTML
+    // document with a trailing `0x01` was accepted as `image/png`.
+    if (hasSignature(declared)) throw contentTypeUnrecognised(key, declared);
+  } else if (!contentTypeMatches(declared, sniffed)) {
     throw contentTypeMismatch(key, declared, sniffed);
   }