PassForge

A lightweight, self-hosted password analysis and secure passphrase generation application. Password analysis, SHA-1 hashing, HIBP suffix matching, and passphrase generation occur locally in the browser.

Features

• Local Password Strength Evaluation: Runs the vendored zxcvbn 4.4.2 library inside the browser.
• Privacy-Preserving Breach Detection: Hashes the password in the browser and sends only the first 5 SHA-1 characters to the PassForge HIBP proxy. The complete hash and plaintext password never reach the PassForge server or HIBP.
• Estimated Guess Entropy: Derives an estimated bit value from zxcvbn's password-guess estimate rather than assuming randomly selected characters.
• Local Secure Passphrase Generator: Uses the browser's cryptographically secure random-number generator with verified EFF Large and Short Wordlists.
• Batch Generation: Generates up to 10 passphrases without transmitting the generated values to the server.
• Progressive Web App Support: Installable on supported mobile and desktop browsers.
• Dark Mode & System Theme Sync: Supports automatic and manually selected themes.

Privacy Architecture

PassForge does not submit plaintext passwords, complete password hashes, or generated passphrases to its Flask server.

For a breach check:

1. The browser calculates the password's SHA-1 hash locally.
2. The browser sends only the first 5 hash characters to PassForge.
3. PassForge requests the corresponding padded HIBP k-Anonymity range.
4. The browser compares the remaining 35 hash characters locally.

Passphrase generation also occurs entirely in the browser. The server supplies only wordlists that passed bundled SHA-256 and entry-count verification.

Use only a PassForge instance you trust. HTTPS is recommended whenever traffic crosses an untrusted network because the browser application itself must be delivered without tampering.

Installation

Unraid (Community Applications)

PassForge is available through Unraid Community Applications. Search for PassForge in the Unraid Apps tab to install it.

Environment Variables

Redis Connection Resolution Logic

The application establishes its cache and rate-limiting store using a tiered fallback strategy:

1. Explicit URL (REDIS_URL): Checked first. If present and non-empty, the app connects directly via this URI.
2. Host & Port Fallback (REDIS_HOST / REDIS_PORT): If REDIS_URL is an empty string ("") or unset, the app builds a connection string formatted as redis://:[PASSWORD]@[HOST]:[PORT]/[DB].
3. In-Memory Mode (memory://): If no Redis URL or host is configured, PassForge uses in-memory rate-limit storage. If Redis is explicitly configured but unavailable, PassForge does not automatically fall back to in-memory storage.

In-memory rate-limit counters are local to each Gunicorn worker. Configure Redis when limits must be shared across workers or application instances.

Reverse Proxy Client Addresses

PassForge uses the direct network peer for rate limiting by default and ignores X-Forwarded-For, Forwarded, and X-Real-IP. When PassForge is reachable only through a known reverse-proxy chain, set TRUSTED_PROXY_HOPS to the exact number of trusted proxies (maximum 10). PassForge then selects the client IP at that right-hand boundary from X-Forwarded-For; entries farther to the left do not affect the limiter key.

Do not enable proxy trust if clients can connect directly to PassForge. The reverse proxy must append each peer address to X-Forwarded-For, and network controls must prevent clients from bypassing the configured trusted proxies. Invalid TRUSTED_PROXY_HOPS values prevent the application from starting.

Container Runtime Hardening

The image runs as the established non-root UID/GID 99:100. Application code, templates, static assets, wordlists, and configuration under /app are owned by root and are not writable by that runtime identity. PassForge has no persistent application-data directory. Its only runtime-writable requirement is temporary space under /tmp, which is also used as its home and Python temporary directory.

Docker and Unraid runtime settings control filesystem and kernel restrictions; an image cannot enforce them on its own. When the surrounding deployment supports these options, run PassForge with:

--read-only
--tmpfs /tmp:rw,noexec,nosuid,nodev,size=16m,mode=1777
--cap-drop=ALL
--security-opt=no-new-privileges:true

These settings leave the image root filesystem read-only, provide only an ephemeral writable /tmp, drop all Linux capabilities, and prevent gaining new privileges. Do not add a writable mount over /app; doing so would make served application code or assets mutable by the container. Redis remains an external, optional service and does not require a container filesystem mount.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.