# Obsidian Encrypted Folders

[![GitHub Release](https://img.shields.io/github/v/release/eng618/obsidian-encrypted-folders?style=flat-square)](https://github.com/eng618/obsidian-encrypted-folders/releases)
[![CI](https://img.shields.io/github/actions/workflow/status/eng618/obsidian-encrypted-folders/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/eng618/obsidian-encrypted-folders/actions/workflows/ci.yml)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/0e0baf5377694cc69afdad1e887e0380)](https://app.codacy.com/gh/ENG618/obsidian-encrypted-folders/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![Codacy Coverage](https://app.codacy.com/project/badge/Coverage/0e0baf5377694cc69afdad1e887e0380)](https://app.codacy.com/gh/ENG618/obsidian-encrypted-folders/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
[![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2Fmaster%2Fcommunity-plugin-stats.json&query=%24%5B%22obsidian-encrypted-folders%22%5D.downloads&logo=obsidian&logoColor=white&label=downloads&color=purple&style=flat-square)](https://obsidian.md/plugins?id=obsidian-encrypted-folders)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feng618%2Fobsidian-encrypted-folders.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Feng618%2Fobsidian-encrypted-folders?ref=badge_shield)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=eng618&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/eng618)

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**: Generate a 32-character recovery key during setup to ensure you never lose access to your data.
- **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.

## 🛡️ Security Specifications

- **Algorithm**: AES-256-GCM (Authenticated Encryption with Associated Data).
- **Key Derivation**: PBKDF2-SHA256 with **600,000 iterations**.
- **Implementation**: Native [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/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.

## 🛠️ Development

### Prerequisites

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

### Install Dependencies

```bash
npm install
```

### Build & Dev

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

## 📚 Documentation

- [Technical Walkthrough](./docs/WALKTHROUGH.md) - Deep dive into how it works.
- [Development Plan](./docs/DEVELOPMENT_PLAN.md) - Roadmap and project status.

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## 📄 License

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feng618%2Fobsidian-encrypted-folders.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Feng618%2Fobsidian-encrypted-folders?ref=badge_large)

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!

[![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%22☕%22&slug=eng618&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/eng618)

## 🤝 Author

**Eric N. Garcia** - [eng618@garciaericn.com](mailto:eng618@garciaericn.com)