modelintegrity

Documentation

Overview

Package modelintegrity implements a model-integrity verification gate, in the style of a HuggingFace cache integrity check, before a model is served.

A model is described by a manifest: a list of expected files, each pinned to an exact content digest (SHA-256, lower-case hex) and an exact byte size. Before serving, every file on disk is verified against its manifest entry by streaming the file through crypto/sha256 and comparing BOTH the resulting digest AND the observed byte size to the expected values. Verification fails closed: a missing file, a content tamper (same size, different bytes), or a length tamper (truncation/extension) each produce a distinct, specific failure so the caller can tell WHY a model was rejected.

The package is stdlib-only. crypto/sha256 is the working reference hash: it is a real, standards-conformant SHA-256 implementation, so a VERIFY result is genuine cryptographic evidence that the on-disk bytes match the pinned digest, not a structural rubber-stamp.

Index

• Variables
• func VerifyFile(path, expectedSHA256hex string, expectedSize int64) error
• type FileResult
• type ManifestEntry
• type MismatchKind
  • func (k MismatchKind) String() string
• type Report
  • func VerifyManifest(rootDir string, entries []ManifestEntry) (Report, error)
  • func (r Report) FailedPaths() []string

Variables

var ErrBadDigest = errors.New("modelintegrity: malformed expected sha256")

ErrBadDigest is returned by VerifyFile when the expected digest is not a valid 64-character lower-case hex SHA-256 string.

var ErrMissingFile = errors.New("modelintegrity: file missing")

ErrMissingFile is returned (wrapped) by VerifyFile when the target file does not exist or cannot be opened. Callers may test for it with errors.Is.

var ErrSHAMismatch = errors.New("modelintegrity: sha256 mismatch")

ErrSHAMismatch is returned (wrapped) by VerifyFile when the file's SHA-256 digest differs from the expected digest while its size matched.

var ErrSizeMismatch = errors.New("modelintegrity: size mismatch")

ErrSizeMismatch is returned (wrapped) by VerifyFile when the file's byte size differs from the expected size.

Functions

func VerifyFile

func VerifyFile(path, expectedSHA256hex string, expectedSize int64) error

VerifyFile verifies a single file at path against an expected SHA-256 (given as lower-case hex) and an expected byte size. It streams the file through crypto/sha256 (constant memory, independent of file size) and compares BOTH the digest AND the observed size.

It returns nil iff the file exists, its size equals expectedSize, AND its digest equals expectedSHA256hex. Otherwise it returns an error wrapping one of ErrMissingFile, ErrSizeMismatch, or ErrSHAMismatch. Size is checked before content so a truncation/extension is reported as a size mismatch rather than being masked as a digest mismatch.

Types

type FileResult

type FileResult struct {
	// Path echoes the manifest entry path that was verified.
	Path string
	// OK is true iff the file matched both digest and size.
	OK bool
	// Mismatch classifies the failure; MismatchNone when OK is true.
	Mismatch MismatchKind
	// ExpectedSHA256 is the manifest digest (lower-case hex).
	ExpectedSHA256 string
	// ActualSHA256 is the digest computed from disk (lower-case hex). It is
	// empty when the file was missing.
	ActualSHA256 string
	// ExpectedSize is the manifest size in bytes.
	ExpectedSize int64
	// ActualSize is the size observed on disk; 0 when the file was missing.
	ActualSize int64
	// Detail is a human-readable explanation of a failure; empty when OK.
	Detail string
}

FileResult is the verification outcome for a single manifest entry.

type ManifestEntry

type ManifestEntry struct {
	// Path is the file location relative to the manifest root directory.
	Path string
	// SHA256 is the expected SHA-256 digest as lower-case hex (64 chars).
	SHA256 string
	// Size is the expected file size in bytes.
	Size int64
}

ManifestEntry pins one model file to an exact content digest and byte size.

type MismatchKind

type MismatchKind int

MismatchKind classifies why a single file failed verification.

const (
	// MismatchNone indicates the file matched both digest and size.
	MismatchNone MismatchKind = iota
	// MismatchMissing indicates the file could not be opened (absent/unreadable).
	MismatchMissing
	// MismatchSize indicates the file's byte size differed from the manifest.
	MismatchSize
	// MismatchSHA indicates the file's SHA-256 digest differed from the manifest
	// while its size matched: a same-length content tamper.
	MismatchSHA
)

func (MismatchKind) String

func (k MismatchKind) String() string

String renders the mismatch kind for diagnostics.

type Report

type Report struct {
	// Root is the directory the manifest was verified against.
	Root string
	// Files holds one FileResult per manifest entry, in manifest order.
	Files []FileResult
	// OK is true iff every file in the manifest verified.
	OK bool
}

Report is the aggregate outcome of verifying a whole manifest.

func VerifyManifest

func VerifyManifest(rootDir string, entries []ManifestEntry) (Report, error)

VerifyManifest verifies every entry in entries against the files found under rootDir, joining each entry's relative path to rootDir. It returns a Report with one FileResult per entry (in entry order); Report.OK is true iff every entry verified.

The returned error is non-nil only for a usage fault that prevents producing a meaningful report (an empty rootDir or a manifest entry with a malformed digest); per-file integrity failures are NOT errors — they are recorded in the Report so the caller sees the full picture in one pass.

func (Report) FailedPaths

func (r Report) FailedPaths() []string

FailedPaths returns the relative paths of every file that did not verify, in manifest order. It is empty when the report is OK.