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.

The authsome daemon binds to 127.0.0.1:7998 and has intentionally minimal hardening in v1. This page makes the model explicit so you can decide whether your deployment shape is inside or outside the trust boundary.

​
The v1 model

The daemon assumes the local machine is trusted. Specifically:
  • Any process running as the same user can talk to the daemon.
  • The OS enforces loopback binding so only same-host traffic reaches the daemon.
  • The daemon does not authenticate its callers.
This is sufficient for a single-developer laptop. It is not sufficient for shared multi-user machines unless you accept that any user on the host can reach the daemon.

​
What the boundary protects against

ThreatOutcome
Network attackers on the LANCannot connect. Daemon binds to 127.0.0.1 only.
Internet attackersCannot connect. Same reason.
Other users’ shell sessions on the same host (Unix)Can connect, but cannot decrypt records they don’t have the master key for. Encryption is still doing work.
Tampering with an in-flight OAuth callbackLimited. The callback URL is 127.0.0.1:7998/auth/callback/oauth. Only same-host traffic can reach it.

​
What the boundary does not protect against

ThreatOutcome
A process running as your userCan call the daemon, including credential-resolution routes. Treat any code you run as having access.
A process running as rootCan read master.key directly. The daemon is not the bottleneck.
Memory inspection of the daemon processCan read decrypted credentials held in active sessions or the proxy’s request pipeline.
Replay of a browser-bridge form submissionNo CSRF token yet. Credentials submitted through the bridge could in principle be replayed by another local process within the session window.
Cross-session leak after a restartActive auth sessions are in-memory. A daemon crash mid-flow leaves orphaned state at the provider but no credential leak locally.

​
v1 limitations

The daemon ships without these and we plan to add them:
  • No bearer token between the CLI, the proxy, and the daemon. Loopback binding is the only access control.
  • No per-session CSRF tokens on browser forms. The browser bridge is opened by the CLI and closed when the flow ends. The window is small but the protection is absent.
  • No persistent session store. A restart loses any login that is mid-flight. The user re-runs the login.
  • No process-level isolation between the daemon and the proxy. Both run in the daemon’s address space. A bug in one is reachable from the other.
These are tracked in authsome-design.md under “Open Questions” and on the roadmap.

​
When the model is adequate

DeploymentAdequateWhy
Single developer laptopYesThe intended target. All trust assumptions hold.
Single developer over SSHYesThe SSH session is the trust boundary, not the daemon.
Shared workstation, single user signed inYesOther users cannot reach 127.0.0.1 from a different account on the same host without privileged operations.
Shared workstation, multiple users signed inCaveatAny signed-in user with a process on the host can connect. Their ~/.authsome/ is isolated, but the daemon is shared if there is one running. Run a per-user daemon by setting AUTHSOME_HOME.
CI runnerCaveatOK if the runner is dedicated and torn down after the job. Treat the runner as untrusted afterward.
Hosted shared daemon on a private networkCaveatApproved only behind VPN/private overlay. See Hosted deployment model.
Public hosted daemonNoThe v1 daemon does not support multi-user. Do not expose to the internet.

​
When the model is not adequate

If you need any of the following, do not run the v1 daemon in that role:
  • Per-user authentication inside the daemon.
  • Tenant isolation between users.
  • Hardened browser sessions for internet-facing forms.
  • Auditable, non-repudiable identity tied to each request.
Those capabilities are on the roadmap.

​
How to harden inside the boundary

Even within the supported model, you can reduce blast radius:
  • Use keyring mode for the master key on machines with a working OS keychain. See Encryption at rest.
  • Run a per-user daemon by setting AUTHSOME_HOME to a user-specific path. This isolates vault files across users on the same host.
  • Keep AUTHSOME_HOME off shared mounts unless you control every host that mounts it.
  • Rotate any credential exposed to a CI runner after the job. The runner is outside your control.
  • Watch ~/.authsome/audit.log for unexpected revoke, register, or export events.

​
What’s next

Threat model

The full asset list and the three trust boundaries.

Hosted deployment model

Running a shared daemon on a trusted private network.

The local daemon

What the daemon does and which routes it exposes.