# WC Licensed Product

A WooCommerce plugin to sell software products using license keys with domain-based validation.

## Description

WC Licensed Product adds a new product type "Licensed Product" to WooCommerce, enabling you to sell software with automatically generated license keys. Licenses are bound to specific domains and can be validated through a REST API.

## Features

### Core Features

- **Licensed Product Type**: New WooCommerce product type for software sales
- **Automatic License Generation**: License keys generated on order completion (format: XXXX-XXXX-XXXX-XXXX)
- **Domain Binding**: Licenses are bound to customer-specified domains
- **REST API**: Public endpoints for license validation and management
- **Response Signing**: Optional HMAC-SHA256 cryptographic signatures for API responses
- **Version Binding**: Optional binding to major software versions
- **Expiration Support**: Set license validity periods or lifetime licenses
- **Rate Limiting**: API endpoints protected with rate limiting (30 requests/minute)
- **Trusted Proxy Support**: Configurable trusted proxies for accurate rate limiting behind CDNs
- **Checkout Blocks**: Full support for WooCommerce Checkout Blocks (default since WC 8.3+)
- **Self-Licensing**: The plugin can validate its own license (for commercial distribution)

### Customer Features

- **My Account Licenses**: Customers can view their licenses in My Account
- **License Transfers**: Customers can transfer licenses to new domains
- **Secure Downloads**: Download purchased software versions with license verification
- **Copy to Clipboard**: Easy license key copying

### Admin Features

- **License Management**: Full CRUD interface for license management
- **License Dashboard**: Statistics and analytics (WooCommerce > Reports > Licenses)
- **Dashboard Widget**: License statistics on WordPress admin dashboard
- **Search & Filtering**: Search by license key, domain, status, or product
- **Live Search**: AJAX-powered instant search results
- **Inline Editing**: Edit license status, expiry, and domain directly in the list
- **Bulk Operations**: Activate, deactivate, revoke, extend, or delete multiple licenses
- **License Transfer**: Transfer licenses to new domains
- **CSV Export/Import**: Export and import licenses via CSV
- **Order Integration**: View and manage licenses directly from order pages
- **Expiration Warnings**: Automatic email notifications before license expiration
- **Auto-Expire**: Daily cron job automatically expires licenses past their expiration date
- **License Testing**: Test licenses against the API directly from admin interface
- **Version Management**: Manage multiple versions per product with file attachments
- **SHA256 Checksums**: File integrity verification with SHA256 hash display
- **Global Settings**: Default license settings via WooCommerce settings tab
- **WooCommerce HPOS**: Compatible with High-Performance Order Storage

## Requirements

- WordPress 6.0 or higher
- WooCommerce 10.0 or higher
- PHP 8.3 or higher

## Installation

1. Upload the `wc-licensed-product` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. The plugin will create necessary database tables on activation

## Usage

### Creating a Licensed Product

1. Go to Products > Add New
2. Select "Licensed Product" from the product type dropdown
3. Configure the product price in the General tab
4. Set license options in the "License Settings" tab:
   - **Max Activations**: Number of domains allowed per license
   - **License Validity**: Days until expiration (empty = lifetime)
   - **Bind to Major Version**: Lock license to current major version

### Managing Product Versions

1. Edit a Licensed Product
2. Use the "Product Versions" meta box to add versions
3. Upload version files via WordPress Media Library
4. Version numbers are auto-detected from filenames (e.g., `plugin-v1.2.3.zip`)

### Global Default Settings

1. Go to WooCommerce > Settings > Licensed Products
2. Set default values for Max Activations, License Validity, and Version Binding
3. Per-product settings override these defaults

### Customer Checkout

When a customer purchases a licensed product, they must enter the domain where they will use the license during checkout.

### Viewing Licenses

- **Customers**: My Account > Licenses
- **Administrators**: WooCommerce > Licenses
- **Dashboard**: WooCommerce > Reports > Licenses (for statistics)

### Exporting & Importing Licenses

**Export:**

1. Go to WooCommerce > Licenses
2. Click "Export CSV" to download all licenses

**Import:**

1. Go to WooCommerce > Licenses
2. Click "Import CSV"
3. Upload a CSV file (supports exported format or simplified format)
4. Choose options: skip header row, update existing licenses

## Security

The plugin implements several security best practices:

- **Input Sanitization**: All user inputs are sanitized using WordPress functions
- **Output Escaping**: All output is escaped to prevent XSS attacks
- **CSRF Protection**: Nonce verification on all forms and AJAX requests
- **SQL Injection Prevention**: All database queries use prepared statements
- **Capability Checks**: Admin functions require `manage_woocommerce` capability
- **Secure Downloads**: File downloads use hash-verified URLs with user authentication
- **Response Signing**: Optional HMAC-SHA256 signatures for API tamper protection

### Trusted Proxy Configuration

If your server is behind a load balancer, reverse proxy, or CDN (like Cloudflare), you need to configure trusted proxies for accurate rate limiting. Without this, the rate limiter uses the direct connection IP which may be your proxy's IP.

**Configuration (wp-config.php):**

```php
// For Cloudflare (includes all Cloudflare IP ranges)
define('WC_LICENSE_TRUSTED_PROXIES', 'CLOUDFLARE');

// For specific proxy IPs
define('WC_LICENSE_TRUSTED_PROXIES', '10.0.0.1,10.0.0.2');

// For CIDR ranges
define('WC_LICENSE_TRUSTED_PROXIES', '10.0.0.0/8,192.168.1.0/24');

// Combine multiple methods
define('WC_LICENSE_TRUSTED_PROXIES', 'CLOUDFLARE,10.0.0.1');
```

**Note**: Only configure trusted proxies if you actually use them. Without this configuration, rate limiting is more secure against IP spoofing attacks.

## REST API

Full API documentation available in `openapi.json` (OpenAPI 3.1 specification).

### Response Signing (Optional)

When the server is configured with a shared secret, all API responses include cryptographic signatures for tamper protection:

**Configuration (wp-config.php):**

```php
define('WC_LICENSE_SERVER_SECRET', 'your-secure-random-string-min-32-chars');
```

Generate a secure secret using:

```bash
openssl rand -hex 32
```

**Response Headers:**

| Header | Description |
| ------ | ----------- |
| `X-License-Signature` | HMAC-SHA256 signature of the response body |
| `X-License-Timestamp` | Unix timestamp when the response was generated |

The signature prevents man-in-the-middle attacks and ensures response integrity. Use the `magdev/wc-licensed-product-client` Composer package with the `SecureLicenseClient` class to automatically verify signatures.

### Client Libraries & Examples

**PHP (Recommended):** Install the official client library via Composer:

```bash
composer require magdev/wc-licensed-product-client
```

The library provides:

- `LicenseClient` - Standard client for API calls
- `SecureLicenseClient` - Client with automatic response signature verification

**Example clients** for other languages are available in `docs/client-examples/`:

- **cURL** - Shell script examples ([curl.sh](docs/client-examples/curl.sh))
- **PHP** - Standalone client example ([php-client.php](docs/client-examples/php-client.php))
- **Python** - Client class with dataclasses ([python-client.py](docs/client-examples/python-client.py))
- **JavaScript** - Browser and Node.js client ([javascript-client.js](docs/client-examples/javascript-client.js))
- **C#** - Async client with System.Text.Json ([csharp-client.cs](docs/client-examples/csharp-client.cs))

All examples include rate limit handling (HTTP 429) and demonstrate the validate, status, and activate endpoints.

### Validate License

Validate a license key for a specific domain.

```http
POST /wp-json/wc-licensed-product/v1/validate
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "domain": "example.com"
}
```

**Success Response (200):**

```json
{
  "valid": true,
  "license": {
    "product_id": 123,
    "expires_at": "2027-01-21",
    "version_id": 5
  }
}
```

**Error Response (403):**

```json
{
  "valid": false,
  "error": "domain_mismatch",
  "message": "This license is not valid for this domain."
}
```

### Check Status

Get detailed license status information.

```http
POST /wp-json/wc-licensed-product/v1/status
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX"
}
```

**Response (200):**

```json
{
  "valid": true,
  "status": "active",
  "domain": "example.com",
  "expires_at": "2027-01-21",
  "activations_count": 1,
  "max_activations": 3
}
```

### Activate License

Activate a license on a domain.

```http
POST /wp-json/wc-licensed-product/v1/activate
Content-Type: application/json

{
  "license_key": "XXXX-XXXX-XXXX-XXXX",
  "domain": "newdomain.com"
}
```

**Response (200):**

```json
{
  "success": true,
  "message": "License activated successfully."
}
```

### Error Codes

| Code | Description |
| ---- | ----------- |
| `license_not_found` | License key does not exist |
| `license_revoked` | License has been revoked |
| `license_expired` | License has expired |
| `license_inactive` | License is inactive |
| `domain_mismatch` | License not valid for this domain |
| `max_activations_reached` | Maximum activations reached |
| `rate_limit_exceeded` | Too many requests (wait and retry) |

## License Statuses

- **Active**: License is valid and usable
- **Inactive**: License has been deactivated
- **Expired**: License validity period has ended
- **Revoked**: License has been manually revoked by admin

## Email Notifications

The plugin sends automatic email notifications (configurable via WooCommerce > Settings > Emails):

- **Order Completion**: License keys included in order confirmation emails
- **Expiration Warning (7 days)**: Reminder sent 7 days before expiration
- **Expiration Warning (1 day)**: Urgent reminder sent 1 day before expiration
- **License Expired**: Notification when a license auto-expires

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

## Support

For issues and feature requests, please visit:
<https://src.bundespruefstelle.ch/magdev/wc-licensed-product/issues>

## Author

Marco Graetsch

## License

GPL-2.0-or-later
