feat: replace mail protocol with smolmail and rebuild the UI
This commit is contained in:
randogoth
parent
cb24b68069
commit
e94e4158cc
93 changed files with 6387 additions and 3479 deletions
107
README.md
107
README.md
|
|
@ -1,80 +1,67 @@
|
|||
# FlashMail
|
||||
# kirakira
|
||||
|
||||
FlashMail is a Mobile application designed to provide users with a temporary email solution powered by the mail.tm platform. With FlashMail, users can receive and view emails conveniently while maintaining their privacy. The app utilizes Riverpod as its state management solution for efficient and organized data handling.
|
||||
A mobile client for [Smol Mail](../smolmail), the minimalist end-to-end encrypted mail protocol: one Ed25519 identity, five operations, Noise_NX transport, sealed and signed messages. The sibling of the reference CLI client (`../smolmail`) and the browser client (`../gsmol`) — everything they do, in an Android app.
|
||||
|
||||
This repository contains the source code for FlashMail developed using the Flutter framework. The app is designed to provide various features and functionalities to enhance user experience. Below, you will find information about how to download the app, its features, dependencies, license, and more.
|
||||
## How it works
|
||||
|
||||
## Download
|
||||
```
|
||||
app (all crypto, all keys) ⇄ smolmaild (TCP :1961, Noise_NX)
|
||||
```
|
||||
|
||||
You can download the latest version of the app from the [GitHub Releases](https://github.com/sarthakkimtani/flash-mail/releases) page. Look for the most recent release and download the corresponding APK or installer file for your device.
|
||||
There is no bridge and no server-side account: the Noise session, sealing, signing, pinning and trust-on-first-use all run on the device. The seed lives in Hive app storage — the phone's app sandbox is the trust boundary, as with the CLI client's `identity.key` file.
|
||||
|
||||
## Requirements
|
||||
## First use
|
||||
|
||||
- Any Operating System (ie. MacOS X, Linux, Windows)
|
||||
- Any IDE with Flutter SDK installed (ie. IntelliJ, Android Studio, VSCode, etc)
|
||||
- A little knowledge of Dart and Flutter
|
||||
1. Create an identity (or restore from a seed) and back the seed up — it is the only secret.
|
||||
2. Pin your home server's public key, obtained from the operator through a trusted channel (SPEC.md §4: registration and fetching refuse unpinned servers).
|
||||
3. Register an address, then fetch. Restoring a seed on a new device? Enter the address alongside the seed — or "Recall" from settings — and it rebinds by RESOLVE + key check, without re-registering.
|
||||
|
||||
## Features
|
||||
## What it implements
|
||||
|
||||
- Instantly create temporary email addresses to receive messages without revealing your personal email.
|
||||
- Enjoy a seamless user experience with an intuitive and user-friendly interface, making it easy to navigate through your emails effortlessly.
|
||||
- Access and download attachments with ease, allowing you to view and save important files directly from your emails.
|
||||
- Access and read your emails effortlessly with a seamless viewing experience.
|
||||
- Benefit from a compact APK size of just 22 MB, ensuring that FlashMail takes up minimal storage space on your device.
|
||||
- **Identity** (§2): one 32-byte seed; the X25519 agreement keys are derived from the Ed25519 keypair. Superseded seeds are kept after rotation, since mail sealed to them is readable with nothing else.
|
||||
- **Addressing** (§3): short `user@host[:1961]` and self-certifying `smol://user@host/key` addresses; base32 fingerprints.
|
||||
- **Trust** (§4, §8): server keys pinned explicitly; mismatch aborts the handshake; registration and fetching require a pin.
|
||||
- **Mail** (§5): sealed and signed envelopes with 1 KiB padding, flat frontmatter bodies, sent copies sealed to self. Fetch verifies id and signature before acknowledging — anything unreadable stays on the server.
|
||||
- **Contacts**: outgoing mail carries a signed `Reply-To` field with the sender's full `smol://` address (an "anonymous" switch omits it); a first-contact claim binds only when its key matches the message's signer, and never over an address already pinned to a different key. The contacts screen shows each bound key with its trust badge and the keys it displaced — the only local record that a contact rotated — and a re-resolve applies §8: a chain-validated rotation is accepted and announced, an unexplained key change is refused until verified out of band. Trust warnings (unpinned sessions, rotations) persist on screen until dismissed, as the spec's §4/§8 messages demand.
|
||||
- **Rotation** (§7): rotate with a signed certificate; contacts accept the change from the chain.
|
||||
- **Backup**: settings can export the inbox, sent mail, contacts and server pins to one shareable file (and import it back) — the same JSON shape as gsmol's export, so backups move between the two clients. It never contains the seed, which has its own reveal-and-copy flow. Import never overwrites a pin or contact that already differs locally; malformed entries are skipped and counted.
|
||||
|
||||
## Screenshots
|
||||
## Layout
|
||||
|
||||
<img src="screenshots/1.png" height="300em" /> <img src="screenshots/2.png" height="300em" /> <img src="screenshots/3.png" height="300em" />
|
||||
<img src="screenshots/4.png" height="300em" />
|
||||
```
|
||||
lib/smol/crypto.dart SHA-2, HKDF, ChaCha20-Poly1305, X25519, Ed25519, §2 conversions
|
||||
lib/smol/noise.dart Noise_NX_25519_ChaChaPoly_SHA256 initiator
|
||||
lib/smol/proto.dart addresses, seal/unseal, frontmatter, rotation, op framing
|
||||
lib/smol/transport.dart TCP byte pipe (dart:io)
|
||||
lib/smol/store.dart Hive: identity, pins, contacts, sealed mail, export/import
|
||||
lib/smol/config.dart deploy-time preset server pin (--dart-define)
|
||||
lib/smol/client.dart connect/fetch/send/register/rotate flows
|
||||
lib/presentation/ the UI (Riverpod + auto_route)
|
||||
test/smol_test.dart byte-exact vectors + protocol cases
|
||||
test/store_test.dart contact key history, import
|
||||
test/widget_test.dart UI smoke test
|
||||
test/e2e_test.dart live round-trip against smolmaild
|
||||
```
|
||||
|
||||
## Installation
|
||||
The crypto is pure Dart, mirroring gsmol's dependency-free modules, so `test/vectors.json` — generated from the reference stack (PyNaCl, noiseprotocol) by `../gsmol/test/gen_vectors.py` — pins every operation byte for byte.
|
||||
|
||||
To run the app locally and make modifications, follow these steps:
|
||||
## Run and verify
|
||||
|
||||
1. Ensure you have Flutter SDK installed on your machine. You can download it from the official Flutter website: https://flutter.dev.
|
||||
2. Clone this repository to your local machine using the following command:<br>
|
||||
```bash
|
||||
git clone https://github.com/sarthakkimtani/flash-mail.git
|
||||
```
|
||||
3. Navigate to the project directory:<br><br>
|
||||
```bash
|
||||
cd flash-mail
|
||||
```
|
||||
4. Fetch the app's dependencies by running the following command:<br>
|
||||
```bash
|
||||
flutter pub get
|
||||
```
|
||||
5. Connect your device or start an emulator.
|
||||
6. Run the app using the following command:<br>
|
||||
```bash
|
||||
flutter run
|
||||
```
|
||||
```
|
||||
devbox run analyze
|
||||
devbox run test
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
Then `flutter run` with a device or emulator attached. `test/e2e_test.dart` additionally runs a live round-trip (register, send to self, fetch, unseal, drain) against `../smolmail/smolmaild.py` on `127.0.0.1:1961`, and self-skips when no server is listening.
|
||||
|
||||
| Name | Usage |
|
||||
| ------------------------------------------------------------------------- | --------------------------- |
|
||||
| [**Auto Route**](https://pub.dev/packages/auto_route) | Navigation & Routing |
|
||||
| [**Dio**](https://pub.dev/packages/dio) | HTTP Requests |
|
||||
| [**External Path**](https://pub.dev/packages/external_path) | External Storage Path |
|
||||
| [**Flash**](https://pub.dev/packages/flash) | Alerts & Dialogs |
|
||||
| [**Flutter Downloader**](https://pub.dev/packages/flutter_downloader) | Download Files |
|
||||
| [**Flutter InAppWebView**](https://pub.dev/packages/flutter_inappwebview) | In-App WebView |
|
||||
| [**Flutter Riverpod**](https://pub.dev/packages/flutter_riverpod) | Global State Management |
|
||||
| [**Freezed**](https://pub.dev/packages/freezed) | Code Generation |
|
||||
| [**Hive**](https://pub.dev/packages/hive) | Local Database |
|
||||
| [**Intl**](https://pub.dev/packages/intl) | Internationalization |
|
||||
| [**Shimmer**](https://pub.dev/packages/shimmer) | Shimmer for Loading Screens |
|
||||
| [**URL Launcher**](https://pub.dev/packages/url_launcher) | URL Launcher |
|
||||
Not verified here: clicking through the app on a real device — the logic under every button is what the tests exercise, as with gsmol.
|
||||
|
||||
## Contributing
|
||||
## Notes and limits
|
||||
|
||||
Contributions to this app are welcome! If you find any issues or have ideas for improvements, please open an issue or submit a pull request. Make sure to follow the repository's guidelines for contributing.
|
||||
- No server push or notifications in v1 (SPEC.md §13): tap fetch.
|
||||
- The seed sits in app storage: a compromised device is game over, same as a stolen `identity.key` file for the CLI client.
|
||||
- Rotation is not revocation (§7): a stolen key can rotate onward and the chain validates. The settings screen surfaces rotations instead of applying them invisibly; out-of-band re-verification is the only defence.
|
||||
|
||||
## License
|
||||
|
||||
This app is distributed under the [MIT License](https://github.com/sarthakkimtani/flash-mail/blob/main/LICENSE). Feel free to modify and use it as per your requirements.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
FlashMail is an independent project and is not affiliated with or endorsed by the mail.tm platform. Please review and comply with the terms of service of mail.tm when using this application.
|
||||
Distributed under the MIT License; see LICENSE.md.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue