Current Task

AUTH-004 — Session Timeout and Authorization Middleware

Sprint:

Sprint 2 — Authentication & Authorization

This task implements ONLY AUTH-004.

Do NOT implement AUTH-003.

---

Mandatory Reading

Before writing any code, review:

Governance

- AI.md v1.1
- AI_DEVELOPMENT_SYSTEM.md
- WORKFLOW.md
- PROJECT.md

Architecture

- DBP_v1.1
- ADR v1.0
- MASTER_IMPLEMENTATION_BACKLOG_v1.1

Sprint Documents

- SPRINT2_PLANNING.md
- SPRINT2_EXECUTION_GUIDE.md
- SPRINT2_PROMPT_LIBRARY.md

Previous Tasks

- AUTH-001
- AUTH-002
- docs/ai/memory/31_auth001.md
- docs/ai/memory/32_auth002.md

Review every dependency before implementation.

---

Dependency Verification

Verify:

- AUTH-001 approved, committed and pushed
- AUTH-002 approved, committed and pushed
- Working tree clean
- Sprint 0 kernel remains frozen
- Sprint 1 utilities unchanged

If any dependency is incomplete:

STOP.

Explain.

Wait for approval.

---

Scope

Implement ONLY AUTH-004.

Exactly as documented in:

- MASTER_IMPLEMENTATION_BACKLOG_v1.1
- DBP_v1.1
- SPRINT2_PLANNING.md

No additional features.

No refactoring.

No optimization.

No architecture changes.

---

Expected Behaviour

Implement the authentication middleware layer.

Includes only:

- AuthMiddleware
- RoleMiddleware
- Session timeout enforcement
- Absolute session timeout
- Universal inactivity timeout
- Session regeneration where documented
- Redirect unauthenticated users to /login
- Redirect expired sessions to /login with flash message
- Role authorization checks
- Logger integration

Do NOT implement password reset.

Do NOT implement remember-me.

Do NOT implement refresh tokens.

Do NOT implement API authentication.

---

Files

Create ONLY the files listed for AUTH-004.

Modify ONLY the files listed for AUTH-004.

If implementation requires additional files not documented:

STOP.

Explain.

Wait for approval.

---

Rules

- Native PHP 7.4 only
- PSR-4 compatible
- MiddlewareInterface implementation required
- Thin middleware
- No business logic in Controller
- No SQL inside middleware
- No BaseController modification
- No Router redesign
- No Session core modification unless explicitly documented
- No new helpers
- No undocumented middleware
- No placeholder code
- No TODO
- No debug code

Respect the frozen kernel.

---

Security Checklist

Verify:

✓ AuthMiddleware implements MiddlewareInterface

✓ RoleMiddleware implements MiddlewareInterface

✓ Authentication required before protected routes

✓ Role validation performed

✓ Session inactivity timeout enforced

✓ Absolute session timeout enforced

✓ Session expiration destroys authentication state

✓ Flash message shown after timeout

✓ Logger::warning() for timeout events

✓ Logger::warning() for authorization failures

✓ Logger::info() for successful authorization (if documented)

✓ Redirect to /login after timeout

✓ Redirect to appropriate page after authorization failure (per planning)

✓ No credential exposure

✓ No SQL inside middleware

---

Conflict Rules

If documentation conflicts are discovered:

STOP.

Reference the conflicting documents.

Explain the conflict.

Wait for approval.

Do not guess.

---

Do NOT execute

- git add
- git commit
- git push
- git merge
- git checkout
- git tag

---

After implementation provide

1. Implementation Summary

2. Files Created

3. Files Modified

4. Acceptance Criteria Verification

5. Security Checklist Verification

6. Definition of Done Checklist

7. Proposed Git Commit Message
(do NOT execute)

8. Documentation Deviations
(if any)

9. Dependency Verification

AUTH-004 ends after implementation.

Do NOT continue to AUTH-003.

Wait for approval.