README

A licensing engine for Laravel — offline verification (PASETO v4 / Ed25519), seat-based licensing, full lifecycle (activation, renewal, grace, expiration, suspension), multi-product signing-key scopes with a two-level key hierarchy, an append-only audit trail, and polymorphic license assignment to any Eloquent model.

Requires PHP ^8.4.1 || ^8.5 on Laravel ^13.

Install

composer require laranail/license-kit

Quick start

php artisan vendor:publish --provider="Simtabi\Laranail\Licence\Kit\LicensingServiceProvider"
php artisan migrate
php artisan laranail::license-kit.keys.make-root
php artisan laranail::license-kit.keys.issue-signing --days=30

use Simtabi\Laranail\Licence\Kit\Models\License;

$license = License::createWithKey([
    'licensable_type' => User::class,
    'licensable_id'   => $user->id,
    'max_usages'      => 3,
    'expires_at'      => now()->addYear(),
]);

$activationKey = $license->license_key; // "LIC-A3F2B9K1-C4D8E5H7-9D2EK8F3-L6A9M1B4"

$found = License::findByKey($activationKey);
$found->verifyKey($activationKey) && $found->activate();

See Getting started for seats, offline tokens, and the rest of the tour.

The moving parts

Documentation

Full documentation is at opensource.simtabi.com/documentation/laranail/license-kit.

Guides

• Installation — requirements, package install, migrations, key generation, verification.
• Getting started — from install to your first license and offline token.
• Configuration — every config/licensing.php option: models, crypto, policies, services.
• Basic usage — creating, activating, checking, renewing licenses; seats; features and entitlements.
• Architecture — layers, contract seams, the key hierarchy, and why it's built this way.
• Security — defense in depth: key protection, input validation, rate limiting, incident response.
• Performance — caching, database optimization, and tuning for high-load environments.
• Client implementation guide — the wire-level spec for building a compatible client in any language.
• Client library architecture — design patterns for client libraries (desktop, mobile, web, CLI).
• FAQ — common questions on the model, crypto, performance, and integration.
• Troubleshooting — diagnosing installation, activation, key, and token problems.
• Release — how versions are cut; what counts as a breaking change.

Reference

• Licenses — the License model: lifecycle, states, keys, metadata, querying.
• Usage & seats — seat registration, fingerprints, heartbeats, over-limit policies.
• Renewals — period-based renewals, history, grace periods, notifications.
• Templates & tiers — reusable license configurations and tier hierarchies.
• Trials — trial lifecycle, extensions, conversion tracking.
• Offline verification — PASETO v4 tokens, key hierarchy, client-side verification.
• License transfers — multi-party transfer workflows with approvals.
• Audit logging — the tamper-evident, hash-chained audit trail.
• Scope templates — binding license plans to product scopes.
• Key management — root/signing key generation, rotation, revocation, storage.
• Multi-software signing keys — per-product scopes with isolated keys.
• Commands — the laranail::license-kit.* Artisan commands.
• Models — the 11 Eloquent models.
• Services — the business-logic services.
• Events — every dispatched event and its payload.
• Contracts — the interfaces behind every service.
• Enums — the 11 status/policy enums.

Recipes

• Set up tiered SaaS licensing — Basic/Pro/Enterprise tiers end to end.
• Verify desktop licenses offline — activation, token storage, and offline checks in a desktop app.
• Enforce device limits in a mobile app — device registration and replacement flows.
• Convert trials to paid licenses — trial registration, monitoring, and conversion.

Project

• CHANGELOG.md — release history.
• UPGRADE.md — breaking changes and migration steps.
• CONTRIBUTING.md — coding conventions, test patterns, PR expectations.
• SECURITY.md — vulnerability disclosure.
• CODE_OF_CONDUCT.md — community standards.

Stability

Pre-1.0 (v0.x): the package is production-quality and fully tested, but the public API may still change between minor versions. Semver applies; every breaking change is documented in UPGRADE.md. Treat the offline-token format as a distributed contract — see Release.

Local development

git clone https://github.com/laranail/license-kit.git && cd license-kit
composer install
composer test    # Pest
composer lint    # Pint + PHPStan + Rector (dry-run)

Sister packages

The laranail licensing family — license-kit is the server side; these cover the client and product side:

• laranail/license-verifier — headless, provider-agnostic verification client: PASETO/Ed25519 offline verification, device fingerprinting, seats.
• laranail/license-verifier-ui — UI engine that scaffolds owned, themeable verification UI presets (Blade, Livewire, Filament, …).
• laranail/product-updater — self-update engine for licensed Laravel products: checks a source, downloads, verifies, applies.
• laranail/demo-mode — license-aware demo/sandbox controller: read-only and write guards per model/route/feature.

Community

Bugs and feature requests → GitHub Issues; questions and ideas → GitHub Discussions.

Contributing & security

Issues and PRs are welcome — see CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.

License

MIT © Simtabi LLC. See LICENSE.