secure-file-validator

Zero-dependency Node.js helper for upload type checks: extension, size, magic numbers, plus a small PDF and SVG content policy.

Aligned with the file-type checking part of OWASP Unrestricted File Upload and CWE-434. Not an antivirus. Not a complete upload-security stack.

Current release: 2.0.0. See CHANGELOG.md.

Install

npm install secure-file-validator

Requires Node.js 14.16+ (ESM).

Quick start

import { validateFile } from "secure-file-validator";

const result = await validateFile("uploads/photo.jpg");

if (result.ok) {
  // result.code === "OK"
} else {
  // result.code === "INVALID_SIGNATURE" | "PDF_JAVASCRIPT" | ...
  console.error(result.code, result.message);
}

result.status still exists as a deprecated alias of result.ok.

From an upload buffer

import { validateFile, validateBytes } from "secure-file-validator";

const result = await validateFile(req.file.buffer, {
  filename: req.file.originalname, // or extension: ".png"
});

if (!result.ok) {
  throw new Error(result.code);
}

const sync = validateBytes(req.file.buffer, { extension: ".png" });

Buffer / Uint8Array input must include filename or extension. Size is checked with byteLength.

Supported types

Extension	Magic check
.jpg / .jpeg	FF D8 FF (any marker after SOI)
.png	89 50 4E 47
.gif	47 49 46 38
.pdf	%PDF + %%EOF, then token policy
.svg	<?xml or <svg, then SVG policy

Default size cap: 5MB (options.maxSizeInBytes).

PDF policy

The checker looks for PDF name tokens, including hex-escaped names (/J#53 → /JS) and names inside inflated Flate streams. The letters JS in ordinary text or XMP are not a hit.

Token	Default	code
/Metadata	allow	PDF_METADATA
/Annots	allow	PDF_ANNOTS
/OpenAction	allow	PDF_OPEN_ACTION
/JS, /JavaScript	deny	PDF_JAVASCRIPT
/Launch	deny	PDF_LAUNCH
/EmbeddedFile	deny	PDF_EMBEDDED_FILE
/XFA	deny	PDF_XFA
/RichMedia	deny	PDF_RICH_MEDIA

const strict = await validateFile(pdfPath, {
  pdf: { allowOpenAction: false },
});

// Dangerous: turns the script check off
const trusted = await validateFile(pdfPath, {
  pdf: { allowJavaScript: true },
});

pdfWhitelist still works as a deprecated alias (JS and JavaScript both set allowJavaScript). Do not allow JavaScript only to silence metadata — metadata already passes. See #1.

SVG policy

Always denied: <script>, javascript:, event handlers (onload= …), <!ENTITY.

Denied by default, overridable with options.svg:

Rule	Default	code
foreignObject	deny	SVG_FOREIGN_OBJECT
data: URI	deny	SVG_DATA_URI
external href	deny	SVG_EXTERNAL_HREF

Allowed: DOCTYPE without ENTITY, fragment href="#id".

await validateFile(svgPath, {
  svg: { allowDataUri: true },
});

Result

{
  ok: false,
  status: false,          // deprecated alias of ok
  code: "PDF_JAVASCRIPT",
  message: "Suspicious PDF name token detected: /JavaScript",
  details: { token: "JavaScript" }
}

code	Meaning
OK	Passed
UNSUPPORTED_TYPE	Extension not in the allow list
INVALID_EXTENSION	Bad or missing extension (buffers need filename / extension)
TOO_LARGE	Over maxSizeInBytes
INVALID_SIGNATURE	Magic number does not match the extension
IO_ERROR	Missing file or unreadable input
PDF_* / SVG_*	See the policy tables

Switch on code. Do not parse message.

API

validateFile(input, options?): Promise<ValidationResult>
validateFileContent(input, options?): Promise<ValidationResult>
validateBytes(bytes, options?): ValidationResult

input is a filesystem path, Buffer, or Uint8Array.

Option	Type	Default
maxSizeInBytes	number	5 * 1024 * 1024
filename	string	required for buffers if extension is omitted
extension	string	.png or png
pdf	PdfPolicy	see table
svg	SvgPolicy	see table
pdfWhitelist	string[]	deprecated alias

Migrating from 1.x

1.x	2.x
result.status	result.ok (status still works)
result.message only	also result.code
path string only	path, Buffer, or Uint8Array
JPEG only FF D8 FF E0/E1	any FF D8 FF
PDF substring /JS/, /Metadata/	name tokens; metadata allowed by default
pdfWhitelist: ['JS'] to dodge false positives	not needed for metadata; use pdf.allowJavaScript only if you mean it

Scope

Does: type vs magic-number check, size cap, PDF name-token policy, SVG active-content policy.

Does not: antivirus, Office/ZIP unpacking, zip-bomb detection, filename sanitization, storage layout, Content-Type on the way out, auth, or rate limits.

Suggested pipeline:

1. Validate bytes (validateFile(buffer, { filename })).
2. Store under a generated name, not the client filename.
3. Keep files outside the webroot.
4. Serve a Content-Type you chose, not one taken from the client.

FAQ

Legitimate PDFs used to fail with /JS/ or /Metadata/.
That was a substring false positive (#1). 2.0.0 matches name tokens only. Metadata / Annots / OpenAction pass by default.

Is a passing result enough to call an upload safe?
No. This reduces wrong-type and obvious active-content mistakes. Pair it with generated names, isolated storage, and a tight serving policy.

License

MIT — see LICENSE.