nest_auth_flutter 2.0.3

Flutter / Dart SDK for NestJS authentication with @ackplus/nest-auth — HTTP client, secure token storage, and automatic refresh.

nest_auth_flutter

Flutter / Dart SDK for @ackplus/nest-auth.

📚 Full documentation: ack-solutions.github.io/nest-auth

A small, dependency-light client: HTTP auth flows, secure token storage, and transparent token refresh. The core (NestAuthClient) is pure Dart; SecureTokenStorage wraps flutter_secure_storage for production apps.

Install

# pubspec.yaml
dependencies:
  nest_auth_flutter: ^2.0.0

Backend setup

Run your nest-auth backend in header token mode so tokens come back in the response body:

NestAuthModule.forRoot({
  session: { jwt: { secret: env.JWT_SECRET }, accessTokenType: 'header' },
});

Quick start

import 'package:nest_auth_flutter/nest_auth_flutter.dart';

final auth = NestAuthClient(
  baseUrl: 'https://api.example.com',
  storage: SecureTokenStorage(), // keychain/keystore-backed
);

// Sign up or log in — tokens are persisted automatically.
await auth.signup(email: '[e-mail]', password: 'secret');
// or
await auth.loginWithEmail('[e-mail]', 'secret');

if (await auth.isAuthenticated) {
  final user = await auth.getSessionUserData();
  print(user.email);
}

await auth.logout();

NestAuthClient attaches the access token to authenticated requests and, on a 401, transparently refreshes once and retries.

Reactive UI (NestAuthController)

Wrap the client in a NestAuthController (a ChangeNotifier) so widgets rebuild on login/logout:

final auth = NestAuthController(
  NestAuthClient(baseUrl: 'https://api.example.com', storage: SecureTokenStorage()),
);

await auth.restore(); // on app start

// In your root widget:
ListenableBuilder(
  listenable: auth,
  builder: (context, _) {
    if (auth.status == AuthStatus.unknown) return const SplashScreen();
    return auth.isAuthenticated ? HomeScreen(auth: auth) : LoginScreen(auth: auth);
  },
);

// A button just calls the controller; the UI updates itself:
await auth.loginWithEmail(email, password);

It exposes status, user, isAuthenticated, isBusy, lastError, plus signup, login, loginWithEmail, logout, restore, refreshUser — and works with provider, Riverpod, or plain ListenableBuilder.

API

Member	Description
NestAuthClient(baseUrl:, storage:, httpClient:)	Create a client. storage defaults to InMemoryTokenStorage.
signup({email, phone, password, tenantId, extra})	Register; persists tokens.
login({providerName, credentials, ...}) / loginWithEmail(email, password)	Log in; persists tokens.
socialLogin(provider, token, {type})	Social login with a provider token you obtained natively.
getSessionUserData()	GET /auth/me → SessionUser.
refresh()	Exchange the refresh token → TokenPair?.
logout()	Revoke server-side (best effort) + clear local tokens.
isAuthenticated / accessToken	Current auth state.

Token storage

• SecureTokenStorage — flutter_secure_storage (keychain / keystore). Recommended.
• InMemoryTokenStorage — ephemeral; good for tests.
• Implement TokenStorage to back the client with anything else.

Errors

Non-2xx responses throw NestAuthException with statusCode, message, and code (matching the backend's error envelope).

Testing

This package ships a real, no-mock test suite: it spawns a live nest-auth backend (sqljs) and drives signup → login → refresh → logout over HTTP.

flutter test

License

MIT