README

Laravel middleware and helpers for VormiaQuery encrypted API integration.

Installation

Option 1: Manual Installation

Install via Composer:

composer require vormiaphp/vormiaqueryphp
composer require phpseclib/phpseclib

Add your RSA keys to .env:

VORMIA_PRIVATE_KEY="<contents of vormia_private.pem>"
VORMIA_PUBLIC_KEY="<contents of vormia_public.pem>"

Option 2: Using Artisan Command (Recommended)

Install via Composer:

composer require vormiaphp/vormiaqueryphp
composer require phpseclib/phpseclib

Run the installation command:

php artisan vormiaquery:install

This command will:

Check if Laravel Sanctum is installed
Add VormiaQuery environment variables to your .env and .env.example files
Publish CORS configuration if needed

Uninstallation

To remove VormiaQuery integration:

php artisan vormiaquery:install --uninstall

This command will:

Remove VormiaQuery environment variables from .env and .env.example files
Remove CORS configuration file

JavaScript Client Package

For optimal performance and RSA encryption support, install the companion JavaScript package:

npm install vormiaqueryjs

For complete documentation and examples, visit:

Middleware Usage

protected $routeMiddleware = [
    // ...
    'vormia.decrypt' => \VormiaQueryPhp\Http\Middleware\DecryptVormiaRequest::class,
    'vormia.encrypt' => \VormiaQueryPhp\Http\Middleware\EncryptVormiaResponse::class,
];

Apply the middleware to your API routes:

Route::middleware(['vormia.decrypt', 'vormia.encrypt'])->group(function () {
    Route::post('/vormia/data', [\VormiaQueryPhp\Http\Controllers\VormiaQueryController::class, 'loadData']);
});

Example Controller

namespace VormiaQueryPhp\Http\Controllers;

use Illuminate\Routing\Controller;
use Illuminate\Http\Request;

class VormiaQueryController extends Controller
{
    public function loadData(Request $request)
    {
        $data = [
            ['id' => 1, 'name' => 'Alpha'],
            ['id' => 2, 'name' => 'Beta'],
        ];

        $response = [
            'response' => $data,
            'message' => 'Success',
            'meta' => [
                'total' => count($data),
                'page' => 1,
                'perPage' => count($data),
            ],
        ];

        return response()->json($response);
    }
}

How It Works

DecryptVormiaRequest: Decrypts incoming requests with the private key if an encrypted field is present.
EncryptVormiaResponse: Encrypts outgoing responses with the public key if the request expects encryption (via header or flag).

Standard VormiaQuery Response: Always return data in the format:

{
  "response": [...],
  "message": "Success",
  "meta": { "total": 2, "page": 1, "perPage": 2 }
}

Security

Never expose your private key in frontend/browser code.
Rotate keys as needed and keep them secure.

Security Helper Examples

1. Domain Whitelisting

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::isDomainAllowed()) {
    abort(403, 'Domain not allowed');
}

2. API Token Validation

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::validateApiToken()) {
    abort(401, 'Invalid API token');
}

3. User Role and Ability Checks

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::userHasRole('admin')) {
    abort(403, 'Admin role required');
}

if (!VormiaSecurityHelper::userCan('edit-posts')) {
    abort(403, 'Permission denied');
}

4. Rate Limiting

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

$key = request()->ip(); // or use Auth::id() for user-based
if (!VormiaSecurityHelper::rateLimit($key, 10, 60)) {
    abort(429, 'Too many requests');
}

5. IP Whitelisting

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::isIpAllowed()) {
    abort(403, 'IP not allowed');
}

6. Advanced Token Validation

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::validateApiToken('advanced')) {
    abort(401, 'Invalid or insufficient token');
}

7. Combining Multiple Security Checks

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

if (!VormiaSecurityHelper::isDomainAllowed()) {
    abort(403, 'Domain not allowed');
}
if (!VormiaSecurityHelper::isIpAllowed()) {
    abort(403, 'IP not allowed');
}
if (!VormiaSecurityHelper::validateApiToken('advanced')) {
    abort(401, 'Invalid or insufficient token');
}
if (!VormiaSecurityHelper::rateLimit(request()->ip(), 5, 60)) {
    abort(429, 'Too many requests');
}

8. Using Security Checks in Middleware

namespace App\Http\Middleware;

use Closure;
use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

class VormiaApiSecurity
{
    public function handle($request, Closure $next)
    {
        if (!VormiaSecurityHelper::isDomainAllowed()) {
            abort(403, 'Domain not allowed');
        }
        if (!VormiaSecurityHelper::isIpAllowed()) {
            abort(403, 'IP not allowed');
        }
        if (!VormiaSecurityHelper::validateApiToken('advanced')) {
            abort(401, 'Invalid or insufficient token');
        }
        if (!VormiaSecurityHelper::rateLimit($request->ip(), 10, 60)) {
            abort(429, 'Too many requests');
        }
        return $next($request);
    }
}

9. Custom Advanced Token Validation

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

// Override the advancedTokenValidation method in your own helper or extend VormiaSecurityHelper
class MySecurityHelper extends VormiaSecurityHelper
{
    public static function advancedTokenValidation($token)
    {
        // Example: check token in a custom DB table
        return \DB::table('api_tokens')->where('token', $token)->where('active', 1)->exists();
    }
}

if (!MySecurityHelper::validateApiToken('advanced')) {
    abort(401, 'Invalid or insufficient token');
}

10. Brute-force Protection

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

$key = request()->ip();
if (!VormiaSecurityHelper::bruteForceProtect($key, 5, 300)) {
    VormiaSecurityHelper::logSecurityEvent('Brute-force blocked', ['ip' => $key]);
    abort(429, 'Too many failed attempts');
}
// On successful login or action:
// VormiaSecurityHelper::resetBruteForce($key);

11. Request Logging

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

VormiaSecurityHelper::logSecurityEvent('Sensitive action', ['action' => 'delete', 'resource_id' => 123]);

12. Security Event Hooks

use VormiaQueryPhp\Helpers\VormiaSecurityHelper;

VormiaSecurityHelper::onSecurityEvent('token_invalid', function($event, $context) {
    // Send alert, log, or trigger custom logic
    \Log::warning("Security event: $event", $context);
});

You can use these helpers in controllers, middleware, or route closures to add extra security to your VormiaQuery endpoints.

For more, see the VormiaQuery JavaScript package documentation.

vormiaphp / vormiaqueryphp

Maintainers

Details