feat(router): add signature validation middleware and route attribute

[Tresor-Kasenda]

This PR adds a route decorator attribute that automatically validates signed URLs, eliminating the need for manual validation in each controller method.

Motivation

Currently, when using signed URLs, developers must manually validate the signature in every controller method:

final class PasswordlessAuthenticationController
{
    public function __construct(
        private readonly UriGenerator $uri,
    ) {}

    public function __invoke(Request $request): Response
    {
        if (! $this->uri->hasValidSignature($request)) {
            return new Forbidden();
        }

        // Actual logic here...
    }
}

This is repetitive, error-prone, and clutters controller code with validation logic.

Solution

The new #[ValidSignature] attribute handles validation automatically:

#[Get('/verify-email/{token}')]
#[ValidSignature]
public function verifyEmail(string $token): Response
{
    // This code only executes if the signature is valid
    // 403 Forbidden is returned automatically if invalid
}

Features

• Declarative validation - Just add the attribute, no boilerplate code
• Automatic 403 response - Returns Forbidden when:
  • Signature is missing
  • Signature is invalid (URL was tampered)
  • Signature has expired (for temporary signed URLs)
• Works with existing signed URL functions - Compatible with signed_uri() and temporary_signed_uri()
• Route-specific middleware - Only runs on routes with the attribute (not globally)

Usage Examples

Permanent signed URL

// Generate URL
$url = signed_uri(
    action: [EmailVerificationController::class, 'verify'],
    userId: $user->id,
    email: $user->email,
);

// Controller - automatically validates signature
#[Get('/verify-email')]
#[ValidSignature]
public function verify(int $userId, string $email): Response
{
    // Safe to proceed - signature was validated
}

Temporary signed URL

// Generate URL with 10-minute expiration
$url = temporary_signed_uri(
    action: PasswordResetController::class,
    duration: Duration::minutes(10),
    token: $resetToken,
);

// Controller - automatically validates signature AND expiration
#[Get('/reset-password/{token}')]
#[ValidSignature]
public function __invoke(string $token): Response
{
    // Safe to proceed - signature is valid and not expired
}

[innocenzi]

I'd call the middleware ValidateSignatureMiddleware.

I think we also need a convention for the route attributes, cc @brendt.