---
phase: 02-shared-email-security
plan: 01
subsystem: infra
tags: [email, phpmailer, csrf, security, shared]

requires:
  - phase: 01-infrastructure
    provides: centralny autoloader PSR-4
provides:
  - Shared\Email\Email — klasa email z PHPMailer
  - Shared\Security\CsrfToken — CSRF z random_bytes + hash_equals
  - Wrappery w Helpers dla kompatybilności wstecznej
affects: [phase-06 admin-base, phase-17 users-security]

tech-stack:
  added: []
  patterns: [wrapper delegation dla Helpers, static utility class dla CsrfToken]

key-files:
  created: [autoload/Shared/Email/Email.php, autoload/Shared/Security/CsrfToken.php]
  modified: [autoload/Shared/Helpers/Helpers.php]

key-decisions:
  - "CsrfToken: single token per session (shopPRO pattern) zamiast multi-token array"
  - "Email: PHPMailer require via __DIR__ absolute paths"
  - "Helpers::get_token() wywołuje regenerate() + getToken() — zachowuje semantykę jednorazowego tokenu"

patterns-established:
  - "Wrapper delegation: stara metoda w Helpers deleguje do nowej klasy"
  - "Security: random_bytes(32) + hash_equals() jako standard"

duration: ~8min
completed: 2026-04-04
---

# Phase 2 Plan 01: Shared Email + Security Summary

**Shared\Email\Email z PHPMailer i Shared\Security\CsrfToken z kryptograficznie bezpiecznym tokenem, plus wrappery w Helpers.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~8min |
| Completed | 2026-04-04 |
| Tasks | 3 completed |
| Files modified | 3 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Email class | Pass | send(), email_check(), load_by_name(), PHPMailer |
| AC-2: CsrfToken class | Pass | random_bytes(32), hash_equals(), regenerate() |
| AC-3: Wrappery w Helpers | Pass | send_email(), get_token(), is_token_valid() delegują |

## Accomplishments

- Utworzono `Shared\Email\Email` z pełną obsługą PHPMailer, załączników, reply-to, regex URL fix
- Utworzono `Shared\Security\CsrfToken` z kryptograficznie bezpiecznym tokenem (upgrade z sha1/mt_rand)
- Wrappery w Helpers zachowują pełną kompatybilność wsteczną

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `autoload/Shared/Email/Email.php` | Created | OOP Email z PHPMailer |
| `autoload/Shared/Security/CsrfToken.php` | Created | CSRF token management |
| `autoload/Shared/Helpers/Helpers.php` | Modified | Wrappery delegujące do nowych klas |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Single token per session (CsrfToken) | Wzór shopPRO, prostsze, bezpieczniejsze | Legacy multi-token array zastąpiony |
| get_token() = regenerate() + getToken() | Zachowuje semantykę: każde wywołanie daje nowy token | Kompatybilność z kodem który zakłada jednorazowy token |
| PHPMailer require via __DIR__ | Absolute paths, działa z każdego entry pointa | Eliminuje problem relatywnych ścieżek |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Scope additions | 1 | Minimal — Email.send() ma $replay param z cmsPRO |

Email.send() w cmsPRO ma dodatkowy parametr `$replay` (reply-to) którego shopPRO nie ma. Zachowano dla kompatybilności z istniejącym kodem.

## Issues Encountered

None.

## Next Phase Readiness

**Ready:**
- Shared layer kompletny (Cache, Helpers, Html, Image, Tpl, Email, Security)
- Fazy 3-5 (Domain repositories) mogą startować

**Concerns:**
- None

**Blockers:**
- None

---
*Phase: 02-shared-email-security, Plan: 01*
*Completed: 2026-04-04*