@aria-framework/kit 0.4.0 → 0.5.0

package/fileSniff.js

@@ -127,6 +127,79 @@ const FAMILY = {
  * @param {string} declaredMime
  * @returns {boolean}
  */
+/**
+ * Extension → MIME, for the cases MAGIC BYTES CANNOT SETTLE.
+ *
+ * .docx, .xlsx and a plain .zip are all ZIP containers; .doc and .xls are both OLE; .mp4, .mov,
+ * .m4a and .heic are all ISO-BMFF. The bytes identify the CONTAINER and stop there, so
+ * something else has to choose within it — and the only candidates are client-supplied.
+ *
+ * That is not a flaw in this table, it is the shape of the formats. What matters is that the
+ * caller is TOLD which answer it got: `from: 'content'` was decided by the bytes and cannot be
+ * influenced; `from: 'extension'` was narrowed by a client-supplied name inside a container the
+ * bytes did confirm. An app storing documents may accept the second; one serving them back
+ * inline should think about it.
+ */
+const EXT = {
+  doc: 'application/msword',
+  xls: 'application/vnd.ms-excel',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  zip: 'application/zip',
+  heic: 'image/heic',
+  heif: 'image/heif',
+  mp4: 'video/mp4',
+  m4v: 'video/mp4',
+  mov: 'video/quicktime',
+  m4a: 'audio/x-m4a',
+  webm: 'video/webm',
+  mkv: 'video/webm',
+  avi: 'video/x-msvideo',
+  wav: 'audio/wav',
+  mp3: 'audio/mpeg',
+  txt: 'text/plain',
+  csv: 'text/csv'
+};
+
+/** Tags sniff() returns that ARE the answer, needing no extension to disambiguate. */
+const CONCRETE = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'application/pdf']);
+
+/**
+ * DECIDE the type, rather than checking someone else's claim.
+ *
+ * `matches()` asks "are these bytes consistent with what the client said?" — and then the caller
+ * usually stores what the client said. `resolve()` asks "what ARE these bytes?" and returns the
+ * answer to store. Where magic is unambiguous the client has no say at all; where it is not, the
+ * extension narrows within a container the bytes confirmed, and the result says so.
+ *
+ * Promoted from a consuming app that had written this by hand for five types, because deriving
+ * is strictly stronger than validating: a file whose bytes say nothing recognisable is REJECTED,
+ * rather than accepted under whatever label happened to arrive with it.
+ *
+ * @param {string|Buffer} input     a path or the bytes
+ * @param {string}        filename  the client's name — used ONLY to disambiguate a container
+ * @param {Set}           allow     permitted MIME types; anything outside is rejected
+ * @returns {{mime: string, from: 'content'|'extension'}|null}
+ */
+function resolve(input, { filename = '', allow = null } = {}) {
+  const tag = sniff(input);
+  if (!tag) return null;                       // unrecognised bytes are refused, never guessed
+
+  const permitted = (m) => !allow || allow.has(m);
+
+  // 1. The bytes named it outright. The client's opinion is not consulted.
+  if (CONCRETE.has(tag)) return permitted(tag) ? { mime: tag, from: 'content' } : null;
+
+  // 2. A container. Narrow by extension, but only to something the container can actually hold —
+  //    so a ZIP named .mp4 is refused rather than relabelled.
+  const ext = String(filename).toLowerCase().split('.').pop();
+  const byExt = EXT[ext];
+  if (!byExt) return null;
+  const acceptableTags = FAMILY[byExt] || [];
+  if (!acceptableTags.includes(tag)) return null;
+  return permitted(byExt) ? { mime: byExt, from: 'extension' } : null;
+}
+
 function matches(input, declaredMime) {
   const allowed = FAMILY[declaredMime];
   if (!allowed) return false;
@@ -134,4 +207,4 @@ function matches(input, declaredMime) {
   return !!sniffed && allowed.includes(sniffed);
 }
 
-module.exports = { sniff, matches };
+module.exports = { sniff, matches, resolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-framework/kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Aria App Framework — kit module. Small dependency-free server utilities: open-redirect guard (safeReturnTo), SQL LIKE escaping, magic-byte upload validation (fileSniff), Crockford base32 tracking IDs, and person-name compose/split helpers.",
   "license": "UNLICENSED",
   "private": false,