Difference between revisions for Users / Eo Ny




← Previous edit
Revision 2 as of 05/05/2026 18:36 ▼
2 05/05/2026 18:36 EoNy 1 05/05/2026 16:15 EoNy [neues Benutzerkonto]

(48.0 KiB)
EoNy
 Next edit →
Revision 3 as of 05/05/2026 18:39 ▼
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

(49.6 KiB) +1,577
EoNy

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