feat(sync): optional end-to-end encryption for cloud sync and backups (#520)

lib/core/services/cloud_storage/encrypting_cloud_storage_provider.dart

@@ -0,0 +1,119 @@
+import 'dart:typed_data';
+
+import 'package:cryptography/cryptography.dart';
+
+import 'package:submersion/core/services/cloud_storage/cloud_storage_provider.dart';
+import 'package:submersion/core/services/sync/crypto/crypto_errors.dart';
+import 'package:submersion/core/services/sync/crypto/keyslots.dart';
+import 'package:submersion/core/services/sync/crypto/sync_envelope.dart';
+
+/// Wraps the configured provider so every non-exempt byte stored in the
+/// cloud is an SBE1 envelope. Filenames, listing, folders, and auth pass
+/// through untouched; encryption is invisible to readers and writers above
+/// this seam (spec section 4.1).
+class EncryptingCloudStorageProvider implements CloudStorageProvider {
+  final CloudStorageProvider inner;
+  final SecretKey _dataKey;
+  final String _libraryKeyId;
+
+  /// fileId -> filename, populated from list/info/upload results so
+  /// downloads know the AAD. Misses fall back to [getFileInfo].
+  final Map<String, String> _names = {};
+
+  EncryptingCloudStorageProvider(
+    this.inner, {
+    required SecretKey dataKey,
+    required String libraryKeyId,
+  }) : _dataKey = dataKey,
+       _libraryKeyId = libraryKeyId;
+
+  /// Exactly two exemptions (spec 4.1): the keyslot bootstrap file and
+  /// backup artifacts, which carry their own framed encryption.
+  static bool isExempt(String filename) =>
+      filename == KeyslotFile.cloudFileName ||
+      filename.startsWith('submersion_backup_');
+
+  @override
+  Future<UploadResult> uploadFile(
+    Uint8List data,
+    String filename, {
+    String? folderId,
+  }) async {
+    final bytes = isExempt(filename)
+        ? data
+        : await SyncEnvelope.seal(
+            plaintext: data,
+            dataKey: _dataKey,
+            libraryKeyId: _libraryKeyId,
+            filename: filename,
+          );
+    final result = await inner.uploadFile(bytes, filename, folderId: folderId);
+    _names[result.fileId] = filename;
+    return result;
+  }
+
+  @override
+  Future<Uint8List> downloadFile(String fileId) async {
+    final bytes = await inner.downloadFile(fileId);
+    if (!SyncEnvelope.hasMagic(bytes)) return bytes;
+    final name = _names[fileId] ?? (await inner.getFileInfo(fileId))?.name;
+    if (name == null) {
+      throw const EnvelopeCorruptException(
+        'Encrypted file has no resolvable name for authentication',
+      );
+    }
+    _names[fileId] = name;
+    return SyncEnvelope.open(
+      envelope: bytes,
+      dataKey: _dataKey,
+      expectedLibraryKeyId: _libraryKeyId,
+      filename: name,
+    );
+  }
+
+  @override
+  Future<List<CloudFileInfo>> listFiles({
+    String? folderId,
+    String? namePattern,
+  }) async {
+    final files = await inner.listFiles(
+      folderId: folderId,
+      namePattern: namePattern,
+    );
+    for (final f in files) {
+      _names[f.id] = f.name;
+    }
+    return files;
+  }
+
+  @override
+  Future<CloudFileInfo?> getFileInfo(String fileId) async {
+    final info = await inner.getFileInfo(fileId);
+    if (info != null) _names[info.id] = info.name;
+    return info;
+  }
+
+  @override
+  String get providerName => inner.providerName;
+  @override
+  String get providerId => inner.providerId;
+  @override
+  Future<bool> isAvailable() => inner.isAvailable();
+  @override
+  Future<bool> isAuthenticated() => inner.isAuthenticated();
+  @override
+  Future<void> authenticate() => inner.authenticate();
+  @override
+  Future<void> signOut() => inner.signOut();
+  @override
+  Future<String?> getUserEmail() => inner.getUserEmail();
+  @override
+  Future<void> deleteFile(String fileId) => inner.deleteFile(fileId);
+  @override
+  Future<bool> fileExists(String fileId) => inner.fileExists(fileId);
+  @override
+  Future<String> createFolder(String folderName, {String? parentFolderId}) =>
+      inner.createFolder(folderName, parentFolderId: parentFolderId);
+  @override
+  Future<String> getOrCreateSyncFolder() => inner.getOrCreateSyncFolder();
+}

lib/core/services/sync/changeset_log/sync_manifest.dart

@@ -1,6 +1,9 @@
 import 'dart:convert';
 import 'dart:typed_data';
 
+import 'package:submersion/core/services/sync/crypto/crypto_errors.dart';
+import 'package:submersion/core/services/sync/crypto/sync_envelope.dart';
+
 /// The per-device manifest: the small, rewritten-each-publish "commit point"
 /// that names the current base and changeset range. The only mutable file in
 /// a device's namespace.
@@ -70,7 +73,17 @@ class SyncManifest {
 
   Uint8List toBytes() => Uint8List.fromList(utf8.encode(jsonEncode(toJson())));
 
-  factory SyncManifest.fromBytes(Uint8List bytes) => SyncManifest.fromJson(
-    jsonDecode(utf8.decode(bytes)) as Map<String, dynamic>,
-  );
+  factory SyncManifest.fromBytes(Uint8List bytes) {
+    // Defense in depth for encrypted libraries: never let an SBE1 envelope
+    // masquerade as a corrupt manifest (spec section 4.3).
+    if (SyncEnvelope.hasMagic(bytes)) {
+      throw SyncEncryptionRequired(
+        libraryKeyId: SyncEnvelope.libraryKeyIdOf(bytes),
+        message: 'Sync manifest is encrypted',
+      );
+    }
+    return SyncManifest.fromJson(
+      jsonDecode(utf8.decode(bytes)) as Map<String, dynamic>,
+    );
+  }
 }

lib/core/services/sync/crypto/crypto_errors.dart

@@ -0,0 +1,27 @@
+/// The cloud library is encrypted and this device holds no (matching) key.
+///
+/// Carriers of this exception halt sync with
+/// SyncResultStatus.awaitingPassphrase instead of surfacing a raw error.
+class SyncEncryptionRequired implements Exception {
+  final String? libraryKeyId;
+  final String message;
+
+  const SyncEncryptionRequired({
+    this.libraryKeyId,
+    this.message = 'The cloud library is encrypted',
+  });
+
+  @override
+  String toString() => 'SyncEncryptionRequired($libraryKeyId): $message';
+}
+
+/// An SBE1 envelope failed structural parsing or authentication. Treated
+/// like a checksum failure: transient-stop, never a silent fallback.
+class EnvelopeCorruptException implements Exception {
+  final String message;
+
+  const EnvelopeCorruptException(this.message);
+
+  @override
+  String toString() => 'EnvelopeCorruptException: $message';
+}