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

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.

laranail / license-kit

Maintainers

Package info

Statistics

Security