Documentation
¶
Overview ¶
Package packaging holds the tar.gz archive primitives shared by every installable Patchcord package format (.patchcord-app, .patchcord-plugin, .patchcord-bundle): archiving a validated source directory, and safely extracting an untrusted archive back onto disk. Format-specific concerns — manifest parsing, where extracted files end up under dataDir, what happens after extraction — stay in each format's own package (internal/apps, internal/plugins, internal/bundles).
Index ¶
Constants ¶
const ( ChecksumsFileName = "checksums.json" SignatureFileName = "signature.json" )
ChecksumsFileName and SignatureFileName are the reserved root-level names SignedArchive writes and Verify reads (vision document, section 9.1). computeChecksums always skips them: they describe a package's content, they are not part of it.
Variables ¶
var ErrChecksumMismatch = errors.New("package checksum mismatch")
ErrChecksumMismatch is returned by Verify when an extracted package's files do not match its checksums.json — corruption or tampering, never a soft warning regardless of the caller's signing policy.
var ErrInvalidSignature = errors.New("package signature is invalid")
ErrInvalidSignature is returned by Verify when a package's signature.json does not verify against its checksums.json — same treatment as ErrChecksumMismatch, always a hard failure.
Functions ¶
func Archive ¶
Archive walks sourceDir and writes it to w as a gzip-compressed tar stream. Only regular files and directories are supported; any other entry type (symlink, device, ...) fails the archive rather than producing a silently incomplete one.
func Extract ¶
Extract extracts a gzip-compressed tar stream (as produced by Archive) into destDir, which must already exist. Every entry is written with mode 0o644 regardless of what the archive's header claims — an archive is untrusted input, so its declared file mode (which could set unusual bits such as setuid) is never trusted. Callers that need an extracted file to be executable (a plugin binary, for instance) must chmod it explicitly after Extract returns.
func SafeJoin ¶
SafeJoin joins destDir and name, rejecting any entry (typically one using "../" components, a "zip slip") whose resolved path would escape destDir. Archives are untrusted input — see the security review requirements in CLAUDE.md (OWASP top 10: path traversal).
func SignedArchive ¶
SignedArchive archives sourceDir exactly like Archive, plus a checksums.json covering every file in sourceDir. If key is non-nil, it also signs checksums.json's exact bytes with Ed25519 and adds signature.json. key == nil produces a package with integrity data but no provenance — the default when `pack` is run without --sign-key.
Types ¶
type VerificationOutcome ¶
type VerificationOutcome struct {
// Checksummed is true if the package had a checksums.json and every
// file matched it. A package with no checksums.json at all (produced
// before this feature existed, or packed without signing support)
// reports false here, not an error.
Checksummed bool
// Signed is true if the package had a signature.json and its Ed25519
// signature over checksums.json verified.
Signed bool
// PublicKey is the key signature.json was verified with. Only
// meaningful when Signed is true.
PublicKey ed25519.PublicKey
}
VerificationOutcome reports what Verify found. It carries no verdict of its own — whether a caller treats an unsigned or untrusted package as acceptable is a policy decision made above internal/packaging (see internal/apps, internal/plugins, internal/bundles InstallPackage, and internal/trust).
func Verify ¶
func Verify(dir string) (VerificationOutcome, error)
Verify checks an already-extracted package directory's integrity and authenticity:
- no checksums.json at all: VerificationOutcome{}, nil — an old-style or deliberately unsigned package, not an error.
- checksums.json present but any file's digest doesn't match: ErrChecksumMismatch.
- checksums.json matches, no signature.json: {Checksummed: true}, nil.
- signature.json present: its Ed25519 signature is checked against checksums.json's raw stored bytes (never a recomputed serialization — avoids any JSON-encoding determinism concern). Invalid: ErrInvalidSignature. Valid: {Checksummed: true, Signed: true, PublicKey: ...}.
Verify never consults a trust store and knows nothing about package ids — it only proves "this is what was signed", not "this signer is legitimate for this package".
Source Files