# Quick Start Guide - Authentication & Rate Limiting

## Files Created

### Core Classes (P1-50, P1-51)
- ✅ `includes/API/AuthMiddleware.php` - Authentication and authorization
- ✅ `includes/API/RateLimiter.php` - Rate limiting for API abuse prevention

### Supporting Files
- ✅ `includes/API/LanguagesRestController.php` - Example REST controller with auth & rate limiting
- ✅ `includes/API/README.md` - Comprehensive documentation
- ✅ `includes/API/INTEGRATION-EXAMPLE.md` - Step-by-step integration guide
- ✅ `includes/API/test-rate-limiting.php` - Test script for verification
- ✅ `includes/API/QUICK-START.md` - This file

## 60-Second Integration

### 1. Enable REST API (2 minutes)

Edit `includes/Core/Plugin.php`, add this method:

```php
/**
 * Register REST API routes
 */
private function register_rest_routes(): void {
    add_action('rest_api_init', function () {
        // Register Languages REST Controller
        $languages_controller = new \MultilingualPressZone\API\LanguagesRestController(
            $this->language_manager
        );
        $languages_controller->register_routes();

        // Register Dashboard REST Controller
        $dashboard_controller = new \MultilingualPressZone\Admin\DashboardRestController();
        $dashboard_controller->register_routes();

        // Register Jobs REST Controller
        $jobs_controller = new \MultilingualPressZone\Admin\JobsRestController();
        $jobs_controller->register_routes();
    });
}
```

Call it from `init()`:

```php
public function init(): void {
    $this->load_dependencies();
    $this->register_hooks();
    $this->register_rest_routes(); // Add this line

    if (is_admin()) {
        $this->init_admin();
    }

    if (!is_admin()) {
        $this->init_frontend();
    }
}
```

### 2. Add Rate Limiting to Existing Controllers (5 minutes per controller)

Edit `includes/Admin/DashboardRestController.php`:

```php
// Add at top of file
use MultilingualPressZone\API\AuthMiddleware;
use MultilingualPressZone\API\RateLimiter;

// Add to class
private AuthMiddleware $auth_middleware;
private RateLimiter $rate_limiter;

public function __construct() {
    $this->auth_middleware = new AuthMiddleware();
    $this->rate_limiter = new RateLimiter();
}

// In each endpoint method, add this at the start:
public function get_stats(WP_REST_Request $request) {
    // Check rate limit
    $identifier = $this->getRequestIdentifier($request);
    $user_id = get_current_user_id();

    if (!$this->rate_limiter->isAllowed($identifier, $user_id ?: null)) {
        return $this->rate_limiter->createErrorResponse($identifier, $user_id ?: null);
    }

    // ... existing code ...

    $response = new WP_REST_Response(['success' => true, 'data' => $data]);
    return $this->rate_limiter->addHeaders($response, $identifier, $user_id ?: null);
}

// Add this helper method
private function getRequestIdentifier(WP_REST_Request $request): string {
    $user_id = get_current_user_id();
    if ($user_id) {
        return 'user_' . $user_id;
    }

    $audit_info = $this->auth_middleware->getCurrentUserForAudit();
    return 'ip_' . ($audit_info['ip_address'] ?: 'unknown');
}
```

Repeat for `includes/Admin/JobsRestController.php`.

### 3. Test It (1 minute)

```bash
# Test basic endpoint
curl http://your-site.local/wp-json/multilingual-press-zone/v1/languages

# Test rate limiting (run 15 times)
for i in {1..15}; do
  curl -i http://your-site.local/wp-json/multilingual-press-zone/v1/languages
done
```

Look for:
- ✅ `X-RateLimit-Limit: 10` header
- ✅ `X-RateLimit-Remaining: X` header
- ✅ HTTP 429 after 10 requests

## Rate Limits

| User Type | Requests/Minute |
|-----------|----------------|
| Anonymous | 10 |
| Authenticated | 60 |
| Admin | 300 |

## Common Use Cases

### Check Permissions

```php
$auth = new AuthMiddleware();

if (!$auth->canManageLanguages()) {
    return new WP_Error('forbidden', 'Access denied', ['status' => 403]);
}
```

### Log User Action

```php
$auth = new AuthMiddleware();
$audit = $auth->getCurrentUserForAudit();

error_log(sprintf(
    'User %s (ID: %d) from %s performed action',
    $audit['username'],
    $audit['user_id'],
    $audit['ip_address']
));
```

### Check Rate Limit Before Expensive Operation

```php
$rate_limiter = new RateLimiter();
$identifier = 'user_' . get_current_user_id();

if (!$rate_limiter->isAllowed($identifier, get_current_user_id())) {
    return $rate_limiter->createErrorResponse($identifier, get_current_user_id());
}

// Proceed with expensive operation
```

## Troubleshooting

### Rate Limits Not Working

**Check:** Are transients enabled?
```php
set_transient('test', 'value', 60);
echo get_transient('test'); // Should output 'value'
```

**Fix:** Enable object cache or ensure transients work.

### Headers Not Showing

**Check:** Response type
```php
// Must be WP_REST_Response, not WP_Error
$response = new WP_REST_Response(['success' => true]);
return $rate_limiter->addHeaders($response, $identifier, $user_id);
```

### Permission Checks Fail

**Check:** User capabilities
```php
$user = wp_get_current_user();
var_dump($user->allcaps); // See all capabilities
```

## Next Steps

1. ✅ Verify all files created (see Files Created section)
2. ⏳ Update `Plugin.php` to register REST routes
3. ⏳ Update existing REST controllers with rate limiting
4. ⏳ Test with curl or REST API console
5. ⏳ Monitor logs for rate limit violations
6. ⏳ Adjust limits if needed

## Full Documentation

- **Complete Guide:** `README.md`
- **Integration Example:** `INTEGRATION-EXAMPLE.md`
- **Test Script:** `test-rate-limiting.php`

## Support

For questions or issues:
1. Check `README.md` for detailed documentation
2. Review `INTEGRATION-EXAMPLE.md` for step-by-step guide
3. Run `test-rate-limiting.php` to verify setup
4. Check WordPress error logs for rate limit violations

---

**Time Investment:**
- Initial setup: ~10 minutes
- Per controller update: ~5 minutes
- Testing: ~2 minutes
- **Total: ~20-30 minutes for complete integration**

**Benefits:**
- ✅ API abuse prevention
- ✅ Proper rate limiting
- ✅ Audit logging
- ✅ Permission management
- ✅ Standard HTTP headers
- ✅ WordPress.org compliant