1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
//! Error types for envseal.
use std::fmt;
/// All errors that can occur in envseal operations.
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
/// Secret with the given name was not found in the vault.
SecretNotFound(String),
/// Secret with the given name already exists.
SecretAlreadyExists(String),
/// Encryption or decryption failed.
CryptoFailure(String),
/// Failed to read or write vault files.
StorageIo(std::io::Error),
/// Policy file could not be parsed.
PolicyParse(String),
/// The target binary is not whitelisted for this secret.
AccessDenied {
/// Name of the secret that was requested.
secret_name: String,
/// Path to the binary that was denied.
binary_path: String,
},
/// The user denied access via the GUI popup.
UserDenied,
/// No GUI display available (headless environment).
NoDisplay,
/// Failed to resolve the binary path.
BinaryResolution(String),
/// Failed to execute the child process.
ExecFailed(std::io::Error),
/// Hostile environment variables detected (`LD_PRELOAD`, etc.).
EnvironmentCompromised(String),
/// Binary hash does not match the stored hash (replaced or corrupted).
BinaryTampered {
/// Filesystem path to the binary.
binary_path: String,
/// Hash stored in policy at time of approval.
expected_hash: String,
/// Hash computed from the binary on disk right now.
actual_hash: String,
},
/// Policy file HMAC signature is invalid (tampering detected).
PolicyTampered(String),
/// Append-only audit log could not be written — operation aborted to preserve integrity.
AuditLogFailed(String),
/// Device-bound hardware seal (DPAPI / Secure Enclave / TPM 2.0) could
/// not wrap or unwrap a master-key envelope. The detail string carries
/// the platform-specific cause (`GetLastError` value, NTSTATUS,
/// `tpm2-tools` stderr, or Security.framework error string).
///
/// Distinct from [`Error::CryptoFailure`] because the recovery path
/// is different: hardware-seal errors are usually device-state
/// problems (TPM owner cleared, keychain reset, user-logon
/// changed), not corruption.
HardwareSealFailed(String),
/// A vault file is sealed by one hardware backend but the active
/// device is using a different backend. This is the precise
/// signal that someone has copied `master.key` to another machine.
DeviceMismatch {
/// Backend that produced the on-disk envelope (e.g. `Windows DPAPI`).
sealed_by: String,
/// Backend currently available on this device (e.g. `macOS Secure Enclave`).
active: String,
},
/// Approval relay was configured as required but failed to deliver
/// an Allow/Deny decision. Detail carries the underlying cause.
/// Holding this distinct from [`Error::CryptoFailure`] makes
/// fail-closed behavior auditable in logs.
RelayRequiredButUnavailable(String),
/// Vault is enrolled with a FIDO2 authenticator but no
/// authenticator was supplied to the unlock path. The caller is
/// expected to attach one (CLI: physical key prompt; tests: mock
/// backend) and retry.
Fido2Required,
/// FIDO2 authenticator was supplied but the assertion failed —
/// wrong credential, no user-presence touch, PIN required, or
/// device communication error. Detail carries the cause from the
/// authenticator backend.
Fido2AssertionFailed(String),
/// Caller attempted to disable / change FIDO2 enrollment on a
/// vault that has no enrollment. Distinct from `CryptoFailure` so
/// CLI surfaces a clean "vault has no FIDO2 enrollment" instead
/// of a generic crypto error.
Fido2NotEnrolled,
}
impl fmt::Display for Error {
#[allow(clippy::too_many_lines)] // long match over a wide variant set, no logic
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::SecretNotFound(name) => {
write!(f, "secret not found in vault: {name}")
}
Self::SecretAlreadyExists(name) => {
write!(
f,
"secret already exists: {name} (use --force to overwrite)"
)
}
Self::CryptoFailure(detail) => {
write!(f, "cryptographic operation failed: {detail}")
}
Self::StorageIo(err) => {
write!(f, "vault storage i/o error: {err}")
}
Self::PolicyParse(detail) => {
write!(f, "failed to parse policy file: {detail}")
}
Self::AccessDenied {
secret_name,
binary_path,
} => {
write!(
f,
"access denied: {binary_path} is not authorized to access secret '{secret_name}'"
)
}
Self::UserDenied => {
write!(f, "access denied: user rejected the approval request")
}
Self::NoDisplay => {
write!(
f,
"no display server available — envseal requires a GUI session for approval"
)
}
Self::BinaryResolution(detail) => {
write!(f, "failed to resolve binary path: {detail}")
}
Self::ExecFailed(err) => {
write!(f, "failed to execute child process: {err}")
}
Self::EnvironmentCompromised(detail) => {
write!(f, "environment compromised — refusing to inject: {detail}")
}
Self::BinaryTampered {
binary_path,
expected_hash,
actual_hash,
} => {
write!(
f,
"binary tampered: {binary_path} hash mismatch — \
expected {expected_hash}, got {actual_hash}. \
the binary may have been replaced since it was approved."
)
}
Self::PolicyTampered(detail) => {
write!(
f,
"policy file tampered: HMAC signature verification failed — {detail}. \
the policy file may have been modified by an unauthorized process."
)
}
Self::AuditLogFailed(detail) => {
write!(f, "audit log write failed — refusing to continue: {detail}")
}
Self::HardwareSealFailed(detail) => {
write!(
f,
"hardware-bound key seal failed (DPAPI / Secure Enclave / TPM 2.0): {detail}"
)
}
Self::DeviceMismatch { sealed_by, active } => {
write!(
f,
"vault was sealed on a different device (backend: {sealed_by}); \
this machine uses {active}. master.key cannot move between machines — \
re-import the secrets here with `envseal import`."
)
}
Self::RelayRequiredButUnavailable(detail) => {
write!(
f,
"approval relay is required by policy but did not respond — \
refusing to fall back to local GUI: {detail}"
)
}
Self::Fido2Required => {
write!(
f,
"vault is enrolled with a FIDO2 authenticator but none was supplied — \
attach your security key and retry"
)
}
Self::Fido2AssertionFailed(detail) => {
write!(
f,
"FIDO2 authenticator assertion failed (wrong key, missing touch, \
or device error): {detail}"
)
}
Self::Fido2NotEnrolled => {
write!(
f,
"vault has no FIDO2 authenticator enrolled — \
run `envseal security fido2-enroll` first"
)
}
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::StorageIo(err) | Self::ExecFailed(err) => Some(err),
_ => None,
}
}
}
impl From<std::io::Error> for Error {
fn from(err: std::io::Error) -> Self {
Self::StorageIo(err)
}
}