README

Sentinel for Laravel

Know when your data was changed behind your application's back, and make every request count once. Sentinel seals Eloquent models with keyed MACs or signatures, detects any change made outside the application (a SQL console, a mass update(), a restored backup), and adds idempotency keys, single-use nonces and URLs, and RFC 9421 HTTP message signatures.

Installation

Requires PHP 8.4+ (ext-hash, ext-mbstring; ext-sodium for Ed25519 keys), Laravel 12 or 13, and SQLite, PostgreSQL or MySQL.

composer require roundly-consulting/sentinel-for-laravel
php artisan sentinel:install   # publishes config + migrations, prints the key lines for .env
php artisan migrate

If your sealed models or users have UUID/ULID keys, set sentinel.key_type / sentinel.actor_key_type before migrating. php artisan sentinel:check confirms the setup.

Usage

Declare a seal on the model — every Eloquent write now seals the row:

use RoundlyConsulting\Sentinel\Concerns\HasSeals;
use RoundlyConsulting\Sentinel\Contracts\Sealable;
use RoundlyConsulting\Sentinel\Definition\SealBuilder;

final class Invoice extends Model implements Sealable
{
    use HasSeals;

    public static function defineSeals(SealBuilder $seals): void
    {
        $seals->seal('financial')->attributes('customer_id', 'currency', 'amount', 'status');
    }
}

Verify wherever it matters:

use RoundlyConsulting\Sentinel\Facades\Sentinel;

$invoice->isIntact();                          // true when every seal verifies
Sentinel::for($invoice)->verifyOrFail();       // throws TamperedModelException otherwise

Route::get('/invoices/{invoice}', ShowInvoice::class)->middleware('sentinel.verified');

Someone runs UPDATE invoices SET amount = 0 WHERE id = 42 in a SQL console:

Sentinel::for($invoice)->verify();
// VerificationResult { status: Tampered, reason: 'mac', changedAttributes: ['a:amount'], … }

$invoice->update(['note' => 'x']);             // TamperedModelException: refused until acknowledged

Sentinel::for($invoice)->by($admin)->because('INC-88: refund fixed by the DBA')->acknowledge();

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/sentinel-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). See LICENSE.md.

roundly-consulting / sentinel-for-laravel

Package info

Security

Fund package maintenance!

Statistics