Line data Source code
1 : part of '../worker.dart';
2 :
3 : /// Cryptographic hash worker (MD5, SHA-1, SHA-256, SHA-512).
4 : ///
5 : /// Computes cryptographic hash of a file for integrity verification,
6 : /// deduplication, or content-addressable storage. Runs in native code
7 : /// **without** Flutter Engine for optimal performance.
8 : ///
9 : /// ## Hash File
10 : ///
11 : /// ```dart
12 : /// await NativeWorkManager.enqueue(
13 : /// taskId: 'verify-download',
14 : /// trigger: TaskTrigger.oneTime(),
15 : /// worker: NativeWorker.hashFile(
16 : /// filePath: '/downloads/file.zip',
17 : /// algorithm: HashAlgorithm.sha256,
18 : /// ),
19 : /// );
20 : /// ```
21 : ///
22 : /// ## Hash String
23 : ///
24 : /// ```dart
25 : /// await NativeWorkManager.enqueue(
26 : /// taskId: 'hash-password',
27 : /// trigger: TaskTrigger.oneTime(),
28 : /// worker: NativeWorker.hashString(
29 : /// data: 'myPassword123',
30 : /// algorithm: HashAlgorithm.sha256,
31 : /// ),
32 : /// );
33 : /// ```
34 : ///
35 : /// ## Parameters
36 : ///
37 : /// **[filePath]** or **[data]** *(required)* - File path or string to hash.
38 : ///
39 : /// **[algorithm]** *(optional)* - Hash algorithm (default: SHA-256).
40 : /// - `HashAlgorithm.md5` - MD5 (fast, 128-bit, not cryptographically secure)
41 : /// - `HashAlgorithm.sha1` - SHA-1 (160-bit, deprecated for security)
42 : /// - `HashAlgorithm.sha256` - SHA-256 (256-bit, recommended)
43 : /// - `HashAlgorithm.sha512` - SHA-512 (512-bit, most secure)
44 : ///
45 : /// ## Behavior
46 : ///
47 : /// - Returns hash as hex string in result data
48 : /// - Streaming computation for large files (low memory)
49 : /// - Task succeeds with hash in result
50 : /// - Task fails if file not found or I/O error
51 : ///
52 : /// ## When to Use
53 : ///
54 : /// ✅ **Use hashFile when:**
55 : /// - Verifying download integrity
56 : /// - Checking for duplicate files
57 : /// - Content-addressable storage
58 : /// - File change detection
59 : ///
60 : /// ## See Also
61 : ///
62 : /// - [NativeWorker.cryptoEncrypt] - Encrypt files with AES-256
63 : /// - [NativeWorker.cryptoDecrypt] - Decrypt encrypted files
64 2 : Worker _buildHashFile({
65 : required String filePath,
66 : HashAlgorithm algorithm = HashAlgorithm.sha256,
67 : }) {
68 2 : NativeWorker._validateFilePath(filePath, 'filePath');
69 2 : return CryptoHashWorker.file(filePath: filePath, algorithm: algorithm);
70 : }
71 :
72 : /// Hash string data.
73 : ///
74 : /// See [NativeWorker.hashFile] for full documentation.
75 2 : Worker _buildHashString({
76 : required String data,
77 : HashAlgorithm algorithm = HashAlgorithm.sha256,
78 : }) {
79 2 : if (data.isEmpty) {
80 2 : throw ArgumentError('data cannot be empty');
81 : }
82 2 : return CryptoHashWorker.string(data: data, algorithm: algorithm);
83 : }
84 :
85 : /// File encryption worker (AES-256-GCM).
86 : ///
87 : /// Encrypts files using AES-256-GCM with password-derived key.
88 : /// Runs in native code **without** Flutter Engine for optimal performance.
89 : ///
90 : /// ## Basic Encryption
91 : ///
92 : /// ```dart
93 : /// await NativeWorkManager.enqueue(
94 : /// taskId: 'encrypt-backup',
95 : /// trigger: TaskTrigger.oneTime(),
96 : /// worker: NativeWorker.cryptoEncrypt(
97 : /// inputPath: '/data/backup.db',
98 : /// outputPath: '/data/backup.db.enc',
99 : /// password: 'mySecretPassword',
100 : /// ),
101 : /// );
102 : /// ```
103 : ///
104 : /// ## Parameters
105 : ///
106 : /// **[inputPath]** *(required)* - Path to file to encrypt.
107 : ///
108 : /// **[outputPath]** *(required)* - Where encrypted file will be saved.
109 : ///
110 : /// **[password]** *(required)* - Password for encryption.
111 : /// - Used to derive AES-256 key via PBKDF2
112 : /// - Minimum 8 characters recommended
113 : /// - Store securely (use Flutter Secure Storage)
114 : ///
115 : /// ## Security Notes
116 : ///
117 : /// - Uses AES-256-GCM (authenticated encryption)
118 : /// - Random IV generated per encryption
119 : /// - PBKDF2 key derivation (100,000 iterations)
120 : /// - Password never stored, only used to derive key
121 : ///
122 : /// ## See Also
123 : ///
124 : /// - [NativeWorker.cryptoDecrypt] - Decrypt encrypted files
125 : /// - [NativeWorker.hashFile] - Hash files for integrity
126 5 : Worker _buildCryptoEncrypt({
127 : required String inputPath,
128 : required String outputPath,
129 : required String password,
130 : }) {
131 5 : NativeWorker._validateFilePath(inputPath, 'inputPath');
132 5 : NativeWorker._validateFilePath(outputPath, 'outputPath');
133 :
134 4 : if (password.isEmpty) {
135 3 : throw ArgumentError('password cannot be empty');
136 : }
137 :
138 8 : if (password.length < 8) {
139 4 : throw ArgumentError(
140 2 : 'Password too weak: ${password.length} characters\n'
141 : 'Minimum required: 8 characters for security\n'
142 : 'Recommendation: Use 12+ characters with mixed case, numbers, and symbols',
143 : );
144 : }
145 :
146 4 : return CryptoEncryptWorker(
147 : inputPath: inputPath,
148 : outputPath: outputPath,
149 : password: password,
150 : );
151 : }
152 :
153 : /// File decryption worker (AES-256-GCM).
154 : ///
155 : /// Decrypts files previously encrypted by [NativeWorker.cryptoEncrypt].
156 : /// Runs in native code **without** Flutter Engine.
157 : ///
158 : /// ## Basic Decryption
159 : ///
160 : /// ```dart
161 : /// await NativeWorkManager.enqueue(
162 : /// taskId: 'decrypt-backup',
163 : /// trigger: TaskTrigger.oneTime(),
164 : /// worker: NativeWorker.cryptoDecrypt(
165 : /// inputPath: '/data/backup.db.enc',
166 : /// outputPath: '/data/backup.db',
167 : /// password: 'mySecretPassword',
168 : /// ),
169 : /// );
170 : /// ```
171 : ///
172 : /// ## Parameters
173 : ///
174 : /// **[inputPath]** *(required)* - Path to encrypted file.
175 : ///
176 : /// **[outputPath]** *(required)* - Where decrypted file will be saved.
177 : ///
178 : /// **[password]** *(required)* - Password used for encryption.
179 : /// - Must match the password used in [NativeWorker.cryptoEncrypt]
180 : /// - Decryption fails with wrong password
181 : ///
182 : /// ## See Also
183 : ///
184 : /// - [NativeWorker.cryptoEncrypt] - Encrypt files
185 : /// - [NativeWorker.hashFile] - Hash files for integrity
186 4 : Worker _buildCryptoDecrypt({
187 : required String inputPath,
188 : required String outputPath,
189 : required String password,
190 : }) {
191 4 : NativeWorker._validateFilePath(inputPath, 'inputPath');
192 3 : NativeWorker._validateFilePath(outputPath, 'outputPath');
193 :
194 3 : if (password.isEmpty) {
195 2 : throw ArgumentError('password cannot be empty');
196 : }
197 :
198 : // Note: For decryption, we accept any password length since it must match
199 : // the original encryption password (which was already validated)
200 3 : return CryptoDecryptWorker(
201 : inputPath: inputPath,
202 : outputPath: outputPath,
203 : password: password,
204 : );
205 : }
|
