Merge pull request #471 from talktosam2003/endpoint

setup endpoint

Author: kingksjo

.env.example

@@ -15,6 +15,11 @@ FRONTEND_URL=http://localhost:5173
 # JWT signing secret (required, min 32 characters)
 JWT_SECRET=replace-this-with-a-strong-32-char-minimum-jwt-secret
 
+# TOTP 2FA encryption key — 64 hex characters (32 bytes, AES-256).
+# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# Optional in development (falls back to JWT_SECRET hash); required in production.
+TOTP_ENCRYPTION_KEY=
+
 # Pino log level (optional; not validated in env.ts) — debug|info|warn|error
 LOG_LEVEL=debug
 

docs/swagger.yaml

@@ -1612,6 +1612,50 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+  /api/auth/2fa/setup:
+    post:
+      summary: Initiate TOTP 2FA setup
+      description: >-
+        Generates a new TOTP secret for the authenticated user, encrypts it at
+        rest (AES-256-GCM), and returns an `otpauth://` URI rendered as a base64
+        PNG QR code data URL. The user should scan this with an authenticator app
+        (e.g. Google Authenticator, Authy). **2FA is not yet enabled** after this
+        call — the user must verify a valid TOTP code via the upcoming verify
+        endpoint to activate protection.
+      tags:
+        - Auth
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: QR code data URL generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  message:
+                    type: string
+                    example: '2FA setup initiated. Scan the QR code with your authenticator app.'
+                  data:
+                    type: object
+                    properties:
+                      qrCodeUrl:
+                        type: string
+                        description: >-
+                          Base64 PNG data URL (`data:image/png;base64,...`) to
+                          be displayed as a QR code for the user to scan.
+                        example: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
+        '401':
+          description: Missing or invalid auth token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   /api/auth/forgot-password:
     post:
       summary: Request a password reset email