Gilos Authenticator

A modern, open-source two-factor authentication (TOTP) app built with Flutter. Securely manage your 2FA codes with cloud synchronization, session management, and a polished Material 3 UI.

This is the official mobile client for the Gilos Auth Server.

Features

• TOTP Management — Add, edit, and delete TOTP tokens via QR code scanning or manual entry
• Cloud Sync — Securely synchronize your TOTPs across devices via the Gilos Auth backend
• Session Management — View and terminate active sessions from any device
• Account Management — Full profile editing including avatar, username, contacts, and security settings
• OAuth2 + PKCE — Secure authentication using the Authorization Code flow with Proof Key for Code Exchange
• Offline-First — Works without internet; changes sync automatically when connectivity returns
• Dark & Light Themes — Beautiful Material 3 design with automatic system theme detection
• Multi-Factor Auth — Support for email, phone, and TOTP-based MFA on your Gilos account

Architecture

lib/
├── main.dart                 # App entry point & routing
├── app.dart                  # App constants & configuration
├── themes.dart               # Light & dark Material 3 themes
├── spacing.dart              # Spacing constants
├── model/
│   ├── backend/
│   │   ├── authentication/   # OAuth, session, auth state
│   │   ├── request/          # HTTP request/response layer
│   │   ├── synchronization/  # Push/pull sync engine
│   │   └── user_sessions/    # Session management
│   ├── database/             # SQLite database (sqflite)
│   ├── settings/             # Preferences (theme, etc.)
│   └── totp/                 # TOTP model, generation, repository
├── pages/                    # UI screens
│   ├── auth/                 # Login page
│   ├── home/                 # Main page with TOTPs & sessions tabs
│   ├── account/              # Account/profile management
│   └── settings/             # App settings
├── widgets/                  # Reusable UI components
└── utils/                    # Utilities (result types, platform, etc.)

Key Design Decisions:

• Riverpod for state management with AsyncNotifier pattern
• Sealed classes for type-safe request/response/result handling
• SQLite (sqflite) for local TOTP & sync queue persistence
• FlutterSecureStorage for tokens and sensitive data
• Exponential backoff with jitter for sync retries

Getting Started

Prerequisites

• Flutter (SDK ^3.10.8)
• A running Gilos Auth backend instance (or use the public one)

Setup

1. Clone the repository

   git clone https://github.com/gilosorg/authenticator.git
   cd authenticator

2. Configure environment

   cp .env.example .env

   Edit .env with your backend URL and OAuth credentials. By default, the app connects to the public Gilos Auth instance:

   BACKEND_URL=https://auth.gilos.org
   OAUTH_CLIENT_ID=1
   OAUTH_REDIRECT_URI=gilos://auth
   

3. Install dependencies

   flutter pub get

4. Run the app

   flutter run

Building for Production

# Android
flutter build apk --release

# iOS
flutter build ios --release

Deep Link Configuration

The app supports two deep link schemes:

Scheme	Purpose	Example
otpauth://	Adding TOTPs via QR code	otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example
gilos://	OAuth callbacks	gilos://auth?code=...&state=...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0.

Trademark Policy

The Gilos name and logos are trademarks of CHERRY SOFTWARES LLC. Please see our Trademark Policy for guidelines on how to properly use and distribute this software without infringing on our brand.

Security

See SECURITY.md for vulnerability reporting and security design details.