MayflyPass

An end-to-end-encrypted TOTP manager, with a lightweight Rust API and a Flutter app that keeps your codes in sync across devices.
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Encryption
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

Home	Add account (QR)	Add account (manual)	Settings

MayflyPass is a monorepo containing two components:

• api/ — A small, resource-efficient Rust backend that can run on very little hardware. It knows nothing about your TOTP secrets — it's a zero-knowledge blob store: storage only ever holds an encrypted key and an encrypted payload per item, both opaque to the server. Registration is gated behind a lightweight proof-of-work challenge to deter bots, and authentication uses short-lived tokens with a refresh/login/logout flow, backed by strong password hashing.
• app/ — A Flutter app that manages your TOTP entries entirely client-side. Secrets are added either by scanning a QR code or manual entry, stored locally on the device, and displayed on the home screen with a live rotating code and countdown timer.

(back to top)

Encryption

MayflyPass uses envelope encryption end-to-end, so the server only ever sees ciphertext:

• The master password is hashed using Argon2id.
• A KEK (key-encryption-key) is derived from that hash using HKDF.
• Each entry gets its own random 32-bytes DEK (data-encryption-key), which is encrypted with the KEK using XChaCha20-Poly1305.
• The TOTP codes themselves are encrypted with their DEK using XChaCha20-Poly1305.

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

Getting Started

To get a local copy up and running follow these steps.

Prerequisites

• Rust toolchain (cargo), for the API
• Flutter Version Management (fvm), for the app
• protoc, to compile proto/databox.proto into the app's Dart bindings

Installation

1. Clone the repo

   git clone git@github.com:tuxlinuxien/mayflypass.git

2. Run the API (SQLite database and migrations are handled automatically via sqlx)

   cd api
   cargo run

3. Build and run the app

   cd app
   fvm flutter pub get
   make build   # codegen, l10n, and protobuf bindings from proto/databox.proto
   fvm flutter run [-D API_URL=http://<ip or domain>[:<port>] ]

(back to top)

Usage

Current tested target devices:

• Android
• Linux

Note on iOS: I don't have a Mac nor a developer account, so I can't test whether the app runs properly, and I'm sure the Podfiles are missing important updates. if you have the opportunity to run it, feel free to create a merge request on github.

(back to top)

Roadmap

• iOS support
• Windows support

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/tuxlinuxien/mayflypass

(back to top)