README

A robust Laravel package providing a middleware for validating API requests with HMAC-SHA256 signatures. It features configurable signature templates, version-specific authentication settings, and a secure, time-based validation to protect your endpoints.

✨ Features

• HMAC-SHA256 Validation: Securely validates incoming API requests.
• Configurable Signature Templates: Easily define the exact order and components of the string-to-be-signed.
• Version-Specific Rules: Apply different secrets, states, and signature templates based on an X-Auth-Version header.
• Timestamp Validation: Protects against replay attacks by ensuring requests are recent.
• Simple Middleware Integration: Secure your routes with a single middleware alias: auth.signature.
• Clean and Modern Codebase: Fully typed, tested, and built on modern PHP and Laravel features.

📋 Requirements

• PHP: ^8.4
• Laravel: 12.x or 13.x

🚀 Installation

1. Install the package via Composer:

   composer require aporat/laravel-auth-signature

2. Publish the configuration file. The service provider is auto-discovered.

   php artisan vendor:publish --provider="Aporat\AuthSignature\AuthSignatureServiceProvider" --tag="config"

   This will create a new configuration file at config/auth-signature.php.

🔧 Configuration

Edit config/auth-signature.php to define your clients, authentication versions, and settings.

<?php

return [
    /*
    | Defines the time window, in seconds, for which a signature is valid.
    | This helps prevent replay attacks. Default is 300 seconds (5 minutes).
    */
    'timestamp_tolerance_seconds' => 300,

    /*
    | Define each client that can make signed requests.
    | The key is the Client ID sent in the `X-Auth-Client-ID` header.
    */
    'clients' => [
        'your-client-id' => [
            // The secret key used to sign requests for this client.
            'client_secret' => env('CLIENT_SECRET_KEY'),
            // The bundle ID or unique identifier for the client application.
            'bundle_id' => 'com.yourcompany.yourapp',
            // (Optional) The minimum auth version this client must use.
            'min_auth_level' => 10,
        ],
    ],

    /*
    | Define rules for different signature versions.
    | This allows you to evolve your signature algorithm over time.
    */
    'auth_versions' => [
        10 => [
            // (Optional) A version-specific secret appended to the client's secret.
            'secret' => env('AUTH_V10_SECRET'),
            // (Optional) A static string included in the signature for this version.
            'state' => 'some_static_string_for_v10',
            // (Optional) The exact order of components for the string-to-be-signed.
            'signature_template' => [
                'bundle_id', 'timestamp', 'client_id', 'state',
                'auth_version', 'method', 'signature', 'path',
            ],
        ],
    ],
];

Remember to add the corresponding keys to your .env file for security.

🛠️ Usage

Applying the Middleware

Apply the auth.signature middleware to any route or route group that requires signature validation.

// in routes/api.php
Route::middleware('auth.signature')->group(function () {
    Route::get('/orders', [OrderController::class, 'index']);
    Route::post('/orders', [OrderController::class, 'store']);
});

The middleware will automatically validate incoming requests and throw a SignatureException (resulting in a 4xx HTTP response) if validation fails.

What the signature covers

The signature is an HMAC-SHA256 over the concatenation (no separator) of the components named by the auth version's signature_template. The signature component is the canonical parameter string, built from the request as follows:

1. Parameter keys are lowercased.
2. Keys are sorted as plain strings (so "10" sorts before "9").
3. Each key/value pair is encoded as rawurlencode(key)=value, and the pairs are joined with &.
4. Values encode as: null → empty, true/false → 1/0, integers verbatim, floats keeping their zero fraction (1.0, not 1), objects as compact JSON with recursively sorted keys, and everything else percent-encoded with rawurlencode.
5. List values expand to key[0], key[1], … after the sort, in list order — tags[10] therefore follows tags[9], and a[0] precedes a2. Expansion is recursive, and an empty list encodes as key=.

The parameter set is read off the wire: the raw request body (JSON decoded on a JSON request, parse_str on a form-urlencoded one) unioned with the raw query string, with the body winning a key collision.

It is deliberately not $request->input(). Laravel's TrimStrings and ConvertEmptyStringsToNull are global middleware, so they rewrite the parsed bags before any route middleware — including this one — runs. Verifying against those rewritten values means a client that legitimately signs name=Rabi%20 gets checked against name=Rabi, and every request carrying leading or trailing whitespace in a string field is rejected with a mismatch the client cannot see or fix. Reading the raw request leaves both transforms in place for the application behind the middleware.

The query string is included because query parameters are readable through $request->input() regardless of content type, so leaving them out would let anyone append parameters to a captured request without invalidating it. Uploaded files are not signed — their temporary paths differ on every request — so a multipart upload signs only its text fields, which are read from the parsed bag because PHP consumes a multipart body before php://input can be read.

The path component is the percent-decoded path (rawurldecode, which leaves a literal + alone), and bundle_id is taken from the client's configuration verbatim.

Generating a Signature

You can use the SignatureGenerator class to create a valid signature, which is useful for testing or for client-side implementations.

use Aporat\AuthSignature\SignatureGenerator;

// Resolve the generator from the container
$generator = app(SignatureGenerator::class);

$signature = $generator->generate(
    clientId: 'your-client-id',
    authVersion: 10,
    timestamp: time(),
    method: 'GET',
    path: '/api/orders',
    params: ['page' => 1]
);

// The output will be a 64-character HMAC-SHA256 hash
// e.g., "b5f0029b48b61a9151528c11e74f115340f666d44a141b279d633036e88c0353"

Example Client Request

A client would then make a request including the generated signature and other required headers.

# Store timestamp and generate signature first
TIMESTAMP=$(date +%s)
SIGNATURE="..." # Generate signature using the same timestamp

curl -X GET "[http://yourapp.test/api/orders?page=1](http://yourapp.test/api/orders?page=1)" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Client-ID: your-client-id" \
  -H "X-Auth-Version: 10" \
  -H "X-Auth-Timestamp: $TIMESTAMP" \
  -H "X-Auth-Signature: $SIGNATURE"

🧪 Testing

The package is fully tested. To run the test suite:

# Run all tests
composer test

# Run tests with code coverage
composer test-ci

🤝 Contributing

Contributions are welcome! Please feel free to fork the repository, create a feature branch, and open a pull request.

📜 License

This package is open-source software licensed under the MIT License.

💬 Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.