From 2cf5c63a1ecfcd5c465594b8c7fcc8cb44f571de Mon Sep 17 00:00:00 2001
From: Hamza-Ayed <hamzaayedflutter@gmail.com>
Date: Wed, 29 Jul 2026 17:32:28 +0300
Subject: [PATCH] docs(env): document ENCRYPTION_MODE, BLIND_INDEX_PEPPER, and
 one-time migration SRC_DB_* vars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

These were required on the server to run the v2 migration and switch
write mode to GCM, but .env.example didn't mention them — anyone
provisioning a fresh environment from this file alone would hit the
same "table doesn't exist" / "access denied" surprises we just debugged.
---
 docker/.env.example | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docker/.env.example b/docker/.env.example
index f381598..a1e07f5 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -82,6 +82,23 @@ SECRET_KEY=cd0b94f349c292bf93c63e798b903bb4b3b3738a049654441d6524ba603d614147fbc
 passwordnewpassenger=$2y$10$0WYS/2Fz9BTtoyCbTusudOG9JgTO3DqCPWBhS2Cf9gIu3H9KoSZKC
 initializationVector=abcdefghijklmnop
 
+# وضع كتابة التشفير — 'gcm' (الافتراضي الحالي في الإنتاج) أو 'cbc' (قديم/توافقية).
+# القراءة تدعم الصيغتين دائماً بغضّ النظر عن هذه القيمة.
+ENCRYPTION_MODE=gcm
+
+# مفتاح HMAC لفهرس البحث الأعمى فوق الحقول المشفّرة (core/Security/BlindIndex.php).
+# ولّده بـ: openssl rand -hex 32 — ولا تغيّره بعد أول استخدام إلا مع إعادة بناء
+# كل الفهارس (backfill_blind_index.php --force)، وإلا يتوقف كل بحث/تسجيل دخول.
+BLIND_INDEX_PEPPER=
+
+# ⚠️ متغيّرات مؤقتة لمرة واحدة — تُستخدم فقط عند تشغيل
+# backend/scripts/migrate_v2_reencrypt.php (ترحيل قاعدة قديمة إلى هذا المخطط).
+# لا علاقة لها بتشغيل التطبيق العادي؛ اتركها فارغة إن لم تكن تُرحّل بيانات.
+SRC_DB_HOST=mysql
+SRC_DB_NAME=
+SRC_DB_USER=
+SRC_DB_PASS=
+
 # ⚠️ تحذير مسارات الملفات السرية:
 # في اللايف كانت هذه الملفات خارج مجلد htdocs. في الدوكر يجب وضع هذه الملفات داخل مجلد منفصل لتبقى آمنة.
 # لقد قمت ببرمجة الدوكر ليقرأ مجلد docker/keys ويربطه بالمسار /keys/ المعزول تماماً عن الويب (لأن مسار الويب هو /var/www).