How To Use ZevSafe

1. Key Derivation Pipeline (v2 Standard: PBKDF2-SHA512 · 600k Iterations)

Passwords are never used directly as encryption keys. To prevent GPU/ASIC brute-forcing and dictionary attacks, ZevSafe employs an ultra-strong key stretching pipeline:

• 32-Byte Salt Generation: A unique, random 256-bit salt is generated for each operation using the browser's cryptographically secure pseudo-random number generator (CSPRNG), window.crypto.getRandomValues(). This renders rainbow tables and pre-computed attacks mathematically impossible.
• PBKDF2-SHA512 Stretching: The password and 32-byte salt are processed through Password-Based Key Derivation Function 2 using SHA-512 as the underlying cryptographic hash function.
• 600,000 Iterations: The key derivation executes for 600,000 iterations (exceeding OWASP 2024 recommendations), introducing an immense computational barrier for unauthorized decryption attempts.
• Optional Keyfile Second Factor: If an optional keyfile is supplied, its SHA-256 digest is XOR-mixed directly into the derived key material before AES-GCM key import.

2. Step-by-Step Encryption Flow

When you drop a folder and click "Encrypt & Download", the browser executes the following sequence:

• Step 2.1: Granular Adaptive Packaging: The selected folder is packaged into a binary stream using per-file adaptive packaging: pre-compressed media (photos, videos, archives, PDFs) use instantaneous STORE mode (0 CPU overhead), while compressible files (text, code, data) use fast Level 1 DEFLATE compression for up to 10x faster vault generation.
• Step 2.2: Header Variables: The CSPRNG generates a random 32-byte Salt and a 12-byte Initialization Vector (IV/Nonce).
• Step 2.3: Key Stretching: The browser derives a 256-bit key from the password, Salt, and optional keyfile hash using PBKDF2-SHA512 (600,000 iterations) via crypto.subtle.deriveBits().
• Step 2.4: AES-256-GCM ciphering: The ZIP binary stream is encrypted using AES-GCM-256 with the derived key and the 12-byte IV. During this operation, a 16-byte (128-bit) GCM authentication tag is generated to ensure data integrity.
• Step 2.5: Zero-Copy Binary Assembly: The 50-byte v2 header [ZV2\0 | Version(0x02) | Flags | Salt(32B) | IV(12B)] is combined with the ciphertext stream via zero-copy Blob-by-reference.
• Step 2.6: Disk Write: The packed array is downloaded as a single .zev vault file directly via browser local memory.

3. Step-by-Step Decryption Flow

When you upload a .zev file and click "Decrypt & Download", the reverse sequence takes place:

• Step 3.1: Automatic Version Detection: The browser reads the raw binary header. If the first 4 bytes match magic ZV2\0, it executes the v2 pipeline; otherwise, it seamlessly routes to the backward-compatible v1 pipeline.
• Step 3.2: Re-deriving Key: The user-provided password, extracted Salt, and optional keyfile are processed through PBKDF2 to re-derive the exact 256-bit AES-GCM key.
• Step 3.3: Cryptographic Decryption & Integrity Verification: The browser calls crypto.subtle.decrypt(). The Web Crypto engine automatically calculates and validates the GCM authentication tag.
  Note: If even a single bit has been modified, or if the password is incorrect, the tag verification fails. The operation throws an OperationError and immediately aborts.
• Step 3.4: Immediate Memory Deallocation: Intermediate encrypted buffers and ciphertext arrays are immediately deallocated before unzipping, slashing peak browser RAM by ~50%.
• Step 3.5: In-Browser Vault Explorer: The decrypted ZIP structure is loaded into the in-browser file explorer for instant playback, selective extraction, or 1-click full archive download.