TELSPAY MEMBER APP v2026.7.0 SECURE UNIFIED R2
=============================================

1. BACK UP the production database and the current application directory before deployment.

2. Keep private files OUTSIDE the web root:
   /home/telsinul/secure_keys/telspay_secure.php
   /home/telsinul/secure_keys/firebase-service-account.json

3. Do not overwrite your populated private secure file with the example in this ZIP.
   The no-secrets template is deployment/telspay_secure.v2026.7.example.php.

4. Database upgrade:
   Import database/RUN_THIS_FIRST_v2026_7_0.sql into the EXISTING TELSPAY database.
   Do not re-import the full historical database over production. The v2026.7 migration
   adds Firebase delivery auditing and registers the release.

5. Recommended PHP extensions:
   mysqli, curl, openssl, json, gd, fileinfo, iconv.
   The TELSPAY native PDF renderer does not require mbstring or external font files.

6. Documents / PDFs:
   TELSPAY now uses documents/pdf_renderer.php, a native PDF renderer based on PDF standard
   Helvetica fonts. It does not load the broken TCPDF main engine or depend on Dompdf font caches.
   The standalone TCPDF 2D barcode helper is used only to calculate the QR matrix.
   Test both View PDF and Download PDF for:
      - Savings statement
      - Shares / loan statements
      - Loan application
      - Loan agreement
      - CRB consent
      - Bank mandate
      - Other member-vault documents
   PIN-protected routes, ownership checks, QR authenticity and access audit logs remain active.

7. Bank-receipt OCR:
   App_home.php loads assets/js/telspay-bank-receipt-ocr.js.
   During receipt reading, a full-screen overlay blocks background interaction and shows staged
   upload/OCR/verification progress. Native Tesseract is used when configured and available;
   otherwise Tesseract.js runs in the member browser and PHP still extracts/validates the final
   receipt/reference number. Low OCR confidence alone does not reject a safely extracted reference.

8. Email:
   Configure TELSPAY_SMTP_* and TELSPAY_MAIL_* in the external secure file.
   All central transactional emails are HTML formatted and use authenticated SMTP.
   PHP mail() fallback is disabled by default; only enable TELSPAY_ALLOW_PHP_MAIL_FALLBACK when
   the hosting provider supplies a trusted local MTA. Registration email maps to the same SMTP
   source by default. Use notifications/health_check.php while signed in to test configuration.

9. Firebase:
   Configure FIREBASE_SERVICE_ACCOUNT_PATH plus all FIREBASE_WEB_* and FIREBASE_VAPID_PUBLIC_KEY.
   The service-account JSON must match FIREBASE_WEB_PROJECT_ID. Firebase browser configuration now
   loads config/config.php first, preventing the previous telspayConfigValue() fatal error. Delivery
   uses Firebase HTTP v1, retries transient failures, deactivates invalid tokens and writes a delivery
   audit to member_firebase_notification_log. Use notifications/health_check.php?oauth=1 to verify.

10. Loan period:
   Members manually enter the repayment period. The backend refuses zero/negative periods and values
   above loan_products.pdt_term for the selected product. Product ID/name/purpose, interest method/rate
   and configured fees remain database-controlled and are not guessed.

11. Guarantor authenticity:
   Invitations retain secure one-time response links and Transaction-PIN verification. After ACCEPTED
   or REJECTED response, TELSPAY stores a response HMAC and creates:
      /loan/guarantor_authenticity.php?code=...&sig=...
   Borrower, guarantor and applicable admin notifications receive the signed verification link. The
   response page also shows a signed QR. Public verification masks identities and exposes only the
   minimum loan/consent data needed to prove authenticity.

12. Notification validation:
   After deployment sign in and open notifications/health_check.php. It reports configuration status
   without exposing passwords/private keys. Use the provided POST test action/CSRF flow to test the
   signed-in member email and Firebase token delivery. Actual delivery still depends on valid live SMTP
   credentials, a reachable SMTP host, a valid Firebase service-account JSON and active FCM tokens.

13. Secure configuration:
   Keep Flutterwave keys, SMTP passwords, Africa's Talking credentials, Firebase Admin JSON, database
   password, KYC encryption key and TELSPAY HMAC keys outside the public application directory.
