Skip to content

Latest commit

 

History

History
118 lines (100 loc) · 7.6 KB

VAULT.md

File metadata and controls

118 lines (100 loc) · 7.6 KB

Credential vault

The portable vault is vault.bin in the application configuration directory. It requires no OS keychain. Back up the encrypted file and retain the master password separately; a forgotten master password cannot be recovered. No cloud provider, account system or plaintext export is implemented. A future storage provider must handle authenticated ciphertext and preserve conflict detection, without receiving secrets or decrypted metadata.

Optional device unlock adds authenticated native key release without changing this portable format. Platform capabilities and requirements are shown in Settings → Vault; password fallback is always retained.

Open Settings → Vault, or Credential Vault in the + menu (which selects the same Settings page). To only unlock it, run "Workspace: Unlock Vault" from the command palette (Ctrl+Shift+P) or choose Unlock vault… in a sign-in prompt: a small dialog asks for the master password, and a vault that does not exist yet opens the Settings page to create it. "Workspace: Lock Vault" locks it. Create requires confirmation; unlock, explicit lock, automatic lock, credential deletion and changing the master password are supported, on the Vault page's Overview, Credentials and Security tabs. Auto-lock and the startup prompt are on its Options tab. Activity is vault operations, not arbitrary keyboard activity. Profiles/recents store opaque IDs; credential labels, bindings and secrets live inside the encrypted payload. Switching tabs, leaving the Vault page or closing Settings clears its password fields and undo history without locking the service. Lock is explicit or automatic. Refresh reloads credential labels saved by other features since the page was opened.

A password can be typed in the connection editor: for Automatic and Password the Password field keeps it in the vault of the window when the connection is saved, bound to its address, and the connection names that record. A new password goes into the record the connection names, so every server it signs in to takes it; Forget unlinks it, so the connection asks again.

A password is bound to the addresses it lists (user@host:port) and answers no other, so one password can sign in to several servers. The Credentials tab of the Vault page lists what the vault keeps by name: Add a password saves one under a name for no server yet; the pencil renames any record; under a password, each server it signs in to has a cross that detaches it; the bin deletes the record. In the connection editor, Saved passwords lists the vault's passwords: choosing one signs the connection in with it and adds its address to the password when the connection is saved. A password of one address is stored as before ("target"), so older versions still read it; one shared by several or saved for none is stored as "targets", which only this version reads (ADR 0151).

Remember is an explicit authentication choice in the window of this computer, and on by default in the window of a hub account (Keep in the account's vault after sign in). Only successful SSH authentication stores a password or private-key passphrase, bound to its target or key path. Interactive/MFA answers have no vault record type. A saved credential is used for the initial matching request; rejected credentials return to manual entry instead of being silently retried. Unlocking can supply the still-pending initial request.

An SSH key can also be a vault record: the binding is private_key with the canonical public half and the secret is the OpenSSH private key without a passphrase, protected by the vault envelope. A profile refers to it with method = "vault_key", the credential id and the public key; signing in compares that public half with the record and never reads a file. Remember does not create or overwrite key records. The Credentials tab shows the fingerprint, never the key.

The vault of a hub account

When a hub server is chosen as the account, the vault in use is that account's: the records are sealed on this device and stored on the server, and vault.bin is not read or changed until the account is stopped. It keeps the passwords and keys of the account's servers for every computer of the account; the hub's web panel saves the servers it connects there too (ADR 0150). Unlocking uses the account's password (or its vault passphrase); creating the vault, changing its password and device unlock are not available for it. See ADR 0103.

Format and persistence

The pure nocterm-vault domain owns this format and prepared state transitions. nocterm-vault-store owns OS entropy, files and the bounded worker; the app passes its VaultAccess contract into the vault feature. No vault service global is used.

Version 1 derives a 32-byte wrapping key with Argon2id (64 MiB, three passes, four lanes, fresh 16-byte salt). It wraps a random 32-byte data key with XChaCha20-Poly1305. The data key encrypts a bounded binary payload with fresh 24-byte nonces. The fixed header authenticates format, KDF/cipher identifiers, parameters and lengths; the payload also authenticates the wrapped key. OS randomness is required. Unsupported KDF parameters, malformed lengths and excessive sizes are rejected before expensive allocation. Maximum payload is 1 MiB / 1024 credentials. Password changes replace the wrapping material without changing IDs.

Writes use a private atomic temporary file, a sibling vault.bin.lock exclusive lock and a revision comparison. A competing writer must lock/unlock to reload before saving. Failed writes preserve the previous file and in-memory state. Unix vault/temporary files have mode 0600; Windows relies on the user's configuration directory ACLs. Moving ciphertext between machines preserves the envelope; keep its companion lock available while an instance is using that directory.

Security boundaries

The single bounded worker keeps KDF and disk I/O off the UI thread. Lock immediately invalidates the service epoch and queued/in-flight results. An already-running Argon2 operation cannot be interrupted; its keys and buffers are erased when that bounded operation finishes. Domain secrets and KDF buffers use secrecy/zeroize; Debug output is redacted. Only encrypted revisions are retained for comparison.

GPUI's password widget uses shared strings and undo storage. Inputs and undo history are cleared on submission/lock, but the widget cannot guarantee erasure of every previous allocation. This is not protection against a compromised running process, a debugger, OS swap or physical memory access. The application does not claim an independent cryptographic audit. Review of this implementation is separate from audit claims about the underlying RustCrypto primitives.

Tests cover wrong passwords, header/ciphertext tampering, hostile lengths/KDFs, private Unix permissions, failed/cancelled writes, concurrent writers, rotation, auto-lock and authentication/MFA boundaries. Cross-platform file ACL handling and an external security audit remain additional verification work.

The optional Linux fingerprint broker classifies invalid bindings/registrations, unavailable keys, capacity limits and native entropy failures with typed internal errors. Its D-Bus boundary retains the existing access-denied wire messages without including registration tokens, vault bindings or key material. Re-registration cancels/removes the previous matching UID/binding before obtaining new randomness; a randomness failure does not reactivate that previous registration.