The vault is a single file encrypted with GnuPG public-key encryption. The recipient key is selected at filecard init time and its fingerprint is stored in ~/.config/filecard/config.json.

Encryption and decryption are performed by the system gpg binary. filecard does not implement cryptography. It passes the vault file to gpg and receives the result. The GnuPG agent handles passphrase prompting and caching.

On every write operation the vault is encrypted atomically: the new ciphertext is written to a temporary .tmp file, then renamed over the existing vault. The rename is atomic on POSIX filesystems when source and destination are on the same filesystem. A failed write does not corrupt the existing vault.

When filecard opens the vault, it decrypts the ciphertext directly into a Python dictionary in process memory. No plaintext file is created. The decrypted data exists only in memory for the duration of the session, and is released when the process exits.

The GnuPG agent caches the passphrase after the first successful decryption. Subsequent operations within the cache window do not prompt again. The default cache window is 10 minutes of inactivity, with an absolute maximum of 2 hours.

To change the cache window, add these lines to ~/.gnupg/gpg-agent.conf:

default-cache-ttl 1800
max-cache-ttl 3600

Apply without rebooting:

gpgconf --reload gpg-agent

To clear the cache immediately:

gpgconf --kill gpg-agent

The agent restarts automatically on the next gpg call.

On every clean exit, filecard compresses the encrypted vault with gzip and writes the result to ~/.local/share/filecard/backups/. The backup file contains only encrypted data. The ten most recent backups are kept; older files are deleted automatically.

Backup files are not encrypted separately — they are compressed copies of the already-encrypted vault file. Access to a backup file alone is not sufficient to read the vault without the GnuPG private key.

To restore from a backup:

gunzip ~/.local/share/filecard/backups/vault-20260503-120000.gpg.gz \
       -c > ~/.local/share/filecard/vault.gpg

The filecard edit --raw command opens a card for editing as a JSON file in $EDITOR. It writes a temporary plaintext file to /tmp for the duration of the edit session. The file is overwritten with random bytes and deleted when the editor exits, whether or not the edit was saved.

On OpenBSD, /tmp is typically backed by MFS (memory file system) and the plaintext file does not reach physical storage.

On Linux, /tmp may be disk-backed depending on the distribution. To ensure it is memory-backed, mount it as tmpfs:

# in /etc/fstab
tmpfs  /tmp  tmpfs  defaults  0  0

Verify:

df /tmp

The filesystem type should be tmpfs.

filecard nuke overwrites the vault file with random bytes in three passes, then deletes the file. It also removes the configuration file.

Backup files in ~/.local/share/filecard/backups/ are not removed by nuke. Delete them manually:

rm -rf ~/.local/share/filecard/backups/

On SSDs and other flash-based storage with wear leveling, the filesystem write may not overwrite the same physical cells as the original data. The drive controller may redirect writes to spare cells to distribute wear. In this case, the original ciphertext may remain in unallocated cells and could be recovered with specialised hardware.

The overwrite is effective on traditional magnetic hard drives where the filesystem controls physical write locations.

For reliable erasure regardless of storage type, use full-disk encryption. The vault ciphertext then sits inside another layer of encryption, and the outer key can be discarded cleanly.

On Linux, use LUKS:

cryptsetup luksFormat /dev/sdX

On OpenBSD, use softraid CRYPTO:

bioctl -c C -l /dev/sdXa softraid0

filecard uses always_trust=True when calling gpg --encrypt. This instructs GnuPG to encrypt to the specified fingerprint without requiring that the key be marked as trusted in the web of trust. For a personal tool with a single known recipient key — your own — this is correct. It avoids "key not certified" errors that would appear if your key lacks a full web-of-trust path to itself.

Do not change this setting if you modify filecard to encrypt to a third-party key without verifying it.