🔐 PassVault

Your passwords, on your phone, and nowhere else.

A fully offline password vault with a native app for iOS (SwiftUI) and Android (Kotlin / Jetpack Compose).

Built as a new home for people leaving BlackBerry Password Keeper: it imports Password Keeper's backups directly.

No account · No server · No analytics · No cloud sync

[!IMPORTANT] Open source, and not independently audited. PassVault uses established encryption (Argon2id and XChaCha20-Poly1305 via libsodium), keeps everything on your device, and has no network features. The code is public, so you can read it and judge for yourself. No professional security review has been done yet. As with any password manager you haven't audited yourself, keep a separate backup of anything important.

📖 See the security model for what it does and doesn't protect against, the feature status, and the encrypted file format.

---

📑 Contents

✨ Features · 📥 Download · 🍎 Build for iOS · 🤖 Build for Android · 🚚 Moving your passwords in · 🔢 Adding 2FA codes · 🛡️ Security checks · ✅ Project status · 📜 License

---

🧭 How it works

Everything happens on your phone. Your master password unlocks the vault, and nothing leaves the device unless you export a file yourself.

flowchart LR
    U([You]) -->|master password<br/>or fingerprint / face| A[PassVault app]
    A <-->|encrypt / decrypt| V[(Encrypted vault<br/>on this phone)]
    A -.->|only when you choose Export| F[/Backup file<br/>CSV or encrypted/]
    F -.->|Import| A
    A -. never connects .- N[Internet, cloud, servers]

The dotted "never connects" line is deliberate: PassVault has no network features, so there is nothing to sign in to and nothing to sync.

---

✨ Features

🔑 Easy, safe unlocking	Unlock with your master password or your fingerprint / face. After 10 wrong attempts, the vault on that device is erased.
🗄️ Encrypted on your device	Every record is encrypted and stored locally. Nothing is ever uploaded.
🔎 Find things fast	Search, star your favorites, and organize records into groups.
📝 Flexible records	Add several usernames, passwords and notes to one record, plus security question-and-answer pairs, in the order you want. Secrets stay hidden until you reveal them.
🔢 2FA authenticator	Built-in time-based one-time codes (TOTP), like Google Authenticator. Add an account by scanning the site's QR code with the camera, reading it from a screenshot, or typing the setup key. Codes are generated offline on your phone.
🎲 Password generator	Create strong passwords with adjustable length and character types.
📤 Backup and restore	Export as CSV or as an encrypted file, and import them back after confirming. Exporting asks for your password first. 2FA setup keys (and seed phrases) are only ever included in the encrypted file, never in CSV.
🔄 Change master password	Update it any time from settings.
📋 Careful clipboard	Copied passwords are handled with care so they don't linger.
⌨️ Autofill (Android)	Fill logins into other apps and browsers. PassVault asks for your password or fingerprint each time, suggests the logins saved for that app or site, and locks again as soon as it has filled.

The app icon is shared by both platforms. See assets/README.md for the prompt and asset details.

---

📥 Download (Android)

The quickest way to try PassVault on Android is the ready-made APK:

1. Open the Releases page of this repository.
2. Pick the latest version and download PassVault-<version>-<build>.apk from Assets.
3. Open the file on your phone and allow Install unknown apps when Android asks.

Requires Android 11 or newer.

[!NOTE] Every release tag carries its own APK. For iOS, please build the app yourself (see below).

---

🍎 Build for iOS

You'll need: full Xcode (Command Line Tools alone can't build the app or run XCTest), an iPhone or iPad on iOS 17+, and XcodeGen.

cd ios
xcodegen generate
open PassVault.xcodeproj

Then:

1. Choose your signing team in Xcode and build to a real device.
2. Swift Package Manager fetches the pinned libsodium wrapper automatically.
3. Set a device passcode before creating a vault. To use biometric unlock, first enroll Face ID or Touch ID, then turn it on in the app's settings.

---

🤖 Build for Android

You'll need: JDK 17 and Android SDK 36. Open the android/ folder in Android Studio, or use the command line:

cd android
./gradlew :app:assembleDebug :app:testDebugUnitTest

Or run scripts/build-android-debug.sh. It runs the unit tests and builds the debug APK (android/app/build/outputs/apk/debug/app-debug.apk), and needs no signing key. Add --skip-tests to skip the tests, or --install to also install it on a connected device or emulator with adb.

Point ANDROID_HOME at your SDK, or create an untracked android/local.properties containing sdk.dir=.... Test biometrics on a real phone.

No shared development key is included, and your signing key never goes on GitHub.

• Run scripts/build-android-release.sh to make a signed AAB (for Google Play) and a signed APK (for sideloading and GitHub Releases). On first use it creates your upload keystore. Results land in dist/.
• Already have installs signed with an older key? Run scripts/rotate-signing-key.sh once (it defaults to rotating from the Android debug key). Afterwards, the build script attaches the rotation lineage to the APK automatically, so existing users update in place without losing data.
• Back up both keystores and ~/.passvault-signing/lineage.bin. Losing them means you can't ship updates.
• To publish, run scripts/release-github.sh. It builds the signed APK, then (after you confirm) tags vX.Y.Z, pushes the tag and creates the GitHub Release with the APK and its checksum file. Add --draft to review the release on GitHub before it goes public. You need the GitHub CLI (gh auth login once).

flowchart LR
    A[Raise version in<br/>build.gradle.kts] --> B[Commit]
    B --> C[scripts/release-github.sh]
    C --> D[Build, test and sign<br/>on your machine]
    D --> E{Confirm?}
    E -->|yes| F[Tag and push]
    F --> G[GitHub Release<br/>APK + SHA256SUMS]

---

🚚 Moving your passwords in

Coming from BlackBerry Password Keeper? PassVault imports its backup files directly, on both iOS and Android. Password Keeper offers two export types, and they are not equal:

Export	What survives
.pkb2 (encrypted) ✅ recommended	Everything, including extra usernames, passwords and other fields
CSV	Only the basics; extra fields are dropped

flowchart TD
    A[Password Keeper app] -->|Export| B{Which format?}
    B -->|.pkb2 encrypted| C[Keeps every field<br/>recommended]
    B -->|CSV| D[Basic fields only]
    C --> E[Copy the file to your phone<br/>directly, e.g. USB or AirDrop]
    D --> E
    E --> F[PassVault: Settings, then Import]
    F --> G[Enter the export password<br/>.pkb2 only]
    G --> H[Check the record count, confirm]
    H --> I[Check your records]
    I --> J[Delete the plaintext file]

Coming from another password manager? Export from it, copy the file to your phone, and import it the same way. PassVault recognises the format from the file itself:

From	Export to use	Notes
KeePass / KeePassXC	the .kdbx database itself, or KeePass XML	Asks for the database password and, if it has one, the key file. Groups, history, expiry dates, custom fields and TOTP keys come across. Twofish databases: switch to AES or ChaCha20 first
Bitwarden	JSON (not "JSON (Encrypted)"), or CSV	Logins, cards, secure notes and identities (as notes), folders, custom fields, password history and TOTP keys
1Password	.1pux, or CSV	Logins, credit cards, notes and other items (as notes), tags as groups, password history and one-time passwords
Chrome, Edge, Firefox, Safari	the browser's password CSV
LastPass, Dashlane, Proton Pass, others	CSV with name/URL and username/password columns

Authenticator keys in these exports become 2FA entries. Attachments are not imported.

How to import

1. Transfer the file to your phone locally.
2. Unlock PassVault → Settings → Import, then pick the file.
3. For .pkb2, enter the password you chose when exporting. CSV needs no password.
4. Check the record count and choose Import or Full replacement (or Cancel).
5. Verify your records, then delete the plaintext migration file.

Import or Full replacement? Entries are matched by their ID, which never changes when you edit an entry (only deleting and recreating it gives a new one).

• Import adds entries that are new and replaces existing entries with the same ID, fields included. Entries missing from the file are kept.
• Full replacement treats the file as the golden source: entries it does not contain are deleted.
• Password Keeper and CSV files carry no PassVault IDs, so Import adds their entries as new ones.

[!TIP] Never commit real credentials. CSV and backup files are ignored by Git.

Good to know

• Your app password needs at least 12 characters, with upper- and lowercase letters, a number and a symbol. Length matters because encrypted backups can be attacked offline.
• On Android, exporting asks for your app password once (this counts as an attempt) and encrypts the backup with it.
• Encrypted backups can be imported on either platform.
• There is no password reset. If you forget your master password, nobody can recover it for you.
• Exported files are independent of local erasure: wiping the vault does not delete files you exported.
• The system file picker may show cloud providers, but PassVault itself has no cloud integration.

---

🔢 Adding 2FA codes

Open the 2FA tab and tap Add 2FA code, then either:

• Scan QR code: point the camera at the QR code the site shows when you turn on two-factor authentication.
• From image: pick a screenshot of that QR code. Handy when the setup page is open on the same phone.
• Type the setup key: the Base32 key sites show next to the QR code. Most sites use the defaults (SHA1, 6 digits, 30 seconds); change them under Advanced only if the site says so.

Check that the code shown matches what the site expects, then save. Tap a code in the list to copy it.

Coming from Google Authenticator? In Google Authenticator choose Transfer accounts → Export accounts, then scan its QR code in PassVault. All of its accounts are added at once; accounts already in your vault are skipped. If the export shows several QR codes, scan each one. Counter-based (HOTP) accounts aren't supported.

Good to know

• QR codes are read on the device. The camera is only used while you scan, and PassVault still has no internet access.
• The setup key can be revealed to check it, but it can't be copied from the app.
• Setup keys are part of the encrypted vault, so encrypted backups include them and restore them on either platform. CSV exports never do.
• Keep an encrypted backup. If you lose your phone without one, you'll need each site's recovery codes to get back in.

---

🛡️ Security checks

The portable Swift core can be tested without full Xcode:

swift run --package-path ios vault-security-checks

To check a local migration file without copying credentials into the repo or printing them:

PASSVAULT_TEST_CSV=/path/to/your_backup.csv \
  swift run --package-path ios vault-security-checks

With full Xcode you can also run swift test --package-path ios. Build tools need internet to fetch dependencies; the finished app never does.

---

✅ Project status

Verified so far

• ✔️ The Swift core compiles, and 180 standalone security and migration checks pass, including the supplied CSV and the 2FA code tests (RFC 6238 test vectors, QR link parsing, Google Authenticator exports).
• ✔️ Android unit tests pass (CSV, backups, Password Keeper import, 2FA), and the debug and release builds succeed.
• ✔️ The iOS UI source type-checks (via Mac Catalyst).

Not yet verified (release blockers, not proof that the apps pass)

• ⏳ Full iOS build in Xcode, on-device UI testing (including camera QR scanning) and biometric behavior.
• ⏳ XCTest, which was unavailable on the development Mac (no full Xcode, Android SDK or JDK at first).

---

📜 License

PassVault is licensed under the GNU General Public License v3.0 only (GPL-3.0-only). Third-party libraries keep their own licenses, and the KeePass test files in fixtures/kdbxweb are MIT-licensed by their authors (see fixtures/kdbxweb/LICENSE).

Name and icon. The PassVault name and app icon are not covered by the license. A fork must use its own name, icon and app ID, so that nobody can mistake it for an official build.

Brand logos. The logos of other services bundled with the app (brand_* images) are trademarks of their owners and are not covered by the license. They are only there to help you recognise your accounts and do not imply any endorsement.

Contributions. By submitting a contribution, you license it under GPL-3.0-only and also allow DCHA to distribute it under other terms, including in official builds on the App Store and Google Play.