How francisrox/password-strength-checker works
1. Repository purpose
- This is a Chrome extension system for analyzing password strength in the browser and persisting credentials locally on the user’s machine.
- The architecture is intentionally offline: there is no backend service, database, or cloud sync layer.
2. Primary runtime boundaries
- The system spans three distinct runtimes:
- Chrome extension runtime in the browser
- Python native host running locally on the OS
- Local filesystem vault where passwords are stored
- The key security/architecture boundary is Chrome’s Native Messaging bridge between the extension and the Python process.
3. Browser extension subsystem
- password-checker-extension/ contains the user-facing browser components.
- manifest.json wires together the extension entry points and permissions.
- contentScript.js runs on web pages, detects password fields, and provides real-time analysis/UI feedback.
- background.js acts as the extension’s coordinator for saving events and communicating with the native host.
- popup.html, popup.js, and styles.css implement the extension popup and setup UI.
4. Password analysis logic
- utils/password_analyzer.js is the local analysis engine used by the extension.
- This is where password strength scoring, duplicate/reuse detection, and warning logic likely live.
- Keeping this logic in the extension avoids any need to send password contents to external services.
5. Form and page interaction flow
- The extension watches password inputs on arbitrary websites.
- As the user types, the content script evaluates strength in real time and surfaces a visual warning/indicator on the page.
- On form submission or password change, the extension prepares a record for local storage.
6. Native messaging bridge
- The extension does not write to disk directly; instead it sends password data to the background script, which forwards it to the native host.
- Native messaging is the central integration point that connects browser events to local file persistence.
- This boundary is important for the diagram: browser-side code and filesystem-side code are separated by a process boundary and Chrome’s messaging protocol.
7. Python native host subsystem
- native-host/host.py is the local service that receives messages from Chrome and writes/updates the vault.
- com.password_manager.host.json is the native host registration manifest used by Chrome to locate and authorize the Python host.
- host.bat and register.bat are Windows orchestration scripts for launching and registering the host.
8. Local vault and storage model
- vault/ is the persistence boundary for user data; the repo expects a local text-based password file inside it.
- The README indicates a single file vault format (passwords.txt) with timestamped blocks including website URL, username, and password.
- The design emphasizes local-only storage, duplicate prevention, and “smart updates” rather than a database schema.
9. Setup and lifecycle scripts
- INSTALL.bat automates installation and host registration, making the environment reproducible on a new machine.
- CLEAN_FOR_SHARING.bat is a privacy/ops tool that clears stored secrets before sharing the repo.
- check_all.bat, debug_native_host.bat, and the README troubleshooting guides support operational diagnostics of the browser-to-host chain.
10. Testing and manual verification
- test-login.html, test_path.py, and test_vault.py suggest lightweight validation of page detection, filesystem paths, and vault behavior.
- These tests support the repo’s main risk areas: browser injection, native messaging setup, and write access to the local vault.
11. Technology profile
- Front end: standard Chrome extension technologies, primarily JavaScript and HTML/CSS.
- Host side: Python for the local native messaging process.
- Platform tooling: Windows batch scripts are first-class citizens, so the repo is oriented toward Windows setup and execution.
12. Most important architectural diagram
- A good diagram should show:
- Web page password field
- Content script injected into the page
- Background script as the extension coordinator
- Native messaging channel to the Python host
- Python host writing to vault/passwords.txt
- The diagram should also reflect that all analysis and storage remain local, with no external server dependencies.
Main entry points: contentScript.js Content Script · host.py Host Process · manifest.json Manifest · background.js Background
Components 17
Web Page
Arbitrary websites where password fields are detected and analyzed.
- Password Field · A password input on a visited website that triggers analysis and save flows.
Chrome Extension
Browser-side runtime that analyzes password strength and coordinates saves.
- Content Script · Injected page script that watches inputs, evaluates strength, and shows feedback.
password-checker-extension/contentScript.js - Password Analyzer · Local scoring and reuse/warning logic used by the extension.
password-checker-extension/utils/password_analyzer.js - Background · Extension background process that receives events and forwards save requests to the host.
password-checker-extension/background.js - Popup UI · Popup and setup interface for the user-facing extension controls.
password-checker-extension/popup.html - Popup Logic · Script behind the popup and setup screens.
password-checker-extension/popup.js - Manifest · Declares extension entry points, permissions, and runtime wiring.
password-checker-extension/manifest.json
Native Host
Local Python process reached through Chrome Native Messaging.
- Native Bridge · The Chrome native messaging boundary between extension and local host.
- Host Process · Python native host that receives messages from Chrome and updates storage.
native-host/host.py - Host Manifest · Chrome native-host registration manifest for locating and authorizing the Python host.
native-host/com.password_manager.host.json - Host Batch · Windows wrapper for launching the native host.
native-host/host.bat - Register Batch · Windows script for registering the native host with Chrome.
native-host/register.bat
Local Vault
Filesystem boundary for persisted credentials.
- Passwords File · Local text vault storing timestamped website, username, and password entries.
vault/.gitkeep
Setup & Diagnostics
Windows scripts, troubleshooting docs, and lightweight verification helpers.
- Install Script · Automates installation and native host registration on a new machine.
INSTALL.bat - Clean Script · Removes stored secrets before sharing the repository.
CLEAN_FOR_SHARING.bat - Diagnostics · Operational guides and batch helpers for checking the extension-to-host chain.
DIAGNOSTIC.md - Vault Test · Validation helper for vault behavior and write paths.
test_vault.py
Connections 17
- Password Field → Content Script: typed input · The content script observes password fields on pages and reacts in real time.
- Content Script → Password Analyzer: score password · The injected script uses local analysis to rate strength and detect reuse.
- Content Script → Background: save event · On submission or change, the content script hands off a credential record.
- Background → Native Bridge: native message · The background script forwards credential data across the Chrome native messaging boundary.
- Native Bridge → Host Process: receive payload · The local Python host reads messages coming from the browser extension.
- Host Process → Passwords File: write update · The host appends or updates the local vault file.
- Manifest → Content Script: injects · The manifest wires the page script into supported websites.
- Manifest → Background: registers · The manifest declares the background coordinator.
- Manifest → Popup UI: opens · The manifest exposes the popup and setup UI.
- Popup UI → Popup Logic: driven by · Popup markup is controlled by its companion script.
- Host Manifest → Host Process: authorizes · Chrome uses the native-host manifest to locate and permit the Python host.
- Host Batch → Host Process: launches · Windows wrapper starts the host process locally.
- Register Batch → Host Manifest: installs · Registration script places the native host manifest for Chrome.
- Install Script → Register Batch: orchestrates · Installation automates host registration and setup steps.
- Clean Script → Passwords File: clears · Sharing cleanup removes persisted credentials from the vault.
- Diagnostics → Native Bridge: troubleshoots · Diagnostics focus on the browser-to-host integration boundary.
- Vault Test → Passwords File: verifies · The vault test checks local persistence and access behavior.