authjar — Multi-cookie session management for HTTP clients and security tools

Why This Exists

Web security tools need to manage multiple authenticated sessions—admin accounts, regular users, different tenants. Cookie jars need proper domain scoping, subdomain matching, and secure flag handling. CSRF tokens need extraction from HTML, headers, and cookies, then injection into requests. This crate handles it all.

Quick Start

use authjar::{AuthSession, SessionStore, SessionSettings, Cookie, CsrfSource, extract_csrf_tokens, inject_csrf_token};

// Create a session and add cookies
let mut session = AuthSession::new("admin");
session.add_cookie("PHPSESSID", "abc123", "example.com");
session.add_cookie("auth_token", "xyz789", "example.com");

// Generate Cookie header for a request
let cookie_header = session.cookie_header("example.com");
assert!(cookie_header.contains("PHPSESSID=abc123"));

// Parse cookies from Set-Cookie headers
let mut session = AuthSession::new("user");
session.add_set_cookie("session=def456; Path=/; HttpOnly; Secure", "api.example.com");

// Multi-session management with persistence
let mut store = SessionStore::new();
store.add(session);

// Save and load sessions
store.save_to_file("sessions.json").unwrap();
let loaded = SessionStore::load_from_file("sessions.json").unwrap();

// Extract CSRF tokens from responses
let html = r#"<meta name="csrf-token" content="token-123">"#;
let headers = vec![("X-CSRF-Token".to_string(), "token-456".to_string())];
let cookies = vec![("XSRF-TOKEN".to_string(), "token-789".to_string())];

let tokens = extract_csrf_tokens(html, &headers, &cookies);
for token in tokens {
    let (header_name, value) = inject_csrf_token(&token);
    println!("Add header: {}: {}", header_name, value);
}

Features

• Domain-scoped cookies — Proper subdomain matching with opt-out
• Path matching — Prefix-based path scoping (RFC-compliant)
• Security flags — Secure and HttpOnly flag enforcement
• Set-Cookie parsing — Full parser for Set-Cookie header lines
• Multi-session store — Named sessions for different users/roles
• JSON persistence — Save/load session state across runs
• TOML configuration — Externalize session settings
• CSRF extraction — Find tokens in HTML meta tags, forms, headers, and cookies
• CSRF injection — Proper header/form field injection based on token source

Configuration

# authjar.toml
[session]
default_domain = "example.com"
default_path = "/api"
match_subdomains = true

use authjar::SessionSettings;

// Load from TOML file
let settings = SessionSettings::from_toml_file("authjar.toml")?;

// Or create programmatically
let settings = SessionSettings {
    default_domain: Some("example.com".to_string()),
    default_path: "/".to_string(),
    match_subdomains: true,
};

// Use with session store
let store = SessionStore::with_settings(settings);

API Overview

Type	Purpose
AuthSession	Named session with cookie jar
Cookie	Individual cookie with name, value, domain, path, flags
SessionStore	Multi-session persistence container
SessionSettings	Domain matching, default paths, subdomain behavior
AuthJarError	I/O, JSON, and TOML error types
CsrfToken	Discovered token with source and field name
CsrfSource	HtmlTag, Header, or Cookie
extract_csrf_tokens()	Extract tokens from HTML, headers, cookies
inject_csrf_token()	Get proper header/form for request injection

License

MIT — Copyright (c) 2024 CORUM COLLECTIVE LLC

See LICENSE for details.

---

• crates.io/crates/authjar
• docs.rs/authjar