Authsome’s architecture is layered: identity, policy, vault, auth, audit. v1 ships Vault, Auth, and the proxy orchestrator. Identity, Policy, and Audit are documented in the design but not yet enforced. This page is the honest tracker for what’s coming and what isn’t. The canonical design document isDocumentation 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-design.md in the source tree.
Landed in v1
- Vault Shipped Encrypted SQLite per profile with AES-256-GCM. Local file or OS keyring backend for the master key. See Encryption at rest.
- Auth Shipped OAuth2 PKCE, device code, and DCR + PKCE flows. API-key flow with a browser bridge and
getpassfallback. Automatic refresh through the AuthLayer. - Provider registry Shipped 14 OAuth + 31 API-key bundled providers. User overrides at
~/.authsome/providers/. Custom provider registration viaauthsome register. - Proxy Shipped mitmproxy-based local HTTP proxy. Host-matched routing via
host_url. Per-provider header injection. Placeholder env vars in the child process. - Daemon Shipped FastAPI HTTP server on
127.0.0.1:7998. Browser bridges, OAuth callbacks, dashboard UI. See The local daemon. - Audit Shipped Append-only
audit.logwith structured JSON events for every significant CLI action. See Audit log format. - CLI Shipped
whoami,doctor,list,inspect,login,get,export,run,logout,revoke,remove,register,log. See CLI reference.
Coming next
Identity layer Planned
Cryptographic agent identity using Ed25519 keys plus a principal chain token that combines an agent actor identity with the user subject identity.- v1 Planned local-only. Agent URIs in the form
agent://local/<name>. User identity derived from the OS session. - Later Future real SPIFFE format (
spiffe://trust-domain/path). Multi-user via RFC 8693 Token Exchange.
Policy layer Planned
can(agent, on_behalf_of=user, operation, resource) → allow | deny evaluated before any vault access. The sidecar resolves identity first, passes it to policy as a parameter (the “layers don’t reach sideways” rule).
- v1 Planned TOML-based rules. A default-allow policy for fresh single-user installs so the layer is in place without breaking the current UX.
- Later Future Cedar for full rule evaluation. TOML rules map to Cedar policies on migration.
CLI-level profile switching Planned
--identity <handle> or equivalent identity switching on every command. Today the CLI bootstraps one registered identity with authsome init.
Per-request connection selection in the proxy Planned
The proxy currently uses each provider’s default connection. Future work: declare per-request connection via headers or path-matching, so a single agent can talk to two connections of the same provider in one run.Master key rotation Future
Re-encrypt every record under a new master key without losing state. The wire format anticipates this (records carry akid field in the JSON envelope spec). The migration command will land when there’s a real reason to rotate.
Recently open questions
These are tracked inauthsome-design.md under “Open Questions”. They are unresolved enough to call out separately.
| Question | Status |
|---|---|
| Final vault protocol shape (sync vs async, error contract, health-check shape) | Open |
| Multi-user token derivation (OS session works only for single-user local) | Open |
| Cedar migration from TOML rules | Open |
| Policy identity bootstrap (sidecar resolves, policy receives as parameter) | Candidate answer, not confirmed |
| Canonical credential address model across vault backends | KV form documented; full model open |
Deliberately out of scope
These are intentional product decisions, not gaps.- A SaaS secrets manager. Authsome is local-first and self-hosted by design. There is no “Authsome Cloud”.
- A network-level identity system. Authsome complements SPIFFE/SPIRE at the credential layer rather than replacing them.
- Rotate-on-use secret stores. Credentials are refreshed by the auth layer, not rotated on every use.
- Enterprise identity platform replacement. Federation and broad enterprise IDP integration is a downstream concern, not the v1 focus.
Hosted deployment
Hosted mode exists in v1 for internal-only deployments. It is not ready for internet-facing or multi-tenant use. Before hosted authsome should be treated as production for external traffic, the following must land:- Real per-user authentication inside the daemon.
- Tenant separation between users sharing the daemon.
- Persistent browser-session storage (today’s sessions are in-memory).
- A built-in admin secret or bearer token gate on the daemon.
- CSRF protection and session hardening on browser forms.
How to influence the roadmap
- File an issue. github.com/agentrhq/authsome/issues.
- Open a PR. The README and
CONTRIBUTING.mdcover the contribution process. The bundled provider list is the most common contribution target; see Custom providers for the schema and Bundled providers for the upstream submission path. - Security issues. Responsible disclosure.
What’s next
Architecture
The layered model and what each layer owns.
Threat model
Current trust assumptions and known limits.
Compared to alternatives
Authsome vs hardcoded env tokens, SaaS secrets managers, and DIY.
Changelog
Recent releases.