docs(security): add AeroCrypt overlay page, correct v3 status and crypto

New features/aerocrypt.md documents the native AeroCrypt overlay (AECR v3),
kept clearly distinct from AeroVault (a Cryptomator-class container) and
rclone crypt (the interop overlay), with the shared-crypto-core note. v3 is
the shipped Archive vault tier, not Experimental/Beta (fixed in encryption.md,
wrapper-stack.md, aerovault.md). The overlay is renamed AeroFTP-Crypt to
AeroCrypt with the correct shipped crypto (AES-256-GCM-SIV content, AES-256-KW
DEK wrap, AES-256-SIV filenames, Argon2id 128 MiB, key-bound config MAC),
replacing the stale AES-256-GCM + HKDF. cli crypt cipher corrected to
AES-256-GCM-SIV. Nav adds AeroCrypt Overlay under Features and Security.

Co-authored-by: EhudKirsh <EhudKirsh@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.vitepress/config.ts

@@ -229,6 +229,7 @@ export default defineConfig({
                 { text: 'AeroFile', link: '/features/aerofile' },
                 { text: 'AeroSync', link: '/features/aerosync' },
                 { text: 'AeroVault', link: '/features/aerovault' },
+                { text: 'AeroCrypt Overlay', link: '/features/aerocrypt' },
                 { text: 'AeroAgent', link: '/features/aeroagent' },
                 { text: 'AeroPlayer', link: '/features/aeroplayer' },
                 { text: 'AeroTools', link: '/features/aerotools' },
@@ -319,6 +320,7 @@ export default defineConfig({
             { text: 'Encryption', link: '/security/encryption' },
             { text: 'Wrapper Stack', link: '/security/wrapper-stack' },
             { text: 'Error Correction', link: '/security/error-correction' },
+            { text: 'AeroCrypt Overlay', link: '/features/aerocrypt' },
             { text: 'rclone crypt', link: '/features/rclone-crypt' },
             { text: 'Credentials', link: '/security/credentials' },
             { text: 'Credential Isolation', link: '/credential-isolation' },

cli/commands.md

@@ -531,7 +531,7 @@ Jobs are persisted in SQLite (`~/.config/aeroftp/jobs.db`) and survive daemon re
 
 ### crypt
 
-Zero-knowledge encrypted storage on any provider. Content encrypted with AES-256-GCM (64KB blocks, hardware accelerated), filenames encrypted with AES-256-SIV, key derivation via Argon2id.
+Zero-knowledge encrypted storage on any provider: the CLI surface of the [AeroCrypt overlay](/features/aerocrypt). Content encrypted with AES-256-GCM-SIV (64 KB blocks) under a per-file random key wrapped with AES-256-KW, filenames encrypted with AES-256-SIV, key derivation via Argon2id (128 MiB). New objects are written as the hardened v3 (`AECR`) format; legacy v1/v2 overlays stay readable.
 
 ```bash
 # Initialize encrypted overlay

features/aerocrypt.md

@@ -0,0 +1,85 @@
+# AeroCrypt Overlay
+
+AeroCrypt is AeroFTP's **native client-side encryption overlay**. It turns any server, protocol or provider into a high-security, zero-knowledge store: the remote only ever holds ciphertext and obfuscated names, while the decrypted view is browsed exactly like a normal server in the standard dual panel.
+
+AeroCrypt is an **overlay**, not a container. One local file maps to one remote object (a per-file encrypted blob with an encrypted name), so an encrypted scope stays listable, navigable and syncable object by object. This is the opposite shape from [AeroVault](/security/encryption), which seals many files into a single `.aerovault` container. The two coexist on purpose: AeroVault for a sealed, portable bundle, AeroCrypt for an ongoing encrypted mirror on a provider you do not trust at rest.
+
+> **Community design attribution.** The AeroCrypt naming (AeroCrypt for the native overlay, Rclone Crypt for the interoperable one), the wrapper-and-overlay model it sits in, the opt-in "no default cipher" rule, and much of the format and UX were shaped by a sustained design contribution from **Ehud Kirsh** across the [Wrappers / Overlays roadmap (#272)](https://github.com/axpdev-lab/aeroftp/discussions/272) and the [AeroVault and cryptography design thread (#276)](https://github.com/axpdev-lab/aeroftp/discussions/276).
+
+::: info AeroVault vs AeroCrypt: two different things
+**AeroVault is to Cryptomator what AeroCrypt is to rclone crypt.** AeroVault is a sealed encrypted **container** (a single `.aerovault` vault you open); AeroCrypt is a transparent per-file **overlay** that encrypts each remote object in place and is browsed like a normal server.
+
+They **share the same audited crypto core** (one implementation, one audit pass, extracted from the AeroVault v3 engine in v4.0.5): AES-256-GCM-SIV content, AES-256-KW key wrapping, AES-256-SIV filenames, and the Argon2id (128 MiB, t=4, p=4) KDF.
+
+They **do not share their shape**: AeroVault seals many files into one container with the full wrapper stack (small-file packing, content-defined chunking, deduplication, per-chunk zstd, and the v4 error-correction extension); AeroCrypt encrypts object by object with no container and no cross-file dedup. Different on-disk formats too: `AEROVAULT3` container plus manifest, versus the per-object `AECR` format plus a `.aeroftp-crypt.json` config.
+:::
+
+There is **no default cipher**: you actively choose AeroCrypt (native) or [Rclone Crypt](/features/rclone-crypt) (the interop lane), by clicking in the GUI or typing in the CLI. Nobody encrypts by tapping Enter.
+
+## What AeroCrypt gives you
+
+- **Zero-knowledge on any backend.** AeroCrypt wraps the storage so the remote bucket only ever holds ciphertext and obfuscated names, on any of the supported backends, even the ones that offer no encryption of their own. On a provider that already encrypts at rest (Filen, MEGA, Internxt) it is a second independent layer keyed only by you, genuine double encryption where the key that matters never leaves your device.
+- **Browses like a normal server.** You unlock once, and from then on the decrypted folder reads, navigates, gets and puts exactly like a connected server in the dual panel, with clear names on your side and ciphertext on the provider's.
+- **AeroCrypt Profile (per-profile binding).** An overlay can be bound to a saved server profile so it auto-unlocks on connect, with a toggle in the connection form, per-session binding that survives a profile switch or reconnect, and edit-mode guards that lock the binding so it cannot be silently changed.
+
+## The AECR format (v3)
+
+AeroCrypt writes one encrypted object per file, with the format magic `AECR`. The current version is v3:
+
+| Layer | Algorithm | Detail |
+| ----- | --------- | ------ |
+| Content encryption | AES-256-GCM-SIV (RFC 8452) | Per-file random data key (DEK), 64 KiB plaintext blocks, per-block random nonce |
+| DEK wrapping | AES-256-KW (RFC 3394) | The per-file DEK is wrapped under the master key |
+| Master key derivation | Argon2id (128 MiB, t=4, p=4) | Derives the master key from your password and the per-overlay salt |
+| Filename encryption | AES-256-SIV (RFC 5297) | Deterministic, so the same plaintext name maps to the same ciphertext and the scope stays listable |
+| Config integrity | HKDF-SHA256 key-bound MAC | On the `.aeroftp-crypt.json` config, over the version, block size, Argon2 profile (memory, time, lanes) and salt |
+
+Each content block is laid out as `nonce(12) ‖ AES-256-GCM-SIV(DEK, plaintext_block, AAD) ‖ tag(16)`, where the AAD binds the block index **and** the total block count. The total block count is also carried, authenticated, in the file header.
+
+### Hardened in v4.0.5 (pre-release audit)
+
+A five-reviewer pre-release audit of the native overlay closed two live data-loss and downgrade classes, and the format was bumped to v3:
+
+- **Per-file length binding.** Every block binds its index and the total block count; silent truncation (a dropped tail or whole blocks) and append (trailing bytes or extra blocks) now fail closed instead of returning short or padded plaintext.
+- **Key-bound config MAC.** The `.aeroftp-crypt.json` config carries an HKDF-SHA256 MAC bound to the master key. A tampered or downgraded config is rejected on unlock, and a wrong password gives a clean error instead of an empty listing.
+- **Init refuses to clobber.** `crypt init` will not overwrite an existing overlay config unless forced, because re-initialising rotates the salt and would orphan every file already in the overlay.
+- **Empty crypt password rejected**, and the decrypted plaintext download is written atomically.
+- **Legacy formats are read-only.** Existing v1 and v2 overlays keep decrypting transparently, but every new object is written as v3, so a stale or downgraded config can never produce weaker ciphertext. (v1 is the original plain AES-256-GCM with an HKDF per-file key and Argon2id-64; v2 is GCM-SIV without the length binding.)
+
+## AeroCrypt vs rclone crypt vs AeroVault
+
+AeroCrypt (native overlay), rclone crypt (interop overlay) and AeroVault (container) are three distinct things. Keep them apart:
+
+| | AeroCrypt (native) | Rclone Crypt (interop) | AeroVault (container) |
+| --- | --- | --- | --- |
+| Shape | Per-file overlay on any provider | Per-file overlay, rclone's own format | Single sealed `.aerovault` file |
+| Content cipher | AES-256-GCM-SIV (nonce-misuse resistant) | XSalsa20-Poly1305 (not nonce-misuse resistant) | AES-256-GCM-SIV |
+| Filenames | AES-256-SIV | rclone EME | Kept inside the encrypted manifest |
+| Interop | AeroFTP only | Reads and writes rclone's format | AeroFTP (plus Cryptomator import) |
+| Best for | Leading encryption on any backend | Existing `rclone crypt` remotes | A sealed, portable bundle |
+
+AeroFTP leads with AeroCrypt and keeps [Rclone Crypt](/features/rclone-crypt) beside it as the labelled interop lane, the same way [AeroVault](/security/encryption) sits beside Cryptomator import: support the foreign format, lead with ours. The nonce-misuse resistance of AES-256-GCM-SIV is the property rclone crypt's stream-cipher construction does not give you, which is why AeroCrypt leans on it.
+
+## CLI
+
+The `crypt` subcommand drives the same overlay from the terminal:
+
+```bash
+# initialize an encrypted overlay at /encrypted on the S3 profile
+AEROFTP_CRYPT_PASSWORD=secret aeroftp-cli --profile "S3" crypt init _ /encrypted
+
+# upload (content and filename encrypted)
+AEROFTP_CRYPT_PASSWORD=secret aeroftp-cli --profile "S3" crypt put ./secret.pdf _ /encrypted
+
+# list (decrypted names visible)
+AEROFTP_CRYPT_PASSWORD=secret aeroftp-cli --profile "S3" crypt ls _ /encrypted
+
+# download and decrypt
+AEROFTP_CRYPT_PASSWORD=secret aeroftp-cli --profile "S3" crypt get secret.pdf _ /encrypted ./out.pdf
+```
+
+See [CLI Commands](/cli/commands) for the full `crypt` surface.
+
+## Where AeroCrypt sits
+
+AeroCrypt is the `crypt` wrapper of the AeroFTP overlay stack, applied per object on top of the provider. For the full layered encryption architecture see [Encryption](/security/encryption), and for the recovery layer that protects bytes against rot see [Error Correction](/security/error-correction).

features/aerovault.md

@@ -155,7 +155,7 @@ AeroVault files are registered as a MIME type on all platforms with dedicated ic
 
 AeroVault v2 (described above) is the stable default. Two newer formats extend it without breaking it.
 
-**v3 (Experimental)** is the first wrapper-stack vault. It keeps the single-file `.aerovault` portability of v2 while adding content-defined chunking (Gear-CDC), per-chunk zstd compression, deduplication, and a forward-compatible extension directory. The write pipeline is chunk-first: chunk → keyed-BLAKE3 chunk id → zstd → AES-256-GCM-SIV → BLAKE3-256 cipher hash. It is gated behind the Experimental tier in the vault-create dialog; v2 stays the default and there is no automatic migration.
+**v3 (the `Archive` tier)** is the first wrapper-stack vault. It keeps the single-file `.aerovault` portability of v2 while adding content-defined chunking (Gear-CDC), per-chunk zstd compression, deduplication, and a forward-compatible extension directory. The write pipeline is chunk-first: chunk → keyed-BLAKE3 chunk id → zstd → AES-256-GCM-SIV → BLAKE3-256 cipher hash. It ships as the `Archive` security tier in the vault-create dialog; the simpler Standard, Advanced and Paranoid tiers stay on v2, and there is no automatic migration.
 
 **v4 = v3 + Error Correction.** v4 adds a fourth wrapper, Reed-Solomon parity, as a non-critical extension, so `v3 + ECC = v4` and a v3-only reader skips the parity it does not understand and still opens the container.
 

security/encryption.md

@@ -9,9 +9,9 @@ AeroFTP applies encryption across several distinct layers:
 | Layer | Purpose | Primary Algorithm |
 | ----- | ------- | ----------------- |
 | AeroVault v2 | Stable encrypted file containers (default) | AES-256-GCM-SIV (RFC 8452) |
-| AeroVault v3 (Experimental) | Wrapper-stack container with content-defined chunking, dedup and per-chunk zstd | AES-256-GCM-SIV (RFC 8452) over zstd chunks |
-| AeroVault v4 error correction | Detached `.aerocorrect` recovery sidecar over the ciphertext (repair, not confidentiality) | Reed-Solomon parity, SHA-256 content binding |
-| AeroFTP-Crypt overlay | Streaming per-file encryption on top of any provider profile | AES-256-GCM with HKDF-derived per-file keys |
+| AeroVault v3 (Archive tier) | Wrapper-stack container with content-defined chunking, dedup and per-chunk zstd | AES-256-GCM-SIV (RFC 8452) over zstd chunks |
+| AeroVault v4 (v3 + error correction) | v3 container plus a detached `.aerocorrect` recovery sidecar over the ciphertext (repair, not confidentiality) | Reed-Solomon parity, SHA-256 content binding |
+| AeroCrypt overlay (native) | Per-file encryption on top of any provider profile (`AECR` format) | AES-256-GCM-SIV content, AES-256-KW DEK wrap, AES-256-SIV filenames |
 | Archive encryption | Password-protected ZIP/7z | AES-256 |
 | rclone crypt interoperability | Compatibility decryption for existing remotes | XSalsa20-Poly1305 content + standard filename decryption |
 | Credential storage | vault.db secrets | AES-256-GCM + Argon2id |
@@ -87,9 +87,9 @@ The key derivation parameters exceed OWASP 2024 minimum recommendations:
 
 AeroFTP can also create and browse Cryptomator vault format 8 containers, using scrypt + AES-256-KW + AES-256-SIV + AES-256-GCM.
 
-## AeroVault v3 (Experimental)
+## AeroVault v3 (Archive tier)
 
-AeroVault v3 is the first wrapper-stack vault format. It keeps the single-file `.aerovault` portability of v2 while adding content-defined chunking, per-chunk zstd compression, deduplication, and a forward-compatible extension directory shaped around the future v4 ECC (error-correction) layer. The format is implementation-draft and gated behind the Experimental security tier in the vault-create dialog. v2 remains the default and there is no automatic v2 → v3 migration until v3 leaves Experimental.
+AeroVault v3 is the first wrapper-stack vault format. It keeps the single-file `.aerovault` portability of v2 while adding content-defined chunking, per-chunk zstd compression, deduplication, and a forward-compatible extension directory used by the v4 error-correction layer. It ships as the **`Archive`** security tier in the vault-create dialog (the simpler Standard, Advanced and Paranoid tiers stay on v2), after its public spec review pass in the [#276 design thread](https://github.com/axpdev-lab/aeroftp/discussions/276). v2 remains the default for the other tiers and there is no automatic v2 → v3 migration.
 
 The canonical reference is the in-repo specification at [`docs/AEROVAULT-V3-SPEC.md`](https://github.com/axpdev-lab/aeroftp/blob/main/docs/AEROVAULT-V3-SPEC.md).
 
@@ -179,24 +179,24 @@ AeroVault v3 uses AES-256-GCM-SIV by default. The wrapper stack is designed so t
 
 ### Tauri command surface
 
-Fifteen Tauri commands cover the v3 lifecycle and are exposed once the Experimental tier is selected: `vault_v3_create`, `vault_v3_open`, `vault_v3_add_files`, `vault_v3_add_files_to_dir`, `vault_v3_create_directory`, `vault_v3_extract_entry`, `vault_v3_delete_entry`, `vault_v3_delete_entries`, `vault_v3_move_entry`, `vault_v3_rename_entry`, `vault_v3_copy_entry`, `vault_v3_change_password`, `vault_v3_add_directory`, `vault_v3_security_info`, `is_vault_v3`.
+Fifteen Tauri commands cover the v3 lifecycle and are exposed via the `Archive` tier: `vault_v3_create`, `vault_v3_open`, `vault_v3_add_files`, `vault_v3_add_files_to_dir`, `vault_v3_create_directory`, `vault_v3_extract_entry`, `vault_v3_delete_entry`, `vault_v3_delete_entries`, `vault_v3_move_entry`, `vault_v3_rename_entry`, `vault_v3_copy_entry`, `vault_v3_change_password`, `vault_v3_add_directory`, `vault_v3_security_info`, `is_vault_v3`.
 
-## AeroVault container vs AeroFTP-Crypt overlay
+## AeroVault container vs AeroCrypt overlay
 
-AeroVault and AeroFTP-Crypt are two different shapes for two different needs, and the choice between them depends on whether you want a sealed object or an ongoing transformation.
+AeroVault and AeroCrypt are two different shapes for two different needs, and the choice between them depends on whether you want a sealed object or an ongoing transformation. They are not the same thing: AeroVault is a container, AeroCrypt is a per-file overlay. See [AeroCrypt Overlay](/features/aerocrypt) for the full overlay guide.
 
-| Property | AeroVault (`.aerovault`) | AeroFTP-Crypt overlay |
-| -------- | ------------------------ | --------------------- |
-| Shape | Single sealed file, OS-integrated MIME type, double-clickable | Streaming per-file overlay on top of any provider profile |
+| Property | AeroVault (`.aerovault`) | AeroCrypt overlay |
+| -------- | ------------------------ | ----------------- |
+| Shape | Single sealed file, OS-integrated MIME type, double-clickable | Per-file overlay on top of any provider profile |
 | Granularity | Whole-container operation, manifest indexes all entries | Per-file: each remote object is independently encrypted |
 | Best for | Sharing several files as one bundle (email, instant messenger, USB stick, cold-storage snapshot) | Ongoing folder mirror on a provider you do not trust at rest |
-| Visibility | Browseable in AeroFTP and (for v3) addressable through the vault commands | Cleartext through an AeroMount mount; encrypted blobs if you open the underlying provider panel directly |
+| Visibility | Browseable in AeroFTP and (for v3) addressable through the vault commands | Browsed like a normal server in the dual panel once unlocked; encrypted blobs if you open the underlying provider panel directly |
 | Single-file aspect | Yes (the load-bearing feature) | No |
-| Format owner | AeroFTP (v2 and v3 specs) | AeroFTP (CLI-defined `.aeroftp-crypt.json` config + per-file AES-256-GCM with HKDF-derived keys) |
+| Format owner | AeroFTP (v2 and v3 specs) | AeroFTP (`AECR` format: per-file AES-256-GCM-SIV under a random DEK wrapped with AES-256-KW, AES-256-SIV filenames, `.aeroftp-crypt.json` config with a key-bound MAC) |
 
-The mental model: if the question is "send a sealed bundle to one person" or "shelve a snapshot on portable media", that is AeroVault. If the question is "keep this folder continuously mirrored on kDrive but the server must never see plaintext", that is the AeroFTP-Crypt overlay. The two coexist on purpose.
+The mental model: if the question is "send a sealed bundle to one person" or "shelve a snapshot on portable media", that is AeroVault. If the question is "keep this folder continuously mirrored on kDrive but the server must never see plaintext", that is the AeroCrypt overlay. The two coexist on purpose. There is no default cipher: you actively pick AeroCrypt (native) or [Rclone Crypt](/features/rclone-crypt) (interop).
 
-Cipher-strength badges in the connection UI follow this distinction: `E2E 128-bit` / `E2E 256-bit` for providers whose vendor performs client-side end-to-end encryption (MEGA, Filen, Internxt), and a plain `128-bit` / `256-bit` (no `E2E` prefix) for AeroFTP-Crypt overlaid on a server-side-encrypted backend, because the server holds no key but the cipher is ours, not the vendor's.
+Cipher-strength badges in the connection UI follow this distinction: `E2E 128-bit` / `E2E 256-bit` for providers whose vendor performs client-side end-to-end encryption (MEGA, Filen, Internxt), and a plain `128-bit` / `256-bit` (no `E2E` prefix) for AeroCrypt overlaid on a server-side-encrypted backend, because the server holds no key but the cipher is ours, not the vendor's.
 
 ## rclone crypt interoperability