refactor: Address Copilot review comments

- Extract HMAC_SHA256_OUTPUT_BYTES to shared tests/TestConstants.php
- Remove fragile require_once from PersonTest
- Create NormalizesPersonFields trait to avoid code duplication
- Update PersonObserver and PersonRepository to use trait
- Update Observer docblock: BYTEA → VARCHAR columns
- Improve Binary cast docblock to explicitly mention PostgreSQL PDO

All Copilot review comments addressed

Author: kevalyq

app/Casts/Binary.php

@@ -12,10 +12,10 @@
 use Illuminate\Database\Eloquent\Model;
 
 /**
- * Cast for binary data stored as base64 in VARCHAR columns.
+ * Cast for binary data stored as base64 in VARCHAR columns to avoid PostgreSQL PDO BYTEA handling issues.
  *
- * Strategy: Store binary data as base64-encoded strings in VARCHAR for
- * reliable cross-database support, avoiding PDO binary binding issues.
+ * Strategy: Store binary data as base64-encoded strings in VARCHAR columns for reliable cross-database support,
+ * specifically to work around PostgreSQL PDO's handling of BYTEA columns and binary binding issues.
  *
  * - GET: Decode base64 from VARCHAR to raw binary
  * - SET: Encode raw binary to base64 for VARCHAR storage

app/Observers/PersonObserver.php

@@ -10,17 +10,20 @@
 
 use App\Models\Person;
 use App\Models\TenantKey;
+use App\Traits\NormalizesPersonFields;
 
 /**
  * PersonObserver automatically computes blind indexes for encrypted fields.
  *
  * When a Person is created or updated, this observer:
  * 1. Normalizes plaintext values (email_plain, phone_plain)
  * 2. Generates HMAC-SHA256 blind indexes using the tenant's idx_key
- * 3. Stores indexes in *_idx BYTEA columns for equality search
+ * 3. Stores indexes in *_idx VARCHAR columns for equality search
  */
 class PersonObserver
 {
+    use NormalizesPersonFields;
+
     /**
      * Handle the Person "creating" event.
      *
@@ -63,24 +66,4 @@ private function updateBlindIndexes(Person $person): void
             $person->phone_idx = $tenantKey->generateBlindIndex($normalized);
         }
     }
-
-    /**
-     * Normalize email for blind index generation.
-     *
-     * Removes whitespace and converts to lowercase.
-     */
-    private function normalizeEmail(string $email): string
-    {
-        return strtolower(trim($email));
-    }
-
-    /**
-     * Normalize phone for blind index generation.
-     *
-     * Extracts only digits (removes spaces, dashes, parentheses).
-     */
-    private function normalizePhone(string $phone): string
-    {
-        return preg_replace('/\D/', '', $phone) ?: '';
-    }
 }

app/Repositories/PersonRepository.php

@@ -10,6 +10,7 @@
 
 use App\Models\Person;
 use App\Models\TenantKey;
+use App\Traits\NormalizesPersonFields;
 
 /**
  * PersonRepository provides business logic for Person operations.
@@ -18,6 +19,8 @@
  */
 class PersonRepository
 {
+    use NormalizesPersonFields;
+
     /**
      * Find a Person by email using blind index search.
      *
@@ -102,20 +105,4 @@ public function createOrUpdate(int $tenantId, array $attributes): Person
 
         return $person;
     }
-
-    /**
-     * Normalize email for blind index generation.
-     */
-    private function normalizeEmail(string $email): string
-    {
-        return strtolower(trim($email));
-    }
-
-    /**
-     * Normalize phone for blind index generation.
-     */
-    private function normalizePhone(string $phone): string
-    {
-        return preg_replace('/\D/', '', $phone) ?: '';
-    }
 }

app/Traits/NormalizesPersonFields.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: 2025 SecPal Contributors
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace App\Traits;
+
+/**
+ * Trait for normalizing Person fields before blind index generation.
+ *
+ * Ensures consistent normalization across PersonObserver and PersonRepository.
+ */
+trait NormalizesPersonFields
+{
+    /**
+     * Normalize email for blind index generation.
+     *
+     * Removes whitespace and converts to lowercase.
+     */
+    private function normalizeEmail(string $email): string
+    {
+        return strtolower(trim($email));
+    }
+
+    /**
+     * Normalize phone for blind index generation.
+     *
+     * Extracts only digits (removes spaces, dashes, parentheses).
+     */
+    private function normalizePhone(string $phone): string
+    {
+        return preg_replace('/\D/', '', $phone) ?: '';
+    }
+}

tests/Feature/PersonTest.php

@@ -10,8 +10,8 @@
 use App\Models\TenantKey;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 
-// Import constant from TenantKeyTest
-require_once __DIR__.'/TenantKeyTest.php';
+// HMAC_SHA256_OUTPUT_BYTES is 32 (SHA-256 output size in bytes)
+require_once __DIR__.'/../TestConstants.php';
 
 uses(RefreshDatabase::class);
 

tests/Feature/TenantKeyTest.php

@@ -9,10 +9,10 @@
 use App\Models\TenantKey;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 
-uses(RefreshDatabase::class);
+// HMAC_SHA256_OUTPUT_BYTES is 32 (SHA-256 output size in bytes)
+require_once __DIR__.'/../TestConstants.php';
 
-// SHA-256 produces 32 bytes output
-const HMAC_SHA256_OUTPUT_BYTES = 32;
+uses(RefreshDatabase::class);
 
 /**
  * Helper function to clean up the KEK file.

tests/TestConstants.php

@@ -0,0 +1,10 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: 2025 SecPal Contributors
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+// SHA-256 produces 32 bytes output
+const HMAC_SHA256_OUTPUT_BYTES = 32;