Upload Verdict

An upload carries three independent claims about its type -- the filename extension, the declared Content-Type, and the actual bytes. Real upload code consults ONE of them.

Measured by execution against the libraries people actually use. mime-types, at roughly 50 million weekly downloads, maps EXTENSION to type and never reads a byte: mime.lookup("invoice.pdf") answers application/pdf for a file whose first bytes are 4d 5a 90 00, a Windows executable. Every check it is capable of performing passes. The file is stored, and later served, as a document.

file-type does read magic bytes and gets that case right. But it returns undefined for every text format -- a PHP open tag, a spreadsheet formula payload, an SVG carrying a script element. undefined means "I cannot tell", and calling code reads it as "nothing wrong". The formats it cannot judge are precisely the dangerous ones, because none of them have magic bytes. A byte sniffer is most confident exactly where it is least useful, and silent exactly where it matters.

THIS GATHERS EVERY SIGNAL AND CHECKS THEY AGREE. Bytes beat claims: content that is conclusively one thing while the name or header says another is not a mislabelled file, it is a file built to be handled by the wrong code path. undecidable is a REFUSAL, not a pass -- accepting it takes an explicit policy flag, and the reason is still recorded so the log stays honest. Text formats are inspected rather than shrugged at: PHP open tags, script elements, inline event handlers, javascript: URLs, and spreadsheet formula injection.

THE DISTINCTION THAT KEEPS THE GATE SWITCHED ON. = and @ always begin a formula; + and - begin BOTH formulas and ordinary negative numbers. The naive rule -- reject any cell starting = + - @ -- rejects -5, and a CSV gate that rejects negative numbers gets switched off within a week, taking the protection against =cmd| with it. Over-rejection here is not the lesser bug, it is how the real defence dies. So a leading sign followed by something that parses as a number is a value, and anything else after a sign is a formula.

NOT A VIRUS SCANNER. This decides whether a file is what it says it is, and whether its declared type is one you allow. Detecting malicious content inside a legitimately-typed file is a different job needing a different tool, and claiming otherwise is how a security library gets trusted for something it cannot do.

VERIFIED: 51 tests, 9 deliberate defects applied to the real source, 8 caught and 1 proved to change no observable behaviour (a control-character guard the only caller cannot reach, because it trims first) — the proofs ship in mutations.json. A seventh mutation targeted a buffer-length guard that turned out to be unfalsifiable in JavaScript -- out-of-range access yields undefined, which never equals a byte -- so the line was removed rather than counted. Zero runtime dependencies.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function sniffBytes(bytes: Uint8Array): string | null;
  export function inspectTextContent(bytes: Uint8Array):;
  export function judgeUpload(claim: UploadClaim, policy: Policy = {}): UploadVerdict;

  export type Verdict = "accept" | "reject" | "undecidable";