amani_auth_sdk

AmaniQuery Auth Intelligence Flutter SDK — device signal collection, risk assessment, passkeys (FIDO2/WebAuthn), biometrics, social sign-in, consent and DSR APIs against the AmaniQuery gateway (/v2/auth/*).

Implements the client side of AmaniQuery_Auth_Intelligence_Part2_Flutter_SDK.md against the real gateway routes (Parts 3, 4, 5, 6 of the same doc set).

Usage

final auth = await AuthService.initialize(AuthEnvironments.staging);
final risk = await auth.collectSignals(screenWidth: 390, screenHeight: 844);
print('risk=${risk.recommendedAction} score=${risk.riskScore}');

Modules

Module	Purpose
`AuthService` (singleton)	Config, persistent device fingerprint, risk stream, session ids
`AuthIntelligenceClient`	HTTP client for `/v2/auth/*` (signals, verify, devices, consent, DSR, social exchange, passkeys)
`BiometricService`	`local_auth` wrapper (Face ID / Touch ID / Android BiometricPrompt)
`PasskeyPlatform` / `PasskeysPlatformImpl`	FIDO2 ceremony glue for the `passkeys` plugin
`SocialAuthService`	Google / Apple / Microsoft / LinkedIn OIDC sign-in
`SessionStore`	Token + fingerprint persistence in secure storage
`OfflineAuthQueue`	SQLite queue for offline verify events
`RetryPolicy`	Exponential backoff with jitter
`RiskAwareLoginFlow`	Documented §5.1 login orchestration (UI-free)

Quick flow

// Pre-auth risk check
final risk = await auth.client.collectSignals(signals);

// Passkey login (public ceremony)
final options = await auth.client.passkeyAuthOptions();
final result = await passkeys.authenticate(options.options);
final tokens = await auth.client.passkeyAuthVerify(
  sessionId: options.sessionId,
  response: result.responseJson,
);
await auth.sessionStore.save(tokens);

// Record the audit event (authenticated)
await auth.client.verifyAuth(
  sessionId: auth.currentSessionId,
  deviceFp: auth.deviceFingerprint ?? '',
  authMethod: 'passkey',
  authProvider: 'webauthn',
);

Testability

AuthService.initialize accepts injectable SignalCollector, FlutterSecureStorage and http.Client, so unit tests run on a plain host without platform channels. See test/.

Configuration

Set your gateway base URL, API key and OIDC client ids in AuthEnvironments or pass an AmaniAuthConfig directly. The production apiKey placeholder must be replaced at runtime.

Android: declare the passkey RP origins in your asset links file. iOS: enable the Associated Domains capability (webcredentials:amaniquery.co.ke) and add Sign in with Apple to your entitlements.