Crate kovra_agent 

kovra-agent — the governed ssh-agent (KOV-13). A thin face over kovra-core, mirroring kovra-wrapper and kovra-cli: kovra is the ssh-agent. It speaks the ssh-agent wire protocol on $SSH_AUTH_SOCK and answers each sign request by signing in its own memory with a custodied Keypair (KOV-12). The private key never leaves kovra and never hits disk (I7).

What a plain agent cannot do, and this one does:

• Per-signature policy. A high/prod key confirms via the broker / biometric on every signature and is audited (I3/I15/I12); low/ medium keys sign silently (still audited).
• Scope (I13). The agent serves keys under an AgentScope read from a config file (<root>/agent.toml, see config); an out-of-scope key is neither listed nor signable.

Honest limit (spec §16). This governs the authentication event — the moment ssh asks the agent to sign the session challenge — not the SSH session that opens afterward. Once a signature is approved and the session is established, kovra has no further control over what flows through it, exactly as Vault/1Password/etc. cannot. Per-signature confirmation makes each new auth an attended, audited act; it does not contain the live session. Do not overclaim this in docs or UAT notes.

Layering

agent → core only (like wrapper → core). core never depends on this crate. Free core (§20): this is crates/agent, NOT enterprise/. All cryptography lives in core (kovra_core::sign_ssh_agent); this crate only parses/encodes the wire protocol and orchestrates policy/scope/audit. The untrusted parser is isolated in protocol (a Phase-4 fuzz target).

Re-exports

pub use config::AGENT_CONFIG_FILE;

pub use config::config_path;

pub use config::load_scope;

pub use daemon::SessionOwned;

pub use daemon::default_socket_path;

pub use error::AgentError;

pub use session::KeypairEntry;

pub use session::Session;

Modules

config

Agent scope configuration (KOV-13, decision Q3: a config file).

daemon

Socket lifecycle for the governed ssh-agent (KOV-13, decision Q4: foreground-only MVP; decision Q5: refuse-and-guide on a pre-existing $SSH_AUTH_SOCK).

error

AgentError — the agent face’s error type (KOV-13).

protocol

The ssh-agent wire protocol — the isolated, untrusted parsing/encoding surface (KOV-13, decision Q1: a minimal in-crate parser, synchronous, no ssh-agent-lib, no tokio).

session

Session logic: map a parsed ssh-agent Request to a response, applying kovra’s policy (KOV-13). This is the heart of the governed agent and is pure / OS-free so it is driven entirely by mocks in tests — the real socket and a real ssh client are [host], not unit-tested (CLAUDE.md rule 4, like the biometric path).

Structs

AgentConfig

Everything run_agent needs, built by the face (the CLI) from its Ctx. The custodied keys are provided by a closure so the daemon can re-read them per request (a key added/removed while the daemon runs is reflected).

Traits

SessionProvider

Provider of the live session inputs per request: the custodied keypairs, a fresh confirmer, audit sink, and clock. Implemented by the CLI over its Ctx; behind a trait so the daemon stays face-agnostic and testable.

Functions

run_agent

Run the governed ssh-agent in the foreground (decision Q4) until Ctrl-C.