ToroPass Client

toropass_client is a Flutter package for launching ToroPass Wallet OAuth identity verification flows from third-party apps.

It handles:

  • launching ToroPass Wallet through a native deep link
  • receiving the callback URI in your app
  • validating the OAuth state
  • exchanging the authorization code for an app-scoped access token
  • fetching the approved ToroPass profile

Features

  • ToroPassClient.verifyIdentity() for the one-call authorization flow
  • ToroPassClient.createAuthorizationRequest() and waitForCallback() for lower-level control
  • ToroPassClient.exchangeAuthorizationCode() and fetchProfile() for manual token/profile flows
  • typed auth results for success, denial, cancellation, timeout, transport failure, and state mismatch
  • ToroPassButton for lightweight UI integration
  • toStatusMessage() for host-friendly result messaging

Installation

dependencies:
  toropass_client: ^0.1.0

Then run:

flutter pub get

Quick Start

final client = ToroPassClient(
  config: ToroPassClientConfig(
    clientId: 'toro_client_123',
    redirectUri: Uri.parse('myapp://oauth/callback'),
    scopes: const {
      ToroPassScope.kycStatus,
      ToroPassScope.wallet,
    },
  ),
);

final result = await client.verifyIdentity(appName: 'Example App');

switch (result) {
  case ToroPassAuthSuccess(:final token, :final profile):
    print(token.accessToken);
    print(profile.wallet.tnsName);
  case ToroPassAuthDenied():
    print('User denied access.');
  case ToroPassAuthCancelled():
    print('User cancelled the flow.');
  case ToroPassAuthTimeout():
    print('ToroPass did not return in time.');
  case ToroPassAuthTransportError(:final message):
    print(message);
  case ToroPassAuthStateMismatch():
    print('Callback state mismatch.');
  case ToroPassAuthorizationCodeReceived():
    break;
}

UI Helper

ToroPassButton(
  client: client,
  appName: 'Example App',
  onResult: (result) {
    final status = result.toStatusMessage();
    debugPrint('${status.title}: ${status.message}');
  },
)

Manual Flow

If you want more control over the handoff:

final request = client.createAuthorizationRequest(appName: 'Example App');
final launched = await client.launchWallet(
  appName: request.appName,
  state: request.state,
);

if (launched == null) {
  print('ToroPass Wallet is unavailable.');
  return;
}

final callback = await client.waitForCallback(launched);

if (callback case ToroPassAuthorizationCodeReceived(:final code)) {
  final session = await client.exchangeAuthorizationCode(code: code);
  final profile = await client.fetchProfile(
    accessToken: session.token.accessToken,
  );
  print(profile.wallet.address);
}

Native Setup

Your client app must do two things:

  1. Register your callback URI scheme, for example myapp://oauth/callback
  2. Allow wallet-scheme discovery for toropass

Android

Register your callback URI in AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
      android:scheme="myapp"
      android:host="oauth"
      android:path="/callback" />
</intent-filter>

Add a visibility query so canLaunchUrl can detect ToroPass Wallet:

<queries>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="toropass" />
  </intent>
</queries>

iOS

Register your callback URI in Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Allow wallet-scheme discovery:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>toropass</string>
</array>

Tokens

toropass_client does not persist OAuth access tokens for you.

Host apps are responsible for deciding:

  • where to store tokens
  • how to refresh app state
  • when to clear tokens after revocation or expiry

Example

A runnable integration harness is included in example.

There is also a manual verification guide.

Libraries

toropass_client