Authentication
Authentication, tokens, and access control.
Authentication and Local Access
Last updated: 2026-05-14
Coven does not currently have daemon-level user authentication in the OAuth, JWT, bearer-token, API-key, browser-cookie, or hosted-account sense.
The current solution is a same-user local access model.
| Property | Group | Meaning |
|---|---|---|
| Local Unix socket only | Transport | The daemon exposes HTTP only over <covenHome>/coven.sock. |
| Default socket path | Transport | The default path is ~/.coven/coven.sock. |
| Client validation is UX | Authority | Clients may validate requests for nicer errors, but Rust remains the enforcement boundary. |
| Harness-owned provider credentials | Credentials | Codex, Claude Code, and other harnesses keep using their normal local auth flow. |
| No credential proxying | Credentials | Coven should not read, proxy, persist, or mint provider or OpenClaw credentials. |
This is intentionally a local-first MVP posture. It is suitable for same-user local clients such as the Coven CLI/TUI, CastCodes, Cast Agent, scripts, and the external OpenClaw plugin. It is not a remote API auth scheme.
The boundary is filesystem permissions plus same-user process locality. Anything outside the dashed zone is rejected by design; introducing a remote, browser, or cross-user surface requires a separate auth design (not a tunnel of the existing socket).
What Protects the API Today
Unix Socket Locality
The API is not exposed as TCP by default. Clients connect to the local Unix socket owned by the user's Coven state directory.
New clients should treat the socket path as the trust anchor and should connect only to the versioned API under /api/v1/....
Rust Authority Checks
The daemon must revalidate sensitive request fields before acting, even when a client already validated them.
| Field | Risk area | Failure behavior |
|---|---|---|
| API version | Compatibility | Fail closed on unknown versions. |
| Project root | Filesystem policy | Reject invalid or widened roots. |
| Working directory | Filesystem policy | Reject cwd values outside the project root. |
| Harness id | Harness policy | Reject unsupported harnesses. |
| Session id | Session control | Return not found for unknown records. |
| Live-session state | Session control | Return conflict for non-live input or kill requests. |
| Input requests | Session control | Forward only to verified live sessions. |
| Kill requests | Session control | Terminate only verified live processes. |
| Control-plane action ids | Action routing | Fail closed on unknown action ids. |
Unknown API versions, unknown action ids, unsupported harnesses, invalid session ids, and outside-root working directories must fail closed.
Harness-owned Provider Auth
Coven launches supported local harness CLIs. It does not implement provider login.
Examples:
| Harness | Auth flow | Owner |
|---|---|---|
| Codex | codex login or Codex CLI local setup | Codex CLI |
| Claude Code | claude doctor or Claude Code CLI local setup | Claude Code CLI |
coven doctor may report setup hints for these tools, but Coven does not own their credentials.
External OpenClaw Plugin Guardrails
OpenClaw integration is externalized through @opencoven/coven. OpenClaw core is not a Coven trust root.
The plugin is disabled by default and must be explicitly selected as the ACP backend. It validates the local socket trust anchor before connecting.
| Guardrail | Risk area | Purpose |
|---|---|---|
covenHome absolute and non-symlink | Path trust | Avoid ambiguous or replaceable state roots. |
socketPath restricted to <covenHome>/coven.sock | Path trust | Prevent arbitrary socket targets. |
| Socket path is not a symlink | Replacement race | Avoid following a swapped socket target. |
| Resolved socket is a Unix socket | Transport | Reject regular files or unexpected filesystem nodes. |
| Socket root, directory, and socket owned by current user | Ownership | Keep access scoped to the same OS user. |
| Socket root and directory not group/world accessible | Permissions | Reduce accidental cross-user access. |
| Socket path fingerprinted around connection | Replacement race | Catch socket replacement between validation and connect. |
These client-side checks improve defense in depth. They do not replace Rust daemon enforcement.
What This is Not
The current auth solution is intentionally narrow.
| Excluded model | Category | Implication |
|---|---|---|
| OAuth | Identity protocol | There is no delegated web login boundary. |
| OpenID Connect | Identity protocol | There is no hosted identity-provider session. |
| JWT sessions | Token auth | There are no daemon-issued session tokens. |
| Bearer-token auth | Token auth | There is no reusable API bearer credential. |
| API-key auth | Token auth | There are no daemon API keys. |
| Browser cookie auth | Browser auth | The daemon is not browser-origin safe. |
| RBAC | Authorization | There are no daemon roles or multi-user permissions. |
| Multi-user authorization | Authorization | Access is same-user local, not team-scoped. |
| CSRF/origin policy | Browser auth | Do not expose the raw socket through a browser-facing bridge. |
| Cloud account boundary | Hosted service | Coven v0 is not a hosted account API. |
| Permission to expose localhost TCP, remote network, or browser access | Transport | Remote access needs a separate auth and pairing design. |
If a future dashboard, mobile app, remote bridge, or browser-exposed service needs to talk to Coven, it needs an explicit additional auth and pairing design. Do not tunnel or proxy the raw daemon socket into a network service and call that authenticated.
Current Hardening Gap
The TypeScript OpenClaw plugin client already performs strict socket trust-anchor validation.
The Rust daemon currently owns request enforcement and socket API behavior, but Rust-side private COVEN_HOME ownership and permission checks before creating, binding, or removing daemon state are still a hardening priority. Until that is implemented, client-side socket validation should be treated as defense in depth for cooperating clients, not as a complete daemon-side auth boundary.
Before broad distribution, Rust should fail closed for the hardening cases below.
| Condition | Risk area | Expected behavior |
|---|---|---|
COVEN_HOME is not owned by the current user | Ownership | Fail before using the state directory. |
COVEN_HOME is group or world accessible | Permissions | Fail before binding or trusting daemon state. |
COVEN_HOME resolves through a symlink | Path trust | Reject ambiguous state roots. |
Socket path resolves outside COVEN_HOME | Path trust | Reject widened socket paths. |
| Existing socket path is a symlink or non-socket file | Replacement race | Refuse cleanup or connection assumptions. |
| Socket creation or cleanup would cross the trusted state directory boundary | State safety | Refuse the operation. |
Requirements for New Clients
New Coven clients must preserve the local authority boundary.
| Requirement | Group | Reason |
|---|---|---|
Use /api/v1/... routes | Versioning | Keeps clients on the documented compatibility contract. |
Call GET /api/v1/health before assuming compatibility | Handshake | Confirms daemon availability and API version first. |
| Treat the Rust daemon as the authority boundary | Policy | Client checks are UX, not enforcement. |
| Keep provider credentials in the provider or harness auth flow | Credentials | Prevents Coven from becoming a credential proxy. |
| Avoid storing repository secrets, environment dumps, private URLs, or token-bearing logs | Privacy | Session artifacts should stay publishable and inspectable where possible. |
Reject configurable socket paths that do not resolve to <covenHome>/coven.sock | Path trust | Avoid arbitrary local socket targets. |
| Fail closed on unknown harness ids or unsupported API versions | Compatibility | Unknown behavior should not be guessed. |
| Avoid network, browser, or remote transport without a separate auth design | Transport | Same-user local access is not remote authentication. |
Last updated on