Build 1Password

The build, in order

1. 1

   A vault with the right parameters

   hideshow

   A KDBX 4 vault exists, uses Argon2id, and you have proved it does rather than assumed it.

   1. 1.1Install KeePassXC and confirm the command line is present

      The command line tool ships with the desktop application on macOS and Windows and is often a separate package on Linux. Confirm it before building anything on top of it.

      terminalcopy

      keepassxc-cli --version

   2. 1.2Create the vault with explicit KDF settings

      Create the database, then set the key derivation function and parameters rather than accepting whatever the version default is. Higher memory costs you a second on unlock and costs an attacker far more.

      Files vault.kdbx

      terminalcopy

      keepassxc-cli db-create vault.kdbx --set-password
      keepassxc-cli db-info vault.kdbx

   3. 1.3Write the verification script

      A short script that runs db-info and asserts the format is KDBX 4 and the KDF is Argon2id, exiting non-zero otherwise. Run it in your test suite so a future migration cannot quietly downgrade you.

      Files scripts/verify_vault.py

   done when · tick each as it passes

   • The verification script reports KDBX 4 and Argon2id and exits zero
   • The same script exits non-zero when pointed at a deliberately created KDBX 3.1 vault
   • A wrong password is rejected without disclosing entry count or structure
   • The chosen memory parameter makes unlock take a noticeable but tolerable moment

   watch out

   • A vault created by an old tool may still be KDBX 3.1 with AES-KDF, which is much cheaper to attack, and nothing in the interface shouts about it. Check the format explicitly rather than trusting the default of whatever created the file.

   next phase
2. 2

   Entries and instant search

   hideshow

   Finding and copying a credential is faster than opening a browser, and the search index never holds a secret.

   1. 2.1Wrap the command line rather than the file

      One module that shells out for show, add, edit and rm, passing the password on stdin and never as an argument, because arguments are visible in the process list.

      Files vault.py

   2. 2.2Build the secret-free index on unlock

      Enumerate entries and write index.json with title, username, url and tags. Add a test that asserts no field of a seeded entry's password appears anywhere in the file.

      Files index.pytests/test_index.py

   3. 2.3Copy with a clipboard timeout

      Copy the secret, then clear the clipboard after a set number of seconds, but only if the clipboard still holds what you put there. Clearing unconditionally destroys whatever the user copied in between.

      Files clip.py

   done when · tick each as it passes

   • Search across a thousand seeded entries returns results without a visible pause
   • A known password from a seeded entry cannot be found anywhere in index.json
   • The clipboard is cleared after the timeout and only if it still holds the secret
   • Passwords are never passed as command line arguments, verified by inspecting the process list during a copy

   watch out

   • Putting the password in the index to make search feel snappier turns a plaintext file into the weakest link in a chain whose whole point was strength. If you catch yourself doing it for performance, measure first: the index without secrets is already fast.

   next phase
3. 3

   Generation with honest entropy

   hideshow

   Every generated secret comes with a number saying how strong it is, and the number is right.

   1. 3.1Use the cryptographic random source

      Python's secrets module, not random. The random module is seeded predictably and is documented as unsuitable for security purposes.

      Files generate.py

   2. 3.2Ship a word list and compute passphrase entropy

      Bundle a diceware style list and record its exact length. Entropy is words multiplied by the base two logarithm of the list length.

      Files wordlist.txtgenerate.py

   3. 3.3Show the number where the secret appears

      Print bits next to every generated secret, and refuse to generate below a floor you choose, explaining why rather than silently upgrading.

      Files cli.py

   done when · tick each as it passes

   • Four words from a 7776 word list reports about 51.7 bits
   • Sixteen characters from a 94 character alphabet reports about 104.9 bits
   • Ten thousand generated passphrases contain no duplicate
   • The code imports secrets and never random for anything that becomes a credential

   watch out

   • Entropy comes from the process that generated the secret, not from the string itself. A passphrase drawn from a 7776 word list at four words is about 51.7 bits whatever the words turn out to be, and a strength meter that scores the resulting string instead will confidently disagree. Compute from the generator's own parameters.

   next phase
4. 4

   TOTP

   hideshow

   Six digit codes match what your phone shows, including across a clock that is slightly wrong.

   1. 4.1Store seeds in the TOTP field, not in notes

      KDBX has a dedicated attribute for this and KeePassXC and its browser extension both read it. Putting the seed in notes works only in your own tool.

      Files vault.py

   2. 4.2Parse otpauth URLs properly

      Extract secret, period, digits and algorithm. Default to thirty seconds and six digits only when the URL does not say otherwise.

      Files totp.py

   3. 4.3Verify against a known vector

      Use a published test seed and timestamp, assert the expected code, and keep that as a test so a refactor cannot break code generation silently.

      Files tests/test_totp.py

   done when · tick each as it passes

   • A known test seed and timestamp produce the documented expected code
   • An otpauth URL with a sixty second period changes the code every sixty seconds
   • The countdown hits zero at the moment the code rolls over
   • A seed stored in the TOTP field is also readable by KeePassXC itself

   watch out

   • Not every issuer uses thirty second periods and six digits, and the parameters ride in the otpauth URL rather than in the seed. Parse the URL and honour period, digits and algorithm, or you will produce confidently wrong codes for a minority of services and never work out why.

   next phase
5. 5

   Sync with conflict detection

   hideshow

   Two machines can edit the vault and you will be told when that happened, instead of losing one side quietly.

   1. 5.1Record hash and modification time around every write

      Hash the whole file. Store it with a timestamp in sync_state.json immediately after a successful write.

      Files sync.py

   2. 5.2Detect divergence before writing

      Re-hash the file on disk and compare to the recorded hash. A mismatch means a remote write landed and you must not overwrite it.

      Files sync.py

   3. 5.3Merge with the vault engine, never by hand

      keepassxc-cli merge understands entry history and timestamps. Your own merge would not.

      terminalcopy

      keepassxc-cli merge vault.kdbx vault-conflict.kdbx

   done when · tick each as it passes

   • A simulated concurrent edit produces a conflict copy and a warning, not a silent overwrite
   • Merging the conflict copy leaves entries from both sides present
   • A normal edit on one machine produces no conflict copy
   • sync_state.json never contains anything derived from a password

   watch out

   • File sync services resolve simultaneous edits by picking one file and, at best, leaving the other beside it with a renamed copy nobody looks at. The whole point of this phase is to notice before that happens. Hash before you write, every time, with no fast path that skips the check.