Documentation
¶
Overview ¶
Package archive is the public release-archive toolkit: the deterministic tar.zst builder that gives every release its content-addressed identity, the hardened extractor for untrusted archives, the trusted unpacker clients use on registry-built archives, and the content sniffers behind the S1 inventory and `agentry validate` parity. The server and the CLI both build on this package, which is what makes "the CLI runs the same checks the server runs" true by construction.
Index ¶
- Variables
- func Extract(r io.Reader, dst string, compressedSize int64, lim ExtractLimits) error
- func Head(data []byte) []byte
- func IsArchiveData(data []byte) bool
- func IsExecutable(data []byte) bool
- func IsImagePath(path string) bool
- func LooksText(head []byte) bool
- func Unpack(r io.Reader, dst string, maxFile, maxTotal int64) error
- func WalkWorkspace(root string) ([]manifest.FileInfo, error)
- type ArchiveInfo
- type ExtractLimits
Constants ¶
This section is empty.
Variables ¶
var ErrArchiveViolation = errors.New("archive: violation")
ErrArchiveViolation marks a rejected archive (structural attack).
Functions ¶
func Extract ¶
Extract unpacks a tar.zst archive from r into dst with full hardening. compressedSize (bytes) enables the ratio check; pass 0 to skip it.
func Head ¶
Head returns the first 512 bytes of data, the window the sniffers use. Nothing in this repo calls it directly — the sniffers take the whole buffer — but it is part of pkg/archive's shared surface: the CLI and the desktop app feed it to LooksText so their offline scans classify files exactly as S1 does. Keep it.
func IsArchiveData ¶
IsArchiveData reports whether data is a compressed container (zip, gzip, zstd, bzip2, xz) or a tar, whose "ustar" magic lives at offset 257.
func IsExecutable ¶
IsExecutable reports whether data opens with an executable or shared library signature (ELF, Mach-O, PE, Java class).
func IsImagePath ¶
IsImagePath reports whether path has a recognized raster-image extension.
func LooksText ¶
LooksText reports whether head is plausibly text: no NUL byte, and under 5% control characters. Pass at most the first ~512 bytes.
func Unpack ¶
Unpack extracts a tar.zst release archive into dst with basic hardening: path traversal, absolute paths, links, and non-regular entries rejected; per-file and total size caps enforced.
Unpack is for archives the registry itself built and signed — the client side of an install, after digest and signature verification. For UNTRUSTED input use Extract, which adds the file-count cap, the compression-ratio check, and the decoder memory bound.
Types ¶
type ArchiveInfo ¶
ArchiveInfo describes a built archive.
func BuildArchive ¶
BuildArchive writes the deterministic tar.zst of the include-filtered workspace to w and returns its identity: sorted entries, zeroed mtimes, normalized modes, fixed uid/gid. Callers MUST have validated the manifest (V4) against the same file list first.
type ExtractLimits ¶
type ExtractLimits struct {
MaxFileBytes int64
MaxTotalBytes int64
MaxFiles int
// MaxRatio caps decompressed/compressed; 0 disables the check.
MaxRatio int64
}
ExtractLimits bounds a safe extraction (the release-archive quotas plus a decompression cap).
func DefaultLimits ¶
func DefaultLimits() ExtractLimits
DefaultLimits are the release-archive quotas, raised by the most a release may ship in knowledge packs: the extractor bounds what any archive can unpack to, and the manifest's V8 holds each release to its own quotas and each pack to a pack's.