Merge branch 'main' into codes11

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
 
@@ -43,13 +48,26 @@ SMTP_PASS=smtp-password
 SMTP_PORT=587
 SMTP_USER=you@example.com
 
-# --- S3 object storage (optional — TODO wire real adapter; see #379) ---
+# --- S3 object storage (optional — for AWS S3, MinIO, etc.) ---
 S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
 S3_BUCKET=my-bucket
 S3_ENDPOINT=https://s3.amazonaws.com
 S3_REGION=us-east-1
 S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
 
+# --- Storage provider selection ---
+# Options: mock (default), s3, r2, cloudinary
+# mock: Local development without cloud credentials
+# s3: AWS S3 or S3-compatible (use S3_* vars above)
+# r2: Cloudflare R2 (use S3_* vars, set S3_ENDPOINT to R2 URL)
+# cloudinary: Cloudinary CDN (image-optimized)
+STORAGE_PROVIDER=mock
+
+# --- Cloudinary storage (optional — for image optimization) ---
+CLOUDINARY_CLOUD_NAME=my-cloud
+CLOUDINARY_API_KEY=my-api-key
+CLOUDINARY_API_SECRET=my-api-secret
+
 # --- Soroban / escrow (optional — TODO implement client; see #358) ---
 ESCROW_CONTRACT_ID=CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2B
 SOROBAN_RPC_URL=https://soroban-rpc.example.com

docs/swagger.yaml

@@ -572,6 +572,95 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+  /api/auth/sessions:
+    get:
+      summary: List active sessions
+      description: |
+        Returns all active session records for the authenticated user (one per device/login).
+        Sessions are ordered newest-first.
+      tags:
+        - Auth
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Session list retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  message:
+                    type: string
+                    example: Sessions retrieved
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Session'
+        '401':
+          description: Missing or invalid authorization token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /api/auth/sessions/{jti}:
+    delete:
+      summary: Revoke a session
+      description: |
+        Blocklists the token identified by `jti` in Redis and removes the session record.
+        The token will be rejected immediately by `requireAuth` on subsequent requests.
+
+        - Returns **403** if the session belongs to a different user (cross-user revocation).
+        - Returns **404** if no session with that `jti` exists.
+      tags:
+        - Auth
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: jti
+          required: true
+          schema:
+            type: string
+          description: The JWT ID (`jti` claim) of the session to revoke
+      responses:
+        '200':
+          description: Session revoked successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  message:
+                    type: string
+                    example: Session revoked successfully
+                  data:
+                    nullable: true
+                    example: null
+        '401':
+          description: Missing or invalid authorization token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '403':
+          description: Forbidden — cannot revoke another user's session
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Session not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /api/auth/signup:
     post:
       summary: Register a new user
@@ -1523,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
@@ -4424,6 +4557,33 @@ paths:
 
 components:
   schemas:
+    Session:
+      type: object
+      description: A per-device session record created on login or signup.
+      properties:
+        _id:
+          type: string
+          description: Session MongoDB ObjectId
+        userId:
+          type: string
+          description: Owner user ObjectId
+        jti:
+          type: string
+          description: JWT ID (UUID v4) — use this as the path param for DELETE /api/auth/sessions/:jti
+        ip:
+          type: string
+          description: Client IP address at time of login (optional)
+        userAgent:
+          type: string
+          description: HTTP User-Agent string at time of login (optional)
+        createdAt:
+          type: string
+          format: date-time
+          description: When the session was created (ISO 8601)
+        lastUsedAt:
+          type: string
+          format: date-time
+          description: When the session was last active (ISO 8601)
     TelemetryUpdateEvent:
       type: object
       description: Real-time telemetry reading from an IoT sensor.