Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/naandalist/secure-file-validator
Secure file validation library with signature checking and content validation
https://github.com/naandalist/secure-file-validator
file-security file-validation mime-type secure-file-upload signature-check
Last synced: 4 days ago
JSON representation
Secure file validation library with signature checking and content validation
- Host: GitHub
- URL: https://github.com/naandalist/secure-file-validator
- Owner: Naandalist
- License: mit
- Created: 2024-11-06T14:05:18.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2024-11-07T02:39:24.000Z (about 2 months ago)
- Last Synced: 2024-12-08T07:47:37.147Z (26 days ago)
- Topics: file-security, file-validation, mime-type, secure-file-upload, signature-check
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/secure-file-validator
- Size: 62.5 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# secure-file-validator
[](https://badge.fury.io/js/secure-file-validator)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
A secure file validation library for Node.js that performs signature checking and content validation. It hardenings app from malicious file uploads by validating file types, checking file signatures, and scanning for suspicious patterns.
This library is built following industry-standard security guidelines:
- [OWASP Unrestricted File Upload Prevention](https://owasp.org/www-community/vulnerabilities/Unrestricted_File_Upload)
- [CWE-434: Unrestricted Upload of File with Dangerous Type](https://cwe.mitre.org/data/definitions/434.html)
- [NIST Security Guidelines for File Uploads](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-53r5.pdf)
## Features
- 🔒 Secure file signature validation
- 📝 Content pattern scanning for malicious code
- 🎯 Support for multiple file types (JPEG, PNG, GIF, PDF, SVG)
- ⚡ Promise-based async/await API
- 🛡️ Built-in security checks for PDF and SVG files
- 📦 Zero dependencies
- 🌟 TypeScript support
- ⚙️ Customizable file size validation
## Installation
```bash
npm install secure-file-validator
```
## Usage
### Basic Usage (Default 5MB limit)
```javascript
import { validateFile } from "secure-file-validator";
try {
const result = await validateFile("path/to/your/file.pdf");
if (result.status) {
console.log("File is valid:", result.message);
} else {
console.log("File validation failed:", result.message);
}
} catch (error) {
console.error("Error:", error);
}
```
### Custom File Size Limit
```javascript
import { validateFile } from "secure-file-validator";
// Example: Set 10MB limit
const TEN_MB = 10 * 1024 * 1024; // 10MB in bytes
try {
const result = await validateFile("path/to/your/file.pdf", {
maxSizeInBytes: TEN_MB,
});
if (result.status) {
console.log("File is valid:", result.message);
} else {
console.log("File validation failed:", result.message);
}
} catch (error) {
console.error("Error:", error);
}
```
### Using Size Constants
```javascript
// File size constants for convenience
const KB = 1024;
const MB = 1024 * KB;
const GB = 1024 * MB;
// Examples
const options = {
maxSizeInBytes: 10 * MB, // 10MB
// or
// maxSizeInBytes: 1 * GB // 1GB
};
const result = await validateFile("path/to/file.pdf", options);
```
### Advanced Usage
```javascript
import {
validateFile,
validateFileContent,
checkFileSignature,
} from "secure-file-validator";
// Example: Custom validation pipeline with size limit
async function validateUserUpload(filePath) {
const options = {
maxSizeInBytes: 15 * 1024 * 1024, // 15MB limit
};
// First, validate the entire file
const fileValidation = await validateFile(filePath, options);
if (!fileValidation.status) {
return fileValidation;
}
// Then, perform additional content validation if needed
const contentValidation = await validateFileContent(filePath);
return contentValidation;
}
```
## Supported File Types
| Category | File Type |
| --------------- | --------- |
| Images | JPEG/JPG |
| Images | PNG |
| Images | GIF |
| Documents | PDF |
| Vector Graphics | SVG |
## API Reference
### validateFile(filePath, options)
Main validation function that performs all checks.
| Parameter | Type | Description | Default |
| ------------------------ | ------ | ---------------------------- | -------- |
| `filePath` | string | Path to the file to validate | required |
| `options ` | Object | Configuration options | `{}` |
| `options.maxSizeInBytes` | number | Maximum file size in bytes | 5MB |
| Return Type | Description |
| ------------------------- | ------------------------------------ |
| `Promise` | Async result object |
| `Promise.status` | boolean indicating validation result |
| `Promise.message` | string containing detailed message |
### validateFileContent(filePath)
Performs content-specific validation.
| Parameter | Type | Description | Default |
| ---------- | ------ | ---------------------------- | -------- |
| `filePath` | string | Path to the file to validate | required |
| Return Type | Description |
| ------------------------- | ------------------------------------ |
| `Promise` | Async result object |
| `Promise.status` | boolean indicating validation result |
| `Promise.message` | string containing detailed message |
### checkFileSignature(buffer, signatures)
Checks file buffer against known signatures.
| Parameter | Type | Description | Default |
| ------------ | ---------------------- | --------------------------------- | -------- |
| `buffer` | Buffer | File buffer to check | required |
| `signatures` | `Array>` | Valid signatures to check against | required |
| Return Type | Description |
| ----------- | ------------------------------------------ |
| `boolean` | True if signature matches, false otherwise |
## File Size Configuration
The file size limit is configurable through the `maxSizeInBytes` option:
```javascript
// Common file size limits
const limits = {
small: 1 * 1024 * 1024, // 1MB
medium: 10 * 1024 * 1024, // 10MB
large: 100 * 1024 * 1024, // 100MB
custom: 15.5 * 1024 * 1024, // 15.5MB
};
// Usage
const result = await validateFile("file.pdf", {
maxSizeInBytes: limits.medium,
});
```
## Example Results
```javascript
// Successful validation
{
status: true,
message: "Content validation passed"
}
// Failed validation (file size)
{
status: false,
message: "File size exceeds limit of 5MB"
}
// Failed validation (invalid file type)
{
status: false,
message: "Invalid file extension"
}
// Failed validation (malicious content)
{
status: false,
message: "Suspicious pattern detected: /