sandboxresource

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

Documentation

Overview

Package sandboxresource owns durable, principal-scoped volume, snapshot and mount-lease manifests. It deliberately does not make an adapter capability claim: a host must separately prove the corresponding data plane.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrAttached means a volume still has a live or unreconciled attachment.
	ErrAttached = errors.New("sandbox resource is attached")
	// ErrConflict means a durable identity or generation was superseded.
	ErrConflict = errors.New("sandbox resource conflict")
	// ErrIntegrity means persisted content or its declared identity did not verify.
	ErrIntegrity = errors.New("sandbox resource integrity check failed")
	// ErrLeaseExpired means a caller tried to use an expired finite lease.
	ErrLeaseExpired = errors.New("sandbox resource lease expired")
	// ErrNotFound means an owner-scoped resource is absent.
	ErrNotFound = errors.New("sandbox resource not found")
	// ErrSnapshotDenied means taint policy did not permit a snapshot.
	ErrSnapshotDenied = errors.New("sandbox snapshot denied by taint policy")
	// ErrTombstoned means an identity is retained but can never be reused.
	ErrTombstoned = errors.New("sandbox resource is tombstoned")
)

Functions

This section is empty.

Types

type Attachment 

type Attachment struct {
	SandboxID      string
	Mode           AttachmentMode
	LeaseExpiresAt time.Time
	Generation     uint64
}

Attachment records the single current volume attachment and its finite fence.

type AttachmentMode 

type AttachmentMode string

AttachmentMode declares the authority granted to an attached named volume. 

const (
	// ReadOnly permits a coherent read-only attachment when a future host profile proves it.
	ReadOnly AttachmentMode = "read-only"
	// ReadWrite is exclusive and must always be generation fenced.
	ReadWrite AttachmentMode = "read-write"
)

type Config 

type Config struct {
	MaximumVolumeBytes   uint64
	MaximumVolumeInodes  uint64
	MaximumSnapshotBytes uint64
}

Config bounds a resource authority instance. All limits must be explicit.

type FileDataPlane 

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

FileDataPlane stores bounded encrypted snapshot payloads in a private directory.

func OpenFileDataPlane 

func OpenFileDataPlane(directory string, key []byte, maximumBytes uint64) (*FileDataPlane, error)

OpenFileDataPlane opens one private encrypted snapshot payload store.

func (*FileDataPlane) Discard 

func (plane *FileDataPlane) Discard(stage StagedSnapshot) error

Discard removes a staged payload and is safe to repeat.

func (*FileDataPlane) Open 

func (plane *FileDataPlane) Open(ctx context.Context, id string, manifest SnapshotManifest) (io.ReadCloser, error)

Open decrypts and verifies a snapshot payload before exposing a bounded reader.

func (*FileDataPlane) Publish 

func (plane *FileDataPlane) Publish(stage StagedSnapshot) error

Publish atomically makes a staged ciphertext visible under its immutable snapshot ID.

func (*FileDataPlane) Remove 

func (plane *FileDataPlane) Remove(id string) error

Remove removes one published payload during a tombstone transition.

func (*FileDataPlane) Stage 

func (plane *FileDataPlane) Stage(ctx context.Context, id string, input io.Reader) (StagedSnapshot, error)

Stage copies, encrypts and digests bounded disk-only bytes before any manifest is published.

type MountLease 

type MountLease struct {
	ID             string
	Owner          string
	SandboxID      string
	Source         SourceIdentity
	Target         string
	Mode           AttachmentMode
	View           string
	Generation     uint64
	LeaseExpiresAt time.Time
	ReleasedAt     time.Time
}

MountLease binds a descriptor identity to one sandbox for a finite period. It is an authority contract, not evidence that a sharing daemon exists.

type SnapshotLease 

type SnapshotLease struct {
	Holder         string
	Generation     uint64
	LeaseExpiresAt time.Time
}

SnapshotLease serializes restore and delete against one snapshot generation.

type SnapshotManifest 

type SnapshotManifest struct {
	SchemaVersion             string
	Owner                     string
	ID                        string
	SourceSandboxID           string
	SourceEffectiveSpecDigest string
	CapabilityDigest          string
	ImageDigest               string
	RequestID                 string
	Format                    string
	Encryption                string
	Integrity                 string
	PlaintextDigest           string
	CiphertextDigest          string
	SizeBytes                 uint64
	CreatedAt                 time.Time
	RetentionExpiresAt        time.Time
	Taint                     Taint
	RiskAttestation           string
	Lease                     *SnapshotLease
	TombstonedAt              time.Time
}

SnapshotManifest is a durable disk-only snapshot record. Content lives in the encrypted data plane and is referred to only by immutable digests.

type SnapshotRestoreRequest 

type SnapshotRestoreRequest struct {
	Owner, ID, Holder                                  string
	Generation                                         uint64
	SandboxID                                          string
	EffectiveSpecDigest, CapabilityDigest, ImageDigest string
}

SnapshotRestoreRequest binds a restore sink to an exact snapshot lease and an admitted restore ceiling. It never permits a snapshot to widen image, policy, or capability authority.

type SnapshotRestoreSink 

type SnapshotRestoreSink interface {
	RestoreSnapshot(context.Context, SnapshotManifest, io.Reader) error
}

SnapshotRestoreSink owns the destination data plane. Store supplies only a verified bounded plaintext reader and never chooses a guest path or mount.

type SourceIdentity 

type SourceIdentity struct {
	ExportID   string
	Device     uint64
	Inode      uint64
	Generation uint64
}

SourceIdentity is the descriptor-first identity a future mount data plane must pin. It intentionally contains no resolvable host pathname.

type StagedSnapshot 

type StagedSnapshot struct {
	PlaintextDigest, CiphertextDigest string
	SizeBytes                         uint64
	// contains filtered or unexported fields
}

StagedSnapshot is an opaque encrypted temporary payload awaiting atomic publish.

type Store 

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

Store persists manifests atomically to a private directory. Its data plane is usable for encrypted snapshot artifacts, but Store itself is deliberately not connected to a sandbox adapter or a capability descriptor.

func Open 

func Open(directory string, config Config, dataKey []byte) (*Store, error)

Open creates or recovers a private manifest store rooted at directory.

func (*Store) AcquireMount 

func (store *Store) AcquireMount(ctx context.Context, lease MountLease, now time.Time) (MountLease, error)

AcquireMount records the source identity that a sharing daemon must recheck. No call here makes a mount available to a sandbox.

func (*Store) AcquireSnapshotLease 

func (store *Store) AcquireSnapshotLease(ctx context.Context, owner, id, holder string, leaseExpiresAt, now time.Time) (SnapshotManifest, error)

AcquireSnapshotLease serializes a restore or delete operation using a finite fence.

func (*Store) AttachVolume 

func (store *Store) AttachVolume(ctx context.Context, owner, id, sandboxID string, mode AttachmentMode, leaseExpiresAt, now time.Time) (VolumeManifest, error)

AttachVolume atomically grants one exclusive read-write generation lease.

func (*Store) CreateSnapshot 

func (store *Store) CreateSnapshot(ctx context.Context, manifest SnapshotManifest, content io.Reader, now time.Time) (SnapshotManifest, error)

CreateSnapshot stages, encrypts, verifies and atomically publishes disk-only content before its manifest.

func (*Store) CreateVolume 

func (store *Store) CreateVolume(ctx context.Context, volume VolumeManifest) (VolumeManifest, error)

CreateVolume writes one immutable volume identity. Tombstoned IDs are never reused.

func (*Store) DetachVolume 

func (store *Store) DetachVolume(ctx context.Context, owner, id string, generation uint64, now time.Time) (VolumeManifest, error)

DetachVolume releases only the exact current attachment generation.

func (*Store) GetVolume 

func (store *Store) GetVolume(ctx context.Context, owner, id string) (VolumeManifest, error)

GetVolume returns a defensive principal-scoped manifest snapshot.

func (*Store) MarkVolumeTainted 

func (store *Store) MarkVolumeTainted(ctx context.Context, owner, id string, taint Taint, now time.Time) (VolumeManifest, error)

MarkVolumeTainted preserves safe exposure provenance through attachment and tombstone.

func (*Store) OpenSnapshot 

func (store *Store) OpenSnapshot(ctx context.Context, owner, id string) (io.ReadCloser, SnapshotManifest, error)

OpenSnapshot returns a verified plaintext reader only to the owning principal.

func (*Store) ReconcileExpiredAttachments 

func (store *Store) ReconcileExpiredAttachments(ctx context.Context, now time.Time) ([]VolumeManifest, error)

ReconcileExpiredAttachments fences abandoned attachments before a new attach may proceed.

func (*Store) ReleaseMount 

func (store *Store) ReleaseMount(ctx context.Context, owner, id string, generation uint64, now time.Time) (MountLease, error)

ReleaseMount releases only the exact lease generation.

func (*Store) ReleaseSnapshotLease 

func (store *Store) ReleaseSnapshotLease(ctx context.Context, owner, id string, generation uint64) (SnapshotManifest, error)

ReleaseSnapshotLease releases only the exact restore/delete generation.

func (*Store) RestoreSnapshot 

func (store *Store) RestoreSnapshot(ctx context.Context, request SnapshotRestoreRequest, sink SnapshotRestoreSink, now time.Time) (SnapshotManifest, error)

RestoreSnapshot opens exactly one leased, verified disk snapshot and hands it to an admitted sink. The lease remains held on sink failure so reaper reconciliation, rather than a racing delete, remains authoritative.

func (*Store) TombstoneSnapshot 

func (store *Store) TombstoneSnapshot(ctx context.Context, owner, id string, now time.Time) (SnapshotManifest, error)

TombstoneSnapshot removes ciphertext and permanently retains the identity.

func (*Store) TombstoneVolume 

func (store *Store) TombstoneVolume(ctx context.Context, owner, id string, generation uint64, now time.Time) (VolumeManifest, error)

TombstoneVolume irreversibly prevents ID reuse after the exact detached generation.

func (*Store) ValidateMountLease 

func (store *Store) ValidateMountLease(ctx context.Context, owner, id string, generation uint64, observed SourceIdentity, now time.Time) error

ValidateMountLease proves that the source identity supplied by a host still matches its lease.

type Taint 

type Taint struct {
	KnownSecretPath bool
	UnknownPath     bool
	Provenance      []TaintProvenance
}

Taint records only SDK-known secret exposure and observable unknown paths.

type TaintProvenance 

type TaintProvenance struct {
	OperationID string
	Class       string
}

TaintProvenance records safe known-secret exposure metadata, never a value or name.

type VolumeManifest 

type VolumeManifest struct {
	SchemaVersion      string
	Owner              string
	ID                 string
	Format             string
	Encryption         string
	Integrity          string
	SizeBytes          uint64
	Inodes             uint64
	CreatedAt          time.Time
	UpdatedAt          time.Time
	RetentionExpiresAt time.Time
	Generation         uint64
	Attachment         *Attachment
	Taint              Taint
	TombstonedAt       time.Time
}

VolumeManifest is the durable authority record for one principal-owned volume.

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.