sandboxhostprotocol

package
v0.0.0-...-804b954 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package sandboxhostprotocol owns the private, bounded host-control wire contract. Public sandbox consumers never see host identities or envelopes.

Index

Constants

View Source 
const (
	// Version is the only currently accepted host-control protocol.
	Version = "sandbox.host-control/v1"
)

Variables

This section is empty.

Functions

func Digest 

func Digest(value []byte) string

Digest returns the canonical SHA-256 identity for bounded bytes.

func SignDataPlaneReceipt 

func SignDataPlaneReceipt(receipt DataPlaneReceipt, privateKey ed25519.PrivateKey) ([]byte, error)

SignDataPlaneReceipt signs one exact canonical reference-only receipt.

func SignEnvelope 

func SignEnvelope(envelope Envelope, keyID string, privateKey ed25519.PrivateKey) ([]byte, error)

SignEnvelope returns exact canonical bytes with an Ed25519 signature over the same object with Signature omitted.

func SignEnvelopeWithTrust 

func SignEnvelopeWithTrust(envelope Envelope, trust TrustBundle, privateKey ed25519.PrivateKey) ([]byte, error)

SignEnvelopeWithTrust binds a delivery to the current key version and revocation epoch of a validated trust snapshot.

func SignOutput 

func SignOutput(output Output, privateKey ed25519.PrivateKey) ([]byte, error)

SignOutput returns exact canonical host-signed output-header bytes.

func SignResult 

func SignResult(result Result, privateKey ed25519.PrivateKey) ([]byte, error)

SignResult returns exact canonical host-signed result bytes.

func ValidObservation 

func ValidObservation(observation *Observation) bool

ValidObservation reports whether observation is a complete bounded dynamic resource view. It is exposed for private host/guest transports that must reject malformed observations before a host signs them. It does not attest that an observation was produced by a real guest or host; that remains the responsibility of the authenticated execution path.

func ValidateAuthenticatedEnvelopeWire 

func ValidateAuthenticatedEnvelopeWire(wire []byte, expected Envelope) error

ValidateAuthenticatedEnvelopeWire proves that a downstream private hop was given the same canonical signed envelope which its caller already verified. It deliberately does not re-verify the signature (the caller owns trust keys); it prevents a verified envelope object from being rebound to another wire before a host-specific data plane consumes it.

Types

type AtomicTrust 

type AtomicTrust struct {
	// contains filtered or unexported fields
}

AtomicTrust owns one replace-only in-memory control trust snapshot.

func NewAtomicTrust 

func NewAtomicTrust(bundle TrustBundle) (*AtomicTrust, error)

NewAtomicTrust validates and retains an initial control trust snapshot.

func (*AtomicTrust) Snapshot 

func (trust *AtomicTrust) Snapshot() TrustBundle

Snapshot returns one immutable copy of the current trust snapshot.

func (*AtomicTrust) Update 

func (trust *AtomicTrust) Update(bundle TrustBundle) error

Update atomically replaces trust with a strictly newer, non-regressing revocation epoch. A key ID is immutable for this AtomicTrust instance; once it leaves a snapshot it is retired for the instance lifetime, and a newly introduced key must have a key version greater than every previously observed key. Readers observe either complete snapshot, never a mix. A process restart needs authenticated persisted trust history to preserve this lineage; the reference host does not implement that persistence.

type DataPlaneReceipt 

type DataPlaneReceipt struct {
	ProtocolVersion string `json:"protocol_version"`
	ReceiptID       string `json:"receipt_id"`
	HostID          string `json:"host_id"`
	HostGeneration  uint64 `json:"host_generation"`
	AssignmentID    string `json:"assignment_id"`
	LeaseEpoch      uint64 `json:"lease_epoch"`
	FencingToken    uint64 `json:"fencing_token"`
	OperationID     string `json:"operation_id"`
	Kind            string `json:"kind"`
	ReceiptDigest   string `json:"receipt_digest"`
	Signature       string `json:"signature"`
}

DataPlaneReceipt is one host-signed, reference-only terminal observation owned by private control. It carries only the digest of the private canonical metadata; the metadata stays in the host journal and never crosses control.

func VerifyDataPlaneReceipt 

func VerifyDataPlaneReceipt(wire []byte, publicKey ed25519.PublicKey) (DataPlaneReceipt, error)

VerifyDataPlaneReceipt strictly verifies one canonical host-signed terminal receipt. Callers must additionally bind it to their enrolled host identity.

type Envelope 

type Envelope struct {
	ProtocolVersion        string    `json:"protocol_version"`
	EnvelopeID             string    `json:"envelope_id"`
	DeliveryID             string    `json:"delivery_id"`
	Nonce                  string    `json:"nonce"`
	IssuedAt               time.Time `json:"issued_at"`
	ExpiresAt              time.Time `json:"expires_at"`
	ControlKeyID           string    `json:"control_key_id"`
	ControlKeyVersion      uint64    `json:"control_key_version"`
	ControlRevocationEpoch uint64    `json:"control_revocation_epoch"`
	HostID                 string    `json:"host_id"`
	HostGeneration         uint64    `json:"host_generation"`
	AssignmentID           string    `json:"assignment_id"`
	LeaseEpoch             uint64    `json:"lease_epoch"`
	FencingToken           uint64    `json:"fencing_token"`
	Tenant                 string    `json:"tenant"`
	Principal              string    `json:"principal"`
	SandboxID              string    `json:"sandbox_id"`
	ProcessID              string    `json:"process_id"`
	// VolumeID and SnapshotID carry only an admitted resource identity. They
	// never identify a host pathname, mount, snapshot payload, or backend
	// handle.
	VolumeID               string `json:"volume_id"`
	SnapshotID             string `json:"snapshot_id"`
	OperationID            string `json:"operation_id"`
	OperationKind          string `json:"operation_kind"`
	EffectiveSpecDigest    string `json:"effective_spec_digest"`
	CapabilityDigest       string `json:"capability_digest"`
	CanonicalRequestDigest string `json:"canonical_request_digest"`
	SequenceContract       string `json:"sequence_contract"`
	PayloadDigest          string `json:"payload_digest"`
	Payload                []byte `json:"payload"`
	Signature              string `json:"signature"`
}

Envelope is one immutable, control-signed assignment delivery.

func VerifyEnvelope 

func VerifyEnvelope(wire []byte, hostID string, generation uint64, now time.Time, keys map[string]ed25519.PublicKey) (Envelope, error)

VerifyEnvelope strictly decodes canonical bytes and verifies key, host, generation, validity interval, payload digest and Ed25519 signature.

func VerifyEnvelopeWithTrust 

func VerifyEnvelopeWithTrust(wire []byte, hostID string, generation uint64, now time.Time, trust TrustBundle) (Envelope, error)

VerifyEnvelopeWithTrust verifies an envelope only against the complete current/next snapshot and refuses keys, validity, or revocation epochs that are no longer trusted.

type FailureObservation 

type FailureObservation struct {
	Code  string `json:"code"`
	Retry string `json:"retry"`
}

FailureObservation is a finite safe failure classification. Message text is deliberately excluded because the host must not turn a backend error into a durable or public detail.

type GuestOutput 

type GuestOutput struct {
	Stream   string
	Sequence uint64
	Data     []byte
}

GuestOutput is one bounded guest chunk before the host signs and durably acknowledges its public-control metadata.

type GuestOutputEmitter 

type GuestOutputEmitter func(context.Context, GuestOutput) error

GuestOutputEmitter accepts one guest chunk at the host-control durability boundary.

type Observation 

type Observation struct {
	Sandbox SandboxObservation  `json:"sandbox"`
	Process *ProcessObservation `json:"process,omitempty"`
}

Observation is the bounded, signed dynamic portion of one resource view. It is a private host-control value: consumers must combine it only with control-owned admitted metadata for a durable SandboxInfo or ProcessInfo projection. It never carries argv, environment, output bytes, guest paths, backend handles, or an unbounded backend error.

type Output 

type Output struct {
	ProtocolVersion string    `json:"protocol_version"`
	OutputID        string    `json:"output_id"`
	HostID          string    `json:"host_id"`
	HostGeneration  uint64    `json:"host_generation"`
	AssignmentID    string    `json:"assignment_id"`
	LeaseEpoch      uint64    `json:"lease_epoch"`
	FencingToken    uint64    `json:"fencing_token"`
	Principal       string    `json:"principal"`
	OperationID     string    `json:"operation_id"`
	Stream          string    `json:"stream"`
	Sequence        uint64    `json:"sequence"`
	ChunkDigest     string    `json:"chunk_digest"`
	SizeBytes       uint32    `json:"size_bytes"`
	Chunk           []byte    `json:"chunk"`
	Redacted        bool      `json:"redacted"`
	ObservedAt      time.Time `json:"observed_at"`
	Signature       string    `json:"signature"`
}

Output is one host-signed bounded output sequence. Chunk is already redacted by the host output owner before it crosses the private control transport; control stores and replays exactly these signed bytes. It is deliberately bounded so a guest cannot make durable control storage unbounded.

func VerifyOutput 

func VerifyOutput(wire []byte, now time.Time, publicKey ed25519.PublicKey) (Output, error)

VerifyOutput strictly verifies canonical output metadata and its enrolled host signature. Durable sequence ownership remains in the control store.

type OutputRetention 

type OutputRetention struct {
	EarliestCursor string `json:"earliest_cursor"`
	RetainedBytes  uint64 `json:"retained_bytes"`
	Truncated      bool   `json:"truncated"`
}

OutputRetention records the bounded retained window for one stream.

type ProcessObservation 

type ProcessObservation struct {
	ID        string          `json:"id"`
	SandboxID string          `json:"sandbox_id"`
	State     string          `json:"state"`
	Result    *ProcessResult  `json:"result,omitempty"`
	Stdout    OutputRetention `json:"stdout"`
	Stderr    OutputRetention `json:"stderr"`
}

ProcessObservation is the host-observable dynamic state of one process. Result is present exactly for terminal process states; stdout and stderr are bounded retention facts, not output content.

type ProcessResult 

type ProcessResult struct {
	StartedAt  time.Time     `json:"started_at"`
	FinishedAt time.Time     `json:"finished_at"`
	ExitCode   *int32        `json:"exit_code,omitempty"`
	Signal     string        `json:"signal,omitempty"`
	Reason     string        `json:"reason"`
	Usage      ResourceUsage `json:"usage"`
	Cleanup    string        `json:"cleanup"`
}

ProcessResult is the finite terminal outcome observed by the host.

type PullRequest 

type PullRequest struct {
	ProtocolVersion string `json:"protocol_version"`
	Kind            string `json:"kind"`
	HostID          string `json:"host_id"`
	HostGeneration  uint64 `json:"host_generation"`
}

PullRequest is the canonical private host poll request accepted by control.

type ReceiptRequest 

type ReceiptRequest struct {
	ProtocolVersion string `json:"protocol_version"`
	Kind            string `json:"kind"`
	AssignmentID    string `json:"assignment_id"`
	FencingToken    uint64 `json:"fencing_token"`
	ReceiptDigest   string `json:"receipt_digest"`
}

ReceiptRequest is the canonical private host receipt acknowledgement.

type ResourceUsage 

type ResourceUsage struct {
	CPUTimeMillis   uint64 `json:"cpu_time_millis"`
	PeakMemoryBytes uint64 `json:"peak_memory_bytes"`
	ReadBytes       uint64 `json:"read_bytes"`
	WrittenBytes    uint64 `json:"written_bytes"`
}

ResourceUsage contains only monotonically bounded resource counters.

type Result 

type Result struct {
	ProtocolVersion     string    `json:"protocol_version"`
	ResultID            string    `json:"result_id"`
	HostID              string    `json:"host_id"`
	HostGeneration      uint64    `json:"host_generation"`
	AssignmentID        string    `json:"assignment_id"`
	LeaseEpoch          uint64    `json:"lease_epoch"`
	FencingToken        uint64    `json:"fencing_token"`
	Principal           string    `json:"principal"`
	OperationID         string    `json:"operation_id"`
	EffectiveSpecDigest string    `json:"effective_spec_digest"`
	CapabilityDigest    string    `json:"capability_digest"`
	State               string    `json:"state"`
	ObservedAt          time.Time `json:"observed_at"`
	// Observation is optional dynamic metadata directly observed by the
	// authenticated host. It intentionally excludes control-owned admitted
	// image, resource, capability, desired-state, and policy facts. The
	// omitempty tag preserves the canonical v1 wire for existing result
	// producers that have no observation source.
	Observation *Observation `json:"observation,omitempty"`
	Signature   string       `json:"signature"`
}

Result is one host-signed terminal or progress observation.

func VerifyResult 

func VerifyResult(wire []byte, now time.Time, publicKey ed25519.PublicKey) (Result, error)

VerifyResult strictly verifies canonical result bytes and the enrolled host signing key. Durable assignment checks remain control-store authority.

type SandboxObservation 

type SandboxObservation struct {
	ID          string              `json:"id"`
	ActualState string              `json:"actual_state"`
	Failure     *FailureObservation `json:"failure,omitempty"`
}

SandboxObservation is the host-observable dynamic state of one sandbox.

type SigningKey 

type SigningKey struct {
	ID        string
	Version   uint64
	PublicKey ed25519.PublicKey
	NotBefore time.Time
	NotAfter  time.Time
}

SigningKey is one versioned public control-signing authority. The private counterpart remains outside the trust bundle.

type TrustBundle 

type TrustBundle struct {
	Version         uint64
	RevocationEpoch uint64
	Current         SigningKey
	Next            *SigningKey
}

TrustBundle is an atomically applied current/next control-key snapshot. RevocationEpoch invalidates envelopes issued under an earlier epoch.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.