@aria-framework/kit 0.3.1 → 0.5.0

package/fileSniff.js

@@ -1,117 +1,210 @@
-/**
- * Magic-byte file-type validation for uploads.
- *
- * multer's `file.mimetype` is the client-declared Content-Type — attacker
- * controlled. This module reads the actual leading bytes and checks they are
- * consistent with the declared MIME's container family, so an HTML file
- * labelled `image/png` is rejected. Office formats can't be distinguished from
- * each other by magic alone (docx/xlsx are both ZIP; doc/xls are both OLE), so
- * we validate the container family, not the exact subtype.
- */
-
-const fs = require('fs');
-
-/** Sniff the container/type from the first bytes. Returns a coarse tag or null. */
-function sniff(filePath) {
-  let fd;
-  try {
-    fd = fs.openSync(filePath, 'r');
-    const buf = Buffer.alloc(16);
-    const n = fs.readSync(fd, buf, 0, 16, 0);
-    const b = buf.subarray(0, n);
-    const hex = b.toString('hex').toUpperCase();
-
-    if (hex.startsWith('89504E47')) return 'image/png';
-    if (hex.startsWith('FFD8FF')) return 'image/jpeg';
-    if (hex.startsWith('47494638')) return 'image/gif';
-    if (hex.startsWith('25504446')) return 'application/pdf';
-
-    // RIFF container — disambiguate by the form-type at bytes 8–12.
-    if (hex.startsWith('52494646') && n >= 12) {
-      const form = b.subarray(8, 12).toString('ascii');
-      if (form === 'WEBP') return 'image/webp';
-      if (form === 'WAVE') return 'riff-wave';
-      if (form === 'AVI ') return 'riff-avi';
-    }
-
-    // ISO-BMFF (MP4/MOV/M4A/HEIC): 'ftyp' box at bytes 4–8. We don't split the
-    // brand — validate the container family, like we do for zip-based formats.
-    if (n >= 8 && b.subarray(4, 8).toString('ascii') === 'ftyp') return 'isobmff';
-    // Matroska/WebM (EBML)
-    if (hex.startsWith('1A45DFA3')) return 'ebml';
-    // Ogg (audio/video)
-    if (hex.startsWith('4F676753')) return 'ogg';
-    // MP3: ID3 tag, or an MPEG audio frame sync (0xFFEx).
-    if (hex.startsWith('494433') || (n >= 2 && b[0] === 0xFF && (b[1] & 0xE0) === 0xE0)) return 'mp3';
-
-    // ZIP container (docx/xlsx and plain zip): PK\x03\x04 / PK\x05\x06 / PK\x07\x08
-    if (hex.startsWith('504B0304') || hex.startsWith('504B0506') || hex.startsWith('504B0708')) return 'zip';
-    // OLE compound file (legacy doc/xls)
-    if (hex.startsWith('D0CF11E0A1B11AE1')) return 'ole';
-    // Other archives
-    if (hex.startsWith('377ABCAF271C')) return '7z';
-    if (hex.startsWith('526172211A07')) return 'rar';   // 'Rar!\x1A\x07'
-    if (hex.startsWith('1F8B')) return 'gzip';
-    // No binary signature: treat as text only if there are no NUL bytes.
-    if (n > 0 && !b.includes(0)) return 'text';
-    return null;
-  } catch (_) {
-    return null;
-  } finally {
-    if (fd !== undefined) { try { fs.closeSync(fd); } catch (_) {} }
-  }
-}
-
-// Declared MIME → the sniffed tags that are acceptable for it.
-const FAMILY = {
-  'image/png': ['image/png'],
-  'image/jpeg': ['image/jpeg'],
-  'image/gif': ['image/gif'],
-  'image/webp': ['image/webp'],
-  'application/pdf': ['application/pdf'],
-  'text/plain': ['text'],
-  'text/csv': ['text'],
-  'application/msword': ['ole'],
-  'application/vnd.ms-excel': ['ole'],
-  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['zip'],
-  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['zip'],
-  // images (HEIC/HEIF are ISO-BMFF)
-  'image/heic': ['isobmff'],
-  'image/heif': ['isobmff'],
-  // video
-  'video/mp4': ['isobmff'],
-  'video/quicktime': ['isobmff'],
-  'video/webm': ['ebml'],
-  'video/x-msvideo': ['riff-avi'],
-  'video/ogg': ['ogg'],
-  // audio
-  'audio/mpeg': ['mp3'],
-  'audio/mp4': ['isobmff'],
-  'audio/x-m4a': ['isobmff'],
-  'audio/wav': ['riff-wave'],
-  'audio/x-wav': ['riff-wave'],
-  'audio/ogg': ['ogg'],
-  'audio/webm': ['ebml'],
-  // archives
-  'application/zip': ['zip'],
-  'application/x-zip-compressed': ['zip'],
-  'application/x-7z-compressed': ['7z'],
-  'application/x-rar-compressed': ['rar'],
-  'application/vnd.rar': ['rar'],
-  'application/gzip': ['gzip']
-};
-
-/**
- * True if the file's actual content is consistent with the declared MIME.
- * @param {string} filePath
- * @param {string} declaredMime
- * @returns {boolean}
- */
-function matches(filePath, declaredMime) {
-  const allowed = FAMILY[declaredMime];
-  if (!allowed) return false;
-  const sniffed = sniff(filePath);
-  return !!sniffed && allowed.includes(sniffed);
-}
-
-module.exports = { sniff, matches };
+/**
+ * Magic-byte file-type validation for uploads.
+ *
+ * multer's `file.mimetype` is the client-declared Content-Type — attacker
+ * controlled. This module reads the actual leading bytes and checks they are
+ * consistent with the declared MIME's container family, so an HTML file
+ * labelled `image/png` is rejected. Office formats can't be distinguished from
+ * each other by magic alone (docx/xlsx are both ZIP; doc/xls are both OLE), so
+ * we validate the container family, not the exact subtype.
+ *
+ * ACCEPTS A PATH OR A BUFFER. Both exist in practice: multer's disk storage gives a path, and
+ * its memory storage gives a buffer with no path at all — which is what a consumer writing
+ * documents into an encrypted database column uses. Sniffing only ever needed the first 16
+ * bytes, so a path-only signature meant the memory case could not be checked and simply was
+ * not, in the one app that stores uploads inside the database.
+ */
+
+const fs = require('fs');
+
+/** The first 16 bytes, from a path or straight from a buffer. */
+function head(input) {
+  if (Buffer.isBuffer(input)) return input.subarray(0, 16);
+  let fd;
+  try {
+    fd = fs.openSync(input, 'r');
+    const buf = Buffer.alloc(16);
+    const n = fs.readSync(fd, buf, 0, 16, 0);
+    return buf.subarray(0, n);
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) { /* noop */ }
+  }
+}
+
+/**
+ * Sniff the container/type from the first bytes. Returns a coarse tag or null.
+ * @param {string|Buffer} input  a file path, or the bytes themselves
+ */
+function sniff(input) {
+  try {
+    const b = head(input);
+    const hex = b.toString('hex').toUpperCase();
+
+    if (hex.startsWith('89504E47')) return 'image/png';
+    if (hex.startsWith('FFD8FF')) return 'image/jpeg';
+    if (hex.startsWith('47494638')) return 'image/gif';
+    if (hex.startsWith('25504446')) return 'application/pdf';
+
+    // RIFF container — disambiguate by the form-type at bytes 8–12.
+    if (hex.startsWith('52494646') && b.length >= 12) {
+      const form = b.subarray(8, 12).toString('ascii');
+      if (form === 'WEBP') return 'image/webp';
+      if (form === 'WAVE') return 'riff-wave';
+      if (form === 'AVI ') return 'riff-avi';
+    }
+
+    // ISO-BMFF (MP4/MOV/M4A/HEIC): 'ftyp' box at bytes 4–8. We don't split the
+    // brand — validate the container family, like we do for zip-based formats.
+    if (b.length >= 8 && b.subarray(4, 8).toString('ascii') === 'ftyp') return 'isobmff';
+    // Matroska/WebM (EBML)
+    if (hex.startsWith('1A45DFA3')) return 'ebml';
+    // Ogg (audio/video)
+    if (hex.startsWith('4F676753')) return 'ogg';
+    // MP3: ID3 tag, or an MPEG audio frame sync (0xFFEx).
+    if (hex.startsWith('494433') || (b.length >= 2 && b[0] === 0xFF && (b[1] & 0xE0) === 0xE0)) return 'mp3';
+
+    // ZIP container (docx/xlsx and plain zip): PK\x03\x04 / PK\x05\x06 / PK\x07\x08
+    if (hex.startsWith('504B0304') || hex.startsWith('504B0506') || hex.startsWith('504B0708')) return 'zip';
+    // OLE compound file (legacy doc/xls)
+    if (hex.startsWith('D0CF11E0A1B11AE1')) return 'ole';
+    // Other archives
+    if (hex.startsWith('377ABCAF271C')) return '7z';
+    if (hex.startsWith('526172211A07')) return 'rar';   // 'Rar!\x1A\x07'
+    if (hex.startsWith('1F8B')) return 'gzip';
+    // No binary signature: treat as text only if there are no NUL bytes.
+    if (b.length > 0 && !b.includes(0)) return 'text';
+    return null;
+  } catch (_) {
+    // A path that cannot be opened, or bytes that cannot be read. "Unknown" rather than a
+    // throw: the caller's next move is to reject the file either way, and a sniffer that can
+    // fail loudly turns an unreadable upload into a 500.
+    return null;
+  }
+}
+
+// Declared MIME → the sniffed tags that are acceptable for it.
+const FAMILY = {
+  'image/png': ['image/png'],
+  'image/jpeg': ['image/jpeg'],
+  'image/gif': ['image/gif'],
+  'image/webp': ['image/webp'],
+  'application/pdf': ['application/pdf'],
+  'text/plain': ['text'],
+  'text/csv': ['text'],
+  'application/msword': ['ole'],
+  'application/vnd.ms-excel': ['ole'],
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['zip'],
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['zip'],
+  // images (HEIC/HEIF are ISO-BMFF)
+  'image/heic': ['isobmff'],
+  'image/heif': ['isobmff'],
+  // video
+  'video/mp4': ['isobmff'],
+  'video/quicktime': ['isobmff'],
+  'video/webm': ['ebml'],
+  'video/x-msvideo': ['riff-avi'],
+  'video/ogg': ['ogg'],
+  // audio
+  'audio/mpeg': ['mp3'],
+  'audio/mp4': ['isobmff'],
+  'audio/x-m4a': ['isobmff'],
+  'audio/wav': ['riff-wave'],
+  'audio/x-wav': ['riff-wave'],
+  'audio/ogg': ['ogg'],
+  'audio/webm': ['ebml'],
+  // archives
+  'application/zip': ['zip'],
+  'application/x-zip-compressed': ['zip'],
+  'application/x-7z-compressed': ['7z'],
+  'application/x-rar-compressed': ['rar'],
+  'application/vnd.rar': ['rar'],
+  'application/gzip': ['gzip']
+};
+
+/**
+ * True if the file's actual content is consistent with the declared MIME.
+ * @param {string|Buffer} input   a file path, or the bytes themselves
+ * @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;
+  const sniffed = sniff(input);
+  return !!sniffed && allowed.includes(sniffed);
+}
+
+module.exports = { sniff, matches, resolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aria-framework/kit",
-  "version": "0.3.1",
+  "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,