Credential storage

How authsome encrypts and namespaces credentials inside a single shared key-value vault keyed by identity handle.

Authsome stores all credentials in a single encrypted key-value store at ~/.authsome/server/kv_store/. Profile names are key prefixes inside that store, not separate folders or databases. The vault speaks a minimal key-value interface; orchestrators on top of it (AuthLayer, the proxy) decide which keys to read and write.

Storage layout

~/.authsome/

audit.log

identities/

<handle>.key

<handle>.json

providers/

server/

master.key

identity_registry.json

kv_store/

The master key lives at ~/.authsome/server/master.key with mode 0600. User-registered provider files in ~/.authsome/providers/ override bundled definitions of the same name. Every credential record lives inside server/kv_store/ under a key prefix scoped to the active identity handle, which is also the profile name.

Profiles are independent credential namespaces. Records stored under one profile prefix are unreachable when a different identity handle is active. For the full directory model, including the daemon and identity files, see Filesystem layout.

Key namespace

Every record inside the shared KV store is namespaced by the profile (identity handle) and the provider:

profile:<profile>:<provider>:metadata
profile:<profile>:<provider>:state
profile:<profile>:<provider>:connection:<connection_name>
server:<provider>:client

Key	Holds
metadata	Non-secret per-profile record: known connection names, default connection, last-used connection.
state	Transient per-profile state: last refresh attempt, last refresh error.
connection:<name>	The credential record for a named connection: tokens, scopes, expiry, account info.
server:<provider>:client	OAuth client credentials (client_id, encrypted client_secret). One per provider, daemon-owned, shared across profiles.

Provider definitions are not stored in the KV store. They live on the filesystem in ~/.authsome/providers/<name>.json (user-registered, takes precedence) or as bundled JSON files inside the package.

Encryption

Sensitive fields are encrypted at rest using AES-256-GCM.

Property	Value
Algorithm	AES-256-GCM
Master key	256 bits, generated on first init
Nonce	96 bits, generated per encryption

The master key is held by one of two backends, selected by config.encryption.mode:

• local_key (default), the key is stored as base64-encoded JSON in ~/.authsome/server/master.key with mode 0600. File permissions are the only protection at rest.
• keyring, the key is stored in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) via the keyring library.

{
  "spec_version": 1,
  "encryption": {
    "mode": "local_key"
  }
}

Sensitive fields

The following fields are always encrypted at rest:

• access_token
• refresh_token
• api_key
• client_secret
• ID tokens, when stored
• Provider-issued secrets

client_id is not sensitive and is stored in plaintext.

Wire format

Each encrypted value is stored as a compact dot-separated string:

base64(nonce) , base64(ciphertext || tag)

For example, a sample stored ciphertext looks like:

8Tn9Cw7yL2pQ4Vx0.4FzM3KDGbR1X...UC7qE9wA

This is the format LocalFileCrypto.encrypt and KeyringCrypto.encrypt produce in src/authsome/vault/crypto.py.

A future portable spec will define a richer JSON envelope ({enc, alg, kid, nonce, ciphertext, tag}) as the cross-language interop target. The current Python implementation uses the compact format above; a future migration may switch to the JSON envelope when a second-language port lands.

The three states

Every provider in a profile is always in exactly one of three states. The state is derived at runtime from what is stored, it is not a persisted field.

State	Meaning
available	The provider definition exists. No credentials are stored for this profile.
configured	OAuth2 client credentials are saved for this profile. The user has not yet logged in. API-key providers skip this state.
connected	A valid connection record exists with an access token or API key.

available → configured   authsome login (collects OAuth client creds)
configured → connected   authsome login (completes auth flow)
available → connected    authsome login (api_key providers)
connected → available    authsome revoke or authsome remove

If a provider is already connected, authsome login <provider> exits with an error. Pass --force to overwrite an existing connection.

Concurrency

The daemon owns the encrypted KV store at server/kv_store/ and is the only writer. CLI commands talk to the daemon over loopback HTTP rather than touching the store directly, so writes from concurrent CLI invocations serialize through a single daemon process. Reads are safe to issue in parallel.

Connection record example

A connected GitHub OAuth2 connection on disk looks like this (with sensitive fields encrypted):

{
  "schema_version": 1,
  "provider": "github",
  "profile": "default",
  "connection_name": "default",
  "auth_type": "oauth2",
  "status": "connected",
  "scopes": ["repo", "read:user"],
  "access_token": {
    "enc": 1,
    "alg": "AES-256-GCM",
    "kid": "local",
    "nonce": "...",
    "ciphertext": "...",
    "tag": "..."
  },
  "refresh_token": { "enc": 1, "alg": "AES-256-GCM", "...": "..." },
  "token_type": "Bearer",
  "expires_at": "2026-05-01T15:40:22Z",
  "obtained_at": "2026-04-30T14:40:22Z",
  "account": { "id": "12345", "label": "octocat" },
  "metadata": {}
}

Trust boundary

Authsome assumes the local machine and user account are trusted relative to remote services. Encryption at rest protects against offline file access (a stolen disk image or an unauthorized user reading your home directory). It does not protect against a compromised running process.

For runtime headers on the wire, see Proxy injection.