laranail/license-kit

laranail/license-kit is not published to Packagist, so there is no registry-version badge to show: see Install.

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 guide and usage

Getting started

1. Set LICENSING_KEY_PASSPHRASE in .env; the root key is encrypted with it.
2. Publish the resources, migrate, and create the root and signing keys:

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

Usage

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

Concept	Model	What it does
License	License	Polymorphic license on any Eloquent model, hashed activation key, full lifecycle
Seat	LicenseUsage	A registered device/installation — fingerprint, heartbeat, over-limit policies
Scope	LicenseScope	Per-product isolation with its own signing keys and rotation schedule
Template	LicenseTemplate	Reusable, tierable license configuration (trial days, duration, features)
Trial	LicenseTrial	Trial lifecycle with fingerprint hashing and conversion tracking
Key	LicensingKey	Root CA and signing keys (Ed25519) behind offline tokens
Audit entry	LicensingAuditLog	Append-only, hash-chained trail of every licensing operation

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.