Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.mbajaj.me/llms.txt

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

Authsome stores all credentials in a per-profile encrypted SQLite vault under ~/.authsome/. 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/
  config.json
  master.key                       # mode 0600
  audit.log
  providers/
    <name>.json                    # user-registered providers (override bundled)
  profiles/
    default/
      store.db                     # SQLite vault
      lock                         # advisory write lock
Profiles are independent credential namespaces. Connections in default are invisible to work and vice versa.

​
Key namespace

Inside a profile’s store.db, keys follow this shape: 
profile:<profile>:<provider>:metadata
profile:<profile>:<provider>:state
profile:<profile>:<provider>:client
profile:<profile>:<provider>:connection:<connection_name>
KeyHolds
metadataNon-secret per-profile record: known connection names, default connection, last-used connection.
stateTransient per-profile state: last refresh attempt, last refresh error.
clientOAuth client credentials (client_id, encrypted client_secret). One per provider per profile.
connection:<name>The credential record for a named connection: tokens, scopes, expiry, account info.
Provider definitions are not stored in the vault. 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.
PropertyValue
AlgorithmAES-256-GCM
Master key256 bits, generated on first init
Nonce96 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/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,
  "default_profile": "default",
  "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.
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 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.
StateMeaning
availableThe provider definition exists. No credentials are stored for this profile.
configuredOAuth2 client credentials are saved for this profile. The user has not yet logged in. API-key providers skip this state.
connectedA 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.

​
Locking

Writes acquire an advisory fcntl.flock on the per-profile lock file. Multiple authsome processes can read concurrently but serialize writes within the same profile. Locks across profiles are independent.

​
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": "manojbajaj95" },
  "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.