@msal95/fileguard 0.1.1

package/src/react/DropZone.jsx

@@ -0,0 +1,146 @@
+import { useState, useRef, useCallback } from 'react'
+
+// ── Client-side validation ────────────────────────────────────────────────────
+
+function clientValidate(file, accept, maxSize) {
+  const ext = file.name.split('.').pop().toLowerCase()
+  if (accept.length > 0 && !accept.map((e) => e.toLowerCase()).includes(ext)) {
+    return { valid: false, error: 'INVALID_EXTENSION', message: `File type .${ext} is not allowed` }
+  }
+  if (maxSize != null && file.size > maxSize) {
+    return { valid: false, error: 'FILE_TOO_LARGE', message: `File size exceeds the ${maxSize}-byte limit` }
+  }
+  return { valid: true }
+}
+
+// ── Default styles (overridable via CSS variables) ────────────────────────────
+
+const S = {
+  zone: {
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 'var(--fg-padding, 40px 24px)',
+    border: '2px dashed var(--fg-border, #d1d5db)',
+    borderRadius: 'var(--fg-radius, 10px)',
+    backgroundColor: 'var(--fg-bg, #fafafa)',
+    color: 'var(--fg-text, #6b7280)',
+    cursor: 'pointer',
+    transition: 'border-color 0.15s, background-color 0.15s',
+    userSelect: 'none',
+    outline: 'none',
+  },
+  zoneActive: {
+    borderColor: 'var(--fg-primary, #2563eb)',
+    backgroundColor: 'var(--fg-bg-active, #eff6ff)',
+    color: 'var(--fg-text-active, #1d4ed8)',
+  },
+  hint: {
+    margin: 0,
+    fontSize: 'var(--fg-font-size, 14px)',
+    lineHeight: 1.5,
+    pointerEvents: 'none',
+  },
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Drag-and-drop file upload zone with optional client-side validation.
+ *
+ * This is a client-side convenience layer only — always validate again on
+ * the server using fileguard's validation pipeline.
+ *
+ * @param {object}   props
+ * @param {Function} [props.onUpload]   Called with the File when it passes validation.
+ * @param {Function} [props.onError]    Called with { error, message, file } on validation failure.
+ * @param {string[]} [props.accept]     Allowed file extensions (e.g. ['png', 'jpg']).
+ * @param {number}   [props.maxSize]    Max file size in bytes.
+ * @param {boolean}  [props.headless]   If true, renders no inline styles.
+ * @param {boolean}  [props.multiple]   If true, allows picking multiple files (all validated).
+ * @param {*}        [props.children]   Override the default inner content.
+ * @param {string}   [props.className]
+ * @param {object}   [props.style]      Additional style overrides.
+ */
+export function DropZone({
+  onUpload,
+  onError,
+  accept = [],
+  maxSize,
+  headless = false,
+  multiple = false,
+  children,
+  className,
+  style,
+  ...rest
+}) {
+  const [isDragging, setIsDragging] = useState(false)
+  const inputRef = useRef(null)
+
+  const handleFile = useCallback(
+    (file) => {
+      const result = clientValidate(file, accept, maxSize)
+      if (!result.valid) {
+        onError?.({ error: result.error, message: result.message, file })
+        return
+      }
+      onUpload?.(file)
+    },
+    [accept, maxSize, onUpload, onError]
+  )
+
+  const handleFiles = useCallback(
+    (files) => Array.from(files).forEach(handleFile),
+    [handleFile]
+  )
+
+  const onDragOver = (e) => { e.preventDefault(); setIsDragging(true) }
+  const onDragLeave = (e) => { e.preventDefault(); setIsDragging(false) }
+  const onDrop = (e) => {
+    e.preventDefault()
+    setIsDragging(false)
+    if (e.dataTransfer.files.length) handleFiles(e.dataTransfer.files)
+  }
+  const onClick = () => inputRef.current?.click()
+  const onKeyDown = (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onClick() } }
+  const onChange = (e) => {
+    if (e.target.files?.length) handleFiles(e.target.files)
+    e.target.value = ''
+  }
+
+  const computedStyle = headless
+    ? style
+    : { ...S.zone, ...(isDragging ? S.zoneActive : {}), ...style }
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-label="File upload drop zone. Press Enter or Space to open the file picker."
+      className={className}
+      style={computedStyle}
+      onDragOver={onDragOver}
+      onDragLeave={onDragLeave}
+      onDrop={onDrop}
+      onClick={onClick}
+      onKeyDown={onKeyDown}
+      {...rest}
+    >
+      <input
+        ref={inputRef}
+        type="file"
+        style={{ display: 'none' }}
+        accept={accept.length ? accept.map((e) => `.${e}`).join(',') : undefined}
+        multiple={multiple}
+        onChange={onChange}
+        tabIndex={-1}
+      />
+      {children ?? (
+        <p style={headless ? undefined : S.hint}>
+          Drop a file here or <strong>click to browse</strong>
+        </p>
+      )}
+    </div>
+  )
+}

package/src/react/FilePreview.jsx

@@ -0,0 +1,152 @@
+import { useState, useEffect } from 'react'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const IMAGE_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'])
+
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${bytes} B`
+}
+
+// ── Default styles (overridable via CSS variables) ────────────────────────────
+
+const S = {
+  container: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '12px',
+    padding: 'var(--fg-padding, 12px)',
+    border: '1px solid var(--fg-border, #e5e7eb)',
+    borderRadius: 'var(--fg-radius, 8px)',
+    backgroundColor: 'var(--fg-bg, #ffffff)',
+  },
+  thumbnail: {
+    width: '48px',
+    height: '48px',
+    objectFit: 'cover',
+    borderRadius: '4px',
+    flexShrink: 0,
+    display: 'block',
+  },
+  iconBox: {
+    width: '48px',
+    height: '48px',
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: 'var(--fg-bg-active, #eff6ff)',
+    borderRadius: '4px',
+    fontSize: '22px',
+  },
+  info: {
+    flex: 1,
+    minWidth: 0,
+  },
+  name: {
+    fontSize: 'var(--fg-font-size, 14px)',
+    fontWeight: '500',
+    color: 'var(--fg-text, #111827)',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    margin: 0,
+  },
+  meta: {
+    fontSize: '12px',
+    color: 'var(--fg-text-muted, #9ca3af)',
+    margin: '2px 0 0',
+  },
+  removeBtn: {
+    flexShrink: 0,
+    background: 'none',
+    border: 'none',
+    cursor: 'pointer',
+    color: 'var(--fg-text-muted, #9ca3af)',
+    fontSize: '20px',
+    lineHeight: 1,
+    padding: '4px',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: '4px',
+    transition: 'color 0.15s',
+  },
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Preview a selected file before it is uploaded.
+ * Displays a thumbnail for images and a generic icon for other file types.
+ *
+ * @param {object}   props
+ * @param {File}     props.file        The browser File object to preview.
+ * @param {Function} [props.onRemove]  Called when the user clicks the remove button.
+ * @param {boolean}  [props.headless]  If true, renders only semantic markup with no inline styles.
+ * @param {string}   [props.className]
+ * @param {object}   [props.style]     Additional style overrides.
+ */
+export function FilePreview({ file, onRemove, headless = false, className, style, ...rest }) {
+  const [previewUrl, setPreviewUrl] = useState(null)
+  const isImage = file != null && IMAGE_TYPES.has(file.type)
+
+  useEffect(() => {
+    if (!isImage || file == null) {
+      setPreviewUrl(null)
+      return
+    }
+    const url = URL.createObjectURL(file)
+    setPreviewUrl(url)
+    return () => URL.revokeObjectURL(url)
+  }, [file, isImage])
+
+  if (file == null) return null
+
+  if (headless) {
+    return (
+      <div className={className} style={style} {...rest}>
+        {isImage && previewUrl && <img src={previewUrl} alt={file.name} />}
+        <span>{file.name}</span>
+        <span>{formatBytes(file.size)}</span>
+        <span>{file.type || 'unknown'}</span>
+        {onRemove && (
+          <button type="button" onClick={onRemove} aria-label={`Remove ${file.name}`}>
+            Remove
+          </button>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div className={className} style={{ ...S.container, ...style }} {...rest}>
+      {isImage && previewUrl ? (
+        <img src={previewUrl} alt="" style={S.thumbnail} aria-hidden="true" />
+      ) : (
+        <div style={S.iconBox} aria-hidden="true">
+          📄
+        </div>
+      )}
+
+      <div style={S.info}>
+        <p style={S.name} title={file.name}>{file.name}</p>
+        <p style={S.meta}>{formatBytes(file.size)} &middot; {file.type || 'unknown type'}</p>
+      </div>
+
+      {onRemove && (
+        <button
+          type="button"
+          onClick={onRemove}
+          style={S.removeBtn}
+          aria-label={`Remove ${file.name}`}
+          title="Remove file"
+        >
+          &times;
+        </button>
+      )}
+    </div>
+  )
+}

package/src/react/ProgressBar.jsx

@@ -0,0 +1,82 @@
+// ── Default styles (overridable via CSS variables) ────────────────────────────
+
+const S = {
+  wrapper: {
+    width: '100%',
+  },
+  labelRow: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'baseline',
+    marginBottom: '6px',
+    fontSize: 'var(--fg-font-size, 13px)',
+    color: 'var(--fg-text, #6b7280)',
+  },
+  track: {
+    width: '100%',
+    height: 'var(--fg-bar-height, 8px)',
+    backgroundColor: 'var(--fg-bar-bg, #e5e7eb)',
+    borderRadius: 'var(--fg-radius, 999px)',
+    overflow: 'hidden',
+  },
+  fill: {
+    height: '100%',
+    backgroundColor: 'var(--fg-primary, #2563eb)',
+    borderRadius: 'inherit',
+    transition: 'width 0.25s ease',
+  },
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Upload progress indicator.
+ *
+ * @param {object}  props
+ * @param {number}  [props.progress]  Value from 0–100. Clamped automatically.
+ * @param {string}  [props.label]     Optional label shown above the bar.
+ * @param {boolean} [props.headless]  If true, renders only semantic markup with no inline styles.
+ * @param {string}  [props.className]
+ * @param {object}  [props.style]     Additional style overrides for the outermost element.
+ */
+export function ProgressBar({ progress = 0, label, headless = false, className, style, ...rest }) {
+  const clamped = Math.max(0, Math.min(100, progress))
+
+  if (headless) {
+    return (
+      <div
+        role="progressbar"
+        aria-valuenow={clamped}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label={label ?? 'Upload progress'}
+        className={className}
+        style={style}
+        {...rest}
+      >
+        <div style={{ width: `${clamped}%` }} />
+      </div>
+    )
+  }
+
+  return (
+    <div className={className} style={{ ...S.wrapper, ...style }} {...rest}>
+      {label != null && (
+        <div style={S.labelRow} aria-hidden="true">
+          <span>{label}</span>
+          <span>{clamped}%</span>
+        </div>
+      )}
+      <div
+        role="progressbar"
+        aria-valuenow={clamped}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label={label ?? 'Upload progress'}
+        style={S.track}
+      >
+        <div style={{ ...S.fill, width: `${clamped}%` }} />
+      </div>
+    </div>
+  )
+}

package/src/react/UploadButton.jsx

@@ -0,0 +1,123 @@
+import { useRef, useCallback } from 'react'
+
+// ── Client-side validation ────────────────────────────────────────────────────
+
+function clientValidate(file, accept, maxSize) {
+  const ext = file.name.split('.').pop().toLowerCase()
+  if (accept.length > 0 && !accept.map((e) => e.toLowerCase()).includes(ext)) {
+    return { valid: false, error: 'INVALID_EXTENSION', message: `File type .${ext} is not allowed` }
+  }
+  if (maxSize != null && file.size > maxSize) {
+    return { valid: false, error: 'FILE_TOO_LARGE', message: `File size exceeds the ${maxSize}-byte limit` }
+  }
+  return { valid: true }
+}
+
+// ── Default styles (overridable via CSS variables) ────────────────────────────
+
+const S = {
+  button: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '6px',
+    padding: 'var(--fg-btn-padding, 8px 18px)',
+    border: 'none',
+    borderRadius: 'var(--fg-radius, 6px)',
+    backgroundColor: 'var(--fg-primary, #2563eb)',
+    color: 'var(--fg-btn-text, #ffffff)',
+    fontSize: 'var(--fg-font-size, 14px)',
+    fontWeight: '500',
+    lineHeight: 1.5,
+    cursor: 'pointer',
+    transition: 'background-color 0.15s, opacity 0.15s',
+  },
+  disabled: {
+    opacity: 0.5,
+    cursor: 'not-allowed',
+  },
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Simple file-picker button with optional client-side validation.
+ *
+ * This is a client-side convenience layer only — always validate again on
+ * the server using fileguard's validation pipeline.
+ *
+ * @param {object}   props
+ * @param {Function} [props.onUpload]   Called with each File that passes validation.
+ * @param {Function} [props.onError]    Called with { error, message, file } on validation failure.
+ * @param {string[]} [props.accept]     Allowed file extensions (e.g. ['pdf', 'docx']).
+ * @param {number}   [props.maxSize]    Max file size in bytes.
+ * @param {boolean}  [props.multiple]   If true, allows picking multiple files.
+ * @param {boolean}  [props.headless]   If true, renders no inline styles on the button.
+ * @param {boolean}  [props.disabled]
+ * @param {*}        [props.children]   Button label content.
+ * @param {string}   [props.className]
+ * @param {object}   [props.style]      Additional style overrides.
+ */
+export function UploadButton({
+  onUpload,
+  onError,
+  accept = [],
+  maxSize,
+  multiple = false,
+  headless = false,
+  disabled = false,
+  children = 'Upload File',
+  className,
+  style,
+  ...rest
+}) {
+  const inputRef = useRef(null)
+
+  const handleFiles = useCallback(
+    (files) => {
+      Array.from(files).forEach((file) => {
+        const result = clientValidate(file, accept, maxSize)
+        if (!result.valid) {
+          onError?.({ error: result.error, message: result.message, file })
+          return
+        }
+        onUpload?.(file)
+      })
+    },
+    [accept, maxSize, onUpload, onError]
+  )
+
+  const onClick = () => { if (!disabled) inputRef.current?.click() }
+  const onChange = (e) => {
+    if (e.target.files?.length) handleFiles(e.target.files)
+    e.target.value = ''
+  }
+
+  const computedStyle = headless
+    ? style
+    : { ...S.button, ...(disabled ? S.disabled : {}), ...style }
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        type="file"
+        style={{ display: 'none' }}
+        accept={accept.length ? accept.map((e) => `.${e}`).join(',') : undefined}
+        multiple={multiple}
+        disabled={disabled}
+        onChange={onChange}
+        tabIndex={-1}
+      />
+      <button
+        type="button"
+        className={className}
+        style={computedStyle}
+        disabled={disabled}
+        onClick={onClick}
+        {...rest}
+      >
+        {children}
+      </button>
+    </>
+  )
+}

package/src/react/index.js

@@ -0,0 +1,4 @@
+export { DropZone } from './DropZone.jsx'
+export { UploadButton } from './UploadButton.jsx'
+export { ProgressBar } from './ProgressBar.jsx'
+export { FilePreview } from './FilePreview.jsx'

package/src/scanners/clamav.js

@@ -0,0 +1,50 @@
+import { Readable } from 'stream'
+import { failResult } from '../errors/UploadError.js'
+
+/**
+ * Scan a buffer with ClamAV using the optional `clamscan` peer dependency.
+ *
+ * Behaviour when ClamAV is unavailable:
+ *   - clamscan not installed  → warn + skip (upload proceeds)
+ *   - ClamAV daemon not running → warn + skip (upload proceeds)
+ *
+ * @param {Buffer} buffer
+ * @param {object} [clamavOptions] - options forwarded to NodeClam.init()
+ * @returns {Promise<{ success: true, skipped?: true } | { success: false, error: string, message: string }>}
+ */
+export async function scanWithClamAV(buffer, clamavOptions = {}) {
+  let NodeClam
+  try {
+    const mod = await import('clamscan')
+    NodeClam = mod.default ?? mod
+  } catch {
+    console.warn(
+      '[fileguard] ClamAV scan skipped: clamscan package is not installed. ' +
+        'Install it with: npm install clamscan'
+    )
+    return { success: true, skipped: true }
+  }
+
+  let clam
+  try {
+    clam = await new NodeClam().init(clamavOptions)
+  } catch (err) {
+    console.warn(`[fileguard] ClamAV initialisation failed: ${err.message}. Skipping scan.`)
+    return { success: true, skipped: true }
+  }
+
+  try {
+    const stream = Readable.from(buffer)
+    const { isInfected, viruses } = await clam.scanStream(stream)
+
+    if (isInfected) {
+      const names = Array.isArray(viruses) && viruses.length ? viruses.join(', ') : 'unknown'
+      return failResult('VIRUS_DETECTED', `ClamAV detected malware: ${names}`)
+    }
+
+    return { success: true }
+  } catch (err) {
+    console.warn(`[fileguard] ClamAV scan error: ${err.message}. Skipping scan.`)
+    return { success: true, skipped: true }
+  }
+}

package/src/scanners/magicBytes.js

@@ -0,0 +1,62 @@
+import { fileTypeFromBuffer } from 'file-type'
+import { failResult } from '../errors/UploadError.js'
+
+const READ_BYTES = 8192
+
+/**
+ * Maps allowed MIME types to their expected file-type detected MIME.
+ * Used to cross-check the detected type against what was declared.
+ */
+const MIME_ALIAS = {
+  'image/jpg': 'image/jpeg',
+}
+
+/**
+ * Detect the real file type from the buffer's magic bytes.
+ * Returns the detected { ext, mime } or null if unknown.
+ * @param {Buffer} buffer
+ * @returns {Promise<{ ext: string, mime: string } | null>}
+ */
+export async function detectFileType(buffer) {
+  try {
+    if (!buffer || buffer.length === 0) return null
+    const slice = buffer.subarray(0, READ_BYTES)
+    return (await fileTypeFromBuffer(slice)) ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Validate that the file's magic bytes match an expected MIME type.
+ * @param {Buffer} buffer - Full file buffer
+ * @param {string} declaredMime - MIME type declared by the uploader
+ * @param {string[]} allowedMimeTypes - List of allowed MIME types from config
+ * @returns {Promise<{ success: true, detectedMime: string, detectedExt: string } | { success: false, error: string, message: string }>}
+ */
+export async function validateMagicBytes(buffer, declaredMime, allowedMimeTypes) {
+  const detected = await detectFileType(buffer)
+
+  if (!detected) {
+    return failResult('INVALID_MAGIC_BYTES', 'File type could not be determined from its contents')
+  }
+
+  const normalizedAllowed = allowedMimeTypes.map((m) => MIME_ALIAS[m] ?? m)
+
+  if (!normalizedAllowed.includes(detected.mime)) {
+    return failResult(
+      'INVALID_MAGIC_BYTES',
+      `File content does not match any allowed type (detected: ${detected.mime})`
+    )
+  }
+
+  const normalizedDeclared = MIME_ALIAS[declaredMime] ?? declaredMime
+  if (normalizedDeclared !== detected.mime) {
+    return failResult(
+      'INVALID_MAGIC_BYTES',
+      `Declared MIME type "${declaredMime}" does not match file content (detected: ${detected.mime})`
+    )
+  }
+
+  return { success: true, detectedMime: detected.mime, detectedExt: detected.ext }
+}

package/src/scanners/polyglot.js

@@ -0,0 +1,58 @@
+import { failResult } from '../errors/UploadError.js'
+
+// Hex byte sequences searched from offset 32 onward.
+// Matching any of these in a non-archive file indicates a polyglot.
+const RED_FLAGS = [
+  { hex: '4d5a', label: 'Windows PE/EXE (MZ header)' },
+  { hex: '3c736372697074', label: 'embedded <script> tag' },
+  { hex: '504b0304', label: 'nested ZIP archive' },
+  { hex: '3c3f706870', label: 'embedded PHP code' },
+  { hex: '2321', label: 'shell shebang (#!)' },
+]
+
+// Pre-convert hex patterns to Buffer instances once at module load.
+const FLAG_BUFS = RED_FLAGS.map(({ hex, label }) => ({
+  buf: Buffer.from(hex, 'hex'),
+  label,
+}))
+
+const SCAN_SKIP = 32
+
+/**
+ * Search for a needle Buffer inside a haystack Buffer starting at `fromOffset`.
+ * @param {Buffer} haystack
+ * @param {Buffer} needle
+ * @param {number} fromOffset
+ * @returns {boolean}
+ */
+function includes(haystack, needle, fromOffset) {
+  const limit = haystack.length - needle.length
+  for (let i = fromOffset; i <= limit; i++) {
+    let match = true
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) { match = false; break }
+    }
+    if (match) return true
+  }
+  return false
+}
+
+/**
+ * Scan a file buffer for polyglot indicators from byte 32 onward.
+ * Files that embed executable or script content inside another format
+ * (e.g. JPEG with a hidden PE header) are rejected.
+ *
+ * @param {Buffer} buffer
+ * @returns {{ success: true } | { success: false, error: string, message: string }}
+ */
+export function checkPolyglot(buffer) {
+  if (buffer.length <= SCAN_SKIP) return { success: true }
+
+  for (const { buf, label } of FLAG_BUFS) {
+    if (includes(buffer, buf, SCAN_SKIP)) {
+      return failResult('POLYGLOT_DETECTED', `File contains suspicious embedded content: ${label}`)
+    }
+  }
+
+  return { success: true }
+}