<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.
File Validation
Accept Types
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>)Size Limits
File size limits are enforced both by attribute and security tier. The more restrictive limit is applied.
| Security Tier | Default Max Size | Notes |
|---|---|---|
| Public | 20 MB | General uploads |
| Authenticated | 10 MB | User uploads |
| Sensitive | 5 MB | Personal documents |
| Critical | 2 MB | ID 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.
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.
{ valid: false }, the file is rejected.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
| Attribute | Type | Default | Description |
|---|---|---|---|
security-tier | string | "critical" | Security level |
name | string | - | Form field name |
label | string | - | Accessible label |
accept | string | - | Accepted file types |
max-size | number | varies | Max file size in bytes |
multiple | boolean | false | Allow multiple files |
required | boolean | false | File is required |
capture | string | - | Camera capture mode (mobile) |
Properties
{ 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.Methods
Events
| Event | Detail | Description |
|---|---|---|
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
<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)
<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
<secure-file-upload
label="Upload Photos"
name="photos"
accept="image/*"
max-size="10485760"
multiple
security-tier="authenticated"
></secure-file-upload>