feat(train): the person's key on Train's devices (ADR 0030, D15)

TrainKeys holds the one key everything of Train's is sealed with: made
on the first write where the account's keys are, kept in the synced
content_key rows sealed to the account, opened on the person's other
devices. Only keys sealed under Train's own IDs open, so the instance
can't relabel one, and a key the account sealed for another app never
counts; two devices that each made one offline write with the older. A
device without the account's keys opens and writes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

apps/train/halkyon_train_flutter/lib/src/core/privacy/content_key_gateway.dart

@@ -0,0 +1,17 @@
+import 'dart:typed_data';
+
+/// A `content_key` row (ADR 0030, D15): the key's ID as the row says it,
+/// which is never trusted, and the key sealed to the account.
+typedef ContentKeyRow = ({String dataKeyId, Uint8List sealedKey});
+
+/// Where the person's data keys are kept: their synced `content_key` rows.
+abstract interface class ContentKeyGateway() {
+  /// Every key row of the person's.
+  Future<List<ContentKeyRow>> all();
+
+  /// Keeps a new key.
+  Future<void> insert({
+    required String dataKeyId,
+    required Uint8List sealedKey,
+  });
+}

apps/train/halkyon_train_flutter/lib/src/core/privacy/train_keys.dart

@@ -0,0 +1,100 @@
+import 'dart:convert';
+import 'dart:math';
+
+import 'package:clock/clock.dart';
+import 'package:halkyon_app/halkyon_app.dart';
+import 'package:halkyon_train_flutter/src/core/privacy/content_key_gateway.dart';
+
+/// Refused: this device holds none of the account's keys (signed in without
+/// them), so it opens none of the person's data and writes none (ADR 0030,
+/// D15; as Learn's ADR 0019 has it).
+final class KeysMissing() implements Exception {
+  @override
+  String toString() => "KeysMissing: the account's keys aren't on this device";
+}
+
+/// The person's key on this device (ADR 0030, D15): one key, with which
+/// everything of Train's is sealed (D7), kept in their synced `content_key`
+/// rows sealed to the account, so their other devices open it.
+///
+/// A key's ID is sealed with it and signed by the account (halkyon_keys'
+/// `sealDataKey` opens a key only under the ID it was sealed with), so the
+/// instance can't relabel one, and only IDs of Train's own form are opened:
+/// a key the account sealed for another app (Learn's personal key) never
+/// counts here. Two devices that each made a key while offline both write
+/// with the older once they see both; every key that opens still reads.
+class TrainKeys(
+  final ContentKeyGateway _gateway,
+
+  /// Seals and opens with the keys; [TrainKeys] owns it.
+  final ContentCipher cipher,
+
+  /// The account's keys on this device; null where none are.
+  final Future<UnlockedAccountKeys?> Function() _accountKeys,
+) {
+  var _unlocked = false;
+  String? _writeKey;
+
+  /// Reads the key rows again and opens the person's keys among them: as
+  /// the person's data opens, and after a sync brought others' rows.
+  Future<void> refresh() async {
+    final account = await _accountKeys();
+    if (account == null) {
+      return;
+    }
+    if (!_unlocked) {
+      await cipher.unlock(account);
+      _unlocked = true;
+    }
+    for (final row in await _gateway.all()) {
+      final id = row.dataKeyId;
+      if (_madeAt(id) != null &&
+          (cipher.has(id) || cipher.openKey(id, row.sealedKey)) &&
+          _older(id, _writeKey)) {
+        _writeKey = id;
+      }
+    }
+  }
+
+  /// Whether what is sealed with the key [keyId] opens here.
+  bool canOpen(String keyId) =>
+      _unlocked && _madeAt(keyId) != null && cipher.has(keyId);
+
+  /// The key to seal with, made and kept the first time; throws
+  /// [KeysMissing] without the account's keys.
+  Future<String> keyToWrite() async {
+    if (_writeKey case final key?) {
+      return key;
+    }
+    if (!_unlocked) {
+      throw KeysMissing();
+    }
+    final random = Random.secure();
+    final nonce = base64Url
+        .encode([for (var i = 0; i < 12; i++) random.nextInt(256)])
+        .replaceAll('=', '');
+    final id = 'train1.${clock.now().toUtc().millisecondsSinceEpoch}.$nonce';
+    await _gateway.insert(dataKeyId: id, sealedKey: cipher.newKey(id));
+    return _writeKey = id;
+  }
+
+  /// Wipes the keys kept open here.
+  void dispose() => cipher.dispose();
+
+  /// When the key [id] was made, as its ID says (`train1.<ms>.<nonce>`);
+  /// null for an ID of another form, which is never Train's.
+  static int? _madeAt(String id) => switch (id.split('.')) {
+    ['train1', final ms, final nonce] when nonce.isNotEmpty => int.tryParse(ms),
+    _ => null,
+  };
+
+  /// Whether [id] was made before [other] (none at all: yes), ties going to
+  /// the smaller ID, so every device picks the same.
+  static bool _older(String id, String? other) {
+    if (other == null) {
+      return true;
+    }
+    final (a, b) = (_madeAt(id)!, _madeAt(other)!);
+    return a < b || (a == b && id.compareTo(other) < 0);
+  }
+}