hecks 3.11.0 → 3.12.0

data/rust/host/src/platform_signin/fetcher.rs

@@ -0,0 +1,322 @@
+//! The real fetch of the issuer's key set, on the HTTP client the host already uses for Google
+//! (`reqwest`, as in the Google token exchange).
+//!
+//! It is bounded on every side: a five second timeout, no redirects (a key set that moves is
+//! refused, not followed), a status of exactly 200, and a body cap checked while reading. It also
+//! reports how long the issuer allows the answer to be cached, which the cache honours up to its
+//! own cap.
+
+use std::sync::atomic::{AtomicI64, Ordering};
+use std::time::Duration;
+
+use super::jwks::{FetchFailed, JwksFetcher};
+
+/// How long a fetch may take, connection and body together.
+pub const TIMEOUT: Duration = Duration::from_secs(5);
+/// The largest key set body accepted, in bytes.
+pub const MAX_BODY_BYTES: usize = 64 * 1024;
+
+/// The stored value that means the last answer carried no cache hint.
+const NO_HINT: i64 = -1;
+
+/// Fetches a key set over HTTPS from a fixed address.
+pub struct HttpJwksFetcher {
+    url: String,
+    timeout: Duration,
+    max_age: AtomicI64,
+}
+
+impl HttpJwksFetcher {
+    /// Builds a fetcher for `url` with the standard timeout.
+    pub fn new(url: &str) -> Self {
+        Self::with_timeout(url, TIMEOUT)
+    }
+
+    /// Builds a fetcher with an explicit timeout.
+    pub fn with_timeout(url: &str, timeout: Duration) -> Self {
+        Self {
+            url: url.to_string(),
+            timeout,
+            max_age: AtomicI64::new(NO_HINT),
+        }
+    }
+
+    async fn get(&self) -> Result<(String, Option<i64>), FetchFailed> {
+        let client = reqwest::Client::builder()
+            .redirect(reqwest::redirect::Policy::none())
+            .timeout(self.timeout)
+            .build()
+            .map_err(|_| FetchFailed)?;
+        let mut response = client
+            .get(&self.url)
+            .send()
+            .await
+            .map_err(|_| FetchFailed)?;
+        if response.status() != reqwest::StatusCode::OK || announced_too_large(&response) {
+            return Err(FetchFailed);
+        }
+        let hint = response
+            .headers()
+            .get(reqwest::header::CACHE_CONTROL)
+            .and_then(|value| value.to_str().ok())
+            .and_then(max_age_of);
+        let mut body = Vec::new();
+        while let Some(chunk) = response.chunk().await.map_err(|_| FetchFailed)? {
+            if body.len() + chunk.len() > MAX_BODY_BYTES {
+                return Err(FetchFailed);
+            }
+            body.extend_from_slice(&chunk);
+        }
+        Ok((String::from_utf8(body).map_err(|_| FetchFailed)?, hint))
+    }
+}
+
+fn announced_too_large(response: &reqwest::Response) -> bool {
+    response
+        .content_length()
+        .is_some_and(|length| length > MAX_BODY_BYTES as u64)
+}
+
+/// Reads `max-age` from a `Cache-Control` value; `no-store`, `no-cache` and absence give `None`.
+pub fn max_age_of(cache_control: &str) -> Option<i64> {
+    let directives: Vec<String> = cache_control
+        .split(',')
+        .map(|d| d.trim().to_ascii_lowercase())
+        .collect();
+    if directives
+        .iter()
+        .any(|d| d == "no-store" || d == "no-cache")
+    {
+        return None;
+    }
+    directives
+        .iter()
+        .find_map(|d| d.strip_prefix("max-age="))
+        .and_then(|seconds| seconds.parse::<i64>().ok())
+        .filter(|seconds| *seconds >= 0)
+}
+
+impl JwksFetcher for HttpJwksFetcher {
+    /// Must be called from a blocking thread of the tokio runtime.
+    fn fetch(&self) -> Result<String, FetchFailed> {
+        let handle = tokio::runtime::Handle::try_current().map_err(|_| FetchFailed)?;
+        let outcome = handle.block_on(self.get());
+        let hint = outcome.as_ref().ok().and_then(|(_, hint)| *hint);
+        self.max_age
+            .store(hint.unwrap_or(NO_HINT), Ordering::SeqCst);
+        outcome.map(|(body, _)| body)
+    }
+
+    fn ttl_hint(&self) -> Option<i64> {
+        Some(self.max_age.load(Ordering::SeqCst)).filter(|hint| *hint >= 0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+
+    /// Serves `responses` in turn on a loopback port, one connection each, and returns the address.
+    fn serve(responses: Vec<Vec<u8>>) -> String {
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        let address = listener.local_addr().unwrap();
+        std::thread::spawn(move || {
+            for response in responses {
+                let Ok((mut stream, _)) = listener.accept() else {
+                    return;
+                };
+                let mut buffer = [0u8; 2048];
+                let _ = stream.read(&mut buffer);
+                let _ = stream.write_all(&response);
+                std::thread::sleep(Duration::from_millis(300));
+            }
+        });
+        format!("http://{address}/jwks.json")
+    }
+
+    fn http(status: &str, headers: &str, body: &str) -> Vec<u8> {
+        format!(
+            "HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n{headers}\r\n{body}",
+            body.len()
+        )
+        .into_bytes()
+    }
+
+    async fn fetch(url: String) -> (Result<String, FetchFailed>, Option<i64>) {
+        tokio::task::spawn_blocking(move || {
+            let fetcher = HttpJwksFetcher::with_timeout(&url, Duration::from_millis(800));
+            let result = fetcher.fetch();
+            (result, fetcher.ttl_hint())
+        })
+        .await
+        .unwrap()
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_200_answer_is_returned_with_its_cache_hint() {
+        let url = serve(vec![http(
+            "200 OK",
+            "Cache-Control: public, max-age=120\r\n",
+            "{\"keys\":[]}",
+        )]);
+        let (body, hint) = fetch(url).await;
+        assert_eq!(body.unwrap(), "{\"keys\":[]}");
+        assert_eq!(hint, Some(120));
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn an_answer_without_a_cache_header_gives_no_hint() {
+        let (body, hint) = fetch(serve(vec![http("200 OK", "", "{}")])).await;
+        assert!(body.is_ok());
+        assert_eq!(hint, None);
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_redirect_is_refused_not_followed() {
+        let target = serve(vec![http("200 OK", "", "{\"keys\":[]}")]);
+        let url = serve(vec![http(
+            "302 Found",
+            &format!("Location: {target}\r\n"),
+            "",
+        )]);
+        assert_eq!(fetch(url).await.0, Err(FetchFailed));
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn any_status_but_200_is_a_failure() {
+        for status in [
+            "204 No Content",
+            "404 Not Found",
+            "500 Internal Server Error",
+            "206 Partial Content",
+        ] {
+            assert_eq!(
+                fetch(serve(vec![http(status, "", "{}")])).await.0,
+                Err(FetchFailed),
+                "{status}"
+            );
+        }
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_body_over_the_cap_is_a_failure_by_header_and_by_reading() {
+        let big = "a".repeat(MAX_BODY_BYTES + 1);
+        assert_eq!(
+            fetch(serve(vec![http("200 OK", "", &big)])).await.0,
+            Err(FetchFailed)
+        );
+        let chunked = format!("HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\nConnection: close\r\n\r\n{:x}\r\n{big}\r\n0\r\n\r\n", big.len());
+        assert_eq!(
+            fetch(serve(vec![chunked.into_bytes()])).await.0,
+            Err(FetchFailed)
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_body_exactly_at_the_cap_is_accepted() {
+        let exact = "a".repeat(MAX_BODY_BYTES);
+        assert_eq!(
+            fetch(serve(vec![http("200 OK", "", &exact)]))
+                .await
+                .0
+                .unwrap()
+                .len(),
+            MAX_BODY_BYTES
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_server_that_never_answers_times_out() {
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        let url = format!("http://{}/jwks.json", listener.local_addr().unwrap());
+        let started = std::time::Instant::now();
+        assert_eq!(fetch(url).await.0, Err(FetchFailed));
+        assert!(started.elapsed() < Duration::from_secs(4));
+        drop(listener);
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_refused_connection_is_a_failure() {
+        let port = TcpListener::bind("127.0.0.1:0")
+            .unwrap()
+            .local_addr()
+            .unwrap()
+            .port();
+        assert_eq!(
+            fetch(format!("http://127.0.0.1:{port}/x")).await.0,
+            Err(FetchFailed)
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn the_real_fetcher_feeds_the_real_verifier_through_the_handler() {
+        use super::super::handler::SigninHandler;
+        use super::super::jti::JtiStore;
+        use super::super::jwks::JwksCache;
+        use super::super::verify::Verifier;
+        use super::super::wiring_support::*;
+        use std::sync::Arc;
+
+        let doc = vectors();
+        let document = doc["jwks"].to_string();
+        let url = serve(vec![http(
+            "200 OK",
+            "Cache-Control: max-age=300\r\n",
+            &document,
+        )]);
+        let pins = &doc["config"];
+        let pinned = super::super::config::PlatformSigninConfig::new(
+            pins["iss"].as_str().unwrap(),
+            &url,
+            pins["aud"].as_str().unwrap(),
+            pins["env"].as_str().unwrap(),
+        );
+        let keys = JwksCache::new(HttpJwksFetcher::with_timeout(&url, Duration::from_secs(2)));
+        let verifier = Verifier::new(pinned, keys, JtiStore::new());
+        let now = doc["now"].as_i64().unwrap();
+        let handler = SigninHandler::new(
+            settings("alongside"),
+            Arc::new(verifier),
+            Arc::new(Recorder::default()),
+        )
+        .with_clock(Box::new(move || now));
+        let members = FakeMembers::resolving(Person::new("person@example.test", Some("Admin")));
+        let response = handler
+            .callback(&request_for(&single(&doc, "valid")), &members)
+            .await;
+        assert_eq!(response["statusCode"], 302);
+    }
+
+    #[test]
+    fn the_standard_timeout_is_five_seconds_and_the_cap_64_kib() {
+        assert_eq!(TIMEOUT, Duration::from_secs(5));
+        assert_eq!(MAX_BODY_BYTES, 65536);
+    }
+
+    #[test]
+    fn max_age_is_read_from_cache_control() {
+        assert_eq!(max_age_of("max-age=300"), Some(300));
+        assert_eq!(max_age_of("public, max-age=60, must-revalidate"), Some(60));
+        assert_eq!(max_age_of("Max-Age=45"), Some(45));
+        assert_eq!(max_age_of("s-maxage=90, max-age=30"), Some(30));
+    }
+
+    #[test]
+    fn a_hint_that_forbids_caching_or_is_unreadable_is_none() {
+        for value in [
+            "",
+            "no-store",
+            "no-cache",
+            "max-age=300, no-store",
+            "max-age=abc",
+            "max-age=-5",
+            "max-age=",
+            "private",
+            "max-age=99999999999999999999",
+        ] {
+            assert_eq!(max_age_of(value), None, "{value:?}");
+        }
+    }
+}

data/rust/host/src/platform_signin/handler.rs

@@ -0,0 +1,251 @@
+//! The two halves of the sign-in flow: starting it, and finishing it on the callback.
+//!
+//! Starting makes a fresh nonce and state, stores them in the browser's `__Host-signin` cookie
+//! and sends the browser to the issuer. Finishing reads that cookie and the callback's `token`
+//! and `state`, verifies the token, maps it to a member and, only then, establishes a session.
+//! Whatever happens, the sign-in cookie is deleted.
+//!
+//! ## What it never reads
+//!
+//! The issuer's address, the site's address and every redirect target come from the validated
+//! settings. The handler is never given a `Host` or `X-Forwarded-*` header and reads no parameter
+//! other than `token` and `state`, so a request cannot change where the browser is sent.
+//!
+//! ## What it never logs
+//!
+//! The token, the nonce, the state and the cookie are never written to a log, and an email only as
+//! a short hash. A refusal logs its stable code.
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+
+use super::cookie;
+use super::jwks::KeySource;
+use super::pages::{self, Failure};
+use super::query;
+use super::session::{self, MemberDirectory};
+use super::settings::SigninSettings;
+use super::verify::{Reason, Refusal, SigninCookie, SigninRequest, VerifiedClaims, Verifier};
+use crate::auth;
+
+/// The verification the handler needs, so a test can stand in a verifier with fixed keys.
+pub trait TokenVerifier: Send + Sync {
+    /// Decides whether a token may be used at `now` (Unix seconds).
+    fn verify(&self, request: &SigninRequest<'_>, now: i64) -> Result<VerifiedClaims, Refusal>;
+}
+
+impl<K: KeySource + Send + Sync> TokenVerifier for Verifier<K> {
+    fn verify(&self, request: &SigninRequest<'_>, now: i64) -> Result<VerifiedClaims, Refusal> {
+        Verifier::verify(self, request, now)
+    }
+}
+
+/// Where the flow records what happened. Fields never hold a secret.
+pub trait SigninLog: Send + Sync {
+    /// Records one event with its identifying fields.
+    fn record(&self, event: &str, fields: Value);
+}
+
+/// The host's own structured log, one JSON line on stdout.
+pub struct StdoutLog;
+
+impl SigninLog for StdoutLog {
+    fn record(&self, event: &str, fields: Value) {
+        crate::log::info(event, fields);
+    }
+}
+
+/// Makes one fresh nonce or state value each time it is called.
+pub type Random = Box<dyn Fn() -> String + Send + Sync>;
+/// Returns the current time in Unix seconds.
+pub type Clock = Box<dyn Fn() -> i64 + Send + Sync>;
+
+/// Makes a value of 244 random bits as 43 base64url characters.
+pub fn fresh_value() -> String {
+    let mut bytes = Vec::with_capacity(32);
+    bytes.extend_from_slice(uuid::Uuid::new_v4().as_bytes());
+    bytes.extend_from_slice(uuid::Uuid::new_v4().as_bytes());
+    super::jws::encode_base64url(&bytes)
+}
+
+/// Reads the system clock.
+pub fn system_clock() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|elapsed| elapsed.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+/// What a callback request carried, already separated from any headers.
+#[derive(Debug, Clone, Default)]
+pub struct CallbackRequest {
+    /// The raw query string, without the leading `?`.
+    pub raw_query: String,
+    /// Every `name=value` cookie pair the request carried.
+    pub cookie_pairs: Vec<String>,
+}
+
+/// Starts and finishes sign-ins for one site against one issuer.
+pub struct SigninHandler {
+    settings: SigninSettings,
+    verifier: Arc<dyn TokenVerifier>,
+    log: Arc<dyn SigninLog>,
+    random: Random,
+    clock: Clock,
+}
+
+impl SigninHandler {
+    /// Builds a handler that uses fresh randomness and the system clock.
+    pub fn new(
+        settings: SigninSettings,
+        verifier: Arc<dyn TokenVerifier>,
+        log: Arc<dyn SigninLog>,
+    ) -> Self {
+        Self {
+            settings,
+            verifier,
+            log,
+            random: Box::new(fresh_value),
+            clock: Box::new(system_clock),
+        }
+    }
+
+    /// Replaces the source of nonce and state values.
+    pub fn with_random(mut self, random: Random) -> Self {
+        self.random = random;
+        self
+    }
+
+    /// Replaces the clock.
+    pub fn with_clock(mut self, clock: Clock) -> Self {
+        self.clock = clock;
+        self
+    }
+
+    /// Returns the validated settings.
+    pub fn settings(&self) -> &SigninSettings {
+        &self.settings
+    }
+
+    /// Starts a sign-in: a redirect to the issuer and the browser's sign-in cookie.
+    pub fn start(&self) -> Value {
+        let cookie = SigninCookie {
+            nonce: (self.random)(),
+            state: (self.random)(),
+        };
+        let location = self.authorize_url(&cookie);
+        self.log.record("platform_signin_started", json!({}));
+        pages::redirect(&location, &[cookie::set_header(&cookie)])
+    }
+
+    fn authorize_url(&self, cookie: &SigninCookie) -> String {
+        let config = &self.settings.config;
+        format!(
+            "{}/sso/authorize?site={}&env={}&nonce={}&state={}",
+            config.issuer_url,
+            auth::urlencode(&config.site_id),
+            auth::urlencode(&config.environment),
+            auth::urlencode(&cookie.nonce),
+            auth::urlencode(&cookie.state),
+        )
+    }
+
+    /// Finishes a sign-in on the callback. Every outcome deletes the sign-in cookie.
+    pub async fn callback(
+        &self,
+        request: &CallbackRequest,
+        members: &dyn MemberDirectory,
+    ) -> Value {
+        match self.finish(request, members).await {
+            Ok(response) => response,
+            Err(failure) => pages::refusal(failure),
+        }
+    }
+
+    async fn finish(
+        &self,
+        request: &CallbackRequest,
+        members: &dyn MemberDirectory,
+    ) -> Result<Value, Failure> {
+        let cookie = cookie::read(&request.cookie_pairs)
+            .map_err(|fault| self.refused(Failure::Cookie, &format!("{fault:?}")))?;
+        let params = query::parse_callback(&request.raw_query)
+            .map_err(|fault| self.refused(Failure::Params, &format!("{fault:?}")))?;
+        let claims = self.verified(cookie, params).await?;
+        let session = match session::map_member(members, &claims).await {
+            Ok(Some(session)) => session,
+            Ok(None) => {
+                return Err(self.refused_with(Failure::Unlinked, "no_member", Some(&claims.email)))
+            }
+            Err(error) => {
+                return Err(self.refused(Failure::Unavailable, &format!("member_store: {error}")))
+            }
+        };
+        self.log_success(&claims, &session);
+        Ok(session::signed_in(&self.settings, &session))
+    }
+
+    /// Verifies on a blocking thread: the key set fetch waits on the network.
+    async fn verified(
+        &self,
+        cookie: SigninCookie,
+        params: query::CallbackParams,
+    ) -> Result<VerifiedClaims, Failure> {
+        let verifier = self.verifier.clone();
+        let now = (self.clock)();
+        let outcome = tokio::task::spawn_blocking(move || {
+            let request = SigninRequest {
+                token: Some(&params.token),
+                state: Some(&params.state),
+                cookie: Some(&cookie),
+            };
+            verifier.verify(&request, now)
+        })
+        .await
+        .map_err(|_| self.refused(Failure::Unavailable, "verification_did_not_finish"))?;
+        outcome.map_err(|refusal| self.refused(failure_for(refusal.reason), refusal.code()))
+    }
+
+    fn refused(&self, failure: Failure, reason: &str) -> Failure {
+        self.refused_with(failure, reason, None)
+    }
+
+    fn refused_with(&self, failure: Failure, reason: &str, email: Option<&str>) -> Failure {
+        let mut fields = json!({"code": failure.code(), "reason": reason});
+        if let Some(email) = email {
+            fields["who"] = json!(short_hash(email));
+        }
+        self.log.record("platform_signin_refused", fields);
+        failure
+    }
+
+    fn log_success(&self, claims: &VerifiedClaims, session: &auth::Session) {
+        if let Some(drift) = session::role_drift(claims, session) {
+            let fields = json!({"token_role": drift.token_role, "local_role": drift.local_role, "who": short_hash(&claims.email)});
+            self.log.record("platform_signin_role_drift", fields);
+        }
+        self.log.record(
+            "platform_signin_succeeded",
+            json!({"who": short_hash(&claims.email)}),
+        );
+    }
+}
+
+/// The page a verifier refusal earns: the browser's own cookie and state are told apart, the rest
+/// share one answer so the page teaches nothing about which later check failed.
+fn failure_for(reason: Reason) -> Failure {
+    match reason {
+        Reason::MissingCookie => Failure::Cookie,
+        Reason::StateMismatch => Failure::State,
+        _ => Failure::Token,
+    }
+}
+
+/// The first four bytes of the lowercased email's SHA-256, enough to tell people apart in a log.
+fn short_hash(email: &str) -> String {
+    let digest = Sha256::digest(email.to_lowercase().as_bytes());
+    let hex: String = digest.iter().take(4).map(|b| format!("{b:02x}")).collect();
+    format!("h:{hex}")
+}