firecracker

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: 37 Imported by: 0

Documentation

Overview

Package firecracker owns the Linux/KVM-only, internal Firecracker host profile.

Index

Constants

View Source 
const GuestDataPlaneReceiptVersion = "agent-runtime.guest-data-plane-receipt/v1"

GuestDataPlaneReceiptVersion is the shared canonical version for private transfer and restore terminal receipts.

View Source 
const GuestMountOperationKind = "agent-runtime.guest-mount/v1"

GuestMountOperationKind identifies the private jailed-sharing command. It carries a mount lease identity only; host paths and share handles are absent.

View Source 
const (
	// GuestProxyOperationKind identifies the private, bounded AF_VSOCK proxy operation.
	GuestProxyOperationKind = "agent-runtime.guest-proxy/v1"
)
View Source 
const GuestSecretCommandOperationKind = "agent-runtime.guest-secret-command/v1"

GuestSecretCommandOperationKind identifies the private command shape that can request one contextual secret. It never carries a secret value.

View Source 
const GuestSnapshotRestoreOperationKind = "agent-runtime.guest-snapshot-restore/v1"

GuestSnapshotRestoreOperationKind identifies the private leased restore command. It names only a snapshot identity; no snapshot bytes are encoded.

View Source 
const GuestTransferOperationKind = "agent-runtime.guest-transfer/v1"

GuestTransferOperationKind identifies the private, reference-only workspace command. It is not a public sandbox API and never carries artifact bytes.

Variables

View Source 
var (
	// ErrFixtureLock means a fixture lock is incomplete or permits mutable provenance.
	ErrFixtureLock = errors.New("invalid Firecracker fixture lock")
	// ErrSmokeUnavailable means a protected-run host cannot prove a smoke prerequisite.
	ErrSmokeUnavailable = errors.New("Firecracker smoke harness unavailable")
)
View Source 
var (
	// ErrInvalidProfile means a declarative Firecracker host profile is unsafe or incomplete.
	ErrInvalidProfile = errors.New("invalid Firecracker host profile")
	// ErrArtifactIntegrity means a fixture differs from its declared immutable digest.
	ErrArtifactIntegrity = errors.New("firecracker fixture integrity check failed")
	// ErrCapabilityUnavailable means a requested profile has no certified Firecracker data plane.
	ErrCapabilityUnavailable = errors.New("firecracker capability is unavailable")
)

Functions

func CompileDirectSmokePlan 

func CompileDirectSmokePlan(config ProtectedSmokeConfig, fixtures FixtureSet) (Plan, JailerExecutionAuthority, error)

CompileDirectSmokePlan derives the same fixed no-NIC Firecracker smoke plan for the separately reviewed Talos direct-run authority. The jailer base is fixed here rather than taken from any command line or operator input.

func CompileProtectedSmokePlan 

func CompileProtectedSmokePlan(config ProtectedSmokeConfig, fixtures FixtureSet) (Plan, JailerExecutionAuthority, error)

CompileProtectedSmokePlan derives the fixed small protected-run plan and its Jailer authority from one verified fixture set. Every non-Jailer resource limit remains explicitly assigned to ExternalOwner; the protected runner must prove those owners before any resulting smoke evidence is accepted.

func DecodeAuthenticatedGuestDispatch 

func DecodeAuthenticatedGuestDispatch(frame []byte) (sandboxhostprotocol.Envelope, []byte, error)

DecodeAuthenticatedGuestDispatch returns the immutable envelope only when the private frame carries the exact same canonical control-signed wire. Signature/trust verification is deliberately performed at the host-control boundary before this frame is created.

func DecodeGuestDispatch 

func DecodeGuestDispatch(frame []byte) (sandboxhostprotocol.Envelope, error)

DecodeGuestDispatch accepts only one bounded canonical frame with matching payload digest.

func DecodeGuestProxyOpen 

func DecodeGuestProxyOpen(frame []byte) (sandboxauthority.ProxySessionRequest, error)

DecodeGuestProxyOpen accepts only the canonical bounded request returned by the guest after it has decoded the authenticated host-control operation.

func DecodeGuestSecretRequest 

func DecodeGuestSecretRequest(payload []byte) (sandboxauthority.SecretRequest, error)

DecodeGuestSecretRequest accepts one canonical secret-free request echo. It cannot carry a secret value or a caller-selected transport address.

func EncodeAuthenticatedGuestDispatch 

func EncodeAuthenticatedGuestDispatch(envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) ([]byte, error)

EncodeAuthenticatedGuestDispatch binds the exact control-signed canonical wire that host-process already verified to its private guest dispatch. The guest frame cannot substitute a different envelope beside that wire.

func EncodeGuestDispatch 

func EncodeGuestDispatch(envelope sandboxhostprotocol.Envelope) ([]byte, error)

EncodeGuestDispatch canonically bounds a verified host envelope before it crosses vsock.

func EncodeGuestProxyOpen 

func EncodeGuestProxyOpen(request sandboxauthority.ProxySessionRequest) ([]byte, error)

EncodeGuestProxyOpen binds the guest's AF_VSOCK open frame to exactly the request that was already signed in its host-control operation.

func EncodeGuestSecretRequest 

func EncodeGuestSecretRequest(request sandboxauthority.SecretRequest) ([]byte, error)

EncodeGuestSecretRequest produces the only canonical, secret-free request echo a guest may send before the host resolves a value for its sealed sink.

func EncodeGuestTerminalObservation 

func EncodeGuestTerminalObservation(observation GuestTerminalObservation) ([]byte, error)

EncodeGuestTerminalObservation produces a canonical bounded private frame. It intentionally has no sandbox-state, resource, output-retention, or cleanup fields because those are host-controlled facts.

func VerifyPlanArtifacts 

func VerifyPlanArtifacts(plan Plan, opener artifactOpener) error

VerifyPlanArtifacts checks all launch inputs before a Jailer or VMM process may start.

Types

type AuthenticatedGuestDispatchChannel 

type AuthenticatedGuestDispatchChannel interface {
	GuestDispatchChannel
	ExecuteAuthenticatedDispatch(context.Context, sandboxhostprotocol.Envelope, []byte) error
}

AuthenticatedGuestDispatchChannel carries the exact already-verified control-signed canonical envelope across the guest boundary.

type AuthenticatedGuestProxyChannel 

type AuthenticatedGuestProxyChannel interface {
	AuthenticatedGuestResultChannel
	ProxyAuthenticated(context.Context, sandboxhostprotocol.Envelope, []byte, *sandboxauthority.ProxySession, time.Time, sandboxauthority.Resolver, sandboxauthority.Dialer) (GuestDispatchResult, error)
}

AuthenticatedGuestProxyChannel is the private host-controlled egress extension. The host creates the exact lease session and owns DNS plus dial; the guest can neither substitute those dependencies nor open a tunnel.

type AuthenticatedGuestResultChannel 

type AuthenticatedGuestResultChannel interface {
	AuthenticatedGuestDispatchChannel
	DispatchAuthenticated(context.Context, sandboxhostprotocol.Envelope, []byte) (GuestDispatchResult, error)
}

AuthenticatedGuestResultChannel returns bounded authenticated guest output before its terminal result for a durable host-control owner.

type AuthenticatedGuestSecretChannel 

type AuthenticatedGuestSecretChannel interface {
	AuthenticatedGuestResultChannel
	DispatchAuthenticatedSecret(context.Context, sandboxhostprotocol.Envelope, []byte, *SecretExecutionAuthority, sandboxhostprotocol.GuestOutputEmitter) error
}

AuthenticatedGuestSecretChannel is the private extension that consumes a SecretExecutionAuthority only while an exact authenticated guest command is live. Implementations must not serialize Manager-held secret bytes into the host journal, output owner, or a new host-selected transport.

type BootInput 

type BootInput struct {
	VMID           string
	FixtureVersion string
}

BootInput is the validated immutable argument pair passed to rootfs /sbin/init.

func (BootInput) KernelArguments 

func (input BootInput) KernelArguments() []string

KernelArguments returns the closed kernel command-line argument sequence for this boot input.

type BuildProvenance 

type BuildProvenance struct {
	RecipePath        string         `json:"recipe_path"`
	SourceRevision    string         `json:"source_revision"`
	Toolchain         string         `json:"toolchain"`
	InputsMember      string         `json:"inputs_member"`
	InputsDigest      sandbox.Digest `json:"inputs_sha256"`
	InputsSizeBytes   uint64         `json:"inputs_size_bytes"`
	SBOMMember        string         `json:"sbom_member"`
	SBOMDigest        sandbox.Digest `json:"sbom_sha256"`
	SBOMSizeBytes     uint64         `json:"sbom_size_bytes"`
	Static            bool           `json:"static"`
	GuestAgentDigest  sandbox.Digest `json:"guest_agent_sha256,omitempty"`
	AttestationMember string         `json:"attestation_member,omitempty"`
}

BuildProvenance records the checked-in, reproducible inputs of a project-owned fixture output.

type CleanupProof 

type CleanupProof struct {
	Proved  bool     `json:"proved"`
	Removed []string `json:"removed,omitempty"`
	Reason  string   `json:"reason,omitempty"`
}

CleanupProof records only non-sensitive cleanup observations.

type CompiledM4IdentityVerifier 

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

CompiledM4IdentityVerifier compares a launch-grant identity to an opaque locally compiled M4 identity. It can be constructed only from CompileTrustedM4Identity output and performs no host effect.

func NewCompiledM4IdentityVerifier 

func NewCompiledM4IdentityVerifier(identity TrustedM4Identity) (CompiledM4IdentityVerifier, error)

NewCompiledM4IdentityVerifier seals one locally compiled M4 identity for a private host-control verifier.

func (CompiledM4IdentityVerifier) VerifyTrustedM4Identity 

func (verifier CompiledM4IdentityVerifier) VerifyTrustedM4Identity(candidate firecrackerlaunchgrant.TrustedM4Identity) error

VerifyTrustedM4Identity refuses a grant identity that differs from the exact locally compiled M4 identity.

type DirectLaunchOwnership 

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

DirectLaunchOwnership is the exclusive, durable owner of one direct-KVM foundation plan. It records verified create authority before a future composition may start a Jailer; it neither starts a process nor promotes a capability profile.

func OpenDirectLaunchOwnership 

func OpenDirectLaunchOwnership(path string, plan Plan) (*DirectLaunchOwnership, error)

OpenDirectLaunchOwnership opens one absolute, exclusively locked direct-KVM ownership journal and refuses a record that is not exact for plan.

func (*DirectLaunchOwnership) BindExec 

func (owner *DirectLaunchOwnership) BindExec(envelope sandboxhostprotocol.Envelope, wire []byte) error

BindExec accepts an exec request only when its exact sandbox, host owner, principal, and immutable authority facts match the recovered create record.

func (*DirectLaunchOwnership) ClaimCreate 

func (owner *DirectLaunchOwnership) ClaimCreate(envelope sandboxhostprotocol.Envelope, wire []byte) error

ClaimCreate durably binds the only valid create request to this exact foundation plan. It has no host side effect and leaves the plan unavailable.

func (*DirectLaunchOwnership) Close 

func (owner *DirectLaunchOwnership) Close() error

Close releases the one host-instance journal lock without deleting intent.

type EnvironmentCheck 

type EnvironmentCheck struct {
	Available bool   `json:"available"`
	Reason    string `json:"reason,omitempty"`
}

EnvironmentCheck records whether one required protected-runner prerequisite was verified.

type EnvironmentReport 

type EnvironmentReport struct {
	Available       bool             `json:"available"`
	Linux           EnvironmentCheck `json:"linux"`
	KVM             EnvironmentCheck `json:"kvm"`
	Jailer          EnvironmentCheck `json:"jailer"`
	CgroupV2        EnvironmentCheck `json:"cgroup_v2"`
	PinnedArtifacts EnvironmentCheck `json:"pinned_artifacts"`
	Reasons         []string         `json:"reasons"`
}

EnvironmentReport is retained by the KVM lane whenever the runner is unavailable.

func AssessEnvironment 

func AssessEnvironment(host environment, goos string, plan Plan) EnvironmentReport

AssessEnvironment verifies every prerequisite for one protected Firecracker runner. A readable /dev/kvm is not proof of usable KVM; the protected lane supplies that proof through its verifier.

func LocalEnvironmentReport 

func LocalEnvironmentReport(check func(string) error) EnvironmentReport

LocalEnvironmentReport probes the current host without starting a VMM and always fails closed without protected-runner proof.

type EvidenceResult 

type EvidenceResult string

EvidenceResult classifies an observed protected-run outcome. 

const (
	// EvidencePassed means the exact Linux/KVM smoke protocol completed.
	EvidencePassed EvidenceResult = "passed"
	// EvidenceBlocked means an unavailable prerequisite prevented a run.
	EvidenceBlocked EvidenceResult = "blocked"
	// ProofLevelLinuxKVME2E identifies only a real protected KVM run.
	ProofLevelLinuxKVME2E = "linux_kvm_e2e"
)

type ExternalJailerLimit 

type ExternalJailerLimit string

ExternalJailerLimit identifies a finite limit whose enforcement is outside Jailer authority. 

const (
	// ExternalJailerLimitRootDisk requires the Stack-owned root-overlay provisioner.
	ExternalJailerLimitRootDisk ExternalJailerLimit = "root-disk"
	// ExternalJailerLimitTmpfs requires the Stack-owned tmpfs provisioner.
	ExternalJailerLimitTmpfs ExternalJailerLimit = "tmpfs"
	// ExternalJailerLimitProcessCount requires a process-accounting owner because cgroup pids limits tasks, not processes.
	ExternalJailerLimitProcessCount ExternalJailerLimit = "process-count"
	// ExternalJailerLimitInodes requires the Stack-owned filesystem quota owner.
	ExternalJailerLimitInodes ExternalJailerLimit = "inodes"
	// ExternalJailerLimitFiles requires the Stack-owned filesystem quota owner.
	ExternalJailerLimitFiles ExternalJailerLimit = "files"
	// ExternalJailerLimitLifetime requires the Stack-owned lifecycle reaper.
	ExternalJailerLimitLifetime ExternalJailerLimit = "lifetime"
	// ExternalJailerLimitProducedOutput requires the core-owned output spool.
	ExternalJailerLimitProducedOutput ExternalJailerLimit = "produced-output"
	// ExternalJailerLimitRetainedOutput requires the core-owned output spool.
	ExternalJailerLimitRetainedOutput ExternalJailerLimit = "retained-output"
)

type ExternalJailerLimitOwner 

type ExternalJailerLimitOwner struct {
	Limit         ExternalJailerLimit
	StackResource string
}

ExternalJailerLimitOwner binds one limit outside Jailer authority to a reviewed Stack resource reference. This declaration is a prerequisite, not a claim that the referenced resource has been provisioned or verified.

type FirecrackerHTTPPort 

type FirecrackerHTTPPort interface {
	Bind(context.Context, string) error
	// WaitReady confirms that the exact bound Unix socket accepts a local
	// connection before the immutable REST sequence starts. A real Jailer
	// returns after spawning Firecracker, before Firecracker creates its API
	// socket, so treating Start as socket readiness races real KVM hosts.
	WaitReady(context.Context) error
	Put(context.Context, string, any) error
}

FirecrackerHTTPPort sends one bounded JSON request over the exact private Firecracker API socket.

type FixtureFetcher 

type FixtureFetcher interface {
	Open(context.Context, string) (FixtureResponse, error)
}

FixtureFetcher retrieves an immutable source without executing it.

type FixtureLock 

type FixtureLock struct {
	Version        string           `json:"version"`
	FixtureVersion string           `json:"fixture_version"`
	Sources        []LockedSource   `json:"sources"`
	Artifacts      []LockedArtifact `json:"artifacts"`
}

FixtureLock is a reviewed, complete fixture identity lock.

func ParseFixtureLock 

func ParseFixtureLock(reader io.Reader) (FixtureLock, error)

ParseFixtureLock reads one bounded, strict, complete fixture-lock document.

func (FixtureLock) Validate 

func (lock FixtureLock) Validate() error

Validate rejects partial, mutable, duplicate, or unlicensed fixture locks.

type FixtureName 

type FixtureName string

FixtureName identifies one non-interchangeable Firecracker fixture. 

const (
	// FixtureFirecracker identifies the Firecracker VMM executable.
	FixtureFirecracker FixtureName = "firecracker"
	// FixtureJailer identifies the Firecracker Jailer executable.
	FixtureJailer FixtureName = "jailer"
	// FixtureKernel identifies the admitted guest kernel.
	FixtureKernel FixtureName = "kernel"
	// FixtureRootFS identifies the admitted guest root filesystem.
	FixtureRootFS FixtureName = "rootfs"
	// FixtureGuestAgent identifies the project-owned static guest control program.
	FixtureGuestAgent FixtureName = "guest-agent"
)

type FixturePlatform 

type FixturePlatform struct {
	OS           string `json:"os"`
	Architecture string `json:"architecture"`
}

FixturePlatform records the operating-system and processor identity of a bootable fixture.

type FixtureResponse 

type FixtureResponse struct {
	Body          io.ReadCloser
	ContentLength int64
}

FixtureResponse is a non-executable immutable fixture response. ContentLength is -1 when the source did not declare one.

type FixtureSet 

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

FixtureSet contains fixtures that have been downloaded and completely verified.

func ProvisionFixtures 

func ProvisionFixtures(ctx context.Context, lock FixtureLock, fetcher FixtureFetcher, destination string) (FixtureSet, error)

ProvisionFixtures downloads every locked fixture to private staging and only returns after all size and digest checks pass.

func (FixtureSet) Artifact 

func (set FixtureSet) Artifact(name FixtureName) (PinnedArtifact, bool)

Artifact returns one verified fixture identity.

func (FixtureSet) Directory 

func (set FixtureSet) Directory() string

Directory returns the private staging directory containing verified fixtures.

func (FixtureSet) FixtureVersion 

func (set FixtureSet) FixtureVersion() string

FixtureVersion returns the immutable fixture identity that the guest must report at boot.

func (FixtureSet) Names 

func (set FixtureSet) Names() []FixtureName

Names returns the complete fixture set in deterministic order.

type FixtureSourceFormat 

type FixtureSourceFormat string

FixtureSourceFormat describes how artifacts are derived from a verified source. 

const (
	// FixtureSourceFile identifies a source containing exactly one artifact.
	FixtureSourceFile FixtureSourceFormat = "file"
	// FixtureSourceTarGzip identifies a gzip-compressed tar source bundle.
	FixtureSourceTarGzip FixtureSourceFormat = "tar.gz"
)

type FixtureSourceKind 

type FixtureSourceKind string

FixtureSourceKind identifies the immutable identity scheme used by one source. 

const (
	// FixtureSourceReleaseArchive identifies a versioned upstream release archive.
	FixtureSourceReleaseArchive FixtureSourceKind = "release-archive"
	// FixtureSourceVersionedObject identifies an immutable object-store object version.
	FixtureSourceVersionedObject FixtureSourceKind = "versioned-object"
	// FixtureSourceProjectBuild identifies an output rebuilt from one project commit.
	FixtureSourceProjectBuild FixtureSourceKind = "project-build"
	// FixtureSourceProjectReleaseAsset identifies a project-controlled immutable
	// release asset retained verbatim from an independently reviewed upstream
	// input. It is deliberately limited to the kernel fixture: unlike project
	// build bundles it has no build recipe or generated provenance to assert.
	FixtureSourceProjectReleaseAsset FixtureSourceKind = "project-release-asset"
)

type GuestControlChannel 

type GuestControlChannel interface {
	Bind(context.Context, string) error
	Ping(context.Context, string) error
	Close(context.Context) error
}

GuestControlChannel carries the private guest-control transport. Concrete AF_VSOCK composition remains profile-gated and unavailable until its Linux/KVM authority/evidence requirements are met.

type GuestDispatch 

type GuestDispatch struct {
	Version               string                       `json:"version"`
	Envelope              sandboxhostprotocol.Envelope `json:"envelope"`
	AuthenticatedEnvelope []byte                       `json:"authenticated_envelope,omitempty"`
}

GuestDispatch is the bounded private vsock frame that carries one already verified and fenced host envelope. It contains no host paths or secret bytes.

type GuestDispatchCanceller 

type GuestDispatchCanceller interface {
	CancelDispatch(context.Context, sandboxhostprotocol.Envelope) error
}

GuestDispatchCanceller is the private cancellation extension of the bounded guest operation protocol. It is separate from Close so a live guest can reap one fenced operation before the host must reap the entire Jailer.

type GuestDispatchChannel 

type GuestDispatchChannel interface {
	GuestControlChannel
	ExecuteDispatch(context.Context, sandboxhostprotocol.Envelope) error
}

GuestDispatchChannel is the private guest-operation extension point. A production implementation may be composed only after its profile's exact capability has been certified; this repository currently binds no such implementation.

type GuestDispatchResult 

type GuestDispatchResult struct {
	State            string
	Outputs          []GuestOutput
	GuestObservation *GuestTerminalObservation
	Observation      *sandboxhostprotocol.Observation
}

GuestDispatchResult records the only terminal result accepted from a guest dispatch exchange and the bounded output that preceded it.

type GuestIdentityBinder 

type GuestIdentityBinder interface {
	BindGuestIdentity(context.Context, string, string) error
}

GuestIdentityBinder binds the boot identities that the guest must echo on every private vsock connection. A host obtains those values only from the immutable launch request and verified fixture stage.

type GuestMountCommand 

type GuestMountCommand struct {
	Version      string `json:"version"`
	MountID      string `json:"mount_id"`
	Generation   uint64 `json:"generation"`
	FencingToken uint64 `json:"fencing_token"`
}

GuestMountCommand binds a pre-acquired mount lease to the current host fence. It cannot select a source path, daemon endpoint, or guest target.

func DecodeGuestMountCommand 

func DecodeGuestMountCommand(payload []byte) (GuestMountCommand, error)

DecodeGuestMountCommand accepts only one canonical lease/fence request.

type GuestOutput 

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

GuestOutput is one bounded, ordered private guest-output chunk. Its caller must route it to a durable output owner before any future profile can claim command-output delivery.

type GuestProxyPayload 

type GuestProxyPayload struct {
	Version string                               `json:"version"`
	Request sandboxauthority.ProxySessionRequest `json:"request"`
	Input   []byte                               `json:"input"`
}

GuestProxyPayload is the only bounded guest egress shape permitted inside a control-signed operation. It contains one lease-bound domain request and at most one finite byte sequence, not a guest-selected socket or tunnel.

func DecodeGuestProxyPayload 

func DecodeGuestProxyPayload(payload []byte) (GuestProxyPayload, error)

DecodeGuestProxyPayload accepts only one canonical bounded proxy payload.

type GuestSecretCommand 

type GuestSecretCommand struct {
	Version string                         `json:"version"`
	Command json.RawMessage                `json:"command"`
	Secret  sandboxauthority.SecretRequest `json:"secret"`
}

GuestSecretCommand is the canonical secret-free command authorization sent across the private guest boundary. Command is the bounded typed command JSON interpreted only by the guest runner after its secret lifecycle is active.

func DecodeGuestSecretCommand 

func DecodeGuestSecretCommand(payload []byte) (GuestSecretCommand, error)

DecodeGuestSecretCommand accepts only one canonical secret-free command authorization. Secret bytes have no representation in this payload.

type GuestSnapshotRestoreCommand 

type GuestSnapshotRestoreCommand struct {
	Version      string                                 `json:"version"`
	FencingToken uint64                                 `json:"fencing_token"`
	Request      sandboxresource.SnapshotRestoreRequest `json:"request"`
}

GuestSnapshotRestoreCommand binds an admitted store restore request to the host-control fencing token, preventing an old lease delivery from rebinding.

func DecodeGuestSnapshotRestoreCommand 

func DecodeGuestSnapshotRestoreCommand(payload []byte) (GuestSnapshotRestoreCommand, error)

DecodeGuestSnapshotRestoreCommand accepts only one canonical, reference-only leased request and rejects a raw payload or caller-selected destination.

type GuestTerminalObservation 

type GuestTerminalObservation struct {
	ProcessID  string    `json:"process_id,omitempty"`
	GuestPID   int       `json:"guest_pid"`
	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"`
}

GuestTerminalObservation is the deliberately small set of terminal facts a guest process can report about itself. It is not a SandboxObservation: the guest cannot truthfully establish host lifecycle state, cgroup usage, retention, cleanup, or the durable control-plane process state. A host may use this private input when it constructs its own observation, but must not promote it directly to a signed resource view.

type GuestTransferCommand 

type GuestTransferCommand struct {
	Version   string                  `json:"version"`
	CopyIn    *sandbox.CopyInRequest  `json:"copy_in,omitempty"`
	ArchiveIn *sandbox.CopyInRequest  `json:"archive_in,omitempty"`
	CopyOut   *sandbox.CopyOutRequest `json:"copy_out,omitempty"`
}

GuestTransferCommand is one canonical transfer direction bound to the same process, operation, fence, and expiry as its authenticated host envelope. Exactly one request is present. Neither request has a representation for bytes: copy-in/archive-in names an immutable source and copy-out returns a reference. Archive-in is deliberately a separate command arm so a regular file cannot silently acquire directory-materialization authority.

func DecodeGuestTransferCommand 

func DecodeGuestTransferCommand(payload []byte) (GuestTransferCommand, error)

DecodeGuestTransferCommand accepts one exact canonical reference-only command. Unknown fields, both directions, raw bytes, and invalid paths are refused before the data plane is touched.

type HostProcessExecutor 

type HostProcessExecutor struct {
	Host     *LinuxJailerHost
	Secrets  *SecretExecutionAuthority
	Egress   *ProxyAuthorityIssuer
	Transfer *TransferExecutionAuthority
	Restore  *SnapshotRestoreExecutionAuthority
	Mount    *MountExecutionAuthority
	// Ownership is the optional durable direct-KVM foundation-plan owner. It
	// never certifies availability or starts a Jailer; when composed it binds
	// verified create and exec deliveries before this adapter reaches a host.
	Ownership *DirectLaunchOwnership
}

HostProcessExecutor adapts the authenticated sandbox-host-process executor seam to one LinuxJailerHost. Envelope signature/trust verification and the durable started/uncertain journal remain owned by sandboxhostprocess; this adapter receives only a verified fenced Envelope.

func UnavailableHostProcessExecutor 

func UnavailableHostProcessExecutor() HostProcessExecutor

UnavailableHostProcessExecutor binds the public host-control runtime to the Firecracker authority adapter before an operator has supplied a reviewed Linux Jailer composition. It is deliberately useful only as a fail-closed control/recovery owner: the empty host cannot launch, dispatch, or promote a capability profile.

func (HostProcessExecutor) Execute 

func (executor HostProcessExecutor) Execute(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

Execute hands an already-verified envelope to the sole Firecracker guest-dispatch gate.

func (HostProcessExecutor) ExecuteAuthenticated 

func (executor HostProcessExecutor) ExecuteAuthenticated(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) error

ExecuteAuthenticated preserves the exact control-signed canonical delivery that sandboxhostprocess already trust-verified before guest dispatch.

func (HostProcessExecutor) ExecuteAuthenticatedMount 

func (executor HostProcessExecutor) ExecuteAuthenticatedMount(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, emit MountReceiptEmitter) (MountReceipt, error)

ExecuteAuthenticatedMount is the private host-control door for one exact jailed sharing lease. LinuxJailerHost keeps it unavailable until the daemon profile has protected Linux/KVM evidence.

func (HostProcessExecutor) ExecuteAuthenticatedSnapshotRestore 

func (executor HostProcessExecutor) ExecuteAuthenticatedSnapshotRestore(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, emit TransferReceiptEmitter) (TransferReceipt, error)

ExecuteAuthenticatedSnapshotRestore is the corresponding private resource restore door. The store/sink remain fixed at construction and profile-gated.

func (HostProcessExecutor) ExecuteAuthenticatedTransfer 

func (executor HostProcessExecutor) ExecuteAuthenticatedTransfer(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, emit TransferReceiptEmitter) (TransferReceipt, error)

ExecuteAuthenticatedTransfer is the private control-to-host data-plane door. It accepts only the original authenticated envelope, returns no bytes, and remains profile-gated until protected guest evidence exists.

func (HostProcessExecutor) ExecuteAuthenticatedWithDataPlaneReceipt 

func (executor HostProcessExecutor) ExecuteAuthenticatedWithDataPlaneReceipt(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, emit func(context.Context, string, []byte) error) error

ExecuteAuthenticatedWithDataPlaneReceipt preserves the exact signed control wire while selecting one fixed transfer, restore, or sharing authority.

func (HostProcessExecutor) ExecuteAuthenticatedWithOutput 

func (executor HostProcessExecutor) ExecuteAuthenticatedWithOutput(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, emit sandboxhostprotocol.GuestOutputEmitter) error

ExecuteAuthenticatedWithOutput preserves exact control trust and forwards each stdout/stderr chunk before allowing the durable terminal path to run.

func (HostProcessExecutor) ExecuteWithDataPlaneReceipt 

func (executor HostProcessExecutor) ExecuteWithDataPlaneReceipt(ctx context.Context, envelope sandboxhostprotocol.Envelope, emit func(context.Context, string, []byte) error) error

ExecuteWithDataPlaneReceipt dispatches only a private reference-only data plane operation. The host-process owner signs and acknowledges the emitted receipt before it may stage a generic terminal result.

func (HostProcessExecutor) ExecuteWithOutput 

func (executor HostProcessExecutor) ExecuteWithOutput(ctx context.Context, envelope sandboxhostprotocol.Envelope, emit sandboxhostprotocol.GuestOutputEmitter) error

ExecuteWithOutput forwards only stdout/stderr chunks to sandboxhostprocess, which signs, journals, and acknowledges them before terminal completion.

func (HostProcessExecutor) ReapAuthenticated 

func (executor HostProcessExecutor) ReapAuthenticated(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) error

ReapAuthenticated converges only the exact already-verified control command after a cancellation or a failed guest exchange. It is intentionally conservative: an unavailable profile may refuse cleanup, but it can never receive an altered envelope, a different lease, or a different fence.

func (HostProcessExecutor) ReapAuthenticatedMount 

func (executor HostProcessExecutor) ReapAuthenticatedMount(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

ReapAuthenticatedMount lets the durable host/reaper owner converge an exact prior mount command after cancellation, host loss, or a lost control ack. It deliberately does not require an available profile: cleanup must remain possible even when capability certification is withdrawn.

func (HostProcessExecutor) ReapAuthenticatedSnapshotRestore 

func (executor HostProcessExecutor) ReapAuthenticatedSnapshotRestore(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

ReapAuthenticatedSnapshotRestore converges the fixed guest sink and exact snapshot lease after cancellation, a process crash, or terminal delivery. Like mount cleanup, it stays callable while profiles are unavailable: a withdrawn capability must never strand an already-started protected sink.

type JailedFixtureBinding 

type JailedFixtureBinding struct {
	Source     PinnedArtifact
	JailedPath string
}

JailedFixtureBinding maps one verified source identity to its path inside one Jailer chroot.

type JailedResourceStage 

type JailedResourceStage struct {
	FixtureVersion string
	JailRoot       string
	OwnerUID       uint32
	OwnerGID       uint32
	Jailer         PinnedArtifact
	Firecracker    JailedFixtureBinding
	Kernel         JailedFixtureBinding
	RootFS         JailedFixtureBinding
	GuestAgent     PinnedArtifact
	GuestInitPath  string
	APISocketPath  string
	VSockUDSPath   string
	BindingDigest  sandbox.Digest
}

JailedResourceStage records the complete, identity-bound mapping from verified sources to one Jailer chroot.

type JailedShareRequest 

type JailedShareRequest struct {
	SandboxID  string
	MountID    string
	Generation uint64
	Source     sandboxresource.SourceIdentity
	Target     string
	Mode       sandboxresource.AttachmentMode
	View       string
}

JailedShareRequest contains the exact source identity and guest-visible target a daemon may attach. There is intentionally no host path field.

type JailedSharingDaemon 

type JailedSharingDaemon interface {
	Attach(context.Context, JailedShareRequest) error
	Detach(context.Context, JailedShareRequest) error
}

JailedSharingDaemon is the only future mount data-plane seam. Attach and Detach must be idempotent for one exact request so a host reaper can converge after crash, cancellation, or a lost control acknowledgement.

type JailerCgroupAssignment 

type JailerCgroupAssignment struct {
	Version       string
	StackResource string
	Parent        string
}

JailerCgroupAssignment names the Stack-owned, delegated cgroup parent that a Jailer may use. Compiling this value neither creates the parent nor proves the parent has enabled controllers.

type JailerExecutionAuthority 

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

JailerExecutionAuthority is an immutable, exact Jailer invocation bound to one compiled plan. It carries only Jailer-enforceable controls and names every required external resource owner.

func CompileJailerExecutionAuthority 

func CompileJailerExecutionAuthority(plan Plan, assignment JailerCgroupAssignment, external []ExternalJailerLimitOwner) (JailerExecutionAuthority, error)

CompileJailerExecutionAuthority binds a verified Plan to a Stack-delegated cgroup and exact Jailer-owned limits. It fails closed until each non-Jailer limit has a named external owner; it does not start Jailer or provision cgroups.

func (JailerExecutionAuthority) Arguments 

func (authority JailerExecutionAuthority) Arguments() []string

Arguments returns a defensive copy of the complete Jailer argument vector.

func (JailerExecutionAuthority) CgroupParent 

func (authority JailerExecutionAuthority) CgroupParent() string

CgroupParent returns the Stack-delegated parent cgroup relative to the unified hierarchy.

func (JailerExecutionAuthority) CgroupPath 

func (authority JailerExecutionAuthority) CgroupPath() string

CgroupPath returns the exact per-VM cgroup path relative to the unified hierarchy.

func (JailerExecutionAuthority) CgroupStackResource 

func (authority JailerExecutionAuthority) CgroupStackResource() string

CgroupStackResource returns the declared Stack resource responsible for the delegated parent cgroup.

func (JailerExecutionAuthority) ExternalLimitOwners 

func (authority JailerExecutionAuthority) ExternalLimitOwners() []ExternalJailerLimitOwner

ExternalLimitOwners returns defensive copies of the Stack dependencies that Jailer cannot enforce.

type JailerProcess 

type JailerProcess interface {
	Terminate(context.Context) error
	Wait(context.Context) error
	Cleanup(context.Context) (CleanupProof, error)
}

JailerProcess owns the running Jailer and its exact per-VM cleanup.

type JailerResourceDiscarder 

type JailerResourceDiscarder interface {
	Discard(context.Context, Plan, JailedResourceStage) (CleanupProof, error)
}

JailerResourceDiscarder removes the exact fresh namespace returned by Stage when no Jailer process has taken ownership.

type JailerResourceStager 

type JailerResourceStager interface {
	Stage(context.Context, Plan, FixtureSet, string) (JailedResourceStage, error)
}

JailerResourceStager creates one per-VM jailed resource mapping before the Jailer process starts.

type JailerSerialObserver 

type JailerSerialObserver interface {
	AwaitSerial(context.Context, string) error
}

JailerSerialObserver observes the exact bounded serial stream owned by one started Jailer process.

type JailerStartRequest 

type JailerStartRequest struct {
	Authority JailerExecutionAuthority
	Stage     JailedResourceStage
}

JailerStartRequest is the complete immutable authority and staged-resource binding for one Jailer process.

type JailerStarter 

type JailerStarter interface {
	Start(context.Context, JailerStartRequest) (JailerProcess, error)
}

JailerStarter starts the Jailer only after the host has validated every launch prerequisite.

type JailerStartupDiagnostic 

type JailerStartupDiagnostic string

JailerStartupDiagnostic is a fixed, safe-to-retain classification of the Jailer/Firecracker startup boundary. 

const (
	JailerStartupDiagnosticUnavailable       JailerStartupDiagnostic = "unavailable"
	JailerStartupDiagnosticStillRunning      JailerStartupDiagnostic = "still-running"
	JailerStartupDiagnosticExited            JailerStartupDiagnostic = "exited"
	JailerStartupDiagnosticAPIInitialization JailerStartupDiagnostic = "api-initialization-failed"
	JailerStartupDiagnosticKVMInitialization JailerStartupDiagnostic = "kvm-initialization-failed"
	JailerStartupDiagnosticPermissionDenied  JailerStartupDiagnostic = "permission-denied"
)

type JailerStartupDiagnosticObserver 

type JailerStartupDiagnosticObserver interface {
	StartupDiagnostic() JailerStartupDiagnostic
}

JailerStartupDiagnosticObserver exposes one redacted, fixed startup result after a Jailer has been started. It never exposes command arguments, host paths, or captured process output. The smoke command uses this only to distinguish an absent Firecracker API socket from an exited Jailer process.

type KVMPreflight 

type KVMPreflight struct {
	GOOS               string `json:"goos"`
	GOARCH             string `json:"goarch"`
	KVMCharacterDevice bool   `json:"kvm_character_device"`
	KVMReadWrite       bool   `json:"kvm_read_write"`
	CgroupV2           bool   `json:"cgroup_v2"`
}

KVMPreflight captures the non-secret, necessary host observations before a protected run.

func InspectLocalKVMPreflight 

func InspectLocalKVMPreflight() KVMPreflight

InspectLocalKVMPreflight performs only environment inspection; it does not launch a VMM.

func (KVMPreflight) Validate 

func (preflight KVMPreflight) Validate() error

Validate rejects every environment other than an actual Linux x86_64 KVM and cgroups-v2 host.

type LaunchRequest 

type LaunchRequest struct {
	JailerPath        string
	JailerArguments   []string
	RootFSCopyPath    string
	CgroupVersion     uint8
	NetworkInterfaces uint8
	SerialMarker      string
	Boot              BootInput
	KernelArguments   []string
}

LaunchRequest is the complete no-NIC Jailer request passed to a protected host implementation.

func NewLaunchRequest 

func NewLaunchRequest(plan Plan, rootFSCopyPath string, boot BootInput) (LaunchRequest, error)

NewLaunchRequest freezes the exact Jailer argv and deny-all launch configuration for one verified rootfs copy.

type LinuxJailedSharingDaemon 

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

LinuxJailedSharingDaemon mounts only descriptor-pinned operator exports into one already-created Jailer mount namespace. It is not a capability profile; LinuxJailerHost keeps this data plane unavailable until protected evidence.

func NewLinuxJailedSharingDaemon 

func NewLinuxJailedSharingDaemon(exports []LinuxShareExport, namespacePath, guestRootPath string) (*LinuxJailedSharingDaemon, error)

NewLinuxJailedSharingDaemon opens every trusted export and target namespace once. The retained descriptors close path-replacement windows between lease observation and the eventual bind mount.

func (*LinuxJailedSharingDaemon) Attach 

func (daemon *LinuxJailedSharingDaemon) Attach(ctx context.Context, request JailedShareRequest) error

Attach resolves both source and target through retained descriptors, then performs a bind mount only while this OS thread is in the Jailer namespace.

func (*LinuxJailedSharingDaemon) Close 

func (daemon *LinuxJailedSharingDaemon) Close() error

Close releases only daemon-held descriptors after the reaper has detached every exact share. It refuses a live attach so cleanup cannot lose authority.

func (*LinuxJailedSharingDaemon) Detach 

func (daemon *LinuxJailedSharingDaemon) Detach(ctx context.Context, request JailedShareRequest) error

Detach removes only the exact target selected by a previously validated request. Repeating the same reaper action is safe; a different tuple cannot detach it.

func (*LinuxJailedSharingDaemon) ObserveMountSource 

func (daemon *LinuxJailedSharingDaemon) ObserveMountSource(ctx context.Context, exportID string) (sandboxresource.SourceIdentity, error)

ObserveMountSource re-stats the pinned descriptor instead of reopening an export path, so a replacement cannot become a later mount source.

type LinuxJailerHost 

type LinuxJailerHost struct {
	PreflightState KVMPreflight
	RootFSCopyPath string
	Resources      JailerResourceStager
	Authority      JailerExecutionAuthority
	Jailer         JailerStarter
	HTTP           FirecrackerHTTPPort
	Guest          GuestControlChannel
	// contains filtered or unexported fields
}

LinuxJailerHost is the Linux/KVM-only SmokeHost adapter composed from real host ports.

func NewLinuxJailerHost 

func NewLinuxJailerHost(config LinuxJailerHostConfig) (*LinuxJailerHost, error)

NewLinuxJailerHost composes the reviewed resource stager, Jailer starter, fixed private Unix REST port, and fixed private guest-vsock transport. The resulting host stays unavailable until profile-specific Linux/KVM evidence. It validates immutable authority before construction but leaves all host I/O to the explicit SmokeHost lifecycle.

func (*LinuxJailerHost) AwaitSerial 

func (host *LinuxJailerHost) AwaitSerial(ctx context.Context, marker string) error

AwaitSerial observes the exact immutable guest marker through the injected guest channel.

func (*LinuxJailerHost) CancelDispatch 

func (host *LinuxJailerHost) CancelDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

CancelDispatch forwards a lease-fenced cancellation only to the exact running guest selected by the immutable compiled plan. It is intentionally unavailable until a future certified guest profile composes a cancellation channel; cleanup still closes the whole channel before reaping the Jailer.

func (*LinuxJailerHost) Cleanup 

func (host *LinuxJailerHost) Cleanup(ctx context.Context) (CleanupProof, error)

Cleanup closes guest control and delegates Jailer termination, wait, and exact resource proof to the process port.

func (*LinuxJailerHost) Control 

func (host *LinuxJailerHost) Control(ctx context.Context) error

Control sends the guest protocol's bounded PING through the injected private vsock channel.

func (*LinuxJailerHost) DispatchAuthenticated 

func (host *LinuxJailerHost) DispatchAuthenticated(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) (GuestDispatchResult, error)

DispatchAuthenticated returns only the bounded result/output exchange from the exact launched guest. It remains unavailable until protected profile evidence permits real guest execution.

func (*LinuxJailerHost) DispatchAuthenticatedMount 

func (host *LinuxJailerHost) DispatchAuthenticatedMount(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, authority *MountExecutionAuthority, emit MountReceiptEmitter) (MountReceipt, error)

DispatchAuthenticatedMount is the future profile-gated path from a verified host envelope to the strict sharing daemon authority. It rejects all mounts until the exact jailed daemon and protected no-escape proof are available.

func (*LinuxJailerHost) DispatchAuthenticatedProxy 

func (host *LinuxJailerHost) DispatchAuthenticatedProxy(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, issuer *ProxyAuthorityIssuer) (GuestDispatchResult, error)

DispatchAuthenticatedProxy is the only future egress composition door. It accepts a narrow host-control issuer which must bind the same no-route topology, plan, lease, DNS request, and fence before it can create a session. It remains unavailable until the no-route profile has protected evidence.

func (*LinuxJailerHost) DispatchAuthenticatedSecret 

func (host *LinuxJailerHost) DispatchAuthenticatedSecret(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, authority *SecretExecutionAuthority, emit sandboxhostprotocol.GuestOutputEmitter) error

DispatchAuthenticatedSecret is the only future Firecracker secret-command composition door. It remains unavailable until the same protected profile can prove guest PID/FD/proc/ptrace/tree-reap containment.

func (*LinuxJailerHost) DispatchAuthenticatedSnapshotRestore 

func (host *LinuxJailerHost) DispatchAuthenticatedSnapshotRestore(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, authority *SnapshotRestoreExecutionAuthority, emit TransferReceiptEmitter) (TransferReceipt, error)

DispatchAuthenticatedSnapshotRestore is the profile-gated private resource restore bridge. It can move only a verified store reader into its fixed sink and returns only a durable snapshot identity receipt.

func (*LinuxJailerHost) DispatchAuthenticatedTransfer 

func (host *LinuxJailerHost) DispatchAuthenticatedTransfer(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, authority *TransferExecutionAuthority, emit TransferReceiptEmitter) (TransferReceipt, error)

DispatchAuthenticatedTransfer is the future profile-gated bridge from an exact authenticated host envelope into a descriptor-rooted transfer authority. It has no host-share or raw-byte API and stays unavailable until a protected guest profile has the exact evidence to consume it.

func (*LinuxJailerHost) ExecuteAuthenticatedDispatch 

func (host *LinuxJailerHost) ExecuteAuthenticatedDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) error

ExecuteAuthenticatedDispatch is the host-process-only guest path. It uses the exact control-signed wire retained through verification so the private guest frame cannot be rebound to a different lease-fenced envelope.

func (*LinuxJailerHost) ExecuteDispatch 

func (host *LinuxJailerHost) ExecuteDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

ExecuteDispatch is the only Firecracker handoff for an already authenticated and fenced host envelope. It fails closed while every Firecracker authority descriptor remains unavailable and never lets a guest select capabilities.

func (*LinuxJailerHost) Launch 

func (host *LinuxJailerHost) Launch(ctx context.Context, request LaunchRequest) error

Launch starts the Jailer and configures only the no-NIC Firecracker REST sequence.

func (*LinuxJailerHost) NoRouteProxyTopologyManifest 

func (host *LinuxJailerHost) NoRouteProxyTopologyManifest() (NoRouteProxyTopologyManifest, bool)

NoRouteProxyTopologyManifest returns the fixed unavailable-profile topology configuration when the host was explicitly composed with one. It is not evidence of an applied no-NIC/no-route guest topology or permitted egress.

func (*LinuxJailerHost) Preflight 

func (host *LinuxJailerHost) Preflight(ctx context.Context, plan Plan, fixtures FixtureSet) error

Preflight rejects all missing Linux/KVM, fixture, plan, resource-stage, and port prerequisites before launch.

func (*LinuxJailerHost) Prepare 

func (host *LinuxJailerHost) Prepare(ctx context.Context, plan Plan, fixtures FixtureSet) (LaunchRequest, error)

Prepare stages one verified jailed mapping and binds the verified fixture version and VM ID into init arguments.

func (*LinuxJailerHost) SecretContainmentManifest 

func (host *LinuxJailerHost) SecretContainmentManifest() (SecretContainmentManifest, bool)

SecretContainmentManifest returns the fixed unavailable-profile launch configuration when the host was explicitly composed with one. It is only a configuration/refusal record: callers must not interpret it as proof that a guest mounted the area or `/proc`, created the cgroup, excluded snapshots, or enforced ptrace isolation.

type LinuxJailerHostConfig 

type LinuxJailerHostConfig struct {
	Plan              Plan
	PreflightState    KVMPreflight
	RootFSCopyPath    string
	Authority         JailerExecutionAuthority
	SecretContainment *SecretContainmentManifest
	NoRouteProxy      *NoRouteProxyTopologyManifest
	UnixDialer        unixSocketDialer
}

LinuxJailerHostConfig is the complete reviewed composition input for one Linux Jailer host. Constructing it neither starts a Jailer nor verifies Linux/KVM execution.

type LinuxJailerResourceStager 

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

LinuxJailerResourceStager creates one fresh, fixture-bound Jailer namespace without starting a process.

func (LinuxJailerResourceStager) Discard 

func (stager LinuxJailerResourceStager) Discard(ctx context.Context, plan Plan, stage JailedResourceStage) (CleanupProof, error)

Discard removes only the fresh per-VM namespace returned by Stage before a Jailer process owns it.

func (LinuxJailerResourceStager) Stage 

func (stager LinuxJailerResourceStager) Stage(ctx context.Context, plan Plan, fixtures FixtureSet, rootFSCopyPath string) (stage JailedResourceStage, err error)

Stage verifies immutable fixture inputs, copies only the jailed kernel and private rootfs, and returns their exact Jailer mapping.

type LinuxJailerStarter 

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

LinuxJailerStarter starts a checked Linux Jailer process from a compiled execution authority and bound resource stage. It is an internal process port and does not itself provide protected-runner, Jailer, or KVM execution evidence.

func (LinuxJailerStarter) Start 

func (starter LinuxJailerStarter) Start(ctx context.Context, request JailerStartRequest) (JailerProcess, error)

Start launches only the Jailer executable, argument vector, cgroup path, and jail namespace bound in request.

type LinuxShareExport 

type LinuxShareExport struct {
	Path   string
	Source sandboxresource.SourceIdentity
}

LinuxShareExport is one operator-configured directory held open by the sharing daemon. Callers receive only its stable SourceIdentity, never Path.

type LockedArtifact 

type LockedArtifact struct {
	Name      FixtureName      `json:"name"`
	SourceID  string           `json:"source_id"`
	Member    string           `json:"member,omitempty"`
	Digest    sandbox.Digest   `json:"sha256"`
	SizeBytes uint64           `json:"size_bytes"`
	License   string           `json:"license"`
	Platform  FixturePlatform  `json:"platform"`
	Build     *BuildProvenance `json:"build,omitempty"`
}

LockedArtifact records immutable provenance required before an artifact may be used.

type LockedSource 

type LockedSource struct {
	ID        string              `json:"id"`
	Kind      FixtureSourceKind   `json:"kind"`
	URL       string              `json:"url"`
	Reference string              `json:"immutable_reference"`
	Format    FixtureSourceFormat `json:"format"`
	Digest    sandbox.Digest      `json:"sha256"`
	SizeBytes uint64              `json:"size_bytes"`
	License   string              `json:"license"`
}

LockedSource records a single immutable non-executable fixture source.

type MachineConfig 

type MachineConfig struct {
	VCPUCount uint32
	MemoryMiB uint32
}

MachineConfig is the exact bounded subset sent to Firecracker's machine-config endpoint.

type MountExecutionAuthority 

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

MountExecutionAuthority freezes a leased resource store, descriptor identity observer, daemon, journal, clock, and command tuple at composition time. It is not a generic sharing service and remains profile-gated by LinuxJailerHost.

func NewLinuxMountExecutionAuthority 

func NewLinuxMountExecutionAuthority(store *sandboxresource.Store, lease sandboxresource.MountLease, processID, operationID string, fence uint64, sourceClock clock.Clock, daemon *LinuxJailedSharingDaemon, journal *sandboxhostjournal.Journal) (*MountExecutionAuthority, error)

NewLinuxMountExecutionAuthority composes one Linux descriptor observer and daemon as the same fixed data-plane owner. The host never accepts a separate observer that could inspect one export while another daemon mounts a path.

func NewMountExecutionAuthority 

func NewMountExecutionAuthority(store *sandboxresource.Store, lease sandboxresource.MountLease, processID, operationID string, fence uint64, sourceClock clock.Clock, observer MountSourceObserver, daemon JailedSharingDaemon, journal *sandboxhostjournal.Journal) (*MountExecutionAuthority, error)

NewMountExecutionAuthority creates one exact jailed-sharing authority around an already-acquired lease. A command cannot replace any data-plane port.

func (*MountExecutionAuthority) AcknowledgeReceipt 

func (authority *MountExecutionAuthority) AcknowledgeReceipt(envelope sandboxhostprotocol.Envelope, receipt MountReceipt) error

AcknowledgeReceipt makes only the exact fsynced mount observation terminal.

func (*MountExecutionAuthority) Execute 

func (authority *MountExecutionAuthority) Execute(ctx context.Context, envelope sandboxhostprotocol.Envelope, emit MountReceiptEmitter) (MountReceipt, error)

Execute observes the source identity immediately before attach, validates the still-live exact lease, then fsyncs a path-free receipt before control send. A replay observes no new daemon attach after a lost acknowledgement.

func (*MountExecutionAuthority) Reap 

func (authority *MountExecutionAuthority) Reap(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

Reap detaches only the exact daemon share and then releases its exact lease. It is safe after uncertain started work: a daemon must make Detach idempotent, and a released lease cannot be rebound by a delayed envelope.

type MountReceipt 

type MountReceipt struct {
	Version      string    `json:"version"`
	EnvelopeID   string    `json:"envelope_id"`
	AssignmentID string    `json:"assignment_id"`
	OperationID  string    `json:"operation_id"`
	FencingToken uint64    `json:"fencing_token"`
	MountID      string    `json:"mount_id"`
	Generation   uint64    `json:"generation"`
	CompletedAt  time.Time `json:"completed_at"`
}

MountReceipt is a canonical private terminal observation for a successful attach. It deliberately contains no host path, socket, descriptor, or bytes.

type MountReceiptEmitter 

type MountReceiptEmitter func(context.Context, []byte) error

MountReceiptEmitter transports only a previously fsynced receipt to control.

type MountSourceObserver 

type MountSourceObserver interface {
	ObserveMountSource(context.Context, string) (sandboxresource.SourceIdentity, error)
}

MountSourceObserver reads descriptor-rooted source identity. Its implementation must never resolve a caller-selected host path.

type NetworkMode 

type NetworkMode string

NetworkMode identifies the only host-network authority represented by a profile. 

const (
	// NetworkDenyAll creates no guest NIC and authorizes no egress.
	NetworkDenyAll NetworkMode = "deny-all"
	// NetworkAllowlist is reserved for the separately certified mandatory-proxy profile.
	NetworkAllowlist NetworkMode = "allowlist"
)

type NetworkPolicy 

type NetworkPolicy struct {
	Mode      NetworkMode
	Allowlist []string
}

NetworkPolicy is the Firecracker host's explicit egress configuration.

type NoRouteProxyTopologyManifest 

type NoRouteProxyTopologyManifest struct {
	Version                   string
	VMID                      string
	HostCgroupPath            string
	GuestCgroupPath           string
	GuestControlTransport     string
	GuestNICCount             uint8
	GuestRoutePolicy          string
	GuestResolverPolicy       string
	HostResolverRequired      bool
	DirectDNSDeniedRequired   bool
	DirectIPDeniedRequired    bool
	CgroupV2LifecycleRequired bool
}

NoRouteProxyTopologyManifest is the fixed desired topology a future Firecracker egress profile must apply before it may consume a proxy lease. It is deliberately a configuration and refusal input, not evidence that a guest has no NIC, route, resolver, DoH path, or metadata path.

func CompileNoRouteProxyTopologyManifest 

func CompileNoRouteProxyTopologyManifest(plan Plan, authority JailerExecutionAuthority) (NoRouteProxyTopologyManifest, error)

CompileNoRouteProxyTopologyManifest derives the one no-NIC/no-route desired topology from the exact compiled plan and Jailer authority. Callers cannot select a guest route, resolver, proxy listener, address, or tunnel. The result remains an unavailable-profile prerequisite until protected Linux/KVM evidence proves an initializer applied and enforced every field.

func (NoRouteProxyTopologyManifest) NoRouteProxyConfigured 

func (manifest NoRouteProxyTopologyManifest) NoRouteProxyConfigured(plan Plan, authority JailerExecutionAuthority) bool

NoRouteProxyConfigured reports whether the manifest is still exactly bound to the compiled plan and Jailer authority. It does not prove topology application, guest peer authentication, route denial, or egress capability.

type PinnedArtifact 

type PinnedArtifact struct {
	Path   string
	Digest sandbox.Digest
}

PinnedArtifact is an immutable host input identified by a SHA-256 digest.

type Plan 

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

Plan is a resolved, immutable launch plan. The host agent verifies fixture digests before launch.

func Compile 

func Compile(profile Profile) (Plan, error)

Compile rejects profile widening and produces the deterministic foundation launch plan.

func (Plan) Capabilities 

func (plan Plan) Capabilities() sandbox.CapabilitySnapshot

Capabilities returns a defensive copy of the uncertified capability snapshot.

func (Plan) Firecracker 

func (plan Plan) Firecracker() PinnedArtifact

Firecracker returns the pinned VMM artifact.

func (Plan) GID 

func (plan Plan) GID() uint32

GID returns the exact unprivileged Jailer group that owns guest-visible staged resources.

func (Plan) GuestAgent 

func (plan Plan) GuestAgent() PinnedArtifact

GuestAgent returns the pinned project-owned guest control program artifact.

func (Plan) Jailer 

func (plan Plan) Jailer() PinnedArtifact

Jailer returns the pinned Jailer artifact.

func (Plan) JailerArguments 

func (plan Plan) JailerArguments() []string

JailerArguments returns a defensive copy of the exact Jailer argument vector.

func (Plan) Kernel 

func (plan Plan) Kernel() PinnedArtifact

Kernel returns the pinned guest kernel artifact.

func (Plan) Machine 

func (plan Plan) Machine() MachineConfig

Machine returns the exact Firecracker machine configuration.

func (Plan) Network 

func (plan Plan) Network() NetworkPolicy

Network returns a defensive copy of the host network policy.

func (Plan) Resources 

func (plan Plan) Resources() ResourceEnforcement

Resources returns the exact finite host enforcement configuration.

func (Plan) RootFS 

func (plan Plan) RootFS() PinnedArtifact

RootFS returns the pinned guest root filesystem artifact.

func (Plan) UID 

func (plan Plan) UID() uint32

UID returns the exact unprivileged Jailer identity that owns guest-visible staged resources.

func (Plan) VMID 

func (plan Plan) VMID() string

VMID returns the Jailer-safe identity of this launch plan.

type Profile 

type Profile struct {
	Version           string
	VMID              string
	Firecracker       PinnedArtifact
	Jailer            PinnedArtifact
	Kernel            PinnedArtifact
	RootFS            PinnedArtifact
	GuestAgent        PinnedArtifact
	KVMDevice         string
	ChrootBaseDir     string
	UID               uint32
	GID               uint32
	Resources         sandbox.ResourceLimits
	Network           NetworkPolicy
	HostMountsEnabled bool
}

Profile is the versioned desired state for one untrusted Firecracker microVM. It intentionally contains no caller-provided host path, secret value, or ambient credential.

type ProtectedSmokeConfig 

type ProtectedSmokeConfig struct {
	VMID, ExternalOwner string
	UID, GID            uint32
	Cgroup              JailerCgroupAssignment
}

ProtectedSmokeConfig is the explicit operator input needed to compile one no-NIC Firecracker smoke launch from already verified fixtures. It does not provision cgroups, stage fixtures, start a Jailer, or make a capability available.

type ProxyAuthorityIssuer 

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

ProxyAuthorityIssuer is the private host-control boundary for one per-command proxy lease. It owns a fixed no-route topology, Jailer authority, resolver, and dialer; it accepts no listener, host address, guest resolver, or arbitrary tunnel input.

func NewProxyAuthorityIssuer 

func NewProxyAuthorityIssuer(plan Plan, jailer JailerExecutionAuthority, topology NoRouteProxyTopologyManifest, lease sandboxauthority.EgressLease, source clock.Clock, resolver sandboxauthority.Resolver, dialer sandboxauthority.Dialer) (*ProxyAuthorityIssuer, error)

NewProxyAuthorityIssuer creates the exact host-control issuer for a finite lease only when it is bound to the compiled no-NIC/no-route Jailer topology. Construction does not apply topology or enable the egress capability.

func (*ProxyAuthorityIssuer) BoundTo 

func (issuer *ProxyAuthorityIssuer) BoundTo(plan Plan, jailer JailerExecutionAuthority, topology NoRouteProxyTopologyManifest) bool

BoundTo reports whether an issuer is still exactly bound to the host's compiled plan, Jailer authority, and unavailable no-route topology.

func (*ProxyAuthorityIssuer) Issue 

func (issuer *ProxyAuthorityIssuer) Issue(envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) (*ProxyExecutionAuthority, error)

Issue accepts only the canonical control-authenticated envelope already verified by host-process. It returns a per-command authority after exact plan/VM/fence/lease/DNS request binding; it does not open any proxy route.

type ProxyExecutionAuthority 

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

ProxyExecutionAuthority binds one already-admitted egress lease to the authenticated host command that may consume it. It owns neither a listener nor a guest-selected resolver, address, or general tunnel.

func NewProxyExecutionAuthority 

func NewProxyExecutionAuthority(lease sandboxauthority.EgressLease, source clock.Clock, resolver sandboxauthority.Resolver, dialer sandboxauthority.Dialer) (*ProxyExecutionAuthority, error)

NewProxyExecutionAuthority freezes one finite lease with the host-owned resolver and dialer used only after exact envelope and guest-frame checks.

func (*ProxyExecutionAuthority) Begin 

func (authority *ProxyExecutionAuthority) Begin(envelope sandboxhostprotocol.Envelope) (*sandboxauthority.ProxySession, error)

Begin opens one lease-fenced proxy session only when the signed host envelope and its bounded proxy body name exactly the authority's command context.

type ResourceEnforcement 

type ResourceEnforcement struct {
	CgroupVersion       uint8
	RootDiskBytes       uint64
	TmpfsBytes          uint64
	PIDs                uint32
	ProcessCount        uint32
	OpenFiles           uint32
	Inodes              uint64
	Files               uint64
	Lifetime            time.Duration
	ProducedOutputBytes uint64
	RetainedOutputBytes uint64
}

ResourceEnforcement is the exact finite host configuration carried to the Jailer and host agent.

type RootFSAttestation 

type RootFSAttestation struct {
	SchemaVersion string          `json:"schema_version"`
	RootFSDigest  sandbox.Digest  `json:"rootfs_sha256"`
	RootFSSize    uint64          `json:"rootfs_size_bytes"`
	InitPath      string          `json:"init_path"`
	InitDigest    sandbox.Digest  `json:"init_sha256"`
	InitSize      uint64          `json:"init_size_bytes"`
	Platform      FixturePlatform `json:"platform"`
	Static        bool            `json:"static"`
}

RootFSAttestation is the rootfs-build sidecar that binds the installed init to the guest-agent artifact.

type SecretContainmentManifest 

type SecretContainmentManifest struct {
	Version                   string
	VMID                      string
	HostCgroupPath            string
	GuestCgroupPath           string
	SecretAreaPath            string
	SecretAreaFilesystem      string
	SecretAreaMountOptions    []string
	ProcMountPath             string
	ProcFilesystem            string
	ProcMountOptions          []string
	MountNamespaceRequired    bool
	SnapshotExclusionRequired bool
	CgroupV2LifecycleRequired bool
}

SecretContainmentManifest is the fixed launch configuration a future protected guest must consume before accepting a command secret. It records only cgroup and guest-mount policy, never a secret value, host path, or capability promotion. Its presence is a prerequisite/refusal input, not Linux/KVM or ptrace/proc containment evidence.

func CompileSecretContainmentManifest 

func CompileSecretContainmentManifest(plan Plan, authority JailerExecutionAuthority) (SecretContainmentManifest, error)

CompileSecretContainmentManifest derives one exact protected-secret launch configuration from the same Plan and Jailer authority used to start the VM. Callers cannot choose its cgroup, secret-area, or /proc paths. The result remains an unavailable-profile prerequisite until a protected Linux/KVM fixture proves that the guest initializer applied it.

func (SecretContainmentManifest) SecretContainmentConfigured 

func (manifest SecretContainmentManifest) SecretContainmentConfigured(plan Plan, authority JailerExecutionAuthority) bool

SecretContainmentConfigured reports whether the manifest is still exactly bound to plan and authority. It says nothing about an applied guest mount, cgroup, ptrace/proc policy, snapshot exclusion, or protected KVM run.

type SecretExecutionAuthority 

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

SecretExecutionAuthority binds one Manager to host-control time. It owns no route or envelope verification and never stores secret bytes itself.

func NewSecretExecutionAuthority 

func NewSecretExecutionAuthority(manager *sandboxauthority.Manager, source clock.Clock) (*SecretExecutionAuthority, error)

NewSecretExecutionAuthority constructs the command-scoped lifecycle only around an explicit resolver/sink/audit Manager and deterministic time source.

func (*SecretExecutionAuthority) AbandonAfterLostContact 

func (authority *SecretExecutionAuthority) AbandonAfterLostContact(ctx context.Context, processID string) error

AbandonAfterLostContact overwrites the host copy after a started guest has lost the authenticated session. The audit event intentionally requires the Jailer reaper to prove the remote process tree's eventual cleanup.

func (*SecretExecutionAuthority) AbortBeforeStart 

func (authority *SecretExecutionAuthority) AbortBeforeStart(ctx context.Context, processID string) error

AbortBeforeStart closes a delivered secret only while the guest has proved that command launch never bound it to a recipient process.

func (*SecretExecutionAuthority) Begin 

func (authority *SecretExecutionAuthority) Begin(ctx context.Context, envelope sandboxhostprotocol.Envelope) (GuestSecretCommand, error)

Begin verifies that a signed host envelope authorizes exactly one contextual secret request, then delivers it through the Manager's ephemeral sink.

func (*SecretExecutionAuthority) BindSink 

func (authority *SecretExecutionAuthority) BindSink(sink sandboxauthority.SecretSink) (*SecretExecutionAuthority, error)

BindSink creates an isolated secret lifecycle for one authenticated guest exchange. It shares only the resolver, audit boundary, and deterministic clock; redaction bytes and process state remain command-local.

func (*SecretExecutionAuthority) RedactOutput 

func (authority *SecretExecutionAuthority) RedactOutput(processID string, output []byte) []byte

RedactOutput returns a copied literal-redacted chunk while the command lifecycle is active; it never returns the transient redaction values.

func (*SecretExecutionAuthority) RevokeAfterTreeReap 

func (authority *SecretExecutionAuthority) RevokeAfterTreeReap(ctx context.Context, processID string) error

RevokeAfterTreeReap delegates the terminal process-tree proof to the ephemeral sink before Manager zeroizes the retained redaction bytes.

type SmokeEvidence 

type SmokeEvidence struct {
	SchemaVersion string         `json:"schema_version"`
	ProofLevel    string         `json:"proof_level"`
	Result        EvidenceResult `json:"result"`
	SerialMarker  string         `json:"serial_marker"`
	Cleanup       CleanupProof   `json:"cleanup"`
}

SmokeEvidence is a bounded, redacted record suitable for workflow retention.

type SmokeHarness 

type SmokeHarness struct {
	Host    SmokeHost
	Timeout time.Duration
}

SmokeHarness orders verification, launch, guest observation, control, and cleanup under one bounded timeout.

func (SmokeHarness) Run 

func (harness SmokeHarness) Run(ctx context.Context, plan Plan, fixtures FixtureSet) (evidence SmokeEvidence, err error)

Run executes a protected smoke run. It never invokes Launch until the compiled plan and fixture set are complete.

type SmokeHost 

type SmokeHost interface {
	Preflight(context.Context, Plan, FixtureSet) error
	Prepare(context.Context, Plan, FixtureSet) (LaunchRequest, error)
	Launch(context.Context, LaunchRequest) error
	AwaitSerial(context.Context, string) error
	Control(context.Context) error
	Cleanup(context.Context) (CleanupProof, error)
}

SmokeHost is the protected-runner boundary; implementations must perform actual host operations.

type SnapshotRestoreExecutionAuthority 

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

SnapshotRestoreExecutionAuthority binds the durable resource store to one leased, fenced command and a host-selected sink. It exposes no path, bytes, or generic host-sharing primitive.

func NewSnapshotRestoreExecutionAuthority 

func NewSnapshotRestoreExecutionAuthority(store *sandboxresource.Store, sink sandboxresource.SnapshotRestoreSink, journal *sandboxhostjournal.Journal, sourceClock clock.Clock) (*SnapshotRestoreExecutionAuthority, error)

NewSnapshotRestoreExecutionAuthority freezes one store/sink/journal/clock set at the composition root; a payload cannot replace any of those ports.

func (*SnapshotRestoreExecutionAuthority) AcknowledgeReceipt 

func (authority *SnapshotRestoreExecutionAuthority) AcknowledgeReceipt(envelope sandboxhostprotocol.Envelope, receipt TransferReceipt) error

AcknowledgeReceipt records the exact terminal restore receipt before a generic terminal result can be staged by the host-process owner.

func (*SnapshotRestoreExecutionAuthority) Execute 

func (authority *SnapshotRestoreExecutionAuthority) Execute(ctx context.Context, envelope sandboxhostprotocol.Envelope, emit TransferReceiptEmitter) (TransferReceipt, error)

Execute restores exactly one store snapshot after durable started intent. It stages and replays the same reference-only terminal receipt on a lost acknowledgement, so the injected sink is never invoked twice for retries.

func (*SnapshotRestoreExecutionAuthority) Reap 

func (authority *SnapshotRestoreExecutionAuthority) Reap(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

Reap converges an exact snapshot sink after cancellation, restart, or a completed terminal lifecycle. A durable but unacknowledged receipt is not reaped: it must remain replayable so a lost acknowledgement cannot turn a completed restore into ambiguous state.

type SnapshotRestoreSinkReaper 

type SnapshotRestoreSinkReaper interface {
	ReapSnapshotRestore(context.Context, sandboxresource.SnapshotRestoreRequest) error
}

SnapshotRestoreSinkReaper removes only the sink state belonging to one exact restore request. Implementations must be idempotent: it is invoked after cancellation and durable recovery, never as a broad host cleanup.

type TransferExecutionAuthority 

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

TransferExecutionAuthority owns an exact descriptor-rooted workspace operation. It is deliberately independent of a Firecracker profile: host composition stays unavailable until protected guest-profile evidence exists.

func NewTransferExecutionAuthority 

func NewTransferExecutionAuthority(workspace *sandboxtransfer.GuestWorkspaceBinding, source sandboxtransfer.ArtifactSource, sink sandboxtransfer.ArtifactSink, journal *sandboxhostjournal.Journal, sourceClock clock.Clock) (*TransferExecutionAuthority, error)

NewTransferExecutionAuthority freezes all host-selected data-plane ports. A caller cannot replace a source, sink, workspace, journal, or clock through an envelope payload.

func (*TransferExecutionAuthority) AcknowledgeReceipt 

func (authority *TransferExecutionAuthority) AcknowledgeReceipt(envelope sandboxhostprotocol.Envelope, receipt TransferReceipt) error

AcknowledgeReceipt permits the generic terminal result only after control has durably accepted this exact terminal data-plane observation.

func (*TransferExecutionAuthority) Execute 

func (authority *TransferExecutionAuthority) Execute(ctx context.Context, envelope sandboxhostprotocol.Envelope, emit TransferReceiptEmitter) (TransferReceipt, error)

Execute performs an exact effect only after sandboxhostprocess has fsynced its signed started intent. It fsyncs the immutable receipt before delivery; retries replay that receipt rather than duplicate copy-in or copy-out.

func (*TransferExecutionAuthority) Reap 

func (authority *TransferExecutionAuthority) Reap(envelope sandboxhostprotocol.Envelope) error

Reap closes the descriptor-rooted workspace only after the exact receipt is acknowledged. A lost ack intentionally preserves the workspace for replay and reconciliation rather than releasing it under an uncertain effect.

type TransferReceipt 

type TransferReceipt struct {
	Version        string               `json:"version"`
	EnvelopeID     string               `json:"envelope_id"`
	AssignmentID   string               `json:"assignment_id"`
	OperationID    string               `json:"operation_id"`
	FencingToken   uint64               `json:"fencing_token"`
	Kind           string               `json:"kind"`
	Artifact       *sandbox.ArtifactRef `json:"artifact,omitempty"`
	ArchiveDigest  string               `json:"archive_digest,omitempty"`
	SnapshotID     string               `json:"snapshot_id,omitempty"`
	SnapshotDigest string               `json:"snapshot_digest,omitempty"`
	CompletedAt    time.Time            `json:"completed_at"`
}

TransferReceipt is the canonical private terminal receipt. It binds an effect to an exact envelope and may contain only an immutable artifact reference; no file, archive, snapshot, or secret bytes may cross this seam.

type TransferReceiptEmitter 

type TransferReceiptEmitter func(context.Context, []byte) error

TransferReceiptEmitter delivers a previously-fsynced canonical receipt to the authenticated control owner. Its acknowledgement is deliberately separate, so a lost response never repeats the workspace effect.

type TrustedM4Identity 

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

TrustedM4Identity is the redacted, domain-separated identity of the exact M4 objects required by a private Firecracker boot-probe grant. It is an immutable value only: compiling it neither interprets a control request nor starts a Jailer, VMM, guest, or vsock connection.

func CompileTrustedM4Identity 

func CompileTrustedM4Identity(plan Plan, fixtures FixtureSet, authority JailerExecutionAuthority, stage JailedResourceStage) (TrustedM4Identity, error)

CompileTrustedM4Identity commits to one exact compiled plan, verified fixture set, Jailer authority, and staged namespace without exposing host paths, fixture sources, launch argv, or secrets.

func (TrustedM4Identity) AuthorityDigest 

func (identity TrustedM4Identity) AuthorityDigest() sandbox.Digest

AuthorityDigest returns the opaque Jailer-authority commitment.

func (TrustedM4Identity) FixtureDigest 

func (identity TrustedM4Identity) FixtureDigest() sandbox.Digest

FixtureDigest returns the opaque verified-fixture commitment.

func (TrustedM4Identity) FixtureVersion 

func (identity TrustedM4Identity) FixtureVersion() string

FixtureVersion returns the exact compiled fixture-set version.

func (TrustedM4Identity) LaunchGrantIdentity 

func (identity TrustedM4Identity) LaunchGrantIdentity() (firecrackerlaunchgrant.TrustedM4Identity, error)

LaunchGrantIdentity returns the non-secret identity tuple that an M4 host may submit to the private boot-probe protocol. The tuple is available only from a compiler-produced identity; callers cannot construct a usable TrustedM4Identity themselves.

func (TrustedM4Identity) PlanDigest 

func (identity TrustedM4Identity) PlanDigest() sandbox.Digest

PlanDigest returns the opaque compiled-plan commitment.

func (TrustedM4Identity) StageDigest 

func (identity TrustedM4Identity) StageDigest() sandbox.Digest

StageDigest returns the opaque jailed-stage commitment.

func (TrustedM4Identity) String 

func (identity TrustedM4Identity) String() string

String returns the safe labels and opaque digests that may cross the private M3/M4 binding seam.

func (TrustedM4Identity) VMID 

func (identity TrustedM4Identity) VMID() string

VMID returns the exact compiled VM identity.

type UnixGuestControlChannel 

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

UnixGuestControlChannel is the host-side private Firecracker vsock-UDS channel. It exposes no TCP, proxy, or arbitrary destination surface.

func NewUnixGuestControlChannel 

func NewUnixGuestControlChannel(dialer unixSocketDialer) (*UnixGuestControlChannel, error)

NewUnixGuestControlChannel constructs a channel before the exact staged UDS and immutable guest identity are bound.

func (*UnixGuestControlChannel) Bind 

func (channel *UnixGuestControlChannel) Bind(ctx context.Context, socket string) error

Bind fixes the exact host-visible staged vsock UDS once.

func (*UnixGuestControlChannel) BindGuestIdentity 

func (channel *UnixGuestControlChannel) BindGuestIdentity(ctx context.Context, vmID, fixtureVersion string) error

BindGuestIdentity fixes the exact boot VM and verified fixture identity once.

func (*UnixGuestControlChannel) CancelDispatch 

func (channel *UnixGuestControlChannel) CancelDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

CancelDispatch asks the exact bound guest to cancel one fenced operation. It never accepts a caller-selected VM or a zero fence, and it leaves the host's durable uncertain-result recovery as the terminal authority.

func (*UnixGuestControlChannel) Close 

func (channel *UnixGuestControlChannel) Close(ctx context.Context) error

Close tears down every in-flight private guest exchange before the Jailer reaper terminates its process. Once closed, the channel cannot be reused.

func (*UnixGuestControlChannel) DispatchAuthenticated 

func (channel *UnixGuestControlChannel) DispatchAuthenticated(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) (GuestDispatchResult, error)

DispatchAuthenticated carries a signed control envelope and returns bounded ordered output before the guest's terminal result. It does not itself make that output durable or authorize a Firecracker profile.

func (*UnixGuestControlChannel) DispatchAuthenticatedSecret 

func (channel *UnixGuestControlChannel) DispatchAuthenticatedSecret(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, authority *SecretExecutionAuthority, emit sandboxhostprotocol.GuestOutputEmitter) error

DispatchAuthenticatedSecret binds one resolver/Manager lifecycle to the same authenticated vsock connection that proves the exact guest request. Output is held until the guest proves tree reaping and the sink confirms revocation, then literal-redacted chunks cross the durable host boundary.

func (*UnixGuestControlChannel) ExecuteAuthenticatedDispatch 

func (channel *UnixGuestControlChannel) ExecuteAuthenticatedDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte) error

ExecuteAuthenticatedDispatch transports the exact control-signed canonical envelope retained by sandboxhostprocess after control trust verification.

func (*UnixGuestControlChannel) ExecuteDispatch 

func (channel *UnixGuestControlChannel) ExecuteDispatch(ctx context.Context, envelope sandboxhostprotocol.Envelope) error

ExecuteDispatch carries one host-authenticated, lease-fenced envelope over the private peer. A guest can only answer unavailable until its profile has protected Linux/KVM evidence; a malformed or widened response is refused.

func (*UnixGuestControlChannel) Ping 

func (channel *UnixGuestControlChannel) Ping(ctx context.Context, vmID string) error

Ping proves the private peer reports the exact immutable VM identity.

func (*UnixGuestControlChannel) ProxyAuthenticated 

func (channel *UnixGuestControlChannel) ProxyAuthenticated(ctx context.Context, envelope sandboxhostprotocol.Envelope, authenticatedEnvelope []byte, session *sandboxauthority.ProxySession, now time.Time, resolver sandboxauthority.Resolver, dialer sandboxauthority.Dialer) (GuestDispatchResult, error)

ProxyAuthenticated relays one bounded, control-signed guest proxy request over the exact private AF_VSOCK channel. It accepts neither a guest-selected resolver nor a general stream: one signed input produces at most one bounded response and every close path revokes the host-owned proxy session.

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.