feat: let a negentropy reconciliation say which identity it may use

doc/concepts/nip42-auth.md

@@ -4,4 +4,4 @@ NDK handles NIP-42 relay authentication automatically. When a relay requires aut
 
 A connection carries at most one identity, chosen when it is opened and immutable for its whole lifetime, so a request that authenticates moves to its own connection.
 
-Which identity a request may be attributed to is the `auth` parameter, see [requests](/usecases/requests.md#relay-authentication-nip-42).
+Which identity a request may be attributed to is the `auth` parameter, see [requests](/usecases/requests.md#relay-authentication-nip-42). The same parameter says which identity a negentropy reconciliation may use, see [negentropy](/usecases/negentropy.md#relay-authentication-nip-42).

doc/usecases/negentropy.md

@@ -21,6 +21,36 @@ final result = await response.future;
 print('Sync complete: ${result.needIds.length} events to fetch, ${result.haveIds.length} events to broadcast');
 ```
 
+## Relay authentication (NIP-42)
+
+Some relays only reconcile with a client that authenticated, the same way they
+only serve a request to one. The `auth` parameter says which identity the
+reconciliation may be attributed to, exactly like on
+[requests](/usecases/requests.md#relay-authentication-nip-42):
+
+```dart
+final response = ndk.nip77.reconcile(
+  relayUrl: 'wss://relay.example.com',
+  filter: Filter(authors: [myPubkey]),
+  auth: RelayAuth.require(account),
+);
+```
+
+| policy | connection | what a relay learns |
+| --- | --- | --- |
+| `RelayAuth.never()` | anonymous, always | nothing. A relay that refuses the negotiation without an identity simply does not reconcile |
+| `RelayAuth.allow(a)` | anonymous, moves to one bound to `a` once the relay refuses | who you are, but only after that relay asked |
+| `RelayAuth.require(a)` | bound to `a` from the start | who you are, as soon as it sends a challenge |
+
+Without `auth`, a refused negotiation authenticates as the currently logged-in
+account, so the relay decides when your identity is revealed. Pass `auth`
+explicitly whenever that matters.
+
+If `require` names an account that cannot sign, no connection can carry the
+reconciliation. Rather than fall back to the anonymous one, which is what
+`require` rules out, nothing is sent and `reconcile` itself throws
+`Nip77AuthUnavailableException`.
+
 ## Error handling
 
 ### Relay doesn't support NIP-77
@@ -41,6 +71,22 @@ try {
 }
 ```
 
+### Relay requires an identity you did not give it
+
+```dart
+try {
+  await ndk.nip77.reconcile(
+    relayUrl: 'wss://relay.example.com',
+    filter: filter,
+    auth: const RelayAuth.never(),
+  ).future;
+} on Nip77AuthRequiredException catch (e) {
+  print('Relay wants an identity: ${e.message}');
+} on Nip77AuthUnavailableException catch (e) {
+  print('${e.pubkey} cannot sign, nothing was sent');
+}
+```
+
 ## When to use
 
 ✅ **Good for:**

packages/ndk/lib/domain_layer/entities/nip77_state.dart

@@ -4,14 +4,34 @@ import 'dart:typed_data';
 import 'package:rxdart/rxdart.dart';
 
 import '../../shared/nips/nip77/negentropy.dart';
+import 'filter.dart';
+import 'relay_auth.dart';
+import 'relay_connection_key.dart';
 
 /// State of a NIP-77 negentropy reconciliation session
 class Nip77State {
   /// Unique subscription ID for this session
   final String subscriptionId;
 
+  /// Connection this session runs on. It moves to a bound connection when a
+  /// relay refuses the negotiation without an identity.
+  RelayConnectionKey connectionKey;
+
+  /// Filter the negotiation was opened with, replayed on an auth retry
+  final Filter filter;
+
+  /// Which identity this session may be attributed to (NIP-42)
+  final RelayAuth? auth;
+
+  /// whether the negotiation already moved from the anonymous connection to a
+  /// bound one
+  bool movedToBoundConnection = false;
+
+  /// whether AUTH was already sent for the bound connection after a refusal
+  bool authenticatedAfterRefusal = false;
+
   /// Relay URL this session is connected to
-  final String relayUrl;
+  String get relayUrl => connectionKey.url;
 
   /// Local items for reconciliation
   final List<NegentropyItem> localItems;
@@ -39,8 +59,10 @@ class Nip77State {
 
   Nip77State({
     required this.subscriptionId,
-    required this.relayUrl,
+    required this.connectionKey,
+    required this.filter,
     required this.localItems,
+    this.auth,
   });
 
   /// Stream of IDs we need from the relay
@@ -55,6 +77,53 @@ class Nip77State {
   /// Whether the session is completed
   bool get isCompleted => _isCompleted;
 
+  Timer? _timeoutTimer;
+  DateTime? _timeoutStartedAt;
+  Duration? _remainingTimeout;
+  void Function()? _onTimeout;
+
+  /// how long the reconciliation itself may take. A paused timeout resumes
+  /// with what is left of it, not with a fresh one
+  Duration? _timeoutDuration;
+
+  /// Starts the session timeout, [onTimeout] firing at most once.
+  void startTimeout(Duration duration, void Function() onTimeout) {
+    _timeoutDuration = duration;
+    _onTimeout = onTimeout;
+    _startTimeout(duration);
+  }
+
+  void _startTimeout(Duration duration) {
+    _timeoutStartedAt = DateTime.now();
+    _timeoutTimer = Timer(duration, () => _onTimeout?.call());
+  }
+
+  /// Pauses the timeout for a wait that is not the relay's to answer, the way
+  /// a request pauses before signing. Call it before an authentication.
+  void pauseTimeout() {
+    if (_timeoutTimer == null || _timeoutDuration == null) return;
+
+    final elapsed = DateTime.now().difference(_timeoutStartedAt!);
+    final remaining = _timeoutDuration! - elapsed;
+    _remainingTimeout = remaining.isNegative ? Duration.zero : remaining;
+    _timeoutTimer!.cancel();
+    _timeoutTimer = null;
+  }
+
+  /// Resumes a paused timeout with the time it had left.
+  void resumeTimeout() {
+    final remaining = _remainingTimeout;
+    if (remaining == null) return;
+    _remainingTimeout = null;
+    _startTimeout(remaining);
+  }
+
+  void _cancelTimeout() {
+    _timeoutTimer?.cancel();
+    _timeoutTimer = null;
+    _remainingTimeout = null;
+  }
+
   /// Process an incoming NEG-MSG from relay
   /// Returns the response message bytes to send back, or null if done
   Uint8List? processMessage(Uint8List messageBytes) {
@@ -90,6 +159,7 @@ class Nip77State {
   void complete() {
     if (_isCompleted) return;
     _isCompleted = true;
+    _cancelTimeout();
     _needController.close();
     _haveController.close();
     _completer.complete(
@@ -104,6 +174,7 @@ class Nip77State {
   void completeWithError(Object error) {
     if (_isCompleted) return;
     _isCompleted = true;
+    _cancelTimeout();
     this.error = error.toString();
     _needController.close();
     _haveController.close();
@@ -114,6 +185,7 @@ class Nip77State {
   void close() {
     if (_isCompleted) return;
     _isCompleted = true;
+    _cancelTimeout();
     _needController.close();
     _haveController.close();
     if (!_completer.isCompleted) {

packages/ndk/lib/domain_layer/usecases/nip77/nip77.dart

@@ -8,6 +8,7 @@ import '../../../shared/nips/nip77/negentropy.dart' as neg;
 import '../../entities/connection_source.dart';
 import '../../entities/global_state.dart';
 import '../../entities/nip77_state.dart';
+import '../../entities/relay_connectivity.dart';
 import '../relay_manager.dart';
 
 part 'nip77_internal.dart';
@@ -24,6 +25,43 @@ class Nip77NotSupportedException implements Exception {
       'Nip77NotSupportedException: Relay $relayUrl does not support NIP-77${message != null ? ': $message' : ''}';
 }
 
+/// Exception thrown when no connection can carry the reconciliation, because
+/// the identity it requires cannot sign. Falling back to the anonymous
+/// connection is exactly what [RelayAuth.require] ruled out.
+class Nip77AuthUnavailableException implements Exception {
+  /// relay the reconciliation was meant for
+  final String relayUrl;
+
+  /// identity that was required
+  final String pubkey;
+
+  /// no connection can carry the reconciliation
+  Nip77AuthUnavailableException(this.relayUrl, this.pubkey);
+
+  @override
+  String toString() =>
+      'Nip77AuthUnavailableException: $pubkey cannot sign, so no connection to '
+      '$relayUrl can carry this reconciliation';
+}
+
+/// Exception thrown when a relay refuses the negotiation without an identity
+/// and the auth policy leaves nobody to authenticate as.
+class Nip77AuthRequiredException implements Exception {
+  /// relay that refused
+  final String relayUrl;
+
+  /// raw refusal from the relay
+  final String message;
+
+  /// the relay asked for an identity this reconciliation may not reveal
+  Nip77AuthRequiredException(this.relayUrl, this.message);
+
+  @override
+  String toString() =>
+      'Nip77AuthRequiredException: $relayUrl requires an identity this '
+      'reconciliation may not authenticate as: $message';
+}
+
 /// Exception thrown when NIP-77 reconciliation times out
 class Nip77TimeoutException implements Exception {
   final String relayUrl;
@@ -76,13 +114,31 @@ class Nip77 {
   static const Duration defaultTimeout = Duration(seconds: 30);
 
   /// Process incoming NEG-MSG from a relay
-  void processNegMsg(String subscriptionId, String relayUrl, String payload) {
-    _internal.processNegMsg(subscriptionId, relayUrl, payload);
+  void processNegMsg(
+    String subscriptionId,
+    RelayConnectionKey key,
+    String payload,
+  ) {
+    _internal.processNegMsg(subscriptionId, key, payload);
   }
 
   /// Process incoming NEG-ERR from a relay
-  void processNegErr(String subscriptionId, String relayUrl, String errorMsg) {
-    _internal.processNegErr(subscriptionId, relayUrl, errorMsg);
+  void processNegErr(
+    String subscriptionId,
+    RelayConnectionKey key,
+    String errorMsg,
+  ) {
+    _internal.processNegErr(subscriptionId, key, errorMsg);
+  }
+
+  /// Process a CLOSED that ends a negotiation, which is how some relays refuse
+  /// a NEG-OPEN instead of answering NEG-ERR
+  void processNegClosed(
+    String subscriptionId,
+    RelayConnectionKey key,
+    String? message,
+  ) {
+    _internal.processNegClosed(subscriptionId, key, message);
   }
 
   /// Close a specific NIP-77 negotiation
@@ -102,23 +158,33 @@ class Nip77 {
   /// [timeout] - How long to wait before timing out (default: 30s)
   /// [localIds] - Optional pre-computed list of local event IDs to use.
   ///              If not provided, will query the cache using the filter.
+  /// [auth] - which identity this reconciliation may be attributed to, see
+  ///          [RelayAuth]. Without it, a relay that refuses the negotiation
+  ///          without an identity is answered as the logged-in account.
   ///
   /// Returns a [Nip77Response] with streams for real-time updates and
   /// a future that completes with the final result.
   ///
-  /// Throws [Nip77NotSupportedException] if the relay doesn't support NIP-77.
-  /// Throws [Nip77TimeoutException] if reconciliation times out.
+  /// Throws [Nip77AuthUnavailableException] from the call itself, before
+  /// anything is sent, if [auth] requires an identity that cannot sign.
+  ///
+  /// The returned future fails with [Nip77NotSupportedException] if the relay
+  /// doesn't support NIP-77, [Nip77TimeoutException] if reconciliation times
+  /// out, and [Nip77AuthRequiredException] if the relay asks for an identity
+  /// [auth] rules out.
   Nip77Response reconcile({
     required String relayUrl,
     required Filter filter,
     Duration timeout = defaultTimeout,
     List<String>? localIds,
+    RelayAuth? auth,
   }) {
     return _internal.reconcile(
       relayUrl: relayUrl,
       filter: filter,
       timeout: timeout,
       localIds: localIds,
+      auth: auth,
     );
   }
 }