PwdHash - A Modern, Multi-Platform Password Generation System

This repository contains a complete, multi-platform implementation of PwdHash, a deterministic password manager that generates strong, per-site passwords from a single master password. This project is a modernization of the original Stanford PwdHash concept, updated with modern, secure cryptography and a consistent, modern user interface across all platforms.

All three platforms feature:

• 🎨 Unified Design: Matching blue color scheme and lock icon across all platforms
• 🔒 Visual Security Indicators: Color-coded cards with "SECURE" badges for modern passwords
• 📱 Modern UI: Material 3 on Android, clean cards on Web and Chrome extension
• ⚡ Seamless Experience: Identical functionality with platform-appropriate interfaces

The core principle is simple: your master password is the key and is never transmitted. The website and Chrome extension only keep it in memory while generating a password. The Android app stores it locally as AES-GCM ciphertext protected by an Android Keystore key, then requires local authentication before use.

The PwdHash Ecosystem

This repository contains three distinct but fully compatible projects. Each sub-project has its own detailed README.

Platform	Description	Details
Chrome Extension	A browser extension that lets you generate passwords directly in password fields by typing @@.	Go to Chrome README
Android App	A mobile app that generates passwords on-the-go, protected by biometric authentication. It can be used standalone or as a share target.	Go to Android README
Website	A static, client-side web page for generating passwords from any browser without installation.	Go to Website README

---

How It Works: The Core Algorithm

All three platforms generate identical passwords for the same inputs, and legacy mode reproduces the original PwdHash exactly. Both claims are checked on every change: node --test tests/*.test.mjs and cd Android && ./gradlew testDebugUnitTest run the extension, the website and the app against shared vectors in tests/, whose legacy expectations are generated by running the vendored original implementation.

The algorithm itself:

1. Domain Extraction (The "Salt"): The system first extracts the unique "registrable domain" from the website you're using (e.g., google.com, bbc.co.uk). This is the main part of the website address—you can enter either just the domain like amazon.com or a full URL like https://www.amazon.com/login and PwdHash will automatically extract amazon.com. This domain becomes the unique salt for each password, ensuring mail.google.com and accounts.google.com produce the same hash.

   The two modes work this out differently, on purpose: legacy mode reproduces the original PwdHash's 2005 rule exactly, quirks included, so old passwords keep working, while modern mode uses a pinned snapshot of the Public Suffix List. See which domain PwdHash hashes with.

2. Key Derivation (The "Engine"): Your master password and the domain salt are fed into the industry-standard PBKDF2 algorithm. This function is run for 300,000 rounds using SHA-256 as its core hash function. This deliberately CPU-intensive process makes password guessing substantially more expensive. It produces a 256-bit (32-byte) derived key that is unique to you and that specific site.

3. Password Generation (The "Output"): The derived key is used as a source of deterministic randomness to build a strong, 16-character password. The algorithm guarantees that every password contains:

   • At least one uppercase letter (A-Z)
   • At least one lowercase letter (a-z)
   • At least one digit (0-9)
   • At least one special symbol (!@#$%^&*()_-+=)

4. Shuffling: Finally, the characters in the generated password are deterministically shuffled based on the derived key. This ensures the required characters don't always appear in predictable positions (e.g., at the start of the password).

---

Security & Philosophy

PwdHash is not a traditional password manager that stores your passwords in an encrypted vault. Instead, it is a deterministic password generator. Android can retain the encrypted master password for convenience, but no platform stores the generated site passwords.

• The site never sees your master password: the extension replaces each character you type with a placeholder, so a page that records its own password field learns only how long your master password is.
• You only have to remember one password: your master password.
• A breach on one site is isolated: Since every site gets a unique password, a credential leak on one site does not affect your accounts on any other site.
• Nothing to steal: There is no vault of encrypted passwords to be stolen from your device or a central server. The system only stores your (optional) configuration settings and, on Android, your encrypted master password protected by the system Keystore.

---

Design & User Experience

All three platforms share a unified design system featuring:

• Consistent Branding: Same lock-with-password icon across all platforms
• Blue Color Scheme: Primary blue (#2563EB) for trust and security
• Security Badges: "SECURE" (green) for modern PBKDF2 passwords, "OLD SITE" (orange) for legacy compatibility
• Card-Based Layouts: Clean, modern Material Design-inspired interface
• Clear Visual Hierarchy: Immediately understand which password is recommended

Development

node --test tests/*.test.mjs                            # extension and website
cd Android && ./gradlew testDebugUnitTest     # Android app
cd Chrome && ./build_zip.sh                   # package the extension

Anything that changes a generated password is a breaking change. The rules and how to change them deliberately are documented in docs/DOMAIN-RULES.md, and RELEASING.md covers cutting a release (./tools/release.sh <version>).

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests. When contributing, please ensure your changes are directed at the appropriate sub-project (Chrome, Android, or Website).

License

This project is licensed under the BSD 3-Clause License. See the LICENCE file for full details.