feat(web-api): контракт customer auth для Nuxt SSR (me / refresh / Bearer bind)

[Ibochkarev]

Описание

Контракт customer auth Web API для headless/Nuxt SSR: introspection GET /customer/me, реальное продление TTL через POST /customer/token/refresh (ротация opaque token, без JWT), bind guest-корзины из валидного Bearer на login/register.

Тип изменений

• Новая функциональность (non-breaking change)

Связанные Issues

Closes #571

Как это было протестировано?

cd core/components/minishop3
php -l src/Services/TokenService.php
php -l src/Services/Customer/CustomerSessionService.php
php -l src/Controllers/Api/Web/CustomerAuthController.php
php -l src/Middleware/TokenMiddleware.php
composer test:smoke          # exit 0, 77 tests
./vendor/bin/phpunit tests/Integration/Customer/AuthManagerLifecycleTest.php
./vendor/bin/phpunit tests/Integration/Customer/ResolveApiTokenTest.php
composer stan -- src/Services/TokenService.php src/Services/Customer/CustomerSessionService.php \
  src/Controllers/Api/Web/CustomerAuthController.php src/Middleware/TokenMiddleware.php

• Автоматические тесты (composer test:smoke, PHPUnit lifecycle, PHPStan на затронутых файлах)
• Ручное тестирование на живом MODX

Конфигурация тестирования:

• MiniShop3: branch feat/issue-571-customer-auth-contract ← beta
• PHP: 8.4.17

Nuxt / SSR contract (docs для #571)

Рекомендуемый production path (BFF + Bearer)

1. Nuxt BFF держит свою httpOnly session cookie.
2. Server-side proxy к MODX с Authorization: Bearer <ms3_token>.
3. Браузер не видит raw MODX token.
4. CSRF для чистого Bearer не требуется.

Same-site cookie path

1. GET /api/v1/customer/token/get (или auto-mint на cart).
2. Запросы с credentials: 'include' и точным ms3_cors_allowed_origins.
3. Cross-site cookie: Secure + SameSite=None через MODX session_cookie_* (или follow-up settings). Иначе BFF.
4. Cookie + cross-origin без BFF — риск CSRF; предпочтителен BFF или SameSite=Lax same-site.

Запрет

Не хранить API token в localStorage / sessionStorage.

Endpoints

Method	Path	Auth
GET	/api/v1/customer/me	TokenMiddleware (guest → authenticated:false)
POST	/api/v1/customer/token/refresh	TokenMiddleware; ротация, старый revoke
POST	/api/v1/customer/login|register	без middleware; bind читает валидный Bearer → session → cookie

TTL strategy: A (refresh rotate). Sliding TTL не включён. JWT не внедрён. Отдельные ms3_token_cookie_* settings — out of scope (follow-up).

Чеклист

• Код соответствует стилю проекта
• Изменения не ломают существующую функциональность
• PHPStan проходит без новых ошибок (на затронутых файлах)
• CHANGELOG.md (релизный maintainer)

Дополнительные заметки

• #334: ложный success-stub не возвращён; тест обновлён под реальный refresh.
• Review fix: невалидный Bearer не маскирует guest cookie/session при bind.
• Rotate откатывает mint, если draft sync/transfer или revoke old fails.
• Deferred: декомпозиция TokenService (~750 LOC), DI-ключ для CustomerSessionService, Apache getallheaders beyond REDIRECT_HTTP_AUTHORIZATION.