Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authsome encrypts every sensitive credential field in the vault before writing it to disk. The encryption is symmetric, the algorithm is AES-256-GCM, and the master key lives outside the vault file.

​
Parameters

AlgorithmAES-256-GCM
Master key256 bits, generated on first init from os.urandom
Nonce96 bits, generated per encryption
Tag128 bits (GCM authentication tag)
Authenticated dataNone in v1
The choice of follows the recommendation and is the same primitive used by TLS 1.3 and most modern at-rest stores. GCM provides confidentiality and integrity in one pass.

​
What gets encrypted

Every field marked Sensitive on a ConnectionRecord is encrypted before write:
  • access_token
  • refresh_token
  • api_key
  • client_secret
  • id_token (when stored)
  • Any provider-issued secret bound to the connection
client_id, scopes, expiry timestamps, and account metadata are stored plaintext. They are not sensitive on their own and need to be queryable.

​
Wire format

Each encrypted value is stored as a compact dot-separated string: 
base64(nonce) . base64(ciphertext || tag)
A sample record looks like: 
8Tn9Cw7yL2pQ4Vx0.4FzM3KDGbR1X...UC7qE9wA
This is produced by LocalFileCrypto.encrypt and KeyringCrypto.encrypt in src/authsome/vault/crypto.py.
The portable spec (docs/specs/authsome-v1.md §11.4) defines a richer JSON envelope ({enc, alg, kid, nonce, ciphertext, tag}) as the cross-language interop target. The Python implementation uses the compact format above; a future release may migrate to the JSON envelope when a second-language port lands.

​
Master key backends

The 256-bit master key is held by one of two backends, selected by config.encryption.mode in ~/.authsome/config.json.

​
local_key (default)

The master key is stored as base64-encoded JSON in ~/.authsome/master.key with mode 0600. Filesystem permissions are the only protection at rest. 
{ "encryption": { "mode": "local_key" } }
Use when. Single-user laptop, CI runners with isolated file systems, environments where the OS keyring is unavailable. Trade-offs.
Works without a graphical sessionYes
Survives rebootsYes
Sharable across usersNo (file mode 0600)
Recovery if lostNone. Without master.key, encrypted records cannot be decrypted.

​
keyring

The master key is stored in the OS keychain via the keyring library. Implementations:
  • macOS: Keychain Access
  • Linux: GNOME Keyring, KWallet, or libsecret
  • Windows: Credential Manager
{ "encryption": { "mode": "keyring" } }
Use when. Desktop machines where the OS keychain is unlocked at login. Trade-offs.
Stronger than file mode 0600Yes (OS-level access control)
Works headlessSometimes (Linux without a graphical session often fails)
Sharable across usersNo
Recovery if lostSame as local_key. Lost key, lost records.
uvx authsome doctor verifies the configured backend is reachable.

​
Switching backends

To move from local_key to keyring, you need to read the current key, migrate it into the keyring, and update the config. This is not yet a built-in command. The migration story is tracked on the roadmap. In the meantime, the safest path is:
  1. Note your active connections (uvx authsome list).
  2. uvx authsome revoke <provider> for each connection that supports revocation.
  3. rm -rf ~/.authsome/ (this destroys every stored credential).
  4. Edit a fresh ~/.authsome/config.json with the desired encryption.mode.
  5. Re-run uvx authsome login <provider> for each connection.

​
What encryption does not do

Encryption protects against offline disk access. It does not protect against:
  • A running process with access to the master key. Once the daemon decrypts a record, the plaintext lives in memory for the duration of the request.
  • Memory inspection via ptrace or kernel-level introspection.
  • A backup tool that copies master.key and store.db together. If both files are in the same backup, the encryption is moot.
The full trust model is in Threat model.

​
Key rotation

Key rotation (replacing the master key without losing records) is not implemented in v1. The vault interface anticipates it: records carry a kid field in the JSON envelope spec, and the Sensitive annotation makes re-encryption straightforward. The migration command will land when a real reason to rotate exists. In the meantime, rotation means rotating the records themselves: revoke and re-login on each provider.

​
What’s next

Threat model

What authsome protects against and what it doesn’t.

Credential storage

Storage layout, key namespace, and the three states.