https://github.com/flutterdude/file_signature
A pure Dart security utility that validates files by checking Magic Byte signatures. Prevents rename attacks (e.g. .exe as .png).
https://github.com/flutterdude/file_signature
dart file-validation flutter magic-numbers security
Last synced: 5 months ago
JSON representation
A pure Dart security utility that validates files by checking Magic Byte signatures. Prevents rename attacks (e.g. .exe as .png).
- Host: GitHub
- URL: https://github.com/flutterdude/file_signature
- Owner: flutterdude
- License: mit
- Created: 2026-01-01T06:54:45.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-01T09:13:42.000Z (6 months ago)
- Last Synced: 2026-01-11T10:37:03.907Z (5 months ago)
- Topics: dart, file-validation, flutter, magic-numbers, security
- Language: C++
- Homepage:
- Size: 363 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# File Signature 🛡️
[](https://pub.dev/packages/file_signature)
[](https://pub.dev/packages/file_signature/score)
[](https://pub.dev/packages/flutter_lints)
[](https://github.com/flutterdude/file_signature/blob/main/LICENSE)
**Don't trust the file extension. Trust the bits.**
`file_signature` is a pure Dart security utility that validates files by checking their **Magic Bytes** (Hex Signatures). It prevents "Rename Attacks" (e.g., renaming `malware.exe` to `image.png`) and works universally on **Mobile, Web, and Desktop**.
### Supported Formats
**Images**
**Documents & Archives**
**Video**
**Blocked Threats**
---
## 🚀 Features
* **🔒 Security First:** Validates the actual binary header, not the text extension.
* **⚡ Zero-Allocation Streams:** Intercepts and guards large file uploads (GBs) without loading them into RAM.
* **🌐 Universal:** Works on **Android, iOS, Web, macOS, Windows, and Linux**.
* **📦 Lightweight:** Zero dependencies on native code.
## 📦 Installation
```yaml
dependencies:
file_signature: ^1.0.0
```
---
## 🛠️ Usage
### 1. The Standard Check (`XFile`)
Ideal for `image_picker` or `file_selector`. It reads only the first 32 bytes.
```dart
import 'package:file_signature/file_signature.dart';
Future uploadAvatar(XFile file) async {
try {
// Validates that the file is genuinely a PNG or JPEG
await FileSignature.guard(
file,
allowed: [FileFormat.png, FileFormat.jpeg],
);
// If code reaches here, the file is safe!
print("File verified.");
} on SecurityException catch (e) {
print("Blocked: ${e.message}");
}
}
```
### 2. The Stream Interceptor ("Middleware")
Ideal for large uploads (Video/PDF) or network piping. It peeks at the header and kills the stream if it's malicious.
```dart
Future secureUpload(Stream> dangerousStream) async {
try {
// This returns a safe stream.
// If the header is bad, the stream emits an error immediately.
final safeStream = FileSignature.guardStream(
dangerousStream,
allowed: [FileFormat.pdf],
);
// Pass 'safeStream' to Dio, HTTP, or AWS S3
await Dio().post('[https://api.com/upload](https://api.com/upload)', data: safeStream);
} on SecurityException catch (e) {
print("Malware upload attempt blocked!");
}
}
```
### 3. Memory Check (`Uint8List`)
Ideal for clipboard data or Base64 strings.
```dart
void checkClipboard(Uint8List data) {
if (FileSignature.isValid(data, allowed: [FileFormat.png])) {
print("Valid Image");
}
}
```
### 🛡️ Supported Formats
We support the most critical formats for upload security:
| Category | Formats |
|------------|----------------------------------------|
| Images | PNG, JPEG, GIF, WebP, BMP |
| Documents | PDF |
| Archives | ZIP (covers DOCX, APK, JAR, etc.) |
| Blocklist | EXE, ELF, Mach-O (Executables) |
### ❓FAQ
Q: Why not just check file.path.endsWith('.png')? A: Because anyone can rename virus.exe to virus.png. The OS will hide the extension, but the file is still an executable. file_signature reads the actual binary header (e.g., 89 50 4E 47) to confirm the type.
Q: Does this download the whole file? A: No. It uses Dart's openRead(0, 32) to fetch only the first 32 bytes. Validating a 10GB video takes milliseconds.
Q: Does it work on Web? A: Yes. It fully supports Blob slicing on the web.
### 🤝 Contributing
Found a new magic byte signature? PRs are welcome! ensuring the package remains lightweight is our priority.