PHPackages n3xt0r/filament-lockbox - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. n3xt0r/filament-lockbox ActiveLibrary[Security](/categories/security) n3xt0r/filament-lockbox ======================= Filament v4 security addon to protect sensitive data with user-bound encryption keys (Split-Key, TOTP, or crypto password) 1.0.0-alpha.2(7mo ago)671[2 issues](https://github.com/N3XT0R/filament-lockbox/issues)[3 PRs](https://github.com/N3XT0R/filament-lockbox/pulls)MITPHPPHP ^8.2CI passing Since Sep 20Pushed 1mo agoCompare [ Source](https://github.com/N3XT0R/filament-lockbox)[ Packagist](https://packagist.org/packages/n3xt0r/filament-lockbox)[ Docs](https://github.com/n3xt0r/filament-lockbox)[ GitHub Sponsors](https://github.com/N3XT0R)[ RSS](/packages/n3xt0r-filament-lockbox/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (14)Versions (12)Used By (0) [![CI](https://github.com/n3xt0r/filament-lockbox/actions/workflows/run-tests.yml/badge.svg)](https://github.com/n3xt0r/filament-lockbox/actions/workflows/run-tests.yml)[![Security Rating](https://camo.githubusercontent.com/2975dc357e0fca2d1e306c3fb887768d16b250dfa3f4cfc762bc4872ccadcdda/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d4e33585430525f66696c616d656e742d6c6f636b626f78266d65747269633d73656375726974795f726174696e67)](https://sonarcloud.io/summary/new_code?id=N3XT0R_filament-lockbox)[![Maintainability](https://camo.githubusercontent.com/11dbd05d9d3a67ccba08234698259cd3acff1deb7386e3a574f326a325961c5f/68747470733a2f2f716c74792e73682f67682f4e33585430522f70726f6a656374732f66696c616d656e742d6c6f636b626f782f6d61696e7461696e6162696c6974792e737667)](https://qlty.sh/gh/N3XT0R/projects/filament-lockbox)[![Code Coverage](https://camo.githubusercontent.com/b7318ba83f15826b7fb7018270b83b509e78cb8e6edef95a7ac5767707d32179/68747470733a2f2f716c74792e73682f67682f4e33585430522f70726f6a656374732f66696c616d656e742d6c6f636b626f782f636f7665726167652e737667)](https://qlty.sh/gh/N3XT0R/projects/filament-lockbox)[![Latest Stable Version](https://camo.githubusercontent.com/53f9bb41f89d185ea0f740bf8d693d4e2f2c817b21bdf4175489089431d7fedc/68747470733a2f2f706f7365722e707567782e6f72672f6e33787430722f66696c616d656e742d6c6f636b626f782f762f737461626c65)](https://packagist.org/packages/n3xt0r/filament-lockbox)[![Latest Unstable Version](https://camo.githubusercontent.com/f01814a4c385aa660a7ecb017a972e0d6ac786cf485a4fd04444106988239c82/68747470733a2f2f706f7365722e707567782e6f72672f6e33787430722f66696c616d656e742d6c6f636b626f782f762f756e737461626c65)](https://packagist.org/packages/n3xt0r/filament-lockbox)[![License](https://camo.githubusercontent.com/98aa4953f586f6a0878dd6bf8ea3d4fb3240f22a7d054d2d2eff4bfb23e69daf/68747470733a2f2f706f7365722e707567782e6f72672f6e33787430722f66696c616d656e742d6c6f636b626f782f6c6963656e7365)](https://packagist.org/packages/n3xt0r/filament-lockbox)[![CodeRabbit Pull Request Reviews](https://camo.githubusercontent.com/0c61a37eba87268442b23eab5bda0163ee3a608816fdc5020b739f842b38335e/68747470733a2f2f696d672e736869656c64732e696f2f636f64657261626269742f7072732f6769746875622f4e33585430522f66696c616d656e742d6c6f636b626f783f75746d5f736f757263653d6f73732675746d5f6d656469756d3d6769746875622675746d5f63616d706169676e3d4e335854305225324666696c616d656e742d6c6f636b626f78266c6162656c436f6c6f723d31373137313726636f6c6f723d464635373041266c696e6b3d6874747073253341253246253246636f64657261626269742e6169266c6162656c3d436f64655261626269742b52657669657773)](https://camo.githubusercontent.com/0c61a37eba87268442b23eab5bda0163ee3a608816fdc5020b739f842b38335e/68747470733a2f2f696d672e736869656c64732e696f2f636f64657261626269742f7072732f6769746875622f4e33585430522f66696c616d656e742d6c6f636b626f783f75746d5f736f757263653d6f73732675746d5f6d656469756d3d6769746875622675746d5f63616d706169676e3d4e335854305225324666696c616d656e742d6c6f636b626f78266c6162656c436f6c6f723d31373137313726636f6c6f723d464635373041266c696e6b3d6874747073253341253246253246636f64657261626269742e6169266c6162656c3d436f64655261626269742b52657669657773) Filament Lockbox ================ [](#filament-lockbox) [![Filament Lockbox Logo](art/lockbox-logo.png)](art/lockbox-logo.png) **Secure per-user field encryption for Filament v4.** This package allows you to encrypt and decrypt sensitive data on a per-user basis, using a split-key approach: - **Part A** (server-side key) is stored encrypted in the database. - **Part B** (user-provided secret) is collected at runtime (crypto password, passkey, or TOTP). - **Final key** is derived from PartA + PartB using `hash('sha256', ...)`. This ensures that **even administrators cannot decrypt data** without the user-provided input. --- πŸ§ͺ Code Quality & Coverage ----------------------------- [](#-code-quality--coverage) To ensure long-term maintainability and security, this package is continuously analyzed with two systems: - **SonarQube Cloud** Monitors code quality, maintainability, and potential security issues. Results are automatically updated on every commit. - **qlty.sh** Provides detailed **path coverage** via PHPUnit’s `--path-coverage`, ensuring not only that lines are executed but also that different execution paths are validated. For cryptographic code, this level of coverage is especially important: it verifies complete execution flows (e.g. valid vs. invalid keys, missing secrets, or failed TOTP checks). Compared to branch coverage, path coverage ensures higher confidence in correctness and security-critical behavior. Both tools run in CI and guarantee that security and quality checks are part of the development workflow. --- 🚧 Project Status ---------------- [](#-project-status) This package is currently in **alpha** and under active development. Features and APIs may change before a stable release. --- ✨ Features ---------- [](#-features) - πŸ”‘ **Per-user encryption keys** (split key: server + user) - 🧩 **Plug-and-play Filament components**: - `EncryptedTextInput` β†’ encrypts before save - `DecryptedTextDisplay` β†’ decrypts on display - `UnlockLockboxAction` β†’ prompts for crypto password or TOTP - πŸ”’ **User-configurable crypto password support** - πŸ—οΈ **Passkey (WebAuthn) support** if your user implements `HasPasskeys` - πŸ” **TOTP support** if your user implements `HasAppAuthentication` - πŸ›‘οΈ **Zero-knowledge for admins** – data is unreadable without user input - βš™οΈ **Configurable key material providers** (PBKDF2, Passkeys, TOTP, custom) --- πŸ—„οΈ Centralized Lockbox Storage ------------------------------ [](#️-centralized-lockbox-storage) Unlike typical field encryption solutions, **Filament Lockbox does not store encrypted data on your models**. Instead, all encrypted values are kept in a dedicated, polymorphic `lockbox` table β€” completely transparent to your application. ### βœ… Benefits of This Architecture [](#-benefits-of-this-architecture) - **Drop-in Usage** Simply use `EncryptedTextInput` anywhere in your Filament form schema β€” no schema changes or model attributes required. - **Polymorphic & Universal** Works with any Eloquent model (`User`, `Product`, `Order`, ...). All sensitive data is centralized, making it easy to see which records have encrypted fields. - **Performance-Friendly** Main tables remain lean and fast, as encrypted data is kept out of your core business tables. - **Compliance & Auditing** - Simplified GDPR / β€œRight to be Forgotten”: just delete Lockbox entries per user. - Perfect for audits: one table gives full visibility of all encrypted fields. - Allows separate backup and retention strategies. - **Developer Experience** - No manual hooks or closures needed β€” saving & loading is handled automatically. - `dehydrated(false)` is applied internally. - Just replace `TextInput` with `EncryptedTextInput` and get full encryption. ``` $form->schema([ // Before: TextInput::make('credit_card'), // After: EncryptedTextInput::make('credit_card') ->label('Credit Card'), ]); ``` The plugin takes care of everything: - πŸ”‘ Per-user key management - πŸ” Encryption & decryption - πŸ—„οΈ Transparent Lockbox record handling - πŸ”„ Auto-loading of values on form display - 🧹 Automatic cleanup when models are deleted --- πŸ”‘ How It Works (Key Derivation) ------------------------------- [](#-how-it-works-key-derivation) ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ encrypted_user_key β”‚ (in DB, encrypted with APP_KEY) β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ decrypt β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Part A β”‚ (server key) β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Part B (User Input) β”‚ ← crypto password, passkey, or TOTP β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ combine β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Final Key (32B) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Encrypt / Decrypt fields β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` This means **database leaks alone cannot decrypt your data** – PartB must be provided by the user. --- πŸš€ Installation -------------- [](#-installation) Install the package via Composer: ``` composer require n3xt0r/filament-lockbox ``` > **Important:** > This package integrates with [`spatie/laravel-passkeys`](https://github.com/spatie/laravel-passkeys). Before running the install command, make sure you have published and run the Spatie migrations: ``` php artisan vendor:publish --provider="Spatie\\LaravelPasskeys\\LaravelPasskeysServiceProvider" --tag="laravel-passkeys-migrations" php artisan migrate Run the install command to publish all required assets and migrations: ```bash php artisan filament-lockbox:install ``` --- πŸ”Œ Register the Plugin (Filament v4) ----------------------------------- [](#-register-the-plugin-filament-v4) Add the plugin to your Filament panel provider: ``` // app/Providers/Filament/AdminPanelProvider.php use Filament\Panel; use Filament\PanelProvider; use N3XT0R\FilamentLockbox\FilamentLockboxPlugin; class AdminPanelProvider extends PanelProvider { public function panel(Panel $panel): Panel { return $panel ->plugins([ FilamentLockboxPlugin::make(), ]); } } ``` Optional configuration: ``` // config/filament-lockbox.php return [ 'show_widget' => true, // set false to hide the status widget 'providers' => [ \N3XT0R\FilamentLockbox\Managers\KeyMaterial\TotpKeyMaterialProvider::class, \N3XT0R\FilamentLockbox\Managers\KeyMaterial\CryptoPasswordKeyMaterialProvider::class, ], ]; ``` You can publish the config and translations if you need customization: ``` php artisan vendor:publish --tag="filament-lockbox-config" php artisan vendor:publish --tag="filament-lockbox-translations" ``` --- βš™οΈ Model Setup -------------- [](#️-model-setup) Your `User` model must: - Implement `HasLockboxKeys` - Use the `InteractsWithLockboxKeys` trait - Hide and cast the lockbox fields ### Example: User Model [](#example-user-model) ``` use Filament\Models\Contracts\FilamentUser; use Illuminate\Contracts\Auth\MustVerifyEmail; use Illuminate\Foundation\Auth\User as Authenticatable; use N3XT0R\FilamentLockbox\Contracts\HasLockboxKeys; use N3XT0R\FilamentLockbox\Concerns\InteractsWithLockboxKeys; class User extends Authenticatable implements FilamentUser, MustVerifyEmail, HasLockboxKeys { use InteractsWithLockboxKeys; protected $hidden = [ 'encrypted_user_key', 'crypto_password_hash', 'lockbox_provider', ]; protected function casts(): array { return [ 'encrypted_user_key' => 'encrypted', 'crypto_password_hash' => 'string', 'lockbox_provider' => 'string', ]; } } ``` ### Example: Any Model with Encrypted Fields [](#example-any-model-with-encrypted-fields) Any Eloquent model that should have encrypted fields must: - Implement `HasLockbox` - Use the `InteractsWithLockbox` trait This enables the polymorphic relation to the `lockbox` table and lets the package handle encryption transparently. ``` use Illuminate\Database\Eloquent\Model; use N3XT0R\FilamentLockbox\Contracts\HasLockbox; use N3XT0R\FilamentLockbox\Concerns\InteractsWithLockbox; class Company extends Model implements HasLockbox { use InteractsWithLockbox; protected $fillable = [ 'name', 'email', // no need to list encrypted fields here – they live in the lockbox table ]; } ``` You can now use `EncryptedTextInput::make('field_name')` in your Filament form schemas for this model β€” the package will automatically store and retrieve the data from the centralized `lockbox` table. --- πŸ§‘β€πŸ’» User Flow ------------- [](#‍-user-flow) 1. Go to the **Lockbox widget** in your Filament panel. 2. Click **Generate Lockbox Key**. 3. Set a **crypto password**, register a **passkey**, or enable **TOTP**. 4. Unlock once per session to access or modify encrypted fields. --- 🧩 Usage in Filament Forms ------------------------- [](#-usage-in-filament-forms) ### 1️⃣ Storing Encrypted Data [](#1️⃣-storing-encrypted-data) ``` use N3XT0R\FilamentLockbox\Forms\Actions\UnlockLockboxAction; use N3XT0R\FilamentLockbox\Forms\Components\EncryptedTextInput; $form ->schema([ EncryptedTextInput::make('secret_notes') ->label('Secret Notes'), ]) ->extraActions([ UnlockLockboxAction::make(), ]); ``` ### 2️⃣ Displaying Decrypted Data [](#2️⃣-displaying-decrypted-data) ``` use N3XT0R\FilamentLockbox\Forms\Components\DecryptedTextDisplay; use N3XT0R\FilamentLockbox\Forms\Actions\UnlockLockboxAction; $form ->schema([ DecryptedTextDisplay::make('secret_notes') ->label('Secret Notes'), ]) ->extraActions([ UnlockLockboxAction::make(), ]); ``` --- πŸ”’ Security Model ---------------- [](#-security-model) - Split-key encryption (PartA + PartB β†’ Final Key) - PBKDF2 key derivation with 100,000 iterations - Server keys stored encrypted with `APP_KEY` - Extensible providers for alternative key material --- ### πŸ”‘ Passkeys (WebAuthn) [](#-passkeys-webauthn) This package ships with built-in support for [spatie/laravel-passkeys](https://github.com/spatie/laravel-passkeys) and requires it by default. You can control Passkey usage via this package's configuration. If you don't plan to use WebAuthn/Passkeys, disable the integration in `config/filament-lockbox.php`. --- πŸ“– Roadmap --------- [](#-roadmap) - Textarea and file encryption support - Automatic modal prompt if unlock is missing - Session-based unlock expiry - Configurable PBKDF2 parameters - Improve TOTP integration: ensure user-assigned secrets (crypto password) are required and TOTP is used only as a second factor --- πŸ“œ License --------- [](#-license) MIT Β© [N3XT0R](https://github.com/N3XT0R) ### Health Score 35 β€” LowBetter than 80% of packages Maintenance73 Regular maintenance activity Popularity10 Limited adoption so far Community10 Small or concentrated contributor base Maturity40 Maturing project, gaining track record Bus Factor1 Top contributor holds 96% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~6 days Total 3 Last Release 220d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8dbd2b0984ee6f62b6c5c3356b0e0cff2f2afa5c98c4d05272eb4356e080d545?d=identicon)[N3XT0R](/maintainers/N3XT0R) --- Top Contributors [![N3XT0R](https://avatars.githubusercontent.com/u/1297846?v=4)](https://github.com/N3XT0R "N3XT0R (192 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags pluginlaraveltotpsecurityencryption2faN3XT0Rfilamentphpfilament-lockbox ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/n3xt0r-filament-lockbox/health.svg) ``` [![Health](https://phpackages.com/badges/n3xt0r-filament-lockbox/health.svg)](https://phpackages.com/packages/n3xt0r-filament-lockbox) ``` ### Alternatives [tzsk/otp A secure, database-free One-Time Password (OTP) generator and verifier for PHP and Laravel. 241641.4k1](/packages/tzsk-otp)[stephenjude/filament-two-factor-authentication Filament Two Factor Authentication: Google 2FA + Passkey Authentication 81158.7k4](/packages/stephenjude-filament-two-factor-authentication)[marcelweidum/filament-passkeys Use passkeys in your filamentphp app 5925.8k](/packages/marcelweidum-filament-passkeys)[mradder/filament-logger Audit logging, activity tracking, exports, alerts, and dashboards for Filament admin panels. 141.1k](/packages/mradder-filament-logger) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)