Bramble

Abstract

1. Introduction

Your passwords are encrypted on your own device and stay there: in the browser's private extension storage, in ordinary files on your own disk in the desktop app, and in app-private encrypted storage on mobile. There's no server holding your vault and no account to sign up for. To use the same vault on more than one device, Bramble syncs it directly between your devices, peer-to-peer, end-to-end encrypted, with no cloud in the middle. Want a copy in your own hands? Export an encrypted backup file any time.

A password manager that keeps your secrets on your own devices. No account, no server holding your vault, no company to get breached and leak everything. You hold the vault, you hold the password, and that's it.

The same encrypted vault and the same Rust crypto core sit behind all four, and your devices can sync to each other directly, peer-to-peer, with no cloud in the middle.

2. Objective

Local-first password manager with direct device-to-device sync

This project demonstrates how TypeScript, Android can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• Local-first, always. Your vault is encrypted and stored on your own device (the browser's private storage in the extension, files on your own disk in the desktop app, app-private storage on mobile), never on a server.
• No shortcuts on crypto. Argon2id for your key, AES-256-GCM for the data, envelope encryption so every entry has its own key. Secrets get wiped from memory after use.
• Everything is encrypted. Site names, usernames, notes, all of it. The only readable part of the stored vault is its header.
• More than logins. Logins, payment cards, secure notes, and SSH keys, each with their own fields.
• Encrypted backups. Export your whole vault to an encrypted .bramble file whenever you want a copy in your own hands. It still needs your master password to open.
• Built-in password generator. Strong passwords on tap.
• Recovery codes. Every vault gets a high-entropy recovery code at setup: a printable backup that unlocks it independently of your master password. Shown once, stored offline, never kept in plaintext. Reset it any time.
• TOTP / 2FA codes. Paste an otpauth:// URI or bare secret and Bramble generates the six-digit codes.
• Peer-to-peer sync. Mirror your vault directly between your own devices over an end-to-end encrypted connection. No cloud, no relay holding your data.
• Breach checking. Optional Have I Been Pwned lookup using k-anonymity, so nothing about your password leaves your machine.

4. Technology Stack

• Autofill just works. Domain matching and an on-page dropdown in the browser, plus system autofill and passkeys on mobile, built in rather than bolted on.
• One opinionated, modern build instead of a sprawl of plugins and forks. Argon2id and AES-256-GCM out of the box.
• Modern UI. KeePass looks like it escaped from 2003 (no disrespect). Bramble is clean and fast, with dark mode and a layout that won't make you wince.

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Node.js (LTS) and npm / yarn / pnpm
• VS Code or any code editor
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/flythenimbus/bramble.git
cd bramble

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by flythenimbus and published on GitHub under the GNU General Public License v3.0. Please follow the license terms and credit the original author when you use or modify this code.