randogoth/kirakira
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite README as a brief overview crediting FlashMail origin

Browse source
This commit is contained in:
randogoth 2026-09-26 22:51:29 +03:00
parent e94e4158cc
commit 0ba82370f1
1 changed files with 17 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

60
README.md
View file

@ -1,67 +1,41 @@
# kirakira # kirakira
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. A mobile client for [Smol Mail](https://smol.place), a minimalist end-to-end encrypted mail protocol: one Ed25519 identity, five operations, sealed and signed messages over a Noise_NX transport. Sibling of the reference CLI client (`https://smol.place`) and the browser client (`https://code.randogoth.com/randogoth/gsmol`).
## How it works kirakira began as [FlashMail](https://github.com/sarthakkimtani/flash-mail), a Flutter UI template for a disposable-email app built on mail.tm. Its networking layer was replaced end to end with a from-scratch Smol Mail implementation (`lib/smol/`: crypto, Noise handshake, framing, client flows), and the UI was redesigned around a Material 3 theme — dark navy and mint green by default, with a matching light theme — built from a single `ColorScheme` and `AppColors` extension rather than hardcoded colors per screen.
``` ## What it does
app (all crypto, all keys) ⇄ smolmaild (TCP :1961, Noise_NX)
```
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. - Create or restore an identity from a 32-byte seed — that's the only secret.
- Pin a server's key, register or recall an address, then fetch and send sealed mail.
## First use - Trust-on-first-use for server and contact keys, with rotation support and on-screen warnings for anything unverified.
- Export/import inbox, sent mail, contacts and server pins as one shareable backup file — never the seed.
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.
## What it implements
- **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.
## Layout ## Layout
``` ```
lib/smol/crypto.dart SHA-2, HKDF, ChaCha20-Poly1305, X25519, Ed25519, §2 conversions lib/smol/ the protocol: crypto, Noise handshake, framing, client flows
lib/smol/noise.dart Noise_NX_25519_ChaChaPoly_SHA256 initiator lib/presentation/ screens, widgets and theme (Riverpod + auto_route)
lib/smol/proto.dart addresses, seal/unseal, frontmatter, rotation, op framing lib/data/ Riverpod providers
lib/smol/transport.dart TCP byte pipe (dart:io) test/ protocol vectors, store tests, a live e2e round-trip
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
``` ```
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.
## Run and verify ## Run and verify
``` ```
devbox run analyze devbox run analyze
devbox run test devbox run test
flutter run
``` ```
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. `test/e2e_test.dart` runs a live round-trip against `https://smol.place/smolmaild.py` on `127.0.0.1:1961` and skips itself when nothing's listening there.
Not verified here: clicking through the app on a real device — the logic under every button is what the tests exercise, as with gsmol.
## Notes and limits ## Notes and limits
- No server push or notifications in v1 (SPEC.md §13): tap fetch. - No server push in v1 — fetch is manual.
- The seed sits in app storage: a compromised device is game over, same as a stolen `identity.key` file for the CLI client. - The seed lives in app storage; a compromised device is a compromised identity.
- 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. - Rotation isn't revocation — a stolen key can still rotate onward. Settings surfaces rotations for out-of-band verification rather than applying them silently.
## License ## License
Distributed under the MIT License; see LICENSE.md. MIT — see LICENSE.md.