npm package: @kodeme-io/next-core-license
Description: License validation system for next-core packages
Author: ABC Food Development Team
Latest version: 0.8.4

# @next-core/license

License validation system for next-core packages.

## Features

- ✅ JWT-based license keys (cryptographically secure)
- ✅ Offline validation (no server required)
- ✅ Development mode bypass (works on localhost)
- ✅ 30-day grace period for expired licenses
- ✅ Multiple license tiers (basic, pro, enterprise)
- ✅ Feature flags support
- ✅ CLI tool for generating and validating licenses

## Installation

```bash
npm install @next-core/license
```

## Usage

### For End Users (Adding License to Project)

Add your license key to `.env.local`:

```bash
NEXT_CORE_LICENSE_KEY=nc_prod_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

That's it! The license will be automatically validated when you use @next-core packages.

### For Administrators (Generating Licenses)

#### Generate a License

```bash
# Generate a production license for 1 year
npx @next-core/license generate \
  --org "ABC Food" \
  --project "Jakarta SFA" \
  --tier pro \
  --days 365 \
  --env prod
```

#### Validate a License

```bash
npx @next-core/license validate nc_prod_eyJhbGciOiJIUzI1...
```

#### View License Information

```bash
npx @next-core/license info nc_prod_eyJhbGciOiJIUzI1...
```

## CLI Commands

### `generate` - Generate a new license

**Required options:**
- `-o, --org <name>` - Organization name
- `-p, --project <name>` - Project name

**Optional options:**
- `-c, --contact <email>` - Contact email (default: support@next-core.dev)
- `-t, --tier <tier>` - License tier: basic, pro, enterprise (default: pro)
- `-d, --days <days>` - Days until expiration (default: 365)
- `-e, --env <env>` - Environment: dev, prod, test (default: prod)
- `-f, --features <features>` - Comma-separated features
- `--max-projects <number>` - Maximum number of projects
- `--domains <domains>` - Comma-separated allowed domains
- `-s, --secret <secret>` - JWT secret

**Example:**

```bash
npx @next-core/license generate \
  --org "ABC Food" \
  --project "Bandung LFA" \
  --tier enterprise \
  --days 365 \
  --env prod \
  --features "ui,auth,odoo-api,pwa,gps,s3,maps" \
  --contact "devops@abcfood.com"
```

### `validate` - Validate a license

```bash
npx @next-core/license validate nc_prod_eyJhbGciOiJIUz...
```

With grace period:

```bash
npx @next-core/license validate --grace nc_prod_eyJhbGciOiJIUz...
```

### `info` - Display license information

```bash
npx @next-core/license info nc_prod_eyJhbGciOiJIUz...
```

### `example` - Show usage examples

```bash
npx @next-core/license example
```

## Programmatic Usage

### Validating a License

```typescript
import { LicenseValidator } from '@next-core/license'

const validator = new LicenseValidator('your-secret-key')

const result = validator.validate(licenseKey)

if (result.valid) {
  console.log('License is valid!')
  console.log('Organization:', result.data?.org)
  console.log('Tier:', result.data?.tier)
} else {
  console.error('License is invalid:', result.reason)
}
```

### With Grace Period

```typescript
const result = validator.validateWithGrace(licenseKey)

if (result.valid && result.warning) {
  console.warn('License validation warning:', result.warning)
}
```

### Generating a License

```typescript
import { generateLicense } from '@next-core/license'

const license = generateLicense(
  {
    org: 'ABC Food',
    project: 'Jakarta SFA',
    tier: 'pro',
    expiresIn: 365 * 24 * 60 * 60, // 1 year in seconds
    environment: 'prod',
  },
  'your-secret-key'
)

console.log('License:', license)
```

## License Tiers

### Basic
- Core UI components
- Authentication
- Odoo API client

**Default features:** `ui`, `auth`, `odoo-api`

### Pro (Recommended)
- Everything in Basic
- PWA components
- GPS utilities
- S3 storage
- Partner & Product modules

**Default features:** `ui`, `auth`, `odoo-api`, `partner`, `product`, `pwa`, `gps`, `s3`

### Enterprise
- Everything in Pro
- N8N integration
- Maps support
- QR code scanning
- Custom features

**Default features:** `ui`, `auth`, `odoo-api`, `partner`, `product`, `n8n`, `pwa`, `gps`, `s3`, `maps`, `qr`, `custom`

## License Key Format

```
nc_{environment}_{jwt_token}
```

**Prefixes:**
- `nc_dev_` - Development license
- `nc_prod_` - Production license
- `nc_test_` - Testing license

**Example:**
```
nc_prod_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJuZXh0LWNvcmUiLCJzdWIiOiJKYWthcnRhIFNGQSIsImlhdCI6MTcyODIxMDAwMCwiZXhwIjoxNzU5NzQ2MDAwLCJ0aWVyIjoicHJvIiwiZmVhdHVyZXMiOlsidWkiLCJhdXRoIiwib2Rvby1hcGkiLCJwYXJ0bmVyIiwicHJvZHVjdCIsInB3YSIsImdwcyIsInMzIl0sIm9yZyI6IkFCQyBGb29kIiwiY29udGFjdCI6InN1cHBvcnRAYWJjZm9vZC5jb20iLCJlbnZpcm9ubWVudCI6InByb2QifQ.xYzABCDEFGH123456
```

## Development Mode

In development mode (localhost), license validation is automatically bypassed:

```typescript
// No license needed for development!
npm run dev  // Works without NEXT_CORE_LICENSE_KEY
```

**Development mode is detected when:**
- `NODE_ENV=development` or `NODE_ENV=test`
- AND not running on deployment platforms (Vercel, Netlify, Railway)

## Grace Period

If a license expires, a 30-day grace period is automatically activated:

1. First expiration check starts grace period
2. App continues to work for 30 days
3. After grace period, license must be renewed

Track grace period:
- Server: `NEXT_CORE_GRACE_PERIOD_START` environment variable
- Client: `next_core_grace_period_start` localStorage key

## Environment Variables

### For End Users

```bash
# Required in production
NEXT_CORE_LICENSE_KEY=nc_prod_eyJhbGciOiJIUz...
```

### For Administrators

```bash
# Required for generating licenses
NEXT_CORE_LICENSE_SECRET=your-secret-key-here

# Optional: track grace period (auto-set)
NEXT_CORE_GRACE_PERIOD_START=2025-10-06T00:00:00.000Z
```

## Security Best Practices

1. **Protect Your Secret**
   - Never commit `NEXT_CORE_LICENSE_SECRET` to git
   - Use environment variables
   - Different secrets for dev/prod

2. **Secure License Distribution**
   - Send licenses via secure channels (email, Slack DM)
   - Document who has which licenses
   - Implement rotation policy

3. **Monitor Usage**
   - Keep track of active licenses
   - Set up expiration reminders
   - Review licenses quarterly

## Troubleshooting

### "License key not found"

**Problem:** `NEXT_CORE_LICENSE_KEY` not set in environment

**Solution:**
1. Create `.env.local` file
2. Add `NEXT_CORE_LICENSE_KEY=nc_prod_...`
3. Restart development server

### "License expired"

**Problem:** License has passed expiration date

**Solution:**
1. Check grace period status
2. Contact administrator for renewal
3. Generate new license with extended date

### "Invalid license signature"

**Problem:** License key is corrupted or secret mismatch

**Solution:**
1. Verify license key is complete (not truncated)
2. Check if using correct secret
3. Request new license if corrupted

### "License environment mismatch"

**Problem:** Using dev license in production or vice versa

**Solution:**
1. Check `NODE_ENV` setting
2. Use correct license type for environment
3. Generate new license for target environment

## Support

For license issues:
- Internal teams: Contact DevOps team
- External clients: support@next-core.dev

## License

MIT © ABC Food Development Team