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 is layered. Each layer has one bounded responsibility. Layers do not reach sideways into other layers. Explicit orchestrators compose them. This makes every layer independently testable and independently swappable. The supported integration mode is the sidecar: authsome run -- python agent.py spawns the agent as a subprocess of authsome with an HTTP proxy injecting credentials at request time. No auth code in the agent. The same layered architecture is also exposed as a Python library (from authsome.server.dependencies import create_auth_service) for embedding inside a larger orchestrator. The two modes share the same layers below. Sidecar-mode call graph. Identity and policy gate the vault; the auth layer refreshes when needed; the sidecar writes back, injects the Authorization header, and audits at every step. 
agent
  ↓  HTTP request via HTTP_PROXY=localhost:<port>
[ sidecar ]              proxy-mode orchestrator
  ↓
identity     →  signed principal chain (actor=agent, subject=user)
  ↓
policy       →  allow / deny
  ↓
vault        →  encrypted credential record
  ↓  if expired:
auth (low)   →  external token endpoint → fresh credential
  ↓
sidecar      →  vault.write(fresh credential)
  ↓
sidecar injects Authorization header
  ↓
external API
  ↓
audit        ←  append-only log entry at every step

​
The five layers

LayerOwnsDoes not own
IdentityAgent identity, principal chain tokenCredentials, access decisions, token expiry
PolicyAccess control, allow/deny decisionsCredentials, token refresh, encryption
VaultMinimal encrypted KV interface (get/put/delete/list)OAuth, providers, expiry, refresh, policy
AuthToken refresh, OAuth acquisition flowsPersistent storage, access decisions
AuditAppend-only event logDecisions, credentials, request flow
Identity, Policy, and Audit are part of the long-term architecture. The current alpha implementation focuses on Vault and Auth. The CLI emits audit events to ~/.authsome/audit.log today; identity and policy enforcement are planned.

​
Vault: minimal storage

The Vault is intentionally small. It exposes a generic encrypted key-value interface and nothing else. 
vault.get(key)
vault.put(key, value)
vault.delete(key)
vault.list(prefix)
Vault does not know about OAuth, providers, token expiry, refresh, policy, audit, or principal-chain semantics. It stores and retrieves credential records by key. Orchestrators decide which keys to read, whether access is allowed, whether a token must be refreshed, and what should be audited. The local backend uses encrypted SQLite under ~/.authsome/profiles/<name>/store.db. Field-level encryption uses AES-256-GCM with a 256-bit data key and a 96-bit nonce per encryption. The data key is wrapped by either a local file (~/.authsome/master.key, mode 0600) or the OS keyring. See Credential storage for the storage model and key namespace.

​
Auth: two levels

The Auth layer has two intentionally separate surfaces. Low level (auth.flows). A pure function. Receives expired credentials and refresh material. Calls the external token endpoint. Returns fresh credentials and updated expiry. No vault access. No side effects. Independently testable. High level (AuthLayer). A stateful orchestrator with a vault dependency. Reads the credential from the vault, calls the stateless refresh if expired, writes the result back, returns a usable token. This is what library users call. 
from authsome.server.dependencies import create_auth_service

auth = create_auth_service()
token = auth.get_access_token("github", connection="default")
Acquisition flows shipped today: , , + PKCE, and an API-key flow.

​
AuthService: the orchestrator

AuthService owns OAuth flows, token refresh, and the login/logout/revoke lifecycle. It receives a Vault, a ProviderRegistry, and an AppStore as dependencies. The daemon assembles one per profile; library callers build one with create_auth_service(). 
from authsome.server.dependencies import create_auth_service

auth = create_auth_service()
token = auth.get_access_token("github", connection="default")
AuthLayer is a thinner facade exposing the building blocks (vault(), registry(), identity(), app_store()) for callers that need them directly. See Python library.

​
Proxy: sidecar orchestrator

In sidecar mode, the proxy runner is the orchestrator.
  1. Starts the HTTP proxy on a random local port.
  2. Spawns the agent as a subprocess with HTTP_PROXY set to the local proxy address.
  3. Intercepts outbound HTTP requests from the agent.
  4. Looks up the matching provider by host_url, asks the AuthLayer for fresh credentials, and injects them into the Authorization header.
  5. Writes refreshed credentials back to the vault.
  6. Tears down cleanly when the agent exits.
See Proxy injection for the routing contract and known limitations.

​
Storage layout

State lives under ~/.authsome/. See Filesystem layout for the full tree and per-file reference.

​
Standards

Concernv1
Token refreshOAuth 2.0 (RFC 6749)
Browser-less OAuthDevice Authorization Grant (RFC 8628)
PKCERFC 7636
Encryption at restAES-256-GCM, 256-bit key, 96-bit nonce
Agent identity (planned)Ed25519, agent://local/<name> URIs
Principal chain (planned)Local signed JWT, RFC 8693 later
Policy (planned)Cedar