Backend PR-3: Tests & API Documentation Update

[kevalyq]

📦 Sub-Issue of Epic #208

Part of: SecPal/frontend#208 (httpOnly Cookie Authentication Migration)
Priority: High
Area: Backend, Testing, Documentation
Repository: api

Goal

Add comprehensive tests for httpOnly cookie authentication flow and update API documentation to reflect the new authentication mechanism.

Acceptance Criteria

• Integration tests for login with httpOnly cookies
• Integration tests for CSRF protection
• Integration tests for logout flow
• Integration tests for authenticated requests with cookies
• Tests verify cookies are httpOnly
• Tests verify cookies have correct sameSite attribute
• API documentation updated (OpenAPI spec in contracts repo)
• Migration guide for developers documented
• Code coverage ≥80% for new code
• PHPStan passes
• Pint passes
• All tests pass

Implementation Details

New test files:

• tests/Feature/Auth/SanctumCookieAuthTest.php
• tests/Feature/Auth/CsrfProtectionTest.php

Test scenarios:

1. Login returns httpOnly cookie
2. Authenticated request with cookie succeeds
3. Request without cookie fails (401)
4. CSRF token validation works
5. Request without CSRF token fails (419)
6. Logout clears cookies
7. Cookie attributes correct (httpOnly, secure, sameSite)

Documentation updates:

• Update docs/api/authentication.md
• Add migration guide in CHANGELOG.md
• Update README.md with new auth flow

Dependencies

• Depends on: Backend PR-1, Backend PR-2 (implementation must be complete)
• Blocks: None (final backend step)

Testing

ddev exec php artisan test --filter=Auth
ddev exec php artisan test --coverage
ddev exec vendor/bin/phpstan analyze
ddev exec vendor/bin/pint --test --dirty

References

• Laravel HTTP Tests
• Pest Testing
• Epic: [EPIC] Security: Migrate authentication from localStorage to httpOnly cookies frontend#208

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.