ms2k/lazaret
SHA256
Watch
0
Code Releases 3 Activity

docs: formalize protocol identity and transition to regular-file escalation mailbox

Browse source 
- Replaces stream/socket escalation with a sandboxed regular-file Escalation Mailbox to satisfy runsc isolation boundaries without exposing `host-uds=open`.
- Expands the TLA+ protocol model with role-bound certificates, tuple authorization, and structured domain-failure recovery paths.
- Adds physical integration journals for host terminfo injection, persistent /etc DNS shims, rootless Podman network topology, and static client delivery.
- Establishes specification requirements for safe host-only State Anchor inspection and crash-consistent reset operations.
This commit is contained in:
ms2k 2026-06-30 02:31:56 +09:00
commit 682d7c7db7
1 changed files with 408 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

94
docs/specification.md
View file

@ -67,10 +67,12 @@ implementation plan, logs, and user interfaces.
| **Agent Workspace** | The canonical host project directory mounted read-write at `/workspace` in the Agent Sandbox. |
| **Agent Sandbox** | The rootless gVisor container in which an agent and its child processes execute. One sandbox is shared by all Client Sessions in a Domain. |
| **Agent Sandbox ID** | A runtime-unique identifier assigned to one Agent Sandbox instance and bound to its Domain protocol identity. |
| **Client CLI ID** | A runtime-unique identifier assigned to one host Lazaret CLI process. It is authenticated as a protocol identity and bound to one Client Session. |
| **Client Session** | One active host Lazaret CLI process and the interactive or non-interactive command it attaches to the Agent Sandbox. |
| **Session ID** | A cryptographically random identifier unique to one Client Session. |
| **Session Anchor** | Ephemeral session credentials that bind protocol messages to a registered Session ID and route them to the owning host CLI. |
| **Session Coordinator** | The ephemeral host process that exclusively owns and coordinates a Domain's runtime resources and Client Sessions. |
| **Session Coordinator ID** | A runtime-unique identifier assigned to one Session Coordinator instance and bound to its Domain protocol identity. |
| **Domain** | The shared runtime and persistent-state scope for one `(Agent Profile, canonical Agent Workspace)` pair. |
| **Domain ID** | A deterministic identifier derived from the Agent Profile name and canonical Agent Workspace path. It namespaces Domain resources but is not an authentication credential. |
| **Domain Root** | The host-only directory containing persistent state and metadata for one Domain. |
@ -79,8 +81,10 @@ implementation plan, logs, and user interfaces.
| **Git Sentry** | The protective mount layout that preserves bidirectional workspace and Git access while preventing writes to the host's default Git hooks and repository configuration. |
| **Ignored Workspace State** | Domain-scoped sandbox-local storage presented at Git-ignored Agent Workspace paths instead of exposing the corresponding host content. |
| **State Anchor** | The Domain-scoped persistent writable filesystem layer merged over selected paths from the sandbox base image. |
| **Trust Anchor** | The ephemeral Domain-scoped certificate authority used to authenticate Lazaret protocol peers. |
| **Trust Anchor** | The ephemeral Domain-scoped certificate authority used to authenticate role-bound Lazaret protocol identities. |
| **Protocol Identity** | An authenticated binding of a component role, Agent Profile, Domain ID, and runtime component ID. Identifiers name components but do not authenticate them by themselves. |
| **Escalation Client** | The Lazaret-provided executable through which a sandboxed process requests a host action. |
| **Escalation Mailbox** | Host-private, Domain-scoped regular-file message paths mounted into the Agent Sandbox for signed escalation requests and correlated results. |
| **Escalation Request ID** | A cryptographically random identifier used to correlate one host escalation request and response. |
| **Escalation Result** | The terminal response to an accepted Host Escalation, correlated by Escalation Request ID and carrying its outcome plus command exit status and output when execution occurred. |
| **Host Escalation** | A request by a sandboxed process for Lazaret to execute a developer-approved or auto-approved action with host authority. |
@ -100,6 +104,7 @@ flowchart LR
Coordinator[Session Coordinator]
State[State Anchor]
Gateway[Network Sidecar]
Mailbox[Escalation Mailbox]
HostExec[Approved host process]
end
@ -114,10 +119,10 @@ flowchart LR
CLI <--> Coordinator
Coordinator --> State
Coordinator --> Gateway
Coordinator --> Agent
Coordinator <--> Mailbox
Agent <--> Workspace
Agent --> Escalate
Escalate --> Coordinator
Escalate <--> Mailbox
Coordinator --> HostExec
Agent --> Gateway
Gateway --> Network[Permitted destinations]
@ -132,10 +137,10 @@ untrusted agent environment.
### 3.2 Domain and Session Lifecycle
The Session Coordinator is the single owner of a Domain's Agent Sandbox, Network
Sidecar, State Anchor, sockets, and active-session registry. Concurrent CLI
processes for the same Domain join the existing coordinator and attach separate
Client Sessions to the shared sandbox. Different Domains never share these
resources.
Sidecar, State Anchor, host-only sockets, Escalation Mailbox, and active-session
registry. Concurrent CLI processes for the same Domain join the existing
coordinator and attach separate Client Sessions to the shared sandbox. Different
Domains never share these resources.
The first Client Session starts the Domain. The coordinator prepares persistent
state, establishes network policy, starts the Agent Sandbox, and then accepts the
@ -145,6 +150,25 @@ retaining Domain-scoped persistent state.
Startup, registration, cancellation, recovery, and teardown transitions are
defined by the [TLA+ application protocol model](protocol/Lazaret.tla).
A Domain failure first withdraws publication, invalidates active trust material,
disconnects sessions, and terminates associated host processes. It does not
assume that already-created sandbox, sidecar, or mount resources disappeared.
Recovery stops the sandbox, then the sidecar, then unmounts the State Anchor
before the Domain may return to the absent state and accept a new startup leader.
The Trust Anchor authenticates distinct Protocol Identities for the Session
Coordinator, Client CLI, Network Sidecar, and Agent Sandbox. Certificates bind a
peer's role, Agent Profile, Domain ID, and runtime component ID; a certificate for
one role or Domain cannot authorize another. Session registration additionally
binds the authenticated Client CLI ID to its Session ID and Session Anchor.
Authorization uses the relevant current identity tuple rather than any identifier
alone. Network attachment binds the `(Domain ID, Network Sidecar ID, Agent Sandbox
ID)` tuple. Session control binds the `(Domain ID, Session Coordinator ID, Client
CLI ID, Session ID)` tuple. Host Escalation binds the authenticated Agent Sandbox
ID to the registered `(Client CLI ID, Session ID, Session Anchor)` tuple in that
Domain.
### 3.3 Filesystem and Git Model
The Agent Workspace is mounted read-write. Tracked paths and untracked paths that
@ -196,6 +220,8 @@ override Lazaret's host control plane.
The Network Sidecar establishes the Domain's egress routes before the Agent
Sandbox starts. The sidecar alone receives the network-administration capability
needed to install policy; the Agent Sandbox does not receive that capability.
The Agent Sandbox may join only the sidecar's prepared network namespace, not the
host network namespace.
IPv4 destinations are permitted by default except for the RFC 1918 private
address ranges, which are denied by default. Explicit, more-specific allow rules
@ -215,10 +241,15 @@ that property.
### 3.6 Host Escalation
The Escalation Client communicates with the Session Coordinator over a
Domain-scoped host-private Unix socket. The Trust Anchor authenticates the Domain
peer, and the Session Anchor binds the request to a registered Client Session. A
verified request is routed only to that session's host CLI.
The Escalation Client exchanges request and result records through the
Escalation Mailbox. Records are regular files written by atomic rename beneath
host-private, Domain-scoped paths. The sandbox-writable request path and
sandbox-readable result path may have different mount modes. The mailbox is not
trusted as an authentication boundary: each request carries authenticated Domain
credentials and a Session Anchor signature binding it to a registered Client
Session and to the exact request content. A verified request is routed only to
that session's host CLI. Host-only CLI/coordinator control may use host-private
Unix sockets that are never mounted into the Agent Sandbox.
A host command may run only when the developer approves it interactively or when
it matches an auto-approval rule in trusted host configuration. Auto-approved
@ -228,16 +259,38 @@ explicit property of an individual rule.
Interactive approval may allow the developer to approve, deny, or edit a request.
Every accepted request must produce an Escalation Result for its Escalation
Client while its Client Session remains connected. The result reports approval,
Client while its Client Session remains connected. The result reports completion,
denial, timeout, cancellation, or failure and, when a host command ran, its exit
status and standard-output and standard-error data. A request reaches its terminal
state only after this result is delivered or its Client Session disconnects.
status and standard-output and standard-error data. Approval is an authorization
decision, not a terminal result. A request reaches its terminal state only after
this result is delivered or its Client Session disconnects.
Terminal ownership must return to the sandbox session after resolution.
Authentication, message correlation, approval, execution, cancellation, and
terminal-routing transitions are defined by the
[TLA+ application protocol model](protocol/Lazaret.tla).
### 3.7 State Inspection and Reset
The host CLI provides read-only discovery, inspection, structural verification,
and explicit reset operations for Domain State Anchors. These operations resolve
a Domain through trusted host metadata and never accept an arbitrary host
filesystem path as an upper-layer target.
Inspection reports metadata and overlay changes without printing file contents by
default. Structural verification requires an inactive Domain and exclusive
lifecycle ownership so its result is not invalidated by concurrent writes. A
reset may target one configured persistent container path or all State Anchors in
the Domain. It discards the selected upper-layer state so the next launch follows
the current base-image lower layer; it does not modify the base image, Agent
Workspace, Ignored Workspace State, or unselected State Anchors.
Reset is permitted only after Lazaret holds the Domain's exclusive lifecycle lock
and has established that no Client Session, coordinator, sandbox, sidecar, host
process, or overlay mount is using the selected state. Confirmation flags may
suppress the human prompt but may not bypass these safety conditions. Reset must
be crash-consistent and must never follow a symlink outside the Domain Root.
## 4. Requirements
### 4.1 Security Requirements
@ -246,17 +299,18 @@ terminal-routing transitions are defined by the
| :--- | :--- |
| **SR-1** | Agent processes shall execute in a rootless gVisor sandbox and shall not receive host root authority. |
| **SR-2** | Host configuration shall never be mounted into the Agent Sandbox or located beneath a host path mounted into it. |
| **SR-3** | Host paths outside the Agent Workspace and developer-configured volumes shall not be accessible to the Agent Sandbox. |
| **SR-3** | Host paths outside the Agent Workspace, developer-configured volumes, and Lazaret-owned fixed control mounts shall not be accessible to the Agent Sandbox. |
| **SR-4** | The sandbox shall be unable to modify the host repository's `.git/config` or default `.git/hooks` directory through the workspace mount. |
| **SR-5** | The Network Sidecar shall establish network policy before the Agent Sandbox starts, and the Agent Sandbox shall not receive network-administration capability. |
| **SR-6** | Network policy shall cover every enabled address family and shall deny equal-specificity policy conflicts. |
| **SR-7** | A host action shall execute only after interactive developer approval or a match against a trusted host auto-approval rule. |
| **SR-8** | Auto-approved host commands shall execute without a shell and shall permit trailing arguments only when the matched rule explicitly grants them. |
| **SR-9** | Escalation requests shall be authenticated to a Domain and bound to a registered Session ID before routing or execution. |
| **SR-10** | Domain sockets and coordination files shall reside in a host-private directory owned by the developer. |
| **SR-9** | Every protocol peer shall be authenticated to its component role, Agent Profile, Domain ID, and runtime component ID. Authorization shall require the relevant current identity tuple; an identifier or certificate for another role, Domain, component instance, or Client Session shall not be accepted. |
| **SR-10** | Domain sockets, mailboxes, and coordination files shall reside in a host-private directory owned by the developer. |
| **SR-11** | Runtime and persistent resources belonging to different Domain IDs shall remain isolated. |
| **SR-12** | The Agent Sandbox shall not join host user, PID, IPC, UTS, cgroup, or network namespaces; the only shared network namespace permitted is the Domain's Network Sidecar enforcement namespace. |
| **SR-13** | Git-ignored Agent Workspace paths shall use Ignored Workspace State by default, preventing the sandbox from reading or modifying corresponding host content; only trusted host configuration may disable this behavior. |
| **SR-14** | State Anchor maintenance shall remain confined to the resolved Domain Root. Destructive maintenance shall require exclusive lifecycle ownership and an inactive, unmounted target. |
### 4.2 Functional Requirements
@ -268,9 +322,11 @@ terminal-routing transitions are defined by the
| **FR-4** | Selected sandbox paths and Ignored Workspace State shall persist across Domain restarts without copying Lazaret host configuration into the sandbox. |
| **FR-5** | The coordinator shall route each escalation prompt to the Client Session identified by the verified Session ID and deliver the correlated Escalation Result to the requesting Escalation Client. |
| **FR-6** | The final Client Session leaving a Domain shall trigger teardown of transient Domain resources. |
| **FR-7** | Startup and teardown shall recover safely from interrupted or stale prior executions. |
| **FR-7** | Startup and teardown shall recover safely from interrupted or stale prior executions without assuming that external runtime resources disappeared with their owner process. |
| **FR-8** | Lazaret shall support interactive terminal sessions without degrading supported host terminal capabilities. |
| **FR-9** | Trusted host configuration shall allow the developer to disable Git-ignored path isolation for an Agent Profile. |
| **FR-10** | Session registration shall bind one authenticated Client CLI ID, Session ID, and Session Anchor, and escalation routing and approval shall preserve that binding. |
| **FR-11** | The host CLI shall list, inspect, structurally verify, and reset all or selected State Anchors without requiring direct manipulation of Lazaret's storage layout. |
### 4.3 Developer-Experience Requirements
@ -281,6 +337,7 @@ terminal-routing transitions are defined by the
| **DX-3** | Normal source editing, `git status`, staging, committing, and reference updates shall work from inside the Agent Sandbox. |
| **DX-4** | Escalation prompts shall identify the requesting profile, session, command, and justification without mixing terminal input or output between sessions. |
| **DX-5** | Failures shall report actionable diagnostics and shall not leave the developer's terminal in a corrupted mode. |
| **DX-6** | State inspection shall provide human-readable and machine-readable output without exposing persisted file contents by default, and reset shall show its resolved Domain and exact scope before confirmation. |
### 4.4 Operational Requirements
@ -290,3 +347,4 @@ terminal-routing transitions are defined by the
| **OR-2** | Every accepted protocol request shall resolve to a delivered completed, denied, timed-out, cancelled, or failed result, unless its Client Session disconnects first. |
| **OR-3** | Cancellation and process termination shall not strand an active host command or permanently block another Client Session. |
| **OR-4** | Security-sensitive behavior shall be covered by integration tests on supported Podman, runsc, filesystem, and network configurations. Test evidence belongs in the journal. |
| **OR-5** | An interrupted State Anchor reset shall recover to either the prior generation or a new empty generation; it shall not leave a partially reset active upper layer. |