DOCUMENTATION

QSafe Vault Docs

Technical reference covering the security model, encryption flow, container format, and operational considerations.

Quick Start

QSafe Vault runs entirely in your browser — no installation required. To get started:

  1. Open app.html (or click "Launch Vault" in the nav)
  2. Click Create New Vault
  3. Enter a vault name and a strong password (min. 8 characters)
  4. Click Create Vault + Generate Keys — wait ~2 seconds for key generation
  5. Drag a file onto the drop zone, or click Add Files
  6. Your file is encrypted and stored. Click the download button to decrypt it back.
ℹ The vault is stored in your browser's IndexedDB. Use Export Backup regularly to save a copy you can restore later.

Creating a Vault

A vault is a named, password-protected container that holds your encrypted files. When you create one:

⚠ Your password cannot be recovered. There is no reset mechanism. Write it down and store it safely. If you forget your password, your files are permanently inaccessible.

Encrypting a File

Drag any file into the drop zone (or click Add Files). Before encrypting, you can optionally attach a time-lock policy. Then:

  1. A random 32-byte file key is generated
  2. The file is encrypted: AES-256-GCM(fileKey, plaintext)
  3. The file key is encapsulated: ML-KEM.encap(publicKey) → {kemCt, sharedSecret}
  4. The file key is wrapped: AES-256-GCM(HKDF(sharedSecret), fileKey)
  5. The entire container is signed: ML-DSA.sign(dsakey, containerBytes)
  6. The QSAFE container is stored in IndexedDB

Decrypting a File

Click the download button next to any file in the vault. The following checks happen before the file is returned:

  1. Signature check: ML-DSA-65 verifies the container hasn't been modified
  2. Policy check: If a time-lock exists, the current time must be after the unlock time
  3. Key decapsulation: ML-KEM.decap recovers the shared secret using your secret key
  4. Key unwrap: HKDF + AES-GCM recovers the file key
  5. Decryption: AES-256-GCM decrypts and authenticates the file

If any step fails, decryption stops immediately. The file is downloaded directly to your device.

Time-Lock Policies

When encrypting a file, you can set a time-lock policy:

Policy fields are embedded inside the QSAFE container and covered by the ML-DSA signature. Modifying the time-lock or removing the policy invalidates the signature, preventing decryption.

You can also create named policies under the Policies tab and attach them to multiple files.

ℹ Time-lock enforcement in the MVP is based on the browser clock. For adversarially strong time-locks in a production deployment, use a server-side key service that controls key release by time.

Export & Import

To back up your vault, click Export Backup in the open vault view. This creates a .vault JSON file containing:

To restore, open the app in any browser, click Import Vault, select the file, and enter your password.

Audit Log

Every significant action is logged to the Audit Log tab:

Security Model

QSafe Vault assumes the following threat model by default:

⚠ QSafe Vault does NOT protect against: malware on your device reading memory, a compromised browser extension, or someone with access to your unlocked device.

QSAFE Container Format

Each encrypted file is stored as a QSAFE binary container with the following structure:

// QSAFE Container v2 binary layout magic 4 bytes — 0x51534146 ("QSAF") version 1 byte — 0x02 cipher_suite 1 byte — 0x01=ML-KEM-768, 0x02=ECDH-P256 (fallback) kem_algo variable — algorithm name string sig_algo variable — signature algorithm name string policy_id 16 bytes — zeros if no policy unlock_time 8 bytes — Unix ms timestamp (0 = no lock) kem_ciphertext variable — encapsulated file key nonce 12 bytes — AES-GCM IV encrypted_file variable — AES-256-GCM ciphertext + tag signature variable — ML-DSA-65 sig over all preceding bytes

The signature covers every byte before the sig_len field, making it impossible to modify any part of the container — including the policy fields — without breaking verification.

Frequently Asked Questions

Why can't I recover my password?
+
Recovery would require us to store something that can reverse your password — which is either the password itself, or a recoverable key. Either approach creates a vulnerability: whoever holds that data becomes a target. The only secure design is one where nobody but you can ever open your vault. This is a deliberate design choice, not a limitation. Write your password down.
Can I use QSafe offline?
+
Yes. Once the page has loaded, QSafe Vault makes zero network requests. All cryptographic operations are fully local. You can save the HTML files and open them from your hard drive with no internet connection.
What is the maximum file size?
+
There is no hard limit in the code, but practical limits come from browser memory — the entire file must fit in RAM during encryption. Files up to a few hundred MB work well in most browsers. For larger files, consider splitting them or using the Export feature to manage storage.
Is the encryption the same as HTTPS?
+
QSafe uses AES-256-GCM which is the same cipher used by modern HTTPS/TLS. However, HTTPS uses classical key exchange (ECDH) which is quantum-vulnerable. QSafe replaces ECDH with ML-KEM-768, making the key exchange quantum-safe. The file cipher (AES-256-GCM) is shared.
Why does key generation take a few seconds?
+
The delay comes from Argon2id — the password hashing function. It is intentionally slow (64MB of memory + 3 time iterations) to make brute-force attacks impractical. This delay only happens when creating or unlocking a vault, not when encrypting or decrypting files.

Known Limitations