libauthcekunit 2.0.3

Super robust CSRF token extractor with configurable retry, logging, and strict validation
Documentation

libauthcekunit

Super robust, secure, and RFC‑compliant CSRF token extractor & authentication library for Rust – with configurable retry, structured logging, full cookie handling, and C FFI support.

Table of Contents

Overview

libauthcekunit is a Rust library that automates the process of logging into a web application that uses CSRF protection (like Laravel), extracting the CSRF token, managing cookies strictly according to RFC 6265, and exposing the functionality both as a high‑level Rust API and a C‑compatible FFI.

It is built for robustness and security:

  • All HTTP requests are retried with exponential backoff on transient errors.
  • Cookies are parsed, stored, and matched following RFC 6265 (domain, path, expiration, secure, same‑site).
  • CSRF tokens are validated against configurable length and character‑set rules.
  • No sensitive data (tokens, passwords) ever appears in log output.
  • After login, the session is verified by accessing a protected page (configurable).

The library provides a CookieJar that can be serialised to/from JSON, making it easy to persist sessions across program restarts.

Features

  • CSRF‑aware login/logout – automatically handles _token extraction and submission.
  • Strict cookie handling – RFC 6265 domain/path matching, expiration, secure flag, SameSite.
  • Exponential backoff retry – for network errors and server errors (5xx).
  • Configurable via environment variables – timeouts, retries, user agent, credentials, etc.
  • Structured logging using tracing – log level controlled by RUST_LOG.
  • Session verification after login – checks for a configurable string on a protected page.
  • C FFI bindings – usable from C, C++, Python ctypes, or any language with C interop.
  • Serializable CookieJar – save/load sessions to JSON files.
  • Multi‑platform – Linux, macOS, Windows (with proper TLS backend). -[x] Zero‑cost abstractions – efficient, no unsafe code except minimal FFI glue.

Installation

For Rust projects

Add this to your Cargo.toml:

[dependencies]
libauthcekunit = "2.0.0"

By default, it uses rustls for TLS. If you prefer native‑tls (OpenSSL), enable the feature:

libauthcekunit = { version = "2.0.0", default-features = false, features = ["native-tls"] }

For C projects

Clone the repository and build:

git clone https://github.com/neuxdotdev/libauthcekunit.git
cd libauthcekunit
make all        # builds static and shared library, generates C header
sudo make install   # installs to /usr/local by default

The header libauthcekunit.h and the libraries will be placed in $PREFIX/include and $PREFIX/lib.

Quick Start

Rust library usage

use libauthcekunit::{login, logout, fetch_token, CookieJar, init_logging};

// (Optional) initialise logging once
init_logging();

// Set required environment variables, or use .env file
let base_url = "https://example.com";

// Login – returns a CookieJar with the session
let jar: CookieJar = login(base_url).expect("Login failed");

// The jar can be used for further authenticated requests
// ... use jar with `RobustHttpClient` or your own HTTP client

// Save session to file for later reuse
jar.save_to_file("session.json").unwrap();

// Later, load the jar back
let jar = CookieJar::load_from_file("session.json").unwrap();

// Logout (destroys server session, but returns updated jar)
let final_jar = logout(base_url, &jar).expect("Logout failed");

If you only need the CSRF token from a page (no login):

let token = libauthcekunit::fetch_token("https://example.com/login").unwrap();
println!("CSRF token: {}", token);

C FFI usage

#include "libauthcekunit.h"
#include <stdio.h>

int main() {
    libauthcekunit_init_logging();

    // Login
    CookieJarHandle* jar = libauthcekunit_login("https://example.com");
    if (jar == NULL) {
        fprintf(stderr, "Login failed\n");
        return 1;
    }

    // Fetch a CSRF token from a page
    char token[256];
    if (libauthcekunit_fetch_token("https://example.com/form", token, sizeof(token))) {
        printf("Token: %s\n", token);
    }

    // Extract token from raw HTML
    const char* html = "<input name=\"_token\" value=\"abc123\">";
    char extracted[64];
    if (libauthcekunit_extract_token(html, extracted, sizeof(extracted))) {
        printf("Extracted: %s\n", extracted);
    }

    // Logout (consumes jar handle)
    int result = libauthcekunit_logout(jar, "https://example.com");
    // jar is now invalid; do not use it again

    // Or free the jar without logout
    // libauthcekunit_free_jar(jar);

    return 0;
}

Compile & link:

gcc -o myapp myapp.c -L/usr/local/lib -lauthcekunit -lpthread -ldl -lm

Environment Variables Configuration

All configuration is done via environment variables (or a .env file loaded automatically by dotenv).
Prefix: LIB_CEKUNIT_AUTH_ENV_.

Complete list of env vars

Variable Type Default Description
LIB_CEKUNIT_AUTH_ENV_TIMEOUT_SECS u64 30 Per‑request timeout (seconds).
LIB_CEKUNIT_AUTH_ENV_MAX_RETRIES u32 3 Maximum number of retry attempts (including the first).
LIB_CEKUNIT_AUTH_ENV_RETRY_INITIAL_MS u64 500 Initial backoff delay in milliseconds.
LIB_CEKUNIT_AUTH_ENV_MAX_REDIRECTS u32 5 Maximum redirects to follow.
LIB_CEKUNIT_AUTH_ENV_FOLLOW_REDIRECTS bool true Whether to follow redirects.
LIB_CEKUNIT_AUTH_ENV_TOKEN_MIN_LEN usize 10 Minimum allowed CSRF token length.
LIB_CEKUNIT_AUTH_ENV_TOKEN_MAX_LEN usize 1024 Maximum allowed CSRF token length.
RUST_LOG string "info" Log level (trace, debug, info, warn, error).
LIB_CEKUNIT_AUTH_ENV_USER_AGENT string "LIB_CEKUNIT_AUTH_ENVUnit/2.0" User‑Agent header for HTTP requests.
LIB_CEKUNIT_AUTH_ENV_EMAIL string "" Email/username for login.
LIB_CEKUNIT_AUTH_ENV_PASSWORD string "" Password for login.
LIB_CEKUNIT_AUTH_ENV_LOGIN_VERIFY_URL string "/dashboard" Relative URL of a protected page used to verify login success.
LIB_CEKUNIT_AUTH_ENV_LOGIN_VERIFY_TEXT string "" (Optional) Text that must appear on the verification page. If empty, verification just checks that the page is reachable.
LIB_CEKUNIT_AUTH_ENV_ENV_PATH string – Path to a .env file (if not in current directory).

Example .env file

LIB_CEKUNIT_AUTH_ENV_EMAIL=admin@example.com
LIB_CEKUNIT_AUTH_ENV_PASSWORD=secret
LIB_CEKUNIT_AUTH_ENV_TIMEOUT_SECS=60
LIB_CEKUNIT_AUTH_ENV_MAX_RETRIES=5
RUST_LOG=libauthcekunit=debug

Library API Reference

Module auth

pub fn login(base_url: &str) -> Result<CookieJar>

Performs login:

  1. Fetches the login page, extracts the CSRF token.
  2. Submits the login form using credentials from environment variables.
  3. Verifies the session by accessing the configured login_verify_url.
  4. Returns the session CookieJar.

Returns Err(AuthError::Config(...)) if email/password are missing, Err(AuthError::LoginFailed(...)) if the verification step fails.

pub fn logout(base_url: &str, cookie_jar: &CookieJar) -> Result<CookieJar>

Logs out by fetching the dashboard (to get a CSRF token), then posting to /logout. Returns the final cookie jar (which typically has the session cookie cleared).

Module cookies

pub struct Cookie

A parsed cookie with all RFC attributes.

Field Type Description
name String Cookie name.
value String Cookie value.
domain Option<String> Domain scope (defaults to request host).
path Option<String> Path scope (defaults to request path directory).
expires Option<SystemTime> Expiration time (UTC).
secure bool Send only over HTTPS.
http_only bool Not accessible via JavaScript.
same_site Option<String> Strict, Lax, or None.

Methods:

  • from_set_cookie(header: &str, request_url: &Url) -> Option<Cookie> – parses a Set‑Cookie header, returns None if expired or malformed.
  • matches(&self, url: &Url) -> bool – tests if this cookie should be sent to the given URL (domain, path, secure, expiry).
  • to_header(&self) -> String – returns name=value for a Cookie header.

pub struct CookieJar

A collection of cookies, stored by name (one per name).

Methods:

  • new() -> Self
  • add_from_set_cookie(&mut self, header: &str, url: &Url) – parses and inserts a cookie.
  • get_cookies_for_url(&self, url: &Url) -> Vec<&Cookie> – returns cookies that match the URL.
  • cookie_header(&self, url: &Url) -> String – builds the Cookie header value.
  • load_from_file(path: &str) -> io::Result<Self> – loads from JSON, discarding expired cookies.
  • save_to_file(&self, path: &str) -> io::Result<()> – serialises to JSON.
  • clear_expired(&mut self) – removes all expired cookies.
  • len(&self) -> usize, is_empty(&self) -> bool

Note: The jar stores only the most recent cookie for a given name. This is sufficient for typical session handling but does not support multiple cookies with the same name from different domains/paths.

Module client

pub struct RobustHttpClient

A synchronous HTTP client built on reqwest, with automatic retry and cookie handling.

Methods:

  • new() -> Result<Self> – creates client using global CONFIG.
  • get(&self, url: &str, cookies: &CookieJar) -> Result<(String, CookieJar)> – performs GET, returns body and updated jar.
  • post_form(&self, url: &str, params: &[(&str, &str)], cookies: &CookieJar) -> Result<(String, CookieJar)> – performs POST with application/x-www-form-urlencoded body.

Both methods implement retry with exponential backoff on server errors (5xx) and network failures. Client errors (4xx) are not retried.

Module parser

pub fn extract_token(html: &str) -> Result<String>

Extracts a CSRF token from HTML. It first tries a regex pattern searching for name="_token" value="...", then falls back to a manual scan. The token is validated for length and allowed characters.

Module config

pub static CONFIG: Lazy<Config>

Global configuration object, initialised once from environment variables.

pub struct Config

Fields (all public):

  • request_timeout_secs: u64
  • max_retries: u32
  • retry_initial_interval_ms: u64
  • max_redirects: u32
  • follow_redirects: bool
  • token_min_length: usize
  • token_max_length: usize
  • log_level: String
  • user_agent: String
  • email: String
  • password: String
  • login_verify_url: String
  • login_verify_text: String

Module error

pub enum AuthError

Variant Description
Http(reqwest::Error) Underlying HTTP client error.
UrlParse(url::ParseError) URL parse error.
TokenNotFound CSRF token not found in HTML.
TokenInvalid { reason } Token fails validation (length, charset).
Config(String) Configuration error.
Io(std::io::Error) Filesystem I/O error.
Regex(regex::Error) Regular expression compilation error.
MaxRetriesExceeded All retry attempts exhausted.
HttpStatus(u16) Non‑success HTTP status (4xx).
LoginFailed(String) Session verification after login failed.

pub type Result<T> = std::result::Result<T, AuthError>;

Module types

pub struct CsrfToken

  • value: String
  • source_url: String
  • extracted_at: SystemTime

pub struct FetchOptions

(Currently not used by high‑level functions, but available for future use or custom client configuration.)

  • timeout_secs: u64
  • max_retries: u32
  • retry_initial_interval_ms: u64
  • follow_redirects: bool
  • max_redirects: u32

Module logging

pub fn init_logging()

Initialises the tracing subscriber (once). Uses the RUST_LOG environment variable.

High‑level functions

These are convenience wrappers exposed directly in lib.rs:

pub fn fetch_token_and_cookies(url: &str) -> Result<(String, CookieJar)>

Fetches a page, extracts the CSRF token, and returns the token together with all Set‑Cookie cookies in a new CookieJar.

pub fn fetch_token(url: &str) -> Result<String>

Like above, but returns only the token.

pub fn fetch_cookies(url: &str) -> Result<CookieJar>

Like above, but returns only the jar.

Security note: The token content is not printed to logs; only its length is recorded in debug mode.

Retry & Resilience Architecture

The RobustHttpClient employs exponential backoff for transient failures:

  • Initial backoff: CONFIG.retry_initial_interval_ms (default 500 ms)
  • Max interval: 5 s
  • Max total elapsed time: request_timeout_secs * max_retries
  • Retries are triggered on: network errors (connection refused, timeouts, etc.) and server errors (5xx responses).
  • Client errors (4xx) are immediately returned as AuthError::HttpStatus.
  • If all retries fail, AuthError::MaxRetriesExceeded is returned.

The backoff parameters are all configurable via environment variables.

Cookie Handling (RFC 6265)

The cookie module implements RFC 6265 strictly, ensuring secure and correct session management.

  • Domain matching: example.com matches example.com and *.example.com; a leading dot is stripped on input.
  • Path matching: /foo matches /foo, /foo/, /foo/bar, but not /foobar.
  • Expiration: Cookies are rejected at parse time if already expired, and again at every matches() call. clear_expired() removes them from the jar.
  • Secure flag: Cookies marked Secure are only sent over HTTPS.
  • SameSite: Parsed and stored, but not enforced by the library (it assumes the caller respects it).
  • Serialization: Cookie jars are serialized to JSON, and expired cookies are purged automatically when loaded.

The implementation has been audited and covers edge cases like default path derivation from the request URL.

CSRF Token Extraction

The parser searches for the standard Laravel pattern:

<input type="hidden" name="_token" value="randomtoken" />

It uses a regex designed to handle both ' and " quotes, and falls back to a manual scan if the regex fails. The extracted token is then validated:

  • Length must be between token_min_length and token_max_length (configurable).
  • Characters must be alphanumeric, or one of _, -, +, =, / (base64url characters).
  • No token content is ever printed in logs – only the token length appears in debug logs.

Logging & Debugging

The library uses the tracing ecosystem. Log output is controlled by the RUST_LOG environment variable. Example:

RUST_LOG=libauthcekunit=debug cargo run

Important debug events include:

  • HTTP request/response summaries (status, body length)
  • Cookie additions and expirations
  • Retry attempts and backoff durations
  • Token extraction steps (regex hit, manual fallback)

All sensitive data (tokens, credentials) is omitted from log lines.

C Foreign Function Interface (FFI)

The library can be compiled as a C dynamic/shared library (cdylib) and a static library (staticlib). All functions are marked #[no_mangle] and extern "C", and use only C‑compatible types.

Header generation

A C header can be generated using cbindgen:

make header   # requires cbindgen installed

Function list

Function Description
void libauthcekunit_init_logging(void) Initialise logging (needed only once).
CookieJarHandle* libauthcekunit_login(const char* base_url) Login, returns a handle to the session jar (or NULL on error).
int libauthcekunit_logout(CookieJarHandle* handle, const char* base_url) Logout, consumes the handle (do not use it afterwards). Returns 0 on success.
void libauthcekunit_free_jar(CookieJarHandle* handle) Free a jar handle without logging out.
size_t libauthcekunit_fetch_token(const char* url, char* out, size_t out_size) Fetch token, writes to out including null terminator; returns bytes written (0 on error).
int libauthcekunit_fetch_cookies(const char* url, const char* file_path) Fetch cookies and save directly to a JSON file.
size_t libauthcekunit_extract_token(const char* html, char* out, size_t out_size) Extract token from HTML string.
const char* libauthcekunit_get_email(void) Returns pointer to configured email (static lifetime).
const char* libauthcekunit_get_user_agent(void) Returns pointer to configured user agent (static lifetime).

Memory model & ownership

  • libauthcekunit_login returns a CookieJarHandle* that must be either passed to libauthcekunit_logout (which frees it) or explicitly freed with libauthcekunit_free_jar.
  • libauthcekunit_logout consumes the handle – after this call the pointer becomes invalid.
  • Strings returned by get_email / get_user_agent point to static memory and must not be freed.

Makefile Usage

The included Makefile provides common tasks:

make all              # Build static, shared, header
make static           # Build static library (.a)
make dynamic          # Build shared library (.so)
make header           # Generate C header
make test             # Build and run static test (loads .env)
make test-dyn         # Build and run dynamic test
make install          # Install to /usr/local (prefix can be changed)
make uninstall        # Remove installed files
make clean            # Clean build artifacts

Set INSTALL_PREFIX to change installation path:

make install INSTALL_PREFIX=/usr

Project Structure

libauthcekunit/
├── Cargo.toml
├── Cargo.lock
├── Makefile
├── LICENSE
├── README.md
└── src/
    ├── lib.rs          # Public API and re-exports
    ├── auth.rs         # Login / logout logic
    ├── client.rs       # Robust HTTP client with retry
    ├── config.rs       # Configuration from environment
    ├── cookies.rs      # Cookie and CookieJar (RFC 6265)
    ├── error.rs        # Error types
    ├── ffi.rs          # C bindings
    ├── logging.rs      # Tracing initialisation
    ├── parser.rs       # CSRF token extraction
    └── types.rs        # Shared types

Development & Contributing

  1. Clone the repository:

    git clone https://github.com/neuxdotdev/libauthcekunit.git
cd libauthcekunit

  2. Build and test:

    cargo build
cargo test

  3. Run the test suite with environment variables:

    cp .env.example .env   # edit .env with test credentials
cargo test

  4. Build C libraries and header:

    make all

  5. Linting and formatting:

    cargo clippy --all-targets --all-features
cargo fmt --all -- --check

Contribution Guidelines

  • Follow Conventional Commits.
  • Add tests for new features.
  • Ensure cargo test passes and cargo clippy is clean.
  • For changes to the FFI, update the header with make header and test the C example.

FAQ

Q: Why build a custom cookie jar instead of using reqwest's built‑in one?
A: reqwest's cookie store is tied to its async runtime and not as strict about RFC 6265 validation. Our jar gives us full control over parsing, matching, and serialisation, plus it works seamlessly with the C FFI.

Q: Can I use this library with async Rust?
A: The current API is synchronous (blocking). For async use, you would need to wrap the calls with tokio::task::spawn_blocking or use an async version of the client. An async feature may be added in the future.

Q: How do I handle websites that use a different CSRF token field name?
A: The parser specifically looks for name="_token". You can customise the regex in parser.rs or use extract_token on raw HTML after a custom extraction step.

Q: Is the library thread‑safe?
A: Yes. All public types are Send + Sync, and the CONFIG is initialised once via Lazy.

Q: The login verifier fails, but I know the credentials are correct. Why?
A: Set LIB_CEKUNIT_AUTH_ENV_LOGIN_VERIFY_TEXT to the empty string to disable text matching. Some sites redirect after login, and the verification URL might not contain the expected text. Adjust LOGIN_VERIFY_URL to point to a static page (e.g., /profile).

License

This project is licensed under the MIT License. See the LICENSE file for details.