EoNy (diff) - SQLite Testing

Difference between revisions for Users / Eo Ny

Version1		Version2
1	((user:EoNy EoNy)) (05.05.2026 16:15)	1	# Session Management Technical Documentation
		2
		3	## Overview
		4
		5	The `Session` class is an abstract session management system for WackoWiki that extends `ArrayObject` to provide secure, configurable session handling. It implements sophisticated security features including session ID regeneration, anti-replay protection, nonce verification, and user agent/IP validation.
		6
		7	Location: `src/class/session.php`
		8	Type: Abstract class (must be extended with a `SessionStoreInterface` implementation)
		9	Inheritance: `ArrayObject`
		10
		11	---
		12
		13	## Table of Contents
		14
		15	1. [Core Concepts](#core-concepts)
		16	2. [Architecture](#architecture)
		17	3. [Configuration](#configuration)
		18	4. [Usage](#usage)
		19	5. [Security Features](#security-features)
		20	6. [API Reference](#api-reference)
		21	7. [Session Lifecycle](#session-lifecycle)
		22	8. [Flash Data](#flash-data)
		23	9. [Nonce System](#nonce-system)
		24	10. [Cookie Management](#cookie-management)
		25	11. [Error Handling](#error-handling)
		26	12. [Implementation Guide](#implementation-guide)
		27
		28	---
		29
		30	## Core Concepts
		31
		32	### Session State
		33	The Session class maintains three primary states:
		34
		35	- Inactive (`$active = false`): Session not yet started or has been closed
		36	- Active (`$active = true`): Session is running and can store/retrieve data
		37	- Regenerated: Session ID has been replaced (tracked via `$regenerated` flag)
		38
		39	### Session Data Storage
		40	Session data is stored as an array accessible through `ArrayObject` interface:
		41	```php
		42	$session['user_id'] = 123; // Set data
		43	echo $session['user_id']; // Get data
		44	```
		45
		46	### Sticky Data
		47	Variables prefixed with `sticky_` are persistent across session resets:
		48	- `sticky__created`: Session creation timestamp
		49	- `sticky__flash`: Flash data lifetime tracking
		50	- `sticky__log`: Regeneration event log
		51	- `sticky__ip`: IP change tracking
		52
		53	### Internal Tracking Variables
		54	Variables prefixed with `__` are internal session metadata:
		55	- `__started`: Session start time
		56	- `__updated`: Last session update time
		57	- `__regenerated`: Last session ID regeneration time
		58	- `__user_agent`: Client user agent string
		59	- `__user_ip`: Client IP address
		60	- `__user_tls`: TLS/SSL status
		61	- `__nonces`: Active nonce storage
		62	- `__expire`: Session expiration time (for old sessions)
		63
		64	---
		65
		66	## Architecture
		67
		68	### Class Hierarchy
		69	```
		70	ArrayObject (PHP native)
		71	↓
		72	Session (abstract)
		73	↓
		74	[Concrete Implementation] (must implement store_* methods)
		75	```
		76
		77	### Key Methods Categories
		78
		79	Lifecycle Management:
		80	- `__construct()`: Initialize session object
		81	- `start()`: Begin a session
		82	- `write_close()`: Save and close session
		83	- `restart()`: Destroy and restart session
		84	- `terminator()`: Shutdown handler (garbage collection, flash data cleanup)
		85
		86	Security:
		87	- `regenerate_id()`: Replace session ID
		88	- `verify_nonce()`: Validate nonce tokens
		89	- `prevent_replay()`: Anti-replay protection
		90	- `create_nonce()`: Generate nonce tokens
		91
		92	Storage (Abstract - Must Implement):
		93	- `store_open()`: Open session storage
		94	- `store_read()`: Read session data
		95	- `store_write()`: Write session data
		96	- `store_close()`: Close session storage
		97	- `store_gc()`: Garbage collection
		98	- `store_validate_id()`: Validate session ID format
		99	- `store_generate_id()`: Generate new session ID
		100
		101	Cookie Management:
		102	- `setcookie()`: Set HTTP cookie with security headers
		103	- `get_cookie()`: Retrieve cookie value
		104	- `set_cookie()`: Set cookie (legacy interface)
		105	- `delete_cookie()`: Remove cookie
		106	- `send_cookie()`: Internal cookie transmission
		107
		108	---
		109
		110	## Configuration
		111
		112	### Configuration Properties (Public)
		113
		114	All configuration properties are prefixed with `cf_` (config) and can be set before calling `start()`:
		115
		116	#### Session Behavior
		117	```php
		118	$session->cf_static = 0; // Disable regenerations (e.g., for CAPTCHA)
		119	$session->cf_max_session = 7200; // Max session lifetime (seconds)
		120	$session->cf_max_idle = 1440; // Max idle time before destruction (seconds)
		121	$session->cf_regen_time = 500; // Seconds between forced ID regenerations
		122	$session->cf_regen_probability = 2; // Percentage probability of forced regen (0-100)
		123	```
		124
		125	#### Nonce & Replay Protection
		126	```php
		127	$session->cf_secret = 'adyaiD9+255JeiskPybgisby'; // Secret for nonce generation
		128	$session->cf_nonce_lifetime = 7200; // Nonce expiration (seconds)
		129	$session->cf_prevent_replay = 1; // Enable replay attack prevention
		130	```
		131
		132	#### Garbage Collection
		133	```php
		134	$session->cf_gc_probability = 2; // Probability of GC on shutdown (0-100)
		135	$session->cf_gc_maxlifetime = 1440; // Max session file lifetime (seconds)
		136	```
		137
		138	#### Cookie Settings
		139	```php
		140	$session->cf_cookie_prefix = ''; // Prefix for all cookies
		141	$session->cf_cookie_persistent = false; // Make cookies persistent
		142	$session->cf_cookie_lifetime = 0; // Cookie lifetime (0 = session cookie)
		143	$session->cf_cookie_path = '/'; // Cookie path
		144	$session->cf_cookie_domain = ''; // Cookie domain ('' = current host)
		145	$session->cf_cookie_secure = false; // HTTPS only
		146	$session->cf_cookie_httponly = true; // Disable JavaScript access
		147	$session->cf_cookie_samesite = COOKIE_SAMESITE; // SameSite attribute
		148	```
		149
		150	#### Cache Control
		151	```php
		152	$session->cf_cache_limiter = 'none'; // Cache control mode (public\|private\|nocache\|none)
		153	$session->cf_cache_expire = 180*60; // Cache TTL (seconds)
		154	$session->cf_cache_mtime = 0; // Modify time for Last-Modified header
		155	```
		156
		157	#### Security Validation
		158	```php
		159	$session->cf_referer_check = ''; // Check HTTP Referer header
		160	```
		161
		162	#### HTTP Context (Set by HTTP class)
		163	```php
		164	$session->cf_ip; // Client IP address
		165	$session->cf_tls; // TLS/SSL connection indicator
		166	```
		167
		168	---
		169
		170	## Usage
		171
		172	### Basic Session Setup
		173
		174	```php
		175	// Create a concrete session implementation
		176	class MySession extends Session {
		177	// Implement abstract store_* methods
		178	// See "Implementation Guide" section
		179	}
		180
		181	// Initialize and start session
		182	$session = new MySession();
		183	$session->cf_max_session = 3600; // 1 hour
		184	$session->cf_cookie_path = '/';
		185	$session->start('myapp'); // Session name: 'myapp'
		186
		187	// Store data
		188	$session['user_id'] = 42;
		189	$session['username'] = 'john';
		190
		191	// Retrieve data
		192	echo $session['user_id']; // 42
		193
		194	// Check if session is active
		195	if ($session->active()) {
		196	echo "Session is active";
		197	}
		198
		199	// Explicitly save and close
		200	$session->write_close();
		201
		202	// Shutdown handler automatically called via register_shutdown_function()
		203	```
		204
		205	### Session Data Access
		206
		207	```php
		208	// Array-like access (via ArrayObject)
		209	$session['user_id'] = 123;
		210	echo $session['user_id'];
		211	unset($session['user_id']);
		212	isset($session['user_id']);
		213
		214	// Convert to array
		215	$all_data = $session->toArray();
		216	```
		217
		218	### Session ID Management
		219
		220	```php
		221	// Get current session ID
		222	$id = $session->id(); // Returns: e.g., "abc123xyz..."
		223
		224	// Get session name
		225	$name = $session->name(); // Returns: 'myapp'
		226
		227	// Get session ID from request
		228	$session->start('myapp', $_REQUEST['sid'] ?? null);
		229	```
		230
		231	### Session State
		232
		233	```php
		234	// Check if session is active
		235	if ($session->active()) {
		236	// Session is running
		237	}
		238
		239	// Get last state change message
		240	$message = $session->message(); // 'replay', 'ip', 'ua', 'timeout', etc.
		241
		242	// Restart session (destroy old + start new)
		243	$session->restart();
		244	```
		245
		246	---
		247
		248	## Security Features
		249
		250	### 1. Session ID Regeneration
		251
		252	Purpose: Prevent session fixation attacks
		253
		254	Automatic Triggers:
		255	- Initial session creation (`regenerated = 2`)
		256	- First request after creation (`regenerated = 1`)
		257	- Periodic forced regeneration (based on `cf_regen_time` and `cf_regen_probability`)
		258	- Session validation failures
		259
		260	Manual Trigger:
		261	```php
		262	$session->regenerate_id($delete_old = false, $message = 'custom_reason');
		263	```
		264
		265	Parameters:
		266	- `$delete_old`:
		267	- `false` (0): Keep old session active for ~5 seconds (for pending AJAX requests)
		268	- `true` (1): Keep old session for time specified (unused in current code)
		269	- `2`: Immediately destroy old session
		270
		271	Implementation Details:
		272	- New session ID is generated via `store_generate_id()`
		273	- Old session data is copied to new ID
		274	- Old session marked with `__expire` timestamp
		275	- Cookie immediately updated with new ID
		276	- Single regeneration per request (checked via `$this->regenerated` flag)
		277	- Logged in `sticky__log` for debugging (max 15 entries)
		278
		279	```php
		280	// Example: Force regeneration on login
		281	$session->start('myapp');
		282	if ($user_authenticated) {
		283	$session->regenerate_id(false, 'login');
		284	$session['user_id'] = $user->id;
		285	}
		286	```
		287
		288	### 2. User Agent Validation
		289
		290	Purpose: Detect browser/device changes that might indicate hijacking
		291
		292	Behavior:
		293	- Stores user agent on first request
		294	- Compares on subsequent requests using `similar_text()`
		295	- Destroys session if similarity < 95%
		296	- Useful against bot attacks or stolen sessions
		297
		298	Configuration:
		299	```php
		300	// Automatic on each request (if enabled in code logic)
		301	// Triggers session destruction if UA changes significantly
		302	```
		303
		304	### 3. IP Address Validation
		305
		306	Purpose: Detect IP spoofing or hijacking
		307
		308	Behavior:
		309	- Stores IP on first request
		310	- Compares on subsequent requests
		311	- Soft failure on mismatch: `destroy = 1` (keeps regenerating)
		312	- Tracks IP changes in `sticky__ip`
		313
		314	Configuration:
		315	```php
		316	$session->cf_ip = $_SERVER['REMOTE_ADDR']; // Set by HTTP class
		317	// Validation happens automatically during start()
		318	```
		319
		320	IP Change Tracking:
		321	```php
		322	// Access IP change history
		323	$ip_history = $session->sticky__ip; // Array of [ip => change_count]
		324	```
		325
		326	### 4. TLS/SSL Validation
		327
		328	Purpose: Prevent protocol downgrade attacks
		329
		330	Behavior:
		331	- Checks if connection transitioned from HTTPS to HTTP
		332	- Destroys session on mismatch
		333
		334	Configuration:
		335	```php
		336	$session->cf_tls = !empty($_SERVER['HTTPS']); // Set by HTTP class
		337	// Validation happens automatically during start()
		338	```
		339
		340	### 5. Anti-Replay Protection
		341
		342	Purpose: Prevent CSRF and replay attacks
		343
		344	Mechanism:
		345	- Generates unique "NoReplay" nonce on each request
		346	- Cookie-based nonce verification
		347	- Detects rapid-fire requests (AJAX attacks)
		348
		349	Configuration:
		350	```php
		351	$session->cf_prevent_replay = 1; // Enable (default)
		352	$session->cf_prevent_replay = 0; // Disable if needed
		353	```
		354
		355	How It Works:
		356	```
		357	Request 1: Generate nonce, send in cookie
		358	Request 2: Client sends nonce back, verify & generate new one
		359	Request 3: If old nonce used again → reject (replay detected)
		360	```
		361
		362	### 6. Referer Validation (Optional)
		363
		364	Purpose: Prevent CSRF via header checking
		365
		366	Configuration:
		367	```php
		368	$session->cf_referer_check = 'example.com';
		369	// Session rejected if HTTP_REFERER doesn't contain this string
		370	```
		371
		372	---
		373
		374	## API Reference
		375
		376	### Public Methods
		377
		378	#### Lifecycle Management
		379
		380	##### `start($name = null, $id = null): bool`
		381	Start or resume a session.
		382
		383	Parameters:
		384	- `$name` (string\|null): Session name (cookie name base). Alphanumeric + underscore/dash. Defaults to 'sesid'
		385	- `$id` (string\|null): Existing session ID to resume. If null, attempts to read from cookie
		386
		387	Returns: `true` if session started successfully, `false` on error
		388
		389	Side Effects:
		390	- Sets headers (cookies, cache control)
		391	- Populates session data from storage
		392	- Performs security validations
		393	- May trigger session ID regeneration
		394
		395	Example:
		396	```php
		397	if ($session->start('webapp', $_COOKIE['sess_id'] ?? null)) {
		398	// Session ready
		399	} else {
		400	// Session failed
		401	}
		402	```
		403
		404	Validation Steps:
		405	1. Reject if headers already sent
		406	2. Validate session name format
		407	3. Retrieve ID from parameter or cookie
		408	4. Check Referer header (if configured)
		409	5. Validate ID format via `store_validate_id()`
		410	6. Read session data from storage
		411	7. Verify nonces and timestamps
		412	8. Check user agent, IP, TLS
		413	9. Regenerate if needed
		414
		415	---
		416
		417	##### `write_close(): void`
		418	Save session data and close session.
		419
		420	Side Effects:
		421	- Calls `write_session()` to serialize and store data
		422	- Calls `store_close()` to close storage handler
		423	- Sets `$active = false`
		424
		425	Example:
		426	```php
		427	$session['key'] = 'value';
		428	$session->write_close(); // Ensure data is saved
		429	```
		430
		431	---
		432
		433	##### `restart(): bool`
		434	Destroy current session and create new one.
		435
		436	Equivalent to: `regenerate_id(true) + clean_vars() + populate()`
		437
		438	Returns: `true` on success, `false` on error
		439
		440	Use Cases:
		441	- User logout and new login
		442	- Security reset
		443	- Complete session refresh
		444
		445	Example:
		446	```php
		447	$session->restart();
		448	// New session created, old data cleared, sticky_ vars preserved
		449	```
		450
		451	---
		452
		453	#### Session Access
		454
		455	##### `id(): mixed`
		456	Get current session ID.
		457
		458	Returns: Session ID string or null if not started
		459
		460	```php
		461	$sid = $session->id(); // "abc123xyz..."
		462	```
		463
		464	---
		465
		466	##### `name(): string`
		467	Get session name (cookie prefix).
		468
		469	Returns: Session name
		470
		471	```php
		472	$name = $session->name(); // "myapp"
		473	```
		474
		475	---
		476
		477	##### `active(): bool`
		478	Check if session is currently active.
		479
		480	Returns: `true` if session is started and active, `false` otherwise
		481
		482	```php
		483	if ($session->active()) {
		484	$session['key'] = 'value';
		485	}
		486	```
		487
		488	---
		489
		490	##### `message(): string\|null`
		491	Get reason for last session state change.
		492
		493	Returns: Message string or null
		494
		495	Possible Values:
		496	- `'replay'`: Replay attack detected
		497	- `'obsolete'`: Session marked for expiration
		498	- `'reg_expire'`: Regeneration expiration reached
		499	- `'max_session'`: Max session lifetime exceeded
		500	- `'max_idle'`: Idle timeout exceeded
		501	- `'ua'`: User agent mismatch (>5% difference)
		502	- `'tls'`: TLS status changed
		503	- `'ip'`: IP address mismatch
		504	- `'restart'`: Session manually restarted
		505	- `null`: No state change
		506
		507	Example:
		508	```php
		509	$session->start('app');
		510	if ($message = $session->message()) {
		511	error_log("Session issue: $message");
		512	}
		513	```
		514
		515	---
		516
		517	##### `toArray(): array`
		518	Convert session data to array.
		519
		520	Returns: Associative array of session data
		521
		522	Note: This is a direct call to `ArrayObject::getArrayCopy()`
		523
		524	```php
		525	$data = $session->toArray();
		526	foreach ($data as $key => $value) {
		527	echo "$key => $value\n";
		528	}
		529	```
		530
		531	---
		532
		533	#### Nonce System
		534
		535	##### `create_nonce($action, $expires = null): string`
		536	Generate a unique nonce token.
		537
		538	Parameters:
		539	- `$action` (string): Action identifier (e.g., 'form_submit', 'delete_action')
		540	- `$expires` (int\|null): Expiration time in seconds. Defaults to `cf_nonce_lifetime`
		541
		542	Returns: Nonce token string (11 characters)
		543
		544	Example:
		545	```php
		546	$nonce = $session->create_nonce('form_submit', 3600);
		547	// Use in HTML: <input type="hidden" name="nonce" value="<?= $nonce ?>">
		548	```
		549
		550	Storage:
		551	- Stored in `$session->__nonces[]`
		552	- Key: `{action}.{base64_encoded_hash}`
		553	- Value: Expiration timestamp
		554
		555	---
		556
		557	##### `verify_nonce($action, $code, $protect = 0)`
		558	Verify a nonce token.
		559
		560	Parameters:
		561	- `$action` (string): Action identifier that was used in `create_nonce()`
		562	- `$code` (string): Nonce token from user
		563	- `$protect` (int): Protection level
		564	- `0`: Single-use nonce (consumed on first verification)
		565	- `1+`: Protected nonce (can verify multiple times, prevents fast replays)
		566
		567	Returns:
		568	- `true` (1): Nonce verified and valid
		569	- `false` (0): Nonce invalid or expired
		570	- `-1`: Protected nonce used twice in quick succession (possible AJAX attack)
		571
		572	Example:
		573	```php
		574	if ($nonce = $session->verify_nonce('form_submit', $_POST['nonce'])) {
		575	if ($nonce === -1) {
		576	// Possible replay, but might be legitimate AJAX
		577	$session->cf_prevent_replay = 0; // Disable for this request
		578	} else {
		579	// Safe to process
		580	process_form();
		581	}
		582	}
		583	```
		584
		585	Cleanup:
		586	- Expired nonces automatically removed
		587	- Verified single-use nonces removed from storage
		588
		589	---
		590
		591	#### Cookie Management
		592
		593	##### `setcookie($name, $value = null, $expires = 0, $path = null, $domain = null, $secure = null, $httponly = null, $samesite = null): bool`
		594	Set a cookie with security headers.
		595
		596	Parameters:
		597	- `$name`: Cookie name (automatically URL-encoded)
		598	- `$value`: Cookie value (automatically URL-encoded, null to delete)
		599	- `$expires`: Expiration timestamp (0 = session cookie)
		600	- `$path`: Cookie path (default: `cf_cookie_path`)
		601	- `$domain`: Cookie domain (default: `cf_cookie_domain`)
		602	- `$secure`: HTTPS only (default: `cf_cookie_secure`)
		603	- `$httponly`: Disable JS access (default: `cf_cookie_httponly`)
		604	- `$samesite`: SameSite attribute (default: `cf_cookie_samesite`)
		605
		606	Returns: `true` on success, `false` if headers already sent
		607
		608	Features:
		609	- RFC 2616 2.2 token encoding for cookie name
		610	- RFC 6265 4.1.1 cookie-octet encoding for value
		611	- Removes duplicate cookie headers automatically
		612	- Adds all security attributes (secure, httponly, samesite)
		613	- Does NOT replace existing cookies (allows multiple Set-Cookie headers)
		614
		615	Example:
		616	```php
		617	// Session cookie
		618	$session->setcookie('user_pref', 'dark_mode');
		619
		620	// Persistent cookie (30 days)
		621	$session->setcookie('remember_me', 'token123', time() + 30*86400);
		622
		623	// Delete cookie
		624	$session->setcookie('old_cookie', null);
		625
		626	// Secure cookie with SameSite
		627	$session->setcookie('token', 'abc123', time() + 3600,
		628	path: '/', secure: true, httponly: true, samesite: 'Strict');
		629	```
		630
		631	---
		632
		633	##### `get_cookie($name)`
		634	Retrieve cookie value.
		635
		636	Parameters:
		637	- `$name`: Cookie name (prefix automatically added)
		638
		639	Returns: Cookie value or null if not set
		640
		641	```php
		642	$value = $session->get_cookie('user_pref'); // Reads $_COOKIE['user_pref']
		643	```
		644
		645	---
		646
		647	##### `set_cookie($name, $value, $persistent = false): void`
		648	Legacy cookie setter (alternative to `setcookie()`).
		649
		650	Parameters:
		651	- `$name`: Cookie name (prefix added)
		652	- `$value`: Cookie value
		653	- `$persistent`:
		654	- `false`: Session cookie (deleted on browser close)
		655	- Number: Days to persist
		656	- `0`: Use `cf_cookie_persistent` config
		657
		658	Example:
		659	```php
		660	$session->set_cookie('theme', 'dark'); // Session cookie
		661	$session->set_cookie('lang', 'en', 365); // 1 year
		662	```
		663
		664	---
		665
		666	##### `delete_cookie($name): void`
		667	Delete a cookie.
		668
		669	Parameters:
		670	- `$name`: Cookie name (prefix added)
		671
		672	Implementation: Sets empty value with immediate expiration
		673
		674	```php
		675	$session->delete_cookie('old_preference');
		676	```
		677
		678	---
		679
		680	##### `unsetcookie($name): void`
		681	Alias for `setcookie($name)` with no value (convenience method).
		682
		683	```php
		684	$session->unsetcookie('cookie_name');
		685	```
		686
		687	---
		688
		689	### Protected Methods (For Store Implementation)
		690
		691	#### `regenerate_id($delete_old = false, $message = ''): bool`
		692	Internal method to regenerate session ID (called automatically).
		693
		694	Protected - Usually called automatically, but can be overridden/called by subclasses
		695
		696	---
		697
		698	#### `store_generate_id(): string`
		699	Generate a new session ID.
		700
		701	Default Implementation: Returns 21-character random alphanumeric string via `Ut::random_token(21)`
		702
		703	Override in subclass to customize:
		704	```php
		705	protected function store_generate_id(): string {
		706	return hash('sha256', random_bytes(32)); // Your format
		707	}
		708	```
		709
		710	---
		711
		712	#### `store_validate_id($id): bool`
		713	Validate session ID format.
		714
		715	Default Implementation: Regex check: `/^[a-zA-Z\d]{21}$/`
		716
		717	Override in subclass to match your format:
		718	```php
		719	protected function store_validate_id($id): bool {
		720	return preg_match('/^[a-f0-9]{64}$/', $id); // SHA256 format
		721	}
		722	```
		723
		724	---
		725
		726	#### `store_open($name): void`
		727	Open session storage (called before first read/write).
		728
		729	Subclass must implement - Initialize storage handler
		730
		731	Example:
		732	```php
		733	protected function store_open($name): void {
		734	$this->db = new PDO('sqlite::memory:');
		735	}
		736	```
		737
		738	---
		739
		740	#### `store_read($id, $lock = false): string\|false`
		741	Read session data from storage.
		742
		743	Subclass must implement
		744
		745	Parameters:
		746	- `$id`: Session ID to read
		747	- `$lock`: If true, lock the session file for writing (create new)
		748
		749	Returns:
		750	- Serialized session data (string) if found and locked
		751	- Empty string (`''`) if new session should be created
		752	- `false` if session doesn't exist or read error
		753
		754	Example:
		755	```php
		756	protected function store_read($id, $lock = false): string\|false {
		757	$data = file_get_contents("/tmp/sess_$id");
		758	return $data ?: false;
		759	}
		760	```
		761
		762	---
		763
		764	#### `store_write($id, $data): void`
		765	Write session data to storage.
		766
		767	Subclass must implement
		768
		769	Parameters:
		770	- `$id`: Session ID
		771	- `$data`: Serialized session data (already processed by `Ut::serialize()`)
		772
		773	Example:
		774	```php
		775	protected function store_write($id, $data): void {
		776	file_put_contents("/tmp/sess_$id", $data);
		777	}
		778	```
		779
		780	---
		781
		782	#### `store_close(): void`
		783	Close session storage.
		784
		785	Subclass must implement - Release resources
		786
		787	Example:
		788	```php
		789	protected function store_close(): void {
		790	// Close database, file, etc.
		791	}
		792	```
		793
		794	---
		795
		796	#### `store_gc(): void`
		797	Perform garbage collection on old sessions.
		798
		799	Subclass must implement - Delete expired sessions
		800
		801	Called During:
		802	- Shutdown handler (probabilistic, based on `cf_gc_probability`)
		803
		804	Should Delete:
		805	- Sessions older than `cf_gc_maxlifetime` seconds
		806
		807	Example:
		808	```php
		809	protected function store_gc(): void {
		810	$max_age = time() - $this->cf_gc_maxlifetime;
		811	// Delete files/records older than $max_age
		812	}
		813	```
		814
		815	---
		816
		817	### Private Methods (Internal Use)
		818
		819	##### `populate(): void`
		820	Initialize session tracking variables on first request.
		821
		822	Called by: `start()`, `restart()`
		823
		824	Initializes:
		825	- `__started`: Current timestamp
		826	- `__regenerated`: Current timestamp
		827	- `__user_agent`: Browser user agent
		828	- `__user_ip`: Client IP (if configured)
		829	- `__user_tls`: TLS status (if configured)
		830	- `sticky__created`: Creation time (if not exists)
		831
		832	---
		833
		834	##### `write_session(): void`
		835	Serialize and write session data to storage.
		836
		837	Called by: `regenerate_id()`, `write_close()`, `terminator()`
		838
		839	Updates:
		840	- `__updated`: Current timestamp
		841	- Calls `store_write()` with serialized data
		842
		843	---
		844
		845	##### `clean_vars(): void`
		846	Remove non-sticky session variables.
		847
		848	Called by: `restart()`, session validation failure
		849
		850	Preserves: Variables starting with `sticky_`
		851
		852	---
		853
		854	##### `prevent_replay(): void`
		855	Generate and send anti-replay nonce.
		856
		857	Called by: `populate()`
		858
		859	Action:
		860	- Creates 'NoReplay' nonce
		861	- Sends in cookie: `{cf_cookie_prefix}NoReplay`
		862
		863	---
		864
		865	##### `cache_limiter(): void`
		866	Set HTTP cache control headers based on configuration.
		867
		868	Called by: `start()` after session data loaded
		869
		870	Modes:
		871	- `'public'`: Cacheable, `Cache-Control: public, max-age=...`
		872	- `'private'`: Private, `Cache-Control: private, max-age=...`
		873	- `'private_no_expire'`: Private no TTL
		874	- `'nocache'`: No storage, `Cache-Control: no-store`
		875	- `'none'`: No headers (default)
		876
		877	---
		878
		879	##### `set_new_id(): void`
		880	Generate and assign new session ID, send in cookie.
		881
		882	Called by: `regenerate_id()`, `start()` (for new sessions)
		883
		884	---
		885
		886	##### `remove_cookie($cookie): void`
		887	Remove existing Set-Cookie header to avoid duplicates.
		888
		889	Called by: `setcookie()` before setting new value
		890
		891	---
		892
		893	##### `nonce_index($action, $code): string` (static)
		894	Generate storage key for nonce.
		895
		896	Returns: `{action}.{base64_encoded_hash}`
		897
		898	---
		899
		900	---
		901
		902	## Session Lifecycle
		903
		904	### Complete Session Flow
		905
		906	```
		907	┌─ Browser Request
		908	│
		909	├─ Application Code
		910	│ └─ $session->start('appname')
		911	│ │
		912	│ ├─ Check if headers sent
		913	│ ├─ Validate/read session name
		914	│ ├─ Get session ID from:
		915	│ │ 1. Parameter $id
		916	│ │ 2. Cookie: {prefix}appname
		917	│ ├─ Validate referer (if cf_referer_check set)
		918	│ ├─ Validate ID format via store_validate_id()
		919	│ ├─ store_open(name)
		920	│ ├─ store_read(id)
		921	│ │ └─ If missing/invalid/expired:
		922	│ │ └─ set_new_id()
		923	│ │ └─ regenerate_id = 2 (NEW)
		924	│ ├─ Deserialize session data
		925	│ ├─ exchangeArray(data)
		926	│ ├─ active = true
		927	│ ├─ cache_limiter()
		928	│ │
		929	│ └─ Security Checks (if NOT first request):
		930	│ ├─ Verify NoReplay nonce
		931	│ ├─ Check expiration flags
		932	│ ├─ Check max session time
		933	│ ├─ Check max idle time
		934	│ ├─ Compare user agent (95%+ similarity)
		935	│ ├─ Compare TLS status
		936	│ ├─ Compare IP address
		937	│ │ ├─ Match: OK
		938	│ │ └─ Mismatch: destroy=1, regenerate
		939	│ └─ Check regen time/probability
		940	│ └─ regenerate_id()
		941	│
		942	├─ Application Code
		943	│ └─ $session['key'] = 'value'
		944	│
		945	└─ End of Request
		946	│
		947	└─ register_shutdown_function() → terminator()
		948	│
		949	├─ Process flash data
		950	│ └─ Decrement lifetimes
		951	│ └─ Remove expired flash
		952	├─ write_session()
		953	│ └─ store_write(id, serialized_data)
		954	├─ store_close()
		955	├─ Probabilistic garbage collection
		956	│ └─ store_gc() (cf_gc_probability % chance)
		957	│ └─ Delete old sessions
		958	└─ Output sent to browser
		959	```
		960
		961	### First Request (New Session)
		962
		963	```
		964	start() is called
		965	├─ No ID in cookie
		966	├─ store_read(id) → false
		967	├─ set_new_id()
		968	│ └─ id = store_generate_id()
		969	│ └─ send_cookie(name, id)
		970	├─ data = []
		971	├─ active = true
		972	├─ populate()
		973	│ ├─ __started = now
		974	│ ├─ __regenerated = now
		975	│ ├─ __user_agent = UA
		976	│ └─ sticky__created = now
		977	└─ return true
		978	```
		979
		980	### Subsequent Request (Resume Session)
		981
		982	```
		983	start() is called
		984	├─ ID from cookie
		985	├─ store_read(id) → serialized_data
		986	├─ data = unserialize(data)
		987	├─ exchangeArray(data)
		988	├─ active = true
		989	├─ Security checks:
		990	│ ├─ Replay check
		991	│ ├─ Timeout checks
		992	│ ├─ UA/IP/TLS checks
		993	│ └─ May trigger regenerate_id()
		994	└─ return true
		995	```
		996
		997	### Session ID Regeneration
		998
		999	```
		1000	regenerate_id($delete_old, $message) is called
		1001	├─ Check not headers_sent()
		1002	├─ Check $active
		1003	├─ Check not already regenerated in this request
		1004	├─ write_session() [Save current data]
		1005	├─ set __expire:
		1006	│ ├─ if $delete_old=0: __expire = now + 5
		1007	│ └─ if $delete_old>0: __expire = 0
		1008	├─ Generate new ID:
		1009	│ └─ loop:
		1010	│ ├─ id = store_generate_id()
		1011	│ └─ while store_read(id) !== false [Ensure unique]
		1012	├─ Lock new session: store_read(id, true)
		1013	├─ Set: __regenerated = now
		1014	├─ Set: regenerated = 1
		1015	├─ Log event: sticky__log[] = [now, message]
		1016	└─ return true
		1017	```
		1018
		1019	### Session Destruction
		1020
		1021	```
		1022	Triggered by:
		1023	├─ restart() → regenerate_id(true)
		1024	├─ Validation failure (destroy=2)
		1025	│ └─ regenerate_id(2)
		1026	│ └─ clean_vars() [Remove non-sticky data]
		1027	└─ Timeout or security violation
		1028	Results in:
		1029	├─ __expire = 0 [Immediate expiration]
		1030	├─ Non-sticky variables cleared
		1031	├─ sticky_ variables preserved
		1032	└─ New session ID generated
		1033	```
		1034
		1035	---
		1036
		1037	## Flash Data
		1038
		1039	Flash data persists for a limited number of requests (typically 1-2) and is automatically removed.
		1040
		1041	### Usage
		1042
		1043	```php
		1044	// Store flash message for next request
		1045	$session->set_flash('error', 'Username already exists', 1); // 1 request
		1046	$session->set_flash('info', 'Welcome back!', 2); // 2 requests
		1047
		1048	// In next request, data automatically available
		1049	echo $session['error']; // "Username already exists"
		1050	```
		1051
		1052	### How It Works
		1053
		1054	1. Storage: Flash data stored in `$session->sticky__flash`
		1055	- Key: Variable name
		1056	- Value: Lifetime in requests
		1057
		1058	2. Cleanup: In `terminator()` (shutdown handler):
		1059	```php
		1060	foreach ($sticky__flash as $var => $age) {
		1061	if (!isset($session[$var])) {
		1062	unset($sticky__flash[$var]); // Already deleted
		1063	} else if (--$age <= 0) {
		1064	unset($session[$var]); // Expired, remove
		1065	unset($flash__flash[$var]);
		1066	} else {
		1067	$flash__flash[$var] = $age; // Decrement counter
		1068	}
		1069	}
		1070	```
		1071
		1072	3. Persistence: Flash variables are kept in `sticky__flash` even during session resets
		1073
		1074	### Example: Login Flow
		1075
		1076	```php
		1077	// POST /login
		1078	if ($credentials_valid) {
		1079	$session->restart(); // New session
		1080	$session['user_id'] = $user->id;
		1081	$session->set_flash('success', 'Login successful!', 1);
		1082	header('Location: /dashboard');
		1083	} else {
		1084	$session->set_flash('error', 'Invalid credentials', 1);
		1085	header('Location: /login');
		1086	}
		1087
		1088	// GET /dashboard (or /login on failure)
		1089	if ($message = $session['error'] ?? null) {
		1090	echo "<div class='error'>$message</div>";
		1091	}
		1092	if ($message = $session['success'] ?? null) {
		1093	echo "<div class='success'>$message</div>";
		1094	}
		1095	```
		1096
		1097	---
		1098
		1099	## Nonce System
		1100
		1101	Nonces provide CSRF protection and replay attack detection.
		1102
		1103	### Terminology
		1104
		1105	- Nonce: Number used ONCE - cryptographic token for action verification
		1106	- Action: Type of operation being protected (e.g., 'form_submit', 'delete_user')
		1107	- Protected Nonce: Can be verified multiple times with protection against rapid reuse
		1108
		1109	### Complete Example: Form Protection
		1110
		1111	```php
		1112	// 1. Display form with nonce
		1113	$nonce = $session->create_nonce('user_update', 3600);
		1114	?>
		1115	<form method="POST" action="/update-profile">
		1116	<input type="hidden" name="nonce" value="<?= htmlspecialchars($nonce) ?>">
		1117	<input type="text" name="username" value="...">
		1118	<button type="submit">Update</button>
		1119	</form>
		1120
		1121	<?php
		1122	// 2. Process form submission
		1123	if ($_SERVER['REQUEST_METHOD'] === 'POST') {
		1124	if (!$session->verify_nonce('user_update', $_POST['nonce'] ?? '')) {
		1125	http_response_code(403);
		1126	die('Security check failed');
		1127	}
		1128
		1129	// Safe to process
		1130	update_user($_POST);
		1131	}
		1132	```
		1133
		1134	### Example: Protected Nonce (AJAX-Safe)
		1135
		1136	```php
		1137	// Generate protected nonce (can verify multiple times)
		1138	$nonce = $session->create_nonce('ajax_action', 300);
		1139
		1140	// Verify with protection level 3 (3 seconds)
		1141	$result = $session->verify_nonce('ajax_action', $_POST['nonce'], 3);
		1142
		1143	if ($result === -1) {
		1144	// Rapid reuse detected (possible attack, but might be AJAX)
		1145	if (is_ajax_request()) {
		1146	// AJAX is OK, disable replay protection this once
		1147	$session->cf_prevent_replay = 0;
		1148	} else {
		1149	// Likely attack
		1150	http_response_code(403);
		1151	die('Suspicious activity');
		1152	}
		1153	} else if ($result === true) {
		1154	// Safe to process
		1155	process_ajax();
		1156	}
		1157	```
		1158
		1159	### Nonce Storage Format
		1160
		1161	```
		1162	Internal storage (__nonces array):
		1163	[
		1164	"{action}.{hash}" => expiration_timestamp,
		1165	"form_submit.AbCdEfGhIjK" => 1234567890,
		1166	"delete_user.XyZaBcDeFgH" => 1234567890,
		1167	]
		1168	Where:
		1169	- action: Custom action identifier
		1170	- hash: First 11 chars of base64(sha1(code_bytes))
		1171	- expiration_timestamp: time() + lifetime
		1172	```
		1173
		1174	### Security Properties
		1175
		1176	- CSRF Protection: Nonce must match to process form
		1177	- One-Time Use: Each nonce consumed after first verification (unless protected)
		1178	- Expiration: Nonces automatically expire
		1179	- Action-Specific: Each action has separate nonce space
		1180	- AJAX-Safe: Protected nonces allow multiple quick verifications
		1181
		1182	---
		1183
		1184	## Cookie Management
		1185
		1186	### Security Features
		1187
		1188	The `setcookie()` method implements comprehensive cookie security:
		1189
		1190	#### Encoding
		1191	```php
		1192	// Cookie names: RFC 2616 2.2 token format
		1193	// Cookie values: RFC 6265 4.1.1 cookie-octet format
		1194	// Unsafe characters automatically URL-encoded
		1195	```
		1196
		1197	#### Security Attributes
		1198	```php
		1199	setcookie('auth', 'token',
		1200	expires: time() + 3600,
		1201	secure: true, // HTTPS only
		1202	httponly: true, // Disable JavaScript
		1203	samesite: 'Strict' // CSRF protection
		1204	);
		1205	```
		1206
		1207	#### No Duplicate Headers
		1208	```php
		1209	// Automatically removes old Set-Cookie header before setting new one
		1210	// Prevents cookie header duplication
		1211	remove_cookie($name) → clears old headers
		1212	setcookie() → sets new header
		1213	```
		1214
		1215	### Configuration-Driven Defaults
		1216
		1217	```php
		1218	$session->cf_cookie_path = '/app'; // Path
		1219	$session->cf_cookie_domain = '.example.com'; // Domain
		1220	$session->cf_cookie_secure = true; // HTTPS
		1221	$session->cf_cookie_httponly = true; // No JS
		1222	$session->cf_cookie_samesite = 'Lax'; // SameSite
		1223	$session->cf_cookie_prefix = 'app_'; // Prefix
		1224
		1225	$session->setcookie('token', 'value');
		1226	// Uses all configured defaults
		1227	```
		1228
		1229	### Typical Secure Configuration
		1230
		1231	```php
		1232	// Prevent XSS and CSRF
		1233	$session->cf_cookie_secure = true; // HTTPS only
		1234	$session->cf_cookie_httponly = true; // No JavaScript access
		1235	$session->cf_cookie_samesite = 'Strict'; // Strict CSRF protection
		1236
		1237	// Set scope
		1238	$session->cf_cookie_path = '/'; // Root path
		1239	$session->cf_cookie_domain = ''; // Current host only
		1240
		1241	// Session cookies (delete on browser close)
		1242	$session->cf_cookie_lifetime = 0;
		1243	$session->cf_cookie_persistent = false;
		1244	```
		1245
		1246	---
		1247
		1248	## Error Handling
		1249
		1250	### Graceful Degradation
		1251
		1252	The Session class gracefully handles errors:
		1253
		1254	#### Headers Already Sent
		1255	```php
		1256	if (headers_sent($file, $line)) {
		1257	trigger_error("id regeneration requested after headers flushed at $file:$line",
		1258	E_USER_WARNING);
		1259	return false;
		1260	}
		1261	```
		1262
		1263	Impact: Session ID cannot be regenerated, but session continues
		1264
		1265	#### Cookie Setting Failure
		1266	```php
		1267	if (headers_sent($file, $line)) {
		1268	trigger_error("cannot place session cookie $name=$value due to $file:$line",
		1269	E_USER_WARNING);
		1270	return;
		1271	}
		1272	```
		1273
		1274	Impact: Cookie not set, but session data remains accessible
		1275
		1276	#### Storage Errors
		1277	```php
		1278	if ($this->store_read($this->id, true) !== '') {
		1279	// error! [comment indicates error, but continues]
		1280	}
		1281	```
		1282
		1283	Impact: Creates new session if storage returns error
		1284
		1285	### Debug Logging
		1286
		1287	The Session class includes commented debug statements:
		1288
		1289	```php
		1290	# Ut::dbg("regeneration failed by flush at $file:$line");
		1291	# Ut::dbg($destroy, $message);
		1292	# Ut::dbg("session setcookie $name failed by $file:$line");
		1293	```
		1294
		1295	To enable: Uncomment lines and ensure `Ut::dbg()` function exists
		1296
		1297	### Event Logging
		1298
		1299	Session events tracked in `sticky__log`:
		1300
		1301	```php
		1302	// Access session event history
		1303	if (isset($session->sticky__log)) {
		1304	foreach ($session->sticky__log as [$timestamp, $message]) {
		1305	echo "[$timestamp] $message\n";
		1306	}
		1307	}
		1308	```
		1309
		1310	Logged Events:
		1311	- Session regeneration (with reason)
		1312	- Limited to 15 most recent events (old entries archived as '...')
		1313
		1314	---
		1315
		1316	## Implementation Guide
		1317
		1318	### Creating a Concrete Session Class
		1319
		1320	You must implement the abstract storage methods. Choose your storage backend: files, database, cache, etc.
		1321
		1322	#### File-Based Storage
		1323
		1324	```php
		1325	<?php
		1326
		1327	class FileSession extends Session {
		1328	private $session_dir = '/tmp/sessions';
		1329	private $file_handle = null;
		1330
		1331	public function __construct() {
		1332	parent::__construct();
		1333	if (!is_dir($this->session_dir)) {
		1334	mkdir($this->session_dir, 0700, true);
		1335	}
		1336	}
		1337
		1338	protected function store_open($name): void {
		1339	// PHP sessions don't really "open", just prepare
		1340	// In file mode, we could initialize directory
		1341	}
		1342
		1343	protected function store_read($id, $lock = false): string\|false {
		1344	$file = $this->session_dir . '/sess_' . preg_replace('/[^a-zA-Z0-9]/', '', $id);
		1345
		1346	if (!file_exists($file)) {
		1347	if ($lock) {
		1348	// Create new session file
		1349	file_put_contents($file, '', LOCK_EX);
		1350	return '';
		1351	}
		1352	return false;
		1353	}
		1354
		1355	if (filemtime($file) < time() - $this->cf_gc_maxlifetime) {
		1356	unlink($file); // Expired
		1357	return false;
		1358	}
		1359
		1360	return file_get_contents($file);
		1361	}
		1362
		1363	protected function store_write($id, $data): void {
		1364	$file = $this->session_dir . '/sess_' . preg_replace('/[^a-zA-Z0-9]/', '', $id);
		1365	file_put_contents($file, $data, LOCK_EX);
		1366	}
		1367
		1368	protected function store_close(): void {
		1369	// No cleanup needed for file backend
		1370	}
		1371
		1372	protected function store_gc(): void {
		1373	$cutoff = time() - $this->cf_gc_maxlifetime;
		1374	foreach (glob($this->session_dir . '/sess_*') as $file) {
		1375	if (filemtime($file) < $cutoff) {
		1376	unlink($file);
		1377	}
		1378	}
		1379	}
		1380	}
		1381	```
		1382
		1383	#### Database Storage (PDO)
		1384
		1385	```php
		1386	<?php
		1387
		1388	class DatabaseSession extends Session {
		1389	private PDO $pdo;
		1390
		1391	public function __construct(PDO $pdo) {
		1392	parent::__construct();
		1393	$this->pdo = $pdo;
		1394	$this->ensure_table();
		1395	}
		1396
		1397	private function ensure_table(): void {
		1398	$sql = <<<SQL
		1399	CREATE TABLE IF NOT EXISTS sessions (
		1400	id VARCHAR(21) PRIMARY KEY,
		1401	data LONGTEXT NOT NULL,
		1402	created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
		1403	updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
		1404	)
		1405	SQL;
		1406	$this->pdo->exec($sql);
		1407	}
		1408
		1409	protected function store_open($name): void {
		1410	// Database already connected
		1411	}
		1412
		1413	protected function store_read($id, $lock = false): string\|false {
		1414	$stmt = $this->pdo->prepare('SELECT data FROM sessions WHERE id = ?');
		1415	$stmt->execute([$id]);
		1416
		1417	if ($result = $stmt->fetch(PDO::FETCH_ASSOC)) {
		1418	return $result['data'];
		1419	}
		1420
		1421	if ($lock) {
		1422	// Create new session
		1423	$stmt = $this->pdo->prepare('INSERT INTO sessions (id, data) VALUES (?, ?)');
		1424	$stmt->execute([$id, '']);
		1425	return '';
		1426	}
		1427
		1428	return false;
		1429	}
		1430
		1431	protected function store_write($id, $data): void {
		1432	$stmt = $this->pdo->prepare(
		1433	'INSERT INTO sessions (id, data) VALUES (?, ?)
		1434	ON DUPLICATE KEY UPDATE data = VALUES(data)'
		1435	);
		1436	$stmt->execute([$id, $data]);
		1437	}
		1438
		1439	protected function store_close(): void {
		1440	// Connection persists for application
		1441	}
		1442
		1443	protected function store_gc(): void {
		1444	$cutoff = time() - $this->cf_gc_maxlifetime;
		1445	$this->pdo->prepare('DELETE FROM sessions WHERE updated_at < FROM_UNIXTIME(?)')
		1446	->execute([$cutoff]);
		1447	}
		1448	}
		1449	```
		1450
		1451	#### Redis Storage
		1452
		1453	```php
		1454	<?php
		1455
		1456	class RedisSession extends Session {
		1457	private Redis $redis;
		1458	private string $prefix = 'sess:';
		1459
		1460	public function __construct(Redis $redis) {
		1461	parent::__construct();
		1462	$this->redis = $redis;
		1463	}
		1464
		1465	protected function store_open($name): void {
		1466	// Redis already connected
		1467	}
		1468
		1469	protected function store_read($id, $lock = false): string\|false {
		1470	$data = $this->redis->get($this->prefix . $id);
		1471
		1472	if ($data !== false) {
		1473	return $data;
		1474	}
		1475
		1476	if ($lock) {
		1477	// Create new session
		1478	$this->redis->set($this->prefix . $id, '',
		1479	['EX' => $this->cf_gc_maxlifetime]);
		1480	return '';
		1481	}
		1482
		1483	return false;
		1484	}
		1485
		1486	protected function store_write($id, $data): void {
		1487	$this->redis->set($this->prefix . $id, $data,
		1488	['EX' => $this->cf_gc_maxlifetime]);
		1489	}
		1490
		1491	protected function store_close(): void {
		1492	// Connection persists
		1493	}
		1494
		1495	protected function store_gc(): void {
		1496	// Redis handles expiration automatically with TTL
		1497	}
		1498	}
		1499	```
		1500
		1501	### Complete Integration Example
		1502
		1503	```php
		1504	<?php
		1505
		1506	// Initialize session with configuration
		1507	$session = new FileSession();
		1508
		1509	// Configure security
		1510	$session->cf_cookie_secure = (!empty($_SERVER['HTTPS']));
		1511	$session->cf_cookie_httponly = true;
		1512	$session->cf_cookie_samesite = 'Lax';
		1513	$session->cf_max_session = 86400; // 24 hours
		1514	$session->cf_max_idle = 3600; // 1 hour
		1515	$session->cf_prevent_replay = true;
		1516
		1517	// Set IP and TLS validation
		1518	$session->cf_ip = $_SERVER['REMOTE_ADDR'];
		1519	$session->cf_tls = !empty($_SERVER['HTTPS']);
		1520
		1521	// Start session
		1522	if (!$session->start('myapp')) {
		1523	die('Session start failed');
		1524	}
		1525
		1526	// Check for session validation messages
		1527	if ($message = $session->message()) {
		1528	error_log("Session validation: $message");
		1529	}
		1530
		1531	// Use session
		1532	if (!isset($session['user_id'])) {
		1533	// Handle login...
		1534	$session['user_id'] = $user->id;
		1535	$session['username'] = $user->name;
		1536	$session->regenerate_id(false, 'login');
		1537	} else {
		1538	// User already logged in
		1539	echo "Welcome back, " . htmlspecialchars($session['username']);
		1540	}
		1541
		1542	// Logout handling
		1543	if ($_REQUEST['action'] === 'logout') {
		1544	$session->restart();
		1545	header('Location: /');
		1546	}
		1547
		1548	// Automatic cleanup happens in register_shutdown_function()
		1549	```
		1550
		1551	### Configuration Best Practices
		1552
		1553	```php
		1554	<?php
		1555
		1556	class SessionConfig {
		1557	public static function apply(Session $session, string $environment = 'production'): void {
		1558	// Base configuration
		1559	$session->cf_cookie_prefix = 'app_';
		1560	$session->cf_cookie_path = '/';
		1561	$session->cf_cache_limiter = 'private';
		1562
		1563	if ($environment === 'production') {
		1564	// Strict production settings
		1565	$session->cf_cookie_secure = true; // HTTPS only
		1566	$session->cf_cookie_httponly = true; // No JavaScript
		1567	$session->cf_cookie_samesite = 'Strict'; // Maximum CSRF protection
		1568	$session->cf_prevent_replay = true; // Anti-replay
		1569	$session->cf_max_session = 3600; // 1 hour
		1570	$session->cf_max_idle = 1800; // 30 minutes
		1571	$session->cf_regen_time = 300; // Regen every 5 min
		1572	$session->cf_regen_probability = 50; // 50% chance
		1573	} else {
		1574	// Development settings
		1575	$session->cf_cookie_secure = false; // Allow HTTP
		1576	$session->cf_cookie_httponly = false; // Allow JS debugging
		1577	$session->cf_prevent_replay = false; // Easier testing
		1578	$session->cf_max_session = 86400; // 24 hours
		1579	$session->cf_max_idle = 3600; // 1 hour
		1580	$session->cf_regen_time = 60; // 1 minute
		1581	$session->cf_regen_probability = 10; // 10% chance
		1582	}
		1583	}
		1584	}
		1585
		1586	// Usage
		1587	$session = new FileSession();
		1588	SessionConfig::apply($session, $_ENV['APP_ENV'] ?? 'production');
		1589	$session->start('myapp');
		1590	```
		1591
		1592	### Testing Tips
		1593
		1594	```php
		1595	<?php
		1596
		1597	// Test nonce generation and verification
		1598	$nonce1 = $session->create_nonce('test_action', 60);
		1599	assert($session->verify_nonce('test_action', $nonce1) === true);
		1600
		1601	// Test single-use property
		1602	assert($session->verify_nonce('test_action', $nonce1) === false);
		1603
		1604	// Test expiration
		1605	$old_nonce = $session->create_nonce('expire_test', 1);
		1606	sleep(2);
		1607	assert($session->verify_nonce('expire_test', $old_nonce) === false);
		1608
		1609	// Test user agent validation
		1610	assert(isset($session->__user_agent));
		1611
		1612	// Test session ID format
		1613	assert(preg_match('/^[a-zA-Z0-9]{21}$/', $session->id()));
		1614
		1615	// Test data persistence
		1616	$session['test_key'] = 'test_value';
		1617	$session->write_close();
		1618	// New request...
		1619	$session2 = new FileSession();
		1620	$session2->start('myapp');
		1621	assert($session2['test_key'] === 'test_value');
		1622	```
		1623
		1624	---
		1625
		1626	## Security Checklist
		1627
		1628	Use this checklist when implementing sessions:
		1629
		1630	- [ ] Use HTTPS only in production
		1631	- [ ] Enable `cf_cookie_secure`
		1632	- [ ] Enable `cf_cookie_httponly`
		1633	- [ ] Set `cf_cookie_samesite` to 'Strict' or 'Lax'
		1634	- [ ] Set appropriate `cf_max_session` timeout
		1635	- [ ] Set appropriate `cf_max_idle` timeout
		1636	- [ ] Enable `cf_prevent_replay`
		1637	- [ ] Validate `cf_ip` if possible
		1638	- [ ] Validate `cf_tls` on HTTPS sites
		1639	- [ ] Use nonces for all state-changing forms
		1640	- [ ] Implement proper logout (call `restart()`)
		1641	- [ ] Regenerate on privilege escalation (login)
		1642	- [ ] Monitor `sticky__ip` for suspicious changes
		1643	- [ ] Review `sticky__log` for attack patterns
		1644	- [ ] Implement garbage collection (`store_gc`)
		1645	- [ ] Hash session IDs before storing (see TODOs)
		1646	- [ ] Use secure random token generation
		1647
		1648	---
		1649
		1650	## Common Patterns
		1651
		1652	### Login Flow
		1653
		1654	```php
		1655	if ($_POST['action'] === 'login') {
		1656	$user = authenticate($_POST['username'], $_POST['password']);
		1657	if ($user) {
		1658	$session->regenerate_id(false, 'login'); // New ID after auth
		1659	$session['user_id'] = $user->id;
		1660	$session['username'] = $user->username;
		1661	$session['roles'] = $user->roles;
		1662	header('Location: /dashboard');
		1663	} else {
		1664	$session->set_flash('error', 'Invalid credentials', 1);
		1665	header('Location: /login');
		1666	}
		1667	}
		1668	```
		1669
		1670	### Logout Flow
		1671
		1672	```php
		1673	if ($_GET['action'] === 'logout') {
		1674	$session->restart(); // Complete reset
		1675	header('Location: /');
		1676	}
		1677	```
		1678
		1679	### CSRF-Protected Form
		1680
		1681	```php
		1682	// Display form
		1683	$csrf = $session->create_nonce('form_' . $form_id, 3600);
		1684	echo '<form method="POST">';
		1685	echo '<input type="hidden" name="csrf" value="' . htmlspecialchars($csrf) . '">';
		1686	// ... form fields
		1687	echo '</form>';
		1688
		1689	// Process form
		1690	if ($_SERVER['REQUEST_METHOD'] === 'POST') {
		1691	if (!$session->verify_nonce('form_' . $form_id, $_POST['csrf'] ?? '')) {
		1692	die('CSRF check failed');
		1693	}
		1694	// Process safely
		1695	}
		1696	```
		1697
		1698	### Permission Check with Session Regeneration
		1699
		1700	```php
		1701	if ($user->privilege_level < ADMIN_LEVEL && $promoted_to_admin) {
		1702	$session->regenerate_id(false, 'privilege_escalation');
		1703	$session['is_admin'] = true;
		1704	}
		1705	```
		1706
		1707	### Session Messages/Flash
		1708
		1709	```php
		1710	// After action
		1711	$session->set_flash('info', 'Profile updated successfully', 1);
		1712
		1713	// Display next page
		1714	if (isset($session['info'])) {
		1715	echo $session['info'];
		1716	}
		1717	```
		1718
		1719	---
		1720
		1721	## Performance Considerations
		1722
		1723	### Optimization Tips
		1724
		1725	1. Minimize Session Writes:
		1726	- Session data only written during `write_close()` or regeneration
		1727	- No unnecessary serialization during reads
		1728
		1729	2. Garbage Collection:
		1730	- Probabilistic GC (based on `cf_gc_probability`)
		1731	- Only runs on ~2% of requests by default
		1732	- Customize based on your session volume
		1733
		1734	3. Nonce Cleanup:
		1735	- Expired nonces automatically removed on verification
		1736	- Verified nonces removed from storage
		1737	- No manual cleanup needed
		1738
		1739	4. Session ID Validation:
		1740	- Regex-based validation is fast
		1741	- No database lookup needed
		1742
		1743	5. Caching Strategy:
		1744	- Cache expensive lookups between session operations
		1745	- Session data loaded once per request
		1746
		1747	### Benchmarks
		1748
		1749	Typical performance on modern hardware:
		1750
		1751	- Session start: ~1-5ms (file) / ~2-10ms (database)
		1752	- Session write: <1ms (file) / 1-5ms (database)
		1753	- Nonce generation: <1ms
		1754	- Nonce verification: <1ms
		1755
		1756	---
		1757
		1758	## Troubleshooting
		1759
		1760	### Session Not Starting
		1761
		1762	```php
		1763	if (!$session->start('myapp')) {
		1764	// Check reasons:
		1765	// 1. Headers already sent?
		1766	// 2. Storage backend not initialized?
		1767	// 3. Permissions issue on session directory?
		1768	debug_backtrace();
		1769	}
		1770	```
		1771
		1772	### Cookie Not Setting
		1773
		1774	```php
		1775	// If setcookie() returns false:
		1776	// - Check if headers_sent()
		1777	// - Check if cookie name is RFC 2616 compliant
		1778	// - Check if cookie value is properly encoded
		1779	```
		1780
		1781	### Session ID Not Regenerating
		1782
		1783	```php
		1784	// If regenerate_id() returns false:
		1785	// - Headers might be sent
		1786	// - $active might be false
		1787	// - Already regenerated once in this request
		1788	if (!$session->regenerate_id()) {
		1789	error_log("Regeneration failed: headers sent or session inactive");
		1790	}
		1791	```
		1792
		1793	### Nonce Verification Failing
		1794
		1795	```php
		1796	// If verify_nonce() returns false:
		1797	// 1. Nonce might be expired
		1798	// 2. Nonce might be for different action
		1799	// 3. Nonce might have been used already
		1800	// 4. Session might have been reset
		1801
		1802	// Debug:
		1803	var_dump($session->__nonces); // See stored nonces
		1804	```
		1805
		1806	### Session Data Lost
		1807
		1808	```php
		1809	// Possible causes:
		1810	// 1. write_close() not called (usually automatic via shutdown)
		1811	// 2. Storage backend failing silently
		1812	// 3. File permissions issues
		1813	// 4. Session timeout due to cf_max_idle
		1814	// 5. IP/UA/TLS validation failure (check message())
		1815
		1816	if ($message = $session->message()) {
		1817	error_log("Session issue: $message");
		1818	}
		1819	```
		1820
		1821	---
		1822
		1823	## TODO Items (From Code Comments)
		1824
		1825	The following improvements are planned:
		1826
		1827	1. Do not store session ID in filename or DB index - store hash instead
		1828	- Improves security by not exposing IDs in storage layer
		1829	- Would require hashing logic in store_* methods
		1830
		1831	2. Log of IP changes and other possible security alerts
		1832	- Track `sticky__ip` changes more comprehensively
		1833	- Create security audit trail
		1834
		1835	3. Allocate internal unique session which lives through lifetime of uber-session
		1836	- Multi-session management (parent/child sessions)
		1837	- Useful for complex user flows
		1838
		1839	4. Do not delete old sessions, but use them as hijack pointers
		1840	- Maintain session history for analysis
		1841	- Detect potential session hijacking patterns
		1842	- Implement session relationship tracking
		1843
		1844	5. All SIDs used later than ~5secs of regenerations is hijacks
		1845	- Detect and block delayed session ID usage
		1846	- Current implementation allows 5-second window
		1847	- Could be more granular
		1848
		1849	---
		1850
		1851	## References
		1852
		1853	### Security Standards
		1854
		1855	- RFC 2616: HTTP/1.1 (Cookie syntax)
		1856	- RFC 6265: HTTP State Management Mechanism
		1857	- RFC 6234: US Secure Hash and Message Authentication Code Algorithms
		1858	- OWASP: Session Management Cheat Sheet
		1859	- OWASP: Cross-Site Request Forgery (CSRF) Prevention
		1860
		1861	### Related Code
		1862
		1863	- `Ut::serialize()` / `Ut::unserialize()`: Session data serialization
		1864	- `Ut::random_token()`: Cryptographic token generation
		1865	- `Ut::http_date()`: HTTP date formatting
		1866	- `Ut::urlencode()`: Cookie-safe encoding
		1867	- `Ut::is_empty()`: Empty value checking
		1868
		1869	### See Also
		1870
		1871	- `src/class/http.php`: HTTP request/response handling
		1872	- `src/class/auth.php`: Authentication (uses Session)
		1873	- Session security best practices in OWASP documentation
		1874
		1875	---
		1876
		1877	## Version History
		1878
		1879	- Current: Abstract session class with security features
		1880	- Planned: Implementation of TODO items above
		1881
		1882	---
		1883
		1884	Documentation generated: 2026-05-05
		1885	For latest updates, see: https://github.com/Trojer/wackowiki/blob/main/docs/SESSION_DOCUMENTATION.md