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.

[biz87]

Привет! Влил по твоему порядку #584 и #583 — оба в beta, issues #576 и #572 закрыты.

Этот PR нужно ребейзнуть на текущую beta: конфликт в TokenMiddleware.php семантический, руками разруливать не стал, чтобы не потерять security-фикс.

Суть конфликта. PR писался до вливания #584, и в нём удалены/перенесены методы, которые #584 как раз добавил:

• stripQueryStringApiTokens() — это фикс [Bug] Web API: hardening rate-limit key, CORS wildcard match, token in query #576 (query-токен больше не принимается как учётные данные). В ветке этого PR его нет;
• resolveToken() — в fix(web-api): hardening rate-limit, CORS wildcards, query tokens #584 переписан на trusted sources (Bearer → MS3TOKEN → cookie → session), в этом PR он выносится в общий сервис.

Плюс собственный тест PR после мержа с beta падает:

FAIL: TokenMiddleware must not keep a private resolveToken duplicate: expected false
(tests/CustomerSessionContractTest.php)

То есть контракт «резолв живёт в одном месте» конфликтует с тем, как метод выглядит после #584. При ребейзе важно, чтобы strip query-токенов сохранился в том слое, куда переедет резолв, — иначе #576 частично откатится.

Мелочь заодно: файл tests/TokenRefreshRouteRemovedTest.php теперь проверяет обратное тому, что написано в имени — что роут POST /customer/token/refresh зарегистрирован. Стоит переименовать (например TokenRefreshRouteContractTest), иначе через полгода это будет сбивать с толку.

Сам код посмотрел, вопросов нет: refreshToken() реально ротирует токен через rotateApiToken() (не заглушка, как было в #351), /me отдаёт CustomerPublicDto и из токена только expires_at/customer_id. Как ребейзнёшь — сразу провалидирую и вольём.

Дальше по твоему списку иду: #586, #587, #595, потом #580 после ребейза, #585 отдельно.