hecks 3.10.0 → 3.12.0

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

@@ -0,0 +1,237 @@
+//! The site's own sign-in cookie, `__Host-signin`, which binds a callback to the browser that
+//! started the flow.
+//!
+//! The value is `<nonce>.<state>`, both base64url, written exactly as the issuer's reference
+//! implementation writes it so the two sides agree. The `__Host-` prefix makes a browser insist on
+//! `Secure`, `Path=/` and no `Domain`, so a sibling subdomain cannot plant a lookalike. `Secure` is
+//! written unconditionally rather than inferred from the request, because the host sits behind
+//! proxies that speak plain http to it. `SameSite=Lax`, not `Strict`: the return from the issuer is
+//! a cross-site top-level navigation, and a strict cookie would not be sent on it.
+//!
+//! Reading is strict in the other direction: a cookie that appears twice is refused, because which
+//! of two values counts is unknowable.
+
+use serde_json::Value;
+
+use super::verify::SigninCookie;
+
+/// The attributes every write of the cookie carries, the same ones that set it and delete it.
+const ATTRIBUTES: &str = "Path=/; Secure; HttpOnly; SameSite=Lax";
+/// The cookie's name.
+pub const NAME: &str = "__Host-signin";
+/// How long the browser keeps the cookie, in seconds.
+pub const MAX_AGE_SECONDS: u32 = 600;
+/// The shortest nonce or state accepted.
+pub const MIN_VALUE_LENGTH: usize = 16;
+/// The longest nonce or state accepted.
+pub const MAX_VALUE_LENGTH: usize = 128;
+
+/// Why the cookie could not be used.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CookieFault {
+    /// The browser sent no such cookie.
+    Absent,
+    /// The browser sent it more than once.
+    Repeated,
+    /// The value is not `<nonce>.<state>` of acceptable shape.
+    Malformed,
+}
+
+/// Returns the `Set-Cookie` value that stores the nonce and state in the browser.
+pub fn set_header(cookie: &SigninCookie) -> String {
+    format!(
+        "{NAME}={}.{}; Max-Age={MAX_AGE_SECONDS}; {ATTRIBUTES}",
+        cookie.nonce, cookie.state
+    )
+}
+
+/// Returns the `Set-Cookie` value that deletes the cookie, with the attributes that set it.
+pub fn clear_header() -> String {
+    format!("{NAME}=; Max-Age=0; {ATTRIBUTES}")
+}
+
+/// Collects every `name=value` pair the request carried, from the event's `cookies` array and its
+/// `cookie` header.
+pub fn request_pairs(event: &Value) -> Vec<String> {
+    let listed = event
+        .get("cookies")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter_map(Value::as_str);
+    let header = event
+        .get("headers")
+        .and_then(|h| h.get("cookie"))
+        .and_then(Value::as_str)
+        .into_iter()
+        .flat_map(|h| h.split(';'));
+    listed
+        .chain(header)
+        .map(|pair| pair.trim().to_string())
+        .filter(|pair| !pair.is_empty())
+        .collect()
+}
+
+/// Finds the sign-in cookie among the request's pairs.
+///
+/// # Errors
+///
+/// Returns the [`CookieFault`] that says why there is no usable cookie.
+pub fn read(pairs: &[String]) -> Result<SigninCookie, CookieFault> {
+    let mut values = pairs
+        .iter()
+        .filter_map(|pair| pair.split_once('='))
+        .filter(|(name, _)| name.trim() == NAME)
+        .map(|(_, value)| value.trim());
+    let value = values.next().ok_or(CookieFault::Absent)?;
+    if values.next().is_some() {
+        return Err(CookieFault::Repeated);
+    }
+    parse_value(value).ok_or(CookieFault::Malformed)
+}
+
+fn parse_value(value: &str) -> Option<SigninCookie> {
+    let (nonce, state) = value.split_once('.')?;
+    let acceptable = |part: &str| {
+        (MIN_VALUE_LENGTH..=MAX_VALUE_LENGTH).contains(&part.len()) && part.bytes().all(is_url_safe)
+    };
+    (acceptable(nonce) && acceptable(state)).then(|| SigninCookie {
+        nonce: nonce.into(),
+        state: state.into(),
+    })
+}
+
+fn is_url_safe(byte: u8) -> bool {
+    byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_'
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    const NONCE: &str = "Nn0nceNn0nceNn0nceAA";
+    const STATE: &str = "StateStateState0123456789";
+
+    fn cookie() -> SigninCookie {
+        SigninCookie {
+            nonce: NONCE.into(),
+            state: STATE.into(),
+        }
+    }
+
+    fn pairs(items: &[&str]) -> Vec<String> {
+        items.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn the_set_header_matches_the_issuers_reference_exactly() {
+        assert_eq!(
+            set_header(&cookie()),
+            format!("__Host-signin={NONCE}.{STATE}; Max-Age=600; Path=/; Secure; HttpOnly; SameSite=Lax")
+        );
+    }
+
+    #[test]
+    fn the_clear_header_keeps_every_attribute_and_zeroes_the_age() {
+        assert_eq!(
+            clear_header(),
+            "__Host-signin=; Max-Age=0; Path=/; Secure; HttpOnly; SameSite=Lax"
+        );
+    }
+
+    #[test]
+    fn neither_header_carries_a_domain_attribute() {
+        assert!(!set_header(&cookie())
+            .to_ascii_lowercase()
+            .contains("domain"));
+        assert!(!clear_header().to_ascii_lowercase().contains("domain"));
+    }
+
+    #[test]
+    fn a_pair_reads_back_into_its_nonce_and_state() {
+        let read = read(&pairs(&[&format!("__Host-signin={NONCE}.{STATE}")])).unwrap();
+        assert_eq!(read, cookie());
+    }
+
+    #[test]
+    fn other_cookies_are_ignored_and_a_lookalike_name_is_not_the_cookie() {
+        let found = read(&pairs(&[
+            "a=b",
+            &format!("__Host-signin={NONCE}.{STATE}"),
+            "c=d",
+        ]))
+        .unwrap();
+        assert_eq!(found, cookie());
+        assert_eq!(
+            read(&pairs(&[
+                &format!("signin={NONCE}.{STATE}"),
+                &format!("x__Host-signin={NONCE}.{STATE}")
+            ])),
+            Err(CookieFault::Absent)
+        );
+    }
+
+    #[test]
+    fn no_cookie_is_absent() {
+        assert_eq!(read(&[]), Err(CookieFault::Absent));
+    }
+
+    #[test]
+    fn a_repeated_cookie_is_refused_even_when_the_values_agree() {
+        let one = format!("__Host-signin={NONCE}.{STATE}");
+        assert_eq!(read(&pairs(&[&one, &one])), Err(CookieFault::Repeated));
+    }
+
+    #[test]
+    fn a_value_of_the_wrong_shape_is_malformed() {
+        for bad in [
+            "",
+            NONCE,
+            &format!("{NONCE}."),
+            &format!(".{STATE}"),
+            &format!("{NONCE}.{STATE}.extra"),
+            &format!("short.{STATE}"),
+            &format!("{NONCE}.short"),
+            &format!("{NONCE}.{}", "s".repeat(129)),
+            &format!("{NONCE}.{STATE}+"),
+            &format!("{NONCE}.{STATE}="),
+            &format!("{NONCE}.sta te0123456789012"),
+        ] {
+            assert_eq!(
+                read(&pairs(&[&format!("__Host-signin={bad}")])),
+                Err(CookieFault::Malformed),
+                "{bad:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn the_longest_acceptable_values_pass() {
+        let long = "a".repeat(128);
+        let found = read(&pairs(&[&format!("__Host-signin={long}.{long}")])).unwrap();
+        assert_eq!(found.nonce.len(), 128);
+    }
+
+    #[test]
+    fn pairs_come_from_the_cookie_header_and_from_the_cookies_array() {
+        let event = json!({"headers": {"cookie": "a=b; __Host-signin=x.y ; c=d"}, "cookies": ["e=f", "g=h"]});
+        let all = request_pairs(&event);
+        for expected in ["a=b", "__Host-signin=x.y", "c=d", "e=f", "g=h"] {
+            assert!(all.iter().any(|p| p == expected), "{expected} in {all:?}");
+        }
+    }
+
+    #[test]
+    fn a_cookie_named_in_both_places_counts_twice() {
+        let one = format!("__Host-signin={NONCE}.{STATE}");
+        let event = json!({"headers": {"cookie": one}, "cookies": [one]});
+        assert_eq!(read(&request_pairs(&event)), Err(CookieFault::Repeated));
+    }
+
+    #[test]
+    fn an_event_without_cookies_yields_no_pairs() {
+        assert!(request_pairs(&json!({})).is_empty());
+        assert!(request_pairs(&json!({"headers": {"cookie": 5}, "cookies": "x"})).is_empty());
+    }
+}

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

@@ -0,0 +1,190 @@
+//! The host extension that puts the sign-in flow on the site's routes.
+//!
+//! It is deliberately small and generically named so it can move to the platform later: it knows
+//! the routes, the mode and nothing about any one site. With `PLATFORM_SIGNIN` unset it is never
+//! installed, so the host answers exactly as before.
+//!
+//! ## One installed instance per process
+//!
+//! The single-use record of token identifiers lives in the verifier this extension owns, and the
+//! host installs one extension for the life of the process, so the record is process-wide. It does
+//! not survive a restart (the replay window that opens is at most the token lifetime plus the
+//! skew, 90 seconds) and it is not shared between instances, which is why the settings refuse any
+//! process that is not the single long-lived server.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use serde_json::Value;
+
+use super::fetcher::HttpJwksFetcher;
+use super::handler::{CallbackRequest, SigninHandler, StdoutLog};
+use super::jti::JtiStore;
+use super::jwks::JwksCache;
+use super::pages::{self, Failure};
+use super::session::{HostMembers, MemberDirectory};
+use super::settings::{Mode, SettingsError, SigninSettings};
+use super::verify::Verifier;
+use super::{cookie, query};
+use crate::extension::{Ctx, HostExtension, RateRule};
+
+/// Starts the flow in either mode.
+pub const START_PATH: &str = "/auth/platform";
+/// Finishes the flow in either mode.
+pub const CALLBACK_PATH: &str = "/auth/platform/callback";
+/// The site's Google sign-in path, which `default` mode takes over.
+pub const GOOGLE_PATH: &str = "/auth/google";
+
+/// Which half of the flow a request is for.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Route {
+    Start,
+    Callback,
+}
+
+/// The platform sign-in extension.
+pub struct PlatformSignin {
+    handler: SigninHandler,
+}
+
+impl PlatformSignin {
+    /// Wraps a handler that is already built.
+    pub fn new(handler: SigninHandler) -> Self {
+        Self { handler }
+    }
+
+    /// Builds the extension from an explicit map, or `None` when `PLATFORM_SIGNIN` is unset.
+    ///
+    /// # Errors
+    ///
+    /// Returns the setting that is missing or malformed once the switch is on.
+    pub fn from_env_map(vars: &HashMap<String, String>) -> Result<Option<Self>, SettingsError> {
+        let Some(settings) = SigninSettings::from_env_map(vars)? else {
+            return Ok(None);
+        };
+        let keys = JwksCache::new(HttpJwksFetcher::new(&settings.config.jwks_url));
+        let verifier = Verifier::new(settings.config.clone(), keys, JtiStore::new());
+        Ok(Some(Self::new(SigninHandler::new(
+            settings,
+            Arc::new(verifier),
+            Arc::new(StdoutLog),
+        ))))
+    }
+
+    /// Decides which half of the flow, if either, a request is for.
+    pub fn classify(&self, event: &Value) -> Option<Route> {
+        let method = event
+            .pointer("/requestContext/http/method")
+            .and_then(Value::as_str)?;
+        let path = event.get("rawPath").and_then(Value::as_str)?;
+        if method != "GET" {
+            return None;
+        }
+        match path {
+            START_PATH => Some(Route::Start),
+            CALLBACK_PATH => Some(Route::Callback),
+            GOOGLE_PATH if self.takes_over_google(raw_query(event)) => Some(Route::Start),
+            _ => None,
+        }
+    }
+
+    fn takes_over_google(&self, raw_query: &str) -> bool {
+        self.handler.settings().mode == Mode::Default
+            && !query::has_value(raw_query, "via", "google")
+    }
+
+    /// Finishes a sign-in for a callback request against a member store.
+    pub async fn finish(&self, request: &CallbackRequest, members: &dyn MemberDirectory) -> Value {
+        self.handler.callback(request, members).await
+    }
+
+    /// Answers a request that belongs to the flow, or `None` for everything else.
+    pub async fn route_event(&self, event: &Value, members: &dyn MemberDirectory) -> Option<Value> {
+        match self.classify(event)? {
+            Route::Start => Some(self.handler.start()),
+            Route::Callback => Some(self.finish(&callback_request(event), members).await),
+        }
+    }
+}
+
+fn raw_query(event: &Value) -> &str {
+    event
+        .get("rawQueryString")
+        .and_then(Value::as_str)
+        .unwrap_or("")
+}
+
+fn callback_request(event: &Value) -> CallbackRequest {
+    CallbackRequest {
+        raw_query: raw_query(event).to_string(),
+        cookie_pairs: cookie::request_pairs(event),
+    }
+}
+
+#[async_trait]
+impl HostExtension for PlatformSignin {
+    async fn guest_route(&self, ctx: &Ctx<'_>) -> Option<Value> {
+        let event = ctx.event?;
+        match self.classify(event)? {
+            Route::Start => Some(self.handler.start()),
+            Route::Callback => Some(self.finish_for_host(ctx, event).await),
+        }
+    }
+
+    fn rate_rules(&self) -> Vec<RateRule> {
+        vec![
+            RateRule {
+                name: "platform_signin_start",
+                method: "GET",
+                path: START_PATH,
+                limit_env: "HECKS_RATE_LIMIT_PLATFORM_SIGNIN_START",
+                default_limit: 30,
+            },
+            RateRule {
+                name: "platform_signin_callback",
+                method: "GET",
+                path: CALLBACK_PATH,
+                limit_env: "HECKS_RATE_LIMIT_PLATFORM_SIGNIN_CALLBACK",
+                default_limit: 30,
+            },
+        ]
+    }
+}
+
+impl PlatformSignin {
+    /// Finishes a callback against the host's own member store.
+    async fn finish_for_host(&self, ctx: &Ctx<'_>, event: &Value) -> Value {
+        let Some(domain_ir) = ctx.domain_ir else {
+            return pages::refusal(Failure::Unavailable);
+        };
+        let members = HostMembers {
+            client: ctx.client,
+            domain_ir,
+            wasm_path: ctx.wasm_path,
+            config: ctx.config,
+            invoker: ctx.invoker,
+        };
+        self.finish(&callback_request(event), &members).await
+    }
+}
+
+/// Refuses the boot because the sign-in settings were switched on and are wrong.
+pub struct RefusedSettings(pub SettingsError);
+
+#[async_trait]
+impl HostExtension for RefusedSettings {
+    fn boot_check(&self, _domain: &str) -> Result<(), String> {
+        Err(format!("platform sign-in: {}", self.0))
+    }
+}
+
+/// The extensions that platform sign-in contributes for these settings: none when it is off, the
+/// flow when it is on, and a boot refusal when the settings are wrong.
+pub fn extensions_for(vars: &HashMap<String, String>) -> Vec<Arc<dyn HostExtension>> {
+    match PlatformSignin::from_env_map(vars) {
+        Ok(None) => Vec::new(),
+        Ok(Some(extension)) => vec![Arc::new(extension)],
+        Err(error) => vec![Arc::new(RefusedSettings(error))],
+    }
+}