@msal95/fileguard 0.1.1

package/src/scanners/virustotal.js

@@ -0,0 +1,85 @@
+import { failResult } from '../errors/UploadError.js'
+
+const VT_BASE = 'https://www.virustotal.com/api/v3'
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Scan a buffer with the VirusTotal API v3.
+ *
+ * Behaviour when scanning is unavailable:
+ *   - apiKey missing or empty  → warn + skip (upload proceeds)
+ *   - upload or poll failure   → warn + skip (upload proceeds)
+ *   - analysis never completes → warn + skip (upload proceeds)
+ *
+ * @param {Buffer} buffer
+ * @param {{ apiKey?: string, pollIntervalMs?: number, maxPolls?: number }} [config]
+ * @returns {Promise<{ success: true, skipped?: true } | { success: false, error: string, message: string }>}
+ */
+export async function scanWithVirusTotal(buffer, config = {}) {
+  const { apiKey, pollIntervalMs = 5_000, maxPolls = 3 } = config
+
+  if (!apiKey) {
+    console.warn('[fileguard] VirusTotal scan skipped: no apiKey configured.')
+    return { success: true, skipped: true }
+  }
+
+  const headers = { 'x-apikey': apiKey }
+
+  // ── Upload ──────────────────────────────────────────────────────────────────
+  let analysisId
+  try {
+    const formData = new FormData()
+    formData.append('file', new Blob([buffer]), 'upload')
+
+    const uploadRes = await fetch(`${VT_BASE}/files`, {
+      method: 'POST',
+      headers,
+      body: formData,
+    })
+
+    if (!uploadRes.ok) {
+      const text = await uploadRes.text().catch(() => uploadRes.status)
+      console.warn(`[fileguard] VirusTotal upload failed (${uploadRes.status}): ${text}. Skipping scan.`)
+      return { success: true, skipped: true }
+    }
+
+    const { data } = await uploadRes.json()
+    analysisId = data.id
+  } catch (err) {
+    console.warn(`[fileguard] VirusTotal upload error: ${err.message}. Skipping scan.`)
+    return { success: true, skipped: true }
+  }
+
+  // ── Poll for results ────────────────────────────────────────────────────────
+  for (let i = 0; i < maxPolls; i++) {
+    try {
+      const res = await fetch(`${VT_BASE}/analyses/${analysisId}`, { headers })
+
+      if (res.ok) {
+        const { data } = await res.json()
+        const status = data?.attributes?.status
+
+        if (status === 'completed') {
+          const { malicious = 0, suspicious = 0 } = data.attributes.stats ?? {}
+          if (malicious > 0 || suspicious > 0) {
+            return failResult(
+              'VIRUS_DETECTED',
+              `VirusTotal flagged this file (malicious: ${malicious}, suspicious: ${suspicious})`
+            )
+          }
+          return { success: true }
+        }
+      }
+    } catch (err) {
+      console.warn(`[fileguard] VirusTotal poll error: ${err.message}. Skipping scan.`)
+      return { success: true, skipped: true }
+    }
+
+    // Wait before next poll (skip sleep on the final iteration)
+    if (i < maxPolls - 1) await sleep(pollIntervalMs)
+  }
+
+  console.warn('[fileguard] VirusTotal analysis did not complete in time. Skipping scan.')
+  return { success: true, skipped: true }
+}

package/src/scanners/zipBomb.js

@@ -0,0 +1,85 @@
+import { failResult } from '../errors/UploadError.js'
+
+const EOCD_SIG = 0x06054b50
+const CD_SIG = 0x02014b50
+
+/**
+ * Locate the End of Central Directory record by scanning backwards.
+ * @param {Buffer} buf
+ * @returns {number} byte offset, or -1 if not found
+ */
+function findEOCD(buf) {
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) return i
+  }
+  return -1
+}
+
+/**
+ * Walk the central directory and sum compressed/uncompressed sizes.
+ * @param {Buffer} buf
+ * @param {number} cdOffset
+ * @param {number} cdSize
+ * @returns {{ totalCompressed: number, totalUncompressed: number, fileCount: number }}
+ */
+function parseCentralDirectory(buf, cdOffset, cdSize) {
+  let totalCompressed = 0
+  let totalUncompressed = 0
+  let fileCount = 0
+  let offset = cdOffset
+
+  while (offset < cdOffset + cdSize && offset + 46 <= buf.length) {
+    if (buf.readUInt32LE(offset) !== CD_SIG) break
+
+    const compressedSize = buf.readUInt32LE(offset + 20)
+    const uncompressedSize = buf.readUInt32LE(offset + 24)
+    const filenameLen = buf.readUInt16LE(offset + 28)
+    const extraLen = buf.readUInt16LE(offset + 30)
+    const commentLen = buf.readUInt16LE(offset + 32)
+
+    totalCompressed += compressedSize
+    totalUncompressed += uncompressedSize
+    fileCount++
+
+    offset += 46 + filenameLen + extraLen + commentLen
+  }
+
+  return { totalCompressed, totalUncompressed, fileCount }
+}
+
+/**
+ * Check a ZIP buffer for zip bomb patterns.
+ * Rejects if compression ratio > ratioThreshold or file count > maxFiles.
+ *
+ * @param {Buffer} buffer
+ * @param {{ ratioThreshold?: number, maxFiles?: number }} [options]
+ * @returns {{ success: true } | { success: false, error: string, message: string }}
+ */
+export function checkZipBomb(buffer, options = {}) {
+  const { ratioThreshold = 100, maxFiles = 1000 } = options
+
+  const eocdOffset = findEOCD(buffer)
+  if (eocdOffset === -1) {
+    return failResult('ZIP_BOMB_DETECTED', 'Invalid ZIP structure: no end-of-central-directory record found')
+  }
+
+  const cdSize = buffer.readUInt32LE(eocdOffset + 12)
+  const cdOffset = buffer.readUInt32LE(eocdOffset + 16)
+
+  if (cdOffset + cdSize > buffer.length) {
+    return failResult('ZIP_BOMB_DETECTED', 'Invalid ZIP structure: central directory out of bounds')
+  }
+
+  const { totalCompressed, totalUncompressed, fileCount } = parseCentralDirectory(buffer, cdOffset, cdSize)
+
+  if (fileCount > maxFiles) {
+    return failResult('ZIP_BOMB_DETECTED', `ZIP contains ${fileCount} files, exceeding the limit of ${maxFiles}`)
+  }
+
+  if (totalCompressed > 0 && totalUncompressed / totalCompressed > ratioThreshold) {
+    const ratio = (totalUncompressed / totalCompressed).toFixed(1)
+    return failResult('ZIP_BOMB_DETECTED', `Compression ratio ${ratio}x exceeds the limit of ${ratioThreshold}x`)
+  }
+
+  return { success: true }
+}

package/src/storage/cloudinary.js

@@ -0,0 +1,56 @@
+import { failResult, successResult } from '../errors/UploadError.js'
+
+/**
+ * Upload a file to Cloudinary.
+ * Requires the optional peer dependency: cloudinary
+ *
+ * @param {{ buffer: Buffer, sanitizedFilename: string, size: number, mimeType: string }} file
+ * @param {{ cloudName: string, apiKey: string, apiSecret: string, resourceType?: string, folder?: string }} config
+ * @returns {Promise<{ success: true, data: object } | { success: false, error: string, message: string }>}
+ */
+export async function cloudinaryStore(file, config = {}) {
+  let cloudinary
+  try {
+    const mod = await import('cloudinary')
+    cloudinary = mod.v2
+  } catch {
+    return failResult(
+      'STORAGE_ERROR',
+      'Cloudinary storage requires the cloudinary package. Install it with: npm install cloudinary'
+    )
+  }
+
+  const { cloudName, apiKey, apiSecret, resourceType = 'auto', folder } = config
+  if (!cloudName || !apiKey || !apiSecret) {
+    return failResult('STORAGE_ERROR', 'Cloudinary storage requires cloudName, apiKey, and apiSecret')
+  }
+
+  cloudinary.config({ cloud_name: cloudName, api_key: apiKey, api_secret: apiSecret })
+
+  try {
+    const uploadOptions = {
+      resource_type: resourceType,
+      use_filename: true,
+      unique_filename: false,
+    }
+    if (folder) uploadOptions.folder = folder
+
+    const result = await new Promise((resolve, reject) => {
+      const stream = cloudinary.uploader.upload_stream(uploadOptions, (err, res) => {
+        if (err) reject(err)
+        else resolve(res)
+      })
+      stream.end(file.buffer)
+    })
+
+    return successResult({
+      url: result.secure_url,
+      filename: file.sanitizedFilename,
+      size: file.size,
+      mimeType: file.mimeType,
+      storage: 'cloudinary',
+    })
+  } catch (err) {
+    return failResult('STORAGE_ERROR', `Cloudinary upload failed: ${err.message}`)
+  }
+}

package/src/storage/index.js

@@ -0,0 +1,27 @@
+export { localStore } from './local.js'
+export { s3Store } from './s3.js'
+export { cloudinaryStore } from './cloudinary.js'
+
+/**
+ * Return the storage adapter function for the given storage type string.
+ * @param {'local'|'s3'|'cloudinary'} type
+ * @returns {Function}
+ */
+export async function getStorageAdapter(type) {
+  switch (type) {
+    case 'local': {
+      const { localStore } = await import('./local.js')
+      return localStore
+    }
+    case 's3': {
+      const { s3Store } = await import('./s3.js')
+      return s3Store
+    }
+    case 'cloudinary': {
+      const { cloudinaryStore } = await import('./cloudinary.js')
+      return cloudinaryStore
+    }
+    default:
+      throw new Error(`Unknown storage adapter: "${type}". Valid values: local, s3, cloudinary`)
+  }
+}

package/src/storage/local.js

@@ -0,0 +1,39 @@
+import { writeFile, mkdir } from 'fs/promises'
+import path from 'path'
+import { v4 as uuidv4 } from 'uuid'
+import { failResult, successResult } from '../errors/UploadError.js'
+
+/**
+ * Store a file to the local filesystem.
+ *
+ * @param {{ buffer: Buffer, sanitizedFilename?: string, filename: string, size: number, mimeType: string }} file
+ * @param {{ localPath?: string }} [config]
+ * @returns {Promise<{ success: true, data: object } | { success: false, error: string, message: string }>}
+ */
+export async function localStore(file, config = {}) {
+  const { localPath = './uploads' } = config
+  const ext = path.extname(file.filename).toLowerCase()
+  const filename = file.sanitizedFilename ?? `${uuidv4()}${ext}`
+  const destDir = path.resolve(localPath)
+  const destPath = path.join(destDir, filename)
+
+  // Guard against path traversal: sanitizedFilename must stay under destDir
+  if (!destPath.startsWith(destDir + path.sep) && destPath !== destDir) {
+    return failResult('STORAGE_ERROR', 'Path traversal detected in filename')
+  }
+
+  try {
+    await mkdir(destDir, { recursive: true })
+    await writeFile(destPath, file.buffer)
+
+    return successResult({
+      url: destPath,
+      filename,
+      size: file.size,
+      mimeType: file.mimeType,
+      storage: 'local',
+    })
+  } catch (err) {
+    return failResult('STORAGE_ERROR', `Local storage failed: ${err.message}`)
+  }
+}

package/src/storage/s3.js

@@ -0,0 +1,62 @@
+import { failResult, successResult } from '../errors/UploadError.js'
+
+/**
+ * Store a file to AWS S3 (or an S3-compatible service).
+ * Requires the optional peer dependency: @aws-sdk/client-s3
+ *
+ * @param {{ buffer: Buffer, sanitizedFilename: string, size: number, mimeType: string }} file
+ * @param {{ bucket: string, region?: string, prefix?: string, endpoint?: string }} config
+ * @returns {Promise<{ success: true, data: object } | { success: false, error: string, message: string }>}
+ */
+export async function s3Store(file, config = {}) {
+  let S3Client, PutObjectCommand
+  try {
+    const sdk = await import('@aws-sdk/client-s3')
+    S3Client = sdk.S3Client
+    PutObjectCommand = sdk.PutObjectCommand
+  } catch {
+    return failResult(
+      'STORAGE_ERROR',
+      'S3 storage requires @aws-sdk/client-s3. Install it with: npm install @aws-sdk/client-s3'
+    )
+  }
+
+  const { bucket, region = 'us-east-1', prefix = '', endpoint } = config
+  if (!bucket) {
+    return failResult('STORAGE_ERROR', 'S3 storage requires a bucket name in config')
+  }
+
+  const filename = file.sanitizedFilename
+  const key = prefix ? `${prefix}/${filename}` : filename
+
+  const clientOptions = { region }
+  if (endpoint) clientOptions.endpoint = endpoint
+
+  const client = new S3Client(clientOptions)
+
+  try {
+    await client.send(
+      new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: file.buffer,
+        ContentType: file.mimeType,
+        ContentLength: file.size,
+      })
+    )
+
+    const baseUrl = endpoint
+      ? `${endpoint.replace(/\/$/, '')}/${bucket}/${key}`
+      : `https://${bucket}.s3.${region}.amazonaws.com/${key}`
+
+    return successResult({
+      url: baseUrl,
+      filename,
+      size: file.size,
+      mimeType: file.mimeType,
+      storage: 's3',
+    })
+  } catch (err) {
+    return failResult('STORAGE_ERROR', `S3 upload failed: ${err.message}`)
+  }
+}