ms2k/lazaret
SHA256
Watch
0
Code Releases 3 Activity

Define protocol cryptography packaging

Browse source
This commit is contained in:
ms2k 2026-07-12 03:08:09 +09:00
commit 6db7cf1d5f
1 changed files with 280 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/specification.md
View file

@ -81,7 +81,8 @@ implementation, logs, and user interfaces.
| **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 Anchor** | An ephemeral host-only signing key whose public key binds developer decisions to a registered Session ID and owning Client CLI. |
| **Session Request Capability** | An ephemeral Session Coordinator-signed binding of one live Client Session to the exact Agent Sandbox generation and its protocol credentials. HC physically holds the signing key. It is a routing capability within the shared sandbox trust domain, not a process-isolation boundary. |
| **Session Coordinator** | The logical Domain role defined by the protocol model. The selected physical refinement maps it to Host Coordinator, Runtime Supervisor, and attached runsc processes. |
| **Session Coordinator ID** | A runtime-unique identifier for the logical Session Coordinator as a protocol peer, authenticated on the Host Coordinator face. Generation scoping and stale-credential refuse follow the protocol model. |
| **Host Coordinator** | The constitutive Session Coordinator process that runs in the host user and mount namespaces. It is the protocol face: Domain lock, durable state store, Session PTY masters, escalation mailbox and routing, publication and session admission, and lifetime authority over the Runtime Supervisor. |
@ -104,8 +105,9 @@ implementation, 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 prepared lower. |
| **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. |
| **Trust Anchor** | The ephemeral Domain-generation trust package containing separate TLS certificate-authority and protocol-credential issuer keys. |
| **Protocol Credential** | A Trust Anchor-issued binding of a protocol-signing public key to an exact Domain generation, component role, and runtime component ID. |
| **Protocol Identity** | An authenticated binding of a component role, Agent Profile, Domain ID, and runtime component ID. Identifiers, paths, filenames, and process IDs name resources but do not authenticate protocol peers 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. |
@ -192,6 +194,42 @@ mounts, `slirp4netns`, PTYs, runsc clients, durable store encoding, and exact
ownership records). Physical recovery enumerates and inspects those resources
independently of process liveness.
#### Protocol cryptography refinement
Before starting the Agent Sandbox, the Host Coordinator creates one ephemeral
Trust Anchor package containing separate Ed25519 TLS-CA and protocol-issuer keys.
Its signed Trust Manifest binds both roots to the generation identity defined in
the schema. The Session Coordinator TLS and protocol credentials use distinct
leaf keys physically held by HC; the Agent Sandbox uses another request-signing
key. The publication identity pins the CA, manifest, and coordinator TLS leaf in
the validated host-private Domain path, while the exact sandbox credential mount
pins the same manifest. Protocol credential IDs are SHA-256 digests of their
signed claims. `SessionCoordinator` remains the logical protocol role; HC is its
physical key holder, not another principal.
The host-private protocol socket uses TLS 1.3 with the generation CA, fixed ALPN
`lazaret-control/1`, no early data, and no session resumption. A connection with
no client certificate may perform only a credential enrollment of at most 8,192
bytes from the trusted developer UID beneath that runtime directory. HC verifies
the signed CSR and issues a one-hour `clientAuth` leaf; all other operations
require a new mTLS connection whose leaf matches the issued Client CLI and
generation. The HC leaf is `serverAuth`-only for
`coordinator.lazaret.invalid`. Peer PID and process start time are not protocol
identity evidence.
The Client CLI keeps its Session Anchor private key in host memory. HC delivers
the signed Session Request Capability with guest execution and mounts the Agent
Sandbox signing key, credential, Trust Manifest, and Session Coordinator
verification credential read-only at the fixed credential path. No TLS,
protocol-issuer, coordinator-signing, or Session Anchor private key enters the
sandbox. HC unlinks the sandbox-key source after the running sandbox holds the
mount and retains only its public key.
All Trust Anchor and session cryptographic material is ephemeral. Normal teardown
withdraws publication before dropping keys and credential artifacts. HC loss
destroys the in-memory package; bootstrap never restores it into another
generation.
### 3.3 Session Terminals
The Host Coordinator owns one host PTY master per interactive Client Session. The
@ -529,6 +567,25 @@ generation identity and are opened through Host Coordinator-owned directory
handles. Host-only CLI/coordinator control may use host-private Unix sockets that
are never mounted into the Agent Sandbox.
Mailbox files carry the signed protocol records defined by the normative design
schema; TLS is not layered over the regular-file transport. HC opens each ready
entry relative to a confined directory handle, rejects links and non-regular
files, bounds the complete file before allocation, and reads it once. It verifies
the signature over those owned bytes before parsing. Pathnames, file ownership,
mailbox identity files, PIDs, and start times are not authentication evidence.
Requests, cancellations, acknowledgements, developer decisions, chunks, and
terminal results use the signer relationships in the schema. Postcard payloads
are signed with `lazaret/v1/` plus the lower-kebab schema record name and their
exact encoded length and bytes. A complete record is at most 65,536 bytes; a
result chunk contains at most 49,152 output bytes.
The Escalation Client acknowledges the highest contiguous result sequence with an
Agent Sandbox signature. HC retains at most eight unacknowledged chunks per
request and pauses the exact host process's output pipes at that bound. Session
loss, cancellation, or acknowledgement timeout terminates and reaps the process
before removing its result files.
The physical host-process launcher invokes an executable with an argument vector
and contains no shell-expansion path.