dugout 0.1.10

Git-native secrets manager for development teams, written in Rust
Documentation 
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

//! Key management operations.
//!
//! Provides key generation and storage abstraction with implementations
//! for different storage backends.
//!
//! ## Adding a New Storage Backend
//!
//! 1. Implement the `Store` trait
//! 2. Add the implementation in a new file (e.g., `cloud.rs`, `vault.rs`)
//! 3. Re-export from this module
//!
//! ## Example
//!
//! ```ignore
//! struct Cloud { /* ... */ }
//!
//! impl Store for Cloud {
//!     fn generate_keypair(&self, project_id: &str) -> Result<String> {
//!         // Generate and store in cloud
//!     }
//!     fn load_identity(&self, project_id: &str) -> Result<Identity> {
//!         // Load from cloud
//!     }
//!     fn has_key(&self, project_id: &str) -> bool {
//!         // Check cloud storage
//!     }
//! }
//! ```

use crate::core::domain::Identity;
use crate::error::Result;

mod backend;
mod fs;

#[cfg(target_os = "macos")]
pub mod keychain;

pub use backend::default_backend;
pub use fs::Filesystem;

/// Key storage trait.
///
/// Abstracts key generation and retrieval to support multiple
/// storage backends (filesystem, cloud KMS, vault, etc.).
pub trait Store {
    /// Generate a new keypair for a project.
    ///
    /// # Arguments
    ///
    /// * `project_id` - Unique identifier for the project
    ///
    /// # Returns
    ///
    /// The public key string.
    ///
    /// # Errors
    ///
    /// Returns `StoreError` if key generation or storage fails.
    fn generate_keypair(&self, project_id: &str) -> Result<String>;

    /// Load the private key (identity) for a project.
    ///
    /// # Arguments
    ///
    /// * `project_id` - Unique identifier for the project
    ///
    /// # Returns
    ///
    /// The private key/identity for decryption.
    ///
    /// # Errors
    ///
    /// Returns `StoreError` if the key doesn't exist or cannot be loaded.
    fn load_identity(&self, project_id: &str) -> Result<Identity>;

    /// Check if a keypair exists for a project.
    ///
    /// # Arguments
    ///
    /// * `project_id` - Unique identifier for the project
    ///
    /// # Returns
    ///
    /// `true` if a key exists, `false` otherwise.
    fn has_key(&self, project_id: &str) -> bool;
}

/// Generate a new age keypair for a project.
///
/// Creates the key directory if it doesn't exist and stores the private
/// key with restricted permissions (0600 on Unix).
///
/// On macOS, stores in Keychain by default (or filesystem if Keychain is disabled).
/// On other platforms, stores in filesystem.
///
/// # Arguments
///
/// * `project_id` - Unique identifier for the project
///
/// # Returns
///
/// The public key string (starts with "age1...").
///
/// # Errors
///
/// Returns `StoreError` if key generation or file operations fail.
pub fn generate_keypair(project_id: &str) -> Result<String> {
    default_backend().generate_keypair(project_id)
}

/// Load the private key (identity) for a project.
///
/// On macOS, tries Keychain first, then falls back to filesystem.
/// On other platforms, loads from filesystem.
///
/// # Arguments
///
/// * `project_id` - Unique identifier for the project
///
/// # Returns
///
/// The Identity for decryption.
///
/// # Errors
///
/// Returns `StoreError::NoPrivateKey` if the key doesn't exist,
/// or `StoreError::InvalidFormat` if the key is malformed.
pub fn load_identity(project_id: &str) -> Result<Identity> {
    default_backend().load_identity(project_id)
}

/// Check if a keypair exists for a project.
///
/// On macOS, checks Keychain then filesystem.
/// On other platforms, checks filesystem.
///
/// # Arguments
///
/// * `project_id` - Unique identifier for the project
///
/// # Returns
///
/// `true` if an identity key exists, `false` otherwise.
pub fn has_key(project_id: &str) -> bool {
    default_backend().has_key(project_id)
}

/// Check if the global identity exists in the active backend or filesystem.
pub fn has_global() -> Result<bool> {
    if has_key("global") {
        return Ok(true);
    }
    Identity::has_global()
}

/// Load global identity from active backend, then filesystem fallback.
pub fn load_global_identity() -> Result<Identity> {
    load_identity("global").or_else(|_| Identity::load_global())
}