Token Class

Security Token (CSRF Protection) Class

---

The Token class is a critical security layer in GeniXCMS designed to prevent Cross-Site Request Forgery (CSRF) attacks. Recently redesigned for maximum reliability, it utilizes a One-Token-Per-Session model that provides robust security without sacrificing usability, especially during deep AJAX operations (like the elFinder media manager).

---

🛡️ Core Protection Architecture (Session-Based)

GeniXCMS implements a robust Session-Paired token strategy.

1. Persistent Session Token: Upon initialization, the system generates a single, secure 20-character token that persists across the user's active session. This eliminates race conditions caused by rapid AJAX requests.
2. Global Constant: The active token is assigned to the TOKEN global constant.
3. Security Fingerprinting (Pairing): Instead of locking a token to a specific URL (which creates issues in dynamic SPAs and background uploads), the token is cryptographically bound to the user's Context Fingerprint, which combines:
   • User IP Address
   • Browser User-Agent
   • SITE_ID

If the token is leaked but the attacker is on a different network or uses a different browser, the validation fails.

---

⚡ Technical Methods

Token::create()

Initializes or retrieves the persistent session token.

• Process: Checks if $_SESSION['gx_token'] exists. If not, it creates a new 20-character random string and generates a Context Fingerprint using Token::pairing().
• Self-Healing AI: If an incoming request provides a valid token within the query string (especially for AJAX routes) and the session is unexpectedly empty, the engine will "adopt" that token to preserve application state.
• Returns: The string value of the active token.

Token::validate(string $token, bool $is_ajax = false) (also Token::isValid())

The primary validation method for incoming state changes.

• Verification: It compares the provided string strictly against $_SESSION['gx_token'].
• Fallback Promotion: If the system detects a legacy array-based token, it handles validation and "promotes" the token to the primary session scope, cleaning up old data arrays.
• Returns: bool (True if the handshake matches).

Token::pairing()

Generates the cryptographic context fingerprint.

• Returns: An MD5 hash of User IP + User Agent + SITE_ID.

---

🎨 Form Implementation Pattern

To secure any HTML form, include the token as a hidden input field.

Frontend (HTML)

<form action="save_profile.php" method="POST">
    <!-- CSRF Protection Field -->
    <input type="hidden" name="token" value="<?= TOKEN; ?>">

    <label>Username</label>
    <input type="text" name="username">
    <button type="submit">Save Changes</button>
</form>

Backend (PHP Controller)

if (Http::isPost()) {
    if (!Token::isValid($_POST['token'])) {
        // Log potential attack and terminate
        die("Security Breach Detected: Invalid CSRF Token.");
    }
    // Proceed with safe processing...
}

---

🔒 Deep AJAX Considerations

When building custom module interfaces using raw AJAX (e.g., File Uploads), GeniXCMS natively allows for tokens to be transmitted directly within the URL route if configured correctly.

Using the Url::ajax() helper automatically formats the token. Example: Url::ajax('elfinder/' . Token::create()) translates to http://domain.com/ajax/elfinder/[token_hash].

The Token system will automatically intercept this segment during boot sequences, ensuring controllers like elFinder instantly recognize the session without requiring the token in POST body payloads.

---

See Also

• Http Class — Handling request methods (POST/GET).
• Security Infrastructure — Managing global security policies.