# PassKeeper — Password Manager Web App & Browser Extension ## Project Overview A full-featured password manager web app and browser extension modelled after LastPass. Users can store, organise, and autofill credentials securely with a zero-knowledge architecture. --- ## Tech Stack ### Development (Windows) - **Backend:** Python 3.12, Flask 3.x - **Database:** MySQL 8.x - **Frontend:** Vanilla JS (Web Crypto API) + Jinja2 templates - **Dev server:** `python run.py` ### Production (Ubuntu) - **Web server:** Nginx (reverse proxy, TLS termination) - **WSGI server:** Gunicorn - **Process manager:** systemd - **Database:** MySQL 8.x - **TLS:** Let's Encrypt / Certbot --- ## Architecture ``` Browser Extension <──────────────────────────────────────┐ Web App <──> Nginx ──> Gunicorn ──> Flask App │ │ │ MySQL DB │ │ REST API (JSON, HTTPS) ───────┘ ``` ### Project File Structure ``` passkeeper/ ├── app/ │ ├── __init__.py # App factory, blueprints, CSRF exemptions, security headers │ ├── config.py # DevelopmentConfig / ProductionConfig │ ├── models/ │ │ ├── user.py # Argon2id, TOTP encrypted, ECDH keys, recovery │ │ ├── vault_item.py # enc_data, iv, enc_name, iv_name │ │ ├── folder.py │ │ ├── token_blacklist.py # JWT revocation (jti + expires_at) │ │ ├── totp_used_code.py # TOTP replay prevention (one-time use per user) │ │ ├── shared_item.py # ECDH-encrypted cross-user shares; enc_name/iv_name │ │ ├── emergency_access.py # State machine │ │ ├── recovery_challenge.py # Server-side recovery challenge (multi-worker safe) │ │ ├── webauthn_credential.py # Passkey / WebAuthn credentials (one row per key) │ │ ├── login_attempt.py # Failed-login lockout scoped to (user, IP) │ │ └── audit_log.py │ ├── routes/ │ │ ├── auth.py # Register, login, MFA, logout, refresh, change-password, recovery │ │ ├── vault.py # CRUD + GET /export + POST /import │ │ ├── folders.py │ │ ├── sharing.py │ │ ├── emergency.py │ │ └── webauthn.py # Passkey registration, authentication, credential management │ ├── services/ │ │ └── auth_service.py # Argon2id, JWT, blacklist, @require_jwt, TOTP encrypt/decrypt, │ │ # TOTP replay helpers (is_totp_code_used / mark_totp_code_used) │ ├── static/ │ │ ├── css/app.css # Full responsive stylesheet; collapsible group styles; tag badge styles │ │ └── js/ │ │ ├── crypto.js # deriveAuthHash, deriveVaultKey, encryptItem, decryptItem, │ │ │ # encryptName, decryptName, generateSalt │ │ ├── auth.js # Login/register + TOTP MFA + VaultSession │ │ ├── recover.js │ │ ├── sharing.js # ECDH P-256; encryptName/decryptName for shared item names │ │ └── vault.js # Full vault UI — see "Key Features" below │ └── templates/vault/ │ └── index.html # Tags field, Auto-Lock setting, Import/Export view + sidebar ├── extension/ │ ├── manifest.json # MV3 (Chrome/Edge); web_accessible_resources: [] │ ├── manifest.firefox.json # MV2 (Firefox); web_accessible_resources: [] │ ├── background.js # Chrome SW: badges, pending-save "!" badge, CLEAR_SAVE_BADGE │ ├── background.firefox.js # Firefox: in-memory session shim, setTimeout idle lock │ ├── shared/ │ │ ├── crypto.js # PBKDF2+AES-GCM; encryptName/decryptName; extractable key │ │ ├── psl.js # GENERATED — vendored Public Suffix List + PkPsl.isSameSite │ │ └── browser-polyfill.js # chrome=browser alias for Firefox content scripts │ ├── popup/ │ │ ├── popup.html # Tabs: All relevant / All items / Favorites / Recents │ │ ├── popup.css # .pk-group-* collapsible styles; .pk-tag badge; .pk-flyout menu │ │ └── popup.js # Vault+folder fetch; collapsible groups; Favorites tab; │ │ # tag display; clipboard auto-clear; CSPRNG generator; │ │ # save badge clear; three-dot flyout; copy-username button │ ├── content/ │ │ └── content.js # _isLikelyUsernameField; _normaliseUrl; debounced input (150ms); │ │ # MutationObserver guard; vault_items_cs from chrome.storage.session │ ├── bridge/ │ │ └── bridge.js # SSO bridge (vault domain only) │ └── icons/ ├── migrations/versions/ │ ├── 71d7158dd3b9_add_audit_log_tables_fix_sharing_public_.py │ ├── a1b2c3d4e5f6_encrypt_totp_secret_at_rest.py │ ├── b2c3d4e5f6a7_add_account_recovery_columns.py │ ├── c3d4e5f6a7b8_encrypt_vault_item_name.py │ ├── d4e5f6a7b8c9_add_lockout_and_mfa_backup_codes.py │ ├── e5f6a7b8c9d0_add_recovery_challenges_table.py │ ├── f6a7b8c9d0e1_add_totp_used_codes_table.py # TOTP replay prevention │ ├── g7h8i9j0k1l2_encrypt_shared_item_name.py # enc_name/iv_name on shared_items │ └── h8i9j0k1l2m3_add_webauthn_credentials_table.py # Passkey / WebAuthn credentials ├── scripts/ │ ├── update_psl.py # regenerates extension/shared/psl.js │ ├── reencrypt_totp_secrets.py │ ├── backup_db.sh / backup.cron / passkeeper-logrotate │ ├── passkeeper-nginx.conf / passkeeper.service ├── tests/ # pytest suite — in-memory SQLite, no MySQL needed │ ├── conftest.py # app/client fixtures + register/login helpers │ ├── test_mfa_gate.py # enc_key_salt withheld until MFA; proof not forgeable │ ├── test_key_rotation.py # re-encryption completeness guard │ ├── test_session_revocation.py # token_epoch revocation; deleted-account 401 │ ├── test_webauthn_uv.py # user verification required on both ceremonies │ ├── test_sharing_expiry.py # expires_days fails closed │ ├── test_registration_privacy.py # register does not disclose account existence │ ├── test_emergency_visibility.py # grantor sees requests + retrievals │ ├── test_login_lockout.py # per-IP lockout; no disclosure, no DoS │ ├── test_deploy_config.py # nginx/gunicorn/systemd/extension packaging guards │ └── js/ │ ├── test_psl.js # PSL same-site matching (node, run in CI) │ └── test_field_heuristics.js # login-field detection predicates ├── gunicorn.conf.py # worker class, timeouts, preload_app=False ├── pytest.ini ├── requirements-dev.txt ├── reset_db.py ├── requirements.txt ├── wsgi.py / run.py └── CLAUDE.md ``` --- ## Database Schema (MySQL) ```sql -- Users CREATE TABLE users ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, master_hash VARCHAR(255) NOT NULL, -- Argon2id(authHash) enc_key_salt VARCHAR(64) NOT NULL, created_at / last_login DATETIME, totp_secret VARCHAR(255), -- AES-256-GCM ciphertext totp_iv VARCHAR(64), totp_enabled TINYINT(1) DEFAULT 0, mfa_backup_codes TEXT, -- JSON array of Argon2id-hashed codes sharing_public_key VARCHAR(128), sharing_private_key_enc TEXT, sharing_private_key_iv VARCHAR(64), recovery_enc_salt VARCHAR(128), recovery_iv VARCHAR(64), recovery_verifier VARCHAR(64), -- HMAC key for the recovery challenge token_epoch INT NOT NULL DEFAULT 0 -- session generation counter ); -- Vault Items CREATE TABLE vault_items ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, user_id INT UNSIGNED NOT NULL, folder_id INT UNSIGNED, item_type VARCHAR(20) NOT NULL DEFAULT 'password', name VARCHAR(255) NOT NULL, -- server label only (item type string) enc_data TEXT NOT NULL, -- AES-256-GCM ciphertext of payload + tags iv VARCHAR(64) NOT NULL, enc_name TEXT, -- AES-256-GCM ciphertext of item name (nullable) iv_name VARCHAR(64), created_at DATETIME DEFAULT NOW(), updated_at DATETIME DEFAULT NOW() ON UPDATE NOW(), FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, FOREIGN KEY (folder_id) REFERENCES folders(id) ON DELETE SET NULL ); -- Shared Items CREATE TABLE shared_items ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, item_id INT UNSIGNED NOT NULL, owner_id INT UNSIGNED NOT NULL, recipient_email VARCHAR(255) NOT NULL, recipient_id INT UNSIGNED, item_name VARCHAR(255) NOT NULL, -- non-sensitive fallback label (= item_type) item_type VARCHAR(20) NOT NULL DEFAULT 'password', enc_data TEXT NOT NULL, -- ECDH-encrypted item payload iv VARCHAR(64) NOT NULL, enc_name VARCHAR(512), -- ECDH-encrypted display name (nullable for legacy) iv_name VARCHAR(64), accepted TINYINT(1) DEFAULT 0, created_at DATETIME NOT NULL ); -- TOTP Used Codes (replay prevention) CREATE TABLE totp_used_codes ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, user_id INT UNSIGNED NOT NULL, code VARCHAR(6) NOT NULL, expires_at DATETIME NOT NULL, UNIQUE KEY uq_totp_used_user_code (user_id, code), FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ); -- Recovery Challenges (multi-worker safe) CREATE TABLE recovery_challenges ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, user_id INT UNSIGNED NOT NULL UNIQUE, nonce VARCHAR(64) NOT NULL, expected_proof VARCHAR(64) NOT NULL, expires_at DATETIME NOT NULL, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ); -- (folders, token_blacklist, emergency_access, audit_logs — standard schemas) -- WebAuthn / Passkey Credentials CREATE TABLE webauthn_credentials ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, user_id INT UNSIGNED NOT NULL, credential_id VARCHAR(512) NOT NULL UNIQUE, -- base64url authenticator credential ID public_key TEXT NOT NULL, -- COSE public key, base64url sign_count BIGINT NOT NULL DEFAULT 0, -- clone detection counter transports VARCHAR(255), -- JSON list e.g. '["internal","hybrid"]' aaguid VARCHAR(64), -- authenticator AAGUID name VARCHAR(128) NOT NULL DEFAULT 'Passkey', -- user-assigned label created_at DATETIME NOT NULL, last_used_at DATETIME, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ); ``` --- ## Migration History | Revision | Description | | ---------------- | ------------------------------------------------ | | `71d7158dd3b9` | Add audit_logs; fix sharing_public_key type | | `a1b2c3d4e5f6` | Encrypt TOTP secret at rest | | `b2c3d4e5f6a7` | Add account recovery columns | | `c3d4e5f6a7b8` | Add enc_name + iv_name to vault_items | | `d4e5f6a7b8c9` | Add lockout columns + MFA backup codes | | `e5f6a7b8c9d0` | Add recovery_challenges table | | `f6a7b8c9d0e1` | Add totp_used_codes table (TOTP replay prevent.) | | `g7h8i9j0k1l2` | Add enc_name/iv_name to shared_items | | `h8i9j0k1l2m3` | Add webauthn_credentials table (passkeys) | | `i9j0k1l2m3n4` | Add expires_at to shared_items | | `j0k1l2m3n4o5` | Add recovery_verifier (decouple recovery proof) | | `k1l2m3n4o5p6` | Add token_epoch (revoke sessions on pw change) | | `l2m3n4o5p6q7` | Add emergency vault retrieval tracking | | `m3n4o5p6q7r8` | Add login_attempts (per-IP lockout) | --- ## Security Model - **Zero-knowledge:** master password never sent to server - `authHash = PBKDF2(masterPassword, email, 100k iter)` → auth only - `vaultKey = PBKDF2(masterPassword, enc_key_salt, 600k iter)` → browser memory only - All vault data (payload + name + tags) encrypted client-side (AES-256-GCM) - **Item name:** `enc_name`/`iv_name` in `vault_items`; server `name` column = item type only - **Shared item name:** `enc_name`/`iv_name` encrypted with ECDH shared key; server `item_name` = item type only - **Tags:** `plain.tags: string[]` inside `enc_data`; server never sees them - **Login lockout:** scoped to (account, source IP) in `login_attempts`, NOT global. A global counter made it a DoS primitive — anyone knowing an address could lock the real owner out for 15 minutes, repeatedly. Every failure mode (unknown account / wrong password / locked out) returns one identical 401 with matching timing, so it discloses nothing. `users.failed_login_count` and `locked_until` remain as an aggregate audit signal only; they no longer gate authentication. - **Argon2id:** double-hashes `authHash` server-side; transparently rehashes on login if parameters are upgraded - **JWT:** HS256, 15 min access / 7 day refresh, JTI blacklisted on logout. Every token carries an `epoch` claim checked against `users.token_epoch`; changing the master password or recovering the account increments it, which revokes every outstanding access AND refresh token. Tokens minted before the claim existed decode as `epoch 0` and remain valid until the next change. - **MFA gate:** `enc_key_salt` is NOT returned by `/login` when TOTP is enabled — it is released by `/mfa/verify` once both factors are proven. Returning it early let a password-only attacker forge a recovery proof (see below). - **MFA:** TOTP secret AES-256-GCM encrypted at rest; each code is single-use (replay prevented via `totp_used_codes` table, 120s TTL) - **Passkeys / WebAuthn:** server authentication via FIDO2; ZK model preserved — WebAuthn proves identity to the server but the vault key is still derived from the master password client-side; `sign_count` updated on every assertion for clone detection - **Sharing:** ECDH P-256 zero-knowledge re-encryption; item name also encrypted with shared key - **Autofill same-site rule:** `PkPsl.isSameSite()` compares *registrable domains* using the vendored Public Suffix List — never suffix comparison. `host.endsWith("." + h)` treated `evil.github.io` and `victim.github.io` as the same site and let an item saved for a bare TLD match everything under it. Used identically by `content.js`, `popup.js`, `background.js` and `background.firefox.js`; all four fall back to exact hostname equality if `psl.js` fails to load (strict, so a failure loses matches rather than leaking credentials). The PRIVATE section of the list is required — that is where `github.io` / `vercel.app` / `herokuapp.com` live. - **Password generator:** fully CSPRNG (`_cryptoRandInt` rejection-sampling) - **Decrypted vault data:** `chrome.storage.session` only — never to disk - **Clipboard auto-clear:** 30 s after any password/username copy (web + extension) - **Breach detection:** HIBP k-anonymity — only 5-char SHA-1 prefix transmitted - **Recovery proof key:** `HMAC-SHA256(key=recovery_verifier, msg=nonce)`. `recovery_verifier` = `PBKDF2(recoveryCode, "passkeeper-recovery-verifier:" + email, 200k)`, derived client-side from the recovery code alone and used for nothing else. It must NEVER be `enc_key_salt`: that value doubles as the vault-key PBKDF2 salt and is disclosed to the client at login, so keying the proof with it allowed anyone holding the master password to pull the entire vault from the unauthenticated `/recovery/items` — bypassing MFA. Accounts whose recovery code predates the column fall back to the legacy key and are flagged via `recovery_is_legacy` on `/recovery/status`. - **Key rotation completeness:** `change_password` and `/recover` refuse (409 `incomplete_reencryption`) unless the client's `items` payload covers every vault item the user owns — a short payload would rotate `enc_key_salt` and leave the missing items permanently undecryptable. `/recover` accepts `allow_partial: true` after the user confirms the loss (otherwise one corrupt item locks them out forever); `change_password` has no such override. - **Passkeys:** both ceremonies use `UserVerificationRequirement.REQUIRED` and `require_user_verification=True`. A passkey replaces password AND TOTP, so possession of an unlocked device must not be sufficient. - **Account recovery:** challenge-response via HMAC-SHA256; `enc_key_salt` NOT returned by `/recovery/data` — client must derive it by decrypting the recovery blob (proves possession of recovery code without transmitting it); challenge rotated on each `/recovery/items` call to prevent proof replay; recovery key derived with the user's email as a per-user PBKDF2 salt — legacy fixed salt `'passkeeper-recovery'` accepted transparently for codes created before this change - **folder_id ownership:** validated server-side on all create/update/import operations — user cannot assign items to another user's folder - **Registration privacy:** `POST /api/auth/register` returns an identical 202 whether or not the address exists, and performs an equivalent Argon2id hash on both branches so timing does not reinstate the oracle. Duplicate attempts are audited under `auth.register_duplicate`. Fully closing this needs email verification so the address owner is told — until then the oracle is removed but the owner cannot be notified. - **Emergency access visibility:** `accept`, `request` and `vault_retrieved` are audited under BOTH parties' user_ids. `/api/auth/audit-log` filters by `user_id`, so an entry written only under the acting user is invisible to the other — which meant a grantee could request and retrieve a vault snapshot without anything reaching the grantor. `vault_retrieved_at` / `vault_retrieval_count` on `emergency_access` record every fetch. Retrieval is intentionally NOT blocked after the first time (the grantor may be unable to re-provision); the wait period is the gate, and the grantor can revoke. - **Audit logs:** never contain plaintext item names, shared item names, or vault data --- ## Extension Storage Architecture | Data | Storage | Reason | | -------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------- | | `access_token`, `vault_key_jwk`, `vault_items`, `vault_items_cs` | `chrome.storage.session` | Memory-only, cleared on browser close | | `refresh_token`, `enc_key_salt`, `pending_save`, `save_blocklist`, `idle_lock_seconds` | `chrome.storage.local` | Persists across restarts | | Web-app session timeout | `localStorage` (`web_idle_minutes`) | Per-browser preference | ### Critical: `vault_items_cs` is in `session`, NOT `local` Requires Chrome 111+. `content.js` `onChanged` listener watches `area === 'session'`. Do not revert — reverting persists decrypted passwords to disk. ### Pending-save badge `background.js` sets a red `"!"` badge on `SAVE_CREDENTIALS`. Cleared via `CLEAR_SAVE_BADGE` when user acts on the save prompt in the popup. --- ## Key Implementation Details ### `password_changed_at` — accurate password age tracking Stored as `plain.password_changed_at: ISO-8601 string` inside the encrypted `enc_data` blob. Server never sees it. **Written by:** - `vault.js` `handleFormSubmit` — **create**: always set to `now`. **Edit**: only updated when the password field value actually changed vs. the decrypted existing item in `_items`. Unchanged password → existing `password_changed_at` preserved. No existing timestamp + unchanged → absent (dashboard falls back to `created_at`). - `popup.js` `saveCredential` and `addItemToVault` — always set to `now` for new extension-saved credentials. - `toggleFavorite` — spreads `{ ...item.plain, tags: newTags }`, automatically preserving the timestamp. **Read by:** - `renderSecurityDashboard` — `ageRef = plain?.password_changed_at || created_at`; items with a recent `password_changed_at` are no longer falsely flagged as old even if the item itself is old. - Backwards compatible: items without `password_changed_at` fall back to `created_at`. ### Auto-lock on tab visibility change `_startWebIdleTracking()` now registers a `visibilitychange` listener in addition to the mouse/keyboard events. **Hidden:** clears the inactivity timer (user cannot be active on a hidden tab), records `_hiddenAt = Date.now()`. **Visible again:** compares elapsed hidden time against the idle timeout. - Hidden `≥ timeout` → immediate lock (same `VaultSession.clear()` + `showUnlockOverlay()` + toast as inactivity lock). - Hidden `< timeout` → clears `_hiddenAt`, resumes timer from zero. This catches screen-lock, minimize, and long tab switches. Short tab switches (< timeout) do not trigger a lock. ### Emergency access stale snapshot detection `EmergencyAccess._enc_vault_is_legacy()` — parses `enc_vault` JSON server-side (no decryption) and returns `True` if any item has a `name` key but lacks `enc_name`. Exposed as `enc_vault_is_legacy` in `to_dict()`. `renderEmergencyGrants()` — `ready` grants now show three states: - `enc_vault_is_legacy: true` → amber `⚠ Outdated snapshot` badge + **Re-provision** button - `enc_vault_is_legacy: false` → secondary **Update Recovery Data** button - `accepted` (no snapshot yet) → primary **Provide Recovery Data** button After re-provisioning, `enc_vault_is_legacy` returns `false` and the warning disappears. ### Extension health badge `_runPopupHealthCheck()` in `popup.js` — fires after every `fetchAndDecryptVault()`. Computes weak/reused synchronously, sends a preliminary `HEALTH_UPDATE` to the background SW, then runs HIBP in parallel (`_popupCheckHibp`). Sends a final `HEALTH_UPDATE` with breach count. `background.js` / `background.firefox.js`: - `HEALTH_UPDATE` handler: stores `{ breached, weak, reused }` in `chrome.storage.local` as `health_status`, calls `applyHealthBadge()`. - `applyHealthBadge()`: on tabs with no match-count badge, shows red `⚠` (breach) or amber `⚠` (weak/reused). Never overwrites the blue match-count badge or the pending-save `!` badge. - `CLEAR_SAVE_BADGE`: after clearing `!`, immediately re-applies health badge. - Idle lock: removes `health_status` from local storage. **Badge priority:** pending-save `!` (red) > match count (blue) > health `⚠` (red/amber). ### Vault health notifications (background checks) `runBackgroundHealthCheck()` fires after every `loadVault()` call — async, non-blocking. **Flow:** 1. Computes weak + reused counts synchronously from `_items` → updates sidebar badge instantly 2. Runs HIBP k-anonymity checks in parallel (`checkHibp`) → updates badge + banner when done **Module state:** - `_healthCache` — `{ weak, reused, breached, breachedItems, hibpResults }` — set after first run - `_hibpRunning` — boolean guard prevents concurrent runs **`_updateHealthUI({ weak, reused, breached })`** — renders: - **Sidebar badge** (`#security-badge`) on the 🛡️ Security link: red for breaches, amber for weak/reused only, hidden when clean - **Dismissible banner** (`#health-banner`) above the vault list: summarises issues with "View report" link → Security tab; dismiss hides for the session (`banner.dataset.dismissed = "1"`); resets on next vault load **Security tab caching:** `renderSecurityDashboard` checks `_healthCache?.hibpResults` before querying HIBP — avoids double-calling the API within the same session. **Banner reset:** `banner.dataset.dismissed` is set to `"0"` on each vault reload so fresh results (e.g. after a password change) are visible again. ### WebAuthn / Passkey **Library:** `py-webauthn` (`webauthn>=2.0`). Installed via `pip install webauthn`. **Config** (`.env` / environment): ``` WEBAUTHN_RP_ID=pwkeeper.ngodanguyen.tech # effective domain, no scheme/port WEBAUTHN_RP_NAME=PassKeeper WEBAUTHN_ORIGINS=https://pwkeeper.ngodanguyen.tech # comma-separated in env ``` In development: `WEBAUTHN_RP_ID=localhost`, `WEBAUTHN_ORIGINS=http://localhost:5000`. **Flows:** *Registration* (requires active JWT — user must be logged in): ``` POST /api/webauthn/register/begin → PublicKeyCredentialCreationOptions POST /api/webauthn/register/complete → verifies attestation, stores credential ``` *Authentication* (unauthenticated — replaces password login): ``` POST /api/webauthn/authenticate/begin → PublicKeyCredentialRequestOptions POST /api/webauthn/authenticate/complete → verifies assertion → { access_token, refresh_token, enc_key_salt } ``` Client still prompts for master password after successful assertion to derive vault key. *Management* (requires JWT): ``` GET /api/webauthn/credentials → list registered passkeys PATCH /api/webauthn/credentials/ → rename a passkey DELETE /api/webauthn/credentials/ → remove a passkey ``` **Challenge storage:** challenge bytes are stored in the Flask session (signed cookie, `SECRET_KEY`). No DB row needed. Challenge is consumed (`session.pop`) on the `/complete` call. **Clone detection:** `sign_count` is read before verification and updated after. `py-webauthn` raises on a decreasing counter. **ZK preserved:** a WebAuthn assertion authenticates the user to the *server* only. The vault key `PBKDF2(masterPassword, enc_key_salt, 600k)` is never sent to or derivable by the server. After a passkey login the client must still enter the master password to unlock the vault. **Client-side (`PasskeyAuth` in `auth.js`):** - `loginWithPasskey(email)` — begin → `navigator.credentials.get()` → complete → stores tokens → redirects to `/vault` - `registerPasskey(name)` — begin → `navigator.credentials.create()` → complete - `_bufToB64url` / `_b64urlToBuf` — ArrayBuffer ↔ base64url conversion helpers - `_credentialToJson(cred)` — serialises `PublicKeyCredential` for the server **Settings UI (`vault.js` `loadPasskeys()`):** renders registered passkeys list with rename/delete; wires "Add passkey" button; hides the section if `window.PublicKeyCredential` is absent. **`auth.js` login wiring:** "Sign in with Passkey" button on `login.html` calls `PasskeyAuth.loginWithPasskey(email)`. On success, stores tokens and navigates to `/vault` — unlock overlay fires if master password field was empty. **Authenticator attachment:** `register_begin` accepts optional `attachment` in the POST body: `"platform"` (default — device biometrics) or `"cross-platform"` (roaming — YubiKey, phone QR, NFC). The settings UI exposes a ``). ### Browser history / back-button - `switchView(view, { pushState = true })` calls `history.pushState({ view }, '', '#view-name')`. - `popstate` listener in `init()` restores view. Direct hash links (`/vault#security`) work. - `Vault.switchToImportExport()` exposed on public return object for sidebar `
  • ` fallback. ### Clipboard auto-clear - Web app: `copyToClipboard()` uses `_clipboardClearTimer` setTimeout 30s → `writeText('')`. - Extension: `_copyWithAutoClear()` same pattern. Applied to password, username, and flyout copies. ### Missing 2FA warning - Security dashboard "No 2FA Saved" section: password items with URL but no `totp_uri`. - Uses existing `extractTotpSecret()` and `makeSection()`. ### Security score age penalty fix - `old` only includes items that are **also weak or reused** (`weakOrReusedIds.has(i.id)`). - Strong unique unchanged passwords no longer penalised. ### Keyboard shortcut - `manifest.json`: `commands._execute_action`, `Ctrl+Shift+L` / `Cmd+Shift+L`. - `manifest.firefox.json`: `_execute_browser_action`. - Customisable at `chrome://extensions/shortcuts`. ### Firefox compatibility | File | Purpose | | ---------------------------- | ------------------------------------------------------------------- | | `manifest.firefox.json` | MV2: `browser_action`, `background.scripts` | | `background.firefox.js` | In-memory session shim, `setTimeout` idle lock, `browserAction` API | | `shared/browser-polyfill.js` | `chrome = browser` alias for content scripts | Load in Firefox: `about:debugging` → This Firefox → Load Temporary Add-on → `manifest.firefox.json`. ### `web_accessible_resources` Both manifests declare `web_accessible_resources: []` (MV3) / `[]` (MV2). This prevents any external page from loading extension resources via `chrome-extension://` or `moz-extension://` URLs, blocking extension fingerprinting. ### `_normaliseUrl()` — bare-domain matching ```js function _normaliseUrl(raw) { if (!raw) return null; const s = raw.trim(); if (/^https?:\/\//i.test(s)) return s; if (s.startsWith("//")) return "https:" + s; return "https://" + s; } ``` In both `content.js` and `popup.js`. Prevents silent match failures for bare domains. ### `_isLikelyUsernameField()` — credential field heuristic 1. **YES:** `autocomplete="username|email|tel"` 2. **NO:** non-credential autocomplete (`name`, `organization`, `search`, etc.) 3. **YES:** `name/id/placeholder/aria-label` matches `user|email|mail|login|phone|tel|mobile|account` 4. **Then:** `_hasPasswordSibling()` must also pass 5. **Otherwise:** not decorated **`autocomplete="off"` is NOT a negative signal** and must never be added back to `NON_CRED_AC`. Routers, banks and admin panels set it on login fields precisely to discourage password managers. It previously caused step 2 to reject fields as obvious as `` before step 3 ever ran (ASUS RT-AX88U admin login). Letting it fall through is safe — the field still needs a credential keyword AND a nearby password input. ### Credential capture without a `
    ` Many login UIs never use a `` — the ASUS router admin page submits with `
    Sign In
    `, so no `submit` event is ever dispatched and the save-credentials banner never appeared. `watchSubmissions()` therefore registers three triggers, all routed through `maybeCaptureCredentials(scope)`: 1. `submit` on any form (scope = the form) 2. `click` on anything `_looksLikeSubmitControl()` accepts — `