Difference between revisions for Users / Eo Ny





Revision 1 as of 05/05/2026 16:15 ▼
1 05/05/2026 16:15 EoNy [neues Benutzerkonto]

(41.0 B)
EoNy
[neues Benutzerkonto]
Next edit →
Revision 2 as of 05/05/2026 18:36 ▼
6 05/21/2026 16:13 WikiAdmin 5 05/19/2026 11:04 WikiAdmin 4 05/05/2026 18:48 EoNy 3 05/05/2026 18:39 EoNy 2 05/05/2026 18:36 EoNy

(48.0 KiB) +49,092
EoNy

Merge of Version1 & Version2
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*