598 lines
22 KiB
Dart
598 lines
22 KiB
Dart
// App-level client: the flows of gsmol's app.js — connect with pinning, fetch
|
|
// with verification and acknowledgment, send with sent copies, contacts and
|
|
// rotation — on top of the pure protocol modules.
|
|
|
|
import "dart:convert";
|
|
import "dart:typed_data";
|
|
|
|
import "package:smol_mail/smol/crypto.dart";
|
|
import "package:smol_mail/smol/errors.dart";
|
|
import "package:smol_mail/smol/proto.dart";
|
|
import "package:smol_mail/smol/store.dart";
|
|
import "package:smol_mail/smol/transport.dart";
|
|
|
|
class RefreshOutcome {
|
|
final String message;
|
|
final bool warn;
|
|
|
|
const RefreshOutcome(this.message, this.warn);
|
|
}
|
|
|
|
class FetchSummary {
|
|
final int stored;
|
|
final List<String> rejected;
|
|
|
|
const FetchSummary(this.stored, this.rejected);
|
|
}
|
|
|
|
class OpenedRecord {
|
|
final String id;
|
|
final Uint8List? sender;
|
|
final int? time;
|
|
final Map<String, String> fields;
|
|
final String body;
|
|
final String? error;
|
|
|
|
const OpenedRecord(this.id,
|
|
{this.sender, this.time, this.fields = const {}, this.body = "", this.error});
|
|
|
|
String get subject => error == null ? (fields["subject"] ?? "") : "";
|
|
}
|
|
|
|
class SmolClient {
|
|
final SmolStore store;
|
|
|
|
/// Trust warnings (§4/§8) the UI must not let the user miss; the app wires
|
|
/// this to a persistent banner in app_widget.dart.
|
|
void Function(String message)? onWarning;
|
|
|
|
SmolClient(this.store);
|
|
|
|
void _warn(String message) => onWarning?.call(message);
|
|
|
|
// Opening an envelope costs an X25519 agreement and an Ed25519
|
|
// verification, and an envelope's plaintext never changes — so the result
|
|
// is kept. Failures are cached too, so one bad message is not retried on
|
|
// every render. Rotation clears it, since the key set grew.
|
|
final _openedCache = <String, OpenedRecord>{};
|
|
|
|
SmolIdentity? get identity => store.identity();
|
|
|
|
Uint8List? get master => store.master();
|
|
|
|
SmolAddress? accountAddress() {
|
|
final account = store.account();
|
|
if (account == null) return null;
|
|
final suffix = account.port == defaultPort ? "" : ":${account.port}";
|
|
return parseAddress("${account.user}@${account.host}$suffix");
|
|
}
|
|
|
|
// §4: registration and fetching demand a pinned key; sending to a recipient
|
|
// whose key we already hold tolerates an unpinned server.
|
|
Future<OpenedSession> connect(SmolAddress addr,
|
|
{required bool requirePin}) async {
|
|
final pinned = store.serverPin(addr.host);
|
|
if (requirePin && pinned == null) {
|
|
throw SmolError("no pinned key for ${addr.host}. Obtain it from the "
|
|
"operator through a trusted channel, then pin it in settings.");
|
|
}
|
|
final wire = await TcpWire.connect(addr.host, addr.port);
|
|
try {
|
|
final opened = await openSession(wire, addr.host, pinned: pinned);
|
|
if (pinned == null) {
|
|
_warn("${addr.host} is not pinned; its key is "
|
|
"${b32encode(opened.serverStatic)}.\n"
|
|
"RESOLVE results from this session are UNVERIFIED (SPEC.md §8).");
|
|
}
|
|
return opened;
|
|
} catch (_) {
|
|
wire.close();
|
|
rethrow;
|
|
}
|
|
}
|
|
|
|
// --- identity setup ------------------------------------------------------------
|
|
|
|
/// A fresh master secret at rotation index 0. Only this local step; nothing
|
|
/// is sent until [registerAccount].
|
|
Uint8List createIdentity() {
|
|
final fresh = randomBytes(keyLen);
|
|
store.setMaster(fresh);
|
|
return fresh;
|
|
}
|
|
|
|
/// §2: a master alone does not say which rotation index a server has bound,
|
|
/// so restoring resolves the address and walks indices 0..[maxChain] until
|
|
/// one derives the key RESOLVE returned. Also binds "account" locally, like
|
|
/// [recallAccount] — restoring on a new device knows the identity but not
|
|
/// the address it was registered under.
|
|
Future<SmolAddress> restoreAndRecall(String masterHex, String addressText) async {
|
|
Uint8List master;
|
|
try {
|
|
master = unhex(masterHex.trim());
|
|
} on Exception {
|
|
throw const SmolError("master must be 64 hex characters");
|
|
}
|
|
if (master.length != keyLen) {
|
|
throw SmolError("master is ${master.length} bytes, expected $keyLen");
|
|
}
|
|
final addr = parseAddress(addressText);
|
|
final opened = await connect(addr, requirePin: true);
|
|
Uint8List current;
|
|
try {
|
|
current = (await resolveOp(opened.session, addr.user)).identity;
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
int? found;
|
|
for (var n = 0; n <= maxChain; n++) {
|
|
if (timingSafeEqual(identityFromSeed(identitySeed(master, n)).publicKey, current)) {
|
|
found = n;
|
|
break;
|
|
}
|
|
}
|
|
if (found == null) {
|
|
throw SmolError("the key bound to ${addr.short} is not derived from "
|
|
"this master within $maxChain rotations");
|
|
}
|
|
store.restoreMaster(master, found);
|
|
store.setAccount(addr);
|
|
return addr;
|
|
}
|
|
|
|
void pinServer(String host, String keyB32) {
|
|
final key = b32decode(keyB32);
|
|
if (key.length != keyLen) {
|
|
throw SmolError("server key is ${key.length} bytes, expected $keyLen");
|
|
}
|
|
store.pinServer(host.trim().toLowerCase(), key);
|
|
}
|
|
|
|
Future<void> registerAccount(String addressText, {String token = ""}) async {
|
|
final me = identity;
|
|
if (me == null) throw const SmolError("no identity yet");
|
|
final addr = parseAddress(addressText);
|
|
final opened = await connect(addr, requirePin: true);
|
|
try {
|
|
await registerOp(opened.session, opened.serverStatic, addr.user, me,
|
|
RegisterOptions(token: token));
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
store.setAccount(addr);
|
|
}
|
|
|
|
/// Restoring a master brings back the identity, not the memory of what
|
|
/// address a *different device* registered it under — "account" is
|
|
/// local-only state, never asked of the server. This binds it without
|
|
/// REGISTER: RESOLVE the address and require it name this exact key, so a
|
|
/// typo or someone else's address cannot misfile fetch and Reply-To.
|
|
Future<SmolAddress> recallAccount(String addressText) async {
|
|
final me = identity;
|
|
if (me == null) throw const SmolError("no identity yet");
|
|
final addr = parseAddress(addressText);
|
|
final opened = await connect(addr, requirePin: true);
|
|
Uint8List current;
|
|
try {
|
|
current = (await resolveOp(opened.session, addr.user)).identity;
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
if (!timingSafeEqual(current, me.publicKey)) {
|
|
throw SmolError(
|
|
"${addr.short} resolves to a different key — not this identity");
|
|
}
|
|
store.setAccount(addr);
|
|
return addr;
|
|
}
|
|
|
|
// --- fetch ----------------------------------------------------------------------
|
|
|
|
Future<FetchSummary> fetch() async {
|
|
final me = identity;
|
|
final master = this.master;
|
|
final addr = accountAddress();
|
|
if (me == null || master == null) throw const SmolError("no identity yet");
|
|
if (addr == null) {
|
|
throw const SmolError("not registered; register an address first");
|
|
}
|
|
var stored = 0;
|
|
final rejected = <String>[];
|
|
// §10: acknowledging (deleting) is the default; "leave mail on server"
|
|
// pages forward by cursor instead, so already-fetched mail is never
|
|
// re-downloaded even though it isn't deleted (store.storeIfNew also
|
|
// dedupes, as a second line of defense).
|
|
final leaveOnServer = store.leaveOnServer();
|
|
var (afterTime, afterId) = store.cursor();
|
|
final opened = await connect(addr, requirePin: true);
|
|
try {
|
|
final (sync, tokens) = store.tokenSet(master);
|
|
await authenticate(opened.session, opened.handshakeHash, addr.user, me,
|
|
sync: sync, tokens: tokens);
|
|
while (true) {
|
|
final records = await fetchOp(opened.session, afterTime, afterId);
|
|
if (records.isEmpty) break;
|
|
final acked = <Uint8List>[];
|
|
for (final record in records) {
|
|
afterTime = record.receivedAt;
|
|
afterId = record.id;
|
|
OpenedMessage msg;
|
|
try {
|
|
if (!timingSafeEqual(messageId(record.envelope), record.id)) {
|
|
throw const SmolError("id does not match the envelope");
|
|
}
|
|
msg = unseal(store.identities(), record.envelope);
|
|
} on SmolError catch (err) {
|
|
// Left on the server rather than destroyed, so a client-side bug
|
|
// cannot lose mail.
|
|
rejected.add("${hex(record.id)}: ${err.message}");
|
|
continue;
|
|
}
|
|
final fresh = await store.storeIfNew(
|
|
"inbox",
|
|
MailRecord(hex(record.id), record.envelope,
|
|
receivedAt: record.receivedAt,
|
|
tier: record.isRequest ? tierRequests : tierMain,
|
|
keptOnServer: leaveOnServer));
|
|
if (fresh != null) {
|
|
stored++;
|
|
_learnToken(msg);
|
|
}
|
|
acked.add(record.id);
|
|
}
|
|
if (leaveOnServer) {
|
|
// Persisted per batch, so an interrupted fetch resumes here rather
|
|
// than re-paging from the start next time.
|
|
store.setCursor(afterTime, afterId);
|
|
} else if (acked.isNotEmpty) {
|
|
await deleteOp(opened.session, acked);
|
|
}
|
|
}
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
if (!leaveOnServer) {
|
|
// Everything acknowledged is deleted, so the next fetch starts fresh; a
|
|
// record left on the server (rejected above) simply resurfaces then.
|
|
store.setCursor(0, Uint8List(idLen));
|
|
}
|
|
return FetchSummary(stored, rejected);
|
|
}
|
|
|
|
// --- delete ------------------------------------------------------------------
|
|
|
|
/// Deletes a message locally, and from the server too if it might still be
|
|
/// sitting there (only possible when "leave mail on server" was on when it
|
|
/// was fetched — §10). Sent copies are local-only; there is nothing
|
|
/// server-side to remove for them (§5.6). Throws, leaving the local copy in
|
|
/// place, if a needed server-side delete fails — otherwise a message could
|
|
/// look gone locally while silently persisting on the server.
|
|
Future<void> deleteMessage(String folder, MailRecord record) async {
|
|
if (folder != "sent" && record.keptOnServer) {
|
|
final me = identity;
|
|
final addr = accountAddress();
|
|
if (me == null || addr == null) {
|
|
throw const SmolError(
|
|
"not registered; cannot reach the server to delete this message");
|
|
}
|
|
final opened = await connect(addr, requirePin: true);
|
|
try {
|
|
await authenticate(opened.session, opened.handshakeHash, addr.user, me,
|
|
sync: 0, tokens: const []);
|
|
await deleteOp(opened.session, [unhex(record.id)]);
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
}
|
|
await store.deleteMessage(folder, record.id);
|
|
}
|
|
|
|
// §5.8: an Accept field is bound to the signer of the message that carried
|
|
// it, which unseal() has already verified.
|
|
void _learnToken(OpenedMessage msg) {
|
|
final parsed = parseFrontmatter(utf8.decode(msg.body, allowMalformed: true));
|
|
final raw = parsed.fields["accept"];
|
|
if (raw == null) return;
|
|
Uint8List token;
|
|
try {
|
|
token = b32decode(raw);
|
|
} on SmolError {
|
|
return;
|
|
}
|
|
if (token.length != tokenLen) return;
|
|
final address = _addressOfSigner(msg.sender, parsed.fields["reply-to"]);
|
|
if (address == null) return; // no address to send to, so no use for a token
|
|
store.learnToken(address, token);
|
|
}
|
|
|
|
/// The address we know a signer by: a contact, or the Reply-To it signed
|
|
/// for itself. Naming a mailbox is not trusting a key, so nothing is
|
|
/// pinned here (§5.7, §8).
|
|
String? _addressOfSigner(Uint8List sender, String? replyTo) {
|
|
final known = store.addressForKey(sender);
|
|
if (known != null) return known;
|
|
if (replyTo == null) return null;
|
|
try {
|
|
final parsed = parseAddress(replyTo);
|
|
if (parsed.identity != null && timingSafeEqual(parsed.identity!, sender)) {
|
|
return parsed.short;
|
|
}
|
|
} on SmolError {
|
|
// malformed claim: no address to learn a token under
|
|
}
|
|
return null;
|
|
}
|
|
|
|
// --- accept tokens (§5.8) --------------------------------------------------------
|
|
|
|
/// Admit a contact to the main tier; their token travels in our next
|
|
/// message to them. Pushes the change to the server right away, since an
|
|
/// accept or a block only takes effect once it holds the changed set.
|
|
Future<int> acceptContact(String address) async {
|
|
final key = store.contact(address)?.key;
|
|
if (key == null) throw SmolError("no key for $address yet");
|
|
store.accept(address, key);
|
|
store.setSyncOk(true);
|
|
return _pushTokens();
|
|
}
|
|
|
|
/// Withdraw a contact's accept token; their mail lands in requests from
|
|
/// their next message on.
|
|
Future<int> blockContact(String address) async {
|
|
store.block(address);
|
|
return _pushTokens();
|
|
}
|
|
|
|
Future<int> _pushTokens() async {
|
|
final me = identity;
|
|
final master = this.master;
|
|
final addr = accountAddress();
|
|
if (me == null || master == null) throw const SmolError("no identity yet");
|
|
if (addr == null) {
|
|
_warn("not registered; the set will be pushed with your first fetch");
|
|
return 0;
|
|
}
|
|
final opened = await connect(addr, requirePin: true);
|
|
try {
|
|
final (sync, tokens) = store.tokenSet(master);
|
|
return await authenticate(opened.session, opened.handshakeHash, addr.user, me,
|
|
sync: sync, tokens: tokens);
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
}
|
|
|
|
// --- compose and send -----------------------------------------------------------
|
|
|
|
// Prefer a key we already trust; fall back to RESOLVE with trust on first
|
|
// use.
|
|
Future<Uint8List> resolveRecipient(SmolAddress addr) async {
|
|
if (addr.identity != null) {
|
|
store.saveContact(addr.short, addr.identity!, true);
|
|
return addr.identity!;
|
|
}
|
|
final known = store.contact(addr.short);
|
|
if (known != null) return known.key;
|
|
final opened = await connect(addr, requirePin: false);
|
|
Uint8List current;
|
|
try {
|
|
current = (await resolveOp(opened.session, addr.user)).identity;
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
store.saveContact(addr.short, current, false);
|
|
return current;
|
|
}
|
|
|
|
Future<String> send(String toText, String subject, String body,
|
|
{String? replyTo, bool anonymous = false}) async {
|
|
final me = identity;
|
|
final master = this.master;
|
|
if (me == null || master == null) throw const SmolError("no identity yet");
|
|
final addr = parseAddress(toText);
|
|
final recipient = await resolveRecipient(addr);
|
|
final account = accountAddress();
|
|
final fields = <String, String>{"Subject": subject, "In-Reply-To": replyTo ?? ""};
|
|
// A signed Reply-To lets a first-time recipient name and answer us
|
|
// (§5.5 allows unknown keys); "anonymous" omits it.
|
|
if (account != null && !anonymous) {
|
|
fields["Reply-To"] = account.uri(me.publicKey);
|
|
}
|
|
// §5.8: hand an accepted correspondent the token for our own mailbox, so
|
|
// a first reply from them reaches our main tier.
|
|
final accepted = store.accepted(addr.short);
|
|
if (accepted != null && accepted.active) {
|
|
fields["Accept"] = b32encode(tokenFor(master, accepted.identity));
|
|
}
|
|
final bodyBytes = utf8Bytes(buildFrontmatter(
|
|
fields, "${body.replaceFirst(RegExp(r"\s+$"), "")}\n"));
|
|
final envelope = seal(me, recipient, bodyBytes);
|
|
// §5.8: our token for their mailbox, if they have given us one.
|
|
final held = store.tokenFrom(addr.short);
|
|
final mac = held == null ? null : acceptMac(held, messageId(envelope));
|
|
final opened = await connect(addr, requirePin: false);
|
|
try {
|
|
await sendOp(opened.session, envelope, mac: mac);
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
// §5.6: the ephemeral is gone, so keep a copy sealed to ourselves.
|
|
await store.storeMessage("sent", MailRecord(hex(messageId(envelope)),
|
|
seal(me, me.publicKey, bodyBytes),
|
|
recipient: addr.short, sentAt: nowSeconds()));
|
|
return addr.short;
|
|
}
|
|
|
|
// --- reading -----------------------------------------------------------------
|
|
|
|
// What is known about a sender changes as the user binds addresses to keys,
|
|
// so this layer sits over the cached envelope and is recomputed per call —
|
|
// it is a map lookup, not crypto.
|
|
OpenedRecord describe(MailRecord row) {
|
|
final opened = _openEnvelope(row);
|
|
if (opened.error != null) return opened;
|
|
return OpenedRecord(
|
|
row.id,
|
|
sender: opened.sender,
|
|
time: opened.time,
|
|
fields: opened.fields,
|
|
body: opened.body,
|
|
);
|
|
}
|
|
|
|
OpenedRecord _openEnvelope(MailRecord row) {
|
|
var entry = _openedCache[row.id];
|
|
if (entry == null) {
|
|
try {
|
|
final opened = unseal(store.identities(), row.envelope);
|
|
final parsed = parseFrontmatter(utf8.decode(opened.body, allowMalformed: true));
|
|
entry = OpenedRecord(row.id,
|
|
sender: opened.sender,
|
|
time: opened.time,
|
|
fields: parsed.fields,
|
|
body: parsed.body);
|
|
} on SmolError catch (err) {
|
|
entry = OpenedRecord(row.id, error: err.message);
|
|
}
|
|
_openedCache[row.id] = entry;
|
|
}
|
|
return entry;
|
|
}
|
|
|
|
/// The Reply-To address carried inside the message, but only when it is a
|
|
/// full smol:// URI whose key matches the signer (§5.7); anything else is
|
|
/// ordinary text.
|
|
SmolAddress? replyAddress(OpenedRecord opened) {
|
|
final claim = opened.fields["reply-to"];
|
|
if (claim == null || opened.sender == null) return null;
|
|
try {
|
|
final parsed = parseAddress(claim);
|
|
if (parsed.identity != null &&
|
|
timingSafeEqual(parsed.identity!, opened.sender!)) {
|
|
return parsed;
|
|
}
|
|
} on SmolError {
|
|
// malformed claim: display, never bind
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/// Bind a user-supplied address to the key that signed a message. A smol://
|
|
/// address carries its own key (verified); a short address is resolved and
|
|
/// the result kept on first use. Anything that binds a different key is
|
|
/// refused.
|
|
Future<void> nameSender(String text, Uint8List senderKey) async {
|
|
final addr = parseAddress(text.trim());
|
|
Uint8List key;
|
|
var verified = true;
|
|
if (addr.identity == null) {
|
|
final opened = await connect(addr, requirePin: false);
|
|
try {
|
|
key = (await resolveOp(opened.session, addr.user)).identity;
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
verified = false; // trust on first use, as with any RESOLVE
|
|
} else {
|
|
key = addr.identity!;
|
|
}
|
|
if (!timingSafeEqual(key, senderKey)) {
|
|
throw const SmolError(
|
|
"that address carries a different key than this message's sender");
|
|
}
|
|
store.saveContact(addr.short, senderKey, verified);
|
|
}
|
|
|
|
/// A signed Reply-To is the sender's own claim, so it saves as verified —
|
|
/// but never over an address already pinned to a different key (§8: a key
|
|
/// change without a rotation chain needs out-of-band confirmation).
|
|
Future<void> saveReplyAddress(SmolAddress addr, Uint8List senderKey) async {
|
|
final existing = store.contact(addr.short);
|
|
if (existing != null && !timingSafeEqual(existing.key, senderKey)) {
|
|
throw SmolError("${addr.short} is already known with a different key — "
|
|
"verify out of band before replying");
|
|
}
|
|
store.saveContact(addr.short, senderKey, true);
|
|
}
|
|
|
|
// Re-resolve a contact and apply §8: a valid rotation chain is accepted and
|
|
// surfaced; anything else requires out-of-band verification.
|
|
Future<RefreshOutcome> refreshContact(String address) async {
|
|
final addr = parseAddress(address);
|
|
if (addr.identity != null) {
|
|
throw const SmolError("that address already carries a key; use import instead");
|
|
}
|
|
final known = store.contact(addr.short);
|
|
final opened = await connect(addr, requirePin: false);
|
|
Resolved resolved;
|
|
try {
|
|
resolved = await resolveOp(opened.session, addr.user);
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
if (known == null) {
|
|
store.saveContact(addr.short, resolved.identity, false);
|
|
return RefreshOutcome(
|
|
"${addr.short} pinned (trust on first use"
|
|
"${opened.pinned ? "" : ", UNVERIFIED server"})",
|
|
!opened.pinned);
|
|
}
|
|
if (timingSafeEqual(known.key, resolved.identity)) {
|
|
return RefreshOutcome("${addr.short}: key unchanged", false);
|
|
}
|
|
if (walkChain(addr.user, known.key, resolved.identity, resolved.chain)) {
|
|
store.saveContact(addr.short, resolved.identity, known.verified);
|
|
return RefreshOutcome(
|
|
"${addr.short} rotated its key; a signed chain confirms it.\n"
|
|
"now ${b32encode(resolved.identity)}",
|
|
true);
|
|
}
|
|
return RefreshOutcome(
|
|
"${addr.short} presents a different key with no valid rotation chain.\n"
|
|
"Verify out of band, then import the new smol:// address.",
|
|
true);
|
|
}
|
|
|
|
// Bind a smol:// address to the key it carries (§8's strong path); the
|
|
// displaced key, if any, lands in the contact's history.
|
|
void importContact(String text) {
|
|
final addr = parseAddress(text.trim());
|
|
if (addr.identity == null) {
|
|
throw const SmolError("import needs a smol:// address carrying a key");
|
|
}
|
|
store.saveContact(addr.short, addr.identity!, true);
|
|
}
|
|
|
|
// --- rotation -----------------------------------------------------------------
|
|
|
|
// §7: rotate to the next index's derived key and rebind the account with a
|
|
// signed certificate. The superseded key stays derivable from the master,
|
|
// since mail sealed to it stays readable with nothing else.
|
|
Future<SmolIdentity> rotateIdentity() async {
|
|
final me = identity;
|
|
final master = this.master;
|
|
final addr = accountAddress();
|
|
if (me == null || master == null || addr == null) {
|
|
throw const SmolError("rotate needs a registered account");
|
|
}
|
|
final freshSeed = identitySeed(master, store.rotations() + 1);
|
|
final fresh = identityFromSeed(freshSeed);
|
|
final cert = makeCert(addr.user, me, freshSeed);
|
|
final opened = await connect(addr, requirePin: true);
|
|
try {
|
|
await registerOp(opened.session, opened.serverStatic, addr.user, fresh,
|
|
RegisterOptions(cert: cert));
|
|
} finally {
|
|
opened.session.wire.close();
|
|
}
|
|
store.advanceRotation();
|
|
_openedCache.clear();
|
|
return fresh;
|
|
}
|
|
|
|
// A full wipe: every secret and every stored envelope. The UI must confirm.
|
|
Future<void> wipe() async {
|
|
await store.wipe();
|
|
_openedCache.clear();
|
|
}
|
|
}
|