A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
//! Connector secrets in the OS secure store (S25.5, S25.7): OAuth tokens, bot tokens, client
//! secrets, and imported headers, keyed by a connector secret id. The app owns the store; the
//! daemon gets a secret in memory over the app channel (`secret_get`, `secret_put`,
//! `secret_delete`, `secret_list` in `app_channel`, T23d), never from a file.
//!
//! - macOS (`Keychain`): generic password items in the login keychain, service
//! [`SERVICE`], account = the secret id, created by the app process. See `macos.rs` for how
//! the items' access list follows the app's code signature.
//! - Linux (`SecretServiceStore`): the Secret Service over D-Bus (GNOME Keyring, KWallet).
//! Items are encrypted at rest, but any same-user process can read unlocked items (S25.7).
//! - Windows (`WindowsDpapiStore`): current-user DPAPI ciphertext in a private,
//! user-wide Local AppData namespace on local NTFS. Same-user processes are trusted.
//! - `MemoryStore`: an in-memory store for tests and unsupported platforms.
//!
//! Secrets are never logged: [`Secret`] and every store redact themselves in `Debug`, have no
//! `Display`, and errors never carry a secret.
mod memory;
#[cfg(any(windows, test))]
mod windows_codec;
#[cfg(windows)]
mod windows;
#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "macos")]
mod macos;
pub use memory::MemoryStore;
#[cfg(windows)]
pub use windows::WindowsDpapiStore;
#[cfg(target_os = "linux")]
pub use linux::SecretServiceStore;
#[cfg(target_os = "macos")]
pub use macos::Keychain;
/// The keychain service (macOS) or `service` attribute (Linux) of every connector secret.
pub const SERVICE: &str = "dev.gentleman.gentle-dot.connectors";
/// The longest secret id, in bytes.
pub const MAX_ID_LEN: usize = 200;
/// A secret value. Redacted in `Debug`, no `Display`, and its bytes are overwritten on drop
/// (best effort: copies made by the OS or by callers are out of reach).
pub struct Secret(String);
impl Secret {
pub fn new(value: impl Into<String>) -> Self {
Secret(value.into())
}
/// The value, for handing it to the daemon. Never log it.
pub fn expose(&self) -> &str {
&self.0
}
}
impl std::fmt::Debug for Secret {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("Secret(<redacted>)")
}
}
impl Drop for Secret {
fn drop(&mut self) {
wipe(&mut std::mem::take(&mut self.0).into_bytes());
}
}
/// Overwrites a buffer with zeros in a way the compiler does not drop as a dead store.
pub(crate) fn wipe(bytes: &mut [u8]) {
for byte in bytes.iter_mut() {
// SAFETY: `byte` is a valid, aligned, exclusive reference.
unsafe { std::ptr::write_volatile(byte, 0) };
}
std::sync::atomic::compiler_fence(std::sync::atomic::Ordering::SeqCst);
}
/// Why a store call failed. Never holds a secret.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StoreError {
/// The id is empty, too long, or has characters outside `[A-Za-z0-9._:@/-]`.
InvalidId,
/// The stored value is not UTF-8 text.
NotText,
/// The user or the system refused access (a declined keychain prompt, a locked item).
Denied,
/// The store cannot be reached (no Secret Service, a locked keychain that cannot ask).
Unavailable(String),
/// Anything else, with the store's own message.
Failed(String),
}
impl std::fmt::Display for StoreError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
StoreError::InvalidId => write!(f, "invalid secret id"),
StoreError::NotText => write!(f, "the stored secret is not text"),
StoreError::Denied => write!(f, "access to the secret store was denied"),
StoreError::Unavailable(why) => write!(f, "the secret store is unavailable: {why}"),
StoreError::Failed(why) => write!(f, "the secret store failed: {why}"),
}
}
}
impl std::error::Error for StoreError {}
/// Where connector secrets live.
pub trait SecretStore: Send + Sync {
/// Stores the secret under `id`, replacing any previous one.
fn put(&self, id: &str, secret: &Secret) -> Result<(), StoreError>;
/// The secret under `id`, or `None` when there is none.
fn get(&self, id: &str) -> Result<Option<Secret>, StoreError>;
/// Removes the secret under `id`; true when one was there.
fn delete(&self, id: &str) -> Result<bool, StoreError>;
/// Every id in this store, sorted, without duplicates.
fn list_ids(&self) -> Result<Vec<String>, StoreError>;
}
/// The store the app serves connector secrets from: the login keychain on macOS, the Secret
/// Service on Linux, and current-user DPAPI on Windows. Nothing is touched until the first request.
pub fn connector_store() -> Box<dyn SecretStore> {
#[cfg(target_os = "macos")]
return Box::new(Keychain::new());
#[cfg(target_os = "linux")]
return Box::new(SecretServiceStore::new());
#[cfg(windows)]
return Box::new(WindowsDpapiStore::new());
#[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
return Box::new(MemoryStore::new());
}
/// Accepts 1 to [`MAX_ID_LEN`] bytes of `[A-Za-z0-9._:@/-]`.
pub fn check_id(id: &str) -> Result<(), StoreError> {
let allowed = |c: char| c.is_ascii_alphanumeric() || "._:@/-".contains(c);
if id.is_empty() || id.len() > MAX_ID_LEN || !id.chars().all(allowed) {
return Err(StoreError::InvalidId);
}
Ok(())
}
/// The contract every store keeps, run against `MemoryStore` here and against a throwaway
/// keychain service in the ignored macOS test.
#[cfg(test)]
pub(crate) fn check_contract(store: &dyn SecretStore) {
assert!(store.get("contract/missing").unwrap().is_none());
assert!(!store.delete("contract/missing").unwrap());
store.put("contract/b", &Secret::new("first")).unwrap();
store.put("contract/a", &Secret::new("xoxb-123")).unwrap();
assert_eq!(store.get("contract/a").unwrap().unwrap().expose(), "xoxb-123");
store.put("contract/a", &Secret::new("replaced ✓")).unwrap();
assert_eq!(store.get("contract/a").unwrap().unwrap().expose(), "replaced ✓");
store.put("contract/empty", &Secret::new("")).unwrap();
assert_eq!(store.get("contract/empty").unwrap().unwrap().expose(), "");
let ids = store.list_ids().unwrap();
assert_eq!(ids, vec!["contract/a", "contract/b", "contract/empty"]);
assert!(store.delete("contract/a").unwrap());
assert!(!store.delete("contract/a").unwrap());
assert!(store.get("contract/a").unwrap().is_none());
assert!(store.delete("contract/b").unwrap());
assert!(store.delete("contract/empty").unwrap());
assert!(store.list_ids().unwrap().is_empty());
for bad in ["", "has space", "new\nline", "tab\t", "ünicode", &"x".repeat(MAX_ID_LEN + 1)] {
assert_eq!(store.put(bad, &Secret::new("s")).unwrap_err(), StoreError::InvalidId, "{bad:?}");
assert_eq!(store.get(bad).unwrap_err(), StoreError::InvalidId, "{bad:?}");
assert_eq!(store.delete(bad).unwrap_err(), StoreError::InvalidId, "{bad:?}");
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ids_allow_a_small_safe_alphabet() {
for good in ["notion", "slack/bot-token", "gmail:client_secret", "a.b@c", &"x".repeat(MAX_ID_LEN)] {
assert_eq!(check_id(good), Ok(()), "{good:?}");
}
for bad in ["", " ", "a b", "a\u{0}b", "a\nb", "ñ", "a\u{202e}b", &"x".repeat(MAX_ID_LEN + 1)] {
assert_eq!(check_id(bad), Err(StoreError::InvalidId), "{bad:?}");
}
}
#[test]
fn a_secret_never_shows_in_debug() {
let secret = Secret::new("hunter2-very-secret");
let shown = format!("{secret:?} {secret:#?}");
assert!(!shown.contains("hunter2"), "{shown}");
assert!(shown.contains("redacted"), "{shown}");
let some = Some(Secret::new("hunter2"));
assert!(!format!("{some:?}").contains("hunter2"));
}
#[test]
fn errors_say_what_failed_without_a_secret() {
assert_eq!(StoreError::Denied.to_string(), "access to the secret store was denied");
assert_eq!(StoreError::InvalidId.to_string(), "invalid secret id");
}
#[test]
fn wipe_zeroes_the_buffer() {
let mut bytes = b"token".to_vec();
wipe(&mut bytes);
assert_eq!(bytes, vec![0; 5]);
}
}