1use super::app_secrets::{self, SecretsOwner};
5use super::platform::NativeKeychain;
6use super::{KeyError, KeyMaterial, PersonRestoreCode};
7use crate::{MaterialError, MemberIdentity, SecretBytes, SecretText, StoreKeyring};
8use coven_foundation::id_source::{DeviceId, StoreId};
9use coven_foundation::locks::lock_unpoisoned;
10use std::{
11 marker::PhantomData,
12 sync::{Arc, Mutex},
13};
14
15fn validate_service(name: &str) -> Result<(), KeyError> {
16 if name.is_empty() || name.contains('\0') {
17 return Err(KeyError::InvalidServiceName);
18 }
19 Ok(())
20}
21
22const DEVICE_ID_ENTRY: &str = "device-id";
23const CREDENTIALS_ENTRY: &str = "storage-credentials";
24const INVITE_CODE_ENTRY: &str = "invite-code";
25const SETUP_CREDENTIALS_ENTRY: &str = "setup-credentials";
26const RESTORE_RECORD_ENTRY: &str = "restore-record";
27const REPLACEMENT_RECORD_ENTRY: &str = "replacement-record";
28
29#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
30pub(crate) enum EntryScope {
31 DeviceOnly,
33 Person,
37}
38
39pub(crate) trait KeychainBackend: std::any::Any + Send + Sync {
40 fn read(
41 &self,
42 scope: EntryScope,
43 service: &str,
44 account: &str,
45 ) -> Result<Option<SecretBytes>, KeyError>;
46 fn write(
47 &self,
48 scope: EntryScope,
49 service: &str,
50 account: &str,
51 bytes: &[u8],
52 ) -> Result<(), KeyError>;
53 fn delete(&self, scope: EntryScope, service: &str, account: &str) -> Result<(), KeyError>;
54 fn person_restore_codes(&self, service: &str) -> Result<Vec<(StoreId, SecretBytes)>, KeyError>;
55 fn person_copies(&self, service: &str, account: &str) -> Result<Vec<SecretBytes>, KeyError>;
57 fn replace_person_entry(
61 &self,
62 service: &str,
63 account: &str,
64 bytes: &[u8],
65 ) -> Result<(), KeyError>;
66 fn supports_person_entries(&self) -> bool;
67 fn person_value_limit(&self, service: &str, account: &str) -> Option<usize>;
70 fn person_backup_follows_writes(&self) -> bool;
73}
74
75pub struct Keychain {
78 name: String,
79 backend: Box<dyn KeychainBackend>,
80 secret_names: Mutex<()>,
82}
83
84impl Keychain {
85 pub fn native(name: impl Into<String>) -> Result<Arc<Self>, KeyError> {
89 let name = name.into();
90 validate_service(&name)?;
91 Ok(Arc::new(Self {
92 name,
93 backend: Box::new(NativeKeychain::new()?),
94 secret_names: Mutex::new(()),
95 }))
96 }
97
98 pub fn person_restore_codes(&self) -> Result<Vec<(StoreId, PersonRestoreCode)>, KeyError> {
108 Ok(by_store(self.backend.person_restore_codes(&self.name)?))
109 }
110
111 pub(super) fn supports_person_entries(&self) -> bool {
115 self.backend.supports_person_entries()
116 }
117
118 pub(super) fn person_backup_follows_writes(&self) -> bool {
121 self.backend.person_backup_follows_writes()
122 }
123
124 pub(super) fn person_value_limit(&self, account: &str) -> Option<usize> {
126 self.backend.person_value_limit(&self.name, account)
127 }
128
129 pub fn device_secret(&self, name: &str) -> Result<Option<String>, KeyError> {
133 app_secrets::read(self, SecretsOwner::Device, name)
134 }
135
136 pub fn set_device_secret(&self, name: &str, value: &str) -> Result<(), KeyError> {
142 app_secrets::change(self, SecretsOwner::Device, name, Some(value))
143 }
144
145 pub fn delete_device_secrets(&self) -> Result<(), KeyError> {
149 app_secrets::delete_all(self, SecretsOwner::Device)
150 }
151
152 pub(super) fn changing_secret_names<T>(&self, change: impl FnOnce() -> T) -> T {
155 let _guard = lock_unpoisoned(&self.secret_names);
156 change()
157 }
158
159 pub(super) fn read(
160 &self,
161 scope: EntryScope,
162 account: &str,
163 ) -> Result<Option<SecretBytes>, KeyError> {
164 self.backend.read(scope, &self.name, account)
165 }
166
167 pub(super) fn write(
168 &self,
169 scope: EntryScope,
170 account: &str,
171 bytes: &[u8],
172 ) -> Result<(), KeyError> {
173 self.backend.write(scope, &self.name, account, bytes)
174 }
175
176 pub(super) fn delete(&self, scope: EntryScope, account: &str) -> Result<(), KeyError> {
177 self.backend.delete(scope, &self.name, account)
178 }
179
180 pub(super) fn person_copies(&self, account: &str) -> Result<Vec<SecretBytes>, KeyError> {
181 self.backend.person_copies(&self.name, account)
182 }
183
184 pub(super) fn replace_person_entry(&self, account: &str, bytes: &[u8]) -> Result<(), KeyError> {
185 self.backend.replace_person_entry(&self.name, account, bytes)
186 }
187}
188
189impl std::fmt::Debug for Keychain {
190 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
191 f.write_str("Keychain([REDACTED])")
192 }
193}
194
195pub struct StoreKeychain {
203 keychain: Arc<Keychain>,
204 store: StoreId,
205}
206
207impl StoreKeychain {
208 pub fn new(keychain: Arc<Keychain>, store: StoreId) -> Self {
210 Self { keychain, store }
211 }
212
213 fn account(&self, name: &str) -> String {
214 account(name, self.store)
215 }
216 fn read(&self, name: &str) -> Result<Option<SecretBytes>, KeyError> {
217 self.keychain.read(EntryScope::DeviceOnly, &self.account(name))
218 }
219 fn write(&self, name: &str, bytes: &[u8]) -> Result<(), KeyError> {
220 self.keychain.write(EntryScope::DeviceOnly, &self.account(name), bytes)
221 }
222 fn remove(&self, name: &str) -> Result<(), KeyError> {
223 self.keychain.delete(EntryScope::DeviceOnly, &self.account(name))
224 }
225
226 #[expect(clippy::map_err_ignore, reason = "a stored device id fails only by not being 8 bytes")]
230 pub fn device_id(&self) -> Result<Option<DeviceId>, KeyError> {
231 self.read(DEVICE_ID_ENTRY)?
232 .map(|bytes| {
233 let bytes: [u8; 8] =
234 bytes.as_bytes().try_into().map_err(|_| KeyError::DeviceIdEncoding)?;
235 Ok(DeviceId(u64::from_be_bytes(bytes)))
236 })
237 .transpose()
238 }
239
240 pub fn set_device_id(&self, device: DeviceId) -> Result<(), KeyError> {
242 self.write(DEVICE_ID_ENTRY, &device.0.to_be_bytes())
243 }
244
245 pub fn delete_device_id(&self) -> Result<(), KeyError> {
247 self.remove(DEVICE_ID_ENTRY)
248 }
249
250 pub fn storage_credentials(&self) -> Result<Option<SecretBytes>, KeyError> {
252 self.read(CREDENTIALS_ENTRY)
253 }
254
255 pub fn set_storage_credentials(&self, bytes: &SecretBytes) -> Result<(), KeyError> {
257 self.write(CREDENTIALS_ENTRY, bytes.as_bytes())
258 }
259
260 pub fn delete_storage_credentials(&self) -> Result<(), KeyError> {
262 self.remove(CREDENTIALS_ENTRY)
263 }
264
265 pub fn setup_credentials(&self) -> Result<Option<SecretBytes>, KeyError> {
269 self.read(SETUP_CREDENTIALS_ENTRY)
270 }
271
272 pub fn set_setup_credentials(&self, bytes: &SecretBytes) -> Result<(), KeyError> {
274 self.write(SETUP_CREDENTIALS_ENTRY, bytes.as_bytes())
275 }
276
277 pub fn delete_setup_credentials(&self) -> Result<(), KeyError> {
280 self.remove(SETUP_CREDENTIALS_ENTRY)
281 }
282
283 #[expect(
287 clippy::map_err_ignore,
288 reason = "a saved invite code fails only by not being UTF-8, which Encoding names"
289 )]
290 pub fn invite_code(&self) -> Result<Option<SecretText>, KeyError> {
291 self.read(INVITE_CODE_ENTRY)?
292 .map(|bytes| {
293 std::str::from_utf8(bytes.as_bytes())
294 .map(|code| SecretText::new(code.to_owned()))
295 .map_err(|_| MaterialError::Encoding.into())
296 })
297 .transpose()
298 }
299
300 pub fn set_invite_code(&self, code: &SecretText) -> Result<(), KeyError> {
302 self.write(INVITE_CODE_ENTRY, code.as_str().as_bytes())
303 }
304
305 pub fn delete_invite_code(&self) -> Result<(), KeyError> {
308 self.remove(INVITE_CODE_ENTRY)
309 }
310
311 pub fn restore_record(&self) -> Result<Option<(SecretText, String)>, KeyError> {
316 self.read_code_record(RESTORE_RECORD_ENTRY)
317 }
318
319 pub fn set_restore_record(&self, code: &SecretText, device_name: &str) -> Result<(), KeyError> {
323 self.write_code_record(RESTORE_RECORD_ENTRY, code, device_name)
324 }
325
326 pub fn delete_restore_record(&self) -> Result<(), KeyError> {
329 self.remove(RESTORE_RECORD_ENTRY)
330 }
331
332 pub fn replacement_record(&self) -> Result<Option<(SecretText, String)>, KeyError> {
337 self.read_code_record(REPLACEMENT_RECORD_ENTRY)
338 }
339
340 pub fn set_replacement_record(
344 &self,
345 code: &SecretText,
346 device_name: &str,
347 ) -> Result<(), KeyError> {
348 self.write_code_record(REPLACEMENT_RECORD_ENTRY, code, device_name)
349 }
350
351 pub fn delete_replacement_record(&self) -> Result<(), KeyError> {
354 self.remove(REPLACEMENT_RECORD_ENTRY)
355 }
356
357 #[expect(
358 clippy::map_err_ignore,
359 reason = "a code record fails only by its layout, which Encoding names"
360 )]
361 fn read_code_record(&self, entry: &str) -> Result<Option<(SecretText, String)>, KeyError> {
362 self.read(entry)?
363 .map(|bytes| {
364 let text = std::str::from_utf8(bytes.as_bytes())
365 .map_err(|_| KeyError::from(MaterialError::Encoding))?;
366 let (code, name) = text.split_once('\0').ok_or(MaterialError::Encoding)?;
367 Ok((SecretText::new(code.to_owned()), name.to_owned()))
368 })
369 .transpose()
370 }
371
372 fn write_code_record(
373 &self,
374 entry: &str,
375 code: &SecretText,
376 device_name: &str,
377 ) -> Result<(), KeyError> {
378 if code.as_str().contains('\0') {
379 return Err(MaterialError::Encoding.into());
380 }
381 let record = SecretText::new(format!("{}\0{device_name}", code.as_str()));
382 self.write(entry, record.as_str().as_bytes())
383 }
384
385 pub fn delete_device_entries(&self) -> Result<(), KeyError> {
393 app_secrets::delete_all(&self.keychain, self.secrets())?;
394 for name in [
395 StoreKeyring::ENTRY,
396 MemberIdentity::ENTRY,
397 DEVICE_ID_ENTRY,
398 CREDENTIALS_ENTRY,
399 SETUP_CREDENTIALS_ENTRY,
400 INVITE_CODE_ENTRY,
401 RESTORE_RECORD_ENTRY,
402 REPLACEMENT_RECORD_ENTRY,
403 ] {
404 self.remove(name)?;
405 }
406 Ok(())
407 }
408
409 fn secrets(&self) -> SecretsOwner {
410 SecretsOwner::Store(self.store)
411 }
412
413 pub fn set_host_secret(&self, name: &str, value: &str) -> Result<(), KeyError> {
419 app_secrets::change(&self.keychain, self.secrets(), name, Some(value))
420 }
421
422 pub fn host_secret(&self, name: &str) -> Result<Option<String>, KeyError> {
424 app_secrets::read(&self.keychain, self.secrets(), name)
425 }
426
427 pub fn delete_host_secret(&self, name: &str) -> Result<(), KeyError> {
431 app_secrets::change(&self.keychain, self.secrets(), name, None)
432 }
433}
434
435impl std::fmt::Debug for StoreKeychain {
436 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
437 f.write_str("StoreKeychain([REDACTED])")
438 }
439}
440
441pub(super) fn account(name: &str, store: StoreId) -> String {
444 format!("{name}:{store}")
445}
446
447pub struct KeyringCustody<T> {
449 keychain: Arc<StoreKeychain>,
450 material: PhantomData<fn() -> T>,
451}
452
453impl<T> KeyringCustody<T> {
454 pub fn new(keychain: Arc<StoreKeychain>) -> Self {
456 Self { keychain, material: PhantomData }
457 }
458 pub(crate) fn read(&self, name: &str) -> Result<Option<SecretBytes>, KeyError> {
459 self.keychain.read(name)
460 }
461 pub(crate) fn write(&self, name: &str, bytes: &[u8]) -> Result<(), KeyError> {
462 self.keychain.write(name, bytes)
463 }
464 pub(crate) fn remove(&self, name: &str) -> Result<(), KeyError> {
465 self.keychain.remove(name)
466 }
467}
468
469impl<T> std::fmt::Debug for KeyringCustody<T> {
470 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
471 f.write_str("KeyringCustody([REDACTED])")
472 }
473}
474
475fn by_store(codes: Vec<(StoreId, SecretBytes)>) -> Vec<(StoreId, PersonRestoreCode)> {
478 let mut stores = std::collections::BTreeMap::new();
479 for (store, code) in codes {
480 stores
481 .entry(store)
482 .and_modify(|found| {
483 tracing::warn!(%store, "more than one keychain group holds a restore code");
484 *found = PersonRestoreCode::Ambiguous;
485 })
486 .or_insert(PersonRestoreCode::Saved(code));
487 }
488 stores.into_iter().collect()
489}
490
491#[cfg(test)]
492#[path = "keychain_tests.rs"]
493mod tests;
494
495#[cfg(any(test, feature = "in-memory-keychain"))]
496#[path = "keychain_test_utils.rs"]
497mod test_utils;