Client Auth

dependencies:
  portal_flutter: ^2.0.0
  app_links: ^7.2.1
  url_launcher: ^6.3.3
  # Only if your environment requires two-factor authentication
  qr_flutter: ^4.1.0
  # Only for a clean slate on iOS reinstalls (see below)
  shared_preferences: ^2.5.5

<!-- android/app/src/main/res/xml/portal_backup_rules.xml — Android 11 and below -->
<full-backup-content>
  <exclude domain="sharedpref" path="PortalAuth.xml" />
</full-backup-content>

<!-- android/app/src/main/res/xml/portal_data_extraction_rules.xml — Android 12 and later -->
<data-extraction-rules>
  <cloud-backup>
    <exclude domain="sharedpref" path="PortalAuth.xml" />
  </cloud-backup>
  <device-transfer>
    <exclude domain="sharedpref" path="PortalAuth.xml" />
  </device-transfer>
</data-extraction-rules>

<application
    ...
    android:fullBackupContent="@xml/portal_backup_rules"
    android:dataExtractionRules="@xml/portal_data_extraction_rules">
</application>

import 'dart:async';

import 'package:app_links/app_links.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

class DeepLinks {
  static final DeepLinks _instance = DeepLinks._();
  factory DeepLinks() => _instance;
  DeepLinks._();

  final _links = StreamController<Uri>.broadcast();
  StreamSubscription<Uri>? _subscription;
  Uri? _pending;

  /// Every link as it arrives, for a sign-in screen that is already showing.
  Stream<Uri> get links => _links.stream;

  void start() {
    _subscription ??= AppLinks().uriLinkStream.listen(
      (uri) {
        _pending = uri;
        _links.add(uri);
      },
      onError: (Object e) => debugPrint('❌ deep link error: $e'),
    );
  }

  /// Returns the pending link and clears it, so it is handled once.
  Uri? takePending() {
    final uri = _pending;
    _pending = null;
    return uri;
  }
}

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  DeepLinks().start();
  runApp(const MyApp());
}

import 'package:portal_flutter/portal_flutter.dart';

Future<void> configureAuth() async {
  await PortalAuth().configure(
    authEnvironmentId: 'YOUR_AUTH_ENVIRONMENT_ID',
    redirectUrl: 'myapp://auth/callback',
    // Required only by sendMagicLink()
    magicLink: PortalMagicLinkConfig(
      fromEmail: 'hello@auth.example.com',
      templateId: 'YOUR_TEMPLATE_ID',
    ),
    // Optional: whether the client Portal creates uses gas sponsorship
    // isAccountAbstracted: true,
  );
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<PortalAuthMethods> loadMethods() async {
  final methods = await PortalAuth().getMethods();

  debugPrint('✅ enabled: ${methods.allowedAuthMethods}'); // [PortalAuthMethod.google, PortalAuthMethod.emailMagicLink]
  debugPrint('✅ autoCreateWallet: ${methods.autoCreateWallet}');

  return methods;
}

import 'package:portal_flutter/portal_flutter.dart';
import 'package:url_launcher/url_launcher.dart';

Future<void> signInWithProvider(PortalAuthMethod method) async {
  final result = method == PortalAuthMethod.apple
      ? await PortalAuth().loginWithApple()
      : await PortalAuth().loginWithGoogle();

  await launchUrl(
    Uri.parse(result.authorizeUrl),
    mode: LaunchMode.externalApplication,
  );
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<void> sendMagicLink(String email) async {
  // Trimmed and lowercased by the SDK before it is sent.
  await PortalAuth().sendMagicLink(email);

  debugPrint('✅ magic link sent — check $email');
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

/// Returns whether [uri] was a Client Auth redirect that was handled.
Future<bool> completeSignIn(Uri uri) async {
  try {
    final result = await PortalAuth().handleRedirect(uri.toString());

    switch (result) {
      case null:
        // Not a Client Auth redirect — let the rest of your routing have it.
        return false;
      case PortalTotpRequired():
        promptForTotp(result);
      case PortalAuthenticated():
        // Must be safe to run twice — see the warning below.
        await onSignedIn(result.session);
    }
    return true;
  } on PortalException catch (e) {
    if (e.code == 'AUTH_AUTHENTICATION_FAILED') {
      debugPrint('❌ the user did not complete the provider sign-in');
    } else {
      debugPrint('❌ handleRedirect failed (${e.code}): ${e.message}');
    }
    return false;
  }
}

import 'package:flutter/foundation.dart';

Future<void> _queue = Future.value();

void _enqueue(Future<void> Function() step) {
  _queue = _queue
      .then((_) => step())
      .catchError((Object e) => debugPrint('❌ sign-in step failed: $e'));
}

Future<void> startSignInFlow() async {
  await configureAuth();

  final initial = DeepLinks().takePending();
  DeepLinks().links.listen((uri) {
    DeepLinks().takePending();
    _enqueue(() => completeSignIn(uri));
  });

  _enqueue(() async {
    // A pending link is a newer sign-in than anything already persisted.
    if (initial != null && await completeSignIn(initial)) return;

    // No link, or one that failed: a relaunch can re-deliver a link whose
    // session is already in storage.
    final session = await restore();
    if (session != null) await onSignedIn(session);
  });
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<PortalSession?> verifyTotp(
  PortalTotpRequired challenge,
  String code,
) async {
  try {
    final result = await PortalAuth().verifyTotp(
      code,
      userJwt: challenge.userJwt,
    );

    // The same session the non-TOTP path returns. Pass it to initialize(session:).
    return result.session;
  } on PortalException catch (e) {
    if (e.code == 'AUTH_TOTP_REJECTED') {
      // A rejected code does not consume the userJwt, so prompting again is normal.
      debugPrint('❌ code rejected — ask for the next code');
    } else {
      debugPrint('❌ verifyTotp failed (${e.code}): ${e.message}');
    }
    return null;
  }
}

import 'package:flutter/material.dart';
import 'package:portal_flutter/portal_flutter.dart';
import 'package:qr_flutter/qr_flutter.dart';

Widget enrollment(PortalTotpRequired challenge) {
  final link = challenge.totpLink;
  final secret = challenge.totpSecret;

  // Already enrolled: just ask for the code.
  if (link == null) return const SizedBox.shrink();

  return Column(
    children: [
      QrImageView(data: link, size: 200),
      if (secret != null) SelectableText(secret),
    ],
  );
}

import 'package:portal_flutter/portal_flutter.dart';

Future<void> initializePortal(PortalSession session) async {
  await Portal().initialize(
    session: session,
    rpcConfig: {
      'eip155:11155111': 'https://api.portalhq.io/rpc/v1/eip155/11155111',
    },
  );
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<void> resolveWallet(PortalAuthMethods methods) async {
  final portal = Portal();

  if (await portal.isWalletOnDevice()) {
    debugPrint('✅ reusing the wallet on this device');
    return;
  }

  final client = await portal.getClient();
  if (client.wallets.isNotEmpty) {
    // The wallet exists elsewhere — recover it. See Recover a wallet.
    debugPrint('✅ wallet exists but is not on this device');
    return;
  }

  if (!methods.autoCreateWallet) {
    debugPrint('✅ autoCreateWallet is off — not creating a wallet');
    return;
  }

  final addresses = await portal.createWallet();
  debugPrint('✅ wallet created: ${addresses.ethereum}');
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<PortalSession?> restore() async {
  try {
    final session = await PortalAuth().restoreSession();

    if (session == null) {
      debugPrint('✅ nothing stored — show the sign-in screen');
    }

    return session;
  } on PortalException catch (e) {
    // AUTH_SESSION_STORAGE_FAILURE: storage failed this time. It may succeed on the next attempt.
    debugPrint('❌ restoreSession failed (${e.code}): ${e.message}');
    return null;
  }
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';
import 'package:shared_preferences/shared_preferences.dart';

const _clearedKey = 'portalAuth.clearedAfterInstall';

Future<void> clearSessionLeftByPreviousInstall() async {
  if (defaultTargetPlatform != TargetPlatform.iOS) return;

  try {
    final prefs = await SharedPreferences.getInstance();
    if (prefs.getBool(_clearedKey) ?? false) return;

    await PortalAuth().clearPersistedSession();
    await prefs.setBool(_clearedKey, true);
  } catch (e) {
    debugPrint('❌ could not clear the previous install\'s session: $e');
  }
}

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

Future<void> signOut() async {
  try {
    await Portal().clearSession();
  } on PortalException catch (e) {
    debugPrint('❌ clearSession failed (${e.code}): ${e.message}');
  }

  // Runs even when clearSession() failed, so the next launch cannot restore
  // the session the user just signed out of.
  await PortalAuth().clearPersistedSession();
}

import 'dart:async';

import 'package:flutter/foundation.dart';
import 'package:portal_flutter/portal_flutter.dart';

class SessionState {
  static final SessionState _instance = SessionState._();
  factory SessionState() => _instance;
  SessionState._();

  final sessionEnded = ValueNotifier<bool>(false);
  StreamSubscription<void>? _subscription;

  /// Call once at startup, before the first initialize(session:).
  void start() {
    _subscription ??= Portal().onSessionInvalidated.listen((_) {
      sessionEnded.value = true;
    });
  }

  /// Call after initialize(session:) with a new session.
  void signedIn() => sessionEnded.value = false;
}

import 'package:portal_flutter/portal_flutter.dart';

/// [completingSignIn] is true when the failure came from handleRedirect() or
/// verifyTotp(), where a rejected grant means the sign-in has to start over.
String describe(PortalException e, {required bool completingSignIn}) {
  if (e.requiresReauthentication) {
    return 'Your session ended. Please sign in again.';
  }

  return switch (e.code) {
    'AUTH_METHOD_UNAVAILABLE' => 'That sign-in method is not available.',
    'AUTH_AUTHENTICATION_FAILED' => 'Sign-in was not completed.',
    'AUTH_RATE_LIMITED' => 'Too many emails sent. Please wait a minute.',
    'AUTH_TOTP_REJECTED' => 'That code was not accepted. Try the next one.',
    'AUTH_HANDLE_REDIRECT_ERROR' when completingSignIn =>
      'That sign-in link could not be used. Please start a new sign-in.',
    'CREDENTIAL_UNAVAILABLE' ||
    'CREDENTIAL_PROVIDER_FAILURE' => 'Could not read your session. Please try again.',
    _ => 'Something went wrong.',
  };
}