Obsidian Encrypted Folders

A secure, recursive folder encryption plugin for Obsidian. Protect entire directories within your vault with industrial-grade encryption while maintaining full compatibility with Obsidian features like Search and Graph while unlocked.

✨ Features

• Recursive Encryption: Encrypt entire folder trees (including nested subfolders) with a single click.
• Session Decryption: Temporarily restores plaintext to disk for seamless use with Obsidian Search, Graph view, and Backlinks while unlocked.
• Improved Data Integrity: Encrypted files use a .locked extension, preventing Obsidian's indexer or third-party plugins from corrupting binary data by attempting "UTF-8 repairs."
• Informational Readme: Automatically generates a README_ENCRYPTED.md in locked folders with clear instructions on how to unlock your data.
• Master Key Architecture: Uses an encrypted Master Key (unwrapped by your password or a recovery key) for flexible access.
• Recovery Keys & Safekeeping: Generate a 32-character recovery key during setup with one-click clipboard copying, .txt backup downloads, and mandatory safekeeping confirmation.
• Transparent Setup Disclosure: Displays a pre-encryption notice informing users that file contents are protected while filenames, titles, and directory structures remain unencrypted.
• Secure File Shredding: Automatically overwrites plaintext files with secure random data before re-encrypting to prevent forensic disk recovery.
• Auto-Lock Security: All folders are automatically re-encrypted and locked when the plugin is disabled or Obsidian is closed.
• Configurable Safeguards: Lock unlocked folders automatically when Obsidian goes into the background or after a configurable period of per-folder inactivity, with an optional countdown warning.
• Large Folder Progress: Shows a blocking progress indicator during long encrypt/decrypt operations and processes eligible files with conservative bounded parallelism.
• Exit Strategy: Permanently remove encryption from a folder if you no longer need it, restoring files to normal plaintext Obsidian management.
• Integrity First: Prevents nested encryption within already encrypted folders to ensure a simple, reliable vault structure.
• Sync-Safe State Tracking: Lock and unlock operations are journaled in metadata to improve cross-device consistency during delayed or partial sync.
• Atomic Staging Writes: Encrypts files to a .locked.tmp staging file and verifies ciphertext integrity before shredding original plaintext notes, preventing data loss on process interrupts or disk failures.

🛡️ Security Specifications

• Algorithm: AES-256-GCM (Authenticated Encryption with Associated Data).
• Key Derivation: PBKDF2-SHA256 with 600,000 iterations.
• Key Safety: Master keys in memory are created as non-extractable (extractable: false), preventing raw key exfiltration by unmanaged code.
• Metadata Integrity: Folders include HMAC signatures (mac and recoveryMac) to prevent disk-level metadata tampering (e.g., parameter alteration).
• Atomic Operations: Staging writes (.locked.tmp) verify ciphertext headers and length on disk before removing original source files.
• Modular Service Architecture: Decoupled core services (MetadataManager, AutoLockManager, BatchProcessor, EncryptionService) ensure strong separation of concerns, testability, and isolated security boundaries.
• Implementation: Native Web Crypto API for maximum speed and security.
• Zero-Knowledge: Your master password and derived keys are never stored on disk.

🚀 How to Use

Encrypting a Folder

1. Right-click any folder in the Obsidian File Explorer.
2. Select Encrypt Folder.
3. Set a strong password.
4. IMPORTANT: Copy the generated Recovery Key and store it in a safe place (like a password manager).

Unlocking a Folder

1. Right-click an encrypted folder.
2. Select Unlock Folder and enter your password.
3. Your files will be restored to plaintext on disk. They will be re-encrypted automatically when you "Lock" the folder or close Obsidian.

Locking a Folder

1. Right-click an unlocked folder.
2. Select Lock Folder.
3. The plugin will securely overwrite the content on disk with ciphertext, rename files to [name].locked, and create a README_ENCRYPTED.md with instructions.
4. The key is purged from memory for maximum security.

Auto-lock safeguards

• By default, unlocked folders are locked automatically when Obsidian moves to the background.
• By default, each unlocked folder is also locked after 5 minutes without activity in that folder.
• The status bar shows the next inactive folder due to lock, and a warning notice appears 60 seconds before auto-lock by default.
• Opening, editing, or otherwise working in files inside an unlocked folder refreshes that folder's inactivity timer.
• You can change both safeguards in Settings → Encrypted Folders.
• Set the inactivity timeout or warning seconds to 0 if you want to disable that safeguard.

Removing Encryption Permanently

1. Right-click an encrypted folder.
2. Select Permanently Decrypt Folder.
3. If the folder is locked, enter your password to restore files.
4. Confirm the permanent removal.
5. The plugin will restore all files to plaintext and delete the encryption metadata files (obsidian-folder-meta.json and README_ENCRYPTED.md).

Sync behavior across devices

• The plugin continuously rescans and reconciles encrypted-folder metadata after file create/modify/rename/delete events.
• If a sync operation lands while a folder is transitioning, metadata state (locking / unlocking) is reconciled on the receiving device.
• Background locking protects every unlocked folder at once, and per-folder inactivity locking reduces the chance that one forgotten unlocked folder stays open long enough to trigger cross-device sync conflicts.

🔒 Privacy & Telemetry

This plugin collects anonymous usage telemetry (via a self-hosted OpenPanel instance) to help improve the plugin. Telemetry is enabled by default but can be opted out of at any time in Settings → Encrypted Folders → Anonymous usage telemetry.

What is collected:

• Feature usage events (folder encrypted, unlocked, locked, auto-lock triggers, encryption removed) with coarse metadata such as file-count buckets (1-10, 11-100, 100+), plugin version, and platform (desktop/mobile).
• A random anonymous ID generated per vault. No account, email, or identifying information is collected.

What is never collected:

• Vault paths, folder names, filenames, file contents, passwords, recovery keys, or encryption keys.
• Anything that could identify you or the contents of your vault.

Network requests go only to the analytics host for event ingestion. No telemetry event ever blocks or affects encryption behavior — all reporting is best-effort and fire-and-forget.

🛠️ Development

Prerequisites

• NodeJS (v22+)
• bun (v1.3.9+)

Install Dependencies

npm install

Build & Dev

npm run dev   # Watch mode
npm run build # Production build
npm run lint  # Linting and type checking

📚 Documentation

• Documentation index - Map of all guides, references, and explanations.
• Getting started - Install the plugin and encrypt your first folder.
• Security spec - Algorithms, key derivation, and file formats.
• Threat model - What encryption protects and what it does not.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License. See LICENSE for details.

Support

If you find this plugin useful and want to support its development, you can buy me a coffee!

🤝 Author

Eric N. Garcia - eng618@garciaericn.com