Difference between revisions for Users / Eo Ny





Revision 1 as of 05/05/2026 16:15 ▼
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 1 05/05/2026 16:15 EoNy [neues Benutzerkonto]

(41.0 B)
EoNy
[neues Benutzerkonto]
Next edit →
Revision 6 as of 05/21/2026 16:13 ▼
10 07/16/2026 09:38 WikiAdmin 9 07/16/2026 09:37 WikiAdmin 8 07/16/2026 09:36 WikiAdmin 7 07/16/2026 09:36 WikiAdmin 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

(49.9 KiB) +51,053
WikiAdmin

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