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
//! Verification trait.
//!
//! # Architecture
//! This module defines the abstract contract for verifying cryptographic signatures.
//! It is the counterpart to the [`Signer`](crate::traits::core::signer::Signer) module.
//! By abstracting verification into a trait, the crate allows the core engine to
//! authenticate commits and tags without being coupled to a specific cryptographic
//! backend (e.g., GPG, SSH, or X.509).
//!
//! # Design Rationale: Stateless Verification
//! Unlike signing, which may require stateful operations (e.g., consuming nonces or
//! locking hardware tokens), signature verification is a pure, stateless mathematical
//! operation. It only requires the public key, the raw data, and the signature.
//! Therefore, the `verify` method takes `&self` instead of `&mut self`. This allows
//! multiple threads to concurrently verify different commits in a revision graph
//! without any synchronization overhead.
use crateVctrlError;
/// Trait for verifying signatures.
///
/// # Why this exists
/// Provides a unified interface for authenticating data. In Git, verifying signed
/// commits and tags ensures that the authorship is genuine and the data has not been
/// tampered with. This trait allows the engine to delegate the complex cryptography
/// to a dedicated backend, ensuring that the core logic remains agnostic of the
/// underlying Public Key Infrastructure (PKI).
///
/// # How it works
/// The implementor receives a `key_id` (to locate the correct public key), the raw
/// `data` that was signed, and the `signature` bytes. The backend applies the
/// verification algorithm (e.g., RSA-SHA256, Ed25519) to confirm that the signature
/// was indeed generated by the owner of the private key corresponding to the public key.
///
/// # Design Rationale: `Result<bool, VctrlError>`
/// The return type distinguishes between a cryptographic failure and a system failure:
/// - `Ok(true)`: The signature is mathematically valid.
/// - `Ok(false)`: The signature is mathematically invalid (tampered data or wrong key).
/// - `Err(VctrlError)`: A system error occurred (e.g., public key not found, I/O error
/// reading the keyring, or unsupported algorithm).
/// This prevents confusing an invalid signature with a system-level fault, allowing
/// callers to handle security violations explicitly.
///
/// # Examples
///
/// Implementing the trait for a mock verifier:
///
/// ```
/// # use libvctrl_handler::traits::core::verifier::Verifier;
/// # use libvctrl_handler::VctrlError;
/// #
/// struct MockVerifier;
///
/// impl Verifier for MockVerifier {
/// fn verify(&self, key_id: &str, data: &[u8], signature: &[u8]) -> Result<bool, VctrlError> {
/// // A real implementation would use a public key here.
/// if key_id != "trusted_key" {
/// return Ok(false); // Unknown key implies invalid signature
/// }
/// Ok(data == signature) // Simplified mock verification
/// }
/// }
///
/// let verifier = MockVerifier;
/// let data = b"commit data";
/// let sig = b"commit data";
///
/// assert!(verifier.verify("trusted_key", data, sig)?);
/// assert!(!verifier.verify("untrusted_key", data, sig)?);
/// # Ok::<(), VctrlError>(())
/// ```