Enum ToolsetInstallError 

#[non_exhaustive]
pub enum ToolsetInstallError {
    Io {
        detail: String,
    },
    PackageTooLarge {
        cap: usize,
    },
    HashMismatch,
    SignatureInvalid,
    UntrustedPublisher {
        publisher_key_redacted: String,
    },
    TrustSetEmpty,
    TrustSetMalformed {
        detail: String,
    },
    InvalidVersion {
        detail: String,
    },
    InvalidShasum {
        detail: String,
    },
    InvalidPackageName {
        detail: String,
    },
    ArchivePathTraversal {
        entry_name: String,
    },
    ArchiveEntryNameInvalid {
        detail: String,
    },
    ArchiveDisallowedEntryType,
    ArchiveDuplicateEntry {
        entry_name: String,
    },
    ArchiveTooManyEntries {
        cap: usize,
    },
    ArchiveEntryTooLarge {
        cap: usize,
    },
    ArchiveTooLarge {
        cap: usize,
    },
    ArchiveTrailingData,
    ArchiveBadTopLevel {
        detail: String,
    },
    ToolsetFormat(ToolsetFormatError),
    IdentityMismatch {
        field: &'static str,
        extracted: String,
        expected: String,
    },
    AlreadyInstalled {
        package: String,
        installed_version: String,
    },
    VersionDowngrade {
        new_version: String,
        installed_version: String,
    },
    NotInstalled {
        package: String,
    },
    PinRecordMalformed {
        detail: String,
    },
    ToolsetsRootInvalid {
        detail: String,
    },
    AttestationRequired {
        package: String,
    },
    AttestationInvalid {
        detail: &'static str,
    },
    AuditorUntrusted {
        auditor_key_redacted: String,
    },
    AttestationFieldMismatch {
        field: &'static str,
    },
}

Typed closed-set error for toolset install and uninstall operations.

Variant overview

Variant	Trigger
Io	OS-level I/O failure (file open, read, write, rename, remove).
PackageTooLarge	Package bytes exceed crate::MAX_PACKAGE_BYTES.
HashMismatch	SHA-256 of package bytes ≠ signed shasum.
SignatureInvalid	ed25519 publisher signature fails verify_strict.
UntrustedPublisher	Signer public key not in the publisher trust set.
TrustSetEmpty	Trust-set file is absent or contains no entries (publisher or auditor).
TrustSetMalformed	Trust-set file contains a malformed or duplicate entry.
InvalidVersion	Version string fails SemVer parse or length cap.
InvalidShasum	signed_shasum argument is not exactly 64 lowercase hex chars.
InvalidPackageName	Package name fails the [a-z0-9-] validation rule.
ArchivePathTraversal	Archive entry path escapes the package root.
ArchiveEntryNameInvalid	Archive entry name contains NUL, control bytes, non-UTF-8, or non-ASCII.
ArchiveDisallowedEntryType	Archive entry is a symlink, hardlink, device, FIFO, or other disallowed type.
ArchiveDuplicateEntry	Two archive entries normalise to the same ASCII-lowercase key.
ArchiveTooManyEntries	Archive entry count exceeds the cap.
ArchiveEntryTooLarge	A single entry’s decompressed size exceeds the per-entry cap.
ArchiveTooLarge	Total decompressed output exceeds the cap.
ArchiveTrailingData	Gzip stream contains trailing data after the first member (multi-member or garbage rejected).
ArchiveBadTopLevel	Archive does not contain exactly one top-level directory named after the package.
ToolsetFormat	TOOLSET.md parse/validation failed (wraps ToolsetFormatError).
IdentityMismatch	Extracted TOOLSET.md name ≠ signed package name. Version is bound by signature.
AlreadyInstalled	Toolset is already installed and --force was not supplied.
VersionDowngrade	--force reinstall would downgrade the version; requires --allow-downgrade.
NotInstalled	Uninstall requested for a toolset that is not installed.
PinRecordMalformed	Stored pin record is invalid (bad name, escaping path, or symlink target) during uninstall.
ToolsetsRootInvalid	The toolsets root directory itself is a symlink leaf (install-time check).
AttestationRequired	Toolset declares a key-touching capability but no attestation was supplied and override_attestation is false.
AttestationInvalid	Attestation signature fails verify_strict, or auditor_pubkey is not a valid ed25519 point.
AuditorUntrusted	Auditor public key is not in the auditor trust set.
AttestationFieldMismatch	An attestation field (package/version/shasum/capabilities) does not match the verified install values.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Io

OS-level I/O error.

The detail string is sanitised (length-capped at 256 chars, control/ANSI stripped) to prevent log-injection.

Fields

detail: String

Sanitised I/O error detail (std::io::Error Display, capped + stripped).

PackageTooLarge

Package bytes exceed the maximum allowed size.

The size limit prevents OOM on untrusted sources; reading is aborted as soon as the limit is reached.

Fields

cap: usize

Configured cap in bytes.

HashMismatch

SHA-256 of the package bytes does not match the signed shasum.

This indicates either data corruption or a tampered package.

SignatureInvalid

ed25519 signature failed verify_strict.

The signature was well-formed but cryptographically invalid for the signed payload and claimed publisher key.

UntrustedPublisher

The signer public key is not present in the trust set.

The publisher key is redacted to first-5-last-5 in Display output.

Fields

publisher_key_redacted: String

Publisher G-strkey, redacted to first-5-last-5.

TrustSetEmpty

Trust-set file is absent or contains no entries.

An empty trust set means no toolset can be installed (fail-closed).

TrustSetMalformed

Trust-set file contains a malformed or duplicate entry.

The entire file is rejected on any single bad entry (ALL-OR-NOTHING parse contract).

Fields

detail: String

Sanitised description of the malformed entry.

InvalidVersion

Version string fails SemVer parse or exceeds the length cap.

For package-name failures see ToolsetInstallError::InvalidPackageName. For shasum format failures see ToolsetInstallError::InvalidShasum.

Fields

detail: String

Sanitised description of the parse failure.

InvalidShasum

Shasum argument fails format validation.

The signed_shasum argument must be exactly 64 lowercase hexadecimal characters ([0-9a-f]). Uppercase hex digits, wrong length, or non-hex characters all trigger this variant before any hash comparison or signature verification.

Fields

detail: String

Sanitised description of the format failure.

InvalidPackageName

Package name fails the [a-z0-9-] validation rule.

A package name must be non-empty, ≤ 64 characters, contain only lowercase ASCII letters, digits, and hyphens, and must not start, end, or contain consecutive hyphens.

Fields

detail: String

Sanitised description of the validation failure.

ArchivePathTraversal

Archive entry path escapes the package root.

Triggered by .. components, absolute paths, drive prefixes, or root-only paths.

Fields

entry_name: String

Sanitised entry name (length-capped, control/ANSI stripped).

ArchiveEntryNameInvalid

Archive entry name contains NUL, control bytes, or non-UTF-8 bytes.

Entry names are validated before any path comparison.

Fields

detail: String

Sanitised description of the invalid name.

ArchiveDisallowedEntryType

Archive entry is a disallowed type (symlink, hardlink, device, FIFO, etc.).

Type check is performed FIRST, before any path or body read.

ArchiveDuplicateEntry

Two archive entries normalise to the same ASCII-lowercase key.

Rejected to prevent APFS/HFS+ case-folding attacks. ASCII-lowercase collision detection is used; full Unicode NFC+case-fold is not yet implemented.

Fields

entry_name: String

Sanitised entry name that triggered the collision.

ArchiveTooManyEntries

Archive entry count exceeds the configured cap.

Fields

cap: usize

Configured entry count cap.

ArchiveEntryTooLarge

A single entry’s decompressed size exceeds the per-entry cap.

Fields

cap: usize

Per-entry decompressed byte cap.

ArchiveTooLarge

Total decompressed output exceeds the cap.

Fields

cap: usize

Total decompressed byte cap.

ArchiveTrailingData

Gzip stream contains trailing data after the first member.

Any non-zero byte after the first gzip footer is rejected — whether it forms a second gzip member (multi-member concatenation) or is arbitrary garbage. Only tar end-of-archive zero padding is tolerated.

ArchiveBadTopLevel

Archive top-level shape is invalid.

A valid package must contain exactly one top-level directory whose name equals the package name.

Fields

detail: String

Sanitised description of the top-level shape found.

ToolsetFormat(ToolsetFormatError)

TOOLSET.md parse or validation failed.

Wraps ToolsetFormatError; the staging directory is rolled back on this error.

IdentityMismatch

Extracted TOOLSET.md name does not match the signed package name.

Version identity is established by the SIGNATURE BINDING — the signed tuple includes the version string, so a package cannot be relabeled to a different version without invalidating the signature. Only the name field is content-cross-checked here because TOOLSET.md carries a name but no version field.

The field is always "name" in current code; "version" is reserved for a future format revision that adds a version field to TOOLSET.md.

Fields

field: &'static str

Which field mismatched ("name"; "version" reserved for future use).

extracted: String

The value found in the extracted TOOLSET.md (sanitised).

expected: String

The value from the signed package identity tuple (sanitised).

AlreadyInstalled

Toolset is already installed and --force was not supplied.

Fields

package: String

Package name (validated [a-z0-9-]).

installed_version: String

Currently installed version string.

VersionDowngrade

--force reinstall would downgrade the installed version.

Downgrade (installing an older version over a newer one) is refused by default; pass --allow-downgrade to override.

Fields

new_version: String

New version being installed.

installed_version: String

Currently installed version.

NotInstalled

Uninstall was requested for a toolset that is not installed.

Fields

package: String

Package name requested for uninstall (validated).

PinRecordMalformed

The stored pin record is invalid.

Triggered during uninstall when the pin record’s package name fails validation or the reconstructed path escapes the toolsets root or resolves to a symlink. NOT used for install-time toolsets-root checks; see ToolsetInstallError::ToolsetsRootInvalid for those.

Fields

detail: String

Sanitised description of the malformed field.

ToolsetsRootInvalid

The toolsets root directory is invalid at install time.

Triggered when the toolsets root directory leaf is a symlink (no-follow discipline). Distinct from ToolsetInstallError::PinRecordMalformed which covers uninstall pin-record issues.

Fields

detail: String

Sanitised description of the invalid root.

AttestationRequired

Toolset declares a key-touching capability but no attestation was supplied and override_attestation is false.

A key-touching toolset (e.g. sign-payment) MUST be accompanied by a valid auditor attestation when override_attestation is false. Absent attestation → install is refused before any artefact is written.

Fields

package: String

Package name (validated [a-z0-9-]).

AttestationInvalid

Attestation signature is cryptographically invalid.

Covers both cases opaquely:

• auditor_pubkey is not a valid compressed ed25519 point.
• ed25519 verify_strict fails for the attestation signature over the canonical preimage.

The error is intentionally opaque — no key bytes, no signature bytes, no oracle for an attacker to distinguish the two cases.

Fields

detail: &'static str

Opaque, non-attacker-influenced description (&'static str).

Uses &'static str so no heap allocation occurs and the set of possible messages is closed at compile time.

AuditorUntrusted

Auditor public key is not in the auditor trust set.

The auditor key carried in the attestation is not present in <toolsets_dir>/auditor-trust.txt. Note that the auditor trust set is DISTINCT from the publisher trust set (trust.txt) — placing a key in trust.txt does NOT implicitly grant auditor status.

The auditor key is redacted to first-5-last-5 in Display.

Fields

auditor_key_redacted: String

Auditor G-strkey, redacted to first-5-last-5.

AttestationFieldMismatch

An attestation field does not match the verified install values.

One of package, version, shasum, or capabilities in the ToolsetAttestation struct does not equal the value from the verified install context. This prevents cross-package / version / capability replay attacks.

The field is a closed set of &'static str values — "package" / "version" / "shasum" / "capabilities" — so no attacker-controlled string reaches the error.

Fields

field: &'static str

Which field mismatched: "package" / "version" / "shasum" / "capabilities".

Closed set of &'static str — no attacker-influenced string.

Implementations

impl ToolsetInstallError

pub fn from_io(err: Error) -> Self

Constructs an ToolsetInstallError::Io from a std::io::Error.

The error’s Display string is sanitised (length-capped at 256 chars, control/ANSI stripped) to prevent log-injection.

Examples

use stellar_agent_toolsets_install::error::ToolsetInstallError;

let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file not found");
let err = ToolsetInstallError::from_io(io_err);
assert!(matches!(err, ToolsetInstallError::Io { .. }));

Trait Implementations

impl Debug for ToolsetInstallError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ToolsetInstallError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ToolsetInstallError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ToolsetFormatError> for ToolsetInstallError

fn from(source: ToolsetFormatError) -> Self

Converts to this type from the input type.