validationmode

package
v0.0.0-...-89d81dd Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package validationmode provides the fail-closed, disposable host boundary used by production-engine validation scenarios.

Index

Constants

View Source 
const (
	TestModeEnvironment = "ENDSTATE_TESTMODE"
	RootEnvironment     = "ENDSTATE_ROOT"
)
View Source 
const (
	RegistryTypeString uint32 = 1
	RegistryTypeBinary uint32 = 3
	RegistryTypeDWORD  uint32 = 4
)

Variables

View Source 
var (
	ErrInvalidActivation = errors.New("invalid validation-mode activation")
	ErrUnsafeRoot        = errors.New("unsafe validation root")
	ErrInvalidDescriptor = errors.New("invalid validation-mode descriptor")
	ErrUnsafePath        = errors.New("unsafe validation path")
	ErrUnsafeRegistry    = errors.New("unsafe validation registry key")
	ErrPackageIdentity   = errors.New("package identity is outside validation inventory")
	ErrInvalidState      = errors.New("invalid validation package state")
	ErrGuardOverlap      = errors.New("validation and protected paths overlap")
	ErrUnsafeGuardPath   = errors.New("unsafe filesystem guard path")
	ErrGuardBudget       = errors.New("validation guard budget exceeded")
	ErrGuardChanged      = errors.New("protected validation target changed")
)

Functions

func NormalizeHKCU 

func NormalizeHKCU(key string) (string, error)

NormalizeHKCU validates and canonicalizes semantic current-user identity. PowerShell's HKCU:\ spelling is accepted only at this boundary.

func NormalizeProductionAuthoredPath 

func NormalizeProductionAuthoredPath(value string) string

NormalizeProductionAuthoredPath maps supported production home paths to the canonical declared alias form.

func ResolvePortablePath 

func ResolvePortablePath(root, portable string) (string, error)

ResolvePortablePath resolves a portable payload or bundle path beneath an explicit existing root.

Types

type Change 

type Change struct {
	Path string
	Kind ChangeKind
}

type ChangeKind 

type ChangeKind string
const (
	ChangeCreated ChangeKind = "created"
	ChangeDeleted ChangeKind = "deleted"
	ChangeType    ChangeKind = "type"
	ChangeContent ChangeKind = "content"
)

type Context 

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

Context contains validation authority. Its host paths are intentionally available only through methods and have no JSON or text representation.

func ActivateFromEnvironment 

func ActivateFromEnvironment() (*Context, func() error, error)

ActivateFromEnvironment loads validation mode, creates its derived roots, installs their environment aliases, and returns an idempotent restoration.

func LoadFromEnvironment 

func LoadFromEnvironment() (*Context, error)

LoadFromEnvironment validates validation-mode authority without mutating the filesystem, environment, package state, or host. A nil context means inactive.

func (*Context) Activate 

func (context *Context) Activate() (func() error, error)

Activate installs the already-loaded context's disposable environment aliases without rereading activation variables or descriptor authority.

func (*Context) Descriptor 

func (context *Context) Descriptor() Descriptor

Descriptor returns a defensive copy of the trusted descriptor.

func (*Context) DisplayHostPath 

func (context *Context) DisplayHostPath(absolute string, policy HostPathPolicy) (string, error)

DisplayHostPath uses explicit instance provenance when available; ordinary dynamic aliases retain their authored alias identity.

func (*Context) DisplayPath 

func (context *Context) DisplayPath(absolute string) (string, error)

DisplayPath projects an absolute validation path to a non-sensitive token.

func (*Context) GlobSandboxPattern 

func (context *Context) GlobSandboxPattern(pattern string) ([]string, error)

GlobSandboxPattern evaluates an already-expanded detector pattern only inside validation-owned virtual roots. Every returned match is canonical, link-free, and revalidated for containment before it can become production instance evidence.

func (*Context) GoString 

func (context *Context) GoString() string

GoString applies the same redaction to %#v formatting.

func (*Context) MapHKCU 

func (context *Context) MapHKCU(key string) (string, error)

MapHKCU maps a semantic current-user key into the scenario namespace.

func (*Context) NewPackageDriver 

func (context *Context) NewPackageDriver() (*PackageDriver, error)

NewPackageDriver opens or initializes the descriptor-bound disposable state.

func (*Context) OriginalEnvironment 

func (context *Context) OriginalEnvironment(name string) (value string, set bool, managed bool)

OriginalEnvironment returns the pre-activation value without making Context itself serializable or printable with host paths.

func (*Context) OriginalHostPath 

func (context *Context) OriginalHostPath(authored string, policy HostPathPolicy) (string, error)

OriginalHostPath transfers a validated authored suffix to the corresponding environment value captured before activation. Wildcards protect their non-wildcard parent prefix. Callers must never serialize the returned path.

func (*Context) RegistryNamespace 

func (context *Context) RegistryNamespace() string

RegistryNamespace returns the disposable HKCU namespace identity.

func (*Context) ResolveHostPath 

func (context *Context) ResolveHostPath(authored string, policy HostPathPolicy) (string, error)

ResolveHostPath resolves a Windows-authored path using only Context aliases.

func (*Context) ResolveHostPattern 

func (context *Context) ResolveHostPattern(authored string, policy HostPathPolicy) (string, error)

ResolveHostPattern resolves a capture-side host pattern through the same alias and instance authority as ResolveHostPath while retaining wildcard syntax for matching. The non-wildcard probe is resolved first, so traversal, unknown aliases, hardcoded paths, and linked parents fail closed.

func (*Context) Root 

func (context *Context) Root() string

Root returns the disposable validation root for boundary checks.

func (*Context) String 

func (context *Context) String() string

String intentionally omits host roots and original environment values.

func (*Context) ValidateSandboxPath 

func (context *Context) ValidateSandboxPath(absolute string) error

ValidateSandboxPath accepts only link-free materialized paths under one validation virtual root or a narrowly owned engine runtime location.

func (*Context) VirtualRoot 

func (context *Context) VirtualRoot(name string) (string, bool)

VirtualRoot resolves an environment alias case-insensitively.

type Descriptor 

type Descriptor struct {
	SchemaVersion int       `json:"schemaVersion"`
	ScenarioID    string    `json:"scenarioId"`
	Nonce         string    `json:"nonce"`
	ModuleID      string    `json:"moduleId"`
	Inventory     Inventory `json:"inventory"`
	DynamicRoots  []string  `json:"dynamicRoots,omitempty"`
}

Descriptor is the data-only authority for one validation scenario.

type HostPathPolicy 

type HostPathPolicy struct {
	AllowRoot     bool
	DynamicRoot   string
	InstanceRoot  string
	InstanceAlias string
}

HostPathPolicy controls the two deliberate host-path exceptions.

type Inventory 

type Inventory struct {
	AppID        string `json:"appId"`
	Driver       string `json:"driver"`
	Ref          string `json:"ref"`
	DisplayName  string `json:"displayName"`
	Version      string `json:"version,omitempty"`
	Source       string `json:"source,omitempty"`
	InitialState string `json:"initialState"`
}

Inventory describes the single disposable package visible to the scenario.

type PackageDriver 

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

PackageDriver is a data-only implementation of all production package capability interfaces. It has no process or network runner.

func (*PackageDriver) Detect 

func (value *PackageDriver) Detect(ref string) (bool, string, error)

func (*PackageDriver) DetectBatch 

func (value *PackageDriver) DetectBatch(refs []string) (map[string]driver.DetectResult, error)

func (*PackageDriver) DetectBatchSource 

func (value *PackageDriver) DetectBatchSource(refs []string, source string) (map[string]driver.DetectResult, error)

func (*PackageDriver) DetectSource 

func (value *PackageDriver) DetectSource(ref, source string) (bool, string, error)

func (*PackageDriver) EnumerateInstalled 

func (value *PackageDriver) EnumerateInstalled() ([]driver.InstalledPackage, error)

func (*PackageDriver) ExternalCallCount 

func (value *PackageDriver) ExternalCallCount() uint64

ExternalCallCount is a testable invariant: this driver has no external runner.

func (*PackageDriver) Install 

func (value *PackageDriver) Install(ref string) (*driver.InstallResult, error)

func (*PackageDriver) InstallSource 

func (value *PackageDriver) InstallSource(ref, source string) (*driver.InstallResult, error)

func (*PackageDriver) InstallVersion 

func (value *PackageDriver) InstallVersion(ref, version string) (*driver.InstallResult, error)

func (*PackageDriver) InstallVersionSource 

func (value *PackageDriver) InstallVersionSource(ref, version, source string) (*driver.InstallResult, error)

func (*PackageDriver) Name 

func (value *PackageDriver) Name() string

func (*PackageDriver) ReinstallVersion 

func (value *PackageDriver) ReinstallVersion(ref, version string) (*driver.InstallResult, error)

func (*PackageDriver) ReinstallVersionSource 

func (value *PackageDriver) ReinstallVersionSource(ref, version, source string) (*driver.InstallResult, error)

func (*PackageDriver) Uninstall 

func (value *PackageDriver) Uninstall(ref string) (*driver.UninstallResult, error)

func (*PackageDriver) UninstallSource 

func (value *PackageDriver) UninstallSource(ref, source string) (*driver.UninstallResult, error)

type ProtectedPath 

type ProtectedPath struct{ Path, Label string }

type ProtectedRegistry 

type ProtectedRegistry struct {
	Key       string
	ValueName string
	Label     string
	WholeKey  bool
}

type RegistryChange 

type RegistryChange struct {
	Label string
	Kind  ChangeKind
}

type RegistryFixture 

type RegistryFixture struct{}

func NewRegistryFixture 

func NewRegistryFixture(*Context) (*RegistryFixture, error)

func (*RegistryFixture) Cleanup 

func (*RegistryFixture) Cleanup() error

func (*RegistryFixture) Materialize 

func (*RegistryFixture) Materialize(string) error

func (*RegistryFixture) ProveAbsent 

func (*RegistryFixture) ProveAbsent(string) error

func (*RegistryFixture) Remove 

func (*RegistryFixture) Remove(string) error

func (*RegistryFixture) Replace 

func (*RegistryFixture) Replace(string, RegistryState) error

func (*RegistryFixture) Snapshot 

func (*RegistryFixture) Snapshot(string) (RegistryState, error)

type RegistryGuard 

type RegistryGuard struct{}

func NewRegistryGuard 

func NewRegistryGuard(*Context) *RegistryGuard

func (*RegistryGuard) Check 

func (*RegistryGuard) Check() ([]RegistryChange, error)

func (*RegistryGuard) Protect 

func (*RegistryGuard) Protect(values []ProtectedRegistry) error

func (*RegistryGuard) Seal 

func (*RegistryGuard) Seal()

type RegistryKey 

type RegistryKey struct {
	Path   string
	Values []RegistryValue
}

RegistryKey is one relative key and all of its values. The empty Path is the authored root and the empty Name is that key's default value.

type RegistryState 

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

RegistryState is an immutable, canonical snapshot of a registry subtree.

func NewRegistryState 

func NewRegistryState(keys []RegistryKey) (RegistryState, error)

NewRegistryState validates and canonically orders a registry subtree.

func (RegistryState) Equal 

func (state RegistryState) Equal(other RegistryState) bool

Equal compares canonical registry identity, type, and raw data exactly.

func (RegistryState) Keys 

func (state RegistryState) Keys() []RegistryKey

Keys returns a defensive copy of the canonical registry keys.

type RegistryValue 

type RegistryValue struct {
	Name string
	Type uint32
	Data []byte
}

RegistryValue is one exact Windows registry value in a disposable fixture.

type WriteGuard 

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

WriteGuard records protected filesystem trees without mutating them.

func NewWriteGuard 

func NewWriteGuard(allowed string, protected []string) (*WriteGuard, error)

NewWriteGuard validates disjoint boundaries and snapshots protected paths.

func (*WriteGuard) Check 

func (guard *WriteGuard) Check() ([]Change, error)

Check returns deterministic protected-path changes since construction.

func (*WriteGuard) Label 

func (guard *WriteGuard) Label(path string) string

Label returns the non-sensitive label associated with a changed absolute path.

func (*WriteGuard) Protect 

func (guard *WriteGuard) Protect(values []ProtectedPath) error

Protect registers and snapshots additional paths before mutation begins.

func (*WriteGuard) ProtectedCount 

func (guard *WriteGuard) ProtectedCount() int

func (*WriteGuard) Seal 

func (guard *WriteGuard) Seal()

Seal closes registration. Protect after Seal is rejected so a late snapshot can never erase evidence of a mutation.

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.