📤

<secure-file-upload>

A security-first file upload component with file type validation, size limits, magic number verification, and scan hook integration.

Overview

The <secure-file-upload> component provides comprehensive file upload security including MIME type validation, extension checking, file size limits, and magic number verification. Content validation runs at every security tier.

Server Validation Required
Client-side validation can be bypassed. Always validate file type, size, and content on the server. Use virus scanning for uploaded files.

File Validation

Accept Types

File Type Restrictions HTML
templ.Raw(<!-- Accept specific MIME types -->
							<secure-file-upload
							label="Profile Picture"
							name="avatar"
							accept="image/jpeg,image/png,image/webp"
							max-size="5242880"
							></secure-file-upload>

							<!-- Accept by extension -->
							<secure-file-upload
							label="Documents"
							name="docs"
							accept=".pdf,.doc,.docx"
							max-size="10485760"
							></secure-file-upload>

							<!-- Accept all images -->
							<secure-file-upload
							label="Any Image"
							name="image"
							accept="image/*"
							></secure-file-upload>)
Live Demo - Image Upload

Size Limits

File size limits are enforced both by attribute and security tier. The more restrictive limit is applied.

Security TierDefault Max SizeNotes
Public20 MBGeneral uploads
Authenticated10 MBUser uploads
Sensitive5 MBPersonal documents
Critical2 MBID verification

Security Features

Magic Number Validation

The component reads the file header and checks its signature against the declared type. This runs at every security tier, not only CRITICAL.

Signatures are known for PDF, JPEG and PNG. A type with no known signature passes this check, so magic numbers narrow the gap — they do not close it. Server-side content inspection remains mandatory.

Supported Magic Numbers Text
templ.Raw(JPEG: FF D8 FF
							PNG:  89 50 4E 47
							PDF:  25 50 44 46
							GIF:  47 49 46 38

							A renamed .exe file won't pass as .jpg)

Path Traversal Prevention

File names containing path traversal sequences are automatically rejected to prevent directory traversal attacks.

Hidden File Rejection

Files starting with a dot (hidden files on Unix systems) are rejected by default for SENSITIVE and CRITICAL tiers.

Scan Hook

Register an async scan function to validate files server-side before accepting them. This is typically used to integrate with a malware scanning service (e.g. ClamAV) or any custom validation endpoint.

Server-Side Scanning
The scan hook sends each file to your server for inspection before the file is accepted. The component shows a scanning indicator and disables the input while the scan is in progress. If the hook throws or returns { valid: false }, the file is rejected.
Registering a Scan Hook JavaScript
const upload = document.querySelector('secure-file-upload');

upload.setScanHook(async (file) => {
  const form = new FormData();
  form.append('file', file);

  const res = await fetch('/api/scan', {
    method: 'POST',
    body: form
  });

  const { clean, threat } = await res.json();
  return { valid: clean, reason: threat };
});

The scan hook runs after all other validation (type, size, magic number) passes. Each file is scanned individually. All scan results are recorded in the audit log with events: scan_started, scan_passed, scan_rejected, or scan_error.

API Reference

Attributes

AttributeTypeDefaultDescription
security-tierstring"critical"Security level
namestring-Form field name
labelstring-Accessible label
acceptstring-Accepted file types
max-sizenumbervariesMax file size in bytes
multiplebooleanfalseAllow multiple files
requiredbooleanfalseFile is required
capturestring-Camera capture mode (mobile)

Properties

files ReadonlyArray<SecureFileMeta> Metadata for accepted files — { name, size, type } only. Raw File objects are never exposed: .arrayBuffer() and .text() would hand file contents to any intercepting script. Empty when nothing is selected.
valid boolean Validation state
hasScanHook boolean Whether a scan hook is registered
scanning boolean Whether a scan is in progress

Methods

clear(): void
Clear selected files
setScanHook(hook: (file: File) => Promise< valid, reason? >): void
Register a server-side scan function called for each file
getAuditLog(): AuditLogEntry[]
Get audit log entries

Events

EventDetailDescription
secure-file-change name, files, tier Fired when files are selected and validated. files is SecureFileMeta[] (name, size, type) — raw File objects are intentionally absent; read them from e.target.files.
secure-audit event, data Security audit event (file select, validation, mount)

Examples

Document Upload

Resume Upload HTML
<secure-file-upload
							label="Upload Resume"
							name="resume"
							accept=".pdf,.doc,.docx"
							max-size="10485760"
							security-tier="sensitive"
							required
							></secure-file-upload>

ID Verification (Critical)

Identity Document HTML
<secure-file-upload
							label="Government ID"
							name="id_document"
							accept="image/jpeg,image/png,.pdf"
							max-size="5242880"
							security-tier="critical"
							capture="environment"
							required
							></secure-file-upload>

Multiple File Upload

Photo Gallery HTML
<secure-file-upload
							label="Upload Photos"
							name="photos"
							accept="image/*"
							max-size="10485760"
							multiple
							security-tier="authenticated"
							></secure-file-upload>