dioxus_cloudflare/

cookie.rs

//! Cookie helpers for authentication flows.
//!
//! ## Outgoing cookies
//!
//! [`set_cookie`] and [`set_cookie_with`] queue `Set-Cookie` headers with secure
//! defaults (`HttpOnly`, `Secure`, `SameSite=Strict`, `Path=/`).
//! [`clear_cookie`] queues a `Max-Age=0` header to delete a cookie.
//!
//! Cookies are queued in thread-local storage and applied to the outgoing
//! `worker::Response` by [`crate::handle`] — no `&mut Response` needed.
//!
//! ## Incoming cookies
//!
//! [`cookie`] reads a named cookie from the request `Cookie` header.
//! [`cookies`] parses all cookies into `(name, value)` pairs.

use std::fmt;

use crate::context::push_cookie;
use crate::error::CfError;

// ---------------------------------------------------------------------------
// Reading cookies from the incoming request
// ---------------------------------------------------------------------------

/// Read a named cookie from the incoming request's `Cookie` header.
///
/// Returns `Ok(None)` if the cookie is not present.
///
/// # Errors
///
/// Returns [`CfError`] if the `Cookie` header cannot be read.
///
/// # Example
///
/// ```rust,ignore
/// use dioxus_cloudflare::prelude::*;
///
/// #[server]
/// pub async fn who_am_i() -> Result<String, ServerFnError> {
///     let session = cf::cookie("session")?.unwrap_or_default();
///     Ok(session)
/// }
/// ```
pub fn cookie(name: &str) -> Result<Option<String>, CfError> {
    let header = crate::context::req()
        .headers()
        .get("Cookie")
        .map_err(CfError)?
        .unwrap_or_default();

    Ok(parse_cookie_value(&header, name))
}

/// Read all cookies from the incoming request's `Cookie` header.
///
/// Returns an empty `Vec` if no `Cookie` header is present.
///
/// # Errors
///
/// Returns [`CfError`] if the `Cookie` header cannot be read.
///
/// # Example
///
/// ```rust,ignore
/// use dioxus_cloudflare::prelude::*;
///
/// #[server]
/// pub async fn list_cookies() -> Result<Vec<(String, String)>, ServerFnError> {
///     let all = cf::cookies()?;
///     Ok(all)
/// }
/// ```
pub fn cookies() -> Result<Vec<(String, String)>, CfError> {
    let header = crate::context::req()
        .headers()
        .get("Cookie")
        .map_err(CfError)?
        .unwrap_or_default();

    Ok(parse_all_cookies(&header))
}

/// Parse a single cookie value by name from a `Cookie` header string.
fn parse_cookie_value(header: &str, name: &str) -> Option<String> {
    header.split(';').find_map(|pair| {
        let mut parts = pair.splitn(2, '=');
        let key = parts.next()?.trim();
        let val = parts.next()?.trim();
        if key == name { Some(val.to_owned()) } else { None }
    })
}

/// Parse all `name=value` pairs from a `Cookie` header string.
fn parse_all_cookies(header: &str) -> Vec<(String, String)> {
    if header.is_empty() {
        return Vec::new();
    }
    header
        .split(';')
        .filter_map(|pair| {
            let mut parts = pair.splitn(2, '=');
            let key = parts.next()?.trim();
            let val = parts.next()?.trim();
            if key.is_empty() {
                None
            } else {
                Some((key.to_owned(), val.to_owned()))
            }
        })
        .collect()
}

// ---------------------------------------------------------------------------
// Writing cookies to the outgoing response
// ---------------------------------------------------------------------------

/// Queue an `HttpOnly` auth cookie on the outgoing response.
///
/// The cookie is configured with:
/// - `HttpOnly` — not accessible via JavaScript (prevents XSS token theft)
/// - `Secure` — only sent over HTTPS
/// - `SameSite=Strict` — not sent on cross-origin requests (prevents CSRF)
/// - `Path=/` — available on all routes
///
/// For custom cookie options, use [`set_cookie_with`] instead.
///
/// # Example
///
/// ```rust,ignore
/// use dioxus_cloudflare::cf;
///
/// #[server]
/// pub async fn login(token: String) -> Result<(), ServerFnError> {
///     cf::set_cookie("session", &token, 60 * 60 * 24 * 7);
///     Ok(())
/// }
/// ```
pub fn set_cookie(name: &str, value: &str, max_age_secs: u64) {
    push_cookie(format!(
        "{name}={value}; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age={max_age_secs}"
    ));
}

/// Queue a cookie-clearing header on the outgoing response (`Max-Age=0`).
///
/// Used for logout flows. The browser will delete the cookie on the next
/// response.
///
/// # Example
///
/// ```rust,ignore
/// use dioxus_cloudflare::cf;
///
/// #[server]
/// pub async fn logout() -> Result<(), ServerFnError> {
///     cf::clear_cookie("session");
///     Ok(())
/// }
/// ```
pub fn clear_cookie(name: &str) {
    push_cookie(format!(
        "{name}=; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=0"
    ));
}

/// Start building a cookie with custom options.
///
/// Returns a [`CookieBuilder`] with secure defaults (same as [`set_cookie`]).
/// Override individual options with builder methods, then call [`.send()`](CookieBuilder::send)
/// to queue the cookie.
///
/// # Example
///
/// ```rust,ignore
/// use dioxus_cloudflare::prelude::*;
///
/// #[server]
/// pub async fn set_theme(theme: String) -> Result<(), ServerFnError> {
///     cf::set_cookie_with("theme", &theme)
///         .http_only(false)
///         .same_site(SameSite::Lax)
///         .max_age(86400 * 30)
///         .send();
///     Ok(())
/// }
/// ```
pub fn set_cookie_with(name: &str, value: &str) -> CookieBuilder {
    CookieBuilder {
        name: name.to_owned(),
        value: value.to_owned(),
        http_only: true,
        secure: true,
        same_site: SameSite::Strict,
        path: "/".to_owned(),
        max_age: None,
        domain: None,
    }
}

/// `SameSite` attribute for cookies.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SameSite {
    /// Cookie is only sent in first-party context. Strongest CSRF protection.
    Strict,
    /// Cookie is sent on top-level navigations from external sites.
    /// Good default for most use cases.
    Lax,
    /// Cookie is sent on all cross-site requests. Requires `Secure`.
    None,
}

impl fmt::Display for SameSite {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Strict => write!(f, "Strict"),
            Self::Lax => write!(f, "Lax"),
            Self::None => write!(f, "None"),
        }
    }
}

/// Builder for cookies with custom options.
///
/// Created by [`set_cookie_with`]. Defaults match [`set_cookie`]:
/// `HttpOnly`, `Secure`, `SameSite=Strict`, `Path=/`.
///
/// Call [`.send()`](Self::send) to queue the cookie on the outgoing response.
#[must_use = "cookie builder does nothing until .send() is called"]
pub struct CookieBuilder {
    name: String,
    value: String,
    http_only: bool,
    secure: bool,
    same_site: SameSite,
    path: String,
    max_age: Option<u64>,
    domain: Option<String>,
}

impl CookieBuilder {
    /// Set the `HttpOnly` flag. Default: `true`.
    ///
    /// Set to `false` for cookies that JavaScript needs to read (e.g., theme
    /// preferences). Never disable for auth tokens.
    pub fn http_only(mut self, yes: bool) -> Self {
        self.http_only = yes;
        self
    }

    /// Set the `Secure` flag. Default: `true`.
    ///
    /// Set to `false` only for local development over HTTP.
    pub fn secure(mut self, yes: bool) -> Self {
        self.secure = yes;
        self
    }

    /// Set the `SameSite` attribute. Default: [`SameSite::Strict`].
    pub fn same_site(mut self, same_site: SameSite) -> Self {
        self.same_site = same_site;
        self
    }

    /// Set the cookie `Path`. Default: `"/"`.
    pub fn path(mut self, path: &str) -> Self {
        self.path = path.to_owned();
        self
    }

    /// Set `Max-Age` in seconds. If not set, the cookie is a session cookie
    /// (deleted when the browser closes).
    pub fn max_age(mut self, secs: u64) -> Self {
        self.max_age = Some(secs);
        self
    }

    /// Set the `Domain` attribute. If not set, the cookie defaults to the
    /// origin domain (no subdomain sharing).
    pub fn domain(mut self, domain: &str) -> Self {
        self.domain = Some(domain.to_owned());
        self
    }

    /// Queue the cookie on the outgoing response.
    pub fn send(self) {
        let mut header = format!(
            "{}={}; SameSite={}; Path={}",
            self.name, self.value, self.same_site, self.path
        );
        if self.http_only {
            header.push_str("; HttpOnly");
        }
        if self.secure {
            header.push_str("; Secure");
        }
        if let Some(max_age) = self.max_age {
            header.push_str(&format!("; Max-Age={max_age}"));
        }
        if let Some(ref domain) = self.domain {
            header.push_str(&format!("; Domain={domain}"));
        }
        push_cookie(header);
    }
}