Flutter SDK Overview

Intended purpose & user: rakomi_flutter is a client SDK for Flutter developers integrating Rakomi authentication into a mobile or web app — sign-in UI, session lifecycle, secure token storage, and OAuth/PKCE social sign-in, all through a single RakomiProvider widget.

Secure defaults

The SDK ships secure-by-default: RS256-only JWT verification, HTTPS-only transport, and platform-native secure storage. See Security for the full posture.

Platform support

Platform	Support
iOS	Supported
Android	Supported
Flutter Web	Supported (see Web security considerations)

Requirements:

• Dart SDK >=3.11.0 <4.0.0
• Flutter >=3.41.0

What this SDK gives you

• RFC 8252-compliant OAuth/PKCE — system-browser sign-in only, no WebView, PKCE S256 mandatory.
• Platform-native secure storage — iOS Keychain, Android encrypted shared_preferences (via flutter_secure_storage), with a documented Web fallback.
• Biometric unlock — a pluggable native adapter exposes a typed BiometricResult.
• MFA (TOTP) — step-up verification wired into the primary sign-in flow.
• Offline-tolerant JWKS verification — signature checks work against a cached key set with a 24-hour ceiling, no network round-trip on every check.
• Pre-built widgets — RakomiAuthGate, RakomiSignInForm, RakomiSignInButton, RakomiUserAvatar — Material on Android/Web, Cupertino on iOS.
• A pluggable native adapter (RakomiNativeAdapter) for consumers who need to swap storage, the system-browser launcher, or the biometric gate for testing or an alternative plugin.

Quick start

import 'package:flutter/material.dart';
import 'package:rakomi_flutter/rakomi_flutter.dart';

void main() => runApp(MaterialApp(home: RakomiProvider(
  publishableKey: 'pk_live_…',
  redirectUri: 'myapp://callback',
  child: RakomiAuthGate(
    signedIn: (ctx, user) => RakomiUserAvatar(),
    signedOut: (ctx) => RakomiSignInForm(
      providers: [SocialProvider.google, SocialProvider.apple],
    ),
  ),
)));

This is the complete, runnable shape of a Rakomi-authenticated screen: RakomiProvider mounts the auth controller for the widget subtree beneath it, and RakomiAuthGate renders the signed-in or signed-out branch based on the current AuthState.

API surface

Area	Reference
Installation & platform setup	Installation
Sign-in / sign-out flows	Authentication
Secure storage, refresh, JWKS	Session & tokens
RakomiProvider constructor	Configuration
SdkError taxonomy	Errors
Threat model & disclosure	Security

Design principles

• Non-blocking mount — the first frame renders AuthState.loading() synchronously; secure- storage hydration runs asynchronously afterward.
• Per-provider-tree, not a singleton — RakomiProvider.of(context) resolves to the nearest enclosing RakomiProvider. Multiple providers can coexist in the same widget tree.
• Result-free async API — sign-in methods return the resulting AuthState; failures never throw across the public surface (programmer errors are the one exception — see Errors).
• Two parallel streams — authStateChanges (the current discriminated snapshot) and events (a fine-grained, append-only lifecycle log) are separate broadcast Streams.