@msal95/fileguard 0.1.1

package/src/adapters/express.js

@@ -0,0 +1,86 @@
+import busboy from 'busboy'
+import { validateFile } from '../core/validator.js'
+import { getStorageAdapter } from '../storage/index.js'
+import { failResult } from '../errors/UploadError.js'
+
+/**
+ * Create an Express middleware that handles multipart file uploads.
+ *
+ * Attaches the result to `req.uploadResult` and always calls `next()`.
+ * On an unexpected internal error, calls `next(err)`.
+ *
+ * Usage:
+ *   app.post('/upload', createExpressMiddleware(config), (req, res) => {
+ *     if (!req.uploadResult.success) return res.status(422).json(req.uploadResult)
+ *     res.json(req.uploadResult)
+ *   })
+ *
+ * @param {object} [config] - fileguard config (storage, allowedExtensions, etc.)
+ * @returns {Function} Express middleware (req, res, next) => void
+ */
+export function createExpressMiddleware(config = {}) {
+  return function uploadMiddleware(req, res, next) {
+    let bb
+    try {
+      bb = busboy({ headers: req.headers, limits: { files: 1 } })
+    } catch (err) {
+      // Malformed Content-Type header (e.g. not a multipart request)
+      req.uploadResult = failResult('STORAGE_ERROR', `Could not parse request: ${err.message}`)
+      return next()
+    }
+
+    let fileData = null
+    let done = false
+    const finish = (result) => {
+      if (done) return
+      done = true
+      req.uploadResult = result
+      next()
+    }
+
+    bb.on('file', (fieldname, fileStream, info) => {
+      const { filename, mimeType } = info
+      const chunks = []
+      fileStream.on('data', (chunk) => chunks.push(chunk))
+      fileStream.on('end', () => {
+        fileData = { buffer: Buffer.concat(chunks), filename, mimeType }
+      })
+      fileStream.on('error', (err) => next(err))
+    })
+
+    bb.on('finish', async () => {
+      try {
+        if (!fileData) {
+          return finish(failResult('STORAGE_ERROR', 'No file found in request'))
+        }
+
+        const { buffer, filename, mimeType } = fileData
+        const validation = await validateFile(
+          { buffer, filename, mimeType, size: buffer.length },
+          config
+        )
+
+        if (!validation.success) return finish(validation)
+
+        const store = await getStorageAdapter(config.storage ?? 'local')
+        const result = await store(
+          {
+            buffer,
+            filename,
+            sanitizedFilename: validation.sanitizedFilename,
+            size: buffer.length,
+            mimeType,
+          },
+          config
+        )
+
+        finish(result)
+      } catch (err) {
+        if (!done) { done = true; next(err) }
+      }
+    })
+
+    bb.on('error', (err) => { if (!done) { done = true; next(err) } })
+    req.pipe(bb)
+  }
+}

package/src/adapters/fastify.js

@@ -0,0 +1,105 @@
+import busboy from 'busboy'
+import { validateFile } from '../core/validator.js'
+import { getStorageAdapter } from '../storage/index.js'
+import { failResult } from '../errors/UploadError.js'
+
+/**
+ * Parse a raw Node.js http.IncomingMessage as a multipart upload using busboy.
+ * @param {import('http').IncomingMessage} rawRequest
+ * @param {object} config
+ * @returns {Promise<object>} fileguard result object
+ */
+async function processMultipart(rawRequest, config) {
+  return new Promise((resolve, reject) => {
+    let bb
+    try {
+      bb = busboy({ headers: rawRequest.headers, limits: { files: 1 } })
+    } catch (err) {
+      return resolve(failResult('STORAGE_ERROR', `Could not parse request: ${err.message}`))
+    }
+
+    let fileData = null
+
+    bb.on('file', (fieldname, fileStream, info) => {
+      const { filename, mimeType } = info
+      const chunks = []
+      fileStream.on('data', (chunk) => chunks.push(chunk))
+      fileStream.on('end', () => {
+        fileData = { buffer: Buffer.concat(chunks), filename, mimeType }
+      })
+      fileStream.on('error', reject)
+    })
+
+    bb.on('finish', async () => {
+      try {
+        if (!fileData) {
+          return resolve(failResult('STORAGE_ERROR', 'No file found in request'))
+        }
+
+        const { buffer, filename, mimeType } = fileData
+        const validation = await validateFile(
+          { buffer, filename, mimeType, size: buffer.length },
+          config
+        )
+
+        if (!validation.success) return resolve(validation)
+
+        const store = await getStorageAdapter(config.storage ?? 'local')
+        const result = await store(
+          {
+            buffer,
+            filename,
+            sanitizedFilename: validation.sanitizedFilename,
+            size: buffer.length,
+            mimeType,
+          },
+          config
+        )
+        resolve(result)
+      } catch (err) {
+        reject(err)
+      }
+    })
+
+    bb.on('error', reject)
+    rawRequest.pipe(bb)
+  })
+}
+
+/**
+ * Create a Fastify plugin for file uploads.
+ *
+ * Registers a content-type parser for multipart/form-data and adds an
+ * `uploadGuard()` decorator that returns a preHandler function.
+ *
+ * Usage:
+ *   await fastify.register(createFastifyPlugin({ storage: 'local' }))
+ *   fastify.post('/upload', { preHandler: fastify.uploadGuard() }, async (req, reply) => {
+ *     reply.send(req.uploadResult)
+ *   })
+ *
+ * @param {object} [config] - fileguard config
+ * @returns {Function} Fastify plugin async (fastify, opts) => void
+ */
+export function createFastifyPlugin(config = {}) {
+  return async function fastifyUploadPlugin(fastify) {
+    // Prevent Fastify from trying to JSON-parse multipart bodies.
+    fastify.addContentTypeParser('multipart/form-data', (_req, payload, done) => {
+      done(null, payload)
+    })
+
+    /**
+     * Returns a preHandler that validates + stores the upload and attaches
+     * the result to `request.uploadResult`.
+     * @param {object} [overrides] - per-route config overrides
+     * @returns {Function} async (request, reply) => void
+     */
+    fastify.decorate('uploadGuard', function uploadGuard(overrides = {}) {
+      const mergedConfig = { ...config, ...overrides }
+
+      return async function preHandler(request) {
+        request.uploadResult = await processMultipart(request.raw, mergedConfig)
+      }
+    })
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,3 @@
+export { createExpressMiddleware } from './express.js'
+export { createNextHandler } from './nextjs.js'
+export { createFastifyPlugin } from './fastify.js'

package/src/adapters/nextjs.js

@@ -0,0 +1,74 @@
+import { validateFile } from '../core/validator.js'
+import { getStorageAdapter } from '../storage/index.js'
+import { failResult } from '../errors/UploadError.js'
+
+/**
+ * Create a Next.js App Router route handler for file uploads.
+ *
+ * Usage in app/api/upload/route.js:
+ *   import { createNextHandler } from 'fileguard/nextjs'
+ *   export const POST = createNextHandler({ storage: 'local', localPath: './uploads' })
+ *
+ * @param {object} [config] - fileguard config
+ * @returns {Function} async (request: Request) => Response
+ */
+export function createNextHandler(config = {}) {
+  const fieldName = config.fieldName ?? 'file'
+
+  return async function handler(request) {
+    try {
+      let formData
+      try {
+        formData = await request.formData()
+      } catch {
+        return jsonResponse(failResult('STORAGE_ERROR', 'Failed to parse form data'), 400)
+      }
+
+      const fileEntry = formData.get(fieldName)
+      if (!fileEntry || typeof fileEntry === 'string') {
+        return jsonResponse(failResult('STORAGE_ERROR', `No file found in field "${fieldName}"`), 400)
+      }
+
+      const buffer = Buffer.from(await fileEntry.arrayBuffer())
+      const filename = fileEntry.name ?? 'upload'
+      const mimeType = fileEntry.type ?? 'application/octet-stream'
+
+      const validation = await validateFile(
+        { buffer, filename, mimeType, size: buffer.length },
+        config
+      )
+
+      if (!validation.success) {
+        return jsonResponse(validation, 422)
+      }
+
+      const store = await getStorageAdapter(config.storage ?? 'local')
+      const result = await store(
+        {
+          buffer,
+          filename,
+          sanitizedFilename: validation.sanitizedFilename,
+          size: buffer.length,
+          mimeType,
+        },
+        config
+      )
+
+      return jsonResponse(result, result.success ? 200 : 500)
+    } catch (err) {
+      return jsonResponse(failResult('STORAGE_ERROR', err.message ?? 'Internal error'), 500)
+    }
+  }
+}
+
+/**
+ * @param {object} body
+ * @param {number} status
+ * @returns {Response}
+ */
+function jsonResponse(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}

package/src/audit/logger.js

@@ -0,0 +1,32 @@
+import { appendFile, mkdir } from 'fs/promises'
+import path from 'path'
+
+/**
+ * Create an audit logger that appends JSON-newline entries to a log file.
+ * If logging fails, the error is printed but the upload is NOT blocked.
+ *
+ * @param {{ logPath?: string, enabled?: boolean }} [config]
+ * @returns {{ log: (event: object) => Promise<void> }}
+ */
+export function createLogger(config = {}) {
+  const { logPath = './logs/uploads.log', enabled = true } = config
+
+  return {
+    /**
+     * Append an audit event to the log file.
+     * @param {object} event - Arbitrary key/value data to record
+     */
+    async log(event) {
+      if (!enabled) return
+
+      const entry = JSON.stringify({ timestamp: new Date().toISOString(), ...event }) + '\n'
+
+      try {
+        await mkdir(path.dirname(path.resolve(logPath)), { recursive: true })
+        await appendFile(logPath, entry, 'utf8')
+      } catch (err) {
+        console.error('[fileguard audit] Failed to write log entry:', err.message)
+      }
+    },
+  }
+}

package/src/core/rateLimiter.js

@@ -0,0 +1,55 @@
+import { failResult } from '../errors/UploadError.js'
+
+/**
+ * Create a per-key in-memory rate limiter.
+ * Expired windows are cleaned up automatically on each check.
+ *
+ * @param {{ maxUploads?: number, windowMs?: number }} [config]
+ * @returns {{ check: (key: string) => object, reset: (key: string) => void }}
+ */
+export function createRateLimiter(config = {}) {
+  const { maxUploads = 10, windowMs = 60_000 } = config
+  const store = new Map()
+
+  function cleanup(now) {
+    for (const [key, entry] of store) {
+      if (now >= entry.resetAt) store.delete(key)
+    }
+  }
+
+  return {
+    /**
+     * Check and increment the counter for a given key.
+     * @param {string} key - User ID or IP address
+     * @returns {{ success: true } | { success: false, error: string, message: string }}
+     */
+    check(key) {
+      const now = Date.now()
+      cleanup(now)
+
+      const entry = store.get(key)
+      if (!entry || now >= entry.resetAt) {
+        if (maxUploads <= 0) {
+          return failResult('RATE_LIMIT_EXCEEDED', 'Upload rate limit exceeded. Try again later.')
+        }
+        store.set(key, { count: 1, resetAt: now + windowMs })
+        return { success: true }
+      }
+
+      if (entry.count >= maxUploads) {
+        return failResult('RATE_LIMIT_EXCEEDED', `Upload rate limit exceeded. Try again later.`)
+      }
+
+      entry.count++
+      return { success: true }
+    },
+
+    /**
+     * Remove the counter for a key (useful in tests).
+     * @param {string} key
+     */
+    reset(key) {
+      store.delete(key)
+    },
+  }
+}

package/src/core/sanitizer.js

@@ -0,0 +1,62 @@
+import path from 'path'
+import { v4 as uuidv4 } from 'uuid'
+
+const MAX_LENGTH = 255
+
+// Windows reserved device names — treated as unsafe regardless of extension.
+const RESERVED = new Set([
+  'CON', 'PRN', 'AUX', 'NUL',
+  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+])
+
+/**
+ * Return true when the filename contains characters or patterns that indicate
+ * path traversal, null bytes, or otherwise unsafe input.
+ * @param {string} filename
+ * @returns {boolean}
+ */
+function isUnsafe(filename) {
+  return (
+    filename.includes('..') ||
+    filename.includes('/') ||
+    filename.includes('\\') ||
+    filename.includes('\0') ||
+    /[\x00-\x1f\x7f]/.test(filename)
+  )
+}
+
+/**
+ * Sanitize a filename for safe storage.
+ *
+ * - Path traversal, null bytes, and control characters → replaced with UUID-based name.
+ * - Windows reserved names → replaced with UUID-based name.
+ * - Remaining special characters stripped from the stem.
+ * - Result truncated to 255 characters.
+ * - Original extension is always preserved (lowercased).
+ *
+ * Never rejects — always returns a safe filename.
+ *
+ * @param {string} filename - Original filename from the upload
+ * @returns {{ sanitizedFilename: string, wasUnsafe: boolean }}
+ */
+export function sanitizeFilename(filename) {
+  const ext = path.extname(filename).toLowerCase()
+  const stem = path.basename(filename, ext)
+
+  const unsafe = isUnsafe(filename) || RESERVED.has(stem.toUpperCase())
+  if (unsafe) {
+    return { sanitizedFilename: `${uuidv4()}${ext}`, wasUnsafe: true }
+  }
+
+  // Strip remaining problematic characters from the stem only.
+  const cleanStem = stem
+    .replace(/[^\w\-. ]/g, '') // keep word chars, hyphens, dots, spaces
+    .replace(/\s+/g, '_')       // spaces → underscores
+    .replace(/^\.+/, '')        // no leading dots
+
+  const safeName = cleanStem ? `${cleanStem}${ext}` : `${uuidv4()}${ext}`
+  const truncated = safeName.slice(0, MAX_LENGTH)
+
+  return { sanitizedFilename: truncated, wasUnsafe: false }
+}

package/src/core/validator.js

@@ -0,0 +1,163 @@
+import path from 'path'
+import { failResult } from '../errors/UploadError.js'
+import { validateMagicBytes } from '../scanners/magicBytes.js'
+import { checkZipBomb } from '../scanners/zipBomb.js'
+import { checkPolyglot } from '../scanners/polyglot.js'
+import { sanitizeFilename } from './sanitizer.js'
+import { scanWithClamAV } from '../scanners/clamav.js'
+import { scanWithVirusTotal } from '../scanners/virustotal.js'
+
+// MIME types that should trigger ZIP bomb detection.
+const ARCHIVE_MIME_TYPES = new Set([
+  'application/zip',
+  'application/x-zip-compressed',
+  'application/x-zip',
+  'application/java-archive',
+])
+
+/**
+ * Default configuration values.
+ */
+export const defaultConfig = {
+  maxFileSize: 10 * 1024 * 1024,
+  allowedExtensions: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'pdf', 'doc', 'docx', 'xls', 'xlsx'],
+  allowedMimeTypes: [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+    'application/pdf',
+  ],
+  storage: 'local',
+  localPath: './uploads',
+  scan: {
+    magicBytes: true,
+    zipBomb: true,
+    polyglot: true,
+    clamav: false,
+    virustotal: false,
+  },
+  rateLimit: {
+    enabled: false,
+    maxUploads: 10,
+    windowMs: 60 * 1000,
+  },
+  audit: {
+    enabled: false,
+    logPath: './logs/uploads.log',
+  },
+  sanitizeFilename: true,
+}
+
+/**
+ * Merge user config over defaults (shallow for top-level, deep for nested objects).
+ * @param {object} userConfig
+ * @returns {object}
+ */
+export function mergeConfig(userConfig = {}) {
+  return {
+    ...defaultConfig,
+    ...userConfig,
+    scan: { ...defaultConfig.scan, ...(userConfig.scan ?? {}) },
+    rateLimit: { ...defaultConfig.rateLimit, ...(userConfig.rateLimit ?? {}) },
+    audit: { ...defaultConfig.audit, ...(userConfig.audit ?? {}) },
+  }
+}
+
+/**
+ * Step 1: Validate file size.
+ * @param {number} size - File size in bytes
+ * @param {number} maxFileSize - Max allowed size in bytes
+ */
+export function checkFileSize(size, maxFileSize) {
+  if (size > maxFileSize) {
+    return failResult(
+      'FILE_TOO_LARGE',
+      `File size ${size} bytes exceeds the limit of ${maxFileSize} bytes`
+    )
+  }
+  return { success: true }
+}
+
+/**
+ * Step 2: Validate file extension against the allowlist.
+ * @param {string} filename
+ * @param {string[]} allowedExtensions
+ */
+export function checkExtension(filename, allowedExtensions) {
+  const ext = path.extname(filename).toLowerCase().replace(/^\./, '')
+  if (!ext) {
+    return failResult('INVALID_EXTENSION', 'File has no extension')
+  }
+  if (!allowedExtensions.map((e) => e.toLowerCase()).includes(ext)) {
+    return failResult('INVALID_EXTENSION', `Extension ".${ext}" is not allowed`)
+  }
+  return { success: true }
+}
+
+/**
+ * Step 3: Validate declared MIME type against the allowlist.
+ * @param {string} mimeType
+ * @param {string[]} allowedMimeTypes
+ */
+export function checkMimeType(mimeType, allowedMimeTypes) {
+  if (!allowedMimeTypes.includes(mimeType)) {
+    return failResult('INVALID_MIME_TYPE', `MIME type "${mimeType}" is not allowed`)
+  }
+  return { success: true }
+}
+
+/**
+ * Run the full validation pipeline on a file.
+ * Order: size → extension → MIME → magic bytes → ZIP bomb → polyglot → sanitize filename
+ *
+ * @param {{ buffer: Buffer, filename: string, mimeType: string, size: number }} file
+ * @param {object} [config]
+ * @returns {Promise<{ success: true, sanitizedFilename: string } | { success: false, error: string, message: string }>}
+ */
+export async function validateFile(file, config = {}) {
+  if (!file || !Buffer.isBuffer(file.buffer) || !file.filename || !file.mimeType || typeof file.size !== 'number') {
+    return failResult('STORAGE_ERROR', 'Invalid file input: buffer, filename, mimeType, and size are required')
+  }
+
+  const cfg = mergeConfig(config)
+  const { buffer, filename, mimeType, size } = file
+
+  const sizeCheck = checkFileSize(size, cfg.maxFileSize)
+  if (!sizeCheck.success) return sizeCheck
+
+  const extCheck = checkExtension(filename, cfg.allowedExtensions)
+  if (!extCheck.success) return extCheck
+
+  const mimeCheck = checkMimeType(mimeType, cfg.allowedMimeTypes)
+  if (!mimeCheck.success) return mimeCheck
+
+  const magicCheck = await validateMagicBytes(buffer, mimeType, cfg.allowedMimeTypes)
+  if (!magicCheck.success) return magicCheck
+
+  if (cfg.scan.zipBomb && ARCHIVE_MIME_TYPES.has(magicCheck.detectedMime)) {
+    const bombCheck = checkZipBomb(buffer)
+    if (!bombCheck.success) return bombCheck
+  }
+
+  if (cfg.scan.polyglot) {
+    const polyglotCheck = checkPolyglot(buffer)
+    if (!polyglotCheck.success) return polyglotCheck
+  }
+
+  const { sanitizedFilename } = cfg.sanitizeFilename
+    ? sanitizeFilename(filename)
+    : { sanitizedFilename: filename }
+
+  if (cfg.scan.clamav) {
+    const clamResult = await scanWithClamAV(buffer, cfg.clamavOptions)
+    if (!clamResult.success) return clamResult
+  }
+
+  if (cfg.scan.virustotal) {
+    const vtResult = await scanWithVirusTotal(buffer, cfg.virustotalOptions)
+    if (!vtResult.success) return vtResult
+  }
+
+  return { success: true, sanitizedFilename }
+}

package/src/errors/UploadError.js

@@ -0,0 +1,43 @@
+export const ERROR_CODES = {
+  FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+  INVALID_EXTENSION: 'INVALID_EXTENSION',
+  INVALID_MIME_TYPE: 'INVALID_MIME_TYPE',
+  INVALID_MAGIC_BYTES: 'INVALID_MAGIC_BYTES',
+  ZIP_BOMB_DETECTED: 'ZIP_BOMB_DETECTED',
+  POLYGLOT_DETECTED: 'POLYGLOT_DETECTED',
+  UNSAFE_FILENAME: 'UNSAFE_FILENAME',
+  VIRUS_DETECTED: 'VIRUS_DETECTED',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+}
+
+export class UploadError extends Error {
+  /**
+   * @param {string} code - One of ERROR_CODES
+   * @param {string} message - Human-readable description
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = 'UploadError'
+    this.code = code
+  }
+}
+
+/**
+ * Build a standard failure result object.
+ * @param {string} code
+ * @param {string} message
+ * @returns {{ success: false, error: string, message: string }}
+ */
+export function failResult(code, message) {
+  return { success: false, error: code, message }
+}
+
+/**
+ * Build a standard success result object.
+ * @param {{ url: string, filename: string, size: number, mimeType: string, storage: string }} data
+ * @returns {{ success: true, data: object }}
+ */
+export function successResult(data) {
+  return { success: true, data }
+}

package/src/index.js

@@ -0,0 +1,65 @@
+import { validateFile, mergeConfig } from './core/validator.js'
+import { failResult } from './errors/UploadError.js'
+import { getStorageAdapter } from './storage/index.js'
+import { createRateLimiter } from './core/rateLimiter.js'
+import { createLogger } from './audit/logger.js'
+
+/**
+ * Create a configured fileguard instance.
+ * @param {object} [config] - Optional configuration overrides
+ * @returns {{ process: Function }}
+ */
+export function createGuard(config = {}) {
+  const cfg = mergeConfig(config)
+  const rateLimiter = cfg.rateLimit.enabled ? createRateLimiter(cfg.rateLimit) : null
+  const logger = cfg.audit.enabled ? createLogger(cfg.audit) : null
+
+  return {
+    /**
+     * Validate and store a file upload end-to-end.
+     * @param {{ buffer: Buffer, filename: string, mimeType: string, size: number }} file
+     * @param {{ key?: string }} [meta] - Optional meta (e.g. user IP for rate limiting)
+     * @returns {Promise<{ success: boolean, data?: object, error?: string, message?: string }>}
+     */
+    async process(file, meta = {}) {
+      try {
+        if (rateLimiter) {
+          const rl = rateLimiter.check(meta.key ?? 'anonymous')
+          if (!rl.success) return rl
+        }
+
+        const validation = await validateFile(file, cfg)
+        if (!validation.success) {
+          await logger?.log({ event: 'upload.rejected', error: validation.error, filename: file.filename })
+          return validation
+        }
+
+        const store = await getStorageAdapter(cfg.storage)
+        const result = await store(
+          {
+            buffer: file.buffer,
+            filename: file.filename,
+            sanitizedFilename: validation.sanitizedFilename,
+            size: file.size,
+            mimeType: file.mimeType,
+          },
+          cfg
+        )
+
+        await logger?.log({
+          event: result.success ? 'upload.success' : 'upload.error',
+          filename: file.filename,
+          size: file.size,
+          storage: cfg.storage,
+          ...(result.success ? { url: result.data.url } : { error: result.error }),
+        })
+
+        return result
+      } catch (err) {
+        return failResult('STORAGE_ERROR', err.message ?? 'An unexpected error occurred')
+      }
+    },
+  }
+}
+
+export { createGuard as fileguard }