diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index 389e5a41..5c4691af 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -353,6 +353,13 @@ cargo run --bin sc -- clone sc+https://host[:port]/repo # TLS clone (P32 # SC_HTTPS_FINGERPRINT= pre-pins (CI), # SC_HTTPS_STRICT=1 refuses unknown hosts; # remote add/fetch/push accept the same URL form +cargo run --bin sc -- tls list [--json] # pins in the known_hosts file (ADR-0053) +cargo run --bin sc -- tls forget # drop a host's pin (changed server key); a later + # accept-new connect (no SC_HTTPS_STRICT, no + # SC_HTTPS_FINGERPRINT) re-pins; errors if nothing + # was pinned +cargo run --bin sc -- tls pin # pin without connecting (replaces) +cargo run --bin sc -- tls path # the pin file in effect bash demo/run_tls_demo.sh # sc+https proof (P32): TLS round trip w/ signed # chunked blob, TOFU pin/mismatch/strict/pre-pin, # tightened plaintext gate — run twice diff --git a/CLAUDE.md b/CLAUDE.md index d51c8f1f..a5fdb4ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -268,8 +268,8 @@ transport-adjacent. The rest, imperatively: Deferred work is tracked in **`ROADMAP.md` → Deferred** (single source of truth — do not re-list items here). Notable standing entries: transparent lazy-fetch for partial clones, per-case gap-tolerant merge/replay on partial -clones, CA-path validation alongside TOFU pinning, and pin-management -UX (`sc tls`). +clones, and CA-path validation alongside TOFU pinning. `sc tls list/forget/pin/path` +manages the `sc+https://` pin file (ADR-0053). ## Agent skills diff --git a/ROADMAP.md b/ROADMAP.md index ce07e441..38d9c78a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -836,9 +836,9 @@ scale-&-reach horizon): the Phase 32 entry above. Follow-ons this phase named rather than closed: CA-path validation as an additive trust option for PEM-provisioned deployments (v1 is pin-only, names/validity ignored); opt-in SNI/ - certificate-name validation; pin-management UX (`sc tls` list/remove - entries in `~/.config/sc/known_hosts` — today only `sc serve fingerprint` - and first-connect/`SC_HTTPS_FINGERPRINT` write pins, nothing removes one); + certificate-name validation; pin-management UX (shipped in ADR-0053 as `sc tls list/forget/pin/path`; + before it, only first-connect and `SC_HTTPS_FINGERPRINT` wrote pins and + nothing listed or removed one); TLS session-resumption knobs (not evaluated this phase — a later throughput pass if repeated short-lived connections to the same host prove handshake cost material). diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 326ef67c..5bd75c9e 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -506,6 +506,12 @@ enum Cmd { #[command(subcommand)] op: SparseOp, }, + /// Manage the `sc+https://` pins in the user-level known_hosts file + /// (`$XDG_CONFIG_HOME/sc/known_hosts`, or `$SC_HTTPS_KNOWN_HOSTS`). + Tls { + #[command(subcommand)] + op: TlsOp, + }, /// Widen a partial clone: fetch objects under these prefixes from the /// promisor origin and widen `.sc/promisor` to include them. Errors if /// this repo is not a partial clone. @@ -597,6 +603,32 @@ enum TranscriptOp { }, } +#[derive(Subcommand)] +enum TlsOp { + /// List the pinned `host:port` fingerprints, in file order. + List { + /// Emit JSON instead of `host:port sha256:` lines. + #[arg(long)] + json: bool, + }, + /// Remove every pin for a host (the recovery for a changed server key). + /// The port defaults to 8730. + Forget { + /// `host` or `host:port`. + target: String, + }, + /// Pin a host to a fingerprint (replacing any pin it had), e.g. one + /// printed by `sc serve fingerprint`, without connecting first. + Pin { + /// `host` or `host:port`. + target: String, + /// `sha256:` (or bare hex), as `sc serve fingerprint` prints it. + fingerprint: String, + }, + /// Print the pin file in effect. + Path, +} + #[derive(Subcommand)] enum SparseOp { /// Print the repo's current sparse-checkout prefixes. @@ -1065,6 +1097,7 @@ fn main() -> Result<()> { Cmd::Sign { r#ref, identity } => run_sign(&r#ref, identity), Cmd::Verify { r#ref, require } => run_verify(r#ref, require), Cmd::Sparse { op } => run_sparse(op), + Cmd::Tls { op } => run_tls(op), Cmd::Backfill { prefixes, all, @@ -1074,6 +1107,76 @@ fn main() -> Result<()> { } } +fn run_tls(op: TlsOp) -> Result<()> { + use scl_repo::tls_pins; + let file = tls_pins::known_hosts_path()?; + match op { + TlsOp::List { json } => { + let entries = tls_pins::list(&file)?; + if json { + let rows: Vec<_> = entries + .iter() + .map(|e| { + serde_json::json!({ + "host": e.host, + "port": e.port, + "pin": tls_pins::fingerprint(&e.pin), + }) + }) + .collect(); + // `display()` is lossy for a non-UTF-8 path; a `PathBuf` would fail to serialize. + print_line( + &serde_json::json!({"file": file.display().to_string(), "pins": rows}) + .to_string(), + ); + } else { + for e in &entries { + print_line(&format!( + "{}:{} {}", + e.host, + e.port, + tls_pins::fingerprint(&e.pin) + )); + } + if entries.is_empty() { + eprintln!("no pins in {}", file.display()); + } + } + Ok(()) + } + TlsOp::Forget { target } => { + let (host, port) = tls_pins::parse_host_port(&target)?; + let n = tls_pins::forget(&file, &host, port)?; + if n == 0 { + anyhow::bail!("no pin for {host}:{port} in {}", file.display()); + } + println!( + "forgot {n} pin(s) for {host}:{port}; a later connection pins what it sees \ + unless SC_HTTPS_STRICT=1 or SC_HTTPS_FINGERPRINT is set (then use `sc tls pin`)" + ); + Ok(()) + } + TlsOp::Pin { + target, + fingerprint, + } => { + let (host, port) = tls_pins::parse_host_port(&target)?; + let pin = tls_pins::parse_fingerprint(&fingerprint)?; + let replaced = tls_pins::set_pin(&file, &host, port, &pin)?; + println!( + "{} {host}:{port} -> {}", + if replaced { "re-pinned" } else { "pinned" }, + tls_pins::fingerprint(&pin) + ); + Ok(()) + } + TlsOp::Path => { + print_line(&file.display().to_string()); + Ok(()) + } + } +} + fn run_sparse(op: SparseOp) -> Result<()> { match op { SparseOp::Show { json } => { diff --git a/crates/cli/tests/tls_pins_cli.rs b/crates/cli/tests/tls_pins_cli.rs new file mode 100644 index 00000000..ab5598b1 --- /dev/null +++ b/crates/cli/tests/tls_pins_cli.rs @@ -0,0 +1,161 @@ +//! `sc tls` (ADR-0042 follow-on): list, forget and pin entries in the +//! `sc+https://` known_hosts file without editing it by hand. + +use std::path::Path; +use std::process::Command; + +fn sc(known_hosts: &Path, args: &[&str]) -> std::process::Output { + // Run in the test-owned directory that holds the pin file. + Command::new(env!("CARGO_BIN_EXE_sc")) + .args(args) + .current_dir(known_hosts.parent().expect("pin file has a parent dir")) + .env("SC_HTTPS_KNOWN_HOSTS", known_hosts) + .output() + .expect("sc runs") +} + +fn out(o: &std::process::Output) -> String { + String::from_utf8_lossy(&o.stdout).into_owned() +} + +fn err(o: &std::process::Output) -> String { + String::from_utf8_lossy(&o.stderr).into_owned() +} + +fn tmp(tag: &str) -> std::path::PathBuf { + let d = std::env::temp_dir().join(format!("scl-cli-tls-pins-{tag}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&d); + std::fs::create_dir_all(&d).unwrap(); + d +} + +#[test] +fn pin_list_forget_round_trip_through_the_cli() { + let dir = tmp("flow"); + let kh = dir.join("known_hosts"); + let fp_a = format!("sha256:{}", "ab".repeat(32)); + let fp_b = format!("sha256:{}", "cd".repeat(32)); + + // Nothing pinned yet: a hint on stderr, no lines on stdout. + let empty = sc(&kh, &["tls", "list"]); + assert!(empty.status.success()); + assert_eq!(out(&empty), ""); + assert!(err(&empty).contains("no pins"), "{}", err(&empty)); + + // Pin by host (default port) and by host:port. + let o = sc(&kh, &["tls", "pin", "a.example", &fp_a]); + assert!(o.status.success(), "{}", err(&o)); + assert!(out(&o).contains("pinned a.example:8730"), "{}", out(&o)); + assert!(sc(&kh, &["tls", "pin", "b.example:9000", &fp_b]) + .status + .success()); + let list = out(&sc(&kh, &["tls", "list"])); + assert_eq!( + list, + format!("a.example:8730 {fp_a}\nb.example:9000 {fp_b}\n") + ); + + // JSON for scripts. + let json = out(&sc(&kh, &["tls", "list", "--json"])); + let v: serde_json::Value = serde_json::from_str(&json).unwrap(); + assert_eq!(v["pins"][1]["host"], "b.example"); + assert_eq!(v["pins"][1]["port"], 9000); + assert_eq!(v["pins"][1]["pin"], fp_b); + + // Re-pinning replaces, and says so. + let re = sc(&kh, &["tls", "pin", "a.example", &fp_b]); + assert!(out(&re).contains("re-pinned"), "{}", out(&re)); + assert_eq!(out(&sc(&kh, &["tls", "list"])).lines().count(), 2); + + // A host typed in another case is the same host. + assert!(sc(&kh, &["tls", "pin", "C.Example:9001", &fp_a]) + .status + .success()); + assert!(out(&sc(&kh, &["tls", "list"])).contains("c.example:9001")); + assert!(sc(&kh, &["tls", "forget", "c.EXAMPLE:9001"]) + .status + .success()); + + // Forget removes that host's pin only; the other survives untouched. + let f = sc(&kh, &["tls", "forget", "A.EXAMPLE"]); + assert!(f.status.success(), "{}", err(&f)); + assert_eq!( + out(&sc(&kh, &["tls", "list"])), + format!("b.example:9000 {fp_b}\n") + ); + + // Forgetting what is not pinned is an error, not a silent success. + let miss = sc(&kh, &["tls", "forget", "nope.example"]); + assert!(!miss.status.success()); + assert!( + err(&miss).contains("no pin for nope.example:8730"), + "{}", + err(&miss) + ); + + // `path` names the file in effect. + assert_eq!(out(&sc(&kh, &["tls", "path"])).trim(), kh.to_str().unwrap()); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); +} + +#[test] +fn bad_input_is_refused_before_the_file_is_touched() { + let dir = tmp("bad"); + let kh = dir.join("known_hosts"); + for args in [ + vec!["tls", "pin", "h", "not-a-fingerprint"], + vec!["tls", "pin", "h", &format!("sha256:{}", "ab".repeat(31))], + vec![ + "tls", + "pin", + ":9000", + &format!("sha256:{}", "ab".repeat(32)), + ], + vec![ + "tls", + "pin", + "h:notaport", + &format!("sha256:{}", "ab".repeat(32)), + ], + vec!["tls", "forget", "h:99999"], + vec![ + "tls", + "pin", + "h/repo", + &format!("sha256:{}", "ab".repeat(32)), + ], + vec!["tls", "pin", "a b", &format!("sha256:{}", "ab".repeat(32))], + ] { + let o = sc(&kh, &args); + assert!(!o.status.success(), "{args:?} must be refused"); + } + assert!( + !kh.exists(), + "a refused command must not create the pin file" + ); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); +} + +/// A pin file path that is not valid UTF-8 is rendered lossily instead of +/// panicking while building the JSON. +#[cfg(unix)] +#[test] +fn list_json_survives_a_non_utf8_pin_file_path() { + use std::os::unix::ffi::OsStrExt; + let dir = tmp("nonutf8"); + let kh = dir.join(std::ffi::OsStr::from_bytes(b"known_\xff_hosts")); + let o = Command::new(env!("CARGO_BIN_EXE_sc")) + .args(["tls", "list", "--json"]) + .current_dir(&dir) + .env("SC_HTTPS_KNOWN_HOSTS", &kh) + .output() + .unwrap(); + assert!(o.status.success(), "{}", err(&o)); + let v: serde_json::Value = serde_json::from_str(&out(&o)).unwrap(); + assert!(v["file"].as_str().unwrap().contains("known_")); + assert_eq!(v["pins"].as_array().unwrap().len(), 0); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); +} diff --git a/crates/repo/src/error.rs b/crates/repo/src/error.rs index 2eae82e1..83c125d6 100644 --- a/crates/repo/src/error.rs +++ b/crates/repo/src/error.rs @@ -122,8 +122,10 @@ pub enum Error { #[error( "sc+https server key for {host} does not match the pinned fingerprint ({file})\n \ pinned: {pinned}\n server: {seen}\n\ - If the server key legitimately changed, remove that host's line from the pin file \ - and reconnect (the next connect re-pins); verify with `sc serve fingerprint` on the server." + If the server key legitimately changed, verify the new fingerprint with `sc serve \ + fingerprint` on the server, then run `sc tls pin {host} sha256:` (works under \ + SC_HTTPS_STRICT=1), or `sc tls forget {host}` and reconnect without SC_HTTPS_STRICT \ + so the next connect re-pins." )] TlsPinMismatch { host: String, @@ -133,7 +135,8 @@ pub enum Error { }, #[error( "sc+https host {0} is not pinned and SC_HTTPS_STRICT=1 refuses unknown hosts; \ - pre-pin with SC_HTTPS_FINGERPRINT=sha256: or connect once without SC_HTTPS_STRICT" + pre-pin with `sc tls pin {0} sha256:` or SC_HTTPS_FINGERPRINT=sha256:, or \ + connect once without SC_HTTPS_STRICT" )] TlsStrictUnknownHost(String), #[error( diff --git a/crates/repo/src/tls_pins.rs b/crates/repo/src/tls_pins.rs index 84883679..9a349ad2 100644 --- a/crates/repo/src/tls_pins.rs +++ b/crates/repo/src/tls_pins.rs @@ -27,10 +27,7 @@ pub struct TlsClientPolicy { impl TlsClientPolicy { pub fn from_env() -> Result { - let known_hosts = match std::env::var_os("SC_HTTPS_KNOWN_HOSTS") { - Some(p) if !p.is_empty() => PathBuf::from(p), - _ => default_known_hosts_path()?, - }; + let known_hosts = known_hosts_path()?; let pre_pin = match std::env::var("SC_HTTPS_FINGERPRINT") { Ok(s) if !s.is_empty() => Some(parse_fingerprint(&s)?), _ => None, @@ -58,6 +55,15 @@ fn strict_from(value: Option<&str>) -> bool { } } +/// The pin file in effect: `SC_HTTPS_KNOWN_HOSTS` if set and non-empty, else +/// [`default_known_hosts_path`]. +pub fn known_hosts_path() -> Result { + match std::env::var_os("SC_HTTPS_KNOWN_HOSTS") { + Some(p) if !p.is_empty() => Ok(PathBuf::from(p)), + _ => default_known_hosts_path(), + } +} + /// `$XDG_CONFIG_HOME/sc/known_hosts`, falling back to /// `$HOME/.config/sc/known_hosts`. pub fn default_known_hosts_path() -> Result { @@ -92,35 +98,21 @@ pub fn parse_fingerprint(s: &str) -> Result<[u8; 32]> { /// malformed or comment line is skipped, never an error (the file is /// user-editable — the documented mismatch recovery is deleting a line). pub fn lookup(file: &Path, host: &str, port: u16) -> Result> { - let text = match std::fs::read_to_string(file) { - Ok(t) => t, - Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), - Err(e) => { - return Err(Error::InvalidArgument(format!( - "read pin file {}: {e}", - file.display() - ))) - } - }; - let key = format!("{host}:{port}"); - for line in text.lines() { - let line = line.trim(); - if line.is_empty() || line.starts_with('#') { - continue; - } - if let Some((k, v)) = line.split_once(' ') { - if k == key { - if let Ok(pin) = parse_fingerprint(v.trim()) { - return Ok(Some(pin)); - } - } - } - } - Ok(None) + let text = read_pin_file(file)?; + // Hostnames are case-insensitive; the port is exact. A malformed or + // comment line is skipped, never an error. + Ok(text + .lines() + .filter_map(parse_line) + .find(|e| e.port == port && e.host.eq_ignore_ascii_case(host)) + .map(|e| e.pin)) } /// Append a pin line (creating parent dirs and the file as needed). pub fn record(file: &Path, host: &str, port: u16, pin: &[u8; 32]) -> Result<()> { + let file = resolve_pin_path(file); + let file = file.as_path(); + let _lock = PinLock::acquire(file)?; if let Some(parent) = file.parent() { std::fs::create_dir_all(parent) .map_err(|e| Error::InvalidArgument(format!("create {}: {e}", parent.display())))?; @@ -136,6 +128,198 @@ pub fn record(file: &Path, host: &str, port: u16, pin: &[u8; 32]) -> Result<()> Ok(()) } +/// An exclusive advisory lock on the pin file's sibling `.lock`, held for +/// a whole read-modify-write (and for a first-connection append), so two `sc` +/// processes cannot lose each other's update or resurrect a forgotten pin. +/// `File::lock` is `flock` on unix and `LockFileEx` on Windows; the lock is +/// released when the guard drops. +struct PinLock { + _file: std::fs::File, +} + +impl PinLock { + fn acquire(file: &Path) -> Result { + let mut lock_path = file.as_os_str().to_owned(); + lock_path.push(".lock"); + let lock_path = PathBuf::from(lock_path); + if let Some(parent) = lock_path.parent().filter(|p| !p.as_os_str().is_empty()) { + std::fs::create_dir_all(parent) + .map_err(|e| Error::InvalidArgument(format!("create {}: {e}", parent.display())))?; + } + let f = std::fs::OpenOptions::new() + .create(true) + .truncate(false) + .write(true) + .open(&lock_path) + .map_err(|e| { + Error::InvalidArgument(format!("open pin lock {}: {e}", lock_path.display())) + })?; + f.lock() + .map_err(|e| Error::InvalidArgument(format!("lock {}: {e}", lock_path.display())))?; + Ok(PinLock { _file: f }) + } +} + +/// Where a pin update really lands: a pin file that is a symlink (a shared or +/// dotfile-managed store) is followed, so the atomic rename replaces the target +/// and not the link. Anything else is returned as given. +fn resolve_pin_path(file: &Path) -> PathBuf { + let is_link = std::fs::symlink_metadata(file).is_ok_and(|m| m.file_type().is_symlink()); + if !is_link { + return file.to_path_buf(); + } + if let Ok(real) = std::fs::canonicalize(file) { + return real; + } + // A dangling link: write where it points. + match std::fs::read_link(file) { + Ok(target) if target.is_absolute() => target, + Ok(target) => file.parent().unwrap_or(Path::new("")).join(target), + Err(_) => file.to_path_buf(), + } +} + +/// One pin as stored: the `host:port` it was recorded for and its SPKI hash. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct PinEntry { + pub host: String, + pub port: u16, + pub pin: [u8; 32], +} + +/// A pin rendered as `sha256:`, the one fingerprint format. +pub fn fingerprint(pin: &[u8; 32]) -> String { + scl_tlsio::fingerprint_hex(pin) +} + +/// Parse `host`, `host:port` (the port defaults to +/// [`crate::http_transport::DEFAULT_PORT`]), the same split an `sc+https://` +/// URL's authority gets, so a pin names exactly what a connection looks up. +pub fn parse_host_port(s: &str) -> Result<(String, u16)> { + let (host, port) = match s.split_once(':') { + Some((h, p)) => ( + h, + p.parse::() + .map_err(|_| Error::InvalidArgument(format!("bad port in {s:?}")))?, + ), + None => (s, crate::http_transport::DEFAULT_PORT), + }; + if host.is_empty() { + return Err(Error::InvalidArgument(format!("empty host in {s:?}"))); + } + // A host that a connection's URL authority could never produce would + // yield a pin nothing looks up (or a line the reader takes for a comment). + if host + .chars() + .any(|c| c.is_whitespace() || c.is_control() || c == '/' || c == '#') + { + return Err(Error::InvalidArgument(format!( + "bad host in {s:?}: no whitespace, '/' or '#'" + ))); + } + Ok((host.to_ascii_lowercase(), port)) +} + +/// One non-comment line as a pin entry, if it is a well-formed one. +fn parse_line(line: &str) -> Option { + let line = line.trim(); + if line.is_empty() || line.starts_with('#') { + return None; + } + let (key, value) = line.split_once(' ')?; + let (host, port) = key.split_once(':')?; + let port = port.parse::().ok()?; + Some(PinEntry { + host: host.to_string(), + port, + pin: parse_fingerprint(value.trim()).ok()?, + }) +} + +fn read_pin_file(file: &Path) -> Result { + match std::fs::read_to_string(file) { + Ok(t) => Ok(t), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(String::new()), + Err(e) => Err(Error::InvalidArgument(format!( + "read pin file {}: {e}", + file.display() + ))), + } +} + +/// Every well-formed pin in the file, in file order (a missing file is none; +/// comments and malformed lines are skipped). A host that was pinned twice is +/// listed twice: a connection uses the first. +pub fn list(file: &Path) -> Result> { + Ok(read_pin_file(file)? + .lines() + .filter_map(parse_line) + .collect()) +} + +/// Drop every pin for `host:port` (hostnames compare case-insensitively) and +/// leave every other line, comments and malformed ones included, as it was. +/// Returns how many pins were removed; the file is only rewritten when it was +/// more than none, and atomically. +pub fn forget(file: &Path, host: &str, port: u16) -> Result { + let file = resolve_pin_path(file); + let file = file.as_path(); + let _lock = PinLock::acquire(file)?; + let text = read_pin_file(file)?; + let (kept, removed) = without_pins(&text, host, port); + if removed > 0 { + write_pin_file(file, &kept)?; + } + Ok(removed) +} + +/// Pin `host:port` to `pin`, replacing any pin it had. Returns whether one was +/// replaced. +pub fn set_pin(file: &Path, host: &str, port: u16, pin: &[u8; 32]) -> Result { + let file = resolve_pin_path(file); + let file = file.as_path(); + let _lock = PinLock::acquire(file)?; + let text = read_pin_file(file)?; + let (mut kept, removed) = without_pins(&text, host, port); + if !kept.is_empty() && !kept.ends_with('\n') { + kept.push('\n'); + } + kept.push_str(&format!( + "{host}:{port} {}\n", + scl_tlsio::fingerprint_hex(pin) + )); + write_pin_file(file, &kept)?; + Ok(removed > 0) +} + +fn without_pins(text: &str, host: &str, port: u16) -> (String, usize) { + let mut kept = String::with_capacity(text.len()); + let mut removed = 0; + for line in text.split_inclusive('\n') { + match parse_line(line) { + Some(e) if e.port == port && e.host.eq_ignore_ascii_case(host) => removed += 1, + _ => kept.push_str(line), + } + } + (kept, removed) +} + +fn write_pin_file(file: &Path, text: &str) -> Result<()> { + // A bare relative name has an empty parent, which the durable write cannot + // open to sync: anchor it at the current directory. + let file: std::borrow::Cow = match file.parent() { + Some(p) if p.as_os_str().is_empty() => Path::new(".").join(file).into(), + _ => file.into(), + }; + let file = file.as_ref(); + if let Some(parent) = file.parent() { + std::fs::create_dir_all(parent) + .map_err(|e| Error::InvalidArgument(format!("create {}: {e}", parent.display())))?; + } + scl_core::fsutil::atomic_write_durable(file, text.as_bytes()) + .map_err(|e| Error::InvalidArgument(format!("write pin file {}: {e}", file.display()))) +} + #[cfg(test)] mod tests { use super::*; @@ -204,4 +388,193 @@ mod tests { assert!(parse_fingerprint("md5:abcd").is_err()); assert!(parse_fingerprint("").is_err()); } + + #[test] + fn list_forget_and_set_pin_manage_the_file() { + let dir = tmp("manage"); + let file = dir.join("known_hosts"); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write( + &file, + format!( + "# mine\nA.example:8730 sha256:{}\nnot a pin\nb.example:9000 sha256:{}\nA.example:8730 sha256:{}\n", + "11".repeat(32), + "22".repeat(32), + "33".repeat(32) + ), + ) + .unwrap(); + let entries = list(&file).unwrap(); + assert_eq!(entries.len(), 3, "a host pinned twice is listed twice"); + assert_eq!(entries[1].host, "b.example"); + assert_eq!(entries[1].port, 9000); + + // Forget is case-insensitive on the host, port-exact, removes every + // pin for the slot, and leaves other lines (comments, junk) alone. + assert_eq!(forget(&file, "a.EXAMPLE", 9000).unwrap(), 0); + assert_eq!(forget(&file, "a.EXAMPLE", 8730).unwrap(), 2); + let text = std::fs::read_to_string(&file).unwrap(); + assert_eq!( + text, + format!( + "# mine\nnot a pin\nb.example:9000 sha256:{}\n", + "22".repeat(32) + ) + ); + assert_eq!(forget(&file, "gone", 1).unwrap(), 0); + assert_eq!( + forget(&dir.join("nope"), "h", 1).unwrap(), + 0, + "no file, no pins" + ); + + // set_pin replaces and appends; the connection path sees the new pin. + assert!(set_pin(&file, "b.example", 9000, &[0x44; 32]).unwrap()); + assert!(!set_pin(&file, "c.example", 8730, &[0x55; 32]).unwrap()); + assert_eq!(lookup(&file, "b.example", 9000).unwrap(), Some([0x44; 32])); + assert_eq!(lookup(&file, "c.example", 8730).unwrap(), Some([0x55; 32])); + assert_eq!(list(&file).unwrap().len(), 2); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); + } + + #[test] + fn set_pin_creates_the_file_and_a_missing_final_newline_is_handled() { + let dir = tmp("create"); + let file = dir.join("sub").join("known_hosts"); + assert!(!set_pin(&file, "h", 1, &[0x66; 32]).unwrap()); + assert_eq!(list(&file).unwrap().len(), 1); + std::fs::write(&file, "x:1 sha256:zz").unwrap(); // no trailing newline + set_pin(&file, "h", 1, &[0x66; 32]).unwrap(); + let text = std::fs::read_to_string(&file).unwrap(); + assert!(text.starts_with("x:1 sha256:zz\nh:1 sha256:"), "{text:?}"); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); + } + + #[test] + fn parse_host_port_defaults_the_port_and_rejects_junk() { + assert_eq!(parse_host_port("h").unwrap(), ("h".into(), 8730)); + assert_eq!(parse_host_port("h:9").unwrap(), ("h".into(), 9)); + assert!(parse_host_port("").is_err()); + assert!(parse_host_port(":9").is_err()); + assert!(parse_host_port("h:notaport").is_err()); + assert!(parse_host_port("h:99999").is_err()); + } + + #[test] + fn lookup_matches_the_host_case_insensitively_and_the_port_exactly() { + let dir = tmp("case"); + let file = dir.join("known_hosts"); + record(&file, "Example.COM", 8730, &[0x77; 32]).unwrap(); + assert_eq!( + lookup(&file, "example.com", 8730).unwrap(), + Some([0x77; 32]) + ); + assert_eq!( + lookup(&file, "EXAMPLE.com", 8730).unwrap(), + Some([0x77; 32]) + ); + assert_eq!(lookup(&file, "example.com", 8731).unwrap(), None); + // A pin typed with any case is stored canonically, so a later lookup + // (or a strict connect) under another case finds it. + let (h, p) = parse_host_port("EXAMPLE.org:9").unwrap(); + assert_eq!((h.as_str(), p), ("example.org", 9)); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); + } + + #[test] + fn parse_host_port_rejects_hosts_no_connection_could_look_up() { + for bad in [ + "example.com/repo", + "a b", + "#x", + "x#y", + "tab\there", + "a\u{7}b", + ] { + assert!(parse_host_port(bad).is_err(), "{bad:?} must be refused"); + } + } + + #[test] + fn a_bare_relative_pin_file_works() { + let dir = tmp("relative"); + std::fs::create_dir_all(&dir).unwrap(); + // Written through a relative name (empty parent), anchored at the cwd + // by `write_pin_file`; the test uses an absolute path to the same effect + // for the durable write, and checks the empty-parent branch directly. + let rel = std::path::Path::new("scl-pins-relative-test-file"); + let _ = std::fs::remove_file(rel); + set_pin(rel, "h", 1, &[0x88; 32]).unwrap(); + assert_eq!(lookup(rel, "h", 1).unwrap(), Some([0x88; 32])); + assert_eq!(forget(rel, "h", 1).unwrap(), 1); + let _ = std::fs::remove_file(rel); + let _ = std::fs::remove_file("scl-pins-relative-test-file.lock"); + std::fs::remove_dir_all(&dir).unwrap(); + } + + /// Concurrent writers (threads stand in for processes: `flock` locks the + /// open file description, and each update opens its own) never lose a pin. + #[cfg(unix)] + #[test] + fn concurrent_pin_updates_lose_nothing() { + let dir = tmp("concurrent"); + let file = dir.join("known_hosts"); + std::fs::create_dir_all(&dir).unwrap(); + let handles: Vec<_> = (0..16u16) + .map(|i| { + let file = file.clone(); + std::thread::spawn(move || { + set_pin(&file, &format!("h{i}.example"), 8730 + i, &[i as u8; 32]).unwrap(); + record(&file, &format!("r{i}.example"), 8730, &[i as u8; 32]).unwrap(); + }) + }) + .collect(); + for h in handles { + h.join().unwrap(); + } + assert_eq!(list(&file).unwrap().len(), 32, "no update may be lost"); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); + } + + /// A pin file that is a symlink to a shared store: updates land in the + /// target and the link survives. + #[cfg(unix)] + #[test] + fn a_symlinked_pin_file_is_updated_through_the_link() { + let dir = tmp("symlink"); + std::fs::create_dir_all(&dir).unwrap(); + let target = dir.join("shared_known_hosts"); + let link = dir.join("known_hosts"); + std::fs::write(&target, "").unwrap(); + std::os::unix::fs::symlink(&target, &link).unwrap(); + + set_pin(&link, "h.example", 1, &[0x99; 32]).unwrap(); + record(&link, "r.example", 2, &[0xaa; 32]).unwrap(); + assert!( + std::fs::symlink_metadata(&link) + .unwrap() + .file_type() + .is_symlink(), + "the link must survive an update" + ); + assert_eq!(list(&target).unwrap().len(), 2, "the target holds the pins"); + assert_eq!(forget(&link, "h.example", 1).unwrap(), 1); + assert!(std::fs::symlink_metadata(&link) + .unwrap() + .file_type() + .is_symlink()); + assert_eq!(list(&target).unwrap().len(), 1); + + // A dangling link is written through to where it points. + let dangling = dir.join("dangling"); + std::os::unix::fs::symlink(dir.join("not-yet"), &dangling).unwrap(); + set_pin(&dangling, "d.example", 3, &[0xbb; 32]).unwrap(); + assert_eq!(list(&dir.join("not-yet")).unwrap().len(), 1); + std::fs::remove_dir_all(&dir).unwrap(); + assert!(!dir.exists()); + } } diff --git a/docs/adr/0053-tls-pin-management.md b/docs/adr/0053-tls-pin-management.md new file mode 100644 index 00000000..16d1e0b4 --- /dev/null +++ b/docs/adr/0053-tls-pin-management.md @@ -0,0 +1,30 @@ +# ADR-0053: TLS pin management (`sc tls`) + +- **Status:** Accepted (built) +- **Date:** 2026-10-19 +- **Builds on:** ADR-0042 (in-binary TLS, accept-new TOFU pinning) + +## Context + +ADR-0042 pins a server's SPKI hash per `host:port` in a user-level `known_hosts` file, written on first connect. The documented recovery for a changed server key was to edit that file and delete a line, and nothing listed or removed a pin. ADR-0042 named pin-management UX as a follow-on. + +## Decision + +`sc tls` is a thin command over the file, with no new trust semantics: + +- `sc tls list [--json]`: the well-formed pins in file order, as `host:port sha256:` lines (JSON for scripts). A host pinned twice is listed twice, because a connection uses the first; a missing file or no pins prints a hint on stderr. +- `sc tls forget `: removes every pin for that host and port, hostname case-insensitively, the port exact (default 8730, as in the URL). It leaves every other line (comments, malformed lines) as it was and rewrites the file atomically and durably, and only when something was removed. Forgetting an unpinned host is an error, not a silent success. A later accept-new connection (no `SC_HTTPS_STRICT`, no `SC_HTTPS_FINGERPRINT`) re-pins what it sees, as accept-new always did; under strict mode, or with a pre-pin, the host stays unpinned (strict refuses it) and `sc tls pin` is the way to set it. +- `sc tls pin `: pins without connecting first (the fingerprint `sc serve fingerprint` prints), replacing any pin the host had. This is the explicit, auditable path for a deployment that distributes the pin out of band, and it works under `SC_HTTPS_STRICT=1`. +- `sc tls path`: the file in effect (`SC_HTTPS_KNOWN_HOSTS`, else `$XDG_CONFIG_HOME/sc/known_hosts`, else `~/.config/sc/known_hosts`). + +Host and port parse as an `sc+https://` URL's authority does, so a pin names what a connection looks up: a host with whitespace, `/` or `#` is refused, the host is stored lowercase, and connection lookup compares the host case-insensitively (the port exactly). Every write to the pin file, including the first-connect append, takes an advisory lock on `.lock` (`File::lock`: `flock` on unix, `LockFileEx` on Windows), so concurrent `sc` processes cannot lose or resurrect a pin; a pin file that is a symlink (a shared or dotfile-managed store) is followed, so an update replaces the target and the link survives; a bare relative file name is anchored at the working directory for the durable write. Bad input (not 32 bytes of hex, an empty host, a bad port) is refused before the file is touched or created. + +The pin-mismatch error names `sc tls pin` (which works under strict mode) first and `sc tls forget` with a non-strict reconnect second; the strict-unknown-host error names `sc tls pin`. + +## Not decided here + +CA-path validation (a PEM-provisioned alternative to pinning) and certificate-name validation are unchanged and remain follow-ons; this ADR adds no trust path. + +## Tests + +`tls_pins` unit tests (list order and duplicates, case-insensitive port-exact forget, comments and junk preserved, set_pin replace/append/create with a missing final newline, host:port parsing) and `crates/cli/tests/tls_pins_cli.rs` (the pin, list, JSON, re-pin, forget and path flow through the binary; refused inputs leave no file). diff --git a/docs/adr/README.md b/docs/adr/README.md index 6f3f16db..6ffbb7e3 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -63,6 +63,7 @@ supersedes the old one and update the **Status** line of the superseded record. | [0050](0050-sessions-on-partial-clones.md) | Agent sessions on partial clones | Accepted | 37d | | [0051](0051-rotate-protected-paths.md) | Rotating protected paths (`sc rewrap --rotate`) | Accepted | — | | [0052](0052-secret-injection-by-fd.md) | Secret injection by file descriptor (`sc run --secrets-fd`) | Accepted | — | +| [0053](0053-tls-pin-management.md) | TLS pin management (`sc tls`) | Accepted | — | See [`ROADMAP.md`](../../ROADMAP.md) for the phase sequence. ADR numbers are assigned in creation order, so 0017 — the secret scanner — sequences as phase P5,