theseus/DESIGN-password-manager.md

Theseus password manager — design

Built-in password manager local to Theseus, derived from a Bitcoin Cash-style seed. The seed is the single root of trust; passwords are one purpose among many (BCH wallet, messenger, future identity uses) all held under distinct hardened derivation subtrees so a leak in one purpose can't compromise another.

Status: design + Phase 1 (local vault, settings UI, no autofill, no sync).

Threat model

In scope:

• Local process compromise reads plaintext passwords ONLY while the vault is unlocked. Locked-vault-on-disk is opaque.
• Disk exfiltration (stolen laptop, forensic image) yields only the encrypted vault. No plaintext, no seed material, no metadata about which sites the user has passwords for.
• A malicious web page CANNOT ask the password manager for anything. Autofill (phase 2) will happen via a Theseus-controlled contentScript bound to the origin; there is no window.passwords API.

Out of scope (phase 1):

• Malware running with keyboard-input capability. (No password manager survives a keylogger.)
• Physical shoulder-surfing when the vault is unlocked and shown.
• Backup / cloud sync — phase 2 (opt-in, Sia).

Explicitly rejected:

• Reusing Chromium's chrome.storage or Electron's safeStorage as the sole cryptographic layer. Both are DPAPI-backed on Windows (encrypted by the OS user's DPAPI key). Fine as a belt alongside our AES-GCM suspenders, not as a standalone.

Crypto

Root

The user provides ONE of:

• Their BCH wallet seed (BIP39 mnemonic) — unified identity, one backup
• A fresh seed generated in Phase 1 setup — isolated from any BCH funds

Seed is never persisted by the password vault. What is persisted is a per-purpose derived root, encrypted under the master password.

Hardened derivation discipline

Every purpose gets its own subtree, using a purpose byte that is distinct from BIP44's coin-type space:

BIP32-style: m / purpose' / subpurpose'
Passwords:   m / 1381' / 0'        (1381 = 0x555 = arbitrary picked; documented)
Messenger:   m / 1414' / 0'        (reserved for future)
BCH wallet:  m / 44' / 145'         (SLIP-44 coin 145 — untouched)

Hardened (') means the parent public key alone cannot derive child keys — you need the parent private key. So even if a password-purpose child key leaks, an attacker cannot walk backward to the BCH wallet subtree.

Vault key

master_key_material = PBKDF2(
  masterPassword,
  salt = 16 random bytes stored in vault header,
  iterations = 200_000,
  hash = SHA-256,
  keylen = 32
)
vault_key = AES-256-GCM key(master_key_material)

200k PBKDF2 iterations balances phone-CPU login latency (~200ms) against brute-force cost. Bumped to 600k on desktop-detected CPUs in Phase 2.

Vault encryption

vault_on_disk = {
  version: 1,
  kdf: { name: "PBKDF2", iters: 200_000, salt: <hex> },
  iv:        <12-byte hex>,
  ciphertext: <hex>,   // AES-GCM(vault_key, iv, JSON.stringify(plaintext))
  tag:       <16-byte hex, appended>,
}

plaintext = {
  purposeRoot: <32-byte hex>,     // the m/1381'/0' node — derived once at setup
  entries: [
    { id, domain, username, addedAt,
      // one of:
      literal: <ciphertext>,       // legacy pasted password (encrypted with vault_key)
      generated: { version, rules } // deterministic — re-derived from purposeRoot on demand
    },
    ...
  ]
}

Every entry carries a stable id (UUIDv4) so autofill (phase 2) can bind by id, not by domain+username (which can change).

Deterministic derivation recipe (the "Generate" button)

For a generated entry, the password is not stored — it's computed:

info  = "silentmode-passwords-v1|" + domain + "|" + username + "|v" + version
bits  = HKDF(hash=SHA-256, key=purposeRoot, salt=<zero>, info) → 32 bytes
password = mapBytesToRules(bits, rules)

rules default:

{ length: 20, upper: true, lower: true, digits: true, symbols: true }

mapBytesToRules is a template scheme: take the first 4 bytes to seed a DRBG, produce N chars from the requested character classes with guaranteed inclusion of at least one from each enabled class. Same input → same password on every device holding the seed.

Version-bumping (v2 etc.) is how a user "rotates" a deterministic password without ever losing the old one — old services rejecting a rotation can still be logged into by looking up v1.

Vault file

Location: <userData>/passwords.vault (single file).

Never written unencrypted. On save: build the new plaintext, encrypt with a fresh IV, write atomically (.tmp + rename).

The file's presence is not itself sensitive — it just says "this user has opted into the password manager". Contents are opaque.

Runtime

• Unlock state lives in the main process only. Never sent to renderers in plaintext except in response to explicit password-get(id) calls.
• Vault stays unlocked for the current session. Auto-locks on:
  • Explicit lock button
  • App quit (before the storage-clear ran)
  • N minutes of settings-page inactivity — phase 2 knob
• No BROWSER autofill in phase 1. Users copy from Settings → Passwords.

UI (phase 1)

New sidebar entry in Settings between Search and Naming: Passwords.

Two states:

Locked / not-yet-set-up:

• "Set up password vault" — one-time form:

  • Master password (with confirm)
  • Source of derivation seed: "Use my Ariadne wallet seed" (default) OR "Generate a new seed for passwords"
  • "Create vault" — writes the encrypted vault file

• "Unlock vault" (when the file exists) — master password only

Unlocked:

• List of entries: favicon + domain + username + reveal / copy / delete
• "Add new entry": domain, username, password (paste) OR "Generate" button
• "Lock now" at the top-right

IPC surface (through settings-preload)

password-status()           → { setup: bool, unlocked: bool }
password-setup(masterPw, seedSource) → { ok: true } | { err }
password-unlock(masterPw)   → { ok: true, entries: [...] } | { err: "bad password" }
password-lock()             → true
password-list()             → array of entries (metadata only)
password-get(id)            → { password: <plaintext> }  (only while unlocked)
password-add(entry)         → id
password-update(id, patch)  → true
password-remove(id)         → true
password-generate({ domain, username, version, rules }) → <plaintext string>

Renderers NEVER see the seed / purposeRoot / vault key / master password past the unlock call.

Phase 2 — autofill + Sia backup

• Autofill: contentScript watches input[type=password] on load, binds by (public-suffix-list-derived) eTLD+1 origin so evil-google.com can't fill google.com entries. Toolbar key icon + right-click "Fill password" menu.
• Sia backup: user provides a Sia S3 endpoint + credentials (or reuses the operator relay). Vault encrypted-blob is uploaded on save; restored on new device by pointing at the same endpoint with the master password.

Phase 3 — unified identity

• Same seed → Nostr messaging keys under m/1414'/0'. Compatible with all Nostr clients (secp256k1 keys, npub/nsec encoding).
• window.bcnr provider spec (Web3-style) exposing signed BCNR name operations to Silent Mode pages — decision to be made per SECURITY.md.

Explicitly not doing

• Cloud sync via anything but Sia. No opinionated third-party.
• Chromium's password autofill UI. Its ergonomics are Google-Sync-shaped and don't fit our threat model.
• Silent-Mode-only browser extension. The whole thing is built-in — no install / no separate origin / no extension permissions to grant.