File Type

Magic-byte content-type detection independent of the declared MIME. The Content-Type header on a multipart upload is supplied by the client; a hostile uploader can label a polyglot HTML payload as image/png and the header alone won't catch it. This primitive inspects the leading bytes against a hardcoded signature registry (PNG / JPEG / GIF / WEBP / AVIF / HEIC / PDF / OOXML / CFB / ZIP / RAR / 7Z / TAR / GZIP / BZ2 / XZ / MP3 / MP4 / WEBM / PE / ELF / Mach-O) and returns the actual format.

detect(buf) returns null rather than throwing on bad input (saved-for-later analysis often runs against partial reads); assertOneOf(buf, allowlist) throws FileTypeError when the detected format is not in the operator-supplied allowlist. Allowlist entries match against mime ("image/png"), short name ("png"), or category ("image") — operators pin the tightest level the use case allows.

Out of scope: content disarm (CDR), polyglot detection, and filename-extension validation. Operators with disarm requirements reach for a sandbox like dangerzone or vmray; filename extensions live behind b.guardFilename. Operators extending the registry pass opts.extra to detect — extras come first, letting an operator override a built-in entry without forking.

b.fileType.detect(buf, opts?) #

{
  extra: Array<{ name, mime, extension, category, offset, magic, extra? }>,
}

Inspects the leading bytes of buf against the signature registry and returns { mime, extension, category, name } for the first matching entry, or null when no signature matches (or buf is empty, or not a Buffer/Uint8Array). OOXML entries (docx/xlsx/ pptx) sit before generic ZIP so well-formed Office files win before the bare ZIP shape; operators extending the registry via opts.extra get their entries scanned first so they can override built-ins without forking.

var fs = require("node:fs");
var buf = fs.readFileSync("photo.png");
b.fileType.detect(buf);
// → { mime: "image/png", extension: "png", category: "image", name: "png" }

b.fileType.detect(Buffer.from(""));   // → null

b.fileType.assertOneOf(buf, allowlist, opts?) #

{
  allowEmpty: boolean,                                                // default false
  extra:      Array<{ name, mime, extension, category, offset, magic, extra? }>,
}

Detects the format of buf and throws FileTypeError when the result is not in allowlist. Allowlist entries match by mime ("image/png"), short name ("png"), or category ("image") so operators pin the tightest level the use case allows. Empty buffers throw EMPTY unless opts.allowEmpty: true. Unrecognized magic bytes throw UNKNOWN_TYPE — the framework refuses to fall back to the advertised header MIME because the entire purpose of this primitive is mistrusting that header.

var fs = require("node:fs");
var buf = fs.readFileSync("photo.png");
var detected = b.fileType.assertOneOf(buf, ["image/png", "image/jpeg"]);
// → { mime: "image/png", extension: "png", category: "image", name: "png" }

// Category-level allowlist (any image format)
b.fileType.assertOneOf(buf, ["image"]);

Last updated 2026-08-08T16:39:49.652Z by seeder.