secure_token_storage #

A tiny, opinionated wrapper around flutter_secure_storage for persisting OAuth-style access + refresh tokens with separate expiry timestamps in the platform's secure enclave (Android Keystore / iOS Keychain).

If you've written this code in three different apps already, this is that code — extracted, tested, and reusable.

Features #

• One TokenBundle value type holds both tokens and both expiries.
• isAccessExpired() / isRefreshExpired() helpers with injectable clock for testing.
• Atomic per-key writes with all-or-nothing read semantics — partial state returns null instead of half-decoded garbage.
• keyPrefix for multi-account or dev/staging isolation on the same device.
• Pure flutter_secure_storage under the hood: no extra native code, no extra permissions.

Install #

flutter pub add secure_token_storage

Usage #

import 'package:secure_token_storage/secure_token_storage.dart';

final storage = const SecureTokenStorage();

// After successful login:
await storage.save(
  TokenBundle(
    accessToken: response.accessToken,
    refreshToken: response.refreshToken,
    accessExpiresAt:
        DateTime.now().toUtc().add(Duration(seconds: response.expiresIn)),
    refreshExpiresAt:
        DateTime.now().toUtc().add(const Duration(days: 30)),
  ),
);

// On app start:
final tokens = await storage.read();
if (tokens == null || tokens.isRefreshExpired()) {
  // user must log in again
} else if (tokens.isAccessExpired()) {
  // call your refresh endpoint, then storage.save(...) the new bundle
} else {
  // use tokens.accessToken
}

// On logout:
await storage.clear();

Multi-account / staging isolation #

final prod = const SecureTokenStorage();
final staging = const SecureTokenStorage(keyPrefix: 'staging_');

The two stores never collide — clear() on one leaves the other intact.

API #

TokenBundle #

SecureTokenStorage #

Testing your own code #

SecureTokenStorage accepts an injected FlutterSecureStorage so you can mock it. See test/secure_token_storage_test.dart for a worked example using mocktail.

flutter test

Example app #

A small interactive demo lives in example/:

cd example
flutter run

License #

MIT — see LICENSE.