From e115dd1ad7398d627a4a5b5f4c47220fae0908e8 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 15:06:00 +0300 Subject: [PATCH 1/3] feat(cli): sc tls list/forget/pin/path manages the sc+https known_hosts pins (ADR-0053) The documented recovery for a changed server key was to edit the pin file by hand, and nothing listed or removed a pin. sc tls lists the pins (JSON for scripts), forgets a host's pins (hostname case-insensitive, port exact, other lines untouched, atomic rewrite, an error if nothing was pinned), pins a host to a fingerprint without connecting (works under SC_HTTPS_STRICT=1) and prints the file in effect. The pin-mismatch and strict-unknown-host errors now name these commands. No new trust semantics. Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/sc-cli-reference/SKILL.md | 5 + CLAUDE.md | 4 +- ROADMAP.md | 4 +- crates/cli/src/main.rs | 96 +++++++++++ crates/cli/tests/tls_pins_cli.rs | 121 +++++++++++++ crates/repo/src/error.rs | 8 +- crates/repo/src/tls_pins.rs | 205 ++++++++++++++++++++++- docs/adr/0053-tls-pin-management.md | 30 ++++ docs/adr/README.md | 1 + 9 files changed, 463 insertions(+), 11 deletions(-) create mode 100644 crates/cli/tests/tls_pins_cli.rs create mode 100644 docs/adr/0053-tls-pin-management.md diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index 389e5a41..f6f27933 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -353,6 +353,11 @@ 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); the next + # connect 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..f9b7be69 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 + certificate-name validation; pin-management UX (SHIPPED in ADR-0053: `sc tls list/forget/pin/path`; it was `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); + and first-connect/`SC_HTTPS_FINGERPRINT` write pins, nothing 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..94e19c0f 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,69 @@ 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(); + print_line(&serde_json::json!({"file": file, "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}; the next connection pins what it sees"); + 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..8e48a053 --- /dev/null +++ b/crates/cli/tests/tls_pins_cli.rs @@ -0,0 +1,121 @@ +//! `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 { + Command::new(env!("CARGO_BIN_EXE_sc")) + .args(args) + .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); + + // 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"], + ] { + 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()); +} diff --git a/crates/repo/src/error.rs b/crates/repo/src/error.rs index 2eae82e1..0de21c85 100644 --- a/crates/repo/src/error.rs +++ b/crates/repo/src/error.rs @@ -122,8 +122,9 @@ 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, run `sc tls forget {host}` (or remove that \ + host's line from the pin file) and reconnect (the next connect re-pins); verify with \ + `sc serve fingerprint` on the server." )] TlsPinMismatch { host: String, @@ -133,7 +134,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..40d047f5 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 { @@ -136,6 +142,124 @@ pub fn record(file: &Path, host: &str, port: u16, pin: &[u8; 32]) -> Result<()> Ok(()) } +/// 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:?}"))); + } + Ok((host.to_string(), 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 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 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<()> { + 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 +328,77 @@ 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()); + } } diff --git a/docs/adr/0053-tls-pin-management.md b/docs/adr/0053-tls-pin-management.md new file mode 100644 index 00000000..cca7e115 --- /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. The next connection re-pins what it sees, as accept-new always did. +- `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 exactly as an `sc+https://` URL's authority does, so a pin names what a connection looks up. 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 and the strict-unknown-host error now name these commands instead of "edit the file". + +## 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, From 67a1dd2b402f1b7171a7ebb778e9f12e2c6deaf5 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 15:17:42 +0300 Subject: [PATCH 2/3] fix(repo): sc tls pins are case-insensitive, locked, host-validated and strict-mode-aware Codex and CodeRabbit: connection lookup compared the host case-sensitively, so a pin typed in another case was missed (lookup is now case-insensitive on the host, and pin stores it lowercase); a read-modify-write could lose a pin or resurrect a forgotten one (every pin-file write now takes an advisory lock); a bare relative pin file broke the durable write (anchored at the cwd); hosts with whitespace, '/' or '#' could form an unusable pin (refused); the mismatch and forget messages recommended a re-pin that strict mode forbids (they now name sc tls pin first); plus doc and test-helper fixes. Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/sc-cli-reference/SKILL.md | 6 +- ROADMAP.md | 6 +- crates/cli/src/main.rs | 5 +- crates/cli/tests/tls_pins_cli.rs | 18 +++ crates/repo/src/error.rs | 7 +- crates/repo/src/tls_pins.rs | 178 +++++++++++++++++++---- docs/adr/0053-tls-pin-management.md | 6 +- 7 files changed, 188 insertions(+), 38 deletions(-) diff --git a/.claude/skills/sc-cli-reference/SKILL.md b/.claude/skills/sc-cli-reference/SKILL.md index f6f27933..5c4691af 100644 --- a/.claude/skills/sc-cli-reference/SKILL.md +++ b/.claude/skills/sc-cli-reference/SKILL.md @@ -354,8 +354,10 @@ cargo run --bin sc -- clone sc+https://host[:port]/repo # TLS clone (P32 # 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); the next - # connect re-pins; errors if nothing was pinned +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 diff --git a/ROADMAP.md b/ROADMAP.md index f9b7be69..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 (SHIPPED in ADR-0053: `sc tls list/forget/pin/path`; it was `sc tls` list/remove - entries in `~/.config/sc/known_hosts` — today only `sc serve fingerprint` - and first-connect/`SC_HTTPS_FINGERPRINT` write pins, nothing removed 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 94e19c0f..e8c2904b 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -1146,7 +1146,10 @@ fn run_tls(op: TlsOp) -> Result<()> { if n == 0 { anyhow::bail!("no pin for {host}:{port} in {}", file.display()); } - println!("forgot {n} pin(s) for {host}:{port}; the next connection pins what it sees"); + 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 { diff --git a/crates/cli/tests/tls_pins_cli.rs b/crates/cli/tests/tls_pins_cli.rs index 8e48a053..723c780b 100644 --- a/crates/cli/tests/tls_pins_cli.rs +++ b/crates/cli/tests/tls_pins_cli.rs @@ -5,8 +5,10 @@ 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") @@ -65,6 +67,15 @@ fn pin_list_forget_round_trip_through_the_cli() { 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)); @@ -108,6 +119,13 @@ fn bad_input_is_refused_before_the_file_is_touched() { &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"); diff --git a/crates/repo/src/error.rs b/crates/repo/src/error.rs index 0de21c85..83c125d6 100644 --- a/crates/repo/src/error.rs +++ b/crates/repo/src/error.rs @@ -122,9 +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, run `sc tls forget {host}` (or 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, diff --git a/crates/repo/src/tls_pins.rs b/crates/repo/src/tls_pins.rs index 40d047f5..f598ce5e 100644 --- a/crates/repo/src/tls_pins.rs +++ b/crates/repo/src/tls_pins.rs @@ -98,35 +98,19 @@ 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 _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())))?; @@ -142,6 +126,51 @@ 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. +/// Unix only; elsewhere updates are unserialized, as before. +struct PinLock { + #[cfg(unix)] + _file: std::fs::File, +} + +impl PinLock { + #[cfg(unix)] + fn acquire(file: &Path) -> Result { + use std::os::fd::AsRawFd; + 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())) + })?; + // SAFETY: flock on a descriptor this File owns; released on drop/close. + if unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX) } != 0 { + return Err(Error::InvalidArgument(format!( + "lock {}: {}", + lock_path.display(), + std::io::Error::last_os_error() + ))); + } + Ok(PinLock { _file: f }) + } + + #[cfg(not(unix))] + fn acquire(_: &Path) -> Result { + Ok(PinLock {}) + } +} + /// One pin as stored: the `host:port` it was recorded for and its SPKI hash. #[derive(Debug, Clone, PartialEq, Eq)] pub struct PinEntry { @@ -170,7 +199,17 @@ pub fn parse_host_port(s: &str) -> Result<(String, u16)> { if host.is_empty() { return Err(Error::InvalidArgument(format!("empty host in {s:?}"))); } - Ok((host.to_string(), port)) + // 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. @@ -215,6 +254,7 @@ pub fn list(file: &Path) -> Result> { /// 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 _lock = PinLock::acquire(file)?; let text = read_pin_file(file)?; let (kept, removed) = without_pins(&text, host, port); if removed > 0 { @@ -226,6 +266,7 @@ pub fn forget(file: &Path, host: &str, port: u16) -> Result { /// 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 _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') { @@ -252,6 +293,13 @@ fn without_pins(text: &str, host: &str, port: u16) -> (String, usize) { } 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())))?; @@ -401,4 +449,82 @@ mod tests { 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()); + } } diff --git a/docs/adr/0053-tls-pin-management.md b/docs/adr/0053-tls-pin-management.md index cca7e115..14543ae2 100644 --- a/docs/adr/0053-tls-pin-management.md +++ b/docs/adr/0053-tls-pin-management.md @@ -13,13 +13,13 @@ ADR-0042 pins a server's SPKI hash per `host:port` in a user-level `known_hosts` `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. The next connection re-pins what it sees, as accept-new always did. +- `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 exactly as an `sc+https://` URL's authority does, so a pin names what a connection looks up. Bad input (not 32 bytes of hex, an empty host, a bad port) is refused before the file is touched or created. +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` (unix), so concurrent `sc` processes cannot lose or resurrect a pin; 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 and the strict-unknown-host error now name these commands instead of "edit the file". +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 From 4e1ce5cbe0bcb06fca7685650afbad3880f683cf Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 15:26:34 +0300 Subject: [PATCH 3/3] fix(repo): sc tls follows a symlinked pin file, locks via File::lock, renders the JSON path lossily Codex and CodeRabbit: an atomic rename replaced a symlinked pin file instead of its target (the target is now resolved, dangling links included); the no-op lock on non-unix targets is replaced by std's File::lock (flock on unix, LockFileEx on Windows); and a non-UTF-8 pin path panicked while building the list --json output. Co-Authored-By: Claude Sonnet 5.5 --- crates/cli/src/main.rs | 6 ++- crates/cli/tests/tls_pins_cli.rs | 22 ++++++++ crates/repo/src/tls_pins.rs | 80 +++++++++++++++++++++++------ docs/adr/0053-tls-pin-management.md | 2 +- 4 files changed, 93 insertions(+), 17 deletions(-) diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index e8c2904b..5bd75c9e 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -1124,7 +1124,11 @@ fn run_tls(op: TlsOp) -> Result<()> { }) }) .collect(); - print_line(&serde_json::json!({"file": file, "pins": rows}).to_string()); + // `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!( diff --git a/crates/cli/tests/tls_pins_cli.rs b/crates/cli/tests/tls_pins_cli.rs index 723c780b..ab5598b1 100644 --- a/crates/cli/tests/tls_pins_cli.rs +++ b/crates/cli/tests/tls_pins_cli.rs @@ -137,3 +137,25 @@ fn bad_input_is_refused_before_the_file_is_touched() { 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/tls_pins.rs b/crates/repo/src/tls_pins.rs index f598ce5e..9a349ad2 100644 --- a/crates/repo/src/tls_pins.rs +++ b/crates/repo/src/tls_pins.rs @@ -110,6 +110,8 @@ pub fn lookup(file: &Path, host: &str, port: u16) -> Result> { /// 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) @@ -129,16 +131,14 @@ pub fn record(file: &Path, host: &str, port: u16, pin: &[u8; 32]) -> Result<()> /// 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. -/// Unix only; elsewhere updates are unserialized, as before. +/// `File::lock` is `flock` on unix and `LockFileEx` on Windows; the lock is +/// released when the guard drops. struct PinLock { - #[cfg(unix)] _file: std::fs::File, } impl PinLock { - #[cfg(unix)] fn acquire(file: &Path) -> Result { - use std::os::fd::AsRawFd; let mut lock_path = file.as_os_str().to_owned(); lock_path.push(".lock"); let lock_path = PathBuf::from(lock_path); @@ -154,20 +154,28 @@ impl PinLock { .map_err(|e| { Error::InvalidArgument(format!("open pin lock {}: {e}", lock_path.display())) })?; - // SAFETY: flock on a descriptor this File owns; released on drop/close. - if unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX) } != 0 { - return Err(Error::InvalidArgument(format!( - "lock {}: {}", - lock_path.display(), - std::io::Error::last_os_error() - ))); - } + f.lock() + .map_err(|e| Error::InvalidArgument(format!("lock {}: {e}", lock_path.display())))?; Ok(PinLock { _file: f }) } +} - #[cfg(not(unix))] - fn acquire(_: &Path) -> Result { - Ok(PinLock {}) +/// 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(), } } @@ -254,6 +262,8 @@ pub fn list(file: &Path) -> Result> { /// 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); @@ -266,6 +276,8 @@ pub fn forget(file: &Path, host: &str, port: u16) -> Result { /// 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); @@ -527,4 +539,42 @@ mod tests { 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 index 14543ae2..16d1e0b4 100644 --- a/docs/adr/0053-tls-pin-management.md +++ b/docs/adr/0053-tls-pin-management.md @@ -17,7 +17,7 @@ ADR-0042 pins a server's SPKI hash per `host:port` in a user-level `known_hosts` - `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` (unix), so concurrent `sc` processes cannot lose or resurrect a pin; 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. +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`.