# Certificate Transfer Ownership Feature

## 🎁 Overview

The Transfer Ownership feature allows original buyers to transfer certificate ownership to new owners (gifts, resales, etc.) with secure email verification.

## 🔒 Security Features

### Email Verification
- Transfer requires original buyer's email (from WooCommerce order)
- Email is NOT shown on certificate (private verification)
- Prevents unauthorized transfers

### Rate Limiting
- Maximum 3 failed attempts per certificate
- 24-hour cooldown after 3 failures
- Prevents brute force attacks

### Transfer History
- Full provenance trail maintained
- Each transfer recorded with:
  - New owner name
  - New owner country
  - Transfer date
  - Optional transfer note
- Cannot be edited once recorded

## 📋 How It Works

### For Original Buyer (Gifting/Selling):

1. **Access Certificate**
   - Buyer receives certificate link via email after purchase
   - Opens certificate page

2. **Click "Transfer Ownership"**
   - Button located below certificate details
   - Opens transfer modal

3. **Fill Transfer Form**
   - **Your Email:** Original buyer's email (verification)
   - **New Owner Name:** Recipient's full name
   - **New Owner Country:** Recipient's country
   - **Note (Optional):** "Birthday gift", "Sold at auction", etc.

4. **Submit Transfer**
   - System verifies email matches order
   - If correct: Transfer completes, page reloads
   - If wrong: Error message, attempts remaining shown

5. **Transfer Complete**
   - Certificate now shows:
     - Original Buyer: [Original Name]
     - Current Owner: [New Name]
     - Transferred: [Date]
   - Transfer button remains for future transfers

### For New Owner (Recipient):

1. **Receives Link**
   - Original buyer shares certificate URL
   - (Optional: Automatic email notification can be enabled)

2. **Views Certificate**
   - Certificate shows them as current owner
   - Can print or save certificate
   - Can transfer again if they sell/gift later

## 🔄 Transfer Flow Example

### Example: Gift Scenario

**Initial Purchase:**
```
Owner: Loïc Kernen
Location: France
Purchase Date: 12.01.2026
```

**After Transfer:**
```
ORIGINAL PURCHASE
Buyer: Loïc Kernen
Location: France
Purchase Date: 12.01.2026

TRANSFERRED TO
Owner: Sarah Johnson
Location: USA
Transferred: 15.03.2026
Note: "Birthday gift"
```

### Example: Multiple Transfers (Resale)

**Second Transfer:**
```
ORIGINAL PURCHASE
Buyer: Loïc Kernen (France)
Purchase Date: 12.01.2026

TRANSFER HISTORY
→ Sarah Johnson (USA) - 15.03.2026
→ Gallery XYZ (UK) - 20.08.2027

CURRENT OWNER
Gallery XYZ, United Kingdom
```

## ⚙️ Configuration

### Enable/Disable New Owner Email

In `class-fineart-certificate-transfer.php`, line 139:

```php
// Uncomment to enable email to new owner
self::send_transfer_notification($cert_id, $new_owner_name);
```

### Customize Transfer Limit

To allow only ONE transfer (gift but no resale):

In `class-fineart-certificate-transfer.php`, around line 120, add:

```php
// Check if already transferred
if (self::is_transferred($cert_id)) {
    wp_send_json_error(['message' => 'This certificate has already been transferred.']);
}
```

### Adjust Rate Limiting

Change from 3 attempts to 5 attempts (line 51):

```php
if ($attempts && $attempts >= 5) {  // Was: >= 3
```

## 🎨 Customization

### Change Button Text

In `single-certificate.php`, find:

```php
Transfer Ownership
```

Change to whatever you prefer:
- "Gift This Certificate"
- "Transfer to New Owner"
- "Change Owner"

### Change Button Style

Modify inline styles in `single-certificate.php`:

```php
style="background: #ff5e14; ..."
```

### Add Required Fields

To require email from new owner, add to form in `single-certificate.php`:

```php
<input type="email" id="new-owner-email" required 
       placeholder="New owner's email">
```

Then update AJAX handler to process it.

## 📊 Database

### Certificate Meta Keys

**Transfer History:**
- `_cert_transfer_history` - Array of all transfers
  ```php
  [
    [
      'name' => 'Sarah Johnson',
      'country' => 'USA',
      'note' => 'Birthday gift',
      'date' => 1710518400
    ],
    // ... more transfers
  ]
  ```

**Current Owner (Quick Access):**
- `_cert_current_owner_name`
- `_cert_current_owner_country`

### Transients

**Rate Limiting:**
- `transfer_attempts_{cert_id}` - Attempt counter
- Expires: 24 hours

## 🔍 Testing

### Test Transfer Flow:

1. **Create Test Order**
   - Complete an order
   - Note the buyer email used

2. **Access Certificate**
   - Open certificate link from test email

3. **Test Successful Transfer**
   - Click "Transfer Ownership"
   - Enter correct buyer email
   - Fill new owner details
   - Submit
   - Verify certificate updates

4. **Test Failed Transfer**
   - Click "Transfer Ownership" again
   - Enter WRONG email
   - Verify error message shows
   - Try 3 times to trigger rate limit

5. **Test Rate Limiting**
   - After 3 failed attempts
   - Verify message: "Too many failed attempts"
   - Wait 24 hours OR delete transient manually

6. **Test Multiple Transfers**
   - Transfer to owner #2
   - Transfer to owner #3
   - Verify full history shows on certificate

### Manual Transient Deletion (Testing)

```php
// In WordPress, run:
delete_transient('transfer_attempts_' . $cert_id);
```

## 🐛 Troubleshooting

### Transfer Not Working

1. **Check JavaScript Console**
   - Open browser dev tools
   - Look for errors

2. **Verify AJAX URL**
   - Check `fineartTransfer.ajaxurl` is correct
   - Should be: `/wp-admin/admin-ajax.php`

3. **Test Direct AJAX**
   ```javascript
   // In browser console
   console.log(fineartTransfer);
   ```

### Email Verification Fails

1. **Email Format**
   - WooCommerce stores: `user@example.com`
   - Must match exactly (case-insensitive)
   - No extra spaces

2. **Check Order Email**
   ```php
   $order = wc_get_order(ORDER_ID);
   echo $order->get_billing_email();
   ```

### Modal Not Appearing

1. **jQuery Loaded?**
   - Check if jQuery is enqueued
   - Check console for errors

2. **Script Enqueued?**
   - View page source
   - Search for: `certificate-transfer.js`

## 📝 Future Enhancements

### Possible Additions:

1. **Email to New Owner**
   - Automatic notification
   - Already coded, just uncomment

2. **Transfer Confirmation**
   - Two-step process
   - Email confirmation link

3. **Transfer Fee**
   - Charge for transfers (WooCommerce)
   - Prevent abuse

4. **Admin Approval**
   - Transfers pending admin review
   - Manual verification

5. **Reverse Transfer**
   - Undo transfer (time-limited)
   - Original buyer can reclaim

6. **Transfer Certificate PDF**
   - Generate transfer document
   - Legal proof of ownership change

## ✅ Best Practices

### For Users:
- Keep certificate link private
- Only share with intended recipient
- Use specific notes for transfers
- Save transfer confirmation

### For Admins:
- Monitor transfer activity
- Check for abuse patterns
- Keep rate limiting enabled
- Maintain email verification

### For Developers:
- Don't remove email verification
- Keep transfer history immutable
- Log all transfer attempts
- Test edge cases thoroughly

## 📞 Support

If transfer issues occur:

1. **Check WordPress Debug Log**
   `/wp-content/debug.log`

2. **Check Browser Console**
   F12 → Console tab

3. **Verify Database**
   ```sql
   SELECT * FROM wp_postmeta 
   WHERE meta_key = '_cert_transfer_history';
   ```

4. **Test AJAX Directly**
   Use browser dev tools Network tab