PHPackages lukk/lukk - 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. [Authentication & Authorization](/categories/authentication) 4. / 5. lukk/lukk ActiveLibrary[Authentication & Authorization](/categories/authentication) lukk/lukk ========= Minimal-dependency JWT auth for first-party Laravel apps (unofficial; not affiliated with the Laravel team): short access tokens, opaque rotating refresh tokens, reuse detection, grace window, and instant denylist revocation. v0.4.0(1mo ago)0183MITPHPPHP ^8.3CI passing Since Jun 28Pushed 1mo agoCompare [ Source](https://github.com/stsepelin/lukk)[ Packagist](https://packagist.org/packages/lukk/lukk)[ Docs](https://github.com/stsepelin/lukk)[ RSS](/packages/lukk-lukk/feed)WikiDiscussions main Synced 2w ago READMEChangelog (8)Dependencies (26)Versions (9)Used By (0) lukk ==== [](#lukk) [![Latest Version](https://camo.githubusercontent.com/5db0ada8d8b35ffe66e6795c14b0bbd80213ffac5ca1f7d1d4a6f9f580790985/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c756b6b2f6c756b6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lukk/lukk)[![Tests](https://camo.githubusercontent.com/463264bc48215699280e7e85b8a626e0984efee35e60f3bc9131a2075d7f0fca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7374736570656c696e2f6c756b6b2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/stsepelin/lukk/actions/workflows/tests.yml)[![Coverage](https://camo.githubusercontent.com/994d68acb2aadf1c3c7711ddcb3b30429246a6c05da9e601f62c3f932ac795a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/stsepelin/lukk/actions/workflows/tests.yml)[![PHP Version](https://camo.githubusercontent.com/37e681305bf210e4321cf84f663ff223b3ce0a5280a19da3986981528c9d9df2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6c756b6b2f6c756b6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lukk/lukk)[![License](https://camo.githubusercontent.com/4229b32a184c7665e84dfec41ca652f4af15dba0799318fb0ef9ad5e68a6a57c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c756b6b2f6c756b6b2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Total Downloads](https://camo.githubusercontent.com/3e2886bce49ba183d02d08590cb1aedd5faeaa8aef4478cdd4fd3d72e91158c4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c756b6b2f6c756b6b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lukk/lukk) Minimal-dependency JWT authentication for **first-party Laravel apps** (Laravel 12/13) — "first-party" meaning *you own both the client and the API*, so there's no third party to delegate to and no OAuth ceremony to perform. > **Unofficial, independent package.** Not affiliated with, endorsed by, or maintained by the Laravel team. "Laravel", "Sanctum", and "Fortify" are referenced only to describe compatibility and design influence; they are trademarks of their respective owners. > **Pre-1.0 — expect breaking changes.** lukk is in the `0.x` series. The core is production-minded and fully tested (100% coverage), but per [semantic versioning for initial development](https://semver.org/#spec-item-4), the public API, config, and **database schema may change between minor versions** without a major bump. Pin an exact version and read the [UPGRADE guide](UPGRADE.md) (and the [CHANGELOG](CHANGELOG.md)) before upgrading — a release may require re-running migrations. The 1.0 release will mark API/schema stability. Features -------- [](#features) - **Short-lived access JWTs** (HS256, 15 min) — stateless, verified on every request with the algorithm pinned and `iss`/`aud` asserted. - **Opaque rotating refresh tokens** (30 days) — stored only as a `sha256` hash, rotated on every use. - **Reuse detection** — replaying a consumed token revokes the whole session (token family). - **Concurrency grace window** — multiple tabs / SSR refresh without false logouts. - **Instant revocation** — a cache-backed denylist kills an access token or a whole session within one request. - **Optional [two-factor auth](https://stsepelin.github.io/lukk-docs/two-factor-authentication)** (TOTP + recovery codes) and **[passkeys](https://stsepelin.github.io/lukk-docs/passkeys)** (WebAuthn / FIDO2), each opt-in and feature-gated. - **Sanctum/Fortify-style design** — a contract per swappable piece, single-purpose Actions, a static `Lukk` config hub, a dedicated guard, and Responsable response contracts. The single runtime dependency is [`firebase/php-jwt`](https://github.com/firebase/php-jwt), the audited JWS primitive — never hand-roll JWT. Everything else is Laravel core. Token model ----------- [](#token-model) **Access token**HS256 JWT, 15 min. Claims `iss/aud/sub/fid/jti/iat/nbf/exp`, header `typ=at+jwt`. Verified every request: alg pinned, `iss`/`aud` asserted, denylist checked by `jti` and `fid`.**Refresh token**Opaque 256-bit secret, 30 days. Returned once; stored only as `sha256`. Rotated on every refresh; reuse after the grace window revokes the whole family.HS256 is correct while this app is its own sole verifier. RS256/ES256 + a JWKS endpoint + `kid` key rotation are built in (behind the same contracts) for when an independent service must verify tokens — flip `LUKK_ALGORITHM` and run `php artisan lukk:keygen`. See [Architecture & Security](https://stsepelin.github.io/lukk-docs/architecture). Requirements ------------ [](#requirements) - PHP `^8.3` - Laravel `^12.0 | ^13.0` - `firebase/php-jwt` `^7.0` Quick start ----------- [](#quick-start) ``` composer require lukk/lukk php artisan vendor:publish --tag=lukk-config # config/lukk.php php artisan vendor:publish --tag=lukk-migrations # refresh_tokens migration php artisan migrate php artisan lukk:secret # writes LUKK_SECRET to .env ``` Map a guard to the `lukk-jwt` driver in `config/auth.php`: ``` 'guards' => [ 'api' => ['driver' => 'lukk-jwt', 'provider' => 'users'], ], ``` Then protect routes with `auth:api` as usual: ``` Route::middleware('auth:api')->get('/me', fn (Request $r) => $r->user()); ``` The package registers `login`, `refresh`, `logout`, and session-revocation (`DELETE /sessions`, `DELETE /sessions/others`) routes automatically. See **[Installation](https://stsepelin.github.io/lukk-docs/installation)** and **[Authentication](https://stsepelin.github.io/lukk-docs/authentication)** for the full walkthrough. Documentation ------------- [](#documentation) 📚 **Full documentation: [stsepelin.github.io/lukk-docs](https://stsepelin.github.io/lukk-docs)** lukk (the Laravel package) and [lukk-js](https://github.com/stsepelin/lukk-js) (the TypeScript/Nuxt client) are documented together on one site — each feature page covers both the server and the client. Start with the [Introduction](https://stsepelin.github.io/lukk-docs/introduction) or jump to [Installation](https://stsepelin.github.io/lukk-docs/installation). **For AI assistants:** the docs are exposed as [`/llms.txt`](https://stsepelin.github.io/lukk-docs/llms.txt) + [`/llms-full.txt`](https://stsepelin.github.io/lukk-docs/llms-full.txt) ([llms.txt](https://llmstxt.org) convention), and [`AGENTS.md`](AGENTS.md) has integration + contribution rules. Testing ------- [](#testing) ``` composer install vendor/bin/pest ``` Acknowledgements ---------------- [](#acknowledgements) lukk stands on the shoulders of the Laravel ecosystem, and its design is a deliberate synthesis of ideas from the first-party packages. Sincere thanks to their authors and maintainers — lukk isn't affiliated with or endorsed by any of them (see the note at the top); these are simply the works that shaped it: - **[Laravel Sanctum](https://laravel.com/docs/sanctum)** — the architectural model. `HasRefreshTokens` is the `HasApiTokens` analog, the static `Lukk` hub mirrors Sanctum's configuration style, and the publish-only migration convention is borrowed wholesale. - **[Laravel Fortify](https://laravel.com/docs/fortify)** — the customization philosophy: single-purpose actions + rebindable response contracts, hooks like `Lukk::registerUsing()` (à la `Fortify::createUsersUsing()`), the `Password::defaults()` policy, and the configurable login identifier. - **[Laravel Passport](https://laravel.com/docs/passport)** — conventions for token issuance, publish-only migrations, and keeping models extensible. - **[Laravel Jetstream](https://jetstream.laravel.com) & [Breeze](https://laravel.com/docs/starter-kits)** — the reference for two-factor + single-use recovery codes and step-up ("sudo") confirmation, and — with **[Inertia](https://inertiajs.com)** and the Nuxt ecosystem — the first-party client-side patterns that shaped [lukk-js](https://github.com/stsepelin/lukk-js). - **[tymon/jwt-auth](https://github.com/tymondesigns/jwt-auth)** — the established Laravel JWT package; its `lock_subject` approach to cross-guard isolation directly informed lukk's multi-guard design. And the libraries lukk is built on: **[firebase/php-jwt](https://github.com/firebase/php-jwt)** (the sole runtime dependency), **[pragmarx/google2fa](https://github.com/antonioribeiro/google2fa)** (TOTP), and **[web-auth/webauthn-lib](https://github.com/web-auth/webauthn-framework)** by Spomky-Labs (passkeys) — plus the [Laravel](https://laravel.com) framework and community that make all of this possible. 🙏 License ------- [](#license) MIT. ### Health Score 42 — FairBetter than 88% of packages Maintenance92 Actively maintained with recent releases Popularity16 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~1 days Total 8 Last Release 37d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/5f197258508199fe5df1ed3c4430eb1c714c90fdab5f7f3f2b596c838175064f?d=identicon)[stsepelin](/maintainers/stsepelin) --- Top Contributors [![stsepelin](https://avatars.githubusercontent.com/u/8102174?v=4)](https://github.com/stsepelin "stsepelin (57 commits)") --- Tags jwtlaraveltotpauthAuthentication2fawebauthnpasskeyrefresh-token ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/lukk-lukk/health.svg) ``` [![Health](https://phpackages.com/badges/lukk-lukk/health.svg)](https://phpackages.com/packages/lukk-lukk) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.6k31.8M158](/packages/laravel-cashier)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M305](/packages/laravel-ai)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 79227.1M218](/packages/laravel-mcp)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel)[masterix21/laravel-licensing Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts. 1614.1k4](/packages/masterix21-laravel-licensing) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)