diff --git a/.github/workflows/rtdb-relay-dart-tests.yml b/.github/workflows/rtdb-relay-dart-tests.yml new file mode 100644 index 0000000..c50c64d --- /dev/null +++ b/.github/workflows/rtdb-relay-dart-tests.yml @@ -0,0 +1,36 @@ +name: rtdb_relay dart tests + +on: + push: + branches: [main] + paths: ['rtdb_relay/dart/**'] + pull_request: + branches: [main] + paths: ['rtdb_relay/dart/**'] + +jobs: + test: + runs-on: ubuntu-latest + defaults: + run: + working-directory: rtdb_relay/dart + + steps: + - uses: actions/checkout@v4 + + - name: Set up Flutter + uses: subosito/flutter-action@v2 + with: + channel: stable + + - name: Install dependencies + run: flutter pub get + + - name: Analyze + run: flutter analyze + + - name: Run tests with coverage + run: flutter test --coverage + + - name: Enforce 100% line coverage + run: scripts/check_coverage.sh coverage/lcov.info 100 diff --git a/rtdb_relay/README.md b/rtdb_relay/README.md index 2edc422..a7fee33 100644 --- a/rtdb_relay/README.md +++ b/rtdb_relay/README.md @@ -76,14 +76,85 @@ from rtdb_relay import presence, sse, mirror local copy of a streamed node. To publish a sealed snapshot node, `await rtdb.put("", value)`. -## Dart API (the Flutter client) +## Dart API (the Flutter client, `dart/`) -Not extracted yet: the tutor app's `lib/sync/` and `lib/relay/` still hold -the client half. Until it moves here, a new client follows the wire format -above (`requests/{rid}/req` sealed with crdt_sync's Dart `E2eCipher`, then -listen on `requests/{rid}/result`). +```yaml +rtdb_relay: + git: + url: https://github.com/kuhyx/utils + ref: rtdb-relay-v0.2.0 + path: rtdb_relay/dart +``` -## Develop +`import 'package:rtdb_relay/rtdb_relay.dart';` The tutor app uses it since +v0.2.0 (`lib/sync/*.dart` there are thin tutor bindings: a worked example). +A request is written by the app and answered by the worker; the app never +writes `claim` or `result`. + +- `RelayLayout(String base, {required List clear, required + Map> units})`: the tree rules, same patterns as the + Python `Layout`. `root` is crdt_sync's e2e prefix of `base` + (`todoimpl/v1` -> `todoimpl/v1-e2e`); the passphrase header lives at + `/e2e`. Start from `kRelayClear` + `kRelayUnits` (claim clear; + `requests/*/req` keeps `created`, `requests/*/result` keeps `at`, + `presence/workers/*` keeps `beat`). `classify(parts) -> E2eRule`, + `unitPath(rel) -> String?`, `rel(path) -> String?`. Unknown paths throw + `E2eLayoutError` on write. +- `RelaySealer(E2eCipher cipher, {required RelayLayout layout, String? + root})`: `seal(rel, value)`, `sealPatch(rel, body)`, `open(rel, value)`. + `E2eGate` makes one for you; build it by hand only in tests. +- `RtdbClient({required RelayLayout layout, required String databaseUrl, + required IdTokenSource idToken, http.Client? httpClient, String? + namespace, RelaySealer? sealer, bool sealRequired = false})`: + `get(path, {query})`, `keys(path)`, `getTagged(path) -> Tagged`, + `put(path, value)`, `putIfMatch(path, value, etag) -> ConditionalResult`, + `deleteIfMatch(path, etag)`, `patch(path, Map)`, `delete(path)`, + `close()`. Paths are full (`/requests//req`). Errors are + `RtdbError` (`isAuth`, `isTransient`); with `sealRequired` nothing under + the root is sent before the key is unlocked. `keyRangeQuery(startAt)` + gives the `$key`-ordered range query (the only index the rules allow). +- `RtdbStream(RtdbClient client, {Sleep? sleep})`: `listen(path, {query}) + -> Stream` (SSE, reconnects with backoff, opens sealed + units; events `RtdbPut`, `RtdbPatch`, `RtdbConnected`, + `RtdbDisconnected`, ...). `applyEvent(tree, event)`, `getAt(tree, path)` + and `setAt(tree, path, value)` keep a local copy of a streamed node. +- `RequestHub(RtdbStream stream, String requestsPath)`: one ranged listen + for every request in flight. `watch(rid) -> Stream` yields the + `requests/` node (`req`, `claim`, `result`) each time it changes; + `inFlight` counts the followed requests. To send: `put('/requests/ + /req', {'kind': k, 'dev': deviceId, 'created': {'.sv': + 'timestamp'}, 'sent_at': ms, 'body': {...}})` with a fresh ULID `rid`, + then `watch(rid)` until `result` appears (`ok`, or `code`/`error`/`retry`). +- `RevWatcher(RtdbStream stream, String path, {WidgetsBinding? binding, + ValueListenable? yieldTo})`: `changesOf(key) -> Stream` emits + real moves of `rev/` only; pauses while the app is hidden and while + `yieldTo` (pass `RequestHub.inFlight`) is above 0. `revOf(rev, key)`, + `foregroundFor(state)`. +- `E2eGate({required RtdbClient client, FlutterSecureStorage storage, + Argon2Params params})`: `unlock() -> Future` opens the key from the + keystore passphrase (crdt_sync_flutter) and sets `client.sealer`; + `locked`, `reason`. +- `RelayFirebaseConfig({apiKey, databaseUrl, syncUid, serverClientId})` + (const; keep the values in a gitignored generated file) and + `RelayAuth({required RelayFirebaseConfig config, required + GoogleTokenFetcher googleToken, required FirebaseCredentialStore store, + http.Client? httpClient, DateTime Function()? clock, Future + Function()? adopt})`: `hasSession()`, `signInWithGoogle({tokenFetcher}) + -> SignInOutcome` (refuses a Google account whose uid is not + `syncUid`), `idToken()` (pass `auth.idToken` to `RtdbClient`), + `signOut()`. `googleToken`: crdt_sync_flutter's `googleIdToken`. + `secureCredentialStore(String key)` is the keystore-backed store. +- Desktop (web in a Chrome `--app` window): `adoptWrapperCredentials(base:, + client:, store:, expectedUid:)` takes the PC server's seeded session once + from `sync-credentials`; pass it as `RelayAuth.adopt`. + +Develop: `cd dart && fvm flutter test --coverage && +scripts/check_coverage.sh coverage/lcov.info 100`; `fvm flutter analyze`. +`test/data/e2e_vectors.json` (the tutor's contract vectors) and +`test/differential_test.dart` (the tutor's pre-extraction sealer, frozen in +`test/support/`) pin the wire format. + +## Develop (Python) `uv venv --python 3.15 .venv && uv pip install -e . pytest==9.2.0 pytest-cov==7.1.0 ruff==0.17.4 mypy==2.4.1`, then `scripts/run_subproject_tests.sh rtdb_relay` diff --git a/rtdb_relay/dart/.fvmrc b/rtdb_relay/dart/.fvmrc new file mode 100644 index 0000000..14bb2a9 --- /dev/null +++ b/rtdb_relay/dart/.fvmrc @@ -0,0 +1,3 @@ +{ + "flutter": "3.50.0" +} diff --git a/rtdb_relay/dart/.gitignore b/rtdb_relay/dart/.gitignore new file mode 100644 index 0000000..bcdad1a --- /dev/null +++ b/rtdb_relay/dart/.gitignore @@ -0,0 +1,3 @@ +.dart_tool/ +build/ +coverage/ diff --git a/rtdb_relay/dart/analysis_options.yaml b/rtdb_relay/dart/analysis_options.yaml new file mode 100644 index 0000000..fb9df11 --- /dev/null +++ b/rtdb_relay/dart/analysis_options.yaml @@ -0,0 +1,37 @@ +include: package:very_good_analysis/analysis_options.yaml + +analyzer: + language: + strict-casts: true + strict-inference: true + strict-raw-types: true + errors: + # Promote key lints to errors so they fail CI, not just warn. + missing_required_param: error + unnecessary_null_comparison: error + dead_code: error + invalid_annotation_target: error + exclude: + - build/** + - "**/*.g.dart" + - "**/*.freezed.dart" + - android/** + - ios/** + - web/** + - windows/** + - macos/** + - linux/** + +linter: + rules: + # very_good_analysis enables most rules; add extras it doesn't include. + always_use_package_imports: true + avoid_print: true + avoid_relative_lib_imports: true + cancel_subscriptions: true + close_sinks: true + comment_references: false # conflicts with typical Flutter API docs style + directives_ordering: true + lines_longer_than_80_chars: true + public_member_api_docs: true + unawaited_futures: true diff --git a/rtdb_relay/dart/lib/rtdb_relay.dart b/rtdb_relay/dart/lib/rtdb_relay.dart new file mode 100644 index 0000000..f809044 --- /dev/null +++ b/rtdb_relay/dart/lib/rtdb_relay.dart @@ -0,0 +1,17 @@ +/// The Flutter client half of the sealed RTDB request relay: REST + SSE +/// over Firebase RTDB, end-to-end sealing per an app's [RelayLayout], the +/// shared `requests` listen, the `rev` watcher, the passphrase gate and the +/// Google -> Firebase session. The PC half is the Python `rtdb_relay`. +library; + +export 'src/auth.dart'; +export 'src/e2e_gate.dart'; +export 'src/json_tree.dart'; +export 'src/layout.dart'; +export 'src/request_hub.dart'; +export 'src/rev_watcher.dart'; +export 'src/rtdb_client.dart'; +export 'src/rtdb_event.dart'; +export 'src/rtdb_stream.dart'; +export 'src/sealer.dart'; +export 'src/wrapper_credentials.dart'; diff --git a/rtdb_relay/dart/lib/src/auth.dart b/rtdb_relay/dart/lib/src/auth.dart new file mode 100644 index 0000000..a689c6c --- /dev/null +++ b/rtdb_relay/dart/lib/src/auth.dart @@ -0,0 +1,150 @@ +/// The signed-in session: Google ID token -> Firebase refresh token in the +/// keystore -> short-lived ID tokens for every RTDB request. +/// +/// "Connected" means a stored session (refresh token), never an account +/// marker: that confusion kept phones "not connected" while their credential +/// sat unused in the keystore (todo, 2026-08-11). +library; + +import 'dart:developer'; + +import 'package:crdt_sync/crdt_sync.dart' + show + FirebaseAuthError, + FirebaseCredentialStore, + FirebaseTokenProvider, + SecureCredentialStore; +import 'package:flutter_secure_storage/flutter_secure_storage.dart'; +import 'package:http/http.dart' as http; + +/// Outcome of an interactive sign-in. +enum SignInOutcome { + /// A session is stored; the app can sync. + signedIn, + + /// The user dismissed the picker, or Google sign-in is unavailable. + cancelled, +} + +/// The Firebase identifiers an app build talks to. Keep the literal values +/// out of public source (a gitignored generated file). +class RelayFirebaseConfig { + /// Creates a config; tests pass fakes. + const new({ + required this.apiKey, + required this.databaseUrl, + required this.syncUid, + required this.serverClientId, + }); + + /// Web API key of the Firebase project. + final String apiKey; + + /// Regional RTDB URL. + final String databaseUrl; + + /// The uid the sync account must resolve to. A wrong Google account signs + /// up a second user; this guard refuses it before anything is stored. + final String syncUid; + + /// Google *Web* OAuth client id, used as the ID-token audience. + final String serverClientId; +} + +/// Fetches a Google ID token for [serverClientId]'s audience; null when the +/// user cancelled or sign-in is unavailable. crdt_sync_flutter's +/// `googleIdToken` fits. +typedef GoogleTokenFetcher = Future Function({ + required String serverClientId, +}); + +/// Owns the Firebase session for this install. +class RelayAuth { + /// Creates the auth wrapper. Tests pass a memory [store] and fake [http]. + new({ + required this.config, + required this.googleToken, + required FirebaseCredentialStore store, + http.Client? httpClient, + DateTime Function()? clock, + this.adopt, + }) : provider = FirebaseTokenProvider( + apiKey: config.apiKey, + store: store, + httpClient: httpClient, + clock: clock, + ); + + /// Desktop only: adopts the PC's seeded session from the wrapper when + /// no session is stored (see `wrapper_credentials.dart`). True if adopted. + final Future Function()? adopt; + + /// The build's Firebase identifiers. + final RelayFirebaseConfig config; + + /// The interactive Google sign-in. + final GoogleTokenFetcher googleToken; + + /// Mints ID tokens, refreshing from the stored refresh token. + final FirebaseTokenProvider provider; + + /// Whether a session is stored. Never throws: an unreadable store reads + /// as "not signed in", and the sign-in screen repairs it. + Future hasSession() async { + try { + if (await provider.hasSession()) return true; + final adopt = this.adopt; + return adopt != null && await adopt() && await provider.hasSession(); + } on Object catch (error, stackTrace) { + // `on Object`: an ArgumentError (Uri.base on Android) is an Error, not + // an Exception, and escaped `on Exception` in todo. + log( + 'session probe failed; treating as signed out', + level: 1000, + error: error, + stackTrace: stackTrace, + ); + return false; + } + } + + /// Interactive Google sign-in with the expected-uid guard. + /// + /// Throws [FirebaseAuthError] when Google resolves to a different uid: + /// picking the wrong account would otherwise silently sign up a second + /// user. Nothing is stored in that case. + Future signInWithGoogle({ + Future Function()? tokenFetcher, + }) async { + final token = + await (tokenFetcher ?? + () => googleToken(serverClientId: config.serverClientId))(); + if (token == null) return SignInOutcome.cancelled; + await provider.signInWithGoogle( + idToken: token, + expectedUid: config.syncUid, + ); + return SignInOutcome.signedIn; + } + + /// A currently valid ID token; throws [FirebaseAuthError] when signed out + /// or the refresh token was revoked (the session is then cleared). + Future idToken() => provider.idToken(); + + /// Forgets the stored session. + Future signOut() => provider.signOut(); +} + +/// The keystore-backed credential store (Android keystore; web storage) +/// under [key] (e.g. `tutor.firebase.credentials`). +// coverage:ignore-start +FirebaseCredentialStore secureCredentialStore(String key) { + const secure = FlutterSecureStorage(); + return SecureCredentialStore( + read: (k) => secure.read(key: k), + write: (k, v) => secure.write(key: k, value: v), + delete: (k) => secure.delete(key: k), + key: key, + ); +} +// coverage:ignore-end diff --git a/rtdb_relay/dart/lib/src/e2e_gate.dart b/rtdb_relay/dart/lib/src/e2e_gate.dart new file mode 100644 index 0000000..32e21de --- /dev/null +++ b/rtdb_relay/dart/lib/src/e2e_gate.dart @@ -0,0 +1,113 @@ +/// Unlocks an app's e2e key: Argon2id of the shared crdt-sync passphrase, +/// read from and cached in the OS keystore by crdt_sync_flutter +/// (tutor DOCS-contract §12). Until it opens, [RtdbClient] sends nothing. +library; + +import 'package:crdt_sync/crdt_sync.dart' + show + Argon2Params, + E2eLocked, + E2eReady, + E2eState, + RemoteStore, + RemoteSyncError; +import 'package:crdt_sync_flutter/crdt_sync_flutter.dart' + show kSecureStorage, openEncryptedStoreFromKeystore; +import 'package:flutter_secure_storage/flutter_secure_storage.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/sealer.dart'; + +/// Opens [client]'s sealer from the keystore; [locked] until it did. +class E2eGate { + /// Creates the gate. [params] is lowered only by tests. + new({ + required this.client, + this.storage = kSecureStorage, + this.params = Argon2Params.recommended, + }); + + /// The client whose sealer this sets. + final RtdbClient client; + + /// The keystore holding the passphrase and the cached key. + final FlutterSecureStorage storage; + + /// Argon2id cost for a header this device creates. + final Argon2Params params; + + /// Why the last [unlock] stayed locked; null once open. + E2eState? last; + + /// True while the client needs a key and has none (nothing is sent). + /// A client built without `sealRequired` (tests, fixtures) never locks. + bool get locked => client.sealRequired && client.sealer == null; + + /// Opens the key (header made on first use); true when unlocked. + /// + /// The crdt_sync log copy inside `openEncryptedStore` finds nothing to + /// copy here ([E2eHeaderStore] lists no directory): a relay tree is + /// not a crdt log; the PC worker copies the old root itself. + Future unlock() async { + if (!locked) return true; + final state = await openEncryptedStoreFromKeystore( + store: E2eHeaderStore(client), + oldPrefix: client.layout.base, + storage: storage, + params: params, + ); + last = state; + if (state is E2eReady) { + client.sealer = RelaySealer( + state.store.key.cipher(), + layout: client.layout, + ); + return true; + } + return false; + } + + /// The lock reason of the last attempt, for the spoken label. + String get reason => switch (last) { + E2eLocked(:final reason) => reason.name, + _ => '', + }; +} + +/// Just enough of crdt_sync's [RemoteStore] for the e2e header: one JSON +/// string leaf (`/e2e`, e.g. `tutor/e2e`), as the PC worker writes it. +class E2eHeaderStore implements RemoteStore { + /// Creates the store over [_client] (no sealing outside the e2e root). + new(this._client); + + final RtdbClient _client; + + @override + Future getFileText(String path) async { + final value = await _client.get(path); + if (value == null || value is String) return value as String?; + // Not a header we wrote: unlock reports badHeader, never overwrites it. + return '$value'; + } + + @override + Future putFileText( + String path, + String text, { + required String message, + }) async { + await _client.put(path, text); + } + + @override + Future> listDirectory(String path) async => const []; + + @override + Future deleteFile(String path, {String message = ''}) => + throw RemoteSyncError('the relay never deletes the e2e header'); + + @override + Future canAccessRemote() async => true; + + @override + void close() {} +} diff --git a/rtdb_relay/dart/lib/src/json_tree.dart b/rtdb_relay/dart/lib/src/json_tree.dart new file mode 100644 index 0000000..2d0d149 --- /dev/null +++ b/rtdb_relay/dart/lib/src/json_tree.dart @@ -0,0 +1,59 @@ +/// Applies RTDB stream events to a local copy of the listened subtree. +/// +/// Pure and copy-on-write: callers keep the previous tree, so a listener can +/// diff old against new without the tree changing under it. +library; + +import 'package:rtdb_relay/src/rtdb_event.dart'; + +List _segments(String path) => + path.split('/').where((s) => s.isNotEmpty).toList(); + +/// Returns [root] with [value] set at [path] (`/` replaces the root). +/// A null [value] deletes; maps left empty collapse to null, as in RTDB. +Object? setAt(Object? root, String path, Object? value) => + _set(root, _segments(path), value); + +Object? _set(Object? node, List segs, Object? value) { + if (segs.isEmpty) return value; + final map = node is Map + ? Map.of(node) + : {}; + final child = _set(map[segs.first], segs.sublist(1), value); + if (child == null) { + map.remove(segs.first); + } else { + map[segs.first] = child; + } + return map.isEmpty ? null : map; +} + +/// Reads the value at [path] in [root]; null when absent. +Object? getAt(Object? root, String path) { + var node = root; + for (final seg in _segments(path)) { + if (node is! Map) return null; + node = node[seg]; + } + return node; +} + +/// Applies one stream event; non-data events return [root] unchanged. +Object? applyEvent(Object? root, RtdbEvent event) { + switch (event) { + case RtdbPut(:final path, :final data): + return setAt(root, path, data); + case RtdbPatch(:final path, :final data): + var next = root; + for (final entry in data.entries) { + next = setAt(next, '$path/${entry.key}', entry.value); + } + return next; + case RtdbConnected(): + case RtdbDisconnected(): + case RtdbKeepAlive(): + case RtdbCancel(): + case RtdbAuthRevoked(): + return root; + } +} diff --git a/rtdb_relay/dart/lib/src/layout.dart b/rtdb_relay/dart/lib/src/layout.dart new file mode 100644 index 0000000..13dd152 --- /dev/null +++ b/rtdb_relay/dart/lib/src/layout.dart @@ -0,0 +1,148 @@ +/// Which RTDB nodes are sealed, and how (the Dart twin of +/// `rtdb_relay/layout.py`). +/// +/// Keys stay clear; every *unit* (a node one writer writes whole) is stored +/// as `{"_e2e": , }`. A `clear` pattern covers its whole +/// subtree; a unit pattern maps to the fields it keeps clear (server +/// timestamps). `*` matches one segment. A write the layout has no rule for +/// throws: nothing new leaks by accident. +library; + +import 'package:crdt_sync/crdt_sync.dart' show E2eLayout; + +/// The key a sealed unit keeps its blob under. +const String kSealedKey = '_e2e'; + +/// The rules every relay app needs: request leases are clear, requests, +/// results and worker presence are sealed units. +const List kRelayClear = ['requests/*/claim']; + +/// The relay's own units and the fields each keeps clear. +const Map> kRelayUnits = { + 'presence/workers/*': {'beat'}, + 'requests/*/req': {'created'}, + 'requests/*/result': {'at'}, +}; + +/// A write the layout refuses (unknown path, or inside a sealed unit). +class E2eLayoutError implements Exception { + /// Creates the error. + const new(this.message); + + /// What was refused. + final String message; + + @override + String toString() => 'E2eLayoutError: $message'; +} + +/// Where a node falls in the layout. +enum E2eRuleKind { + /// Stored as is (ids, counters, lease times). + clear, + + /// Sealed whole. + unit, + + /// Inside a unit: never written on its own. + below, + + /// A map of clear keys above units. + struct, + + /// No rule: refused on write. + unknown, +} + +/// The rule for one node. +class E2eRule { + /// Creates the rule. + const new(this.kind, [this.depth = 0, this.keep = const {}]); + + /// Its kind. + final E2eRuleKind kind; + + /// For [E2eRuleKind.below]: how many segments the unit has. + final int depth; + + /// For a unit: the fields kept clear. + final Set keep; +} + +/// [path]'s segments, empty ones dropped. +List e2eParts(String path) => + path.split('/').where((s) => s.isNotEmpty).toList(); + +bool _matches(List pattern, List parts) { + if (pattern.length != parts.length) return false; + for (var i = 0; i < parts.length; i++) { + if (pattern[i] != '*' && pattern[i] != parts[i]) return false; + } + return true; +} + +/// One app's sealed tree: its root and its rules. +class RelayLayout { + /// The layout for app root [base] (e.g. `tutor/v1`); the sealed tree lives + /// at crdt_sync's e2e prefix of it (`tutor/v1-e2e`). Pattern order matters: + /// the first matching rule wins, clear before units. + new(this.base, {required this.clear, required this.units}) + : root = E2eLayout.of(base).prefix; + + /// The pre-e2e root; the key header hangs off it (crdt_sync). + final String base; + + /// The e2e root every relative path hangs off. + final String root; + + /// Clear subtrees. + final List clear; + + /// Sealed units and the fields each keeps clear. + final Map> units; + + /// The rule for the node at [parts] (relative to [root]). + E2eRule classify(List parts) { + for (final pattern in clear) { + final pat = pattern.split('/'); + if (pat.length <= parts.length && + _matches(pat, parts.sublist(0, pat.length))) { + return const E2eRule(E2eRuleKind.clear); + } + } + for (final entry in units.entries) { + final pat = entry.key.split('/'); + if (_matches(pat, parts)) { + return E2eRule(E2eRuleKind.unit, pat.length, entry.value); + } + if (pat.length < parts.length && + _matches(pat, parts.sublist(0, pat.length))) { + return E2eRule(E2eRuleKind.below, pat.length, entry.value); + } + } + for (final pattern in [...clear, ...units.keys]) { + final pat = pattern.split('/'); + if (parts.length < pat.length && + _matches(pat.sublist(0, parts.length), parts)) { + return const E2eRule(E2eRuleKind.struct); + } + } + return const E2eRule(E2eRuleKind.unknown); + } + + /// The sealed unit [rel] lies strictly below, or null. + String? unitPath(String rel) { + final parts = e2eParts(rel); + final rule = classify(parts); + return rule.kind == E2eRuleKind.below + ? parts.sublist(0, rule.depth).join('/') + : null; + } + + /// [path] relative to [root], or null when outside it. + String? rel(String path) { + final clean = e2eParts(path).join('/'); + if (clean == root) return ''; + return clean.startsWith('$root/') ? clean.substring(root.length + 1) : null; + } +} diff --git a/rtdb_relay/dart/lib/src/request_hub.dart b/rtdb_relay/dart/lib/src/request_hub.dart new file mode 100644 index 0000000..9ea0177 --- /dev/null +++ b/rtdb_relay/dart/lib/src/request_hub.dart @@ -0,0 +1,124 @@ +/// Every request in flight, followed over ONE listen (tutor DOCS-contract +/// §4, §9). +/// +/// RTDB speaks HTTP/1.1, so a browser holds at most 6 connections to it and +/// every listen keeps one for good. A listen per request let a Home request +/// still running under a Session turn take the app to 6 and starve the next +/// write. One `requests` listen ranged from the oldest followed rid +/// (`orderBy="$key"&startAt`: ULIDs sort by time) serves them all; another +/// device's request in that window rides along, unread. +/// +/// `inFlight` counts the requests followed; the shared `rev` listen yields +/// to it (`rev_watcher.dart`), so requests and `rev` share one connection. +/// A request's PUT goes out before its follow starts, while `rev` may still +/// be open: 4 streams and the PUT, 1 connection to spare. +library; + +import 'dart:async'; + +import 'package:flutter/foundation.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart' show keyRangeQuery; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +/// The shared `requests` listen. +class RequestHub { + /// Creates the hub over [_stream], following the requests node at + /// [requestsPath] (`/requests`). + new(this._stream, this.requestsPath); + + final RtdbStream _stream; + + /// The full path of the requests node. + final String requestsPath; + + /// Requests being followed; while above 0, `rev` waits. + final ValueNotifier inFlight = ValueNotifier(0); + + final Map>> _watchers = {}; + // Cancelled in _close(); the lint cannot see across methods. + // ignore: cancel_subscriptions + StreamSubscription? _sub; + String? _from; + Object? _tree; + + /// The `requests/{rid}` node each time it changes (null while absent), + /// until the subscription is cancelled. + Stream watch(String rid) { + late final StreamController out; + out = StreamController( + // `rev` lets go before this listen opens and comes back only after + // it closed, so the two never hold two connections at once. + onListen: () { + inFlight.value++; + _watchers.putIfAbsent(rid, () => []).add(out); + _cover(rid); + }, + onCancel: () { + final list = _watchers[rid]!..remove(out); + if (list.isEmpty) _watchers.remove(rid); + if (_watchers.isEmpty) _close(); + inFlight.value--; + }, + ); + return out.stream; + } + + /// Makes the listen reach back to [rid]: reopened from it when it is + /// older than the range's start, else [rid]'s node so far is handed over. + void _cover(String rid) { + final from = _from; + if (from != null && from.compareTo(rid) <= 0) { + final node = getAt(_tree, rid); + if (node != null) _send(rid, node); + return; + } + _close(); + _from = rid; + _sub = _stream + .listen(requestsPath, query: keyRangeQuery(rid)) + .listen(_on, onDone: _ended); + } + + // The transport gave up for good (rules `cancel`): every follow ends with + // no result, as its own listen's end did. + void _ended() { + _sub = null; + _from = null; + _tree = null; + for (final list in [..._watchers.values]) { + for (final out in [...list]) { + unawaited(out.close()); + } + } + } + + void _close() { + final sub = _sub; + _sub = null; + _from = null; + _tree = null; + unawaited(sub?.cancel()); + } + + void _on(RtdbEvent event) { + if (event is! RtdbPut && event is! RtdbPatch) return; + final before = _tree; + _tree = applyEvent(before, event); + // Copy-on-write: a node no event touched is the very same object. + final snapshot = event is RtdbPut && event.path == '/'; + for (final rid in [..._watchers.keys]) { + final node = getAt(_tree, rid); + // A snapshot (each connect) answers every watcher, as a per-request + // listen did: absent means queued. + if (snapshot || !identical(node, getAt(before, rid))) _send(rid, node); + } + } + + void _send(String rid, Object? node) { + for (final out in [...?_watchers[rid]]) { + out.add(node); + } + } +} diff --git a/rtdb_relay/dart/lib/src/rev_watcher.dart b/rtdb_relay/dart/lib/src/rev_watcher.dart new file mode 100644 index 0000000..4f1b802 --- /dev/null +++ b/rtdb_relay/dart/lib/src/rev_watcher.dart @@ -0,0 +1,161 @@ +/// "Did X change?" from a `rev` node of counters (the tutor's +/// DOCS-contract §3, §9: `rev.catalog`, `rev.stats`). +/// +/// One shared listen for every screen: each `changesOf(key)` is a broadcast +/// stream; the first listener of any opens the SSE and the last cancel +/// closes it. The listen also pauses while the app is hidden and resumes +/// when it is back in front. +/// +/// While a request is in flight ([RevWatcher.new]'s `yieldTo` above 0) the +/// listen stays closed: RTDB speaks HTTP/1.1, every listen holds one of the +/// browser's 6 connections, and the request's own listen takes this one. +/// Nothing is lost: the snapshot on reopening emits any move made meanwhile. +/// +/// Only real moves are emitted; the full snapshot every (re)connect resends +/// while a value is unchanged is not a move. A snapshot whose value *did* +/// change (the worker moved it while the app was hidden) is. +library; + +import 'dart:async'; + +import 'package:flutter/foundation.dart'; +import 'package:flutter/widgets.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +/// Counter [key] of a `rev` tree; 0 when absent. +int revOf(Object? rev, String key) { + final value = rev is Map ? rev[key] : null; + return value is num ? value.toInt() : 0; +} + +/// Whether the app counts as in front for [state] (null: not reported yet). +/// `inactive` keeps whatever was decided before: desktop web reports it on +/// a mere focus change, which is no reason to drop or reopen the listen. +bool? foregroundFor(AppLifecycleState? state) => switch (state) { + null || AppLifecycleState.resumed => true, + AppLifecycleState.inactive => null, + AppLifecycleState.hidden || + AppLifecycleState.paused || + AppLifecycleState.detached => false, +}; + +/// Streams `rev` while someone listens and the app is in front. +class RevWatcher { + /// Creates the watcher; `binding` (tests) reports the app lifecycle; + /// while [yieldTo] is above 0 the listen is closed. + /// [path] is the full path of the `rev` node. + new(this._stream, this.path, {this._binding, this.yieldTo}) { + yieldTo?.addListener(_yield); + } + + final RtdbStream _stream; + final WidgetsBinding? _binding; + + /// The full path of the `rev` node. + final String path; + + /// Requests in flight (`RequestRelay.inFlight`). + final ValueListenable? yieldTo; + + bool get _yielding => (yieldTo?.value ?? 0) > 0; + + final Map> _outs = {}; + final Map _last = {}; + + // Cancelled in _disconnect(); the lint cannot see across methods. + // ignore: cancel_subscriptions + StreamSubscription? _sub; + AppLifecycleListener? _lifecycle; + bool _foreground = true; + Object? _tree; + + /// The new `rev.` each time it moves. + Stream changesOf(String key) => _outs.putIfAbsent(key, () { + // A counter absent so far reads 0: its baseline once any event came. + if (_tree != null) _last.putIfAbsent(key, () => revOf(_tree, key)); + return StreamController.broadcast(onListen: _open, onCancel: _release); + }).stream; + + bool get _wanted => _outs.values.any((c) => c.hasListener); + + /// Whether the SSE listen is open (tests). + bool get listening => _sub != null; + + /// Tells the watcher the app went to the back (false) or front (true). + void foreground({required bool visible}) { + _foreground = visible; + visible ? _connect() : unawaited(_disconnect()); + } + + /// Closes the listen and the stream. + Future dispose() async { + yieldTo?.removeListener(_yield); + for (final out in _outs.values) { + await out.close(); + } + await _close(); + } + + // The first listener of either stream opens the listen, the last closes it. + void _open() { + if (_lifecycle != null) return; + final binding = _binding ?? WidgetsBinding.instance; + _foreground = foregroundFor(binding.lifecycleState) ?? true; + _lifecycle = AppLifecycleListener( + binding: binding, + onStateChange: (state) { + final visible = foregroundFor(state); + if (visible != null) foreground(visible: visible); + }, + ); + _connect(); + } + + Future _release() async { + if (!_wanted) await _close(); + } + + Future _close() async { + _lifecycle?.dispose(); + _lifecycle = null; + await _disconnect(); + } + + void _yield() => _yielding ? unawaited(_disconnect()) : _connect(); + + void _connect() { + if (_sub != null || !_foreground || !_wanted || _yielding) return; + _tree = null; + _sub = _stream.listen(path).listen(_on, onDone: () => _sub = null); + } + + Future _disconnect() async { + final sub = _sub; + _sub = null; + await sub?.cancel(); + } + + void _on(RtdbEvent event) { + if (event is RtdbConnected) _tree = null; + if (event is! RtdbPut && event is! RtdbPatch) return; + final tree = _tree = applyEvent(_tree, event); + // Every counter keeps a baseline, watched or not, so a stream opened + // later still sees only real moves. + final keys = { + if (tree is Map) ...tree.keys, + ..._outs.keys, + }; + for (final key in keys) { + final now = revOf(tree, key); + final before = _last[key]; + _last[key] = now; + // The first value ever is the baseline the screens loaded against. + final out = _outs[key]; + if (before != null && before != now && out != null && !out.isClosed) { + out.add(now); + } + } + } +} diff --git a/rtdb_relay/dart/lib/src/rtdb_client.dart b/rtdb_relay/dart/lib/src/rtdb_client.dart new file mode 100644 index 0000000..5ae5e38 --- /dev/null +++ b/rtdb_relay/dart/lib/src/rtdb_client.dart @@ -0,0 +1,220 @@ +/// Firebase Realtime Database over REST, with ETag conditional writes. +/// +/// crdt_sync's `FirebaseRestClient` stores only string leaves, so the relay +/// keeps its own GET/PUT/PATCH/DELETE. Every request carries +/// `?auth=`; the token source refreshes it. +/// +/// Under the layout's e2e root (e.g. `tutor/v1-e2e`) every value passes +/// through `sealer` (sealed on write, opened on read). With `sealRequired` +/// (the app) a call there before the key is unlocked throws instead of +/// sending plaintext. +library; + +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' + show checkSyncNamespace, syncNamespace; +import 'package:http/http.dart' as http; +import 'package:rtdb_relay/src/layout.dart'; +import 'package:rtdb_relay/src/rtdb_types.dart'; +import 'package:rtdb_relay/src/sealer.dart'; + +export 'package:rtdb_relay/src/rtdb_types.dart'; + +/// The REST client. +class RtdbClient { + /// Creates a client for [databaseUrl] authenticated by [idToken]. + /// + /// [namespace] (default: the `SYNC_NAMESPACE` dart-define, as in crdt_sync) + /// is empty for production or `sandbox/`; every request path then + /// lives under `//`. Anything else throws (fail closed). + new({ + required this.layout, + required String databaseUrl, + required this.idToken, + http.Client? httpClient, + String? namespace, + this.sealer, + this.sealRequired = false, + }) : _namespace = checkSyncNamespace(namespace ?? syncNamespace), + _base = databaseUrl.endsWith('/') + ? databaseUrl.substring(0, databaseUrl.length - 1) + : databaseUrl, + _http = httpClient ?? http.Client(); + + /// The app's sealed tree. + final RelayLayout layout; + + final String _base; + final String _namespace; + + /// Token source; also used by the stream for reconnects. + final IdTokenSource idToken; + final http.Client _http; + + /// The underlying HTTP client, shared with the SSE stream. + http.Client get httpClient => _http; + + /// Seals and opens the e2e root; null until the key is unlocked. + RelaySealer? sealer; + + /// When true, a call under the e2e root without [sealer] throws. + final bool sealRequired; + + /// [path] relative to the e2e root, or null when outside it. + String? e2eRel(String path) => layout.rel(path); + + RelaySealer? _sealerFor(String? rel) { + if (rel == null) return null; + if (sealer == null && sealRequired) { + throw const RtdbError('e2e locked: no key, nothing is sent'); + } + return sealer; + } + + /// [value] read at [path] with its sealed units opened. + Future opened(String path, Object? value) async { + final rel = e2eRel(path); + final s = _sealerFor(rel); + return s == null ? value : await s.open(rel!, value); + } + + Future _sealed(String path, Object? value) async { + final rel = e2eRel(path); + final s = _sealerFor(rel); + return s == null ? value : await s.seal(rel!, value); + } + + /// The REST URL of [path] with a fresh token and [query]. + Future uri(String path, {Map query = const {}}) async { + final segments = [ + ..._namespace.split('/'), + ...path.split('/'), + ].where((s) => s.isNotEmpty); + final encoded = segments.map(Uri.encodeComponent).join('/'); + return Uri.parse('$_base/$encoded.json') + .replace(queryParameters: {'auth': await idToken(), ...query}); + } + + /// Reads [path]; null when absent. + Future get( + String path, { + Map query = const {}, + }) async { + final rel = e2eRel(path); + final unit = rel != null && _sealerFor(rel) != null + ? layout.unitPath(rel) + : null; + if (unit != null) { + // Below a sealed unit: read the whole unit, open it, walk down. + var node = await get('${layout.root}/$unit'); + for (final part in e2eParts(rel!).skip(e2eParts(unit).length)) { + node = node is Map ? node[part] : null; + } + return node; + } + final res = await _send('GET', path, query: query); + return await opened(path, _decode(res)); + } + + /// Keys directly under [path] (`shallow=true`, values not transferred). + Future> keys(String path) async { + final value = await get(path, query: {'shallow': 'true'}); + if (value is! Map) return const []; + return value.keys.cast().toList()..sort(); + } + + /// Reads [path] with its ETag, for a following conditional write. + Future getTagged(String path) async { + final res = await _send('GET', path, headers: {'X-Firebase-ETag': 'true'}); + return Tagged(await opened(path, _decode(res)), res.headers['etag'] ?? ''); + } + + /// Writes [value] at [path]; returns the stored value with server values + /// (`{".sv":"timestamp"}`) resolved. + Future put(String path, Object? value) async => await opened( + path, + _decode(await _send('PUT', path, body: await _sealed(path, value))), + ); + + /// PUT only if the node still has [etag]; a 412 is a lost race. + Future putIfMatch( + String path, + Object? value, + String etag, + ) async => + await _conditional('PUT', path, etag, body: await _sealed(path, value)); + + /// DELETE only if the node still has [etag]. + Future deleteIfMatch(String path, String etag) => + _conditional('DELETE', path, etag); + + /// Merges [values] into the map at [path] (no ETag support in RTDB). + Future patch(String path, Map values) async { + final rel = e2eRel(path); + final s = _sealerFor(rel); + final body = s == null ? values : await s.sealPatch(rel!, values); + await _send('PATCH', path, body: body); + } + + /// Removes [path]. + Future delete(String path) async { + _sealerFor(e2eRel(path)); + await _send('DELETE', path); + } + + /// Releases the HTTP client. + void close() => _http.close(); + + Future _conditional( + String method, + String path, + String etag, { + Object? body, + }) async { + final res = await _send( + method, + path, + body: body, + headers: {'if-match': etag}, + accept412: true, + ); + return ConditionalResult( + ok: res.statusCode != 412, + value: await opened(path, _decode(res)), + etag: res.headers['etag'], + ); + } + + Future _send( + String method, + String path, { + Object? body, + Map query = const {}, + Map headers = const {}, + bool accept412 = false, + }) async { + final request = http.Request(method, await uri(path, query: query)) + ..headers.addAll(headers); + if (method == 'PUT' || method == 'PATCH') { + request.body = jsonEncode(body); + } + final http.Response res; + try { + res = await http.Response.fromStream(await _http.send(request)); + } on http.ClientException catch (exc) { + throw RtdbError('network error: $method $path: $exc'); + } + final ok = res.statusCode >= 200 && res.statusCode < 300; + if (!ok && !(accept412 && res.statusCode == 412)) { + throw RtdbError( + '$method $path: HTTP ${res.statusCode} ${res.body.trim()}', + status: res.statusCode, + ); + } + return res; + } + + static Object? _decode(http.Response res) => + res.body.isEmpty ? null : jsonDecode(res.body); +} diff --git a/rtdb_relay/dart/lib/src/rtdb_event.dart b/rtdb_relay/dart/lib/src/rtdb_event.dart new file mode 100644 index 0000000..34bdedc --- /dev/null +++ b/rtdb_relay/dart/lib/src/rtdb_event.dart @@ -0,0 +1,142 @@ +/// Server-sent events from the RTDB streaming API, parsed and typed. +/// +/// Pure: no I/O, so every line-splitting and event-mapping edge is unit +/// tested without a socket. The transport lives in `rtdb_stream.dart`. +library; + +import 'dart:convert'; + +/// One raw SSE frame: an `event:` name and its joined `data:` lines. +class SseFrame { + /// Creates the frame. + const new(this.event, this.data); + + /// The `event:` field (`put`, `patch`, `keep-alive`, ...). + final String event; + + /// The `data:` lines joined with `\n`. + final String data; +} + +/// Splits a text stream into [SseFrame]s. +/// +/// Feed decoded chunks in arrival order; a chunk may end mid-line or +/// mid-frame. A blank line dispatches the frame being built. +class SseParser { + String _buffer = ''; + String _event = ''; + final List _data = []; + + /// Adds [chunk] and returns the frames it completed. + List add(String chunk) { + _buffer += chunk; + final frames = []; + while (true) { + final newline = _buffer.indexOf('\n'); + if (newline < 0) break; + var line = _buffer.substring(0, newline); + _buffer = _buffer.substring(newline + 1); + if (line.endsWith('\r')) line = line.substring(0, line.length - 1); + if (line.isEmpty) { + if (_event.isNotEmpty || _data.isNotEmpty) { + frames.add(SseFrame(_event, _data.join('\n'))); + } + _event = ''; + _data.clear(); + } else if (line.startsWith('event:')) { + _event = line.substring(6).trim(); + } else if (line.startsWith('data:')) { + _data.add(line.substring(5).trimLeft()); + } + // Comments (":...") and unknown fields are ignored, as SSE requires. + } + return frames; + } +} + +/// A typed RTDB stream event. +sealed class RtdbEvent { + const new(); + + /// Maps an SSE frame; null for frames the client ignores. + static RtdbEvent? fromFrame(SseFrame frame) { + switch (frame.event) { + case 'put': + case 'patch': + final body = jsonDecode(frame.data) as Map; + final path = body['path'] as String; + return frame.event == 'put' + ? RtdbPut(path, body['data']) + : RtdbPatch(path, body['data'] as Map); + case 'keep-alive': + return const RtdbKeepAlive(); + case 'cancel': + return RtdbCancel(frame.data); + case 'auth_revoked': + return const RtdbAuthRevoked(); + } + return null; + } +} + +/// Emitted by the transport before each (re)connect's snapshot `put`. +class RtdbConnected extends RtdbEvent { + /// Creates the marker. + const new(); +} + +/// Emitted by the transport when a connection drops or fails to open; it +/// reconnects on its own after a backoff. +class RtdbDisconnected extends RtdbEvent { + /// Creates the marker. + const new(this.error); + + /// Why (an [Exception], an HTTP status error, or null for a clean end). + final Object? error; +} + +/// `put`: [data] replaces the node at [path] (relative to the listened path; +/// `/` on connect is the full snapshot). +class RtdbPut extends RtdbEvent { + /// Creates the event. + const new(this.path, this.data); + + /// Path relative to the listened location. + final String path; + + /// New value (null deletes). + final Object? data; +} + +/// `patch`: each child of [data] replaces that child under [path]. +class RtdbPatch extends RtdbEvent { + /// Creates the event. + const new(this.path, this.data); + + /// Path relative to the listened location. + final String path; + + /// Children to replace. + final Map data; +} + +/// The server's liveness ping (every ~30 s with no data). +class RtdbKeepAlive extends RtdbEvent { + /// Creates the event. + const new(); +} + +/// The rules no longer allow this listen; the stream ends. +class RtdbCancel extends RtdbEvent { + /// Creates the event. + const new(this.reason); + + /// Server-provided reason text. + final String reason; +} + +/// The token expired; the transport reconnects with a fresh one. +class RtdbAuthRevoked extends RtdbEvent { + /// Creates the event. + const new(); +} diff --git a/rtdb_relay/dart/lib/src/rtdb_stream.dart b/rtdb_relay/dart/lib/src/rtdb_stream.dart new file mode 100644 index 0000000..6eed432 --- /dev/null +++ b/rtdb_relay/dart/lib/src/rtdb_stream.dart @@ -0,0 +1,211 @@ +/// The RTDB streaming transport: one long-lived `text/event-stream` GET per +/// listened path, reconnecting until the listener cancels. +/// +/// Every (re)connect resends the full snapshot of the path, so callers listen +/// narrowly (tutor DOCS-contract §9). `auth_revoked` reconnects at once with a +/// fresh token; network failures and clean ends back off 1 s .. 30 s; +/// `cancel` (rules changed) ends the stream for good. +/// +/// RTDB speaks HTTP/1.1, so a browser holds at most 6 connections to it and +/// every listen is one. The app keeps at most 4 open, leaving 2 for writes +/// and reads (tutor DOCS-contract §9). A cancelled +/// listen therefore aborts its request, even one still connecting: a leaked +/// stream starved the next session's listens and the chat stayed empty after +/// Next card (2026-10-12). +library; + +import 'dart:async'; +import 'dart:convert'; + +import 'package:flutter/foundation.dart' show kIsWeb; +import 'package:http/http.dart' as http; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; + +/// Waits [d]; injectable so tests run the reconnect loop without real time. +typedef Sleep = Future Function(Duration d); + +/// Backoff before reconnect attempt [n] (0-based): 1, 2, 4 .. 30 s. +Duration reconnectDelay(int n) => Duration(seconds: n >= 5 ? 30 : 1 << n); + +enum _End { reconnectNow, backoff, stop } + +/// Opens SSE listens through an [RtdbClient]. +class RtdbStream { + /// Creates the transport. + new(this.client, {Sleep? sleep}) : _sleep = sleep ?? Future.delayed; + + /// Supplies URLs (with fresh tokens) and the HTTP client. + final RtdbClient client; + final Sleep _sleep; + + /// Streams events for [path] until the subscription is cancelled. + Stream listen( + String path, { + Map query = const {}, + }) { + late final StreamController out; + StreamSubscription? sub; + final abort = Completer(); + var stopped = false; + void emit(RtdbEvent event) { + if (!stopped && !out.isClosed) out.add(event); + } + + // Sealed units open asynchronously; a chain keeps the events in order. + final sealed = client.e2eRel(path) != null; + var chain = Future.value(); + + Future<_End> consume(http.StreamedResponse res) { + final done = Completer<_End>(); + final parser = SseParser(); + void finish(_End end) { + if (!done.isCompleted) done.complete(end); + } + + sub = res.stream + .transform(utf8.decoder) + .listen( + (chunk) { + for (final frame in parser.add(chunk)) { + if (done.isCompleted) return; + final RtdbEvent? event; + try { + event = RtdbEvent.fromFrame(frame); + } on Object catch (error) { + // A malformed frame: drop the connection and resync from + // the next snapshot rather than apply half an update. + emit(RtdbDisconnected(error)); + finish(_End.backoff); + return; + } + if (event == null) continue; + if (!sealed) { + emit(event); + } else { + final sealedEvent = event; + chain = chain.then((_) async { + try { + emit(await openEvent(client, path, sealedEvent)); + } on Object catch (error) { + // Locked, or an event inside a unit: resync later. + emit(RtdbDisconnected(error)); + finish(_End.backoff); + } + }); + } + if (event is RtdbAuthRevoked) finish(_End.reconnectNow); + if (event is RtdbCancel) finish(_End.stop); + } + }, + onError: (Object e) { + emit(RtdbDisconnected(e)); + finish(_End.backoff); + }, + onDone: () { + chain = chain.then((_) { + emit(const RtdbDisconnected(null)); + finish(_End.backoff); + }); + }, + ); + return done.future; + } + + Future run() async { + var attempt = 0; + while (!stopped) { + var end = _End.backoff; + try { + final res = await _open( + await client.uri(path, query: query), + abort.future, + ); + if (stopped) { + // Cancelled while connecting: let go of the response too. + await res.stream.listen(null).cancel(); + break; + } + attempt = 0; + emit(const RtdbConnected()); + end = await consume(res); + await sub?.cancel(); + } on Object catch (error) { + // `on Object`: a token failure is a FirebaseAuthError, a bad frame + // a FormatException, a dropped socket a ClientException; all of + // them mean "try again later", never "crash the listener". + emit(RtdbDisconnected(error)); + } + if (end == _End.stop || stopped) break; + if (end == _End.backoff) await _sleep(reconnectDelay(attempt++)); + } + if (!out.isClosed) await out.close(); + } + + out = StreamController( + onListen: () => unawaited(run()), + onCancel: () async { + stopped = true; + if (!abort.isCompleted) abort.complete(); + await sub?.cancel(); + }, + ); + return out.stream; + } + + /// GET with `Accept: text/event-stream`, following redirects by hand so + /// the Accept header survives a 307 to another RTDB host. + Future _open(Uri uri, Future abort) async { + var target = uri; + for (var hop = 0; hop < 5; hop++) { + final request = http.AbortableRequest('GET', target, abortTrigger: abort) + // A browser's fetch cannot hand a redirect back (http's + // BrowserClient raises instead) and follows it keeping Accept, so + // only the VM follows by hand. + ..followRedirects = kIsWeb + ..headers['Accept'] = 'text/event-stream'; + final res = await client.httpClient.send(request); + final location = res.headers['location']; + if (res.statusCode >= 300 && res.statusCode < 400 && location != null) { + await res.stream.drain(); + target = target.resolve(location); + continue; + } + if (res.statusCode != 200) { + final body = await res.stream.bytesToString(); + throw RtdbError( + 'stream ${uri.path}: HTTP ${res.statusCode} ${body.trim()}', + status: res.statusCode, + ); + } + return res; + } + throw RtdbError('stream ${uri.path}: too many redirects'); + } +} + +/// [event] (from a listen on [listened]) with its sealed units opened. +Future openEvent( + RtdbClient client, + String listened, + RtdbEvent event, +) async { + String at(String rel) => [ + listened, + rel, + ].expand((p) => p.split('/')).where((s) => s.isNotEmpty).join('/'); + switch (event) { + case RtdbPut(): + return RtdbPut( + event.path, + await client.opened(at(event.path), event.data), + ); + case RtdbPatch(): + return RtdbPatch(event.path, { + for (final e in event.data.entries) + e.key: await client.opened(at('${event.path}/${e.key}'), e.value), + }); + default: + return event; + } +} diff --git a/rtdb_relay/dart/lib/src/rtdb_types.dart b/rtdb_relay/dart/lib/src/rtdb_types.dart new file mode 100644 index 0000000..f640b7e --- /dev/null +++ b/rtdb_relay/dart/lib/src/rtdb_types.dart @@ -0,0 +1,65 @@ +/// The REST client's value types: token source, errors, ETag pairs and the +/// `$key` range query. +library; + +import 'dart:convert'; + +/// Supplies a currently valid Firebase ID token. +typedef IdTokenSource = Future Function(); + +/// A failed RTDB request. [status] is null for network failures. +class RtdbError implements Exception { + /// Creates the error. + const new(this.message, {this.status}); + + /// What failed, with the HTTP body when there was one. + final String message; + + /// HTTP status, or null when the request never got an answer. + final int? status; + + /// True when the rules or the token rejected this request (401/403). + bool get isAuth => status == 401 || status == 403; + + /// True when retrying the same request can succeed (network, 5xx). + bool get isTransient => status == null || status! >= 500; + + @override + String toString() => 'RtdbError($status): $message'; +} + +/// A value read together with the ETag a conditional write must match. +class Tagged { + /// Creates the pair. + const new(this.value, this.etag); + + /// The decoded JSON value (null when the node is absent). + final Object? value; + + /// The opaque ETag of [value]. + final String etag; +} + +/// Result of a conditional PUT/DELETE. +class ConditionalResult { + /// Creates the result. + const new({required this.ok, required this.value, required this.etag}); + + /// False on 412: another writer won the race. + final bool ok; + + /// The written value (server values resolved), or the current one on 412. + final Object? value; + + /// ETag of [value] after the call, when the server sent one. + final String? etag; +} + +/// Query parameters for a `$key`-ordered read starting at [startAt]. +/// +/// RTDB wants both values JSON-quoted. Only `orderBy="$key"` is usable: +/// the shared rules add no `.indexOn`. +Map keyRangeQuery(String startAt) => { + 'orderBy': jsonEncode(r'$key'), + 'startAt': jsonEncode(startAt), +}; diff --git a/rtdb_relay/dart/lib/src/sealer.dart b/rtdb_relay/dart/lib/src/sealer.dart new file mode 100644 index 0000000..7260a9c --- /dev/null +++ b/rtdb_relay/dart/lib/src/sealer.dart @@ -0,0 +1,151 @@ +/// Seals writes and opens reads of one app's tree (the Dart twin of +/// `rtdb_relay/seal.py`): each unit becomes crdt_sync's [E2eCipher] blob +/// with the unit's full path as AAD, so a blob moved elsewhere does not open. +library; + +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' show E2eCipher; +import 'package:rtdb_relay/src/layout.dart'; + +Object? _pruned(Object? value) { + if (value is! Map) return value; + final out = {}; + for (final e in value.entries) { + final v = _pruned(e.value); + if (v != null) out[e.key as String] = v; + } + return out.isEmpty ? null : out; +} + +/// Seals writes and opens reads under [root] with [cipher]. +class RelaySealer { + /// Creates the sealer for [layout]; [root] overrides its e2e root. + new(this.cipher, {required this.layout, String? root}) + : root = root ?? layout.root; + + /// The tree rules. + final RelayLayout layout; + + /// The key's cipher. + final E2eCipher cipher; + + /// The e2e root every relative path hangs off. + final String root; + + String _aad(List parts) => [root, ...parts].join('/'); + + /// [value] as it may be stored at [rel]; throws [E2eLayoutError] for an + /// unknown path. + Future seal(String rel, Object? value) => + _seal(e2eParts(rel), value); + + /// A PATCH body for [rel]: each (multi-segment) key sealed on its own. + Future> sealPatch( + String rel, + Map body, + ) async { + final base = e2eParts(rel); + final kind = layout.classify(base).kind; + if (kind == E2eRuleKind.unit || kind == E2eRuleKind.below) { + throw E2eLayoutError('PATCH into sealed unit $rel'); + } + return { + for (final e in body.entries) + e.key: await _seal([...base, ...e2eParts(e.key)], e.value), + }; + } + + Future _seal(List parts, Object? value) async { + final rule = layout.classify(parts); + if (rule.kind == E2eRuleKind.clear || value == null) return value; + if (rule.kind == E2eRuleKind.unit) { + return await _sealUnit(parts, value, rule.keep); + } + if (rule.kind == E2eRuleKind.struct && value is Map) { + return { + for (final e in value.entries) + e.key as String: await _seal([ + ...parts, + ...e2eParts(e.key as String), + ], e.value), + }; + } + throw E2eLayoutError( + 'no e2e rule for a ${value.runtimeType} at ${parts.join('/')} ' + '(${rule.kind.name})', + ); + } + + Future?> _sealUnit( + List parts, + Object raw, + Set keep, + ) async { + // As RTDB would keep it: no null members, no empty objects. + final value = _pruned(raw); + if (value == null) return null; + var body = value; + final clear = {}; + if (value is Map && keep.isNotEmpty) { + body = { + for (final e in value.entries) + if (!keep.contains(e.key)) e.key as String: e.value, + }; + for (final e in value.entries) { + if (keep.contains(e.key)) clear[e.key as String] = e.value; + } + } + final blob = await cipher.seal(jsonEncode(body), path: _aad(parts)); + return {kSealedKey: blob, ...clear}; + } + + /// [value] read at [rel] with every unit in it opened. A unit that does + /// not open reads as absent; legacy plaintext is returned as stored. + Future open(String rel, Object? value) => + _open(e2eParts(rel), value); + + Future _open(List parts, Object? value) async { + final rule = layout.classify(parts); + switch (rule.kind) { + case E2eRuleKind.unit: + return await _openUnit(parts, value); + case E2eRuleKind.below: + throw E2eLayoutError('read below sealed unit: ${parts.join('/')}'); + case E2eRuleKind.struct when value is Map: + final out = {}; + for (final e in value.entries) { + final v = await _open([...parts, e.key as String], e.value); + if (v != null) out[e.key as String] = v; + } + return out; + case E2eRuleKind.struct when value is List: + return [ + for (var i = 0; i < value.length; i++) + await _open([...parts, '$i'], value[i]), + ]; + case _: + return value; + } + } + + Future _openUnit(List parts, Object? value) async { + if (value is! Map || value[kSealedKey] is! String) return value; + try { + final text = await cipher.open( + value[kSealedKey] as String, + path: _aad(parts), + ); + final data = jsonDecode(text); + if (data is! Map) return data; + return { + ...data.cast(), + for (final e in value.entries) + if (e.key != kSealedKey) e.key as String: e.value, + }; + } on FormatException { + // E2eDecryptError is one: tampered, moved, or another key. + return null; + } + } +} diff --git a/rtdb_relay/dart/lib/src/wrapper_credentials.dart b/rtdb_relay/dart/lib/src/wrapper_credentials.dart new file mode 100644 index 0000000..2d12462 --- /dev/null +++ b/rtdb_relay/dart/lib/src/wrapper_credentials.dart @@ -0,0 +1,72 @@ +/// Desktop sign-in without Google in the browser (todo's pattern). +/// +/// The desktop app is the web build in a Chrome `--app` window, served by the +/// app's PC server (e.g. the tutor's). Google Identity Services cannot sign in +/// programmatically there, and nothing outside the Chrome profile can write its +/// storage. So the server hands the page the PC's own seeded session (e.g. +/// `~/.config/tutor/firebase_auth.json`, written by crdt-sync's +/// `link_google.py`) ONCE, at `/sync-credentials`, and the page keeps it +/// in its own credential store from then on. +library; + +import 'dart:convert'; +import 'dart:developer'; + +import 'package:crdt_sync/crdt_sync.dart' + show FirebaseCredentialStore, FirebaseCredentials; +import 'package:http/http.dart' as http; + +/// Route, relative to the app's base URL (`/app/sync-credentials`). +const kSyncCredentialsRoute = 'sync-credentials'; + +/// The Firebase uid inside [idToken] (JWT `user_id`, else `sub`), or null. +String? uidOfIdToken(String idToken) { + final parts = idToken.split('.'); + if (parts.length != 3) return null; + try { + final payload = jsonDecode( + utf8.decode(base64Url.decode(base64Url.normalize(parts[1]))), + ); + if (payload is! Map) return null; + final uid = payload['user_id'] ?? payload['sub']; + return uid is String ? uid : null; + } on FormatException { + return null; + } +} + +/// Fetches the seeded session from the wrapper at [base] and saves it into +/// [store]. True when adopted. Refuses a session for any uid but +/// [expectedUid]: adopting bypasses the sign-in's wrong-account guard, so +/// the same check is made here. +Future adoptWrapperCredentials({ + required Uri base, + required http.Client client, + required FirebaseCredentialStore store, + required String expectedUid, +}) async { + try { + final res = await client.get(base.resolve(kSyncCredentialsRoute)); + if (res.statusCode != 200) return false; + final body = jsonDecode(utf8.decode(res.bodyBytes)); + if (body is! Map || + body['id_token'] is! String || + body['refresh_token'] is! String || + body['expires_at'] is! String) { + log('wrapper credentials malformed; not adopted', level: 900); + return false; + } + final uid = uidOfIdToken(body['id_token'] as String); + if (uid != expectedUid) { + log('wrapper credentials are for another account', level: 1000); + return false; + } + await store.save(FirebaseCredentials.fromJson(body)); + return true; + } on Object catch (error) { + // `on Object`: no wrapper at all (Android: `Uri.base` is file:///, an + // ArgumentError) or a network error both mean "not adopted". + log('wrapper credentials unavailable', level: 800, error: error); + return false; + } +} diff --git a/rtdb_relay/dart/pubspec.lock b/rtdb_relay/dart/pubspec.lock new file mode 100644 index 0000000..dd3257b --- /dev/null +++ b/rtdb_relay/dart/pubspec.lock @@ -0,0 +1,698 @@ +# Generated by pub +# See https://dart.dev/tools/pub/glossary#lockfile +packages: + args: + dependency: transitive + description: + name: args + sha256: d0481093c50b1da8910eb0bb301626d4d8eb7284aa739614d2b394ee09e3ea04 + url: "https://pub.dev" + source: hosted + version: "2.7.0" + async: + dependency: transitive + description: + name: async + sha256: e2eb0491ba5ddb6177742d2da23904574082139b07c1e33b8503b9f46f3e1a37 + url: "https://pub.dev" + source: hosted + version: "2.13.1" + boolean_selector: + dependency: transitive + description: + name: boolean_selector + sha256: "8aab1771e1243a5063b8b0ff68042d67334e3feab9e95b9490f9a6ebf73b42ea" + url: "https://pub.dev" + source: hosted + version: "2.1.2" + characters: + dependency: transitive + description: + name: characters + sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b + url: "https://pub.dev" + source: hosted + version: "1.4.1" + clock: + dependency: transitive + description: + name: clock + sha256: e51d50bca3217c9a9fa2b41a30e4a38971133f5f9ec7a3d57bae095007f1d28e + url: "https://pub.dev" + source: hosted + version: "1.1.3" + code_assets: + dependency: transitive + description: + name: code_assets + sha256: "1ef22a0be3af9370bd9481ac76db114db92bfe75d5ca2b2d7bc911764478a4d9" + url: "https://pub.dev" + source: hosted + version: "2.2.0" + collection: + dependency: transitive + description: + name: collection + sha256: "2f5709ae4d3d59dd8f7cd309b4e023046b57d8a6c82130785d2b0e5868084e76" + url: "https://pub.dev" + source: hosted + version: "1.19.1" + crdt_sync: + dependency: "direct main" + description: + path: crdt_sync_dart + ref: "crdt_sync_dart-v0.14.1" + resolved-ref: edd0f7a7882cb1d3904932ba94faa282d08165df + url: "https://github.com/kuhyx/utils" + source: git + version: "0.14.1" + crdt_sync_flutter: + dependency: "direct main" + description: + path: crdt_sync_flutter + ref: "crdt_sync_flutter-v0.8.2" + resolved-ref: "1962d303336dfe260850466b8ee841033b9ad1ce" + url: "https://github.com/kuhyx/utils" + source: git + version: "0.8.2" + crypto: + dependency: transitive + description: + name: crypto + sha256: e3626ae6270383c9e3a549f34c9e4cd26c09ae6a9adaab2bf4737a00340efdc4 + url: "https://pub.dev" + source: hosted + version: "3.0.8" + cryptography: + dependency: transitive + description: + name: cryptography + sha256: "3eda3029d34ec9095a27a198ac9785630fe525c0eb6a49f3d575272f8e792ef0" + url: "https://pub.dev" + source: hosted + version: "2.9.0" + cupertino_ui: + dependency: transitive + description: + name: cupertino_ui + sha256: c3eaf7f5bdfee36deb0b14a4cbf7602f1b6b8d8b8576b81f38fc08c25881c94c + url: "https://pub.dev" + source: hosted + version: "1.1.7" + fake_async: + dependency: "direct dev" + description: + name: fake_async + sha256: "5368f224a74523e8d2e7399ea1638b37aecfca824a3cc4dfdf77bf1fa905ac44" + url: "https://pub.dev" + source: hosted + version: "1.3.3" + ffi: + dependency: transitive + description: + name: ffi + sha256: "6d7fd89431262d8f3125e81b50d3847a091d846eafcd4fdb88dd06f36d705a45" + url: "https://pub.dev" + source: hosted + version: "2.2.0" + ffi_leak_tracker: + dependency: transitive + description: + name: ffi_leak_tracker + sha256: "4093d4ef9ca06ffe2786e73bfb25e22aa92112b9bb4ec941f11e3e6b61489a97" + url: "https://pub.dev" + source: hosted + version: "0.1.2" + file: + dependency: transitive + description: + name: file + sha256: a3b4f84adafef897088c160faf7dfffb7696046cb13ae90b508c2cbc95d3b8d4 + url: "https://pub.dev" + source: hosted + version: "7.0.1" + fixnum: + dependency: transitive + description: + name: fixnum + sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be + url: "https://pub.dev" + source: hosted + version: "1.1.1" + flutter: + dependency: "direct main" + description: flutter + source: sdk + version: "0.0.0" + flutter_localizations: + dependency: transitive + description: flutter + source: sdk + version: "0.0.0" + flutter_secure_storage: + dependency: "direct main" + description: + name: flutter_secure_storage + sha256: d4e1fb6b2cb524868929e78dc0282fa000554b22060fb53789dc481c9fc95bb8 + url: "https://pub.dev" + source: hosted + version: "11.2.0" + flutter_secure_storage_darwin: + dependency: transitive + description: + name: flutter_secure_storage_darwin + sha256: a031ceac9b070e62ef183cd7f7d1a8798ebde402d5049f0fe6eb3a51bd797a21 + url: "https://pub.dev" + source: hosted + version: "0.4.3" + flutter_secure_storage_linux: + dependency: transitive + description: + name: flutter_secure_storage_linux + sha256: caa75bd78f017422912e3a904933113b2428eb79f981ac37acd2dd2a700458ea + url: "https://pub.dev" + source: hosted + version: "3.0.3" + flutter_secure_storage_platform_interface: + dependency: transitive + description: + name: flutter_secure_storage_platform_interface + sha256: "64951127f001f546891c86f414972bf49ef2c4c8a4c92c65f5790cc0c9100045" + url: "https://pub.dev" + source: hosted + version: "2.1.1" + flutter_secure_storage_web: + dependency: transitive + description: + name: flutter_secure_storage_web + sha256: "073a62b3aeb866ab4ce795f960413948e51e5a42a9b0c8333b6daf5bb3208a1c" + url: "https://pub.dev" + source: hosted + version: "2.1.1" + flutter_secure_storage_windows: + dependency: transitive + description: + name: flutter_secure_storage_windows + sha256: "471951813a97006d899db4948acc654a4f28c440083ea08178935ce20b173ec1" + url: "https://pub.dev" + source: hosted + version: "4.2.2" + flutter_test: + dependency: "direct dev" + description: flutter + source: sdk + version: "0.0.0" + flutter_web_plugins: + dependency: transitive + description: flutter + source: sdk + version: "0.0.0" + google_account_token: + dependency: transitive + description: + path: google_account_token + ref: "google_account_token-v0.1.0" + resolved-ref: db70ba204d124c6eadf9b8808cd3d3b3e70363d1 + url: "https://github.com/kuhyx/utils" + source: git + version: "0.1.0" + hooks: + dependency: transitive + description: + name: hooks + sha256: eaac480a35ec0814146c2c48d96aaa829e0e44a7662c88ae84c9edf4bc35651f + url: "https://pub.dev" + source: hosted + version: "2.2.0" + http: + dependency: "direct main" + description: + name: http + sha256: "87721a4a50b19c7f1d49001e51409bddc46303966ce89a65af4f4e6004896412" + url: "https://pub.dev" + source: hosted + version: "1.6.0" + http_parser: + dependency: transitive + description: + name: http_parser + sha256: "178d74305e7866013777bab2c3d8726205dc5a4dd935297175b19a23a2e66571" + url: "https://pub.dev" + source: hosted + version: "4.1.2" + intl: + dependency: transitive + description: + name: intl + sha256: "1ca20c894b1717686a2319b8548763d812bc0aabdac580420a44c5178c57a867" + url: "https://pub.dev" + source: hosted + version: "0.20.3" + jni: + dependency: transitive + description: + name: jni + sha256: "2e91e6087291affd10b31b6c872f3e3ac7dc5d93b51b5ba485d930c8f08bde6c" + url: "https://pub.dev" + source: hosted + version: "1.1.2" + jni_flutter: + dependency: transitive + description: + name: jni_flutter + sha256: "0dd33d67797560f66e961a6053882d4df54bd345bf063b8fe7ea133f7ad8b191" + url: "https://pub.dev" + source: hosted + version: "1.0.4+1" + jni_util: + dependency: transitive + description: + name: jni_util + sha256: "1ba86da04a5f2bf18fde2edb235587e70c5b0fc5bd4ba955f46b00942c3fc35f" + url: "https://pub.dev" + source: hosted + version: "1.0.0" + leak_tracker: + dependency: transitive + description: + name: leak_tracker + sha256: "33e2e26bdd85a0112ec15400c8cbffea70d0f9c3407491f672a2fad47915e2de" + url: "https://pub.dev" + source: hosted + version: "11.0.2" + leak_tracker_flutter_testing: + dependency: transitive + description: + name: leak_tracker_flutter_testing + sha256: "1dbc140bb5a23c75ea9c4811222756104fbcd1a27173f0c34ca01e16bea473c1" + url: "https://pub.dev" + source: hosted + version: "3.0.10" + leak_tracker_testing: + dependency: transitive + description: + name: leak_tracker_testing + sha256: "8d5a2d49f4a66b49744b23b018848400d23e54caf9463f4eb20df3eb8acb2eb1" + url: "https://pub.dev" + source: hosted + version: "3.0.2" + listen: + dependency: transitive + description: + name: listen + sha256: "47501a08016a43fcad79252439d723f50f14f88fa7bfd8a177e0a417e5c9e1f2" + url: "https://pub.dev" + source: hosted + version: "1.0.1" + logging: + dependency: transitive + description: + name: logging + sha256: c8245ada5f1717ed44271ed1c26b8ce85ca3228fd2ffdb75468ab01979309d61 + url: "https://pub.dev" + source: hosted + version: "1.3.0" + matcher: + dependency: transitive + description: + name: matcher + sha256: "31bd099b47c10cd1aeb55146a2d46ce0277630ecef3f7dae54ad7873f36696cd" + url: "https://pub.dev" + source: hosted + version: "0.12.20" + material_color_utilities: + dependency: transitive + description: + name: material_color_utilities + sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b" + url: "https://pub.dev" + source: hosted + version: "0.13.0" + material_ui: + dependency: transitive + description: + name: material_ui + sha256: "474c135fd46b56ff1d35ca982155e8863d28fbc6464d1192acf4ee53a738680e" + url: "https://pub.dev" + source: hosted + version: "1.11.0" + meta: + dependency: transitive + description: + name: meta + sha256: "307249ce4ff29d58a18e97f6345f539382eb9c9c29ecda628900f31de0443dd9" + url: "https://pub.dev" + source: hosted + version: "1.19.0" + objective_c: + dependency: transitive + description: + name: objective_c + sha256: c965d264fd4b0b4dd402dce9d049b70656bf98d3ca108b9bc55d2544ceadbe5e + url: "https://pub.dev" + source: hosted + version: "9.6.4" + package_config: + dependency: transitive + description: + name: package_config + sha256: ffcf4cf3d6c0b74ac43708d9f56625506e8a68aa935abe9d267a7330f320eb5d + url: "https://pub.dev" + source: hosted + version: "3.0.0" + path: + dependency: transitive + description: + name: path + sha256: "75cca69d1490965be98c73ceaea117e8a04dd21217b37b292c9ddbec0d955bc5" + url: "https://pub.dev" + source: hosted + version: "1.9.1" + path_provider: + dependency: transitive + description: + name: path_provider + sha256: a7f4874f987173da295a61c181b8ee71dab59b332a486b391babf26a1b884825 + url: "https://pub.dev" + source: hosted + version: "2.1.6" + path_provider_android: + dependency: transitive + description: + name: path_provider_android + sha256: "69cbd515a62b94d32a7944f086b2f82b4ac40a1d45bebfc00813a430ab2dabcd" + url: "https://pub.dev" + source: hosted + version: "2.3.1" + path_provider_foundation: + dependency: transitive + description: + name: path_provider_foundation + sha256: "2a376b7d6392d80cd3705782d2caa734ca4727776db0b6ec36ef3f1855197699" + url: "https://pub.dev" + source: hosted + version: "2.6.0" + path_provider_linux: + dependency: transitive + description: + name: path_provider_linux + sha256: "58c2005f147315b11e9b4a7bc889cd5203e250cba8e3f012dae259b4972b5c16" + url: "https://pub.dev" + source: hosted + version: "2.2.2" + path_provider_platform_interface: + dependency: transitive + description: + name: path_provider_platform_interface + sha256: "484838772624c3a4b94f1e44a3e19897fee738f2d5c4ce448443b0417f7c9dda" + url: "https://pub.dev" + source: hosted + version: "2.1.3" + path_provider_windows: + dependency: transitive + description: + name: path_provider_windows + sha256: bd6f00dbd873bfb70d0761682da2b3a2c2fccc2b9e84c495821639601d81afe7 + url: "https://pub.dev" + source: hosted + version: "2.3.0" + platform: + dependency: transitive + description: + name: platform + sha256: a36d119c13416516a7b5913fbe8af8531e11633d784c550b2125f76c758524ec + url: "https://pub.dev" + source: hosted + version: "3.2.0" + plugin_platform_interface: + dependency: transitive + description: + name: plugin_platform_interface + sha256: "4820fbfdb9478b1ebae27888254d445073732dae3d6ea81f0b7e06d5dedc3f02" + url: "https://pub.dev" + source: hosted + version: "2.1.8" + pub_semver: + dependency: transitive + description: + name: pub_semver + sha256: "261236774e8b1d69cfc6b9eabbc96c40f25e7a2d6b171f3385d4f65d5734fb24" + url: "https://pub.dev" + source: hosted + version: "2.2.1" + record_use: + dependency: transitive + description: + name: record_use + sha256: "1cb8564af8d43b464294411db9217f5ec04891c6f22ee2c32d73ae05e88a6bd2" + url: "https://pub.dev" + source: hosted + version: "1.1.1" + shared_preferences: + dependency: transitive + description: + name: shared_preferences + sha256: "1e85e0dccf5b4a016077fea7dfbb4a7cb39c759ac1596fcf60c06deadb7da91f" + url: "https://pub.dev" + source: hosted + version: "2.5.6" + shared_preferences_android: + dependency: transitive + description: + name: shared_preferences_android + sha256: "137dedccacb394b8f470d6c9b435ffc3d33faaa6ce2949c4f54a61007d64396d" + url: "https://pub.dev" + source: hosted + version: "2.5.5" + shared_preferences_foundation: + dependency: transitive + description: + name: shared_preferences_foundation + sha256: "89435cb71ecb1ad1bf29ef73a381f871a06f433d4182b7e2ba7243b02b2c544b" + url: "https://pub.dev" + source: hosted + version: "2.6.2" + shared_preferences_linux: + dependency: transitive + description: + name: shared_preferences_linux + sha256: "580abfd40f415611503cae30adf626e6656dfb2f0cee8f465ece7b6defb40f2f" + url: "https://pub.dev" + source: hosted + version: "2.4.1" + shared_preferences_platform_interface: + dependency: transitive + description: + name: shared_preferences_platform_interface + sha256: "649dc798a33931919ea356c4305c2d1f81619ea6e92244070b520187b5140ef9" + url: "https://pub.dev" + source: hosted + version: "2.4.2" + shared_preferences_web: + dependency: transitive + description: + name: shared_preferences_web + sha256: c49bd060261c9a3f0ff445892695d6212ff603ef3115edbb448509d407600019 + url: "https://pub.dev" + source: hosted + version: "2.4.3" + shared_preferences_windows: + dependency: transitive + description: + name: shared_preferences_windows + sha256: "94ef0f72b2d71bc3e700e025db3710911bd51a71cefb65cc609dd0d9a982e3c1" + url: "https://pub.dev" + source: hosted + version: "2.4.1" + sky_engine: + dependency: transitive + description: flutter + source: sdk + version: "0.0.0" + source_span: + dependency: transitive + description: + name: source_span + sha256: "56a02f1f4cd1a2d96303c0144c93bd6d909eea6bee6bf5a0e0b685edbd4c47ab" + url: "https://pub.dev" + source: hosted + version: "1.10.2" + stack_trace: + dependency: transitive + description: + name: stack_trace + sha256: "277654b3034d17ac6f9f1cb5595db011b1d5d41e8806866db28e0abaa101c490" + url: "https://pub.dev" + source: hosted + version: "1.12.2" + stream_channel: + dependency: transitive + description: + name: stream_channel + sha256: "969e04c80b8bcdf826f8f16579c7b14d780458bd97f56d107d3950fdbeef059d" + url: "https://pub.dev" + source: hosted + version: "2.1.4" + string_scanner: + dependency: transitive + description: + name: string_scanner + sha256: "921cd31725b72fe181906c6a94d987c78e3b98c2e205b397ea399d4054872b43" + url: "https://pub.dev" + source: hosted + version: "1.4.1" + term_glyph: + dependency: transitive + description: + name: term_glyph + sha256: "7f554798625ea768a7518313e58f83891c7f5024f88e46e7182a4558850a4b8e" + url: "https://pub.dev" + source: hosted + version: "1.2.2" + test_api: + dependency: transitive + description: + name: test_api + sha256: "0a10344e901e5b2e63819567951cb6a06673ed6b84f40462188ff5a0c41f371f" + url: "https://pub.dev" + source: hosted + version: "0.7.14" + typed_data: + dependency: transitive + description: + name: typed_data + sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006 + url: "https://pub.dev" + source: hosted + version: "1.4.0" + url_launcher: + dependency: transitive + description: + name: url_launcher + sha256: e8cc955c97e06df9879140a1fe301f3d493f01b7c62dec7f46834be31d7e9fda + url: "https://pub.dev" + source: hosted + version: "6.3.3" + url_launcher_android: + dependency: transitive + description: + name: url_launcher_android + sha256: b8073b1e5173d63afe1a18985a75896d72f759d3bc1817eb1ae8d26e8527cceb + url: "https://pub.dev" + source: hosted + version: "6.3.35" + url_launcher_ios: + dependency: transitive + description: + name: url_launcher_ios + sha256: "8faa1aab294f1ab4040b43660c887b0418d5fa4f0cffef76a484e6aa1092eb4a" + url: "https://pub.dev" + source: hosted + version: "6.4.2" + url_launcher_linux: + dependency: transitive + description: + name: url_launcher_linux + sha256: "10f86fef4c2c43563fa6c211ff9cf757adf4d3ab762c56bd430664a947d70cd0" + url: "https://pub.dev" + source: hosted + version: "3.2.3" + url_launcher_macos: + dependency: transitive + description: + name: url_launcher_macos + sha256: "5e835a3b869c2d70325349c81c5a45c28e20791265b67b2669da6b08c5cd5201" + url: "https://pub.dev" + source: hosted + version: "3.2.6" + url_launcher_platform_interface: + dependency: transitive + description: + name: url_launcher_platform_interface + sha256: "552f8a1e663569be95a8190206a38187b531910283c3e982193e4f2733f01029" + url: "https://pub.dev" + source: hosted + version: "2.3.2" + url_launcher_web: + dependency: transitive + description: + name: url_launcher_web + sha256: "85c81589622fbc87c1c683aaea164d3604a7777495a79d91e39ffcdec39ddb34" + url: "https://pub.dev" + source: hosted + version: "2.4.3" + url_launcher_windows: + dependency: transitive + description: + name: url_launcher_windows + sha256: "6c5ad3f22cd4c38e089b81963b3cd7bb83b111b2df5dce008bb066162f42e429" + url: "https://pub.dev" + source: hosted + version: "3.1.6" + uuid: + dependency: transitive + description: + name: uuid + sha256: "9b129329f58692f6e6578329498a8fe9fbe98f090beb764ffbb8ee2eadd01dcd" + url: "https://pub.dev" + source: hosted + version: "4.6.0" + vector_math: + dependency: transitive + description: + name: vector_math + sha256: fa49e1674cb84acb900141714e6c6e1f9ae099827c24d141430ff6819db4e1bc + url: "https://pub.dev" + source: hosted + version: "2.4.4" + very_good_analysis: + dependency: "direct dev" + description: + name: very_good_analysis + sha256: "0bd5eb8d6be76aa0d71e70cbdae6cac8f784f761170568e3c2214a6948c7f6d3" + url: "https://pub.dev" + source: hosted + version: "11.0.0" + vm_service: + dependency: transitive + description: + name: vm_service + sha256: "89b11d62e1040ee681af3b4f1c97a803ecbf010c6e8b9c5896ee5b08c3bf7b78" + url: "https://pub.dev" + source: hosted + version: "15.4.0" + web: + dependency: transitive + description: + name: web + sha256: e119e82ac4795c7925103b7cf3768191f33941b99e7ccffbd6c645201d9f606b + url: "https://pub.dev" + source: hosted + version: "1.1.2" + win32: + dependency: transitive + description: + name: win32 + sha256: a0b93865d5644f11cf6a8c3f6db909f1ec168958b5805f6cc684adea957cd63d + url: "https://pub.dev" + source: hosted + version: "6.4.0" + xdg_directories: + dependency: transitive + description: + name: xdg_directories + sha256: "7a3f37b05d989967cdddcbb571f1ea834867ae2faa29725fd085180e0883aa15" + url: "https://pub.dev" + source: hosted + version: "1.1.0" + yaml: + dependency: transitive + description: + name: yaml + sha256: f67cdd8e07d3c6329146aaef1ba043542b3134c12489f553ca9a7435d1068aea + url: "https://pub.dev" + source: hosted + version: "3.1.4" +sdks: + dart: ">=3.13.5 <4.0.0" + flutter: ">=3.47.0" diff --git a/rtdb_relay/dart/pubspec.yaml b/rtdb_relay/dart/pubspec.yaml new file mode 100644 index 0000000..480f30e --- /dev/null +++ b/rtdb_relay/dart/pubspec.yaml @@ -0,0 +1,32 @@ +name: rtdb_relay +description: >- + The Flutter client half of the sealed Firebase RTDB request relay (the PC + half is the Python rtdb_relay next to this directory). Extracted from the + tutor app; any app that talks to a PC worker over RTDB reuses it. +publish_to: 'none' +version: 0.2.0 + +environment: + sdk: ^3.13.5 + +dependencies: + crdt_sync: + git: + url: https://github.com/kuhyx/utils + ref: crdt_sync_dart-v0.14.1 + path: crdt_sync_dart + crdt_sync_flutter: + git: + url: https://github.com/kuhyx/utils + ref: crdt_sync_flutter-v0.8.2 + path: crdt_sync_flutter + flutter: + sdk: flutter + flutter_secure_storage: 11.2.0 + http: 1.6.0 + +dev_dependencies: + fake_async: 1.3.3 + flutter_test: + sdk: flutter + very_good_analysis: ^11.0.0 diff --git a/rtdb_relay/dart/scripts/check_coverage.sh b/rtdb_relay/dart/scripts/check_coverage.sh new file mode 100755 index 0000000..6e90bbd --- /dev/null +++ b/rtdb_relay/dart/scripts/check_coverage.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +# ============================================================================ +# Fail if lcov line coverage drops below a threshold. +# +# Thin delegate to the shared gate in ~/src/utils/scripts, which owns the parsing +# and the threshold comparison. This file used to be a byte-identical copy of +# that logic; three such copies existed, which is how one package's idea of +# "covered" drifts from every other package's. +# +# Usage: check_coverage.sh +# ============================================================================ + +set -euo pipefail + +# Repo-relative, resolved from this script's own location: an absolute +# /home/... path exits 127 on an Actions runner. +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +readonly SCRIPT_DIR +readonly SHARED_GATE="${SCRIPT_DIR}/../../../scripts/check_coverage.sh" + +main() { + if [[ ! -f "$SHARED_GATE" ]]; then + echo "Error: shared coverage gate not found at $SHARED_GATE" >&2 + echo " It lives in the utils repo at scripts/check_coverage.sh." >&2 + exit 1 + fi + + exec bash "$SHARED_GATE" "$@" +} + +main "$@" diff --git a/rtdb_relay/dart/test/auth_test.dart b/rtdb_relay/dart/test/auth_test.dart new file mode 100644 index 0000000..f986f15 --- /dev/null +++ b/rtdb_relay/dart/test/auth_test.dart @@ -0,0 +1,103 @@ +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' + show + FirebaseAuthError, + FirebaseCredentialStore, + FirebaseCredentials, + InMemoryCredentialStore; +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/auth.dart'; + +const _config = RelayFirebaseConfig( + apiKey: 'key', + databaseUrl: 'https://db', + syncUid: 'right-uid', + serverClientId: '', +); + +MockClient _idp(String uid) => MockClient( + (_) async => http.Response( + jsonEncode({ + 'localId': uid, + 'idToken': 'id-1', + 'refreshToken': 'refresh-1', + 'expiresIn': '3600', + }), + 200, + ), +); + +class _BrokenStore extends InMemoryCredentialStore { + @override + Future load() => throw ArgumentError('Uri.base'); +} + +// The default sign-in: declines when no client id is compiled in. +Future _google({required String serverClientId}) async => + serverClientId.isEmpty ? null : 'g'; + +RelayAuth _auth(FirebaseCredentialStore store, [http.Client? client]) => + RelayAuth( + config: _config, + googleToken: _google, + store: store, + httpClient: client, + ); + +void main() { + test('right account: session stored, token served', () async { + final store = InMemoryCredentialStore(); + final auth = _auth(store, _idp('right-uid')); + expect(await auth.hasSession(), isFalse); + final out = await auth.signInWithGoogle(tokenFetcher: () async => 'g'); + expect(out, SignInOutcome.signedIn); + expect(await auth.hasSession(), isTrue); + expect(await auth.idToken(), 'id-1'); + await auth.signOut(); + expect(await store.load(), isNull); + }); + + test('wrong account throws and stores nothing', () async { + final store = InMemoryCredentialStore(); + final auth = _auth(store, _idp('second-user')); + await expectLater( + auth.signInWithGoogle(tokenFetcher: () async => 'g'), + throwsA(isA()), + ); + expect(await store.load(), isNull); + }); + + test('cancelled picker and missing client id are not errors', () async { + final auth = _auth(InMemoryCredentialStore()); + expect( + await auth.signInWithGoogle(tokenFetcher: () async => null), + SignInOutcome.cancelled, + ); + // No client id compiled in: the default fetcher declines. + expect(await auth.signInWithGoogle(), SignInOutcome.cancelled); + }); + + test('a store that throws an Error reads as signed out', () async { + final auth = _auth(_BrokenStore()); + expect(await auth.hasSession(), isFalse); + }); + + test('the adopt hook signs in a desktop with no session', () async { + final store = InMemoryCredentialStore(); + var asked = 0; + final auth = RelayAuth( + config: _config, + googleToken: _google, + store: store, + adopt: () async { + asked++; + return false; + }, + ); + expect(await auth.hasSession(), isFalse); + expect(asked, 1); + }); +} diff --git a/rtdb_relay/dart/test/data/e2e_vectors.json b/rtdb_relay/dart/test/data/e2e_vectors.json new file mode 100644 index 0000000..5ab7a69 --- /dev/null +++ b/rtdb_relay/dart/test/data/e2e_vectors.json @@ -0,0 +1,266 @@ +{ + "key_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", + "root": "tutor/v1-e2e", + "sealed_key": "_e2e", + "rules": [ + { + "path": "", + "kind": "struct" + }, + { + "path": "meta", + "kind": "clear" + }, + { + "path": "meta/min_client", + "kind": "clear" + }, + { + "path": "rev", + "kind": "clear" + }, + { + "path": "rev/catalog", + "kind": "clear" + }, + { + "path": "live", + "kind": "unit" + }, + { + "path": "prefs", + "kind": "struct" + }, + { + "path": "prefs/current_subject", + "kind": "unit" + }, + { + "path": "stats", + "kind": "struct" + }, + { + "path": "stats/today", + "kind": "unit" + }, + { + "path": "stats/today/new_cap", + "kind": "below" + }, + { + "path": "presence/workers/d1", + "kind": "unit" + }, + { + "path": "presence/clients/d1", + "kind": "unit" + }, + { + "path": "uploads/u1/c0001", + "kind": "unit" + }, + { + "path": "requests", + "kind": "struct" + }, + { + "path": "requests/r1", + "kind": "struct" + }, + { + "path": "requests/r1/req", + "kind": "unit" + }, + { + "path": "requests/r1/claim", + "kind": "clear" + }, + { + "path": "requests/r1/claim/by", + "kind": "clear" + }, + { + "path": "requests/r1/result", + "kind": "unit" + }, + { + "path": "sessions/s1", + "kind": "struct" + }, + { + "path": "sessions/s1/meta", + "kind": "struct" + }, + { + "path": "sessions/s1/meta/busy", + "kind": "unit" + }, + { + "path": "sessions/s1/meta/busy/phase", + "kind": "below" + }, + { + "path": "sessions/s1/msgs/m0001", + "kind": "unit" + }, + { + "path": "sessions/s1/receipts/r0001", + "kind": "unit" + }, + { + "path": "sessions/s1/user", + "kind": "struct" + }, + { + "path": "sessions/s1/user/archived", + "kind": "unit" + }, + { + "path": "sessions/s1/progress", + "kind": "struct" + }, + { + "path": "sessions/s1/progress/rid", + "kind": "clear" + }, + { + "path": "sessions/s1/progress/steps/s0001", + "kind": "unit" + }, + { + "path": "session_index/s1", + "kind": "unit" + }, + { + "path": "subjects/car/meta", + "kind": "unit" + }, + { + "path": "subjects/car/meta/rev", + "kind": "below" + }, + { + "path": "subjects/car/plan", + "kind": "unit" + }, + { + "path": "subjects/car/cards", + "kind": "unit" + }, + { + "path": "subjects/car/concepts", + "kind": "unit" + }, + { + "path": "log/d1", + "kind": "struct" + }, + { + "path": "log/d1/e1", + "kind": "unit" + }, + { + "path": "feedback/f1", + "kind": "unit" + }, + { + "path": "migration/v1_copied_at", + "kind": "clear" + }, + { + "path": "secrets", + "kind": "unknown" + }, + { + "path": "sessions/s1/other", + "kind": "unknown" + } + ], + "units": [ + { + "path": "requests/01J0000000000000000000000R/req", + "value": { + "kind": "message", + "dev": "d1", + "created": 1800000000000, + "sent_at": 1799999999000, + "body": { + "session": "20261012-170448-5b71", + "text": "zażółć gęślą jaźń" + } + }, + "stored": { + "_e2e": "AVnxpT1g95cKDT1ORKsCeyjnBNJGfjyto/ezodv1ysIc2zHOmj77unCOLXQqYgQjvbfbNub710heso/QkMAUS5Mq+M5+/yIW56HevylofoiyPapWi7obYbu9otQwuOUeiQzutdJpQNw9x7dfUPLZAu1BRQoboIyCG0TrNH3X9LkBIRgWLHOpf3lxhmXGJht3muR4lS4zwDOxj7pB1lRluLM/mnJcXqzDdmgHHw==", + "created": 1800000000000 + } + }, + { + "path": "requests/01J0000000000000000000000R/result", + "value": { + "ok": true, + "at": 1800000000500, + "data": { + "msg": "m0002" + } + }, + "stored": { + "_e2e": "AREDDVq3hgmR9xsL5pUrhSJbK+fBCm823Hx8oKUo+ExwPT342IvIEqu55Rog+u4wWXxON6Vy5xxJZwd4+gXfxkQ49j6cb+H0tyRO", + "at": 1800000000500 + } + }, + { + "path": "presence/clients/d1", + "value": { + "platform": "android", + "app": "1.0.0", + "seen": 1800000000000 + }, + "stored": { + "_e2e": "AYhbgKJJ4tsHmFB0THKTxQoCzwKOpa/3ioNcYmtj2UhmhRZyavA7614RT6y3aPAmBWf5uNhQgkKKOO+Qavw4XAad+7xttA23RB7Xhb0=", + "seen": 1800000000000 + } + }, + { + "path": "prefs/current_subject", + "value": "car", + "stored": { + "_e2e": "AWEy8u/msdxYHsp7PQ0jkzrYpdNP6SEqbJ0SUyqzT2DzoEpXRf+1vKAQVh1hUQ==" + } + }, + { + "path": "sessions/20261012-170448-5b71/user/archived", + "value": true, + "stored": { + "_e2e": "AbS7aTNu+meRs1jvcw/alGgKKgbhV83VPihFMd8AmqW6QhwgCQMg46hnrJls" + } + }, + { + "path": "log/d1/01J0000000000000000000000E", + "value": { + "type": "review", + "card": "ld-x", + "r": 3, + "t": 1800000000000 + }, + "stored": { + "_e2e": "ASqR1ybCH4+WKx7P0nihgr8IOcGMsw1fXXyigH7kgrAZHru4DX0lXW2cZF0DPwQxeay3dS36BYXPN6OgO8xnXjcTz3hUwjjlVLANzZvG0zICImA8rBDy5bInd/INDmc5" + } + } + ], + "header": { + "path": "tutor/e2e", + "passphrase": "correct horse", + "text": "{\"v\":1,\"kdf\":\"argon2id\",\"salt\":\"67H6FMZ+zlSFuBRuMIy2IQ==\",\"m\":8,\"t\":1,\"p\":1,\"check\":\"JQdQLQiowhtNkztQDPtOOUARTzUStpsKZmPHGZXEJ/8=\"}", + "unit": { + "path": "log/0b6f2c1e-8f2a-4c1d-9e3b-7a5d4c3b2a10/01J0000000000000000000000E", + "value": { + "type": "review", + "card": "ld-x", + "r": 3 + }, + "stored": { + "_e2e": "ATvPPA3qI5F70kbmI3XDguYjUsmQZQD2j8fY85sGGOg5IcxeYQn4mbWichyVU82pQQ7WA1YDngEs0K17HImxMyJSUf2H622XzinCPSqN" + } + } + } +} diff --git a/rtdb_relay/dart/test/differential_test.dart b/rtdb_relay/dart/test/differential_test.dart new file mode 100644 index 0000000..e6dd449 --- /dev/null +++ b/rtdb_relay/dart/test/differential_test.dart @@ -0,0 +1,113 @@ +// Old vs new: the tutor's pre-extraction sealer (frozen copy) and the +// package's RelaySealer over the tutor layout must agree byte for byte, or +// the APK already on the phone stops reading what the new code writes. +import 'dart:convert'; +import 'dart:math'; +import 'dart:typed_data'; + +import 'package:crdt_sync/crdt_sync.dart' show E2eCipher; +import 'package:flutter_test/flutter_test.dart'; +import 'package:rtdb_relay/src/layout.dart'; +import 'package:rtdb_relay/src/sealer.dart'; + +import 'support/legacy_tutor_seal.dart' as old; +import 'support/tutor_layout.dart'; + +const _segments = [ + 'requests', + 'req', + 'result', + 'claim', + 'presence', + 'workers', + 'clients', + 'sessions', + 'meta', + 'msgs', + 'receipts', + 'user', + 'progress', + 'steps', + 'rid', + 'subjects', + 'plan', + 'cards', + 'concepts', + 'log', + 'feedback', + 'uploads', + 'live', + 'prefs', + 'stats', + 'rev', + 'migration', + 'session_index', + 'x', + '1', +]; + +List _path(Random rng) => [ + for (var i = 0, n = rng.nextInt(6); i < n; i++) + _segments[rng.nextInt(_segments.length)], +]; + +/// A sealable value for the unit at [parts]: a map holding its clear fields. +Object? _value(Random rng, Set keep) => { + 'n': rng.nextInt(1000), + 'text': 'v${rng.nextInt(99)}', + for (final k in keep) k: rng.nextInt(1 << 30), +}; + +void main() { + final cipher = E2eCipher( + Uint8List.fromList(List.generate(32, (i) => i * 7 % 256)), + ); + final before = old.TutorSealer(cipher); + final after = RelaySealer(cipher, layout: tutorLayout); + + test('same root and the same rule for 20000 random paths', () { + expect(tutorLayout.root, old.kE2eLayout.prefix); + final rng = Random(20261117); + for (var i = 0; i < 20000; i++) { + final parts = _path(rng); + final a = old.classifyE2e(parts); + final b = tutorLayout.classify(parts); + expect( + [b.kind.name, b.depth, b.keep], + [a.kind.name, a.depth, a.keep], + reason: parts.join('/'), + ); + expect( + tutorLayout.unitPath(parts.join('/')), + old.e2eUnitPath(parts.join('/')), + ); + } + }); + + test( + 'a unit sealed by either side opens on the other, identically', + () async { + final rng = Random(7); + var units = 0; + for (var i = 0; i < 40000 && units < 300; i++) { + final parts = _path(rng); + final rule = tutorLayout.classify(parts); + if (rule.kind != E2eRuleKind.unit) continue; + units++; + final rel = parts.join('/'); + final value = _value(rng, rule.keep); + final sealedOld = await before.seal(rel, value); + final sealedNew = await after.seal(rel, value); + // Nonces differ; the clear siblings and the shape must not. + String strip(Object? v) => jsonEncode({ + for (final e in (v! as Map).entries) + if (e.key != kSealedKey) e.key: e.value, + }); + expect(strip(sealedNew), strip(sealedOld)); + expect(await after.open(rel, sealedOld), value); + expect(await before.open(rel, sealedNew), value); + } + expect(units, 300); + }, + ); +} diff --git a/rtdb_relay/dart/test/e2e_gate_test.dart b/rtdb_relay/dart/test/e2e_gate_test.dart new file mode 100644 index 0000000..9e7538e --- /dev/null +++ b/rtdb_relay/dart/test/e2e_gate_test.dart @@ -0,0 +1,123 @@ +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' show E2eLayout, E2eLockReason; +import 'package:crdt_sync_flutter/crdt_sync_flutter.dart' + show kE2ePassphraseKey; +import 'package:crdt_sync_flutter/testing/fake_secure_storage.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:rtdb_relay/src/e2e_gate.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/layout.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; + +import 'support/e2e_fixture.dart'; +import 'support/fake_rtdb.dart'; +import 'support/tutor_layout.dart'; + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + test('a client that needs a key sends nothing without one', () async { + final db = FakeRtdb(); + final client = RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://fake', + idToken: () async => 'tok', + httpClient: db.client().httpClient, + namespace: '', + sealRequired: true, + ); + await expectLater( + client.put('tutor/v1-e2e/requests/$testRid/req', {'kind': 'x'}), + throwsA(isA()), + ); + await expectLater( + client.get('tutor/v1-e2e/live'), + throwsA(isA()), + ); + await expectLater( + client.delete('tutor/v1-e2e/live'), + throwsA(isA()), + ); + expect(db.log, isEmpty); + expect(E2eGate(client: client).locked, isTrue); + expect(E2eGate(client: db.client()).locked, isFalse); + expect(await E2eGate(client: db.client()).unlock(), isTrue); + }); + + group('E2eGate', () { + RtdbClient needy(FakeRtdb db) => RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://fake', + idToken: () async => 'tok', + httpClient: db.client().httpClient, + namespace: '', + sealRequired: true, + ); + + test('unlocks from the keystore and makes the header once', () async { + installFakeSecureStorage(initial: {kE2ePassphraseKey: 'test-passphrase'}); + final db = FakeRtdb(); + final client = needy(db); + final gate = E2eGate(client: client, params: fastArgon); + expect(await gate.unlock(), isTrue); + expect(gate.locked, isFalse); + expect(await gate.unlock(), isTrue); // already open + final header = getAt(db.root, E2eLayout.of(tutorLayout.base).e2ePath); + expect(header, isA()); + await client.put('tutor/v1-e2e/live', {'session': 'x'}); + expect( + jsonEncode(getAt(db.root, 'tutor/v1-e2e/live')), + contains(kSealedKey), + ); + // A second device with the same passphrase reads the same key. + final other = needy(db); + expect(await E2eGate(client: other, params: fastArgon).unlock(), isTrue); + expect(await other.get('tutor/v1-e2e/live'), {'session': 'x'}); + }); + + test('stays locked without, or with a wrong, passphrase', () async { + installFakeSecureStorage(); + final db = FakeRtdb(); + final gate = E2eGate(client: needy(db), params: fastArgon); + expect(await gate.unlock(), isFalse); + expect(gate.reason, E2eLockReason.needsPassphrase.name); + db.root = setAt(db.root, E2eLayout.of(tutorLayout.base).e2ePath, { + 'not': 'a header', + }); + installFakeSecureStorage(initial: {kE2ePassphraseKey: 'x'}); + final bad = E2eGate(client: needy(db), params: fastArgon); + expect(await bad.unlock(), isFalse); + expect(bad.reason, E2eLockReason.badHeader.name); + }); + + test('opens a header and a unit the Python worker made', () async { + final h = e2eVectors['header'] as Map; + installFakeSecureStorage( + initial: {kE2ePassphraseKey: h['passphrase'] as String}, + ); + final db = FakeRtdb()..root = setAt(null, h['path'] as String, h['text']); + final unit = h['unit'] as Map; + db.root = setAt(db.root, 'tutor/v1-e2e/${unit['path']}', unit['stored']); + final client = needy(db); + expect(await E2eGate(client: client, params: fastArgon).unlock(), isTrue); + expect(await client.get('tutor/v1-e2e/${unit['path']}'), unit['value']); + installFakeSecureStorage(initial: {kE2ePassphraseKey: 'wrong'}); + final wrong = E2eGate(client: needy(db), params: fastArgon); + expect(await wrong.unlock(), isFalse); + expect(wrong.reason, E2eLockReason.wrongKey.name); + }); + }); + + test('the header store reads strings only and never deletes', () async { + final db = FakeRtdb()..root = setAt(null, 'tutor/e2e', {'x': 1}); + final store = E2eHeaderStore(db.client()); + expect(await store.getFileText('tutor/e2e'), '{x: 1}'); + expect(await store.getFileText('tutor/none'), isNull); + expect(await store.listDirectory('tutor'), isEmpty); + expect(await store.canAccessRemote(), isTrue); + expect(() => store.deleteFile('tutor/e2e'), throwsA(anything)); + store.close(); + expect(const E2eLayoutError('x').toString(), 'E2eLayoutError: x'); + }); +} diff --git a/rtdb_relay/dart/test/e2e_seal_test.dart b/rtdb_relay/dart/test/e2e_seal_test.dart new file mode 100644 index 0000000..6b5d0e7 --- /dev/null +++ b/rtdb_relay/dart/test/e2e_seal_test.dart @@ -0,0 +1,179 @@ +import 'dart:async'; +import 'dart:convert'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/layout.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +import 'support/e2e_fixture.dart'; +import 'support/fake_rtdb.dart'; +import 'support/tutor_layout.dart'; + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + test( + 'a pushed request is ciphertext at rest, read back in the clear', + () async { + final db = FakeRtdb(); + final client = sealedClient(db); + final stored = await client.put('tutor/v1-e2e/requests/$testRid/req', { + 'kind': 'message', + 'dev': 'd1', + 'created': {'.sv': 'timestamp'}, + 'body': {'session': '20261012-170448-5b71', 'text': 'secret words'}, + }); + final atRest = jsonEncode(db.root); + expect(atRest, isNot(contains('secret words'))); + expect(atRest, isNot(contains('"text"'))); + expect(atRest, isNot(contains('"kind"'))); + // The server timestamp the credit maths needs stays clear and resolved. + expect( + getAt(db.root, '${'tutor/v1-e2e/requests/$testRid/req'}/created'), + db.serverTime, + ); + expect((stored! as Map)['body'], { + 'session': '20261012-170448-5b71', + 'text': 'secret words', + }); + final read = await client.get('tutor/v1-e2e/requests/$testRid') as Map?; + expect((read!['req'] as Map)['created'], db.serverTime); + expect(((read['req'] as Map)['body'] as Map)['text'], 'secret words'); + }, + ); + + test('the vectors pin the rules and open what Python sealed', () async { + expect(e2eVectors['root'], tutorLayout.root); + expect(e2eVectors['sealed_key'], kSealedKey); + for (final r + in (e2eVectors['rules'] as List).cast>()) { + expect( + tutorLayout.classify(e2eParts(r['path'] as String)).kind.name, + r['kind'], + reason: r['path'] as String, + ); + } + final s = vectorSealer(); + for (final u + in (e2eVectors['units'] as List).cast>()) { + final path = u['path'] as String; + expect(await s.open(path, u['stored']), u['value'], reason: path); + // And Dart's own seal round-trips through the same layout. + expect(await s.open(path, await s.seal(path, u['value'])), u['value']); + } + }); + + test('every path the app writes has a rule', () async { + final s = vectorSealer(); + String rel(String p) => p.substring('tutor/v1-e2e'.length + 1); + final writes = { + 'tutor/v1-e2e/requests/$testRid/req': {'kind': 'x', 'created': 1}, + 'tutor/v1-e2e/feedback/$testRid': {'text': 'x'}, + 'tutor/v1-e2e/uploads/$testRid/c0001': 'aGVsbG8=', + 'tutor/v1-e2e/log/0b6f2c1e-8f2a-4c1d-9e3b-7a5d4c3b2a10/$testRid': { + 'r': 3, + }, + 'tutor/v1-e2e/prefs/current_subject': 'car', + 'tutor/v1-e2e/presence/clients/0b6f2c1e-8f2a-4c1d-9e3b-7a5d4c3b2a10': { + 'platform': 'web', + 'seen': 1, + }, + 'tutor/v1-e2e/sessions/20261012-170448-5b71/user': {'archived': true}, + }; + for (final e in writes.entries) { + final sealed = await s.seal(rel(e.key), e.value); + expect(jsonEncode(sealed), contains(kSealedKey), reason: e.key); + expect(await s.open(rel(e.key), sealed), e.value, reason: e.key); + } + await expectLater( + s.seal('secrets', {'a': 1}), + throwsA(isA()), + ); + await expectLater( + s.sealPatch('sessions/s/msgs/m0001', {'text': 'x'}), + throwsA(isA()), + ); + await expectLater( + s.open('stats/today/x', 1), + throwsA(isA()), + ); + expect( + await s.open('prefs', { + 'current_subject': {kSealedKey: 'AQ=='}, + 'other': 'legacy', + }), + {'other': 'legacy'}, + ); + expect(await s.open('sessions', [1]), [1]); + expect(await s.seal('presence/clients/d', {'x': null}), isNull); + }); + + test('patch, tagged reads, below-unit reads and events open', () async { + final db = FakeRtdb(); + final client = sealedClient(db); + const session = 'tutor/v1-e2e/sessions/20261012-170448-5b71'; + await client.patch('$session/user', {'archived': true}); + await client.put('tutor/v1-e2e/stats/today', {'new_cap': 25}); + expect(jsonEncode(db.root), isNot(contains('new_cap'))); + expect(await client.get('tutor/v1-e2e/stats/today/new_cap'), 25); + expect(await client.get('tutor/v1-e2e/stats/today/nope/x'), isNull); + expect((await client.getTagged('$session/user')).value, {'archived': true}); + final put = await openEvent( + client, + session, + RtdbPut('/', getAt(db.root, session)), + ); + expect((put as RtdbPut).data, { + 'user': {'archived': true}, + }); + final patch = await openEvent( + client, + 'tutor/v1-e2e/stats', + RtdbPatch('/', {'today': getAt(db.root, 'tutor/v1-e2e/stats/today')}), + ); + expect((patch as RtdbPatch).data, { + 'today': {'new_cap': 25}, + }); + expect( + await openEvent(client, session, const RtdbKeepAlive()), + isA(), + ); + final cond = await client.putIfMatch('tutor/v1-e2e/stats/today', { + 'n': 1, + }, 'x'); + expect(cond.value, {'n': 1}); + // Outside the e2e root nothing is sealed (the header lives there). + await client.put('tutor/e2e', 'header'); + expect(getAt(db.root, 'tutor/e2e'), 'header'); + }); + + test( + 'a stream event inside a unit drops the connection, then resyncs', + () async { + final sse = StreamController>(); + final client = RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://db', + idToken: () async => 'tok', + httpClient: MockClient.streaming( + (req, _) async => http.StreamedResponse(sse.stream, 200), + ), + namespace: '', + )..sealer = vectorSealer(); + final events = []; + final sub = RtdbStream( + client, + sleep: (_) => Completer().future, + ).listen('tutor/v1-e2e/stats/today').listen(events.add); + sse.add(utf8.encode('event: put\ndata: {"path":"/x","data":1}\n\n')); + await pumpEventQueue(); + expect(events.last, isA()); + await sub.cancel(); + }, + ); +} diff --git a/rtdb_relay/dart/test/request_hub_test.dart b/rtdb_relay/dart/test/request_hub_test.dart new file mode 100644 index 0000000..f172109 --- /dev/null +++ b/rtdb_relay/dart/test/request_hub_test.dart @@ -0,0 +1,137 @@ +// Every request in flight shares one ranged `requests` listen. +import 'dart:async'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:rtdb_relay/src/request_hub.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; + +import 'support/fake_stream.dart'; + +const _requests = 'tutor/v1-e2e/requests'; +const _a = '01M4RBCX52MMHCK7K73E6KV910'; +const _b = '01M4RBCX52MMHCK7K73E6KV911'; +const _older = '01M4RBCX52MMHCK7K73E6KV900'; + +Future _pump() => Future.delayed(Duration.zero); + +void main() { + late FakeStream stream; + late RequestHub hub; + + setUp(() { + stream = FakeStream(); + hub = RequestHub(stream, _requests); + }); + + test( + 'two requests, one listen from the older rid; each sees its own', + () async { + final a = []; + final b = []; + final subA = hub.watch(_a).listen(a.add); + expect(hub.inFlight.value, 1); + expect(stream.openPaths, [_requests]); + expect(stream.queries[_requests]!['startAt'], '"$_a"'); + final listen = stream.listens[_requests]! + ..add(const RtdbConnected()) + ..add(const RtdbKeepAlive()) + ..add( + const RtdbPut('/', { + _a: {'req': 1}, + }), + ); + await _pump(); + expect(a, [ + {'req': 1}, + ]); + + // A newer rid is inside the range already: no new listen, and what is + // known of it is handed over at once. + stream.emit('$_requests/$_b', const RtdbPut('/req', 2)); + await _pump(); + final subB = hub.watch(_b).listen(b.add); + await _pump(); + expect(stream.listens[_requests], same(listen)); + expect(stream.peak, 1); + expect(hub.inFlight.value, 2); + expect(b, [ + {'req': 2}, + ]); + + // An event for one request does not wake the other. + stream.emit('$_requests/$_b', const RtdbPut('/claim', 'w')); + await _pump(); + expect(a, hasLength(1)); + expect(b.last, {'req': 2, 'claim': 'w'}); + + // A reconnect's snapshot answers both. + listen.add( + const RtdbPut('/', { + _a: {'req': 1}, + }), + ); + await _pump(); + expect(a, hasLength(2)); + expect(b.last, isNull); + + await subA.cancel(); + expect(stream.openPaths, [_requests], reason: 'b still follows'); + await subB.cancel(); + expect(stream.openPaths, isEmpty); + expect(hub.inFlight.value, 0); + }, + ); + + test('an older rid reopens the listen from it', () async { + final subA = hub.watch(_a).listen((_) {}); + final first = stream.listens[_requests]!; + final old = []; + final subOld = hub.watch(_older).listen(old.add); + expect(stream.listens[_requests], isNot(same(first))); + expect(first.hasListener, isFalse); + expect(stream.openPaths, [_requests]); + expect(stream.queries[_requests]!['startAt'], '"$_older"'); + // Not yet heard: nothing handed over. + final subNone = hub.watch(_b).listen(old.add); + await _pump(); + expect(old, isEmpty); + stream.emit('$_requests/$_older', const RtdbPut('/result', 'r')); + await _pump(); + expect(old, [ + {'result': 'r'}, + ]); + await subNone.cancel(); + await subOld.cancel(); + await subA.cancel(); + expect(stream.openPaths, isEmpty); + expect(hub.inFlight.value, 0); + }); + + test('two watchers of the same rid both hear it', () async { + final got = []; + final one = hub.watch(_a).listen(got.add); + final two = hub.watch(_a).listen(got.add); + stream.emit('$_requests/$_a', const RtdbPatch('/', {'claim': 'w'})); + await _pump(); + expect(got, hasLength(2)); + await one.cancel(); + expect(stream.openPaths, [_requests]); + unawaited(two.cancel()); + }); + + test('the listen ending for good ends every follow', () async { + var ended = 0; + hub.watch(_a).listen(null, onDone: () => ended++); + hub.watch(_b).listen(null, onDone: () => ended++); + await stream.listens[_requests]!.close(); + await _pump(); + expect(ended, 2); + expect(hub.inFlight.value, 0); + expect(stream.openPaths, isEmpty); + // The next follow opens a fresh listen. + final sub = hub.watch(_b).listen(null); + expect(stream.openPaths, [_requests]); + expect(stream.queries[_requests]!['startAt'], '"$_b"'); + await sub.cancel(); + }); +} diff --git a/rtdb_relay/dart/test/rev_watcher_test.dart b/rtdb_relay/dart/test/rev_watcher_test.dart new file mode 100644 index 0000000..5c4986c --- /dev/null +++ b/rtdb_relay/dart/test/rev_watcher_test.dart @@ -0,0 +1,238 @@ +import 'dart:async'; + +import 'package:flutter/widgets.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:rtdb_relay/src/rev_watcher.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +class _FakeStream implements RtdbStream { + StreamController? events; + final paths = []; + + @override + RtdbClient get client => throw UnimplementedError(); + + @override + Stream listen( + String path, { + Map query = const {}, + }) { + paths.add(path); + return (events = StreamController()).stream; + } +} + +const _rev = 'tutor/v1-e2e/rev'; + +void main() { + final binding = TestWidgetsFlutterBinding.ensureInitialized(); + + setUp( + () => binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed), + ); + + test('revOf and foregroundFor', () { + expect(revOf(null, 'catalog'), 0); + expect(revOf(const {'stats': 3}, 'catalog'), 0); + expect(revOf(const {'catalog': 'x'}, 'catalog'), 0); + expect(revOf(const {'catalog': 7.0}, 'catalog'), 7); + expect(foregroundFor(null), isTrue); + expect(foregroundFor(AppLifecycleState.resumed), isTrue); + expect(foregroundFor(AppLifecycleState.inactive), isNull); + for (final s in [ + AppLifecycleState.hidden, + AppLifecycleState.paused, + AppLifecycleState.detached, + ]) { + expect(foregroundFor(s), isFalse); + } + }); + + test( + 'emits real catalog moves only; reconnect snapshots are ignored', + () async { + final s = _FakeStream(); + final w = RevWatcher(s, _rev); + final seen = []; + final sub = w.changesOf('catalog').listen(seen.add); + expect(s.paths, ['tutor/v1-e2e/rev']); + s.events! + ..add(const RtdbConnected()) + ..add(const RtdbPut('/', {'catalog': 7, 'stats': 3})) + ..add(const RtdbPatch('/', {'stats': 4})) + ..add(const RtdbKeepAlive()) + ..add(const RtdbPut('/catalog', 8)) + // A reconnect resends the whole node, unchanged: not a move. + ..add(const RtdbDisconnected(null)) + ..add(const RtdbConnected()) + ..add(const RtdbPut('/', {'catalog': 8, 'stats': 4})) + ..add(const RtdbPatch('/', {'catalog': 9})); + await pumpEventQueue(); + expect(seen, [8, 9]); + await sub.cancel(); + await w.dispose(); + }, + ); + + test( + 'a key watched late keeps the baseline it had, absent reads 0', + () async { + final s = _FakeStream(); + final w = RevWatcher(s, _rev); + final catalog = w.changesOf('catalog').listen((_) {}); + s.events!.add(const RtdbPut('/', {'catalog': 1})); + await pumpEventQueue(); + final stats = []; + final late = w.changesOf('stats').listen(stats.add); + final todo = []; + final fresh = w.changesOf('todo').listen(todo.add); + s.events! + ..add(const RtdbPatch('/', {'stats': 2})) + ..add(const RtdbPatch('/', {'catalog': 1})); + await pumpEventQueue(); + expect(stats, [2]); // 0 -> 2 is a move + expect(todo, isEmpty); + await (catalog.cancel(), late.cancel(), fresh.cancel()).wait; + await w.dispose(); + }, + ); + + test( + 'ref-counted: one listen for many screens, closed by the last', + () async { + final s = _FakeStream(); + final w = RevWatcher(s, _rev); + final a = w.changesOf('catalog').listen((_) {}); + final b = w.changesOf('catalog').listen((_) {}); + expect(s.paths, hasLength(1)); + await a.cancel(); + expect(w.listening, isTrue); + await b.cancel(); + expect(w.listening, isFalse); + expect(s.events!.hasListener, isFalse); + // The baseline survives: a move seen on the next listen is emitted. + final seen = []; + final c = w.changesOf('catalog').listen(seen.add); + expect(s.paths, hasLength(2)); + s.events!.add(const RtdbPut('/', {'catalog': 1})); + await pumpEventQueue(); + expect(seen, isEmpty); // first value ever = baseline + await c.cancel(); + await w.dispose(); + }, + ); + + test( + 'pauses in the back, resumes in front; a missed move is emitted', + () async { + final s = _FakeStream(); + // Without listeners, coming to the front opens nothing. + final w = RevWatcher(s, _rev)..foreground(visible: true); + expect(s.paths, isEmpty); + final seen = []; + final sub = w.changesOf('catalog').listen(seen.add); + s.events!.add(const RtdbPut('/', {'catalog': 7})); + await pumpEventQueue(); + final first = s.events!; + binding + ..handleAppLifecycleStateChanged(AppLifecycleState.inactive) + ..handleAppLifecycleStateChanged(AppLifecycleState.hidden); + await pumpEventQueue(); + expect(w.listening, isFalse); + expect(first.hasListener, isFalse); + binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive); + expect(w.listening, isFalse); // inactive alone decides nothing + binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed); + expect(w.listening, isTrue); + expect(s.paths, hasLength(2)); + s.events! + ..add(const RtdbConnected()) + ..add(const RtdbPut('/', {'catalog': 9})); + await pumpEventQueue(); + expect(seen, [9]); + // `cancel` ends the listen; the next return to the front reopens it. + await s.events!.close(); + await pumpEventQueue(); + expect(w.listening, isFalse); + w.foreground(visible: true); + expect(s.paths, hasLength(3)); + await sub.cancel(); + await w.dispose(); + }, + ); + + test('opened while hidden: waits for the front', () async { + binding + ..handleAppLifecycleStateChanged(AppLifecycleState.inactive) + ..handleAppLifecycleStateChanged(AppLifecycleState.hidden); + final s = _FakeStream(); + final w = RevWatcher(s, _rev, binding: binding); + final sub = w.changesOf('catalog').listen((_) {}); + expect(s.paths, isEmpty); + binding + ..handleAppLifecycleStateChanged(AppLifecycleState.inactive) + ..handleAppLifecycleStateChanged(AppLifecycleState.resumed); + expect(s.paths, hasLength(1)); + await w.dispose(); + await sub.cancel(); + }); + + test('stats moves: one shared listen for both streams', () async { + final s = _FakeStream(); + final w = RevWatcher(s, _rev, binding: binding); + final stats = []; + final catalog = []; + final a = w.changesOf('stats').listen(stats.add); + final b = w.changesOf('catalog').listen(catalog.add); + expect(s.paths, ['tutor/v1-e2e/rev']); // the second listener shares it + s.events! + ..add(const RtdbPut('/', {'catalog': 1, 'stats': 4})) + ..add(const RtdbPut('/', {'catalog': 1, 'stats': 4})) + ..add(const RtdbPatch('/', {'stats': 5})); + await Future.delayed(Duration.zero); + expect(stats, [5]); + expect(catalog, isEmpty); + await b.cancel(); + expect(w.listening, isTrue); // stats still wants it + await a.cancel(); + expect(w.listening, isFalse); + await w.dispose(); + }); + + test( + 'closed while a request is in flight; a move meanwhile is emitted', + () async { + final s = _FakeStream(); + final inFlight = ValueNotifier(0); + final w = RevWatcher(s, _rev, yieldTo: inFlight); + final seen = []; + final sub = w.changesOf('catalog').listen(seen.add); + s.events! + ..add(const RtdbConnected()) + ..add(const RtdbPut('/', {'catalog': 3})); + await Future.delayed(Duration.zero); + inFlight.value = 1; + expect(w.listening, isFalse); + expect(s.events!.hasListener, isFalse); + inFlight.value = 2; // a second request: still closed, no new listen + expect(s.paths, hasLength(1)); + // In front again mid-request: stays closed. + w.foreground(visible: true); + expect(w.listening, isFalse); + inFlight.value = 0; + expect(w.listening, isTrue); + expect(s.paths, hasLength(2)); + s.events! + ..add(const RtdbConnected()) + ..add(const RtdbPut('/', {'catalog': 4})); + await Future.delayed(Duration.zero); + expect(seen, [4]); + await sub.cancel(); + await w.dispose(); + inFlight.value = 1; // no longer heard + expect(s.paths, hasLength(2)); + }, + ); +} diff --git a/rtdb_relay/dart/test/rtdb_client_test.dart b/rtdb_relay/dart/test/rtdb_client_test.dart new file mode 100644 index 0000000..5a7b021 --- /dev/null +++ b/rtdb_relay/dart/test/rtdb_client_test.dart @@ -0,0 +1,140 @@ +import 'dart:convert'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; + +import 'support/tutor_layout.dart'; + +RtdbClient _client(MockClientHandler handler, {String url = 'https://db/'}) => + RtdbClient( + layout: tutorLayout, + databaseUrl: url, + idToken: () async => 'tok', + httpClient: MockClient(handler), + ); + +void main() { + test('uri encodes segments and carries the token and query', () async { + final c = _client((_) async => http.Response('null', 200)); + final uri = await c.uri( + '/tutor/v1-e2e/a b/', + query: keyRangeQuery('m0003'), + ); + expect(uri.path, '/tutor/v1-e2e/a%20b.json'); + expect(uri.queryParameters['auth'], 'tok'); + expect(uri.queryParameters['orderBy'], r'"$key"'); + expect(uri.queryParameters['startAt'], '"m0003"'); + final noSlash = RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://x', + idToken: () async => 't', + ); + expect((await noSlash.uri('a')).toString(), startsWith('https://x/a.json')); + noSlash.close(); + }); + + test('get decodes JSON; empty body is null; keys are sorted', () async { + final c = _client((req) async { + if (req.url.queryParameters['shallow'] == 'true') { + return http.Response('{"b":true,"a":true}', 200); + } + return http.Response(req.url.path == '/e.json' ? '' : '{"x":1}', 200); + }); + expect(await c.get('v'), {'x': 1}); + expect(await c.get('e'), isNull); + expect(await c.keys('v'), ['a', 'b']); + }); + + test('keys of an absent node is empty', () async { + final c = _client((_) async => http.Response('null', 200)); + expect(await c.keys('v'), isEmpty); + }); + + test('put sends JSON and returns the resolved body', () async { + late http.Request seen; + final c = _client((req) async { + seen = req; + return http.Response('{"created":123}', 200); + }); + final out = await c.put('r', { + 'created': {'.sv': 'timestamp'}, + }); + expect(seen.method, 'PUT'); + expect(jsonDecode(seen.body), { + 'created': {'.sv': 'timestamp'}, + }); + expect(out, {'created': 123}); + }); + + test('getTagged asks for and returns the ETag', () async { + final c = _client((req) async { + expect(req.headers['X-Firebase-ETag'], 'true'); + return http.Response('null', 200, headers: {'etag': 'E1'}); + }); + final t = await c.getTagged('claim'); + expect(t.value, isNull); + expect(t.etag, 'E1'); + final bare = _client((_) async => http.Response('1', 200)); + expect((await bare.getTagged('x')).etag, ''); + }); + + test('putIfMatch: success and 412 lost race', () async { + var status = 200; + final c = _client((req) async { + expect(req.headers['if-match'], 'E1'); + return http.Response('{"by":"other"}', status, headers: {'etag': 'E2'}); + }); + final won = await c.putIfMatch('claim', {'by': 'me'}, 'E1'); + expect(won.ok, isTrue); + status = 412; + final lost = await c.putIfMatch('claim', {'by': 'me'}, 'E1'); + expect(lost.ok, isFalse); + expect(lost.value, {'by': 'other'}); + expect(lost.etag, 'E2'); + final del = await c.deleteIfMatch('claim', 'E1'); + expect(del.ok, isFalse); + }); + + test('patch and delete use their methods', () async { + final methods = []; + final c = _client((req) async { + methods.add(req.method); + return http.Response('null', 200); + }); + await c.patch('p', {'a': 1}); + await c.delete('p'); + expect(methods, ['PATCH', 'DELETE']); + }); + + test('HTTP errors classify auth vs transient', () async { + var status = 401; + final c = _client((_) async => http.Response('{"error":"x"}', status)); + final e401 = await c + .get('a') + .then((_) => null, onError: (Object e) => e as RtdbError); + expect(e401!.isAuth, isTrue); + expect(e401.isTransient, isFalse); + expect(e401.toString(), contains('401')); + status = 503; + await expectLater( + c.get('a'), + throwsA(isA().having((e) => e.isTransient, 't', isTrue)), + ); + status = 412; + await expectLater(c.put('a', 1), throwsA(isA())); + }); + + test('network failure is a transient RtdbError', () async { + final c = _client((_) async => throw http.ClientException('down')); + await expectLater( + c.get('a'), + throwsA( + isA() + .having((e) => e.status, 'status', isNull) + .having((e) => e.isTransient, 't', isTrue), + ), + ); + }); +} diff --git a/rtdb_relay/dart/test/rtdb_event_test.dart b/rtdb_relay/dart/test/rtdb_event_test.dart new file mode 100644 index 0000000..365ed84 --- /dev/null +++ b/rtdb_relay/dart/test/rtdb_event_test.dart @@ -0,0 +1,91 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; + +void main() { + group('SseParser', () { + test('frames split across chunks, CRLF, comments, multi-line data', () { + final p = SseParser(); + expect(p.add('event: put\r\ndata: {"path":"/",'), isEmpty); + final frames = p.add('"data":1}\r\n\r\n: comment\nid: 1\n\n'); + expect(frames, hasLength(1)); + expect(frames.single.event, 'put'); + expect(frames.single.data, '{"path":"/","data":1}'); + final multi = p.add('event: x\ndata: a\ndata:b\n\n'); + expect(multi.single.data, 'a\nb'); + }); + }); + + group('RtdbEvent.fromFrame', () { + test('put and patch', () { + final put = + RtdbEvent.fromFrame( + const SseFrame('put', '{"path":"/a","data":{"x":1}}'), + )! + as RtdbPut; + expect(put.path, '/a'); + expect(put.data, {'x': 1}); + final patch = + RtdbEvent.fromFrame( + const SseFrame('patch', '{"path":"/","data":{"b":2}}'), + )! + as RtdbPatch; + expect(patch.data, {'b': 2}); + }); + + test('control events and unknown ones', () { + expect( + RtdbEvent.fromFrame(const SseFrame('keep-alive', 'null')), + isA(), + ); + final cancel = RtdbEvent.fromFrame(const SseFrame('cancel', 'denied')); + expect((cancel! as RtdbCancel).reason, 'denied'); + expect( + RtdbEvent.fromFrame(const SseFrame('auth_revoked', 'x')), + isA(), + ); + expect(RtdbEvent.fromFrame(const SseFrame('other', '')), isNull); + }); + }); + + group('json tree', () { + test('put at root, nested put, delete collapses empty maps', () { + var t = applyEvent(null, const RtdbPut('/', {'a': 1})); + t = applyEvent(t, const RtdbPut('/b/c', 2)); + expect(t, { + 'a': 1, + 'b': {'c': 2}, + }); + expect(getAt(t, 'b/c'), 2); + expect(getAt(t, 'a/x'), isNull); + t = applyEvent(t, const RtdbPut('/b/c', null)); + expect(t, {'a': 1}); + t = applyEvent(t, const RtdbPut('/a', null)); + expect(t, isNull); + }); + + test('patch replaces each child; others untouched; non-data no-op', () { + final before = { + 'w': {'x': 1, 'y': 2}, + }; + final after = applyEvent(before, const RtdbPatch('/w', {'x': 9, 'z': 3})); + expect(after, { + 'w': {'x': 9, 'y': 2, 'z': 3}, + }); + expect(before['w'], {'x': 1, 'y': 2}); + for (final e in const [ + RtdbConnected(), + RtdbDisconnected(null), + RtdbKeepAlive(), + RtdbCancel('r'), + RtdbAuthRevoked(), + ]) { + expect(applyEvent(after, e), same(after)); + } + }); + + test('a put under a scalar replaces it with a map', () { + expect(setAt(5, 'a', 1), {'a': 1}); + }); + }); +} diff --git a/rtdb_relay/dart/test/rtdb_namespace_test.dart b/rtdb_relay/dart/test/rtdb_namespace_test.dart new file mode 100644 index 0000000..914e68c --- /dev/null +++ b/rtdb_relay/dart/test/rtdb_namespace_test.dart @@ -0,0 +1,92 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; + +import 'support/tutor_layout.dart'; + +/// Records every request the client sends. +class _Spy { + final seen = []; + + RtdbClient client({String? namespace}) => RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://db/', + idToken: () async => 'tok', + namespace: namespace, + httpClient: MockClient((req) async { + seen.add(req); + return http.Response('null', 200, headers: {'etag': 'e1'}); + }), + ); +} + +void main() { + test('empty namespace keeps every path byte-identical', () async { + final spy = _Spy(); + final c = spy.client(namespace: ''); + await c.get('tutor/v1-e2e/a'); + await c.put('/tutor/v1-e2e/b/', 1); + await c.patch('tutor/v1-e2e/c', {'k': 1}); + await c.delete('tutor/v1-e2e/d'); + await c.getTagged('tutor/v1-e2e/e'); + await c.putIfMatch('tutor/v1-e2e/f', 1, 'e1'); + await c.deleteIfMatch('tutor/v1-e2e/g', 'e1'); + await c.keys('tutor/v1-e2e/h'); + expect(spy.seen.map((r) => r.url.path), [ + '/tutor/v1-e2e/a.json', + '/tutor/v1-e2e/b.json', + '/tutor/v1-e2e/c.json', + '/tutor/v1-e2e/d.json', + '/tutor/v1-e2e/e.json', + '/tutor/v1-e2e/f.json', + '/tutor/v1-e2e/g.json', + '/tutor/v1-e2e/h.json', + ]); + }); + + test('a sandbox namespace prefixes every request path', () async { + final spy = _Spy(); + final c = spy.client(namespace: 'sandbox/slot3'); + await c.get('tutor/v1-e2e/a'); + await c.put('/tutor/v1-e2e/b/', 1); + await c.patch('tutor/v1-e2e/c', {'k': 1}); + await c.delete('tutor/v1-e2e/d'); + await c.getTagged('tutor/v1-e2e/e'); + await c.putIfMatch('tutor/v1-e2e/f', 1, 'e1'); + await c.deleteIfMatch('tutor/v1-e2e/g', 'e1'); + await c.keys('tutor/v1-e2e/h'); + expect( + spy.seen.map((r) => r.url.path), + everyElement(startsWith('/sandbox/slot3/tutor/v1-e2e/')), + ); + expect(spy.seen, hasLength(8)); + }); + + test('uri (used by the SSE stream) is prefixed too', () async { + final c = _Spy().client(namespace: 'sandbox/slot3'); + expect( + (await c.uri('tutor/v1-e2e/rev')).path, + '/sandbox/slot3/tutor/v1-e2e/rev.json', + ); + }); + + test('an invalid namespace fails closed at construction', () { + for (final bad in [ + 'slot3', + 'sandbox/', + 'sandbox/Slot', + 'prod', + '/x', + 'sandbox/a/b', + 'sandbox/s\n', + ]) { + expect(() => _Spy().client(namespace: bad), throwsException, reason: bad); + } + }); + + test('the compiled define defaults to empty (production paths)', () async { + final c = _Spy().client(); + expect((await c.uri('a')).path, '/a.json'); + }); +} diff --git a/rtdb_relay/dart/test/rtdb_stream_test.dart b/rtdb_relay/dart/test/rtdb_stream_test.dart new file mode 100644 index 0000000..ab009ab --- /dev/null +++ b/rtdb_relay/dart/test/rtdb_stream_test.dart @@ -0,0 +1,195 @@ +import 'dart:async'; +import 'dart:convert'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +import 'support/tutor_layout.dart'; + +/// Scripted server: each connection takes the next response factory. +class _Server { + final List script = []; + final List requests = []; + final List slept = []; + + RtdbStream stream() { + final client = MockClient.streaming((req, _) async { + requests.add(req); + if (script.isEmpty) return _never(); + return script.removeAt(0)(req); + }); + return RtdbStream( + RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://db', + idToken: () async => 'tok', + httpClient: client, + ), + sleep: (d) async => slept.add(d), + ); + } +} + +http.StreamedResponse _sse(List chunks, {bool close = true}) { + final c = StreamController>(); + for (final chunk in chunks) { + c.add(utf8.encode(chunk)); + } + if (close) unawaited(c.close()); + return http.StreamedResponse(c.stream, 200); +} + +http.StreamedResponse _never() => + http.StreamedResponse(StreamController>().stream, 200); + +String _frame(String event, String data) => 'event: $event\ndata: $data\n\n'; + +void main() { + test('reconnectDelay doubles to a 30 s cap', () { + expect( + [for (var i = 0; i < 7; i++) reconnectDelay(i).inSeconds], + [ + 1, 2, 4, 8, 16, 30, 30, // + ], + ); + }); + + test( + 'snapshot, keep-alive, auth_revoked reconnects now, cancel ends', + () async { + final s = _Server() + ..script.add( + (_) => _sse([ + _frame('put', '{"path":"/","data":{"a":1}}'), + _frame('keep-alive', 'null'), + _frame('auth_revoked', 'credential is no longer valid'), + _frame('put', '{"path":"/late","data":1}'), + ], close: false), + ) + ..script.add((_) => _sse([_frame('cancel', 'permission denied')])); + final events = await s.stream().listen('tutor/v1-e2e/presence').toList(); + expect(events.map((e) => e.runtimeType).toList(), [ + RtdbConnected, + RtdbPut, + RtdbKeepAlive, + RtdbAuthRevoked, + RtdbConnected, + RtdbCancel, + ]); + expect(s.slept, isEmpty); + expect(s.requests.first.headers['Accept'], 'text/event-stream'); + }, + ); + + test('follows a 307 keeping Accept; HTTP error backs off', () async { + final s = _Server() + ..script.add( + (_) => http.StreamedResponse( + const Stream.empty(), + 307, + headers: {'location': 'https://other/x.json?auth=t'}, + ), + ) + ..script.add( + (_) => http.StreamedResponse(Stream.value(utf8.encode('no')), 401), + ) + ..script.add((_) => _sse([_frame('cancel', 'bye')])); + final events = await s.stream().listen('x').toList(); + expect(s.requests[1].url.host, 'other'); + expect(s.requests[1].headers['Accept'], 'text/event-stream'); + final err = (events.first as RtdbDisconnected).error! as RtdbError; + expect(err.status, 401); + expect(s.slept, [const Duration(seconds: 1)]); + expect(events.last, isA()); + }); + + test('too many redirects is a disconnect', () async { + final s = _Server(); + for (var i = 0; i < 5; i++) { + s.script.add( + (_) => http.StreamedResponse( + const Stream.empty(), + 307, + headers: {'location': '/again'}, + ), + ); + } + s.script.add((_) => _sse([_frame('cancel', 'bye')])); + final events = await s.stream().listen('x').toList(); + expect((events.first as RtdbDisconnected).error, isA()); + }); + + test('clean end, socket error and bad frame all back off', () async { + final broken = StreamController>(); + final s = _Server() + ..script.add((_) => _sse([])) + ..script.add((_) { + broken.addError(http.ClientException('reset')); + return http.StreamedResponse(broken.stream, 200); + }) + ..script.add((_) => _sse([_frame('put', 'not json')], close: false)) + ..script.add((_) => _sse([_frame('cancel', 'bye')])); + final events = await s.stream().listen('x').toList(); + final drops = events.whereType().toList(); + expect(drops[0].error, isNull); + expect(drops[1].error, isA()); + expect(drops[2].error, isA()); + expect(s.slept, hasLength(3)); + await broken.close(); + }); + + test('cancelling the subscription stops reconnecting', () async { + final s = _Server() + ..script.add( + (_) => _sse([_frame('put', '{"path":"/","data":1}')], close: false), + ); + final got = Completer(); + final sub = s.stream().listen('x').listen((e) { + if (e is RtdbPut) got.complete(); + }); + await got.future; + await sub.cancel(); + await Future.delayed(Duration.zero); + expect(s.requests, hasLength(1)); + }); + + test('a listen cancelled while connecting aborts and lets go', () async { + // RTDB is HTTP/1.1: a browser has 6 connections to it. A leaked listen + // starved the next session's meta/msgs (empty chat after Next card). + final server = _Server(); + final gate = Completer(); + var released = false; + final body = StreamController>(onCancel: () => released = true); + server.script.add((_) => http.StreamedResponse(body.stream, 200)); + final client = MockClient.streaming((req, _) async { + server.requests.add(req); + await gate.future; + return server.script.removeAt(0)(req); + }); + final stream = RtdbStream( + RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://db', + idToken: () async => 'tok', + httpClient: client, + ), + sleep: (d) async {}, + ); + final sub = stream.listen('tutor/v1-e2e/live').listen((_) {}); + await Future.delayed(Duration.zero); + final req = server.requests.single as http.Abortable; + var aborted = false; + unawaited(req.abortTrigger!.then((_) => aborted = true)); + await sub.cancel(); + await Future.delayed(Duration.zero); + expect(aborted, isTrue); + gate.complete(); + await Future.delayed(Duration.zero); + await Future.delayed(Duration.zero); + expect(released, isTrue); + }); +} diff --git a/rtdb_relay/dart/test/support/e2e_fixture.dart b/rtdb_relay/dart/test/support/e2e_fixture.dart new file mode 100644 index 0000000..10a2f8f --- /dev/null +++ b/rtdb_relay/dart/test/support/e2e_fixture.dart @@ -0,0 +1,28 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:crdt_sync/crdt_sync.dart' show Argon2Params, E2eCipher; +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/sealer.dart'; + +import 'fake_rtdb.dart'; +import 'tutor_layout.dart'; + +const fastArgon = Argon2Params(memoryKiB: 8, iterations: 1, parallelism: 1); +const testRid = '01J0000000000000000000000R'; + +final Map e2eVectors = jsonDecode( + File('test/data/e2e_vectors.json').readAsStringSync(), +) as Map; + +RelaySealer vectorSealer() => RelaySealer( + E2eCipher(hexBytes(e2eVectors['key_hex'] as String)), + layout: tutorLayout, +); + +List hexBytes(String s) => [ + for (var i = 0; i < s.length; i += 2) + int.parse(s.substring(i, i + 2), radix: 16), +]; + +RtdbClient sealedClient(FakeRtdb db) => db.client()..sealer = vectorSealer(); diff --git a/rtdb_relay/dart/test/support/fake_rtdb.dart b/rtdb_relay/dart/test/support/fake_rtdb.dart new file mode 100644 index 0000000..9bac06a --- /dev/null +++ b/rtdb_relay/dart/test/support/fake_rtdb.dart @@ -0,0 +1,93 @@ +/// An in-memory RTDB REST server behind a MockClient: GET (shallow, +/// `orderBy="$key"` + `startAt`), PUT (resolving `.sv` timestamps), PATCH, +/// DELETE. Enough for the logic tests; streaming is faked separately. +library; + +import 'dart:convert'; + +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/json_tree.dart'; +import 'package:rtdb_relay/src/rtdb_client.dart'; + +import 'tutor_layout.dart'; + +/// The fake database. +class FakeRtdb { + /// The whole tree. + Object? root; + + /// Server time used for `{".sv":"timestamp"}`. + int serverTime = 1791731346000; + + /// Requests seen, as `METHOD path`. + final List log = []; + + /// When set, every request throws a network error. + bool offline = false; + + /// Requests whose path starts with this throw a network error. + String? failPrefix; + + /// A client wired to this fake. + /// + /// The namespace is pinned to production (''): a phone slot build of the + /// screenshot fixture sets SYNC_NAMESPACE=sandbox/slotN, which would + /// otherwise move every read under a prefix this in-memory tree lacks + /// (Home and Progress came up empty on the Pixel). + RtdbClient client() => RtdbClient( + layout: tutorLayout, + databaseUrl: 'https://fake', + idToken: () async => 'tok', + httpClient: MockClient(_handle), + namespace: '', + ); + + Object? _resolve(Object? v) { + if (v is Map) { + if (v.length == 1 && v['.sv'] == 'timestamp') return serverTime; + return {for (final e in v.entries) e.key: _resolve(e.value)}; + } + return v; + } + + Future _handle(http.Request req) async { + if (offline) throw http.ClientException('offline'); + final path = req.url.path.replaceFirst(RegExp(r'\.json$'), ''); + if (failPrefix != null && path.startsWith(failPrefix!)) { + throw http.ClientException('unreachable'); + } + log.add('${req.method} $path'); + final q = req.url.queryParameters; + switch (req.method) { + case 'GET': + var value = getAt(root, path); + if (q['shallow'] == 'true' && value is Map) { + value = {for (final k in value.keys) k: true}; + } + final start = q['startAt']; + if (start != null && value is Map) { + final from = jsonDecode(start) as String; + value = { + for (final e in value.entries) + if (e.key.compareTo(from) >= 0) e.key: e.value, + }; + if (value.isEmpty) value = null; + } + return http.Response(jsonEncode(value), 200); + case 'PUT': + final value = _resolve(jsonDecode(req.body)); + root = setAt(root, path, value); + return http.Response(jsonEncode(value), 200); + case 'PATCH': + final patch = jsonDecode(req.body) as Map; + for (final e in patch.entries) { + root = setAt(root, '$path/${e.key}', _resolve(e.value)); + } + return http.Response(req.body, 200); + default: // DELETE + root = setAt(root, path, null); + return http.Response('null', 200); + } + } +} diff --git a/rtdb_relay/dart/test/support/fake_stream.dart b/rtdb_relay/dart/test/support/fake_stream.dart new file mode 100644 index 0000000..7d32084 --- /dev/null +++ b/rtdb_relay/dart/test/support/fake_stream.dart @@ -0,0 +1,84 @@ +/// An [RtdbStream] whose events the test pushes by path. +/// +/// It also counts the listens open at once, as a browser counts the +/// connections they hold: RTDB speaks HTTP/1.1 and Chrome gives a host 6, so +/// the app must keep its streams well under that (`stream_budget_test`). +library; + +import 'dart:async'; +import 'dart:math'; + +import 'package:rtdb_relay/src/rtdb_client.dart'; +import 'package:rtdb_relay/src/rtdb_event.dart'; +import 'package:rtdb_relay/src/rtdb_stream.dart'; + +/// The fake transport. +class FakeStream implements RtdbStream { + /// Listens by path (the latest one per path), open or not. + final Map> listens = {}; + + /// The query of the latest listen per path. + final Map> queries = {}; + + final Set> _open = {}; + final Map, String> _paths = {}; + + /// The most listens ever open at once, and which they were. + int peak = 0; + + /// The paths open when [peak] was reached. + List peakPaths = const []; + + /// The paths of the listens open now. + List get openPaths => [for (final c in _open) _paths[c]!]; + + @override + RtdbClient get client => throw UnimplementedError(); + + @override + Stream listen( + String path, { + Map query = const {}, + }) { + queries[path] = query; + late final StreamController c; + c = StreamController( + onListen: () { + _open.add(c); + if (_open.length > peak) { + peak = _open.length; + peakPaths = openPaths; + } + }, + onCancel: () => _open.remove(c), + ); + _paths[c] = path; + return (listens[path] = c).stream; + } + + /// Delivers [event] for [path] as RTDB does: to the open listen on that + /// path, else to the nearest open listen above it with the event's path + /// prefixed by the rest. False when nothing listens there. + bool emit(String path, RtdbEvent event) { + for (var at = path; at.isNotEmpty; at = _parent(at)) { + final c = listens[at]; + if (c == null || !_open.contains(c)) continue; + final rest = path.substring(at.length); + c.add(rest.isEmpty ? event : _under(rest, event)); + return true; + } + return false; + } + + static String _parent(String path) => + path.substring(0, max(0, path.lastIndexOf('/'))); + + static RtdbEvent _under(String rest, RtdbEvent event) { + String join(String p) => p == '/' ? rest : '$rest$p'; + return switch (event) { + RtdbPut(:final path, :final data) => RtdbPut(join(path), data), + RtdbPatch(:final path, :final data) => RtdbPatch(join(path), data), + _ => event, + }; + } +} diff --git a/rtdb_relay/dart/test/support/legacy_tutor_seal.dart b/rtdb_relay/dart/test/support/legacy_tutor_seal.dart new file mode 100644 index 0000000..73969b0 --- /dev/null +++ b/rtdb_relay/dart/test/support/legacy_tutor_seal.dart @@ -0,0 +1,244 @@ +// FROZEN copy of the tutor app's lib/sync/e2e_seal.dart at tutor d72bba7, the +// code the phone APK ran before the extraction. Only the differential test +// reads it; never edit it (doc comments stripped for the line cap). +// ignore_for_file: type=lint +/// End-to-end encryption of the tutor's RTDB tree (DOCS-contract §12). +library; + +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' show E2eCipher, E2eLayout; + +const String kOldRoot = 'tutor/v1'; + +final E2eLayout kE2eLayout = E2eLayout.of(kOldRoot); + +const String kSealedKey = '_e2e'; + +const List _clear = [ + 'meta', + 'rev', + 'migration', + 'requests/*/claim', + 'sessions/*/progress/rid', +]; + +const Map> _units = { + 'live': {}, + 'prefs/*': {}, + 'stats/*': {}, + 'presence/workers/*': {'beat'}, + 'presence/clients/*': {'seen'}, + 'uploads/*/*': {}, + 'requests/*/req': {'created'}, + 'requests/*/result': {'at'}, + 'sessions/*/meta/*': {}, + 'sessions/*/msgs/*': {}, + 'sessions/*/receipts/*': {}, + 'sessions/*/user/*': {}, + 'sessions/*/progress/steps/*': {}, + 'session_index/*': {}, + 'subjects/*/meta': {}, + 'subjects/*/plan': {}, + 'subjects/*/cards': {}, + 'subjects/*/concepts': {}, + 'log/*/*': {}, + 'feedback/*': {}, +}; + +class E2eLayoutError implements Exception { + const new(this.message); + + final String message; + + @override + String toString() => 'E2eLayoutError: $message'; +} + +enum E2eRuleKind { clear, unit, below, struct, unknown } + +class E2eRule { + const new(this.kind, [this.depth = 0, this.keep = const {}]); + + final E2eRuleKind kind; + + final int depth; + + final Set keep; +} + +Object? _pruned(Object? value) { + if (value is! Map) return value; + final out = {}; + for (final e in value.entries) { + final v = _pruned(e.value); + if (v != null) out[e.key as String] = v; + } + return out.isEmpty ? null : out; +} + +List e2eParts(String path) => + path.split('/').where((s) => s.isNotEmpty).toList(); + +bool _matches(List pattern, List parts) { + if (pattern.length != parts.length) return false; + for (var i = 0; i < parts.length; i++) { + if (pattern[i] != '*' && pattern[i] != parts[i]) return false; + } + return true; +} + +E2eRule classifyE2e(List parts) { + for (final pattern in _clear) { + final pat = pattern.split('/'); + if (pat.length <= parts.length && + _matches(pat, parts.sublist(0, pat.length))) { + return const E2eRule(E2eRuleKind.clear); + } + } + for (final entry in _units.entries) { + final pat = entry.key.split('/'); + if (_matches(pat, parts)) { + return E2eRule(E2eRuleKind.unit, pat.length, entry.value); + } + if (pat.length < parts.length && + _matches(pat, parts.sublist(0, pat.length))) { + return E2eRule(E2eRuleKind.below, pat.length, entry.value); + } + } + for (final pattern in [..._clear, ..._units.keys]) { + final pat = pattern.split('/'); + if (parts.length < pat.length && + _matches(pat.sublist(0, parts.length), parts)) { + return const E2eRule(E2eRuleKind.struct); + } + } + return const E2eRule(E2eRuleKind.unknown); +} + +String? e2eUnitPath(String rel) { + final parts = e2eParts(rel); + final rule = classifyE2e(parts); + return rule.kind == E2eRuleKind.below + ? parts.sublist(0, rule.depth).join('/') + : null; +} + +class TutorSealer { + new(this.cipher, {String? root}) : root = root ?? kE2eLayout.prefix; + + final E2eCipher cipher; + + final String root; + + String _aad(List parts) => [root, ...parts].join('/'); + + Future seal(String rel, Object? value) => + _seal(e2eParts(rel), value); + + Future> sealPatch( + String rel, + Map body, + ) async { + final base = e2eParts(rel); + final kind = classifyE2e(base).kind; + if (kind == E2eRuleKind.unit || kind == E2eRuleKind.below) { + throw E2eLayoutError('PATCH into sealed unit $rel'); + } + return { + for (final e in body.entries) + e.key: await _seal([...base, ...e2eParts(e.key)], e.value), + }; + } + + Future _seal(List parts, Object? value) async { + final rule = classifyE2e(parts); + if (rule.kind == E2eRuleKind.clear || value == null) return value; + if (rule.kind == E2eRuleKind.unit) { + return await _sealUnit(parts, value, rule.keep); + } + if (rule.kind == E2eRuleKind.struct && value is Map) { + return { + for (final e in value.entries) + e.key as String: await _seal([ + ...parts, + ...e2eParts(e.key as String), + ], e.value), + }; + } + throw E2eLayoutError( + 'no e2e rule for a ${value.runtimeType} at ${parts.join('/')} ' + '(${rule.kind.name})', + ); + } + + Future?> _sealUnit( + List parts, + Object raw, + Set keep, + ) async { + // As RTDB would keep it: no null members, no empty objects. + final value = _pruned(raw); + if (value == null) return null; + var body = value; + final clear = {}; + if (value is Map && keep.isNotEmpty) { + body = { + for (final e in value.entries) + if (!keep.contains(e.key)) e.key as String: e.value, + }; + for (final e in value.entries) { + if (keep.contains(e.key)) clear[e.key as String] = e.value; + } + } + final blob = await cipher.seal(jsonEncode(body), path: _aad(parts)); + return {kSealedKey: blob, ...clear}; + } + + Future open(String rel, Object? value) => + _open(e2eParts(rel), value); + + Future _open(List parts, Object? value) async { + final rule = classifyE2e(parts); + switch (rule.kind) { + case E2eRuleKind.unit: + return await _openUnit(parts, value); + case E2eRuleKind.below: + throw E2eLayoutError('read below sealed unit: ${parts.join('/')}'); + case E2eRuleKind.struct when value is Map: + final out = {}; + for (final e in value.entries) { + final v = await _open([...parts, e.key as String], e.value); + if (v != null) out[e.key as String] = v; + } + return out; + case E2eRuleKind.struct when value is List: + return [ + for (var i = 0; i < value.length; i++) + await _open([...parts, '$i'], value[i]), + ]; + case _: + return value; + } + } + + Future _openUnit(List parts, Object? value) async { + if (value is! Map || value[kSealedKey] is! String) return value; + try { + final text = await cipher.open( + value[kSealedKey] as String, + path: _aad(parts), + ); + final data = jsonDecode(text); + if (data is! Map) return data; + return { + ...data.cast(), + for (final e in value.entries) + if (e.key != kSealedKey) e.key as String: e.value, + }; + } on FormatException { + // E2eDecryptError is one: tampered, moved, or another key. + return null; + } + } +} diff --git a/rtdb_relay/dart/test/support/tutor_layout.dart b/rtdb_relay/dart/test/support/tutor_layout.dart new file mode 100644 index 0000000..e2aaef4 --- /dev/null +++ b/rtdb_relay/dart/test/support/tutor_layout.dart @@ -0,0 +1,37 @@ +// The tutor app's layout (tutor DOCS-contract §12): the first consumer and +// the one its e2e vectors pin, so the tests run against the real tree. +import 'package:rtdb_relay/src/layout.dart'; + +/// The tutor's sealed tree, `tutor/v1-e2e`. +final RelayLayout tutorLayout = RelayLayout( + 'tutor/v1', + clear: const [ + 'meta', + 'rev', + 'migration', + 'requests/*/claim', + 'sessions/*/progress/rid', + ], + units: const { + 'live': {}, + 'prefs/*': {}, + 'stats/*': {}, + 'presence/workers/*': {'beat'}, + 'presence/clients/*': {'seen'}, + 'uploads/*/*': {}, + 'requests/*/req': {'created'}, + 'requests/*/result': {'at'}, + 'sessions/*/meta/*': {}, + 'sessions/*/msgs/*': {}, + 'sessions/*/receipts/*': {}, + 'sessions/*/user/*': {}, + 'sessions/*/progress/steps/*': {}, + 'session_index/*': {}, + 'subjects/*/meta': {}, + 'subjects/*/plan': {}, + 'subjects/*/cards': {}, + 'subjects/*/concepts': {}, + 'log/*/*': {}, + 'feedback/*': {}, + }, +); diff --git a/rtdb_relay/dart/test/wrapper_credentials_test.dart b/rtdb_relay/dart/test/wrapper_credentials_test.dart new file mode 100644 index 0000000..ead3d2d --- /dev/null +++ b/rtdb_relay/dart/test/wrapper_credentials_test.dart @@ -0,0 +1,98 @@ +import 'dart:convert'; + +import 'package:crdt_sync/crdt_sync.dart' show InMemoryCredentialStore; +import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; +import 'package:rtdb_relay/src/auth.dart'; +import 'package:rtdb_relay/src/wrapper_credentials.dart'; + +String _jwt(Map payload) { + final body = base64Url.encode(utf8.encode(jsonEncode(payload))); + return 'h.${body.replaceAll('=', '')}.s'; +} + +Map _creds(String token) => { + 'id_token': token, + 'refresh_token': 'r', + 'expires_at': '2099-01-01T00:00:00.000Z', +}; + +void main() { + final base = Uri.parse('http://127.0.0.1:8778/app/'); + + test('uid from the id token', () { + expect(uidOfIdToken(_jwt({'user_id': 'u'})), 'u'); + expect(uidOfIdToken(_jwt({'sub': 's'})), 's'); + expect(uidOfIdToken(_jwt({'sub': 1})), isNull); + expect(uidOfIdToken('a.b'), isNull); + expect(uidOfIdToken('a.!!!.c'), isNull); + expect(uidOfIdToken('h.${base64Url.encode(utf8.encode('[1]'))}.s'), isNull); + }); + + Future adopt(http.Response Function(http.Request) answer) async { + final store = InMemoryCredentialStore(); + final ok = await adoptWrapperCredentials( + base: base, + client: MockClient((r) async { + expect(r.url.path, '/app/sync-credentials'); + return answer(r); + }), + store: store, + expectedUid: 'u', + ); + expect(await store.load() != null, ok); + return ok; + } + + test('adopts the right account only', () async { + expect( + await adopt( + (_) => http.Response(jsonEncode(_creds(_jwt({'user_id': 'u'}))), 200), + ), + isTrue, + ); + expect( + await adopt( + (_) => http.Response(jsonEncode(_creds(_jwt({'user_id': 'x'}))), 200), + ), + isFalse, + ); + expect(await adopt((_) => http.Response('', 404)), isFalse); + expect(await adopt((_) => http.Response('[1]', 200)), isFalse); + expect( + await adopt((_) => http.Response(jsonEncode({'id_token': 'x'}), 200)), + isFalse, + ); + expect( + await adopt((_) => throw http.ClientException('no wrapper')), + isFalse, + ); + }); + + test('auth: the desktop adopts on the first session probe', () async { + final token = _jwt({'user_id': 'u'}); + final store = InMemoryCredentialStore(); + final client = MockClient( + (_) async => http.Response(jsonEncode(_creds(token)), 200), + ); + final auth = RelayAuth( + config: const RelayFirebaseConfig( + apiKey: 'k', + databaseUrl: 'https://db', + syncUid: 'u', + serverClientId: '', + ), + googleToken: ({required serverClientId}) async => null, + store: store, + httpClient: client, + adopt: () => adoptWrapperCredentials( + base: base, + client: client, + store: store, + expectedUid: 'u', + ), + ); + expect(await auth.hasSession(), isTrue); + }); +}