PassRanger

PassRanger is an Android password manager implemented in Java with local encrypted storage, optional Firebase synchronization, and Android Autofill integration.

Repository: https://github.com/tryh4rd-26/PassRanger.git

Scope

PassRanger currently targets phone-first credential management with:

• Room-backed local vault persistence.
• AES-GCM encryption for serialized secret payloads.
• Optional cloud sync through Firebase Authentication and Cloud Firestore.
• Password quality analysis (rule-based + on-device ML wrapper).
• Android AutofillService for credential suggestions in third-party apps.

Technology Baseline

• Language: Java 17
• Android Gradle Plugin: 8.7.3
• Compile SDK: 34
• Target SDK: 34
• Min SDK: 26
• Build features: ViewBinding enabled
• Data layer: Room 2.6.1
• Cloud: Firebase Auth + Firestore (BoM 32.7.0)
• Utility libraries: Gson 2.10.1, AndroidX Biometric 1.1.0

Repository Layout

• app/: Android application module
• app/src/main/java/com/passranger: activities and feature orchestration
• app/src/main/java/com/passranger/data: Room schema and DAO access
• app/src/main/java/com/passranger/logic: cryptography, sync, strength analysis, autofill service
• app/src/main/assets/models: mobile inference configuration and weights
• app/src/main/res: layouts, drawables, XML service/config declarations
• ML_Training/: model training, export, and mobile conversion scripts

Runtime Architecture

UI and navigation

Primary entry flow starts at SplashActivity and routes to authentication and vault screens. Core screens include:

• LoginActivity and RegisterActivity for account onboarding.
• VaultActivity for list/search/render of entries.
• AddEntryActivity and ViewEntryActivity for write/read operations.
• LockScreenActivity for lock-state enforcement.
• SettingsActivity for runtime preferences.

Data model

Vault storage is defined by Room entity VaultEntity in table vault_entries.

Schema fields:

• id (int, primary key, auto-generated)
• uuid (String, sync identity key)
• title (String)
• category (String)
• nickname (String)
• encryptedBlob (String, Base64 payload)
• timestamp (long)

DAO operations include insert, update, deleteById, deleteAll, getAll, getById, getByCategory, searchByTitle, getByTitleAndTimestamp, and getByUuid.

Database config:

• Database name: passranger_db
• Room version: 2
• Migration policy: fallbackToDestructiveMigration()

Encryption path

EncryptionManager applies:

• Key derivation: PBKDF2WithHmacSHA256
• Iterations: 65536
• Derived key length: 256-bit AES
• Salt source: user email bytes
• Cipher mode: AES/GCM/NoPadding
• IV length: 12 bytes (random per encryption)
• Auth tag length: 128 bits

Encrypted payload format is Base64(IV || ciphertext+tag).

KeyManager is an in-memory singleton holder for the active master key during unlocked app sessions.

Cloud synchronization

FirebaseSyncManager syncs documents under:

• users/{uid}/vault/{entryUuid}

Sync behavior:

• uploadEntry writes full entry metadata and encryptedBlob.
• deleteEntry removes by UUID document key.
• fetchAllEntries performs timestamp-based upsert against local Room rows.

Autofill service

PassRangerAutofillService is declared with android.permission.BIND_AUTOFILL_SERVICE and configured by res/xml/autofill_service_config.xml.

Fill behavior:

• Detects username/password fields by Autofill hints and view identifiers.
• Requires authentication intent when KeyManager has no active master key.
• Builds datasets from decrypted vault entries in category Password / Login.
• Populates username and password fields when available.

Password Analysis Subsystem

Two analyzers are present:

• PasswordStrengthChecker: deterministic rule-based scoring.
• MLPasswordStrengthChecker: hybrid scoring using extracted features and MLModelWrapper.

Rule signals include:

• Length tiers
• Character class diversity
• Entropy estimate
• Common-password suppression
• Keyboard-sequence detection
• Repetition penalties
• Basic leet-pattern penalties

Additional online check:

• HIBPChecker integrates Have I Been Pwned range API using SHA-1 k-anonymity prefix queries.

Build and Verification

Prerequisites

• JDK 17
• Android SDK platform 34
• Android Studio (recommended) or command-line Gradle
• Python 3.10+ (only for ML_Training scripts)

Local configuration

Create a local Firebase config file from template and fill project values:

cp app/google-services.example.json app/google-services.json

Android commands

./gradlew :app:assembleDebug
./gradlew :app:installDebug
./gradlew :app:testDebugUnitTest
./gradlew :app:connectedDebugAndroidTest

ML Training Pipeline

ML_Training/train_password_models.py builds a classifier pipeline with:

• Handcrafted lexical features (length, ratios, entropy, sequence signals, dictionary/leet signals)
• SentenceTransformer embeddings (all-MiniLM-L6-v2)
• Candidate models: XGBoost, LightGBM, LogisticRegression
• Balanced model scoring that combines accuracy, inference time, and model size

Conversion for mobile:

• ML_Training/convert_to_mobile.py exports selected sklearn model to ONNX.
• ML_Training/extract_model_weights.py and setup_ml_integration.sh support packaging runtime artifacts.

Existing mobile runtime artifacts are tracked in app/src/main/assets/models/.

Operational Notes

• The file app/google-services.json is intentionally untracked for local environment use.
• Keep large generated datasets or embedding caches out of git history.
• The repository includes LICENSE and is distributed under MIT terms.

License

MIT License. See LICENSE.