Define protocol cryptography packaging

docs/schema.md

@@ -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
+it does not preserve stdout and stderr as separate channels.
-cryptographic envelopes and wire encoding are outside this schema.
+
+## 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
 

docs/specification.md

@@ -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. |
+| **Trust Anchor** | The ephemeral Domain-generation trust package containing separate TLS certificate-authority and protocol-credential issuer keys. |
-| **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. |
+| **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.