Documentation
¶
Overview ¶
Package modelsource classifies where a model's weights come from and how far that source can be trusted, so a model from anywhere (a curated catalog entry, a model-hub reference, a raw URL, or a file a user drops in) goes through one trust decision before it is ever fetched or run. A model file is untrusted input to a parser with a history of memory-safety flaws, so the source it came from sets the containment a run requires: our own pinned catalog entry is the trust anchor, a recognized publisher is semi-trusted, and anything else is untrusted by default and may only run where it can be genuinely contained.
The package is pure: it parses a reference, names the weight format, and maps the source to a trust level. It performs no I/O, so the classification is fully testable and is the same whatever calls it. Fetching, pinning, and running compose on top.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckRunnableFormat ¶
CheckRunnableFormat refuses a format that cannot be safely parsed: a code-executing format outright, and an unrecognized one conservatively. Only the safe-parse formats (GGUF, safetensors) are allowed. This holds for every source, not only catalog fetches, so a dropped pickle file is refused the same as a downloaded one.
func KnownPublisher ¶
KnownPublisher reports whether a hub owner is a recognized first-party publisher. Extra owners (for example the publishers already named in the embedded catalog) can be supplied so a source a curator already vouched for is recognized too.
Types ¶
type Classification ¶
type Classification struct {
// Trust is the sandbox trust level the source maps to, which sets the containment a
// run requires through sandbox.Required.
Trust sandbox.Trust
// Reason is a short, plain-language explanation of why the source got this trust.
Reason string
}
Classification is the trust decision for a source: the containment-setting trust level and a plain-language reason a user can be shown.
func Classify ¶
func Classify(s Source, knownPublisher func(owner string) bool) Classification
Classify maps a source to a trust level. The embedded catalog is the trust anchor, so a catalog entry is trusted. A hub model from a recognized publisher is semi-trusted: the publisher is reputable but the bytes are still parsed by a vulnerable runtime, so it needs kernel confinement. Everything else (an unknown publisher, a raw URL, a local file) is untrusted by default and may run only where it can be genuinely contained. knownPublisher reports whether a hub owner is a recognized first-party publisher.
type Integrity ¶
type Integrity int
Integrity is what is known about a model's bytes: whether they have been verified against a digest, and how strong that pin is.
const ( // IntegrityUnverified means no digest has been established for the source yet, so // its bytes carry no integrity claim. IntegrityUnverified Integrity = iota // IntegrityTOFU means the digest was pinned on first use (trust on first use): a // later fetch that does not match is refused, but the first fetch trusted whoever // answered. IntegrityTOFU // IntegrityPinned means the digest was pinned ahead of time by a curator (a catalog // entry), the strongest claim: the bytes are exactly what was vetted offline. IntegrityPinned )
type Kind ¶
type Kind int
Kind is where a model's weights come from. The kind alone does not decide trust (a publisher still matters), but it decides how the reference is resolved to bytes.
const ( // KindCatalog is a blessed entry in the embedded catalog: pinned URL and digest, // vetted offline. The catalog is the trust anchor, independent of any live registry. KindCatalog Kind = iota // KindHuggingFace is a model-hub reference, hf:owner/repo[/file] or a huggingface.co // URL. The owner is the publisher whose reputation the trust decision turns on. KindHuggingFace // KindURL is a direct https link to a weights file from no recognized publisher. KindURL // KindFile is a local weights file a user points at or drops in. KindFile )
type Ledger ¶
type Ledger struct {
// contains filtered or unexported fields
}
Ledger persists model-source provenance to a single JSON file, keyed by source key. It is the trust-on-first-use store and the audit log in one: the first time a source is fetched its digest is pinned here, and every later fetch is checked against it. Access is mutex-guarded within a process and the file is rewritten atomically, so a concurrent reader never sees a partial file. A corrupt ledger is read as empty rather than wedging a run, the same default-open-to-rebuild posture the runtime registry uses.
func (*Ledger) Get ¶
func (l *Ledger) Get(key string) (Provenance, bool, error)
Get returns the record for a source key, and whether one exists.
func (*Ledger) List ¶
func (l *Ledger) List() ([]Provenance, error)
List returns all provenance records, sorted by key. A missing or unreadable file is an empty ledger, not an error.
func (*Ledger) PinnedDigest ¶
PinnedDigest returns the digest recorded for a source key, and whether one is pinned. A caller passes it to the verified fetch as the expected digest, so a source pinned once cannot be swapped underneath a later run.
func (*Ledger) Record ¶
func (l *Ledger) Record(p Provenance) error
Record inserts or updates the provenance for its key and persists the ledger. It preserves FirstSeen on an update so the audit trail keeps the original sighting.
type Provenance ¶
type Provenance struct {
// Key is the stable source key (see Source.Key), the record's primary key.
Key string `json:"key"`
// Raw is the original reference the user supplied.
Raw string `json:"raw"`
// Trust is the classified trust level, recorded as its plain name.
Trust string `json:"trust"`
// Format is the detected weight format name.
Format string `json:"format,omitempty"`
// Digest is the sha256 the source's bytes were pinned to, "sha256:..." form. Empty
// until the weights have been fetched and verified at least once.
Digest string `json:"digest,omitempty"`
// FirstSeen and LastVerified are Unix times, for audit. FirstSeen is when the source
// was first recorded; LastVerified is the most recent successful integrity check.
FirstSeen int64 `json:"firstSeen,omitempty"`
LastVerified int64 `json:"lastVerified,omitempty"`
}
Provenance is the durable record of a model source: where it came from, how it was classified, the weight format, and the content digest that was pinned for it. It is the audit trail for a run and, through the digest, the trust-on-first-use anchor: a source whose digest was pinned once is refused later if its bytes no longer match. No secret is ever recorded.
type RiskSurface ¶
type RiskSurface struct {
// Source is the original reference.
Source string
// Trust is the classified trust level.
Trust sandbox.Trust
// TrustReason is the plain-language reason for the trust level.
TrustReason string
// Required is the containment the trust level demands to run.
Required sandbox.Containment
// Integrity is what is known about the bytes.
Integrity Integrity
// Egress states the network posture of a local model run. A local model is served on
// a loopback port and needs no outbound access, so egress is denied; surfacing it
// tells the user a model cannot phone home.
Egress string
}
RiskSurface is the plain-language summary of what running a model means: how far its source is trusted, the isolation that trust requires, whether its bytes are verified, and its network posture. It is what a user is shown before a model is run, so the risk is visible without reading any documentation.
func DescribeRisk ¶
func DescribeRisk(src Source, class Classification, integrity Integrity) RiskSurface
DescribeRisk builds the risk surface for a classified source. The containment comes from the trust level through the same gate the run uses, so what the user is shown is exactly what is enforced.
func (RiskSurface) Lines ¶
func (r RiskSurface) Lines() []string
Lines renders the risk surface as plain-language lines for display. Each line is a single fact a non-expert can read: what the source is, how trusted, how isolated, how verified, and its network posture.
func (RiskSurface) Risky ¶
func (r RiskSurface) Risky() bool
Risky reports whether running this source is a risk a user must explicitly accept: any source that is not a vetted, trusted catalog entry. A trusted source runs without a consent prompt; everything else is a deliberate choice.
type Source ¶
type Source struct {
// Kind is how the reference resolves to bytes.
Kind Kind
// Raw is the original reference string, kept for provenance and messages.
Raw string
// CatalogID is the catalog entry id, when KindCatalog.
CatalogID string
// Owner and Repo identify a hub model, when KindHuggingFace. File is the optional
// specific weights file within the repo.
Owner, Repo, File string
// URL is the direct download location, when KindURL.
URL string
// Path is the local file path, when KindFile.
Path string
}
Source is a parsed, not-yet-fetched model reference. Exactly the fields for its Kind are populated.
func Parse ¶
Parse classifies a reference string into a Source. isCatalogID reports whether a bare string names a known catalog entry, so a catalog id is recognized before it is treated as anything else. The grammar is deliberately small and unambiguous: a catalog id, an hf: prefix or a huggingface.co URL, any other https URL, or a local path.
type WeightFormat ¶
type WeightFormat int
WeightFormat is the on-disk encoding of a weights file, which decides whether loading it can execute code.
const ( // FormatUnknown is an extension we do not recognize. It is refused, since an // unrecognized container cannot be assumed safe to parse. FormatUnknown WeightFormat = iota // FormatGGUF is the single-file quantized format, read by the hardened reader. FormatGGUF // FormatSafetensors stores tensors only and executes no code on load. FormatSafetensors // FormatCodeExecuting is a format that can run arbitrary code when loaded (a Python // pickle, or an archive that could carry one). It is refused everywhere. FormatCodeExecuting )
func DetectFormat ¶
func DetectFormat(name string) WeightFormat
DetectFormat names the weight format from a filename or path by its extension. An empty or extension-less name is unknown, not assumed safe.
Source Files