Crayfish Commons Syn Laravel Package

Technical Evaluation

Architecture Fit

• Multi-tenancy Focus: The package is explicitly designed to address multi-tenancy gaps left by Crayfish-Commons 4.x’s Syn JWT integration. If the application requires tenant-aware JWT validation (e.g., dynamic token claims per tenant), this package provides a targeted solution.
• Lexik JWT Foundation: Built on top of Lexik/JWTAuthenticationBundle, it aligns with Symfony’s security ecosystem, making it a natural fit for Symfony/Laravel (via Symfony Bridge) applications needing JWT auth.
• Standalone Syn Parsing: Since Syn parsing was removed from Crayfish-Commons, this package reintroduces it in a modular way, reducing dependency bloat for projects only needing JWT auth.

Integration Feasibility

• Laravel Compatibility:
  • Symfony Bridge Required: Laravel lacks native Symfony security components, so integration would require:
    • Symfony Security Bundle (via symfony/security-bundle).
    • Lexik JWT Bundle (lexik/jwt-authentication-bundle).
    • Custom Authenticator Adapter to bridge Symfony’s AuthenticatorInterface with Laravel’s Authenticatable.
  • Feasibility: Medium-High. Possible but non-trivial due to Laravel’s divergent auth stack.
• Key Dependencies:
  • PHP 7.2+ (Laravel 8+ supports this).
  • Composer (standard in Laravel).
  • Symfony’s EventDispatcher (Laravel has a compatible Illuminate\Events system).

Technical Risk

• Risk 1: Authenticator Interface Mismatch
  • Laravel’s Authenticatable and Symfony’s AuthenticatorInterface differ. Custom glue code will be needed to adapt the authenticator.
  • Mitigation: Abstract the authenticator behind a Laravel-compatible facade or middleware.
• Risk 2: Event System Differences
  • Symfony’s EventDispatcher is used for JWT events (e.g., security.authentication.success). Laravel’s Events system is similar but not identical.
  • Mitigation: Use a wrapper class to translate Symfony events to Laravel events.
• Risk 3: Tenant Context Propagation
  • Multi-tenancy in Laravel often relies on context managers (e.g., tenancy package). The package assumes Symfony’s RequestStack for tenant resolution.
  • Mitigation: Override tenant resolution logic to use Laravel’s request context (e.g., request()->tenant()).
• Risk 4: Documentation Gaps
  • Minimal README and reliance on Islandora docs (Symfony-focused). Laravel-specific quirks (e.g., service container binding) may not be covered.
  • Mitigation: Conduct a proof-of-concept (PoC) with a minimal Laravel app to validate integration.

Key Questions

1. Is multi-tenancy a hard requirement?
   • If not, Lexik JWT alone may suffice, reducing integration effort.
2. What’s the Laravel auth stack?
   • Using Laravel’s built-in auth? Sanctum/Passport? This affects how the authenticator is wired.
3. How are tenants identified?
   • Subdomains? Paths? Headers? The package expects Symfony’s RequestStack; Laravel may need custom tenant extraction.
4. Is Symfony’s EventDispatcher acceptable?
   • If not, event-driven features (e.g., post-auth hooks) may need rewriting.
5. What’s the failure mode tolerance?
   • If JWT validation fails, how should Laravel handle it (e.g., 401 vs. redirect)?

Integration Approach

Stack Fit

• Core Stack:
  • Laravel 8+ (PHP 7.2+ compatible).
  • Symfony Bridge:
    • symfony/security-bundle (for AuthenticatorInterface).
    • lexik/jwt-authentication-bundle (JWT core).
  • Laravel Auth Integration:
    • Middleware to intercept requests and delegate to Symfony’s authenticator.
    • Custom AuthManager to bridge Laravel’s Auth facade with Symfony’s AuthenticationUtils.
• Multi-Tenancy:
  • Use a tenant-aware middleware (e.g., tenant-middleware) to set the tenant context before JWT validation.
  • Override islandora_crayfish_commons_syn.jwt.authenticator to resolve tenants via Laravel’s request context.

Migration Path

1. Phase 1: Dependency Setup
   • Install required packages:

     composer require symfony/security-bundle lexik/jwt-authentication-bundle discoverygarden/crayfish-commons-syn
     

   • Configure Symfony bundles in config/bundles.php (Laravel’s Symfony bridge).
2. Phase 2: Authenticator Adapter
   • Create a Laravel middleware (app/Http/Middleware/JwtAuthenticate.php) that:
     • Extracts the JWT from the Authorization header.
     • Delegates validation to the Symfony authenticator.
     • Sets the Laravel user on success.
   • Example:

     public function handle(Request $request, Closure $next) {
         $authenticator = app()->make('islandora_crayfish_commons_syn.jwt.authenticator');
         $token = $request->bearerToken();
         $authResult = $authenticator->authenticate(new Request($request->toArray(), [], [], [], [], $request->server()), new MockHttpFoundationRequest($request));
     
         if ($authResult->isAuthenticated()) {
             auth()->login($authResult->getUser());
         }
         return $next($request);
     }
     

3. Phase 3: Tenant Context Integration
   • Modify the authenticator to resolve tenants from Laravel’s request (e.g., request()->tenant()).
   • Register a tenant middleware before JwtAuthenticate to set the context.
4. Phase 4: Event System Bridge
   • Create a Laravel event listener to translate Symfony’s security.authentication.success to Laravel’s auth.login or a custom event.
5. Phase 5: Configuration
   • Merge Symfony’s security.yaml requirements into Laravel’s config/security.php (or equivalent).
   • Example:

     'security' => [
         'enable_authenticator_manager' => true,
         'providers' => [
             'users' => [
                 'memory' => [], // Placeholder; replace with Laravel user provider
             ],
         ],
         'firewalls' => [
             'main' => [
                 'anonymous' => false,
                 'provider' => 'users',
                 'custom_authenticators' => [
                     'islandora_crayfish_commons_syn.jwt.authenticator',
                 ],
             ],
         ],
     ],
     

Compatibility

• Pros:
  • Leverages Laravel’s service container for dependency injection.
  • Middleware-based auth aligns with Laravel’s routing system.
  • MIT license allows easy modification.
• Cons:
  • Symfony-specific abstractions (e.g., RequestStack) require adaptation.
  • No native Laravel support: All features must be shimmed.
  • Multi-tenancy logic may conflict with existing Laravel tenancy solutions (e.g., stancl/tenancy).

Sequencing

1. Validate Tenant Strategy
   • Decide how tenants are identified (e.g., subdomain, header, or path).
2. Implement Auth Middleware
   • Start with a minimal JWT validation middleware before adding tenant logic.
3. Integrate Tenant Context
   • Ensure the authenticator can resolve tenants from Laravel’s request.
4. Test Edge Cases
   • Invalid JWTs, missing tenants, and concurrent requests.
5. Optimize Performance
   • Cache tenant lookups if resolution is expensive.

Operational Impact

Maintenance

• Pros:
  • Modular design: Only the auth layer is affected; business logic remains unchanged.
  • MIT license: Easy to fork/modify if upstream changes break compatibility.
• Cons:
  • Dual Auth Stack: Maintaining both Laravel and Symfony auth components increases complexity.
  • Dependency Bloat: Adding Symfony bundles may introduce unused features (e.g., Symfony’s form auth).
  • Long-Term Viability: If the package is abandoned (0 stars, low activity), custom maintenance may be needed.

Support

• Challenges:
  • Limited Documentation: Relies on Islandora’s Symfony-focused docs.
  • Community Support: No active maintainers or Laravel-specific help.
  • Debugging: Symfony/Laravel auth interactions may produce cryptic errors.
• Mitigations:
  • Logging: Add verbose logging for JWT/tenant resolution steps.
  • PoC Validation: Test with a disposable Laravel app before production integration.
  • Fallback Plan: Have a Lexik JWT-only implementation as a backup.

Scaling

• Performance:
  • JWT Validation: Lexik JWT is optimized; expect low overhead.
  • Tenant Resolution: If tenant lookups are database-bound, cache results (e.g