docs: Sanctum SPA Authentication Guide (httpOnly Cookies) #220
+580
−9
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
💡 Tip: Consider Using Draft PRsBenefits of opening PRs as drafts initially:
How to convert:
This is just a friendly reminder - feel free to continue as is! 😊 |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Copilot finished reviewing on behalf of
kevalyq
November 24, 2025 19:11
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for Laravel Sanctum SPA authentication using httpOnly cookies. The documentation covers architecture, configuration, testing, troubleshooting, and production deployment. While the backend implementation is already complete and tested (22 passing tests), this documentation provides essential guidance for developers implementing the frontend integration and understanding the security model.
Key Changes
- Added 564-line comprehensive guide covering Sanctum SPA authentication with httpOnly cookies
- Documented dual authentication support (SPA session cookies + API bearer tokens)
- Included detailed troubleshooting section for common CSRF, CORS, and cookie issues
- Updated CHANGELOG with new documentation entry
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
docs/guides/sanctum-spa-auth.md |
New comprehensive guide with architecture diagrams, configuration examples, TypeScript/PHP code samples, troubleshooting, and production deployment checklist |
CHANGELOG.md |
Added entry for Sanctum SPA Authentication Guide under Unreleased section |
- Create docs/guides/sanctum-spa-auth.md (600+ lines) * Complete architecture overview with flow diagrams * Detailed configuration documentation for Laravel 11 + Sanctum * Environment variable setup with SANCTUM_STATEFUL_DOMAINS example * API endpoint documentation with curl examples * Testing guide with Pest PHP examples * Troubleshooting section for common issues * Production deployment checklist * Security best practices * TypeScript frontend integration examples with proper types - Update CHANGELOG.md with documentation entry - Fix all Copilot review comments: * Fixed malformed markdown in environment variables section * Merged duplicate '### Added' sections (Keep a Changelog compliance) * Added API_URL constant definition to prevent runtime errors * Added TypeScript interface for LoginCredentials * Clarified comment about token handling in SPA mode * Changed license to AGPL-3.0-or-later for consistency with other guides All backend configuration (Sanctum stateful domains, CORS with credentials, session cookies with httpOnly/Secure/SameSite) already verified and tested. 22 tests passing (14 SanctumCookieAuthTest + 8 CsrfProtectionTest). Fixes #218
kevalyq
force-pushed
the
feature/218-sanctum-spa-config-docs
branch
from
e994d3d to
1c5ad1d
Compare
Copilot finished reviewing on behalf of
kevalyq
November 25, 2025 05:20
Fixes 8 code review issues identified by GitHub Copilot: Session Cookie Name: - Corrected cookie name from 'secpal_session' to 'secpal-session' throughout - Matches Laravel's Str::slug() format: APP_NAME + '-session' - Updated in: diagrams, code examples, curl commands, PHP tests CHANGELOG Format Compliance: - Removed '### Added (continued)' heading (Keep a Changelog violation) - Merged all Added entries into single section - Moved Changed section after Added section - Improved cross-repo references: (api#217, frontend#205) → (#217, SecPal/frontend#205) API Response Correction: - Fixed: return data.data → return data - AuthController returns {token, user} directly, no data wrapper - Updated comment to clarify SPA ignores token, uses session cookie Session Driver Documentation: - Corrected default: 'database' (not 'cookie') - Matches config/session.php line 25 actual default - Added clarifying comment about driver options Curl Token Extraction: - Improved robustness: awk '{print $7}' → sed + cut approach - Less fragile when cookie attributes vary All changes maintain documentation accuracy and follow project conventions.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Adds comprehensive documentation for Laravel Sanctum SPA authentication with httpOnly cookies. All backend configuration was already in place and tested - this PR provides complete developer documentation.
Part of Epic #217 (Backend: httpOnly Cookie Authentication)
Changes
New Documentation
docs/guides/sanctum-spa-auth.md(600+ lines)Updated Files
CHANGELOG.md: Added entry referencing Epic [EPIC] httpOnly Cookie Authentication Migration #217 and frontend fix: Move RateLimiter configuration to AppServiceProvider #205Configuration Status
✅ All Backend Configuration Complete:
config/sanctum.php)config/cors.php)config/session.php).env.example)Testing
✅ 22 Tests Passing:
SanctumCookieAuthTest.php(auth flow, sessions, cookies)CsrfProtectionTest.php(token validation, middleware)All tests verified before creating this documentation.
Documentation Highlights
Quality
Related Issues
Fixes #218
Part of Epic #217 - Backend: httpOnly Cookie Authentication
Coordinates with frontend #205 - httpOnly Cookie Authentication
Checklist