actix_csrf_middleware/

lib.rs

use actix_http::{header::HeaderMap, StatusCode};
#[cfg(feature = "actix-session")]
use actix_session::SessionExt;
use actix_utils::future::Either;
use actix_web::{
    body::{EitherBody, MessageBody},
    cookie::{time, Cookie, SameSite},
    dev::forward_ready,
    dev::{Service, ServiceRequest, ServiceResponse, Transform},
    http::{header, Method},
    web::BytesMut,
    Error, FromRequest, HttpMessage, HttpRequest, HttpResponse, HttpResponseBuilder,
};
use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
use futures_util::{
    future::{err, ok, Ready},
    ready,
    stream::StreamExt,
};
use hmac::{Hmac, Mac};
use log::{error, warn};
use pin_project_lite::pin_project;
use rand::RngCore;
use sha2::Sha256;
use std::{
    collections::HashMap,
    future::Future,
    marker::PhantomData,
    pin::Pin,
    rc::Rc,
    task::{Context, Poll},
};
use subtle::ConstantTimeEq;
use url::Url;

// Strict security defaults for pre-session cookie
const PRE_SESSION_HTTP_ONLY: bool = true;
const PRE_SESSION_SECURE: bool = true;
const PRE_SESSION_SAME_SITE: SameSite = SameSite::Strict;

/// Cookie name or actix-session key used to store the authorized (session-bound) token
pub const DEFAULT_CSRF_TOKEN_KEY: &str = "CSRF";

/// Cookie name used to store the anonymous (pre-session) token
pub const DEFAULT_CSRF_ANON_TOKEN_KEY: &str = "CSRF-ANON";

/// Csrf token field name in `application/x-www-form-urlencoded` or `application/json` body.
/// `CsrfMiddleware` will try to extract a token from that field.
pub const DEFAULT_CSRF_TOKEN_FIELD: &str = "csrf_token";
pub const DEFAULT_CSRF_TOKEN_HEADER: &str = "X-CSRF-Token";

/// Key of user session created outside the middleware. It's cookie name or actix-session key
/// depending on enabled `session` feature and middleware core will extract value by this key
/// to use this unique session id in HMAC hashes. That's how `CsrfMiddleware` can be integrated
/// into existing applications that already have authorization logic.
pub const DEFAULT_SESSION_ID_KEY: &str = "id";

/// Cookie name of pre-session generated by `CsrfMiddleware` for allowed unauthorized routes
/// that need to mutate data when there's not authorized user yet. For example
/// in cases such as registration, login or newsletter subscription.
pub const CSRF_PRE_SESSION_KEY: &str = "pre-session";

/// Standard 256-bit encryption
const TOKEN_LEN: usize = 32; // 32 bytes -> 256 bits

type HmacSha256 = Hmac<Sha256>;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Classification of CSRF tokens by context.
///
/// - [`TokenClass::Anonymous`]: Token associated with a pre-session (not yet authenticated).
/// - [`TokenClass::Authorized`]: Token bound to an authenticated session.
///
/// This distinction helps prevent accidental mixing of tokens. For example, an
/// anonymous token must not be accepted on endpoints that require an authenticated
/// session.
///
/// # Examples
/// Choosing the correct class when generating HMAC tokens:
/// ```
/// use actix_csrf_middleware::{generate_hmac_token_ctx, validate_hmac_token_ctx, TokenClass};
///
/// let secret = b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
/// let session_id = "SID-42";
/// let t = generate_hmac_token_ctx(TokenClass::Authorized, session_id, secret);
///
/// assert!(validate_hmac_token_ctx(TokenClass::Authorized, session_id, t.as_bytes(), secret).unwrap());
/// ```
pub enum TokenClass {
    /// Token used before authentication.
    Anonymous,
    /// Token used after authentication; tied to a session id.
    Authorized,
}

impl TokenClass {
    fn as_str(&self) -> &'static str {
        match self {
            TokenClass::Anonymous => "anon",
            TokenClass::Authorized => "auth",
        }
    }
}

/// CSRF defense patterns supported by [`CsrfMiddleware`].
///
/// - [`CsrfPattern::DoubleSubmitCookie`]: Stores an HMAC-protected token in a cookie and
///   expects the client to echo it back via header or form/json field. Does not require
///   server-side session storage.
/// - [`CsrfPattern::SynchronizerToken`]: Stores a random token server-side in a session
///   (requires `actix-session`) and expects the client to send back the same value.
///
/// See [`CsrfMiddlewareConfig`] constructors for examples.
#[derive(Clone, PartialEq)]
pub enum CsrfPattern {
    /// Store tokens server-side in session storage (requires `actix-session`)
    #[cfg(feature = "actix-session")]
    SynchronizerToken,
    /// Store tokens client-side in cookies and verify with HMAC
    DoubleSubmitCookie,
}

#[derive(Clone)]
/// Cookie flags for tokens when using the Double-Submit Cookie pattern.
///
/// - `http_only`: Must be `false` so client code can read the token and mirror it into a
///   header or form field.
/// - `secure`: Should be `true` in production to restrict cookies to HTTPS.
/// - `same_site`: Choose `Strict` or `Lax` depending on your cross-site needs.
///
/// # Examples
/// ```
/// use actix_csrf_middleware::{CsrfMiddlewareConfig, CsrfDoubleSubmitCookie};
/// use actix_web::cookie::SameSite;
///
/// let secret = b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
/// let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret)
///     .with_token_cookie_config(CsrfDoubleSubmitCookie {
///         http_only: false,
///         secure: true,
///         same_site: SameSite::Strict,
///     });
/// ```
pub struct CsrfDoubleSubmitCookie {
    /// If true, JavaScript cannot read the cookie
    pub http_only: bool,
    /// Restrict cookies to HTTPS in production
    pub secure: bool,
    /// SameSite policy controlling cross-site cookie sending
    pub same_site: SameSite,
}

#[derive(Clone)]
/// Configuration for [`CsrfMiddleware`].
///
/// Choose a CSRF defense pattern and adjust behavior such as token locations, cookie
/// names, content-type handling, and origin checks.
///
/// - For the Double-Submit Cookie pattern, use [`CsrfMiddlewareConfig::double_submit_cookie`].
/// - For the Synchronizer Token pattern (requires the `actix-session` feature), use
///   [`CsrfMiddlewareConfig::synchronizer_token`].
///
/// # Defaults
/// - Token header: [`DEFAULT_CSRF_TOKEN_HEADER`]
/// - Token form/json field: [`DEFAULT_CSRF_TOKEN_FIELD`]
/// - Session id cookie name: [`DEFAULT_SESSION_ID_KEY`]
/// - Max body bytes to scan for token: 2 MiB
///
/// # Security
/// - When using Double-Submit Cookie, ensure the token cookie is readable by the client
///   (i.e., `http_only` must be `false`) so it can be mirrored into the header.
/// - Consider enabling strict Origin/Referer enforcement with
///   [`with_enforce_origin`](Self::with_enforce_origin) to mitigate CSRF even if a token
///   leaks.
/// - Avoid allowing `multipart/form-data` unless you can handle token extraction manually.
///
/// # Examples
/// Basic Double-Submit Cookie configuration:
/// ```
/// use actix_csrf_middleware::{CsrfMiddlewareConfig, CsrfDoubleSubmitCookie};
/// use actix_web::cookie::SameSite;
///
/// let secret = b"at-least-32-bytes-of-secret-key-material...";
/// let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret)
///     .with_enforce_origin(true, vec!["https://example.com".to_string()])
///     .with_token_cookie_config(CsrfDoubleSubmitCookie {
///         http_only: false, // must be false for Double-Submit
///         secure: true,
///         same_site: SameSite::Lax,
///     });
/// ```
pub struct CsrfMiddlewareConfig {
    pub pattern: CsrfPattern,
    pub manual_multipart: bool,
    pub session_id_cookie_name: String,
    /// Authorized (session-bound) tokens
    pub token_cookie_name: String,
    /// Anonymous (pre-session) tokens
    pub anon_token_cookie_name: String,
    #[cfg(feature = "actix-session")]
    /// Anonymous (pre-session) token key for SynchronizerToken    
    pub anon_session_key_name: String,
    pub token_form_field: String,
    pub token_header_name: String,
    pub token_cookie_config: Option<CsrfDoubleSubmitCookie>,
    pub secret_key: zeroize::Zeroizing<Vec<u8>>,
    pub skip_for: Vec<String>,
    /// Enforce Origin/Referer checks for mutating requests
    pub enforce_origin: bool,
    /// Allowed origins (scheme://host[:port]) when enforce_origin = true
    pub allowed_origins: Vec<String>,
    /// Maximum allowed body bytes to read when extracting
    /// CSRF tokens from body (POST/PUT/PATCH/DELETE)
    pub max_body_bytes: usize,
}

impl CsrfMiddlewareConfig {
    #[cfg(feature = "actix-session")]
    /// Constructs a configuration for the Synchronizer Token pattern.
    ///
    /// Tokens are stored server-side in the session via `actix-session` and compared against
    /// the value presented by the client.
    ///
    /// # Examples
    /// Using cookie-based sessions (requires enabling the `actix-session` feature for this crate):
    /// ```ignore
    /// use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig};
    /// use actix_session::{SessionMiddleware, storage::CookieSessionStore};
    /// use actix_web::{App, cookie::Key};
    ///
    /// let secret = b"a-very-long-application-secret-key-of-32+bytes";
    /// let cfg = CsrfMiddlewareConfig::synchronizer_token(secret);
    /// let app = App::new()
    ///     .wrap(SessionMiddleware::new(CookieSessionStore::default(), Key::generate()))
    ///     .wrap(CsrfMiddleware::new(cfg));
    /// ```
    pub fn synchronizer_token(secret_key: &[u8]) -> Self {
        check_secret_key(secret_key);

        CsrfMiddlewareConfig {
            pattern: CsrfPattern::SynchronizerToken,
            session_id_cookie_name: DEFAULT_SESSION_ID_KEY.to_string(),
            token_cookie_name: DEFAULT_CSRF_TOKEN_KEY.into(),
            anon_token_cookie_name: DEFAULT_CSRF_ANON_TOKEN_KEY.into(),
            #[cfg(feature = "actix-session")]
            anon_session_key_name: format!("{}-anon", DEFAULT_CSRF_TOKEN_KEY),
            token_form_field: DEFAULT_CSRF_TOKEN_FIELD.into(),
            token_header_name: DEFAULT_CSRF_TOKEN_HEADER.into(),
            token_cookie_config: None,
            secret_key: zeroize::Zeroizing::new(secret_key.into()),
            skip_for: vec![],
            manual_multipart: false,
            enforce_origin: false,
            allowed_origins: vec![],
            max_body_bytes: 2 * 1024 * 1024, // 2 MiB default
        }
    }

    /// Constructs a configuration for the Double-Submit Cookie pattern.
    ///
    /// The CSRF token is placed in a cookie and echoed by clients in a header or form field.
    /// The token’s integrity is protected by an HMAC bound to the session id and the token.
    ///
    /// # Examples
    /// ```
    /// use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig};
    /// use actix_web::{App};
    ///
    /// let secret = b"a-very-long-application-secret-key-of-32+bytes";
    /// let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret);
    /// let app = App::new().wrap(CsrfMiddleware::new(cfg));
    /// ```
    pub fn double_submit_cookie(secret_key: &[u8]) -> Self {
        check_secret_key(secret_key);

        CsrfMiddlewareConfig {
            pattern: CsrfPattern::DoubleSubmitCookie,
            session_id_cookie_name: DEFAULT_SESSION_ID_KEY.to_string(),
            token_cookie_name: DEFAULT_CSRF_TOKEN_KEY.into(),
            anon_token_cookie_name: DEFAULT_CSRF_ANON_TOKEN_KEY.into(),
            #[cfg(feature = "actix-session")]
            anon_session_key_name: format!("{}-anon", DEFAULT_CSRF_TOKEN_KEY),
            token_form_field: DEFAULT_CSRF_TOKEN_FIELD.into(),
            token_header_name: DEFAULT_CSRF_TOKEN_HEADER.into(),
            token_cookie_config: Some(CsrfDoubleSubmitCookie {
                http_only: false, // Should be false for double-submit cookie
                secure: true,
                same_site: SameSite::Strict,
            }),
            secret_key: zeroize::Zeroizing::new(secret_key.into()),
            skip_for: vec![],
            manual_multipart: false,
            enforce_origin: false,
            allowed_origins: vec![],
            max_body_bytes: 2 * 1024 * 1024,
        }
    }

    /// Controls whether `multipart/form-data` requests are allowed to pass through.
    ///
    /// When set to `true`, the middleware does not attempt to extract the CSRF token from a
    /// multipart body. Your handler must read and validate the token manually.
    ///
    /// Defaults to `false` for safety.
    pub fn with_multipart(mut self, multipart: bool) -> Self {
        self.manual_multipart = multipart;
        self
    }

    /// Sets the maximum number of request body bytes read when searching for a CSRF token
    /// in JSON or `application/x-www-form-urlencoded` bodies.
    ///
    /// Defaults to 2 MiB.
    pub fn with_max_body_bytes(mut self, limit: usize) -> Self {
        self.max_body_bytes = limit;
        self
    }

    /// Overrides cookie flags for token cookies (Double-Submit Cookie pattern).
    ///
    /// For Double-Submit Cookie, `http_only` must be `false` so client-side code can read
    /// the cookie value and mirror it into a header or form field.
    pub fn with_token_cookie_config(mut self, config: CsrfDoubleSubmitCookie) -> Self {
        self.token_cookie_config = Some(config);
        self
    }

    /// Skips CSRF validation for requests whose path starts with any of the given prefixes.
    ///
    /// Useful for health checks or public webhooks where CSRF is not applicable.
    pub fn with_skip_for(mut self, patches: Vec<String>) -> Self {
        self.skip_for = patches;
        self
    }

    /// Enables strict Origin/Referer checks for mutating requests and sets the allowed origins.
    ///
    /// Origins are compared strictly by scheme, host, and port. If `allowed` is empty and
    /// `enforce` is `true`, all mutating requests are rejected.
    ///
    /// Example enabling enforcement for a single origin:
    /// ```
    /// use actix_csrf_middleware::CsrfMiddlewareConfig;
    ///
    /// let cfg = CsrfMiddlewareConfig::double_submit_cookie(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    ///     .with_enforce_origin(true, vec!["https://example.com".to_string()]);
    /// ```
    pub fn with_enforce_origin(mut self, enforce: bool, allowed: Vec<String>) -> Self {
        self.enforce_origin = enforce;
        self.allowed_origins = allowed;
        self
    }
}

/// Actix Web middleware providing CSRF protection.
///
/// Supports two patterns:
/// - Double-Submit Cookie (default): a token is stored in a cookie and echoed by the client.
/// - Synchronizer Token (with `actix-session`): a token is stored server-side in the session.
///
/// # How It Works
/// - For safe methods (GET/HEAD), the middleware ensures a token exists and may set it in
///   cookies. For the Double-Submit Cookie pattern, an anonymous pre-session cookie may be
///   issued before the user is authenticated.
/// - For mutating methods (POST/PUT/PATCH/DELETE), a token is required. The middleware
///   accepts tokens from the header [`DEFAULT_CSRF_TOKEN_HEADER`] or the body field
///   [`DEFAULT_CSRF_TOKEN_FIELD`] for JSON or url-encoded bodies. `multipart/form-data`
///   is rejected unless [`CsrfMiddlewareConfig::with_multipart`] is enabled.
/// - On successful validation, the token is rotated.
/// - Optional strict Origin/Referer checks can be enabled via
///   [`CsrfMiddlewareConfig::with_enforce_origin`].
///
/// # Examples
/// Double-Submit Cookie (no session middleware required):
/// ```
/// use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig, CsrfToken};
/// use actix_web::{web, App, HttpResponse};
///
/// let secret = b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; // >= 32 bytes
/// let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret);
///
/// let app = App::new()
///     .wrap(CsrfMiddleware::new(cfg))
///     .service(
///         web::resource("/form").route(web::get().to(|csrf: CsrfToken| async move {
///             Ok::<_, actix_web::Error>(HttpResponse::Ok().body(format!("token:{}", csrf.0)))
///         }))
///     )
///     .service(
///         web::resource("/submit").route(web::post().to(|_csrf: CsrfToken| async move {
///             Ok::<_, actix_web::Error>(HttpResponse::Ok())
///         }))
///     );
/// ```
///
/// Synchronizer Token (requires `actix-session`) example:
/// ```ignore
/// use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig};
/// use actix_session::{storage::CookieSessionStore, SessionMiddleware};
/// use actix_web::{App, cookie::Key};
///
/// let cfg = CsrfMiddlewareConfig::synchronizer_token(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
/// let app = App::new()
///     .wrap(SessionMiddleware::new(CookieSessionStore::default(), Key::generate()))
///     .wrap(CsrfMiddleware::new(cfg));
/// ```
pub struct CsrfMiddleware {
    config: Rc<CsrfMiddlewareConfig>,
}

impl CsrfMiddleware {
    /// Creates a CSRF middleware instance with the given configuration.
    ///
    /// See [`CsrfMiddlewareConfig`] for available options and examples.
    pub fn new(config: CsrfMiddlewareConfig) -> Self {
        Self {
            config: Rc::new(config),
        }
    }
}

impl<S, B> Transform<S, ServiceRequest> for CsrfMiddleware
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    B: MessageBody,
{
    type Response = ServiceResponse<EitherBody<B>>;
    type Error = Error;
    type Transform = CsrfMiddlewareService<S>;
    type InitError = ();
    type Future = Ready<Result<Self::Transform, Self::InitError>>;

    fn new_transform(&self, service: S) -> Self::Future {
        ok(CsrfMiddlewareService {
            service: Rc::new(service),
            config: self.config.clone(),
        })
    }
}

pub struct CsrfMiddlewareService<S> {
    service: Rc<S>,
    config: Rc<CsrfMiddlewareConfig>,
}

impl<S> CsrfMiddlewareService<S> {
    fn get_session_from_cookie(&self, req: &ServiceRequest) -> (String, bool, TokenClass) {
        // Try to extract from session id cookie first,
        // if nothing found then check pre-session or create new one.
        if let Some(id) = req
            .cookie(&self.config.session_id_cookie_name)
            .map(|c| c.value().to_string())
        {
            (id, false, TokenClass::Authorized)
        } else if let Some(val) = req
            .cookie(CSRF_PRE_SESSION_KEY)
            .map(|c| c.value().to_string())
        {
            // Validate signed/encrypted pre-session value; if invalid, rotate
            if let Some(pre_id) = decode_pre_session_cookie(&val, self.config.secret_key.as_slice())
            {
                (pre_id, false, TokenClass::Anonymous)
            } else {
                (generate_random_token(), true, TokenClass::Anonymous)
            }
        } else {
            // Generate pre-session id here
            (generate_random_token(), true, TokenClass::Anonymous)
        }
    }

    fn get_true_token(
        &self,
        req: &ServiceRequest,
        session_id: Option<&str>,
        class: TokenClass,
    ) -> (String, bool) {
        match self.config.pattern {
            // If corresponding feature enabled then get token from persistent session storage
            #[cfg(feature = "actix-session")]
            CsrfPattern::SynchronizerToken => {
                let session = req.get_session();
                let key = match class {
                    TokenClass::Authorized => &self.config.token_cookie_name,
                    TokenClass::Anonymous => &self.config.anon_session_key_name,
                };

                let found = session.get::<String>(key).ok().flatten();

                match found {
                    Some(tok) => (tok, false),
                    None => (generate_random_token(), true),
                }
            }
            // Check for csrf token in request cookies
            CsrfPattern::DoubleSubmitCookie => {
                let (cookie_name, ctx) = match class {
                    TokenClass::Authorized => {
                        (&self.config.token_cookie_name, TokenClass::Authorized)
                    }
                    TokenClass::Anonymous => {
                        (&self.config.anon_token_cookie_name, TokenClass::Anonymous)
                    }
                };

                let token = { req.cookie(cookie_name).map(|c| c.value().to_string()) };

                match token {
                    Some(tok) => (tok, false),
                    None => {
                        let secret = self.config.secret_key.as_slice();
                        let tok = generate_hmac_token_ctx(
                            ctx,
                            session_id.expect("Session or pre-session id is passed"),
                            secret,
                        );
                        (tok, true)
                    }
                }
            }
        }
    }

    fn should_skip_validation(&self, req: &ServiceRequest) -> bool {
        let req_path = req.path();
        self.config
            .skip_for
            .iter()
            .any(|prefix| req_path.starts_with(prefix))
    }
}

impl<S, B> Service<ServiceRequest> for CsrfMiddlewareService<S>
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    B: MessageBody,
{
    type Response = ServiceResponse<EitherBody<B>>;
    type Error = Error;
    type Future = Either<CsrfTokenValidator<S, B>, Ready<Result<Self::Response, Self::Error>>>;

    forward_ready!(service);

    fn call(&self, req: ServiceRequest) -> Self::Future {
        if self.should_skip_validation(&req) {
            let resp = CsrfResponse {
                fut: self.service.call(req),
                config: Some(self.config.clone()),
                set_token: None,
                set_pre_session: None,
                token_class: None,
                remove_pre_session: false,
                _phantom: PhantomData,
            };
            return Either::left(CsrfTokenValidator::CsrfResponse { response: resp });
        }

        // Get current token from cookie or actix-session or generate new one
        let (true_token, should_set_token, cookie_session, token_class): (
            String,
            bool,
            Option<(String, bool)>,
            Option<TokenClass>,
        ) = match self.config.pattern {
            CsrfPattern::DoubleSubmitCookie => {
                let (session_id, set_pre_session, token_class) = self.get_session_from_cookie(&req);
                let (true_token, should_set_token) =
                    self.get_true_token(&req, Some(&session_id), token_class);
                (
                    true_token,
                    should_set_token,
                    Some((session_id, set_pre_session)),
                    Some(token_class),
                )
            }
            #[cfg(feature = "actix-session")]
            CsrfPattern::SynchronizerToken => {
                // Derive class from cookies and set pre-session cookie if needed
                let (session_id, set_pre_session, token_class) = self.get_session_from_cookie(&req);
                let (token, should_set_token) = self.get_true_token(&req, None, token_class);

                (
                    token,
                    should_set_token,
                    Some((session_id, set_pre_session)),
                    Some(token_class),
                )
            }
        };

        req.extensions_mut().insert(CsrfToken(true_token.clone()));
        req.extensions_mut().insert(self.config.clone());

        let is_mutating = matches!(
            *req.method(),
            Method::POST | Method::PUT | Method::PATCH | Method::DELETE
        );

        // Skip validation for read only requests, but csrf token still should be
        // added to the response when should_set_token flag is set to true.
        if !is_mutating {
            let mut set_token_bytes = if should_set_token {
                Some(true_token.clone())
            } else {
                None
            };

            let session_id = if let Some((ref session_id, set_pre_session)) = cookie_session {
                if set_pre_session {
                    Some(session_id.clone())
                } else {
                    None
                }
            } else {
                None
            };

            // Ensure an authorized token cookie exists after login (DoubleSubmitCookie only)
            if self.config.pattern == CsrfPattern::DoubleSubmitCookie {
                if let (Some(TokenClass::Authorized), Some((ref sess_id, _))) =
                    (token_class, cookie_session.as_ref())
                {
                    // If no authorized token cookie yet, issue one now
                    if req.cookie(&self.config.token_cookie_name).is_none() {
                        let tok = generate_hmac_token_ctx(
                            TokenClass::Authorized,
                            sess_id,
                            self.config.secret_key.as_slice(),
                        );
                        set_token_bytes = Some(tok);
                    }
                }
            }

            let remove_pre_session = matches!(token_class, Some(TokenClass::Authorized));
            let resp = CsrfResponse {
                fut: self.service.call(req),
                config: Some(self.config.clone()),
                set_token: set_token_bytes,
                set_pre_session: session_id,
                token_class,
                remove_pre_session,
                _phantom: PhantomData,
            };

            return Either::left(CsrfTokenValidator::CsrfResponse { response: resp });
        }

        // Optionally enforce Origin/Referer before token checks
        if self.config.enforce_origin && !origin_allowed(req.headers(), &self.config) {
            let resp = HttpResponse::with_body(StatusCode::FORBIDDEN, "Invalid request origin");
            return Either::right(ok(req
                .into_response(resp)
                .map_into_boxed_body()
                .map_into_right_body()));
        }

        // Otherwise, process mutating request with token
        // extraction from the body and future validation.

        // Handle multipart form data requests
        if let Some(ct) = req
            .headers()
            .get(header::CONTENT_TYPE)
            .and_then(|hv| hv.to_str().ok())
        {
            if ct.starts_with("multipart/form-data") {
                // Deny any multipart/form-data requests if
                // it isn't allowed explicitly by the consumer.
                if !self.config.manual_multipart {
                    let resp = HttpResponse::with_body(
                        StatusCode::BAD_REQUEST,
                        "Multipart form data is not enabled by csrf config",
                    );

                    return Either::right(ok(req
                        .into_response(resp)
                        .map_into_boxed_body()
                        .map_into_right_body()));
                }

                // Then consumer reads body, extracts and
                // verifies csrf tokens manually in their handlers.
                let resp = CsrfResponse {
                    fut: self.service.call(req),
                    config: Some(self.config.clone()),
                    set_token: None,
                    set_pre_session: None,
                    token_class: None,
                    remove_pre_session: false,
                    _phantom: PhantomData,
                };

                return Either::left(CsrfTokenValidator::CsrfResponse { response: resp });
            }
        }

        let (session_id, token_class) = if let Some((session_id, _)) = cookie_session {
            (Some(session_id), token_class)
        } else {
            (None, token_class)
        };

        // Try to extract csrf token from header
        let header_token = req
            .headers()
            .get(&self.config.token_header_name)
            .and_then(|hv| hv.to_str().ok())
            .map(|s| s.to_string());

        // Fastest and easiest way when token just received in headers
        if let Some(token) = header_token {
            return Either::left(CsrfTokenValidator::MutatingRequest {
                service: self.service.clone(),
                config: self.config.clone(),
                true_token,
                client_token: token,
                session_id,
                token_class,
                req: Some(req),
            });
        }

        // For mutating requests without header token, read body first
        let mut req2 = req;
        let payload = req2.take_payload();

        // Pre-allocate body buffer using Content-Length when available and within limit
        let initial_capacity = req2
            .headers()
            .get(header::CONTENT_LENGTH)
            .and_then(|hv| hv.to_str().ok())
            .and_then(|s| s.parse::<usize>().ok())
            .map(|n| n.min(self.config.max_body_bytes))
            .unwrap_or(0);

        let body_buf = if initial_capacity > 0 {
            BytesMut::with_capacity(initial_capacity)
        } else {
            BytesMut::new()
        };

        Either::left(CsrfTokenValidator::ReadingBody {
            req: Some(req2),
            payload: Some(payload),
            body_bytes: body_buf,
            config: self.config.clone(),
            service: self.service.clone(),
            true_token,
            session_id,
            token_class,
        })
    }
}

pin_project! {
    #[project = CsrfTokenValidatorProj]
    pub enum CsrfTokenValidator<S, B>
    where
        S: Service<ServiceRequest>,
        B: MessageBody,
    {
        CsrfResponse {
            #[pin]
            response: CsrfResponse<S, B>,
        },
        MutatingRequest {
            service: Rc<S>,
            config: Rc<CsrfMiddlewareConfig>,
            true_token: String,
            client_token: String,
            session_id: Option<String>,
            token_class: Option<TokenClass>,
            req: Option<ServiceRequest>
        },
        ReadingBody {
            service: Rc<S>,
            config: Rc<CsrfMiddlewareConfig>,
            req: Option<ServiceRequest>,
            payload: Option<actix_web::dev::Payload>,
            body_bytes: BytesMut,
            true_token: String,
            session_id: Option<String>,
            token_class: Option<TokenClass>,
        },
    }
}

impl<S, B> Future for CsrfTokenValidator<S, B>
where
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
    B: MessageBody,
{
    type Output = Result<ServiceResponse<EitherBody<B>>, Error>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        match self.as_mut().project() {
            CsrfTokenValidatorProj::CsrfResponse { response } => response.poll(cx),
            CsrfTokenValidatorProj::MutatingRequest {
                service,
                config,
                true_token,
                client_token,
                session_id,
                token_class,
                req,
            } => {
                #[cfg(not(feature = "actix-session"))]
                let _ = &true_token;

                if let Some(req) = req.take() {
                    // Session id cannot be empty with DoubleSubmitCookie pattern
                    let session_id = if config.pattern == CsrfPattern::DoubleSubmitCookie {
                        if let Some(id) = session_id.take() {
                            Some(id)
                        } else {
                            let resp = HttpResponse::with_body(
                                StatusCode::INTERNAL_SERVER_ERROR,
                                "Session id is empty in csrf token validator".to_string(),
                            );

                            return Poll::Ready(Ok(req
                                .into_response(resp)
                                .map_into_boxed_body()
                                .map_into_right_body()));
                        }
                    } else {
                        None
                    };

                    // Validate client token based on the pattern
                    let valid = match &config.pattern {
                        #[cfg(feature = "actix-session")]
                        CsrfPattern::SynchronizerToken => {
                            if eq_tokens(true_token.as_bytes(), client_token.as_bytes()) {
                                true
                            } else {
                                let alt_valid = {
                                    let session = req.get_session();
                                    let alt_key = match token_class
                                        .as_ref()
                                        .copied()
                                        .unwrap_or(TokenClass::Authorized)
                                    {
                                        TokenClass::Authorized => &config.anon_session_key_name,
                                        TokenClass::Anonymous => &config.token_cookie_name,
                                    };
                                    let alt = session.get::<String>(alt_key).ok().flatten();

                                    alt.map(|t| eq_tokens(t.as_bytes(), client_token.as_bytes()))
                                        .unwrap_or(false)
                                };

                                alt_valid
                            }
                        }
                        CsrfPattern::DoubleSubmitCookie => {
                            let ctx = token_class
                                .as_ref()
                                .copied()
                                .unwrap_or(TokenClass::Anonymous);
                            validate_hmac_token_ctx(
                                ctx,
                                session_id
                                    .as_deref()
                                    .expect("session id cannot be empty is hmac validation"),
                                client_token.as_bytes(),
                                config.secret_key.as_slice(),
                            )
                            .unwrap_or(false)
                        }
                    };

                    if !valid {
                        let resp = HttpResponse::BadRequest().body("Invalid CSRF token");
                        return Poll::Ready(Ok(req
                            .into_response(resp)
                            .map_into_boxed_body()
                            .map_into_right_body()));
                    }

                    // Rotate token based on configured pattern after every successful validation
                    let new_token = match &config.pattern {
                        #[cfg(feature = "actix-session")]
                        CsrfPattern::SynchronizerToken => generate_random_token(),
                        CsrfPattern::DoubleSubmitCookie => {
                            let ctx = token_class
                                .as_ref()
                                .copied()
                                .unwrap_or(TokenClass::Anonymous);
                            generate_hmac_token_ctx(
                                ctx,
                                session_id
                                    .as_deref()
                                    .expect("session id cannot be empty is hmac validation"),
                                config.secret_key.as_ref(),
                            )
                        }
                    };

                    let resp = CsrfResponse {
                        fut: service.call(req),
                        config: Some(config.clone()),
                        set_token: Some(new_token),
                        set_pre_session: None,
                        token_class: *token_class,
                        remove_pre_session: false,
                        _phantom: PhantomData,
                    };

                    self.set(CsrfTokenValidator::CsrfResponse { response: resp });

                    cx.waker().wake_by_ref(); // wake for the next pool
                    Poll::Pending
                } else {
                    error!("request already taken in csrf validator's state machine");

                    Poll::Ready(Err(actix_web::error::ErrorInternalServerError(
                        "Request was already taken",
                    )))
                }
            }
            CsrfTokenValidatorProj::ReadingBody {
                service,
                config,
                req,
                payload,
                body_bytes,
                true_token,
                session_id,
                token_class,
            } => {
                if req.is_none() {
                    error!("request already taken in csrf validator's state machine");
                    return Poll::Ready(Err(actix_web::error::ErrorInternalServerError(
                        "Request was already taken",
                    )));
                }

                // Safe: just checked
                let request_mut = req.as_mut().unwrap();
                let payload = match payload.as_mut() {
                    Some(p) => p,
                    None => {
                        error!("payload missing in reading body state");
                        return Poll::Ready(Err(actix_web::error::ErrorInternalServerError(
                            "Payload missing",
                        )));
                    }
                };

                match payload.poll_next_unpin(cx) {
                    Poll::Pending => Poll::Pending,
                    Poll::Ready(Some(Ok(bytes))) => {
                        body_bytes.extend_from_slice(&bytes);

                        if body_bytes.len() > config.max_body_bytes {
                            let req_owned = req.take().unwrap();
                            let resp = HttpResponse::with_body(
                                StatusCode::PAYLOAD_TOO_LARGE,
                                "Request body too large for CSRF token extraction",
                            );

                            return Poll::Ready(Ok(req_owned
                                .into_response(resp)
                                .map_into_boxed_body()
                                .map_into_right_body()));
                        }

                        cx.waker().wake_by_ref();

                        Poll::Pending
                    }
                    Poll::Ready(Some(Err(e))) => {
                        Poll::Ready(Err(actix_web::error::ErrorBadRequest(e)))
                    }
                    Poll::Ready(None) => {
                        let body = std::mem::take(&mut *body_bytes).freeze();
                        let client_token = match sync_read_token_from_body(
                            request_mut.headers(),
                            &body,
                            &config.token_form_field,
                        ) {
                            Some(token) => token,
                            None => {
                                let req_owned = req.take().unwrap();
                                let res = HttpResponse::BadRequest().body("CSRF token is required");
                                return Poll::Ready(Ok(req_owned
                                    .into_response(res)
                                    .map_into_boxed_body()
                                    .map_into_right_body()));
                            }
                        };

                        request_mut.set_payload(actix_web::dev::Payload::from(body.clone()));

                        let req_owned = req.take().unwrap();
                        let next_state = {
                            let service = service.clone();
                            let config = config.clone();
                            let true_token = std::mem::take(true_token);
                            let session_id = session_id.take();
                            let token_class = token_class.take();
                            let req = Some(req_owned);

                            CsrfTokenValidator::MutatingRequest {
                                service,
                                config,
                                true_token,
                                client_token,
                                session_id,
                                token_class,
                                req,
                            }
                        };

                        self.set(next_state);
                        cx.waker().wake_by_ref();

                        Poll::Pending
                    }
                }
            }
        }
    }
}

fn sync_read_token_from_body(
    headers: &HeaderMap,
    body: &[u8],
    token_field: &str,
) -> Option<String> {
    if let Some(ct) = headers.get(header::CONTENT_TYPE) {
        if let Ok(ct) = ct.to_str() {
            if ct.starts_with("application/json") {
                if let Ok(json) = serde_json::from_slice::<serde_json::Value>(body) {
                    return json
                        .get(token_field)
                        .and_then(|v| v.as_str().map(String::from));
                }
            } else if ct.starts_with("application/x-www-form-urlencoded") {
                if let Ok(form) = serde_urlencoded::from_bytes::<HashMap<String, String>>(body) {
                    return form.get(token_field).cloned();
                }
            } else {
                warn!("unsupported request content type, unable to extract and verify csrf token");
            }
        }
    }
    None
}

pin_project! {
    pub struct CsrfResponse<S, B>
    where
        S: Service<ServiceRequest>,
        B: MessageBody,
    {
        #[pin]
        fut: S::Future,
        config: Option<Rc<CsrfMiddlewareConfig>>,
        set_token: Option<String>,
        set_pre_session: Option<String>,
        token_class: Option<TokenClass>,
        remove_pre_session: bool,
        _phantom: PhantomData<B>,
    }
}

impl<S, B> Future for CsrfResponse<S, B>
where
    B: MessageBody,
    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error>,
{
    type Output = Result<ServiceResponse<EitherBody<B>>, Error>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.as_mut().project();
        match ready!(this.fut.poll(cx)) {
            Ok(mut resp) => {
                let config = match &this.config {
                    Some(config) => config,
                    None => {
                        let res = HttpResponse::InternalServerError()
                            .body("An empty csrf middleware config passed into csrf response");

                        error!("unable to extract csrf middleware config in csrf response");
                        return Poll::Ready(Ok(resp
                            .into_response(res)
                            .map_into_boxed_body()
                            .map_into_right_body()));
                    }
                };

                // Set pre-session if requested
                if let Some(pre_session_id) = this.set_pre_session {
                    let cookie_val =
                        encode_pre_session_cookie(pre_session_id, config.secret_key.as_slice());

                    match resp.response_mut().add_cookie(
                        &Cookie::build(CSRF_PRE_SESSION_KEY, cookie_val)
                            .http_only(PRE_SESSION_HTTP_ONLY)
                            .secure(PRE_SESSION_SECURE)
                            .same_site(PRE_SESSION_SAME_SITE)
                            .path("/")
                            .finish(),
                    ) {
                        Ok(_) => {}
                        Err(e) => {
                            let res = HttpResponse::InternalServerError()
                                .body("Unable to set pre-session cookie");

                            error!("unable to set pre-session cookie in csrf response: {e:?}");
                            return Poll::Ready(Ok(resp
                                .into_response(res)
                                .map_into_boxed_body()
                                .map_into_right_body()));
                        }
                    }
                }

                // If requested, clear pre-session cookie and anon token cookie
                if *this.remove_pre_session {
                    // Expire pre-session
                    let mut del = Cookie::new(CSRF_PRE_SESSION_KEY.to_string(), "");
                    del.set_max_age(time::Duration::seconds(0));
                    del.set_expires(time::OffsetDateTime::UNIX_EPOCH);
                    del.set_path("/");
                    del.set_http_only(PRE_SESSION_HTTP_ONLY);
                    del.set_secure(PRE_SESSION_SECURE);
                    del.set_same_site(PRE_SESSION_SAME_SITE);

                    if let Err(e) = resp.response_mut().add_cookie(&del) {
                        let res = HttpResponse::InternalServerError()
                            .body("Failed to expire pre-session cookie");

                        error!("unable to expire pre-session cookie in csrf response: {e:?}");
                        return Poll::Ready(Ok(resp
                            .into_response(res)
                            .map_into_boxed_body()
                            .map_into_right_body()));
                    }

                    // Expire anonymous token cookie
                    if matches!(config.pattern, CsrfPattern::DoubleSubmitCookie) {
                        let mut del_tok = Cookie::new(config.anon_token_cookie_name.clone(), "");
                        del_tok.set_max_age(time::Duration::seconds(0));
                        del_tok.set_expires(time::OffsetDateTime::UNIX_EPOCH);
                        del_tok.set_path("/");

                        if let Err(e) = resp.response_mut().add_cookie(&del_tok) {
                            let res = HttpResponse::InternalServerError()
                                .body("Failed to expire anon token cookie");

                            error!("unable to expire anon token cookie in csrf response: {e:?}");
                            return Poll::Ready(Ok(resp
                                .into_response(res)
                                .map_into_boxed_body()
                                .map_into_right_body()));
                        }
                    }
                }

                // Based on configured pattern, set a new token or rotate
                // the old one for the service response if pattern is passed.
                if let Some(new_token) = this.set_token.take() {
                    match config.pattern {
                        #[cfg(feature = "actix-session")]
                        CsrfPattern::SynchronizerToken => {
                            if *this.remove_pre_session {
                                let _ = resp
                                    .request()
                                    .get_session()
                                    .remove(&config.anon_session_key_name);
                            }

                            // Set a new token into actix session under key decided by class
                            let key = match this.token_class.unwrap_or(TokenClass::Authorized) {
                                TokenClass::Authorized => &config.token_cookie_name,
                                TokenClass::Anonymous => &config.anon_session_key_name,
                            };

                            match resp.request().get_session().insert(key, new_token) {
                                Ok(()) => {}
                                Err(e) => {
                                    let res = HttpResponse::with_body(
                                        StatusCode::INTERNAL_SERVER_ERROR,
                                        "Failed to insert CSRF token into session",
                                    );

                                    error!("unable to set a csrf token with actix session in csrf response: {:?}",e);
                                    return Poll::Ready(Ok(resp
                                        .into_response(res)
                                        .map_into_boxed_body()
                                        .map_into_right_body()));
                                }
                            }
                        }
                        CsrfPattern::DoubleSubmitCookie => {
                            let cookie_config = match &config.token_cookie_config {
                                Some(config) => config,
                                None => {
                                    let res = HttpResponse::InternalServerError().body(
                                        "An empty csrf cookie config passed into csrf response",
                                    );

                                    error!(
                                        "unable to extract token_cookie_config in csrf response"
                                    );
                                    return Poll::Ready(Ok(resp
                                        .into_response(res)
                                        .map_into_boxed_body()
                                        .map_into_right_body()));
                                }
                            };

                            // Choose cookie name based on token class
                            let cookie_name =
                                match this.token_class.unwrap_or(TokenClass::Anonymous) {
                                    TokenClass::Authorized => &config.token_cookie_name,
                                    TokenClass::Anonymous => &config.anon_token_cookie_name,
                                };

                            let new_token_cookie = Cookie::build(cookie_name, new_token)
                                .http_only(cookie_config.http_only)
                                .secure(cookie_config.secure)
                                .same_site(cookie_config.same_site)
                                .path("/")
                                .finish();

                            // Update token cookie with a new token
                            match resp.response_mut().add_cookie(&new_token_cookie) {
                                Ok(_) => {}
                                Err(e) => {
                                    let res = HttpResponse::InternalServerError()
                                        .body("Failed to set a new csrf token");

                                    error!("unable to set a token cookie in csrf response: {e:?}");
                                    return Poll::Ready(Ok(resp
                                        .into_response(res)
                                        .map_into_boxed_body()
                                        .map_into_right_body()));
                                }
                            }
                        }
                    }
                }

                Poll::Ready(Ok(resp.map_into_left_body()))
            }
            Err(err) => Poll::Ready(Err(err)),
        }
    }
}

#[derive(Clone)]
/// Extractor for the current CSRF token.
///
/// - On safe requests (GET/HEAD), ensures a token exists and makes it available to handlers.
/// - On mutating requests (POST/PUT/PATCH/DELETE), extracting [`CsrfToken`] verifies the
///   token before your handler is called; if verification fails, the request is rejected and
///   your handler is not executed.
///
/// # Examples
/// Read the token in a form-rendering handler and embed it into HTML or a JSON response.
/// ```
/// use actix_csrf_middleware::CsrfToken;
/// use actix_web::{HttpResponse, Responder};
///
/// async fn form(csrf: CsrfToken) -> impl Responder {
///     HttpResponse::Ok().body(format!("token:{}", csrf.0))
/// }
/// ```
///
/// Note: Using this extractor requires the middleware to be installed via
/// [`CsrfMiddleware::new`]. If not configured, extraction will fail with an internal error.
pub struct CsrfToken(pub String);

impl FromRequest for CsrfToken {
    type Error = Error;
    type Future = Ready<Result<Self, Self::Error>>;

    fn from_request(req: &HttpRequest, _: &mut actix_web::dev::Payload) -> Self::Future {
        match req.extensions().get::<CsrfToken>() {
            Some(token) => ok(token.clone()),
            None => err(actix_web::error::ErrorInternalServerError(
                "CSRF middleware is not configured",
            )),
        }
    }
}

/// Extension trait for Actix [`HttpRequest`] to rotate the CSRF token in a response.
///
/// This is a convenience wrapper around [`rotate_csrf_token_in_response`], allowing you to
/// rotate tokens without passing configuration explicitly. Typical use-cases include
/// rotating the token immediately after login or privilege escalation.
///
/// # Examples
/// Rotate after a successful login:
/// ```
/// use actix_csrf_middleware::CsrfRequestExt;
/// use actix_web::{HttpRequest, HttpResponse};
///
/// async fn after_login(req: HttpRequest) -> actix_web::Result<HttpResponse> {
///     let mut resp = HttpResponse::Ok();
///     req.rotate_csrf_token_in_response(&mut resp)?;
///     Ok(resp.finish())
/// }
/// ```
pub trait CsrfRequestExt {
    /// Rotates the CSRF token and writes it to the outgoing response according to the
    /// configured pattern.
    fn rotate_csrf_token_in_response(&self, resp: &mut HttpResponseBuilder) -> Result<(), Error>;
}

impl CsrfRequestExt for HttpRequest {
    fn rotate_csrf_token_in_response(&self, resp: &mut HttpResponseBuilder) -> Result<(), Error> {
        // Clone out the config to avoid holding an extensions borrow across session access
        let cfg_rc: Rc<CsrfMiddlewareConfig> =
            match self.extensions().get::<Rc<CsrfMiddlewareConfig>>() {
                Some(cfg_rc_ref) => cfg_rc_ref.clone(),
                None => {
                    return Err(actix_web::error::ErrorInternalServerError(
                        "CSRF middleware config not found in request extensions",
                    ))
                }
            };

        rotate_csrf_token_in_response(self, resp, cfg_rc.as_ref())
    }
}

/// Generates a cryptographically secure random CSRF token.
///
/// The token is 32 bytes of randomness, encoded with URL-safe base64 without padding
/// (aka base64url), resulting in a 43-character ASCII string. The alphabet is limited to
/// `A-Z`, `a-z`, `0-9`, `-`, and `_`, making it safe for use in URLs, HTTP headers, and
/// HTML form fields without additional escaping.
///
/// This function returns a standalone random value and does not bind the token to any
/// session or identity. For the Double-Submit Cookie pattern used by this crate, prefer
/// [`generate_hmac_token_ctx`] which derives an HMAC-protected token from a session id
/// and the token, making it unforgeable by clients.
///
/// # Security
/// - The token is generated using a CSPRNG and is suitable for CSRF defenses.
/// - When using the Double-Submit Cookie pattern, do not place this raw token into a
///   cookie by itself. Use [`generate_hmac_token_ctx`] so the server can verify integrity.
/// - When using the Synchronizer Token pattern (feature `actix-session`), this raw token
///   may be stored server-side in session and compared using constant-time equality.
///
/// # Examples
/// Generate a token and validate its shape.
/// ```
/// let tok = actix_csrf_middleware::generate_random_token();
/// assert_eq!(tok.len(), 43, "32 bytes base64url-encoded -> 43 chars");
/// assert!(tok.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'));
/// ```
///
/// Produce an HMAC-protected token for Double-Submit Cookie flows.
/// ```
/// use actix_csrf_middleware::{generate_random_token, generate_hmac_token_ctx, TokenClass};
///
/// let session_id = "SID-123";
/// let secret = b"an-application-wide-secret-at-least-32-bytes-long";
/// let raw = generate_random_token();
///
/// // In typical flows you would call `generate_hmac_token_ctx` directly without
/// // generating the raw token yourself; shown here for illustration.
/// let hmac_token = generate_hmac_token_ctx(TokenClass::Authorized, session_id, secret);
/// assert!(hmac_token.contains('.'));
///
/// let parts: Vec<_> = hmac_token.split('.').collect();
/// assert_eq!(parts.len(), 2);
/// ```
pub fn generate_random_token() -> String {
    let mut buf = [0u8; TOKEN_LEN];
    rand::rng().fill_bytes(&mut buf);
    URL_SAFE_NO_PAD.encode(buf)
}

/// Generates an HMAC-protected CSRF token bound to a context and identifier.
///
/// The produced token has the shape `HEX_HMAC.RANDOM`, where:
/// - `RANDOM` is a fresh value from [`generate_random_token`].
/// - `HEX_HMAC` is a hex-encoded HMAC-SHA256 over the message
///   `"{class}|{id}|{RANDOM}"`, using the provided `secret`.
///
/// This format is designed for the Double-Submit Cookie pattern:
/// - The server sets the token as a cookie and expects clients to echo it back via a
///   form field or header.
/// - On receipt, the server recomputes the HMAC with the same `class`, `id`, and `secret`.
///   If the HMAC matches, the token is authentic and not forgeable by the client.
///
/// The `class` determines which logical bucket the token belongs to:
/// - [`TokenClass::Authorized`]: token that is bound to an authenticated session.
/// - [`TokenClass::Anonymous`]: token used before authentication (pre-session).
///
/// # Parameters
/// - `class`: Distinguishes the token namespace (authorized vs. anonymous).
/// - `id`: Identifier bound into the token (e.g., a session id); must be the same value
///   used later for verification.
/// - `secret`: Application-wide secret key (>= 32 bytes recommended). Changing the secret
///   invalidates all existing tokens immediately.
///
/// # Security
/// - Tokens are unforgeable without knowledge of `secret` and `id`.
/// - Use different `class` values to prevent confusion between anonymous and authorized
///   tokens; they are not interchangeable.
/// - Choose a high-entropy `secret` with at least 32 bytes.
///
/// # Examples
/// Generate and verify an authorized token.
/// ```
/// use actix_csrf_middleware::{generate_hmac_token_ctx, validate_hmac_token_ctx, TokenClass};
///
/// let session_id = "SID-abc";
/// let secret = b"an-application-wide-secret-at-least-32-bytes!";
/// let tok = generate_hmac_token_ctx(TokenClass::Authorized, session_id, secret);
///
/// assert!(tok.contains('.'));
/// assert!(validate_hmac_token_ctx(TokenClass::Authorized, session_id, tok.as_bytes(), secret).unwrap());
/// ```
///
/// Generate an anonymous token (pre-session) and verify it with the same `id` and `class`.
/// ```
/// use actix_csrf_middleware::{generate_hmac_token_ctx, validate_hmac_token_ctx, TokenClass};
///
/// let pre_session_id = "pre-123";
/// let secret = b"an-application-wide-secret-at-least-32-bytes!";
/// let tok = generate_hmac_token_ctx(TokenClass::Anonymous, pre_session_id, secret);
///
/// assert!(validate_hmac_token_ctx(TokenClass::Anonymous, pre_session_id, tok.as_bytes(), secret).unwrap());
/// ```
pub fn generate_hmac_token_ctx(class: TokenClass, id: &str, secret: &[u8]) -> String {
    let tok = generate_random_token();
    let mut mac = HmacSha256::new_from_slice(secret).expect("HMAC can take key of any size");
    mac.update(class.as_str().as_bytes());
    mac.update(b"|");
    mac.update(id.as_bytes());
    mac.update(b"|");
    mac.update(tok.as_bytes());

    let hmac_hex = hex::encode(mac.finalize().into_bytes());
    format!("{hmac_hex}.{tok}")
}

/// Constant-time equality for token byte slices.
///
/// Uses a timing-attack resistant comparison to avoid leaking information about token
/// values. Prefer using higher-level helpers for CSRF validation, but this function is
/// useful when verifying raw secrets or signatures.
///
/// # Examples
/// ```
/// use actix_csrf_middleware::eq_tokens;
/// assert!(eq_tokens(b"abc", b"abc"));
/// assert!(!eq_tokens(b"abc", b"abcd"));
/// ```
pub fn eq_tokens(token_a: &[u8], token_b: &[u8]) -> bool {
    token_a.ct_eq(token_b).unwrap_u8() == 1
}

fn encode_pre_session_cookie(id: &str, secret: &[u8]) -> String {
    let mut mac = HmacSha256::new_from_slice(secret).expect("HMAC can take key of any size");
    mac.update(b"pre|");
    mac.update(id.as_bytes());

    let sig = hex::encode(mac.finalize().into_bytes());
    format!("{sig}.{id}")
}

fn decode_pre_session_cookie(val: &str, secret: &[u8]) -> Option<String> {
    let parts: Vec<&str> = val.split('.').collect();
    if parts.len() != 2 {
        return None;
    }

    let (sig_hex, id) = (parts[0], parts[1]);
    let sig_bytes = hex::decode(sig_hex).ok()?;

    let mut mac = Hmac::<Sha256>::new_from_slice(secret).ok()?;
    mac.update(b"pre|");
    mac.update(id.as_bytes());

    let expected = mac.finalize().into_bytes();

    if eq_tokens(&expected, &sig_bytes) {
        Some(id.to_string())
    } else {
        None
    }
}

/// Verifies an HMAC-protected CSRF token for a given class and identifier.
///
/// Accepts tokens in the `HEX_HMAC.RANDOM` format produced by
/// [`generate_hmac_token_ctx`]. Returns `Ok(true)` on a valid token and `Ok(false)` on
/// structural or verification failure. Returns an `Err` only for malformed UTF-8 or
/// hex-decoding errors while parsing.
///
/// The token is recomputed as HMAC-SHA256 over `"{class}|{id}|{RANDOM}"` using the
/// provided `secret` and compared in constant time.
///
/// # Errors
/// - Returns `Err` if `token` is not valid UTF-8.
/// - Returns `Err` if the HMAC hex part cannot be decoded.
///
/// # Examples
/// ```
/// use actix_csrf_middleware::{
///     generate_hmac_token_ctx, validate_hmac_token_ctx, TokenClass
/// };
///
/// let sid = "SID-xyz";
/// let secret = b"application-secret-at-least-32-bytes-long";
/// let token = generate_hmac_token_ctx(TokenClass::Authorized, sid, secret);
///
/// assert!(validate_hmac_token_ctx(TokenClass::Authorized, sid, token.as_bytes(), secret).unwrap());
///
/// // Wrong class or id will fail verification
/// assert!(!validate_hmac_token_ctx(TokenClass::Anonymous, sid, token.as_bytes(), secret).unwrap());
/// assert!(!validate_hmac_token_ctx(TokenClass::Authorized, "SID-other", token.as_bytes(), secret).unwrap());
/// ```
pub fn validate_hmac_token_ctx(
    class: TokenClass,
    id: &str,
    token: &[u8],
    secret: &[u8],
) -> Result<bool, Error> {
    let token_str = std::str::from_utf8(token)?;
    let parts: Vec<&str> = token_str.split('.').collect();
    if parts.len() != 2 {
        return Ok(false);
    }

    let (hmac_hex, csrf_token) = (parts[0], parts[1]);
    let hmac_bytes = hex::decode(hmac_hex).map_err(actix_web::error::ErrorInternalServerError)?;

    let mut mac = Hmac::<Sha256>::new_from_slice(secret)
        .map_err(actix_web::error::ErrorInternalServerError)?;
    mac.update(class.as_str().as_bytes());
    mac.update(b"|");
    mac.update(id.as_bytes());
    mac.update(b"|");
    mac.update(csrf_token.as_bytes());

    let expected_hmac = mac.finalize().into_bytes();

    Ok(eq_tokens(&expected_hmac, &hmac_bytes))
}

/// Convenience helper to validate an authorized-class CSRF token.
///
/// This is a thin wrapper around [`validate_hmac_token_ctx`] that always uses
/// [`TokenClass::Authorized`]. It is intended for tests and simple validation flows
/// where only authorized tokens are expected.
///
/// # Examples
/// ```
/// use actix_csrf_middleware::{
///     generate_hmac_token_ctx, validate_hmac_token, TokenClass
/// };
///
/// let sid = "SID-xyz";
/// let secret = b"application-secret-at-least-32-bytes-long";
/// let token = generate_hmac_token_ctx(TokenClass::Authorized, sid, secret);
///
/// assert!(validate_hmac_token(sid, token.as_bytes(), secret).unwrap());
/// ```
pub fn validate_hmac_token(session_id: &str, token: &[u8], secret: &[u8]) -> Result<bool, Error> {
    validate_hmac_token_ctx(TokenClass::Authorized, session_id, token, secret)
}

/// Rotates the CSRF token and writes any necessary cookie updates to the response.
///
/// - Double-Submit Cookie: requires a session id cookie to be present; sets a fresh
///   HMAC-protected authorized token cookie and expires any anonymous token.
/// - Synchronizer Token: sets a fresh random token in server-side session and expires
///   pre-session markers.
///
/// This function is safe to call on both safe and mutating handlers, but it is commonly
/// used after authentication to immediately upgrade from anonymous to authorized tokens.
///
/// # Errors
/// - Returns `BadRequest` when required inputs are missing (e.g., session id cookie for
///   Double-Submit Cookie).
/// - Returns `InternalServerError` if session updates fail (Synchronizer Token) or cookies
///   cannot be set.
///
/// # Examples
/// Rotate in a handler using the extension trait (preferred):
/// ```
/// use actix_csrf_middleware::CsrfRequestExt;
/// use actix_web::{HttpRequest, HttpResponse};
///
/// async fn rotate(req: HttpRequest) -> actix_web::Result<HttpResponse> {
///     let mut resp = HttpResponse::Ok();
///     req.rotate_csrf_token_in_response(&mut resp)?;
///     Ok(resp.finish())
/// }
/// ```
pub fn rotate_csrf_token_in_response(
    req: &HttpRequest,
    resp: &mut HttpResponseBuilder,
    config: &CsrfMiddlewareConfig,
) -> Result<(), Error> {
    // Always expire the pre-session cookie (best-effort) with strict flags
    let mut del = Cookie::new(CSRF_PRE_SESSION_KEY.to_string(), "");
    del.set_max_age(time::Duration::seconds(0));
    del.set_expires(time::OffsetDateTime::UNIX_EPOCH);
    del.set_path("/");
    del.set_http_only(PRE_SESSION_HTTP_ONLY);
    del.set_secure(PRE_SESSION_SECURE);
    del.set_same_site(PRE_SESSION_SAME_SITE);
    resp.cookie(del);

    match config.pattern {
        #[cfg(feature = "actix-session")]
        CsrfPattern::SynchronizerToken => {
            let session = req.get_session();
            let new_token = generate_random_token();

            let _ = session.remove(&config.anon_session_key_name);

            session
                .insert(&config.token_cookie_name, new_token)
                .map_err(|_| {
                    actix_web::error::ErrorInternalServerError(
                        "Failed to rotate CSRF token in session",
                    )
                })?;

            Ok(())
        }
        CsrfPattern::DoubleSubmitCookie => {
            // Need the session id from cookie
            let session_id = req
                .cookie(&config.session_id_cookie_name)
                .map(|c| c.value().to_string())
                .ok_or_else(|| {
                    actix_web::error::ErrorBadRequest("Missing session id cookie for CSRF rotation")
                })?;

            let token = generate_hmac_token_ctx(
                TokenClass::Authorized,
                &session_id,
                config.secret_key.as_slice(),
            );

            let (http_only, secure, same_site) = match &config.token_cookie_config {
                Some(cfg) => (cfg.http_only, cfg.secure, cfg.same_site),
                None => (true, true, SameSite::Lax),
            };

            let csrf_cookie = Cookie::build(&config.token_cookie_name, token)
                .http_only(http_only)
                .secure(secure)
                .same_site(same_site)
                .path("/")
                .finish();

            // Also expire anonymous token cookie
            let mut del_anon = Cookie::new(config.anon_token_cookie_name.clone(), "");
            del_anon.set_max_age(time::Duration::seconds(0));
            del_anon.set_expires(time::OffsetDateTime::UNIX_EPOCH);
            del_anon.set_path("/");

            resp.cookie(csrf_cookie);
            resp.cookie(del_anon);

            Ok(())
        }
    }
}

fn check_secret_key(secret_key: &[u8]) {
    if secret_key.len() < 32 {
        panic!("csrf secret_key too short: require >=32 bytes");
    }
}

fn origin_allowed(headers: &HeaderMap, cfg: &CsrfMiddlewareConfig) -> bool {
    if !cfg.enforce_origin {
        return true;
    }

    if cfg.allowed_origins.is_empty() {
        return false;
    }

    // Helper to compare origins strictly (scheme, host, port)
    let is_allowed_origin = |u: &Url| -> bool {
        cfg.allowed_origins.iter().any(|allowed| {
            if let Ok(au) = Url::parse(allowed) {
                au.scheme() == u.scheme()
                    && au.host_str() == u.host_str()
                    && au.port_or_known_default() == u.port_or_known_default()
            } else {
                false
            }
        })
    };

    // Try Origin header first (preferred)
    if let Some(origin) = headers.get(header::ORIGIN).and_then(|hv| hv.to_str().ok()) {
        if let Ok(u) = Url::parse(origin) {
            return is_allowed_origin(&u);
        }

        return false;
    }

    // Fallback: Referer header, use its origin
    if let Some(referer) = headers.get(header::REFERER).and_then(|hv| hv.to_str().ok()) {
        if let Ok(u) = Url::parse(referer) {
            let origin = format!(
                "{}://{}{}",
                u.scheme(),
                u.host_str().unwrap_or(""),
                u.port().map(|p| format!(":{p}")).unwrap_or_default()
            );

            if let Ok(o) = Url::parse(&origin) {
                return is_allowed_origin(&o);
            }
        }

        return false;
    }

    false
}