94 lines
3.8 KiB
Go
94 lines
3.8 KiB
Go
// Package fs defines the 9P namespace for olliesrv.
|
|
//
|
|
// # The Namespace IS the Security Model
|
|
//
|
|
// This package implements the namespace-bounded capability model: an agent's
|
|
// capabilities are defined by what exists in its namespace and what permissions
|
|
// it has on those files.
|
|
//
|
|
// # Isolation Boundaries
|
|
//
|
|
// Two levels of isolation:
|
|
//
|
|
// 1. Session-level: each session has its own toolsrv process, tool registry,
|
|
// and Landlock sandbox configuration. Cross-session isolation is process
|
|
// isolation — agents in different sessions cannot share capabilities.
|
|
//
|
|
// 2. Agent-level (within session): agents in the same session share the
|
|
// toolsrv process and 9P connection, but have per-agent capabilities
|
|
// enforced by file permissions and registry lookups.
|
|
//
|
|
// # Structural Enforcement (within session)
|
|
//
|
|
// Three layers of structural enforcement within a session:
|
|
//
|
|
// 1. File existence: if a file doesn't exist in the namespace, the agent
|
|
// can't reference it. The peer/ directory only contains declared peers;
|
|
// an agent can't message a peer that isn't in its directory.
|
|
//
|
|
// 2. File permissions: each agent file is owned by its agent ID. Unix
|
|
// permission bits (owner/group/world) determine who can read/write.
|
|
// Agent A can't read Agent B's plan because the file is mode 0600
|
|
// with a different owner.
|
|
//
|
|
// 3. Registry check: tool execution requires registry.Lookup to confirm
|
|
// the tool is loaded for the calling agent (see toolsrv/internal/registry).
|
|
//
|
|
// None of these checks depend on the model's behavior or compliance. They are
|
|
// structural: if the file doesn't exist, if the permission check fails, or if
|
|
// the tool isn't in the registry, the operation is denied unconditionally.
|
|
//
|
|
// # Namespace Structure
|
|
//
|
|
// Root level:
|
|
//
|
|
// /agents - available agent profile names
|
|
// /backends - available backend names
|
|
// /models - available models (backend\tmodel per line)
|
|
// /ctl - server control (invalidate, kill)
|
|
// /generate - one-shot generation (rdwr)
|
|
// /session/ - session directory
|
|
//
|
|
// Session level (/session/{name}/):
|
|
//
|
|
// env - session environment variables
|
|
// goal - session objective (write triggers workflow)
|
|
// agent/ - agents within this session
|
|
// agent/new - create agent (rdwr)
|
|
//
|
|
// Agent level (/session/{name}/agent/{agent}/):
|
|
//
|
|
// prompt - submit prompt (write, mode 0200, owner only)
|
|
// chat - conversation history (read, mode 0440, owner+group)
|
|
// state - current agent state (read, mode 0444, world)
|
|
// plan - agent's plan (rw, mode 0600, owner only)
|
|
// ctl - agent control commands (rw, mode 0600, owner only)
|
|
// peer/ - peer directory (dynamically generated from peer list)
|
|
//
|
|
// # Per-Agent File Ownership
|
|
//
|
|
// Agent directories are owned by their agent ID (UID) with group "agent" (GID).
|
|
// Permissions enforce isolation:
|
|
//
|
|
// - mode 0600: owner only (plan, ctl, fifo) — private to owning agent
|
|
// - mode 0640: owner rw, group r (cfg, name) — readable by other agents
|
|
// - mode 0440: owner r, group r (chat, log) — readable by other agents
|
|
// - mode 0444: world readable (state, id) — non-sensitive, observable
|
|
// - mode 0220: owner+group write (prompt) — CLI and owning agent can submit
|
|
//
|
|
// Admin clients (empty uname, "admin", or server owner) bypass permission checks.
|
|
// This allows CLI tools and GUIs to manage all agents.
|
|
//
|
|
// # Blocking Reads
|
|
//
|
|
// Files like event block until their condition is met.
|
|
// This is the primary coordination mechanism — clients read these files
|
|
// in a loop to react to state changes.
|
|
//
|
|
// # Implementation
|
|
//
|
|
// The spec is pure declaration; handlers are closures that capture their
|
|
// targets. NewRoot() builds the virtfs.Tree from the spec. The tree is
|
|
// served directly by the 9P server.
|
|
package fs
|