hecks 3.11.0 → 3.12.0

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

@@ -0,0 +1,233 @@
+//! The callback's query string, read strictly.
+//!
+//! The host's general query parser keeps the last of a repeated key. For a sign-in callback that
+//! would let two parsers disagree about which `token` or `state` counts, so this one keeps every
+//! value and refuses a repeat. Everything except `token` and `state` is ignored: nothing in the
+//! query can steer where the browser goes next.
+
+/// The longest query string read, in bytes. It only bounds the work done on hostile input; the
+/// verifier caps the token itself.
+pub const MAX_QUERY_BYTES: usize = 16 * 1024;
+
+/// The two values a callback carries.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CallbackParams {
+    pub token: String,
+    pub state: String,
+}
+
+/// Why the query could not be used.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ParamFault {
+    /// The query is longer than [`MAX_QUERY_BYTES`].
+    Oversized,
+    /// A percent escape is malformed or the decoded text is not UTF-8.
+    BadEncoding,
+    /// A required parameter was not given.
+    Missing,
+    /// A required parameter was given more than once.
+    Repeated,
+}
+
+/// Reads `token` and `state` from a raw query string.
+///
+/// # Errors
+///
+/// Returns the [`ParamFault`] that says why the pair is not usable.
+pub fn parse_callback(raw_query: &str) -> Result<CallbackParams, ParamFault> {
+    let pairs = decode_pairs(raw_query)?;
+    Ok(CallbackParams {
+        token: single(&pairs, "token")?,
+        state: single(&pairs, "state")?,
+    })
+}
+
+fn single(pairs: &[(String, String)], name: &str) -> Result<String, ParamFault> {
+    let mut found = pairs
+        .iter()
+        .filter(|(key, _)| key == name)
+        .map(|(_, value)| value);
+    let value = found.next().ok_or(ParamFault::Missing)?;
+    if found.next().is_some() {
+        return Err(ParamFault::Repeated);
+    }
+    Ok(value.clone())
+}
+
+fn decode_pairs(raw_query: &str) -> Result<Vec<(String, String)>, ParamFault> {
+    if raw_query.len() > MAX_QUERY_BYTES {
+        return Err(ParamFault::Oversized);
+    }
+    raw_query
+        .split('&')
+        .filter(|pair| !pair.is_empty())
+        .map(|pair| {
+            let (name, value) = pair.split_once('=').unwrap_or((pair, ""));
+            Ok((decode(name)?, decode(value)?))
+        })
+        .collect()
+}
+
+/// Decodes percent escapes; a plus stays a plus, as it does in the host's other query reading.
+fn decode(text: &str) -> Result<String, ParamFault> {
+    let bytes = text.as_bytes();
+    let mut out = Vec::with_capacity(bytes.len());
+    let mut i = 0;
+    while i < bytes.len() {
+        if bytes[i] == b'%' {
+            let pair = bytes.get(i + 1..i + 3).ok_or(ParamFault::BadEncoding)?;
+            out.push(hex_byte(pair).ok_or(ParamFault::BadEncoding)?);
+            i += 3;
+        } else {
+            out.push(bytes[i]);
+            i += 1;
+        }
+    }
+    String::from_utf8(out).map_err(|_| ParamFault::BadEncoding)
+}
+
+fn hex_byte(pair: &[u8]) -> Option<u8> {
+    let digit = |b: u8| (b as char).to_digit(16);
+    Some((digit(pair[0])? * 16 + digit(pair[1])?) as u8)
+}
+
+/// Tells whether the query carries `name` with exactly `value` at least once.
+///
+/// A malformed query carries nothing.
+pub fn has_value(raw_query: &str, name: &str, value: &str) -> bool {
+    decode_pairs(raw_query).is_ok_and(|pairs| pairs.iter().any(|(k, v)| k == name && v == value))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn token_and_state_are_read_and_the_rest_is_ignored() {
+        let params =
+            parse_callback("token=a.b.c&state=S1&return=https%3A%2F%2Fevil.example&next=/x")
+                .unwrap();
+        assert_eq!(
+            params,
+            CallbackParams {
+                token: "a.b.c".into(),
+                state: "S1".into()
+            }
+        );
+    }
+
+    #[test]
+    fn order_and_empty_pairs_do_not_matter() {
+        let params = parse_callback("&state=S1&&token=T&").unwrap();
+        assert_eq!((params.token.as_str(), params.state.as_str()), ("T", "S1"));
+    }
+
+    #[test]
+    fn percent_escapes_decode_and_a_plus_stays_a_plus() {
+        let params = parse_callback("token=a%2Bb+c&state=%53%31").unwrap();
+        assert_eq!(params.token, "a+b+c");
+        assert_eq!(params.state, "S1");
+    }
+
+    #[test]
+    fn a_missing_parameter_is_a_fault_whichever_one() {
+        assert_eq!(parse_callback("state=S1"), Err(ParamFault::Missing));
+        assert_eq!(parse_callback("token=T"), Err(ParamFault::Missing));
+        assert_eq!(parse_callback(""), Err(ParamFault::Missing));
+    }
+
+    #[test]
+    fn an_empty_value_is_present_and_left_to_the_verifier() {
+        let params = parse_callback("token=&state=").unwrap();
+        assert_eq!((params.token.as_str(), params.state.as_str()), ("", ""));
+    }
+
+    #[test]
+    fn a_repeated_parameter_is_refused_even_when_the_values_agree() {
+        assert_eq!(
+            parse_callback("token=T&token=T&state=S"),
+            Err(ParamFault::Repeated)
+        );
+        assert_eq!(
+            parse_callback("token=T&state=S&state=S"),
+            Err(ParamFault::Repeated)
+        );
+        assert_eq!(
+            parse_callback("token=T&state=S&token=U"),
+            Err(ParamFault::Repeated)
+        );
+    }
+
+    #[test]
+    fn array_style_names_are_different_names() {
+        assert_eq!(
+            parse_callback("token[]=T&state=S"),
+            Err(ParamFault::Missing)
+        );
+        let params = parse_callback("token=T&state=S&token[]=U").unwrap();
+        assert_eq!(params.token, "T");
+    }
+
+    #[test]
+    fn a_percent_encoded_name_counts_as_the_name() {
+        assert_eq!(
+            parse_callback("tok%65n=T&token=U&state=S"),
+            Err(ParamFault::Repeated)
+        );
+    }
+
+    #[test]
+    fn an_oversized_query_is_refused_before_it_is_read() {
+        let big = format!("token={}&state=S", "a".repeat(MAX_QUERY_BYTES));
+        assert_eq!(parse_callback(&big), Err(ParamFault::Oversized));
+        let exact = format!(
+            "token={}&state=S",
+            "a".repeat(MAX_QUERY_BYTES - "token=&state=S".len())
+        );
+        assert_eq!(exact.len(), MAX_QUERY_BYTES);
+        assert!(parse_callback(&exact).is_ok());
+    }
+
+    #[test]
+    fn a_bad_percent_escape_or_invalid_utf8_is_a_fault() {
+        for bad in [
+            "token=%&state=S",
+            "token=%G1&state=S",
+            "token=%4&state=S",
+            "token=%ff%fe&state=S",
+            "token=T&state=%c3",
+        ] {
+            assert_eq!(parse_callback(bad), Err(ParamFault::BadEncoding), "{bad}");
+        }
+    }
+
+    #[test]
+    fn a_name_without_an_equals_sign_is_a_name_with_an_empty_value() {
+        assert_eq!(parse_callback("token&state=S").unwrap().token, "");
+    }
+
+    #[test]
+    fn has_value_finds_an_exact_pair_anywhere() {
+        assert!(has_value("via=google", "via", "google"));
+        assert!(has_value("a=1&via=google&b=2", "via", "google"));
+        assert!(has_value("via=x&via=google", "via", "google"));
+        assert!(has_value("v%69a=goo%67le", "via", "google"));
+    }
+
+    #[test]
+    fn has_value_is_exact_and_tolerates_junk() {
+        for query in [
+            "",
+            "via=",
+            "via=Google",
+            "via=google2",
+            "via=googl",
+            "xvia=google",
+            "via",
+            "via=%",
+            "a=via=google",
+        ] {
+            assert!(!has_value(query, "via", "google"), "{query:?}");
+        }
+    }
+}

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

@@ -0,0 +1,151 @@
+//! Turning a verified token into a signed-in member of this site, or a refusal.
+//!
+//! The token proves who the issuer says the person is; it never creates a member. The mapping is
+//! the one the site's Google sign-in already uses:
+//!
+//! 1. the token's `(idp_iss, idp_sub)` resolves to an identity that a member is linked to;
+//! 2. otherwise the person's email is matched to an existing, enabled member who has a role and
+//!    no identity yet, and that member is linked (the one write this flow can cause);
+//! 3. otherwise the sign-in is refused. There is no fallback by email alone: the identity pin is
+//!    what protects against a recycled or reassigned address.
+//!
+//! A member without a role is refused as well. The token's role is compared with the member's
+//! local role and a difference is logged, never written.
+
+use std::path::Path;
+
+use async_trait::async_trait;
+use serde_json::Value;
+use tokio::sync::Mutex;
+use tokio_postgres::Client;
+
+use super::settings::SigninSettings;
+use super::verify::VerifiedClaims;
+use super::{cookie, pages};
+use crate::auth::{self, Session};
+use crate::journal::LineageConfig;
+use crate::lambda_client::LambdaInvoker;
+
+/// Where the account lands after a successful sign-in.
+pub const LANDING_PATH: &str = "/admin.html";
+
+/// What the flow needs to know about this site's members.
+#[async_trait]
+pub trait MemberDirectory: Send + Sync {
+    /// Finds the identity registered for a provider's `(issuer, subject)`.
+    async fn identity_for(&self, issuer: &str, subject: &str) -> anyhow::Result<Option<String>>;
+
+    /// Finds the enabled member linked to an identity.
+    async fn session_for_identity(&self, identity_id: &str) -> anyhow::Result<Option<Session>>;
+
+    /// Links an existing, enabled member with a role and no identity, found by email.
+    async fn provision(
+        &self,
+        email: &str,
+        issuer: &str,
+        subject: &str,
+    ) -> anyhow::Result<Option<Session>>;
+}
+
+/// Maps a verified token to the member it may sign in, or `None` to refuse.
+///
+/// # Errors
+///
+/// Returns the member store's error; the caller treats it as this side's fault, not a refusal.
+pub async fn map_member(
+    directory: &dyn MemberDirectory,
+    claims: &VerifiedClaims,
+) -> anyhow::Result<Option<Session>> {
+    let (Some(issuer), Some(subject)) =
+        (claims.idp_issuer.as_deref(), claims.idp_subject.as_deref())
+    else {
+        return Ok(None);
+    };
+    let by_identity = match directory.identity_for(issuer, subject).await? {
+        Some(identity_id) => directory.session_for_identity(&identity_id).await?,
+        None => None,
+    };
+    let session = match by_identity {
+        Some(session) => Some(session),
+        None => directory.provision(&claims.email, issuer, subject).await?,
+    };
+    Ok(session.filter(has_role))
+}
+
+fn has_role(session: &Session) -> bool {
+    session.role.as_deref().is_some_and(|role| !role.is_empty())
+}
+
+/// A difference between the role the issuer sent and the member's local role.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RoleDrift {
+    pub token_role: Option<String>,
+    pub local_role: Option<String>,
+}
+
+/// Compares the token's role with the member's local one.
+pub fn role_drift(claims: &VerifiedClaims, session: &Session) -> Option<RoleDrift> {
+    let token_role = claims.roles.first().cloned();
+    let local_role = session.role.clone();
+    (token_role != local_role).then_some(RoleDrift {
+        token_role,
+        local_role,
+    })
+}
+
+/// Builds the signed-in response: the account cookie, the cleared sign-in cookie, and a redirect
+/// to the landing page.
+pub fn signed_in(settings: &SigninSettings, session: &Session) -> Value {
+    let token = auth::account_token(
+        &settings.session_secret,
+        &session.email,
+        auth::SESSION_TTL_SECS,
+    );
+    // The site address decides Secure: the redirect URI of a Google client may be absent.
+    let flags = crate::web::account_cookie_flags("", &settings.site_url);
+    let account = format!(
+        "{}={token}{flags}; Max-Age={}",
+        settings.account_cookie,
+        auth::SESSION_TTL_SECS
+    );
+    pages::redirect(LANDING_PATH, &[account, cookie::clear_header()])
+}
+
+/// The host's own member store, reached through the same functions the Google sign-in uses.
+pub struct HostMembers<'a> {
+    pub client: &'a Mutex<Client>,
+    pub domain_ir: &'a Value,
+    pub wasm_path: &'a Path,
+    pub config: &'a LineageConfig,
+    pub invoker: &'a dyn LambdaInvoker,
+}
+
+#[async_trait]
+impl MemberDirectory for HostMembers<'_> {
+    async fn identity_for(&self, issuer: &str, subject: &str) -> anyhow::Result<Option<String>> {
+        auth::resolve_identity_from_head(self.client, self.domain_ir, issuer, subject).await
+    }
+
+    async fn session_for_identity(&self, identity_id: &str) -> anyhow::Result<Option<Session>> {
+        auth::session_for_member_by_identity(self.client, self.domain_ir, identity_id).await
+    }
+
+    async fn provision(
+        &self,
+        email: &str,
+        issuer: &str,
+        subject: &str,
+    ) -> anyhow::Result<Option<Session>> {
+        auth::provision(
+            self.client,
+            self.wasm_path,
+            self.config,
+            self.domain_ir,
+            email,
+            issuer,
+            subject,
+            self.invoker,
+        )
+        .await
+    }
+}