ggen-core 26.7.3

//! Template security hardening for sandboxed Tera environments
//!
//! **Week 3 Security Hardening: Template Security**
//!
//! This module implements comprehensive template security mechanisms:
//! - Sandboxed Tera environment with restricted functions
//! - Template variable validation (alphanumeric + underscore only)
//! - Template source validation (prevent template injection)
//! - Context-aware escaping filters (HTML, SQL, Shell)
//! - Maximum template size enforcement (1MB)
//! - Path traversal prevention in template includes
//!
//! ## Security Measures
//!
//! 1. **Function Whitelist**: Only safe Tera functions allowed (no file/network/shell access)
//! 2. **Variable Validation**: All variables must be alphanumeric + underscore
//! 3. **Size Limits**: Templates limited to 1MB maximum
//! 4. **Escaping**: Context-aware output escaping (HTML, SQL, Shell)
//! 5. **Path Security**: No path traversal in includes

use crate::utils::error::{Error, Result};
use std::collections::{HashMap, HashSet};
use tera::{Context, Tera, Value};

/// Maximum template size in bytes (1MB)
pub const MAX_TEMPLATE_SIZE: usize = 1_048_576;

/// Maximum variable name length
pub const MAX_VARIABLE_NAME_LENGTH: usize = 256;

/// Error type for template security violations
#[derive(Debug, thiserror::Error)]
pub enum TemplateSecurityError {
    #[error("Template too large: {0} bytes (max: {1})")]
    TemplateTooLarge(usize, usize),

    #[error("Invalid variable name: {0}")]
    InvalidVariableName(String),

    #[error("Forbidden function: {0}")]
    ForbiddenFunction(String),

    #[error("Template injection detected: {0}")]
    TemplateInjection(String),

    #[error("Path traversal in include: {0}")]
    PathTraversal(String),

    #[error("Context required for escaping: {0}")]
    MissingContext(String),

    #[error("Invalid template syntax: {0}")]
    InvalidSyntax(String),
}

impl From<TemplateSecurityError> for Error {
    fn from(err: TemplateSecurityError) -> Self {
        Error::new(&err.to_string())
    }
}

/// Trait for sandboxed template environments
pub trait TemplateSandbox {
    /// Validate template source before rendering
    fn validate_template(&self, source: &str) -> Result<()>;

    /// Render template with validated context
    fn render_safe(&self, source: &str, context: &Context) -> Result<String>;

    /// Check if a function is allowed in the sandbox
    fn is_function_allowed(&self, name: &str) -> bool;

    /// Validate variable name for security
    fn validate_variable_name(&self, name: &str) -> Result<()>;
}

/// Secure Tera environment with sandboxing
pub struct SecureTeraEnvironment {
    /// Allowed Tera functions (whitelist)
    allowed_functions: HashSet<String>,
    /// Forbidden patterns in templates
    forbidden_patterns: Vec<&'static str>,
    /// Maximum template size
    max_size: usize,
}

impl SecureTeraEnvironment {
    /// Create new secure Tera environment with default whitelist
    pub fn new() -> Self {
        Self {
            allowed_functions: Self::default_allowed_functions(),
            forbidden_patterns: Self::default_forbidden_patterns(),
            max_size: MAX_TEMPLATE_SIZE,
        }
    }

    /// Create with custom maximum size
    pub fn with_max_size(mut self, max_size: usize) -> Self {
        self.max_size = max_size;
        self
    }

    /// Default allowed functions (whitelist - no file/network/shell access)
    fn default_allowed_functions() -> HashSet<String> {
        let mut set = HashSet::new();

        // String manipulation (safe)
        set.insert("upper".to_string());
        set.insert("lower".to_string());
        set.insert("trim".to_string());
        set.insert("truncate".to_string());
        set.insert("wordcount".to_string());
        set.insert("replace".to_string());
        set.insert("split".to_string());
        set.insert("join".to_string());
        set.insert("capitalize".to_string());
        set.insert("title".to_string());

        // Math operations (safe)
        set.insert("round".to_string());
        set.insert("abs".to_string());
        set.insert("plus".to_string());
        set.insert("minus".to_string());
        set.insert("times".to_string());
        set.insert("divided_by".to_string());

        // Collections (safe)
        set.insert("length".to_string());
        set.insert("first".to_string());
        set.insert("last".to_string());
        set.insert("nth".to_string());
        set.insert("slice".to_string());
        set.insert("concat".to_string());
        set.insert("reverse".to_string());
        set.insert("sort".to_string());
        set.insert("unique".to_string());
        set.insert("group_by".to_string());
        set.insert("filter".to_string());
        set.insert("map".to_string());

        // Formatting (safe)
        set.insert("date".to_string());
        set.insert("json_encode".to_string());
        set.insert("urlencode".to_string());
        set.insert("escape".to_string());
        set.insert("safe".to_string());

        // Security: Custom escaping filters
        set.insert("escape_html".to_string());
        set.insert("escape_sql".to_string());
        set.insert("escape_shell".to_string());

        set
    }

    /// Forbidden patterns that indicate potential security issues
    fn default_forbidden_patterns() -> Vec<&'static str> {
        vec![
            // File system access attempts
            "include_raw",
            "read_file",
            "write_file",
            // Network access attempts
            "http",
            "https",
            "fetch",
            "curl",
            // Shell execution attempts
            "exec",
            "system",
            "shell",
            "cmd",
            "bash",
            // Dangerous path patterns
            "../",
            "..\\",
            "/etc/",
            "/proc/",
            "/sys/",
            "C:\\Windows",
        ]
    }

    /// Validate template size
    fn validate_size(&self, source: &str) -> Result<()> {
        let size = source.len();
        if size > self.max_size {
            return Err(TemplateSecurityError::TemplateTooLarge(size, self.max_size).into());
        }
        Ok(())
    }

    /// Check for forbidden patterns in template
    fn check_forbidden_patterns(&self, source: &str) -> Result<()> {
        // The escape filters provided by this sandbox (`escape_shell`, etc.) contain
        // substrings that overlap with forbidden patterns (e.g. "shell"). Neutralize
        // these legitimate, sandbox-provided filter names before substring-matching so
        // they do not produce false positives, without weakening detection of genuine
        // dangerous tokens like `exec`, `bash`, or `system`.
        let mut scanned = source.to_string();
        for safe in ["escape_shell", "escape_sql", "escape_html"] {
            scanned = scanned.replace(safe, "");
        }

        for pattern in &self.forbidden_patterns {
            if scanned.contains(pattern) {
                return Err(TemplateSecurityError::TemplateInjection(format!(
                    "Forbidden pattern detected: {}",
                    pattern
                ))
                .into());
            }
        }
        Ok(())
    }

    /// Validate template includes for path traversal
    fn validate_includes(&self, source: &str) -> Result<()> {
        // Check for include statements
        for line in source.lines() {
            let trimmed = line.trim();
            if trimmed.starts_with("{%") && trimmed.contains("include") {
                // Extract include path (simplified - production would use proper parsing)
                if trimmed.contains("..") {
                    return Err(TemplateSecurityError::PathTraversal(
                        "Path traversal detected in include".to_string(),
                    )
                    .into());
                }
            }
        }
        Ok(())
    }
}

impl Default for SecureTeraEnvironment {
    fn default() -> Self {
        Self::new()
    }
}

impl TemplateSandbox for SecureTeraEnvironment {
    fn validate_template(&self, source: &str) -> Result<()> {
        // 1. Check template size
        self.validate_size(source)?;

        // 2. Check for forbidden patterns
        self.check_forbidden_patterns(source)?;

        // 3. Validate includes
        self.validate_includes(source)?;

        Ok(())
    }

    fn render_safe(&self, source: &str, context: &Context) -> Result<String> {
        // Validate template first
        self.validate_template(source)?;

        // Create Tera instance with security filters
        let mut tera = Tera::default();

        // Register security filters
        tera.register_filter("escape_html", escape_html_filter);
        tera.register_filter("escape_sql", escape_sql_filter);
        tera.register_filter("escape_shell", escape_shell_filter);

        // Render template
        tera.render_str(source, context)
            .map_err(|e| Error::new(&format!("Template rendering failed: {}", e)))
    }

    fn is_function_allowed(&self, name: &str) -> bool {
        self.allowed_functions.contains(name)
    }

    fn validate_variable_name(&self, name: &str) -> Result<()> {
        TemplateValidator::validate_variable_name(name)
    }
}

/// Template validator for security checks
pub struct TemplateValidator;

impl TemplateValidator {
    /// Validate variable name (alphanumeric + underscore only)
    ///
    /// # Security
    ///
    /// Prevents injection via variable names with special characters
    ///
    /// # Examples
    ///
    /// ```rust
    /// use crate::security::template_secure::TemplateValidator;
    ///
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// // Valid variable names
    /// assert!(TemplateValidator::validate_variable_name("user_name").is_ok());
    /// assert!(TemplateValidator::validate_variable_name("count_123").is_ok());
    ///
    /// // Invalid variable names
    /// assert!(TemplateValidator::validate_variable_name("user.name").is_err());
    /// assert!(TemplateValidator::validate_variable_name("user[0]").is_err());
    /// assert!(TemplateValidator::validate_variable_name("../etc/passwd").is_err());
    /// # Ok(())
    /// # }
    /// ```
    pub fn validate_variable_name(name: &str) -> Result<()> {
        // Check empty
        if name.is_empty() {
            return Err(TemplateSecurityError::InvalidVariableName(
                "Variable name is empty".to_string(),
            )
            .into());
        }

        // Check length
        if name.len() > MAX_VARIABLE_NAME_LENGTH {
            return Err(TemplateSecurityError::InvalidVariableName(format!(
                "Variable name too long: {} (max: {})",
                name.len(),
                MAX_VARIABLE_NAME_LENGTH
            ))
            .into());
        }

        // Check characters (alphanumeric + underscore only)
        if !name.chars().all(|c| c.is_alphanumeric() || c == '_') {
            return Err(TemplateSecurityError::InvalidVariableName(format!(
                "Variable name contains invalid characters: {}",
                name
            ))
            .into());
        }

        // Additional check: must not start with number
        if name.chars().next().is_some_and(|c| c.is_numeric()) {
            return Err(TemplateSecurityError::InvalidVariableName(
                "Variable name cannot start with number".to_string(),
            )
            .into());
        }

        Ok(())
    }

    /// Validate all variables in a context
    pub fn validate_context(_context: &Context) -> Result<()> {
        // Extract variable names from context
        // Note: Tera Context doesn't expose keys directly, so we validate during insertion
        // This is a placeholder - actual validation happens in variable name validation
        Ok(())
    }

    /// Validate template syntax without rendering
    pub fn validate_syntax(source: &str) -> Result<()> {
        let mut tera = Tera::default();
        tera.render_str(source, &Context::new())
            .map(|_| ())
            .map_err(|e| {
                TemplateSecurityError::InvalidSyntax(format!("Template syntax error: {}", e)).into()
            })
    }
}

/// Context-aware escaping for different output contexts
pub struct ContextEscaper;

impl ContextEscaper {
    /// Escape for HTML context
    ///
    /// # Security
    ///
    /// Prevents XSS attacks by escaping HTML special characters
    ///
    /// # Examples
    ///
    /// ```rust
    /// use crate::security::template_secure::ContextEscaper;
    ///
    /// let escaped = ContextEscaper::escape_html("<script>alert('xss')</script>");
    /// assert_eq!(escaped, "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;&#x2F;script&gt;");
    /// ```
    pub fn escape_html(input: &str) -> String {
        input
            .replace('&', "&amp;")
            .replace('<', "&lt;")
            .replace('>', "&gt;")
            .replace('"', "&quot;")
            .replace('\'', "&#x27;")
            .replace('/', "&#x2F;")
    }

    /// Escape for SQL context (prevent SQL injection)
    ///
    /// # Security
    ///
    /// Escapes SQL special characters to prevent injection
    ///
    /// # Examples
    ///
    /// ```rust
    /// use crate::security::template_secure::ContextEscaper;
    ///
    /// let escaped = ContextEscaper::escape_sql("'; DROP TABLE users; --");
    /// assert_eq!(escaped, "''; DROP TABLE users; --");
    /// ```
    pub fn escape_sql(input: &str) -> String {
        // Escape single quotes by doubling them
        input.replace('\'', "''")
    }

    /// Escape for shell context (prevent command injection)
    ///
    /// # Security
    ///
    /// Escapes shell metacharacters to prevent command injection
    ///
    /// # Examples
    ///
    /// ```rust
    /// use crate::security::template_secure::ContextEscaper;
    ///
    /// let escaped = ContextEscaper::escape_shell("file.txt; rm -rf /");
    /// assert_eq!(escaped, "file.txt\\;\\ rm\\ -rf\\ /");
    /// ```
    pub fn escape_shell(input: &str) -> String {
        let mut result = String::with_capacity(input.len() * 2);
        for c in input.chars() {
            match c {
                // Shell metacharacters that need escaping
                '$' | '`' | '"' | '\\' | '!' | '\n' | '&' | ';' | '|' | '(' | ')' | '<' | '>'
                | ' ' | '\t' | '*' | '?' | '[' | ']' | '{' | '}' | '~' | '#' => {
                    result.push('\\');
                    result.push(c);
                }
                _ => result.push(c),
            }
        }
        result
    }

    /// Escape for URL context
    ///
    /// # Note
    ///
    /// For production use, consider using a URL encoding library
    pub fn escape_url(input: &str) -> String {
        // Simple URL encoding implementation
        input
            .chars()
            .map(|c| match c {
                'A'..='Z' | 'a'..='z' | '0'..='9' | '-' | '_' | '.' | '~' => c.to_string(),
                ' ' => "+".to_string(),
                _ => format!("%{:02X}", c as u8),
            })
            .collect()
    }

    /// Escape for JavaScript string context
    pub fn escape_js(input: &str) -> String {
        input
            .replace('\\', "\\\\")
            .replace('"', "\\\"")
            .replace('\'', "\\'")
            .replace('\n', "\\n")
            .replace('\r', "\\r")
            .replace('\t', "\\t")
            .replace('<', "\\x3C")
            .replace('>', "\\x3E")
    }
}

// Tera filter functions

fn escape_html_filter(value: &Value, _args: &HashMap<String, Value>) -> tera::Result<Value> {
    match value {
        Value::String(s) => Ok(Value::String(ContextEscaper::escape_html(s))),
        _ => Ok(value.clone()),
    }
}

fn escape_sql_filter(value: &Value, _args: &HashMap<String, Value>) -> tera::Result<Value> {
    match value {
        Value::String(s) => Ok(Value::String(ContextEscaper::escape_sql(s))),
        _ => Ok(value.clone()),
    }
}

fn escape_shell_filter(value: &Value, _args: &HashMap<String, Value>) -> tera::Result<Value> {
    match value {
        Value::String(s) => Ok(Value::String(ContextEscaper::escape_shell(s))),
        _ => Ok(value.clone()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // === Template Size Validation Tests ===

    #[test]
    fn test_template_size_validation_valid() {
        let sandbox = SecureTeraEnvironment::new();
        let small_template = "Hello {{ name }}!";
        assert!(sandbox.validate_size(small_template).is_ok());
    }

    #[test]
    fn test_template_size_validation_too_large() {
        let sandbox = SecureTeraEnvironment::new();
        let large_template = "a".repeat(MAX_TEMPLATE_SIZE + 1);
        let result = sandbox.validate_size(&large_template);
        assert!(result.is_err());
    }

    #[test]
    fn test_custom_max_size() {
        let sandbox = SecureTeraEnvironment::new().with_max_size(100);
        let template = "a".repeat(101);
        assert!(sandbox.validate_size(&template).is_err());
    }

    // === Variable Name Validation Tests ===

    #[test]
    fn test_valid_variable_names() {
        assert!(TemplateValidator::validate_variable_name("user_name").is_ok());
        assert!(TemplateValidator::validate_variable_name("count_123").is_ok());
        assert!(TemplateValidator::validate_variable_name("_private").is_ok());
        assert!(TemplateValidator::validate_variable_name("CamelCase").is_ok());
        assert!(TemplateValidator::validate_variable_name("snake_case_123").is_ok());
    }

    #[test]
    fn test_invalid_variable_names() {
        // Empty name
        assert!(TemplateValidator::validate_variable_name("").is_err());

        // Special characters
        assert!(TemplateValidator::validate_variable_name("user.name").is_err());
        assert!(TemplateValidator::validate_variable_name("user[0]").is_err());
        assert!(TemplateValidator::validate_variable_name("user-name").is_err());
        assert!(TemplateValidator::validate_variable_name("user@host").is_err());

        // Path traversal attempts
        assert!(TemplateValidator::validate_variable_name("../etc/passwd").is_err());
        assert!(TemplateValidator::validate_variable_name("..\\windows").is_err());

        // Starts with number
        assert!(TemplateValidator::validate_variable_name("123abc").is_err());

        // Too long
        let long_name = "a".repeat(MAX_VARIABLE_NAME_LENGTH + 1);
        assert!(TemplateValidator::validate_variable_name(&long_name).is_err());
    }

    // === Forbidden Pattern Detection Tests ===

    #[test]
    fn test_forbidden_patterns_detected() {
        let sandbox = SecureTeraEnvironment::new();

        // File access attempts
        assert!(sandbox
            .check_forbidden_patterns("{{ include_raw('secret.txt') }}")
            .is_err());
        assert!(sandbox
            .check_forbidden_patterns("{{ read_file('/etc/passwd') }}")
            .is_err());

        // Network access attempts
        assert!(sandbox
            .check_forbidden_patterns("{{ http('evil.com') }}")
            .is_err());

        // Shell execution attempts
        assert!(sandbox
            .check_forbidden_patterns("{{ exec('rm -rf /') }}")
            .is_err());

        // Path traversal
        assert!(sandbox
            .check_forbidden_patterns("../../../etc/passwd")
            .is_err());
    }

    #[test]
    fn test_safe_patterns_allowed() {
        let sandbox = SecureTeraEnvironment::new();

        // Normal template operations
        assert!(sandbox
            .check_forbidden_patterns("Hello {{ name | upper }}!")
            .is_ok());
        assert!(sandbox
            .check_forbidden_patterns("{{ items | length }}")
            .is_ok());
    }

    // === Include Validation Tests ===

    #[test]
    fn test_include_path_traversal_detection() {
        let sandbox = SecureTeraEnvironment::new();

        // Path traversal in include
        assert!(sandbox
            .validate_includes("{% include '../../../etc/passwd' %}")
            .is_err());

        // Safe include
        assert!(sandbox
            .validate_includes("{% include 'header.html' %}")
            .is_ok());
    }

    // === Function Whitelist Tests ===

    #[test]
    fn test_allowed_functions() {
        let sandbox = SecureTeraEnvironment::new();

        // String functions
        assert!(sandbox.is_function_allowed("upper"));
        assert!(sandbox.is_function_allowed("lower"));
        assert!(sandbox.is_function_allowed("trim"));

        // Math functions
        assert!(sandbox.is_function_allowed("round"));
        assert!(sandbox.is_function_allowed("abs"));

        // Collection functions
        assert!(sandbox.is_function_allowed("length"));
        assert!(sandbox.is_function_allowed("first"));

        // Security filters
        assert!(sandbox.is_function_allowed("escape_html"));
        assert!(sandbox.is_function_allowed("escape_sql"));
        assert!(sandbox.is_function_allowed("escape_shell"));
    }

    #[test]
    fn test_forbidden_functions() {
        let sandbox = SecureTeraEnvironment::new();

        // These should NOT be in whitelist
        assert!(!sandbox.is_function_allowed("include_raw"));
        assert!(!sandbox.is_function_allowed("read_file"));
        assert!(!sandbox.is_function_allowed("http"));
        assert!(!sandbox.is_function_allowed("exec"));
    }

    // === HTML Escaping Tests ===

    #[test]
    fn test_escape_html_basic() {
        let input = "<script>alert('xss')</script>";
        let escaped = ContextEscaper::escape_html(input);
        assert_eq!(
            escaped,
            "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;&#x2F;script&gt;"
        );
    }

    #[test]
    fn test_escape_html_all_chars() {
        assert_eq!(ContextEscaper::escape_html("&"), "&amp;");
        assert_eq!(ContextEscaper::escape_html("<"), "&lt;");
        assert_eq!(ContextEscaper::escape_html(">"), "&gt;");
        assert_eq!(ContextEscaper::escape_html("\""), "&quot;");
        assert_eq!(ContextEscaper::escape_html("'"), "&#x27;");
        assert_eq!(ContextEscaper::escape_html("/"), "&#x2F;");
    }

    #[test]
    fn test_escape_html_complex() {
        let input = "<div onclick=\"alert('xss')\" data-value='test'>";
        let escaped = ContextEscaper::escape_html(input);
        assert!(!escaped.contains('<'));
        assert!(!escaped.contains('>'));
        assert!(!escaped.contains('"'));
        assert!(!escaped.contains('\''));
    }

    // === SQL Escaping Tests ===

    #[test]
    #[ignore = "Test expectation contradicts test_escape_sql_multiple_quotes: standard SQL escaping doubles single quotes ('' not '''), making these two tests mutually exclusive. The multiple-quotes test is correct per SQL standard."]
    fn test_escape_sql_basic() {
        let input = "'; DROP TABLE users; --";
        let escaped = ContextEscaper::escape_sql(input);
        assert_eq!(escaped, "'''; DROP TABLE users; --");
    }

    #[test]
    fn test_escape_sql_multiple_quotes() {
        let input = "O'Reilly's book";
        let escaped = ContextEscaper::escape_sql(input);
        assert_eq!(escaped, "O''Reilly''s book");
    }

    #[test]
    fn test_escape_sql_no_quotes() {
        let input = "normal text";
        let escaped = ContextEscaper::escape_sql(input);
        assert_eq!(escaped, "normal text");
    }

    // === Shell Escaping Tests ===

    #[test]
    fn test_escape_shell_basic() {
        let input = "file.txt; rm -rf /";
        let escaped = ContextEscaper::escape_shell(input);
        assert_eq!(escaped, "file.txt\\;\\ rm\\ -rf\\ /");
    }

    #[test]
    fn test_escape_shell_metacharacters() {
        assert!(ContextEscaper::escape_shell("$VAR").contains("\\$"));
        assert!(ContextEscaper::escape_shell("`cmd`").contains("\\`"));
        assert!(ContextEscaper::escape_shell("a & b").contains("\\&"));
        assert!(ContextEscaper::escape_shell("a | b").contains("\\|"));
        assert!(ContextEscaper::escape_shell("a; b").contains("\\;"));
    }

    #[test]
    #[ignore = "Logically impossible: assert!(!escaped.contains('$')) and assert!(escaped.contains(\"\\\\$\")) are contradictory — '\\$' always contains '$'. The escape_shell function correctly escapes '$' as '\\$'; the test assertions are mutually exclusive."]
    fn test_escape_shell_complex() {
        let input = "$(whoami) && echo 'pwned'";
        let escaped = ContextEscaper::escape_shell(input);
        assert!(!escaped.contains('$'));
        assert!(escaped.contains("\\$"));
    }

    // === Integration Tests ===

    #[test]
    fn test_sandbox_render_safe_simple() {
        let sandbox = SecureTeraEnvironment::new();
        let mut context = Context::new();
        context.insert("name", &"World");

        let template = "Hello {{ name }}!";
        let result = sandbox.render_safe(template, &context);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), "Hello World!");
    }

    #[test]
    fn test_sandbox_reject_dangerous_template() {
        let sandbox = SecureTeraEnvironment::new();
        let context = Context::new();

        // Attempt to include file
        let template = "{{ read_file('/etc/passwd') }}";
        let result = sandbox.render_safe(template, &context);
        assert!(result.is_err());
    }

    #[test]
    fn test_full_validation_workflow() {
        let sandbox = SecureTeraEnvironment::new();

        // Valid template
        let valid_template = "Hello {{ user_name | upper }}!";
        assert!(sandbox.validate_template(valid_template).is_ok());

        // Too large template
        let large_template = "a".repeat(MAX_TEMPLATE_SIZE + 1);
        assert!(sandbox.validate_template(&large_template).is_err());

        // Forbidden pattern
        let dangerous_template = "{{ exec('rm -rf /') }}";
        assert!(sandbox.validate_template(dangerous_template).is_err());

        // Path traversal
        let traversal_template = "{% include '../../../etc/passwd' %}";
        assert!(sandbox.validate_template(traversal_template).is_err());
    }
}