Secrets

Every credential Firetower holds — a git host's token, an agent's token — is encrypted in the database. The Secrets screen shows what is held and every time it was touched, and lets you show, replace or remove one.

Showing a credential is logged as Reveal, separately from a session using it. Anything that can reach the API can read every token, so the log is the only way to notice it happening.

#How it is sealed

Ordinary envelope encryption. Each secret gets a key of its own; that key encrypts the value; a root key encrypts that key. The cipher is XChaCha20-Poly1305.

Both layers are bound to the secret's scope, name and version, so a row moved to another name or restored from before a rotation fails to open instead of quietly handing back the wrong credential.

#Where the root key lives

Not in the database. It comes from one of two places:

# 1. an environment variable — for containers, servers, anything with a key
#    manager in front of it. Nothing is written to disk.
FIRETOWER_ROOT_KEY=$(openssl rand -base64 32)
 
# 2. otherwise ~/.firetower/root.key, mode 0600, created on first run.

44 characters ending in =. Anything else stops start-up rather than being used — a key that is not a key would seal every credential under junk, and finding that out later is worse than finding it out now.

This loses work

Back the root key up separately from the database. A database backup on its own cannot be decrypted. Lose the key and every credential has to be added again.

#The read log

Reads are logged with the reason they happened, and each entry carries a fingerprint of the one before it, keyed with the root key. Editing or deleting a row directly in the database breaks the chain, and the Secrets screen says so.

#Why not the system keychain

A keychain belongs to one machine and one signed-in user. Firetower hands credentials to workers on other machines and to containers with no desktop session.

Workers are handed a secret per operation and hold it in memory only, so a machine that runs your sessions never stores your git credentials.