rakomi_flutter #

The official Rakomi SDK for Flutter — RFC 8252-compliant OAuth/PKCE, platform-native secure storage, biometric unlock, MFA (TOTP), offline-tolerant JWKS verification. Targets iOS, Android, and Flutter Web.

Quickstart (<15 lines) #

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],
    ),
  ),
)));

What this SDK gives you #

• EU-based operator: Rakomi is operated by CRE8EVE Sp. z o.o., incorporated in Poland. Primary infrastructure and database hosting are in the EU. Some optional, tenant-enabled integrations involve processing outside the EU; the full sub-processor list, the processing locations and the transfer safeguards relied upon are set out in the Data Processing Agreement, which is the authoritative source — this README makes no transfer determination.
• Multi-tenant by design: the tenant boundary is enforced at the JWT issuer level, with row-level-security-backed storage at the API. A single set of credentials serves many tenants; no per-tenant project is required.
• Open standards: OAuth 2.0, OIDC, PKCE S256, JWT/JWKS, RS256 — no proprietary token format, no cookies, no session affinity.
• Documented security posture: coordinated vulnerability disclosure via security@rakomi.com (see SECURITY.md), and vulnerability records kept under 10-year retention.

OIDC vs OAuth 2.0 in Rakomi #

The SDK consumes OAuth 2.0 access tokens (RS256-signed JWTs). id_token handling for full OIDC compliance is planned and does not ship today.

Tenant scope vs OAuth scopes #

Tenant binding is encoded in the JWT claim tenant_id, NOT in OAuth scope strings. Each tenant has its own publishable key (which derives the storage namespace and the issuer URL).

Why not flutter_appauth underneath? #

flutter_appauth is iOS+Android only and has no Web target. We use flutter_web_auth_2 directly because it provides a single API across iOS / Android / Web, and the system browser semantics are identical across the three platforms (RFC 8252 / popup postMessage).

OAuth 2.1 readiness #

• PKCE-mandatory (S256). No plain fallback.
• No implicit flow. No password-grant for new clients.
• Aligned with draft-ietf-oauth-v2-1.

Privacy considerations (RFC 6973) #

• The SDK does NOT log tokens.
• The SDK does NOT collect device telemetry by default.
• The SDK does NOT issue cookies.

Token lifetimes #

• Access token: ~15 min (server-side configurable, see API canonical docs).
• Refresh token: ~7 d (server-side configurable).
• Single in-flight refresh dedup via Dart Completer — never two concurrent refreshes for the same provider tree.

No cookies / no CSRF in SDK #

Bearer tokens only. The SDK adds Authorization: Bearer <access> headers and nothing else. No cookies, no CSRF defense needed at the SDK layer.

Custom URL scheme caveats #

On Android, custom URL schemes are first-come-first-serve at the OS level — a malicious sibling app can register the same scheme and intercept the OAuth callback. The recommended remediation is Universal Links (Android App Links). This SDK currently supports custom schemes only; Universal Links support is planned.

Provisioning & code-signing #

• iOS: register your scheme in Info.plist > CFBundleURLTypes. For Universal Links, see Apple Associated Domains.
• Android: register your scheme in AndroidManifest.xml > intent-filter. For Android App Links, see Android App Links.

iOS Info.plist snippet #

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>your.app.bundle.id</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <!-- Replace `myapp` with the scheme you passed to RakomiProvider(redirectUri:). -->
      <string>myapp</string>
    </array>
  </dict>
</array>

Android AndroidManifest.xml snippet #

<activity android:name=".MainActivity" android:launchMode="singleTask">
  <intent-filter android:autoVerify="false">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Replace `myapp` with the scheme you passed to RakomiProvider(redirectUri:). -->
    <data android:scheme="myapp" android:host="callback" />
  </intent-filter>
</activity>

Publishable-key acquisition #

Sign in to your tenant dashboard at https://dashboard.rakomi.com → API keys panel → Create publishable key. Copy the pk_live_… (or pk_test_…) prefix into RakomiProvider(publishableKey:).

Threat model #

The SDK defends against the OWASP MASVS v2 V2 (storage) / V3 (cryptography) / V4 (authentication) classes by construction. Residual risks NOT mitigated by the SDK:

• Rooted/jailbroken device: Keychain/Keystore extraction is possible. Mitigation is consumer-app responsibility (e.g. freerasp / RootBeer).
• Device PIN bypass: on a stolen device with no passcode set, stored credentials remain readable once the device has been unlocked at least once. The SDK surfaces BiometricUnavailable(reason: 'no_device_passcode') so the application can react. Credentials are stored device-only and are therefore NOT carried into an iCloud or iTunes backup.
• Screen-overlay attack (Android clickjacking): consumer apps SHOULD set WindowManager.LayoutParams.FLAG_SECURE on the auth Activity.
• Keylogger: outside the SDK's threat model — biometric paths bypass password input on supported platforms.
• App-switcher screenshot leak: consumer-app responsibility — set FLAG_SECURE (Android) / UIWindow.privacyOverlay (iOS) when authenticated state is visible.
• MITM on managed networks: optional RakomiProvider(certificateFingerprints:) pins server certificates on mobile (Web ignored — browser TLS).

Transport security #

RakomiProvider(apiBaseUrl:) requires https://. Exactly one exception exists, for local development, and it is enforced in the constructor: an http:// URL is accepted only when the host is exactly localhost, or is written as four dot-separated numbers beginning 127. or 10.. Any other http:// URL is rejected with an ArgumentError before the provider is built.

⚠ 10.0.0.0/8 is a private LAN range, not loopback — traffic to it leaves the device. Treat that exception as a development convenience only, and never point a production build at a plaintext http:// address.

Optional certificate pinning (RakomiProvider(certificateFingerprints:)) applies to https:// requests to non-loopback hosts on iOS and Android; on Web it is ignored, because transport security is the browser's.

Web security considerations #

flutter_secure_storage v10 on Flutter Web stores the refresh token in localStorage with AES-GCM encryption (key derived from a per-origin random secret in IndexedDB). This is NOT OS-level secure storage — a successful XSS in your app reads the token. Mitigations:

• Content Security Policy with script-src 'self' (no inline JS).
• Trusted Types if your bundler emits sinks.
• Treat Web differently: shorter token lifetimes, more aggressive refresh.

Compliance posture #

• CRA (Reg. 2024/2847): coordinated vulnerability disclosure via security@rakomi.com. The disclosure process, the timelines we commit to and the record-keeping are described in SECURITY.md.
• GDPR Art. 17 (right to erasure): signOut() clears local + this tenant's JWKS cache; fresh-install detection PURGES Keychain residue.
• GDPR Art. 25 (privacy by design): non-blocking mount, no telemetry, no token logging, secure-storage namespacing.
• GDPR Art. 32 (technical measures): Keychain/EncryptedSharedPreferences encryption-at-rest; RS256; CSPRNG; HTTPS required for the API base URL, with a development-only http:// exception (see "Transport security" below); redacted error strings.
• NIS2 (Reg. 2022/2555): coordinated vulnerability disclosure — see SECURITY.md.
• PSD2 / PSD3: the SDK can carry a TOTP factor (possession) and a biometric factor (inherence), when the API operator configures factor binding. Whether a given deployment satisfies strong customer authentication is a determination for the operator and their supervisor — the SDK does not make it and certifies nothing.
• NIST SP 800-63B: MAY meet AAL2 when the API operator configures factor binding. The SDK does not certify AAL2.
• EUDI Wallet (Reg. 2024/1183): a SocialProvider.eudiWallet enum value is reserved as a forward-compatibility hook. No wallet integration ships today.

Audit logging #

The SDK emits 32 distinct AuthEvent types via the broadcast Stream RakomiAuth.instance.events. Consumer apps are responsible for forwarding to their audit log. The SDK does NOT auto-forward to any sink (CRA + GDPR Art. 30).

Audit-significant events (recommended forwarding for SOC 2 / ISO 27001):

• signedIn / signedOut — record userId + tenantId + ts.
• tokenReceived / refreshSucceeded — record userId + sessionId + ts.
• signInFailed — record email_hash + ip_hash + reason + ts.
• clockSkewDetected / biometricFailed / deepLinkReceived — security-relevant; forward to SIEM.

EUDI Wallet roadmap #

The EU Digital Identity Wallet mandate begins end-of-2026 (Reg. 2024/1183 implementing acts). When the bridge endpoint lands at the API, the SocialProvider.eudiWallet enum value will be wired without a major version bump. Consumer-side switch statements over SocialProvider MUST use a default: clause to allow this additive enum extension.

Stability policy #

See CHANGELOG.md § "Stability policy". TL;DR: 0.x adapter changes additive-only; breaking changes go to 0.(x+1).0 with MIGRATION.md entry.

Publisher webhooks #

verifyPublisherWebhook verifies Rakomi publisher-app webhook deliveries (Standard Webhooks HMAC-SHA256, replay defence, key-rotation tolerance). See the canonical publisher-webhook receiver contract.

License #

MIT — see LICENSE.