archive

package
v0.6.1000-dev.3 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 12 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrArchiveViolation = errors.New("archive: violation")

ErrArchiveViolation marks a rejected archive (structural attack).

Functions

func Extract

func Extract(r io.Reader, dst string, compressedSize int64, lim ExtractLimits) error

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(data []byte) []byte

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

func IsArchiveData(data []byte) bool

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

func IsExecutable(data []byte) bool

IsExecutable reports whether data opens with an executable or shared library signature (ELF, Mach-O, PE, Java class).

func IsImagePath

func IsImagePath(path string) bool

IsImagePath reports whether path has a recognized raster-image extension.

func LooksText

func LooksText(head []byte) bool

LooksText reports whether head is plausibly text: no NUL byte, and under 5% control characters. Pass at most the first ~512 bytes.

func Unpack

func Unpack(r io.Reader, dst string, maxFile, maxTotal int64) error

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.

func WalkWorkspace

func WalkWorkspace(root string) ([]manifest.FileInfo, error)

WalkWorkspace lists regular files (and flags symlinks) under root as repo-relative FileInfos for validation and archiving.

Types

type ArchiveInfo

type ArchiveInfo struct {
	Digest string // "sha256:<hex>"
	Size   int64
	Files  []manifest.FileInfo
}

ArchiveInfo describes a built archive.

func BuildArchive

func BuildArchive(root string, include []manifest.FileInfo, w io.Writer) (ArchiveInfo, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL