feat: implement #724, #740, #741, #742 - DEBUG_PII, docs, preflightChecks

docs/Auth_and_User_APIs.md

@@ -40,6 +40,50 @@ Success response (201 Created):
 Errors:
 - 400 Bad Request — validation failure (missing/weak password, invalid email)
 - 400 Bad Request — email already exists
+- 400 Bad Request — registration already pending from this IP
+
+---
+
+## Email verification flow
+
+Purpose: verify the email address used during registration.
+
+After a successful `POST /auth/register`, the newly created user has `isVerified: false` and
+cannot log in — login will return `401 Unauthorized` with the message
+`"Please verify your email before logging in."`.
+
+The user receives an email containing a verification link that points to the
+`POST /auth/verify-email` endpoint:
+
+**Request:**
+```json
+{ "token": "62-char-random-token" }
+```
+
+**Success response (200 OK):**
+```json
+{
+  "message": "Email verified successfully",
+  "user": { "id": "user_abc123", "email": "user@example.com", "firstName": "Jane" },
+  "accessToken": "ey...",
+  "refreshToken": "ey..."
+}
+```
+
+Errors:
+- 400 Bad Request — invalid or expired verification token
+- 400 Bad Request — email already verified
+
+### Token expiry
+
+The verification token expires after the duration configured in
+`EMAIL_VERIFICATION_EXPIRES_IN` (default: `24h`). When the token expires, the user must request
+a new verification email via `POST /api/users/email/resend` (or re-register).
+
+### Registration from the same IP
+
+To prevent abuse, a second registration from the same IP is blocked until the pending email
+verification is either completed or the token expires. This is a soft, in-memory guard.
 
 ---
 

docs/CHANGELOG_GUIDE.md

@@ -6,6 +6,45 @@ This guide explains how to maintain the project changelog for PropChain-BackEnd.
 
 ---
 
+## Log Redaction Policy
+
+### What is redacted
+
+The following PII (Personally Identifiable Information) is redacted in log output:
+
+- **Email addresses**: replaced with a SHA-256 hash truncated to the first 12 characters
+  (e.g. `user@example.com` → `a1b2c3d4e5f6`)
+
+### How it works
+
+The private `hashEmail(email)` helper in `AuthService` performs the redaction:
+
+```typescript
+private hashEmail(email: string): string {
+  return createSha256(email).slice(0, 12);
+}
+```
+
+All log lines that reference a user's email address route through `hashEmail()` so that
+plaintext emails are never written to the logs.
+
+### DEBUG_PII environment variable
+
+| Variable     | Default | Description                                                     |
+|--------------|---------|-----------------------------------------------------------------|
+| `DEBUG_PII`  | `false` | When `true`, plaintext PII is logged instead of redacted values |
+
+- **Local development**: set `DEBUG_PII=true` in `.env` to see real email addresses in logs.
+- **All other environments**: `DEBUG_PII` must remain `false` or unset.
+
+### Security
+
+Enabling `DEBUG_PII` in production would write sensitive user data to log files, creating
+a data-breach risk. CI/CD pipelines should verify that `DEBUG_PII` is not set to `true`
+in deployed environments.
+
+---
+
 ## 📍 Changelog Location
 
 - **File**: `CHANGELOG.md` (root directory)

src/auth/auth.service.ts

@@ -64,6 +64,10 @@ export class AuthService {
   private readonly issuer = 'PropChain';
 
   private hashEmail(email: string): string {
+    const debugPii = this.configService.get<string>('DEBUG_PII') === 'true';
+    if (debugPii) {
+      return email;
+    }
     return createSha256(email).slice(0, 12);
   }