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
2 changed files with 280 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

222
docs/schema.md
View file

@ -223,8 +223,226 @@ classDiagram
`exit_code` is present only for `Exited` and is the status collected from the
non-detached runsc exec client. Interactive PTY output is one merged byte stream;
it does not preserve stdout and stderr as separate channels. Protocol
cryptographic envelopes and wire encoding are outside this schema.
it does not preserve stdout and stderr as separate channels.
## Protocol cryptography
```mermaid
classDiagram
class GenerationIdentity {
agent_profile
domain_id
generation_id
configuration_fingerprint
coordinator_id
sandbox_id
}
class TrustManifest {
protocol_version
generation_identity
tls_ca_sha256
protocol_issuer_public_key
issuer_signature
}
class TlsCredential {
generation_identity
role
subject_id
certificate_der
certificate_sha256
}
class ProtocolPublicationIdentity {
protocol_version
generation_identity
tls_ca_certificate_der
trust_manifest_sha256
coordinator_tls_certificate_sha256
}
class SandboxCredentialBundle {
protocol_version
generation_identity
trust_manifest
coordinator_protocol_credential
sandbox_protocol_credential
sandbox_private_key
}
class TlsRole {
<<enumeration>>
SessionCoordinator
ClientCLI
}
class ProtocolCredential {
protocol_version
credential_id
generation_identity
role
subject_id
public_key
issuer_signature
}
class ProtocolCredentialRole {
<<enumeration>>
SessionCoordinator
AgentSandbox
}
class SessionBinding {
generation_identity
cli_id
session_id
session_anchor_public_key
}
class SessionRequestCapability {
protocol_version
capability_id
session_binding
coordinator_credential_id
sandbox_credential_id
coordinator_signature
}
TrustManifest --> GenerationIdentity
TlsCredential --> TlsRole
TlsCredential --> GenerationIdentity
ProtocolPublicationIdentity --> GenerationIdentity
ProtocolPublicationIdentity --> TrustManifest
ProtocolPublicationIdentity --> TlsCredential : coordinator TLS leaf
SandboxCredentialBundle --> GenerationIdentity
SandboxCredentialBundle --> TrustManifest
SandboxCredentialBundle --> ProtocolCredential : coordinator verifier
SandboxCredentialBundle --> ProtocolCredential : sandbox signer
ProtocolCredential --> GenerationIdentity
ProtocolCredential --> ProtocolCredentialRole
SessionBinding --> GenerationIdentity
SessionRequestCapability --> SessionBinding
SessionRequestCapability --> ProtocolCredential : coordinator signer
SessionRequestCapability --> ProtocolCredential : sandbox subject
```
Trust Manifests, credentials, capabilities, and private keys are ephemeral
protocol material, not Domain Store records.
```mermaid
classDiagram
class SignedProtocolRecord {
<<union>>
payload_bytes
signature
}
class MailboxRequest {
protocol_version
session_binding
request_id
session_capability
sandbox_credential_id
command_argv
justification
}
class MailboxCancellation {
protocol_version
session_binding
request_id
session_capability
sandbox_credential_id
}
class MailboxResultAck {
protocol_version
session_binding
request_id
request_sha256
session_capability
sandbox_credential_id
highest_contiguous_sequence
}
class DeveloperDecision {
protocol_version
session_binding
request_id
request_sha256
decision
approved_command_argv
}
class DeveloperDecisionKind {
<<enumeration>>
Approve
Deny
}
class MailboxResult {
protocol_version
session_binding
request_id
request_sha256
coordinator_credential_id
outcome
exit_code
chunk_count
stdout_sha256
stderr_sha256
}
class MailboxResultChunk {
protocol_version
session_binding
request_id
request_sha256
coordinator_credential_id
sequence
stream
bytes
}
class ResultStream {
<<enumeration>>
Stdout
Stderr
}
class EscalationOutcome {
<<enumeration>>
Completed
Denied
TimedOut
Cancelled
Failed
}
SignedProtocolRecord --> MailboxRequest
SignedProtocolRecord --> MailboxCancellation
SignedProtocolRecord --> MailboxResultAck
SignedProtocolRecord --> DeveloperDecision
SignedProtocolRecord --> MailboxResult
SignedProtocolRecord --> MailboxResultChunk
MailboxRequest --> SessionBinding
MailboxRequest --> SessionRequestCapability
MailboxCancellation --> SessionBinding
MailboxCancellation --> SessionRequestCapability
MailboxResultAck --> SessionBinding
MailboxResultAck --> SessionRequestCapability
DeveloperDecision --> SessionBinding
DeveloperDecision --> DeveloperDecisionKind
MailboxResult --> SessionBinding
MailboxResult --> EscalationOutcome
MailboxResultChunk --> SessionBinding
MailboxResultChunk --> ResultStream
```
`SessionCoordinator` is the logical protocol identity served physically by the
Host Coordinator. It is not a distinct Host Coordinator principal. Physical
encoding, signing, size, and validation rules are defined by the specification.
### Participant ownership

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.