[Spec]: Self-Hosted Business License Monetization & Enforcement (Keygen.sh Integration)

[kalinga777]

Overview

WorkLenz currently provides:
• Cloud (Free, Pro, Business)
• Self-hosted (Open core with Business features planned)

To monetize the self-hosted Business plan ($99/month), we need a secure license management and enforcement mechanism using Keygen.sh.

This feature introduces:
• Business feature gating
• License activation and validation
• Periodic revalidation
• Grace period handling
• Admin license management UI
• Secure backend license enforcement

The goal is to ensure:
• Open-source core remains free (AGPL)
• Business features require a valid subscription license
• Revenue is protected without harming open-source distribution

Goals & Non-goals

🎯 Goals
1. Enable recurring monetization for self-hosted Business edition.
2. Integrate Keygen.sh for subscription-based license management.
3. Enforce Business feature access only when license is valid.
4. Prevent license sharing across multiple production instances.
5. Provide clear admin visibility of license status.
6. Ensure system continues functioning even if license expires (core remains usable).

🚫 Non-Goals
1. Per-user licensing (this is per instance only).
2. Shutting down entire system when license expires.
3. DRM-style aggressive locking mechanisms.
4. Client-side license validation (all validation must be server-side).
5. Complex enterprise license tiers (future enhancement).

Requirements (Functional & Non-functional)

Functional Requirements

License Activation
• Admin must be able to:
• Enter a license key
• Activate license
• View license status
• Remove license
• System must:
• Validate license key with Keygen.sh
• Bind license to machine fingerprint
• Store encrypted license metadata

Machine Fingerprinting

System must generate a unique fingerprint using:
• Domain name
• Server MAC hash
• Install UUID
• Database UUID

Fingerprint must be:
• Deterministic
• Non-editable via UI
• Stored securely

Business Feature Gating

Business features must only be accessible when:

license.status === "active"
AND
license.plan === "business"

If invalid:
• Show upgrade modal
• Disable feature UI
• Prevent API access

Business features include (initial scope):
• Advanced Reporting
• Client Portal Customization
• White Label Branding
• Audit Logs
• Advanced Role Permissions
• Enterprise Integrations
• AI Automation Modules

Periodic License Revalidation

System must:
• Revalidate license every 24 hours
• Support background cron execution
• Detect:
• Expired license
• Revoked license
• Suspended subscription

Grace Period

If:
• Keygen API unreachable
• Temporary offline mode

Then:
• Allow 7-day grace period
• After grace expiration → disable Business features

Core features must remain operational.

License Status UI

Admin Panel → Settings → License

Display:
• License Key (masked)
• Plan Name
• Status (Active / Expired / Invalid / Suspended)
• Expiry Date
• Machine ID
• Revalidation Timestamp

Upgrade Flow

When accessing Business feature without valid license:

Show modal:
• Feature list preview
• Pricing ($99/month)
• “Buy License” button
• “Enter License Key” option

🔐 Non-Functional Requirements

Security
• All Keygen API calls must be server-side.
• API secrets must not be exposed to frontend.
• License keys stored encrypted.
• Business feature checks must exist at:
• Backend API level
• Not only frontend UI

⸻

Performance
• License validation must not block request cycle.
• Revalidation must run asynchronously.
• Feature checks must add negligible overhead.

⸻

Reliability
• System must tolerate temporary Keygen downtime.
• Grace period mechanism must prevent accidental lockout.

User Flows / Diagrams

Admin License Activation Flow

Admin → Settings → License
→ Enter License Key
→ Click Activate
→ Backend validates via Keygen API
→ If valid:
Store license
Bind machine fingerprint
Enable Business features
→ If invalid:
Show error

Periodic Revalidation Flow

Cron Job (24h)
→ Fetch stored license
→ Call Keygen validate
→ Update status:
- Active
- Expired
- Suspended
→ If expired:
Disable Business features

Feature Access Without License

User clicks Business Feature
→ Backend middleware checks license
→ If valid → proceed
→ If invalid → return 403 + upgrade message

Acceptance Criteria

License Activation
• Admin can successfully activate valid license.
• System stores encrypted license metadata.
• License binds to one machine only.
• Activation fails if machine already registered.

⸻

✅ Feature Gating
• Business features inaccessible without valid license.
• Backend blocks API access when license invalid.
• Upgrade modal shown on restricted features.
• Core features remain unaffected.

⸻

✅ Revalidation
• License automatically revalidated every 24 hours.
• Grace period works when Keygen unreachable.
• Business features disabled after grace expiry.
• License status updates correctly in UI.

⸻

✅ Security
• No Keygen secret exposed in frontend.
• Business checks cannot be bypassed via UI manipulation.
• License removal immediately disables Business features.

⸻

✅ Stability
• Expired license does not crash system.
• License checks do not noticeably impact performance.