plthook/error.rs
1//! Typed, thread-safe error model for the import-rebinding engine.
2//!
3//! The C `plthook` returns integer codes and stashes a description in a
4//! out as a defect to fix. Here every fallible operation returns a typed
5//! [`Error`] with structured fields — no shared mutable error buffer, no
6//! stringly-typed channel — so failures are inspectable and thread-safe.
7
8/// Errors produced by the engine while acquiring, parsing, or patching a module.
9#[derive(Debug, thiserror::Error)]
10#[non_exhaustive]
11pub enum Error {
12 /// A requested module could not be located in the current process
13 /// (`GetModuleHandleExW` failed, or a null handle was supplied).
14 #[error("module not found: {reason} (os error {os_error})")]
15 ModuleNotFound {
16 /// What was being resolved (a handle, an address, or a name).
17 reason: &'static str,
18 /// `GetLastError()` captured at the failure site.
19 os_error: u32,
20 },
21
22 /// The loader reported no valid mapped size for the module, so no bounded
23 /// range exists to parse against.
24 #[error("could not determine the mapped size of module at {base:#x} (os error {os_error})")]
25 ImageSizeUnknown {
26 /// Module base address (`HMODULE`).
27 base: usize,
28 /// `GetLastError()` captured at the failure site.
29 os_error: u32,
30 },
31
32 /// A structural defect was found while parsing the mapped image (PE or ELF).
33 /// The parser bounds-checks every field against the validated mapped range
34 /// *before* dereferencing, so a malformed image yields this error rather than
35 #[error("malformed image: {0}")]
36 Malformed(&'static str),
37
38 /// The image is a valid PE/ELF the engine intentionally does not handle at
39 /// runtime (e.g. a 32-bit PE32 image inside a 64-bit process, a legacy
40 /// absolute-VA delay-import descriptor, or an ELF machine that is not
41 /// `EM_X86_64`/`EM_AARCH64`). Reported rather than guessed.
42 #[error("unsupported image: {0}")]
43 Unsupported(&'static str),
44
45 /// A `Replacement` marked `required` matched no import slot in the module.
46 #[error("required symbol not found in module `{module}`: {symbol}")]
47 SymbolNotFound {
48 /// Module name the lookup ran against.
49 module: String,
50 /// The symbol that was requested but not imported.
51 symbol: String,
52 },
53
54 /// A matched import's canonical original entry point could not be resolved,
55 /// so passing through to it is impossible. This arises for a **delay-load**
56 /// import whose providing DLL cannot be loaded (or whose symbol is absent
57 /// from it): the delay IAT slot holds only the `__delayLoadHelper2` stub
58 /// until first call, and the engine refuses to hand a stub out as the
59 /// original (calling it would resolve the import and overwrite the very slot
60 /// we patched, silently dropping the hook). Reported for a `required`
61 /// replacement; an `optional` one skips the slot instead.
62 #[error(
63 "could not resolve the original entry point for `{symbol}` from `{library}` \
64 (delay-load provider unavailable) in module `{module}`"
65 )]
66 OriginalUnresolved {
67 /// Module whose import was being hooked.
68 module: String,
69 /// Providing (delay-load) library that could not be resolved.
70 library: String,
71 /// The symbol whose original could not be resolved.
72 symbol: String,
73 },
74
75 /// A matched import slot holds an **authenticated** (PAC-signed) pointer — an
76 /// it would require a replacement signed with the slot's key, diversity, and
77 /// address-discrimination, which cannot be synthesized here; the engine refuses
78 /// the slot rather than write a pointer that fails its `AUT*` check (or is
79 /// dereferenced unsigned). arm64e support is a dedicated, device-tested effort;
80 /// plain arm64 and x86-64 slots are never authenticated and are unaffected.
81 #[error(
82 "refusing to rebind authenticated (arm64e PAC-signed) import `{symbol}` in \
83 module `{module}`: authenticated slots require dedicated PAC support"
84 )]
85 AuthenticatedSlot {
86 /// Module whose authenticated import was matched.
87 module: String,
88 /// The symbol whose slot is authenticated.
89 symbol: String,
90 },
91
92 /// Changing a slot page's protection failed. Carries the slot address and
93 /// the OS error. When this happens mid-install the engine rolls back every
94 #[error("VirtualProtect failed for slot {slot:#x}: os error {os_error}")]
95 Protect {
96 /// Address of the import slot whose page could not be reprotected.
97 slot: usize,
98 /// `GetLastError()` from the failing `VirtualProtect` call.
99 os_error: u32,
100 },
101
102 /// During restore, a slot no longer held this guard's replacement pointer,
103 /// untouched and reports the conflict instead (compare-exchange restore,
104 #[error(
105 "restore conflict at slot {slot:#x}: expected {expected:#x}, found {found:#x} \
106 (a subsequent hook owns this slot; left untouched)"
107 )]
108 RestoreConflict {
109 /// Address of the conflicted import slot.
110 slot: usize,
111 /// The replacement pointer this guard installed and expected to find.
112 expected: usize,
113 /// The pointer actually present in the slot.
114 found: usize,
115 },
116}
117
118/// Crate-local result alias.
119pub type Result<T> = core::result::Result<T, Error>;