SERVICE #01 • CRYPTOGRAPHIC FOUNDATION

Core Streaming Vault (ZV3)

⏱️ 6 min read 🔒 Authenticated STREAM AEAD 📦 Version 3.0 Standard

The Core Streaming Vault is the fundamental cryptographic engine of ZevSafe. It allows users to pack gigabytes of sensitive files and complete folder hierarchies into a single authenticated, portable .zev container directly in the browser—with zero server uploads, zero disk leakage, and bounded peak memory under 150 MB.

🟢 Simple User Guide

How to Lock and Unlock Vaults in 3 Steps

STEP 01

Select Files or Folders

Drag and drop individual files, videos, documents, or an entire folder tree onto the Lock Vault dropzone. ZevSafe scans the hierarchy locally in your browser without reading them into RAM all at once.

STEP 02

Set Password & Optional Keyfile

Enter a strong passphrase or generate one using the built-in Diceware generator. You can optionally attach any file (a photo, audio track, or security token) as a Physical Keyfile (2FA). Both are required to unlock the vault later.

STEP 03

Stream-Encrypt & Save Emergency Sheet

Click Lock Vault. The browser compresses and encrypts your data chunk by chunk, streaming the finished .zev file directly to your downloads. Print or store the generated Emergency Recovery Sheet containing your configuration parameters.

💡
Instant Unlock: To view or extract files later, drag your .zev vault into the Unlock Vault tab. You don't have to wait to unpack the entire file—ZevSafe loads the file catalog instantly in milliseconds!
🔵 Technical Specification

The 57-Byte Container Header Layout

Every v3 .zev vault begins with an unencrypted, 57-byte authenticated header. This header establishes the cipher configuration, master salt, base initialization vector, and tail manifest pointer.

Byte Offset Field Name Size Type Description & Invariants
0x00 .. 0x03 MAGIC 4 Bytes ASCII Must strictly equal ZV3\0 (Hex: 5A 56 33 00).
0x04 VERSION 1 Byte uint8 Format version; strictly 0x03.
0x05 FLAGS 1 Byte uint8 Bitfield: 0x00 = Standard Vault, 0x02 = Duress Decoy Enabled.
0x06 .. 0x09 CHUNK_SIZE 4 Bytes uint32 BE Nominal plaintext chunk size (Default: 0x00400000 = 4,194,304 B).
0x0A .. 0x29 SALT 32 Bytes Binary CSPRNG random salt passed to PBKDF2-SHA512 key derivation.
0x2A .. 0x30 BASE_IV_PREFIX 7 Bytes Binary CSPRNG random prefix for constructing deterministic 12-byte chunk IVs.
0x31 .. 0x38 MANIFEST_OFFSET 8 Bytes uint64 BE Absolute byte offset where the encrypted JSON tail manifest begins.
JavaScript Header Parser 
// js/stream-unpacker.js: Read 57-byte container header
function parseV3Header(headerBytes) {
    if (headerBytes.byteLength < 57) throw new Error("Header truncated");
    const view = new DataView(headerBytes.buffer, headerBytes.byteOffset, 57);
    
    // Check Magic 'ZV3\0'
    const magic = String.fromCharCode(...headerBytes.slice(0, 4));
    if (magic !== 'ZV3\0') throw new Error("Invalid container magic: " + magic);
    
    const version = view.getUint8(4); // 0x03
    const flags = view.getUint8(5);   // 0x00 or 0x02
    const chunkSize = view.getUint32(6, false); // Big-Endian uint32
    const salt = headerBytes.slice(10, 42);     // 32-byte salt
    const ivPrefix = headerBytes.slice(42, 49); // 7-byte IV prefix
    const manifestOffset = Number(view.getBigUint64(49, false)); // Big-Endian uint64
    
    return { version, flags, chunkSize, salt, ivPrefix, manifestOffset };
}

STREAM AEAD Framing & Mathematical Invariants

To protect against chunk reordering, truncation, injection, or splicing attacks, ZevSafe binds the Chunk Index and a Final Chunk Flag into both the 12-byte initialization vector (IV) and the Additional Authenticated Data (AAD).

12-Byte Chunk IV Construction

Byte Offset Field Length Formula / Value
0 .. 6 Base IV Prefix 7 Bytes Extracted verbatim from BASE_IV_PREFIX in container header.
7 .. 10 Chunk Sequence Counter 4 Bytes Big-Endian uint32 counter ($i = 0, 1, 2, \dots, N$).
11 Last Chunk Marker 1 Byte 0x00 for intermediate frames; 0x01 for the final frame ($i = N$).

10-Byte AAD (Additional Authenticated Data) Binding

Every chunk is authenticated with an explicit 10-byte AAD vector:

Binary AAD Structure 
AAD = [ 'ZV3\0' (4B) | VERSION: 0x03 (1B) | COUNTER: uint32BE (4B) | IS_LAST: uint8 (1B) ]
Total AAD Size: Exactly 10 Bytes
🔒
Cryptographic Truncation Proof: An adversary cannot delete the last chunk or truncate the archive, because the final chunk is authenticated with IS_LAST = 0x01. If any intermediate chunk is removed or reordered, the counter mismatch causes AES-256-GCM authentication to immediately fail with OperationError.

Emergency Recovery Sheet

Because ZevSafe operates with zero backend servers and absolute zero knowledge, forgotten passwords cannot be reset. The Emergency Recovery Sheet provides a printable offline record containing:

  • Container Fingerprint: First 16 hex characters of the master salt for vault identification.
  • Key Derivation Parameters: Selected PBKDF2 iteration count (600k, 1.2M, or 2.4M) and hash algorithm.
  • Keyfile SHA-256 Digest: Hexadecimal hash of the required 2FA hardware keyfile.
  • Passphrase Reminder / Cold Storage Box: Dedicated writing area for air-gapped paper safes.

Security Invariants Enforced

Invariant Technical Guarantee Enforcement Location
Zero Memory Spills Peak RAM strictly < 150 MB across 5 GB vaults. Backpressure credit controller in js/worker-bridge.js.
Nonce Uniqueness Deterministic IV monotonically advances counter; never repeats. js/stream-crypto.js:buildChunkIV()
Zero Network Access Strict CSP air-gap blocks all external HTTP/WebSocket egress. meta http-equiv="Content-Security-Policy"