Airlock Laravel Package

Technical Evaluation

Architecture Fit

• Lightweight Authentication: Sanctum is purpose-built for SPAs (Single-Page Applications) and simple APIs, aligning perfectly with modern Laravel applications requiring stateless token-based auth. Its minimalist design avoids bloat while providing essential features like token generation, validation, and revocation.
• Laravel Ecosystem Integration: Deeply integrated with Laravel’s core (e.g., middleware, guards, Eloquent), reducing friction for adoption. Works seamlessly with Laravel’s built-in auth system (e.g., HasApiTokens trait, Sanctum guard).
• Stateless vs. Stateful: Supports both stateless APIs (via tokens) and stateful SPAs (via cookies), offering flexibility for hybrid architectures. The stateful configuration allows SPAs to use session-like behavior without traditional sessions.
• Token Management: Built-in token expiration, revocation, and scoping (via tokenCan()) aligns with security best practices. Recent optimizations (e.g., indexed personal_access_tokens table) improve performance for high-scale use cases.

Integration Feasibility

• Prerequisites: Requires Laravel 10+ and PHP 8.1+. Compatibility with Laravel 13 is confirmed (v4.3.1+), but Laravel 11+ is the sweet spot for long-term support.
• Database Schema: Includes a single migration (personal_access_tokens), which is lightweight and non-intrusive. No complex schema changes are required.
• Middleware: Leverages Laravel’s middleware stack (e.g., EnsureFrontendRequestsAreStateful, Authenticate). Existing middleware can be extended or overridden.
• Customization: Highly extensible via:
  • Token Resolution: Override getAccessTokenFromRequestUsing() to customize token extraction (e.g., from headers, query params).
  • Token Creation: Extend createToken() or use HasApiTokens trait for custom token logic.
  • Guards: Supports multiple guards (e.g., sanctum + api), enabling granular auth logic.
• API/SPA Use Cases:
  • SPAs: Stateless token auth via Authorization: Bearer headers.
  • Simple APIs: Stateless or stateful (cookie-based) auth for frontend-backend communication.
  • Mobile Apps: Token-based auth with optional token expiration.

Technical Risk

• Laravel Version Lock-In: Sanctum’s rapid updates (e.g., Laravel 13 support in v4.3.1) may require frequent dependency updates. Risk: Minor if using LTS Laravel versions (e.g., 11/12).
• Token Security:
  • Risk: Token leakage (e.g., via localStorage in SPAs) is inherent to stateless auth. Mitigation: Use short-lived tokens + stateful mode for SPAs.
  • Risk: CSRF vulnerabilities in stateful mode. Mitigation: Sanctum includes EnsureFrontendRequestsAreStateful middleware to validate X-Requested-With headers.
• Performance:
  • Risk: Token lookup performance at scale. Mitigation: Recent optimizations (e.g., indexed personal_access_tokens) address this. Benchmark with expected load.
  • Risk: Stateless token validation overhead. Mitigation: Sanctum’s design minimizes this via efficient token hashing (e.g., crc32b).
• Migration Path:
  • Risk: Breaking changes in major versions (e.g., v3.0.0 introduced token expiration). Mitigation: Sanctum’s changelog is thorough; test thoroughly during upgrades.
  • Risk: Custom token models. Mitigation: Sanctum v4+ supports generics (HasApiTokens trait), reducing coupling.

Key Questions

1. Use Case Clarity:
   • Is Sanctum replacing an existing auth system (e.g., Passport, JWT)? If so, what are the trade-offs (e.g., Passport’s OAuth2 vs. Sanctum’s simplicity)?
   • Will the application use stateful (cookie-based) or stateless (token-based) auth? This impacts middleware and frontend implementation.
2. Scalability Needs:
   • What is the expected token volume (e.g., 1M+ tokens)? Sanctum’s performance optimizations (e.g., indexed tokens) may need further tuning.
   • Are there multi-tenant requirements? Sanctum doesn’t natively support multi-tenancy; this would require custom logic (e.g., scoped tokens).
3. Security Requirements:
   • Are token expiration and revocation critical? Sanctum supports both but may need custom logic for complex workflows (e.g., OAuth2 revocation endpoints).
   • How will token storage work on the frontend? For SPAs, avoid localStorage; prefer HttpOnly cookies (stateful) or secure token managers.
4. Integration Complexity:
   • Does the application use custom user models? Sanctum’s HasApiTokens trait supports this, but testing is required.
   • Are there third-party API integrations? Sanctum’s stateless tokens work well for machine-to-machine auth.
5. Team Expertise:
   • Is the team familiar with Laravel’s auth system? Sanctum’s simplicity reduces learning curve, but middleware customization may require deeper knowledge.
   • Are there legacy systems relying on sessions? Sanctum’s stateful mode can coexist but may require session cleanup.

Integration Approach

Stack Fit

• Laravel Core: Sanctum is a first-class citizen in the Laravel ecosystem, designed to work with:
  • Eloquent Models: HasApiTokens trait for user/token relationships.
  • Middleware: Built-in middleware for auth, CSRF, and stateful checks.
  • Routing: Predefined routes for token creation/revocation (customizable via routes config).
  • Testing: Mockable auth logic for PHPUnit/Pest tests.
• Frontend Compatibility:
  • SPAs: Works with React, Vue, Next.js, etc., via fetch/axios with Authorization headers or stateful cookies.
  • Mobile Apps: Native support for token-based auth (e.g., iOS/Android apps calling Laravel APIs).
• Database Support:
  • MySQL/PostgreSQL/SQLite: Officially supported. No vendor-specific quirks (e.g., PostgreSQL’s text column for token names).
  • Custom Token Models: Possible via generics in HasApiTokens (v4+), but requires testing.

Migration Path

1. Assessment Phase:
   • Audit existing auth flows (e.g., session-based, Passport, custom JWT).
   • Identify endpoints requiring token auth (e.g., API routes, SPA calls).
   • Decide: Stateless (tokens) or Stateful (cookies) or Hybrid.
2. Proof of Concept (PoC):
   • Install Sanctum (composer require laravel/sanctum).
   • Run migrations (php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider").
   • Test token generation/revocation with a single route.
   • Validate frontend integration (e.g., SPA login flow).
3. Incremental Rollout:
   • Phase 1: Replace session-based auth for SPAs with Sanctum tokens.
   • Phase 2: Migrate API endpoints to token auth, one service at a time.
   • Phase 3: Deprecate legacy auth systems (e.g., sessions, Passport).
4. Configuration:
   • Update config/sanctum.php:

     'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost,127.0.0.1,.yourspa.com')),
     'expiration' => null, // Or set TTL (e.g., now()->addDays(14))
     'middleware' => ['web', 'api'], // Adjust as needed
     

   • Publish Sanctum’s assets/config:

     php artisan vendor:publish --tag="sanctum-config" --tag="sanctum-migrations"
     

Compatibility

• Laravel Versions:
  • Recommended: Laravel 11/12 (Sanctum v4.x).
  • Supported: Laravel 10 (Sanctum v3.x), but upgrade path exists.
  • Avoid: Laravel <10 (EOL).
• PHP Versions:
  • Minimum: PHP 8.1 (Sanctum v4.0+).
  • Recommended: PHP 8.2+ for performance and security.
• Frontend Frameworks:
  • SPAs: Works with any framework (React, Vue, Svelte) via fetch/axios.
  • Server-Side Rendering (SSR): Stateful mode (cookies) is ideal for Next.js/Nuxt.
• Third-Party Packages:
  • Passport: Sanctum is not a drop-in replacement; migration requires rearchitecting OAuth2 flows.
  • JWT: Sanctum uses Laravel’s native token hashing (not JWT). If JWT is required, consider `