SecureLocal Drive 🔐

SecureLocal Drive is a lightweight, offline, military-grade secure local file management system built on Python and Vanilla Javascript, with absolutely no external remote dependencies. It is designed to act as your own personal, high-security vault that runs completely locally on your machine.

---

🚀 Getting Started

1. Requirements & Installations

You will need Python 3.8+ installed on your computer.

To run the server, you need to install standard Python libraries for the backend (FastAPI, cryptography). Open a terminal in this directory and run: pip install -r requirements.txt

(Or pip3 install -r requirements.txt if you are on Mac/Linux).

2. How to Start the Server

• Windows: Simply double-click the run_server.bat file in this folder. It will start the server and automatically open the application in your browser.
• Mac/Linux: Double-click run_server.sh or run ./run_server.sh in the terminal.
• Manual Start: If the scripts give you trouble, you can manually type: python -m uvicorn src.main:app --port 8000

Once started, open your web browser and go to: http://localhost:8000

(The default first-time login is Username: admin, Password: admin123)

3. How to Stop the Server

When you are done using your drive and want to secure everything:

Graceful Shutdown (Recommended):

1. Go back to the black Command Prompt / Terminal window where the server is running.
2. Press Ctrl + C on your keyboard. This will safely kill the server connection, save your current states, and completely free up Port 8000. It is safe to close the window after this.

Forced Shutdown (If Port 8000 gets stuck): If you accidentally click the "X" on the window instead of using Ctrl+C, the server might remain running silently in your system cache and refuse to let the port go! If you ever launch the app and it is stuck on a grey loading screen, run this command to forcefully kill it:

• Windows: Open a new Command Prompt and type taskkill /F /IM python.exe
• Mac/Linux: Open terminal and type pkill -f uvicorn

---

🏗 How It Works

SecureLocal Drive is essentially composed of two layers: your Interface, and your Secure Vault.

1. You upload a file: When you upload a file, you'll be asked to provide an encryption password.
2. Encryption: Before the file touches the hard drive, your custom password is run through 100,000 algorithmic cycles (PBKDF2) to generate a massive encryption key. The backend encrypts your file using Industry Standard AES-256-CBC.
3. Storage: The raw unencrypted file is wiped from memory, and only an unrecognizable .enc snippet is saved to the hard drive.
4. Hashing: A SHA-256 "digital fingerprint" is taken of the file to guarantee an attacker cannot secretly manipulate the encrypted blob on your disk without triggering an alert when you download it later.

---

📂 The File Architecture (Where does data go?)

When you use the app, all logic runs from the src/ and static/ folders, but your actual sensitive data is held exclusively in the vault/ folder!

The Encrypted Files (vault/*.enc)

Any file you upload is instantly encrypted into a blob (e.g., 1a2b3c...enc) and dropped into the vault/ folder. The actual filename (e.g., tax_returns.pdf) is never saved on your hard drive operating system to protect you from search indexing and snooping!

The SQLite Database (vault/metadata.db)

Inside the vault folder is a single database file called metadata.db. This is the nervous system of the tracker. It NEVER holds the contents of your secure files, but it tracks their metadata. It contains:

• users: Contains all your accounts and their access roles (Admin/User and Upload Permissions).
• files & versions: Stores the original human-readable names mapping to the unrecognizable blobs. Also securely logs the SHA-256 hashes for data integrity.
• audit_logs: Remembers who uploaded, downloaded, or deleted files.

If you ever want to backup your drive, simply backup your entire vault/ folder.

---

⚠️ Important Troubleshooting & Security Risks

What happens if I forget my file encryption password?

Caution

Your file is gone forever. SecureLocal Drive executes proper "Zero Knowledge" symmetrical encryption. Because we never transmit your password or store it in the SQLite database, neither the system nor an Admin can help you recover a file encrypted with a forgotten password. The math physically prevents recovery without brute-forcing the AES-256 key. Do not forget the password you used!

What if I am unable to start the application?

1. Ensure no other applications are running on Port 8000.
2. Ensure you have installed the correct dependencies. Check requirements.txt specifically checking if your Python version is compatible with the cryptography module.
3. If the server locks up completely and the web browser spins on a grey screen indefinitely, you likely have old zombie python processes still running. Open Task Manager and forcibly end task on all python.exe background tasks, then double-click run_server.bat again cleanly.

Deploying for Production?

Important

If you are setting this up for a real-world office or exposed network, you should modify your cryptographic token signature. Open src/security.py and change the SECRET_KEY = "super-secret-key-change-in-production" to a completely random generated string unique to your machine. This prevents attackers who also downloaded this software from spoofing login sessions!