feat: refactor getAuthenticationUrl to use API and add webhook signature verification

- Change getAuthenticationUrl() to call /v1/authentication/form API endpoint
  instead of generating URLs client-side, enabling server-side nonce and
  timestamp for replay attack protection
- Add support for new authentication parameters: type, delegated, syncFrom,
  notifyFrom, subconnections, and path
- Add verifyWebhookSignature() method to validate webhook requests using
  HMAC-SHA256 with timing-safe comparison
- Update README with new parameters table and webhook verification docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: andris9

README.md

@@ -49,8 +49,8 @@ $result = $client->messages->submit('account-id', [
 $client = new EmailEngine(
     accessToken: 'your-access-token',      // Required: API access token
     baseUrl: 'http://localhost:3000',       // EmailEngine base URL (default: localhost:3000)
-    serviceSecret: 'your-service-secret',   // For hosted authentication URLs
-    redirectUrl: 'http://your-app/callback', // Default redirect URL for auth
+    serviceSecret: 'your-service-secret',   // For verifying webhook signatures
+    redirectUrl: 'http://your-app/callback', // Default redirect URL for hosted auth
     timeout: 30,                            // Request timeout in seconds
 );
 ```
@@ -266,17 +266,16 @@ $client->settings->setWebhooks([
 
 ### Hosted Authentication
 
-Generate URLs for EmailEngine's hosted authentication form:
+Generate URLs for EmailEngine's hosted authentication form. This method calls the EmailEngine API to generate a secure authentication URL with server-side nonce and timestamp for replay attack protection.
 
 ```php
 $client = new EmailEngine(
     accessToken: 'your-token',
     baseUrl: 'http://localhost:3000',
-    serviceSecret: 'your-service-secret',
     redirectUrl: 'http://your-app/auth-callback',
 );
 
-// Generate auth URL
+// Generate auth URL with basic options
 $authUrl = $client->getAuthenticationUrl([
     'account' => null, // null = auto-generate account ID
     'name' => 'User Name',
@@ -287,6 +286,62 @@ $authUrl = $client->getAuthenticationUrl([
 header('Location: ' . $authUrl);
 ```
 
+#### Available Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `account` | string\|null | Account ID (null to auto-generate) |
+| `name` | string | Display name for the account |
+| `email` | string | Email address hint |
+| `redirectUrl` | string | Override default redirect URL |
+| `type` | string | Account type (e.g., 'imap', 'gmail', 'outlook') |
+| `delegated` | bool | Enable delegated access |
+| `syncFrom` | string | ISO 8601 date to sync messages from |
+| `notifyFrom` | string | ISO 8601 date to send notifications from |
+| `subconnections` | array | List of shared mailboxes to connect |
+| `path` | string\|array | Mailbox path(s) to monitor |
+
+```php
+// Example with all parameters
+$authUrl = $client->getAuthenticationUrl([
+    'account' => 'user-123',
+    'name' => 'John Doe',
+    'email' => 'john@example.com',
+    'type' => 'gmail',
+    'delegated' => true,
+    'syncFrom' => '2024-01-01T00:00:00Z',
+    'notifyFrom' => '2024-01-01T00:00:00Z',
+    'subconnections' => ['Shared Mailbox'],
+    'path' => ['INBOX', 'Sent'],
+]);
+```
+
+### Webhook Signature Verification
+
+Verify webhook signatures to ensure requests are authentically from EmailEngine. Requires the `serviceSecret` to be configured.
+
+```php
+$client = new EmailEngine(
+    accessToken: 'your-token',
+    baseUrl: 'http://localhost:3000',
+    serviceSecret: 'your-service-secret',
+);
+
+// Get the raw request body and signature header
+$body = file_get_contents('php://input');
+$signature = $_SERVER['HTTP_X_EE_WH_SIGNATURE'] ?? '';
+
+if ($client->verifyWebhookSignature($body, $signature)) {
+    // Signature is valid - process the webhook
+    $payload = json_decode($body, true);
+    // ... handle webhook event
+} else {
+    // Invalid signature - reject the request
+    http_response_code(401);
+    exit('Invalid signature');
+}
+```
+
 ### Outbox Management
 
 ```php

src/EmailEngine.php

@@ -218,34 +218,67 @@ public function blocklists(): Blocklists
     /**
      * Generate a redirect URL for EmailEngine's hosted authentication page
      *
+     * This method calls the EmailEngine API to generate a secure authentication URL
+     * with server-side nonce and timestamp for replay attack protection.
+     *
      * @param array{
      *     account?: string|null,
      *     name?: string,
      *     email?: string,
-     *     redirectUrl?: string
+     *     redirectUrl?: string,
+     *     type?: string,
+     *     delegated?: bool,
+     *     syncFrom?: string,
+     *     notifyFrom?: string,
+     *     subconnections?: array<string>,
+     *     path?: string|array<string>
      * } $data Authentication data
-     * @throws EmailEngineException If service secret is not configured
+     * @throws EmailEngineException If the API request fails
      */
     public function getAuthenticationUrl(array $data = []): string
     {
-        if ($this->serviceSecret === null) {
+        $data['redirectUrl'] ??= $this->redirectUrl;
+
+        if (empty($data['redirectUrl'])) {
+            throw new EmailEngineException(
+                message: 'redirectUrl is required for generating authentication URLs'
+            );
+        }
+
+        $response = $this->httpClient->post('/v1/authentication/form', $data);
+
+        if (!isset($response['url'])) {
             throw new EmailEngineException(
-                message: 'Service secret is required for generating authentication URLs'
+                message: 'Invalid response from authentication form API: missing url field'
             );
         }
 
-        // Use provided redirectUrl or fall back to default
-        if (empty($data['redirectUrl']) && $this->redirectUrl !== null) {
-            $data['redirectUrl'] = $this->redirectUrl;
+        return $response['url'];
+    }
+
+    /**
+     * Verify a webhook signature from EmailEngine
+     *
+     * EmailEngine signs webhooks with the X-EE-Wh-Signature header using
+     * HMAC-SHA256 of the raw request body, base64url encoded.
+     *
+     * @param string $body The raw webhook request body
+     * @param string $signature The signature from X-EE-Wh-Signature header
+     * @return bool True if the signature is valid
+     * @throws EmailEngineException If service secret is not configured
+     */
+    public function verifyWebhookSignature(string $body, string $signature): bool
+    {
+        if ($this->serviceSecret === null) {
+            throw new EmailEngineException(
+                message: 'Service secret is required for verifying webhook signatures'
+            );
         }
 
-        $dataJson = json_encode($data, JSON_THROW_ON_ERROR);
-        $signature = $this->signRequest($dataJson, $this->serviceSecret);
+        $computed = hash_hmac('sha256', $body, $this->serviceSecret, true);
+        $computedBase64 = $this->base64EncodeUrlsafe($computed);
 
-        return $this->baseUrl . '/accounts/new?data=' .
-            $this->base64EncodeUrlsafe($dataJson) .
-            '&sig=' .
-            $this->base64EncodeUrlsafe($signature);
+        return hash_equals($computedBase64, $signature);
     }
 
     /**