Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .claude/skills/sc-cli-reference/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,9 @@ cargo run --bin sc -- clone sc+https://host[:port]/repo <dst> # TLS clone (P32
# overrides), mismatch always hard-fails;
# SC_HTTPS_FINGERPRINT=<sha256:hex> pre-pins (CI),
# SC_HTTPS_STRICT=1 refuses unknown hosts;
# SC_HTTPS_CA_FILE=<pem> | SC_HTTPS_CA=system validate the
# chain, dates and name against a CA instead of
# pinning (no pin file read/written; ADR-0054);
# 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 <host[:port]> # drop a host's pin (changed server key); a later
Expand Down
5 changes: 3 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,8 +268,9 @@ 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, and CA-path validation alongside TOFU pinning. `sc tls list/forget/pin/path`
manages the `sc+https://` pin file (ADR-0053).
clones. `sc tls list/forget/pin/path` manages the `sc+https://` pin file
(ADR-0053); `SC_HTTPS_CA_FILE=<pem>` / `SC_HTTPS_CA=system` switch a client to CA
validation instead of pinning (ADR-0054).

## Agent skills

Expand Down
5 changes: 3 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -835,8 +835,10 @@ scale-&-reach horizon):
a narrowed non-loopback bind gate (`--tls` + token, not token alone). See
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 as `sc tls list/forget/pin/path`;
deployments (shipped in ADR-0054: `SC_HTTPS_CA_FILE` / `SC_HTTPS_CA=system`,
with chain, validity and name checks; v1 was pin-only, names/validity
ignored); opt-in SNI/
certificate-name validation (covered by the CA mode); 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
Expand Down
108 changes: 108 additions & 0 deletions crates/repo/src/http_transport.rs
Original file line number Diff line number Diff line change
Expand Up @@ -374,6 +374,17 @@ impl HttpTransport {
}
}

// Two trust decisions in one policy is a caller bug: refuse it before
// any socket exists, so a caller cannot believe a pin is being checked
// while CA validation silently wins (`from_env` rejects it too).
if let Some(p) = policy {
if p.ca.is_some() && p.pre_pin.is_some() {
return Err(Error::InvalidArgument(
"a TLS policy cannot combine CA validation with a pre-pin".to_string(),
));
}
}

let stream = TcpStream::connect(url.authority())
.map_err(|e| Error::ConnectionLost(format!("sc+http connect to {url:?}: {e}")))?;

Expand All @@ -400,6 +411,24 @@ impl HttpTransport {
HttpWriteHalf::Plain(stream),
)
}
// CA validation (ADR-0054): chain, validity and name against a CA,
// not a pin; the pin file is neither read nor written, and the
// handshake still completes before any application byte.
(true, Some(p)) if p.ca.is_some() => {
let trust = match p.ca.as_ref().expect("guarded by is_some") {
Comment thread
tonibergholm marked this conversation as resolved.
Resolved
crate::tls_pins::CaSource::File(f) => scl_tlsio::CaTrust::from_pem_file(f),
crate::tls_pins::CaSource::System => scl_tlsio::CaTrust::system(),
}?;
for w in trust.warnings() {
eprintln!("warning: sc+https CA trust: {w}");
}
let tls = scl_tlsio::client_connect_ca(stream, &url.host, &trust)?;
let (rh, wh) = tls.split();
(
BufReader::new(HttpReadHalf::Tls(rh)),
HttpWriteHalf::Tls(wh),
)
}
(true, Some(p)) => {
let expected = match p.pre_pin {
Some(pin) => Some(pin),
Expand Down Expand Up @@ -2179,6 +2208,7 @@ mod tests {
known_hosts: kh.clone(),
pre_pin: None,
strict: false,
ca: None,
};

// 1. Unknown host, accept-new: connects AND records the pin.
Expand All @@ -2197,13 +2227,15 @@ mod tests {
known_hosts: kh.clone(),
pre_pin: None,
strict: true,
ca: None,
};
HttpTransport::connect_with_pins(&url, None, Some(&strict_known)).unwrap();
let fresh = pins_dir.join("fresh_kh");
let strict_unknown = crate::tls_pins::TlsClientPolicy {
known_hosts: fresh.clone(),
pre_pin: None,
strict: true,
ca: None,
};
match HttpTransport::connect_with_pins(&url, None, Some(&strict_unknown)) {
Err(Error::TlsStrictUnknownHost(_)) => {}
Expand All @@ -2217,6 +2249,7 @@ mod tests {
known_hosts: prepin_file.clone(),
pre_pin: Some(spki),
strict: true,
ca: None,
};
HttpTransport::connect_with_pins(&url, None, Some(&prepin)).unwrap();
assert!(!prepin_file.exists(), "pre-pin must not persist");
Expand All @@ -2228,6 +2261,7 @@ mod tests {
known_hosts: bad.clone(),
pre_pin: None,
strict: false,
ca: None,
};
match HttpTransport::connect_with_pins(&url, None, Some(&badpol)) {
Err(Error::TlsPinMismatch {
Expand All @@ -2248,6 +2282,79 @@ mod tests {
std::fs::remove_dir_all(&root).unwrap();
}

/// CA validation replaces pinning (ADR-0054): a server the CA does not
/// vouch for is refused, the pin file is neither created nor read, and an
/// unusable CA bundle fails the connection instead of falling back to
/// accept-new.
#[test]
fn a_ca_policy_never_touches_the_pin_file_and_fails_closed() {
let root = tmp_repo("tls-ca-policy");
let (addr, _spki) = spawn_tls_server(&root);
let (host, port) = addr
.rsplit_once(':')
.map(|(h, p)| (h.to_string(), p.parse::<u16>().unwrap()))
.unwrap();
let url = ScHttpUrl {
host,
port,
path: "/".into(),
tls: true,
};
let dir = std::env::temp_dir().join(format!("scl-ca-policy-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
let kh = dir.join("known_hosts");
let policy = |ca| crate::tls_pins::TlsClientPolicy {
known_hosts: kh.clone(),
pre_pin: None,
strict: false,
ca: Some(ca),
};

// The server's own self-signed certificate is not a CA for the name
// dialled (it covers `sc-serve`, not 127.0.0.1): refused.
let own_cert = root.join(".sc/serve-tls/cert.pem");
let as_ca = policy(crate::tls_pins::CaSource::File(own_cert));
match HttpTransport::connect_with_pins(&url, None, Some(&as_ca)) {
Err(Error::Tls(e)) => {
assert!(e.to_string().contains("certificate validation"), "got {e}")
}
other => panic!(
"expected a CA validation failure, got {:?}",
other.map(|_| ())
),
}
assert!(!kh.exists(), "CA mode must not write a pin");

// A missing or empty bundle fails closed, never falls back to TOFU.
let missing = policy(crate::tls_pins::CaSource::File(dir.join("absent.pem")));
assert!(matches!(
HttpTransport::connect_with_pins(&url, None, Some(&missing)),
Err(Error::Tls(_))
));
std::fs::write(dir.join("empty.pem"), "").unwrap();
let empty = policy(crate::tls_pins::CaSource::File(dir.join("empty.pem")));
assert!(matches!(
HttpTransport::connect_with_pins(&url, None, Some(&empty)),
Err(Error::Tls(_))
));
assert!(!kh.exists(), "still no pin written");

// A policy that asks for both trust decisions is refused up front.
let both = crate::tls_pins::TlsClientPolicy {
known_hosts: kh.clone(),
pre_pin: Some([0x11; 32]),
strict: false,
ca: Some(crate::tls_pins::CaSource::System),
};
assert!(matches!(
HttpTransport::connect_with_pins(&url, None, Some(&both)),
Err(Error::InvalidArgument(m)) if m.contains("cannot combine")
));
std::fs::remove_dir_all(&dir).unwrap();
std::fs::remove_dir_all(&root).unwrap();
}

/// Transport verbs work over TLS end to end (list_refs against the real
/// server — the full clone/push/fetch acceptance rides the CLI test in
/// Task 7).
Expand All @@ -2269,6 +2376,7 @@ mod tests {
known_hosts: std::env::temp_dir().join(format!("scl-verbs-kh-{}", std::process::id())),
pre_pin: Some(spki),
strict: false,
ca: None,
};
let t = HttpTransport::connect_with_pins(&url, None, Some(&policy)).unwrap();
// A fresh `tmp_repo` has no commits, so `list_refs()` is legitimately
Expand Down
127 changes: 125 additions & 2 deletions crates/repo/src/tls_pins.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,20 +23,106 @@ pub struct TlsClientPolicy {
/// as enabled (fails closed on typos like `=true`/`=yes` rather than
/// silently falling back to accept-new — see [`strict_from`]).
pub strict: bool,
/// `SC_HTTPS_CA_FILE` / `SC_HTTPS_CA=system` (ADR-0054): validate the
/// server's certificate chain, validity and name against a CA instead of
/// pinning. When set, the pin file is neither read nor written.
pub ca: Option<CaSource>,
}

/// Where a CA-validated connection gets its trust anchors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CaSource {
/// A PEM bundle of CA certificates (`SC_HTTPS_CA_FILE`).
File(PathBuf),
/// The platform trust store (`SC_HTTPS_CA=system`).
System,
}

/// Pure decision for the CA env knobs, factored out for the same reason as
/// [`strict_from`]. `file`/`mode` are the raw environment values (`None` =
/// the variable is absent). Fails closed: a security knob that is PRESENT but
/// empty (an unset shell variable in `SC_HTTPS_CA_FILE="$BUNDLE"`) or not
/// valid UTF-8 is an error, not an absence; so is an unrecognized `SC_HTTPS_CA`
/// value, both knobs at once, or CA trust together with a pre-pin. Nothing
/// here may quietly fall back to pinning or accept-new, which would send the
/// bearer token to an unverified host.
fn ca_from(
file: Option<&std::ffi::OsStr>,
mode: Option<&std::ffi::OsStr>,
has_pre_pin: bool,
) -> Result<Option<CaSource>> {
if file.is_some_and(|f| f.is_empty()) {
return Err(Error::InvalidArgument(
"SC_HTTPS_CA_FILE is set but empty; unset it or point it at a PEM bundle".to_string(),
));
}
let mode =
match mode {
None => None,
Some(m) => Some(m.to_str().ok_or_else(|| {
Error::InvalidArgument("SC_HTTPS_CA is not valid UTF-8".to_string())
})?),
};
if mode.is_some_and(|m| m.is_empty()) {
return Err(Error::InvalidArgument(
"SC_HTTPS_CA is set but empty; use `system` or unset it".to_string(),
));
}
let source = match (file, mode) {
(None, None) => return Ok(None),
(Some(_), Some(_)) => {
return Err(Error::InvalidArgument(
"set one of SC_HTTPS_CA_FILE and SC_HTTPS_CA, not both".to_string(),
))
}
(Some(f), None) => CaSource::File(PathBuf::from(f)),
(None, Some("system")) => CaSource::System,
(None, Some(other)) => {
return Err(Error::InvalidArgument(format!(
"SC_HTTPS_CA must be `system` (or use SC_HTTPS_CA_FILE=<pem>), got {other:?}"
)))
}
};
if has_pre_pin {
return Err(Error::InvalidArgument(
"SC_HTTPS_FINGERPRINT (a pin) cannot be combined with CA validation".to_string(),
));
}
Ok(Some(source))
}

impl TlsClientPolicy {
pub fn from_env() -> Result<TlsClientPolicy> {
let known_hosts = known_hosts_path()?;
// A pre-pin that is present but not valid UTF-8 is an error, not an
// absent pin: ignoring it would drop an explicit trust decision (and
// its conflict check with CA trust).
let pre_pin = match std::env::var("SC_HTTPS_FINGERPRINT") {
Ok(s) if !s.is_empty() => Some(parse_fingerprint(&s)?),
_ => None,
Ok(_) | Err(std::env::VarError::NotPresent) => None,
Err(std::env::VarError::NotUnicode(_)) => {
return Err(Error::InvalidArgument(
"SC_HTTPS_FINGERPRINT is not valid UTF-8".to_string(),
))
}
};
let strict = strict_from(std::env::var("SC_HTTPS_STRICT").ok().as_deref());
let ca = ca_from(
std::env::var_os("SC_HTTPS_CA_FILE").as_deref(),
std::env::var_os("SC_HTTPS_CA").as_deref(),
pre_pin.is_some(),
)?;
Comment thread
tonibergholm marked this conversation as resolved.
Resolved
// CA mode never reads or writes the pin file, so a missing HOME (a
// service, a container) must not fail it.
let known_hosts = if ca.is_some() {
known_hosts_path().unwrap_or_default()
} else {
known_hosts_path()?
};
Ok(TlsClientPolicy {
known_hosts,
pre_pin,
strict,
ca,
})
}
}
Expand Down Expand Up @@ -577,4 +663,41 @@ mod tests {
std::fs::remove_dir_all(&dir).unwrap();
assert!(!dir.exists());
}

#[test]
fn ca_from_resolves_the_knobs_and_fails_closed() {
use std::ffi::OsStr;
let os = OsStr::new;
assert_eq!(ca_from(None, None, false).unwrap(), None);
assert_eq!(
ca_from(Some(os("/etc/ca.pem")), None, false).unwrap(),
Some(CaSource::File("/etc/ca.pem".into()))
);
assert_eq!(
ca_from(None, Some(os("system")), false).unwrap(),
Some(CaSource::System)
);
for bad in [
ca_from(None, Some(os("yes")), false),
ca_from(None, Some(os("System")), false),
ca_from(Some(os("/x")), Some(os("system")), false),
ca_from(None, Some(os("system")), true),
ca_from(Some(os("/x")), None, true),
// Present but empty: an unset shell variable, never an absence.
ca_from(Some(os("")), None, false),
ca_from(None, Some(os("")), false),
ca_from(Some(os("")), Some(os("system")), false),
] {
assert!(bad.is_err(), "must fail closed, got {bad:?}");
}
}

/// A non-UTF-8 `SC_HTTPS_CA` must not read as "unset".
#[cfg(unix)]
#[test]
fn ca_from_rejects_a_non_utf8_mode() {
use std::os::unix::ffi::OsStrExt;
let bad = std::ffi::OsStr::from_bytes(b"sys\xffem");
assert!(ca_from(None, Some(bad), false).is_err());
}
}
1 change: 1 addition & 0 deletions crates/tlsio/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ hex = "0.4.3"
rcgen = "0.14.8"
ring = "0.17.14"
rustls = { version = "0.23.41", default-features = false, features = ["ring", "std", "tls12", "logging"] }
rustls-native-certs = "0.8.5"
rustls-pki-types = { version = "1.15.0", features = ["std"] }
thiserror = "2.0.18"

Expand Down
Loading
Loading