# Walkthrough - Session Lifecycle & Portal Behavior (RC-004)

This document describes the implementation details, verification results, and acceptance status for Release Candidate RC-004.

## 1. Files Modified
- [LandingController.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Auth/LandingController.php)
- [landing.php](file:///c:/xampp/htdocs/inveetaire/app/views/public/landing.php)
- [AuthService.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Auth/AuthService.php)
- [AuthController.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Auth/AuthController.php)
- [AuthMiddleware.php](file:///c:/xampp/htdocs/inveetaire/app/middleware/AuthMiddleware.php)
- [session.php](file:///c:/xampp/htdocs/inveetaire/config/session.php)
- [.env](file:///c:/xampp/htdocs/inveetaire/.env)

---

## 2. Session Lifecycle & Timeout Implementation
- **Session Timeout Duration**: Adjusted the default session inactivity timeout in [.env](file:///c:/xampp/htdocs/inveetaire/.env) and [session.php](file:///c:/xampp/htdocs/inveetaire/config/session.php) config to `1800` seconds (30 minutes).
- **Portal Context Tracking**: Stored the login portal identifier (`admin` or `couple`) in the session variable `portal` inside `bindSession` (value `admin` for role `super_admin`, else `couple`).
- **Session Expiration Redirects**: When inactivity exceeds 30 minutes, `AuthMiddleware` extracts the `portal` key from the session, invalidates the old session, registers a clean anonymous session ID, and redirects to the appropriate login portal (`/admin` vs `/couple`) with the exact flash message: `"Your session has expired due to inactivity. Please sign in again."`.

---

## 3. Portal Behavior & Navigation Implementation
- **GET /**: Always renders the Landing Page (redirection of authenticated sessions has been removed).
- **Dynamic Landing Page Links**: Added session checks to the top of [landing.php](file:///c:/xampp/htdocs/inveetaire/app/views/public/landing.php) view to dynamically resolve Couple and Admin link targets to dashboards when authenticated.
- **GET /admin & GET /couple Auto-Login**: Authenticated users accessing login gates are automatically redirected to their respective dashboards.
- **GET /login**: Remains a 302 Redirect to `/couple` for backward compatibility.
- **Logout Refinement**: Destroying the session via POST `/logout` invalidates the cookies/files, clears the active workspace context, sets flash success to `"You have successfully logged out."`, and redirects to `/`.
- **Role-Aware Guest Access Redirects**: Directs unauthenticated attempts on `/app/admin/*` paths to `/admin`, and `/app/couple/*` or `/app/crew/*` paths to `/couple`.

---

## 4. Verification Results
We created and executed automated test scripts to verify the complete routing, portal behavior, and session lifecycle features. All tests passed successfully:

### Routing & Redirection Tests
```
=== 1. Unauthenticated Checks ===
GET / code: 200
GET /login code: 302, Location: http://localhost/inveetaire/couple
GET /admin code: 200
GET /couple code: 200

=== 2. Route Protection Checks ===
GET /app/admin/dashboard code: 302, Location: http://localhost/inveetaire/admin
GET /app/couple/dashboard code: 302, Location: http://localhost/inveetaire/couple
GET /app/crew/dashboard code: 302, Location: http://localhost/inveetaire/couple

=== 3. Admin Behavior ===
Admin Login POST code: 302, Location: http://localhost/inveetaire/app/admin/dashboard
GET /admin with Admin Session code: 302, Location: http://localhost/inveetaire/app/admin/dashboard
GET / with Admin Session code: 200
Has Admin Dashboard link: YES
Has Couple login link: YES

=== 4. Couple Behavior ===
Couple Login POST code: 302, Location: http://localhost/inveetaire/app/couple/dashboard
GET /couple with Couple Session code: 302, Location: http://localhost/inveetaire/app/couple/dashboard
GET / with Couple Session code: 200
Has Couple Dashboard link: YES
Has Admin login link: YES

=== 5. Crew Behavior ===
Crew Login POST code: 302, Location: http://localhost/inveetaire/app/crew/dashboard
GET /couple with Crew Session code: 302, Location: http://localhost/inveetaire/app/couple/dashboard
GET / with Crew Session code: 200
Has Crew Dashboard link: YES

=== 6. Logout Behavior ===
POST /logout code: 302, Location: http://localhost/inveetaire/
GET /app/couple/dashboard after logout code: 302, Location: http://localhost/inveetaire/couple
```

### Timeout Expiry Tests
```
--- Simulating Admin Timeout ---
Response code: 302
Redirect destination: http://localhost/inveetaire/admin
Has Expiry Flash: YES

--- Simulating Couple Timeout ---
Response code: 302
Redirect destination: http://localhost/inveetaire/couple
Has Expiry Flash: YES
```

---

## 5. Acceptance Checklist
- [x] Root URL `GET /` always renders the public Landing Page (even if authenticated).
- [x] Portal login links on the landing page dynamically guide users to dashboards if authenticated, or login forms if not.
- [x] Auto-login / autologin redirects for `/admin` and `/couple` work correctly.
- [x] Legacy login route `/login` issues a 302 redirect to `/couple`.
- [x] Session inactivity timeout set to 30 minutes (1800 seconds).
- [x] Timeouts invalidate session and redirect to the correct login gate (`/admin` or `/couple`) with the exact flash message.
- [x] Unauthenticated operator access redirects to `/admin` and couple/crew access redirects to `/couple`.
- [x] Logout destroys workspace/auth context, sets flash success to `"You have successfully logged out."`, and redirects to `/`.
- [x] Authentication architecture remains unchanged.
- [x] PHP syntax validation passes.

---

## 6. PHP Syntax Results
- `LandingController.php`: `No syntax errors detected`
- `landing.php`: `No syntax errors detected`
- `AuthService.php`: `No syntax errors detected`
- `AuthController.php`: `No syntax errors detected`
- `AuthMiddleware.php`: `No syntax errors detected`
- `session.php`: `No syntax errors detected`
