You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

213 lines
9.3 KiB
Go

// Package domaincreatevalidate verifies the immutable inputs at the boundary
// before a future host-bound domain create. It is deliberately read-only:
// validation may inspect a published NoCloud seed and render the deterministic
// pre-host XML, but it never writes a seed, allocates storage, defines a
// domain, changes power, or configures networking.
package domaincreatevalidate
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"io/fs"
"os"
"g.luoli.live/root/virt/agent/internal/domaincreateplan"
"g.luoli.live/root/virt/agent/internal/domainpreflight"
"g.luoli.live/root/virt/agent/internal/seedmedia"
)
const (
codePrefix = "domain_create_validate_"
CommitBoundarySeedVerified = "seed_verified"
)
var (
// ErrInvalidJournal means the durable plan identity is malformed or
// internally inconsistent. It is definitive because no host mutation is
// needed to reject it.
ErrInvalidJournal = errors.New("invalid domain create journal")
// ErrSeedArtifactRejected means the immutable seed is missing, malformed,
// or does not match the manifest recorded in the journal. It is definitive
// before a domain definition is attempted.
ErrSeedArtifactRejected = errors.New("seed artifact rejected")
// ErrPolicyRejected means the typed domain policy or deterministic XML no
// longer matches the journaled identity. It is definitive.
ErrPolicyRejected = errors.New("domain create policy rejected")
// ErrArtifactUnavailable means the artifact root/permission boundary could
// not be read. The caller may repair the host and reconcile, so it remains
// non-definitive.
ErrArtifactUnavailable = errors.New("seed artifact unavailable")
// ErrTransportUnavailable covers an unexpected host/filesystem I/O failure
// whose outcome cannot prove whether the immutable artifact is present and
// correct. It is intentionally non-definitive for reconciliation.
ErrTransportUnavailable = errors.New("validation transport unavailable")
// ErrCanceled means validation was interrupted by the caller. No mutation
// was attempted and the operation must remain uncertain until reconciled.
ErrCanceled = errors.New("domain create validation canceled")
)
// Error carries a stable operation error code while keeping the underlying
// cause available to local tests and diagnostics. Message is intentionally
// generic and never includes an artifact path or tenant-provided content.
type Error struct {
CodeValue string `json:"code"`
Message string `json:"message"`
Definitive bool `json:"definitive"`
Cause error `json:"-"`
}
func (e *Error) Error() string {
if e == nil {
return codePrefix + "failed"
}
if e.Message == "" {
return e.CodeValue
}
return e.CodeValue + ": " + e.Message
}
func (e *Error) Unwrap() error {
if e == nil {
return nil
}
return e.Cause
}
func newError(code, message string, definitive bool, cause error) error {
return &Error{CodeValue: code, Message: message, Definitive: definitive, Cause: cause}
}
// Code returns the stable error code intended for operation.ErrorCode.
func Code(err error) string {
var typed *Error
if errors.As(err, &typed) && typed != nil && typed.CodeValue != "" {
return typed.CodeValue
}
return codePrefix + "failed"
}
// IsDefinitive reports whether validation proved a rejection before any host
// mutation. Artifact permission/unavailability and cancellation are false.
func IsDefinitive(err error) bool {
var typed *Error
return errors.As(err, &typed) && typed != nil && typed.Definitive
}
// Result is the safe boundary record returned after seed verification. It
// contains only immutable identities and digest metadata; it never contains
// seed bytes, startup script text, network JSON, or a host filesystem path.
type Result struct {
CommitBoundary string `json:"commit_boundary"`
SeedArtifactID string `json:"seed_artifact_id"`
SeedManifest domaincreateplan.SeedManifest `json:"seed_manifest"`
StartupScriptPresent bool `json:"first_boot_present"`
StartupScriptSHA256 string `json:"first_boot_digest"`
DomainXMLHash string `json:"domain_xml_hash"`
PlanHash string `json:"plan_hash"`
LoaderPending bool `json:"loader_pending"`
}
// Validate performs the read-only create-intent validation boundary.
//
// artifactRoot must be a clean absolute directory configured by the agent.
// The only seed lookup key is the canonical artifact UUID; callers cannot
// provide a path or filename. The journal is checked first, then the internal
// seedmedia resolver reads and verifies the immutable artifact, and finally
// the pre-host XML is rendered and hashed. No write or libvirt operation is
// reachable from this package.
func Validate(ctx context.Context, artifactRoot string, payload domaincreateplan.JournalPayload) (Result, error) {
if ctx == nil {
ctx = context.Background()
}
if err := ctx.Err(); err != nil {
return Result{}, newError(codePrefix+"canceled", "validation was canceled", false, fmt.Errorf("%w: %v", ErrCanceled, err))
}
// ValidateJournal performs strict canonical UUID, manifest shape, digest,
// and plan-hash validation. It does not contact the host or filesystem.
if err := domaincreateplan.ValidateJournal(payload); err != nil {
return Result{}, newError(codePrefix+"journal_mismatch", "journal identity is not valid", true, fmt.Errorf("%w: %v", ErrInvalidJournal, err))
}
resolver, err := seedmedia.NewDirectoryResolver(artifactRoot)
if err != nil {
// Keep the historical domain_create_validate error code and definitive
// classification for malformed agent configuration. The resolver owns
// path-shape validation; this adapter only translates its boundary.
return Result{}, newError(codePrefix+"artifact_root_invalid", "seed artifact root is invalid", true, ErrArtifactUnavailable)
}
_, err = resolver.Resolve(ctx, seedmedia.Request{
ArtifactID: payload.SeedArtifactID,
SeedManifest: payload.SeedManifest,
StartupScriptPresent: payload.StartupScriptPresent,
StartupScriptSHA256: payload.StartupScriptSHA256,
})
if err != nil {
return Result{}, classifySeedMediaError(err)
}
normalized, err := domainpreflight.RenderRequest(payload.Domain)
if err != nil {
return Result{}, newError(codePrefix+"policy_rejected", "domain policy could not be rendered", true, fmt.Errorf("%w: %v", ErrPolicyRejected, err))
}
xmlHash := digest(normalized)
if xmlHash != payload.DomainXMLHash {
return Result{}, newError(codePrefix+"policy_mismatch", "rendered domain policy differs from the journal", true, ErrPolicyRejected)
}
if err := ctx.Err(); err != nil {
return Result{}, newError(codePrefix+"canceled", "validation was canceled", false, fmt.Errorf("%w: %v", ErrCanceled, err))
}
return Result{
CommitBoundary: CommitBoundarySeedVerified,
SeedArtifactID: payload.SeedArtifactID,
SeedManifest: payload.SeedManifest,
StartupScriptPresent: payload.StartupScriptPresent,
StartupScriptSHA256: payload.StartupScriptSHA256,
DomainXMLHash: xmlHash,
PlanHash: payload.PlanHash,
LoaderPending: true,
}, nil
}
// Verify is an explicit alias for callers that want the operation's read-back
// semantics to be apparent at the call site.
func Verify(ctx context.Context, artifactRoot string, payload domaincreateplan.JournalPayload) (Result, error) {
return Validate(ctx, artifactRoot, payload)
}
// classifySeedMediaError preserves the public domain_create_validate error
// contract while delegating artifact path, manifest, and startup identity
// checks to seedmedia. The adapter never exposes the resolver's host path or
// underlying diagnostic text to the operation result.
func classifySeedMediaError(err error) error {
if errors.Is(err, seedmedia.ErrCanceled) {
return newError(codePrefix+"canceled", "validation was canceled", false, fmt.Errorf("%w: %v", ErrCanceled, err))
}
if errors.Is(err, seedmedia.ErrInvalidRequest) {
return newError(codePrefix+"journal_mismatch", "journal identity is not valid", true, fmt.Errorf("%w: %v", ErrInvalidJournal, err))
}
if errors.Is(err, seedmedia.ErrArtifactRejected) {
if seedmedia.Code(err) == "seed_media_identity_mismatch" {
return newError(codePrefix+"seed_manifest_mismatch", "seed artifact does not match the journaled manifest", true, ErrSeedArtifactRejected)
}
return newError(codePrefix+"seed_artifact_rejected", "seed artifact is missing or does not verify", true, ErrSeedArtifactRejected)
}
if errors.Is(err, seedmedia.ErrUnavailable) {
if errors.Is(err, fs.ErrPermission) || os.IsPermission(err) {
return newError(codePrefix+"artifact_permission", "seed artifact permissions could not be read", false, fmt.Errorf("%w: %v", ErrArtifactUnavailable, err))
}
return newError(codePrefix+"artifact_unavailable", "seed artifact storage is unavailable", false, fmt.Errorf("%w: %v", ErrArtifactUnavailable, err))
}
// Unknown verifier failures remain uncertain so a later reconcile can
// distinguish a repaired host from persistent corruption.
return newError(codePrefix+"transport_unavailable", "seed artifact read did not complete", false, fmt.Errorf("%w: %v", ErrTransportUnavailable, err))
}
func digest(value []byte) string {
sum := sha256.Sum256(value)
return hex.EncodeToString(sum[:])
}