use std::fmt;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use crate::error::{AuthCause, Error};
use crate::Result;
pub const API_KEY_ENV: &str = "SPIDER_API_KEY";
pub const API_KEY_ENV_ALT: &str = "SPIDER_CLOUD_API_KEY";
pub const CREDENTIALS_PATH: &str = ".spider/credentials";
pub const KEYRING_SERVICE: &str = "spider_client";
pub const KEYRING_USER: &str = "default";
const REDACTED: &str = "<redacted>";
pub const MAX_KEY_FILE_BYTES: usize = 4096;
#[cfg(unix)]
pub const FILE_MODE: u32 = 0o600;
#[cfg(unix)]
pub const DIR_MODE: u32 = 0o700;
static WARNED_ABOUT_PERMISSIONS: AtomicBool = AtomicBool::new(false);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Source {
Explicit,
Env(&'static str),
Keyring,
File,
}
impl fmt::Display for Source {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Source::Explicit => f.write_str("the key passed in"),
Source::Env(name) => write!(f, "{name}"),
Source::Keyring => f.write_str("the operating system keychain"),
Source::File => write!(f, "~/{CREDENTIALS_PATH}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Stored {
Keyring,
File(PathBuf),
}
#[derive(Clone, PartialEq, Eq)]
pub struct Credentials {
key: String,
source: Source,
}
impl fmt::Debug for Credentials {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Credentials")
.field("key", &REDACTED)
.field("source", &self.source)
.finish()
}
}
impl Credentials {
pub fn resolve() -> Option<Credentials> {
Credentials::resolve_with(None)
}
pub fn resolve_with(explicit: Option<&str>) -> Option<Credentials> {
resolve_in(&Lookup {
explicit,
env: [
(API_KEY_ENV, std::env::var("SPIDER_API_KEY").ok()),
(API_KEY_ENV_ALT, std::env::var("SPIDER_CLOUD_API_KEY").ok()),
],
keyring: &keyring_read,
home: home_dir(),
})
}
pub fn expose(&self) -> &str {
&self.key
}
pub fn into_key(self) -> String {
self.key
}
pub fn source(&self) -> Source {
self.source
}
pub fn store(key: &str) -> Result<Stored> {
let key = key.trim();
if key.is_empty() {
return Err(Error::Auth {
cause: AuthCause::EmptyKey,
message: "refusing to store an empty api key".to_string(),
});
}
if keyring_write(key) {
return Ok(Stored::Keyring);
}
let home = home_dir().ok_or_else(|| local("no home directory to write to".to_string()))?;
let path = write_key_file(&home, key)
.map_err(|e| local(format!("could not write ~/{CREDENTIALS_PATH}: {e}")))?;
Ok(Stored::File(path))
}
pub fn tighten_file_permissions() -> Result<Option<PathBuf>> {
let home = home_dir().ok_or_else(|| local("no home directory to read".to_string()))?;
let path = home.join(CREDENTIALS_PATH);
tighten(&path).map_err(|e| local(format!("could not change the mode: {e}")))
}
}
fn local(message: String) -> Error {
Error::Auth {
cause: AuthCause::Local,
message,
}
}
struct Lookup<'a> {
explicit: Option<&'a str>,
env: [(&'static str, Option<String>); 2],
keyring: &'a dyn Fn() -> Option<String>,
home: Option<PathBuf>,
}
fn resolve_in(lookup: &Lookup<'_>) -> Option<Credentials> {
if let Some(key) = trimmed(lookup.explicit.map(str::to_string)) {
return Some(Credentials {
key,
source: Source::Explicit,
});
}
for (name, value) in &lookup.env {
if let Some(key) = trimmed(value.clone()) {
return Some(Credentials {
key,
source: Source::Env(name),
});
}
}
if let Some(key) = trimmed((lookup.keyring)()) {
return Some(Credentials {
key,
source: Source::Keyring,
});
}
let home = lookup.home.as_deref()?;
let key = trimmed(read_key_file(&home.join(CREDENTIALS_PATH)))?;
Some(Credentials {
key,
source: Source::File,
})
}
fn read_key_file(path: &Path) -> Option<String> {
use std::io::Read;
let file = std::fs::File::open(path).ok()?;
let mut bytes = Vec::new();
file.take(MAX_KEY_FILE_BYTES as u64 + 1)
.read_to_end(&mut bytes)
.ok()?;
if bytes.len() > MAX_KEY_FILE_BYTES {
log::warn!(
"{} is larger than {MAX_KEY_FILE_BYTES} bytes, which no api key is, so it was not read",
path.display()
);
return None;
}
let contents = String::from_utf8(bytes).ok()?;
if let Some(mode) = wide_permissions(path) {
let fix = "call Credentials::tighten_file_permissions";
warn_wide_permissions(path, mode, &WARNED_ABOUT_PERMISSIONS, fix);
}
Some(contents)
}
pub(super) fn wide_permissions(path: &Path) -> Option<u32> {
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mode = std::fs::metadata(path).ok()?.permissions().mode() & 0o777;
(mode & 0o077 != 0).then_some(mode)
}
#[cfg(not(unix))]
{
let _ = path;
None
}
}
pub(super) fn warn_wide_permissions(path: &Path, mode: u32, once: &AtomicBool, fix: &str) {
if once.swap(true, Ordering::Relaxed) {
return;
}
log::warn!(
"{} is readable by more than its owner (mode {mode:o}). The keys in it have been \
readable for as long as the file has existed. Narrow it with chmod 600, or {fix}.",
path.display()
);
}
fn tighten(path: &Path) -> std::io::Result<Option<PathBuf>> {
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
if wide_permissions(path).is_none() {
return Ok(None);
}
std::fs::set_permissions(path, std::fs::Permissions::from_mode(FILE_MODE))?;
Ok(Some(path.to_path_buf()))
}
#[cfg(not(unix))]
{
let _ = path;
Ok(None)
}
}
fn write_key_file(home: &Path, key: &str) -> std::io::Result<PathBuf> {
write_owner_only(&home.join(CREDENTIALS_PATH), key.as_bytes())
}
pub const SPIDER_DIR: &str = ".spider";
pub fn spider_dir() -> Option<PathBuf> {
home_dir().map(|home| home.join(SPIDER_DIR))
}
pub fn ensure_spider_dir() -> std::io::Result<PathBuf> {
let dir = spider_dir()
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "no home directory"))?;
create_owner_only_dir(&dir)?;
Ok(dir)
}
pub fn write_private_file(name: &str, contents: &[u8]) -> std::io::Result<PathBuf> {
let plain = !name.is_empty()
&& name != "."
&& name != ".."
&& !name.contains(['/', '\\'])
&& Some(name)
!= Path::new(CREDENTIALS_PATH)
.file_name()
.and_then(|n| n.to_str());
if !plain {
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidInput,
"a private file name is one plain name, and not the credentials file",
));
}
let dir = spider_dir()
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "no home directory"))?;
write_owner_only(&dir.join(name), contents)
}
fn create_owner_only_dir(dir: &Path) -> std::io::Result<()> {
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt;
std::fs::DirBuilder::new()
.recursive(true)
.mode(DIR_MODE)
.create(dir)
}
#[cfg(not(unix))]
std::fs::create_dir_all(dir)
}
fn write_owner_only(path: &Path, contents: &[u8]) -> std::io::Result<PathBuf> {
use std::io::Write;
let parent = path.parent().ok_or_else(|| {
std::io::Error::new(std::io::ErrorKind::InvalidInput, "no parent directory")
})?;
let stem = path
.file_name()
.and_then(|name| name.to_str())
.unwrap_or("private");
create_owner_only_dir(parent)?;
let (mut file, staged) = create_staging_file(parent, stem)?;
let written = file
.write_all(contents)
.and_then(|()| file.flush())
.and_then(|()| file.sync_all());
drop(file);
if let Err(e) = written {
let _ = std::fs::remove_file(&staged);
return Err(e);
}
if let Err(e) = std::fs::rename(&staged, path) {
let _ = std::fs::remove_file(&staged);
return Err(e);
}
#[cfg(unix)]
if let Ok(dir) = std::fs::File::open(parent) {
let _ = dir.sync_all();
}
Ok(path.to_path_buf())
}
const STAGING_ATTEMPTS: u32 = 8;
fn create_staging_file(parent: &Path, stem: &str) -> std::io::Result<(std::fs::File, PathBuf)> {
let pid = std::process::id();
let mut last = std::io::Error::new(std::io::ErrorKind::AlreadyExists, "no free staging name");
for attempt in 0..STAGING_ATTEMPTS {
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
let staged = parent.join(format!(".{stem}.{pid}.{nanos}.{attempt}.tmp"));
let mut options = std::fs::OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(FILE_MODE);
}
match options.open(&staged) {
Ok(file) => return Ok((file, staged)),
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => last = e,
Err(e) => return Err(e),
}
}
Err(last)
}
fn home_dir() -> Option<PathBuf> {
#[allow(deprecated)]
std::env::home_dir()
}
fn keyring_read() -> Option<String> {
#[cfg(feature = "keyring")]
{
keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER)
.ok()?
.get_password()
.ok()
}
#[cfg(not(feature = "keyring"))]
{
None
}
}
fn keyring_write(key: &str) -> bool {
#[cfg(feature = "keyring")]
{
match keyring::Entry::new(KEYRING_SERVICE, KEYRING_USER) {
Ok(entry) => entry.set_password(key).is_ok(),
Err(_) => false,
}
}
#[cfg(not(feature = "keyring"))]
{
let _ = key;
false
}
}
fn trimmed(value: Option<String>) -> Option<String> {
value
.map(|v| v.trim().to_string())
.filter(|v| !v.is_empty())
}
#[cfg(test)]
mod tests {
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::unreachable,
clippy::indexing_slicing,
clippy::string_slice
)]
use super::*;
use std::sync::atomic::AtomicUsize;
const SECRET: &str = "sk-live-not-a-real-key-0123456789";
struct TempHome(PathBuf);
impl TempHome {
fn new(tag: &str) -> TempHome {
let unique = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
let path = std::env::temp_dir().join(format!("spider-auth-{tag}-{unique}"));
std::fs::create_dir_all(&path).unwrap();
TempHome(path)
}
fn path(&self) -> &Path {
&self.0
}
fn write_credentials(&self, contents: &str) -> PathBuf {
let path = self.0.join(CREDENTIALS_PATH);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(&path, contents).unwrap();
path
}
}
impl Drop for TempHome {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn env_of(pairs: &[(&str, &str)]) -> [(&'static str, Option<String>); 2] {
let value = |wanted: &str| {
pairs
.iter()
.find(|(k, _)| *k == wanted)
.map(|(_, v)| v.to_string())
};
[
(API_KEY_ENV, value(API_KEY_ENV)),
(API_KEY_ENV_ALT, value(API_KEY_ENV_ALT)),
]
}
fn no_keyring() -> Option<String> {
None
}
fn some_keyring() -> Option<String> {
Some("from-the-keyring".to_string())
}
#[test]
fn an_explicit_key_wins_over_every_other_source() {
let home = TempHome::new("explicit");
home.write_credentials("from-the-file");
let env = env_of(&[(API_KEY_ENV, "from-the-env")]);
let found = resolve_in(&Lookup {
explicit: Some(SECRET),
env,
keyring: &some_keyring,
home: Some(home.path().to_path_buf()),
})
.unwrap();
assert_eq!(found.expose(), SECRET);
assert_eq!(found.source(), Source::Explicit);
}
#[test]
fn the_first_variable_wins_when_no_key_was_passed_in() {
let home = TempHome::new("env-first");
home.write_credentials("from-the-file");
let env = env_of(&[(API_KEY_ENV, "first"), (API_KEY_ENV_ALT, "second")]);
let found = resolve_in(&Lookup {
explicit: None,
env,
keyring: &some_keyring,
home: Some(home.path().to_path_buf()),
})
.unwrap();
assert_eq!(found.expose(), "first");
assert_eq!(found.source(), Source::Env(API_KEY_ENV));
}
#[test]
fn the_second_variable_is_read_when_the_first_is_absent() {
let env = env_of(&[(API_KEY_ENV_ALT, "second")]);
let found = resolve_in(&Lookup {
explicit: None,
env,
keyring: &no_keyring,
home: None,
})
.unwrap();
assert_eq!(found.expose(), "second");
assert_eq!(found.source(), Source::Env(API_KEY_ENV_ALT));
}
#[test]
fn an_empty_variable_does_not_shadow_a_later_source() {
let env = env_of(&[(API_KEY_ENV, " ")]);
let found = resolve_in(&Lookup {
explicit: None,
env,
keyring: &some_keyring,
home: None,
})
.unwrap();
assert_eq!(found.source(), Source::Keyring);
}
#[test]
fn the_keychain_is_read_after_the_variables_and_before_the_file() {
let home = TempHome::new("keyring-before-file");
home.write_credentials("from-the-file");
let env = env_of(&[]);
let found = resolve_in(&Lookup {
explicit: None,
env,
keyring: &some_keyring,
home: Some(home.path().to_path_buf()),
})
.unwrap();
assert_eq!(found.expose(), "from-the-keyring");
assert_eq!(found.source(), Source::Keyring);
}
#[test]
fn the_file_is_read_last_and_is_trimmed() {
let home = TempHome::new("file-last");
home.write_credentials(" from-the-file\n");
let env = env_of(&[]);
let found = resolve_in(&Lookup {
explicit: None,
env,
keyring: &no_keyring,
home: Some(home.path().to_path_buf()),
})
.unwrap();
assert_eq!(found.expose(), "from-the-file");
assert_eq!(found.source(), Source::File);
}
#[test]
fn nothing_anywhere_is_not_an_error_it_is_no_key() {
let home = TempHome::new("empty");
let env = env_of(&[]);
assert!(resolve_in(&Lookup {
explicit: None,
env,
keyring: &no_keyring,
home: Some(home.path().to_path_buf()),
})
.is_none());
}
#[test]
fn the_variable_names_match_the_literals_that_are_actually_read() {
assert_eq!(API_KEY_ENV, "SPIDER_API_KEY");
assert_eq!(API_KEY_ENV_ALT, "SPIDER_CLOUD_API_KEY");
}
#[test]
fn credentials_never_print_the_key() {
let found = Credentials {
key: SECRET.to_string(),
source: Source::File,
};
let printed = format!("{found:?}");
assert!(!printed.contains(SECRET), "{printed}");
assert!(printed.contains(REDACTED), "{printed}");
}
#[test]
fn a_source_prints_no_part_of_a_key() {
for source in [
Source::Explicit,
Source::Env(API_KEY_ENV),
Source::Keyring,
Source::File,
] {
let printed = format!("{source:?} {source}");
assert!(!printed.contains(SECRET), "{printed}");
}
}
#[test]
fn stored_prints_no_part_of_a_key() {
let printed = format!("{:?}", Stored::File(PathBuf::from("/tmp/x")));
assert!(!printed.contains(SECRET), "{printed}");
assert!(!format!("{:?}", Stored::Keyring).contains(SECRET));
}
#[test]
fn a_private_file_cannot_be_the_key_or_leave_the_directory() {
for name in [
"credentials",
"",
".",
"..",
"../credentials",
"a/b",
"a\\b",
] {
let refused = write_private_file(name, b"x").unwrap_err();
assert_eq!(refused.kind(), std::io::ErrorKind::InvalidInput, "{name:?}");
}
}
#[test]
fn storing_an_empty_key_is_refused() {
assert!(matches!(
Credentials::store(" "),
Err(Error::Auth {
cause: AuthCause::EmptyKey,
..
})
));
}
#[cfg(unix)]
#[test]
fn a_written_file_is_owner_only_inside_an_owner_only_directory() {
use std::os::unix::fs::PermissionsExt;
let home = TempHome::new("modes");
let path = write_key_file(home.path(), SECRET).unwrap();
let file = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
assert_eq!(file, FILE_MODE, "file mode {file:o}");
let dir = std::fs::metadata(path.parent().unwrap())
.unwrap()
.permissions()
.mode()
& 0o777;
assert_eq!(dir, DIR_MODE, "directory mode {dir:o}");
assert_eq!(std::fs::read_to_string(&path).unwrap(), SECRET);
}
#[cfg(unix)]
#[test]
fn rewriting_a_wide_file_narrows_it_before_the_key_goes_in() {
use std::os::unix::fs::PermissionsExt;
let home = TempHome::new("rewrite");
let path = home.write_credentials("old");
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
write_key_file(home.path(), SECRET).unwrap();
let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
assert_eq!(mode, FILE_MODE, "mode {mode:o}");
}
#[test]
fn writers_racing_for_the_file_leave_one_whole_key_and_never_a_mix() {
let home = TempHome::new("race");
let keys: Vec<String> = (0..4)
.map(|n| format!("key-{n}-").repeat(64 + n * 16))
.collect();
for _ in 0..25 {
let writers: Vec<_> = keys
.iter()
.cloned()
.map(|key| {
let home = home.path().to_path_buf();
std::thread::spawn(move || write_key_file(&home, &key).unwrap())
})
.collect();
for writer in writers {
writer.join().unwrap();
}
let path = home.path().join(CREDENTIALS_PATH);
let read = std::fs::read_to_string(&path).unwrap();
assert!(keys.contains(&read), "the file holds a mix: {read:?}");
}
}
#[test]
fn a_write_leaves_nothing_beside_the_file() {
let home = TempHome::new("tidy");
let path = write_key_file(home.path(), SECRET).unwrap();
let mut names: Vec<String> = std::fs::read_dir(path.parent().unwrap())
.unwrap()
.map(|entry| entry.unwrap().file_name().to_string_lossy().into_owned())
.collect();
names.sort();
assert_eq!(names, vec!["credentials".to_string()]);
}
#[cfg(unix)]
#[test]
fn a_symlink_at_the_path_is_replaced_and_its_target_is_left_alone() {
let home = TempHome::new("symlink");
let elsewhere = home.path().join("elsewhere");
std::fs::write(&elsewhere, "old").unwrap();
let path = home.path().join(CREDENTIALS_PATH);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::os::unix::fs::symlink(&elsewhere, &path).unwrap();
write_key_file(home.path(), SECRET).unwrap();
assert_eq!(std::fs::read_to_string(&elsewhere).unwrap(), "old");
assert!(
!std::fs::symlink_metadata(&path).unwrap().is_symlink(),
"the symlink was written through rather than replaced"
);
assert_eq!(std::fs::read_to_string(&path).unwrap(), SECRET);
}
#[test]
fn a_file_far_larger_than_any_key_is_not_read_as_one() {
let home = TempHome::new("oversized");
let path = home.write_credentials(&"x".repeat(MAX_KEY_FILE_BYTES + 1));
assert_eq!(read_key_file(&path), None);
let path = home.write_credentials(&"y".repeat(MAX_KEY_FILE_BYTES));
assert_eq!(
read_key_file(&path).map(|k| k.len()),
Some(MAX_KEY_FILE_BYTES)
);
}
#[test]
fn a_directory_an_empty_file_or_bytes_that_are_not_text_yield_no_key() {
let home = TempHome::new("odd");
let path = home.path().join(CREDENTIALS_PATH);
std::fs::create_dir_all(&path).unwrap();
assert_eq!(read_key_file(&path), None);
std::fs::remove_dir(&path).unwrap();
std::fs::write(&path, b"").unwrap();
assert_eq!(trimmed(read_key_file(&path)), None);
std::fs::write(&path, [0xff, 0xfe, b'k', b'e', b'y']).unwrap();
assert_eq!(read_key_file(&path), None);
std::fs::write(&path, " \n\n").unwrap();
assert_eq!(trimmed(read_key_file(&path)), None);
}
#[cfg(unix)]
#[test]
fn a_wide_file_is_reported_and_left_alone() {
use std::os::unix::fs::PermissionsExt;
let home = TempHome::new("wide");
let path = home.write_credentials(SECRET);
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
assert_eq!(wide_permissions(&path), Some(0o644));
let before = WARNINGS.load(Ordering::Relaxed);
let flag = AtomicBool::new(false);
install_counting_logger();
warn_wide_permissions(&path, 0o644, &flag, "narrow it");
warn_wide_permissions(&path, 0o644, &flag, "narrow it");
let warned = WARNINGS.load(Ordering::Relaxed) - before;
assert_eq!(warned, 1, "warned {warned} times, wanted once");
let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
assert_eq!(mode, 0o644, "the mode was changed to {mode:o}");
}
#[cfg(unix)]
#[test]
fn an_owner_only_file_is_not_reported() {
let home = TempHome::new("narrow");
let path = home.write_credentials(SECRET);
tighten(&path).unwrap();
assert_eq!(wide_permissions(&path), None);
}
#[cfg(unix)]
#[test]
fn tightening_reports_the_path_it_changed_and_then_has_nothing_to_do() {
use std::os::unix::fs::PermissionsExt;
let home = TempHome::new("tighten");
let path = home.write_credentials(SECRET);
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o666)).unwrap();
assert_eq!(tighten(&path).unwrap(), Some(path.clone()));
let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
assert_eq!(mode, FILE_MODE, "mode {mode:o}");
assert_eq!(tighten(&path).unwrap(), None);
}
static WARNINGS: AtomicUsize = AtomicUsize::new(0);
static LOGGER_INSTALLED: std::sync::Once = std::sync::Once::new();
struct Counting;
static COUNTING: Counting = Counting;
impl log::Log for Counting {
fn enabled(&self, _: &log::Metadata<'_>) -> bool {
true
}
fn log(&self, record: &log::Record<'_>) {
if record.level() == log::Level::Warn {
WARNINGS.fetch_add(1, Ordering::Relaxed);
}
}
fn flush(&self) {}
}
fn install_counting_logger() {
LOGGER_INSTALLED.call_once(|| {
if log::set_logger(&COUNTING).is_ok() {
log::set_max_level(log::LevelFilter::Warn);
}
});
}
}