Files
buzz/mobile/lib/features/invites/invite_join_provider.dart
Taylor Ho d8281b9c93 feat(mobile): require device authentication for identity export (#5116)
**Category:** new-feature
**User Impact:** Mobile users must confirm with Face ID, biometrics, or
their device passcode before sending their Buzz identity to Desktop.

**Problem:** A signed-in phone could send its full identity, including
the `nsec`, to a desktop without fresh local verification.

**Solution:** Require OS device authentication before opening the
identity-recovery scanner, retain that authorization only for the active
pairing session and short pairing window, and require fresh
authentication again if it expires before the identity payload is sent.
Normal app opening, identity import, and community removal remain
unchanged.

## Screencasts

| Enable Face ID | Use Face ID |
| --- | --- |
| ![Enabling Face ID during identity
import](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/5116/enable-face-id.gif)
| ![Using Face ID for identity
export](https://d24qwcpro867f5.cloudfront.net/repos/buzz/prs/5116/use-face-id.gif)
|

<details>
<summary>File changes</summary>

**Android and iOS integration**
- `mobile/android/app/build.gradle.kts` declares the AppCompat
dependency required by the biometric activity theme.
-
`mobile/android/app/src/main/kotlin/xyz/block/buzz/mobile/MainActivity.kt`
uses the activity type required by the system authentication prompt.
- `mobile/android/app/src/main/res/values/styles.xml` and
`mobile/android/app/src/main/res/values-night/styles.xml` use the
compatible launch theme.
- `mobile/ios/Podfile.lock` records the native local-authentication
dependency.
- `mobile/ios/Runner/Info.plist` explains why Buzz requests Face ID
access.

**Identity policy and pairing flow**
- `mobile/lib/shared/security/sensitive_action_authorizer.dart` wraps OS
authentication and maps platform errors to stable app-level outcomes.
- `mobile/lib/shared/community/community.dart` and
`mobile/lib/shared/community/community_storage.dart` persist the
sensitive-action policy.
- `mobile/lib/features/invites/invite_join_provider.dart` assigns the
explicit policy for invite-created communities.
- `mobile/lib/features/pairing/pairing_provider.dart` gates export,
binds grants to the active community/session, reauthenticates expired
grants, and clears grants on every terminal path.
- `mobile/lib/features/pairing/pairing_page.dart` lets users choose
biometric protection while importing an identity.
- `mobile/lib/features/settings/settings_page.dart` wires pairing into
settings.
- `mobile/lib/features/settings/settings_page/connection_section.dart`
authenticates before opening export recovery and bounds the
foreground-resume wait.
- `mobile/pubspec.yaml` and `mobile/pubspec.lock` add and lock
`local_auth`.

**Coverage**
- `mobile/test/shared/security/sensitive_action_authorizer_test.dart`
covers native result mapping, unsupported devices, and single-flight
behavior.
- `mobile/test/shared/community/community_test.dart` and
`mobile/test/shared/community/community_storage_test.dart` cover policy
defaults and persistence.
- `mobile/test/features/invites/invite_join_provider_test.dart` covers
the invite policy.
- `mobile/test/features/pairing/pairing_page_test.dart` covers import
protection controls.
- `mobile/test/features/pairing/pairing_provider_test.dart` covers
export/import authorization, stale/reset/concurrent guards, malformed
payload cleanup, and no-export failure paths.
- `mobile/test/features/settings/connection_section_test.dart` covers
the tap gate, lifecycle resume, and timeout behavior.

</details>

## Reproduction steps

1. Pair an identity into the mobile app.
2. Open Settings and choose “Send identity to desktop.”
3. Verify Face ID, biometrics, or the device passcode is required before
the recovery scanner opens.
4. Cancel device authentication and verify the scanner does not open and
no identity transfer begins.
5. Authenticate, scan a Desktop recovery code, confirm the SAS, and
verify the identity transfer completes.

## Validation

At `be5620f5f10aa6cc16e86a4f01f102f3d9aeef9b`:
- `cd mobile && ../bin/flutter analyze` — no issues
- `cd mobile && ../bin/flutter test` — 1,368 tests passed
- `cd mobile/android && JAVA_HOME=$(/usr/libexec/java_home -v 21)
./gradlew app:assembleDebug` — debug APK assembled successfully

---------

Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
2026-08-15 18:34:02 -07:00

288 lines
8.5 KiB
Dart

import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:hooks_riverpod/hooks_riverpod.dart';
import 'package:nostr/nostr.dart' as nostr;
import '../../shared/auth/auth.dart';
import '../../shared/deeplink/deep_link.dart';
import '../../shared/relay/relay_session.dart';
import '../../shared/relay/relay_validation.dart';
final inviteJoinHttpClientProvider = Provider<http.Client>((ref) {
final client = http.Client();
ref.onDispose(client.close);
return client;
});
final inviteKeyGeneratorProvider = Provider<InviteKeyGenerator>((ref) {
return () => nostr.Keys.generate();
});
typedef InviteKeyGenerator = nostr.Keys Function();
enum InviteJoinStatus {
idle,
confirming,
claiming,
success,
switchedExisting,
error,
}
class InviteJoinState {
final InviteJoinStatus status;
final InviteDeepLink? invite;
final String? host;
final String? communityName;
final String? errorMessage;
final bool requiresFreshInvite;
const InviteJoinState({
this.status = InviteJoinStatus.idle,
this.invite,
this.host,
this.communityName,
this.errorMessage,
this.requiresFreshInvite = false,
});
InviteJoinState copyWith({
InviteJoinStatus? status,
InviteDeepLink? invite,
String? host,
String? communityName,
String? errorMessage,
bool? requiresFreshInvite,
}) => InviteJoinState(
status: status ?? this.status,
invite: invite ?? this.invite,
host: host ?? this.host,
communityName: communityName ?? this.communityName,
errorMessage: errorMessage ?? this.errorMessage,
requiresFreshInvite: requiresFreshInvite ?? this.requiresFreshInvite,
);
}
class InviteJoinNotifier extends Notifier<InviteJoinState> {
@override
InviteJoinState build() => const InviteJoinState();
Future<void> prepare(InviteDeepLink invite) async {
validateInviteRelayUri(Uri.parse(invite.relayUrl));
final communities = await ref.read(communityListProvider.future);
final existing = _existingCommunity(communities, invite.relayUrl);
if (existing != null) {
await ref
.read(communityListProvider.notifier)
.switchCommunity(existing.id);
state = InviteJoinState(
status: InviteJoinStatus.switchedExisting,
invite: invite,
host: _hostFromRelay(invite.relayUrl),
communityName: existing.name,
);
return;
}
state = InviteJoinState(
status: InviteJoinStatus.confirming,
invite: invite,
host: _hostFromRelay(invite.relayUrl),
communityName: Community.nameFromUrl(invite.relayUrl),
);
}
Future<void> confirmJoin() async {
final invite = state.invite;
if (invite == null ||
state.requiresFreshInvite ||
(state.status != InviteJoinStatus.confirming &&
state.status != InviteJoinStatus.error)) {
return;
}
state = state.copyWith(status: InviteJoinStatus.claiming);
try {
final communities = await ref.read(communityListProvider.future);
final existing = _existingCommunity(communities, invite.relayUrl);
if (existing != null) {
await ref
.read(communityListProvider.notifier)
.switchCommunity(existing.id);
state = state.copyWith(
status: InviteJoinStatus.switchedExisting,
communityName: existing.name,
);
return;
}
final keys = ref.read(inviteKeyGeneratorProvider)();
final body = jsonEncode({
'code': invite.code,
if (invite.policyReceipt != null)
'policy_receipt': invite.policyReceipt,
});
final relayUri = Uri.parse(invite.relayUrl);
validateInviteRelayUri(relayUri);
final url = _claimUrlFromRelay(invite.relayUrl);
final request = http.Request('POST', Uri.parse(url))
..followRedirects = false
..headers.addAll({
'Authorization': buildNip98AuthHeader(
method: 'POST',
url: url,
bodyBytes: utf8.encode(body),
nsec: keys.nsec,
),
'Content-Type': 'application/json',
})
..body = body;
final streamedResponse = await ref
.read(inviteJoinHttpClientProvider)
.send(request);
final response = await http.Response.fromStream(streamedResponse);
final decoded = jsonDecode(response.body.isEmpty ? '{}' : response.body);
if (response.statusCode < 200 || response.statusCode >= 300) {
final message = decoded is Map && decoded['error'] is String
? decoded['error'] as String
: 'HTTP ${response.statusCode}';
throw InviteClaimException(message);
}
if (decoded is! Map) {
throw const FormatException('Invite claim returned malformed JSON');
}
final claim = Map<String, dynamic>.from(decoded);
final community = Community.create(
name: _communityNameFromClaim(claim, invite.relayUrl),
relayUrl: invite.relayUrl,
pubkey: keys.public,
nsec: keys.nsec,
sensitiveActionPolicy: SensitiveActionPolicy.disabledByUser,
);
await ref
.read(authProvider.notifier)
.authenticateWithCommunity(community);
state = state.copyWith(
status: InviteJoinStatus.success,
communityName: community.name,
);
} catch (error) {
final requiresFreshInvite = _requiresFreshInvite(error);
state = state.copyWith(
status: InviteJoinStatus.error,
errorMessage: _friendlyInviteError(error),
requiresFreshInvite: requiresFreshInvite,
);
}
}
void reset() {
state = const InviteJoinState();
}
}
final inviteJoinProvider =
NotifierProvider<InviteJoinNotifier, InviteJoinState>(
InviteJoinNotifier.new,
);
class InviteClaimException implements Exception {
final String message;
const InviteClaimException(this.message);
@override
String toString() => message;
}
Community? _existingCommunity(List<Community> communities, String relayUrl) {
final invite = _relayOriginForComparison(relayUrl);
for (final community in communities) {
final current = _relayOriginForComparison(community.relayUrl);
if (current == null) continue;
if (current == invite) {
return community;
}
}
return null;
}
({bool secure, String host, int? port})? _relayOriginForComparison(String url) {
final uri = Uri.tryParse(url);
if (uri == null || uri.host.isEmpty) return null;
final secure = switch (uri.scheme) {
'https' || 'wss' => true,
'http' || 'ws' => false,
_ => null,
};
if (secure == null) return null;
return (
secure: secure,
host: uri.host.toLowerCase(),
port: _effectivePort(uri),
);
}
int? _effectivePort(Uri uri) {
if (uri.hasPort) return uri.port;
return switch (uri.scheme) {
'https' || 'wss' => 443,
'http' || 'ws' => 80,
_ => null,
};
}
String _hostFromRelay(String relayUrl) {
final uri = Uri.parse(relayUrl);
if (uri.hasPort) return '${uri.host}:${uri.port}';
return uri.host;
}
String _claimUrlFromRelay(String relayUrl) {
final uri = Uri.parse(relayUrl);
final scheme = switch (uri.scheme) {
'wss' => 'https',
'ws' => 'http',
_ => throw FormatException('Invalid relay URL scheme: ${uri.scheme}'),
};
return Uri(
scheme: scheme,
host: uri.host,
port: uri.hasPort ? uri.port : null,
path: '/api/invites/claim',
).toString();
}
String _communityNameFromClaim(Map<String, dynamic> claim, String relayUrl) {
final host = claim['host'];
if (host is String && host.trim().isNotEmpty) return host.trim();
return Community.nameFromUrl(relayUrl);
}
bool _requiresFreshInvite(Object error) {
final message = error.toString();
return message.contains('join_policy_required') ||
message.contains('invite_exhausted');
}
String _friendlyInviteError(Object error) {
final message = error.toString();
if (message.contains('invite_expired')) return 'This invite has expired.';
if (message.contains('invite_exhausted')) {
return 'This invite has reached its use limit. Ask for a new invite.';
}
if (message.contains('invite_invalid')) return 'This invite is not valid.';
if (message.contains('join_policy_required')) {
return 'This invite approval has expired. Re-open the invite link to try again.';
}
if (message.contains('SocketException') ||
message.contains('Connection refused') ||
message.contains('Network is unreachable') ||
message.contains('No route to host')) {
return 'Could not reach the relay. Check your connection and try again.';
}
return 'Could not join this community: $message';
}