Signed Request Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require br/signed-request-bundle
   

   Add to config/bundles.php:

   Baldurrensch\SignedRequestBundle\BaldurrenschSignedRequestBundle::class => ['all' => true],
   

2. Configuration: Add to config/packages/baldurrensch_signed_request.yaml:

   baldurrensch_signed_request:
       salt: '%env(SIGNED_REQUEST_SALT)%'  # Store this securely in .env
       verify_request: true
       sign_response: true
   

3. First Use Case:

   • Client-Side: Append X-SignedRequest header to requests with:

     const signature = md5(requestUri + JSON.stringify(requestBody) + salt);
     headers['X-SignedRequest'] = signature;
     

   • Server-Side: The bundle auto-verifies requests and signs responses. No manual code needed for basic usage.

Implementation Patterns

Workflows

1. Request Verification:

   • Enable verify_request: true to enforce signed requests globally.
   • Exclude routes via annotations:

     /**
      * @Route("/public", name="public_route")
      * @SignedRequest(verify=false)
      */
     public function publicAction() { ... }
     

2. Response Signing:

   • Enable sign_response: true to auto-sign all responses.
   • Customize signing logic by extending the Signer service:

     services:
         baldurrensch_signed_request.signer:
             class: App\Service\CustomSigner
             arguments: ['%baldurrensch_signed_request.salt%']
             tags: ['baldurrensch_signed_request.signer']
     

3. API Integration:

   • Useful for validating incoming API requests (e.g., webhooks, mobile apps).
   • Example: Validate a webhook payload in a controller:

     use Baldurrensch\SignedRequestBundle\EventListener\RequestListener;
     
     public function webhookAction(Request $request) {
         $listener = $this->container->get('baldurrensch_signed_request.request_listener');
         if (!$listener->isRequestValid($request)) {
             throw new \RuntimeException('Invalid signature');
         }
         // Process request...
     }
     

4. Custom Headers:

   • Override the default X-SignedRequest header via config:

     baldurrensch_signed_request:
         signature_header: 'X-Custom-Signature'
     

Gotchas and Tips

Pitfalls

1. Salt Management:

   • The salt must be kept secret (e.g., in .env). Never commit it to version control.
   • Changing the salt invalidates all existing signatures. Plan migrations carefully.

2. Case Sensitivity:

   • Headers (e.g., X-SignedRequest) are case-insensitive in HTTP, but the bundle enforces exact matching. Avoid typos in config.

3. Content-Type Dependencies:

   • The bundle assumes Content-Type: application/json for request signing. For other formats (e.g., form-data), extend the RequestListener:

     public function isRequestValid(Request $request) {
         if ($request->getContentType() === 'application/x-www-form-urlencoded') {
             $content = $request->request->all();
         }
         // Custom logic...
     }
     

4. Performance:

   • MD5 signing is lightweight, but avoid signing large payloads (e.g., file uploads). Use this for metadata or small payloads.

5. Debugging:

   • Enable debug mode to log validation failures:

     baldurrensch_signed_request:
         debug: true
     

   • Check Symfony’s profiler for signed_request events.

Tips

1. Testing:

   • Mock the RequestListener in PHPUnit:

     $listener = $this->createMock(RequestListener::class);
     $listener->method('isRequestValid')->willReturn(true);
     $this->container->set('baldurrensch_signed_request.request_listener', $listener);
     

2. Partial Signing:

   • Sign only specific routes by excluding others:

     baldurrensch_signed_request:
         verify_request: false  # Default off
     

     Then enable signing for critical routes via annotations.

3. Non-Symfony Projects:

   • Use the bundle’s core logic in Laravel by extracting the Signer class and adapting it to Laravel’s request/response objects.

4. Security:

   • Combine with other measures (e.g., IP whitelisting) for high-security endpoints.
   • Rotate salts periodically and invalidate old signatures.

5. Extending:

   • Override the Signer class to use HMAC-SHA256 instead of MD5:

     use Symfony\Component\HttpFoundation\BinaryFileResponse;
     
     class CustomSigner extends Signer {
         protected function sign($content) {
             return hash_hmac('sha256', $content, $this->salt);
         }
     }