Safety Model
How Coven handles safety and guardrails.
Coven Safety Model
Coven is local-first, but local does not mean harmless. It can launch agent harnesses in real repositories, forward input to live processes, and preserve logs. This document states the safety boundaries that docs, clients, and code should preserve.
Trust Boundary
The Rust daemon is the authority boundary.
Every client is untrusted for enforcement purposes.
| Surface | Status | Trust posture |
|---|---|---|
| CLI/TUI | Current | Presentation layer; daemon still enforces sensitive decisions. |
| CastCodes | Current | Workspace layer; cannot widen project or session policy. |
| Cast Agent | Current backend | Substrate and session backend; still submits to daemon enforcement. |
| External OpenClaw plugin | External bridge | Bridge layer; must use daemon validation. |
| Scripts | Current | Automation callers; treated like any other untrusted client. |
| Future desktop clients | Future | Local UI surfaces; policy remains behind Coven. |
Clients may improve UX, but they must not be the only place where a sensitive decision is enforced.
Anything in UntrustedZone can lie, drift, or be replaced. Anything in TrustedZone is the Rust daemon's job and must fail closed on unknowns. The arrow direction is the only direction a sensitive decision is allowed to flow: from untrusted into the boundary, where it is revalidated.
Cast Codes are part of the untrusted intent surface. They can make routing clear, but they do not authorize launches, live input, kill requests, external actions, or destructive session operations.
Authentication and Local Access
Coven's current auth solution is a same-user local access model, not a network authentication protocol.
| Rule | Group | Implication |
|---|---|---|
Daemon API runs over <covenHome>/coven.sock, not TCP. | Transport | The API is same-user local by default. |
| No daemon OAuth, JWT, bearer token, API key, browser cookie, RBAC, or hosted account session in v0. | Auth model | Do not treat v0 as a remote service auth scheme. |
| Provider credentials stay in the harness/provider local auth flow. | Credentials | Codex or Claude Code own provider login. |
| Clients are untrusted for enforcement. | Authority | The Rust daemon must revalidate every sensitive request. |
| External OpenClaw plugin performs socket trust-anchor validation. | Defense in depth | Client checks help, but Rust-side private COVEN_HOME checks remain a hardening priority. |
| Do not expose the raw socket API through localhost TCP, browser, remote bridge, or mobile pairing without explicit auth design. | Transport | Remote access needs a separate design. |
The detailed contract lives in Authentication and local access.
Core Rules
| Rule | Risk area | Reason |
|---|---|---|
| Launch only with an explicit project root. | Filesystem policy | Every session needs a clear boundary. |
Canonicalize projectRoot and cwd before comparing paths. | Filesystem policy | String paths are not enough for enforcement. |
| Reject working directories outside the project root. | Filesystem policy | Clients cannot widen the launch boundary. |
| Keep harness ids allowlisted until a real policy layer exists. | Harness policy | Unknown adapters should not run by default. |
| Build harness commands with argv APIs. | Command execution | Prompt text should remain data. |
Do not execute prompts through sh -c. | Command execution | Avoid shell interpolation hazards. |
| Keep provider credentials in provider or harness authentication flow. | Credentials | Coven should not become a credential holder. |
| Treat the socket API as a local product contract. | Compatibility | Clients should use documented behavior, not internals. |
| Fail closed on unknown API versions, unknown action ids, unsupported harnesses, and invalid session ids. | Unknown behavior | Ambiguous requests should not be guessed. |
Data and Secrets
Coven should not require repository-stored secrets.
Do not commit runtime state:
| Pattern | Category | Risk |
|---|---|---|
.coven/ | Coven state | Local runtime records and sockets do not belong in repos. |
*.sqlite | Database | May contain local session history. |
*.sqlite3 | Database | May contain local session history. |
*.db | Database | May contain local or application state. |
*.sock | Socket | Socket paths are machine-local runtime artifacts. |
.env* | Secrets | Environment files often contain credentials. |
| Private keys | Secrets | Private key material must never be published. |
| Certificates | Secrets | Certificates may expose signing or identity material. |
| Token-bearing logs | Secrets | Logs can accidentally contain live credentials. |
Docs and examples must use placeholders such as /path/to/project, /Users/example, session-1, and intent-1.
Event Log Caution
The event log records harness output. A harness may print sensitive data if the user asks it to inspect a sensitive repository or command output includes secrets.
Recommended user guidance:
| Guidance | Risk area | Reason |
|---|---|---|
| Do not run untrusted prompts in sensitive repositories. | Prompt risk | Harness output may preserve inspected data. |
| Do not ask a harness to dump environment variables. | Secrets | Environment output can include tokens. |
| Do not paste secrets into prompts. | Secrets | Prompt text can be echoed or stored. |
| Use throwaway projects for demos and smoke tests. | Demo safety | Demo logs should be safe to publish. |
Run python scripts/check-secrets.py before publishing docs, fixtures, or release artifacts. | Publishing | Catch accidental secret material before release. |
Local Socket Posture
The daemon API runs over a local Unix socket. It is intended for same-user local clients.
Hardening priorities:
| Priority | Group | Purpose |
|---|---|---|
Private COVEN_HOME ownership and permissions | Filesystem trust | Keep daemon state same-user local. |
| Safe socket creation and cleanup | Socket lifecycle | Avoid symlink and replacement hazards. |
| Request size limits | API hardening | Constrain malformed or oversized requests. |
| Read timeouts | API hardening | Avoid stalled local clients holding resources indefinitely. |
| Structured error codes | Compatibility | Let clients handle failures consistently. |
| Event pagination | Scalability | Keep large event logs usable. |
| Compatibility tests for external clients | Compatibility | Prevent drift between daemon behavior and clients. |
Live Session Control
Live input and kill requests require a valid live session id.
Expected behavior:
| Condition | Response |
|---|---|
| Unknown session id | Return not found. |
| Non-live session input/kill | Return conflict. |
| Destructive session deletion of a running session | Refuse deletion. |
| Interactive deletion | Require explicit confirmation. |
Desktop Automation and Local UI Control
Future desktop automation adapters should be treated as privileged local capabilities.
Required posture:
| Requirement | Group | Reason |
|---|---|---|
| Discover capabilities before showing actions | Capability discovery | Clients should not invent unavailable controls. |
| Label risky actions clearly | Approval UX | Users need to understand sensitive effects. |
| Require explicit approval for clicks, typing, deleting, sending, buying, posting, or modifying external state | Approval UX | Visibility is not consent. |
| Log action requests and outcomes without recording secrets | Observability | Audits need traces, not credential leakage. |
| Keep adapters behind the Coven control plane | Architecture | Clients should not bind directly to brittle OS automation APIs. |
The split should remain:
client intent -> Coven policy/control plane -> adapter -> desktop/appExternal Actions
Coven should ask or require host-level policy before actions that leave the machine or affect external services.
| Action | Category | Approval reason |
|---|---|---|
| Sending messages | Communication | Leaves the local machine and speaks to another person. |
| Sending email | Communication | Creates durable external communication. |
| Posting publicly | Publishing | Publishes content under an identity or project. |
| Purchasing | Commerce | Can spend money or create obligations. |
| Deleting remote data | Remote state | Can destroy data outside the local ledger. |
| Pushing to git remotes | Remote state | Changes shared source history or branches. |
| Modifying cloud resources | Remote infrastructure | Can affect live services or billing. |
The local runtime can make these actions visible, but visibility is not consent.
Last updated on